withruntime 0.18.0 → 0.21.0

package/dist/products/agents.js

@@ -0,0 +1,251 @@
+/** 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";
+const START = 'npx -y @anthropic-ai/claude-code --dangerously-skip-permissions --mcp-config ~/.runtime-agent/mcp.json -p "$(cat ~/.runtime-agent/start.md)"';
+const CODEX = 'npx -y @openai/codex exec --dangerously-bypass-approvals-and-sandbox "$(cat ~/.runtime-agent/start.md)"';
+const GEMINI = 'npx -y @google/gemini-cli --yolo -p "$(cat ~/.runtime-agent/start.md)"';
+/** The five harnesses (agents-contract.md); tests/agents.test.ts holds them
+ * to packages/cloud-guide/agent-templates.json. */
+export const AGENT_TEMPLATES = {
+    "claude-code": {
+        key: "claude-code",
+        title: "Claude Code",
+        command: START,
+        apiKeySecret: "ANTHROPIC_API_KEY",
+        apiKeyHost: "api.anthropic.com",
+        subscription: "token: run `claude setup-token` on your own computer (Pro/Max), then `runtime secrets set CLAUDE_CODE_OAUTH_TOKEN` scoped to api.anthropic.com",
+        definition: { command: START, secrets: ["ANTHROPIC_API_KEY"] },
+    },
+    codex: {
+        key: "codex",
+        title: "Codex CLI",
+        command: CODEX,
+        apiKeySecret: "OPENAI_API_KEY",
+        apiKeyHost: "api.openai.com",
+        subscription: "login once in the sandbox's terminal: `npx -y @openai/codex login --device-auth`, kept in the snapshot or a volume at `~/.codex`",
+        definition: { command: CODEX, secrets: ["OPENAI_API_KEY"] },
+    },
+    "gemini-cli": {
+        key: "gemini-cli",
+        title: "Gemini CLI",
+        command: GEMINI,
+        apiKeySecret: "GEMINI_API_KEY",
+        apiKeyHost: "generativelanguage.googleapis.com",
+        subscription: "login once in the sandbox's terminal (Sign in with Google), kept at `~/.gemini`",
+        definition: { command: GEMINI, secrets: ["GEMINI_API_KEY"] },
+    },
+    "claude-agent-sdk": {
+        key: "claude-agent-sdk",
+        title: "Claude Agent SDK",
+        command: "python3 ~/agent.py",
+        apiKeySecret: "ANTHROPIC_API_KEY",
+        apiKeyHost: "api.anthropic.com",
+        subscription: null,
+        definition: { command: "python3 ~/agent.py", secrets: ["ANTHROPIC_API_KEY"] },
+    },
+    "openai-agents-sdk": {
+        key: "openai-agents-sdk",
+        title: "OpenAI Agents SDK",
+        command: "python3 ~/agent.py",
+        apiKeySecret: "OPENAI_API_KEY",
+        apiKeyHost: "api.openai.com",
+        subscription: null,
+        definition: { command: "python3 ~/agent.py", secrets: ["OPENAI_API_KEY"] },
+    },
+};
+export const AGENT_USES = {
+    support: {
+        key: "support",
+        title: "Your customers",
+        sessionKey: "customer:<id>",
+        triggers: ["api", "webhook"],
+        definition: {
+            template: "support",
+            vcpu: 1,
+            memoryMiB: 1024,
+            idlePauseSeconds: 10,
+            maxConcurrent: 1000,
+        },
+    },
+    team: {
+        key: "team",
+        title: "Your team",
+        sessionKey: null,
+        triggers: ["slack", "github"],
+        definition: { template: "team", vcpu: 4, memoryMiB: 8192 },
+    },
+};
+const enc = encodeURIComponent;
+const ENDED = ["done", "failed", "stopped"];
+export function agents(t) {
+    const getSession = (id, options) => t.json({ method: "GET", path: `/v1/agents/sessions/${enc(id)}`, ...options });
+    async function* events(id, options = {}) {
+        let after = options.after ?? 0;
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const read = await t.json({
+                method: "GET",
+                path: `/v1/agents/sessions/${enc(id)}/events`,
+                query: { after, wait: 30 },
+                ...(options.signal ? { signal: options.signal } : {}),
+                timeoutMs: 0,
+            });
+            for (const event of read.data) {
+                after = event.seq;
+                yield event;
+            }
+            if (read.ended)
+                return;
+        }
+    }
+    const handle = (session, joined = false, seq = session.lastSeq) => ({
+        id: session.id,
+        session,
+        joined,
+        seq,
+        send: (text, options) => t.json({
+            method: "POST",
+            path: `/v1/agents/sessions/${enc(session.id)}/messages`,
+            body: { text },
+            ...options,
+        }),
+        events: (options) => events(session.id, options),
+        stop: (options) => t.json({
+            method: "POST",
+            path: `/v1/agents/sessions/${enc(session.id)}/stop`,
+            body: {},
+            ...options,
+        }),
+        async wait(options = {}) {
+            const now = await getSession(session.id, options);
+            if (ENDED.includes(now.state))
+                return now;
+            for await (const _ of events(session.id, { after: now.lastSeq, ...options }))
+                ;
+            return getSession(session.id, options);
+        },
+        get: (options) => getSession(session.id, options),
+    });
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/agents",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    const listSessions = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/agents/sessions",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => listSessions({ ...query, cursor }, options));
+    };
+    return {
+        /** An agent: a name and a definition its sessions start from. */
+        create: (input, options) => t.json({ method: "POST", path: "/v1/agents", body: input, ...options }),
+        /** By its id or its name. */
+        get: (agent, options) => t.json({ method: "GET", path: `/v1/agents/${enc(agent)}`, ...options }),
+        /** Your agents, oldest first. Await for a page, or `for await` for all. */
+        list,
+        /** A new version of the definition, whole; sessions already started keep theirs. */
+        update: (agent, definition, options) => t.json({
+            method: "PATCH",
+            path: `/v1/agents/${enc(agent)}`,
+            body: { definition },
+            ...options,
+        }),
+        /** Its triggers go and its open sessions stop. */
+        delete: async (agent, options) => {
+            await t.json({ method: "DELETE", path: `/v1/agents/${enc(agent)}`, ...options });
+        },
+        /** A session with its first words, or the open one with the same key joined. */
+        async start(agent, input, options) {
+            const out = await t.json({
+                method: "POST",
+                path: `/v1/agents/${enc(agent)}/sessions`,
+                body: input,
+                ...options,
+            });
+            return handle(out.session, out.joined, out.seq);
+        },
+        /** A session you already have, by its id. */
+        async session(id, options) {
+            return handle(await getSession(id, options));
+        },
+        sessions: {
+            get: getSession,
+            /** Newest first; of one agent, or in some states. */
+            list: listSessions,
+            /** 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: async (id, options) => {
+                await t.json({
+                    method: "DELETE",
+                    path: `/v1/agents/sessions/${enc(id)}`,
+                    ...options,
+                });
+            },
+        },
+        triggers: {
+            create: (agent, input, options) => t.json({
+                method: "POST",
+                path: `/v1/agents/${enc(agent)}/triggers`,
+                body: input,
+                ...options,
+            }),
+            list: async (agent, options) => (await t.json({
+                method: "GET",
+                path: `/v1/agents/${enc(agent)}/triggers`,
+                ...options,
+            })).data,
+            /** Its events are refused, saying `why`; nothing else is held. */
+            pause: (id, why, options) => t.json({
+                method: "POST",
+                path: `/v1/agents/triggers/${enc(id)}/pause`,
+                body: { why },
+                ...options,
+            }),
+            resume: (id, options) => t.json({
+                method: "POST",
+                path: `/v1/agents/triggers/${enc(id)}/resume`,
+                body: {},
+                ...options,
+            }),
+            delete: async (id, options) => {
+                await t.json({
+                    method: "DELETE",
+                    path: `/v1/agents/triggers/${enc(id)}`,
+                    ...options,
+                });
+            },
+        },
+        /** The harnesses, as data: claude-code, codex, gemini-cli,
+         * claude-agent-sdk, openai-agents-sdk. */
+        templates: AGENT_TEMPLATES,
+        /** The uses, as data: support (your customers) and team (your team). */
+        uses: AGENT_USES,
+    };
+}

package/dist/products/containers.d.ts

@@ -0,0 +1,71 @@
+/** Containers: one OCI image's process on its own microVM, billed at the
+ * sandbox rates (packages/cloud/src/api/products/containers.ts), at
+ * /v1/containers. In a private beta: an account outside it is refused with
+ * product_in_beta (403), and retrying does not change it. */
+import type { Transport } from "../transport.js";
+import { type ResourceRecord } from "./resources.js";
+export type ContainerState = "waiting" | "running" | "sleeping" | "stopped" | "failed" | "deleting" | "deleted";
+export type Container = ResourceRecord & {
+    name: string | null;
+    labels: Record<string, string>;
+    state: ContainerState;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    /** The image it runs, pinned to its digest (name@sha256:...). */
+    image: string;
+    entrypoint: string[];
+    command: string[];
+    workingDir: string;
+    user: string;
+    /** The TCP port it serves on, or null when it serves none. */
+    port: number | null;
+    /** The image's exposed ports, as N/tcp or N/udp. */
+    exposedPorts: string[];
+    onExit: "restart" | "stop";
+    sleep: boolean;
+    vcpu: number;
+    memoryMiB: number;
+    /** The environment's names. Values are never answered: they may be secrets. */
+    envNames: string[];
+};
+export type CreateContainer = {
+    /** An OCI image reference; the answer pins its digest. */
+    image: string;
+    /** 1 to 16. */
+    vcpu: number;
+    /** 128 to 65536 MiB. */
+    memoryMiB: number;
+    name?: string;
+    labels?: Record<string, string>;
+    /** Replaces the image's Entrypoint and drops its Cmd. */
+    entrypoint?: string[];
+    /** Replaces the image's Cmd; keeps the effective entrypoint. */
+    command?: string[];
+    /** Set over the image's own environment. */
+    env?: Record<string, string>;
+    /** An absolute path; the image's, else /. */
+    workingDir?: string;
+    /** The image's, else root. */
+    user?: string;
+    /** 1 to 65535. Required when the image exposes several TCP ports. */
+    port?: number;
+    /** Default: restart when it serves a port, otherwise stop. */
+    onExit?: "restart" | "stop";
+    /** Sleep when idle; false by default. */
+    sleep?: boolean;
+};
+/** Only the name and labels change; a null name clears it. */
+export type UpdateContainer = {
+    name?: string | null;
+    labels?: Record<string, string>;
+};
+export declare function containers(t: Transport): {
+    base: string;
+    create: (input: CreateContainer, options?: import("../transport.js").RequestOptions) => Promise<Container>;
+    get: (id: string, options?: import("./resources.js").ResourceGetOptions<"stopped" | "running" | "deleted" | "failed" | "deleting" | "waiting" | "sleeping">) => Promise<Container>;
+    list: (query?: import("./resources.js").ResourceListQuery<"stopped" | "running" | "deleted" | "failed" | "deleting" | "waiting" | "sleeping">, options?: import("../transport.js").RequestOptions) => Promise<import("../page.js").Page<Container>>;
+    update: (id: string, input: UpdateContainer, options?: import("../transport.js").RequestOptions) => Promise<Container>;
+    wait: (id: string, target: "stopped" | "running" | "deleted" | "failed" | "deleting" | "waiting" | "sleeping", options?: import("./resources.js").ResourceWaitOptions) => Promise<Container>;
+    delete: (id: string, options?: import("./resources.js").ResourceDeleteOptions) => Promise<Container>;
+};

package/dist/products/containers.js

@@ -0,0 +1,6 @@
+import { resource } from "./resources.js";
+/** A wait ends at its target or at one of these, with the container's error. */
+const SETTLED = ["failed", "deleted"];
+export function containers(t) {
+    return resource(t, "containers", SETTLED);
+}

package/dist/products/index.d.ts

@@ -21,6 +21,9 @@ import { sandboxTailscale } from "./tailscale.js";
 import { secrets } from "./secrets.js";
 import { mcp, sandboxMcp } from "./mcp.js";
 import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
+import { agents } from "./agents.js";
+import { builds } from "./builds.js";
+import { containers } from "./containers.js";
 export declare const clientExtensions: {
     images: typeof images;
     volumes: typeof volumes;
@@ -41,6 +44,9 @@ export declare const clientExtensions: {
     ports: typeof ports;
     ips: typeof ips;
     networks: typeof networks;
+    agents: typeof agents;
+    builds: typeof builds;
+    containers: typeof containers;
 };
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;

package/dist/products/index.js

@@ -19,6 +19,9 @@ import { sandboxTailscale } from "./tailscale.js";
 import { secrets } from "./secrets.js";
 import { mcp, sandboxMcp } from "./mcp.js";
 import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
+import { agents } from "./agents.js";
+import { builds } from "./builds.js";
+import { containers } from "./containers.js";
 /* HOW A LANE ADDS A PRODUCT TO THE SDK
  *
  * 1. Write src/products/<name>.ts exporting a factory:
@@ -54,6 +57,10 @@ export const clientExtensions = {
     ports,
     ips,
     networks,
+    agents,
+    // Builds (beta): the API answers product_in_beta outside its list.
+    builds,
+    containers,
 };
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,

package/dist/sandbox.d.ts

@@ -95,12 +95,15 @@ export declare class Sandbox extends Machine<SandboxInfo, SandboxSettings, Delet
      * each its own sandbox, answered once they run. A running sandbox is paused
      * for the moment its snapshot takes, then woken. One without `count`; an
      * array with it. `funding` is what the copies run on, as for a create;
+     * omitted, they keep this sandbox's. `secrets` names the egress secrets the
+     * copies may use, and may only narrow this sandbox's list: [] is none;
      * omitted, they keep this sandbox's. */
     fork(options?: {
         name?: string;
         labels?: Record<string, string>;
         keepSnapshot?: boolean;
         funding?: "trial" | "paid";
+        secrets?: string[];
     } & RequestOptions): Promise<Sandbox>;
     fork(options: {
         count: number;
@@ -108,6 +111,7 @@ export declare class Sandbox extends Machine<SandboxInfo, SandboxSettings, Delet
         labels?: Record<string, string>;
         keepSnapshot?: boolean;
         funding?: "trial" | "paid";
+        secrets?: string[];
     } & RequestOptions): Promise<Sandbox[]>;
 }
 /** A sandbox session, as the API answers it. `token` is set only in the

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.21.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -38,7 +38,7 @@ export type Query = Record<string, string | number | boolean | readonly string[]
 export type Call = RequestOptions & {
     /** Internal protocol hook: successful headers arrived, before reading the body. */
     onResponse?: (response: Response) => void;
-    method: "GET" | "POST" | "PUT" | "DELETE";
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     path: string;
     query?: Query;
     body?: unknown;

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
 import { warningText } from "./product-renames.js";
-export const VERSION = "0.18.0";
+export const VERSION = "0.21.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/tunnel.js

@@ -235,7 +235,7 @@ export class Tunnel {
                                 message: "The sandbox has no OpenSSH server (sshd).",
                                 code: "sshd_missing",
                                 status: 0,
-                                hint: "Install it once: sudo apt-get install -y openssh-server",
+                                hint: "Install it once: sudo apt-get update && sudo apt-get install -y openssh-server",
                             })
                             : new RuntimeError({
                                 message: `The sandbox refused the connection (${error.message}).`,

package/dist/types.d.ts

@@ -62,6 +62,12 @@ export type SandboxInfo = {
     /** The names of its own environment variables (`env`), on a create, an
      * update and a read of one sandbox. Values are never shown. */
     envNames?: string[];
+    /** The egress secrets this sandbox may use, by name: only those of your
+     * egress secrets that would otherwise reach it. Null is every secret that
+     * reaches it. Fixed for the sandbox's life; a fork or a copy of a snapshot
+     * may only narrow its source's list. On a create, an update, a fork and a
+     * read of one sandbox; absent from list pages and older servers. */
+    secrets?: string[] | null;
     /** On an update with labels by a key that may read secrets, when one of
      * the account's egress secrets is scoped: true once every server running its sandboxes holds the change,
      * so the next request uses the new scope; false while one has not
@@ -102,6 +108,11 @@ export type CreateSandbox = {
      * `env`. At most 32 variables and 32 KiB. Values are never shown again;
      * answers list only `envNames`. Copies made by fork() keep them. */
     env?: Record<string, string>;
+    /** The egress secrets this sandbox may use, by name: only those of your
+     * egress secrets that would otherwise reach it. [] is none; leave it out
+     * for every secret that reaches it. Fixed for the sandbox's life; a fork or
+     * a copy of a snapshot may only narrow its source's list. At most 64. */
+    secrets?: string[];
     /** Omit to use the free usage while it lasts, then prepaid credit. */
     funding?: "trial" | "paid";
     region?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.18.0",
+  "version": "0.21.0",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
@@ -55,6 +55,21 @@
       "import": "./dist/networks/index.js",
       "default": "./dist/networks/index.js"
     },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "import": "./dist/agents/index.js",
+      "default": "./dist/agents/index.js"
+    },
+    "./containers": {
+      "types": "./dist/containers/index.d.ts",
+      "import": "./dist/containers/index.js",
+      "default": "./dist/containers/index.js"
+    },
+    "./builds": {
+      "types": "./dist/builds/index.d.ts",
+      "import": "./dist/builds/index.js",
+      "default": "./dist/builds/index.js"
+    },
     "./e2b": {
       "types": "./dist/e2b/index.d.ts",
       "import": "./dist/e2b/index.js",