@camelai/agent-runtime 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qaml-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @camelai/agent-runtime
+
+SDK for the camelAI hosted agent runtime. Your application defines tools as
+ordinary functions; the runtime runs the model loop, keeps each agent's history,
+and executes model-written code in a sandbox that can only call your tools.
+Tool calls come back to your process over SSE, so your data and credentials
+never leave it.
+
+Requires Node 22 or later (or Bun).
+
+## Install
+
+```sh
+npm install @camelai/agent-runtime
+```
+
+Upgrade with `npm update @camelai/agent-runtime`.
+
+The SDK has one runtime dependency (`typebox`). Its message and model types come
+from Pi; for full typing of history and events, also install
+`@earendil-works/pi-agent-core@0.80.6` and `@earendil-works/pi-ai@0.80.6` as dev
+dependencies. Without them those types resolve to `any` (with `skipLibCheck`).
+
+## Use
+
+You need the runtime URL and your tenant's operator token. Keep the operator
+token on your backend; it can create and control every agent in your tenant.
+
+```ts
+import { AgentRuntime, schema, tool } from "@camelai/agent-runtime/node";
+
+const runtime = new AgentRuntime({
+  url: "https://agents.camelai.dev",
+  apiKey: process.env.AGENT_RUNTIME_TOKEN,
+  stateDirectory: ".agent-runtime", // tool receipts and cursors survive restarts
+});
+
+const agent = await runtime.createAgent({
+  name: "Inventory planner",
+  type: "inventory",
+  model: "anthropic/claude-sonnet-5", // any "provider/model-id" from GET /v1/models
+  systemPrompt: "You plan restocks. Never place orders.",
+  tools: {
+    read_inventory: tool({
+      description: "Read stock and target quantities",
+      input: schema.Object({}),
+      execute: () => db.inventory(),
+    }),
+    plan_restock: tool({
+      description: "Save a restock plan",
+      input: schema.Object({ sku: schema.String(), quantity: schema.Integer() }),
+      // callId is stable across retries: use it as your idempotency key.
+      execute: ({ sku, quantity }, { callId }) => db.plan(sku, quantity, { idempotencyKey: callId }),
+    }),
+  },
+  onEvent: event => console.log(event.type),
+});
+
+await agent.prompt("Plan restocks for anything below target.");
+```
+
+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.
+
+## Console and REST API
+
+Sign in at https://agents.camelai.dev/console with GitHub (qaml-ai members) to add
+provider keys, browse models, create API tokens, watch agents and see usage.
+Everything there is also available over REST with an API token:
+
+```sh
+curl -X PUT https://agents.camelai.dev/v1/providers/anthropic/key \
+  -H "Authorization: Bearer $AGENT_RUNTIME_TOKEN" -H "Content-Type: application/json" \
+  -d '{"apiKey": "sk-ant-..."}'
+curl "https://agents.camelai.dev/v1/models?available=true" -H "Authorization: Bearer $AGENT_RUNTIME_TOKEN"
+```
+
+The routes are `/v1/me`, `/v1/providers` (+ `/:provider/key`), `/v1/models`,
+`/v1/agents` (+ `/:id`, `/:id/history`, `/:id/prompt`, `/:id/abort`),
+`/v1/tokens` and `/v1/usage`; see `src/api.ts`.
+
+Save `agent.session` (it contains a scoped credential) to reconnect later with
+`runtime.connectAgent(session, { tools })`. Pass the same `idempotencyKey` to
+`createAgent` to get the same agent back instead of a new one.
+
+`@camelai/agent-runtime` (without `/node`) is the portable build for Workers and
+other runtimes without a filesystem; supply your own `journalStore`.
+
+See `clients/README.md` in the repository for delivery
+guarantees, tool-call semantics, and the full API.

package/dist/clients/node.d.ts

@@ -0,0 +1,9 @@
+import { AgentRuntime as PortableAgentRuntime, type RuntimeOptions as PortableRuntimeOptions, type JournalStore } from "./typescript.ts";
+export * from "./typescript.ts";
+export interface RuntimeOptions extends PortableRuntimeOptions {
+    stateDirectory?: string;
+}
+export declare function fileJournalStore(directory: string): JournalStore;
+export declare class AgentRuntime extends PortableAgentRuntime {
+    constructor(options?: RuntimeOptions);
+}

package/dist/clients/node.js

@@ -0,0 +1,35 @@
+/** Node/Bun convenience entry. The portable SDK itself imports no Node modules. */
+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";
+export function fileJournalStore(directory) {
+    const root = resolve(directory);
+    const path = (id) => {
+        if (!/^client_[a-f0-9]{40}$/.test(id))
+            throw new Error("Invalid journal session id");
+        return join(root, `${id}.json`);
+    };
+    return {
+        async load(id) {
+            try {
+                return JSON.parse(await readFile(path(id), "utf8"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+        },
+        async save(id, journal) { writeDurableJson(path(id), journal); },
+    };
+}
+export class AgentRuntime extends PortableAgentRuntime {
+    constructor(options = {}) {
+        super({ ...options, url: options.url ?? process.env.AGENT_URL,
+            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/typescript.d.ts

@@ -0,0 +1,298 @@
+import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, ImageContent, Model } from "@earendil-works/pi-ai";
+import { Type, type TSchema, type Static } from "typebox";
+import { type Outcome, type RequestMethod, type SessionCredentials, type SessionState } from "../shared/client-protocol.ts";
+export { Type as schema };
+export type { SessionCredentials, SessionState };
+export interface ToolContext {
+    signal: AbortSignal;
+    callId: string;
+    toolCallId?: string;
+    /** Set by the runtime, e.g. `{ channel, conversationId, sender }` for a turn a channel message started. */
+    origin?: Record<string, unknown>;
+}
+export interface Tool<T = any> {
+    description: string;
+    resultFormat?: "json" | "content";
+    exposure?: "direct" | "codemode" | "both";
+    executionMode?: "sequential" | "parallel";
+    input: Record<string, unknown>;
+    execute: (args: T, context: ToolContext) => unknown | Promise<unknown>;
+}
+/** Infer callback arguments from the schema; no manually duplicated argument type. */
+export declare function tool<S extends TSchema>(definition: Omit<Tool<Static<S>>, "input"> & {
+    input: S;
+}): Tool<Static<S>>;
+export type Tools = Record<string, Tool>;
+export interface RuntimeOptions {
+    url?: string;
+    apiKey?: string;
+    /** Persist tool receipts and event cursors before acknowledging work. Default: memory only. */
+    journalStore?: JournalStore;
+    /** Injectable for tests, observability, or an application's HTTP stack. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface AgentOptions {
+    tools: Tools;
+    onEvent?: (event: any, requestId?: string) => unknown | Promise<unknown>;
+    onConnection?: (connected: boolean) => void;
+    onError?: (error: Error) => void;
+}
+export type { ThinkingLevel };
+export interface CreateAgentOptions extends AgentOptions {
+    idempotencyKey?: string;
+    /** Agent lifetime in seconds (60 to 366 days), or null to keep the agent until it is deleted. Default one day. */
+    ttlSeconds?: number | null;
+    systemPrompt?: string;
+    name?: string;
+    type?: string;
+    /**
+     * A model from the runtime's catalog as "provider/model-id" (see GET /v1/models),
+     * e.g. "anthropic/claude-sonnet-5" or "openrouter/openai/gpt-5.2". A full Pi
+     * model object is also accepted if its endpoint is trusted by the runtime.
+     */
+    model?: string | Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+    initialMessages?: AgentMessage[];
+    /** Volumes for the agent's file tools (read, write, edit, ls, glob, grep). Default: its own workspace volume at /workspace. */
+    mounts?: Mount[];
+}
+/** A volume the agent's file tools see at `path`; `notify` prompts the agent when others change files there. */
+export interface Mount {
+    volumeId: string;
+    path: string;
+    mode: "ro" | "rw";
+    subpath?: string;
+    notify?: boolean;
+}
+export interface Volume {
+    id: string;
+    name: string;
+    createdAt: number;
+    seq?: number;
+    files?: number;
+    bytes?: number;
+    origin?: {
+        volume: string;
+        snapshot?: string;
+        seq: number;
+    };
+}
+export interface VolumeFile {
+    path: string;
+    version: number;
+    size: number;
+    updatedAt: number;
+    by?: string;
+}
+export interface VolumeSnapshot {
+    id: string;
+    volume: string;
+    name: string;
+    seq: number;
+    createdAt: number;
+    files: number;
+    bytes: number;
+}
+export interface VolumeChanges {
+    seq: number;
+    changes: {
+        seq: number;
+        path: string;
+        kind: "write" | "delete";
+        version?: number;
+        size?: number;
+        by?: string;
+        at: number;
+    }[];
+    gap?: boolean;
+}
+export interface AgentHistory {
+    messages: AgentMessage[];
+}
+export interface Schedule {
+    id: string;
+    agent: string;
+    text?: string;
+    code?: string;
+    dueAt: number;
+    everySeconds?: number;
+    createdAt: number;
+}
+export interface RequestOptions {
+    idempotencyKey?: string;
+    timeoutMs?: number;
+}
+export declare class AgentError extends Error {
+    status: number;
+    requestId?: string;
+    constructor(message: string, status?: number, requestId?: string);
+}
+declare class Transport {
+    readonly base: string;
+    readonly fetcher: typeof globalThis.fetch;
+    constructor(options: RuntimeOptions);
+    json(path: string, token: string, method?: string, body?: unknown, retry?: boolean, headers?: Record<string, string>): Promise<any>;
+    /** A request with a raw body or response (volume file contents). */
+    raw(path: string, token: string, init?: {
+        method?: string;
+        body?: Uint8Array;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+}
+/** Trusted-backend SDK. Only createAgent needs the operator key. */
+export declare class AgentRuntime {
+    readonly options: RuntimeOptions;
+    private readonly transport;
+    constructor(options?: RuntimeOptions);
+    createAgent(options: CreateAgentOptions): Promise<AgentClient>;
+    connectAgent(session: SessionCredentials, options: AgentOptions): Promise<AgentClient>;
+    private operator;
+    createVolume(options?: {
+        name?: string;
+    }): Promise<Volume>;
+    listVolumes(): Promise<Volume[]>;
+    /** A handle on one volume's files, snapshots and forks. */
+    volume(id: string): VolumeHandle;
+    mounts(agentId: string): Promise<Mount[]>;
+    /** Replace an agent's mounts; an idle agent restarts so its tools describe them. */
+    setMounts(agentId: string, mounts: Mount[]): Promise<Mount[]>;
+}
+/** Files are versioned: pass `version` to write or remove only if nobody changed the file since (0: must not exist). */
+export declare class VolumeHandle {
+    readonly id: string;
+    private readonly transport;
+    private readonly token;
+    constructor(transport: Transport, token: string, id: string);
+    private path;
+    private file;
+    info(): Promise<Volume>;
+    delete(): Promise<any>;
+    snapshot(options?: {
+        name?: string;
+    }): Promise<VolumeSnapshot>;
+    snapshots(): Promise<VolumeSnapshot[]>;
+    deleteSnapshot(id: string): Promise<any>;
+    /** A new volume with this one's files (or a snapshot's); only metadata is copied. */
+    fork(options?: {
+        name?: string;
+        snapshot?: string;
+    }): Promise<Volume>;
+    changes(since?: number): Promise<VolumeChanges>;
+    list(options?: {
+        prefix?: string;
+        glob?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        files: VolumeFile[];
+        next?: string;
+    }>;
+    write(path: string, data: string | Uint8Array, options?: {
+        version?: number;
+    }): Promise<VolumeFile>;
+    /** A file's bytes, or `range` of them ([start, end) in bytes). */
+    read(path: string, options?: {
+        range?: [number, number?];
+    }): Promise<{
+        data: Uint8Array;
+        version: number;
+    }>;
+    readText(path: string): Promise<string>;
+    remove(path: string, options?: {
+        version?: number;
+    }): Promise<any>;
+}
+export type Journal = {
+    version: 1;
+    cursor: number;
+    calls: Record<string, {
+        state: "started" | "done";
+        outcome?: Outcome;
+    }>;
+};
+/** Stores must resolve only once the complete snapshot is committed. Use one active client per agent. */
+export interface JournalStore {
+    load(sessionId: string): Promise<Journal | undefined>;
+    save(sessionId: string, journal: Journal): Promise<void>;
+}
+export declare function memoryJournalStore(): JournalStore;
+export declare class AgentClient {
+    readonly session: SessionCredentials;
+    readonly tools: Tools;
+    private readonly transport;
+    private readonly store;
+    private journal;
+    private loaded?;
+    private saving;
+    private readonly options;
+    private readonly pending;
+    private readonly active;
+    private readonly delivered;
+    private stream?;
+    private loop?;
+    private closed;
+    private fatal?;
+    private ready;
+    constructor(runtime: RuntimeOptions, session: SessionCredentials, options: AgentOptions);
+    private load;
+    private save;
+    private path;
+    private http;
+    private report;
+    connect(): Promise<void>;
+    private events;
+    /** Rename/regroup this agent without changing its conversation or tools. */
+    setMetadata(metadata: {
+        name: string;
+        type: string;
+    }): Promise<any>;
+    private receive;
+    private settle;
+    private sync;
+    private dispatch;
+    private runTool;
+    request(method: RequestMethod, params?: Record<string, unknown>, options?: RequestOptions): Promise<any>;
+    /** Observe an already accepted request. This never submits or re-executes work. */
+    waitForRequest(id: string, options?: {
+        timeoutMs?: number;
+    }): Promise<any>;
+    prompt(text: string, options?: RequestOptions & {
+        images?: ImageContent[];
+    }): Promise<any>;
+    history(): Promise<AgentHistory>;
+    continue(options?: RequestOptions): Promise<any>;
+    steer(text: string): Promise<any>;
+    followUp(text: string): Promise<any>;
+    /** Change the prompt, thinking level, tools, or model ("provider/model-id") between runs. */
+    configure(options: {
+        systemPrompt?: string;
+        thinkingLevel?: ThinkingLevel;
+        tools?: Tools;
+        model?: string;
+    }): Promise<any>;
+    execute(code: string, options?: RequestOptions & {
+        timeoutMs?: number;
+        executionTimeoutMs?: number;
+    }): Promise<any>;
+    /**
+     * 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: {
+        text?: string;
+        code?: string;
+        at?: string | Date;
+        inSeconds?: number;
+        everySeconds?: number;
+    }): Promise<Schedule>;
+    schedules(): Promise<Schedule[]>;
+    unschedule(id: string): Promise<any>;
+    status(): Promise<any>;
+    abort(): Promise<any>;
+    requestStatus(id: string): Promise<any>;
+    outcomes(): Promise<SessionState>;
+    close(): Promise<void>;
+    destroy(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/clients/typescript.js

@@ -0,0 +1,509 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { FRAME_BYTES } from "../shared/client-protocol.js";
+export { Type as schema };
+/** Infer callback arguments from the schema; no manually duplicated argument type. */
+export function tool(definition) {
+    return { ...definition, input: definition.input };
+}
+export class AgentError extends Error {
+    status;
+    requestId;
+    constructor(message, status = 0, requestId) { super(message); this.name = "AgentError"; this.status = status; this.requestId = requestId; }
+}
+const byteLength = (value) => new TextEncoder().encode(value).byteLength;
+const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const definitions = (tools) => Object.entries(tools).map(([name, tool]) => ({ name, description: tool.description, parameters: tool.input, ...(tool.resultFormat ? { resultFormat: tool.resultFormat } : {}), ...(tool.exposure ? { exposure: tool.exposure } : {}), ...(tool.executionMode ? { executionMode: tool.executionMode } : {}) }));
+async function rejectRedirect(response) {
+    if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new AgentError("Runtime redirects are not allowed", response.status);
+    }
+}
+class Transport {
+    base;
+    fetcher;
+    constructor(options) {
+        const url = new URL(options.url ?? "http://127.0.0.1:8790");
+        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:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+            throw new Error("Remote runtimes require https://");
+        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.json();
+                if (!response.ok)
+                    throw new AgentError(value.error ?? `HTTP ${response.status}`, response.status);
+                return value;
+            }
+            catch (error) {
+                if (!retry || attempt >= 3 || (error instanceof AgentError && error.status < 500))
+                    throw error;
+                await pause(100 * 2 ** attempt);
+            }
+        }
+    }
+    /** A request with a raw body or response (volume file contents). */
+    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);
+        }
+        return response;
+    }
+}
+/** Trusted-backend SDK. Only createAgent needs the operator key. */
+export class AgentRuntime {
+    options;
+    transport;
+    constructor(options = {}) { this.options = options; this.transport = new Transport(options); }
+    async createAgent(options) {
+        const key = this.options.apiKey;
+        if (!key)
+            throw new AgentError("Set apiKey to provision an agent");
+        const session = await this.transport.json("/client-sessions", key, "POST", { tools: definitions(options.tools), ...(options.mounts !== undefined ? { mounts: options.mounts } : {}), ...(options.model !== undefined ? { model: options.model } : {}), ...(options.thinkingLevel !== undefined ? { thinkingLevel: options.thinkingLevel } : {}), ...(options.initialMessages !== undefined ? { initialMessages: options.initialMessages } : {}), ...(options.name !== undefined ? { name: options.name } : {}), ...(options.type !== undefined ? { type: options.type } : {}), ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}), ...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}) }, true, { "Idempotency-Key": options.idempotencyKey ?? globalThis.crypto.randomUUID() });
+        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 volumes and mounts");
+        return this.options.apiKey;
+    }
+    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);
+    }
+    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); }
+}
+/** 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);
+    }
+    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}"` } : {}) };
+        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('"', "")) };
+    }
+    async readText(path) { return new TextDecoder().decode((await this.read(path)).data); }
+    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();
+    }
+}
+export function memoryJournalStore() {
+    const entries = new Map();
+    return {
+        async load(id) { const value = entries.get(id); return value && structuredClone(value); },
+        async save(id, journal) { entries.set(id, structuredClone(journal)); },
+    };
+}
+export class AgentClient {
+    session;
+    tools;
+    transport;
+    store;
+    journal = { version: 1, cursor: 0, calls: {} };
+    loaded;
+    saving = Promise.resolve();
+    options;
+    pending = new Map();
+    active = new Map();
+    delivered = new Set();
+    stream;
+    loop;
+    closed = false;
+    fatal;
+    ready = Promise.withResolvers();
+    constructor(runtime, session, options) {
+        if (!/^client_[a-f0-9]{40}$/.test(session.id))
+            throw new AgentError("Invalid session id");
+        this.session = { id: session.id, token: session.token, expiresAt: session.expiresAt };
+        this.tools = { ...options.tools };
+        this.options = options;
+        this.transport = new Transport(runtime);
+        this.store = runtime.journalStore ?? memoryJournalStore();
+    }
+    async load() {
+        const journal = await this.store.load(this.session.id);
+        if (!journal)
+            return;
+        if (journal.version !== 1 || !Number.isSafeInteger(journal.cursor) || journal.cursor < 0 || !journal.calls || typeof journal.calls !== "object")
+            throw new AgentError("Unsupported client journal");
+        this.journal = structuredClone(journal);
+    }
+    save() {
+        const snapshot = structuredClone(this.journal);
+        // Serialize commits so concurrent tool completions cannot overwrite newer receipts.
+        this.saving = this.saving.then(() => this.store.save(this.session.id, snapshot));
+        return this.saving;
+    }
+    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");
+        await (this.loaded ??= this.load());
+        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 {
+                const response = await this.transport.fetcher(this.transport.base + this.path("/events"), {
+                    headers: { Authorization: `Bearer ${this.session.token}`, Accept: "text/event-stream", "Last-Event-ID": String(this.journal.cursor) },
+                    signal: this.stream.signal, redirect: "manual",
+                });
+                await rejectRedirect(response);
+                if (response.status === 409) {
+                    await response.body?.cancel();
+                    const snapshot = await this.sync();
+                    this.journal.cursor = snapshot.cursor;
+                    await this.save();
+                    await this.options.onEvent?.({ 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;
+                            if (lines.includes("event: ready")) {
+                                await this.sync();
+                                backoff = 250;
+                                this.ready.resolve();
+                                this.options.onConnection?.(true);
+                                continue;
+                            }
+                            const id = Number(lines.find(line => line.startsWith("id:"))?.slice(3));
+                            if (!Number.isSafeInteger(id) || id <= 0)
+                                throw new AgentError("Invalid SSE cursor");
+                            if (id <= this.journal.cursor)
+                                continue;
+                            const event = JSON.parse(data);
+                            await this.receive(event);
+                            this.journal.cursor = id;
+                            // Display events are replayable only from the host's memory; persisting the
+                            // cursor for each one would cost a storage write per streamed token.
+                            if (event.type !== "event")
+                                await this.save();
+                        }
+                        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;
+                if (error instanceof AgentError && ([401, 403, 410].includes(error.status) || (error.status >= 300 && error.status < 400))) {
+                    this.fatal = error;
+                    this.ready.reject(error);
+                    for (const waiter of this.pending.values())
+                        waiter.reject(error);
+                    this.pending.clear();
+                    this.report(error);
+                    break;
+                }
+                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);
+    }
+    async receive(event) {
+        if (event.type === "tool_call")
+            this.dispatch(event.call);
+        else if (event.type === "tool_cancel")
+            this.active.get(event.id)?.controller.abort();
+        else if (event.type === "response")
+            this.settle(event.id, event.outcome);
+        else if (event.type === "event")
+            await this.options.onEvent?.(event.event, event.requestId);
+    }
+    settle(id, value) {
+        const waiter = this.pending.get(id);
+        if (!waiter)
+            return;
+        this.pending.delete(id);
+        if ("error" in value)
+            waiter.reject(new AgentError(value.error ?? "Unknown failure", 0, id));
+        else
+            waiter.resolve(value.result);
+    }
+    async sync() {
+        const state = await this.outcomes();
+        for (const request of state.requests)
+            if (request.outcome)
+                this.settle(request.id, request.outcome);
+        for (const call of state.calls)
+            this.dispatch(call);
+        return state;
+    }
+    dispatch(call) {
+        if (this.closed || this.active.has(call.id) || this.delivered.has(call.id) || ["completed", "cancelled"].includes(call.state))
+            return;
+        const controller = new AbortController();
+        // Defer execution until the active entry exists; replay can arrive immediately.
+        const task = Promise.resolve().then(() => this.runTool(call, controller)).catch(error => this.report(error)).finally(() => this.active.delete(call.id));
+        this.active.set(call.id, { controller, task });
+    }
+    async runTool(call, controller) {
+        let receipt = this.journal.calls[call.id];
+        if (receipt?.state === "done") {
+            await this.http(`/calls/${call.id}/outcome`, "POST", receipt.outcome);
+            this.delivered.add(call.id);
+            return;
+        }
+        if (call.state === "uncertain")
+            return; // Already settled as unknown; never execute again.
+        let value;
+        if (call.state === "started")
+            value = { error: "The application lost this tool call's outcome; it may or may not have taken effect", uncertain: true };
+        else {
+            this.journal.calls[call.id] = { state: "started" };
+            await this.save();
+            try {
+                // Claim is deliberately NOT retried. A lost acknowledgement is ambiguous.
+                const claim = await this.http(`/calls/${call.id}/claim`, "POST", {}, false);
+                if (!claim.execute) {
+                    if (claim.call.state !== "started")
+                        return;
+                    value = { error: "Tool execution was already claimed; outcome unknown", uncertain: true };
+                }
+                else {
+                    const timer = setTimeout(() => controller.abort(), Math.max(1, call.deadline - Date.now()));
+                    // A callback that ignores cancellation must not keep a closed client's process alive until the deadline.
+                    timer.unref?.();
+                    try {
+                        const definition = this.tools[call.name];
+                        if (!Object.hasOwn(this.tools, call.name) || !Check(definition.input, call.args))
+                            throw new Error("Tool is missing or arguments failed validation");
+                        controller.signal.throwIfAborted();
+                        const result = await definition.execute(call.args, { callId: call.id, toolCallId: call.toolCallId, signal: controller.signal, ...(call.origin ? { origin: call.origin } : {}) });
+                        if (result === undefined || byteLength(JSON.stringify(result)) > 1024 * 1024)
+                            throw new Error("Tool must return a bounded JSON value");
+                        value = { result };
+                    }
+                    catch (error) {
+                        value = { error: String(error).slice(0, 2048), ...(controller.signal.aborted ? { uncertain: true } : {}) };
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                }
+            }
+            catch (error) {
+                value = { error: `Execution claim failed: ${String(error).slice(0, 1800)}`, uncertain: true };
+            }
+        }
+        // Persist before POST; reconnect resends this receipt, never the side effect.
+        receipt = { state: "done", outcome: value };
+        this.journal.calls[call.id] = receipt;
+        await this.save();
+        await this.http(`/calls/${call.id}/outcome`, "POST", value);
+        this.delivered.add(call.id);
+    }
+    async request(method, params = {}, options = {}) {
+        if (this.closed || this.fatal)
+            throw this.fatal ?? new AgentError("Client closed");
+        if (this.pending.size >= 8)
+            throw new AgentError("Too many outstanding requests");
+        const id = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+        if (this.pending.has(id))
+            throw new AgentError("Request already pending", 409, id);
+        const deferred = Promise.withResolvers();
+        // Attach immediately, even while the POST is pending, to avoid unhandled errors.
+        deferred.promise.catch(() => { });
+        this.pending.set(id, deferred);
+        const timer = setTimeout(() => {
+            this.pending.delete(id);
+            deferred.reject(new AgentError("Request timed out; inspect requestStatus() or reuse the same idempotencyKey", 0, id));
+        }, options.timeoutMs ?? 180_000);
+        try {
+            const record = await this.http("/requests", "POST", { id, method, params });
+            if (record.outcome)
+                this.settle(id, record.outcome);
+            return await deferred.promise;
+        }
+        catch (error) {
+            if (error instanceof AgentError) {
+                error.requestId ??= id;
+                throw error;
+            }
+            throw new AgentError(String(error), 0, id);
+        }
+        finally {
+            clearTimeout(timer);
+            this.pending.delete(id);
+        }
+    }
+    /** Observe an already accepted request. This never submits or re-executes work. */
+    async waitForRequest(id, options = {}) {
+        if (this.closed || this.fatal)
+            throw this.fatal ?? new AgentError("Client closed");
+        if (this.pending.has(id))
+            throw new AgentError("Request already pending", 409, id);
+        const deferred = Promise.withResolvers();
+        deferred.promise.catch(() => { });
+        this.pending.set(id, deferred);
+        const timer = setTimeout(() => {
+            deferred.reject(new AgentError("Request observation timed out; the request may still be running", 0, id));
+        }, options.timeoutMs ?? 180_000);
+        try {
+            const record = await this.requestStatus(id);
+            if (record.outcome)
+                this.settle(id, record.outcome);
+            return await deferred.promise;
+        }
+        finally {
+            clearTimeout(timer);
+            this.pending.delete(id);
+        }
+    }
+    prompt(text, options) { return this.request("prompt", { text, ...(options?.images ? { images: options.images } : {}) }, options); }
+    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 }); }
+    /** Change the prompt, thinking level, tools, or model ("provider/model-id") between runs. */
+    async configure(options) {
+        const result = await this.request("configure", { ...options, ...(options.tools ? { tools: definitions(options.tools) } : {}) });
+        if (options.tools) {
+            for (const key of Object.keys(this.tools))
+                delete this.tools[key];
+            Object.assign(this.tools, options.tools);
+        }
+        return result;
+    }
+    execute(code, options) {
+        return this.request("execute", { code, ...(options?.executionTimeoutMs ? { timeoutMs: options.executionTimeoutMs } : {}) }, 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)}`); }
+    outcomes() { return this.http("/state"); }
+    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;
+        // User callbacks must cooperate with cancellation. Do not hang shutdown on one.
+    }
+    async destroy() { try {
+        await this.http("", "DELETE");
+    }
+    finally {
+        await this.close();
+    } }
+    async [Symbol.asyncDispose]() { await this.close(); }
+}

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

@@ -0,0 +1,79 @@
+export declare const FRAME_BYTES = 1100000;
+/** `uncertain` marks an outcome nobody can confirm (timeout after claim, restart). It is informational, never a gate. */
+export type Outcome = {
+    result: unknown;
+    error?: never;
+    uncertain?: never;
+} | {
+    error: string;
+    uncertain?: boolean;
+    result?: never;
+};
+/** `expiresAt` is null for agents that live until deleted. */
+export interface SessionCredentials {
+    id: string;
+    token: string;
+    expiresAt: number | null;
+}
+export type RequestMethod = "prompt" | "execute" | "status" | "abort" | "history" | "continue" | "steer" | "followUp" | "configure";
+export type CallRecord = {
+    id: string;
+    toolCallId?: string;
+    requestId?: string;
+    createdAt?: number;
+    name: string;
+    args: Record<string, unknown>;
+    deadline: number;
+    /** `uncertain`: claimed, but the outcome was lost; the model was told it is unknown. */
+    state: "offered" | "started" | "completed" | "cancelled" | "uncertain";
+    outcome?: Outcome;
+    /** A result that arrived after the call was already settled as uncertain. */
+    lateOutcome?: Outcome;
+    /** Where the turn came from, set by the runtime (e.g. a channel and its sender), so tools can authorize. */
+    origin?: Record<string, unknown>;
+};
+export type RequestRecord = {
+    id: string;
+    startedAt?: number;
+    endedAt?: number;
+    prompt?: string;
+    code?: string;
+    fingerprint: string;
+    method: RequestMethod;
+    /** "running" covers queued runs too: a run has begun once `began` is set. */
+    state: "running" | "completed";
+    outcome?: Outcome;
+    /** When the agent actually started this run (runs queue behind each other). */
+    began?: number;
+    /** Kept until the run begins, so a queued run survives a restart and runs exactly once. */
+    params?: unknown;
+};
+export type ClientEvent = {
+    type: "tool_call";
+    call: CallRecord;
+} | {
+    type: "tool_cancel";
+    id: string;
+} | {
+    type: "event";
+    requestId: string;
+    event: any;
+} | {
+    type: "response";
+    id: string;
+    outcome: Outcome;
+};
+export type SessionState = {
+    cursor: number;
+    calls: CallRecord[];
+    requests: RequestRecord[];
+};
+/** A tool an application offers its agent; shared by the SDKs and the runtime. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    resultFormat?: "json" | "content";
+    exposure?: "direct" | "codemode" | "both";
+    executionMode?: "sequential" | "parallel";
+}

package/dist/shared/client-protocol.js

@@ -0,0 +1 @@
+export const FRAME_BYTES = 1_100_000;

package/dist/shared/durable-json.d.ts

@@ -0,0 +1,3 @@
+/** Local-disk commit before acknowledging a request or dispatching a side effect. */
+export declare function writeDurableJson(path: string, value: unknown): void;
+export declare function canonical(value: unknown): string;

package/dist/shared/durable-json.js

@@ -0,0 +1,36 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+/** Local-disk commit before acknowledging a request or dispatching a side effect. */
+export function writeDurableJson(path, value) {
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const fd = openSync(temporary, "wx", 0o600);
+    try {
+        writeFileSync(fd, JSON.stringify(value));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temporary, path);
+    const parent = openSync(directory, "r");
+    try {
+        fsyncSync(parent);
+    }
+    finally {
+        closeSync(parent);
+    }
+}
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new Error("Expected a JSON value");
+    return json;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@camelai/agent-runtime",
+  "version": "0.3.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qaml-ai/agent-runtime.git",
+    "directory": "sdk"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/clients/typescript.d.ts",
+      "default": "./dist/clients/typescript.js"
+    },
+    "./node": {
+      "types": "./dist/clients/node.d.ts",
+      "default": "./dist/clients/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "typebox": "1.1.38"
+  },
+  "homepage": "https://agents.camelai.dev"
+}