withruntime 0.17.2 → 0.21.0

package/COMPATIBILITY.md

@@ -102,6 +102,37 @@ all 73 inventory items are present or refused, none missing. How it maps:
   `withruntime.morph`, inventoried as `morph-python`; see
   [the Python document](../../sdks/python/COMPATIBILITY.md).
 
+### Cloudflare 0.12.10 Worker examples, live (18 October 2026)
+
+`tests/compat/cloudflare-examples/` holds Cloudflare's own Workers, copied
+verbatim with their source URL and the date read: the `minimal` and `alpine`
+examples at the `@cloudflare/sandbox@0.12.10` tag, the get-started Worker, and
+the runnable 0.x snippets from the docs on exec, streaming, files, background
+processes, the code interpreter, preview URLs, sessions and `gitCheckout`. The
+only change in each is the package name and, in `wrangler.jsonc`, the removed
+`containers` block. `fixtures.ts` lists what each must answer, and the
+examples skipped with the reason (Workers AI, Artifacts, model keys, backups,
+tunnels, terminals, placeholder repositories, or a call 0.12.10 does not have).
+
+- `RUNTIME_API_KEY=... bun scripts/compatibility-cloudflare-live.ts --run`
+  builds the package, runs each example under `wrangler dev` (workerd) with the
+  key as a Worker secret, sends the requests the docs describe, and checks the
+  answers. A local relay caps it at 12 sandboxes, gives each a 10 minute limit
+  and a cost cap, labels them with the run, and deletes them after each Worker
+  and at the end.
+- 18 October 2026: 58 of 58 checks passed, 9 sandboxes created, all deleted.
+- The run found that the Worker's Durable Object lacked most of the module's
+  calls (`gitCheckout`, `runCode`, `streamProcessLogs` and the session calls
+  failed with "RPC receiver does not implement"), `waitForPort` was missing,
+  local preview URLs were not Cloudflare's `http://<port>-<id>-<token>.localhost`,
+  `readFile` had no `mimeType`, and 14 of upstream's value exports and about
+  70 of its types were missing. `tests/compat/cloudflare-worker-surface.test.ts`
+  checks each.
+- Differences that stay: a sandbox holds at most 4 code contexts (a fifth
+  `createCodeContext` says how to free one); a process's `pid` is not
+  reported; `processId` and `autoCleanup` refuse. Errors across a Durable
+  Object call keep their message but not `code`, as on Cloudflare.
+
 ### Freestyle 0.2.18, 0.2.19 and 0.2.20 review (15 October 2026)
 
 The pin advances from 0.2.17 to 0.2.20; support remains partial. The four npm
@@ -311,7 +342,7 @@ Remaining implementation work is tracked only in the repository `WORKLIST.md`.
 | Sprites     | No control-mode WebSocket protocol, managed services, in-place checkpoint restore (start a new sandbox from the snapshot), checkpoint history filters, network presets (`include`), an allow rule inside a denied wildcard (Runtime's deny always wins), privilege or resource policies, `maxRunAfterDisconnect`, Fly token exchange or Sprite list streaming; each is refused by name. A checkpoint is a Runtime disk snapshot (files, not running processes); the Sprite pauses for the moment it takes. An allow rule makes an allowlist, as Sprites' DNS allowlist does. The port watcher polls `ss` once a second. Session handles use native process IDs, not tmux. The sprite URL maps port 8080. File bytes and process byte streams preserve binary data.                                                                                                                                    |
 | Freestyle   | Provider catalog snapshot slugs are not Runtime snapshots and are refused. Firewall support is limited to an explicit empty rule set or the exact allow-public-outbound shape; arbitrary rule selectors, TLS policies and private networks are refused. No automatic-restart guarantee, retention scheduler, placement constraints, live resize, Linux-user switching, PTY namespace, public IPv6 or account-owned egress address emulation. Native snapshot retention is positive whole days.                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Modal       | CPU sandboxes only; different resource reservation/limit values, fractional CPU, GPU and foreign placement are refused. Named Apps group Runtime sandboxes; they do not deploy Functions. Registry authentication uses Runtime's registry configuration. No Functions/Cls, volumes/bucket mounts, GPU image steps, readiness probes, sidecars, directory mounts, filesystem-only images from snapshots, or snapshot restoration API. Entry-point completion stops the sandbox while the originating client is alive; the native lease remains the bound if that client disappears. A different client can reconnect using the saved entrypoint process ID.                                                                                                                                                                                                                                            |
-| Cloudflare  | The conditional Worker entry supplies a Durable Object bridge and custom-hostname preview proxy; infrastructure configuration must still remove the vendor Container declaration and provide Runtime secrets. Custom preview routing is implemented but has no live public-hostname acceptance evidence. No isolated PID namespaces, interpreter contexts, bucket mounts, backup format, terminal WebSocket protocol, watchers/change versions, custom process IDs or provider cleanup-record semantics. Foreground named sessions use resident Bash; background processes inherit exported state/cwd but do not yet inherit every local variable/function/option.                                                                                                                                                                                                                                    |
+| Cloudflare  | The conditional Worker entry supplies a Durable Object bridge and custom-hostname preview proxy; infrastructure configuration must still remove the vendor Container declaration and provide Runtime secrets. Cloudflare's examples run live under `wrangler dev` (above); custom preview routing has no live public-hostname acceptance evidence. At most 4 interpreter contexts. No isolated PID namespaces, backup format, terminal WebSocket protocol, custom process IDs or provider cleanup-record semantics. Foreground named sessions use resident Bash; background processes inherit exported state/cwd but do not yet inherit every local variable/function/option.                                                                                                                                                                                                                         |
 
 ## Keeping compatibility current
 

package/README.md

@@ -162,6 +162,25 @@ copies memory and processes. `stop` deletes the sandbox, as Morph's does.
 SSH, reboot and a time limit set after start throw `CompatibilityError`
 naming the alternative. `COMPATIBILITY.md` lists every mapping.
 
+## Code written for Cloudflare's Sandbox SDK
+
+`withruntime/cloudflare` runs a Worker written for Cloudflare's 0.x
+`@cloudflare/sandbox` API on Runtime sandboxes. Change the package name in the
+import and in the `Sandbox` export:
+
+```ts no-run
+import { getSandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
+export { Sandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
+```
+
+Then delete the `containers` block from the Wrangler config, keeping the
+`Sandbox` Durable Object binding, and store a key with
+`npx wrangler secret put RUNTIME_API_KEY`. Exec, streaming, files, processes,
+the code interpreter, sessions, `gitCheckout` and `exposePort` work as
+Cloudflare documents them; backups, tunnels, terminals and outbound
+interception throw `CompatibilityError` naming the alternative.
+`COMPATIBILITY.md` lists every mapping.
+
 ## Agent frameworks
 
 `withruntime/openai-agents` is a sandbox client for the OpenAI Agents SDK's

package/README.src.md

@@ -164,6 +164,25 @@ copies memory and processes. `stop` deletes the sandbox, as Morph's does.
 SSH, reboot and a time limit set after start throw `CompatibilityError`
 naming the alternative. `COMPATIBILITY.md` lists every mapping.
 
+## Code written for Cloudflare's Sandbox SDK
+
+`withruntime/cloudflare` runs a Worker written for Cloudflare's 0.x
+`@cloudflare/sandbox` API on Runtime sandboxes. Change the package name in the
+import and in the `Sandbox` export:
+
+```ts no-run
+import { getSandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
+export { Sandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
+```
+
+Then delete the `containers` block from the Wrangler config, keeping the
+`Sandbox` Durable Object binding, and store a key with
+`npx wrangler secret put RUNTIME_API_KEY`. Exec, streaming, files, processes,
+the code interpreter, sessions, `gitCheckout` and `exposePort` work as
+Cloudflare documents them; backups, tunnels, terminals and outbound
+interception throw `CompatibilityError` naming the alternative.
+`COMPATIBILITY.md` lists every mapping.
+
 ## Agent frameworks
 
 `withruntime/openai-agents` is a sandbox client for the OpenAI Agents SDK's

package/dist/agents/index.d.ts

@@ -0,0 +1,11 @@
+/** `withruntime/agents`: Agents alone. A harness in a sandbox of its own per
+ * session, on your own model key. In a private beta.
+ *
+ *   import { agents } from "withruntime/agents";
+ *   const client = agents(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/agents.js";
+export { AGENT_TEMPLATES, AGENT_USES } from "../products/agents.js";
+/** `runtime.agents` of a client made with `options`. */
+export declare function agents(options?: RuntimeOptions): Runtime["agents"];

package/dist/agents/index.js

@@ -0,0 +1,12 @@
+/** `withruntime/agents`: Agents alone. A harness in a sandbox of its own per
+ * session, on your own model key. In a private beta.
+ *
+ *   import { agents } from "withruntime/agents";
+ *   const client = agents(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+export { AGENT_TEMPLATES, AGENT_USES } from "../products/agents.js";
+/** `runtime.agents` of a client made with `options`. */
+export function agents(options) {
+    return new Runtime(options).agents;
+}

package/dist/agents-cli.d.ts

@@ -0,0 +1,10 @@
+import type { CliKit } from "./cli.js";
+import type { Runtime } from "./client.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare const AGENT_HELP = "runtime agents <command>\n\n  An agent runs a harness (Claude Code, Codex, Gemini CLI, or your own code on\n  an agents SDK) in a sandbox of its own for each session, on your model key.\n  In a private beta: outside it, each command says how to ask to join.\n\n  templates                                   The harnesses and uses to start from\n  create <name> (--template <harness> | --command \"<cmd>\") [--use support|team]\n         [--instructions <text> | --instructions-file <path>] [--secret NAME]...\n         [--env KEY=VALUE]... [--image <image> | --snapshot <id>] [--vcpu n] [--memory n]\n         [--max-concurrent n] [--idle-pause n] [--label key=value]...\n                                              Make an agent; prints its id. --secret names an egress\n                                              secret it may use: its model key, of any provider\n  ls                                          Your agents\n  get <agent>                                 One agent, in full (an id or its name)\n  update <agent> [the options of create]      A new version: what you give changes, the rest stays\n  rm <agent>                                  Delete it, its triggers, and stop its sessions\n  start <agent> <words...> [--key <key>] [--follow]\n                                              A session with these words, or the open one with the\n                                              key (such as customer:42); --follow prints its log\n                                              until it ends\n  send <session> <words...>                   Words into a session\n  events <session> [--after <seq>] [--follow] A session's log; --follow until it ends\n  sessions [--agent <agent>] [--state <state>]...\n                                              Sessions, newest first\n  sessions delete <session>                   Delete an ended session and its log; its history is\n                                              storage, kept until you delete it\n  stop <session>                              Stop a session\n  triggers <agent>                            Its triggers\n  triggers add <agent> --kind <slack|github|schedule|webhook> --config '<json>'\n  triggers pause <triggerId> --why <words>    Refuse its events, saying why; nothing else is held\n  triggers resume <triggerId>\n  triggers rm <triggerId>\n\n  A subscription is for your own team's agents; an agent that serves your\n  customers uses an API key.\n\nExamples\n  printf %s \"$ANTHROPIC_API_KEY\" | runtime secrets set ANTHROPIC_API_KEY --host api.anthropic.com\n  runtime agents create helper --template claude-code --use support --instructions \"Answer briefly.\"\n  runtime agents start helper \"How do I reset my password?\" --key customer:42 --follow\n";
+export declare function agentsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export {};

package/dist/agents-cli.js

@@ -0,0 +1,362 @@
+import { readFileSync } from "node:fs";
+import { me, named } from "./cli-name.js";
+import { AGENT_TEMPLATES, AGENT_USES, agents, } from "./products/agents.js";
+export const AGENT_HELP = `runtime agents <command>
+
+  An agent runs a harness (Claude Code, Codex, Gemini CLI, or your own code on
+  an agents SDK) in a sandbox of its own for each session, on your model key.
+  In a private beta: outside it, each command says how to ask to join.
+
+  templates                                   The harnesses and uses to start from
+  create <name> (--template <harness> | --command "<cmd>") [--use support|team]
+         [--instructions <text> | --instructions-file <path>] [--secret NAME]...
+         [--env KEY=VALUE]... [--image <image> | --snapshot <id>] [--vcpu n] [--memory n]
+         [--max-concurrent n] [--idle-pause n] [--label key=value]...
+                                              Make an agent; prints its id. --secret names an egress
+                                              secret it may use: its model key, of any provider
+  ls                                          Your agents
+  get <agent>                                 One agent, in full (an id or its name)
+  update <agent> [the options of create]      A new version: what you give changes, the rest stays
+  rm <agent>                                  Delete it, its triggers, and stop its sessions
+  start <agent> <words...> [--key <key>] [--follow]
+                                              A session with these words, or the open one with the
+                                              key (such as customer:42); --follow prints its log
+                                              until it ends
+  send <session> <words...>                   Words into a session
+  events <session> [--after <seq>] [--follow] A session's log; --follow until it ends
+  sessions [--agent <agent>] [--state <state>]...
+                                              Sessions, newest first
+  sessions delete <session>                   Delete an ended session and its log; its history is
+                                              storage, kept until you delete it
+  stop <session>                              Stop a session
+  triggers <agent>                            Its triggers
+  triggers add <agent> --kind <slack|github|schedule|webhook> --config '<json>'
+  triggers pause <triggerId> --why <words>    Refuse its events, saying why; nothing else is held
+  triggers resume <triggerId>
+  triggers rm <triggerId>
+
+  A subscription is for your own team's agents; an agent that serves your
+  customers uses an API key.
+
+Examples
+  printf %s "$ANTHROPIC_API_KEY" | runtime secrets set ANTHROPIC_API_KEY --host api.anthropic.com
+  runtime agents create helper --template claude-code --use support --instructions "Answer briefly."
+  runtime agents start helper "How do I reset my password?" --key customer:42 --follow
+`;
+const when = (iso) => iso ?? "-";
+const OPTIONS = [
+    "template",
+    "use",
+    "command",
+    "instructions",
+    "instructions-file",
+    "secret",
+    "env",
+    "image",
+    "snapshot",
+    "vcpu",
+    "memory",
+    "max-concurrent",
+    "idle-pause",
+    "label",
+];
+const STATES = [
+    "queued",
+    "running",
+    "waiting",
+    "done",
+    "failed",
+    "stopped",
+];
+/** The definition the options give, on top of `base` (an agent's own, for
+ * an update): a template's command and key, a use's sizes, then each option. */
+function definitionOf(args, kit, env, base) {
+    const { flag, integer, usage } = kit;
+    const template = flag(args, "template");
+    const use = flag(args, "use");
+    if (template !== undefined && !(template in AGENT_TEMPLATES))
+        throw usage(`--template takes ${Object.keys(AGENT_TEMPLATES).join(", ")}.`);
+    if (use !== undefined && use !== "support" && use !== "team")
+        throw usage("--use takes support or team.");
+    const instructionsFile = flag(args, "instructions-file");
+    const instructions = instructionsFile !== undefined
+        ? readFileSync(instructionsFile, "utf8")
+        : flag(args, "instructions");
+    const image = flag(args, "image");
+    const snapshot = flag(args, "snapshot");
+    if (image !== undefined && snapshot !== undefined)
+        throw usage("Give --image or --snapshot, not both.");
+    const secrets = args.flags.get("secret");
+    const definition = {
+        ...(base ?? {}),
+        ...(template ? AGENT_TEMPLATES[template].definition : {}),
+        ...(use ? AGENT_USES[use].definition : {}),
+    };
+    const set = (field, value) => {
+        if (value !== undefined)
+            definition[field] = value;
+    };
+    set("command", flag(args, "command"));
+    set("instructions", instructions);
+    if (secrets)
+        set("secrets", [...new Set([...(definition.secrets ?? []), ...secrets])]);
+    if (args.flags.has("env"))
+        set("env", {
+            ...(definition.env ?? {}),
+            ...kit.envPairs(args, env),
+        });
+    if (image !== undefined)
+        set("from", { image });
+    if (snapshot !== undefined)
+        set("from", { snapshot });
+    set("vcpu", integer(args, "vcpu"));
+    set("memoryMiB", integer(args, "memory"));
+    set("maxConcurrent", integer(args, "max-concurrent"));
+    set("idlePauseSeconds", integer(args, "idle-pause"));
+    return definition;
+}
+const line = (e) => `${String(e.seq).padStart(4)} ${e.kind.padEnd(6)} ${e.actor}: ${typeof e.body.text === "string" ? e.body.text : JSON.stringify(e.body)}`;
+export async function agentsCommand(argv, env, out, client, kit) {
+    const { parse, flag, has, need, pairs, table, usage, unknown } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(AGENT_HELP), { usage: named(AGENT_HELP) });
+        return 0;
+    }
+    if (verb === "templates") {
+        const value = { templates: AGENT_TEMPLATES, uses: AGENT_USES };
+        print([
+            table([
+                ["TEMPLATE", "HARNESS", "MODEL KEY", "SUBSCRIPTION"],
+                ...Object.values(AGENT_TEMPLATES).map((t) => [
+                    t.key,
+                    t.title,
+                    `${t.apiKeySecret} (${t.apiKeyHost})`,
+                    t.subscription ? "yes, for your own team" : "no",
+                ]),
+            ]),
+            "",
+            table([
+                ["USE", "FOR", "SIZE", "TRIGGERS"],
+                ...Object.values(AGENT_USES).map((u) => [
+                    u.key,
+                    u.title,
+                    `${u.definition.vcpu} vCPU, ${u.definition.memoryMiB} MiB`,
+                    u.triggers.join(", "),
+                ]),
+            ]),
+        ].join("\n"), value);
+        return 0;
+    }
+    const transport = (await client()).transport;
+    const api = agents(transport);
+    const follow = async (sessionId, after) => {
+        for await (const e of (await api.session(sessionId)).events({ after }))
+            out.write(out.json ? JSON.stringify(e) : line(e));
+    };
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, [], OPTIONS);
+            const name = need(args.positional[0], "the agent's name");
+            const definition = definitionOf(args, kit, env);
+            if (!definition.command)
+                throw usage(`Give --template (${Object.keys(AGENT_TEMPLATES).join(", ")}) or --command.`);
+            const agent = await api.create({
+                name,
+                definition,
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+            });
+            if (!out.json && agent.warnings.includes("subscription_for_customers"))
+                out.error("Warning: this agent answers your customers with a subscription's token. A subscription is for your own team's agents; an agent that serves your customers uses an API key.");
+            print(agent.id, agent);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            parse(rest, [], []);
+            const all = await (await api.list({ limit: 100 })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "VERSION", "SIZE", "COMMAND", "CREATED"],
+                    ...all.map((a) => [
+                        a.id,
+                        a.name,
+                        `v${a.version}`,
+                        `${a.definition.vcpu} vCPU, ${a.definition.memoryMiB} MiB`,
+                        a.definition.command.length > 40
+                            ? `${a.definition.command.slice(0, 39)}…`
+                            : a.definition.command,
+                        when(a.createdAt),
+                    ]),
+                ])
+                : `No agents. Make one: ${me} agents create helper --template claude-code --use support`, all);
+            return 0;
+        }
+        case "get": {
+            const agent = await api.get(need(rest[0], "an agent's id or name"));
+            print(JSON.stringify(agent, null, 2), agent);
+            return 0;
+        }
+        case "update": {
+            const args = parse(rest, [], OPTIONS.filter((o) => o !== "label"));
+            const current = await api.get(need(args.positional[0], "an agent's id or name"));
+            const agent = await api.update(current.id, definitionOf(args, kit, env, current.definition));
+            print(`${agent.name} is now version ${agent.version}.`, agent);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const target = need(rest[0], "an agent's id or name");
+            await api.delete(target);
+            print(`${target} deleted; its open sessions are stopping.`, { deleted: true });
+            return 0;
+        }
+        case "start": {
+            const args = parse(rest, ["follow"], ["key"]);
+            const target = need(args.positional[0], "an agent's id or name");
+            const input = args.positional.slice(1).join(" ");
+            if (!input)
+                throw usage(`Give the words: ${me} agents start ${target} "Fix the failing test"`);
+            const key = flag(args, "key");
+            const session = await api.start(target, {
+                input,
+                ...(key === undefined ? {} : { key }),
+            });
+            if (!has(args, "follow")) {
+                print(session.id, { session: session.session, joined: session.joined, seq: session.seq });
+                return 0;
+            }
+            if (!out.json)
+                out.error(`Session ${session.id}${session.joined ? " (joined)" : ""}`);
+            await follow(session.id, 0);
+            return 0;
+        }
+        case "send": {
+            const id = need(rest[0], "a session's id");
+            const text = rest.slice(1).join(" ");
+            if (!text)
+                throw usage(`Give the words: ${me} agents send ${id} "And the docs too"`);
+            const sent = await (await api.session(id)).send(text);
+            print(`seq ${sent.seq}`, sent);
+            return 0;
+        }
+        case "events": {
+            const args = parse(rest, ["follow"], ["after"]);
+            const id = need(args.positional[0], "a session's id");
+            const after = kit.integer(args, "after") ?? 0;
+            if (has(args, "follow")) {
+                await follow(id, after);
+                return 0;
+            }
+            // One read without waiting: what is there now.
+            const read = await transport.json({
+                method: "GET",
+                path: `/v1/agents/sessions/${encodeURIComponent(id)}/events`,
+                query: { after },
+            });
+            print(read.data.map(line).join("\n") || "No events yet.", read);
+            return 0;
+        }
+        case "sessions": {
+            if (rest[0] === "delete" || rest[0] === "rm") {
+                const target = need(rest[1], "a session's id");
+                await api.sessions.delete(target);
+                print(`${target} deleted.`, { deleted: true });
+                return 0;
+            }
+            const args = parse(rest, [], ["agent", "state"]);
+            const states = args.flags.get("state");
+            for (const state of states ?? [])
+                if (!STATES.includes(state))
+                    throw usage(`--state takes ${STATES.join(", ")}.`);
+            const agent = flag(args, "agent");
+            const page = await api.sessions.list({
+                limit: 100,
+                ...(agent === undefined ? {} : { agent }),
+                ...(states ? { state: states } : {}),
+            });
+            print(page.data.length
+                ? table([
+                    ["ID", "AGENT", "STATE", "KEY", "TRIGGER", "CREATED"],
+                    ...page.data.map((s) => [
+                        s.id,
+                        s.agentId,
+                        s.state,
+                        s.key ?? "-",
+                        s.trigger,
+                        when(s.createdAt),
+                    ]),
+                ])
+                : "No sessions.", page.data);
+            return 0;
+        }
+        case "stop": {
+            const session = await (await api.session(need(rest[0], "a session's id"))).stop();
+            print(`${session.id} ${session.state}.`, session);
+            return 0;
+        }
+        case "triggers": {
+            const [sub, ...more] = rest;
+            if (sub === "add") {
+                const args = parse(more, [], ["kind", "config"]);
+                const target = need(args.positional[0], "an agent's id or name");
+                let config;
+                try {
+                    config = JSON.parse(flag(args, "config") ?? "{}");
+                }
+                catch {
+                    throw usage(`--config takes JSON, such as --config '{"cron":"0 9 * * 1-5","input":"Triage new issues"}'.`);
+                }
+                const trigger = await api.triggers.create(target, {
+                    kind: need(flag(args, "kind"), "--kind"),
+                    config,
+                });
+                // A webhook's secret is answered this once.
+                print(trigger.secret
+                    ? `${trigger.id}\nsecret ${trigger.secret} (shown once; each call carries it)`
+                    : trigger.id, trigger);
+                return 0;
+            }
+            if (sub === "pause") {
+                const args = parse(more, [], ["why"]);
+                const trigger = await api.triggers.pause(need(args.positional[0], "a trigger's id"), need(flag(args, "why"), "--why"));
+                print(`${trigger.id} paused: ${trigger.pausedWhy}`, trigger);
+                return 0;
+            }
+            if (sub === "resume") {
+                const trigger = await api.triggers.resume(need(more[0], "a trigger's id"));
+                print(`${trigger.id} resumed.`, trigger);
+                return 0;
+            }
+            if (sub === "rm" || sub === "delete") {
+                await api.triggers.delete(need(more[0], "a trigger's id"));
+                print(`${more[0]} deleted.`, { deleted: true });
+                return 0;
+            }
+            const all = await api.triggers.list(need(sub, "an agent's id or name"));
+            print(all.length
+                ? table([
+                    ["ID", "KIND", "CONFIG", "PAUSED"],
+                    ...all.map((t) => [t.id, t.kind, JSON.stringify(t.config), t.pausedWhy ?? "-"]),
+                ])
+                : "No triggers.", all);
+            return 0;
+        }
+        default:
+            throw unknown("agents command", verb, [
+                "templates",
+                "create",
+                "ls",
+                "get",
+                "update",
+                "rm",
+                "start",
+                "send",
+                "events",
+                "sessions",
+                "stop",
+                "triggers",
+            ]);
+    }
+}

package/dist/apps-cli.d.ts

@@ -0,0 +1,14 @@
+import type { CliKit } from "./cli.js";
+import type { Runtime } from "./client.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare const APP_HELP = "runtime apps <command>\n\n  An App serves your web server from an image or a build. Copies start when\n  requests come and stop when they end, between --min-copies and --max-copies.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>\n         [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]\n         [--health-path /healthz] [--label key=value]...\n                                              Make an App, waiting for its first deploy; prints its id\n  ls [--all]                                  Your Apps: state, live version, copies; --all, deleted too\n  get <app>                                   One App, in full (an id or its name)\n  update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]\n         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--label key=value]...\n                                              Change its settings\n  rm <app>                                    Delete it and stop its copies\n  deploy <app> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]\n         [--port 8080] [--health-path /healthz] [--no-wait]\n                                              A new version. Waits until it is live, or says why it\n                                              failed; --no-wait prints the deploy's id at once.\n                                              --image: an image of yours (id, name, name:tag);\n                                              --build: a build that succeeded (runtime builds).\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --keep-env keeps the last deploy's environment, sealed\n  deploys <app> [<deployId>] [--wait]         Each version's deploy: state and address; with an id,\n                                              that one (--wait: until it ends)\n  versions <app>                              Its versions; the live and previous ones keep saved copies\n  copies <app>                                Its copies now: version, region, state\n  rollback <app> [--no-wait]                  Put the previous version live again\n\nExamples\n  runtime apps create web --vcpu 1 --memory 512 --max-copies 3\n  runtime apps deploy web --image web:latest --env NODE_ENV=production\n  runtime apps rollback web\n";
+export declare const BUILD_HELP = "runtime builds <command>\n\n  A build turns a commit of a connected repository into a saved server an App\n  deploys. A push to the production branch builds and deploys by itself.\n  In a private beta: outside it, each command says how to ask to join.\n\n  repos connect <owner/name | https URL> --deploy <app name> [--branch main] [--no-previews]\n        [--root <folder>] [--install <command>] [--build <command>] [--start <command>]\n        [--port 8080] [--health-path /healthz] [--build-env KEY=VALUE]... [--name <name>]\n                                              Connect a repository; prints its id. --deploy takes an\n                                              App's name, or function:<name>. --start runs once the\n                                              build is done, with PORT set: the server the App deploys\n  repos ls                                    Connected repositories\n  repos change <repoId> [the options of connect but the repository]\n                                              Change its settings; its id and builds stay\n  repos disconnect <repoId>                   Stop building it; its builds stay\n  repos install                               A link to install Runtime's GitHub App, so a private\n                                              repository builds\n  create <repoId> [--ref main] [--branch <name>] [--name <name>]\n                                              Build a branch, tag or commit now; prints the build's id\n  run <repoId> [--ref main] [--branch <name>] [--name <name>] [--raw]\n                                              The same, then follows its log; exits 0 once it succeeds\n  ls [--repository <repoId>] [--commit <sha>] [--state <state>]...\n                                              Builds, oldest first; --commit: a full sha\n  get <buildId>                               One build: state, commit, step times, what it made\n  cancel <buildId>                            Stop a build that has not ended\n  logs <buildId> [--follow] [--raw]           Its last 200 lines, or every line as it comes until it\n                                              ends; on a terminal control characters show as \\uXXXX\n                                              unless --raw\n\nExamples\n  runtime builds repos connect acme/web --deploy web --start \"npm start\"\n  runtime builds run <repoId> --ref main\n  runtime builds ls --commit $(git rev-parse HEAD)\n";
+export declare const CONTAINER_HELP = "runtime containers <command>\n\n  A container runs one OCI image's process on its own microVM, billed at the\n  sandbox rates. It never sleeps unless --sleep; on exit it restarts when it\n  serves a port, else it stops (--on-exit sets either).\n  In a private beta: outside it, each command says how to ask to join.\n\n  create <image> --vcpu <1-16> --memory <128-65536> [--name <name>] [--label key=value]...\n         [--env KEY[=VALUE]]... [--entrypoint <program>] [--workdir /app] [--user <user>]\n         [--port <1-65535>] [--on-exit restart|stop] [--sleep] [-- <command...>]\n                                              Run it; prints its id. The image's digest is pinned.\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --entrypoint drops the image's command; after --, the\n                                              command replaces the image's\n  ls [--all] [--state <state>]... [--label key=value]...\n                                              Your containers: all but deleting and deleted, unless\n                                              --all or --state\n  get <container>                             One container, in full (an id or its name): its\n                                              environment's names, never their values\n  update <container> [--name <name>] [--label key=value]...\n                                              Rename it or replace its labels\n  rm <container> [--wait]                     Delete it and stop its process; --wait: until deleted\n\nExamples\n  runtime containers create nginx:1.27 --vcpu 1 --memory 512 --name web\n  runtime containers create python:3.12 --vcpu 1 --memory 1024 -- python3 -m http.server 8000\n  runtime containers rm web --wait\n";
+export declare function appsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export declare function buildsCommand(argv: string[], out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export declare function containersCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export {};