withruntime 0.33.2 → 0.34.0

package/dist/cli.js

@@ -69,7 +69,9 @@ Account
                                                (job create --secret NAME); with --host, both
   secrets scope <NAME> --only-label k=v... | --only-sandbox <id>... | --only-app <id>... | --all-sandboxes
                                                Change which sandboxes get it; no value needed
-  secrets ls | get <NAME>                      Names, hosts, placeholders and jobs versions, never values
+  secrets ls [--limit N] [--after NAME] | get <NAME>
+                                               Names, hosts, placeholders and jobs versions, never values;
+                                               by name, a page of N after NAME
   secrets rotate <NAME>                        A new version of the jobs copy, from standard input
   secrets reveal <NAME> [--version N]          Print the jobs copy's value. The sandboxes' copy is
                                                never readable, by anyone
@@ -136,6 +138,8 @@ Products
   builds     A connected repository's commits built into what an App deploys (beta)
   ci         CI/CD: each push and pull request of a repository checked in sandboxes (beta)
   containers One OCI image's process on its own microVM, at the sandbox rates (beta)
+  browsers   Chromium on its own sandbox: a CDP address and screenshots (beta)
+  desktops   A Linux desktop on its own sandbox: live view, computer use (beta)
   agents     Claude Code, Codex, Gemini CLI or your own agent in a sandbox per session (beta)
   domains    Your own hostname for a sandbox's port, with HTTPS
   ports      A public TCP port to a sandbox: databases, game servers
@@ -476,6 +480,8 @@ const COMMANDS = [
     "builds",
     "ci",
     "containers",
+    "browsers",
+    "desktops",
     "agents",
     "domains",
     "ports",
@@ -500,6 +506,8 @@ const OWN_HELP = [
     "builds",
     "ci",
     "containers",
+    "browsers",
+    "desktops",
     "agents",
     "keys",
     "reservations",
@@ -872,6 +880,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             const rt = await client(env);
             const cursors = new Set();
             let cursor;
+            // The export is final only as far as its earliest page's finalThrough.
+            let finalThrough;
             for (;;) {
                 const page = await rt.usageExport({
                     since,
@@ -891,8 +901,19 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
                 else if (page.csv)
                     out.write(page.csv);
                 await out.drain?.();
-                if (page.nextCursor === null)
+                const at = page.finalThrough;
+                finalThrough =
+                    finalThrough === undefined
+                        ? at
+                        : finalThrough === null || at === null
+                            ? null
+                            : at < finalThrough
+                                ? at
+                                : finalThrough;
+                if (page.nextCursor === null) {
+                    out.error(finalLine({ until: page.until, finalThrough: finalThrough ?? null }));
                     return 0;
+                }
                 cursors.add(page.nextCursor);
                 cursor = page.nextCursor;
             }
@@ -1351,6 +1372,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "containers";
         return (await import("./apps-cli.js")).containersCommand(rest, env, out, () => client(env), kit);
     }
+    if (["browser", "browsers", "desktop", "desktops"].includes(command)) {
+        product = command.endsWith("s") ? command : `${command}s`;
+        return (await import("./browsers-cli.js")).machineProductCommand(product, rest, out, () => client(env), kit);
+    }
     if (command === "agent" || command === "agents") {
         product = "agents";
         return (await import("./agents-cli.js")).agentsCommand(rest, env, out, () => client(env), kit);
@@ -1365,6 +1390,15 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     throw unknown("command", command, COMMANDS);
 }
+/** `usage export`'s last word, on stderr beside the CSV: how much of the
+ * range can still change. */
+export function finalLine(page) {
+    if (page.finalThrough === null)
+        return "Charges in this range may still settle; export it again later for a final copy.";
+    if (Date.parse(page.finalThrough) >= Date.parse(page.until))
+        return "Final: no more charges will settle in this range.";
+    return `Final up to ${page.finalThrough}; charges after that may still settle. Export again later for the rest.`;
+}
 /** `runtime usage` for a person: the balance, the free usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
@@ -2689,6 +2723,8 @@ read = readSecret) {
         "only-app",
         "agent",
         "env",
+        "limit",
+        "after",
     ]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const rows = (list) => list.length
@@ -2706,11 +2742,19 @@ read = readSecret) {
         ])
         : "No secrets.";
     if (verb === "ls" || verb === "list" || verb === undefined) {
+        const limit = integer(args, "limit");
+        if (limit !== undefined && (limit < 1 || limit > 100))
+            throw usage("--limit takes 1 to 100 secrets a page.");
+        const after = flag(args, "after");
         const runtime = await client(env);
-        const all = await runtime.secrets.all();
+        // A page of both copies by name, as the API pages each: an organization
+        // keeps at most 50 secrets for sandboxes, so both are read whole.
+        const every = (await runtime.secrets.all()).filter((s) => after === undefined || s.name > after);
+        const all = limit === undefined ? every : every.slice(0, limit);
+        const more = all.length < every.length ? all.at(-1).name : undefined;
         // --json keeps the sandboxes' list it always printed; the jobs copies
         // are in `runtime secrets get <NAME> --json`.
-        print(rows(all), all.flatMap((s) => (s.sandboxes ? [s.sandboxes] : [])));
+        print(more ? `${rows(all)}\nMore: ${me} secrets ls --limit ${limit} --after ${more}` : rows(all), all.flatMap((s) => (s.sandboxes ? [s.sandboxes] : [])));
         return 0;
     }
     const jobsOnly = "Only a secret's copy for jobs has versions and can be read back";
@@ -4377,10 +4421,39 @@ const VOLUME_HELP = `runtime volumes <command>
   backup-rm <backupId>                        Delete a backup
   backup-policy <id> [--daily on|off] [--retention-days N]
                                               Daily backups on or off, and how long each is kept
+  backup-policy <id> --every <minutes> | --cron "<m h dom mon dow>" [--keep hourly=24,daily=7,...]
+                                              Back up on a schedule of its own (UTC), keeping
+                                              last, hourly, daily, weekly, monthly, yearly counts
+  backup-policy <id> --no-schedule            Back to daily backups
   Attach one: runtime sandboxes create --volume <id>:/data
-  Volumes are backed up off their host daily unless you turn it off.
+  Volumes are backed up off their host daily, or on their own schedule, unless you turn it off.
   Shared commands work where shared disks are enabled.
 `;
+const KEEP_TIERS = ["last", "hourly", "daily", "weekly", "monthly", "yearly"];
+/** `hourly=24,daily=7` as keep counts; the server checks the numbers. */
+function keepCounts(text) {
+    const counts = {};
+    for (const part of text.split(",")) {
+        const [name, value, extra] = part.trim().split("=");
+        const tier = KEEP_TIERS.find((t) => t === name);
+        if (!tier || value === undefined || extra !== undefined || !/^\d+$/.test(value))
+            throw usage(`--keep takes name=count pairs such as hourly=24,daily=7; names: ${KEEP_TIERS.join(", ")}.`);
+        counts[tier] = Number(value);
+    }
+    return counts;
+}
+/** "daily backups on, kept 7 days", or the schedule, its keep counts and next run. */
+function backupPolicyWords(b) {
+    if (!b.schedule)
+        return `daily backups ${b.daily ? "on" : "off"}, kept ${b.retentionDays} days`;
+    const when = "everyMinutes" in b.schedule
+        ? `every ${b.schedule.everyMinutes} minutes`
+        : `on cron "${b.schedule.cron.trim()}" (UTC)`;
+    const kept = KEEP_TIERS.filter((t) => (b.keep?.[t] ?? 0) > 0)
+        .map((t) => `${t} ${b.keep[t]}`)
+        .join(", ");
+    return `backups ${when}${b.daily ? "" : " (off)"}, keeping ${kept}${b.daily && b.nextAt ? `; next ${b.nextAt}` : ""}`;
+}
 async function volume(argv, env, out) {
     const [verb, ...rest] = argv;
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
@@ -4489,7 +4562,7 @@ async function volume(argv, env, out) {
                         String(b.sizeMiB),
                         b.storedBytes === null ? "-" : `${Math.ceil(b.storedBytes / 1048576)} MiB`,
                         b.createdAt,
-                        b.expiresAt,
+                        b.expiresAt ?? "by keep counts",
                     ]),
                 ])
                 : "No backups yet.", all);
@@ -4510,19 +4583,30 @@ async function volume(argv, env, out) {
             return 0;
         }
         case "backup-policy": {
-            const args = parse(rest, [], ["daily", "retention-days"]);
+            const args = parse(rest, ["no-schedule"], ["daily", "retention-days", "every", "cron", "keep"]);
             const id = need(args.positional[0], "a volume id");
             const daily = flag(args, "daily");
             if (daily !== undefined && !["on", "off", "true", "false"].includes(daily))
                 throw usage("--daily takes on or off.");
             const days = integer(args, "retention-days");
-            if (daily === undefined && days === undefined)
-                throw usage("Give --daily on|off, --retention-days N or both.");
+            const every = integer(args, "every");
+            const cron = flag(args, "cron");
+            const off = has(args, "no-schedule");
+            if ([every !== undefined, cron !== undefined, off].filter(Boolean).length > 1)
+                throw usage("Give one of --every, --cron and --no-schedule.");
+            const keepText = flag(args, "keep");
+            const keep = keepText === undefined ? undefined : keepCounts(keepText);
+            if ([daily, days, every, cron, keep].every((x) => x === undefined) && !off)
+                throw usage("Give --daily on|off, --retention-days N, --every, --cron, --keep or --no-schedule.");
             const updated = await api.setBackupPolicy(id, {
                 ...(daily === undefined ? {} : { daily: daily === "on" || daily === "true" }),
                 ...(days === undefined ? {} : { retentionDays: days }),
+                ...(every === undefined ? {} : { schedule: { everyMinutes: every } }),
+                ...(cron === undefined ? {} : { schedule: { cron } }),
+                ...(off ? { schedule: null } : {}),
+                ...(keep === undefined ? {} : { keep }),
             });
-            print(`${updated.id} daily backups ${updated.backups.daily ? "on" : "off"}, kept ${updated.backups.retentionDays} days`, updated);
+            print(`${updated.id} ${backupPolicyWords(updated.backups)}`, updated);
             return 0;
         }
     }

package/dist/desktops/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/desktops`: Desktops alone. A Linux desktop on its own sandbox, with a live view and computer use, at the sandbox rates. In a private beta.
+ *
+ *   import { desktops } from "withruntime/desktops";
+ *   const client = desktops(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/desktops.js";
+/** `runtime.desktops` of a client made with `options`. */
+export declare function desktops(options?: RuntimeOptions): Runtime["desktops"];

package/dist/desktops/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/desktops`: Desktops alone. A Linux desktop on its own sandbox, with a live view and computer use, at the sandbox rates. In a private beta.
+ *
+ *   import { desktops } from "withruntime/desktops";
+ *   const client = desktops(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.desktops` of a client made with `options`. */
+export function desktops(options) {
+    return new Runtime(options).desktops;
+}

package/dist/e2b/code-interpreter.d.ts

@@ -1,11 +1,4 @@
-/** `@e2b/code-interpreter`, on Runtime. Change the import:
- *
- *   import { Sandbox } from "withruntime/e2b/code-interpreter";
- *
- * runCode runs in Runtime's interpreter (sandbox.runtime.interpreter):
- * stateful contexts in every E2B interpreter language. */
-import type { Runtime } from "../client.js";
-import type { ConnectionOpts } from "./client.js";
+import { E2B as BaseE2B } from "./index.js";
 import { Sandbox as BaseSandbox } from "./sandbox.js";
 export * from "./index.js";
 export type RunCodeLanguage = "python" | "javascript" | "typescript" | "r" | "java" | "bash" | (string & {});
@@ -135,9 +128,7 @@ export declare class Sandbox extends BaseSandbox {
 }
 export default Sandbox;
 /** E2B's client with bound options, for the code interpreter. */
-export declare class E2B {
+export declare class E2B extends BaseE2B {
+    protected static readonly sandboxClass: typeof BaseSandbox;
     readonly Sandbox: typeof Sandbox;
-    constructor(opts?: Omit<ConnectionOpts, "signal"> & {
-        client?: Runtime;
-    });
 }

package/dist/e2b/code-interpreter.js

@@ -1,5 +1,5 @@
 import { guard, NotSupportedError, SandboxError, TimeoutError } from "./errors.js";
-import { bind } from "./index.js";
+import { E2B as BaseE2B } from "./index.js";
 import { Sandbox as BaseSandbox } from "./sandbox.js";
 export * from "./index.js";
 /** A line of output, as E2B's callbacks receive it. */
@@ -234,9 +234,6 @@ export class Sandbox extends BaseSandbox {
 }
 export default Sandbox;
 /** E2B's client with bound options, for the code interpreter. */
-export class E2B {
-    Sandbox;
-    constructor(opts = {}) {
-        this.Sandbox = bind(Sandbox, opts);
-    }
+export class E2B extends BaseE2B {
+    static sandboxClass = Sandbox;
 }

package/dist/e2b/index.d.ts

@@ -15,9 +15,15 @@ export type { ConnectionOpts, HttpVersion, RuntimeOpts } from "./client.js";
 export { Pty, type PtyCreateOpts, type PtyConnectOpts } from "./pty.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, SecretPaginator, Git, ReadyCmd, LogEntry, LogEntryStart, LogEntryEnd, defaultBuildLogger, ConnectionConfig, ApiClient, getSignature, ALL_TRAFFIC, VolumeFileType, } from "./unsupported.js";
 export default Sandbox;
-/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
+/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`.
+ * Its Secret, Template and Volume refuse, naming Runtime's alternative, as
+ * the top-level exports do. */
 export declare class E2B {
+    protected static readonly sandboxClass: typeof Sandbox;
     readonly Sandbox: typeof Sandbox;
+    readonly Secret: import("./unsupported.js").Unsupported;
+    readonly Template: import("./unsupported.js").Unsupported;
+    readonly Volume: import("./unsupported.js").Unsupported;
     constructor(opts?: Omit<ConnectionOpts, "signal"> & {
         client?: Runtime;
     });

package/dist/e2b/index.js

@@ -1,5 +1,6 @@
 import { clientFor } from "./client.js";
 import { Sandbox } from "./sandbox.js";
+import { Secret, Template, Volume } from "./unsupported.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, } from "./commands.js";
 export { Filesystem, FileType, FilesystemEventType, } from "./filesystem.js";
@@ -7,11 +8,17 @@ export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError,
 export { Pty } from "./pty.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, SecretPaginator, Git, ReadyCmd, LogEntry, LogEntryStart, LogEntryEnd, defaultBuildLogger, ConnectionConfig, ApiClient, getSignature, ALL_TRAFFIC, VolumeFileType, } from "./unsupported.js";
 export default Sandbox;
-/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
+/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`.
+ * Its Secret, Template and Volume refuse, naming Runtime's alternative, as
+ * the top-level exports do. */
 export class E2B {
+    static sandboxClass = Sandbox;
     Sandbox;
+    Secret = Secret;
+    Template = Template;
+    Volume = Volume;
     constructor(opts = {}) {
-        this.Sandbox = bind(Sandbox, opts);
+        this.Sandbox = bind(new.target.sandboxClass, opts);
     }
 }
 /** A subclass whose static calls use `opts`'s key or client unless a call

package/dist/index.d.ts

@@ -18,13 +18,13 @@ export type { BookRoom, RoomBooking, RoomBookingPage } from "./products/reservat
 export type { AuditEvent, AuditPage } from "./products/audit.js";
 export type { Plan, PlanAddOn, PlanChange, PlanIncluded, PlanLimit, PlanNow, Plans, } from "./products/plans.js";
 export type { UsageExportQuery, UsageExportRow, UsageExportPage, } from "./products/observability.js";
-export type { JobSecret, Secret, SecretApiPolicy, SecretGit, SecretGithubApp, SecretRule, SecretScope, SecretUse, SetSecret, } from "./products/secrets.js";
+export type { JobSecret, Secret, SecretApiPolicy, SecretGit, SecretGithubApp, SecretRule, SecretScope, SecretUse, ListSecrets, SetSecret, } from "./products/secrets.js";
 export { SecretPartlyStoredError } from "./products/secrets.js";
 export type { McpCatalogEntry, McpGateway, McpServerRequest } from "./products/mcp.js";
 export type { FileEvent, FileEventType, WatchHandle, WatchNotice, WatchOptions, } from "./products/watch.js";
 export type { Mount, MountBucket } from "./products/mounts.js";
 export type { TailscaleJoin, TailscaleJoined, TailscaleNode, TailscaleStatus, } from "./products/tailscale.js";
-export type { Volume, VolumeBackup, CreateVolume, VolumeAttachment } from "./products/volumes.js";
+export type { Volume, VolumeBackup, VolumeBackupKeep, VolumeBackupSchedule, CreateVolume, VolumeAttachment, } from "./products/volumes.js";
 export type { CreateJob, Job, JobAlert, JobAlertDelivery, JobCompute, JobDefinition, JobLogs, JobRun, JobRunState, JobSchedule, UpdateJob, } from "./products/jobs.js";
 export type { CheckedDomain, DnsRecord, Domain, EgressAddress, TcpPort, Tunnel as PrivateTunnel, TunnelPeer, TunnelPeerCreated, SetUpstreamProxy, UpstreamProxy, } from "./products/network-products.js";
 export type { PrivateNetwork } from "./products/private-network.js";
@@ -78,8 +78,10 @@ export { openWalletAccount, claimWalletAccount, rekeyWalletAccount, type OpenedW
 export type { Topup } from "./products/billing.js";
 export type { NewKey, LimitedKey, LimitedKeyAction, MadeKey, ListedKey, KeyUsage, } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";
-export type { Agent, AgentDefinition, AgentEvent, AgentMemoryEntry, AgentMemoryFile, AgentMemoryHit, AgentMemoryPage, AgentMemoryUsage, AgentMemoryWritten, AgentSession, AgentSessionHandle, AgentSessionState, AgentTemplate, AgentTemplateKey, AgentTrigger, AgentTriggerKind, AgentUse, CreateAgent, CreateAgentTrigger, StartAgentSession, } from "./products/agents.js";
+export type { Agent, AgentAsk, AgentAskState, AgentDefinition, AgentEvent, AgentHeldCall, AgentMemoryEntry, AgentMemoryFile, AgentMemoryHit, AgentMemoryPage, AgentMemoryUsage, AgentMemoryWritten, AgentSession, AgentSessionHandle, AgentSessionState, AgentTemplate, AgentTemplateKey, AgentTrigger, AgentTriggerCall, AgentTriggerCallOutcome, AgentTriggerKind, AgentTriggerRules, AgentUse, AnswerAgentAsk, CreateAgent, CreateAgentTrigger, ListAgentAsks, StartAgentSession, } from "./products/agents.js";
 export { AGENT_TEMPLATES, AGENT_USES } from "./products/agents.js";
 export type { AgentsDeployChange, AgentsDeployOptions, AgentsDeployResult, AgentsFile, AgentsFileAgent, AgentsFileTrigger, AgentsSource, } from "./agents-deploy.js";
 export type { Container, ContainerState, CreateContainer, UpdateContainer, } from "./products/containers.js";
-export type { CiFlake, CiFlakeDetail, CiRepository, CiTestResult, ConnectCiRepository, ListCiFlakes, ListCiRepositories, UpdateCiFlake, } from "./products/ci.js";
+export type { Browser, BrowserConnectOptions, BrowserInfo, BrowserScreenshot, BrowserScreenshotResult, CreateBrowser, UpdateBrowser, } from "./products/browsers.js";
+export type { CreateDesktop, Desktop, DesktopAct, DesktopState, UpdateDesktop, } from "./products/desktops.js";
+export type { CiFlake, CiFlakeDetail, CiReleaseStep, CiRepository, CiTestResult, ConnectCiRepository, ListCiFlakes, ListCiReleaseSteps, ListCiRepositories, UpdateCiFlake, } from "./products/ci.js";

package/dist/products/agents.d.ts

@@ -51,6 +51,11 @@ export type AgentDefinition = {
      * GEMINI_API_KEY, OPENROUTER_API_KEY, or an OpenAI-compatible endpoint's
      * key with env.OPENAI_BASE_URL). */
     secrets?: string[];
+    /** Claude accounts, 1 to 16 egress secrets' names: subscription tokens,
+     * or API keys for a name holding API_KEY. Each session takes the one with
+     * the most usage left; the review template moves to the next when one is
+     * out of usage, and waits for the soonest reset when all are. */
+    pool?: string[];
     /** MCP servers the harness may reach. */
     mcp?: {
         name: string;
@@ -130,12 +135,90 @@ export type AgentEvent = {
     } & Record<string, unknown>;
     createdAt: string;
 };
+export type AgentAskState = "open" | "answered" | "expired" | "withdrawn" | "closed";
+/** One row of the account's inbox: a question a session's harness needs
+ * answered to go on. Asks of one agent's sessions sharing a memory, with the same `step` are
+ * one row while it is open, and one answer reaches every session asking. */
+export type AgentAsk = {
+    id: string;
+    /** The agent of the session that asked first. */
+    agentId: string;
+    /** What it waits on, in the asker's words. */
+    step: string | null;
+    question: string;
+    /** Why it matters. */
+    why: string | null;
+    options: {
+        label: string;
+        detail?: string;
+    }[];
+    /** The recommended option's label; taken as the answer when it expires. */
+    pick: string | null;
+    /** Who sees it: its agent's labels with the ask's own over them. */
+    labels: Record<string, string>;
+    state: AgentAskState;
+    /** An option's label and/or words; `expired` when the pick was taken at
+     * expiry. */
+    answer: {
+        option?: string;
+        text?: string;
+        expired?: boolean;
+    } | null;
+    /** A key's principal id, or `runtime` for a pick taken at expiry. */
+    answeredBy: string | null;
+    /** The sessions asking it, each with its ask event's seq and the answer
+     * event that woke it. */
+    sessions: {
+        sessionId: string;
+        state: "asking" | "answered" | "expired" | "withdrawn" | "ended";
+        seq: number;
+        answerSeq: number | null;
+    }[];
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    closedAt: string | null;
+};
+export type ListAgentAsks = {
+    /** Open by default. */
+    state?: AgentAskState[];
+    agent?: string;
+    /** Asks carrying every one of these labels: who sees an ask. */
+    labels?: Record<string, string>;
+    cursor?: string;
+    limit?: number;
+};
+/** An option's label, words, or both. */
+export type AnswerAgentAsk = {
+    option?: string;
+    text?: string;
+};
 export type AgentTriggerKind = "slack" | "github" | "schedule" | "webhook";
+/** A trigger's rules, each optional. */
+export type AgentTriggerRules = {
+    /** Queue order of its sessions when the agent's maxConcurrent is full:
+     * -100 to 100, higher first, then oldest. Default 0. */
+    priority?: number;
+    /** Sessions it may start in an hour; a call past it is held for you.
+     * Joining an open session is never capped. Default none. */
+    maxStartsPerHour?: number;
+    /** A call whose key's last session has ended: "start" a new one (the
+     * default), "note" it in the ended session's log and run nothing, or
+     * "ask" you (the call is held until you start it). */
+    onEnded?: "start" | "note" | "ask";
+    /** Where a held call is told: "email" to who added the trigger (the
+     * default), or "webhook", the account's webhooks' agent.call.held alone. */
+    notify?: "email" | "webhook";
+    /** A webhook's only: the key of a call that sends none, from its JSON's
+     * fields: "{cause}", "{alert.host}:{check}". */
+    key?: string;
+};
 export type AgentTrigger = {
     id: string;
     agentId: string;
     kind: AgentTriggerKind;
     config: Record<string, unknown>;
+    rules: AgentTriggerRules;
     pausedAt: string | null;
     pausedWhy: string | null;
     createdAt: string;
@@ -157,7 +240,7 @@ export type StartAgentSession = {
     key?: string;
     labels?: Record<string, string>;
 };
-export type CreateAgentTrigger = {
+export type CreateAgentTrigger = ({
     kind: "slack";
     config: {
         team: string;
@@ -180,9 +263,48 @@ export type CreateAgentTrigger = {
 } | {
     kind: "webhook";
     config: Record<string, never>;
+}) & {
+    rules?: AgentTriggerRules;
+};
+/** One call to a webhook trigger: its words, and the key and labels of the
+ * session it starts or joins. */
+export type AgentTriggerCall = {
+    text: string;
+    key?: string;
+    labels?: Record<string, string>;
+};
+/** What a call did: started a session, joined its key's open one, was
+ * noted in its key's ended one, or was held for you (`why`). */
+export type AgentTriggerCallOutcome = {
+    outcome: "started" | "joined" | "noted" | "held";
+    sessionId: string | null;
+    seq: number | null;
+    callId: string | null;
+    why: AgentHeldCall["why"] | null;
+    replayed: boolean;
+};
+/** A call a trigger held for you because no session could take it. None is
+ * ever dropped. */
+export type AgentHeldCall = {
+    id: string;
+    triggerId: string;
+    agentId: string;
+    key: string | null;
+    text: string;
+    labels: Record<string, string>;
+    /** The trigger was paused; it had started maxStartsPerHour sessions this
+     * hour; its key's session had ended and onEnded is "ask"; the agent's day
+     * budget was spent; the account's sessions were at their limit; Agents
+     * was closed to the account. */
+    why: "paused" | "rate" | "ended" | "budget" | "quota" | "closed";
+    state: "held" | "started" | "dismissed";
+    sessionId: string | null;
+    notify: "email" | "webhook";
+    createdAt: string;
+    resolvedAt: string | null;
 };
-/** The five harnesses' names, so `templates["claude-code"]` is known to be there. */
-export type AgentTemplateKey = "claude-code" | "codex" | "gemini-cli" | "claude-agent-sdk" | "openai-agents-sdk";
+/** The harnesses' names, so `templates["claude-code"]` is known to be there. */
+export type AgentTemplateKey = "claude-code" | "codex" | "gemini-cli" | "claude-agent-sdk" | "openai-agents-sdk" | "review" | "judge";
 /** A file of an agent's memory (`memory.list`). `scope` is whose: empty for
  * the shared memory, which every session reads (one keeping memory per key
  * reads what you wrote there, and never changes it), or a session key
@@ -240,9 +362,8 @@ export type AgentTemplate = {
     /** How your own subscription logs it in, for your own team's agents, or
      * null when it takes an API key alone. */
     subscription: string | null;
-    definition: {
+    definition: Pick<AgentDefinition, "secrets" | "pool" | "vcpu" | "memoryMiB" | "maxSessionSeconds"> & {
         command: string;
-        secrets: string[];
     };
 };
 /** A use: what an agent is for, merged into a template's definition. */
@@ -257,7 +378,7 @@ export type AgentUse = {
         template: "support" | "team";
     };
 };
-/** The five harnesses (agents-contract.md); tests/agents.test.ts holds them
+/** The harnesses (agents-contract.md); tests/agents.test.ts holds them
  * to packages/cloud-guide/agent-templates.json. */
 export declare const AGENT_TEMPLATES: Readonly<Record<AgentTemplateKey, AgentTemplate>>;
 /** A harness by a key read from a file or a flag, or undefined. */
@@ -321,13 +442,45 @@ export declare function agents(t: Transport): {
          * (`session_open`): stop it first. */
         delete: (id: string, options?: RequestOptions) => Promise<void>;
     };
+    /** The account's inbox: the questions its agents' sessions need answered
+     * to go on, one row per step however many sessions ask it. */
+    asks: {
+        /** Newest first; open ones unless `state` says otherwise. */
+        list: (query?: ListAgentAsks, options?: RequestOptions) => Promise<Page<AgentAsk>>;
+        get: (id: string, options?: RequestOptions) => Promise<AgentAsk>;
+        /** Every session asking it reads the answer next, and wakes. An ask no
+         * longer open is refused with `ask_closed`. */
+        answer: (id: string, answer: AnswerAgentAsk, options?: RequestOptions) => Promise<AgentAsk>;
+    };
     triggers: {
         create: (agent: string, input: CreateAgentTrigger, options?: RequestOptions) => Promise<AgentTrigger>;
         list: (agent: string, options?: RequestOptions) => Promise<AgentTrigger[]>;
-        /** Its events are refused, saying `why`; nothing else is held. */
+        /** Held: a webhook's calls are kept for you (see `held`), saying
+         * `why`; nothing else is held. */
         pause: (id: string, why: string, options?: RequestOptions) => Promise<AgentTrigger>;
         resume: (id: string, options?: RequestOptions) => Promise<AgentTrigger>;
         delete: (id: string, options?: RequestOptions) => Promise<void>;
+        /** Its rules, whole, in place: its secret stays. `{}` is every default. */
+        setRules: (id: string, rules: AgentTriggerRules, options?: RequestOptions) => Promise<AgentTrigger>;
+        /** A webhook trigger's call, as its sender makes it: by the trigger's
+         * secret, never your key. A call with the key of an open session joins
+         * it. Pass `idempotencyKey` to make a retry the same call. */
+        call: (id: string, secret: string, call: AgentTriggerCall, options?: RequestOptions) => Promise<AgentTriggerCallOutcome>;
+        /** Calls it held for you, newest first. */
+        held: (trigger: string, query?: {
+            state?: AgentHeldCall["state"][];
+            cursor?: string;
+            limit?: number;
+        }, options?: RequestOptions) => Promise<Page<AgentHeldCall>>;
+        /** Start a held call: one session with it and every call held for its
+         * key since, oldest first. */
+        startHeld: (id: string, call: string, options?: RequestOptions) => Promise<{
+            session: AgentSession;
+            joined: boolean;
+            calls: number;
+        }>;
+        /** Dismiss a held call: nothing runs. */
+        dismissHeld: (id: string, call: string, options?: RequestOptions) => Promise<AgentHeldCall>;
     };
     /** Its built-in memory: text files kept across sessions, which the
      * agent reads, writes and searches from inside its sessions. A scope is
@@ -363,7 +516,8 @@ export declare function agents(t: Transport): {
         }, options?: RequestOptions) => Promise<boolean>;
     };
     /** The harnesses, as data: claude-code, codex, gemini-cli,
-     * claude-agent-sdk, openai-agents-sdk. */
+     * claude-agent-sdk, openai-agents-sdk, review (a CI/CD agent step's
+     * reviewer) and judge (an agent step held to your instructions alone). */
     templates: Readonly<Record<AgentTemplateKey, AgentTemplate>>;
     /** The uses, as data: support (your customers) and team (your team). */
     uses: Readonly<Record<"team" | "support", AgentUse>>;