withruntime 0.33.3 → 0.34.0

package/E2B.md

@@ -38,6 +38,12 @@ may be two accounts, a warning says so once (`RUNTIME_E2B_TWO_KEYS`; Python: a
 `RuntimeWarning`). A template with no image of its name fails naming the
 account the key belongs to and where the key came from.
 
+E2B's client works the same way: `new E2B({ apiKey }).Sandbox` (Python:
+`E2B(api_key=...).Sandbox` and `.AsyncSandbox`) uses that key unless a call
+names its own, and the code interpreter's `E2B` gives its own `Sandbox`. The
+client's `Template`, `Volume` and `Secret` (Python: and their `Async` forms)
+refuse as the top-level ones do, naming the alternative under "Gaps".
+
 ## What a sandbox gets
 
 - **Machine:** E2B's default, 2 vCPU and 512 MiB. For another, pass
@@ -145,6 +151,7 @@ before anything happens. The error's `feature` names the gap and its
 | `git`                                                         | `commands.run("git ...")`. E2B has deprecated its git module too.                                                    |
 | File `metadata`                                               | Keep it in a file beside the data.                                                                                   |
 | `runCode(code, { envs })`                                     | A context made with them: `sandbox.runtime.interpreter.contexts.create({ env })`.                                    |
+| `new E2B(opts).Template`, `.Secret`, `.Volume`                | As `Template`, `Secret` and `Volume` above: each throws `NotSupportedError` naming the alternative.                  |
 | `domain`, `apiUrl`, `sandboxUrl`, `headers`, `proxy`, `debug` | Remove them. `RUNTIME_API_URL` sets Runtime's origin, and `HTTPS_PROXY` sets a proxy.                                |
 
 Directory watches use Runtime's native watch stream. JavaScript uses

package/dist/agents-cli.d.ts

@@ -5,6 +5,6 @@ type Out = {
     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  init [name] [--template <harness>] [--use support|team] [--file runtime.yml]\n                                              Write a starter agents: section into runtime.yml\n  deploy [--file runtime.yml] [--dry-run] [--prune [--prune-memory]]\n                                              Make your agents match runtime.yml: create, update\n                                              (a new version only when it changed) and set\n                                              triggers; one line per change. --prune deletes the\n                                              agents a deploy made that the file no longer names,\n                                              with their triggers; one holding memory files only\n                                              with --prune-memory too, which deletes them for good\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  memory ls <agent> [--scope <key>] [--prefix <path>]\n                                              Its memory files, with their scope (shared or a key)\n  memory search <agent> <words...> [--scope <key>] [--limit n]\n                                              Files whose words match, best first\n  memory cat <agent> <path> [--scope <key>]   A file's text\n  memory put <agent> <path> [<file> | - | --content <text>] [--scope <key>]\n                                              Seed or replace a file (from a file, or - for stdin)\n  memory rm <agent> <path> [--scope <key>]    Delete a file\n                                              Without --scope: the shared memory, which every\n                                              session reads and only a shared agent's write\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  runtime agents memory put helper faq/refunds.md refunds.md\n  runtime agents init --template claude-code && runtime agents deploy --dry-run\n";
+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  init [name] [--template <harness>] [--use support|team] [--file runtime.yml]\n                                              Write a starter agents: section into runtime.yml\n  deploy [--file runtime.yml] [--dry-run] [--prune [--prune-memory]]\n                                              Make your agents match runtime.yml: create, update\n                                              (a new version only when it changed) and set\n                                              triggers; one line per change. --prune deletes the\n                                              agents a deploy made that the file no longer names,\n                                              with their triggers; one holding memory files only\n                                              with --prune-memory too, which deletes them for good\n  create <name> (--template <harness> | --command \"<cmd>\") [--use support|team]\n         [--instructions <text> | --instructions-file <path>] [--secret NAME]... [--pool 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                                              --pool names a Claude account's secret (each one\n                                              given replaces the template's): each session takes\n                                              the one with the most usage left\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  asks [--state <state>]... [--agent <agent>] [--label key=value]...\n                                              The inbox: what your agents' sessions need answered,\n                                              one row per step however many sessions ask it\n  asks get <ask>                              One ask: its options, pick and the sessions asking\n  answer <ask> [<option>] [--text <words>]    Answer it with an option's label, words, or both:\n                                              every session asking reads it next and wakes\n  triggers <agent>                            Its triggers\n  triggers add <agent> --kind <slack|github|schedule|webhook> --config '<json>' [--rules '<json>']\n  triggers rules <triggerId> '<json>'         Set its rules in place: priority, maxStartsPerHour,\n                                              onEnded (start|note|ask), notify (email|webhook)\n                                              and a webhook's key (\"{cause}\"); its secret stays\n  triggers call <triggerId> <words...> [--key <key>] [--label key=value]... [--secret <secret>]\n                                              Call a webhook as its sender would, by its secret\n                                              (or RUNTIME_TRIGGER_SECRET): starts, joins, notes or\n                                              holds\n  triggers held <triggerId> [--state held|started|dismissed]...\n                                              Calls it held for you; none is dropped\n  triggers held start <triggerId> <callId>    Start one, with every call held for its key since\n  triggers held dismiss <triggerId> <callId>  Dismiss one; nothing runs\n  triggers pause <triggerId> --why <words>    Hold it: a webhook's calls are kept for you, saying why\n  triggers resume <triggerId>\n  triggers rm <triggerId>\n  memory ls <agent> [--scope <key>] [--prefix <path>]\n                                              Its memory files, with their scope (shared or a key)\n  memory search <agent> <words...> [--scope <key>] [--limit n]\n                                              Files whose words match, best first\n  memory cat <agent> <path> [--scope <key>]   A file's text\n  memory put <agent> <path> [<file> | - | --content <text>] [--scope <key>]\n                                              Seed or replace a file (from a file, or - for stdin)\n  memory rm <agent> <path> [--scope <key>]    Delete a file\n                                              Without --scope: the shared memory, which every\n                                              session reads and only a shared agent's write\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  runtime agents memory put helper faq/refunds.md refunds.md\n  runtime agents asks && runtime agents answer <ask> \"Raise to 20 TB\"\n  runtime agents init --template claude-code && runtime agents deploy --dry-run\n  runtime agents create ci-review --template review --pool CLAUDE_1 --pool CLAUDE_2\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

@@ -19,11 +19,14 @@ export const AGENT_HELP = `runtime agents <command>
                                               with their triggers; one holding memory files only
                                               with --prune-memory too, which deletes them for good
   create <name> (--template <harness> | --command "<cmd>") [--use support|team]
-         [--instructions <text> | --instructions-file <path>] [--secret NAME]...
+         [--instructions <text> | --instructions-file <path>] [--secret NAME]... [--pool 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
+                                              secret it may use: its model key, of any provider.
+                                              --pool names a Claude account's secret (each one
+                                              given replaces the template's): each session takes
+                                              the one with the most usage left
   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
@@ -39,9 +42,26 @@ export const AGENT_HELP = `runtime agents <command>
   sessions delete <session>                   Delete an ended session and its log; its history is
                                               storage, kept until you delete it
   stop <session>                              Stop a session
+  asks [--state <state>]... [--agent <agent>] [--label key=value]...
+                                              The inbox: what your agents' sessions need answered,
+                                              one row per step however many sessions ask it
+  asks get <ask>                              One ask: its options, pick and the sessions asking
+  answer <ask> [<option>] [--text <words>]    Answer it with an option's label, words, or both:
+                                              every session asking reads it next and wakes
   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 add <agent> --kind <slack|github|schedule|webhook> --config '<json>' [--rules '<json>']
+  triggers rules <triggerId> '<json>'         Set its rules in place: priority, maxStartsPerHour,
+                                              onEnded (start|note|ask), notify (email|webhook)
+                                              and a webhook's key ("{cause}"); its secret stays
+  triggers call <triggerId> <words...> [--key <key>] [--label key=value]... [--secret <secret>]
+                                              Call a webhook as its sender would, by its secret
+                                              (or RUNTIME_TRIGGER_SECRET): starts, joins, notes or
+                                              holds
+  triggers held <triggerId> [--state held|started|dismissed]...
+                                              Calls it held for you; none is dropped
+  triggers held start <triggerId> <callId>    Start one, with every call held for its key since
+  triggers held dismiss <triggerId> <callId>  Dismiss one; nothing runs
+  triggers pause <triggerId> --why <words>    Hold it: a webhook's calls are kept for you, saying why
   triggers resume <triggerId>
   triggers rm <triggerId>
   memory ls <agent> [--scope <key>] [--prefix <path>]
@@ -63,9 +83,24 @@ Examples
   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
   runtime agents memory put helper faq/refunds.md refunds.md
+  runtime agents asks && runtime agents answer <ask> "Raise to 20 TB"
   runtime agents init --template claude-code && runtime agents deploy --dry-run
+  runtime agents create ci-review --template review --pool CLAUDE_1 --pool CLAUDE_2
 `;
 const when = (iso) => iso ?? "-";
+/** A trigger's rules as the CLI takes them: one JSON object. */
+function rulesOf(text, kit) {
+    let rules;
+    try {
+        rules = JSON.parse(text);
+    }
+    catch {
+        rules = undefined;
+    }
+    if (!rules || typeof rules !== "object" || Array.isArray(rules))
+        throw kit.usage(`Rules are a JSON object, such as '{"key":"{cause}","maxStartsPerHour":60,"onEnded":"ask"}'.`);
+    return rules;
+}
 const OPTIONS = [
     "template",
     "use",
@@ -73,6 +108,7 @@ const OPTIONS = [
     "instructions",
     "instructions-file",
     "secret",
+    "pool",
     "env",
     "image",
     "snapshot",
@@ -82,6 +118,20 @@ const OPTIONS = [
     "idle-pause",
     "label",
 ];
+const ASK_STATES = ["open", "answered", "expired", "withdrawn", "closed"];
+const askLine = (a) => {
+    const options = a.options.map((o) => (o.label === a.pick ? `${o.label} (pick)` : o.label));
+    return [
+        `${a.id} ${a.state}${a.step ? ` step ${a.step}` : ""}, ${a.sessions.length} session${a.sessions.length === 1 ? "" : "s"} asking`,
+        `  ${a.question}`,
+        ...(a.why ? [`  why: ${a.why}`] : []),
+        ...(options.length ? [`  options: ${options.join(" | ")}`] : []),
+        ...(a.expiresAt ? [`  expires ${a.expiresAt}`] : []),
+        ...(a.answer
+            ? [`  answered: ${[a.answer.option, a.answer.text].filter(Boolean).join(": ")}`]
+            : []),
+    ].join("\n");
+};
 const STATES = [
     "queued",
     "running",
@@ -122,6 +172,9 @@ function definitionOf(args, kit, env, base) {
     set("instructions", instructions);
     if (secrets)
         set("secrets", [...new Set([...(definition.secrets ?? []), ...secrets])]);
+    const pool = args.flags.get("pool");
+    if (pool)
+        set("pool", [...new Set(pool)]);
     if (args.flags.has("env"))
         set("env", {
             ...(definition.env ?? {}),
@@ -317,6 +370,42 @@ export async function agentsCommand(argv, env, out, client, kit) {
                 : "No sessions.", page.data);
             return 0;
         }
+        case "asks": {
+            if (rest[0] === "get") {
+                const one = await api.asks.get(need(rest[1], "an ask's id"));
+                print(askLine(one), one);
+                return 0;
+            }
+            const args = parse(rest, [], ["state", "agent", "label"]);
+            const states = args.flags.get("state");
+            for (const state of states ?? [])
+                if (!ASK_STATES.includes(state))
+                    throw usage(`--state takes ${ASK_STATES.join(", ")}.`);
+            const agent = flag(args, "agent");
+            const labels = args.flags.has("label") ? pairs(args, "label") : undefined;
+            const page = await api.asks.list({
+                limit: 100,
+                ...(agent === undefined ? {} : { agent }),
+                ...(states ? { state: states } : {}),
+                ...(labels ? { labels } : {}),
+            });
+            print(page.data.map(askLine).join("\n\n") || "Nothing to answer.", page.data);
+            return 0;
+        }
+        case "answer": {
+            const args = parse(rest, [], ["text"]);
+            const id = need(args.positional[0], "an ask's id");
+            const option = args.positional.slice(1).join(" ") || undefined;
+            const text = flag(args, "text");
+            if (option === undefined && text === undefined)
+                throw usage(`Give an option's label, --text, or both: ${me} agents answer ${id} "Keep it"`);
+            const answered = await api.asks.answer(id, {
+                ...(option === undefined ? {} : { option }),
+                ...(text === undefined ? {} : { text }),
+            });
+            print(`${answered.id} answered; ${answered.sessions.filter((x) => x.state === "answered").length} session(s) woken.`, answered);
+            return 0;
+        }
         case "stop": {
             const session = await (await api.session(need(rest[0], "a session's id"))).stop();
             print(`${session.id} ${session.state}.`, session);
@@ -325,7 +414,7 @@ export async function agentsCommand(argv, env, out, client, kit) {
         case "triggers": {
             const [sub, ...more] = rest;
             if (sub === "add") {
-                const args = parse(more, [], ["kind", "config"]);
+                const args = parse(more, [], ["kind", "config", "rules"]);
                 const target = need(args.positional[0], "an agent's id or name");
                 let config;
                 try {
@@ -334,9 +423,11 @@ export async function agentsCommand(argv, env, out, client, kit) {
                 catch {
                     throw usage(`--config takes JSON, such as --config '{"cron":"0 9 * * 1-5","input":"Triage new issues"}'.`);
                 }
+                const rules = flag(args, "rules");
                 const trigger = await api.triggers.create(target, {
                     kind: need(flag(args, "kind"), "--kind"),
                     config,
+                    ...(rules === undefined ? {} : { rules: rulesOf(rules, kit) }),
                 });
                 // A webhook's secret is answered this once.
                 print(trigger.secret
@@ -344,6 +435,71 @@ export async function agentsCommand(argv, env, out, client, kit) {
                     : trigger.id, trigger);
                 return 0;
             }
+            if (sub === "rules") {
+                const id = need(more[0], "a trigger's id");
+                const trigger = await api.triggers.setRules(id, rulesOf(need(more[1], `the rules as JSON: ${me} agents triggers rules ${id} '{"priority":10}'`), kit));
+                print(`${trigger.id} rules ${JSON.stringify(trigger.rules)}`, trigger);
+                return 0;
+            }
+            if (sub === "call") {
+                const args = parse(more, [], ["key", "label", "secret"]);
+                const id = need(args.positional[0], "a trigger's id");
+                const text = args.positional.slice(1).join(" ");
+                if (!text)
+                    throw usage(`Give the words: ${me} agents triggers call ${id} "disk full on db-1"`);
+                const secret = flag(args, "secret") ?? env.RUNTIME_TRIGGER_SECRET;
+                if (!secret)
+                    throw usage("Give the trigger's secret: --secret rtat_… or RUNTIME_TRIGGER_SECRET, as answered when the webhook was added.");
+                const key = flag(args, "key");
+                const done = await api.triggers.call(id, secret, {
+                    text,
+                    ...(key === undefined ? {} : { key }),
+                    ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+                });
+                print(done.outcome === "held"
+                    ? `held ${done.callId}: ${done.why}`
+                    : `${done.outcome} ${done.sessionId} seq ${done.seq}`, done);
+                return 0;
+            }
+            if (sub === "held") {
+                const [action, ...after] = more;
+                if (action === "start" || action === "dismiss") {
+                    const id = need(after[0], "a trigger's id");
+                    const call = need(after[1], "a held call's id");
+                    if (action === "start") {
+                        const started = await api.triggers.startHeld(id, call);
+                        print(`${started.joined ? "joined" : "started"} ${started.session.id} with ${started.calls} held call${started.calls === 1 ? "" : "s"}`, started);
+                    }
+                    else {
+                        const dismissed = await api.triggers.dismissHeld(id, call);
+                        print(`${dismissed.id} dismissed.`, dismissed);
+                    }
+                    return 0;
+                }
+                const args = parse(more, [], ["state"]);
+                const states = args.flags.get("state");
+                for (const state of states ?? [])
+                    if (!["held", "started", "dismissed"].includes(state))
+                        throw usage("--state takes held, started, dismissed.");
+                const page = await api.triggers.held(need(args.positional[0], "a trigger's id"), {
+                    limit: 100,
+                    ...(states ? { state: states } : {}),
+                });
+                print(page.data.length
+                    ? table([
+                        ["ID", "STATE", "WHY", "KEY", "CREATED", "WORDS"],
+                        ...page.data.map((c) => [
+                            c.id,
+                            c.state,
+                            c.why,
+                            c.key ?? "-",
+                            when(c.createdAt),
+                            c.text.replace(/\s+/g, " ").slice(0, 60),
+                        ]),
+                    ])
+                    : "No held calls.", page.data);
+                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"));
@@ -363,8 +519,14 @@ export async function agentsCommand(argv, env, out, client, kit) {
             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 ?? "-"]),
+                    ["ID", "KIND", "CONFIG", "RULES", "PAUSED"],
+                    ...all.map((t) => [
+                        t.id,
+                        t.kind,
+                        JSON.stringify(t.config),
+                        Object.keys(t.rules ?? {}).length ? JSON.stringify(t.rules) : "-",
+                        t.pausedWhy ?? "-",
+                    ]),
                 ])
                 : "No triggers.", all);
             return 0;
@@ -386,6 +548,8 @@ export async function agentsCommand(argv, env, out, client, kit) {
                 "events",
                 "sessions",
                 "stop",
+                "asks",
+                "answer",
                 "triggers",
                 "memory",
             ]);

package/dist/agents-deploy.d.ts

@@ -1,16 +1,18 @@
 import type { Runtime } from "./client.js";
-import { type Agent, type AgentDefinition, type AgentTrigger, type AgentTriggerKind, type CreateAgentTrigger } from "./products/agents.js";
-/** One trigger as the file writes it. `paused` holds it, saying why. */
+import { type Agent, type AgentDefinition, type AgentTrigger, type AgentTriggerKind, type AgentTriggerRules, type CreateAgentTrigger } from "./products/agents.js";
+/** One trigger as the file writes it. `paused` holds it, saying why;
+ * `rules` are changed in place, never by making the trigger again. */
 export type AgentsFileTrigger = {
     kind: AgentTriggerKind;
     config: Record<string, unknown>;
+    rules?: AgentTriggerRules;
     paused?: string;
 };
 /** One agent as the file writes it: a harness template and a use fill in
  * what it leaves out, then each definition field it sets. */
 export type AgentsFileAgent = Omit<Partial<AgentDefinition>, "template"> & {
     /** A harness: claude-code, codex, gemini-cli, claude-agent-sdk,
-     * openai-agents-sdk. Fills in `command` and `secrets`. */
+     * openai-agents-sdk, review, judge. Fills in `command` and its model keys. */
     template?: string;
     /** support or team: a size and bounds for that use (`agents.uses`). */
     use?: "support" | "team";
@@ -53,6 +55,7 @@ export type AgentsDeployPort = {
     pauseTrigger(triggerId: string, why: string, key: string): Promise<AgentTrigger>;
     resumeTrigger(triggerId: string, key: string): Promise<AgentTrigger>;
     removeTrigger(triggerId: string, key: string): Promise<void>;
+    setTriggerRules(triggerId: string, rules: AgentTriggerRules, key: string): Promise<AgentTrigger>;
     /** How many memory files the agent holds: deleting it deletes them. */
     memoryFiles(agentId: string): Promise<number>;
 };
@@ -101,6 +104,13 @@ export type AgentsDeployChange = {
     triggerId: string;
     key: string;
     text: string;
+} | {
+    action: "set-trigger-rules";
+    agent: string;
+    triggerId: string;
+    rules: AgentTriggerRules;
+    key: string;
+    text: string;
 } | {
     action: "remove-trigger";
     agent: string;

package/dist/agents-deploy.js

@@ -22,6 +22,7 @@ const DEFINITION_FIELDS = [
     "instructions",
     "env",
     "secrets",
+    "pool",
     "mcp",
     "volumes",
     "idlePauseSeconds",
@@ -131,9 +132,10 @@ function checkAgent(name, entry, source, say) {
         Object.assign(def, AGENT_USES[use].definition);
     const found = typeof template === "string" ? agentTemplate(template) : undefined;
     if (found) {
-        const t = found.definition;
-        def.command = t.command;
-        def.secrets = [...t.secrets];
+        // A use's size wins over the template's, as the CLI's --use does.
+        for (const [k, v] of Object.entries(found.definition))
+            if (def[k] === undefined)
+                def[k] = Array.isArray(v) ? [...v] : v;
     }
     const integer = (field, min, max) => {
         const v = entry[field];
@@ -200,8 +202,11 @@ function checkAgent(name, entry, source, say) {
         if (!isObject(v) ||
             keys.length !== 1 ||
             !((typeof v.image === "string" && /^[A-Za-z0-9][A-Za-z0-9_./:@-]{0,255}$/.test(v.image)) ||
-                (typeof v.snapshot === "string" && UUID.test(v.snapshot))))
-            note(at("from"), "takes { image: name[:tag] } or { snapshot: <snapshot id> }.");
+                (typeof v.snapshot === "string" && UUID.test(v.snapshot)) ||
+                // The API's own pattern (packages/cloud/src/api/products/agents.ts).
+                (typeof v.repo === "string" &&
+                    /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/.test(v.repo))))
+            note(at("from"), "takes { image: name[:tag] }, { snapshot: <snapshot id> } or { repo: owner/name }.");
         else
             def.from = { ...v };
     }
@@ -258,6 +263,18 @@ function checkAgent(name, entry, source, say) {
             def.secrets = [...new Set(v)];
         }
     }
+    if (entry.pool !== undefined) {
+        const v = entry.pool;
+        if (!Array.isArray(v) || v.length < 1 || v.length > 16)
+            note(at("pool"), "takes a list of 1 to 16 egress secrets' names, one per Claude account.");
+        else {
+            v.forEach((s, i) => {
+                if (typeof s !== "string" || !SHELL_NAME.test(s))
+                    note(at("pool", i), "is not a secret's name, such as CLAUDE_1.");
+            });
+            def.pool = [...new Set(v)];
+        }
+    }
     if (entry.mcp !== undefined) {
         const v = entry.mcp;
         if (!Array.isArray(v) || v.length > 16)
@@ -347,8 +364,8 @@ function checkTrigger(t, note) {
         note(rest, message);
     };
     for (const key of Object.keys(t))
-        if (!["kind", "config", "paused"].includes(key))
-            bad([key], `is not a field a trigger takes${hint(key, ["kind", "config", "paused"])}`);
+        if (!["kind", "config", "rules", "paused"].includes(key))
+            bad([key], `is not a field a trigger takes${hint(key, ["kind", "config", "rules", "paused"])}`);
     const kind = t.kind;
     if (!TRIGGER_KINDS.includes(kind)) {
         bad(["kind"], `takes ${TRIGGER_KINDS.join(", ")}.`);
@@ -391,12 +408,37 @@ function checkTrigger(t, note) {
     if (paused !== undefined &&
         (typeof paused !== "string" || paused.length < 1 || paused.length > 1024))
         bad(["paused"], "takes the words a held trigger says, 1 to 1024 characters.");
+    const rules = t.rules ?? {};
+    if (!isObject(rules))
+        bad(["rules"], `takes ${RULES}.`);
+    else
+        for (const [k, v] of Object.entries(rules)) {
+            const whole = (lo, hi) => typeof v === "number" && Number.isInteger(v) && v >= lo && v <= hi;
+            if (!((k === "priority" && whole(-100, 100)) ||
+                (k === "maxStartsPerHour" && whole(1, 100000)) ||
+                (k === "onEnded" && ["start", "note", "ask"].includes(v)) ||
+                (k === "notify" && ["email", "webhook"].includes(v)) ||
+                (k === "key" &&
+                    kind === "webhook" &&
+                    typeof v === "string" &&
+                    v.length <= 256 &&
+                    RULE_KEY.test(v))))
+                bad(["rules", k], `takes ${RULES}.`);
+        }
     if (ok && !within(config, TRIGGER_MAX_BYTES))
         bad(["config"], "is over 40 KiB.");
     if (!ok)
         return null;
-    return { kind, config, ...(typeof paused === "string" ? { paused } : {}) };
+    return {
+        kind,
+        config,
+        ...(isObject(rules) && Object.keys(rules).length ? { rules: rules } : {}),
+        ...(typeof paused === "string" ? { paused } : {}),
+    };
 }
+const RULES = '{ priority?: -100 to 100, maxStartsPerHour?: 1 to 100000, onEnded?: start | note | ask, notify?: email | webhook, key?: "{field}" (a webhook\'s) }';
+/** A webhook's key template, as the API holds it. */
+const RULE_KEY = /^([A-Za-z0-9._:/@#+=-]|\{[A-Za-z0-9_-]{1,64}(\.[A-Za-z0-9_-]{1,64}){0,7}\})+$/;
 const TRIGGER_KEYS = {
     slack: ["team", "channel"],
     github: ["installation", "repository", "events"],
@@ -479,6 +521,15 @@ export async function planAgents(port, desired, options = {}) {
                 continue;
             }
             const [match] = open.splice(at, 1);
+            if (canonical(trigger.rules ?? {}) !== canonical(match.rules ?? {}))
+                changes.push({
+                    action: "set-trigger-rules",
+                    agent: want.name,
+                    triggerId: match.id,
+                    rules: trigger.rules ?? {},
+                    key: await keyOf("set-trigger-rules", match.id, trigger.rules ?? {}, match.updatedAt),
+                    text: `set rules of trigger ${match.id} (${triggerText(trigger)}) of ${want.name}: ${canonical(trigger.rules ?? {})}`,
+                });
             if (trigger.paused !== undefined && match.pausedWhy !== trigger.paused)
                 changes.push({
                     action: "pause-trigger",
@@ -590,7 +641,11 @@ async function apply(port, change, ids) {
             if (!change.agentId)
                 change.key = await keyOf(change.key, agentId);
             const key = change.key;
-            const made = await port.addTrigger(agentId, { kind: change.trigger.kind, config: change.trigger.config }, key);
+            const made = await port.addTrigger(agentId, {
+                kind: change.trigger.kind,
+                config: change.trigger.config,
+                ...(change.trigger.rules ? { rules: change.trigger.rules } : {}),
+            }, key);
             change.triggerId = made.id;
             if (made.secret)
                 change.secret = made.secret;
@@ -607,6 +662,9 @@ async function apply(port, change, ids) {
         case "remove-trigger":
             await port.removeTrigger(change.triggerId, change.key);
             return;
+        case "set-trigger-rules":
+            await port.setTriggerRules(change.triggerId, change.rules, change.key);
+            return;
     }
 }
 /** The fields whose value differs. A field the file leaves out matches the
@@ -740,6 +798,7 @@ function clientPort(api) {
         pauseTrigger: (id, why, idempotencyKey) => api.triggers.pause(id, why, { idempotencyKey }),
         resumeTrigger: (id, idempotencyKey) => api.triggers.resume(id, { idempotencyKey }),
         removeTrigger: (id, idempotencyKey) => api.triggers.delete(id, { idempotencyKey }),
+        setTriggerRules: (id, rules, idempotencyKey) => api.triggers.setRules(id, rules, { idempotencyKey }),
         memoryFiles: async (agentId) => (await api.memory.list(agentId, { limit: 1 })).usage.files,
     };
 }

package/dist/apps-cli.d.ts

@@ -5,7 +5,7 @@ type Out = {
     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] [--health-fail 60] [--stop-grace 30] [--cdn on|off]\n         [--volume <volumeId>:<path>] [--label key=value]...\n                                              Make an App, waiting for its first deploy; prints its id.\n                                              --health-fail: seconds a live copy may fail its health\n                                              check before it is replaced. --stop-grace: seconds a\n                                              stopped copy has after SIGTERM. --volume mounts one\n                                              volume of yours at a path under /data, /mnt, /state,\n                                              /storage or /volumes, in the App's one copy: it needs\n                                              --max-copies 1 (--min-copies is then 1, --spares 0), and\n                                              each deploy stops the old copy before the new one boots\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] [--health-fail n]\n         [--stop-grace n] [--volume <volumeId>:<path> | none] [--cdn on|off]\n         [--label key=value]...\n                                              Change its settings; --volume none takes the volume\n                                              away, only before its first deploy;\n                                              --cdn off sends visitors straight to Runtime's routers,\n                                              with nothing cached (on: Cloudflare's CDN in front)\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  logs <app> [--follow] [--since 1h] [--version n] [--copy <copyId>] [--stream stdout|stderr]\n         [--limit 100] [--raw]                What its copies printed: the newest lines since --since\n                                              (a time, or 30s, 15m, 2h, 7d; kept 14 days), or with\n                                              --follow every line as it comes, until Ctrl-C. On a\n                                              terminal control characters show as \\uXXXX unless --raw\n  exec <app> [--copy <id>] [--root] [--cwd <dir>] [--env K=V]... [--timeout <ms>] [--trace-files <file.json>] -- <command>\n                                              Run a command in its live copy\n  cp <file> <app>:/<path> [--copy <id>]       Copy a file onto its live copy\n  cp <app>:/<path> <file> [--copy <id>]       Copy a file off it\n  exec and cp go to a serving copy of the live version unless --copy names\n  one. A copy holds the App's secrets, so only an owner's or admin's key\n  reaches into one. A file written to a copy lasts as long as that copy; a\n  deploy replaces its copies.\n  rollback <app> [--no-wait]                  Put the previous version live again\n  restart <app> [--no-wait]                   Start the live version afresh, as a deploy of its own;\n                                              with a volume, the old copy stops first and the\n                                              downtime is said\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 logs web --follow\n  runtime apps rollback web\n  runtime apps create db --vcpu 1 --memory 1024 --max-copies 1 --volume <volumeId>:/data\n";
+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] [--health-fail 60] [--stop-grace 30] [--cdn on|off]\n         [--release at-once|staged] [--soak 300] [--volume <volumeId>:<path>] [--label key=value]...\n                                              Make an App, waiting for its first deploy; prints its id.\n                                              --health-fail: seconds a live copy may fail its health\n                                              check before it is replaced. --stop-grace: seconds a\n                                              stopped copy has after SIGTERM. --release staged: a new\n                                              version goes live on one copy, then about 10%, 50% and\n                                              all of them, each stage running --soak seconds (60 to\n                                              3600) and judged on its visitors' errors and speed\n                                              before the next; a stage that does worse goes back and\n                                              the deploy fails, the live version never stopping.\n                                              --volume mounts one\n                                              volume of yours at a path under /data, /mnt, /state,\n                                              /storage or /volumes, in the App's one copy: it needs\n                                              --max-copies 1 (--min-copies is then 1, --spares 0), and\n                                              each deploy stops the old copy before the new one boots\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] [--health-fail n]\n         [--stop-grace n] [--volume <volumeId>:<path> | none] [--cdn on|off]\n         [--release at-once|staged] [--soak n] [--label key=value]...\n                                              Change its settings; --volume none takes the volume\n                                              away, only before its first deploy;\n                                              --cdn off sends visitors straight to Runtime's routers,\n                                              with nothing cached (on: Cloudflare's CDN in front)\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  logs <app> [--follow] [--since 1h] [--version n] [--copy <copyId>] [--stream stdout|stderr]\n         [--limit 100] [--raw]                What its copies printed: the newest lines since --since\n                                              (a time, or 30s, 15m, 2h, 7d; kept 14 days), or with\n                                              --follow every line as it comes, until Ctrl-C. On a\n                                              terminal control characters show as \\uXXXX unless --raw\n  exec <app> [--copy <id>] [--root] [--cwd <dir>] [--env K=V]... [--timeout <ms>] [--trace-files <file.json>] -- <command>\n                                              Run a command in its live copy\n  cp <file> <app>:/<path> [--copy <id>]       Copy a file onto its live copy\n  cp <app>:/<path> <file> [--copy <id>]       Copy a file off it\n  exec and cp go to a serving copy of the live version unless --copy names\n  one. A copy holds the App's secrets, so only an owner's or admin's key\n  reaches into one. A file written to a copy lasts as long as that copy; a\n  deploy replaces its copies.\n  rollback <app> [--no-wait]                  Put the previous version live again\n  restart <app> [--no-wait]                   Start the live version afresh, as a deploy of its own;\n                                              with a volume, the old copy stops first and the\n                                              downtime is said\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 logs web --follow\n  runtime apps rollback web\n  runtime apps create db --vcpu 1 --memory 1024 --max-copies 1 --volume <volumeId>:/data\n";
 export declare const FUNCTION_HELP = "runtime functions <command>\n\n  A Function serves your HTTP handler from an image or a build, at its own\n  address. Copies start when calls come, up to --max-copies, and sleep when\n  they stop: an idle Function has no copy awake.\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         [--concurrency 100] [--spares 2] [--port 8080]\n         [--health-path /healthz] [--health-fail 60] [--label key=value]...\n                                              Make a Function, waiting for its first deploy; prints its id.\n                                              --health-fail: seconds a live copy may fail its health\n                                              check before it is replaced\n  ls [--all]                                  Your Functions: state, live version, copies; --all, deleted too\n  get <function>                              One Function, in full (an id or its name)\n  update <function> [--name <name>] [--vcpu n] [--memory n] [--max-copies n]\n         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--health-fail n]\n         [--label key=value]...\n                                              Change its settings\n  rm <function>                               Delete it and stop its copies\n  deploy <function> (--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 <function> [<deployId>] [--wait]    Each version's deploy: state and address; with an id,\n                                              that one (--wait: until it ends)\n  versions <function>                         Its versions; the live and previous ones keep saved copies\n  copies <function>                           Its copies now: version, region, state\n  logs <function> [--follow] [--since 1h] [--version n] [--copy <copyId>] [--stream stdout|stderr]\n         [--limit 100] [--raw]                What its copies printed: the newest lines since --since\n                                              (a time, or 30s, 15m, 2h, 7d; kept 14 days), or with\n                                              --follow every line as it comes, until Ctrl-C. On a\n                                              terminal control characters show as \\uXXXX unless --raw\n  rollback <function> [--no-wait]             Put the previous version live again\n  restart <function> [--no-wait]              Start the live version afresh, as a deploy of its own\n\nExamples\n  runtime functions create resize --vcpu 1 --memory 512 --max-copies 10\n  runtime functions deploy resize --image resize:latest\n  runtime functions logs resize --follow\n  runtime functions rollback resize\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";