dyadic 1.3.1 → 1.7.0

package/dist/index.js

@@ -1,7 +1,10 @@
 // The official TypeScript SDK for the Dyadic API: Iris
-// through the OpenAI-compatible endpoints at https://dyadic.app/api/openai/v1.
-export const VERSION = "1.3.1";
+// through the OpenAI-compatible endpoints at https://dyadic.app/api/openai/v1, and beside them the Anthropic API
+// (/api/anthropic/v1) and OpenRouter's API through the AI gateway (/api/openrouter/v1).
+export const VERSION = "1.7.0";
 export const DEFAULT_BASE_URL = "https://dyadic.app/api/openai/v1";
+/** The Anthropic API version the `anthropic` calls speak (sent as anthropic-version, as Anthropic's SDKs do). */
+export const ANTHROPIC_VERSION = "2023-06-01";
 /** Bytes from the API (speech audio, file downloads). */
 export class Binary {
     constructor(data, contentType, requestId = "") {
@@ -40,6 +43,15 @@ function form(fields, files) {
     }
     return out;
 }
+/** A skill's upload: each file as a "files" part named by its path in the skill (or one zip). */
+function skillForm(files, makeDefault) {
+    const out = new FormData();
+    const list = Array.isArray(files) ? files : [files];
+    list.forEach((file, index) => { const [blob, name] = toBlob(file, list.length === 1 ? "skill.zip" : `file-${index}`); out.append("files", blob, name); });
+    if (makeDefault !== undefined)
+        out.append("default", makeDefault ? "true" : "false");
+    return out;
+}
 /** An error from the API, in OpenAI's shape (status 0 for a network failure). */
 export class DyadicError extends Error {
     constructor(message, init = {}) {
@@ -53,6 +65,19 @@ export class DyadicError extends Error {
         this.body = init.body;
     }
 }
+/** A Black Box run this key made was deleted by the account's owner or the application (HTTP 410, code run_deleted).
+ * `deletion` is the signed record of the deletion when the service sends one. */
+export class RunDeletedError extends DyadicError {
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = "RunDeletedError";
+    }
+    get deletion() {
+        const body = (this.body ?? {});
+        const found = body.deletion ?? body.error?.deletion;
+        return found && typeof found === "object" ? found : null;
+    }
+}
 /** A streamed completion: `for await (const chunk of stream)`. `text` and `usage` fill in as it goes. */
 export class Stream {
     constructor(http, controller, onDone = () => { }) {
@@ -65,12 +90,14 @@ export class Stream {
     async *[Symbol.asyncIterator]() {
         const reader = this.http.body.getReader();
         const decoder = new TextDecoder();
-        let buffer = "";
+        let buffer = "", finished = false;
         try {
             for (;;) {
                 const { value, done } = await reader.read();
-                if (done)
+                if (done) {
+                    finished = true;
                     return;
+                }
                 buffer += decoder.decode(value, { stream: true });
                 let index;
                 while ((index = buffer.indexOf("\n\n")) >= 0) {
@@ -79,8 +106,10 @@ export class Stream {
                     const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("");
                     if (!data)
                         continue;
-                    if (data === "[DONE]")
+                    if (data === "[DONE]") {
+                        finished = true;
                         return;
+                    }
                     const chunk = JSON.parse(data);
                     if (chunk.error)
                         throw new DyadicError(chunk.error.message, { status: 200, type: chunk.error.type, code: chunk.error.code, body: chunk });
@@ -88,7 +117,12 @@ export class Stream {
                         const failure = chunk.response?.error ?? { message: "The response failed." };
                         throw new DyadicError(failure.message, { status: 200, code: failure.code ?? null, body: chunk });
                     }
-                    if (chunk.usage)
+                    // An Anthropic stream's usage starts in message_start, and message_delta adds to it.
+                    if (chunk.type === "message_start")
+                        this.usage = chunk.message?.usage ?? this.usage;
+                    else if (chunk.type === "message_delta" && chunk.usage)
+                        this.usage = { ...(this.usage ?? {}), ...chunk.usage };
+                    else if (chunk.usage)
                         this.usage = chunk.usage;
                     if (chunk.type === "run.completed") {
                         this.run = chunk;
@@ -101,12 +135,19 @@ export class Stream {
                     }
                     const choice = chunk.choices?.[0];
                     this.text += chunk.type === "response.output_text.delta" ? chunk.delta ?? "" : chunk.type === "delta" ? chunk.text ?? ""
-                        : choice?.delta?.content ?? choice?.text ?? "";
+                        : chunk.type === "content_block_delta" ? (chunk.delta?.type === "text_delta" ? chunk.delta.text ?? "" : "")
+                            : choice?.delta?.content ?? choice?.text ?? "";
                     yield chunk;
                 }
             }
         }
         finally {
+            // Leaving early (break, return, a throw) must end the request too: releasing the reader alone leaves the
+            // response, and the completion it is paying for, running.
+            if (!finished) {
+                await reader.cancel().catch(() => { });
+                this.controller.abort();
+            }
             reader.releaseLock();
             this.onDone();
         }
@@ -129,6 +170,83 @@ const sentNothing = (error) => {
     const e = error;
     return [e?.code, e?.cause?.code, e?.cause?.cause?.code].some((code) => code !== undefined && NOT_SENT.has(code));
 };
+// Browsers don't let a page set User-Agent (and a custom one would cost a CORS preflight); every other runtime says who calls.
+const IN_BROWSER = typeof globalThis.document !== "undefined"
+    || typeof globalThis.importScripts === "function";
+const USER_AGENT = IN_BROWSER ? undefined : `dyadic-typescript/${VERSION}`;
+// One trace for one piece of work (a bot answering one message): every request after `useTrace()` carries the same W3C
+// traceparent, so Dyadic shows the decision, the model call and the run that answered one message as one turn.
+let currentTraceId = "";
+const randomHex = (bytes) => Array.from({ length: bytes }, () => Math.floor(Math.random() * 256).toString(16).padStart(2, "0")).join("");
+/** Start (or join, given a 32-hex trace id) the trace the following requests carry; returns its id. */
+export function useTrace(traceId) {
+    const value = String(traceId ?? "").trim().toLowerCase();
+    currentTraceId = /^[0-9a-f]{32}$/.test(value) && !/^0+$/.test(value) ? value : randomHex(16);
+    return currentTraceId;
+}
+/** The current trace's traceparent header (a new span each call), or {} when none was started. */
+export function currentTraceparent() {
+    return currentTraceId ? { traceparent: `00-${currentTraceId}-${randomHex(8)}-01` } : {};
+}
+// A live stream with no bytes (not even the service's 15-second keep-alives) for this long has dropped.
+const LIVE_IDLE_MS = 60000;
+const pause = (ms, signal) => new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() { clearTimeout(timer); signal?.removeEventListener("abort", done); resolve(); }
+    signal?.addEventListener("abort", done, { once: true });
+});
+const aborted = (signal, cause) => signal.reason ?? cause
+    ?? Object.assign(new Error("The operation was aborted."), { name: "AbortError" });
+function queryString(query) {
+    const parts = [];
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(item))}`);
+    }
+    return parts.join("&");
+}
+/** Server-sent event frames, [event, id, data], from a body reader; `onBytes` hears every chunk (keep-alives too). */
+async function* sseFrames(reader, onBytes) {
+    const decoder = new TextDecoder();
+    let buffer = "", event = "", id = null, data = [];
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            return;
+        onBytes();
+        buffer += decoder.decode(value, { stream: true });
+        let index;
+        while ((index = buffer.search(/\r\n|\r|\n/)) >= 0) {
+            if (buffer[index] === "\r" && index === buffer.length - 1)
+                break; // a \r\n split between chunks
+            const line = buffer.slice(0, index);
+            buffer = buffer.slice(index + (buffer.startsWith("\r\n", index) ? 2 : 1));
+            if (!line) {
+                if (data.length || event)
+                    yield [event || "message", id, data.join("\n")];
+                event = "";
+                id = null;
+                data = [];
+                continue;
+            }
+            if (line.startsWith(":"))
+                continue;
+            const colon = line.indexOf(":");
+            const name = colon < 0 ? line : line.slice(0, colon);
+            let field = colon < 0 ? "" : line.slice(colon + 1);
+            if (field.startsWith(" "))
+                field = field.slice(1);
+            if (name === "event")
+                event = field;
+            else if (name === "data")
+                data.push(field);
+            else if (name === "id" && !field.includes("\0"))
+                id = field;
+        }
+    }
+}
 const newKey = () => globalThis.crypto?.randomUUID?.()
     ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
 /** Loopback, a private address or a single-label name (a Docker or LAN service such as dyadic-api): where plain http
@@ -148,9 +266,10 @@ export class Dyadic {
     constructor(options = {}) {
         /** An agent answers a conversation: one of the account's agents by id ("iris") or your own agent inline,
          * with Dyadic's built-in tools and your own functions. A run that calls your functions ends with status
-         * "requires_action": run `function_calls`, append `messages` and your results, and run again (or use `run`). */
+         * "requires_action": run `function_calls`, append `messages` and your results, and run again (or use `run`).
+         * With the key's plans switch, `planMode` proposes a plan and `planId` carries out an approved one. */
         this.runs = {
-            create: ((params) => this.request("POST", this.platformURL("/runs"), params, Boolean(params.stream), { executes: true })),
+            create: ((params) => this.request("POST", this.platformURL("/runs"), this.runBody(params), Boolean(params.stream), { executes: true })),
             /** Run to completion, calling your functions whenever the agent asks. The result's `messages` hold
              * everything the run added, ready to append to your conversation. */
             run: async (params) => {
@@ -191,6 +310,21 @@ export class Dyadic {
                     const body = params.stream ? { stream_options: { include_usage: true }, ...params } : params;
                     return this.request("POST", "/chat/completions", body, Boolean(params.stream));
                 }),
+                /** Completions created with store: true (kept 30 days), newest first; `metadata` matches key/values. */
+                list: (query = {}) => {
+                    const { metadata, ...rest } = query;
+                    const flat = { ...rest };
+                    for (const [key, value] of Object.entries(metadata ?? {}))
+                        flat[`metadata[${key}]`] = value;
+                    return this.request("GET", "/chat/completions", undefined, false, { query: flat });
+                },
+                retrieve: (id) => this.request("GET", `/chat/completions/${id}`),
+                /** Replace a stored completion's metadata. */
+                update: (id, params) => this.request("POST", `/chat/completions/${id}`, params, false, { idempotent: true }),
+                delete: (id) => this.request("DELETE", `/chat/completions/${id}`),
+                messages: {
+                    list: (id, query = {}) => this.request("GET", `/chat/completions/${id}/messages`, undefined, false, { query }),
+                },
             },
         };
         this.completions = {
@@ -205,6 +339,31 @@ export class Dyadic {
             delete: (id) => this.request("DELETE", `/responses/${id}`),
             inputItems: (id, query = {}) => this.request("GET", `/responses/${id}/input_items`, undefined, false, { query }),
             cancel: (id) => this.request("POST", `/responses/${id}/cancel`),
+            /** How many input tokens a Responses request would use: an estimate, free (no model runs). */
+            inputTokens: {
+                count: (params) => this.request("POST", "/responses/input_tokens", params, false, { idempotent: true }),
+            },
+            /** Your user messages and one compaction item summarising everything else; send its output as the next request's input. */
+            compact: (params) => this.request("POST", "/responses/compact", params),
+        };
+        /** Conversations for the Responses API: pass `conversation` to responses.create and each response's input and output
+         * are added to it. */
+        this.conversations = {
+            create: (params = {}) => this.request("POST", "/conversations", params),
+            retrieve: (id) => this.request("GET", `/conversations/${id}`),
+            update: (id, params) => this.request("POST", `/conversations/${id}`, params, false, { idempotent: true }),
+            /** Deletes the conversation and its items. */
+            delete: (id) => this.request("DELETE", `/conversations/${id}`),
+            items: {
+                create: (conversationId, params) => this.request("POST", `/conversations/${conversationId}/items`, { items: params.items }, false, { query: { "include[]": params.include } }),
+                list: (conversationId, query = {}) => {
+                    const { include, ...rest } = query;
+                    return this.request("GET", `/conversations/${conversationId}/items`, undefined, false, { query: { ...rest, "include[]": include } });
+                },
+                retrieve: (itemId, params) => this.request("GET", `/conversations/${params.conversation_id}/items/${itemId}`, undefined, false, { query: { "include[]": params.include } }),
+                /** Removes the item; answers with the conversation. */
+                delete: (itemId, params) => this.request("DELETE", `/conversations/${params.conversation_id}/items/${itemId}`),
+            },
         };
         this.embeddings = {
             create: (params) => this.request("POST", "/embeddings", params),
@@ -243,6 +402,140 @@ export class Dyadic {
             retrieve: (id) => this.request("GET", `/batches/${id}`),
             cancel: (id) => this.request("POST", `/batches/${id}/cancel`),
         };
+        /** Containers (cntr_...) for the code interpreter and shell tools; needs the key's code interpreter switch. */
+        this.containers = {
+            create: (params = {}) => this.request("POST", "/containers", { name: "", ...params }),
+            list: (query = {}) => this.request("GET", "/containers", undefined, false, { query }),
+            retrieve: (id) => this.request("GET", `/containers/${id}`),
+            delete: (id) => this.request("DELETE", `/containers/${id}`),
+            files: {
+                /** Put a file in the container (at /mnt/data/<name>): upload `file`, or copy an uploaded `file_id`. */
+                create: (containerId, params) => params.file !== undefined
+                    ? this.request("POST", `/containers/${containerId}/files`, undefined, false, { form: form({}, { file: [params.file, "file"] }) })
+                    : this.request("POST", `/containers/${containerId}/files`, { file_id: params.file_id }),
+                list: (containerId, query = {}) => this.request("GET", `/containers/${containerId}/files`, undefined, false, { query }),
+                retrieve: (fileId, params) => this.request("GET", `/containers/${params.container_id}/files/${fileId}`),
+                delete: (fileId, params) => this.request("DELETE", `/containers/${params.container_id}/files/${fileId}`),
+                content: {
+                    retrieve: (fileId, params) => this.request("GET", `/containers/${params.container_id}/files/${fileId}/content`, undefined, false, { raw: true }),
+                },
+            },
+        };
+        /** Vector stores (vs_...) for the file search tool, and searching them directly; needs the key's file search switch.
+         * Indexing and search cost no credits. */
+        this.vectorStores = {
+            create: (params = {}) => this.request("POST", "/vector_stores", params),
+            list: (query = {}) => this.request("GET", "/vector_stores", undefined, false, { query }),
+            retrieve: (id) => this.request("GET", `/vector_stores/${id}`),
+            update: (id, params) => this.request("POST", `/vector_stores/${id}`, params, false, { idempotent: true }),
+            delete: (id) => this.request("DELETE", `/vector_stores/${id}`),
+            search: (id, params) => this.request("POST", `/vector_stores/${id}/search`, params, false, { idempotent: true }),
+            files: {
+                /** Add an uploaded file; it is read and indexed in the background. */
+                create: (vectorStoreId, params) => this.request("POST", `/vector_stores/${vectorStoreId}/files`, params),
+                list: (vectorStoreId, query = {}) => this.request("GET", `/vector_stores/${vectorStoreId}/files`, undefined, false, { query }),
+                retrieve: (fileId, params) => this.request("GET", `/vector_stores/${params.vector_store_id}/files/${fileId}`),
+                update: (fileId, params) => this.request("POST", `/vector_stores/${params.vector_store_id}/files/${fileId}`, { attributes: params.attributes }, false, { idempotent: true }),
+                delete: (fileId, params) => this.request("DELETE", `/vector_stores/${params.vector_store_id}/files/${fileId}`),
+                /** The file's parsed text, as indexed. */
+                content: (fileId, params) => this.request("GET", `/vector_stores/${params.vector_store_id}/files/${fileId}/content`),
+            },
+            fileBatches: {
+                create: (vectorStoreId, params) => this.request("POST", `/vector_stores/${vectorStoreId}/file_batches`, params),
+                retrieve: (batchId, params) => this.request("GET", `/vector_stores/${params.vector_store_id}/file_batches/${batchId}`),
+                cancel: (batchId, params) => this.request("POST", `/vector_stores/${params.vector_store_id}/file_batches/${batchId}/cancel`),
+                listFiles: (batchId, params) => {
+                    const { vector_store_id, ...query } = params;
+                    return this.request("GET", `/vector_stores/${vector_store_id}/file_batches/${batchId}/files`, undefined, false, { query });
+                },
+            },
+        };
+        /** Skills (skill_...): a SKILL.md and its files, mounted into containers; needs the key's skills switch. Upload the files
+         * with their paths in the skill as names ({ name: "scripts/run.py", data }), or one zip. */
+        this.skills = {
+            create: (params) => this.request("POST", "/skills", undefined, false, { form: skillForm(params.files) }),
+            list: (query = {}) => this.request("GET", "/skills", undefined, false, { query }),
+            retrieve: (id) => this.request("GET", `/skills/${id}`),
+            /** Choose the default version. */
+            update: (id, params) => this.request("POST", `/skills/${id}`, { default_version: String(params.default_version) }, false, { idempotent: true }),
+            delete: (id) => this.request("DELETE", `/skills/${id}`),
+            /** The default version's files as a zip. */
+            content: { retrieve: (id) => this.request("GET", `/skills/${id}/content`, undefined, false, { raw: true }) },
+            versions: {
+                create: (skillId, params) => this.request("POST", `/skills/${skillId}/versions`, undefined, false, { form: skillForm(params.files, params.default) }),
+                list: (skillId, query = {}) => this.request("GET", `/skills/${skillId}/versions`, undefined, false, { query }),
+                retrieve: (version, params) => this.request("GET", `/skills/${params.skill_id}/versions/${version}`),
+                delete: (version, params) => this.request("DELETE", `/skills/${params.skill_id}/versions/${version}`),
+                content: {
+                    retrieve: (version, params) => this.request("GET", `/skills/${params.skill_id}/versions/${version}/content`, undefined, false, { raw: true }),
+                },
+            },
+        };
+        /** The Anthropic API through Dyadic (/api/anthropic/v1, with this client's key): Claude's own request and answer shapes,
+         * behaving as Anthropic's do, with Dyadic's billing, limits, activity log and Black Box. Anthropic's own SDKs work there
+         * too (baseURL https://dyadic.app/api/anthropic). */
+        this.anthropic = {
+            messages: {
+                /** A message, or with `stream: true` Anthropic's events; the stream's `text` and `usage` fill in as they come. */
+                create: ((params) => this.anthropicCall("POST", "/messages", params, Boolean(params.stream))),
+                /** A request's input tokens (free; no model runs). */
+                countTokens: (params) => this.anthropicCall("POST", "/messages/count_tokens", params, false, { idempotent: true }),
+                /** Up to 100,000 requests at half price; poll `retrieve` until processing_status is "ended", then read `results`. */
+                batches: {
+                    create: (params) => this.anthropicCall("POST", "/messages/batches", params),
+                    list: (query = {}) => this.anthropicCall("GET", "/messages/batches", undefined, false, { query }),
+                    retrieve: (id) => this.anthropicCall("GET", `/messages/batches/${id}`),
+                    cancel: (id) => this.anthropicCall("POST", `/messages/batches/${id}/cancel`, undefined, false, { idempotent: true }),
+                    /** Each request's result once the batch has ended, in order. */
+                    results: async (id) => {
+                        const lines = await this.anthropicCall("GET", `/messages/batches/${id}/results`, undefined, false, { raw: true });
+                        return lines.text().split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+                    },
+                    delete: (id) => this.anthropicCall("DELETE", `/messages/batches/${id}`),
+                },
+            },
+            /** The Claude models this key may call. */
+            models: {
+                list: (query = {}) => this.anthropicCall("GET", "/models", undefined, false, { query }),
+                retrieve: (id) => this.anthropicCall("GET", `/models/${id}`),
+            },
+            /** Files to reference from a message ({ type: "document", source: { type: "file", file_id } }). */
+            files: {
+                create: (params) => this.anthropicCall("POST", "/files", undefined, false, { form: form({}, { file: [params.file, "file"] }) }),
+                list: (query = {}) => this.anthropicCall("GET", "/files", undefined, false, { query }),
+                retrieve: (id) => this.anthropicCall("GET", `/files/${id}`),
+                content: (id) => this.anthropicCall("GET", `/files/${id}/content`, undefined, false, { raw: true }),
+                delete: (id) => this.anthropicCall("DELETE", `/files/${id}`),
+            },
+        };
+        /** OpenRouter's API through Dyadic's gateway (/api/openrouter/v1, with this client's key). It needs the key's AI gateway,
+         * which Dyadic turns on for an app on request (the key's owner can turn it off; a key without it is answered 403
+         * gateway_not_allowed). Every call counts against the key's limits and is billed and logged by Dyadic. */
+        this.openrouter = {
+            chat: {
+                completions: {
+                    create: ((params) => this.request("POST", this.apiURL("openrouter", "/chat/completions"), params, Boolean(params.stream))),
+                },
+            },
+            completions: {
+                create: ((params) => this.request("POST", this.apiURL("openrouter", "/completions"), params, Boolean(params.stream))),
+            },
+            /** Embeddings (the key's Embeddings switch). */
+            embeddings: {
+                create: (params) => this.request("POST", this.apiURL("openrouter", "/embeddings"), params),
+            },
+            models: {
+                list: (query = {}) => this.request("GET", this.apiURL("openrouter", "/models"), undefined, false, { query }),
+                /** A model's providers and their prices. */
+                endpoints: (author, slug) => this.request("GET", this.apiURL("openrouter", `/models/${author}/${slug}/endpoints`)),
+            },
+            /** A generation's cost and tokens (this key's own requests only). */
+            generation: (id) => this.request("GET", this.apiURL("openrouter", "/generation"), undefined, false, { query: { id } }),
+            /** This Dyadic key's usage and limits, as OpenRouter's /key answers (answered by Dyadic). */
+            key: () => this.request("GET", this.apiURL("openrouter", "/key")),
+            /** The account's allowance and use this week, in dollars (answered by Dyadic). */
+            credits: () => this.request("GET", this.apiURL("openrouter", "/credits")),
+        };
         /** Connected apps. Show the person `authorize_url` when `authorized` is false. */
         this.connections = {
             discord: (discordId) => this.request("GET", this.platformURL(`/connections/discord/${discordId}`)),
@@ -255,6 +548,117 @@ export class Dyadic {
                 create: ({ discord_id, ...fields }) => this.request("POST", this.platformURL("/workspace/saves"), { user: { discord_id: String(discord_id) }, ...fields }, false, { executes: true }),
             },
         };
+        /** Agent Black Box: send what your agent does (or record it with BlackBoxRecorder), read the runs this key made (also
+         * live), export and verify evidence, simulate (nothing ever runs: not the chat's Replay from here, which asks again for
+         * real), triage findings, route records to webhooks and collectors. A run of the key's that was deleted throws
+         * RunDeletedError (HTTP 410). */
+        this.blackbox = {
+            send: (batch, options = {}) => this.request("POST", this.platformURL("/blackbox/events"), batch, false, { idempotent: true, idempotencyKey: options.idempotencyKey }),
+            /** OTLP/HTTP traces: an object is sent as OTLP/JSON, bytes as OTLP protobuf (application/x-protobuf; the answer is then
+             * the protobuf ExportTraceServiceResponse, as Binary). */
+            sendOtlp: (request) => request instanceof Uint8Array || request instanceof ArrayBuffer
+                ? this.request("POST", this.platformURL("/blackbox/otlp/v1/traces"), undefined, false, { idempotent: true, content: request,
+                    headers: { "Content-Type": "application/x-protobuf", Accept: "application/x-protobuf" } })
+                : this.request("POST", this.platformURL("/blackbox/otlp/v1/traces"), request, false, { idempotent: true }),
+            /** Counts for this key's runs: by status and outcome, open findings, recording gaps. */
+            overview: () => this.request("GET", this.platformURL("/blackbox/overview")),
+            /** What the account keeps (recording, capture by kind) and for how long. */
+            settings: () => this.request("GET", this.platformURL("/blackbox/settings")),
+            runs: {
+                list: (query = {}) => this.request("GET", this.platformURL("/blackbox/runs"), undefined, false, { query }),
+                retrieve: (id) => this.request("GET", this.platformURL(`/blackbox/runs/${id}`)),
+                /** The run's events in chain order; `types` keeps only those types (up to 20). */
+                events: (id, query = {}) => this.request("GET", this.platformURL(`/blackbox/runs/${id}/events`), undefined, false, { query: { after: query.after, limit: query.limit, types: Array.isArray(query.types) ? query.types.join(",") || undefined : query.types } }),
+                graph: (id) => this.request("GET", this.platformURL(`/blackbox/runs/${id}/graph`)),
+                verify: (id) => this.request("GET", this.platformURL(`/blackbox/runs/${id}/verify`)),
+                /** The run's signed checkpoints and the anchor (an RFC 3161 timestamp over a Merkle root) that fixes them in time. */
+                checkpoints: (id) => this.request("GET", this.platformURL(`/blackbox/runs/${id}/checkpoints`)),
+                /** The run's kept content, opened (all of it, or `refs`); needs the key's content permission and is logged. */
+                content: (id, options = {}) => this.request("POST", this.platformURL(`/blackbox/runs/${id}/content`), options.refs ? { refs: options.refs } : {}, false, { idempotent: true }),
+                export: (id, options = {}) => this.request("GET", this.platformURL(`/blackbox/runs/${id}/export`), undefined, false, { query: { format: options.format ?? "json", content: options.content ? "true" : undefined }, raw: options.format === "zip" }),
+                otlp: (id, options = {}) => this.request("GET", this.platformURL(`/blackbox/runs/${id}/otlp`), undefined, false, { query: { content: options.content ? "true" : undefined } }),
+                simulate: (id, params) => this.request("POST", this.platformURL(`/blackbox/runs/${id}/simulate`), params),
+                /** Erase the run's content, keeping a signed erasure record (the key's manage permission; a running run answers 409). */
+                erase: (id, options = {}) => this.request("POST", this.platformURL(`/blackbox/runs/${id}/erase`), undefined, false, { query: { reason: options.reason }, idempotent: true }),
+                /** Delete the run, leaving a signed deletion record (the key's manage permission); later reads throw RunDeletedError. */
+                delete: (id, options = {}) => this.request("DELETE", this.platformURL(`/blackbox/runs/${id}`), undefined, false, { query: { reason: options.reason } }),
+                /** The run's events live (server-sent events): `event` events (`id` the sequence number, `data` the envelope) from `after`
+                 * on, then `end` ({ status, outcome, events }) or `deleted`, after which it stops. It connects again by itself when asked
+                 * to or when the connection drops, resuming after the last event; `signal` (or leaving the loop) ends it. */
+                stream: (id, options = {}) => this.live(this.platformURL(`/blackbox/runs/${id}/stream`), { after: options.after ?? 0, terminal: ["end", "deleted"], runId: id,
+                    signal: options.signal, maxReconnects: options.maxReconnects }),
+            },
+            bookmarks: {
+                list: (runId) => this.request("GET", this.platformURL(`/blackbox/runs/${runId}/bookmarks`)),
+                /** Mark event `seq` of a run with a note (the key's write permission). */
+                create: (runId, params) => this.request("POST", this.platformURL(`/blackbox/runs/${runId}/bookmarks`), { note: "", ...params }),
+                delete: (bookmarkId) => this.request("DELETE", this.platformURL(`/blackbox/bookmarks/${bookmarkId}`)),
+            },
+            /** What the detection rules noticed in this key's runs (hypotheses with evidence). Call it, or use `list`; `update` triages. */
+            findings: Object.assign((query = {}) => this.findingsList(query), {
+                list: (query = {}) => this.findingsList(query),
+                update: (id, params) => this.request("PATCH", this.platformURL(`/blackbox/findings/${id}`), params, false, { idempotent: true }),
+            }),
+            rules: {
+                /** The detection rules and the account's configuration of them. */
+                list: () => this.request("GET", this.platformURL("/blackbox/rules")),
+                /** What detection would raise with these settings over this key's recent runs; nothing is saved. */
+                preview: (params) => this.request("POST", this.platformURL("/blackbox/rules/preview"), params, false, { idempotent: true }),
+            },
+            /** Where this key's records go as they happen: webhooks (signed; check them with verifyWebhook) and OpenTelemetry
+             * collectors. Needs the key's manage permission; a key sees only its own sinks and runs. */
+            sinks: {
+                list: () => this.request("GET", this.platformURL("/blackbox/sinks")),
+                /** A webhook's `secret` (whsec_...) is in this answer only. */
+                create: (params) => this.request("POST", this.platformURL("/blackbox/sinks"), params),
+                retrieve: (id) => this.request("GET", this.platformURL(`/blackbox/sinks/${id}`)),
+                update: (id, params) => this.request("PATCH", this.platformURL(`/blackbox/sinks/${id}`), params, false, { idempotent: true }),
+                delete: (id) => this.request("DELETE", this.platformURL(`/blackbox/sinks/${id}`)),
+                /** Queue a test message (a ping). */
+                test: (id) => this.request("POST", this.platformURL(`/blackbox/sinks/${id}/test`)),
+                /** A webhook's new secret (in this answer only); the old one stops working. */
+                rotate: (id) => this.request("POST", this.platformURL(`/blackbox/sinks/${id}/rotate`)),
+                deliveries: (id, query = {}) => this.request("GET", this.platformURL(`/blackbox/sinks/${id}/deliveries`), undefined, false, { query }),
+                /** Send a delivery again. */
+                retryDelivery: (deliveryId) => this.request("POST", this.platformURL(`/blackbox/deliveries/${deliveryId}/retry`), undefined, false, { idempotent: true }),
+            },
+            diff: (a, b) => this.request("GET", this.platformURL("/blackbox/diff"), undefined, false, { query: { a, b } }),
+            keys: () => this.request("GET", this.platformURL("/blackbox/keys")),
+            verify: (bundle) => this.request("POST", this.platformURL("/blackbox/verify"), bundle, false, { idempotent: true }),
+            /** This key's runs live (server-sent events): `ready` on each connection, then a `run` event (`data`: the run's summary)
+             * whenever one starts, changes status or grows. It connects again by itself and never ends on its own: leave the loop
+             * or abort `signal`. */
+            watch: (options = {}) => this.live(this.platformURL("/blackbox/runs/stream"), { terminal: [], signal: options.signal, maxReconnects: options.maxReconnects }),
+        };
+        /** Plans (the key's plans switch): a piece of work as Steps that waits for approval and is carried out step by step, the
+         * same engine the Workspace's Plans use. A run with `planMode` proposes one; one with `planId` carries out an approved one
+         * (runs.create). Approval and what may run are checked by the service. A key sees only the plans it made. */
+        this.plans = {
+            /** This key's plans, newest change first (without their history); `after` (a plan id, `last_id`) pages on. */
+            list: (query = {}) => this.request("GET", this.platformURL("/plans"), undefined, false, { query: { ...query } }),
+            /** A plan: mode "plan" (the default) waits for approval; "live" is running from the start. */
+            create: (params) => this.request("POST", this.platformURL("/plans"), params),
+            /** The plan, its steps and progress, and its recent history (`events`). */
+            retrieve: (id) => this.request("GET", this.platformURL(`/plans/${id}`)),
+            /** Revise the plan from `revision`, the one you saw (409 if it moved on since). Steps keeping their key keep their progress;
+             * an approved plan goes back to draft and is approved again before it runs. */
+            update: (id, params) => this.request("PATCH", this.platformURL(`/plans/${id}`), params),
+            /** Approve `revision`, the one you reviewed (409 if it was revised since). A run with `planId` then carries it out. */
+            approve: (id, params) => this.request("POST", this.platformURL(`/plans/${id}/approve`), { revision: params.revision }),
+            /** Cancel the plan: no run carries it out after this. */
+            cancel: (id) => this.request("POST", this.platformURL(`/plans/${id}/cancel`)),
+            /** Move a step by hand. A step with sub-steps follows them (move those); one can't be completed before what it depends on.
+             * Returns the plan. */
+            moveStep: (id, key, params) => this.request("POST", this.platformURL(`/plans/${id}/steps/${key}`), params),
+            /** The plan's changes after event `after`, oldest first. */
+            events: (id, query = {}) => this.request("GET", this.platformURL(`/plans/${id}/events`), undefined, false, { query }),
+            /** The plan live (server-sent events): `plan.snapshot` (the plan as it is) on each connection, then each change from `after`
+             * on (`id` the event's id, `data` the event with `plan` as it is then), and `end` once the plan is completed, cancelled or
+             * failed, after which it stops. It connects again by itself when asked to or when the connection drops, resuming after the
+             * last event (Last-Event-ID); `signal` (or leaving the loop) ends it. */
+            stream: (id, options = {}) => this.live(this.platformURL(`/plans/${id}/events`), { after: options.after ?? 0, terminal: ["end"], signal: options.signal,
+                maxReconnects: options.maxReconnects }),
+        };
         // process.env where it exists (Node, Bun, Deno with compat). Keep the key on a server: never ship it to a browser.
         const env = globalThis.process?.env ?? {};
         this.apiKey = options.apiKey ?? env.DYADIC_API_KEY ?? "";
@@ -296,33 +700,70 @@ export class Dyadic {
         }
         return target.toString();
     }
-    /** Low-level request: JSON (or multipart `options.form`) in; JSON, text, Binary (`options.raw`) or a Stream out. `path` is
-     * relative to the base URL; an absolute URL must be on its origin. GET, HEAD, DELETE and OPTIONS are retried on busy or
-     * failing servers; anything else only if it provably never started, unless `options.idempotent`. */
+    /** Low-level request: JSON (or multipart `options.form`, or raw `options.content`) in; JSON, text, Binary (`options.raw`)
+     * or a Stream out. `path` is relative to the base URL; an absolute URL must be on its origin. GET, HEAD, DELETE and OPTIONS
+     * are retried on busy or failing servers; anything else only if it provably never started, unless `options.idempotent`. */
     async request(method, path, body, stream = false, options = {}) {
+        const { response, controller, release } = await this.open(method, path, body, stream, options);
+        if (stream)
+            return new Stream(response, controller, release);
+        try {
+            const kind = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+            if (!options.raw && (kind === "application/json" || kind.endsWith("+json")))
+                return await response.json();
+            if (!options.raw && kind.startsWith("text/"))
+                return await response.text();
+            return new Binary(await response.arrayBuffer(), kind, response.headers.get("x-request-id") ?? "");
+        }
+        finally {
+            release();
+        }
+    }
+    /** The successful response to a call, after its retries; any other answer throws. A stream's timeout and abort link
+     * stay until `release`. */
+    async open(method, path, body, stream, options) {
         const headers = { Authorization: `Bearer ${this.apiKey}`, Accept: stream ? "text/event-stream" : options.raw ? "*/*" : "application/json" };
-        if (body !== undefined && !options.form)
+        if (USER_AGENT)
+            headers["User-Agent"] = USER_AGENT;
+        Object.assign(headers, currentTraceparent()); // a call's own traceparent (options.headers) replaces it below
+        if (body !== undefined && !options.form && options.content === undefined)
             headers["Content-Type"] = "application/json";
-        const query = Object.entries(options.query ?? {}).filter(([, v]) => v !== undefined).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+        for (const [name, value] of Object.entries(options.headers ?? {})) {
+            if (name.toLowerCase() === "authorization")
+                continue;
+            for (const existing of Object.keys(headers))
+                if (existing.toLowerCase() === name.toLowerCase())
+                    delete headers[existing];
+            headers[name] = value;
+        }
+        const query = queryString(options.query ?? {});
         const target = this.url(path);
         const url = `${target}${query ? `${target.includes("?") ? "&" : "?"}${query}` : ""}`;
-        const payload = options.form ?? (body === undefined ? undefined : JSON.stringify(body));
+        const payload = options.form ?? options.content ?? (body === undefined ? undefined : JSON.stringify(body));
         if (this.appName)
             headers["X-Title"] = this.appName;
         const replayable = Boolean(options.idempotent) || SAFE_METHODS.has(method.toUpperCase());
         if (!replayable || options.idempotencyKey)
             headers["Idempotency-Key"] = options.idempotencyKey ?? newKey();
+        const outer = options.signal;
         for (let attempt = 0;; attempt++) {
+            if (outer?.aborted)
+                throw aborted(outer);
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), this.timeoutMs);
             timer?.unref?.();
+            const onAbort = () => controller.abort(outer?.reason);
+            outer?.addEventListener("abort", onAbort, { once: true });
+            const release = () => { clearTimeout(timer); outer?.removeEventListener("abort", onAbort); };
             let response;
             try {
                 // Never follow a redirect: it would carry the key wherever it points.
                 response = await this.fetcher(url, { method, headers, body: payload, signal: controller.signal, redirect: "manual" });
             }
             catch (error) {
-                clearTimeout(timer);
+                release();
+                if (outer?.aborted)
+                    throw aborted(outer, error);
                 if (attempt < this.maxRetries && (replayable || sentNothing(error))) {
                     await sleep(500 * 2 ** attempt);
                     continue;
@@ -330,22 +771,14 @@ export class Dyadic {
                 throw new DyadicError(`Could not reach the Dyadic API: ${error.message}`);
             }
             if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
-                clearTimeout(timer);
+                release();
                 throw new DyadicError(`The API answered with a redirect (HTTP ${response.status}); not following it with your key.`, { status: response.status });
             }
             if (!stream)
                 clearTimeout(timer);
-            if (response.ok) {
-                if (stream)
-                    return new Stream(response, controller, () => clearTimeout(timer));
-                const kind = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
-                if (!options.raw && (kind === "application/json" || kind.endsWith("+json")))
-                    return await response.json();
-                if (!options.raw && kind.startsWith("text/"))
-                    return await response.text();
-                return new Binary(await response.arrayBuffer(), kind, response.headers.get("x-request-id") ?? "");
-            }
-            clearTimeout(timer);
+            if (response.ok)
+                return { response, controller, release };
+            release();
             const data = await response.json().catch(() => ({ error: { message: `HTTP ${response.status}` } }));
             const error = data?.error ?? {};
             const retry = replayable ? RETRY.has(response.status) : response.status === 429 && ADMISSION_CODES.has(error.code);
@@ -354,12 +787,105 @@ export class Dyadic {
                 await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 30) * 1000 : 500 * 2 ** attempt);
                 continue;
             }
-            throw new DyadicError(error.message ?? `HTTP ${response.status}`, { status: response.status, type: error.type, code: error.code, param: error.param,
+            const Kind = error.code === "run_deleted" ? RunDeletedError : DyadicError;
+            throw new Kind(error.message ?? `HTTP ${response.status}`, { status: response.status, type: error.type, code: error.code, param: error.param,
                 requestId: response.headers.get("x-request-id") ?? "", body: data });
         }
     }
+    /** A Black Box live stream: server-sent events as `{ event, id, data }`, connecting again when the service asks
+     * (`reconnect`) or the connection drops (resuming after the last event when `after` is given), until a `terminal` event,
+     * the signal aborts, or the consumer stops iterating. */
+    async *live(path, options) {
+        const resume = options.after !== undefined;
+        let after = Math.max(0, Math.trunc(options.after ?? 0)), failures = 0, connected = false;
+        const maxReconnects = Math.max(0, options.maxReconnects ?? 10), signal = options.signal;
+        const backoff = (n) => pause(Math.min(500 * 2 ** n, 8000) + Math.random() * 250, signal);
+        while (!signal?.aborted) {
+            let opened;
+            try {
+                opened = await this.open("GET", path, undefined, true, { signal, query: resume ? { after } : {},
+                    headers: { "Cache-Control": "no-cache", ...(resume && after ? { "Last-Event-ID": String(after) } : {}) } });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                if (connected && error instanceof RunDeletedError) {
+                    yield { event: "deleted", id: null, data: { run_id: options.runId ?? "", deletion: error.deletion } };
+                    return;
+                }
+                const status = error instanceof DyadicError ? error.status : -1;
+                if (connected && failures < maxReconnects && (status === 0 || status >= 500 || status === 408 || status === 429)) {
+                    failures++;
+                    await backoff(failures - 1);
+                    continue;
+                }
+                throw error;
+            }
+            connected = true;
+            // A stream outlives a request's timeout: the service's keep-alives (every 15 s) show it is alive instead.
+            opened.release();
+            const reader = opened.response.body.getReader();
+            let again = false, idle = null;
+            const watch = () => { clearTimeout(idle); idle = setTimeout(() => opened.controller.abort(), LIVE_IDLE_MS); idle?.unref?.(); };
+            const onAbort = () => opened.controller.abort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+            try {
+                watch();
+                for await (const [name, id, data] of sseFrames(reader, watch)) {
+                    failures = 0;
+                    let value = data;
+                    try {
+                        value = data ? JSON.parse(data) : null;
+                    }
+                    catch { /* not JSON: the text as it came */ }
+                    if (name === "reconnect") {
+                        if (resume && Number.isInteger(value?.after))
+                            after = Math.max(after, value.after);
+                        again = true;
+                        break;
+                    }
+                    if (resume && id !== null && /^\d+$/.test(id))
+                        after = Number(id);
+                    yield { event: name, id, data: value };
+                    if (options.terminal.includes(name))
+                        return;
+                }
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                // The connection dropped: connect again below.
+            }
+            finally {
+                clearTimeout(idle);
+                signal?.removeEventListener("abort", onAbort);
+                await reader.cancel().catch(() => { });
+                opened.controller.abort();
+            }
+            if (signal?.aborted)
+                return;
+            if (!again) {
+                failures++;
+                if (failures > maxReconnects)
+                    throw new DyadicError(`The event stream dropped ${failures} times in a row; giving up.`);
+                await backoff(failures - 1);
+            }
+        }
+    }
     /** Dyadic's own endpoints sit beside the OpenAI-compatible base: .../api/openai/v1 -> .../api/v1. */
     platformURL(path) { return this.baseURL.replace(/\/openai(\/v1)?$/, "/v1") + path; }
+    /** So do its other compatible APIs: .../api/openai/v1 -> .../api/anthropic/v1 or .../api/openrouter/v1. */
+    apiURL(api, path) { return this.baseURL.replace(/\/openai(\/v1)?$/, `/${api}/v1`) + path; }
+    anthropicCall(method, path, body, stream = false, options = {}) {
+        return this.request(method, this.apiURL("anthropic", path), body, stream, { ...options, headers: { "anthropic-version": ANTHROPIC_VERSION, ...options.headers } });
+    }
+    /** A run's body as the API names its fields (planMode and planId as plan_mode and plan_id). */
+    runBody(params) {
+        const { planMode, planId, ...rest } = params;
+        return { ...rest, ...(planMode !== undefined ? { plan_mode: planMode } : {}), ...(planId !== undefined ? { plan_id: planId } : {}) };
+    }
     /** One question, one answer: the reply's text. */
     async ask(prompt, options = {}) {
         const { model = "iris", system, ...params } = options;
@@ -367,7 +893,12 @@ export class Dyadic {
         const reply = await this.chat.completions.create({ ...params, model, messages, stream: false });
         return reply.choices[0]?.message.content ?? "";
     }
+    findingsList(query) {
+        return this.request("GET", this.platformURL("/blackbox/findings"), undefined, false, { query: { ...query } });
+    }
     /** The API's OpenAPI description. */
     openapi() { return this.request("GET", "/openapi.json"); }
 }
 export default Dyadic;
+export * from "./blackbox.js";
+export * from "./otel.js";