Most frameworks treat an agent run as ephemeral control flow that happens to emit logs. Nexus inverts that: the persisted run record is the execution, and the process is just the thing currently advancing it. Everything else, crash resume, approvals, budgets, replay, falls out of that inversion.
Watch the lifecycle, this is the actual state machine from the spec, not an illustration:
running (crashed process), waiting_approval, halted_budget, halted_max_turns, call resume() and execution continues exactly where the record says it stopped.
completed, failed, cancelled. Terminal runs stay forever as audit records, and become replay fixtures.
A tool call whose result is already recorded is never executed twice. Approve one of three tool calls tomorrow; the two safe ones that already ran stay ran.
Two artifacts per run, a mutable snapshot and an immutable journal. Both have public-domain JSON Schemas. Watch a run being written:
{
"format": "oar/0.2",
"id": "run_8a4f21",
"agent": "support",
"model": "claude-sonnet-4-5",
"status": "waiting_approval",
"messages": […full conversation…],
"pendingApprovals": [{
"toolName": "issue_refund",
"arguments": { "amountUsd": 250 }
}],
"usage": { "costUsd": 0.0041, … }
}
Because the record is complete and open, any tool can audit it, any conforming runtime can resume it, and anyone can replay it, without Nexus. That's the difference between a framework feature and a format. Read the 2-page spec →
Assistant messages in the record are the model's recorded responses; tool results are the recorded outputs. So a finished run re-executes with zero API calls, and diffs precisely against a new model or prompt.
Verifies the engine reproduces the record byte-for-byte. Debug production incidents locally with the actual data, not a reconstruction.
Recorded tool results + a live candidate model or new prompt. Divergences are reported at the precise tool call where new behavior departs from production. Run it in CI.
When a run pauses on an approval, a person has four moves, and every one is journaled with who made it. Approve is only the simplest.
// let it run as the model proposed await runtime.approve(runId, callId); // run it, but fix the arguments first await runtime.approve(runId, callId, { edited: { amountUsd: 50 } }); // refuse; the model sees the denial and reacts await runtime.deny(runId, callId, 'over policy'); // answer the call directly; the tool never runs await runtime.respond(runId, callId, 'refund already issued by phone');
The model wanted to refund $250; the reviewer authorizes $50 instead. The tool runs with the corrected input, and the journal records both what was proposed and what was approved.
Sometimes the right move is not to run the tool at all but to hand the agent a fact: "already handled," "use account B." respond injects that result so the run continues, tool untouched, still journaled.
One call attaches an OpenTelemetry exporter. Nexus emits GenAI-convention spans over OTLP/HTTP with zero dependencies, so runs show up in the tracing stack you already operate.
import { attachOtel } from '@nexusaiframework/runtime'; attachOtel(runtime, { endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT, }); // spans: invoke_agent → chat → execute_tool // token usage attached, prompt content off by default // lands in Datadog, Grafana, Langfuse, any OTLP backend
// tag a run once… await runtime.run('support', ticket, { tags: { customerId: 'acme-42' }, }); // …and the tag rides the record, the journal, // your webhooks, and every OTel span. await runtime.listRuns({ tags: { customerId: 'acme-42' } }); // "whose runs doubled the bill?" is now a filter
No vendor lock in the trace path: the exporter speaks OTLP, so the same runs flow into your SIEM or APM without a proprietary agent SDK. See the enterprise framing →
Providers stream tokens as an event, so a UI can render partials as the model writes. And cancellation aborts a live model call in flight, not just at the next checkpoint.
// render tokens as the model produces them runtime.on('llm:token', ({ runId, token }) => process.stdout.write(token)); // abort the in-flight call now, not at the next step boundary await runtime.cancel(runId);
No changes to the server. Nexus speaks raw JSON-RPC over stdio and Streamable HTTP, no SDK, and wraps every tool the server exposes:
Why it matters: MCP's own 2026 roadmap lists durability, retry semantics, and enterprise controls as open problems, and 2025-26 saw real attacks flow through over-privileged MCP tools. Gating and journaling the tool layer is where the blast radius gets contained. See the case studies →
We already wrap servers. Now nexus mcp exposes Nexus itself as an MCP server over stdio, so Claude, Cursor, or any MCP client can start, approve, deny, respond to, resume, and list durable runs as tools. The agent driving the runtime becomes just another MCP client.
# expose run/approve/deny/respond/resume/list # as MCP tools over stdio $ nexus mcp
OAR is public domain, and it now has two independent conformance implementations. A format only one codebase can read is a file layout; a format two unrelated codebases agree on is something you can build on for a decade.
import { validateRun, validateStep, validateJournal } from '@nexusaiframework/runtime'; validateRun(record); // throws on non-conformance validateJournal(steps); // checks the append-only log
$ python -m oar validate run_8a4f21.oar.json ✔ conforms to oar/0.2 $ python -m oar timeline run_8a4f21.oar.json # prints the run as a readable step timeline
The format is now oar/0.2, additive over 0.1, so older runs still validate. Read the spec →
Providers speak fetch. Storage is node:fs, built-in SQLite, or your own pg client. MCP is hand-rolled JSON-RPC. Your security team reviews our code, not 300 transitive packages.
The Provider interface is one method; Storage is five, with four adapters in the box, memory, file, built-in SQLite, and Postgres for multi-node. Anthropic, OpenAI, and Ollama ship too; local models mean fully air-gapped agents.
OpenTelemetry export, an event stream, Slack/webhook notifications, a self-hosted dashboard (nexus serve), and a CLI for everything, all zero-dep.