@camelai/agent-runtime 0.4.0 → 0.5.0

package/dist/clients/typescript.js

@@ -2,29 +2,120 @@ 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/";
-const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+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 ? { _meta: { ...(tool.exposure ? { [`${META}exposure`]: tool.exposure } : {}), ...(tool.executionMode ? { [`${META}executionMode`]: tool.executionMode } : {}) } } : {}),
+            ...(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 };
@@ -56,6 +147,8 @@ function retryAfter(response) {
 const RATE_LIMIT_ATTEMPTS = 8;
 const byteLength = (value) => new TextEncoder().encode(value).byteLength;
 const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/** 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();
@@ -102,15 +195,51 @@ class Transport {
             }
         }
     }
-    /** 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. */
@@ -123,7 +252,7 @@ export class AgentRuntime {
         if (!key)
             throw new AgentError("Set apiKey to provision an agent");
         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() });
+        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) {
@@ -139,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); }
@@ -150,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 {
@@ -174,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();
     }
@@ -197,6 +349,33 @@ 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;
@@ -207,6 +386,10 @@ export class AgentClient {
     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();
@@ -226,6 +409,9 @@ export class AgentClient {
         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);
@@ -370,8 +556,16 @@ export class AgentClient {
     async receive(event) {
         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);
@@ -383,6 +577,20 @@ 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)
@@ -404,31 +612,13 @@ export class AgentClient {
             return;
         }
         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 ?? {};
+        const controller = new AbortController();
+        if (message.method === "tools/call")
+            this.active.set(key, controller);
         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) } });
+            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);
@@ -454,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) {
@@ -484,18 +674,69 @@ 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 { tools, mcp, ...rest } = options;
@@ -511,7 +752,7 @@ export class AgentClient {
         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
@@ -525,6 +766,10 @@ 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;

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

@@ -15,7 +15,7 @@ export interface SessionCredentials {
     token: string;
     expiresAt: number | null;
 }
-export type RequestMethod = "prompt" | "execute" | "status" | "abort" | "history" | "continue" | "steer" | "followUp" | "configure";
+export type RequestMethod = "prompt" | "execute" | "status" | "abort" | "history" | "continue" | "steer" | "followUp" | "configure" | "resume";
 export type RequestRecord = {
     id: string;
     startedAt?: number;
@@ -33,6 +33,10 @@ export type RequestRecord = {
     params?: unknown;
     /** Times a new owner resumed this run's turn after the node running it was lost. */
     resumes?: number;
+    /** Who the application said is acting in this run: passed to its tool calls (`act` in identity tokens). */
+    actor?: string;
+    /** A `resume` run's suspension: the run whose turn waited on human input, which this one continues. */
+    suspension?: string;
 };
 /** 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 = {
@@ -59,4 +63,6 @@ export interface ToolDefinition {
     resultFormat?: "json" | "content";
     exposure?: "direct" | "codemode" | "both";
     executionMode?: "sequential" | "parallel";
+    /** The user approves each call before it runs (a source's approval policy, or the tool's own needsApproval); such a tool is declared directly. */
+    needsApproval?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camelai/agent-runtime",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -28,6 +28,14 @@
     "./mcp": {
       "types": "./dist/clients/mcp.d.ts",
       "default": "./dist/clients/mcp.js"
+    },
+    "./server": {
+      "types": "./dist/clients/server.d.ts",
+      "default": "./dist/clients/server.js"
+    },
+    "./testing": {
+      "types": "./dist/clients/testing.d.ts",
+      "default": "./dist/clients/testing.js"
     }
   },
   "files": [