{"_id":"@agentrouterhq/sdk","_rev":"4-e8d784e4846e98a54e22ad84ff334979","name":"@agentrouterhq/sdk","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@agentrouterhq/sdk","version":"0.1.0","keywords":["agentrouter","agents","codex","claude-code","sandbox","coding-agents"],"license":"MIT","_id":"@agentrouterhq/sdk@0.1.0","maintainers":[{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"}],"homepage":"https://github.com/perixtar/AgentRouter#readme","bugs":{"url":"https://github.com/perixtar/AgentRouter/issues"},"dist":{"shasum":"1c2b1ab88f03ff41b98fe699dd7da97c432124b2","tarball":"https://registry.npmjs.org/@agentrouterhq/sdk/-/sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-WgGL5RSvlC080b6kYtOUOZxChX+1SBplRJCzXuwKxnFd+iMLjYEQtcAyOKnhMqwnojD/dYaiUpwDixwcIklsEQ==","signatures":[{"sig":"MEQCIFDOQ61vMlT1XTpXLJpVWSbUCF4OxnJDQ1z03JxIX821AiA4RfE3ItcfFt++HS0mD0tGXApuNXmz/zk+Wb/5Sed1Hw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42826},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"801ea0349228effa2ed23ce5dcd54b9b2afe96b9","scripts":{"build":"tsc -p tsconfig.json","prepack":"npm run build"},"_npmUser":{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"},"repository":{"url":"git+https://github.com/perixtar/AgentRouter.git","type":"git","directory":"packages/sdk-typescript"},"_npmVersion":"11.6.2","description":"TypeScript SDK for AgentRouter","directories":{},"sideEffects":false,"_nodeVersion":"25.1.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1780457193708_0.9699179281930848","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentrouterhq/sdk","version":"0.1.1","keywords":["agentrouter","agents","codex","claude-code","sandbox","coding-agents"],"license":"MIT","_id":"@agentrouterhq/sdk@0.1.1","maintainers":[{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"}],"homepage":"https://github.com/perixtar/AgentRouter#readme","bugs":{"url":"https://github.com/perixtar/AgentRouter/issues"},"dist":{"shasum":"94385bd70bca7b4d8ac7b5b7ee567ea81ec1152c","tarball":"https://registry.npmjs.org/@agentrouterhq/sdk/-/sdk-0.1.1.tgz","fileCount":6,"integrity":"sha512-wu+MCbkmzqI4r3KfMuJj8hAnbBOPY+EqOY9P50h3ulUl20AM4oaJziYlnzwuy0OuIFtWuCeHZ9P2VNL+j04ULg==","signatures":[{"sig":"MEQCIDJ92CmQyD9f/cuBC38JwJjrN1F8L1eLibWNhLA5PsZ2AiBqvMPygZiEpklR0HDkHzY6YWMCEcUPvN21lea78IpOrA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48719},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"03f5cf9b5d3a8ec1fefc743bc0bfa03dce1fe73d","scripts":{"build":"tsc -p tsconfig.json","prepack":"npm run build"},"_npmUser":{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"},"repository":{"url":"git+https://github.com/perixtar/AgentRouter.git","type":"git","directory":"packages/sdk-typescript"},"_npmVersion":"11.6.2","description":"TypeScript SDK for running Codex and Claude Code agents with AgentRouter","directories":{},"sideEffects":false,"_nodeVersion":"25.1.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.1_1780457844453_0.9328023569575716","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@agentrouterhq/sdk","version":"0.1.2","keywords":["agentrouter","agents","codex","claude-code","sandbox","coding-agents"],"author":"","license":"MIT","_id":"@agentrouterhq/sdk@0.1.2","maintainers":[{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"}],"homepage":"https://github.com/perixtar/AgentRouter#readme","bugs":{"url":"https://github.com/perixtar/AgentRouter/issues"},"dist":{"shasum":"32221fef3437556872b7173b3e8f8e365dc8fa20","tarball":"https://registry.npmjs.org/@agentrouterhq/sdk/-/sdk-0.1.2.tgz","fileCount":6,"integrity":"sha512-zFva4QWT/v+kasg3hPGWS8QeuorST3KrftV95VJtmSKsfLWCcX1saFOIO++nRQmb39SNXvBZT6ZClzoZEQJpng==","signatures":[{"sig":"MEQCIC/P6nO1zp5wD8QDoyqLVJGil1YIrRyCk6HX6B0jQLO1AiBeAa+nqr7sfDUEdRS3UN7ZlC4h5k1YAIb63Kk89qYQ/A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45988},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"187f4b2eb5818c089158b774217b68e88e458dee","scripts":{"build":"tsc -p tsconfig.json","prepack":"npm run build"},"_npmUser":{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"},"repository":{"url":"git+https://github.com/perixtar/AgentRouter.git","type":"git","directory":"packages/sdk-typescript"},"_npmVersion":"11.6.2","description":"TypeScript SDK for running Codex and Claude Code agents with AgentRouter","directories":{},"sideEffects":false,"_nodeVersion":"25.1.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.2_1780470714929_0.606502612935206","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@agentrouterhq/sdk","version":"0.1.3","description":"TypeScript SDK for running Codex and Claude Code agents with AgentRouter","license":"MIT","type":"module","sideEffects":false,"keywords":["agentrouter","agents","codex","claude-code","sandbox","coding-agents"],"repository":{"type":"git","url":"git+https://github.com/perixtar/AgentRouter.git","directory":"packages/sdk-typescript"},"bugs":{"url":"https://github.com/perixtar/AgentRouter/issues"},"homepage":"https://github.com/perixtar/AgentRouter#readme","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","prepack":"npm run build"},"publishConfig":{"access":"public"},"author":"","gitHead":"8c7e339f36593d4daf03003a7ca24f7e380e8ed6","_id":"@agentrouterhq/sdk@0.1.3","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-v0EhW82TYxyGBLHHFFIqhwk7wJopIO8T5WjUYaHUTigerCaW11NtH/HoNjFRc639rFe1nIMBXZ/e4Zd6cxthPw==","shasum":"c4d21f28fccbbcb6a7a811765edf20907f957cea","tarball":"https://registry.npmjs.org/@agentrouterhq/sdk/-/sdk-0.1.3.tgz","fileCount":6,"unpackedSize":55507,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentrouterhq%2fsdk@0.1.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDxeKaSx9U4ZA8eFZcjWtkCzalSSLt6n8ksUD3swgSekAIgeDhK8XhpaMPH7LFTHHlEZ5JfCZnu8qi40EWLGknesXE="}]},"_npmUser":{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"},"directories":{},"maintainers":[{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.3_1781416681637_0.28785826300619766"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T03:26:33.553Z","modified":"2026-06-14T05:58:02.058Z","0.1.0":"2026-06-03T03:26:33.878Z","0.1.1":"2026-06-03T03:37:24.604Z","0.1.2":"2026-06-03T07:11:55.177Z","0.1.3":"2026-06-14T05:58:01.767Z"},"bugs":{"url":"https://github.com/perixtar/AgentRouter/issues"},"license":"MIT","homepage":"https://github.com/perixtar/AgentRouter#readme","keywords":["agentrouter","agents","codex","claude-code","sandbox","coding-agents"],"repository":{"type":"git","url":"git+https://github.com/perixtar/AgentRouter.git","directory":"packages/sdk-typescript"},"description":"TypeScript SDK for running Codex and Claude Code agents with AgentRouter","maintainers":[{"name":"agentrouterhq","email":"agentrouter2026@gmail.com"}],"readme":"# AgentRouter TypeScript SDK\n\n[![npm version](https://img.shields.io/npm/v/@agentrouterhq/sdk.svg)](https://www.npmjs.com/package/@agentrouterhq/sdk)\n[![license](https://img.shields.io/npm/l/@agentrouterhq/sdk.svg)](https://github.com/perixtar/AgentRouter/blob/main/LICENSE)\n[![types](https://img.shields.io/badge/types-TypeScript-3178c6)](https://github.com/perixtar/AgentRouter)\n\nThe TypeScript client for AgentRouter, a self-hosted runtime for running Codex\nand Claude Code agents in secure sandboxes.\n\nUse the SDK to create agent runs, stream observable progress, continue a\nconversation by run id, fetch artifacts, and control long-running coding-agent\nworkflows from your app, CLI, or CI.\n\n## Installation\n\n```sh\nnpm install @agentrouterhq/sdk\n```\n\n```sh\npnpm add @agentrouterhq/sdk\n```\n\n```sh\nyarn add @agentrouterhq/sdk\n```\n\n## Requirements\n\n- A running AgentRouter API, usually `http://127.0.0.1:8787` for local\n  self-hosting.\n- An `AGENTROUTER_API_KEY` bearer token configured on the AgentRouter API.\n- Provider credentials on the runtime side, such as `OPENAI_API_KEY`,\n  `CODEX_API_KEY`, or `ANTHROPIC_API_KEY`.\n- A server-side TypeScript or JavaScript runtime with `fetch`.\n\nThis SDK does not call OpenAI, Anthropic, Daytona, or R2 directly. It talks to\nyour AgentRouter API, and the runtime keeps provider keys server-side.\n\n## Quickstart\n\n```ts\nimport { agentrouter, codex, runAgent } from \"@agentrouterhq/sdk\";\n\nconst client = agentrouter({\n  baseUrl: \"http://127.0.0.1:8787\",\n  apiKey: process.env.AGENTROUTER_API_KEY!\n});\n\nconst result = await runAgent({\n  client,\n  task: \"Inspect this repo and summarize the test strategy.\",\n  runtime: codex({ mode: \"default\", model: \"gpt-4o\" })\n});\n\nconsole.log(result.status);\nconsole.log(result.text);\n```\n\n`runAgent` creates a run, waits until it reaches a terminal state, and returns\nthe final session snapshot:\n\n```ts\nresult.id;               // run id\nresult.status;           // completed | failed | cancelled\nresult.text;             // final agent response text, when available\nresult.artifacts.items;  // generated logs, patches, and workspace artifacts\nresult.eventCursor;      // last observed event sequence\n```\n\n## Streaming a run\n\nUse `streamAgent` when you want progress updates while the sandboxed agent is\nworking.\n\n```ts\nimport { agentrouter, codex, streamAgent } from \"@agentrouterhq/sdk\";\n\nconst client = agentrouter({\n  baseUrl: process.env.AGENTROUTER_API_BASE_URL ?? \"http://127.0.0.1:8787\",\n  apiKey: process.env.AGENTROUTER_API_KEY!\n});\n\nconst stream = await streamAgent({\n  client,\n  task: \"Create reports/agent-smoke.txt and explain what you changed.\",\n  runtime: codex({ mode: \"full_access\" }),\n  pollIntervalMs: 1000,\n  maxWaitMs: 10 * 60 * 1000\n});\n\nfor await (const part of stream.fullStream) {\n  if (part.type === \"progress\") console.log(\"process:\", part.text);\n  if (part.type === \"message\") console.log(\"agent:\", part.text);\n  if (part.type === \"text\") process.stdout.write(part.text);\n  if (part.type === \"error\") console.error(part.text);\n}\n\nconst final = await stream.finalResult;\nconsole.log(final.status);\n```\n\n`fullStream` emits safe progress summaries, no-progress warnings, messages,\nfinal text, errors, and terminal status. It does not expose hidden model\nchain-of-thought.\n\nIf you only want final text chunks:\n\n```ts\nfor await (const text of stream.textStream) {\n  process.stdout.write(text);\n}\n```\n\n## Control-plane events\n\nAgentRouter streams two related surfaces:\n\n- `stream.events` yields raw persisted `RunEvent` records exactly as stored by\n  the runtime control plane.\n- `stream.fullStream` yields ergonomic `AgentStreamPart` objects for app code.\n\nUse `fullStream` for most products. Drop to raw events when you need the\nsequence number, original payload, artifact references, or audit trail.\n\n| Raw event | `fullStream` part | Purpose |\n| --- | --- | --- |\n| `action.proposed` | `action` | AgentRouter has defined the exact runtime action it may execute, including `actionId`, `actionDigest`, target, and schema version. |\n| `policy.evaluated` | `progress` | The configured policy decided whether that action is `allowed`, `requires_approval`, or `blocked`. |\n| `approval.requested` | `approval_request` | The run is paused until your app records an approval decision for the same `actionDigest`. |\n| `approval.decided` | `approval_decision` | A human or approval system approved or denied the action. Repeated identical decisions are deterministic no-ops. |\n| `execution.started` | `execution` | The approved action started inside the sandbox. |\n| `execution.completed` | `execution` | The action completed successfully. |\n| `execution.failed` | `execution` | Runtime execution failed after policy/approval; this does not rewrite the approval decision. |\n| `agent.progress` | `progress` | Public progress summary from the provider stream. Hidden reasoning is not exposed. |\n| `agent.no_progress` | `no_progress` | The runtime saw a suspected loop, such as repeated failed commands, repeated edits, or long output without state transitions. Use this to show a warning, ask for approval, cancel, or retry from the current state. |\n| `agent.message` | `message` | Assistant-visible message content before the final normalized response. |\n| `agent.response` | `text` | Final normalized agent response text. |\n| `run.completed`, `run.failed`, `run.cancelled` | `done` or `error` | Terminal run state. |\n\nNo-progress handling example:\n\n```ts\nfor await (const part of stream.fullStream) {\n  if (part.type === \"no_progress\") {\n    console.warn(`Agent may be stuck: ${part.signal} - ${part.text}`);\n    // Your app can cancel the run, ask for approval, or let the user continue.\n  }\n}\n```\n\nThe raw `agent.no_progress` event stays in `stream.events`, session manifests,\nand artifact-backed event archives, so dashboards and audit views can replay\nwhen the loop signal happened.\n\nManual approval example:\n\n```ts\nconst stream = await streamAgent({\n  client,\n  task: \"Run the repository tests and summarize failures.\",\n  runtime: codex({ mode: \"full_access\" }),\n  approvalMode: \"manual\"\n});\n\nfor await (const part of stream.fullStream) {\n  if (part.type === \"approval_request\") {\n    await client.approveRunAction({\n      runId: stream.run.id,\n      actionId: part.actionId,\n      actionDigest: part.actionDigest,\n      reason: \"Approved by CI policy\"\n    });\n  }\n\n  if (part.type === \"execution\") {\n    console.log(part.status);\n  }\n}\n```\n\n`actionDigest` is the important safety field. An approval for digest A cannot\nstart execution for digest B.\n\n## Continue a conversation\n\nAgentRouter can keep a sandbox and provider thread alive after a run finishes.\nThe first run id becomes the conversation handle.\n\nRun ids are the SDK's public conversation handle. Use `streamAgent` with\n`continueRun` for streamed follow-up turns, or `runAgent` with `continueRun`\nwhen you only need the final result. There is no separate public session API.\n\n`conversationId` and `runId` are different on follow-up turns:\n\n```txt\nconversationId  stable id for the whole conversation; pass this as continueRun\nrunId           id for one specific turn; stream/fetch this turn's events\n```\n\nFor turn 1 they are the same id. For turn 2+, `conversationId` stays fixed as\nthe first run id, while `runId` is the newly-created run for that turn.\n\n```ts\nimport { agentrouter, codex, runAgent, streamAgent } from \"@agentrouterhq/sdk\";\n\nconst client = agentrouter({\n  baseUrl: \"http://127.0.0.1:8787\",\n  apiKey: process.env.AGENTROUTER_API_KEY!\n});\n\nconst firstTurn = await runAgent({\n  client,\n  task: \"Create src/fib.ts with a fib(n) function.\",\n  runtime: codex({ mode: \"full_access\" })\n});\n\nconst secondTurn = await streamAgent({\n  client,\n  continueRun: firstTurn.id,\n  message: \"Now add tests for fib(n).\"\n});\n\nfor await (const part of secondTurn.fullStream) {\n  if (part.type === \"progress\") console.log(part.text);\n  if (part.type === \"text\") process.stdout.write(part.text);\n}\n\nawait client.closeRun(firstTurn.id);\n```\n\nYou can also continue and wait in one call:\n\n```ts\nconst result = await runAgent({\n  client,\n  continueRun: firstTurn.id,\n  message: \"Add edge-case tests for n = 0 and n = 1.\"\n});\n```\n\n## Claude Code runs\n\nUse `claudeCode` instead of `codex` to run the same workflow through Claude\nCode.\n\n```ts\nimport { agentrouter, claudeCode, runAgent } from \"@agentrouterhq/sdk\";\n\nconst client = agentrouter({\n  baseUrl: \"http://127.0.0.1:8787\",\n  apiKey: process.env.AGENTROUTER_API_KEY!\n});\n\nconst result = await runAgent({\n  client,\n  task: \"Review the current repository and suggest the highest-impact cleanup.\",\n  runtime: claudeCode({ permissionMode: \"default\", model: \"claude-sonnet-4-6\" })\n});\n\nconsole.log(result.text);\n```\n\n## Low-level client\n\nThe helper functions are built on top of a small typed client. Use it directly\nwhen you need more control.\n\n```ts\nconst run = await client.createRun({\n  task: \"Run the test suite and summarize failures.\",\n  runtime: codex({ mode: \"read_only\" }),\n  metadata: { source: \"ci\" },\n  idempotencyKey: \"pr-123-review\"\n});\n\nfor await (const event of client.streamRun(run.id)) {\n  console.log(event.sequence, event.type);\n}\n\nconst runSession = await client.getRunSession(run.id);\nconst artifacts = await client.listRunArtifacts(run.id);\n```\n\nAvailable client methods:\n\n| Method | Purpose |\n| --- | --- |\n| `createRun` | Queue a new agent run |\n| `createRunAndWait` | Queue a run and wait for the final run session snapshot |\n| `getRun`, `listRuns`, `cancelRun` | Inspect and control runs |\n| `listRunEvents`, `streamRun` | Read observable run events |\n| `getRunSession` | Get the final run response, event cursor, and artifact manifest |\n| `listRunArtifacts`, `downloadArtifact` | Inspect and download artifacts |\n| `approveRunAction`, `denyRunAction` | Record an immutable approval decision for an `approval.requested` action digest |\n| `continueRun`, `getRunTurns`, `closeRun` | Continue, inspect, or close a run-id conversation |\n\n## Runtime options\n\nCodex:\n\n```ts\ncodex({ mode: \"default\", model: \"gpt-4o\" });\ncodex({ mode: \"read_only\" });\ncodex({ mode: \"full_access\" });\ncodex({ mode: \"auto_review\" });\n```\n\nClaude Code:\n\n```ts\nclaudeCode({ permissionMode: \"default\" });\nclaudeCode({ permissionMode: \"plan\" });\nclaudeCode({ permissionMode: \"acceptEdits\" });\nclaudeCode({ permissionMode: \"bypassPermissions\" });\n```\n\n## Custom headers and fetch\n\nUse `defaultHeaders` when your self-hosted deployment needs per-client headers,\nfor example tenant routing or internal request metadata.\n\n```ts\nconst client = agentrouter({\n  baseUrl: \"https://agentrouter.example.com\",\n  apiKey: process.env.AGENTROUTER_API_KEY!,\n  defaultHeaders: {\n    \"x-workspace-id\": \"workspace_123\"\n  }\n});\n```\n\nUse `fetchImpl` when your runtime needs a custom fetch implementation.\n\n```ts\nconst client = agentrouter({\n  apiKey: process.env.AGENTROUTER_API_KEY!,\n  fetchImpl: customFetch\n});\n```\n\n## Error handling\n\nAPI errors and wait timeouts throw `AgentRouterError`.\n\n```ts\nimport { AgentRouterError, agentrouter, codex, runAgent } from \"@agentrouterhq/sdk\";\n\nconst client = agentrouter({\n  baseUrl: \"http://127.0.0.1:8787\",\n  apiKey: process.env.AGENTROUTER_API_KEY!\n});\n\ntry {\n  await runAgent({\n    client,\n    task: \"Run tests.\",\n    runtime: codex({ mode: \"default\" }),\n    maxWaitMs: 60_000\n  });\n} catch (error) {\n  if (error instanceof AgentRouterError) {\n    console.error(error.code);\n    console.error(error.statusCode);\n    console.error(error.details);\n  } else {\n    throw error;\n  }\n}\n```\n\nCommon SDK-side error codes:\n\n| Code | Meaning |\n| --- | --- |\n| `wait_timeout` | A run did not reach a terminal state before `maxWaitMs` |\n| `invalid_run_agent_request` | `runAgent` received neither a new task nor a continuation message |\n\nServer-side API errors keep the error code returned by the AgentRouter API.\n\n## Security notes\n\n- Keep `AGENTROUTER_API_KEY` on the server side. Do not ship it to an\n  untrusted browser client.\n- Provider keys stay in the AgentRouter runtime environment, not in SDK calls.\n- `fullStream` exposes observable progress and final output, not hidden\n  chain-of-thought.\n- Agent commands run inside the sandbox provider configured by your\n  self-hosted runtime.\n\n## Links\n\n- [GitHub repository](https://github.com/perixtar/AgentRouter)\n- [Self-hosting guide](https://github.com/perixtar/AgentRouter/blob/main/docs/self-hosting.md)\n- [Examples](https://github.com/perixtar/AgentRouter/tree/main/examples)\n- [Security policy](https://github.com/perixtar/AgentRouter/blob/main/SECURITY.md)\n","readmeFilename":"README.md"}