@camelai/agent-runtime 0.3.0 → 0.5.0

package/dist/clients/typescript.js

@@ -2,18 +2,153 @@ import { Type } from "typebox";
 import { Check } from "typebox/value";
 import { FRAME_BYTES } from "../shared/client-protocol.js";
 export { Type as schema };
+/** A runtime identity from its claims (a verified token's payload, or an attached call's `_meta`). */
+export function identityFromClaims(claims) {
+    const text = (value) => typeof value === "string" && value ? value : undefined;
+    const agent = text(claims.agent) ?? "";
+    const subject = text(claims.sub) ?? agent;
+    const actor = text(claims.act);
+    return {
+        user: actor ?? subject, subject, ...(actor ? { actor } : {}), tenant: text(claims.tenant) ?? "", agent,
+        ...(text(claims.definition) ? { definition: claims.definition } : {}),
+        context: isRecord(claims.ctx) ? claims.ctx : {}, ...(isRecord(claims.origin) ? { origin: claims.origin } : {}),
+        ...(isRecord(claims.approval) ? { approval: claims.approval } : {}),
+    };
+}
+/** Thrown by a ToolContext's asks: the call answers MCP's `input_required`, and runs again once the user answers. */
+export class InputRequired extends Error {
+    inputRequests;
+    /** The answers so far, which the runtime hands back on the next call (MCP's `requestState`). */
+    requestState;
+    constructor(inputRequests, requestState) {
+        super("Waiting for the user's input");
+        this.name = "InputRequired";
+        this.inputRequests = inputRequests;
+        if (requestState)
+            this.requestState = requestState;
+    }
+}
 /** Infer callback arguments from the schema; no manually duplicated argument type. */
 export function tool(definition) {
     return { ...definition, input: definition.input };
 }
+const META = "agent-runtime/";
+function isRecord(value) { return !!value && typeof value === "object" && !Array.isArray(value); }
+/**
+ * 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 function toolContext(params, fallbackId, signal, identity) {
+    const meta = isRecord(params._meta) ? params._meta : {};
+    const sent = isRecord(meta[`${META}identity`]) ? identityFromClaims(meta[`${META}identity`]) : undefined;
+    const who = identity ?? sent;
+    const origin = isRecord(meta[`${META}origin`]) ? meta[`${META}origin`] : who?.origin;
+    // Each round answers only its own ask: earlier answers come back in the state this call handed out.
+    let earlier = {};
+    try {
+        earlier = typeof params.requestState === "string" ? JSON.parse(atob(params.requestState)) : {};
+    }
+    catch { /* not ours: start over */ }
+    const responses = { ...isRecord(earlier) ? earlier : {}, ...isRecord(params.inputResponses) ? params.inputResponses : {} };
+    let asked = 0;
+    const request = async (input) => {
+        const key = `input_${++asked}`;
+        if (isRecord(responses[key]))
+            return responses[key];
+        throw new InputRequired({ [key]: { method: "elicitation/create", params: input } }, Object.keys(responses).length ? btoa(JSON.stringify(responses)) : undefined);
+    };
+    return {
+        callId: typeof meta[`${META}callId`] === "string" ? meta[`${META}callId`] : fallbackId, signal,
+        ...(typeof meta[`${META}toolCallId`] === "string" ? { toolCallId: meta[`${META}toolCallId`] } : {}),
+        ...(origin ? { origin } : {}), ...(who ? { identity: who } : {}),
+        confirm: async (message) => (await request({ mode: "form", message, requestedSchema: { type: "object", properties: {} } })).action === "accept",
+        ask: async (message, schema) => { const answer = await request({ mode: "form", message, requestedSchema: schema }); return answer.action === "accept" ? answer.content : undefined; },
+        requireUrl: async (url, message) => (await request({ mode: "url", message, url, elicitationId: `${fallbackId}-${asked + 1}` })).action === "accept",
+    };
+}
+/**
+ * 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 async function answerMcp(message, server, context, info = { name: "agent-runtime-sdk", version: "1.0.0" }) {
+    const params = isRecord(message.params) ? message.params : {};
+    if (message.method === "initialize")
+        return { result: { protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : "2025-06-18", capabilities: { tools: {} }, serverInfo: info } };
+    if (message.method === "ping")
+        return { result: {} };
+    if (message.method === "tools/list")
+        return { result: { tools: await server.listTools() } };
+    if (message.method !== "tools/call")
+        return { error: { code: -32601, message: `Unknown method ${message.method}` } };
+    try {
+        const result = await server.callTool(String(params.name), isRecord(params.arguments) ? params.arguments : {}, context(params));
+        if (!isRecord(result) || (!Array.isArray(result.content) && result.resultType !== "input_required") || byteLength(JSON.stringify(result)) > 1024 * 1024)
+            throw new Error("The MCP server must answer with a bounded CallToolResult");
+        return { result };
+    }
+    catch (error) {
+        return { error: { code: -32603, message: String(error).slice(0, 2048) } };
+    }
+}
+/** `tool({...})` definitions as an attached MCP server: JSON results become a text block (and structured content for objects). */
+export function toolServer(tools) {
+    return {
+        listTools: () => Object.entries(tools).map(([name, tool]) => ({
+            name, description: tool.description, inputSchema: tool.input,
+            ...(tool.exposure || tool.executionMode || tool.needsApproval ? { _meta: {
+                    ...(tool.exposure ? { [`${META}exposure`]: tool.exposure } : {}), ...(tool.executionMode ? { [`${META}executionMode`]: tool.executionMode } : {}),
+                    ...(tool.needsApproval ? { [`${META}needsApproval`]: true } : {}),
+                } } : {}),
+        })),
+        async callTool(name, args, context) {
+            const definition = tools[name];
+            if (!Object.hasOwn(tools, name) || !Check(definition.input, args))
+                throw new Error("Tool is missing or arguments failed validation");
+            context.signal.throwIfAborted();
+            // Not yet approved: the runtime asks the user, showing this call, and calls again once they approve.
+            const asks = typeof definition.needsApproval === "function" ? await definition.needsApproval(args, context) : definition.needsApproval;
+            if (asks && !context.identity?.approval)
+                return { resultType: "input_required", inputRequests: { approval: { method: `${META}approval` } } };
+            let result;
+            try {
+                result = await definition.execute(args, context);
+            }
+            catch (error) {
+                if (error instanceof InputRequired)
+                    return { resultType: "input_required", inputRequests: error.inputRequests, ...(error.requestState ? { requestState: error.requestState } : {}) };
+                if (context.signal.aborted)
+                    throw error;
+                return { content: [{ type: "text", text: String(error).slice(0, 2048) }], isError: true };
+            }
+            if (result === undefined || byteLength(JSON.stringify(result)) > 1024 * 1024)
+                throw new Error("Tool must return a bounded JSON value");
+            if (definition.resultFormat === "content")
+                return result;
+            return { content: [{ type: "text", text: JSON.stringify(result) }], ...(isRecord(result) ? { structuredContent: result } : {}) };
+        },
+    };
+}
 export class AgentError extends Error {
     status;
     requestId;
+    /** Milliseconds the runtime asked to wait before retrying (its Retry-After), for 429 and 503. */
+    retryAfterMs;
     constructor(message, status = 0, requestId) { super(message); this.name = "AgentError"; this.status = status; this.requestId = requestId; }
 }
+/** Retry-After as milliseconds (seconds or an HTTP date), capped so a bad value cannot stall a caller. */
+function retryAfter(response) {
+    const value = response.headers.get("retry-after");
+    if (value === null)
+        return undefined;
+    const ms = /^\d+$/.test(value.trim()) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+    return Number.isFinite(ms) ? Math.min(Math.max(0, ms), 60_000) : undefined;
+}
+/** A 429 (quota, or an agent's queue is full) was refused before anything happened, so any request may be retried after it. */
+const RATE_LIMIT_ATTEMPTS = 8;
 const byteLength = (value) => new TextEncoder().encode(value).byteLength;
 const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-const definitions = (tools) => Object.entries(tools).map(([name, tool]) => ({ name, description: tool.description, parameters: tool.input, ...(tool.resultFormat ? { resultFormat: tool.resultFormat } : {}), ...(tool.exposure ? { exposure: tool.exposure } : {}), ...(tool.executionMode ? { executionMode: tool.executionMode } : {}) }));
+/** A download's content type, without parameters (text is always UTF-8). */
+const contentTypeOf = (response) => (response.headers.get("content-type") ?? "application/octet-stream").split(";")[0].trim();
 async function rejectRedirect(response) {
     if (response.status >= 300 && response.status < 400) {
         await response.body?.cancel();
@@ -44,27 +179,67 @@ class Transport {
                     redirect: "manual", signal: AbortSignal.timeout(10_000),
                 });
                 await rejectRedirect(response);
-                const value = await response.json();
+                const value = await (response.ok ? response.json() : response.json().catch(() => ({})));
                 if (!response.ok)
-                    throw new AgentError(value.error ?? `HTTP ${response.status}`, response.status);
+                    throw Object.assign(new AgentError(value.error ?? `HTTP ${response.status}`, response.status), { retryAfterMs: retryAfter(response) });
                 return value;
             }
             catch (error) {
-                if (!retry || attempt >= 3 || (error instanceof AgentError && error.status < 500))
+                const limited = error instanceof AgentError && error.status === 429;
+                if (limited ? attempt >= RATE_LIMIT_ATTEMPTS - 1 : !retry || attempt >= 3 || (error instanceof AgentError && error.status < 500))
                     throw error;
-                await pause(100 * 2 ** attempt);
+                // Honour the runtime's Retry-After, with jitter so refused callers do not return together; else back off exponentially.
+                const backoff = Math.min(10_000, (limited ? 500 : 100) * 2 ** attempt);
+                const hinted = error instanceof AgentError ? error.retryAfterMs : undefined;
+                await pause(hinted !== undefined ? hinted + Math.random() * Math.min(1000, backoff) : backoff);
             }
         }
     }
-    /** 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.
+     */
     async raw(path, token, init = {}) {
-        const response = await this.fetcher(this.base + path, { method: init.method ?? "GET", body: init.body, headers: { Authorization: `Bearer ${token}`, ...init.headers }, redirect: "manual" });
-        await rejectRedirect(response);
-        if (!response.ok) {
-            const value = await response.json().catch(() => ({}));
-            throw new AgentError(value.error ?? `HTTP ${response.status}`, response.status);
+        // A 503 (the agent is moving, a node draining) was refused before anything happened; a read may be retried after anything.
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.transfer(path, token, init);
+            }
+            catch (error) {
+                const status = error instanceof AgentError ? error.status : 500;
+                if (attempt >= 3 || !(status === 503 || (status >= 500 && (init.method ?? "GET") === "GET")))
+                    throw error;
+                await pause(error.retryAfterMs ?? 100 * 2 ** attempt);
+            }
+        }
+    }
+    async transfer(path, token, init) {
+        const controller = new AbortController();
+        let timer;
+        const wait = (ms) => { clearTimeout(timer); timer = setTimeout(() => controller.abort(new AgentError("File transfer stalled")), ms); };
+        wait(init.body === undefined ? 30_000 : 15 * 60_000);
+        try {
+            const response = await this.fetcher(this.base + path, { method: init.method ?? "GET", body: init.body, headers: { Authorization: `Bearer ${token}`, ...init.headers }, redirect: "manual", signal: controller.signal });
+            await rejectRedirect(response);
+            if (!response.ok) {
+                const value = await response.json().catch(() => ({}));
+                throw Object.assign(new AgentError(value.error ?? `HTTP ${response.status}`, response.status), { retryAfterMs: retryAfter(response) });
+            }
+            if (!response.body) {
+                clearTimeout(timer);
+                return response;
+            }
+            wait(30_000);
+            const body = response.body.pipeThrough(new TransformStream({
+                transform(chunk, stream) { wait(30_000); stream.enqueue(chunk); },
+                flush() { clearTimeout(timer); },
+            }));
+            return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            throw error;
         }
-        return response;
     }
 }
 /** Trusted-backend SDK. Only createAgent needs the operator key. */
@@ -76,7 +251,8 @@ export class AgentRuntime {
         const key = this.options.apiKey;
         if (!key)
             throw new AgentError("Set apiKey to provision an agent");
-        const session = await this.transport.json("/client-sessions", key, "POST", { tools: definitions(options.tools), ...(options.mounts !== undefined ? { mounts: options.mounts } : {}), ...(options.model !== undefined ? { model: options.model } : {}), ...(options.thinkingLevel !== undefined ? { thinkingLevel: options.thinkingLevel } : {}), ...(options.initialMessages !== undefined ? { initialMessages: options.initialMessages } : {}), ...(options.name !== undefined ? { name: options.name } : {}), ...(options.type !== undefined ? { type: options.type } : {}), ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}), ...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}) }, true, { "Idempotency-Key": options.idempotencyKey ?? globalThis.crypto.randomUUID() });
+        const server = options.mcp ?? toolServer(options.tools ?? {});
+        const session = await this.transport.json("/client-sessions", key, "POST", { mcp: { tools: await server.listTools() }, ...(options.subject !== undefined ? { subject: options.subject } : {}), ...(options.context !== undefined ? { context: options.context } : {}), ...(options.definition !== undefined ? { definition: options.definition } : {}), ...(options.mounts !== undefined ? { mounts: options.mounts } : {}), ...(options.model !== undefined ? { model: options.model } : {}), ...(options.thinkingLevel !== undefined ? { thinkingLevel: options.thinkingLevel } : {}), ...(options.initialMessages !== undefined ? { initialMessages: options.initialMessages } : {}), ...(options.name !== undefined ? { name: options.name } : {}), ...(options.type !== undefined ? { type: options.type } : {}), ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}), ...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}) }, true, { "Idempotency-Key": options.idempotencyKey ?? globalThis.crypto.randomUUID() });
         return this.connectAgent(session, options);
     }
     async connectAgent(session, options) {
@@ -92,7 +268,7 @@ export class AgentRuntime {
     }
     operator() {
         if (!this.options.apiKey)
-            throw new AgentError("Set apiKey to manage volumes and mounts");
+            throw new AgentError("Set apiKey to manage definitions, volumes and mounts");
         return this.options.apiKey;
     }
     createVolume(options = {}) { return this.transport.json("/v1/volumes", this.operator(), "POST", options, false); }
@@ -103,9 +279,29 @@ export class AgentRuntime {
             throw new AgentError("Invalid volume id");
         return new VolumeHandle(this.transport, this.operator(), id);
     }
+    /**
+     * Definitions: reusable agent configurations with their tool sources (MCP servers, OpenAPI
+     * specs, built-ins). Make agents from one with `createAgent({ definition: id })`.
+     */
+    createDefinition(input) { return this.transport.json("/v1/definitions", this.operator(), "POST", input, false); }
+    /** Replace the fields given (null removes one); `apply: "all"` also reconfigures its live agents between their turns. */
+    updateDefinition(id, input) { return this.transport.json(`/v1/definitions/${encodeURIComponent(id)}`, this.operator(), "PATCH", input, false); }
+    definition(id) { return this.transport.json(`/v1/definitions/${encodeURIComponent(id)}`, this.operator()); }
+    definitions() { return this.transport.json("/v1/definitions", this.operator()); }
+    deleteDefinition(id) { return this.transport.json(`/v1/definitions/${encodeURIComponent(id)}`, this.operator(), "DELETE", undefined, false); }
     mounts(agentId) { return this.transport.json(`/v1/agents/${encodeURIComponent(agentId)}/mounts`, this.operator()); }
     /** Replace an agent's mounts; an idle agent restarts so its tools describe them. */
     setMounts(agentId, mounts) { return this.transport.json(`/v1/agents/${encodeURIComponent(agentId)}/mounts`, this.operator(), "PUT", { mounts }, false); }
+    /**
+     * 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) { return this.transport.json(`/v1/inputs${state ? `?state=${state}` : ""}`, this.operator()); }
+    async toolSources(agentId, options = {}) {
+        const query = [options.schemas && "schemas=true", options.refresh && "refresh=true"].filter(Boolean).join("&");
+        return (await this.transport.json(`/v1/agents/${encodeURIComponent(agentId)}${query ? `?${query}` : ""}`, this.operator())).toolSources;
+    }
 }
 /** Files are versioned: pass `version` to write or remove only if nobody changed the file since (0: must not exist). */
 export class VolumeHandle {
@@ -127,18 +323,21 @@ export class VolumeHandle {
         const query = new URLSearchParams(Object.entries(options).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
         return this.transport.json(this.path(`/files${query.size ? `?${query}` : ""}`), this.token);
     }
+    /** Without `contentType`, the runtime sniffs it from the file's first bytes and name. */
     async write(path, data, options = {}) {
         const body = typeof data === "string" ? new TextEncoder().encode(data) : data;
-        const headers = { "Content-Type": "application/octet-stream", ...(options.version === 0 ? { "If-None-Match": "*" } : options.version !== undefined ? { "If-Match": `"${options.version}"` } : {}) };
+        const headers = { "Content-Type": options.contentType ?? "application/octet-stream", ...(options.version === 0 ? { "If-None-Match": "*" } : options.version !== undefined ? { "If-Match": `"${options.version}"` } : {}) };
         return (await this.transport.raw(this.file(path), this.token, { method: "PUT", body, headers })).json();
     }
     /** A file's bytes, or `range` of them ([start, end) in bytes). */
     async read(path, options = {}) {
         const [start, end] = options.range ?? [];
         const response = await this.transport.raw(this.file(path), this.token, start !== undefined ? { headers: { Range: `bytes=${start}-${end !== undefined ? end - 1 : ""}` } } : {});
-        return { data: new Uint8Array(await response.arrayBuffer()), version: Number(response.headers.get("etag")?.replaceAll('"', "")) };
+        return { data: new Uint8Array(await response.arrayBuffer()), version: Number(response.headers.get("etag")?.replaceAll('"', "")), contentType: contentTypeOf(response) };
     }
     async readText(path) { return new TextDecoder().decode((await this.read(path)).data); }
+    /** A signed URL to download (GET) or upload (PUT) one file without a token. */
+    link(path, options = {}) { return this.transport.json(this.path("/links"), this.token, "POST", { path, ...options }, false); }
     async remove(path, options = {}) {
         return (await this.transport.raw(this.file(path), this.token, { method: "DELETE", headers: options.version !== undefined ? { "If-Match": `"${options.version}"` } : {} })).json();
     }
@@ -150,18 +349,52 @@ export function memoryJournalStore() {
         async save(id, journal) { entries.set(id, structuredClone(journal)); },
     };
 }
+const encodePath = (path) => path.split("/").filter(Boolean).map(encodeURIComponent).join("/");
+/**
+ * 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 class AgentFiles {
+    transport;
+    token;
+    base;
+    constructor(transport, token, base) { this.transport = transport; this.token = token; this.base = base; }
+    /** Files under `path` (default: the first mount), in path order, a page at a time. */
+    list(options = {}) {
+        const query = new URLSearchParams(Object.entries(options).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+        return this.transport.json(`${this.base}/files${query.size ? `?${query}` : ""}`, this.token);
+    }
+    async download(path) {
+        const response = await this.transport.raw(`${this.base}/files/${encodePath(path)}`, this.token);
+        return { data: new Uint8Array(await response.arrayBuffer()), contentType: contentTypeOf(response), version: Number(response.headers.get("etag")?.replaceAll('"', "")) };
+    }
+    /** Write a file into a writable mount; without `contentType` the runtime sniffs it. */
+    async upload(path, data, options = {}) {
+        const body = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        return (await this.transport.raw(`${this.base}/files/${encodePath(path)}`, this.token, { method: "PUT", body, headers: options.contentType ? { "Content-Type": options.contentType } : {} })).json();
+    }
+    /** A signed URL to download (GET) or upload (PUT) one file without a token, e.g. for a browser or another service. */
+    link(path, options = {}) { return this.transport.json(`${this.base}/links`, this.token, "POST", { path, ...options }, false); }
+}
 export class AgentClient {
     session;
     tools;
+    server;
     transport;
     store;
-    journal = { version: 1, cursor: 0, calls: {} };
+    journal = { version: 1, cursor: 0 };
     loaded;
     saving = Promise.resolve();
     options;
+    openFile;
+    pollMs;
+    /** The agent's files: list, download, upload and link. */
+    files;
     pending = new Map();
+    /** Tool calls running, by JSON-RPC id, so the runtime can cancel them. */
     active = new Map();
-    delivered = new Set();
+    /** The event stream's connection, named in the MCP messages this client sends back. */
+    connection;
     stream;
     loop;
     closed = false;
@@ -172,21 +405,25 @@ export class AgentClient {
             throw new AgentError("Invalid session id");
         this.session = { id: session.id, token: session.token, expiresAt: session.expiresAt };
         this.tools = { ...options.tools };
+        this.server = options.mcp ?? toolServer(this.tools);
         this.options = options;
         this.transport = new Transport(runtime);
         this.store = runtime.journalStore ?? memoryJournalStore();
+        this.openFile = runtime.openFile;
+        this.pollMs = runtime.pollMs ?? 30_000;
+        this.files = new AgentFiles(this.transport, this.session.token, this.path());
     }
     async load() {
         const journal = await this.store.load(this.session.id);
         if (!journal)
             return;
-        if (journal.version !== 1 || !Number.isSafeInteger(journal.cursor) || journal.cursor < 0 || !journal.calls || typeof journal.calls !== "object")
+        if (journal.version !== 1 || !Number.isSafeInteger(journal.cursor) || journal.cursor < 0)
             throw new AgentError("Unsupported client journal");
-        this.journal = structuredClone(journal);
+        this.journal = { version: 1, cursor: journal.cursor };
     }
     save() {
         const snapshot = structuredClone(this.journal);
-        // Serialize commits so concurrent tool completions cannot overwrite newer receipts.
+        // Serialize commits so an older cursor never overwrites a newer one.
         this.saving = this.saving.then(() => this.store.save(this.session.id, snapshot));
         return this.saving;
     }
@@ -251,13 +488,22 @@ export class AgentClient {
                             if (!data)
                                 continue;
                             if (lines.includes("event: ready")) {
+                                this.connection = JSON.parse(data).connection;
                                 await this.sync();
                                 backoff = 250;
                                 this.ready.resolve();
                                 this.options.onConnection?.(true);
                                 continue;
                             }
-                            const id = Number(lines.find(line => line.startsWith("id:"))?.slice(3));
+                            const idLine = lines.find(line => line.startsWith("id:"));
+                            // The runtime's MCP messages are live only: no id, never replayed, no cursor.
+                            if (!idLine) {
+                                const event = JSON.parse(data);
+                                if (event.type === "mcp")
+                                    void this.mcp(event.message).catch(error => this.report(error));
+                                continue;
+                            }
+                            const id = Number(idLine.slice(3));
                             if (!Number.isSafeInteger(id) || id <= 0)
                                 throw new AgentError("Invalid SSE cursor");
                             if (id <= this.journal.cursor)
@@ -308,14 +554,18 @@ export class AgentClient {
         return this.transport.json(this.path('/metadata'), this.session.token, 'POST', metadata);
     }
     async receive(event) {
-        if (event.type === "tool_call")
-            this.dispatch(event.call);
-        else if (event.type === "tool_cancel")
-            this.active.get(event.id)?.controller.abort();
-        else if (event.type === "response")
+        if (event.type === "response")
             this.settle(event.id, event.outcome);
-        else if (event.type === "event")
+        else if (event.type === "event") {
             await this.options.onEvent?.(event.event, event.requestId);
+            const onInput = this.options.onInput;
+            if (onInput && event.event?.type === "input_required")
+                void (async () => {
+                    const answer = await onInput(event.event.input, event.requestId);
+                    if (answer)
+                        await this.answer(event.event.input.id, answer);
+                })().catch(error => this.report(error));
+        }
     }
     settle(id, value) {
         const waiter = this.pending.get(id);
@@ -327,78 +577,52 @@ export class AgentClient {
         else
             waiter.resolve(value.result);
     }
+    /**
+     * 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.
+     */
+    async outcome(id, result) {
+        const poll = setInterval(() => void this.requestStatus(id).then(record => { if (record.outcome)
+            this.settle(id, record.outcome); }, () => { }), this.pollMs);
+        try {
+            return await result;
+        }
+        finally {
+            clearInterval(poll);
+        }
+    }
     async sync() {
         const state = await this.outcomes();
         for (const request of state.requests)
             if (request.outcome)
                 this.settle(request.id, request.outcome);
-        for (const call of state.calls)
-            this.dispatch(call);
         return state;
     }
-    dispatch(call) {
-        if (this.closed || this.active.has(call.id) || this.delivered.has(call.id) || ["completed", "cancelled"].includes(call.state))
+    /**
+     * 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".
+     */
+    async mcp(message) {
+        if (typeof message.method !== "string")
             return;
-        const controller = new AbortController();
-        // Defer execution until the active entry exists; replay can arrive immediately.
-        const task = Promise.resolve().then(() => this.runTool(call, controller)).catch(error => this.report(error)).finally(() => this.active.delete(call.id));
-        this.active.set(call.id, { controller, task });
-    }
-    async runTool(call, controller) {
-        let receipt = this.journal.calls[call.id];
-        if (receipt?.state === "done") {
-            await this.http(`/calls/${call.id}/outcome`, "POST", receipt.outcome);
-            this.delivered.add(call.id);
+        if (message.id === undefined) {
+            if (message.method === "notifications/cancelled")
+                this.active.get(String(message.params?.requestId))?.abort();
             return;
         }
-        if (call.state === "uncertain")
-            return; // Already settled as unknown; never execute again.
-        let value;
-        if (call.state === "started")
-            value = { error: "The application lost this tool call's outcome; it may or may not have taken effect", uncertain: true };
-        else {
-            this.journal.calls[call.id] = { state: "started" };
-            await this.save();
-            try {
-                // Claim is deliberately NOT retried. A lost acknowledgement is ambiguous.
-                const claim = await this.http(`/calls/${call.id}/claim`, "POST", {}, false);
-                if (!claim.execute) {
-                    if (claim.call.state !== "started")
-                        return;
-                    value = { error: "Tool execution was already claimed; outcome unknown", uncertain: true };
-                }
-                else {
-                    const timer = setTimeout(() => controller.abort(), Math.max(1, call.deadline - Date.now()));
-                    // A callback that ignores cancellation must not keep a closed client's process alive until the deadline.
-                    timer.unref?.();
-                    try {
-                        const definition = this.tools[call.name];
-                        if (!Object.hasOwn(this.tools, call.name) || !Check(definition.input, call.args))
-                            throw new Error("Tool is missing or arguments failed validation");
-                        controller.signal.throwIfAborted();
-                        const result = await definition.execute(call.args, { callId: call.id, toolCallId: call.toolCallId, signal: controller.signal, ...(call.origin ? { origin: call.origin } : {}) });
-                        if (result === undefined || byteLength(JSON.stringify(result)) > 1024 * 1024)
-                            throw new Error("Tool must return a bounded JSON value");
-                        value = { result };
-                    }
-                    catch (error) {
-                        value = { error: String(error).slice(0, 2048), ...(controller.signal.aborted ? { uncertain: true } : {}) };
-                    }
-                    finally {
-                        clearTimeout(timer);
-                    }
-                }
-            }
-            catch (error) {
-                value = { error: `Execution claim failed: ${String(error).slice(0, 1800)}`, uncertain: true };
-            }
+        const connection = this.connection;
+        const key = String(message.id);
+        const controller = new AbortController();
+        if (message.method === "tools/call")
+            this.active.set(key, controller);
+        try {
+            const answer = await answerMcp(message, this.server, params => toolContext(params, key, controller.signal));
+            await this.transport.json(this.path("/mcp"), this.session.token, "POST", { jsonrpc: "2.0", id: message.id, ...answer }, true, { "X-Agent-Connection": connection ?? "" });
+        }
+        finally {
+            this.active.delete(key);
         }
-        // Persist before POST; reconnect resends this receipt, never the side effect.
-        receipt = { state: "done", outcome: value };
-        this.journal.calls[call.id] = receipt;
-        await this.save();
-        await this.http(`/calls/${call.id}/outcome`, "POST", value);
-        this.delivered.add(call.id);
     }
     async request(method, params = {}, options = {}) {
         if (this.closed || this.fatal)
@@ -420,7 +644,7 @@ export class AgentClient {
             const record = await this.http("/requests", "POST", { id, method, params });
             if (record.outcome)
                 this.settle(id, record.outcome);
-            return await deferred.promise;
+            return await this.outcome(id, deferred.promise);
         }
         catch (error) {
             if (error instanceof AgentError) {
@@ -450,30 +674,85 @@ export class AgentClient {
             const record = await this.requestStatus(id);
             if (record.outcome)
                 this.settle(id, record.outcome);
-            return await deferred.promise;
+            return await this.outcome(id, deferred.promise);
         }
         finally {
             clearTimeout(timer);
             this.pending.delete(id);
         }
     }
-    prompt(text, options) { return this.request("prompt", { text, ...(options?.images ? { images: options.images } : {}) }, options); }
+    /**
+     * `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, options) {
+        return this.message("prompt", text, options, { ...(options?.actor ? { actor: options.actor } : {}) });
+    }
+    /**
+     * 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.
+     */
+    async message(method, text, options, extra = {}) {
+        const id = options?.idempotencyKey ?? globalThis.crypto.randomUUID();
+        const files = options?.files?.length ? await this.attach(id, options.files) : undefined;
+        return this.request(method, { text, ...(files ? { files } : {}), ...(options?.images ? { images: options.images } : {}), ...extra, ...(options?.from ? { from: options.from } : {}) }, { ...options, idempotencyKey: id });
+    }
+    async attach(requestId, files) {
+        const names = new Set();
+        const attached = [];
+        for (const [index, file] of files.entries()) {
+            if (isRecord(file) && "path" in file && typeof file.path === "string" && !("data" in file)) {
+                attached.push({ path: file.path });
+                continue;
+            }
+            let data, name, contentType;
+            if (typeof file === "string") {
+                if (!this.openFile)
+                    throw new AgentError("Attaching a local path needs the Node entry (@camelai/agent-runtime/node); pass bytes or a Blob instead");
+                data = await this.openFile(file);
+                name = file.split(/[\\/]/).pop();
+            }
+            else if (file instanceof Uint8Array || file instanceof Blob) {
+                data = file;
+                name = file.name;
+                contentType = file instanceof Blob && file.type ? file.type : undefined;
+            }
+            else {
+                const entry = file;
+                ({ data, name } = entry);
+                contentType = entry.contentType ?? (data instanceof Blob && data.type ? data.type : undefined);
+            }
+            // Each file in a request needs its own name: they share uploads/<request>/.
+            const base = name || `attachment-${index + 1}`;
+            let unique = base;
+            for (let n = 2; names.has(unique); n++)
+                unique = base.replace(/(\.[^.]*)?$/, extension => `-${n}${extension}`);
+            names.add(unique);
+            const response = await this.transport.raw(this.path(`/uploads/${encodeURIComponent(requestId)}/${encodeURIComponent(unique)}`), this.session.token, { method: "PUT", body: data, headers: contentType ? { "Content-Type": contentType } : {} });
+            attached.push({ path: (await response.json()).path });
+        }
+        return attached;
+    }
     history() { return this.http("/history"); }
-    continue(options) { return this.request("continue", {}, options); }
-    steer(text) { return this.request("steer", { text }); }
-    followUp(text) { return this.request("followUp", { text }); }
+    continue(options) { return this.request("continue", options?.actor ? { actor: options.actor } : {}, options); }
+    steer(text, options) { return this.message("steer", text, options); }
+    followUp(text, options) { return this.message("followUp", text, options); }
     /** Change the prompt, thinking level, tools, or model ("provider/model-id") between runs. */
     async configure(options) {
-        const result = await this.request("configure", { ...options, ...(options.tools ? { tools: definitions(options.tools) } : {}) });
-        if (options.tools) {
+        const { tools, mcp, ...rest } = options;
+        const server = mcp ?? (tools ? toolServer(tools) : undefined);
+        const result = await this.request("configure", { ...rest, ...(server ? { mcp: { tools: await server.listTools() } } : {}) });
+        if (tools) {
             for (const key of Object.keys(this.tools))
                 delete this.tools[key];
-            Object.assign(this.tools, options.tools);
+            Object.assign(this.tools, tools);
         }
+        if (server)
+            this.server = mcp ?? toolServer(this.tools);
         return result;
     }
     execute(code, options) {
-        return this.request("execute", { code, ...(options?.executionTimeoutMs ? { timeoutMs: options.executionTimeoutMs } : {}) }, options);
+        return this.request("execute", { code, ...(options?.executionTimeoutMs ? { timeoutMs: options.executionTimeoutMs } : {}), ...(options?.actor ? { actor: options.actor } : {}) }, options);
     }
     /**
      * Wake this agent later: with `text` it gets a prompt, with `code` it runs sandboxed
@@ -487,11 +766,15 @@ export class AgentClient {
     status() { return this.request("status"); }
     abort() { return this.request("abort"); }
     requestStatus(id) { return this.http(`/requests/${encodeURIComponent(id)}`); }
+    /** Answer an input the agent waits on. `request` is the run resuming its turn, once its last input is answered. */
+    answer(inputId, answer) { return this.http(`/inputs/${encodeURIComponent(inputId)}`, "POST", answer); }
+    /** The agent's inputs, newest first: `pending` ones, say. */
+    inputs(state) { return this.http(`/inputs${state ? `?state=${state}` : ""}`); }
     outcomes() { return this.http("/state"); }
     async close() {
         this.closed = true;
         this.stream?.abort();
-        for (const { controller } of this.active.values())
+        for (const controller of this.active.values())
             controller.abort();
         for (const [id, waiter] of this.pending)
             waiter.reject(new AgentError("Client closed; request may still be running", 0, id));