withruntime 0.23.0 → 0.33.0

package/dist/index.d.ts

@@ -14,16 +14,18 @@ export { Files, Process, Processes, SandboxSessions, Terminal, type CreatedSandb
 export { Tunnel, TunnelStream, type PortForward } from "./tunnel.js";
 export { Page } from "./page.js";
 export type { AccountLimit, KeyLimits } from "./products/limits.js";
+export type { BookRoom, RoomBooking, RoomBookingPage } from "./products/reservations.js";
 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, SecretRule, SecretScope, SecretUse, SetSecret, } from "./products/secrets.js";
+export type { JobSecret, Secret, SecretApiPolicy, SecretGit, SecretGithubApp, SecretRule, SecretScope, SecretUse, 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 { CreateJob, Job, JobCompute, JobDefinition, JobLogs, JobRun, JobRunState, JobSchedule, } from "./products/jobs.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";
 export type { SignedRequests } from "./products/signed-requests.js";
@@ -76,6 +78,8 @@ export { openWalletAccount, claimWalletAccount, rekeyWalletAccount, type OpenedW
 export type { Topup } from "./products/billing.js";
 export type { NewKey, LimitedKey, LimitedKeyAction, MadeKey, ListedKey, KeyUsage, } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";
-export type { Agent, AgentDefinition, AgentEvent, AgentSession, AgentSessionHandle, AgentSessionState, AgentTemplate, AgentTemplateKey, AgentTrigger, AgentTriggerKind, AgentUse, CreateAgent, CreateAgentTrigger, StartAgentSession, } from "./products/agents.js";
+export 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 { 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";

package/dist/machine.d.ts

@@ -90,19 +90,23 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
      * persistent, and comes back running at the new size on the same server; a
      * paused or stopped one is started. Memory bills on the new size from then.
+     * A larger disk alone on a running sandbox grows live instead, every
+     * program left running; `restart: false` asks for that or a refusal
+     * (`resize_needs_restart`: paused, stopped, a custom image, or a server
+     * that cannot), never a restart.
      * Refused, with nothing changed, when the server has no room
      * (`no_capacity`), above your quota or the 2 vCPU and 4 GiB without credit, or
-     * while a snapshot or fork of it is being taken. `restart` is optional:
-     * true is the only value, and it is sent either way, so an API from before
-     * it was optional accepts the call too. */
+     * while a snapshot or fork of it is being taken. `restart` defaults to
+     * true and is sent either way, so an API from before it was optional
+     * accepts the call too. */
     resize(
-    /** diskMiB only grows; the filesystem fills it at the restart. */
+    /** diskMiB only grows; the filesystem fills it at once (live) or at the restart. */
     size: {
         vcpu?: number;
         memoryMiB?: number;
         diskMiB?: number;
     }, options?: RequestOptions & {
-        restart?: true;
+        restart?: boolean;
     }): Promise<this>;
     /** Keeps a sandbox with a time limit running past it, in the background,
      * until stop() or the returned function ends it: every `everySeconds` (60)
@@ -110,7 +114,7 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * than the hour ahead the API allows. A sandbox with no time limit
      * (`endsAt` null) needs none, and is only watched. Running time is billed
      * as it is used. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
+     * unless autoWake is off); a stopped or deleted one ends the loop. It does not keep a
      * Node or Bun process alive by itself. */
     keepAlive(options?: KeepAliveOptions): () => void;
     /** Days a paused sandbox is kept before deletion (1 to 365), or `null` to

package/dist/machine.js

@@ -170,20 +170,24 @@ export class Machine {
      * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
      * persistent, and comes back running at the new size on the same server; a
      * paused or stopped one is started. Memory bills on the new size from then.
+     * A larger disk alone on a running sandbox grows live instead, every
+     * program left running; `restart: false` asks for that or a refusal
+     * (`resize_needs_restart`: paused, stopped, a custom image, or a server
+     * that cannot), never a restart.
      * Refused, with nothing changed, when the server has no room
      * (`no_capacity`), above your quota or the 2 vCPU and 4 GiB without credit, or
-     * while a snapshot or fork of it is being taken. `restart` is optional:
-     * true is the only value, and it is sent either way, so an API from before
-     * it was optional accepts the call too. */
+     * while a snapshot or fork of it is being taken. `restart` defaults to
+     * true and is sent either way, so an API from before it was optional
+     * accepts the call too. */
     async resize(
-    /** diskMiB only grows; the filesystem fills it at the restart. */
+    /** diskMiB only grows; the filesystem fills it at once (live) or at the restart. */
     size, options = {}) {
         const { restart = true, ...rest } = options;
         this.#keep(await this.#t.json({
             method: "POST",
             path: this.#path(":resize"),
             body: { ...size, restart },
-            // A pause or stop and a cold boot.
+            // A pause or stop and a cold boot (a live grow answers at once).
             wait: 120,
             ...requestOnly(rest),
         }));
@@ -195,7 +199,7 @@ export class Machine {
      * than the hour ahead the API allows. A sandbox with no time limit
      * (`endsAt` null) needs none, and is only watched. Running time is billed
      * as it is used. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
+     * unless autoWake is off); a stopped or deleted one ends the loop. It does not keep a
      * Node or Bun process alive by itself. */
     keepAlive(options = {}) {
         this.#keepAlive?.();
@@ -226,6 +230,10 @@ export class Machine {
                 }
             }
             catch (error) {
+                // Gone (deleted elsewhere, or by its own time limit): nothing to keep
+                // alive, and asking again would only be refused.
+                if (error instanceof RuntimeError && error.status === 404)
+                    return end();
                 options.onError?.(error);
             }
             if (ended)

package/dist/modal/index.d.ts

@@ -149,6 +149,21 @@ export declare class Proxy {
 export declare class ProxyService {
     readonly fromName: RefusedAsync;
 }
+export declare class FunctionService {
+    readonly fromName: RefusedAsync;
+    readonly fromId: RefusedAsync;
+}
+export declare class FunctionCallService {
+    readonly fromId: RefusedAsync;
+}
+export declare class ClsService {
+    readonly fromName: RefusedAsync;
+}
+export declare class QueueService {
+    readonly fromName: RefusedAsync;
+    readonly ephemeral: RefusedAsync;
+    readonly delete: RefusedAsync;
+}
 export declare class ExperimentalOutboundPolicy {
     readonly withHeaderReplacement: Refused;
 }
@@ -185,8 +200,14 @@ export declare class Image {
     /** The id is a native disk snapshot (snapshotFilesystem), not an image. */
     snapshot?: boolean);
     get imageId(): string;
+    /** A layer of Dockerfile commands. Its `secrets` refuse: a Runtime build
+     * keeps its build arguments in the image's build plan, history and cache
+     * key, and has no channel that never keeps a value, so a secret is used at
+     * run time instead (security review, 18 October 2026). */
     dockerfileCommands(commands: string[], params?: {
         env?: Record<string, string>;
+        secrets?: Secret[];
+        gpu?: string;
         forceBuild?: boolean;
     }): Image;
     build(_app?: App): Promise<Image>;
@@ -248,6 +269,10 @@ export declare class ModalClient {
     readonly sandboxSnapshots: SandboxSnapshotService;
     readonly proxies: ProxyService;
     readonly environments: EnvironmentService;
+    readonly functions: FunctionService;
+    readonly functionCalls: FunctionCallService;
+    readonly cls: ClsService;
+    readonly queues: QueueService;
     constructor(options?: ModalClientParams);
     /** Throws once close() was called, as Modal's client does. */
     open(): void;
@@ -269,6 +294,7 @@ export type SandboxCreateParams = {
     memoryLimitMiB?: number;
     runtime?: "gvisor" | "vm";
     timeoutMs?: number;
+    idleTimeoutMs?: number;
     workdir?: string;
     command?: string[];
     env?: Record<string, string>;
@@ -285,6 +311,7 @@ export type SandboxCreateParams = {
     cloudBucketMounts?: Record<string, CloudBucketMount>;
     readinessProbe?: Probe;
     experimentalEnableSnapshot?: boolean;
+    experimentalOptions?: Record<string, boolean | string>;
 };
 export type SandboxExecParams = {
     mode?: "text" | "binary";
@@ -341,6 +368,7 @@ export declare class ModalWriteStream<R extends string | Uint8Array = string> ex
     writeBytes(bytes: Uint8Array): Promise<void>;
 }
 export declare class ContainerProcess<R extends string | Uint8Array = string> {
+    #private;
     readonly native: Process;
     readonly stdin: ModalWriteStream<R>;
     readonly stdout: ModalReadStream<R>;
@@ -348,6 +376,8 @@ export declare class ContainerProcess<R extends string | Uint8Array = string> {
     constructor(native: Process, mode: "text" | "binary", params?: SandboxExecParams);
     wait(): Promise<number>;
     closeStdin(): Promise<void>;
+    /** null while it runs, then its exit code. A process whose sandbox ended
+     * before its exit was seen was killed with it: 137, as Modal reports. */
     _poll(): Promise<number | null>;
 }
 /** Host and port of a sandbox port's public HTTPS address. Runtime previews
@@ -400,6 +430,10 @@ export declare class Sandbox {
     monitorEntrypoint(): void;
     constructor(native: NativeSandbox, primary: ContainerProcess, client?: ModalClient | undefined);
     get sandboxId(): string;
+    /** Ends the sandbox after `ms`, for a Modal timeout under Runtime's
+     * shortest time limit (a minute, which stays the bound if this client
+     * goes away). The timer never keeps the program running. */
+    terminateAfter(ms: number): void;
     private attached;
     exec(command: string[], params?: SandboxExecParams & {
         mode?: "text";

package/dist/modal/index.js

@@ -274,6 +274,26 @@ export class ProxyService {
 const STATIC_IPS = "Runtime static egress IPs: runtime.ips";
 refuse("Modal", "Proxy", Proxy, { proxyId: STATIC_IPS }, { sync: true });
 refuse("Modal", "ProxyService", ProxyService, { fromName: STATIC_IPS });
+// Modal's other products, outside its sandboxes: each call refuses, naming
+// what to use, where it was undefined before (function-call.ts, 18 October 2026).
+const FUNCTIONS = "Runtime runs sandboxes, not Modal Functions: run the code in a sandbox (modal.sandboxes.create), or on a schedule as a Runtime job (runtime.jobs)";
+const QUEUES = "keep the queue in your own store, or in a file on a Runtime volume (runtime.volumes)";
+export class FunctionService {
+}
+export class FunctionCallService {
+}
+export class ClsService {
+}
+export class QueueService {
+}
+refuse("Modal", "FunctionService", FunctionService, { fromName: FUNCTIONS, fromId: FUNCTIONS });
+refuse("Modal", "FunctionCallService", FunctionCallService, { fromId: FUNCTIONS });
+refuse("Modal", "ClsService", ClsService, { fromName: FUNCTIONS });
+refuse("Modal", "QueueService", QueueService, {
+    fromName: QUEUES,
+    ephemeral: QUEUES,
+    delete: QUEUES,
+});
 export class ExperimentalOutboundPolicy {
 }
 refuse("Modal", "ExperimentalOutboundPolicy", ExperimentalOutboundPolicy, {
@@ -309,6 +329,7 @@ export class Probe {
 }
 refuse("Modal", "Probe", Probe, { toProto: "pass it as readinessProbe" }, { sync: true });
 // Images ------------------------------------------------------------------------
+const BUILD_SECRETS = "a Runtime image build keeps no secret: use it at run time, with sandboxes.create(app, image, { secrets }), or runtime.secrets.set({ value, hosts }) so the sandbox never sees it";
 export class Image {
     runtime;
     tag;
@@ -335,10 +356,18 @@ export class Image {
             throw new Error("Image is not built; await image.build(app) first.");
         return this.built;
     }
+    /** A layer of Dockerfile commands. Its `secrets` refuse: a Runtime build
+     * keeps its build arguments in the image's build plan, history and cache
+     * key, and has no channel that never keeps a value, so a secret is used at
+     * run time instead (security review, 18 October 2026). */
     dockerfileCommands(commands, params = {}) {
-        only("Modal image", params, ["env", "forceBuild"]);
+        only("Modal image", params, ["env", "secrets", "gpu", "forceBuild"]);
+        if (params.gpu)
+            throw new CompatibilityError("Modal", "GPU image builds");
         if (!this.tag)
             throw new CompatibilityError("Modal", "extending a prebuilt Runtime image through Dockerfile layers");
+        if (params.secrets?.length)
+            throw refusal("Modal", "Image.dockerfileCommands secrets", BUILD_SECRETS);
         return new Image(this.runtime, this.tag, undefined, [...this.commands, ...commands], { ...this.env, ...params.env }, params.forceBuild ? false : this.cache);
     }
     async build(_app) {
@@ -433,6 +462,10 @@ export class ModalClient {
     sandboxSnapshots;
     proxies = new ProxyService();
     environments = new EnvironmentService();
+    functions = new FunctionService();
+    functionCalls = new FunctionCallService();
+    cls = new ClsService();
+    queues = new QueueService();
     #closed = false;
     constructor(options = {}) {
         if (options.endpoint !== undefined ||
@@ -496,21 +529,45 @@ refuse("Modal", "ModalClient", ModalClient, {
 refuse("Modal", "ModalClient", ModalClient, {
     getImageBuilderVersion: "Runtime images record theirs: (await runtime.images.get(id)).build.builderVersion",
 });
-/** Modal's outbound allowlists as Runtime network rules, never wider than
- * Modal's: a missing list or a wildcard entry allows everything, an empty
- * list blocks all egress. Runtime's rules are one list a connection matches
- * any entry of, so a domain list and a CIDR list that both narrow are
- * refused rather than joined into a wider rule. */
+// Sandboxes ---------------------------------------------------------------------
+/** Who a sandbox's processes run as: root, as in a Modal container (and a
+ * registry image's default user), where Runtime's own default is uid 1000.
+ * Modal code writes to /, installs packages and starts daemons unprefixed. */
+const ROOT = "root";
+/** Modal's outbound allowlists as Runtime network rules. Modal allows a
+ * connection a listed domain or a listed CIDR range admits, and a list left
+ * out admits nothing once the other is given (modal-client
+ * buildOutboundNetworkAccess; its guide: "except traffic allowed by
+ * outbound_domain_allowlist"). Runtime's `allow` is the same union, one list
+ * a connection matches any entry of. Modal's `*.example.com` also matches
+ * example.com, where Runtime's leaves the apex out, so both are listed.
+ * Every domain ("*") with narrower addresses is refused: Runtime cannot
+ * admit every name without every address. Before 18 October 2026 an empty
+ * CIDR list blocked the listed domains too, and two narrowing lists were
+ * refused (Modal's sandbox-network-policy.ts gives both). */
 function egress(domains, cidrs) {
-    if (domains?.length === 0 || cidrs?.length === 0)
-        return { internet: false };
-    const anyDomain = !domains || domains.includes("*");
-    const anyCidr = !cidrs || cidrs.some((c) => c === "0.0.0.0/0" || c === "::/0");
-    if (anyDomain && anyCidr)
+    if (domains === undefined && cidrs === undefined)
+        return { internet: true };
+    // Every address is both families' whole range. One of them alone stays an
+    // ordinary rule: ::/0 by itself opened IPv4 as well, wider than Modal.
+    const whole = [...new Set(cidrs ?? [])].filter((c) => c === "0.0.0.0/0" || c === "::/0");
+    if (whole.length === 2)
         return { internet: true };
-    if (!anyDomain && !anyCidr)
-        throw new CompatibilityError("Modal", "a domain allowlist and a CIDR allowlist at once; pass one list of domains and CIDR ranges to sandbox.native.network.set({ internet: true, allow })");
-    return { internet: true, allow: anyDomain ? cidrs : domains };
+    if ((domains ?? []).includes("*")) {
+        // Every name beside one family's whole range: Runtime has no rule for
+        // every name, so the range alone (Modal's own examples pass "*" with
+        // 0.0.0.0/0). Narrower than Modal's by the other family, never wider.
+        if (whole.length)
+            return { internet: true, allow: whole };
+        throw new CompatibilityError("Modal", 'a domain allowlist of "*" with a narrower CIDR allowlist; pass ["0.0.0.0/0", "::/0"] with it for all traffic, or list the domains');
+    }
+    const allow = [
+        ...new Set([
+            ...(domains ?? []).flatMap((d) => (d.startsWith("*.") ? [d, d.slice(2)] : [d])),
+            ...(cidrs ?? []),
+        ]),
+    ];
+    return allow.length ? { internet: true, allow } : { internet: false };
 }
 const ENVIRONMENTS = "named Modal environments";
 const CREATE_OPTIONS = [
@@ -521,6 +578,7 @@ const CREATE_OPTIONS = [
     "memoryLimitMiB",
     "runtime",
     "timeoutMs",
+    "idleTimeoutMs",
     "workdir",
     "command",
     "env",
@@ -537,6 +595,7 @@ const CREATE_OPTIONS = [
     "cloudBucketMounts",
     "readinessProbe",
     "experimentalEnableSnapshot",
+    "experimentalOptions",
 ];
 export class SandboxService {
     runtime;
@@ -566,6 +625,15 @@ export class SandboxService {
             throw new TypeError("blockNetwork cannot be combined with allowlists");
         if (params.runtime !== undefined && params.runtime !== "vm")
             throw new InvalidError(`Unknown sandbox runtime ${String(params.runtime)}`);
+        for (const [option, value] of Object.entries(params.experimentalOptions ?? {}))
+            throw option === "enable_exit_snapshot" && value
+                ? refusal("Modal", "experimentalOptions.enable_exit_snapshot", "call sandbox.snapshotFilesystem() before terminate(), then start new sandboxes from that Image")
+                : new CompatibilityError("Modal", `experimental option ${option}`);
+        if (params.timeoutMs !== undefined && !(params.timeoutMs > 0))
+            throw new InvalidError(`timeoutMs must be positive, got ${params.timeoutMs}`);
+        if (params.idleTimeoutMs !== undefined &&
+            (!(params.idleTimeoutMs > 0) || params.idleTimeoutMs % 1000 !== 0))
+            throw new InvalidError(`idleTimeoutMs must be a positive multiple of 1000ms, got ${params.idleTimeoutMs}`);
         const network = params.blockNetwork
             ? { internet: false }
             : egress(params.outboundDomainAllowlist, params.outboundCidrAllowlist);
@@ -604,11 +672,22 @@ export class SandboxService {
             region: placement,
             ...(volumes.length ? { volumes } : {}),
             // A timeout is the customer's limit, and the sandbox never pauses
-            // for idleness before it. None is no time limit (0300): it runs while
-            // it works and pauses when idle.
+            // for idleness before it unless idleTimeoutMs asks. None is no time
+            // limit (0300): it runs while it works and pauses when idle. Runtime's
+            // shortest limit is a minute: a shorter one is kept by this client
+            // (below), with the minute as the bound if the client goes away.
             ...(params.timeoutMs === undefined
                 ? {}
-                : { timeoutSeconds: Math.ceil(params.timeoutMs / 1000), idlePauseSeconds: 0 }),
+                : {
+                    timeoutSeconds: Math.max(60, Math.ceil(params.timeoutMs / 1000)),
+                    idlePauseSeconds: 0,
+                }),
+            // Modal ends an idle sandbox; Runtime pauses it, memory kept and CPU
+            // no longer billed, and wakes it at the next command, file call or
+            // tunnel request. Runtime's shortest idle pause is ten seconds.
+            ...(params.idleTimeoutMs === undefined
+                ? {}
+                : { idlePauseSeconds: Math.max(10, params.idleTimeoutMs / 1000) }),
             onLeaseEnd: "stop",
             network,
         };
@@ -616,7 +695,7 @@ export class SandboxService {
             for (const mount of mounts)
                 await s.mounts.add(mount);
             primary = await s.spawn(params.command ?? ["sleep", "infinity"], {
-                ...(await execOptions(s, { cwd: params.workdir })),
+                ...(await execOptions(s, { cwd: params.workdir, user: ROOT })),
                 stdin: "pipe",
                 pty: params.pty ? {} : undefined,
             });
@@ -626,6 +705,8 @@ export class SandboxService {
         }));
         const sandbox = new Sandbox(s, new ContainerProcess(primary, "text"), this.client);
         sandbox.monitorEntrypoint();
+        if (params.timeoutMs !== undefined && params.timeoutMs < 60_000)
+            sandbox.terminateAfter(params.timeoutMs);
         return sandbox;
     }
     async experimentalCreate(app, image, params = {}) {
@@ -807,18 +888,35 @@ export class ContainerProcess {
         this.stdout = new ModalReadStream(native, "stdout", mode, params.stdout === "ignore");
         this.stderr = new ModalReadStream(native, "stderr", mode, params.stderr === "ignore");
     }
+    /** The exit code, once seen: a poll after the sandbox ended still has it. */
+    #exitCode;
     async wait() {
         const r = await this.native.wait();
         if (r.timedOut)
             throw new SandboxTimeoutError("Process timed out");
-        return r.exitCode ?? -1;
+        this.#exitCode = r.exitCode ?? -1;
+        return this.#exitCode;
     }
     closeStdin() {
         return this.native.write("", { eof: true });
     }
+    /** null while it runs, then its exit code. A process whose sandbox ended
+     * before its exit was seen was killed with it: 137, as Modal reports. */
     async _poll() {
-        const p = await this.native.refresh();
-        return p.state === "running" ? null : p.exitCode;
+        if (this.#exitCode !== undefined)
+            return this.#exitCode;
+        try {
+            const p = await this.native.refresh();
+            if (p.state === "running")
+                return null;
+            return (this.#exitCode = p.exitCode ?? -1);
+        }
+        catch (error) {
+            if (error instanceof RuntimeError &&
+                (error.code === "sandbox_stopped" || error.status === 404))
+                return (this.#exitCode = 137);
+            throw error;
+        }
     }
 }
 /** Host and port of a sandbox port's public HTTPS address. Runtime previews
@@ -903,6 +1001,13 @@ export class Sandbox {
     get sandboxId() {
         return this.native.id;
     }
+    /** Ends the sandbox after `ms`, for a Modal timeout under Runtime's
+     * shortest time limit (a minute, which stays the bound if this client
+     * goes away). The timer never keeps the program running. */
+    terminateAfter(ms) {
+        const timer = setTimeout(() => void this.terminate().catch(() => undefined), ms);
+        timer.unref?.();
+    }
     attached() {
         this.client?.open();
         if (this.detached)
@@ -922,6 +1027,7 @@ export class Sandbox {
         ]);
         const p = await this.native.spawn(command, {
             ...(await execOptions(this.native, {
+                user: ROOT,
                 cwd: params.workdir,
                 timeoutMs: params.timeoutMs === 0 ? 86_400_000 : params.timeoutMs,
                 env: Object.assign({}, ...(params.secrets?.map((s) => s.values) ?? []), params.env ?? {}),
@@ -989,7 +1095,7 @@ export class Sandbox {
             const left = Math.ceil(until - performance.now());
             if (left <= 0)
                 throw new TimeoutError("Timeout expired");
-            const result = await this.native.exec(argv, { timeoutMs: left });
+            const result = await this.native.exec(argv, { timeoutMs: left, user: ROOT });
             if (result.exitCode === 0)
                 return;
             await new Promise((resolve) => setTimeout(resolve, Math.min(probe.intervalMs, left)));

package/dist/products/agents.d.ts

@@ -23,13 +23,19 @@ import type { RequestOptions, Transport } from "../transport.js";
 export type AgentDefinition = {
     /** What runs the harness, from the sandbox's home. */
     command: string;
-    /** Where each session's sandbox starts: an image of yours, or a snapshot
-     * of a machine you set up by hand (a harness logged in to your own
-     * subscription included). The default image has Node and Python. */
+    /** Where each session's sandbox starts: an image of yours; a snapshot of
+     * a machine you set up by hand (a harness logged in to your own
+     * subscription included); or a GitHub repository connected to CI/CD,
+     * `owner/name`, whose warm snapshot (checked out at /workspace/repo at its
+     * production branch's last passing commit, set up) each session starts
+     * as a copy of, its harness run there. The default image has Node and
+     * Python. */
     from?: {
         image: string;
     } | {
         snapshot: string;
+    } | {
+        repo: string;
     };
     /** 1, 2, 4, 8 or 16; default 4. */
     vcpu?: number;
@@ -61,8 +67,19 @@ export type AgentDefinition = {
     maxSessionSeconds?: number;
     /** Sessions running at once; more wait, queued. Default 10. */
     maxConcurrent?: number;
+    /** What one session may cost, its subagents' sessions included, in
+     * dollars; it stops with reason `budget` there. Default 5. */
+    maxSessionDollars?: number;
+    /** What the agent's sessions may cost in a day, in dollars; past it the
+     * agent starts nothing new (`budget_reached`) until the next. Default 100. */
+    maxDayDollars?: number;
     /** The use it was set up for (`uses`). */
     template?: "support" | "team";
+    /** Whose memory a session reads: `key` (the default), each session key
+     * its own; `agent`, one all its sessions share, never a support agent's. */
+    memory?: {
+        scope: "key" | "agent";
+    };
 };
 export type Agent = {
     id: string;
@@ -122,6 +139,8 @@ export type AgentTrigger = {
     pausedAt: string | null;
     pausedWhy: string | null;
     createdAt: string;
+    /** When it last changed: made, paused or resumed. */
+    updatedAt: string;
     /** A webhook's secret, which each of its calls carries: answered once,
      * when it is added, and never again. Keep it where you keep your keys. */
     secret?: string;
@@ -164,6 +183,50 @@ export type CreateAgentTrigger = {
 };
 /** The five harnesses' names, so `templates["claude-code"]` is known to be there. */
 export type AgentTemplateKey = "claude-code" | "codex" | "gemini-cli" | "claude-agent-sdk" | "openai-agents-sdk";
+/** A 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
+ * (`customer:42`) for that key's alone. */
+export type AgentMemoryEntry = {
+    scope: string;
+    path: string;
+    /** Its text and path, in bytes, as billed. */
+    bytes: number;
+    updatedAt: string;
+    /** A key's principal id, or session:<id> when the agent wrote it. */
+    updatedBy: string;
+};
+export type AgentMemoryFile = AgentMemoryEntry & {
+    content: string;
+};
+export type AgentMemoryHit = {
+    scope: string;
+    path: string;
+    /** Its words around the match, matches in **bold**. */
+    snippet: string;
+    /** Higher is better. */
+    rank: number;
+    bytes: number;
+    updatedAt: string;
+};
+export type AgentMemoryWritten = {
+    scope: string;
+    path: string;
+    bytes: number;
+    /** True for a new file, false for one replaced. */
+    created: boolean;
+    updatedAt: string;
+};
+/** The agent's whole memory, every scope: what storage is billed on. */
+export type AgentMemoryUsage = {
+    bytes: number;
+    files: number;
+    limitBytes: number;
+    limitFiles: number;
+};
+export type AgentMemoryPage = Page<AgentMemoryEntry> & {
+    readonly usage: AgentMemoryUsage;
+};
 /** A harness, as data (packages/cloud-guide/agent-templates.json, the same
  * in every SDK and the guide). `definition` is what an agent's definition
  * takes from it; add a use's (`uses`) and your instructions. */
@@ -197,6 +260,8 @@ export type AgentUse = {
 /** The five harnesses (agents-contract.md); tests/agents.test.ts holds them
  * to packages/cloud-guide/agent-templates.json. */
 export declare const AGENT_TEMPLATES: Readonly<Record<AgentTemplateKey, AgentTemplate>>;
+/** A harness by a key read from a file or a flag, or undefined. */
+export declare function agentTemplate(key: string): AgentTemplate | undefined;
 export declare const AGENT_USES: Readonly<Record<"support" | "team", AgentUse>>;
 /** One session, to talk to and follow. */
 export type AgentSessionHandle = {
@@ -264,6 +329,39 @@ export declare function agents(t: Transport): {
         resume: (id: string, options?: RequestOptions) => Promise<AgentTrigger>;
         delete: (id: string, options?: RequestOptions) => Promise<void>;
     };
+    /** Its built-in memory: text files kept across sessions, which the
+     * agent reads, writes and searches from inside its sessions. A scope is
+     * whose: "" (the default) for what every session reads, or a session key
+     * ("customer:42") for that key's alone. Up to 1 MiB a file, 1 GiB and
+     * 100,000 files an agent, billed as storage. */
+    memory: {
+        /** Its files by scope and path, a page at a time, with its usage.
+         * Without scope, every scope. */
+        list: (agent: string, query?: {
+            scope?: string;
+            prefix?: string;
+            cursor?: string;
+            limit?: number;
+        }, options?: RequestOptions) => Promise<AgentMemoryPage>;
+        /** The files whose words or paths match, best first, each with a
+         * snippet: words, "a phrase", or, -not. Without scope, every scope. */
+        search: (agent: string, q: string, query?: {
+            scope?: string;
+            limit?: number;
+        }, options?: RequestOptions) => Promise<AgentMemoryHit[]>;
+        /** One file, with its text; not_found when there is none. */
+        read: (agent: string, path: string, query?: {
+            scope?: string;
+        }, options?: RequestOptions) => Promise<AgentMemoryFile>;
+        /** Seeds or replaces a file. */
+        write: (agent: string, path: string, content: string, query?: {
+            scope?: string;
+        }, options?: RequestOptions) => Promise<AgentMemoryWritten>;
+        /** Answers whether there was a file. */
+        delete: (agent: string, path: string, query?: {
+            scope?: string;
+        }, options?: RequestOptions) => Promise<boolean>;
+    };
     /** The harnesses, as data: claude-code, codex, gemini-cli,
      * claude-agent-sdk, openai-agents-sdk. */
     templates: Readonly<Record<AgentTemplateKey, AgentTemplate>>;