dyadic 1.3.1 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## 1.7.1 (2026-10-17)
+
+- Corrected: `anthropic.messages.batches.create` described message batches as running at half price. Dyadic runs them in the
+  background at the usual price; nothing about the calls changed.
+
+## 1.7.0 (2026-10-17)
+
+The Anthropic API and OpenRouter's.
+
+- `client.anthropic`: the Anthropic API at `/api/anthropic/v1`, beside the base URL, with the client's key and
+  `anthropic-version: 2023-06-01`: `messages.create` (Anthropic's answer; with `stream: true` its events, the stream's
+  `text` from the text blocks and `usage` from `message_start` and `message_delta`), `messages.countTokens`,
+  `messages.batches.create/list/retrieve/cancel/results/delete` (`results` parses the JSONL), `models.list/retrieve` and
+  `files.create/list/retrieve/content/delete`, with types (`AnthropicMessage`, `AnthropicStreamEvent`, `AnthropicBatch`, ...).
+- `client.openrouter`: OpenRouter's API through the AI gateway at `/api/openrouter/v1`: `chat.completions.create`,
+  `completions.create`, `embeddings.create`, `models.list/endpoints`, `generation(id)`, `key()` and `credits()` (both
+  answered by Dyadic). A key without the gateway throws `DyadicError` with status 403 and code `gateway_not_allowed`:
+  Dyadic turns the gateway on for an app's key on request.
+- `Stream<T, U = Usage>`: a stream's usage type is its own (an Anthropic stream's is `AnthropicUsage`); existing code
+  is unchanged.
+- Packaging: the package carries its MIT license text (`LICENSE`).
+- Tests: `npm test` runs only the mocked suite (`test/`); `npm run test:production` checks a real API with `DYADIC_LIVE_API_KEY`.
+
+## 1.6.0 (2026-10-15)
+
+One trace per turn.
+
+- `useTrace()`: every following request carries the same W3C `traceparent`, so Dyadic shows a turn's decision, model
+  calls and run as one in API Activity and the Black Box; `currentTraceparent()` for requests sent another way. A call's
+  own `traceparent` header still wins.
+
+## 1.5.0 (2026-10-14)
+
+Plans.
+
+- `client.plans` (the key's plans switch): `list({ conversation, status, limit, after })`, `create({ title, steps, summary,
+  mode, conversation, metadata })`, `retrieve`, `update(id, { revision, ... })` (409 if the plan moved on since),
+  `approve(id, { revision })`, `cancel`, `moveStep(id, key, { status, note, verified_by })` and `events(id, { after, limit })`.
+- `client.plans.stream(id, { after, signal })`: the plan live, an async generator of `{ event, id, data }`: `plan.snapshot`
+  on each connection, then `plan.created`, `plan.approved`, `plan.step`, ... with the plan as it is then. It connects again
+  when the service asks or the connection drops, resuming after the last event (`Last-Event-ID`), stops after `end` (the
+  plan completed, cancelled or failed), and honors an AbortSignal.
+- `runs.create({ planMode: true })` investigates read-only and proposes a plan; `runs.create({ planId })` carries out an
+  approved plan (refused with `plan_not_runnable` otherwise). Sent as `plan_mode` and `plan_id`, which `RunParams` also
+  takes. Streamed runs send `plan.updated` (`RunEvent.plan`); a completed run lists the plans it touched (`Run.plans`).
+- Types: `Plan`, `PlanStep`, `PlanEvent`, `PlanStatus`, `PlanStepStatus`, `PlanStepInput`, `PlanCreateParams`,
+  `PlanUpdateParams`, `PlanListQuery`, `PlanStreamEvent`; `BuiltinTool` includes `plans.propose`, `plans.step` and `plans.get`.
+
+## 1.4.0 (2026-10-14)
+
+Agent Black Box.
+
+- `BlackBoxRecorder`: record your own agent's runs (model calls, tool calls, subagents, policy
+  decisions, approvals, verified outcomes) into `POST /v1/blackbox/events`, without blocking it:
+  bounded queue, batches with an `Idempotency-Key`, per-process sequence numbers so lost events show
+  as gaps, metadata only unless `captureContent: true` (secrets redacted first).
+- W3C trace context: `span.traceparent()`, `recorder.start({ traceparent })` for remote subagents.
+- `instrumentMcpClient` (MCP tool calls).
+- `BlackBoxSpanExporter`: an OpenTelemetry `SpanExporter` (SDK 1.x and 2.x, no runtime dependency) that sends
+  GenAI and OpenInference spans as OTLP/JSON; content attributes only with `captureContent: true`, values redacted
+  first, batches split to fit the service. `spanToOtlp` and `toOtlpRequests` convert without sending.
+- `client.blackbox`: `send`, `sendOtlp`, `runs.list/retrieve/events/graph/verify/export/otlp/simulate`,
+  `findings`, `diff`, `keys`, `verify`.
+- `verifyBundle`: check an evidence bundle offline (WebCrypto Ed25519; Node 18+, browsers). It also checks a bundle's
+  anchors: the anchored checkpoint is in the bundle's log at or after the run's last checkpoint, the Merkle proof leads to
+  the root, and the RFC 3161 token's messageImprint is that root (its genTime is reported). The authority's signature on the
+  token is not checked in TypeScript, and the report's warnings say so. `readTimestampToken`, `anchorLeaf`, `foldProof`.
+- `client.blackbox` covers every route of the service: `overview`, `settings`, `runs.checkpoints/content/erase/delete`,
+  `runs.events({ types })`, `bookmarks.list/create/delete`, `findings.list/update` (calling `findings(query)` still works),
+  `rules.list/preview`, `sinks.list/create/retrieve/update/delete/test/rotate/deliveries/retryDelivery`; `sendOtlp(bytes)`
+  sends OTLP protobuf.
+- Live streams: `client.blackbox.runs.stream(id, { after, signal })` and `client.blackbox.watch({ signal })`, async generators
+  of `{ event, id, data }` over fetch and ReadableStream that connect again when the service asks or the connection drops
+  (resuming after the last event), stop after `end` or `deleted`, and honor an AbortSignal.
+- `verifyWebhook(body, headers, secret, { tolerance })` checks a webhook sink's Standard Webhooks signature (WebCrypto HMAC,
+  constant-time, several signatures, 5 minutes by default) and returns the message; `signWebhook`, `WebhookVerificationError`.
+- `RunDeletedError` (a `DyadicError`): a run of the key's that was deleted (HTTP 410, `run_deleted`), with `deletion`.
+- The rest of the OpenAI-compatible API: `conversations` (and `items`), stored chat completions (`chat.completions.list/
+  retrieve/update/delete`, `messages.list`), `responses.inputTokens.count` and `responses.compact`, `containers` (and
+  `files`), `vectorStores` (`files`, `fileBatches`, `search`) and `skills` (and `versions`).
+- `request()` takes `headers`, a raw `content` body and an AbortSignal (`signal`); query values may be arrays.
+- `BuiltinTool` includes `audio.speak` and `audio.transcribe`; `ResponseParams` has `conversation` and `background`.
+
+Fixes:
+
+- Leaving a `for await` over a stream early (`break`, `return`, a throw) only released the reader: the HTTP request, and the
+  completion it was paying for, kept running. It now cancels the body and aborts the request.
+- Requests say who calls: `User-Agent: dyadic-typescript/<version>`, except in browsers (which don't allow it).
+- The README's connected-apps example compiles (`error.body` is `unknown`).
+
 ## 1.3.1 (2026-10-10)
 
 - The version the SDK reports (`__version__` / `VERSION`, and the User-Agent header) is the package's

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dyadic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -67,7 +67,31 @@ const run = await client.runs.run({
 console.log(run.output_text);
 ```
 
-`client.runs.create({ ..., stream: true })` streams the run's events.
+`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
 
@@ -95,6 +119,8 @@ 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
 
@@ -103,7 +129,9 @@ try {
     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.authorize_url);
+  if (error instanceof DyadicError && error.code === "authorization_required") {
+    console.log("Allow this app:", (error.body as { authorize_url?: string }).authorize_url);
+  }
 }
 ```
 
@@ -111,4 +139,167 @@ try {
 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/

package/dist/blackbox.d.ts

@@ -0,0 +1,266 @@
+export declare const BUNDLE_FORMAT = "dyadic.blackbox.bundle/1";
+export declare const LIMITATIONS: string[];
+/** RFC 8785 canonical JSON: sorted keys (UTF-16 code units), no whitespace, ECMAScript numbers and string escapes. */
+export declare function canonical(value: unknown): string;
+export declare function sha256Hex(data: string | Uint8Array): Promise<string>;
+export declare const genesis: (runId: string) => Promise<string>;
+export declare function commitment(salt: Uint8Array, value: unknown): Promise<string>;
+export declare function ed25519Verify(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+export declare const newTraceId: () => string;
+export declare const newSpanId: () => string;
+/** { traceId, spanId, sampled } from a W3C traceparent header (lowercase hex only), or null. */
+export declare function parseTraceparent(header?: string | null): {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+} | null;
+export declare const formatTraceparent: (traceId: string, spanId: string, sampled?: boolean) => string;
+/** Credentials replaced with [REDACTED:<kind>] before anything leaves the process (the service redacts again, and more). */
+export declare function redactSecrets(value: unknown, depth?: number): unknown;
+export interface VerifyReport {
+    ok: boolean;
+    events: number;
+    signed_through: number;
+    trusted_keys: boolean;
+    checks: {
+        name: string;
+        ok: boolean;
+        detail: string;
+    }[];
+    errors: string[];
+    warnings: string[];
+    limitations: string[];
+}
+/** The same checks as the service's and the Python SDK's verifier. `trustedKeys` maps key ids to base64 public keys. */
+export declare function verifyBundle(bundle: any, trustedKeys?: Record<string, string>): Promise<VerifyReport>;
+/** What an RFC 3161 TimeStampToken says it stamps (its TSTInfo's messageImprint) and when (genTime). Unchecked: the
+ * authority's CMS signature over it is not verified here. */
+export declare function readTimestampToken(token: Uint8Array): {
+    hashAlg: string;
+    digest: string;
+    genTime: string;
+};
+/** A head's leaf in an anchoring batch (RFC 6962 hashing): sha256(0x00 || canonical({v, tenant, tenant_seq, head})). */
+export declare const anchorLeaf: (tenant: string, tenantSeq: number, head: string) => Promise<Uint8Array>;
+/** The root a leaf and its proof lead to: each step's sibling on its side, nodes sha256(0x01 || left || right). */
+export declare function foldProof(leaf: Uint8Array, proof: {
+    side: string;
+    hash: string;
+}[]): Promise<Uint8Array>;
+/** The message isn't one the sink signed, or its timestamp is too far from now. */
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type HeaderSource = {
+    get(name: string): string | null | undefined;
+} | Record<string, string | string[] | undefined | null> | Iterable<[string, string]>;
+/** The webhook-signature value the service sends for `body` (to test your own receiver). */
+export declare function signWebhook(secret: string, messageId: string, timestamp: number, body: string | Uint8Array | ArrayBuffer): Promise<string>;
+/** A Black Box webhook, parsed, once its signature matches and its timestamp is within `tolerance` seconds (300) of now
+ * (`now`, in Unix seconds, for tests); otherwise WebhookVerificationError says why. Pass the body exactly as it arrived (the
+ * raw text or bytes, before any JSON parsing) and the request's headers (a Headers object, Node's req.headers, or a plain
+ * object: case doesn't matter). Several space-separated signatures (a secret being rotated) are fine. WebCrypto: Node 18+,
+ * browsers, Deno, Bun, workers. */
+export declare function verifyWebhook<T = any>(body: string | Uint8Array | ArrayBuffer, headers: HeaderSource, secret: string, options?: {
+    tolerance?: number;
+    now?: number;
+}): Promise<T>;
+export interface BlackBoxEvent {
+    id: string;
+    type: string;
+    status: string;
+    name: string;
+    time: string;
+    seq: number;
+    span_id: string;
+    parent_span_id: string;
+    agent: string;
+    attrs: Record<string, unknown>;
+    content?: Record<string, unknown>;
+    basis?: string;
+}
+export interface RecorderOptions {
+    environment?: "production" | "staging" | "development" | "test";
+    captureContent?: boolean;
+    redact?: ((value: unknown) => unknown) | null;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxQueue?: number;
+    maxRetries?: number;
+    /** Replaces the HTTP call (tests, a proxy). */
+    send?: (batch: Record<string, unknown>, idempotencyKey: string) => Promise<unknown>;
+    onError?: (error: unknown, batch: Record<string, unknown>) => void;
+}
+interface Sender {
+    blackbox: {
+        send: (batch: Record<string, unknown>, options?: {
+            idempotencyKey?: string;
+        }) => Promise<unknown>;
+    };
+}
+export declare class BlackBoxRecorder {
+    readonly stats: {
+        queued: number;
+        sent: number;
+        dropped: number;
+        failedBatches: number;
+    };
+    readonly options: Required<Omit<RecorderOptions, "send" | "onError">> & Pick<RecorderOptions, "onError">;
+    private queue;
+    private dropped;
+    private timer;
+    private sending;
+    private readonly send;
+    constructor(client: Sender | null, options?: RecorderOptions);
+    /** Start a run; with `body`, run it and end it (failed if it throws). */
+    start(params: {
+        title?: string;
+        agent?: string;
+        agentName?: string;
+        runId?: string;
+        traceparent?: string;
+    }): BlackBoxRun;
+    run<T>(params: {
+        title?: string;
+        agent?: string;
+        agentName?: string;
+        runId?: string;
+        traceparent?: string;
+    }, body: (run: BlackBoxRun) => Promise<T> | T): Promise<T>;
+    /** @internal */
+    enqueue(run: BlackBoxRun, event: BlackBoxEvent): void;
+    /** Send everything queued; resolves when it has been sent (or given up on). */
+    flush(): Promise<void>;
+    private drain;
+    private deliver;
+}
+type SpanKind = "run" | "span" | "model" | "tool" | "agent";
+/** A timed piece of a run. Its methods make its children. */
+export declare class BlackBoxSpan {
+    readonly run: BlackBoxRun;
+    readonly kind: SpanKind;
+    readonly name: string;
+    readonly parentId: string;
+    readonly agent: string;
+    private readonly attrs;
+    private readonly content?;
+    readonly spanId: string;
+    ended: boolean;
+    private readonly startedAt;
+    constructor(run: BlackBoxRun, kind: SpanKind, name: string, parentId: string, agent: string, attrs?: Record<string, unknown>, content?: Record<string, unknown> | undefined, spanId?: string);
+    /** @internal */
+    begin(): this;
+    protected finish(type: string, status: string, attrs?: Record<string, unknown>, content?: Record<string, unknown>): void;
+    end(attrs?: Record<string, unknown>): void;
+    fail(error?: unknown, attrs?: Record<string, unknown>): void;
+    traceparent(): string;
+    private around;
+    modelCall<T>(model: string, options?: {
+        input?: unknown;
+        provider?: string;
+        [k: string]: unknown;
+    }, body?: (call: ModelCallSpan) => Promise<T> | T): Promise<T | undefined>;
+    toolCall<T>(name: string, options?: {
+        args?: unknown;
+        kind?: string;
+        effect?: boolean;
+        hosts?: string[];
+        callId?: string;
+        risk?: string;
+        [k: string]: unknown;
+    }, body?: (tool: ToolCallSpan) => Promise<T> | T): Promise<T | undefined>;
+    agentSpan<T>(agentId: string, options?: {
+        name?: string;
+        task?: unknown;
+        [k: string]: unknown;
+    }, body?: (agent: BlackBoxSpan) => Promise<T> | T): Promise<T | undefined>;
+    span<T>(name: string, attrs?: Record<string, unknown>, body?: (span: BlackBoxSpan) => Promise<T> | T): Promise<T | undefined>;
+    /** A decision your own policy made (allow, deny, require_approval). */
+    policy(decision: string, rule: string, options?: {
+        tool?: string;
+        reason?: string;
+        policy?: string;
+        version?: string;
+    }): void;
+    note(text: string, attrs?: Record<string, unknown>): void;
+}
+export declare class ModelCallSpan extends BlackBoxSpan {
+    /** What the model returned. Never pass hidden reasoning: it is not recorded. */
+    responded(options?: {
+        output?: unknown;
+        usage?: Record<string, number>;
+        toolCalls?: {
+            id?: string;
+            name?: string;
+        }[];
+        responseModel?: string;
+        responseId?: string;
+        finishReason?: string;
+    }): void;
+}
+export declare class ToolCallSpan extends BlackBoxSpan {
+    executing(): void;
+    /** It worked, as the tool reports: a claim, until `run.verified` records evidence. */
+    result(value?: unknown, attrs?: Record<string, unknown>): void;
+    blocked(rule: string, reason?: string, decision?: "deny" | "require_approval"): void;
+}
+export declare class BlackBoxRun extends BlackBoxSpan {
+    readonly recorder: BlackBoxRecorder;
+    readonly id: string;
+    readonly traceId: string;
+    readonly title: string;
+    readonly agentName: string;
+    private readonly parentHeader;
+    private readonly remoteParent;
+    private seq;
+    constructor(recorder: BlackBoxRecorder, params: {
+        title?: string;
+        agent?: string;
+        agentName?: string;
+        runId?: string;
+        traceparent?: string;
+    });
+    descriptor(): Record<string, unknown>;
+    /** @internal */
+    event(type: string, span: BlackBoxSpan, fields?: {
+        status?: string;
+        name?: string;
+        attrs?: Record<string, unknown>;
+        content?: Record<string, unknown>;
+    }): BlackBoxEvent;
+    /** @internal */
+    emit(type: string, span: BlackBoxSpan, fields?: Parameters<BlackBoxRun["event"]>[2]): void;
+    /** @internal */
+    noteEvent(text: string, attrs: Record<string, unknown>): BlackBoxEvent;
+    start(): this;
+    end(status?: "completed" | "failed" | "cancelled" | "requires_action" | Record<string, unknown>, options?: {
+        error?: unknown;
+    }): void;
+    /** The task and its boundaries: the Black Box flags tools, hosts or steps beyond them. */
+    declare(options?: {
+        prompt?: string;
+        allowedTools?: string[];
+        allowedHosts?: string[];
+        maxSteps?: number;
+        [k: string]: unknown;
+    }): void;
+    approval(tool: string, decision: "approved" | "denied" | "expired", options?: {
+        approvalId?: string | number;
+        by?: string;
+    }): void;
+    /** You checked an effect independently (read back what was written): evidence, not a claim. */
+    verified(kind: string, evidence: string, attrs?: Record<string, unknown>): void;
+    unverified(kind: string, reason: string): void;
+}
+/** Every tool an MCP client calls, recorded on `span`: the official TypeScript SDK's Client (callTool({ name, arguments })), or anything shaped like it. */
+export declare function instrumentMcpClient<C extends {
+    callTool: (params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }, ...rest: any[]) => Promise<any>;
+}>(client: C, span: BlackBoxSpan, options?: {
+    server?: string;
+    host?: string;
+    readOnly?: string[];
+}): C;
+export {};