technology
How it works

The run is the source of truth.

The persisted record is the execution; the process is just the thing currently advancing it. Everything else falls out of that inversion.

The state machine, live

user task → running
llm turn · persisted
safe tool · executed & journaled
⏸ waiting_approval, durable pause
gated tool · approved by human
✓ completed, forever auditable

The invariant that matters

A tool call whose result is already recorded is never executed twice. Approve one of three calls tomorrow, the two that already ran stay ran.

Two files per run

Snapshot, run.oar.json

Status, full conversation, pending approvals, cost. Mutable, atomically replaced.

Journal, steps.jsonl

Append-only: every LLM call, tool execution, and decision with who made it. Never rewritten. This is the audit artifact.

Both have public-domain JSON Schemas, the Open Agent Run spec. Any tool can audit; any conforming runtime can resume; anyone can replay.

Replay

nexus replay run_8a4f21
llm turn 1 ← recorded
lookup_customer ← recorded
issue_refund ← recorded
✔ identical to the record
offline · $0.00 · deterministic

Or replay against a new model or prompt: recorded tool results become fixtures, and every divergence is reported at the exact call where behavior changed.

Durable MCP

Wraps any unmodified MCP server

stdio or HTTP, zero-dep JSON-RPC. Every tool call: journaled · budget-metered · approval-gated · resumable · replayable. One line of policy. MCP's own roadmap lists durability as an open problem, this is the answer you can deploy today.

And the reverse: nexus mcp

Exposes Nexus itself as an MCP server over stdio: run, approve, deny, respond, resume, and list durable runs as MCP tools, so Claude or Cursor can drive them.

Approvals are an execution point

Four moves, all journaled

On a pause a human can approve, deny, approve with edited arguments (authorize $50 instead of the proposed $250 before it runs), or respond to answer the call directly so the tool never runs. Human-in-the-loop is an architecture, not a yes/no gate.

Observability & cost attribution

attachOtel(runtime, {
  endpoint: OTEL_ENDPOINT });
// GenAI spans: invoke_agent → chat → execute_tool
// token usage · prompt content off by default
// → Datadog, Grafana, Langfuse, any OTLP backend

await runtime.run('support', t, {
  tags: { customerId: 'acme-42' } });
// tags ride record, journal, webhooks & spans

"Which customer moved the bill" becomes listRuns({ tags }), not a forensics project. The exporter speaks OTLP, so runs flow into your SIEM or APM with no vendor SDK.

Streaming & cancellation

Tokens live, stop mid-flight

Providers stream tokens as an llm:token event, and cancel() aborts a live model call in flight, not just at the next checkpoint.

A format with two implementations

oar/0.2, read two ways

Zero-dep validateRun/validateStep/validateJournal in the box, plus a stdlib-only Python reader (python -m oar validate|timeline). Two independent implementations of a public-domain format is what makes it a real standard.

Storage

Four adapters

Memory, file (zero-dep default), built-in SQLite, and Postgres for multi-node, bring your own pg client so it stays zero-dependency. The interface is 5 methods.

See the live demo →