NexusAIAgentFramework

Nexus

Every AI agent run should be a file you can audit, replay, and resume.

🌐 nexus-agent-runs.netlify.app, where the OAR schemas are hosted too (run · step).

Nexus is two things:

1. The Open Agent Run (OAR) format: a small, vendor-neutral, versioned spec ([spec/SPEC.md](spec/SPEC.md)) for durable agent runs: the state machine, the messages, the approvals, the costs, and an append-only audit journal. Public domain (CC0). Every framework today traps this data in proprietary shapes; OAR sets it free.
2. The reference runtime: a durable, model-agnostic agent runtime with zero runtime dependencies that produces and consumes that format.

Every agent framework can call an LLM in a loop. Almost none of them answer the questions that actually matter in production:

• What happens when the process crashes mid-run? → Nexus runs are persistent and resumable.
• How do I stop an agent from doing something dangerous? → Approval gates pause the run until a human approves, denies, edits the arguments before they run, or answers the call directly.
• How do I stop an agent from burning $400 overnight? → Per-run token and USD budgets halt execution, checked before each model call.
• What exactly did the agent do? → Every LLM call, tool execution, and decision is journaled, and the whole run exports as OpenTelemetry spans to Datadog, Grafana, or Langfuse.
• Which customer did this run cost money for? → Tag a run and per-run cost becomes per-customer cost.
• How do I debug or regression-test agent behavior? → Any finished run replays deterministically from its own record, offline, for $0.00, and can be re-run against a new model or prompt with divergences reported.
• What about my MCP servers? → Point Nexus at any unmodified MCP server (stdio or HTTP) and its tools get durability, approvals, and budgets wrapped around them. Or expose Nexus itself as an MCP server so Claude or Cursor can drive durable runs.
• Which model vendor am I married to? → None. Anthropic, OpenAI, and Ollama (local) adapters ship in the box with token streaming and cancellation; the provider interface is ~10 lines.

Nexus is the reliability layer, not another orchestration DSL. Agents are a definition (provider + model + prompt + tools); the runtime makes their execution durable, governable, and observable.

npm install @nexusaiframework/runtime   # zero runtime dependencies

# working from source? clone this repo, then:
npm install    # dev deps only
npm test       # 171 tests
npm run demo   # full lifecycle offline, no API keys needed

Quick start

import {
  NexusRuntime, FileStorage, AnthropicProvider,
  defineAgent, defineTool,
} from '@nexusaiframework/runtime';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  parameters: {
    type: 'object',
    properties: { to: { type: 'string' }, subject: { type: 'string' }, body: { type: 'string' } },
    required: ['to', 'subject', 'body'],
  },
  requiresApproval: true,          // ← human must approve before this ever executes
  async execute({ to }) { /* ... */ return `sent to ${to}`; },
});

const runtime = new NexusRuntime({ storage: new FileStorage('.nexus') });

runtime.register(defineAgent({
  name: 'assistant',
  provider: new AnthropicProvider(),        // or OpenAIProvider / OllamaProvider
  model: 'claude-sonnet-4-5',
  systemPrompt: 'You are a helpful operations assistant.',
  tools: [sendEmail],
  maxTurns: 10,
  budget: { maxUsd: 0.50, maxTotalTokens: 100_000 },   // ← hard caps, enforced per run
}));

const run = await runtime.run('assistant', 'Email the team a status update.');

if (run.status === 'waiting_approval') {
  // ...maybe hours later, maybe from a different process entirely:
  const finished = await runtime.approve(run.id);
  console.log(finished.result);
}

Every run is a persistent state machine: running → waiting_approval → completed | failed | halted_budget | halted_max_turns | cancelled. Kill the process at any point and runtime.resume(runId) picks up where it left off. Tool results already recorded are never re-executed on resume.

CLI

nexus run assistant "Summarize today's tickets" --tag customerId=acme   # start + follow, tagged
nexus runs --status waiting_approval --tag customerId=acme   # filter by what needs a human, and by tag
nexus approve run_abc123 call_xyz                 # unblock it (from any process)
nexus approve run_abc123 call_xyz --edit '{"amountUsd":200}'   # correct the args, then run
nexus respond run_abc123 call_xyz --message "the balance is $412"   # answer without running the tool
nexus deny run_abc123 call_xyz --reason "wrong recipient"
nexus resume run_abc123                           # continue after crash/restart
nexus runs --status waiting_approval --stale 30m  # approvals past their SLA
nexus cancel-all --agent support                  # kill switch: stop everything
nexus show run_abc123 --steps                     # full audit journal
nexus serve --token $NEXUS_DASHBOARD_TOKEN        # dashboard + JSON API
nexus mcp                                         # expose the runtime as an MCP server

The CLI loads nexus.config.mjs (see examples/nexus.config.mjs), which exports a configured NexusRuntime.

Approvals that fit how teams actually work

// Policy rules decide the easy cases; humans decide the rest.
runtime.register(defineAgent({
  name: 'support', provider, model, tools,
  approvalPolicy: ({ toolName, arguments: args }) =>
    toolName === 'issue_refund' && Number(args.amountUsd)  pagerduty.trigger(run.id, run.waitingMs),
});
//   nexus runs --status waiting_approval --stale 30m   // the SLA-breach view from the CLI

// Scrub PII from the audit journal before it ships to your SIEM. The live run
// record keeps the real content (the runtime needs it to resume); only the
// journal copy is redacted, so pair with encryption-at-rest on your storage.
const runtime = new NexusRuntime({
  storage,
  redactStep: (type, detail) => redactPii(detail),
});

The honest split: Nexus gives you the audit journal, the human gates, per-run budgets, the kill switch, and stale-approval signals. You bring SSO/RBAC (an IdP + proxy in front of nexus serve), immutable log retention (ship the journal to your SIEM), scoped short-lived credentials (your tools fetch them server-side; the agent never holds a raw token), and network-egress control. Nexus is the governance core, not the whole perimeter.

Durable MCP

MCP standardized how agents reach tools; Nexus makes those tool calls safe to run unattended, with no changes to the server:

import { McpClient, mcpTools } from '@nexusaiframework/runtime';

const client = await McpClient.connect({
  command: 'npx', args: ['-y', '@your/mcp-server'],   // stdio…
  // …or url: 'https://mcp.example.com/mcp'           // …or Streamable HTTP
});

const tools = await mcpTools(client, {
  requiresApproval: ['issue_refund', 'delete_record'],  // policy in one line
  namespace: 'crm',
});

runtime.register(defineAgent({ name: 'support', provider, model, tools, budget: { maxUsd: 1 } }));

Every MCP call is journaled, budget-metered, resumable after a crash, and, where you say so, held for human approval. npx tsx examples/02-durable-mcp.ts demos the whole flow offline. The client is zero-dependency JSON-RPC over stdio or Streamable HTTP (SSE responses included).

Replay: turn production runs into test fixtures

A finished OAR run contains everything needed to re-execute it without the network:

import { replayRun } from '@nexusaiframework/runtime';

// exact replay: verifies the record reproduces byte-for-byte, offline, $0.00
const report = await replayRun(run);
report.identical;          // true

// regression replay: recorded tools + a LIVE candidate model or new prompt
const regression = await replayRun(run, {
  provider: new AnthropicProvider(),
  model: 'claude-sonnet-5',
  systemPrompt: newPrompt,
});
regression.divergences;    // where the new behavior differs from production

nexus replay does the exact-replay check from the CLI. Yesterday's incident becomes today's regression test.

Why this exists

Production agent systems need more than a model loop. They need durable state, explicit human control, spend limits, auditability, replay and operational escape hatches. Those concerns are often assembled across several orchestration, workflow and observability layers.

Nexus takes the position that a small, self-hosted, MIT-licensed library should provide that governance core without introducing a runtime dependency stack or another hosted control plane. It uses node:fs or SQLite for local persistence, fetch for providers, and keeps the integration boundaries open.

Storage

| Adapter | Durability | Requirements | |---|---|---| | MemoryStorage | none (tests/dev) | none | | FileStorage | JSON + append-only JSONL journal | any Node ≥ 20 | | SqliteStorage | single SQLite file | Node ≥ 22 (built-in node:sqlite), import from @nexusaiframework/runtime/sqlite | | PostgresStorage | shared database, multi-node | bring any pg-compatible client, import from @nexusaiframework/runtime/postgres |

The Storage interface is 5 methods; Redis/S3 adapters are straightforward contributions. PostgresStorage imports no driver of its own: you pass a pg Pool (or anything with a query method), so the zero-dependency guarantee holds.

Observability

Every run exports as OpenTelemetry spans following the GenAI semantic conventions, zero dependencies, over OTLP/HTTP:

import { attachOtel } from '@nexusaiframework/runtime';

attachOtel(runtime, { endpoint: 'http://localhost:4318' });
// invoke_agent → chat → execute_tool spans, with gen_ai.usage token counts,
// land in Datadog, Grafana, Langfuse, or any OTLP backend. No vendor SDK.
// Prompt/argument content is off by default (the convention's privacy default);
// pass { captureContent: true } to include it.

The runtime is also an EventEmitter: run:start, llm:call, llm:response, llm:token (streaming), tool:start, tool:end, approval:required, retry, run:complete, run:failed, run:halted. Wire them to your own logger or metrics. The step journal (nexus show --steps) is the permanent audit record.

Cost attribution with tags

await runtime.run('support', 'Refund order #4417', { tags: { customerId: 'acme', tier: 'enterprise' } });

// Tags ride through the record, journal, webhooks, and OTel spans.
const acme = await runtime.listRuns({ tags: { customerId: 'acme' } });
const spend = acme.reduce((sum, run) => sum + run.usage.costUsd, 0);   // per-customer cost, not per-invoice

Nexus as an MCP server

Expose the runtime's controls as MCP tools so Claude, Cursor, or any MCP client can drive durable runs:

nexus mcp        # serves run/list/get/approve/deny/respond/resume/cancel over stdio

The OAR ecosystem

The format is a real standard, not just our storage shape:

• Validators ship in the box: validateRun, validateStep, validateJournal check any producer's documents against the spec, zero dependencies, no JSON-Schema engine required.
• A Python reader (python/, stdlib only) is a second, independent implementation: python -m oar validate and python -m oar timeline .... Two implementations of one public-domain format is what makes it portable.

Status & roadmap

Today (v0.2, working and tested): the OAR format spec with JSON Schemas, conformance tests, in-box validators, and an independent Python reader; durable run loop; approval gates with policy rules plus edit-before-approve and respond; pre-flight token/USD budgets; token streaming and in-flight cancellation; OpenTelemetry export; run tags for cost attribution; Slack/webhook notifications; self-hosted dashboard (nexus serve, optional token auth); Nexus-as-MCP-server (nexus mcp); the operability kit (kill switch via cancelAll/disableAgent, stale-approval SLA watcher, journal redaction hook); retries with backoff; crash resume; deterministic + regression replay; MCP client adapter (stdio + Streamable HTTP); three provider adapters + scriptable mock; four storage adapters (memory, file, SQLite, Postgres); CLI; 171 tests; CI. Published on npm as @nexusaiframework/runtime.

Next (in order):

1. Standalone oar CLI (oar validate ) wrapping the shipped validators for use without installing the runtime.
2. Publish the Python reader to PyPI.
3. Track the MCP 2026-07-28 revision (stateless core, Tasks extension) in the client adapter once it is final.
4. Redis and S3 storage adapters.

Things we will not claim until they're real: a hosted cloud, "zero-copy" anything, adoption numbers we cannot cite.

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). npm test must pass; new behavior needs a test.

Maintainer

Nexus and the Open Agent Run work in this repository are designed and maintained by Athar Jameel Ahmed. The project is developed in the open under the BULMKT GitHub account.

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BULMKT
• Source: BULMKT/NexusAIAgentFramework
• License: MIT
• Homepage: https://nexus-agent-runs.netlify.app

Install and usage instructions live in the source repository linked above.