@theokit/sdk 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-06-12
+
+### Added
+
+- `.claude/` consumer template with 15 domain-specific passive skills, convention rules, AGENTS.md (cross-agent), and CLAUDE.md for AI coding tool integration. Scaffold via `npx theokit-init-claude`. Skills auto-inject TheoKit API knowledge when editing files matching each domain (Agent Core, Tools, Memory, DI, DI-Agent, Gateways, RAG, Workflows, Eval, Cron, Subscriptions, Errors, Config, Streaming, Budget). 33 tests.
+
 ## [1.7.0] - 2026-06-11
 
 ### Changed

package/bin/init-claude.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { cpSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// EC-1: Node version guard (matches SDK engines.node)
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 12)) {
+  console.error(`@theokit/sdk requires Node >= 22.12.0. Current: ${process.version}`);
+  process.exit(1);
+}
+
+const templateDir = join(import.meta.dirname, "../claude-template");
+const cwd = process.cwd();
+const targetDir = join(cwd, ".claude");
+const force = process.argv.includes("--force");
+
+// EC-4: Check .claude/, AGENTS.md, CLAUDE.md independently
+const conflicts = [];
+if (existsSync(targetDir)) conflicts.push(".claude/");
+if (existsSync(join(cwd, "AGENTS.md"))) conflicts.push("AGENTS.md");
+if (existsSync(join(cwd, "CLAUDE.md"))) conflicts.push("CLAUDE.md");
+
+if (conflicts.length > 0 && !force) {
+  console.error(`Already exists: ${conflicts.join(", ")}. Use --force to overwrite.`);
+  process.exit(1);
+}
+
+cpSync(join(templateDir, "dot-claude"), targetDir, { recursive: true });
+cpSync(join(templateDir, "AGENTS.md"), join(cwd, "AGENTS.md"));
+cpSync(join(templateDir, "CLAUDE.md"), join(cwd, "CLAUDE.md"));
+
+console.log("Created .claude/ with TheoKit SDK configuration (15 domain skills).");
+console.log("Created AGENTS.md (cross-agent) and CLAUDE.md (Claude Code).");
+console.log("\nNext: open Claude Code and start building with TheoKit.");

package/claude-template/AGENTS.md

@@ -0,0 +1,139 @@
+# @theokit/sdk — TypeScript SDK for AI Agents
+
+Build AI agents that run locally or in the cloud. Same code, same API, pick your runtime.
+
+## Setup
+
+```bash
+npm install @theokit/sdk
+```
+
+Set your API key:
+```bash
+export THEOKIT_API_KEY="your-key"
+```
+
+## Import Map
+
+```typescript
+import { Agent } from "@theokit/sdk";                         // Core: Agent, Run, SDKMessage
+import { defineTool } from "@theokit/sdk";                     // Tool definitions
+import { TheokitAgentError } from "@theokit/sdk/errors";       // Error hierarchy
+import { Cron } from "@theokit/sdk/cron";                      // Scheduled jobs
+import { Eval } from "@theokit/sdk/eval";                      // Evaluation suite
+import { Workflow } from "@theokit/sdk/workflow";               // Multi-step workflows
+import { defineSubscription } from "@theokit/sdk/subscription"; // SSE/WebSocket subscriptions
+import { VectorRetriever } from "@theokit/sdk/rag";            // RAG: retrievers, rerankers, splitters
+import { defineSubAgent } from "@theokit/sdk/a2a";             // Agent-to-agent delegation
+import { SandboxBackend } from "@theokit/sdk/sandbox";         // Sandbox backends
+import { defineAuth } from "@theokit/sdk/server/auth";         // Authentication
+import { TaskStore } from "@theokit/sdk/task-store";           // Task persistence
+import { createClient } from "@theokit/sdk/client";            // HTTP client
+```
+
+## Quick Start
+
+```typescript
+const agent = await Agent.create({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+
+const run = await agent.send("Summarize this repository");
+for await (const event of run.stream()) {
+  if (event.type === "assistant") console.log(event.content);
+}
+
+agent.dispose(); // Always clean up
+```
+
+## Core Patterns
+
+### Agent lifecycle
+- `Agent.create(options)` — create an agent (local or cloud)
+- `agent.send(prompt)` — send a message, get a Run
+- `run.stream()` — AsyncGenerator of SDKMessage events
+- `agent.dispose()` — clean up resources (or use `await using`)
+- `Agent.prompt(options, prompt)` — one-shot: create, send, dispose
+
+### Tool definition
+```typescript
+const searchTool = defineTool({
+  name: "search",
+  description: "Search the web",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => ({ results: await search(query) }),
+});
+```
+
+### Streaming events (SDKMessage)
+- `{ type: "assistant", content }` — text from the model
+- `{ type: "tool_use", name, input }` — tool call
+- `{ type: "tool_result", name, output }` — tool response
+- `{ type: "status", status }` — run status change
+- `{ type: "error", error }` — error event
+- `{ type: "usage", tokens }` — token usage update
+
+### Error handling
+```typescript
+try {
+  await agent.send("...");
+} catch (e) {
+  if (e instanceof TheokitAgentError) {
+    console.error(e.code, e.message); // typed error with code
+  }
+}
+```
+
+### DI decorators (`@theokit/di` + `@theokit/di-agent`)
+```typescript
+import { Injectable, Container } from "@theokit/di";
+import { Tool, Workflow, Cron, InjectAgent } from "@theokit/di-agent";
+
+@Injectable()
+class MyService {
+  @Tool({ name: "search", description: "Search" })
+  searchTool!: ToolOptions;
+
+  @Cron({ schedule: "*/5 * * * *" })
+  cleanup() { /* runs every 5 min */ }
+}
+```
+
+### Gateways
+```typescript
+import { defineGateway } from "@theokit/gateway-telegram"; // or -slack, -discord, etc.
+const gateway = defineGateway({ token: process.env.BOT_TOKEN });
+```
+
+Available: telegram, slack, discord, whatsapp, teams, email, sms, mattermost, line, matrix.
+
+## Anti-patterns
+
+- NEVER import from `@theokit/sdk/internal/...` — internal paths are not public API
+- NEVER import from `@theokit/sdk/dist/...` — use the exports map above
+- NEVER forget `agent.dispose()` — causes resource leaks
+- NEVER use `new Agent()` — always use `Agent.create()`
+- NEVER use `any` for tool input schemas — use Zod schemas
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@theokit/sdk` | Core SDK (Agent, Run, Tools, Memory, Streaming) |
+| `@theokit/di` | Dependency injection container |
+| `@theokit/di-agent` | 15 agentic decorators for DI |
+| `@theokit/gateway-*` | Platform gateways (Telegram, Slack, etc.) |
+| `@theokit/react` | React hooks for agent UIs |
+
+## Configuration
+
+Project config lives in `.theokit/`:
+- `.theokit/mcp.json` — MCP server configuration
+- `.theokit/hooks.json` — lifecycle hooks
+- `.theokit/agents/*.md` — agent instruction files
+
+Environment variables:
+- `THEOKIT_API_KEY` — API key (required)
+- `THEOKIT_MODEL_ID` — default model override

package/claude-template/CLAUDE.md

@@ -0,0 +1,51 @@
+@AGENTS.md
+
+## Claude Code — TheoKit SDK Extensions
+
+This project uses `@theokit/sdk`. The AGENTS.md above contains the full API reference. Below are Claude Code-specific extensions.
+
+### Available Skills (auto-loaded by domain)
+
+These skills inject TheoKit knowledge automatically when you edit files matching their domain:
+
+| Skill | Triggers on files matching |
+|-------|---------------------------|
+| `theokit-agent-core` | `*agent*`, `*Agent*`, `sdk.*` |
+| `theokit-tools` | `*tool*`, `*Tool*` |
+| `theokit-memory` | `*memory*`, `*Memory*`, `*embed*` |
+| `theokit-di` | `*container*`, `*inject*`, `*provider*`, `*module*` |
+| `theokit-di-agent` | `*decorator*`, `*Decorator*`, `di-agent*` |
+| `theokit-gateways` | `*gateway*`, `*telegram*`, `*slack*`, `*discord*` |
+| `theokit-rag` | `*retriev*`, `*rerank*`, `*splitter*`, `*rag*` |
+| `theokit-workflows` | `*workflow*`, `*Workflow*`, `*step*` |
+| `theokit-eval` | `*eval*`, `*Eval*`, `*scorer*` |
+| `theokit-cron` | `*cron*`, `*Cron*`, `*job*`, `*schedule*` |
+| `theokit-subscriptions` | `*subscri*`, `*sse*`, `*websocket*`, `*ws.*` |
+| `theokit-errors` | `*error*`, `*Error*`, `*exception*` |
+| `theokit-config` | `.theokit/**`, `config.*`, `theo.config.*` |
+| `theokit-streaming` | `*stream*`, `*Stream*`, `*SDKMessage*` |
+| `theokit-budget` | `*budget*`, `*Budget*`, `*cost*`, `*token*` |
+
+### Settings
+
+`.claude/settings.json` is pre-configured with safe defaults:
+- Allows: `npm run *`, `pnpm *`, `git status`, `git diff`, reading `src/` and `docs/`
+- Denies: `.env*` file reads, `sudo`, `rm -rf`
+- Override locally: create `.claude/settings.local.json` (add to `.gitignore`)
+
+### Customization
+
+Add your project-specific instructions below this line. The SDK knowledge above stays current with your installed `@theokit/sdk` version.
+
+```markdown
+## My Project
+
+Build: `npm run build`
+Test: `npm test`
+Lint: `npm run lint`
+
+## Architecture
+- `src/agents/` — agent definitions
+- `src/tools/` — tool implementations
+- `src/services/` — business logic
+```

package/claude-template/dot-claude/rules/theokit-conventions.md

@@ -0,0 +1,33 @@
+# TheoKit SDK Conventions
+
+## Agent lifecycle
+- Always use `Agent.create()` to create agents — NEVER `new Agent()`
+- Always call `agent.dispose()` or use `await using` when done
+- Use `Agent.prompt()` for one-shot operations (auto-disposes)
+
+## Imports
+- Use `@theokit/sdk` for core (Agent, defineTool, Memory)
+- Use `@theokit/sdk/errors` for error types
+- Use `@theokit/sdk/subscription` for SSE/WebSocket
+- Use `@theokit/sdk/rag` for retrievers, rerankers, splitters
+- Use `@theokit/sdk/cron` for scheduled jobs
+- Use `@theokit/sdk/eval` for evaluation
+- Use `@theokit/sdk/workflow` for workflows
+- NEVER import from `@theokit/sdk/internal/...`
+- NEVER import from `@theokit/sdk/dist/...`
+
+## Tools
+- Tool `inputSchema` MUST use Zod schemas — NEVER `any` or untyped objects
+- Tool `execute` MUST return a serializable value
+
+## DI
+- Use `@Injectable()` + `@Inject()` from `@theokit/di`
+- NEVER manually `new` a service — let the container resolve it
+
+## Error handling
+- Catch `TheokitAgentError` (base class) and check `error.code`
+- NEVER silently swallow errors — log with context or rethrow
+
+## Gateways
+- One gateway per agent instance
+- Configure via `defineGateway()` from the specific gateway package

package/claude-template/dot-claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(pnpm *)",
+      "Bash(npx *)",
+      "Read(./src/**)",
+      "Read(./docs/**)",
+      "Read(./tests/**)",
+      "Bash(git status)",
+      "Bash(git diff)",
+      "Bash(git log *)"
+    ],
+    "deny": ["Read(.env*)", "Read(**/.env*)", "Bash(sudo *)", "Bash(rm -rf *)"]
+  }
+}

package/claude-template/dot-claude/skills/theokit-agent-core/SKILL.md

@@ -0,0 +1,209 @@
+---
+user-invocable: false
+description: Agent lifecycle, sending messages, streaming, and disposal patterns for @theokit/sdk.
+paths:
+  - "**/*agent*"
+  - "**/*Agent*"
+  - "**/sdk.*"
+---
+
+# TheoKit SDK -- Agent Core
+
+Quick reference for Agent lifecycle, Run streaming, and disposal.
+
+## Agent.create
+
+```typescript
+import { Agent } from "@theokit/sdk";
+
+const agent = await Agent.create({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+```
+
+Returns an `SDKAgent`. Local agents get `agent-<uuid>` IDs; cloud agents get `bc-<uuid>`.
+
+### AgentOptions (key fields)
+
+| Property | Type | Notes |
+|---|---|---|
+| `model` | `ModelSelection` | Required for local; `{ id, params? }`. |
+| `apiKey` | `string` | Falls back to `THEOKIT_API_KEY` env. |
+| `local` | `{ cwd, settingSources?, sandboxOptions? }` | Local runtime config. |
+| `cloud` | `CloudOptions` | Cloud runtime config (repos, autoCreatePR, envVars). |
+| `systemPrompt` | `string \| (ctx: SystemPromptContext) => string` | Static string or async resolver. |
+| `mcpServers` | `Record<string, McpServerConfig>` | Inline MCP server definitions. |
+| `agents` | `Record<string, AgentDefinition>` | Subagent definitions. |
+| `tools` | `CustomTool[]` | Inline custom tools (local only). |
+| `memory` | `MemoryOptions` | Durable memory config. |
+| `handoffs` | `Array<SDKAgent \| Handoff>` | Peer-to-peer agent handoffs. |
+| `conversationStorage` | `ConversationStorageAdapter` | Pluggable persistence. |
+
+## Agent.prompt (one-shot)
+
+```typescript
+const result = await Agent.prompt("What does the auth middleware do?", {
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+// result: { id, status, result?, model?, durationMs?, git? }
+```
+
+Pass `throwOnError: true` to reject with `AgentRunError` instead of resolving with `status: 'error'`.
+
+## agent.send and Run
+
+```typescript
+const run = await agent.send("Find the bug in src/auth.ts");
+```
+
+### Run interface
+
+| Member | Type | Description |
+|---|---|---|
+| `id` | `string` | Run identifier. |
+| `status` | `RunStatus` | `"running" \| "finished" \| "error" \| "cancelled"` |
+| `stream()` | `AsyncGenerator<SDKMessage>` | Normalized event stream. |
+| `wait()` | `Promise<RunResult>` | Block until finished. |
+| `cancel()` | `Promise<void>` | Cancel the run. |
+| `conversation()` | `Promise<ConversationTurn[]>` | Structured turn history. |
+| `onDidChangeStatus(fn)` | `() => void` | Status change listener; returns unsubscribe. |
+
+### Streaming SDKMessage types
+
+```typescript
+for await (const event of run.stream()) {
+  switch (event.type) {
+    case "assistant": /* event.message.content: (TextBlock | ToolUseBlock)[] */ break;
+    case "thinking":  /* event.text, event.thinking_duration_ms? */ break;
+    case "tool_call": /* event.name, event.status, event.args?, event.result? */ break;
+    case "status":    /* event.status: cloud lifecycle transitions */ break;
+    case "task":      /* event.text: task milestones */ break;
+    case "request":   /* event.request_id: awaiting user input */ break;
+  }
+}
+```
+
+### Per-send options
+
+```typescript
+await agent.send("Plan the refactor", {
+  model: { id: "claude-sonnet-4-6", params: [{ id: "thinking", value: "high" }] },
+  systemPrompt: "Focus on performance.",
+  signal: abortController.signal,
+  onDelta: ({ update }) => { /* InteractionUpdate */ },
+  onStep: ({ step }) => { /* ConversationStep */ },
+});
+```
+
+## Agent.resume
+
+```typescript
+const agent = await Agent.resume("bc-abc123", {
+  apiKey: process.env.THEOKIT_API_KEY!,
+});
+```
+
+Runtime auto-detected from ID prefix. Inline `mcpServers` and `tools` are NOT persisted -- re-pass on resume.
+
+## Agent.getOrCreate
+
+```typescript
+const agent = await Agent.getOrCreate(`tg-user-${userId}`, {
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "claude-sonnet-4-6" },
+  local: { cwd: process.cwd() },
+});
+```
+
+Tries resume first; on `UnknownAgentError` falls through to create.
+
+## Agent.get / Agent.list / Agent.listRuns
+
+```typescript
+const info = await Agent.get(agentId);
+const { items, nextCursor } = await Agent.list({ runtime: "local", cwd: process.cwd() });
+const { items: runs } = await Agent.listRuns(agentId);
+```
+
+## createAgentFactory
+
+```typescript
+import { createAgentFactory } from "@theokit/sdk";
+
+const factory = createAgentFactory({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "claude-sonnet-4-6" },
+  local: { cwd: process.cwd() },
+  systemPrompt: "You are a helpful assistant.",
+});
+const agent = await factory.getOrCreate(`user-${userId}`);
+```
+
+## Agent.builder (fluent API)
+
+```typescript
+const agent = await Agent.builder()
+  .apiKey(process.env.THEOKIT_API_KEY!)
+  .model({ id: "claude-sonnet-4-6" })
+  .local({ cwd: process.cwd() })
+  .tools([myTool])
+  .getOrCreate(`user-${userId}`);
+```
+
+## Agent.generateObject / Agent.streamObject
+
+```typescript
+import { z } from "zod";
+
+const { object } = await Agent.generateObject({
+  schema: z.object({ title: z.string(), year: z.number().nullable() }),
+  prompt: "Fact card about jazz.",
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+
+for await (const evt of Agent.streamObject({ schema, prompt, model, local })) {
+  if (evt.type === "partial") render(evt.partial);
+  if (evt.type === "complete") finalize(evt.object);
+}
+```
+
+## Disposal patterns
+
+```typescript
+// Preferred: await using (auto-dispose on block exit)
+await using agent = await Agent.create({ /* ... */ });
+
+// Explicit dispose
+await agent[Symbol.asyncDispose]();
+
+// Fire-and-forget close
+agent.close();
+
+// Reload config without disposing
+await agent.reload();
+```
+
+## Agent.registry (production)
+
+```typescript
+Agent.registry.configure({ maxAgents: 1000, idleTimeoutMs: 15 * 60 * 1000 });
+Agent.registry.size();
+Agent.registry.evict("agent-42");
+await Agent.registry.evictAll(); // graceful shutdown
+```
+
+## Cancellation
+
+```typescript
+const run = await agent.send(message, { signal: request.signal });
+// On abort: AgentRunError with code "aborted"
+
+// Compose with timeout:
+const composed = AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]);
+await agent.send(message, { signal: composed });
+```

package/claude-template/dot-claude/skills/theokit-budget/SKILL.md

@@ -0,0 +1,176 @@
+---
+user-invocable: false
+paths:
+  - "**/*budget*"
+  - "**/*Budget*"
+  - "**/*cost*"
+  - "**/*token*"
+description: TheoKit SDK Budget API reference — cost tracking, token budget enforcement, usage reporting
+---
+
+# TheoKit Budget
+
+Token cost enforcement primitive. Track, warn, and block LLM spend at the
+process level with stacked USD limits and configurable enforcement modes.
+
+## Quick start
+
+```typescript
+import { Budget } from "@theokit/sdk";
+
+const handle = Budget.create({
+  name: "my-bot",
+  scope: "process",
+  mode: "warn",
+  limits: [
+    { window: "1h", limitUsd: 5.0 },
+    { window: "1d", limitUsd: 50.0 },
+  ],
+  onThreshold: (event) => {
+    console.warn(`Budget ${event.budgetName}: ${event.threshold * 100}% of ${event.window} limit`);
+  },
+  onExceed: (event) => {
+    console.error(`Budget ${event.budgetName}: exceeded ${event.window} limit`);
+  },
+});
+```
+
+## Enforcement modes
+
+| Mode | Behavior |
+|---|---|
+| `"audit"` | Log only. Never throws, never blocks. |
+| `"warn"` | Callbacks fire at 80%, 95%, and 100% thresholds. No throw. Default. |
+| `"block"` | Preflight throw (`BudgetExceededError`) BEFORE the LLM call when would-exceed. |
+
+## Stacked limits
+
+Pass multiple limits. ANY exceeded limit triggers enforcement:
+
+```typescript
+Budget.create({
+  name: "emergency-stop",
+  scope: "process",
+  mode: "block",
+  limits: [
+    { window: "1h", limitUsd: 2.0 },
+    { window: "1d", limitUsd: 10.0 },
+    { window: "30d", limitUsd: 100.0 },
+  ],
+});
+```
+
+Empty `limits[]` is valid: pure tracking with no threshold/exceed callbacks.
+
+## Time windows
+
+| Window | Alignment |
+|---|---|
+| `"1h"` | Relative (last 60 minutes) |
+| `"1d"` | UTC midnight boundary |
+| `"1w"` | Monday 00:00 UTC |
+| `"30d"` | 1st of month 00:00 UTC |
+| `"365d"` | Jan 1 00:00 UTC |
+
+## Managing budgets
+
+```typescript
+// Retrieve a budget handle
+const handle = Budget.get("my-bot");
+
+// Check spend and remaining
+handle?.spentIn("1d");       // USD spent in current day window
+handle?.remainingIn("1d");   // USD remaining before limit
+
+// List all active budgets
+const budgets = Budget.list();
+
+// Snapshot all windows for all budgets
+const snapshots = Budget.snapshot();
+// [{ name, window, spentUsd, limitUsd, ratio }, ...]
+
+// Delete a budget
+Budget.delete("my-bot");
+```
+
+## Type reference
+
+```typescript
+type BudgetScope = "agent" | "call" | "process";
+type BudgetWindow = "1h" | "1d" | "1w" | "30d" | "365d";
+type BudgetMode = "audit" | "warn" | "block";
+
+interface BudgetLimit {
+  readonly window: BudgetWindow;
+  readonly limitUsd: number;
+}
+
+interface BudgetOptions {
+  readonly name: string;          // must match ^[a-z0-9][a-z0-9_-]*$
+  readonly scope: BudgetScope;
+  readonly limits: ReadonlyArray<BudgetLimit>;
+  readonly mode?: BudgetMode;     // default "warn"
+  readonly onThreshold?: (event: BudgetThresholdEvent) => void | Promise<void>;
+  readonly onExceed?: (event: BudgetExceedEvent) => void | Promise<void>;
+}
+
+interface BudgetHandle {
+  readonly name: string;
+  readonly mode: BudgetMode;
+  readonly scope: BudgetScope;
+  readonly limits: ReadonlyArray<BudgetLimit>;
+  spentIn(window: BudgetWindow): number;
+  remainingIn(window: BudgetWindow): number;
+}
+
+interface BudgetSnapshot {
+  readonly name: string;
+  readonly window: BudgetWindow;
+  readonly spentUsd: number;
+  readonly limitUsd: number;
+  readonly ratio: number;
+}
+
+interface BudgetThresholdEvent {
+  readonly budgetName: string;
+  readonly window: BudgetWindow;
+  readonly threshold: 0.8 | 0.95;
+  readonly spentUsd: number;
+  readonly limitUsd: number;
+}
+
+interface BudgetExceedEvent {
+  readonly budgetName: string;
+  readonly window: BudgetWindow;
+  readonly spentUsd: number;
+  readonly limitUsd: number;
+  readonly mode: BudgetMode;
+}
+```
+
+## Wiring with agents
+
+Budget enforcement integrates with `agent.send()`. When a budget is active
+and mode is `"block"`, a preflight check runs before the LLM call. If the
+estimated cost would exceed a limit, `BudgetExceededError` is thrown.
+
+The `turn-ended` InteractionUpdate carries token usage that feeds the budget
+ledger automatically:
+
+```typescript
+{ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens }
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `ConfigurationError` | Invalid `name` (grammar violation) or duplicate `name` |
+| `BudgetExceededError` | `mode: "block"` and spend would exceed a limit |
+
+## Known limitations
+
+- v1 supports `scope: "process"` only. `"agent"` and `"call"` scopes are
+  reserved for future multi-tenant scenarios.
+- In-flight `agent.send` calls referencing a deleted budget treat subsequent
+  charges as a silent no-op with a stderr warning.