withruntime 0.18.0 → 0.21.0

package/dist/cloudflare/worker.js

@@ -1,12 +1,47 @@
-/** Workers conditional entry. The Durable Object coordinates requests and stores
- * configuration; Runtime owns compute. Existing Container/Wrangler declarations
- * still need removal during infrastructure migration. */
-import { DurableObject } from "cloudflare:workers";
-import { only, CompatibilityError } from "../compat/core.js";
+/** Workers conditional entry: what a Worker imports as `withruntime/cloudflare`.
+ * `Sandbox` is the Durable Object class the Worker exports and binds, as with
+ * @cloudflare/sandbox; it keeps the sandbox's name and preview tokens, and
+ * Runtime runs the sandbox. The Wrangler config drops its `containers` block. */
+import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
+import { only, refusal, CompatibilityError } from "../compat/core.js";
 import { Runtime } from "../client.js";
 import { workerSandboxIdentity } from "./identity.js";
-import { Sandbox as RuntimeSandbox, sanitizeSandboxId, validateSandboxConfiguration, } from "./index.js";
+import { Sandbox as RuntimeSandbox, SandboxSecurityError, sanitizeSandboxId, validateSandboxConfiguration, } from "./index.js";
 export * from "./index.js";
+/** Cloudflare's egress entrypoint for outbound interception, which Runtime
+ * does with network rules and secrets instead. */
+export class ContainerProxy extends WorkerEntrypoint {
+    fetch() {
+        return Promise.reject(refusal("Cloudflare", "ContainerProxy", OUTBOUND));
+    }
+}
+const OUTBOUND = "set the sandbox's network rules with Runtime's network API, and store keys as Runtime secrets, which Runtime's proxy adds to the requests you name";
+const TERMINAL = "open a terminal with the native Runtime sandbox's terminal()";
+/** Members of Cloudflare's Durable Object a Runtime sandbox has no counterpart
+ * for, refused with what to use instead. */
+const REFUSED = {
+    callTunnels: "use exposePort for a public URL",
+    setContainerTimeouts: "a Runtime sandbox has no container start to tune",
+    setTransport: "Runtime's API is the only transport",
+    containerFetch: "fetch the URL exposePort returns",
+    getContainerPlacementId: "a Runtime sandbox's id is its place",
+    createBackup: "snapshot the sandbox with Runtime's snapshots, or keep the folder on a volume",
+    restoreBackup: "create a sandbox from a Runtime snapshot",
+    terminal: TERMINAL,
+};
+/** Hooks and outbound settings a subclass of Cloudflare's class may set,
+ * which would otherwise be silently ignored. */
+const SUBCLASS = {
+    onStart: "a Runtime sandbox has no Durable Object lifecycle hooks",
+    onStop: "a Runtime sandbox has no Durable Object lifecycle hooks",
+    onError: "a Runtime sandbox has no Durable Object lifecycle hooks",
+    onActivityExpired: "set sleepAfter or keepAlive instead",
+    interceptHttps: OUTBOUND,
+    enableInternet: OUTBOUND,
+    allowedHosts: OUTBOUND,
+    deniedHosts: OUTBOUND,
+};
+const STATIC_OUTBOUND = ["outboundByHost", "outbound", "outboundHandlers"];
 const CONFIGURATION_KEY = "runtime.configuration";
 const CONFIGURATION_INTENT_KEY = "runtime.configuration.pending";
 /** Preserve the original failure even when durable recovery also fails. */
@@ -58,20 +93,46 @@ function sessionTarget(session) {
         exec: (command, options) => session.exec(command, options),
         execStream: (command, options) => session.execStream(command, options),
         startProcess: async (command, options) => processTarget(await session.startProcess(command, options)),
+        listProcesses: async () => (await session.listProcesses()).map((p) => processTarget(p)),
+        getProcess: async (id) => {
+            const p = await session.getProcess(id);
+            return p ? processTarget(p) : null;
+        },
+        killProcess: (id, signal) => session.killProcess(id, signal),
+        killAllProcesses: () => session.killAllProcesses(),
+        cleanupCompletedProcesses: () => session.cleanupCompletedProcesses(),
+        getProcessLogs: (id) => session.getProcessLogs(id),
+        streamProcessLogs: (id) => session.streamProcessLogs(id),
         writeFile: (...args) => session.writeFile(...args),
         readFile,
+        readFileStream: (path) => session.readFileStream(path),
         mkdir: (...args) => session.mkdir(...args),
         deleteFile: (path) => session.deleteFile(path),
         renameFile: (path, to) => session.renameFile(path, to),
         moveFile: (path, to) => session.renameFile(path, to),
         exists: (path) => session.exists(path),
         listFiles: (...args) => session.listFiles(...args),
+        gitCheckout: (repoUrl, options) => session.gitCheckout(repoUrl, options),
+        watch: (path, options) => session.watch(path, options),
+        checkChanges: (path, options) => session.checkChanges(path, options),
         setEnvVars: (...args) => session.setEnvVars(...args),
+        createCodeContext: (options) => session.createCodeContext(options),
+        runCode: (code, options) => session.runCode(code, options),
+        runCodeStream: (code, options) => session.runCodeStream(code, options),
+        listCodeContexts: () => session.listCodeContexts(),
+        deleteCodeContext: (id) => session.deleteCodeContext(id),
+        mountBucket: (bucket, path, options) => session.mountBucket(bucket, path, options),
+        unmountBucket: (path) => session.unmountBucket(path),
+        terminal: () => Promise.reject(refusal("Cloudflare", "ExecutionSession.terminal", TERMINAL)),
     };
 }
+/** A Process as plain data and callable members, as Cloudflare's RPC returns
+ * one. `pid` is absent: Runtime does not report it (Cloudflare's type has it
+ * optional). */
 function processTarget(process) {
     return {
         id: process.id,
+        pid: undefined,
         command: process.command,
         status: process.status,
         startTime: process.startTime,
@@ -83,6 +144,7 @@ function processTarget(process) {
         getLogs: () => process.getLogs(),
         waitForExit: (timeout) => process.waitForExit(timeout),
         waitForLog: (pattern, timeout) => process.waitForLog(pattern, timeout),
+        waitForPort: (port, options) => process.waitForPort(port, options),
     };
 }
 export class Sandbox extends DurableObject {
@@ -126,6 +188,7 @@ export class Sandbox extends DurableObject {
             throw new Error("Call getSandbox(namespace, id) before using the Durable Object");
         if (!this.env.RUNTIME_API_KEY?.startsWith("rtcloud_"))
             throw new Error("Set the RUNTIME_API_KEY Worker secret to a Runtime API key");
+        this.refuseSubclassSettings();
         this.facade ??= new RuntimeSandbox(new Runtime({ apiKey: this.env.RUNTIME_API_KEY, baseUrl: this.env.RUNTIME_API_URL }), workerSandboxIdentity(this.ctx.id.toString(), this.configuration), { ...this.configuration });
         return this.facade;
     }
@@ -308,34 +371,99 @@ export class Sandbox extends DurableObject {
     async setEnvVars(...args) {
         return (await this.sandbox()).setEnvVars(...args);
     }
+    // The rest of Cloudflare's 0.x Sandbox, each a call on the Runtime sandbox.
+    async setLabels(labels) {
+        return (await this.sandbox()).setLabels(labels);
+    }
+    async execWithSessionToken(command, sessionId, options) {
+        return (await this.sandbox(options?.signal)).execWithSessionToken(command, sessionId, options);
+    }
+    async execStreamWithSessionToken(command, sessionId, options) {
+        return (await this.sandbox(options?.signal)).execStreamWithSessionToken(command, sessionId, options);
+    }
+    async streamProcessLogs(processId, options) {
+        return (await this.sandbox(options?.signal)).streamProcessLogs(processId, options);
+    }
+    async cleanupCompletedProcesses(sessionId) {
+        return (await this.sandbox()).cleanupCompletedProcesses(sessionId);
+    }
+    async readFileStream(path, options) {
+        return (await this.sandbox()).readFileStream(path, options);
+    }
+    async gitCheckout(repoUrl, options) {
+        return (await this.sandbox()).gitCheckout(repoUrl, options);
+    }
+    async watch(path, options) {
+        return (await this.sandbox()).watch(path, options);
+    }
+    async checkChanges(path, options) {
+        return (await this.sandbox()).checkChanges(path, options);
+    }
+    async mountBucket(bucket, mountPath, options) {
+        return (await this.sandbox()).mountBucket(bucket, mountPath, options);
+    }
+    async unmountBucket(mountPath) {
+        return (await this.sandbox()).unmountBucket(mountPath);
+    }
+    async createCodeContext(options) {
+        return (await this.sandbox()).createCodeContext(options);
+    }
+    async runCode(code, options) {
+        return (await this.sandbox(options?.signal)).runCode(code, options);
+    }
+    async runCodeStream(code, options) {
+        return (await this.sandbox(options?.signal)).runCodeStream(code, options);
+    }
+    async listCodeContexts() {
+        return (await this.sandbox()).listCodeContexts();
+    }
+    async deleteCodeContext(contextId) {
+        return (await this.sandbox()).deleteCodeContext(contextId);
+    }
+    /** Stops the sandbox; its files stay, and the next call starts it again. */
+    async stop(signal) {
+        return (await this.sandbox()).stop(signal);
+    }
+    /** A subclass's Cloudflare-only hooks and outbound settings would do
+     * nothing here, so the first call refuses them by name. */
+    refuseSubclassSettings() {
+        for (const [member, alternative] of Object.entries(SUBCLASS))
+            if (this[member] !== undefined)
+                throw refusal("Cloudflare", `Sandbox.${member}`, alternative);
+        const statics = this.constructor;
+        for (const member of STATIC_OUTBOUND)
+            if (statics[member] !== undefined)
+                throw refusal("Cloudflare", `Sandbox.${member}`, OUTBOUND);
+    }
     exposePort(port, options) {
         return this.previewOperation(() => this.expose(port, options));
     }
     async expose(port, options) {
         only("Cloudflare Worker exposePort", options, ["name", "hostname", "token"]);
         if (!Number.isInteger(port) || port < 1024 || port > 65535 || port === 3000)
-            throw new TypeError("Preview port must be 1024-65535, excluding 3000");
-        if (!/^[a-z0-9.-]+$/i.test(options.hostname) ||
+            throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`, "INVALID_PORT");
+        if (!/^[a-z0-9.-]+(:\d{1,5})?$/i.test(options.hostname) ||
             options.hostname.startsWith(".") ||
-            options.hostname.endsWith("."))
+            /\.(:|$)/.test(options.hostname))
             throw new TypeError("Preview hostname must be a DNS hostname");
         if (options.hostname.endsWith(".workers.dev"))
-            throw new Error("Port exposure requires a custom domain; .workers.dev does not support wildcard preview subdomains");
+            throw new Error("Port exposure requires a custom domain. .workers.dev domains do not support wildcard subdomains required for port proxying.");
+        if (options.token !== undefined)
+            validateToken(options.token);
         const existing = await this.ctx.storage.get(`runtime.preview.${port}`);
-        const token = options.token ?? existing?.token ?? crypto.randomUUID().replaceAll("-", "");
+        const token = options.token ?? existing?.token ?? newToken();
         const ports = await this.ctx.storage.list({
             prefix: "runtime.preview.",
         });
-        if ([...ports.values()].some((p) => p.port !== port && p.token === token))
-            throw new Error(`Token '${token}' is already in use by another port`);
-        if (!/^[a-z0-9_]{1,63}$/.test(token))
-            throw new TypeError("Preview token must contain 1-63 lowercase letters, digits or underscores");
+        const taken = [...ports.values()].find((p) => p.port !== port && p.token === token);
+        if (taken)
+            throw new SandboxSecurityError(`Token '${token}' is already in use by port ${taken.port}. Please use a different token.`, "TOKEN_IN_USE");
         const sandbox = await this.sandbox();
         const name = this.configuration.sandboxName.name;
         if (name !== name.toLowerCase())
             throw new CompatibilityError("Cloudflare", "uppercase sandbox IDs in preview hostnames; use normalizeId:true");
         const native = await (await sandbox.native()).previews.create(port, { visibility: "private" });
-        const url = `https://${port}-${name}-${token}.${options.hostname}`;
+        const url = previewUrl(port, name, options.hostname, token);
         await this.ctx.storage.put(`runtime.preview.${port}`, {
             token,
             url,
@@ -366,7 +494,7 @@ export class Sandbox extends DurableObject {
                 prefix: "runtime.preview.",
             })).values(),
         ].map((p) => ({
-            url: `https://${p.port}-${this.configuration.sandboxName.name}-${p.token}.${hostname}`,
+            url: previewUrl(p.port, this.configuration.sandboxName.name, hostname, p.token),
             port: p.port,
             status: "active",
         }));
@@ -410,6 +538,9 @@ export class Sandbox extends DurableObject {
     }
 }
 export function getSandbox(namespace, id, options = {}) {
+    for (const [option, alternative] of Object.entries(OPTIONS))
+        if (options[option] !== undefined)
+            throw refusal("Cloudflare", `getSandbox ${option}`, alternative);
     only("Cloudflare Worker getSandbox", options, ["normalizeId", "sleepAfter", "keepAlive"]);
     sanitizeSandboxId(id);
     const name = options.normalizeId ? id.toLowerCase() : id;
@@ -422,6 +553,16 @@ export function getSandbox(namespace, id, options = {}) {
     // Await configuration for every operation so no request can race name setup.
     return new Proxy(stub, {
         get(target, key) {
+            // Cloudflare's getSandbox adds these on the Worker side; an RPC stub
+            // would answer every name, so refuse them here, by name.
+            if (key === "tunnels")
+                return tunnels;
+            if (key === "wsConnect")
+                return () => Promise.reject(refusal("Cloudflare", "Sandbox.wsConnect", "connect to the URL exposePort returns"));
+            if (key === "terminal")
+                return () => Promise.reject(refusal("Cloudflare", "Sandbox.terminal", TERMINAL));
+            if (key === "client")
+                throw refusal("Cloudflare", "Sandbox.client", "Runtime's API is the client");
             const value = Reflect.get(target, key);
             if (typeof value !== "function" || key === "then")
                 return value;
@@ -429,6 +570,51 @@ export function getSandbox(namespace, id, options = {}) {
         },
     });
 }
+for (const [member, alternative] of Object.entries(REFUSED))
+    Object.defineProperty(Sandbox.prototype, member, {
+        configurable: true,
+        writable: true,
+        value: () => Promise.reject(refusal("Cloudflare", `Sandbox.${member}`, alternative)),
+    });
+/** getSandbox options Cloudflare's class reads that a Runtime sandbox has no
+ * counterpart for. */
+const OPTIONS = {
+    containerTimeouts: "a Runtime sandbox has no container start to tune",
+    transport: "Runtime's API is the only transport",
+    enableDefaultSession: "commands share the default session; use createSession() for a separate shell",
+    labels: "call sandbox.setLabels(labels)",
+};
+const TUNNELS = "use exposePort for a URL to a port; Runtime serves it itself";
+const tunnels = Object.fromEntries(["get", "list", "destroy"].map((method) => [
+    method,
+    () => Promise.reject(refusal("Cloudflare", `Sandbox.tunnels.${method}`, TUNNELS)),
+]));
+/** Cloudflare's preview URL for a port: `http` and the given port on a local
+ * hostname, `https` otherwise, built as its SDK builds it. */
+function previewUrl(port, sandboxId, hostname, token) {
+    const id = sanitizeSandboxId(sandboxId).toLowerCase();
+    const [host = "", mainPort] = hostname.split(":");
+    const local = ["localhost", "127.0.0.1", "0.0.0.0"].includes(host);
+    const base = new URL(local ? `http://${host}:${mainPort || "80"}` : `https://${hostname}`);
+    base.hostname = `${port}-${id}-${token}.${host}`;
+    return base.toString();
+}
+function validateToken(token) {
+    if (token.length === 0)
+        throw new SandboxSecurityError("Custom token cannot be empty.", "INVALID_TOKEN");
+    if (token.length > 16)
+        throw new SandboxSecurityError(`Custom token too long. Maximum 16 characters allowed. Received: ${token.length} characters.`, "INVALID_TOKEN");
+    if (!/^[a-z0-9_]+$/.test(token))
+        throw new SandboxSecurityError("Custom token must contain only lowercase letters (a-z), numbers (0-9), and underscores (_). Invalid token provided.", "INVALID_TOKEN");
+}
+/** 16 characters of a-z, 0-9 and _, as Cloudflare's tokens are. */
+function newToken() {
+    const bytes = crypto.getRandomValues(new Uint8Array(12));
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/[+/]/g, "_")
+        .replace(/=/g, "")
+        .toLowerCase();
+}
 function previewRoute(url) {
     const label = url.hostname.split(".")[0] ?? "";
     const match = /^(\d{4,5})-([a-z0-9_-]+)-([a-z0-9_]{1,63})$/.exec(label);

package/dist/containers/index.d.ts

@@ -0,0 +1,10 @@
+/** `withruntime/containers`: Containers alone. One OCI image's process on its
+ * own microVM, at the sandbox rates. In a private beta.
+ *
+ *   import { containers } from "withruntime/containers";
+ *   const client = containers(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/containers.js";
+/** `runtime.containers` of a client made with `options`. */
+export declare function containers(options?: RuntimeOptions): Runtime["containers"];

package/dist/containers/index.js

@@ -0,0 +1,11 @@
+/** `withruntime/containers`: Containers alone. One OCI image's process on its
+ * own microVM, at the sandbox rates. In a private beta.
+ *
+ *   import { containers } from "withruntime/containers";
+ *   const client = containers(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.containers` of a client made with `options`. */
+export function containers(options) {
+    return new Runtime(options).containers;
+}

package/dist/index.d.ts

@@ -76,3 +76,6 @@ export { openWalletAccount, claimWalletAccount, rekeyWalletAccount, type OpenedW
 export type { Topup } from "./products/billing.js";
 export type { NewKey, LimitedKey, LimitedKeyAction, MadeKey, ListedKey, KeyUsage, } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";
+export type { Agent, AgentDefinition, AgentEvent, AgentSession, AgentSessionHandle, AgentSessionState, AgentTemplate, AgentTemplateKey, AgentTrigger, AgentTriggerKind, AgentUse, CreateAgent, CreateAgentTrigger, StartAgentSession, } from "./products/agents.js";
+export { AGENT_TEMPLATES, AGENT_USES } from "./products/agents.js";
+export type { Container, ContainerState, CreateContainer, UpdateContainer, } from "./products/containers.js";

package/dist/index.js

@@ -48,3 +48,4 @@ export class Sandbox extends SandboxClass {
 }
 export { identityToken } from "./identity.js";
 export { openWalletAccount, claimWalletAccount, rekeyWalletAccount, } from "./wallet.js";
+export { AGENT_TEMPLATES, AGENT_USES } from "./products/agents.js";

package/dist/product-names.js

@@ -34,6 +34,8 @@ export const PRODUCT_NAMES = [
     { name: "jobs", title: "Jobs", engine: "machine", singular: "job", old: was("job") },
     { name: "workflows", title: "Workflows", engine: "machine", singular: "workflow", old: [] },
     { name: "builds", title: "Builds", engine: "machine", singular: "build", old: [] },
+    { name: "agents", title: "Agents", engine: "machine", singular: "agent", old: [] },
+    { name: "ci", title: "CI/CD", engine: "machine", old: [] },
     // Disk
     { name: "volumes", title: "Volumes", engine: "disk", singular: "volume", old: was("volume") },
     {
@@ -91,6 +93,7 @@ export const PRODUCT_NAMES = [
     { name: "usage", title: "Usage", engine: "meter", old: [] },
     { name: "billing", title: "Billing", engine: "meter", old: [] },
     { name: "metrics", title: "Metrics", engine: "meter", old: [] },
+    { name: "plans", title: "Plans", engine: "meter", singular: "plan", old: [] },
     // Database (not now: CLOUD.md section 2)
     { name: "postgres", title: "Postgres", engine: "database", old: [] },
     { name: "mysql", title: "MySQL", engine: "database", old: [] },

package/dist/products/agents.d.ts

@@ -0,0 +1,272 @@
+/** Agents: a coding or support agent's harness (Claude Code, Codex, Gemini
+ * CLI, or your own code on an agents SDK) in a sandbox of its own per
+ * session, on your own model key. Your app drives its sessions through this
+ * API and webhooks. In a private beta: outside it every call is refused with
+ * `product_in_beta`.
+ *
+ *   const agent = await runtime.agents.create({
+ *     name: "support",
+ *     definition: {
+ *       ...runtime.agents.templates["claude-code"].definition,
+ *       ...runtime.agents.uses.support.definition,
+ *       instructions: "Answer questions about our product. Be brief.",
+ *     },
+ *   });
+ *   const session = await runtime.agents.start("support", { input: "Hi!", key: "customer:42" });
+ *   for await (const event of session.events()) if (event.kind === "reply") console.log(event.body.text);
+ *
+ * A session's sandbox is billed while it runs, at $0.03 per active vCPU-hour
+ * and $0.01 per GiB-hour of memory; a waiting session's sandbox is paused.
+ * No session fee, no seats. */
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type AgentDefinition = {
+    /** What runs the harness, from the sandbox's home. */
+    command: string;
+    /** Where each session's sandbox starts: an image of yours, or a snapshot
+     * of a machine you set up by hand (a harness logged in to your own
+     * subscription included). The default image has Node and Python. */
+    from?: {
+        image: string;
+    } | {
+        snapshot: string;
+    };
+    /** 1, 2, 4, 8 or 16; default 4. */
+    vcpu?: number;
+    /** 512 to 65536, a multiple of 256; default 8192 (8 GiB). */
+    memoryMiB?: number;
+    /** The agent's standing words, at most 64 KiB. */
+    instructions?: string;
+    /** Settings the harness sees; never a secret. */
+    env?: Record<string, string>;
+    /** Names of your egress secrets the sandbox may use: it sees a placeholder,
+     * and the egress proxy adds the value toward the secret's hosts. Model
+     * keys of any provider go here (ANTHROPIC_API_KEY, OPENAI_API_KEY,
+     * GEMINI_API_KEY, OPENROUTER_API_KEY, or an OpenAI-compatible endpoint's
+     * key with env.OPENAI_BASE_URL). */
+    secrets?: string[];
+    /** MCP servers the harness may reach. */
+    mcp?: {
+        name: string;
+        url: string;
+    }[];
+    volumes?: {
+        volume: string;
+        path: string;
+    }[];
+    /** How long a session's sandbox runs with nothing happening before it
+     * pauses; default 60. */
+    idlePauseSeconds?: number;
+    /** A session's longest life; default 86400. */
+    maxSessionSeconds?: number;
+    /** Sessions running at once; more wait, queued. Default 10. */
+    maxConcurrent?: number;
+    /** The use it was set up for (`uses`). */
+    template?: "support" | "team";
+};
+export type Agent = {
+    id: string;
+    name: string;
+    version: number;
+    /** With its defaults written in. */
+    definition: AgentDefinition;
+    labels: Record<string, string>;
+    /** `subscription_for_customers`: its secrets name CLAUDE_CODE_OAUTH_TOKEN
+     * and it is set up to answer your customers (`template: "support"`). A
+     * subscription is for your own team's agents; an agent that serves your
+     * customers uses an API key. */
+    warnings: "subscription_for_customers"[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type AgentSessionState = "queued" | "running" | "waiting" | "done" | "failed" | "stopped";
+/** One session. Subagents' parentSessionId and rootSessionId, its cost and
+ * treeCost, historyBytes and attachmentBytes join it as the API gains
+ * them. */
+export type AgentSession = {
+    id: string;
+    agentId: string;
+    agentVersion: number;
+    key: string | null;
+    trigger: "api" | AgentTriggerKind;
+    state: AgentSessionState;
+    /** Why it ended. */
+    reason: string | null;
+    /** What the agent said it ended with: a pull request's address, an answer. */
+    result: string | null;
+    sandboxId: string | null;
+    lastSeq: number;
+    labels: Record<string, string>;
+    createdAt: string;
+    startedAt: string | null;
+    endedAt: string | null;
+};
+export type AgentEvent = {
+    seq: number;
+    kind: "input" | "answer" | "reply" | "ask" | "status" | "result" | "error" | "note";
+    /** A key's principal id, slack:<user>, github:<login>, agent (the
+     * harness) or runtime. */
+    actor: string;
+    /** Words are body.text. */
+    body: {
+        text?: string;
+    } & Record<string, unknown>;
+    createdAt: string;
+};
+export type AgentTriggerKind = "slack" | "github" | "schedule" | "webhook";
+export type AgentTrigger = {
+    id: string;
+    agentId: string;
+    kind: AgentTriggerKind;
+    config: Record<string, unknown>;
+    pausedAt: string | null;
+    pausedWhy: string | null;
+    createdAt: string;
+    /** A webhook's secret, which each of its calls carries: answered once,
+     * when it is added, and never again. Keep it where you keep your keys. */
+    secret?: string;
+};
+export type CreateAgent = {
+    name: string;
+    definition: AgentDefinition;
+    labels?: Record<string, string>;
+};
+export type StartAgentSession = {
+    input: string;
+    /** Words with the same key join its open session: a Slack thread, a pull
+     * request, one of your customers (`customer:42`). */
+    key?: string;
+    labels?: Record<string, string>;
+};
+export type CreateAgentTrigger = {
+    kind: "slack";
+    config: {
+        team: string;
+        channel: string;
+    };
+} | {
+    kind: "github";
+    config: {
+        installation: number;
+        repository: string;
+        events?: string[];
+    };
+} | {
+    kind: "schedule";
+    config: {
+        cron: string;
+        timezone?: string;
+        input: string;
+    };
+} | {
+    kind: "webhook";
+    config: Record<string, never>;
+};
+/** The five harnesses' names, so `templates["claude-code"]` is known to be there. */
+export type AgentTemplateKey = "claude-code" | "codex" | "gemini-cli" | "claude-agent-sdk" | "openai-agents-sdk";
+/** A harness, as data (packages/cloud-guide/agent-templates.json, the same
+ * in every SDK and the guide). `definition` is what an agent's definition
+ * takes from it; add a use's (`uses`) and your instructions. */
+export type AgentTemplate = {
+    key: AgentTemplateKey;
+    title: string;
+    command: string;
+    /** The egress secret its API key is stored as, and the host it is for. */
+    apiKeySecret: string;
+    apiKeyHost: string;
+    /** How your own subscription logs it in, for your own team's agents, or
+     * null when it takes an API key alone. */
+    subscription: string | null;
+    definition: {
+        command: string;
+        secrets: string[];
+    };
+};
+/** A use: what an agent is for, merged into a template's definition. */
+export type AgentUse = {
+    key: "support" | "team";
+    title: string;
+    /** How its sessions are keyed: the key your app passes per customer, or
+     * none. */
+    sessionKey: string | null;
+    triggers: ("api" | AgentTriggerKind)[];
+    definition: Partial<AgentDefinition> & {
+        template: "support" | "team";
+    };
+};
+/** The five harnesses (agents-contract.md); tests/agents.test.ts holds them
+ * to packages/cloud-guide/agent-templates.json. */
+export declare const AGENT_TEMPLATES: Readonly<Record<AgentTemplateKey, AgentTemplate>>;
+export declare const AGENT_USES: Readonly<Record<"support" | "team", AgentUse>>;
+/** One session, to talk to and follow. */
+export type AgentSessionHandle = {
+    readonly id: string;
+    /** The session as it was when started or read. */
+    readonly session: AgentSession;
+    /** Whether the start's words joined a session already open with its key. */
+    readonly joined: boolean;
+    /** The seq of the words that started or joined it. */
+    readonly seq: number;
+    /** Words in; answers their seq. */
+    send(text: string, options?: RequestOptions): Promise<{
+        seq: number;
+    }>;
+    /** Its log after `after` (0 by default), each event as it comes, waiting
+     * up to 30 seconds a call; ends when the session has ended. */
+    events(options?: {
+        after?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
+    stop(options?: RequestOptions): Promise<AgentSession>;
+    /** Until it has ended; answers it then. */
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSession>;
+    get(options?: RequestOptions): Promise<AgentSession>;
+};
+export declare function agents(t: Transport): {
+    /** An agent: a name and a definition its sessions start from. */
+    create: (input: CreateAgent, options?: RequestOptions) => Promise<Agent>;
+    /** By its id or its name. */
+    get: (agent: string, options?: RequestOptions) => Promise<Agent>;
+    /** Your agents, oldest first. Await for a page, or `for await` for all. */
+    list: (query?: {
+        cursor?: string;
+        limit?: number;
+    }, options?: RequestOptions) => Promise<Page<Agent>>;
+    /** A new version of the definition, whole; sessions already started keep theirs. */
+    update: (agent: string, definition: AgentDefinition, options?: RequestOptions) => Promise<Agent>;
+    /** Its triggers go and its open sessions stop. */
+    delete: (agent: string, options?: RequestOptions) => Promise<void>;
+    /** A session with its first words, or the open one with the same key joined. */
+    start(agent: string, input: StartAgentSession, options?: RequestOptions): Promise<AgentSessionHandle>;
+    /** A session you already have, by its id. */
+    session(id: string, options?: RequestOptions): Promise<AgentSessionHandle>;
+    sessions: {
+        get: (id: string, options?: RequestOptions) => Promise<AgentSession>;
+        /** Newest first; of one agent, or in some states. */
+        list: (query?: {
+            agent?: string;
+            state?: AgentSessionState[];
+            cursor?: string;
+            limit?: number;
+        }, options?: RequestOptions) => Promise<Page<AgentSession>>;
+        /** An ended session and its log go. Its history is storage like any
+         * other, kept until you delete it; an open session is refused
+         * (`session_open`): stop it first. */
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    triggers: {
+        create: (agent: string, input: CreateAgentTrigger, options?: RequestOptions) => Promise<AgentTrigger>;
+        list: (agent: string, options?: RequestOptions) => Promise<AgentTrigger[]>;
+        /** Its events are refused, saying `why`; nothing else is held. */
+        pause: (id: string, why: string, options?: RequestOptions) => Promise<AgentTrigger>;
+        resume: (id: string, options?: RequestOptions) => Promise<AgentTrigger>;
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    /** The harnesses, as data: claude-code, codex, gemini-cli,
+     * claude-agent-sdk, openai-agents-sdk. */
+    templates: Readonly<Record<AgentTemplateKey, AgentTemplate>>;
+    /** The uses, as data: support (your customers) and team (your team). */
+    uses: Readonly<Record<"team" | "support", AgentUse>>;
+};