dyadic 1.8.1 → 1.8.2

package/README.md

@@ -1,305 +1,305 @@
-# dyadic
-
-```sh
-npm install dyadic
-```
-
-The official TypeScript and JavaScript SDK for the [Dyadic API](https://dyadic.app/developers/): Iris with streaming, function calling, images and typed errors. No dependencies; for server-side code on Node 18+, Deno and Bun (keep your key off the browser, see below).
-
-```ts
-import { Dyadic } from "dyadic";
-
-const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
-console.log(await client.ask("Hello!", { model: "iris" }));
-```
-
-## Keep your key on the server
-
-**A Dyadic API key is a long-lived secret that spends your credits. Never ship it
-to a browser**: not in a bundle, page source, local storage or a request your
-front end makes, where any visitor or extension can copy it. Use the SDK in
-server-side code (Node 18+, Deno, Bun, edge functions) and have your front end
-call your own server:
-
-```ts
-// server.ts: the key stays here
-import { Dyadic } from "dyadic";
-const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
-
-export async function POST(request: Request) {
-  const { question } = await request.json();
-  // Check your own user's session and limits here before spending credits.
-  return Response.json({ answer: await client.ask(String(question).slice(0, 4000), { model: "iris" }) });
-}
-```
-
-`request()` only ever sends the key to the API you configured: a relative path
-joins `baseURL`, and an absolute URL on any other host, port or scheme (or with
-credentials in it) throws `DyadicError` instead of being sent. Redirects are not
-followed. Plain `http://` is accepted only for a local or private-network API.
-
-## Retries
-
-GET, HEAD, DELETE and OPTIONS are retried on busy or failing servers. Anything
-else (a completion, an upload, a run) may already have run, and been billed,
-when it fails, so it is retried only if it provably never started: the
-connection was never made, or Dyadic refused it with `rate_limit_exceeded` or
-`concurrency_limit`. Every attempt of one call carries the same
-`Idempotency-Key`; pass `{ idempotencyKey }` to choose it, or `{ idempotent: true }`
-for a call that is safe to send twice.
-
-## Runs: your own agent, Dyadic's tools, your functions
-
-```ts
-const run = await client.runs.run({
-  agent: { id: "helpdesk", name: "Helpdesk", instructions: "You answer customers of a small shop." },
-  messages: [{ role: "user", content: "Where is order 1042?" }],
-  builtin_tools: ["data.web_search"],
-  functions: {
-    lookup_order: {
-      description: "Look up an order by id.",
-      parameters: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
-      handler: async ({ order_id }) => ({ order_id, status: "shipped" }),
-    },
-  },
-  end_user: "customer-17",
-});
-console.log(run.output_text);
-```
-
-`client.runs.create({ ..., stream: true })` streams the run's events. Leaving a `for await` over any stream early
-(`break`, `return`, a throw) ends its request too, so nothing keeps running (or billing) behind it.
-
-## Plans: propose, approve, carry out
-
-With the key's plans switch on, a run can plan before it acts. `planMode: true` investigates read-only and proposes a
-plan of Steps; nothing that changes anything runs. Your user reviews it (edit it with `plans.update`), you approve the
-revision they saw, and a run with `planId` carries it out step by step. The service checks the approval: a plan that isn't
-approved at its current revision doesn't run (`plan_not_runnable`). A run that ends with steps left pauses the plan;
-another run with the same `planId` resumes it.
-
-```ts
-const proposal = await client.runs.create({ agent: "iris", messages: [{ role: "user", content: "Move our blog to a static site." }],
-  planMode: true, conversation_id: "ticket-88" });
-let plan = await client.plans.retrieve(proposal.plans![0].id);
-plan = await client.plans.approve(plan.id, { revision: plan.revision });
-await client.runs.create({ agent: "iris", messages: [{ role: "user", content: "Go ahead." }], planId: plan.id, conversation_id: "ticket-88" });
-
-for await (const event of client.plans.stream(plan.id)) console.log(event.event, event.data.step, event.data.status);
-```
-
-`client.plans` also has `list({ conversation, status, limit, after })`, `create({ title, steps, mode })`,
-`update(id, { revision, ... })`, `cancel(id)`, `moveStep(id, key, { status, note, verified_by })` and
-`events(id, { after })`. The stream resumes after the last event (Last-Event-ID), ends once the plan is finished, and
-honors an AbortSignal. A key sees only its own plans.
-
-## Decisions: typed answers, fast and cheap
-
-Ask one or more questions about some text (or text and images) and get typed answers
-back: a probability (`predicate`), one of your values (`choice`) or a rubric level
-(`score`). A fraction of a second and a fraction of a cent; billed at cost.
-
-```ts
-const decision = await client.decisions.create({
-  input: "I can't log in after resetting my password.",
-  questions: [
-    { type: "predicate", name: "urgent", instructions: "The customer is blocked from using the product." },
-    { type: "choice", name: "team", instructions: "Which team should handle this.", choices: [
-      { value: "account", description: "Sign-in and account access" },
-      { value: "billing", description: "Payments and invoices" },
-      { value: "other", description: "Anything else" },
-    ] },
-  ],
-});
-```
-
-## Connected apps: saving into a person's Workspace
-
-With the person's approval, an application can save into their Dyadic
-Workspace, naming them by the Discord account linked to their Dyadic account.
-
-```ts
-import { Dyadic, DyadicError } from "dyadic";
-
-const status = await client.connections.discord(discordId);
-if (!status.authorized) console.log("Allow this app:", status.authorize_url); // show the person this link
-
-try {
-  const saved = await client.workspace.saves.create({ discord_id: discordId, kind: "message", title: "From #general",
-    text: "Worth keeping", url: "https://discord.com/channels/1/2/3" });
-  console.log(saved.url);
-} catch (error) {
-  if (error instanceof DyadicError && error.code === "authorization_required") {
-    console.log("Allow this app:", (error.body as { authorize_url?: string }).authorize_url);
-  }
-}
-```
-
-`kind` is `message`, `conversation` (with `messages`, saved as a chat the
-person can continue unless `as_chat: false`), `image` or `file` (with `files`:
-base64, up to 10 of 8 MB).
-
-## Conversations, stored completions, containers, vector stores, skills
-
-The rest of the OpenAI-compatible API, named as OpenAI's SDK names it:
-
-```ts
-const conversation = await client.conversations.create({ metadata: { ticket: "88" } });
-await client.responses.create({ model: "iris", input: "Hello", conversation: conversation.id });
-const items = await client.conversations.items.list(conversation.id, { order: "asc" });
-
-const { input_tokens } = await client.responses.inputTokens.count({ model: "iris", input: "How long is this?" }); // free
-const compacted = await client.responses.compact({ model: "iris", previous_response_id: "resp_..." }); // send compacted.output next
-
-const stored = await client.chat.completions.list({ metadata: { team: "support" } }); // completions made with store: true
-await client.chat.completions.messages.list(stored.data[0].id);
-
-const container = await client.containers.create({ name: "scratch" });              // code interpreter switch
-await client.containers.files.create(container.id, { file: { name: "data.csv", data: csv } });
-
-const store = await client.vectorStores.create({ name: "docs", file_ids: [file.id] }); // file search switch; no credits
-const hits = await client.vectorStores.search(store.id, { query: "refund policy" });
-
-const skill = await client.skills.create({ files: [{ name: "SKILL.md", data: skillMd }, { name: "scripts/read.py", data: script }] });
-```
-
-Also `conversations.retrieve/update/delete`, `conversations.items.create/retrieve/delete`, `chat.completions.retrieve/update/delete`,
-`containers.files.list/retrieve/delete/content.retrieve`, `vectorStores.files.*` and `vectorStores.fileBatches.*`, and
-`skills.versions.*` (a skill is uploaded as its files, each named by its path in the skill, or as one zip).
-
-## The Anthropic API and OpenRouter's, on the same key
-
-`client.anthropic` speaks [the Anthropic API](https://dyadic.app/developers/#anthropic) at `/api/anthropic/v1`
-(Claude's request and answer shapes, behaving as Anthropic's do) and `client.openrouter` OpenRouter's API through the
-[AI gateway](https://dyadic.app/developers/#openrouter) at `/api/openrouter/v1`, both with this client's key and beside
-its base URL:
-
-```ts
-const message = await client.anthropic.messages.create({ model: "iris", max_tokens: 1024, messages: [{ role: "user", content: "Hello" }] });
-console.log(message.content, message.stop_reason, message.usage.output_tokens);   // Anthropic's answer
-
-const stream = await client.anthropic.messages.create({ model: "iris", max_tokens: 1024, stream: true, messages: [{ role: "user", content: "Tell me a story" }] });
-for await (const event of stream) if (event.type === "content_block_delta" && event.delta?.type === "text_delta") process.stdout.write(event.delta.text);
-console.log(stream.usage);                                                      // input and output tokens
-
-const batch = await client.anthropic.messages.batches.create({ requests: [{ custom_id: "a", params: { model: "iris", max_tokens: 256, messages: [{ role: "user", content: "Hi" }] } }] });
-const results = await client.anthropic.messages.batches.results(batch.id);      // once processing_status is "ended"
-
-// OpenRouter's models through the AI gateway (Dyadic turns it on for an app's key on request):
-const reply = await client.openrouter.chat.completions.create({ model: "anthropic/claude-haiku-5.5", messages: [{ role: "user", content: "Hello" }] });
-const { data } = await client.openrouter.key();                                 // this key's limits, answered by Dyadic
-```
-
-Also `anthropic.messages.countTokens` (free), `anthropic.messages.batches.list/retrieve/cancel/delete`,
-`anthropic.models.list/retrieve`, `anthropic.files.create/list/retrieve/content/delete`, and `openrouter.completions`,
-`openrouter.embeddings`, `openrouter.models.list/endpoints`, `openrouter.generation` and `openrouter.credits`. The
-gateway is a platform decision: Dyadic turns it on for an app's key on request, the key's owner can turn it off, and a
-key without it gets `403 gateway_not_allowed`. Anthropic's own SDKs and Claude Code work too, with the base URL
-`https://dyadic.app/api/anthropic`.
-
-## Agent Black Box: a flight recorder for your own agent
-
-Record what your agent does into Dyadic's tamper-evident Black Box (hash-chained,
-signed, verifiable offline). Switch **Black Box: send telemetry** (and **read**) on
-for the key first; both are off by default.
-
-```ts
-import { BlackBoxRecorder, verifyBundle } from "dyadic";
-
-const recorder = new BlackBoxRecorder(client);
-await recorder.run({ title: "Book a room", agent: "planner" }, async (run) => {
-  run.declare({ allowedTools: ["book_room"], allowedHosts: ["rooms.example.com"] });
-  await run.toolCall("book_room", { effect: true, hosts: ["rooms.example.com"] }, async (tool) => tool.result(await bookRoom("Orion")));
-  run.verified("booking", "confirmation ORN-1042 read back from the booking API");
-});
-await recorder.flush();
-```
-
-Spans nest through their own methods (`run.agentSpan("researcher", {}, async (sub) => sub.toolCall(...))`); a
-remote subagent joins the trace with `recorder.start({ traceparent: span.traceparent() })`. Only metadata is sent
-unless `{ captureContent: true }` (secrets redacted first). `instrumentMcpClient(mcpClient, run)` records MCP tool
-calls. `client.blackbox.runs.export(id)` returns an evidence bundle; `await verifyBundle(bundle, { [keyId]: publicKey })`
-checks it offline with WebCrypto. `client.blackbox.runs.simulate(id, { mode })` never runs anything.
-
-### Reading, triaging and managing
-
-With the key's **read** switch: `client.blackbox.overview()`, `settings()`, `runs.list/retrieve/events({ types })/graph/verify/
-checkpoints/otlp/export`, `diff(a, b)`, `findings.list({ status, severity, rule })`, `rules.list()` and
-`rules.preview({ rules })` (what detection would raise with other settings; nothing is saved). **Write**: `bookmarks.create(runId,
-{ seq, note })`, `findings.update(id, { status: "dismissed" })`. **Content**: `runs.content(id)`. **Manage**: `runs.erase(id)`,
-`runs.delete(id)` and the sinks below. A run of the key's that was deleted throws `RunDeletedError` (HTTP 410). OTLP protobuf
-goes as it is: `client.blackbox.sendOtlp(bytes)`.
-
-### Live
-
-```ts
-const controller = new AbortController();
-for await (const { event, id, data } of client.blackbox.runs.stream(runId, { signal: controller.signal })) {
-  if (event === "event") console.log(id, data.type);            // id is the event's sequence number
-  if (event === "end") console.log(data.status, data.outcome);  // the stream stops after end (or deleted)
-}
-for await (const { event, data } of client.blackbox.watch()) if (event === "run") console.log(data.id, data.status);
-```
-
-Both connect again by themselves when the service asks or the connection drops (a run's stream resumes after its last
-event), and end when you leave the loop or abort the signal. Node 18+ and browsers (fetch and ReadableStream).
-
-### Webhooks and collectors
-
-`client.blackbox.sinks.create({ kind: "webhook", url, events: ["finding.created", "run.failed"], min_severity: "high" })` sends
-signed JSON as findings are raised and runs end (keep its `secret`: it is shown once; `sinks.rotate(id)` makes a new one);
-`{ kind: "otlp", url, protocol: "http/protobuf", headers }` exports each finished run to an OpenTelemetry collector. Check every
-webhook before trusting it, with the body exactly as it arrived:
-
-```ts
-import { verifyWebhook, WebhookVerificationError } from "dyadic";
-
-export async function POST(request: Request) {
-  try {
-    const message = await verifyWebhook(await request.text(), request.headers, process.env.BLACKBOX_WEBHOOK_SECRET!);
-    // message.type: finding.created, run.completed, run.failed, ...; skip repeats by the webhook-id header
-  } catch (error) {
-    if (error instanceof WebhookVerificationError) return new Response("bad signature", { status: 400 });
-    throw error;
-  }
-  return new Response(null, { status: 204 });
-}
-```
-
-(Standard Webhooks: HMAC-SHA256, several signatures during a rotation, a timestamp within 5 minutes by default.)
-
-### Anchors
-
-When the platform anchors its checkpoint logs (RFC 3161 timestamps over a Merkle root), bundles carry the anchor and
-`verifyBundle` checks it: the anchored checkpoint is in the bundle's log at or after the run's last checkpoint, its Merkle
-proof leads to the root, and the timestamp token stamps that root (its time is in the check's detail). The authority's
-signature on the token is **not** checked here (it needs CMS and certificate work this verifier doesn't do); the report says
-so in its warnings. The Python SDK's `verify_bundle` and the bundle's `verify.py` check it.
-
-### OpenTelemetry
-
-If your agent framework already makes OpenTelemetry spans, send them as they are. `BlackBoxSpanExporter` is a
-`SpanExporter` for the official SDK (1.x and 2.x; nothing from OpenTelemetry is needed at runtime):
-
-```ts
-import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { BlackBoxSpanExporter } from "dyadic";
-
-const provider = new BasicTracerProvider({ spanProcessors: [new BatchSpanProcessor(new BlackBoxSpanExporter(client))] });
-```
-
-Spans following the GenAI semantic conventions (`gen_ai.operation.name`: `chat`, `execute_tool`, `invoke_agent`, ...)
-or OpenInference (`openinference.span.kind`) become model calls, tool calls and agents; others are kept as generic
-spans; one run per trace. Content attributes (`gen_ai.input.messages`, `gen_ai.tool.call.arguments`, `input.value`,
-...) stay in your process unless `{ captureContent: true }`, and every value is redacted first (secrets, by default;
-`redact` replaces it). Large batches are split to fit the service (1,000 spans or 4 MB per request), and a failed
-export is reported to the span processor, never thrown. `toOtlpRequests(spans)` gives the OTLP/JSON without sending it.
-
-## Tests
-
-`npm test` runs the SDK's own tests against a mocked fetch or a local stand-in server: nothing reaches Dyadic and nothing
-is spent. `npm run test:production` runs the live checks in `live_tests/` against a real API, only with
-`DYADIC_LIVE_API_KEY` set (`DYADIC_LIVE_BASE_URL` for another deployment): free listings and token counts, and two
-messages of at most 16 tokens. Use a short-lived key with a small credit cap.
-
-Full guide: https://dyadic.app/developers/
+# dyadic
+
+```sh
+npm install dyadic
+```
+
+The official TypeScript and JavaScript SDK for the [Dyadic API](https://dyadic.app/developers/): Iris with streaming, function calling, images and typed errors. No dependencies; for server-side code on Node 18+, Deno and Bun (keep your key off the browser, see below).
+
+```ts
+import { Dyadic } from "dyadic";
+
+const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
+console.log(await client.ask("Hello!", { model: "iris" }));
+```
+
+## Keep your key on the server
+
+**A Dyadic API key is a long-lived secret that spends your credits. Never ship it
+to a browser**: not in a bundle, page source, local storage or a request your
+front end makes, where any visitor or extension can copy it. Use the SDK in
+server-side code (Node 18+, Deno, Bun, edge functions) and have your front end
+call your own server:
+
+```ts
+// server.ts: the key stays here
+import { Dyadic } from "dyadic";
+const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
+
+export async function POST(request: Request) {
+  const { question } = await request.json();
+  // Check your own user's session and limits here before spending credits.
+  return Response.json({ answer: await client.ask(String(question).slice(0, 4000), { model: "iris" }) });
+}
+```
+
+`request()` only ever sends the key to the API you configured: a relative path
+joins `baseURL`, and an absolute URL on any other host, port or scheme (or with
+credentials in it) throws `DyadicError` instead of being sent. Redirects are not
+followed. Plain `http://` is accepted only for a local or private-network API.
+
+## Retries
+
+GET, HEAD, DELETE and OPTIONS are retried on busy or failing servers. Anything
+else (a completion, an upload, a run) may already have run, and been billed,
+when it fails, so it is retried only if it provably never started: the
+connection was never made, or Dyadic refused it with `rate_limit_exceeded` or
+`concurrency_limit`. Every attempt of one call carries the same
+`Idempotency-Key`; pass `{ idempotencyKey }` to choose it, or `{ idempotent: true }`
+for a call that is safe to send twice.
+
+## Runs: your own agent, Dyadic's tools, your functions
+
+```ts
+const run = await client.runs.run({
+  agent: { id: "helpdesk", name: "Helpdesk", instructions: "You answer customers of a small shop." },
+  messages: [{ role: "user", content: "Where is order 1042?" }],
+  builtin_tools: ["data.web_search"],
+  functions: {
+    lookup_order: {
+      description: "Look up an order by id.",
+      parameters: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
+      handler: async ({ order_id }) => ({ order_id, status: "shipped" }),
+    },
+  },
+  end_user: "customer-17",
+});
+console.log(run.output_text);
+```
+
+`client.runs.create({ ..., stream: true })` streams the run's events. Leaving a `for await` over any stream early
+(`break`, `return`, a throw) ends its request too, so nothing keeps running (or billing) behind it.
+
+## Plans: propose, approve, carry out
+
+With the key's plans switch on, a run can plan before it acts. `planMode: true` investigates read-only and proposes a
+plan of Steps; nothing that changes anything runs. Your user reviews it (edit it with `plans.update`), you approve the
+revision they saw, and a run with `planId` carries it out step by step. The service checks the approval: a plan that isn't
+approved at its current revision doesn't run (`plan_not_runnable`). A run that ends with steps left pauses the plan;
+another run with the same `planId` resumes it.
+
+```ts
+const proposal = await client.runs.create({ agent: "iris", messages: [{ role: "user", content: "Move our blog to a static site." }],
+  planMode: true, conversation_id: "ticket-88" });
+let plan = await client.plans.retrieve(proposal.plans![0].id);
+plan = await client.plans.approve(plan.id, { revision: plan.revision });
+await client.runs.create({ agent: "iris", messages: [{ role: "user", content: "Go ahead." }], planId: plan.id, conversation_id: "ticket-88" });
+
+for await (const event of client.plans.stream(plan.id)) console.log(event.event, event.data.step, event.data.status);
+```
+
+`client.plans` also has `list({ conversation, status, limit, after })`, `create({ title, steps, mode })`,
+`update(id, { revision, ... })`, `cancel(id)`, `moveStep(id, key, { status, note, verified_by })` and
+`events(id, { after })`. The stream resumes after the last event (Last-Event-ID), ends once the plan is finished, and
+honors an AbortSignal. A key sees only its own plans.
+
+## Decisions: typed answers, fast and cheap
+
+Ask one or more questions about some text (or text and images) and get typed answers
+back: a probability (`predicate`), one of your values (`choice`) or a rubric level
+(`score`). A fraction of a second and a fraction of a cent; billed at cost.
+
+```ts
+const decision = await client.decisions.create({
+  input: "I can't log in after resetting my password.",
+  questions: [
+    { type: "predicate", name: "urgent", instructions: "The customer is blocked from using the product." },
+    { type: "choice", name: "team", instructions: "Which team should handle this.", choices: [
+      { value: "account", description: "Sign-in and account access" },
+      { value: "billing", description: "Payments and invoices" },
+      { value: "other", description: "Anything else" },
+    ] },
+  ],
+});
+```
+
+## Connected apps: saving into a person's Workspace
+
+With the person's approval, an application can save into their Dyadic
+Workspace, naming them by the Discord account linked to their Dyadic account.
+
+```ts
+import { Dyadic, DyadicError } from "dyadic";
+
+const status = await client.connections.discord(discordId);
+if (!status.authorized) console.log("Allow this app:", status.authorize_url); // show the person this link
+
+try {
+  const saved = await client.workspace.saves.create({ discord_id: discordId, kind: "message", title: "From #general",
+    text: "Worth keeping", url: "https://discord.com/channels/1/2/3" });
+  console.log(saved.url);
+} catch (error) {
+  if (error instanceof DyadicError && error.code === "authorization_required") {
+    console.log("Allow this app:", (error.body as { authorize_url?: string }).authorize_url);
+  }
+}
+```
+
+`kind` is `message`, `conversation` (with `messages`, saved as a chat the
+person can continue unless `as_chat: false`), `image` or `file` (with `files`:
+base64, up to 10 of 8 MB).
+
+## Conversations, stored completions, containers, vector stores, skills
+
+The rest of the OpenAI-compatible API, named as OpenAI's SDK names it:
+
+```ts
+const conversation = await client.conversations.create({ metadata: { ticket: "88" } });
+await client.responses.create({ model: "iris", input: "Hello", conversation: conversation.id });
+const items = await client.conversations.items.list(conversation.id, { order: "asc" });
+
+const { input_tokens } = await client.responses.inputTokens.count({ model: "iris", input: "How long is this?" }); // free
+const compacted = await client.responses.compact({ model: "iris", previous_response_id: "resp_..." }); // send compacted.output next
+
+const stored = await client.chat.completions.list({ metadata: { team: "support" } }); // completions made with store: true
+await client.chat.completions.messages.list(stored.data[0].id);
+
+const container = await client.containers.create({ name: "scratch" });              // code interpreter switch
+await client.containers.files.create(container.id, { file: { name: "data.csv", data: csv } });
+
+const store = await client.vectorStores.create({ name: "docs", file_ids: [file.id] }); // file search switch; no credits
+const hits = await client.vectorStores.search(store.id, { query: "refund policy" });
+
+const skill = await client.skills.create({ files: [{ name: "SKILL.md", data: skillMd }, { name: "scripts/read.py", data: script }] });
+```
+
+Also `conversations.retrieve/update/delete`, `conversations.items.create/retrieve/delete`, `chat.completions.retrieve/update/delete`,
+`containers.files.list/retrieve/delete/content.retrieve`, `vectorStores.files.*` and `vectorStores.fileBatches.*`, and
+`skills.versions.*` (a skill is uploaded as its files, each named by its path in the skill, or as one zip).
+
+## The Anthropic API and OpenRouter's, on the same key
+
+`client.anthropic` speaks [the Anthropic API](https://dyadic.app/developers/#anthropic) at `/api/anthropic/v1`
+(Claude's request and answer shapes, behaving as Anthropic's do) and `client.openrouter` OpenRouter's API through the
+[AI gateway](https://dyadic.app/developers/#openrouter) at `/api/openrouter/v1`, both with this client's key and beside
+its base URL:
+
+```ts
+const message = await client.anthropic.messages.create({ model: "iris", max_tokens: 1024, messages: [{ role: "user", content: "Hello" }] });
+console.log(message.content, message.stop_reason, message.usage.output_tokens);   // Anthropic's answer
+
+const stream = await client.anthropic.messages.create({ model: "iris", max_tokens: 1024, stream: true, messages: [{ role: "user", content: "Tell me a story" }] });
+for await (const event of stream) if (event.type === "content_block_delta" && event.delta?.type === "text_delta") process.stdout.write(event.delta.text);
+console.log(stream.usage);                                                      // input and output tokens
+
+const batch = await client.anthropic.messages.batches.create({ requests: [{ custom_id: "a", params: { model: "iris", max_tokens: 256, messages: [{ role: "user", content: "Hi" }] } }] });
+const results = await client.anthropic.messages.batches.results(batch.id);      // once processing_status is "ended"
+
+// OpenRouter's models through the AI gateway (Dyadic turns it on for an app's key on request):
+const reply = await client.openrouter.chat.completions.create({ model: "anthropic/claude-haiku-5.5", messages: [{ role: "user", content: "Hello" }] });
+const { data } = await client.openrouter.key();                                 // this key's limits, answered by Dyadic
+```
+
+Also `anthropic.messages.countTokens` (free), `anthropic.messages.batches.list/retrieve/cancel/delete`,
+`anthropic.models.list/retrieve`, `anthropic.files.create/list/retrieve/content/delete`, and `openrouter.completions`,
+`openrouter.embeddings`, `openrouter.models.list/endpoints`, `openrouter.generation` and `openrouter.credits`. The
+gateway is a platform decision: Dyadic turns it on for an app's key on request, the key's owner can turn it off, and a
+key without it gets `403 gateway_not_allowed`. Anthropic's own SDKs and Claude Code work too, with the base URL
+`https://dyadic.app/api/anthropic`.
+
+## Agent Black Box: a flight recorder for your own agent
+
+Record what your agent does into Dyadic's tamper-evident Black Box (hash-chained,
+signed, verifiable offline). Switch **Black Box: send telemetry** (and **read**) on
+for the key first; both are off by default.
+
+```ts
+import { BlackBoxRecorder, verifyBundle } from "dyadic";
+
+const recorder = new BlackBoxRecorder(client);
+await recorder.run({ title: "Book a room", agent: "planner" }, async (run) => {
+  run.declare({ allowedTools: ["book_room"], allowedHosts: ["rooms.example.com"] });
+  await run.toolCall("book_room", { effect: true, hosts: ["rooms.example.com"] }, async (tool) => tool.result(await bookRoom("Orion")));
+  run.verified("booking", "confirmation ORN-1042 read back from the booking API");
+});
+await recorder.flush();
+```
+
+Spans nest through their own methods (`run.agentSpan("researcher", {}, async (sub) => sub.toolCall(...))`); a
+remote subagent joins the trace with `recorder.start({ traceparent: span.traceparent() })`. Only metadata is sent
+unless `{ captureContent: true }` (secrets redacted first). `instrumentMcpClient(mcpClient, run)` records MCP tool
+calls. `client.blackbox.runs.export(id)` returns an evidence bundle; `await verifyBundle(bundle, { [keyId]: publicKey })`
+checks it offline with WebCrypto. `client.blackbox.runs.simulate(id, { mode })` never runs anything.
+
+### Reading, triaging and managing
+
+With the key's **read** switch: `client.blackbox.overview()`, `settings()`, `runs.list/retrieve/events({ types })/graph/verify/
+checkpoints/otlp/export`, `diff(a, b)`, `findings.list({ status, severity, rule })`, `rules.list()` and
+`rules.preview({ rules })` (what detection would raise with other settings; nothing is saved). **Write**: `bookmarks.create(runId,
+{ seq, note })`, `findings.update(id, { status: "dismissed" })`. **Content**: `runs.content(id)`. **Manage**: `runs.erase(id)`,
+`runs.delete(id)` and the sinks below. A run of the key's that was deleted throws `RunDeletedError` (HTTP 410). OTLP protobuf
+goes as it is: `client.blackbox.sendOtlp(bytes)`.
+
+### Live
+
+```ts
+const controller = new AbortController();
+for await (const { event, id, data } of client.blackbox.runs.stream(runId, { signal: controller.signal })) {
+  if (event === "event") console.log(id, data.type);            // id is the event's sequence number
+  if (event === "end") console.log(data.status, data.outcome);  // the stream stops after end (or deleted)
+}
+for await (const { event, data } of client.blackbox.watch()) if (event === "run") console.log(data.id, data.status);
+```
+
+Both connect again by themselves when the service asks or the connection drops (a run's stream resumes after its last
+event), and end when you leave the loop or abort the signal. Node 18+ and browsers (fetch and ReadableStream).
+
+### Webhooks and collectors
+
+`client.blackbox.sinks.create({ kind: "webhook", url, events: ["finding.created", "run.failed"], min_severity: "high" })` sends
+signed JSON as findings are raised and runs end (keep its `secret`: it is shown once; `sinks.rotate(id)` makes a new one);
+`{ kind: "otlp", url, protocol: "http/protobuf", headers }` exports each finished run to an OpenTelemetry collector. Check every
+webhook before trusting it, with the body exactly as it arrived:
+
+```ts
+import { verifyWebhook, WebhookVerificationError } from "dyadic";
+
+export async function POST(request: Request) {
+  try {
+    const message = await verifyWebhook(await request.text(), request.headers, process.env.BLACKBOX_WEBHOOK_SECRET!);
+    // message.type: finding.created, run.completed, run.failed, ...; skip repeats by the webhook-id header
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return new Response("bad signature", { status: 400 });
+    throw error;
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+(Standard Webhooks: HMAC-SHA256, several signatures during a rotation, a timestamp within 5 minutes by default.)
+
+### Anchors
+
+When the platform anchors its checkpoint logs (RFC 3161 timestamps over a Merkle root), bundles carry the anchor and
+`verifyBundle` checks it: the anchored checkpoint is in the bundle's log at or after the run's last checkpoint, its Merkle
+proof leads to the root, and the timestamp token stamps that root (its time is in the check's detail). The authority's
+signature on the token is **not** checked here (it needs CMS and certificate work this verifier doesn't do); the report says
+so in its warnings. The Python SDK's `verify_bundle` and the bundle's `verify.py` check it.
+
+### OpenTelemetry
+
+If your agent framework already makes OpenTelemetry spans, send them as they are. `BlackBoxSpanExporter` is a
+`SpanExporter` for the official SDK (1.x and 2.x; nothing from OpenTelemetry is needed at runtime):
+
+```ts
+import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { BlackBoxSpanExporter } from "dyadic";
+
+const provider = new BasicTracerProvider({ spanProcessors: [new BatchSpanProcessor(new BlackBoxSpanExporter(client))] });
+```
+
+Spans following the GenAI semantic conventions (`gen_ai.operation.name`: `chat`, `execute_tool`, `invoke_agent`, ...)
+or OpenInference (`openinference.span.kind`) become model calls, tool calls and agents; others are kept as generic
+spans; one run per trace. Content attributes (`gen_ai.input.messages`, `gen_ai.tool.call.arguments`, `input.value`,
+...) stay in your process unless `{ captureContent: true }`, and every value is redacted first (secrets, by default;
+`redact` replaces it). Large batches are split to fit the service (1,000 spans or 4 MB per request), and a failed
+export is reported to the span processor, never thrown. `toOtlpRequests(spans)` gives the OTLP/JSON without sending it.
+
+## Tests
+
+`npm test` runs the SDK's own tests against a mocked fetch or a local stand-in server: nothing reaches Dyadic and nothing
+is spent. `npm run test:production` runs the live checks in `live_tests/` against a real API, only with
+`DYADIC_LIVE_API_KEY` set (`DYADIC_LIVE_BASE_URL` for another deployment): free listings and token counts, and two
+messages of at most 16 tokens. Use a short-lived key with a small credit cap.
+
+Full guide: https://dyadic.app/developers/