@camelai/run 0.0.0 → 0.11.1

package/dist/clients/typescript.js

@@ -0,0 +1,1037 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { FRAME_BYTES } from "../shared/client-protocol.js";
+export { Type as schema };
+/** A runtime identity from its claims (a verified token's payload, or an attached call's `_meta`). */
+export function identityFromClaims(claims) {
+    const text = (value) => typeof value === "string" && value ? value : undefined;
+    const agent = text(claims.agent) ?? "";
+    const subject = text(claims.sub) ?? agent;
+    const actor = text(claims.act);
+    return {
+        user: actor ?? subject, subject, ...(actor ? { actor } : {}), tenant: text(claims.tenant) ?? "", agent,
+        ...(text(claims.definition) ? { definition: claims.definition } : {}),
+        context: isRecord(claims.ctx) ? claims.ctx : {}, ...(isRecord(claims.origin) ? { origin: claims.origin } : {}),
+        ...(isRecord(claims.approval) ? { approval: claims.approval } : {}),
+    };
+}
+/** Thrown by a ToolContext's asks: the call answers MCP's `input_required`, and runs again once the user answers. */
+export class InputRequired extends Error {
+    inputRequests;
+    /** The answers so far, which the runtime hands back on the next call (MCP's `requestState`). */
+    requestState;
+    constructor(inputRequests, requestState) {
+        super("Waiting for the user's input");
+        this.name = "InputRequired";
+        this.inputRequests = inputRequests;
+        if (requestState)
+            this.requestState = requestState;
+    }
+}
+/** Infer callback arguments from the schema; no manually duplicated argument type. */
+export function tool(definition) {
+    return { ...definition, input: definition.input };
+}
+const META = "agent-runtime/";
+function isRecord(value) { return !!value && typeof value === "object" && !Array.isArray(value); }
+/**
+ * A call's context from its params: ids, origin, and the identity the runtime sent in `_meta` (or
+ * `identity`, from a verified token); its asks answer from the retry's `inputResponses`, by position.
+ */
+export function toolContext(params, fallbackId, signal, identity, notify) {
+    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);
+    };
+    const callId = typeof meta[`${META}callId`] === "string" ? meta[`${META}callId`] : fallbackId;
+    const toolCallId = typeof meta[`${META}toolCallId`] === "string" ? meta[`${META}toolCallId`] : undefined;
+    const innerCallId = typeof meta[`${META}innerCallId`] === "string" ? meta[`${META}innerCallId`] : undefined;
+    // The runtime's stable key; from a runtime that sends none, the model's call (and the code's call within it).
+    const idempotencyKey = typeof meta[`${META}idempotencyKey`] === "string" ? meta[`${META}idempotencyKey`]
+        : toolCallId ? [who?.agent ?? "", toolCallId, innerCallId ?? ""].join(":") : callId;
+    const progressToken = meta.progressToken;
+    let reported = 0;
+    return {
+        callId, idempotencyKey, signal,
+        ...(toolCallId ? { toolCallId } : {}),
+        progress(update) {
+            if (progressToken === undefined || !notify || signal.aborted)
+                return;
+            const value = typeof update === "string" ? { progress: ++reported, message: update } : { ...update, progress: Math.max(update.progress, reported) };
+            reported = value.progress;
+            notify({ jsonrpc: "2.0", method: "notifications/progress", params: { progressToken, ...value } });
+        },
+        ...(origin ? { origin } : {}), ...(who ? { identity: who } : {}),
+        confirm: async (message) => (await request({ mode: "form", message, requestedSchema: { type: "object", properties: {} } })).action === "accept",
+        ask: async (message, schema) => { const answer = await request({ mode: "form", message, requestedSchema: schema }); return answer.action === "accept" ? answer.content : undefined; },
+        requireUrl: async (url, message) => (await request({ mode: "url", message, url, elicitationId: `${fallbackId}-${asked + 1}` })).action === "accept",
+    };
+}
+/**
+ * Answer one MCP JSON-RPC request as a tool server: initialize, ping, tools/list and tools/call.
+ * Both an attached server (answering over the agent's connection) and `serveTools` (over HTTP) use it.
+ */
+export async function answerMcp(message, server, context, info = { name: "agent-runtime-sdk", version: "1.0.0" }) {
+    const params = isRecord(message.params) ? message.params : {};
+    if (message.method === "initialize")
+        return { result: { protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : "2025-06-18", capabilities: { tools: {} }, serverInfo: info } };
+    if (message.method === "ping")
+        return { result: {} };
+    if (message.method === "tools/list")
+        return { result: { tools: await server.listTools() } };
+    if (message.method !== "tools/call")
+        return { error: { code: -32601, message: `Unknown method ${message.method}` } };
+    try {
+        const result = await server.callTool(String(params.name), isRecord(params.arguments) ? params.arguments : {}, context(params));
+        if (!isRecord(result) || (!Array.isArray(result.content) && result.resultType !== "input_required") || byteLength(JSON.stringify(result)) > 1024 * 1024)
+            throw new Error("The MCP server must answer with a bounded CallToolResult");
+        return { result };
+    }
+    catch (error) {
+        return { error: { code: -32603, message: String(error).slice(0, 2048) } };
+    }
+}
+/** `tool({...})` definitions as an attached MCP server: JSON results become a text block (and structured content for objects). */
+export function toolServer(tools) {
+    return {
+        listTools: () => Object.entries(tools).map(([name, tool]) => ({
+            name, description: tool.description, inputSchema: tool.input,
+            ...(tool.exposure || tool.executionMode || tool.needsApproval || tool.timeoutMs ? { _meta: {
+                    ...(tool.exposure ? { [`${META}exposure`]: tool.exposure } : {}), ...(tool.executionMode ? { [`${META}executionMode`]: tool.executionMode } : {}),
+                    ...(tool.needsApproval ? { [`${META}needsApproval`]: true } : {}), ...(tool.timeoutMs ? { [`${META}timeoutMs`]: tool.timeoutMs } : {}),
+                } } : {}),
+        })),
+        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 };
+            }
+            // A tool that returns nothing did its work: the model hears null, not a failure it would retry.
+            if (result === undefined)
+                result = null;
+            if (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 } : {}) };
+        },
+    };
+}
+/** The hosted runtime; `url` points elsewhere (a self-hosted runtime, or http://127.0.0.1:8790 in development). */
+export const DEFAULT_URL = "https://run.camelai.com";
+export class AgentError extends Error {
+    /** The HTTP status, or 0 for a failure that is not an HTTP response's (a run's, the connection's). */
+    status;
+    requestId;
+    /** A stable name for the failure where the runtime gives one, e.g. APPLICATION_NOT_CONNECTED. */
+    code;
+    /** The runtime could not tell whether the work took effect (a restart cut it short). */
+    uncertain;
+    /** 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; }
+}
+/** A run that failed (`agent.run` throws it unless `throwOnError: false`): `run` is how it ended, `code` why. */
+export class RunError extends AgentError {
+    run;
+    constructor(run) {
+        super(run.error?.message ?? "The run failed", 0, run.id);
+        this.name = "RunError";
+        this.run = run;
+        this.code = run.error?.code;
+        if (run.error?.uncertain)
+            this.uncertain = true;
+    }
+}
+/** An error body's stable name: its `code`, or the prefix of its message (`APPLICATION_CONNECTED: …`). */
+function codeOf(value) {
+    if (typeof value.code === "string")
+        return { code: value.code };
+    const prefix = typeof value.error === "string" ? /^([A-Z][A-Z0-9_]+):/.exec(value.error)?.[1] : undefined;
+    return prefix ? { code: prefix } : {};
+}
+/** 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));
+/** 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();
+/** A downloaded file's version, from X-File-Version: proxies may rewrite the ETag (W/"n" once gzipped). */
+const fileVersion = (response) => Number(response.headers.get("x-file-version"));
+async function rejectRedirect(response) {
+    if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new AgentError("Runtime redirects are not allowed", response.status);
+    }
+}
+/**
+ * Hosts plain http:// may reach: loopback, and names and addresses only a private network resolves
+ * (a Docker Compose service, `*.internal`, `*.local`, 10/8, 172.16/12, 192.168/16), as for a runtime kept private.
+ */
+export function privateHost(hostname) {
+    const host = hostname.toLowerCase().replace(/\.$/, "");
+    if (["localhost", "[::1]"].includes(host) || /\.(?:localhost|internal|local)$/.test(host))
+        return true;
+    const ip = /^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/.exec(host);
+    if (ip) {
+        const [a, b] = [Number(ip[1]), Number(ip[2])];
+        return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+    }
+    return !host.includes(".") && !host.startsWith("[");
+}
+class Transport {
+    base;
+    fetcher;
+    constructor(options) {
+        const url = new URL(options.url ?? DEFAULT_URL);
+        if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
+            throw new Error("Use a runtime origin without credentials, path, or query");
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && privateHost(url.hostname)))
+            throw new Error("Remote runtimes require https://; http:// only on a private network (localhost, a single-label or .internal name, a private IP)");
+        this.base = url.origin;
+        const fetcher = options.fetch;
+        this.fetcher = fetcher ? (input, init) => fetcher(input, init) : globalThis.fetch.bind(globalThis);
+    }
+    async json(path, token, method = "GET", body, retry = true, headers = {}) {
+        const data = body === undefined ? undefined : JSON.stringify(body);
+        if (data && byteLength(data) > FRAME_BYTES)
+            throw new AgentError("Request exceeds transport limit");
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await this.fetcher(this.base + path, {
+                    method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers }, body: data,
+                    redirect: "manual", signal: AbortSignal.timeout(10_000),
+                });
+                await rejectRedirect(response);
+                const value = await (response.ok ? response.json() : response.json().catch(() => ({})));
+                if (!response.ok)
+                    throw Object.assign(new AgentError(value.error ?? `HTTP ${response.status}`, response.status), { retryAfterMs: retryAfter(response), ...codeOf(value) });
+                return value;
+            }
+            catch (error) {
+                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;
+                // Honour the runtime's Retry-After, with jitter so refused callers do not return together; else back off exponentially.
+                const backoff = Math.min(10_000, (limited ? 500 : 100) * 2 ** attempt);
+                const hinted = error instanceof AgentError ? error.retryAfterMs : undefined;
+                await pause(hinted !== undefined ? hinted + Math.random() * Math.min(1000, backoff) : backoff);
+            }
+        }
+    }
+    /**
+     * A request with a raw body or response (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 = {}) {
+        // 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;
+        }
+    }
+}
+/** What an agent's key, and a request's id (its idempotency key), may be. */
+const AGENT_KEY = /^[A-Za-z0-9_-]{1,80}$/;
+const REQUEST_ID = AGENT_KEY;
+/** A create request's fields, from the options given. */
+function provisioning(options) {
+    const fields = ["subject", "context", "keyScope", "spendLimit", "modelHeaders", "definition", "mounts", "model", "thinkingLevel", "initialMessages", "name", "type", "systemPrompt", "systemPromptAppend", "fileTools", "builtins", "prompt"];
+    return Object.fromEntries(fields.filter(field => options[field] !== undefined).map(field => [field, options[field]]));
+}
+/** Trusted-backend SDK. Only createAgent needs the operator key. */
+export class AgentRuntime {
+    options;
+    transport;
+    constructor(options = {}) { this.options = options; this.transport = new Transport(options); }
+    /**
+     * The agent for `key`: made if there is none, set to `options` if it differs. Returns its credentials;
+     * connect with `connectAgent`. Keyed agents live until they are deleted.
+     */
+    async upsertAgent(key, options) {
+        const apiKey = this.options.apiKey;
+        if (!apiKey)
+            throw new AgentError("Set apiKey to provision an agent");
+        if (!AGENT_KEY.test(key))
+            throw new AgentError(`An agent's key is 1 to 80 letters, digits, _ and -: ${JSON.stringify(key.slice(0, 100))} is not`);
+        const server = options.mcp ?? toolServer(options.tools ?? {});
+        // The key is the agent's idempotency key: the same key is the same agent, reconfigured when its configuration differs.
+        const answer = await this.transport.json("/v1/agents", apiKey, "POST", { mcp: { tools: await server.listTools() }, ...provisioning(options) }, true, { "Idempotency-Key": key });
+        return { session: { id: answer.id, token: answer.token, expiresAt: answer.expiresAt ?? null }, ...(answer.reconfigured ? { reconfigured: answer.reconfigured } : {}), ...(answer.prompt ? { prompt: answer.prompt } : {}) };
+    }
+    async createAgent(options) {
+        const key = this.options.apiKey;
+        if (!key)
+            throw new AgentError("Set apiKey to provision an agent");
+        const server = options.mcp ?? toolServer(options.tools ?? {});
+        // A key of the caller's makes the agent durable (it lives until deleted); one the SDK makes up, only so a retried
+        // create finds the same agent, keeps a scratch agent's day, said explicitly since any key would make it durable.
+        const ttlSeconds = options.ttlSeconds !== undefined ? options.ttlSeconds : options.idempotencyKey === undefined ? 86_400 : undefined;
+        const session = await this.transport.json("/v1/agents", key, "POST", { mcp: { tools: await server.listTools() }, ...provisioning(options), ...(ttlSeconds !== undefined ? { ttlSeconds } : {}) }, true, { "Idempotency-Key": options.idempotencyKey ?? globalThis.crypto.randomUUID() });
+        return this.connectAgent(session, options);
+    }
+    async connectAgent(session, options) {
+        const client = new AgentClient(this.options, session, options);
+        try {
+            await client.connect();
+            return client;
+        }
+        catch (error) {
+            await client.close();
+            throw error;
+        }
+    }
+    operator() {
+        if (!this.options.apiKey)
+            throw new AgentError("Set apiKey to manage definitions, volumes and mounts");
+        return this.options.apiKey;
+    }
+    /**
+     * Add or replace a provider of your own: a server that speaks OpenAI Chat Completions, with the models it has. Agents
+     * name them `<name>/<model id>`. `apiKey` and `headers` left out keep what is stored; null removes them.
+     */
+    setProvider(name, config) { return this.transport.json(`/v1/providers/${encodeURIComponent(name)}`, this.operator(), "PUT", config); }
+    deleteProvider(name) { return this.transport.json(`/v1/providers/${encodeURIComponent(name)}`, this.operator(), "DELETE", undefined, false); }
+    /** Every provider: the built-in ones with your keys' status, and your own (`custom`). */
+    providers() { return this.transport.json("/v1/providers", this.operator()); }
+    /** The tenant's agents, each with the key it was made with (null for one made without) and its name. */
+    listAgents() { return this.transport.json("/v1/agents", this.operator()); }
+    createVolume(options = {}) { return this.transport.json("/v1/volumes", this.operator(), "POST", options, false); }
+    listVolumes() { return this.transport.json("/v1/volumes", this.operator()); }
+    /** A handle on one volume's files, snapshots and forks. */
+    volume(id) {
+        if (!/^vol_[a-f0-9]{24}$/.test(id))
+            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); }
+    /** The definition for `key`, set to `input` whole: made if there is none, else a new revision if `input` changes it. The same key is the same definition. */
+    upsertDefinition(key, input) {
+        if (!AGENT_KEY.test(key))
+            throw new AgentError(`A definition's key is 1 to 80 letters, digits, _ and -: ${JSON.stringify(key.slice(0, 100))} is not`);
+        return this.transport.json("/v1/definitions", this.operator(), "POST", input, true, { "Idempotency-Key": key });
+    }
+    /** 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.
+     */
+    /**
+     * A token a browser reads one agent with (`@camelai/run/watch`): mint one per user, after your
+     * own access checks. It reads only that agent's events, state, history and inputs (or `scopes`), for
+     * `ttlSeconds` (default 900, 5 to 3600).
+     */
+    browserToken(agentId, options = {}) {
+        return this.transport.json(`/v1/agents/${encodeURIComponent(agentId)}/browser-tokens`, this.operator(), "POST", options, false);
+    }
+    /** Who the API key is: `tenant` is your tenant's id, which serveTools and verifyRuntimeToken take. */
+    /** Who the API key is (`tenant`), and `defaultModel`, the model an agent gets when it names none. */
+    me() { return this.transport.json("/v1/me", this.operator()); }
+    /** 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 {
+    id;
+    transport;
+    token;
+    constructor(transport, token, id) { this.transport = transport; this.token = token; this.id = id; }
+    path(suffix = "") { return `/v1/volumes/${this.id}${suffix}`; }
+    file(path) { return this.path(`/files/${path.split("/").filter(Boolean).map(encodeURIComponent).join("/")}`); }
+    info() { return this.transport.json(this.path(), this.token); }
+    delete() { return this.transport.json(this.path(), this.token, "DELETE", undefined, false); }
+    snapshot(options = {}) { return this.transport.json(this.path("/snapshots"), this.token, "POST", options, false); }
+    snapshots() { return this.transport.json(this.path("/snapshots"), this.token); }
+    deleteSnapshot(id) { return this.transport.json(this.path(`/snapshots/${encodeURIComponent(id)}`), this.token, "DELETE", undefined, false); }
+    /** A new volume with this one's files (or a snapshot's); only metadata is copied. */
+    fork(options = {}) { return this.transport.json(this.path("/fork"), this.token, "POST", options, false); }
+    changes(since = 0) { return this.transport.json(this.path(`/changes?since=${since}`), this.token); }
+    list(options = {}) {
+        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": 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: fileVersion(response), 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();
+    }
+}
+/** Requests one client may wait on at once. */
+const MAX_PENDING = 1000;
+/** Events waiting for a slow onEvent; past this, streamed deltas are dropped (the messages they build still arrive). */
+const MAX_QUEUED_EVENTS = 10_000;
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+/** Credentials whose token stays out of logs: not enumerable, so JSON.stringify and console.log leave it out. */
+function redacted(session) {
+    const value = { id: session.id, expiresAt: session.expiresAt };
+    Object.defineProperty(value, "token", { value: session.token, enumerable: false });
+    return value;
+}
+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: fileVersion(response) };
+    }
+    /** 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 {
+    /** The agent's id (client_…): safe to log and to store. */
+    id;
+    /** The agent's id and its token: keep the token secret (it is left out of logs and JSON). */
+    session;
+    tools;
+    server;
+    transport;
+    /** The last event taken from the stream: a reconnect resumes after it (a new client starts from a snapshot). */
+    cursor = 0;
+    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();
+    /** The event stream's connection, named in the MCP messages this client sends back. */
+    connection;
+    stream;
+    loop;
+    closed = false;
+    fatal;
+    ready = Promise.withResolvers();
+    /** onEvent's queue: events wait here, in order, so the stream never waits on the application. */
+    dispatching = Promise.resolve();
+    queued = 0;
+    dropped = 0;
+    listeners = new Set();
+    attaching;
+    /** The stream was cut on purpose, to reconnect in another mode: not an error to report. */
+    switching = false;
+    constructor(runtime, session, options) {
+        if (!/^client_[a-f0-9]{40}$/.test(session.id))
+            throw new AgentError("Invalid session id");
+        this.id = session.id;
+        this.session = redacted(session);
+        this.attaching = options.attach !== false;
+        this.tools = { ...options.tools };
+        this.server = options.mcp ?? toolServer(this.tools);
+        this.options = options;
+        this.transport = new Transport(runtime);
+        this.openFile = runtime.openFile;
+        this.pollMs = runtime.pollMs ?? 30_000;
+        this.files = new AgentFiles(this.transport, this.session.token, this.path());
+    }
+    path(suffix = "") { return `/clients/${this.session.id}${suffix}`; }
+    http(suffix, method = "GET", body, retry = true) { return this.transport.json(this.path(suffix), this.session.token, method, body, retry); }
+    report(error) { this.options.onError?.(error instanceof Error ? error : new Error(String(error))); }
+    async connect() {
+        if (this.closed)
+            throw new AgentError("Client closed");
+        this.loop ??= this.events();
+        await Promise.race([this.ready.promise, new Promise((_, reject) => {
+                const timer = setTimeout(() => reject(new AgentError("Timed out connecting to agent")), 10_000);
+                this.ready.promise.finally(() => clearTimeout(timer)).catch(() => { });
+            })]);
+    }
+    async events() {
+        let backoff = 250;
+        while (!this.closed) {
+            this.stream = new AbortController();
+            let watchdog;
+            const touch = () => { clearTimeout(watchdog); watchdog = setTimeout(() => this.stream?.abort(), 20_000); };
+            touch();
+            try {
+                // One application serves an agent's tools at a time: a reconnect names the connection it held; `takeover` replaces another's, once.
+                const mode = !this.attaching ? "&watch=1" : this.options.takeover && !this.connection ? "&takeover=true" : "";
+                const response = await this.transport.fetcher(this.transport.base + this.path(`/events?snapshot=1${mode}`), {
+                    headers: {
+                        Authorization: `Bearer ${this.session.token}`, Accept: "text/event-stream", "Last-Event-ID": String(this.cursor),
+                        ...(this.attaching && this.connection ? { "X-Agent-Connection": this.connection } : {}),
+                    },
+                    signal: this.stream.signal, redirect: "manual",
+                });
+                await rejectRedirect(response);
+                if (response.status === 409) {
+                    const refusal = await response.json().catch(() => ({}));
+                    if (refusal.code === "APPLICATION_CONNECTED" || refusal.error?.startsWith("APPLICATION_CONNECTED")) {
+                        throw Object.assign(new AgentError("Another process serves this agent's tools. One process at a time answers an agent's tool calls: close that one, pass takeover: true to replace it, or connect with attach: false to run the agent without serving its tools", 409), { code: "APPLICATION_CONNECTED" });
+                    }
+                    const snapshot = await this.sync();
+                    this.cursor = snapshot.cursor;
+                    this.emit({ type: "replay_gap", cursor: snapshot.cursor });
+                    continue;
+                }
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw new AgentError(`Event stream HTTP ${response.status}`, response.status);
+                }
+                if (!response.headers.get("content-type")?.startsWith("text/event-stream") || !response.body)
+                    throw new AgentError("Expected an SSE response");
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                try {
+                    while (!this.closed) {
+                        const { value, done } = await reader.read();
+                        if (done)
+                            break;
+                        touch();
+                        buffer += decoder.decode(value, { stream: true });
+                        let end;
+                        while ((end = buffer.indexOf("\n\n")) !== -1) {
+                            const frame = buffer.slice(0, end);
+                            buffer = buffer.slice(end + 2);
+                            if (byteLength(frame) > FRAME_BYTES)
+                                throw new AgentError("SSE frame too large");
+                            const lines = frame.split("\n");
+                            const data = lines.filter(line => line.startsWith("data:")).map(line => line.slice(5).trimStart()).join("\n");
+                            if (!data)
+                                continue;
+                            // Another process took over this agent's tools: this one stops, rather than take them back.
+                            if (lines.includes("event: closed")) {
+                                throw Object.assign(new AgentError("Another process took over this agent's tools (takeover): this client no longer serves them, and follows the agent without them", 409), { code: "APPLICATION_REPLACED" });
+                            }
+                            if (lines.includes("event: ready")) {
+                                const ready = JSON.parse(data);
+                                this.connection = ready.connection;
+                                // Tools that differ from those the agent was last given: declare these, between its turns.
+                                if (this.attaching && ready.toolsHash && this.options.syncTools !== false)
+                                    void this.syncTools(ready.toolsHash).catch(error => this.report(error));
+                                await this.sync();
+                                backoff = 250;
+                                this.ready.resolve();
+                                this.options.onConnection?.(true);
+                                continue;
+                            }
+                            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");
+                            const event = JSON.parse(data);
+                            // A snapshot restarts the stream at its cursor, even one below the last (a restarted host).
+                            if (event.type === "snapshot") {
+                                this.cursor = id;
+                                this.emit(event);
+                                continue;
+                            }
+                            if (id <= this.cursor)
+                                continue;
+                            await this.receive(event);
+                            this.cursor = id;
+                        }
+                        if (byteLength(buffer) > FRAME_BYTES)
+                            throw new AgentError("SSE frame too large");
+                    }
+                }
+                finally {
+                    await reader.cancel().catch(() => { });
+                    reader.releaseLock();
+                }
+            }
+            catch (error) {
+                if (this.closed)
+                    break;
+                // Another process serves the tools now (it took over, or took them while this one was away): this one
+                // goes on following the agent, and running it, without serving them, so its requests still settle.
+                if (error instanceof AgentError && (error.code === "APPLICATION_REPLACED" || (error.code === "APPLICATION_CONNECTED" && this.connection))) {
+                    this.attaching = false;
+                    this.report(error);
+                }
+                else if (error instanceof AgentError && ([401, 403, 410].includes(error.status) || (error.status >= 300 && error.status < 400) || error.code === "APPLICATION_CONNECTED")) {
+                    this.fatal = error;
+                    this.ready.reject(error);
+                    for (const waiter of this.pending.values())
+                        waiter.reject(error);
+                    this.pending.clear();
+                    this.report(error);
+                    break;
+                }
+                else if (this.switching)
+                    this.switching = false;
+                else
+                    this.report(error);
+            }
+            finally {
+                clearTimeout(watchdog);
+                this.options.onConnection?.(false);
+            }
+            if (!this.closed) {
+                await pause(backoff);
+                backoff = Math.min(5000, backoff * 2);
+            }
+        }
+    }
+    /** Rename/regroup this agent without changing its conversation or tools. */
+    async setMetadata(metadata) {
+        return this.transport.json(this.path('/metadata'), this.session.token, 'POST', metadata);
+    }
+    /** Hand an event to the listeners, and queue it for onEvent: the stream goes on without waiting for either. */
+    emit(event, requestId) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event, requestId);
+            }
+            catch (error) {
+                this.report(error);
+            }
+        }
+        const onEvent = this.options.onEvent;
+        if (!onEvent || this.closed)
+            return;
+        if (this.queued >= MAX_QUEUED_EVENTS && event.type === "message_update") {
+            if (this.dropped++ === 0)
+                this.report(new AgentError(`onEvent is falling behind: over ${MAX_QUEUED_EVENTS} events wait, so streamed deltas are dropped until it catches up`));
+            return;
+        }
+        this.queued++;
+        this.dispatching = this.dispatching.then(async () => {
+            // A closed client calls onEvent no more: events still queued are dropped.
+            try {
+                if (!this.closed)
+                    await onEvent(event, requestId);
+            }
+            catch (error) {
+                this.report(error);
+            }
+            finally {
+                if (--this.queued === 0)
+                    this.dropped = 0;
+            }
+        });
+    }
+    /** @internal Hear every event as it arrives (synchronously, before onEvent); returns the unsubscribe. */
+    listen(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Resolves once onEvent has handled every event received so far. */
+    drained() { return this.dispatching; }
+    async receive(event) {
+        if (event.type === "response")
+            this.settle(event.id, event.outcome);
+        else if (event.type === "event") {
+            this.emit(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);
+        if (!waiter)
+            return;
+        this.pending.delete(id);
+        if ("error" in value) {
+            const outcome = value;
+            waiter.reject(Object.assign(new AgentError(outcome.error ?? "Unknown failure", 0, id), {
+                ...(typeof outcome.code === "string" ? { code: outcome.code } : {}), ...(outcome.uncertain ? { uncertain: true } : {}),
+            }));
+        }
+        else
+            waiter.resolve(value.result);
+    }
+    /**
+     * A request's result arrives as an event; a reconnect also settles from /state. As a last resort,
+     * ask for its status now and then, so an event lost on the way can never strand the caller.
+     */
+    async outcome(id, result) {
+        const poll = setInterval(() => void this.requestStatus(id).then(record => { if (record.outcome)
+            this.settle(id, record.outcome); }, () => { }), this.pollMs);
+        try {
+            return await result;
+        }
+        finally {
+            clearInterval(poll);
+        }
+    }
+    async sync() {
+        const state = await this.outcomes();
+        for (const request of state.requests)
+            if (request.outcome)
+                this.settle(request.id, request.outcome);
+        return 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;
+        if (message.id === undefined) {
+            if (message.method === "notifications/cancelled")
+                this.active.get(String(message.params?.requestId))?.abort();
+            return;
+        }
+        const connection = this.connection;
+        const key = String(message.id);
+        const controller = new AbortController();
+        if (message.method === "tools/call")
+            this.active.set(key, controller);
+        const notify = (notification) => void this.transport.json(this.path("/mcp"), this.session.token, "POST", notification, false, { "X-Agent-Connection": connection ?? "" }).catch(() => { });
+        try {
+            const answer = await answerMcp(message, this.server, params => toolContext(params, key, controller.signal, undefined, notify));
+            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);
+        }
+    }
+    /**
+     * Send a request and wait for its outcome, however long the run takes: there is no timeout unless
+     * `timeoutMs` or `signal` says so, and either only stops the wait (the request goes on).
+     */
+    async request(method, params = {}, options = {}) {
+        if (this.closed || this.fatal)
+            throw this.fatal ?? new AgentError("Client closed");
+        const id = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+        if (!REQUEST_ID.test(id))
+            throw new AgentError(`An idempotency key is 1 to 80 letters, digits, _ and -: ${JSON.stringify(id.slice(0, 100))} is not`, 400);
+        options.signal?.throwIfAborted();
+        const deferred = this.waiter(id, options, "Request timed out; it may still be running: requestStatus() or waitForRequest() observe it");
+        try {
+            const record = await this.http("/requests", "POST", { id, method, params });
+            if (record.outcome)
+                this.settle(id, record.outcome);
+            return await this.outcome(id, deferred.promise);
+        }
+        catch (error) {
+            if (error instanceof AgentError) {
+                error.requestId ??= id;
+                throw error;
+            }
+            if (options.signal?.aborted && error === options.signal.reason)
+                throw error;
+            throw new AgentError(String(error), 0, id);
+        }
+        finally {
+            deferred.done();
+        }
+    }
+    /**
+     * Wait for request `id` to settle, until `timeoutMs` or `signal` says to stop waiting. Calls waiting on the same
+     * request share its settlement (the same key sent again joins the run), and each stops waiting on its own.
+     */
+    waiter(id, options, timedOut) {
+        let shared = this.pending.get(id);
+        if (!shared) {
+            if (this.pending.size >= MAX_PENDING)
+                throw new AgentError("Too many outstanding requests");
+            shared = { ...Promise.withResolvers(), waiters: 0 };
+            // Attach immediately, even while the POST is pending, to avoid unhandled errors.
+            shared.promise.catch(() => { });
+            this.pending.set(id, shared);
+        }
+        shared.waiters++;
+        const own = Promise.withResolvers();
+        own.promise.catch(() => { });
+        shared.promise.then(own.resolve, own.reject);
+        const timer = options.timeoutMs !== undefined ? setTimeout(() => own.reject(new AgentError(timedOut, 0, id)), options.timeoutMs) : undefined;
+        const aborted = () => own.reject(options.signal.reason);
+        options.signal?.addEventListener("abort", aborted, { once: true });
+        const settled = shared;
+        return {
+            promise: own.promise,
+            done: () => {
+                clearTimeout(timer);
+                options.signal?.removeEventListener("abort", aborted);
+                if (--settled.waiters === 0 && this.pending.get(id) === settled)
+                    this.pending.delete(id);
+            },
+        };
+    }
+    /** Wait for a request already sent (by this process or another) to settle. This never submits or re-executes work. */
+    async waitForRequest(id, options = {}) {
+        if (this.closed || this.fatal)
+            throw this.fatal ?? new AgentError("Client closed");
+        options.signal?.throwIfAborted();
+        const deferred = this.waiter(id, options, "Stopped waiting; the request may still be running");
+        try {
+            const record = await this.requestStatus(id);
+            if (record.outcome)
+                this.settle(id, record.outcome);
+            return await this.outcome(id, deferred.promise);
+        }
+        finally {
+            deferred.done();
+        }
+    }
+    /**
+     * `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.
+     * `metadata` is the application's own key-value data about the message (at most 16 string values): the
+     * stored message and its request carry it, with the request's id, in history, events and webhooks; the model never sees it.
+     * `whileRunning: "steer"` hands the message to a running turn, and resolves with that turn's outcome. `spendLimit` is this run's own
+     * budget: it ends before its next model request once it has spent that; the agent's spendLimit is unchanged.
+     */
+    prompt(text, options) {
+        return this.message("prompt", text, options, { ...(options?.actor ? { actor: options.actor } : {}), ...(options?.whileRunning === "steer" ? { whileRunning: "steer" } : {}), ...(options?.allowDisconnected ? { allowDisconnected: true } : {}), ...(options?.spendLimit ? { spendLimit: options.spendLimit } : {}) });
+    }
+    /**
+     * Send a message with its files: each is uploaded to the agent's workspace under the request's
+     * id first, then attached by path.
+     */
+    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 } : {}), ...extra, ...(options?.from ? { from: options.from } : {}), ...(options?.metadata ? { metadata: options.metadata } : {}) }, { ...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/run/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"); }
+    /**
+     * The page of whole turns ending before `before` (default: the newest message, the running turn's
+     * included), with at least `limit` messages (default 50) where there are that many. It reads only
+     * that page, however long the history.
+     */
+    historyPage(options = {}) {
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50), ...(options.before !== undefined ? { before: String(options.before) } : {}) });
+        return this.http(`/history?${query}`);
+    }
+    continue(options) { return this.request("continue", { ...(options?.actor ? { actor: options.actor } : {}), ...(options?.allowDisconnected ? { allowDisconnected: true } : {}) }, options); }
+    /** The legacy steer request: a message held for the running turn. New code: `prompt(text, { whileRunning: "steer" })`. */
+    steer(text, options) { return this.message("steer", text, options); }
+    /** Change the prompt, thinking level, tools, or model ("provider/model-id") between runs. */
+    async configure(options) {
+        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, tools);
+        }
+        if (server)
+            this.server = mcp ?? toolServer(this.tools);
+        // Tools that run here now: answer the agent's calls, as its application.
+        if (server && !this.attaching && (mcp || Object.keys(tools ?? {}).length))
+            await this.reconnect(true);
+        return result;
+    }
+    /** Declare this client's tools when they differ from what the agent has (its `toolsHash`). */
+    async syncTools(declared) {
+        const tools = await this.server.listTools();
+        const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(tools))));
+        if ([...digest].map(byte => byte.toString(16).padStart(2, "0")).join("") === declared)
+            return;
+        await this.request("configure", { mcp: { tools } });
+    }
+    /** Connect again, attached (answering tool calls) or not. */
+    async reconnect(attach) {
+        this.attaching = attach;
+        this.ready = Promise.withResolvers();
+        this.switching = true;
+        this.stream?.abort();
+        await this.connect();
+    }
+    execute(code, options) {
+        return this.request("execute", { code, ...(options?.executionTimeoutMs ? { timeoutMs: options.executionTimeoutMs } : {}), ...(options?.actor ? { actor: options.actor } : {}), ...(options?.allowDisconnected ? { allowDisconnected: true } : {}) }, options);
+    }
+    /**
+     * Wake this agent later: with `text` it gets a prompt, with `code` it runs sandboxed
+     * code against your tools. `everySeconds` (at least 60) repeats it.
+     */
+    schedule(input) {
+        return this.http("/schedules", "POST", { ...input, ...(input.at instanceof Date ? { at: input.at.toISOString() } : {}) }, false);
+    }
+    schedules() { return this.http("/schedules"); }
+    unschedule(id) { return this.http(`/schedules/${encodeURIComponent(id)}`, "DELETE", undefined, false); }
+    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"); }
+    toJSON() { return { id: this.id }; }
+    [INSPECT]() { return `AgentClient { id: '${this.id}' }`; }
+    async close() {
+        this.closed = true;
+        this.stream?.abort();
+        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));
+        this.pending.clear();
+        await this.loop;
+        // onEvent is called no more; the call in progress may finish, but one that never returns cannot hang shutdown.
+        let timer;
+        await Promise.race([this.dispatching, new Promise(resolve => { timer = setTimeout(resolve, 2000); })]);
+        clearTimeout(timer);
+    }
+    async destroy() { try {
+        await this.http("", "DELETE");
+    }
+    finally {
+        await this.close();
+    } }
+    async [Symbol.asyncDispose]() { await this.close(); }
+}
+export { Agents, Agent } from "./agents.js";