research-document
Praxis remote agent contract
Praxis remote agent contract
This page is for an agent — or a person, or automation — that can reach this repository on GitHub but has no local .NET, F#, or Praxis runtime. Praxis governs such work just as strictly as it governs local work. You send typed requests, and Praxis runs them for you.
The full specification is remote-protocol.md. This
page is all you need to take part.
1. Discover
Dispatch a praxis.describe request, described in section 2. The response's
result tells you:
- whether remote execution is available here;
- the Praxis version and protocol versions;
- every operation, with its required and optional arguments and the capability it needs;
- what this repository allows (
repository.capabilities); - the open and ready work;
- where results are kept.
If the repository does not have .github/workflows/praxis-remote.yml,
remote execution is not installed. Work locally, or ask a maintainer.
2. Send a request
Write the request as a document:
{
"protocol": "praxis.remote",
"protocolVersion": "1.0",
"requestId": "req-<something unique you keep>",
"operation": "work.start",
"repository": { "ref": "refs/heads/<branch>", "expectedSha": "<the commit you just read>" },
"actor": { "kind": "agent", "id": "<your stable id>", "provider": "<if known>", "model": "<if known>", "runtime": "<if known>", "sessionId": "<if known>" },
"arguments": { "workItemIds": ["<ID>"] }
}
Dispatch it on the branch it targets:
gh workflow run praxis-remote.yml --ref <branch> -f request_id=<requestId> -f request="$(cat request.json)"
You can use the REST API instead:
POST /repos/{owner}/{repo}/actions/workflows/praxis-remote.yml/dispatches,
with the body {"ref": "<branch>", "inputs": {"request": "...", "request_id": "..."}}.
If you can commit to the repository but cannot dispatch a workflow.
Some agent integrations can create branches and commit files but have no
Actions dispatch operation, and some run with no network in their sandbox.
Use the inbox instead (DF-ROS-2026-A045):
- Create a branch named
praxis-inbox/<anything>from the default branch, or reuse one. Never use the branch your request targets. - Commit the request document, unchanged, as
.praxis-inbox/<requestId>.jsonon that branch. - The Praxis remote inbox workflow sees the push and dispatches
praxis-remote.ymlon the request'srepository.refwith the file's exact bytes. A request with no ref, which is a read, runs on the default branch.
Everything else is the same. Praxis validates, authorizes and binds the
request, and your identity is what the request says. Because the target
branch does not move, your expectedSha stays valid. Read the result from
the journal on the target branch (section 3). A file the inbox cannot route
is not dispatched: the inbox run fails with an error that names the file.
To retry, commit the identical document again, since same requestId means
same intent. For your next request, commit a new file.
Several operations in one run. Use "operation": "batch" with
"protocolVersion": "1.2" and
"arguments": {"requests": [{"requestId": "...", "operation": "...", "arguments": {...}}, ...]}.
Each constituent keeps its own request ID and outcome. The batch stops at
the first constituent that does not succeed, and result.stoppedAt names
it.
3. Get the result
- For a mutation, read the journal on the branch. It is at
.ros/remote/requests/<requestId>.json(a:in your request ID becomes~). This is the durable record. You can also sendrequest.statuswith{"requestId": "..."}. - Or open the run. It is named
praxis remote <requestId>. Its summary and itspraxis-remote-responseartifact hold the same response. - Or read the job log. The job that executed the request prints the
same response in a
praxis.remote responsegroup. This is the way to read a read-only result, or a rejection, when you can read job logs but cannot download artifacts.
4. Rules that keep you governed
- Say who you are, and nothing more. Fill in only the actor fields you
actually know. Leave out anything you do not know; Praxis records it as
unknown. Never reuse another agent's ID or execution. Continue only your own execution, throughexecution.id. - One intent, one request ID. If you do not know whether a request ran,
because of a timeout, a lost result, or an outcome of
unknown, send the same document with the samerequestIdagain. If it already happened, you get the recorded result back withreplayed: true. Never mint a new ID for the same intent, and never reuse an ID for a different intent. The second case is refused asidempotency-conflict. - Bind mutations to what you saw.
repository.expectedShamust be the commit you read before forming the request. If the branch has moved, you getstale-ref: read the branch again and form a new request. - Operations only. There is no way to run a command. The operation
catalog in
praxis.describeis the whole surface. - Never put secrets in a request. A request that contains what looks
like a credential is refused as
secret-detected. - Telemetry is what you report. Values you send through
telemetry.recordare labelled as supplied by you. Report only numbers you actually have, and omit the rest. A missing value stays unknown; it is never zero.
5. Continue someone else's work, and what to do when you cannot reach Praxis
- Make your work durable (protocol 1.3). Push your commits through
GitHub, then send
work.checkpointwith{workItemId, summary, nextAction, stepId?}and your ownexecution.id. Praxis verifies that the branch head it is checked out at is exactly the remote branch head, and records the checkpoint. Checkpoint at coherent boundaries: after a meaningful slice, before a handoff, and beforework.complete. Where the repository enforces durable checkpoints,work.completerefuses Git-backed work without a current one. - Taking over from an agent that disappeared (protocol 1.3). Read
work.context. Itscontinuityblock names the checkpoint commit, what was completed, the next action, and whether the remote still carries it. Then sendwork.continuewith{workItemId}. You get your own execution, with the predecessor as its parent; the predecessor is recorded as interrupted. No block and resume are needed. Continue before you complete:work.completeis refused asdomain-rejectedwhile the item still has an active execution that is not yours, whether or not you name an execution. - Handing off intentionally. Checkpoint, then send
work.blockwith a reason that says it is a handoff. If work that no checkpoint covers must be left behind, addunrecoverableReasonstating truthfully why it cannot be made durable.work.resumeis legal only fromblocked. - Taking over from another agent. Resume the work item as yourself. You
get your own execution, and Praxis records its
parentExecutionIdas the predecessor's execution. You never continue, or record telemetry into, an execution that is not yours. Praxis refuses that, and it applies equally to another run of your own agent. - If the predecessor left the item active and the executor only
supports protocol 1.2,
work.resumeis refused asdomain-rejected. Sendwork.blockyourself, with a reason that names the predecessor's session or execution and says you are taking over, thenwork.resume. The block is recorded as your action, not the predecessor's. With 1.3, usework.continue. - You cannot run Praxis, cannot dispatch, and cannot commit. Stop.
Report what you recovered (the checkpoint, what was completed, the next
action) and why you cannot continue. Hand off to an executor that can.
Do not edit the work or
.ros/state by hand, and do not ask anyone to send requests under your name. A request must come from the agent it names. - You could not invoke Praxis at all. Commit your legitimate work
normally. When Praxis is reachable again, attribute that work with
work.reconcile, naming the commits. The attribution is recorded aspost-hoc. The original Git author and committer are preserved, and you are recorded separately as the reconciliation actor. Never touch or recommit files to make them look attributed. Reconciliation is idempotent, and a change already reconciled to another work item is a conflict. It is never overwritten.
6. Read the outcome
failure.retry |
What to do |
|---|---|
never |
Fix the request. Examples: invalid-request, unauthorized, domain-rejected. |
after-refresh |
Re-read the branch, then form a new request with a new expectedSha. Examples: stale-ref, concurrency-conflict. |
same-request |
Retry the identical document with the same requestId. Examples: timeout, transport-failed. |
An outcome of unknown never means success. Retry with the same request
ID, or ask request.status.
A later agent can read everything you recorded and continue the work under its own identity. That handoff is how continuity works here; nobody needs to impersonate anyone.