@camelai/agent-runtime 0.3.0 → 0.5.0

package/dist/clients/typescript.d.ts

@@ -1,15 +1,66 @@
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, ImageContent, Model } from "@earendil-works/pi-ai";
 import { Type, type TSchema, type Static } from "typebox";
-import { type Outcome, type RequestMethod, type SessionCredentials, type SessionState } from "../shared/client-protocol.ts";
+import { type RequestMethod, type SessionCredentials, type SessionState } from "../shared/client-protocol.ts";
 export { Type as schema };
 export type { SessionCredentials, SessionState };
+/**
+ * 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;
     callId: string;
     toolCallId?: string;
     /** 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;
@@ -18,12 +69,72 @@ export interface Tool<T = any> {
     executionMode?: "sequential" | "parallel";
     input: Record<string, unknown>;
     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>;
+    _meta?: Record<string, unknown>;
+}
+/** 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): 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;
 export interface RuntimeOptions {
     url?: string;
     apiKey?: string;
@@ -31,18 +142,73 @@ export interface RuntimeOptions {
     journalStore?: JournalStore;
     /** 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/agent-runtime/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 {
-    tools: Tools;
+    /** 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;
     onEvent?: (event: any, 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;
 }
+/**
+ * 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;
+    /** question: { questions }; approval: { tool, source, arguments, argumentsHash }; form: { requestedSchema }; url: { url, origin }. */
+    detail: Record<string, any>;
+    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;
+}
+/** 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 the agent until it is deleted. Default 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>;
     systemPrompt?: string;
     name?: string;
     type?: string;
@@ -58,6 +224,83 @@ export interface CreateAgentOptions extends AgentOptions {
     mounts?: Mount[];
 }
 /** 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?: ("web_fetch" | "web_search" | "schedule")[];
+    /** 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;
+    }[];
+}
 export interface Mount {
     volumeId: string;
     path: string;
@@ -84,6 +327,7 @@ export interface VolumeFile {
     size: number;
     updatedAt: number;
     by?: string;
+    contentType: string;
 }
 export interface VolumeSnapshot {
     id: string;
@@ -107,9 +351,46 @@ export interface VolumeChanges {
     }[];
     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;
+}
 export interface AgentHistory {
     messages: AgentMessage[];
 }
+/**
+ * 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;
@@ -123,9 +404,17 @@ export interface RequestOptions {
     idempotencyKey?: string;
     timeoutMs?: number;
 }
+/** 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 {
     status: number;
     requestId?: string;
+    /** Milliseconds the runtime asked to wait before retrying (its Retry-After), for 429 and 503. */
+    retryAfterMs?: number;
     constructor(message: string, status?: number, requestId?: string);
 }
 declare class Transport {
@@ -133,12 +422,16 @@ declare class Transport {
     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 (volume file contents). */
+    /**
+     * 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;
+        body?: Uint8Array | Blob;
         headers?: Record<string, string>;
     }): Promise<Response>;
+    private transfer;
 }
 /** Trusted-backend SDK. Only createAgent needs the operator key. */
 export declare class AgentRuntime {
@@ -154,9 +447,34 @@ export declare class AgentRuntime {
     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>;
+    /** 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.
+     */
+    /** 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 {
@@ -188,8 +506,10 @@ export declare class VolumeHandle {
         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?: {
@@ -197,19 +517,19 @@ export declare class VolumeHandle {
     }): 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>;
 }
+/** The client's event cursor, saved so a restarted client resumes where it was. */
 export type Journal = {
     version: 1;
     cursor: number;
-    calls: Record<string, {
-        state: "started" | "done";
-        outcome?: Outcome;
-    }>;
 };
 /** Stores must resolve only once the complete snapshot is committed. Use one active client per agent. */
 export interface JournalStore {
@@ -217,18 +537,56 @@ export interface JournalStore {
     save(sessionId: string, journal: Journal): Promise<void>;
 }
 export declare function memoryJournalStore(): JournalStore;
+/**
+ * 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 {
     readonly session: SessionCredentials;
     readonly tools: Tools;
+    private server;
     private readonly transport;
     private readonly store;
     private journal;
     private loaded?;
     private saving;
     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;
-    private readonly delivered;
+    /** The event stream's connection, named in the MCP messages this client sends back. */
+    private connection?;
     private stream?;
     private loop?;
     private closed;
@@ -249,31 +607,63 @@ export declare class AgentClient {
     }): Promise<any>;
     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;
-    private dispatch;
-    private runTool;
+    /**
+     * 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;
     request(method: RequestMethod, params?: Record<string, unknown>, options?: RequestOptions): Promise<any>;
     /** Observe an already accepted request. This never submits or re-executes work. */
     waitForRequest(id: string, options?: {
         timeoutMs?: number;
     }): 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.
+     */
     prompt(text: string, options?: RequestOptions & {
+        files?: Attachment[];
         images?: ImageContent[];
+        actor?: string;
+        from?: Sender;
     }): 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. `images` (base64 blocks) are sent inline and saved as files.
+     */
+    private message;
+    private attach;
     history(): Promise<AgentHistory>;
-    continue(options?: RequestOptions): Promise<any>;
-    steer(text: string): Promise<any>;
-    followUp(text: string): Promise<any>;
+    continue(options?: RequestOptions & {
+        actor?: string;
+    }): Promise<any>;
+    steer(text: string, options?: {
+        from?: Sender;
+        files?: Attachment[];
+    }): Promise<any>;
+    followUp(text: string, options?: {
+        from?: Sender;
+        files?: Attachment[];
+    }): 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>;
     execute(code: string, options?: RequestOptions & {
         timeoutMs?: number;
         executionTimeoutMs?: number;
+        actor?: string;
     }): Promise<any>;
     /**
      * Wake this agent later: with `text` it gets a prompt, with `code` it runs sandboxed
@@ -291,6 +681,13 @@ export declare class AgentClient {
     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>;
     close(): Promise<void>;
     destroy(): Promise<void>;