@camelai/agent-runtime 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ Upgrade with `npm update @camelai/agent-runtime`.
 
 The SDK has one runtime dependency (`typebox`). Its message and model types come
 from Pi; for full typing of history and events, also install
-`@earendil-works/pi-agent-core@0.80.6` and `@earendil-works/pi-ai@0.80.6` as dev
+`@earendil-works/pi-agent-core@0.87.1` and `@earendil-works/pi-ai@0.87.1` as dev
 dependencies. Without them those types resolve to `any` (with `skipLibCheck`).
 
 ## Use
@@ -59,6 +59,16 @@ const agent = await runtime.createAgent({
 await agent.prompt("Plan restocks for anything below target.");
 ```
 
+Already have an MCP server? Attach it instead of (or alongside) `tools`: the SDK
+talks to it in memory, and the same server can later run remotely as a definition's
+`mcpServers` entry without changing its tools. Install `@modelcontextprotocol/sdk` too.
+
+```ts
+import { fromMcpServer } from "@camelai/agent-runtime/mcp";
+
+const agent = await runtime.createAgent({ name: "Inventory planner", mcp: await fromMcpServer(server) });
+```
+
 Switch models between turns with `await agent.configure({ model: "openai/gpt-5.2" })`;
 the history carries over. Your tenant needs a key for that provider.
 
@@ -80,7 +90,7 @@ The routes are `/v1/me`, `/v1/providers` (+ `/:provider/key`), `/v1/models`,
 `/v1/tokens` and `/v1/usage`; see `src/api.ts`.
 
 Save `agent.session` (it contains a scoped credential) to reconnect later with
-`runtime.connectAgent(session, { tools })`. Pass the same `idempotencyKey` to
+`runtime.connectAgent(session, { tools })` (or `{ mcp }`). Pass the same `idempotencyKey` to
 `createAgent` to get the same agent back instead of a new one.
 
 `@camelai/agent-runtime` (without `/node`) is the portable build for Workers and

package/dist/clients/mcp.d.ts

@@ -0,0 +1,13 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolServer } from "./typescript.ts";
+/**
+ * Attach an MCP SDK server (`McpServer` or low-level `Server`) to an agent: pass the result
+ * as `mcp` to `createAgent`, `connectAgent` or `configure`. The SDK talks to the server in
+ * memory, so the same server can later run remotely, as a definition's `mcpServers` entry,
+ * without changing its tools. `callId`, `toolCallId` and `origin` reach its handlers as
+ * `_meta["agent-runtime/…"]`.
+ */
+export declare function fromMcpServer(server: McpServer | Server): Promise<ToolServer & {
+    close(): Promise<void>;
+}>;

package/dist/clients/mcp.js

@@ -0,0 +1,38 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+/** Tool names the runtime accepts; others are renamed, and calls map back. */
+const safeName = (name) => (/^[A-Za-z]/.test(name) ? name : `t_${name}`).replace(/[^A-Za-z0-9_]/g, "_").slice(0, 80);
+/**
+ * Attach an MCP SDK server (`McpServer` or low-level `Server`) to an agent: pass the result
+ * as `mcp` to `createAgent`, `connectAgent` or `configure`. The SDK talks to the server in
+ * memory, so the same server can later run remotely, as a definition's `mcpServers` entry,
+ * without changing its tools. `callId`, `toolCallId` and `origin` reach its handlers as
+ * `_meta["agent-runtime/…"]`.
+ */
+export async function fromMcpServer(server) {
+    const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverSide);
+    const client = new Client({ name: "agent-runtime-sdk", version: "1.0.0" });
+    await client.connect(clientSide);
+    const names = new Map();
+    return {
+        async listTools() {
+            const tools = [];
+            let cursor;
+            do {
+                const page = await client.listTools(cursor ? { cursor } : {});
+                for (const tool of page.tools) {
+                    names.set(safeName(tool.name), tool.name);
+                    tools.push({ ...tool, name: safeName(tool.name) });
+                }
+                cursor = page.nextCursor;
+            } while (cursor);
+            return tools;
+        },
+        async callTool(name, args, context) {
+            const _meta = { "agent-runtime/callId": context.callId, ...(context.toolCallId ? { "agent-runtime/toolCallId": context.toolCallId } : {}), ...(context.origin ? { "agent-runtime/origin": context.origin } : {}) };
+            return await client.callTool({ name: names.get(name) ?? name, arguments: args, _meta }, undefined, { signal: context.signal });
+        },
+        async close() { await client.close(); },
+    };
+}

package/dist/clients/typescript.d.ts

@@ -1,7 +1,7 @@
 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 };
 export interface ToolContext {
@@ -24,6 +24,32 @@ export declare function tool<S extends TSchema>(definition: Omit<Tool<Static<S>>
     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. */
+export interface CallToolResult {
+    content: Array<Record<string, unknown>>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/**
+ * 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>;
+}
+/** `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;
@@ -33,7 +59,10 @@ export interface RuntimeOptions {
     fetch?: typeof globalThis.fetch;
 }
 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>;
     onConnection?: (connected: boolean) => void;
     onError?: (error: Error) => void;
@@ -41,6 +70,12 @@ export interface AgentOptions {
 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;
     systemPrompt?: string;
@@ -126,6 +161,8 @@ export interface RequestOptions {
 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 {
@@ -203,13 +240,10 @@ export declare class VolumeHandle {
         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 {
@@ -220,6 +254,7 @@ export declare function memoryJournalStore(): JournalStore;
 export declare class AgentClient {
     readonly session: SessionCredentials;
     readonly tools: Tools;
+    private server;
     private readonly transport;
     private readonly store;
     private journal;
@@ -227,8 +262,10 @@ export declare class AgentClient {
     private saving;
     private readonly options;
     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;
@@ -250,8 +287,12 @@ export declare class AgentClient {
     private receive;
     private settle;
     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?: {
@@ -269,6 +310,7 @@ export declare class AgentClient {
         systemPrompt?: string;
         thinkingLevel?: ThinkingLevel;
         tools?: Tools;
+        mcp?: ToolServer;
         model?: string;
     }): Promise<any>;
     execute(code: string, options?: RequestOptions & {

package/dist/clients/typescript.js

@@ -6,14 +6,56 @@ export { Type as schema };
 export function tool(definition) {
     return { ...definition, input: definition.input };
 }
+const META = "agent-runtime/";
+const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** `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 ? { _meta: { ...(tool.exposure ? { [`${META}exposure`]: tool.exposure } : {}), ...(tool.executionMode ? { [`${META}executionMode`]: tool.executionMode } : {}) } } : {}),
+        })),
+        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();
+            let result;
+            try {
+                result = await definition.execute(args, context);
+            }
+            catch (error) {
+                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 } : {}) }));
 async function rejectRedirect(response) {
     if (response.status >= 300 && response.status < 400) {
         await response.body?.cancel();
@@ -44,15 +86,19 @@ 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);
             }
         }
     }
@@ -76,7 +122,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.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) {
@@ -153,15 +200,18 @@ export function memoryJournalStore() {
 export class AgentClient {
     session;
     tools;
+    server;
     transport;
     store;
-    journal = { version: 1, cursor: 0, calls: {} };
+    journal = { version: 1, cursor: 0 };
     loaded;
     saving = Promise.resolve();
     options;
     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,6 +222,7 @@ 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();
@@ -180,13 +231,13 @@ export class AgentClient {
         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 +302,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,11 +368,7 @@ 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")
             await this.options.onEvent?.(event.event, event.requestId);
@@ -332,73 +388,51 @@ export class AgentClient {
         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 reply = (answer) => this.transport.json(this.path("/mcp"), this.session.token, "POST", { jsonrpc: "2.0", id: message.id, ...answer }, true, { "X-Agent-Connection": connection ?? "" });
+        const params = message.params ?? {};
+        if (message.method === "initialize")
+            return reply({ result: { protocolVersion: params.protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "agent-runtime-sdk", version: "1.0.0" } } });
+        if (message.method === "ping")
+            return reply({ result: {} });
+        if (message.method === "tools/list")
+            return reply({ result: { tools: await this.server.listTools() } });
+        if (message.method !== "tools/call")
+            return reply({ error: { code: -32601, message: `Unknown method ${message.method}` } });
+        const controller = new AbortController();
+        const key = String(message.id);
+        this.active.set(key, controller);
+        const meta = params._meta ?? {};
+        try {
+            const result = await this.server.callTool(params.name, params.arguments ?? {}, {
+                callId: meta["agent-runtime/callId"] ?? key, signal: controller.signal,
+                ...(meta["agent-runtime/toolCallId"] ? { toolCallId: meta["agent-runtime/toolCallId"] } : {}), ...(meta["agent-runtime/origin"] ? { origin: meta["agent-runtime/origin"] } : {}),
+            });
+            if (!isRecord(result) || !Array.isArray(result.content) || byteLength(JSON.stringify(result)) > 1024 * 1024)
+                throw new Error("The MCP server must answer with a bounded CallToolResult");
+            await reply({ result });
+        }
+        catch (error) {
+            await reply({ error: { code: -32603, message: String(error).slice(0, 2048) } });
+        }
+        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)
@@ -464,12 +498,16 @@ export class AgentClient {
     followUp(text) { return this.request("followUp", { text }); }
     /** 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) {
@@ -491,7 +529,7 @@ export class AgentClient {
     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));

package/dist/shared/client-protocol.d.ts

@@ -16,22 +16,6 @@ export interface SessionCredentials {
     expiresAt: number | null;
 }
 export type RequestMethod = "prompt" | "execute" | "status" | "abort" | "history" | "continue" | "steer" | "followUp" | "configure";
-export type CallRecord = {
-    id: string;
-    toolCallId?: string;
-    requestId?: string;
-    createdAt?: number;
-    name: string;
-    args: Record<string, unknown>;
-    deadline: number;
-    /** `uncertain`: claimed, but the outcome was lost; the model was told it is unknown. */
-    state: "offered" | "started" | "completed" | "cancelled" | "uncertain";
-    outcome?: Outcome;
-    /** A result that arrived after the call was already settled as uncertain. */
-    lateOutcome?: Outcome;
-    /** Where the turn came from, set by the runtime (e.g. a channel and its sender), so tools can authorize. */
-    origin?: Record<string, unknown>;
-};
 export type RequestRecord = {
     id: string;
     startedAt?: number;
@@ -47,14 +31,11 @@ export type RequestRecord = {
     began?: number;
     /** Kept until the run begins, so a queued run survives a restart and runs exactly once. */
     params?: unknown;
+    /** Times a new owner resumed this run's turn after the node running it was lost. */
+    resumes?: number;
 };
+/** Events on an agent's stream. `mcp` carries the runtime's JSON-RPC messages to the application's attached MCP server: live only, with no id, never replayed. */
 export type ClientEvent = {
-    type: "tool_call";
-    call: CallRecord;
-} | {
-    type: "tool_cancel";
-    id: string;
-} | {
     type: "event";
     requestId: string;
     event: any;
@@ -62,10 +43,12 @@ export type ClientEvent = {
     type: "response";
     id: string;
     outcome: Outcome;
+} | {
+    type: "mcp";
+    message: Record<string, unknown>;
 };
 export type SessionState = {
     cursor: number;
-    calls: CallRecord[];
     requests: RequestRecord[];
 };
 /** A tool an application offers its agent; shared by the SDKs and the runtime. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camelai/agent-runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "SDK for the camelAI hosted agent runtime: define tools in your app, and the runtime runs the model loop, history and sandbox.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,10 @@
     "./node": {
       "types": "./dist/clients/node.d.ts",
       "default": "./dist/clients/node.js"
+    },
+    "./mcp": {
+      "types": "./dist/clients/mcp.d.ts",
+      "default": "./dist/clients/mcp.js"
     }
   },
   "files": [
@@ -38,5 +42,13 @@
   "dependencies": {
     "typebox": "1.1.38"
   },
-  "homepage": "https://agents.camelai.dev"
+  "homepage": "https://agents.camelai.dev",
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  }
 }