dyadic 1.3.1 → 1.7.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export declare const VERSION = "1.3.1";
+export declare const VERSION = "1.7.0";
 export declare 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 declare const ANTHROPIC_VERSION = "2023-06-01";
 export type Model = "iris" | "iris-think" | (string & {});
 export type Role = "system" | "developer" | "user" | "assistant" | "tool";
 export type ContentPart = {
@@ -192,6 +194,11 @@ export interface ResponseParams {
     instructions?: string;
     previous_response_id?: string;
     store?: boolean;
+    /** Continue a conversation (conversations.create): this response's input and output are added to it. */
+    conversation?: string | {
+        id: string;
+    };
+    background?: boolean;
     tools?: Record<string, unknown>[];
     tool_choice?: unknown;
     parallel_tool_calls?: boolean;
@@ -400,8 +407,9 @@ export interface Batch {
     expires_at: number | null;
     metadata: Record<string, string>;
 }
-/** Dyadic's built-in tools an application's run may use. */
-export type BuiltinTool = "data.web_search" | "data.web_fetch" | "image.generate" | "vision.describe_image";
+/** Dyadic's built-in tools an application's run may use (the audio tools need the key's audio switch, the plan tools its
+ * plans switch; a run with planMode or planId has the plan tools anyway). */
+export type BuiltinTool = "data.web_search" | "data.web_fetch" | "image.generate" | "vision.describe_image" | "audio.speak" | "audio.transcribe" | "plans.propose" | "plans.step" | "plans.get";
 /** Your own agent, sent with the run: its name and instructions, optional
  * behaviour overrides (tool_rules, safety, style, citations, research: text to
  * replace the default, or false to turn it off) and model choices. */
@@ -429,6 +437,15 @@ export interface RunParams {
     max_cost_usd?: number;
     /** Ask for up to four suggested follow-up questions (`followups` on the completed run). */
     followups?: boolean;
+    /** Plan Mode (the key's plans switch): investigate read-only and propose a plan for approval; nothing that changes anything
+     * runs. Sent as `plan_mode`. */
+    planMode?: boolean;
+    /** Carry out this plan of the key's, picking up where it left off; refused with `plan_not_runnable` unless a Plan Mode plan
+     * is approved at its current revision. Sent as `plan_id`. */
+    planId?: string;
+    /** As the API names them (the same as planMode and planId). */
+    plan_mode?: boolean;
+    plan_id?: string;
 }
 export interface Run {
     object: "run";
@@ -460,11 +477,114 @@ export interface Run {
     seconds: number;
     log_id?: string;
     followups?: string[];
+    /** The plans this run made or moved, as it left them (only when it touched any). */
+    plans?: {
+        id: string;
+        title: string;
+        status: PlanStatus;
+        revision: number;
+    }[];
 }
+/** A streamed run's events; `plan.updated` carries a plan the run made or moved (`plan`). */
 export interface RunEvent {
     type: string;
+    plan?: Plan;
     [key: string]: unknown;
 }
+export type PlanStatus = "draft" | "approved" | "running" | "paused" | "completed" | "failed" | "cancelled";
+export type PlanStepStatus = "pending" | "in_progress" | "completed" | "failed" | "blocked" | "skipped";
+/** A step as you write it: its title alone (numbered in order), or with its key (1, 2, or 2.1 inside 2), how it will be done
+ * and checked, and the keys it waits for. */
+export type PlanStepInput = string | {
+    key?: string;
+    title: string;
+    detail?: string;
+    depends_on?: string[] | string;
+};
+export interface PlanStep {
+    key: string;
+    parent: string;
+    title: string;
+    detail: string;
+    status: PlanStepStatus;
+    depends_on: string[];
+    /** How completion was checked (a run must say it). */
+    verified_by: string;
+    note: string;
+    evidence: Record<string, unknown>[];
+    started_at: string | null;
+    finished_at: string | null;
+    updated_at: string | null;
+}
+export interface PlanEvent {
+    id: number;
+    object: "plan.event";
+    plan_id: string;
+    kind: "created" | "revised" | "edited" | "approved" | "started" | "resumed" | "step" | "interrupted" | "completed" | "cancelled";
+    type: string;
+    step: string | null;
+    status: string | null;
+    detail: Record<string, unknown>;
+    /** iris (an agent in a run), owner (the Workspace) or application (an API key). */
+    actor: string;
+    operation_id: string | null;
+    at: string;
+}
+/** A plan: work as Steps that waits for approval (origin "plan") or runs as the work goes (origin "live"). */
+export interface Plan {
+    id: string;
+    object: "plan";
+    chat_id: string | null;
+    api_key_id: string | null;
+    conversation: string;
+    metadata: Record<string, string>;
+    title: string;
+    summary: string;
+    origin: "plan" | "live";
+    status: PlanStatus;
+    revision: number;
+    approved_revision: number | null;
+    approved_at: string | null;
+    created_at: string;
+    updated_at: string;
+    /** Over the steps with no sub-steps. */
+    progress: {
+        done: number;
+        total: number;
+        percent: number;
+        failed: number;
+        blocked: number;
+    };
+    steps: PlanStep[];
+    /** Its recent history, oldest first (not in lists). */
+    events?: PlanEvent[];
+}
+export interface PlanCreateParams {
+    title: string;
+    steps: PlanStepInput[];
+    summary?: string;
+    /** "plan" (the default) waits for approval; "live" is running from the start. */
+    mode?: "plan" | "live";
+    /** Your conversation it belongs to (a run's conversation_id). */
+    conversation?: string;
+    metadata?: Record<string, string>;
+}
+export interface PlanUpdateParams {
+    revision: number;
+    title?: string;
+    summary?: string;
+    steps?: PlanStepInput[];
+    metadata?: Record<string, string>;
+}
+export interface PlanListQuery {
+    conversation?: string;
+    status?: PlanStatus;
+    limit?: number;
+    after?: string;
+}
+/** One event of a plan's live stream: `plan.snapshot` (data: the Plan), `plan.<kind>` (data: the PlanEvent with `plan`, the
+ * plan as it is then) or `end` (data: { plan_id, status, last_id }). */
+export type PlanStreamEvent = BlackBoxStreamEvent<any>;
 /** A function your application runs: its schema and the handler called with the parsed arguments. */
 export interface FunctionHandler {
     description?: string;
@@ -510,15 +630,273 @@ export interface WorkspaceSave {
 }
 /** `idempotent`: the call is safe to send twice, so it is retried like a GET. `idempotencyKey`: the Idempotency-Key every
  * attempt of this call carries (one is made for anything but GET, HEAD, DELETE and OPTIONS). `executes` is accepted for
- * compatibility; it is now the rule for every POST. */
+ * compatibility; it is now the rule for every POST. `headers` are sent too (never in place of the key); `content` is sent
+ * as the body as it is (give its Content-Type in `headers`); `signal` aborts the call (and a stream's reading). A query
+ * value that is an array is sent once per item. */
 export interface RequestOptions {
     form?: FormData;
-    query?: Record<string, string | number | undefined>;
+    query?: Record<string, QueryValue>;
     raw?: boolean;
     executes?: boolean;
     idempotent?: boolean;
     idempotencyKey?: string;
+    headers?: Record<string, string>;
+    content?: Uint8Array | ArrayBuffer | Blob | string;
+    signal?: AbortSignal;
+}
+export type QueryValue = string | number | boolean | undefined | null | (string | number)[];
+/** The Anthropic API's request: its own fields (system, tools, tool_choice, thinking, cache_control, ...) pass through. */
+export interface AnthropicMessageParams {
+    model: string;
+    max_tokens: number;
+    messages: {
+        role: "user" | "assistant";
+        content: string | Record<string, unknown>[];
+    }[];
+    system?: string | Record<string, unknown>[];
+    tools?: Record<string, unknown>[];
+    tool_choice?: Record<string, unknown>;
+    thinking?: Record<string, unknown>;
+    stop_sequences?: string[];
+    metadata?: {
+        user_id?: string;
+    };
+    stream?: boolean;
+    [key: string]: unknown;
+}
+export interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+    server_tool_use?: Record<string, number> | null;
+    [key: string]: unknown;
+}
+export interface AnthropicMessage {
+    id: string;
+    type: "message";
+    role: "assistant";
+    model: string;
+    content: {
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }[];
+    stop_reason: string | null;
+    stop_sequence: string | null;
+    usage: AnthropicUsage;
+    [key: string]: unknown;
+}
+/** One event of a streamed message: message_start, content_block_start, content_block_delta, ..., message_stop, ping. */
+export interface AnthropicStreamEvent {
+    type: string;
+    index?: number;
+    delta?: Record<string, any>;
+    [key: string]: any;
+}
+export interface AnthropicPage<T> {
+    data: T[];
+    has_more: boolean;
+    first_id: string | null;
+    last_id: string | null;
+}
+export interface AnthropicBatch {
+    id: string;
+    type: "message_batch";
+    processing_status: "in_progress" | "canceling" | "ended";
+    request_counts: {
+        processing: number;
+        succeeded: number;
+        errored: number;
+        canceled: number;
+        expired: number;
+    };
+    created_at: string;
+    ended_at: string | null;
+    expires_at: string;
+    cancel_initiated_at: string | null;
+    results_url: string | null;
+    [key: string]: unknown;
+}
+export interface AnthropicBatchResult {
+    custom_id: string;
+    result: {
+        type: "succeeded";
+        message: AnthropicMessage;
+    } | {
+        type: "errored";
+        error: Record<string, unknown>;
+    } | {
+        type: "canceled";
+    } | {
+        type: "expired";
+    };
+}
+export interface AnthropicFile {
+    id: string;
+    type: "file";
+    filename: string;
+    mime_type: string;
+    size_bytes: number;
+    created_at: string;
+    downloadable?: boolean;
+}
+export interface AnthropicModel {
+    id: string;
+    type: "model";
+    display_name: string;
+    created_at: string;
+    [key: string]: unknown;
+}
+/** OpenRouter's request, unchanged: its model ids ("anthropic/claude-haiku-5.5") and fields (models, provider, reasoning, plugins). */
+export interface OpenRouterChatParams {
+    model: string;
+    messages: Record<string, unknown>[];
+    stream?: boolean;
+    [key: string]: unknown;
+}
+/** /key, answered by Dyadic: this key's usage and limits in dollars. */
+export interface OpenRouterKeyInfo {
+    data: {
+        label: string;
+        usage: number;
+        limit: number | null;
+        limit_remaining: number | null;
+        limit_reset: "daily" | "weekly" | "monthly" | null;
+        is_free_tier: false;
+        is_provisioning_key: false;
+        rate_limit: {
+            requests: number;
+            interval: "1m";
+        };
+    };
+}
+/** /credits, answered by Dyadic: the account's allowance this week (null when unlimited) and what's used, in dollars. */
+export interface OpenRouterCredits {
+    data: {
+        total_credits: number | null;
+        total_usage: number;
+    };
+}
+export interface Deleted {
+    id: string;
+    object: string;
+    deleted: boolean;
+}
+/** Completions created with store: true, kept 30 days. */
+export interface StoredChatCompletion extends ChatCompletion {
+    metadata?: Record<string, string> | null;
+    request_id?: string;
+    [key: string]: unknown;
+}
+export interface Conversation {
+    id: string;
+    object: "conversation";
+    created_at: number;
+    metadata: Record<string, string> | null;
+}
+export interface ConversationItem {
+    id?: string;
+    type: string;
+    [key: string]: unknown;
+}
+export interface Container {
+    id: string;
+    object: "container";
+    name: string;
+    status: string;
+    created_at: number;
+    last_active_at: number;
+    expires_after: {
+        anchor: "last_active_at";
+        minutes: number;
+    };
+    memory_limit?: string | null;
+}
+export interface ContainerFile {
+    id: string;
+    object: "container.file";
+    container_id: string;
+    path: string;
+    bytes: number;
+    created_at: number;
+    source: string;
+}
+export interface VectorStore {
+    id: string;
+    object: "vector_store";
+    name: string;
+    status: "expired" | "in_progress" | "completed";
+    created_at: number;
+    usage_bytes: number;
+    file_counts: {
+        in_progress: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+        total: number;
+    };
+    expires_after: {
+        anchor: "last_active_at";
+        days: number;
+    } | null;
+    expires_at: number | null;
+    last_active_at: number;
+    metadata: Record<string, string>;
 }
+export interface VectorStoreFile {
+    id: string;
+    object: "vector_store.file";
+    vector_store_id: string;
+    status: "in_progress" | "completed" | "failed" | "cancelled";
+    usage_bytes: number;
+    created_at: number;
+    last_error: {
+        code: string;
+        message: string;
+    } | null;
+    attributes: Record<string, string | number | boolean>;
+    chunking_strategy: Record<string, unknown>;
+    filename?: string;
+}
+export interface VectorStoreSearchPage {
+    object: "vector_store.search_results.page";
+    search_query: string;
+    has_more: boolean;
+    next_page: string | null;
+    data: {
+        file_id: string;
+        filename: string;
+        score: number;
+        attributes?: Record<string, unknown>;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }[];
+}
+export interface Skill {
+    id: string;
+    object: "skill";
+    name: string;
+    description: string;
+    created_at: number;
+    default_version: string;
+    latest_version: string;
+}
+export interface SkillVersion {
+    id: string;
+    object: "skill.version";
+    skill_id: string;
+    version: string;
+    name: string;
+    description: string;
+    created_at: number;
+    bytes: number;
+    files: string[];
+}
+/** A file in a skill: its path in the skill as the name (or one zip). */
+export type SkillFile = Uploadable;
 /** Bytes from the API (speech audio, file downloads). */
 export declare class Binary {
     readonly data: ArrayBuffer;
@@ -555,13 +933,25 @@ export declare class DyadicError extends Error {
         body?: unknown;
     });
 }
+/** 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 declare class RunDeletedError extends DyadicError {
+    constructor(message: string, init?: ConstructorParameters<typeof DyadicError>[1]);
+    get deletion(): Record<string, unknown> | null;
+}
+/** One server-sent event of a Black Box live stream. */
+export interface BlackBoxStreamEvent<T = any> {
+    event: string;
+    id: string | null;
+    data: T;
+}
 /** A streamed completion: `for await (const chunk of stream)`. `text` and `usage` fill in as it goes. */
-export declare class Stream<T> implements AsyncIterable<T> {
+export declare class Stream<T, U = Usage> implements AsyncIterable<T> {
     private http;
     readonly controller: AbortController;
     private onDone;
     text: string;
-    usage: Usage | undefined;
+    usage: U | undefined;
     /** Responses streams: the final Response once response.completed arrives. */
     response: ResponseObject | undefined;
     /** Run streams: the completed run once run.completed arrives. */
@@ -573,6 +963,10 @@ export declare class Stream<T> implements AsyncIterable<T> {
     finalText(): Promise<string>;
     abort(): void;
 }
+/** Start (or join, given a 32-hex trace id) the trace the following requests carry; returns its id. */
+export declare function useTrace(traceId?: string): string;
+/** The current trace's traceparent header (a new span each call), or {} when none was started. */
+export declare function currentTraceparent(): Record<string, string>;
 export declare class Dyadic {
     readonly apiKey: string;
     readonly baseURL: string;
@@ -587,15 +981,28 @@ export declare class Dyadic {
      * origin. The key goes with every request, so it must never reach another host, a plain-http downgrade, or a URL with
      * credentials in it. */
     private url;
-    /** 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`. */
     request<T>(method: string, path: string, body?: unknown, stream?: boolean, options?: RequestOptions): Promise<T>;
+    /** The successful response to a call, after its retries; any other answer throws. A stream's timeout and abort link
+     * stay until `release`. */
+    private open;
+    /** 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. */
+    private live;
     /** Dyadic's own endpoints sit beside the OpenAI-compatible base: .../api/openai/v1 -> .../api/v1. */
     platformURL(path: string): string;
+    /** So do its other compatible APIs: .../api/openai/v1 -> .../api/anthropic/v1 or .../api/openrouter/v1. */
+    private apiURL;
+    private anthropicCall;
+    /** A run's body as the API names its fields (planMode and planId as plan_mode and plan_id). */
+    private runBody;
     /** 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. */
     readonly runs: {
         create: {
             (params: RunParams & {
@@ -630,6 +1037,27 @@ export declare class Dyadic {
                 }): Promise<ChatCompletion>;
                 (params: ChatCompletionParams): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
             };
+            /** Completions created with store: true (kept 30 days), newest first; `metadata` matches key/values. */
+            list: (query?: {
+                model?: string;
+                metadata?: Record<string, string>;
+                after?: string;
+                limit?: number;
+                order?: "asc" | "desc";
+            }) => Promise<Page<StoredChatCompletion>>;
+            retrieve: (id: string) => Promise<StoredChatCompletion>;
+            /** Replace a stored completion's metadata. */
+            update: (id: string, params: {
+                metadata: Record<string, string> | null;
+            }) => Promise<StoredChatCompletion>;
+            delete: (id: string) => Promise<Deleted>;
+            messages: {
+                list: (id: string, query?: {
+                    after?: string;
+                    limit?: number;
+                    order?: "asc" | "desc";
+                }) => Promise<Page<Record<string, unknown>>>;
+            };
         };
     };
     readonly completions: {
@@ -663,6 +1091,60 @@ export declare class Dyadic {
             order?: "asc" | "desc";
         }) => Promise<Page<Record<string, unknown>>>;
         cancel: (id: string) => Promise<ResponseObject>;
+        /** How many input tokens a Responses request would use: an estimate, free (no model runs). */
+        inputTokens: {
+            count: (params: Omit<ResponseParams, "stream" | "store" | "background">) => Promise<{
+                object: "response.input_tokens";
+                input_tokens: number;
+            }>;
+        };
+        /** Your user messages and one compaction item summarising everything else; send its output as the next request's input. */
+        compact: (params: {
+            model: Model;
+            input?: string | Record<string, unknown>[];
+            instructions?: string;
+            previous_response_id?: string;
+        }) => Promise<{
+            [key: string]: unknown;
+            id: string;
+            object: "response.compaction";
+            output: Record<string, unknown>[];
+            usage?: Record<string, unknown>;
+        }>;
+    };
+    /** Conversations for the Responses API: pass `conversation` to responses.create and each response's input and output
+     * are added to it. */
+    readonly conversations: {
+        create: (params?: {
+            items?: Record<string, unknown>[];
+            metadata?: Record<string, string>;
+        }) => Promise<Conversation>;
+        retrieve: (id: string) => Promise<Conversation>;
+        update: (id: string, params: {
+            metadata: Record<string, string> | null;
+        }) => Promise<Conversation>;
+        /** Deletes the conversation and its items. */
+        delete: (id: string) => Promise<Deleted>;
+        items: {
+            create: (conversationId: string, params: {
+                items: Record<string, unknown>[];
+                include?: string[];
+            }) => Promise<Page<ConversationItem>>;
+            list: (conversationId: string, query?: {
+                after?: string;
+                limit?: number;
+                order?: "asc" | "desc";
+                include?: string[];
+            }) => Promise<Page<ConversationItem>>;
+            retrieve: (itemId: string, params: {
+                conversation_id: string;
+                include?: string[];
+            }) => Promise<ConversationItem>;
+            /** Removes the item; answers with the conversation. */
+            delete: (itemId: string, params: {
+                conversation_id: string;
+            }) => Promise<Conversation>;
+        };
     };
     readonly embeddings: {
         create: (params: EmbeddingParams) => Promise<EmbeddingList>;
@@ -737,6 +1219,311 @@ export declare class Dyadic {
         retrieve: (id: string) => Promise<Batch>;
         cancel: (id: string) => Promise<Batch>;
     };
+    /** Containers (cntr_...) for the code interpreter and shell tools; needs the key's code interpreter switch. */
+    readonly containers: {
+        create: (params?: {
+            name?: string;
+            expires_after?: {
+                anchor: "last_active_at";
+                minutes: number;
+            };
+            memory_limit?: string;
+            file_ids?: string[];
+            skills?: Record<string, unknown>[];
+        }) => Promise<Container>;
+        list: (query?: {
+            after?: string;
+            limit?: number;
+            order?: "asc" | "desc";
+        }) => Promise<Page<Container>>;
+        retrieve: (id: string) => Promise<Container>;
+        delete: (id: string) => Promise<Deleted>;
+        files: {
+            /** Put a file in the container (at /mnt/data/<name>): upload `file`, or copy an uploaded `file_id`. */
+            create: (containerId: string, params: {
+                file?: Uploadable;
+                file_id?: string;
+            }) => Promise<ContainerFile>;
+            list: (containerId: string, query?: {
+                after?: string;
+                limit?: number;
+                order?: "asc" | "desc";
+            }) => Promise<Page<ContainerFile>>;
+            retrieve: (fileId: string, params: {
+                container_id: string;
+            }) => Promise<ContainerFile>;
+            delete: (fileId: string, params: {
+                container_id: string;
+            }) => Promise<Deleted>;
+            content: {
+                retrieve: (fileId: string, params: {
+                    container_id: string;
+                }) => Promise<Binary>;
+            };
+        };
+    };
+    /** 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. */
+    readonly vectorStores: {
+        create: (params?: {
+            name?: string;
+            file_ids?: string[];
+            chunking_strategy?: Record<string, unknown>;
+            metadata?: Record<string, string>;
+            expires_after?: {
+                anchor: "last_active_at";
+                days: number;
+            };
+        }) => Promise<VectorStore>;
+        list: (query?: {
+            after?: string;
+            limit?: number;
+            order?: "asc" | "desc";
+        }) => Promise<Page<VectorStore>>;
+        retrieve: (id: string) => Promise<VectorStore>;
+        update: (id: string, params: {
+            name?: string;
+            metadata?: Record<string, string> | null;
+            expires_after?: {
+                anchor: "last_active_at";
+                days: number;
+            } | null;
+        }) => Promise<VectorStore>;
+        delete: (id: string) => Promise<Deleted>;
+        search: (id: string, params: {
+            query: string | string[];
+            max_num_results?: number;
+            filters?: Record<string, unknown>;
+            ranking_options?: Record<string, unknown>;
+            rewrite_query?: boolean;
+        }) => Promise<VectorStoreSearchPage>;
+        files: {
+            /** Add an uploaded file; it is read and indexed in the background. */
+            create: (vectorStoreId: string, params: {
+                file_id: string;
+                attributes?: Record<string, string | number | boolean>;
+                chunking_strategy?: Record<string, unknown>;
+            }) => Promise<VectorStoreFile>;
+            list: (vectorStoreId: string, query?: {
+                after?: string;
+                limit?: number;
+                order?: "asc" | "desc";
+                filter?: "in_progress" | "completed" | "failed" | "cancelled";
+            }) => Promise<Page<VectorStoreFile>>;
+            retrieve: (fileId: string, params: {
+                vector_store_id: string;
+            }) => Promise<VectorStoreFile>;
+            update: (fileId: string, params: {
+                vector_store_id: string;
+                attributes: Record<string, string | number | boolean> | null;
+            }) => Promise<VectorStoreFile>;
+            delete: (fileId: string, params: {
+                vector_store_id: string;
+            }) => Promise<Deleted>;
+            /** The file's parsed text, as indexed. */
+            content: (fileId: string, params: {
+                vector_store_id: string;
+            }) => Promise<{
+                [key: string]: unknown;
+                object: string;
+                data: {
+                    type: "text";
+                    text: string;
+                }[];
+            }>;
+        };
+        fileBatches: {
+            create: (vectorStoreId: string, params: {
+                file_ids?: string[];
+                files?: Record<string, unknown>[];
+                attributes?: Record<string, unknown>;
+                chunking_strategy?: Record<string, unknown>;
+            }) => Promise<Record<string, unknown>>;
+            retrieve: (batchId: string, params: {
+                vector_store_id: string;
+            }) => Promise<Record<string, unknown>>;
+            cancel: (batchId: string, params: {
+                vector_store_id: string;
+            }) => Promise<Record<string, unknown>>;
+            listFiles: (batchId: string, params: {
+                vector_store_id: string;
+                after?: string;
+                limit?: number;
+                order?: "asc" | "desc";
+                filter?: string;
+            }) => Promise<Page<VectorStoreFile>>;
+        };
+    };
+    /** 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. */
+    readonly skills: {
+        create: (params: {
+            files: SkillFile | SkillFile[];
+        }) => Promise<Skill>;
+        list: (query?: {
+            after?: string;
+            limit?: number;
+            order?: "asc" | "desc";
+        }) => Promise<Page<Skill>>;
+        retrieve: (id: string) => Promise<Skill>;
+        /** Choose the default version. */
+        update: (id: string, params: {
+            default_version: string | number;
+        }) => Promise<Skill>;
+        delete: (id: string) => Promise<Deleted>;
+        /** The default version's files as a zip. */
+        content: {
+            retrieve: (id: string) => Promise<Binary>;
+        };
+        versions: {
+            create: (skillId: string, params: {
+                files: SkillFile | SkillFile[];
+                default?: boolean;
+            }) => Promise<SkillVersion>;
+            list: (skillId: string, query?: {
+                after?: string;
+                limit?: number;
+                order?: "asc" | "desc";
+            }) => Promise<Page<SkillVersion>>;
+            retrieve: (version: string | number, params: {
+                skill_id: string;
+            }) => Promise<SkillVersion>;
+            delete: (version: string | number, params: {
+                skill_id: string;
+            }) => Promise<Deleted>;
+            content: {
+                retrieve: (version: string | number, params: {
+                    skill_id: string;
+                }) => Promise<Binary>;
+            };
+        };
+    };
+    /** 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). */
+    readonly anthropic: {
+        messages: {
+            /** A message, or with `stream: true` Anthropic's events; the stream's `text` and `usage` fill in as they come. */
+            create: {
+                (params: AnthropicMessageParams & {
+                    stream: true;
+                }): Promise<Stream<AnthropicStreamEvent, AnthropicUsage>>;
+                (params: AnthropicMessageParams & {
+                    stream?: false;
+                }): Promise<AnthropicMessage>;
+            };
+            /** A request's input tokens (free; no model runs). */
+            countTokens: (params: Omit<AnthropicMessageParams, "max_tokens" | "stream">) => Promise<{
+                input_tokens: number;
+            }>;
+            /** Up to 100,000 requests at half price; poll `retrieve` until processing_status is "ended", then read `results`. */
+            batches: {
+                create: (params: {
+                    requests: {
+                        custom_id: string;
+                        params: AnthropicMessageParams;
+                    }[];
+                }) => Promise<AnthropicBatch>;
+                list: (query?: {
+                    limit?: number;
+                    before_id?: string;
+                    after_id?: string;
+                }) => Promise<AnthropicPage<AnthropicBatch>>;
+                retrieve: (id: string) => Promise<AnthropicBatch>;
+                cancel: (id: string) => Promise<AnthropicBatch>;
+                /** Each request's result once the batch has ended, in order. */
+                results: (id: string) => Promise<AnthropicBatchResult[]>;
+                delete: (id: string) => Promise<{
+                    id: string;
+                    type: "message_batch_deleted";
+                }>;
+            };
+        };
+        /** The Claude models this key may call. */
+        models: {
+            list: (query?: {
+                limit?: number;
+                before_id?: string;
+                after_id?: string;
+            }) => Promise<AnthropicPage<AnthropicModel>>;
+            retrieve: (id: string) => Promise<AnthropicModel>;
+        };
+        /** Files to reference from a message ({ type: "document", source: { type: "file", file_id } }). */
+        files: {
+            create: (params: {
+                file: Uploadable;
+            }) => Promise<AnthropicFile>;
+            list: (query?: {
+                limit?: number;
+                before_id?: string;
+                after_id?: string;
+            }) => Promise<AnthropicPage<AnthropicFile>>;
+            retrieve: (id: string) => Promise<AnthropicFile>;
+            content: (id: string) => Promise<Binary>;
+            delete: (id: string) => Promise<{
+                id: string;
+                type: "file_deleted";
+            }>;
+        };
+    };
+    /** 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. */
+    readonly openrouter: {
+        chat: {
+            completions: {
+                create: {
+                    (params: OpenRouterChatParams & {
+                        stream: true;
+                    }): Promise<Stream<ChatCompletionChunk>>;
+                    (params: OpenRouterChatParams & {
+                        stream?: false;
+                    }): Promise<ChatCompletion & Record<string, unknown>>;
+                };
+            };
+        };
+        completions: {
+            create: {
+                (params: {
+                    model: string;
+                    prompt: string;
+                    stream: true;
+                    [key: string]: unknown;
+                }): Promise<Stream<TextCompletion>>;
+                (params: {
+                    model: string;
+                    prompt: string;
+                    stream?: false;
+                    [key: string]: unknown;
+                }): Promise<TextCompletion>;
+            };
+        };
+        /** Embeddings (the key's Embeddings switch). */
+        embeddings: {
+            create: (params: {
+                model: string;
+                input: string | string[];
+                [key: string]: unknown;
+            }) => Promise<EmbeddingList>;
+        };
+        models: {
+            list: (query?: Record<string, QueryValue>) => Promise<{
+                data: Record<string, unknown>[];
+            }>;
+            /** A model's providers and their prices. */
+            endpoints: (author: string, slug: string) => Promise<{
+                data: Record<string, unknown>;
+            }>;
+        };
+        /** A generation's cost and tokens (this key's own requests only). */
+        generation: (id: string) => Promise<{
+            data: Record<string, unknown>;
+        }>;
+        /** This Dyadic key's usage and limits, as OpenRouter's /key answers (answered by Dyadic). */
+        key: () => Promise<OpenRouterKeyInfo>;
+        /** The account's allowance and use this week, in dollars (answered by Dyadic). */
+        credits: () => Promise<OpenRouterCredits>;
+    };
     /** Connected apps. Show the person `authorize_url` when `authorized` is false. */
     readonly connections: {
         discord: (discordId: string | number) => Promise<Connection>;
@@ -749,12 +1536,309 @@ export declare class Dyadic {
             create: ({ discord_id, ...fields }: WorkspaceSaveParams) => Promise<WorkspaceSave>;
         };
     };
+    /** 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). */
+    readonly blackbox: {
+        send: (batch: Record<string, unknown>, options?: {
+            idempotencyKey?: string;
+        }) => Promise<BlackBoxBatchResult>;
+        /** 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: Record<string, unknown> | Uint8Array | ArrayBuffer) => Promise<Record<string, unknown>> | Promise<Binary>;
+        /** Counts for this key's runs: by status and outcome, open findings, recording gaps. */
+        overview: () => Promise<Record<string, unknown>>;
+        /** What the account keeps (recording, capture by kind) and for how long. */
+        settings: () => Promise<Record<string, unknown>>;
+        runs: {
+            list: (query?: Record<string, string | number | undefined>) => Promise<{
+                runs: BlackBoxRunSummary[];
+                next: string | null;
+            }>;
+            retrieve: (id: string) => Promise<BlackBoxRunSummary>;
+            /** The run's events in chain order; `types` keeps only those types (up to 20). */
+            events: (id: string, query?: {
+                after?: number;
+                limit?: number;
+                types?: string[] | string;
+            }) => Promise<{
+                run_id: string;
+                events: Record<string, unknown>[];
+                has_more: boolean;
+            }>;
+            graph: (id: string) => Promise<Record<string, unknown>>;
+            verify: (id: string) => Promise<VerifyReport>;
+            /** The run's signed checkpoints and the anchor (an RFC 3161 timestamp over a Merkle root) that fixes them in time. */
+            checkpoints: (id: string) => Promise<{
+                run_id: string;
+                tenant: string;
+                checkpoints: Record<string, unknown>[];
+                anchors: Record<string, unknown>[];
+            }>;
+            /** The run's kept content, opened (all of it, or `refs`); needs the key's content permission and is logged. */
+            content: (id: string, options?: {
+                refs?: string[];
+            }) => Promise<{
+                run_id: string;
+                content: {
+                    ref: string;
+                    kind: string;
+                    value: unknown;
+                }[];
+                erased: boolean;
+            }>;
+            export: (id: string, options?: {
+                format?: "json" | "zip";
+                content?: boolean;
+            }) => Promise<Record<string, unknown> | Binary>;
+            otlp: (id: string, options?: {
+                content?: boolean;
+            }) => Promise<Record<string, unknown>>;
+            simulate: (id: string, params: {
+                mode: "reconstruct" | "simulate" | "counterfactual";
+                [key: string]: unknown;
+            }) => Promise<Record<string, unknown>>;
+            /** Erase the run's content, keeping a signed erasure record (the key's manage permission; a running run answers 409). */
+            erase: (id: string, options?: {
+                reason?: string;
+            }) => Promise<Record<string, unknown>>;
+            /** Delete the run, leaving a signed deletion record (the key's manage permission); later reads throw RunDeletedError. */
+            delete: (id: string, options?: {
+                reason?: string;
+            }) => Promise<Record<string, unknown>>;
+            /** 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: string, options?: {
+                after?: number;
+                signal?: AbortSignal;
+                maxReconnects?: number;
+            }) => AsyncGenerator<BlackBoxStreamEvent<any>, void, undefined>;
+        };
+        bookmarks: {
+            list: (runId: string) => Promise<{
+                bookmarks: Record<string, unknown>[];
+            }>;
+            /** Mark event `seq` of a run with a note (the key's write permission). */
+            create: (runId: string, params: {
+                seq: number;
+                note?: string;
+            }) => Promise<Record<string, unknown>>;
+            delete: (bookmarkId: string | number) => Promise<{
+                deleted: boolean;
+            }>;
+        };
+        /** What the detection rules noticed in this key's runs (hypotheses with evidence). Call it, or use `list`; `update` triages. */
+        findings: ((query?: BlackBoxFindingsQuery) => Promise<{
+            findings: Record<string, unknown>[];
+        }>) & {
+            list: (query?: BlackBoxFindingsQuery) => Promise<{
+                findings: Record<string, unknown>[];
+            }>;
+            update: (id: string | number, params: {
+                status: "open" | "dismissed" | "confirmed";
+                note?: string;
+            }) => Promise<{
+                id: number;
+                status: string;
+                triaged_by: string;
+            }>;
+        };
+        rules: {
+            /** The detection rules and the account's configuration of them. */
+            list: () => Promise<{
+                rules: Record<string, unknown>[];
+                configured: Record<string, unknown>;
+            }>;
+            /** What detection would raise with these settings over this key's recent runs; nothing is saved. */
+            preview: (params: {
+                rules: Record<string, unknown>;
+                runs?: number;
+                days?: number;
+            }) => Promise<Record<string, unknown>>;
+        };
+        /** 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: () => Promise<{
+                sinks: BlackBoxSink[];
+                events: string[];
+                protocols: string[];
+            }>;
+            /** A webhook's `secret` (whsec_...) is in this answer only. */
+            create: (params: BlackBoxSinkParams & {
+                kind: "webhook" | "otlp";
+                url: string;
+            }) => Promise<BlackBoxSink>;
+            retrieve: (id: string) => Promise<BlackBoxSink>;
+            update: (id: string, params: BlackBoxSinkParams) => Promise<BlackBoxSink>;
+            delete: (id: string) => Promise<{
+                deleted: boolean;
+            }>;
+            /** Queue a test message (a ping). */
+            test: (id: string) => Promise<Record<string, unknown>>;
+            /** A webhook's new secret (in this answer only); the old one stops working. */
+            rotate: (id: string) => Promise<BlackBoxSink>;
+            deliveries: (id: string, query?: {
+                limit?: number;
+            }) => Promise<{
+                deliveries: Record<string, unknown>[];
+            }>;
+            /** Send a delivery again. */
+            retryDelivery: (deliveryId: string | number) => Promise<{
+                queued: boolean;
+            }>;
+        };
+        diff: (a: string, b: string) => Promise<Record<string, unknown>>;
+        keys: () => Promise<{
+            keys: {
+                key_id: string;
+                alg: string;
+                public_key: string;
+            }[];
+        }>;
+        verify: (bundle: Record<string, unknown>) => Promise<VerifyReport>;
+        /** 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?: {
+            signal?: AbortSignal;
+            maxReconnects?: number;
+        }) => AsyncGenerator<BlackBoxStreamEvent<any>, void, undefined>;
+    };
+    /** 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. */
+    readonly plans: {
+        /** This key's plans, newest change first (without their history); `after` (a plan id, `last_id`) pages on. */
+        list: (query?: PlanListQuery) => Promise<Page<Plan>>;
+        /** A plan: mode "plan" (the default) waits for approval; "live" is running from the start. */
+        create: (params: PlanCreateParams) => Promise<Plan>;
+        /** The plan, its steps and progress, and its recent history (`events`). */
+        retrieve: (id: string) => Promise<Plan>;
+        /** 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: string, params: PlanUpdateParams) => Promise<Plan>;
+        /** Approve `revision`, the one you reviewed (409 if it was revised since). A run with `planId` then carries it out. */
+        approve: (id: string, params: {
+            revision: number;
+        }) => Promise<Plan>;
+        /** Cancel the plan: no run carries it out after this. */
+        cancel: (id: string) => Promise<Plan>;
+        /** 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: string, key: string, params: {
+            status: PlanStepStatus;
+            note?: string;
+            verified_by?: string;
+        }) => Promise<Plan>;
+        /** The plan's changes after event `after`, oldest first. */
+        events: (id: string, query?: {
+            after?: number;
+            limit?: number;
+        }) => Promise<{
+            object: "list";
+            data: PlanEvent[];
+            has_more: boolean;
+            last_id: number | null;
+        }>;
+        /** 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: string, options?: {
+            after?: number;
+            signal?: AbortSignal;
+            maxReconnects?: number;
+        }) => AsyncGenerator<PlanStreamEvent, void, undefined>;
+    };
     /** One question, one answer: the reply's text. */
     ask(prompt: string, options?: Omit<ChatCompletionParams, "messages" | "model" | "stream"> & {
         model?: Model;
         system?: string;
     }): Promise<string>;
+    private findingsList;
     /** The API's OpenAPI description. */
     openapi(): Promise<Record<string, unknown>>;
 }
 export default Dyadic;
+export interface BlackBoxBatchResult {
+    run_id: string;
+    trace_id: string;
+    accepted: number;
+    duplicates: number;
+    rejected: {
+        index: number;
+        reason: string;
+    }[];
+    head: {
+        seq: number;
+        hash: string;
+    } | null;
+    status: string | null;
+    ended: boolean;
+}
+export interface BlackBoxRunSummary {
+    id: string;
+    title: string;
+    agent_id: string;
+    status: string;
+    outcome: string;
+    started_at: string;
+    ended_at: string | null;
+    trace_id: string;
+    events: number;
+    signed_through: number;
+    findings: number;
+    max_severity: string | null;
+    [key: string]: unknown;
+}
+/** Findings: status open (the default), dismissed, confirmed or all (the default for a run); severity; a rule (BB-R001...). */
+export interface BlackBoxFindingsQuery {
+    run_id?: string;
+    status?: "open" | "dismissed" | "confirmed" | "all";
+    severity?: string;
+    rule?: string;
+    limit?: number;
+}
+export interface BlackBoxSinkParams {
+    kind?: "webhook" | "otlp";
+    url?: string;
+    name?: string;
+    /** Webhooks: finding.created, run.completed, run.failed, run.cancelled, run.interrupted, run.abandoned, run.requires_action. */
+    events?: string[];
+    min_severity?: "info" | "low" | "medium" | "high" | "critical";
+    environments?: ("production" | "staging" | "development" | "test" | "simulation")[];
+    /** OpenTelemetry sinks: how runs are sent, whether content goes too (needs the content permission), the collector's headers. */
+    protocol?: "http/json" | "http/protobuf";
+    content?: boolean;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+}
+export interface BlackBoxSink {
+    id: string;
+    kind: "webhook" | "otlp";
+    name: string;
+    url: string;
+    events: string[];
+    min_severity: string;
+    environments: string[];
+    protocol: string;
+    content: boolean;
+    enabled: boolean;
+    header_names: string[];
+    api_key_id: string | null;
+    created_by: string;
+    failures: number;
+    last_success_at: string | null;
+    last_failure_at: string | null;
+    last_error: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+    /** A new webhook's, or a rotated one's, signing secret: shown once. */
+    secret?: string;
+}
+export * from "./blackbox.js";
+import type { VerifyReport } from "./blackbox.js";
+export * from "./otel.js";