@camelai/run 0.0.0 → 0.11.0

package/dist/clients/typescript.d.ts

@@ -0,0 +1,1161 @@
+import type { AgentEvent, Message, PresentedFile, ThinkingLevel } from "./types.ts";
+import type { Run } from "./agents.ts";
+import { Type, type TSchema, type Static } from "typebox";
+import { type RequestMethod, type SessionCredentials, type SessionState } from "../shared/client-protocol.ts";
+export { Type as schema };
+export type { SessionCredentials, SessionState };
+export type * from "./types.ts";
+/**
+ * Who a tool call is for, as the runtime says: from its signed identity token when the tools are
+ * served over HTTP (`serveTools`), or from the call itself when they are attached to the agent.
+ * Authorize as `user`, within `tenant` and `context`.
+ */
+export interface RuntimeIdentity {
+    /** Who is acting: the turn's actor (a prompt's `actor`, or its `from.id`), else the agent's subject. */
+    user: string;
+    /** Whom the agent acts for, as its creator set it (`createAgent({ subject })`); the agent's id if none. */
+    subject: string;
+    /** Who is acting in this turn, if the prompt named someone. */
+    actor?: string;
+    /** The runtime tenant that owns the agent. */
+    tenant: string;
+    agent: string;
+    definition?: string;
+    /** Claims the agent's creator attached (`createAgent({ context })`), e.g. `{ org, workspace }`. */
+    context: Record<string, unknown>;
+    /** Where the turn came from, e.g. `{ channel, conversationId, sender }` for a channel message. */
+    origin?: Record<string, unknown>;
+    /** The call was approved by a person: which input, who (their ids), and when. */
+    approval?: {
+        input: string;
+        by: Record<string, unknown>;
+        at: number;
+    };
+}
+/** A runtime identity from its claims (a verified token's payload, or an attached call's `_meta`). */
+export declare function identityFromClaims(claims: Record<string, any>): RuntimeIdentity;
+export interface ToolContext {
+    signal: AbortSignal;
+    /**
+     * The same for every attempt at this call (a retry after a lost connection, a call run again once the
+     * user answered): key your side effects by it, so a call that runs twice acts once.
+     */
+    idempotencyKey: string;
+    /** This attempt's id (a JSON-RPC id): a new one each attempt, so never a key for side effects. */
+    callId: string;
+    /** The model's tool call this is (or, from code, the code's call). */
+    toolCallId?: string;
+    /**
+     * Report progress: people watching see it, and each report restarts the tool's timeout (`timeoutMs`),
+     * so a long call that keeps reporting is not cut off. A message, or how far it is (`progress` of `total`).
+     */
+    progress(update: string | {
+        progress: number;
+        total?: number;
+        message?: string;
+    }): void;
+    /** Set by the runtime, e.g. `{ channel, conversationId, sender }` for a turn a channel message started. */
+    origin?: Record<string, unknown>;
+    /** Who the call is for: always set by `serveTools`; set for attached tools by runtimes that send it. */
+    identity?: RuntimeIdentity;
+    /**
+     * Ask the user, and get their answer. The call ends here and the agent's turn waits, for days if need
+     * be; once they answer, the runtime calls the tool again with the same arguments, and this returns
+     * the answer. So everything before an ask runs again on that call: ask first, act after.
+     * `confirm`: whether they said yes. `ask`: what they filled in (a flat object schema), or undefined
+     * if they declined. `requireUrl`: whether they say they have done what the https page asks.
+     */
+    confirm(message: string): Promise<boolean>;
+    ask<T extends Record<string, unknown> = Record<string, unknown>>(message: string, schema: Record<string, unknown>): Promise<T | undefined>;
+    requireUrl(url: string, message: string): Promise<boolean>;
+}
+/** Thrown by a ToolContext's asks: the call answers MCP's `input_required`, and runs again once the user answers. */
+export declare class InputRequired extends Error {
+    readonly inputRequests: Record<string, {
+        method: string;
+        params: Record<string, unknown>;
+    }>;
+    /** The answers so far, which the runtime hands back on the next call (MCP's `requestState`). */
+    readonly requestState?: string;
+    constructor(inputRequests: InputRequired["inputRequests"], requestState?: string);
+}
+export interface Tool<T = any> {
+    description: string;
+    /**
+     * How long one call may go without an answer before the runtime gives up on it (1 s to 20 minutes;
+     * default 15 s).
+     * Each `context.progress()` restarts it. A call cut off is an error the model sees; it may still finish here.
+     */
+    timeoutMs?: number;
+    resultFormat?: "json" | "content";
+    exposure?: "direct" | "codemode" | "both";
+    executionMode?: "sequential" | "parallel";
+    input: Record<string, unknown>;
+    /** Return any JSON value (`undefined` is sent as null); throw to tell the model the call failed. */
+    execute: (args: T, context: ToolContext) => unknown | Promise<unknown>;
+    /**
+     * Ask the user to approve each call before it runs (or only the calls this says need it). The runtime
+     * shows them the real call; the tool is declared to the model directly, as code cannot wait for a person.
+     */
+    needsApproval?: boolean | ((args: T, context: ToolContext) => boolean | Promise<boolean>);
+}
+/** Infer callback arguments from the schema; no manually duplicated argument type. */
+export declare function tool<S extends TSchema>(definition: Omit<Tool<Static<S>>, "input"> & {
+    input: S;
+}): Tool<Static<S>>;
+export type Tools = Record<string, Tool>;
+/** A tool as an MCP server lists it (`tools/list`). Runtime options ride in `_meta` under "agent-runtime/". */
+export interface McpTool {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    _metadata?: Record<string, string>;
+}
+/** An MCP `tools/call` result: complete, or (MCP's multi round-trip requests) asking for input to retry with. */
+export type CallToolResult = {
+    content: Array<Record<string, unknown>>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    resultType?: "complete";
+} | {
+    resultType: "input_required";
+    inputRequests?: Record<string, {
+        method: string;
+        params?: Record<string, unknown>;
+    }>;
+    requestState?: string;
+    content?: never;
+};
+/**
+ * The MCP server an application attaches to its agent: the SDK relays the runtime's
+ * `tools/list` and `tools/call` to it over the agent's connection. Throw from `callTool`
+ * only when the call could not be answered; a tool's own failure is an `isError` result.
+ */
+export interface ToolServer {
+    listTools(): McpTool[] | Promise<McpTool[]>;
+    callTool(name: string, args: Record<string, unknown>, context: ToolContext): Promise<CallToolResult>;
+}
+/**
+ * A call's context from its params: ids, origin, and the identity the runtime sent in `_meta` (or
+ * `identity`, from a verified token); its asks answer from the retry's `inputResponses`, by position.
+ */
+export declare function toolContext(params: Record<string, any>, fallbackId: string, signal: AbortSignal, identity?: RuntimeIdentity, notify?: (message: Record<string, unknown>) => void): ToolContext;
+/**
+ * Answer one MCP JSON-RPC request as a tool server: initialize, ping, tools/list and tools/call.
+ * Both an attached server (answering over the agent's connection) and `serveTools` (over HTTP) use it.
+ */
+export declare function answerMcp(message: Record<string, any>, server: ToolServer, context: (params: Record<string, any>) => ToolContext, info?: {
+    name: string;
+    version: string;
+}): Promise<{
+    result: unknown;
+} | {
+    error: {
+        code: number;
+        message: string;
+    };
+}>;
+/** `tool({...})` definitions as an attached MCP server: JSON results become a text block (and structured content for objects). */
+export declare function toolServer(tools: Tools): ToolServer;
+/** The hosted runtime; `url` points elsewhere (a self-hosted runtime, or http://127.0.0.1:8790 in development). */
+export declare const DEFAULT_URL = "https://agents.camelai.dev";
+export interface RuntimeOptions {
+    /** The runtime's origin. Default https://agents.camelai.dev. */
+    url?: string;
+    apiKey?: string;
+    /** Injectable for tests, observability, or an application's HTTP stack. */
+    fetch?: typeof globalThis.fetch;
+    /** Opens a local file to attach by its path; set by the Node entry (`@camelai/run/node`). */
+    openFile?: (path: string) => Promise<Blob>;
+    /** How often a request still waiting for its result asks for its status, in case the result's event was lost. Default 30 s. */
+    pollMs?: number;
+}
+export interface AgentOptions {
+    /** The application's tools, served to the agent as an attached MCP server. */
+    tools?: Tools;
+    /** Or an MCP server of the application's own (see `clients/mcp.ts` for MCP SDK servers). */
+    mcp?: ToolServer;
+    /**
+     * The agent's events, for display: a run's result is the truth. They are delivered in order, one at a
+     * time, apart from the connection (a slow or failing handler never holds up tool calls); an error it
+     * throws goes to `onError`. A `message_update` is its delta alone (`assistantMessageEvent`), without the
+     * message it updates: fold that from its `message_start` and the deltas since. Where the stream
+     * cannot replay (a first connect, or a reconnect after the host's buffer moved on), the first event
+     * is a `{ type: "snapshot", turn }` of the running turn to fold from.
+     */
+    onEvent?: (event: AgentEvent, requestId?: string) => unknown | Promise<unknown>;
+    /**
+     * A question, approval or setup step the agent's turn now waits on. Return an answer to give it
+     * at once, or nothing to answer later with `agent.answer` (from any process, via connectAgent).
+     */
+    onInput?: (input: AgentInput, requestId?: string) => InputAnswer | void | Promise<InputAnswer | void>;
+    onConnection?: (connected: boolean) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Whether this client answers the agent's tool calls (its attached MCP server). Default: true. One
+     * process is the agent's application at a time; `false` connects to follow the agent and run it only,
+     * as any number of processes may (serverless functions, a second service), and answers no tool calls.
+     */
+    attach?: boolean;
+    /**
+     * Replace the process that serves the agent's tools now (it stops serving them, and its onError hears
+     * APPLICATION_REPLACED). Without it, connecting while another process serves them fails with APPLICATION_CONNECTED.
+     */
+    takeover?: boolean;
+    /**
+     * Declare this client's tools when they differ from those the agent has, as it connects (default true), so
+     * a process restarted with changed tools updates its agent. The declaration applies between the agent's turns.
+     */
+    syncTools?: boolean;
+}
+/**
+ * Human input a suspended turn waits on (its run ends with `stopped: "input_required"` and these in
+ * `inputs`): the model's questions (ask_user), approvals, and a tool's form or URL step.
+ */
+export interface AgentInput {
+    id: string;
+    agent: string;
+    requestId: string;
+    toolCallId: string;
+    kind: "question" | "approval" | "form" | "url";
+    message: string;
+    /** What it asks, by `kind`. */
+    detail: InputDetail;
+    responders: {
+        audience?: string[];
+    };
+    state: "pending" | "answered" | "declined" | "cancelled" | "expired" | "superseded";
+    answer?: {
+        action: string;
+        content?: unknown;
+        by: Record<string, unknown>;
+        at: number;
+    };
+    createdAt: number;
+    expiresAt: number;
+}
+/** What an input asks: by its `kind`, the fields of one of these. */
+export interface InputDetail {
+    /** question: the model's questions (ask_user). */
+    questions?: {
+        question: string;
+        header?: string;
+        options: {
+            label: string;
+            description?: string;
+        }[];
+        multiSelect: boolean;
+        allowOther: boolean;
+    }[];
+    /** approval: the tool call it waits on, where its tool comes from ("application", "runtime", or a tool source's name), and why it asks. */
+    tool?: string;
+    source?: string;
+    reason?: string;
+    /** approval: the call's arguments, as its tool_call event has them; past 4,000 characters of JSON, `argumentsPreview` (their start) instead. */
+    arguments?: Record<string, unknown>;
+    argumentsPreview?: string;
+    argumentsHash?: string;
+    /** form: the fields asked for, as a flat JSON Schema. */
+    requestedSchema?: Record<string, unknown>;
+    /** url: the page to open, and its origin. */
+    url?: string;
+    origin?: string;
+}
+/** An answer. `content`: for a question, { answers: { "<question>": "<label>" | ["<label>"] | "<own words>" } }; for a form, its fields. `from`/`actor`: who answers, checked against who may. */
+export interface InputAnswer {
+    action: "accept" | "decline" | "cancel";
+    content?: unknown;
+    from?: Sender;
+    actor?: string;
+}
+export type { ThinkingLevel };
+export interface CreateAgentOptions extends AgentOptions {
+    idempotencyKey?: string;
+    /**
+     * Make the agent from a definition (GET /v1/definitions): it supplies the model, system
+     * prompt, thinking level and tool sources, so leave those out. `tools` (or `mcp`) are added
+     * as the agent's attached server.
+     */
+    definition?: string;
+    /** Agent lifetime in seconds (60 to 366 days), or null to keep it until deleted. Default: until deleted with an `idempotencyKey` of yours, else one day. */
+    ttlSeconds?: number | null;
+    /** Who the agent acts for (a user id in your app): `sub` in the identity tokens its tool servers get. Set only at creation. */
+    subject?: string;
+    /** Claims your tool servers need (org, workspace, thread…): `ctx` in its identity tokens. Set only at creation. */
+    context?: Record<string, unknown>;
+    /** A key scope (PUT /v1/key-scopes/:scope/providers/:provider) whose keys its model calls use first. */
+    keyScope?: string;
+    /** The most the agent may spend on model calls from now on (USD); PATCH /v1/agents/:id/configuration sets a new one. */
+    spendLimit?: {
+        usd: number;
+    };
+    /** Non-secret headers for each of its model calls, e.g. cf-aig-metadata; never auth headers. */
+    modelHeaders?: Record<string, string>;
+    systemPrompt?: string;
+    /** Text the model reads after the system prompt (a definition's, say): per-conversation context. */
+    systemPromptAppend?: string;
+    /** false: no file tools (read, write, edit, ls, glob, grep) for an application with file tools of its own. */
+    fileTools?: boolean;
+    name?: string;
+    type?: string;
+    /**
+     * A model from the runtime's catalog as "provider/model-id" (see GET /v1/models),
+     * e.g. "anthropic/claude-sonnet-5-5" or "openrouter/openai/gpt-5.2". A full Pi
+     * model object is also accepted if its endpoint is trusted by the runtime.
+     */
+    model?: string | Record<string, unknown>;
+    thinkingLevel?: ThinkingLevel;
+    initialMessages?: Message[];
+    /** Volumes for the agent's file tools (read, write, edit, ls, glob, grep). Default: its own workspace volume at /workspace. */
+    mounts?: Mount[];
+    /** Tools the runtime answers itself, for an agent without a definition (one made from a definition has its definition's). */
+    builtins?: Builtin[];
+    /**
+     * A first prompt, sent in the same call once the agent is made (upsertAgent returns its request, or why it was refused).
+     * Give it a `requestId`: a retried call with the same key and requestId sends it once.
+     */
+    prompt?: {
+        text: string;
+        requestId?: string;
+        actor?: string;
+        from?: Sender;
+        metadata?: Record<string, string>;
+        spendLimit?: {
+            usd: number;
+        };
+        whileRunning?: "queue" | "steer";
+        allowDisconnected?: boolean;
+        files?: ({
+            path: string;
+        } | {
+            name?: string;
+            data: string;
+            contentType?: string;
+        })[];
+    };
+}
+/** A tool the runtime answers itself: web_fetch, web_search, schedule (wake-ups) or ask_user (questions, waiting for the answer). */
+export type Builtin = "web_fetch" | "web_search" | "schedule" | "ask_user";
+/** A volume the agent's file tools see at `path`; `notify` prompts the agent when others change files there. */
+/** How a tool source is authenticated: a stored bearer token, or identity tokens the runtime signs for each request. */
+export type SourceAuth = {
+    type: "bearer";
+    token: string;
+} | {
+    type: "runtime";
+};
+/** Options every tool source takes. `exposure` defaults to both for a source of up to 10 tools, else codemode. */
+interface SourceOptions {
+    name: string;
+    headers?: Record<string, string>;
+    auth?: SourceAuth;
+    audience?: string;
+    allowTools?: string[];
+    denyTools?: string[];
+    exposure?: "direct" | "codemode" | "both";
+    timeoutMs?: number;
+}
+export interface DefinitionInput {
+    name: string;
+    model?: string;
+    systemPrompt?: string;
+    thinkingLevel?: ThinkingLevel;
+    limits?: {
+        ttlSeconds?: number | null;
+    };
+    mounts?: unknown[];
+    builtins?: Builtin[];
+    /** The search providers web_search tries, in order, instead of the runtime's. */
+    webSearch?: {
+        providers: ("exa" | "brave" | "parallel")[];
+    };
+    mcpServers?: (SourceOptions & {
+        url: string;
+    })[];
+    openApi?: (SourceOptions & {
+        spec?: string | Record<string, unknown>;
+        baseUrl?: string;
+    })[];
+}
+/** What applying a definition's revision did to one agent; poll a queued one's request for its outcome. */
+export interface ApplyResult {
+    agent: string;
+    requestId: string;
+    status: "updated" | "queued" | "failed";
+    error?: string;
+}
+/** A definition as the runtime returns it: credentials are never included. */
+export interface Definition extends Omit<DefinitionInput, "mcpServers" | "openApi"> {
+    id: string;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+    mcpServers?: Record<string, unknown>[];
+    openApi?: Record<string, unknown>[];
+    applied?: ApplyResult[];
+}
+/** One source of an agent's tools; `excluded` says why the model does not get a tool, when it does not. */
+export interface ToolSource {
+    kind: "channel" | "application" | "files" | "builtin" | "mcp" | "openapi";
+    name: string;
+    /** unlisted: an MCP server the runtime has not listed yet; error: listing it failed. */
+    status: "listed" | "unlisted" | "error";
+    error?: string;
+    listedAt?: number;
+    connected?: boolean;
+    url?: string;
+    exposure?: "direct" | "codemode" | "both";
+    tools: {
+        name: string;
+        description: string;
+        exposure?: "direct" | "codemode" | "both";
+        executionMode?: "sequential" | "parallel";
+        parameters?: Record<string, unknown>;
+        excluded?: string;
+    }[];
+}
+/**
+ * A model on a provider of your own: its id on the server, its context window (compaction keeps requests within it),
+ * the most it writes in a reply (default 8,192, or half a smaller window), what it takes in, whether it reasons, its
+ * pricing in USD per million tokens (for usage, spend limits and webhooks; none: free), and `compat` switches for a
+ * server that differs from OpenAI's.
+ */
+export interface CustomModel {
+    id: string;
+    contextWindow: number;
+    maxOutputTokens?: number;
+    input?: ("text" | "image")[];
+    reasoning?: boolean;
+    pricing?: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+    compat?: {
+        supportsDeveloperRole?: boolean;
+        supportsUsageInStreaming?: boolean;
+        supportsFinishReason?: boolean;
+        supportsReasoningEffort?: boolean;
+        maxTokensField?: "max_tokens" | "max_completion_tokens";
+        thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "qwen-chat-template";
+    };
+}
+/** A provider of your own: a public https server that speaks OpenAI Chat Completions (`POST <baseUrl>/chat/completions`). */
+/** The API a custom provider speaks. */
+export type CustomProviderType = "openai-completions" | "openai-responses" | "anthropic-messages";
+export interface CustomProviderInput {
+    type: CustomProviderType;
+    baseUrl: string;
+    apiKey?: string | null;
+    headers?: Record<string, string> | null; /** anthropic-messages: "bearer" sends the key as Authorization: Bearer, not x-api-key. */
+    auth?: "x-api-key" | "bearer";
+    models: CustomModel[];
+}
+/** A provider as GET /v1/providers lists it; never a key or header value. */
+export interface ProviderSummary {
+    id: string;
+    kind: "model" | "search" | "fetch";
+    models: number;
+    apiKey: boolean;
+    requires?: string;
+    key: {
+        provider: string;
+        source: "tenant" | "admin" | "platform";
+        last4?: string;
+        setAt?: number;
+    } | null;
+    custom?: {
+        type: CustomProviderType;
+        baseUrl: string;
+        auth: "x-api-key" | "bearer";
+        headers?: string[];
+        models: CustomModel[];
+    };
+}
+/** An agent as GET /v1/agents lists it. */
+export interface AgentSummary {
+    id: string;
+    key: string | null;
+    name: string;
+    type: string;
+    model: string;
+    connected: boolean;
+    running: boolean;
+    expiresAt: number | null;
+    resume: {
+        failures: number;
+        after: number;
+    } | null;
+}
+export interface Mount {
+    volumeId: string;
+    path: string;
+    mode: "ro" | "rw";
+    subpath?: string;
+    notify?: boolean;
+}
+export interface Volume {
+    id: string;
+    name: string;
+    createdAt: number;
+    seq?: number;
+    files?: number;
+    bytes?: number;
+    origin?: {
+        volume: string;
+        snapshot?: string;
+        seq: number;
+    };
+}
+export interface VolumeFile {
+    path: string;
+    version: number;
+    size: number;
+    updatedAt: number;
+    by?: string;
+    contentType: string;
+}
+export interface VolumeSnapshot {
+    id: string;
+    volume: string;
+    name: string;
+    seq: number;
+    createdAt: number;
+    files: number;
+    bytes: number;
+}
+export interface VolumeChanges {
+    seq: number;
+    changes: {
+        seq: number;
+        path: string;
+        kind: "write" | "delete";
+        version?: number;
+        size?: number;
+        by?: string;
+        at: number;
+    }[];
+    gap?: boolean;
+}
+/** A signed URL for one file: send `method` to `url` with no Authorization header, until `expiresAt`. */
+export interface FileLink {
+    url: string;
+    method: "GET" | "PUT";
+    path: string;
+    expiresAt: number;
+    maxBytes?: number;
+    contentType?: string;
+}
+/** A link's options: `expiresIn` seconds (default 900, at most 86400); for PUT, the largest upload and its content type. */
+export interface LinkOptions {
+    method?: "GET" | "PUT";
+    expiresIn?: number;
+    maxBytes?: number;
+    contentType?: string;
+}
+/** A message as the runtime records it: a user message also names its sender (if given), the request that sent it, and the application's `metadata`. */
+export type RecordedMessage = Message & {
+    from?: Sender;
+    requestId?: string;
+    metadata?: Record<string, string>;
+};
+export interface AgentHistory {
+    messages: RecordedMessage[];
+}
+/** A page of history: whole turns, oldest first, each message at its index in the agent's history. `next` is the older page's `before` (null at the start). */
+export interface HistoryPage {
+    entries: {
+        index: number;
+        message: RecordedMessage;
+    }[];
+    next: number | null;
+    total: number;
+    split?: true;
+}
+/** What a run's model responses used (`run.completed`, `run.failed`); null when it made none on the node that ended it. */
+export interface RunUsage {
+    responses: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    costUsd: number;
+}
+type RunFacts = {
+    agentId: string;
+    requestId: string;
+    method: "prompt" | "continue" | "resume" | "execute";
+    actor?: string;
+    metadata?: Record<string, string>;
+};
+/**
+ * An event a tenant's webhook endpoint receives (`POST /v1/webhooks {url, events}`), signed per Standard Webhooks.
+ * `created` is Unix seconds; dedupe by `id`. Payloads carry ids and key facts: read the rest with the tenant token.
+ */
+export type WebhookEvent = {
+    id: string;
+    created: number;
+} & ({
+    type: "billing.balance.low" | "billing.balance.depleted";
+    data: {
+        /** Integer micro-USD, including negative balances. */
+        balance: number;
+        threshold: number;
+        previousBalance?: number;
+        source: "balance" | "threshold_changed";
+    };
+} | {
+    type: "run.started";
+    data: RunFacts & {
+        resumes?: number;
+    };
+} | {
+    type: "run.completed";
+    data: RunFacts & {
+        usage: RunUsage | null;
+        stopped?: "input_required" | "spend_limit";
+        inputIds?: string[];
+        replyIndex?: number;
+        messageCount?: number;
+        steeredInto?: string;
+    };
+} | {
+    type: "run.failed";
+    data: RunFacts & {
+        usage: RunUsage | null;
+        error: string;
+        uncertain?: boolean;
+        steeredInto?: string;
+    };
+} | {
+    type: "input.requested";
+    data: {
+        agentId: string;
+        requestId: string;
+        inputId: string;
+        toolCallId: string;
+        kind: AgentInput["kind"];
+        expiresAt: number;
+    };
+} | {
+    type: "input.resolved";
+    data: {
+        agentId: string;
+        requestId: string;
+        inputId: string;
+        state: Exclude<AgentInput["state"], "pending">;
+    };
+} | {
+    type: "usage.recorded";
+    data: {
+        agentId: string;
+        requestId: string | null;
+        subject: string;
+        actor: string | null;
+        context: Record<string, unknown>;
+        keyScope: string | null;
+        provider: string;
+        model: string;
+        kind: "response" | "compaction";
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        reasoning?: number;
+        cost: {
+            usd: number;
+            source: "provider" | "catalog";
+        };
+        at: number;
+    };
+});
+/**
+ * A file to attach to a message: bytes or a Blob (a File keeps its name and type), `{ name, data,
+ * contentType? }`, a local path (Node entry), or `{ path }` for a file already in the agent's mounts.
+ * The SDK uploads each to the agent's workspace (uploads/<request>/<name>) before sending the message.
+ */
+export type Attachment = Uint8Array | Blob | string | {
+    name?: string;
+    data: Uint8Array | Blob;
+    contentType?: string;
+} | {
+    path: string;
+};
+/** A file in the agent's mounts, at the path the agent sees it. */
+export interface AgentFile {
+    path: string;
+    version: number;
+    size: number;
+    updatedAt: number;
+    by?: string;
+    contentType: string;
+}
+export interface Schedule {
+    id: string;
+    agent: string;
+    text?: string;
+    code?: string;
+    dueAt: number;
+    everySeconds?: number;
+    createdAt: number;
+}
+/**
+ * `idempotencyKey`: the request's id; sending the same key again returns the same request, never a second one.
+ * `signal`: stop waiting (the request goes on; `abort()` stops the agent's turn). `timeoutMs`: the same, after a time.
+ */
+export interface RequestOptions {
+    idempotencyKey?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * `allowDisconnected`: run even when no process serves the agent's tools (its calls to them then fail as
+ * not_connected). Without it, a run of an agent with application tools and none connected is refused
+ * with APPLICATION_NOT_CONNECTED.
+ */
+export interface RunRequestOptions extends RequestOptions {
+    allowDisconnected?: boolean;
+}
+/** Who sent a message: `id` is yours and the model may rely on it; the names are the sender's own. */
+export interface Sender {
+    id: string;
+    name?: string;
+    username?: string;
+}
+export declare class AgentError extends Error {
+    /** The HTTP status, or 0 for a failure that is not an HTTP response's (a run's, the connection's). */
+    status: number;
+    requestId?: string;
+    /** A stable name for the failure where the runtime gives one, e.g. APPLICATION_NOT_CONNECTED. */
+    code?: string;
+    /** The runtime could not tell whether the work took effect (a restart cut it short). */
+    uncertain?: boolean;
+    /** Milliseconds the runtime asked to wait before retrying (its Retry-After), for 429 and 503. */
+    retryAfterMs?: number;
+    constructor(message: string, status?: number, requestId?: string);
+}
+/** A run that failed (`agent.run` throws it unless `throwOnError: false`): `run` is how it ended, `code` why. */
+export declare class RunError extends AgentError {
+    readonly run: Run;
+    constructor(run: Run);
+}
+/** What a run produced: its reply, how it stopped, the inputs it waits on and the files it wrote. */
+export interface RunResult {
+    /** The final assistant message's text ("" when it said nothing). */
+    reply?: string;
+    /** The model's error, or null. */
+    error: string | null;
+    /** Why it stopped early: waiting on human input (`inputs`), or its spend limit. */
+    stopped?: "input_required" | "spend_limit";
+    inputs?: AgentInput[];
+    replyIndex?: number;
+    /** Messages in the agent's history after it. */
+    messages?: number;
+    files?: AgentFile[];
+    presented?: PresentedFile[];
+    usage?: RunUsage | null;
+    /** A stable name for `error`, where the runtime gives one. */
+    code?: string;
+    /** Tool calls that did not complete (the model was told): timed out, lost, with no application connected, and so on. */
+    toolErrors?: ToolError[];
+    /** Tool sources (MCP servers, OpenAPI specs) that could not be listed, so the model went without their tools. */
+    sourceErrors?: {
+        kind: string;
+        source: string;
+        message: string;
+    }[];
+}
+/**
+ * A tool call that did not complete. `code`: timeout or connection_lost (with `outcomeUnknown`: it may have
+ * taken effect), not_connected (no application was connected to run it: it did not run), source_unavailable, failed.
+ */
+export interface ToolError {
+    tool: string;
+    toolCallId?: string;
+    innerCallId?: string;
+    code: "timeout" | "connection_lost" | "not_connected" | "source_unavailable" | "failed";
+    outcomeUnknown?: true;
+    message: string;
+}
+/**
+ * Hosts plain http:// may reach: loopback, and names and addresses only a private network resolves
+ * (a Docker Compose service, `*.internal`, `*.local`, 10/8, 172.16/12, 192.168/16), as for a runtime kept private.
+ */
+export declare function privateHost(hostname: string): boolean;
+declare class Transport {
+    readonly base: string;
+    readonly fetcher: typeof globalThis.fetch;
+    constructor(options: RuntimeOptions);
+    json(path: string, token: string, method?: string, body?: unknown, retry?: boolean, headers?: Record<string, string>): Promise<any>;
+    /**
+     * A request with a raw body or response (file contents). It fails once nothing arrives for 30 s
+     * (an upload has the runtime's 15 minutes to be sent), so a stalled transfer never hangs its caller.
+     */
+    raw(path: string, token: string, init?: {
+        method?: string;
+        body?: Uint8Array | Blob;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    private transfer;
+}
+/** Trusted-backend SDK. Only createAgent needs the operator key. */
+export declare class AgentRuntime {
+    readonly options: RuntimeOptions;
+    private readonly transport;
+    constructor(options?: RuntimeOptions);
+    /**
+     * The agent for `key`: made if there is none, set to `options` if it differs. Returns its credentials;
+     * connect with `connectAgent`. Keyed agents live until they are deleted.
+     */
+    upsertAgent(key: string, options: CreateAgentOptions): Promise<{
+        session: SessionCredentials;
+        reconfigured?: {
+            id: string;
+        };
+        prompt?: {
+            id: string;
+            state: "running" | "completed";
+            [field: string]: unknown;
+        } | {
+            error: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+    }>;
+    createAgent(options: CreateAgentOptions): Promise<AgentClient>;
+    connectAgent(session: SessionCredentials, options: AgentOptions): Promise<AgentClient>;
+    private operator;
+    /**
+     * Add or replace a provider of your own: a server that speaks OpenAI Chat Completions, with the models it has. Agents
+     * name them `<name>/<model id>`. `apiKey` and `headers` left out keep what is stored; null removes them.
+     */
+    setProvider(name: string, config: CustomProviderInput): Promise<ProviderSummary>;
+    deleteProvider(name: string): Promise<{
+        deleted: true;
+    }>;
+    /** Every provider: the built-in ones with your keys' status, and your own (`custom`). */
+    providers(): Promise<ProviderSummary[]>;
+    /** The tenant's agents, each with the key it was made with (null for one made without) and its name. */
+    listAgents(): Promise<AgentSummary[]>;
+    createVolume(options?: {
+        name?: string;
+    }): Promise<Volume>;
+    listVolumes(): Promise<Volume[]>;
+    /** A handle on one volume's files, snapshots and forks. */
+    volume(id: string): VolumeHandle;
+    /**
+     * Definitions: reusable agent configurations with their tool sources (MCP servers, OpenAPI
+     * specs, built-ins). Make agents from one with `createAgent({ definition: id })`.
+     */
+    createDefinition(input: DefinitionInput): Promise<Definition>;
+    /** The definition for `key`, set to `input` whole: made if there is none, else a new revision if `input` changes it. The same key is the same definition. */
+    upsertDefinition(key: string, input: DefinitionInput): Promise<Definition>;
+    /** Replace the fields given (null removes one); `apply: "all"` also reconfigures its live agents between their turns. */
+    updateDefinition(id: string, input: Partial<DefinitionInput> & {
+        revision?: number;
+        apply?: "all";
+    }): Promise<Definition>;
+    definition(id: string): Promise<Definition>;
+    definitions(): Promise<Definition[]>;
+    deleteDefinition(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    mounts(agentId: string): Promise<Mount[]>;
+    /** Replace an agent's mounts; an idle agent restarts so its tools describe them. */
+    setMounts(agentId: string, mounts: Mount[]): Promise<Mount[]>;
+    /**
+     * Every source of an agent's tools (its application, file tools, built-ins, MCP servers, OpenAPI
+     * specs) and what each offers the model. `schemas` includes input schemas; `refresh` lists MCP servers now.
+     */
+    /**
+     * A token a browser reads one agent with (`@camelai/run/watch`): mint one per user, after your
+     * own access checks. It reads only that agent's events, state, history and inputs (or `scopes`), for
+     * `ttlSeconds` (default 900, 5 to 3600).
+     */
+    browserToken(agentId: string, options?: {
+        ttlSeconds?: number;
+        scopes?: ("events" | "state" | "history" | "inputs")[];
+        events?: string[];
+        redact?: "usage.cost"[];
+        subject?: string;
+    }): Promise<{
+        token: string;
+        expiresAt: number;
+        agentId: string;
+        url?: string;
+    }>;
+    /** Who the API key is: `tenant` is your tenant's id, which serveTools and verifyRuntimeToken take. */
+    /** Who the API key is (`tenant`), and `defaultModel`, the model an agent gets when it names none. */
+    me(): Promise<{
+        tenant: string;
+        via: string;
+        login?: string;
+        defaultModel: string;
+    }>;
+    /** Inputs waiting on someone across all the tenant's agents (`pending` ones, say), newest first. */
+    inbox(state?: AgentInput["state"]): Promise<AgentInput[]>;
+    toolSources(agentId: string, options?: {
+        schemas?: boolean;
+        refresh?: boolean;
+    }): Promise<ToolSource[]>;
+}
+/** Files are versioned: pass `version` to write or remove only if nobody changed the file since (0: must not exist). */
+export declare class VolumeHandle {
+    readonly id: string;
+    private readonly transport;
+    private readonly token;
+    constructor(transport: Transport, token: string, id: string);
+    private path;
+    private file;
+    info(): Promise<Volume>;
+    delete(): Promise<any>;
+    snapshot(options?: {
+        name?: string;
+    }): Promise<VolumeSnapshot>;
+    snapshots(): Promise<VolumeSnapshot[]>;
+    deleteSnapshot(id: string): Promise<any>;
+    /** A new volume with this one's files (or a snapshot's); only metadata is copied. */
+    fork(options?: {
+        name?: string;
+        snapshot?: string;
+    }): Promise<Volume>;
+    changes(since?: number): Promise<VolumeChanges>;
+    list(options?: {
+        prefix?: string;
+        glob?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        files: VolumeFile[];
+        next?: string;
+    }>;
+    /** Without `contentType`, the runtime sniffs it from the file's first bytes and name. */
+    write(path: string, data: string | Uint8Array, options?: {
+        version?: number;
+        contentType?: string;
+    }): Promise<VolumeFile>;
+    /** A file's bytes, or `range` of them ([start, end) in bytes). */
+    read(path: string, options?: {
+        range?: [number, number?];
+    }): Promise<{
+        data: Uint8Array;
+        version: number;
+        contentType: string;
+    }>;
+    readText(path: string): Promise<string>;
+    /** A signed URL to download (GET) or upload (PUT) one file without a token. */
+    link(path: string, options?: LinkOptions): Promise<FileLink>;
+    remove(path: string, options?: {
+        version?: number;
+    }): Promise<any>;
+}
+declare const INSPECT: unique symbol;
+/**
+ * The agent's files, at the paths it sees them (`/workspace/report.pdf`), with the agent's own
+ * token: what it wrote during a run (a run's outcome lists `files`), and links to hand them on.
+ */
+export declare class AgentFiles {
+    private readonly transport;
+    private readonly token;
+    private readonly base;
+    constructor(transport: Transport, token: string, base: string);
+    /** Files under `path` (default: the first mount), in path order, a page at a time. */
+    list(options?: {
+        path?: string;
+        glob?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        files: AgentFile[];
+        next?: string;
+    }>;
+    download(path: string): Promise<{
+        data: Uint8Array;
+        contentType: string;
+        version: number;
+    }>;
+    /** Write a file into a writable mount; without `contentType` the runtime sniffs it. */
+    upload(path: string, data: Uint8Array | Blob | string, options?: {
+        contentType?: string;
+    }): Promise<AgentFile>;
+    /** A signed URL to download (GET) or upload (PUT) one file without a token, e.g. for a browser or another service. */
+    link(path: string, options?: LinkOptions): Promise<FileLink>;
+}
+export declare class AgentClient {
+    /** The agent's id (client_…): safe to log and to store. */
+    readonly id: string;
+    /** The agent's id and its token: keep the token secret (it is left out of logs and JSON). */
+    readonly session: SessionCredentials;
+    readonly tools: Tools;
+    private server;
+    private readonly transport;
+    /** The last event taken from the stream: a reconnect resumes after it (a new client starts from a snapshot). */
+    private cursor;
+    private readonly options;
+    private readonly openFile?;
+    private readonly pollMs;
+    /** The agent's files: list, download, upload and link. */
+    readonly files: AgentFiles;
+    private readonly pending;
+    /** Tool calls running, by JSON-RPC id, so the runtime can cancel them. */
+    private readonly active;
+    /** The event stream's connection, named in the MCP messages this client sends back. */
+    private connection?;
+    private stream?;
+    private loop?;
+    private closed;
+    private fatal?;
+    private ready;
+    /** onEvent's queue: events wait here, in order, so the stream never waits on the application. */
+    private dispatching;
+    private queued;
+    private dropped;
+    private readonly listeners;
+    private attaching;
+    /** The stream was cut on purpose, to reconnect in another mode: not an error to report. */
+    private switching;
+    constructor(runtime: RuntimeOptions, session: SessionCredentials, options: AgentOptions);
+    private path;
+    private http;
+    private report;
+    connect(): Promise<void>;
+    private events;
+    /** Rename/regroup this agent without changing its conversation or tools. */
+    setMetadata(metadata: {
+        name: string;
+        type: string;
+    }): Promise<any>;
+    /** Hand an event to the listeners, and queue it for onEvent: the stream goes on without waiting for either. */
+    private emit;
+    /** @internal Hear every event as it arrives (synchronously, before onEvent); returns the unsubscribe. */
+    listen(listener: (event: AgentEvent, requestId?: string) => void): () => void;
+    /** Resolves once onEvent has handled every event received so far. */
+    drained(): Promise<void>;
+    private receive;
+    private settle;
+    /**
+     * A request's result arrives as an event; a reconnect also settles from /state. As a last resort,
+     * ask for its status now and then, so an event lost on the way can never strand the caller.
+     */
+    private outcome;
+    private sync;
+    /**
+     * Answer the runtime's JSON-RPC messages as the agent's attached MCP server: initialize,
+     * ping, tools/list and tools/call, and cancellation. The runtime runs a call once; a call
+     * whose answer is lost with the connection ends for the agent as "outcome unknown".
+     */
+    private mcp;
+    /**
+     * Send a request and wait for its outcome, however long the run takes: there is no timeout unless
+     * `timeoutMs` or `signal` says so, and either only stops the wait (the request goes on).
+     */
+    request(method: RequestMethod, params?: Record<string, unknown>, options?: RequestOptions): Promise<any>;
+    /**
+     * Wait for request `id` to settle, until `timeoutMs` or `signal` says to stop waiting. Calls waiting on the same
+     * request share its settlement (the same key sent again joins the run), and each stops waiting on its own.
+     */
+    private waiter;
+    /** Wait for a request already sent (by this process or another) to settle. This never submits or re-executes work. */
+    waitForRequest(id: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<any>;
+    /**
+     * `from` says who sent the message: the model sees it in a block only the runtime can write, and
+     * `from.id` is the turn's actor. `actor` names someone else acting (`act` in identity tokens) without telling the model.
+     * `metadata` is the application's own key-value data about the message (at most 16 string values): the
+     * stored message and its request carry it, with the request's id, in history, events and webhooks; the model never sees it.
+     * `whileRunning: "steer"` hands the message to a running turn, and resolves with that turn's outcome. `spendLimit` is this run's own
+     * budget: it ends before its next model request once it has spent that; the agent's spendLimit is unchanged.
+     */
+    prompt(text: string, options?: RunRequestOptions & {
+        files?: Attachment[];
+        actor?: string;
+        from?: Sender;
+        metadata?: Record<string, string>;
+        whileRunning?: "queue" | "steer";
+        spendLimit?: {
+            usd: number;
+        };
+    }): Promise<any>;
+    /**
+     * Send a message with its files: each is uploaded to the agent's workspace under the request's
+     * id first, then attached by path.
+     */
+    private message;
+    private attach;
+    history(): Promise<AgentHistory>;
+    /**
+     * The page of whole turns ending before `before` (default: the newest message, the running turn's
+     * included), with at least `limit` messages (default 50) where there are that many. It reads only
+     * that page, however long the history.
+     */
+    historyPage(options?: {
+        before?: number;
+        limit?: number;
+    }): Promise<HistoryPage>;
+    continue(options?: RunRequestOptions & {
+        actor?: string;
+    }): Promise<any>;
+    /** The legacy steer request: a message held for the running turn. New code: `prompt(text, { whileRunning: "steer" })`. */
+    steer(text: string, options?: {
+        from?: Sender;
+        files?: Attachment[];
+        metadata?: Record<string, string>;
+    }): Promise<any>;
+    /** Change the prompt, thinking level, tools, or model ("provider/model-id") between runs. */
+    configure(options: {
+        systemPrompt?: string;
+        thinkingLevel?: ThinkingLevel;
+        tools?: Tools;
+        mcp?: ToolServer;
+        model?: string;
+    }): Promise<any>;
+    /** Declare this client's tools when they differ from what the agent has (its `toolsHash`). */
+    private syncTools;
+    /** Connect again, attached (answering tool calls) or not. */
+    private reconnect;
+    execute(code: string, options?: RunRequestOptions & {
+        timeoutMs?: number;
+        executionTimeoutMs?: number;
+        actor?: string;
+    }): Promise<any>;
+    /**
+     * Wake this agent later: with `text` it gets a prompt, with `code` it runs sandboxed
+     * code against your tools. `everySeconds` (at least 60) repeats it.
+     */
+    schedule(input: {
+        text?: string;
+        code?: string;
+        at?: string | Date;
+        inSeconds?: number;
+        everySeconds?: number;
+    }): Promise<Schedule>;
+    schedules(): Promise<Schedule[]>;
+    unschedule(id: string): Promise<any>;
+    status(): Promise<any>;
+    abort(): Promise<any>;
+    requestStatus(id: string): Promise<any>;
+    /** Answer an input the agent waits on. `request` is the run resuming its turn, once its last input is answered. */
+    answer(inputId: string, answer: InputAnswer): Promise<{
+        input: AgentInput;
+        request: any | null;
+    }>;
+    /** The agent's inputs, newest first: `pending` ones, say. */
+    inputs(state?: AgentInput["state"]): Promise<AgentInput[]>;
+    outcomes(): Promise<SessionState>;
+    toJSON(): {
+        id: string;
+    };
+    [INSPECT](): string;
+    close(): Promise<void>;
+    destroy(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export { Agents, Agent } from "./agents.ts";
+export type { AgentsOptions, AgentConfig, Run, RunFailure, RunInput, RunOptions, RunStream, StreamPart, InputValue, AnswerOptions } from "./agents.ts";