CLI
Response-producing commands emit exactly one JSON object on stdout. Diagnostics stay on stderr; raw output remains available even when inline compression is enabled.
Read the output contractRun it now. Reconnect when it finishes.
agent-exec turns unknown-duration commands into durable jobs. It watches the risky first seconds, returns one JSON response, and keeps the process available through a stable job_id.
$ agent-exec run -- cargo test --all
{
"ok": true,
"type": "run",
"job_id": "a4f27c91…",
"state": "running",
"stdout": "Compiling agent-exec…"
}Catch a bad start without another round trip.
run observes for up to 10 seconds by default. Fast failures arrive in the first response; longer work continues as a job. Use --no-wait only when immediate return matters more than startup feedback.
The same job, whenever you return.
Every operation is bounded, non-interactive, and machine-readable. Keep the job_id; choose what the agent needs next.
statusRead the current state without waiting.
waitObserve until a bounded deadline and receive the exit code when terminal.
tailRetrieve bounded stdout and stderr again, with byte ranges and retained log paths.
killExplicitly stop the process. An observation deadline never stops the job.
Detached shell, with a contract.
Durability is only useful when the next agent turn can discover what happened.
| Capability | Subprocess | nohup | agent-exec |
|---|---|---|---|
| Return before completion | No | Yes | Yes |
| Stable job identifier | No | No | Yes |
| Structured state and exit result | Limited | No | Yes |
| Discoverable retained logs | Caller-managed | Caller-managed | Yes |
| Reconnect later | Caller-managed | Manual | Yes |
Use one lifecycle from any agent surface.
The CLI contract also powers MCP and HTTP integrations. No separate job model to learn.
MCP
Expose run, status, tail, wait, and kill over stdio.
HTTP
Serve the lifecycle on loopback for local tools and controlled automation.
Review HTTP safety