@camelai/agent-runtime 0.4.0 → 0.5.0

package/README.md

@@ -69,9 +69,36 @@ import { fromMcpServer } from "@camelai/agent-runtime/mcp";
 const agent = await runtime.createAgent({ name: "Inventory planner", mcp: await fromMcpServer(server) });
 ```
 
+Serving tools to many users' agents from one server? `serveTools` from
+`@camelai/agent-runtime/server` serves the same `tools` over HTTP and verifies the
+runtime's signed identity token on every call, so each tool knows who it is for:
+
+```ts
+import { serveTools } from "@camelai/agent-runtime/server";
+
+const tools = {
+  list_todos: tool({
+    description: "The current user's to-dos", input: schema.Object({}),
+    execute: (_args, { identity }) => db.todos(identity!.user, identity!.context.team),
+  }),
+};
+export default { fetch: serveTools(tools, { runtime: "https://agents.camelai.dev" }) };
+```
+
+Name it in a definition with `mcpServers: [{ name: "todos", url, auth: { type: "runtime" } }]`,
+create agents with a `subject` and `context`, and prompt with `from` or `actor`.
+`testRuntime()` from `@camelai/agent-runtime/testing` signs tokens for tests.
+
 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.
 
+A turn can also wait for the user: a tool with `needsApproval: true` is approved
+before each call, and `ctx.confirm`, `ctx.ask` and `ctx.requireUrl` ask from
+inside a tool. `prompt()` then resolves with `stopped: "input_required"` and the
+`inputs`; answer them with `onInput`, or later with `agent.answer(inputId, { action: "accept" })`,
+and the turn resumes. An ask ends the call, and the tool runs again with the
+answer, so everything before an ask runs twice: ask first, act after.
+
 ## Console and REST API
 
 Sign in at https://agents.camelai.dev/console with GitHub (qaml-ai members) to add

package/dist/clients/node.d.ts

@@ -3,6 +3,14 @@ export * from "./typescript.ts";
 export interface RuntimeOptions extends PortableRuntimeOptions {
     stateDirectory?: string;
 }
+/**
+ * A fetch-style handler (e.g. `serveTools(...)`) as a `node:http` request listener:
+ * `createServer(nodeListener(serveTools(tools, { runtime })))`. `origin` is your public URL when the
+ * server is behind a proxy (tokens are checked against it); by default the request's Host.
+ */
+export declare function nodeListener(handler: (request: Request) => Promise<Response>, options?: {
+    origin?: string;
+}): (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => Promise<void>;
 export declare function fileJournalStore(directory: string): JournalStore;
 export declare class AgentRuntime extends PortableAgentRuntime {
     constructor(options?: RuntimeOptions);

package/dist/clients/node.js

@@ -1,9 +1,42 @@
 /** Node/Bun convenience entry. The portable SDK itself imports no Node modules. */
+import { openAsBlob } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { writeDurableJson } from "../shared/durable-json.js";
 import { AgentRuntime as PortableAgentRuntime } from "./typescript.js";
 export * from "./typescript.js";
+/**
+ * A fetch-style handler (e.g. `serveTools(...)`) as a `node:http` request listener:
+ * `createServer(nodeListener(serveTools(tools, { runtime })))`. `origin` is your public URL when the
+ * server is behind a proxy (tokens are checked against it); by default the request's Host.
+ */
+export function nodeListener(handler, options = {}) {
+    return async (req, res) => {
+        try {
+            const origin = options.origin ?? `http://${req.headers.host ?? "localhost"}`;
+            const controller = new AbortController();
+            res.on("close", () => { if (!res.writableFinished)
+                controller.abort(); });
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(req.headers))
+                if (value !== undefined)
+                    headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+            const chunks = [];
+            if (req.method !== "GET" && req.method !== "HEAD")
+                for await (const chunk of req)
+                    chunks.push(chunk);
+            const body = chunks.length ? new Uint8Array(Buffer.concat(chunks)) : undefined;
+            const response = await handler(new Request(new URL(req.url ?? "/", origin), { method: req.method, headers, body, signal: controller.signal }));
+            res.writeHead(response.status, Object.fromEntries(response.headers));
+            res.end(response.body ? Buffer.from(await response.arrayBuffer()) : undefined);
+        }
+        catch (error) {
+            if (!res.headersSent)
+                res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: String(error).slice(0, 500) }));
+        }
+    };
+}
 export function fileJournalStore(directory) {
     const root = resolve(directory);
     const path = (id) => {
@@ -27,7 +60,7 @@ export function fileJournalStore(directory) {
 }
 export class AgentRuntime extends PortableAgentRuntime {
     constructor(options = {}) {
-        super({ ...options, url: options.url ?? process.env.AGENT_URL,
+        super({ ...options, url: options.url ?? process.env.AGENT_URL, openFile: options.openFile ?? (path => openAsBlob(path)),
             apiKey: options.apiKey ?? process.env.AGENT_RUNTIME_TOKEN,
             journalStore: options.journalStore ?? fileJournalStore(options.stateDirectory ?? process.env.AGENT_CLIENT_STATE_DIR ?? ".agent-runtime/client-sdk"),
         });

package/dist/clients/server.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Serving tools to agents from your own server, for many users at once. The runtime calls a tool
+ * source with `auth: { type: "runtime" }` with a token it signs for each request, naming the agent,
+ * whom it acts for and who is acting; these helpers verify it and hand your tools the identity.
+ * Portable: fetch-style handlers and WebCrypto (Ed25519), so it runs on Workers, Node 22+, Bun and Deno.
+ *
+ *   export default { fetch: serveTools(tools, { runtime: "https://agents.camelai.dev" }) };
+ */
+import { type RuntimeIdentity, type ToolServer, type Tools } from "./typescript.ts";
+export type { RuntimeIdentity };
+export interface VerifyOptions {
+    /** The runtime's URL (e.g. https://agents.camelai.dev): its keys are at /.well-known/jwks.json. */
+    runtime: string;
+    /** The issuer tokens must name; the runtime's URL by default. */
+    issuer?: string;
+    /** What tokens must be for: your server's URL as the runtime calls it (a definition's `url`, or its `audience`). */
+    audience: string | string[];
+    /** Fetches the runtime's keys; `testRuntime()` supplies one. */
+    fetch?: typeof globalThis.fetch;
+    /** Seconds of clock skew allowed (default 30). */
+    clockTolerance?: number;
+}
+/** A token that is missing, malformed, unsigned by the runtime, for another server, or expired. */
+export declare class RuntimeTokenError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify an identity token and return who the call is for. Checks the signature against the runtime's
+ * published Ed25519 keys (EdDSA only), the issuer, that the audience is yours, and the times.
+ */
+export declare function verifyRuntimeToken(token: string, options: VerifyOptions): Promise<RuntimeIdentity & {
+    claims: Record<string, unknown>;
+}>;
+/** A request's bearer token, if it has one. */
+export declare function bearerToken(request: Request): string | undefined;
+/**
+ * For servers built with the MCP SDK (or Cloudflare's `createMcpHandler`): verify the request's
+ * token and return MCP's `AuthInfo`, with the identity in `extra.identity` (the token's claims in `extra.claims`). Pass it as the request's
+ * `auth` (`transport.handleRequest(Object.assign(req, { auth }), ...)`, or `createMcpHandler(server,
+ * { authContext })`), and a tool handler reads `runtimeIdentity(extra)`.
+ */
+export declare function runtimeAuth(request: Request, options: Omit<VerifyOptions, "audience"> & {
+    audience?: string | string[];
+}): Promise<{
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt: number;
+    extra: {
+        identity: RuntimeIdentity;
+        claims: Record<string, unknown>;
+    };
+}>;
+/** The identity `runtimeAuth` put in an MCP SDK tool handler's `extra`. */
+export declare function runtimeIdentity(extra: {
+    authInfo?: {
+        extra?: Record<string, unknown>;
+    };
+} | undefined): RuntimeIdentity | undefined;
+export interface ServeOptions extends Omit<VerifyOptions, "audience"> {
+    /** What tokens must be for; by default the request's URL (origin and path), which is what the runtime signs for unless your definition sets `audience`. */
+    audience?: string | string[];
+    /** Serve MCP's protected-resource metadata (RFC 9728) naming the runtime as the issuer; on by default. */
+    metadata?: boolean;
+    /** The name and version `initialize` reports. */
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Serve tools (`tool({...})` definitions, or any `ToolServer`) as a stateless MCP server over
+ * Streamable HTTP, for the runtime to call with its identity tokens: a fetch handler
+ * (`(Request) => Promise<Response>`). Every call's context carries the verified `identity`;
+ * requests without a valid token get a 401. The same tools can be attached to an agent instead.
+ */
+export declare function serveTools(tools: Tools | ToolServer, options: ServeOptions): (request: Request) => Promise<Response>;

package/dist/clients/server.js

@@ -0,0 +1,171 @@
+/**
+ * Serving tools to agents from your own server, for many users at once. The runtime calls a tool
+ * source with `auth: { type: "runtime" }` with a token it signs for each request, naming the agent,
+ * whom it acts for and who is acting; these helpers verify it and hand your tools the identity.
+ * Portable: fetch-style handlers and WebCrypto (Ed25519), so it runs on Workers, Node 22+, Bun and Deno.
+ *
+ *   export default { fetch: serveTools(tools, { runtime: "https://agents.camelai.dev" }) };
+ */
+import { answerMcp, identityFromClaims, toolContext, toolServer } from "./typescript.js";
+/** A token that is missing, malformed, unsigned by the runtime, for another server, or expired. */
+export class RuntimeTokenError extends Error {
+    constructor(message) { super(message); this.name = "RuntimeTokenError"; }
+}
+const trim = (url) => url.replace(/\/+$/, "");
+const decoder = new TextDecoder();
+function base64url(text) {
+    const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(text.length / 4) * 4, "="));
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+const part = (text) => { try {
+    return JSON.parse(decoder.decode(base64url(text)));
+}
+catch {
+    throw new RuntimeTokenError("Malformed token");
+} };
+const keySets = new WeakMap();
+async function publicKey(url, kid, fetcher) {
+    let sets = keySets.get(fetcher);
+    if (!sets)
+        keySets.set(fetcher, sets = new Map());
+    let set = sets.get(url);
+    if (!set)
+        sets.set(url, set = { keys: new Map(), fetched: 0 });
+    const age = Date.now() - set.fetched;
+    if (age > 300_000 || (!set.keys.has(kid) && age > 10_000)) {
+        set.loading ??= (async () => {
+            const response = await fetcher(url, { headers: { Accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+            if (!response.ok)
+                throw new RuntimeTokenError(`Could not read the runtime's keys (${url}: HTTP ${response.status})`);
+            const body = await response.json();
+            const keys = new Map();
+            for (const jwk of body.keys ?? []) {
+                if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.kid !== "string")
+                    continue;
+                keys.set(jwk.kid, await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]));
+            }
+            set.keys = keys;
+            set.fetched = Date.now();
+        })().finally(() => { set.loading = undefined; });
+        await set.loading;
+    }
+    const key = set.keys.get(kid);
+    if (!key)
+        throw new RuntimeTokenError("Token signed with a key the runtime does not publish");
+    return key;
+}
+/**
+ * Verify an identity token and return who the call is for. Checks the signature against the runtime's
+ * published Ed25519 keys (EdDSA only), the issuer, that the audience is yours, and the times.
+ */
+export async function verifyRuntimeToken(token, options) {
+    const pieces = token.split(".");
+    if (pieces.length !== 3)
+        throw new RuntimeTokenError("Malformed token");
+    const header = part(pieces[0]);
+    if (header.alg !== "EdDSA" || typeof header.kid !== "string")
+        throw new RuntimeTokenError("Token is not an EdDSA token with a key id");
+    const runtime = trim(options.runtime);
+    const key = await publicKey(`${runtime}/.well-known/jwks.json`, header.kid, options.fetch ?? globalThis.fetch);
+    const valid = await crypto.subtle.verify({ name: "Ed25519" }, key, base64url(pieces[2]), new TextEncoder().encode(`${pieces[0]}.${pieces[1]}`));
+    if (!valid)
+        throw new RuntimeTokenError("Token signature does not verify");
+    const claims = part(pieces[1]);
+    const now = Math.floor(Date.now() / 1000), skew = options.clockTolerance ?? 30;
+    if (claims.iss !== trim(options.issuer ?? runtime))
+        throw new RuntimeTokenError("Token is from another issuer");
+    const audiences = new Set((Array.isArray(options.audience) ? options.audience : [options.audience]).map(trim));
+    if (![claims.aud].flat().some(audience => typeof audience === "string" && audiences.has(trim(audience))))
+        throw new RuntimeTokenError("Token is for another server");
+    if (typeof claims.exp !== "number" || claims.exp + skew < now)
+        throw new RuntimeTokenError("Token has expired");
+    if (typeof claims.nbf === "number" && claims.nbf - skew > now)
+        throw new RuntimeTokenError("Token is not valid yet");
+    if (typeof claims.iat === "number" && claims.iat - skew > now)
+        throw new RuntimeTokenError("Token is issued in the future");
+    return { ...identityFromClaims(claims), claims };
+}
+/** A request's bearer token, if it has one. */
+export function bearerToken(request) {
+    const match = /^Bearer\s+(\S+)$/i.exec(request.headers.get("authorization") ?? "");
+    return match?.[1];
+}
+/** Your server's URL as the runtime calls it, from a request: its origin and path, without query. */
+const requestAudience = (request) => { const url = new URL(request.url); return `${url.origin}${url.pathname}`; };
+/**
+ * For servers built with the MCP SDK (or Cloudflare's `createMcpHandler`): verify the request's
+ * token and return MCP's `AuthInfo`, with the identity in `extra.identity` (the token's claims in `extra.claims`). Pass it as the request's
+ * `auth` (`transport.handleRequest(Object.assign(req, { auth }), ...)`, or `createMcpHandler(server,
+ * { authContext })`), and a tool handler reads `runtimeIdentity(extra)`.
+ */
+export async function runtimeAuth(request, options) {
+    const token = bearerToken(request);
+    if (!token)
+        throw new RuntimeTokenError("No bearer token");
+    const { claims, ...identity } = await verifyRuntimeToken(token, { ...options, audience: options.audience ?? requestAudience(request) });
+    return { token, clientId: identity.agent, scopes: [], expiresAt: claims.exp, extra: { identity: identity, claims } };
+}
+/** The identity `runtimeAuth` put in an MCP SDK tool handler's `extra`. */
+export function runtimeIdentity(extra) {
+    return extra?.authInfo?.extra?.identity;
+}
+/**
+ * Serve tools (`tool({...})` definitions, or any `ToolServer`) as a stateless MCP server over
+ * Streamable HTTP, for the runtime to call with its identity tokens: a fetch handler
+ * (`(Request) => Promise<Response>`). Every call's context carries the verified `identity`;
+ * requests without a valid token get a 401. The same tools can be attached to an agent instead.
+ */
+export function serveTools(tools, options) {
+    const server = typeof tools.listTools === "function" && typeof tools.callTool === "function" ? tools : toolServer(tools);
+    const issuer = trim(options.issuer ?? options.runtime);
+    const json = (status, body, headers = {}) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", ...headers } });
+    const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+    return async (request) => {
+        const url = new URL(request.url);
+        // RFC 9728: the metadata for https://host/mcp is at https://host/.well-known/oauth-protected-resource/mcp.
+        if (options.metadata !== false && request.method === "GET" && url.pathname.startsWith(WELL_KNOWN)) {
+            const resource = `${url.origin}${url.pathname.slice(WELL_KNOWN.length) || "/"}`;
+            return json(200, { resource, authorization_servers: [issuer], bearer_methods_supported: ["header"], resource_name: options.serverInfo?.name ?? "agent-runtime tools" });
+        }
+        if (request.method !== "POST")
+            return json(405, { error: "Use POST: this MCP server is stateless and has no event stream" }, { Allow: "POST" });
+        let identity;
+        try {
+            const token = bearerToken(request);
+            if (!token)
+                throw new RuntimeTokenError("No bearer token");
+            const { claims: _claims, ...verified } = await verifyRuntimeToken(token, { ...options, audience: options.audience ?? requestAudience(request) });
+            identity = verified;
+        }
+        catch (error) {
+            if (!(error instanceof RuntimeTokenError))
+                throw error;
+            const metadata = options.metadata !== false ? `, resource_metadata="${url.origin}${WELL_KNOWN}${url.pathname === "/" ? "" : url.pathname}"` : "";
+            return json(401, { error: error.message }, { "WWW-Authenticate": `Bearer error="invalid_token"${metadata}` });
+        }
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return json(400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+        }
+        const messages = Array.isArray(body) ? body : [body];
+        const answers = await Promise.all(messages.map(async (message) => {
+            if (!message || typeof message.method !== "string")
+                return message && "id" in message ? { jsonrpc: "2.0", id: message.id ?? null, error: { code: -32600, message: "Invalid request" } } : undefined;
+            if (message.id === undefined)
+                return undefined;
+            const answer = await answerMcp(message, server, params => toolContext(params, String(message.id), request.signal, identity), options.serverInfo);
+            return { jsonrpc: "2.0", id: message.id, ...answer };
+        }));
+        const replies = answers.filter(answer => answer !== undefined);
+        // Only notifications: accepted, nothing to answer.
+        if (!replies.length)
+            return new Response(null, { status: 202 });
+        return json(200, Array.isArray(body) ? replies : replies[0]);
+    };
+}

package/dist/clients/testing.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Test your tool server's authorization without a runtime: `testRuntime()` signs identity tokens
+ * with a key of its own and serves its keys to `serveTools` / `verifyRuntimeToken` through `fetch`.
+ *
+ *   const runtime = await testRuntime();
+ *   const handler = serveTools(tools, runtime.options);
+ *   const result = await runtime.callTool(handler, "https://app.test/mcp", "list_todos", {}, { subject: "alice" });
+ */
+export interface TestIdentity {
+    subject?: string;
+    actor?: string;
+    tenant?: string;
+    agent?: string;
+    definition?: string;
+    context?: Record<string, unknown>;
+    origin?: Record<string, unknown>;
+}
+export declare function testRuntime(options?: {
+    url?: string;
+}): Promise<{
+    url: string;
+    jwk: {
+        crv?: string;
+        d?: string;
+        dp?: string;
+        dq?: string;
+        e?: string;
+        ext?: boolean;
+        k?: string;
+        key_ops?: string[];
+        kty?: string;
+        n?: string;
+        oth?: RsaOtherPrimesInfo[];
+        p?: string;
+        q?: string;
+        qi?: string;
+        x?: string;
+        y?: string;
+        kid: `${string}-${string}-${string}-${string}-${string}`;
+        alg: string;
+        use: string;
+    };
+    token: (identity: TestIdentity, audience: string, overrides?: {
+        claims?: Record<string, unknown>;
+        header?: Record<string, unknown>;
+        expiresIn?: number;
+    }) => Promise<string>;
+    request: (serverUrl: string, message: unknown, identity?: TestIdentity | null) => Promise<Request>;
+    callTool: (handler: (request: Request) => Promise<Response>, serverUrl: string, name: string, args: Record<string, unknown>, identity: TestIdentity) => Promise<{
+        content: Array<Record<string, unknown>>;
+        structuredContent?: Record<string, unknown>;
+        isError?: boolean;
+    }>;
+    fetch: typeof fetch;
+    options: {
+        runtime: string;
+        fetch: typeof fetch;
+    };
+}>;

package/dist/clients/testing.js

@@ -0,0 +1,53 @@
+const encode = (value) => base64url(new TextEncoder().encode(typeof value === "string" ? value : JSON.stringify(value)));
+function base64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export async function testRuntime(options = {}) {
+    const url = (options.url ?? "https://runtime.test").replace(/\/+$/, "");
+    const { privateKey, publicKey } = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);
+    const kid = crypto.randomUUID();
+    const jwk = { ...await crypto.subtle.exportKey("jwk", publicKey), kid, alg: "EdDSA", use: "sig" };
+    const jwksUrl = `${url}/.well-known/jwks.json`;
+    /** Serves this runtime's keys; any other URL goes to the real fetch. */
+    const fetcher = async (input, init) => {
+        const target = input instanceof Request ? input.url : String(input);
+        if (target === jwksUrl)
+            return new Response(JSON.stringify({ keys: [jwk] }), { headers: { "Content-Type": "application/json" } });
+        return globalThis.fetch(input, init);
+    };
+    /** A token for `audience` as the runtime would sign it; `overrides` change claims or the header, to test rejections. */
+    async function token(identity, audience, overrides = {}) {
+        const now = Math.floor(Date.now() / 1000);
+        const agent = identity.agent ?? "client_test";
+        const claims = {
+            iss: url, aud: audience, sub: identity.subject ?? agent, tenant: identity.tenant ?? "test", agent,
+            ...(identity.definition ? { definition: identity.definition } : {}), ...(identity.context ? { ctx: identity.context } : {}),
+            ...(identity.actor ? { act: identity.actor } : {}), ...(identity.origin ? { origin: identity.origin } : {}),
+            iat: now, exp: now + (overrides.expiresIn ?? 120), jti: crypto.randomUUID(), ...overrides.claims,
+        };
+        const signed = `${encode({ alg: "EdDSA", kid, typ: "JWT", ...overrides.header })}.${encode(claims)}`;
+        const signature = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, privateKey, new TextEncoder().encode(signed)));
+        return `${signed}.${base64url(signature)}`;
+    }
+    /** A JSON-RPC POST to `serverUrl`, carrying a token for `identity` (none if `identity` is null). */
+    async function request(serverUrl, message, identity = {}) {
+        const headers = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
+        if (identity)
+            headers.Authorization = `Bearer ${await token(identity, serverUrl)}`;
+        return new Request(serverUrl, { method: "POST", headers, body: JSON.stringify(message) });
+    }
+    /** Call one tool through a fetch handler as `identity`: its CallToolResult, or the JSON-RPC error thrown. */
+    async function callTool(handler, serverUrl, name, args, identity) {
+        const response = await handler(await request(serverUrl, { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, identity));
+        const body = await response.json();
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}: ${body.error ?? JSON.stringify(body)}`);
+        if (body.error)
+            throw new Error(body.error.message);
+        return body.result;
+    }
+    return { url, jwk, token, request, callTool, fetch: fetcher, options: { runtime: url, fetch: fetcher } };
+}