Claude Agent SDK (TypeScript)
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
@dynamoprotocol/claude-agent-sdk adds Dynamo to the Claude Agent SDK for TypeScript (query() with agents). It is the TypeScript twin of the Python Claude Agent SDK plugin. Every agent run gets its own capped slice of one budget. A sub-agent the run launches through the Agent tool (alias Task) runs on a child slice, which can never exceed what its parent has left. A run or a launch that would go over its slice is refused before it starts.
The SDK reports cost once per query and has no hook before each model call, so this plugin reserves per run and per sub-agent launch (the spawn-scoped profile), not per model call.
The plugin is not published. It is used from a clone of the repository.
Install and try it
These are the commands from the plugin README. They build the workspace and run the offline containment demo: the real SDK query() over a scripted stand-in for the Claude Code CLI, so Claude Code is never launched, no key is needed and no model is called. You need Node 22.12 or later and pnpm 9.
cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/core-host... -r build
pnpm --filter "@dynamoprotocol/claude-agent-sdk..." build
node packages/plugin-claude-agent-sdk-ts/examples/containment.mjs
The Claude Agent SDK is a peer dependency. The README installs it next to the package:
npm install @anthropic-ai/claude-agent-sdk@0.3.293
The SDK is published by its vendor under the vendor's own terms; installing it means accepting those terms.
Wrap an agent run in a budget
This is packages/plugin-claude-agent-sdk-ts/examples/app/with-dynamo.mjs: a small two-agent app with Dynamo added. It needs DYNAMO_CORE_URL and DYNAMO_OWNER_TOKEN set to a running core. make test-plugin-claude-agent-sdk-ts runs it against a local core (test/examples.test.ts).
// SPDX-License-Identifier: Apache-2.0
// A small multi-agent app on the Claude Agent SDK — with Dynamo.
// Runs offline: the scripted CLI stands in for Claude Code and the model.
import { DynamoClaude, usd } from "@dynamoprotocol/claude-agent-sdk";
import { ScriptedClaudeCli, scriptedOptions, spawn, text } from "@dynamoprotocol/claude-agent-sdk/testing";
const dyn = await DynamoClaude.connect({ cap: usd("5"), mandate: { categories: ["research", "writing"], maxDepth: 3 },
agents: { orchestrator: { slice: usd("2"), category: "writing" }, researcher: { slice: usd("1"), category: "research" } },
runBudgets: { orchestrator: usd("0.10"), researcher: usd("0.10") } });
const cli = new ScriptedClaudeCli();
cli.entry = "orchestrator";
cli.script("orchestrator", spawn("researcher", "grid-scale storage"), text("brief written"));
cli.script("researcher", text("three sources found"));
const agents = { researcher: { description: "Researches a topic.", prompt: "You research." } };
const options = scriptedOptions(cli, { model: "mock/scripted-1", agents });
let answer = "";
for await (const message of dyn.query("orchestrator", { prompt: "Write a brief on grid-scale storage", options })) {
if (message.type === "result") answer = message.result;
}
console.log(answer);
dyn.query(agent, { prompt, options })is the SDK'squery()for one run
of agent. Before launch it reserves runBudgets[agent] on the agent's stream.
- The example's
optionscome fromscriptedOptions(...)so it runs
offline; in your app, pass your own query() options.
- No price table is needed: the SDK reports cost in USD.
What a refusal looks like
A refusal is a plain Error subclass (the SDK exports no error base class to extend): DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied, DynamoAmendmentRefused and DynamoPermissionModeUnsafe, each with reason, streamId and headroom.
A refused sub-agent launch is denied by the PreToolUse hook with continue: false, so the CLI never launches it and stops the run; an unexpected error in the hook is a denial (admission_failed). The refusal is thrown after the run is settled; its result holds the result message and its receipts what the run was billed. A run that would start with permission checks bypassed is refused with DynamoPermissionModeUnsafe (permission_mode_unsafe) before anything is reserved or launched.
Funding modes
- Control Mode (Live). A budget the plugin opens itself (
cap) is
always a Control Mode budget: every check runs and no money moves. The quickstart and every test of this plugin use one.
- A funded budget. You can pass an existing stablecoin or credit card
budget by id (budgetId). The plugin does not refuse it, but no test runs the plugin on one. In those modes the core requires signed hops by default, and a sub-agent's slice opened without its delegator's signature is refused hop_unsigned. Pass hops (a LayerHops from @dynamoprotocol/agents: the delegator's key and each payee's own signed offer) so the plugin signs every hop it opens.
- Real money (Release-gated). A core runs a money mode only when its
operator allows it, and real-money settlement is not released.
Known limits
Read packages/plugin-claude-agent-sdk-ts/KNOWN-LIMITS.md in the repository before you rely on the plugin.