withruntime 0.12.0 → 0.14.0

package/dist/products/balancers.d.ts

@@ -0,0 +1,87 @@
+import type { Transport } from "../transport.js";
+import { type ResourceRecord } from "./resources.js";
+/** Private until launch: load balancers and the inbound firewall
+ * (packages/cloud/src/api/products/balancers.ts). A change answers
+ * `applying`; it is `active` once every router serves it, and `waitingOn`
+ * names any router that does not yet. */
+export type AddressState = "applying" | "active" | "failed" | "deleting" | "deleted";
+type Common = ResourceRecord & {
+    name: string | null;
+    labels: Record<string, string>;
+    state: AddressState;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    /** Routers that do not yet serve the newest change. */
+    waitingOn: string[];
+};
+/** A sandbox with the port it serves on, or an App or Function by id. */
+export type BalancerTarget = {
+    id: string;
+    port?: number;
+};
+export type Balancer = Common & {
+    hostname: string;
+    targets: BalancerTarget[];
+};
+export type CreateBalancer = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** Up to 1000, all the organization's own. */
+    targets?: BalancerTarget[];
+};
+export type UpdateBalancer = {
+    name?: string | null;
+    labels?: Record<string, string>;
+    /** Replaces the whole list. */
+    targets?: BalancerTarget[];
+};
+export type FirewallRule = Common & {
+    address: string;
+    effect: "allow" | "deny" | "limit";
+    source?: string;
+    ports?: string;
+    requests?: number;
+    seconds?: number;
+    burst?: number;
+    priority: number;
+};
+export type CreateFirewallRule = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** The load balancer it guards. */
+    address: string;
+    priority?: number;
+} & ({
+    effect: "allow" | "deny";
+    source?: string;
+    ports?: string;
+} | {
+    effect: "limit";
+    requests: number;
+    seconds: number;
+    burst?: number;
+});
+export type UpdateFirewallRule = {
+    name?: string | null;
+    labels?: Record<string, string>;
+};
+export declare function balancers(t: Transport): {
+    base: string;
+    create: (input: CreateBalancer, options?: import("../transport.js").RequestOptions) => Promise<Balancer>;
+    get: (id: string, options?: import("./resources.js").ResourceGetOptions<"active" | "deleted" | "failed" | "deleting" | "applying">) => Promise<Balancer>;
+    list: (query?: import("./resources.js").ResourceListQuery<"active" | "deleted" | "failed" | "deleting" | "applying">, options?: import("../transport.js").RequestOptions) => Promise<import("../page.js").Page<Balancer>>;
+    update: (id: string, input: UpdateBalancer, options?: import("../transport.js").RequestOptions) => Promise<Balancer>;
+    wait: (id: string, target: "active" | "deleted" | "failed" | "deleting" | "applying", options?: import("./resources.js").ResourceWaitOptions) => Promise<Balancer>;
+    delete: (id: string, options?: import("./resources.js").ResourceDeleteOptions) => Promise<Balancer>;
+};
+export declare function firewall(t: Transport): {
+    base: string;
+    create: (input: CreateFirewallRule, options?: import("../transport.js").RequestOptions) => Promise<FirewallRule>;
+    get: (id: string, options?: import("./resources.js").ResourceGetOptions<"active" | "deleted" | "failed" | "deleting" | "applying">) => Promise<FirewallRule>;
+    list: (query?: import("./resources.js").ResourceListQuery<"active" | "deleted" | "failed" | "deleting" | "applying">, options?: import("../transport.js").RequestOptions) => Promise<import("../page.js").Page<FirewallRule>>;
+    update: (id: string, input: UpdateFirewallRule, options?: import("../transport.js").RequestOptions) => Promise<FirewallRule>;
+    wait: (id: string, target: "active" | "deleted" | "failed" | "deleting" | "applying", options?: import("./resources.js").ResourceWaitOptions) => Promise<FirewallRule>;
+    delete: (id: string, options?: import("./resources.js").ResourceDeleteOptions) => Promise<FirewallRule>;
+};
+export {};

package/dist/products/balancers.js

@@ -0,0 +1,8 @@
+import { resource } from "./resources.js";
+const SETTLED = ["failed", "deleted"];
+export function balancers(t) {
+    return resource(t, "balancers", SETTLED);
+}
+export function firewall(t) {
+    return resource(t, "firewall/rules", SETTLED);
+}

package/dist/products/builds.d.ts

@@ -16,16 +16,33 @@ type Resource = {
 export type Build = Resource & {
     repositoryId: string;
     ref: string;
+    /** The branch whose move asked for it, when the caller said. */
+    branch: string | null;
     commit: string | null;
     state: BuildState;
     reason: string | null;
+    /** Milliseconds per step once the runner is done (install, build, mirror,
+     * fork, snapshot, total, ...); null until then. */
+    timings: Record<string, number> | null;
+    /** The saved server an App deploys, once a build of a repository with a
+     * start command succeeded; null otherwise. */
+    outputSnapshotId: string | null;
 };
 export type CreateBuild = {
     repositoryId: string;
     ref: string;
+    /** The same branch and commit is one build; a newer build of the branch
+     * supersedes older ones not yet ended. */
+    branch?: string;
     name?: string;
     labels?: Record<string, string>;
 };
+/** A connected repository's settings changed in place; its id and builds
+ * stay. A field left out stays as it is; a null name clears it. */
+export type ChangeRepository = Partial<Omit<ConnectRepository, "provider" | "name" | "labels">> & {
+    name?: string | null;
+    labels?: Record<string, string>;
+};
 export type ConnectRepository = {
     provider: "github" | "git";
     repository: string;
@@ -37,6 +54,14 @@ export type ConnectRepository = {
     /** Leave out to choose by the lockfile (bun, pnpm, Yarn or npm). */
     installCommand?: string | null;
     buildCommand?: string | null;
+    /** Run after the build with PORT set; the build ends as this server,
+     * answering healthPath with 200 and saved with its memory. */
+    startCommand?: string | null;
+    port?: number;
+    healthPath?: string | null;
+    /** Settings install and build are given. Never a secret: anyone who reads
+     * the repository sees them. */
+    buildEnv?: Record<string, string>;
     name?: string;
     labels?: Record<string, string>;
 };
@@ -49,6 +74,10 @@ export type Repository = Resource & {
     rootDirectory: string;
     installCommand: string | null;
     buildCommand: string | null;
+    startCommand: string | null;
+    port: number;
+    healthPath: string | null;
+    buildEnv: Record<string, string>;
     state: "connected" | "disconnected";
 };
 export type ListBuilds = {
@@ -120,6 +149,7 @@ export declare function builds(t: Transport): {
     repositories: {
         connect: (input: ConnectRepository, options?: RequestOptions) => Promise<Repository>;
         list: (query?: ListRepositories, options?: RequestOptions) => Promise<Page<Repository>>;
+        update: (id: string, change: ChangeRepository, options?: RequestOptions) => Promise<Repository>;
         disconnect: (id: string, options?: RequestOptions) => Promise<Repository>;
     };
 };

package/dist/products/builds.js

@@ -211,6 +211,12 @@ export function builds(t) {
         repositories: {
             connect: (input, options) => t.json({ method: "POST", path: "/v1/repositories", body: input, ...options }),
             list: listRepositories,
+            update: (id, change, options) => t.json({
+                method: "POST",
+                path: `/v1/repositories/${encodeURIComponent(id)}:update`,
+                body: change,
+                ...options,
+            }),
             disconnect: (id, options) => t.json({
                 method: "DELETE",
                 path: `/v1/repositories/${encodeURIComponent(id)}`,

package/dist/products/index.d.ts

@@ -13,6 +13,7 @@ import { audit } from "./audit.js";
 import { sso } from "./sso.js";
 import { switching } from "./switching.js";
 import { limits } from "./limits.js";
+import { keys } from "./api-keys.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
@@ -27,6 +28,7 @@ export declare const clientExtensions: {
     referrals: typeof referrals;
     billing: typeof billing;
     limits: typeof limits;
+    keys: typeof keys;
     switching: typeof switching;
     secrets: typeof secrets;
     webhooks: typeof webhooks;

package/dist/products/index.js

@@ -11,6 +11,7 @@ import { audit } from "./audit.js";
 import { sso } from "./sso.js";
 import { switching } from "./switching.js";
 import { limits } from "./limits.js";
+import { keys } from "./api-keys.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
@@ -40,6 +41,7 @@ export const clientExtensions = {
     referrals,
     billing,
     limits,
+    keys,
     switching,
     secrets,
     webhooks,

package/dist/products/jobs.d.ts

@@ -1,7 +1,7 @@
 import { Page } from "../page.js";
 import type { RequestOptions, Transport } from "../transport.js";
 /** A run's sandbox. Every field has a default; a run is a sandbox of this
- * size, on the included usage first and then on credit at the sandbox rates. */
+ * size, on the free usage first and then on credit at the sandbox rates. */
 export type JobCompute = {
     region: string;
     vcpu: number;
@@ -176,7 +176,7 @@ export declare function jobBody(input: CreateJob): Record<string, unknown>;
  * request id, and says no retry will change it. */
 export declare function switchedOff(product: string): (error: unknown) => never;
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a sandbox, paid for as one: from the included usage first while the run fits the limits without credit, then from credit
+ * schedule. Each run is a sandbox, paid for as one: from the free usage first while the run fits the limits without credit, then from credit
  * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({

package/dist/products/jobs.js

@@ -131,7 +131,7 @@ export function switchedOff(product) {
     };
 }
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a sandbox, paid for as one: from the included usage first while the run fits the limits without credit, then from credit
+ * schedule. Each run is a sandbox, paid for as one: from the free usage first while the run fits the limits without credit, then from credit
  * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({

package/dist/products/observability.d.ts

@@ -35,7 +35,7 @@ export type SandboxMetrics = {
     latest: MetricPoint | null;
     points: MetricPoint[];
 };
-export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "sandbox.files.changed" | "sandbox.out_of_memory" | "sandbox.secret_not_applied" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted" | "egress_secret.created" | "egress_secret.updated" | "egress_secret.deleted" | "upstream_proxy.set" | "upstream_proxy.removed";
+export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "sandbox.files.changed" | "sandbox.out_of_memory" | "sandbox.secret_not_applied" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted" | "volume.recovered" | "egress_secret.created" | "egress_secret.updated" | "egress_secret.deleted" | "upstream_proxy.set" | "upstream_proxy.removed";
 /** An event as /v1/events lists it and a webhook delivers it. */
 export type RuntimeEvent = {
     id: string;
@@ -113,7 +113,7 @@ export type UsageExportRow = {
     name: string | null;
     kind: string;
     meter: string;
-    /** credit, the trial's hours, or the month's included usage. */
+    /** credit, the trial's hours, or the month's free usage. */
     fundedBy: "credit" | "trial" | "allowance";
     startsAt: string;
     endsAt: string;
@@ -128,12 +128,17 @@ export type UsageExportRow = {
     /** Exact JSON text, preserving integers beyond JavaScript's number range. */
     measurementsJson: string | null;
     evidence: "measured" | "partial" | "missing" | null;
+    /** The resource is deleted and every charge it will ever have settled
+     * before finalThrough. A volume's backups bill on until retention ends. */
+    final: boolean;
 };
 export type UsageExportPage = {
     since: string;
     until: string;
     data: UsageExportRow[];
     nextCursor: string | null;
+    /** No row with settledAt before this can still appear or change. */
+    finalThrough: string | null;
     /** Concatenate pages in order; only the first page includes the header. */
     csv: string;
 };

package/dist/products/resources.d.ts

@@ -0,0 +1,54 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** The five verbs every resource product shares (CLOUD.md section 4, "One
+ * shape for every interface"; packages/cloud/src/api/resource-product.ts),
+ * and following one to a state. A product builds its client on these and
+ * adds only its own verbs. */
+export type ResourceRecord = {
+    id: string;
+    state: string;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+};
+export type ResourceListQuery<S extends string = string> = {
+    name?: string;
+    /** Repeated key:value filters; all must match. */
+    label?: readonly string[];
+    /** Defaults to the product's live states. */
+    state?: readonly S[];
+    /** 1 to 100; defaults to 50. */
+    limit?: number;
+    cursor?: string;
+};
+export type ResourceGetOptions<S extends string = string> = RequestOptions & {
+    waitFor?: S;
+    /** Server wait, 1 to 60 seconds; defaults to 30. Check the returned state. */
+    timeoutSeconds?: number;
+};
+export type ResourceWaitOptions = RequestOptions & {
+    /** Whole wait, including retries; defaults to 300000 ms. 0 disables it. */
+    timeoutMs?: number;
+    /** Delay between reads; defaults to 250 ms. */
+    pollMs?: number;
+};
+export type ResourceDeleteOptions = ResourceWaitOptions & {
+    wait?: boolean;
+};
+export declare const enc: typeof encodeURIComponent;
+/** One deadline covers the write, retries and every read. A timed-out delete
+ * can be retried after a process restart with this same key. */
+export declare function following<T>(options: ResourceWaitOptions, work: (request: RequestOptions, pause: () => Promise<void>) => Promise<T>): Promise<T>;
+/** A resource product's client at `/v1/<path>`. A wait ends at its target
+ * or at any of `settled`, which answers with the resource's error. */
+export declare function resource<R extends ResourceRecord, C, U, S extends string = R["state"]>(t: Transport, path: string, settled: readonly S[]): {
+    base: string;
+    /** Defaults belong to the API, so the SDK does not override them. */
+    create: (input: C, options?: RequestOptions) => Promise<R>;
+    get: (id: string, options?: ResourceGetOptions<S>) => Promise<R>;
+    list: (query?: ResourceListQuery<S>, options?: RequestOptions) => Promise<Page<R>>;
+    update: (id: string, input: U, options?: RequestOptions) => Promise<R>;
+    wait: (id: string, target: S, options?: ResourceWaitOptions) => Promise<R>;
+    delete: (id: string, options?: ResourceDeleteOptions) => Promise<R>;
+};

package/dist/products/resources.js

@@ -0,0 +1,122 @@
+import { RuntimeError } from "../errors.js";
+import { Page } from "../page.js";
+import { pause } from "../wait.js";
+export const enc = encodeURIComponent;
+function invalid(field) {
+    return new RuntimeError({
+        code: "invalid_request",
+        status: 0,
+        message: `${field} must be a finite, nonnegative number.`,
+        hint: "Fix the option and call again; nothing was sent.",
+        details: { field },
+    });
+}
+/** One deadline covers the write, retries and every read. A timed-out delete
+ * can be retried after a process restart with this same key. */
+export async function following(options, work) {
+    const { pollMs = 250, timeoutMs = 300_000, signal, ...rest } = options;
+    if (!Number.isFinite(pollMs) || pollMs < 0)
+        throw invalid("pollMs");
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw invalid("timeoutMs");
+    const deadline = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    const timer = timeoutMs > 0 ? setTimeout(() => deadline.abort(), timeoutMs) : undefined;
+    const request = { ...rest, timeoutMs: 0, signal: combined };
+    const poll = () => pause(pollMs, combined);
+    try {
+        combined.throwIfAborted();
+        const result = await work(request, poll);
+        combined.throwIfAborted();
+        return result;
+    }
+    catch (cause) {
+        if (!combined.aborted) {
+            // A read failure still belongs to the write that started this wait.
+            // Keep its key so a caller can recover after losing the reply.
+            if (cause instanceof RuntimeError && rest.idempotencyKey && !cause.idempotencyKey)
+                throw new RuntimeError({
+                    message: cause.message,
+                    code: cause.code,
+                    status: cause.status,
+                    requestId: cause.requestId,
+                    hint: cause.hint,
+                    details: cause.details,
+                    retryAfterMs: cause.retryAfterMs,
+                    idempotencyKey: rest.idempotencyKey,
+                    cause,
+                });
+            throw cause;
+        }
+        throw new RuntimeError({
+            code: "timeout",
+            status: 0,
+            message: "Waiting was cancelled or reached its deadline; the resource may still change.",
+            hint: "Read the resource to resume waiting. Retry a write with the same idempotencyKey.",
+            ...(rest.idempotencyKey === undefined ? {} : { idempotencyKey: rest.idempotencyKey }),
+            cause,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A resource product's client at `/v1/<path>`. A wait ends at its target
+ * or at any of `settled`, which answers with the resource's error. */
+export function resource(t, path, settled) {
+    const base = `/v1/${path}`;
+    const get = (id, options = {}) => {
+        const { waitFor, timeoutSeconds, ...request } = options;
+        return t.json({
+            method: "GET",
+            path: `${base}/${enc(id)}`,
+            query: { waitFor, timeoutSeconds },
+            ...request,
+        });
+    };
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: base,
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    const follow = async (id, target, request, pause, initial) => {
+        let record = initial ?? (await get(id, request));
+        for (;;) {
+            if (record.state === target)
+                return record;
+            if (settled.includes(record.state))
+                throw new RuntimeError({
+                    code: record.error?.code ?? "unexpected_state",
+                    status: 0,
+                    message: record.error?.message ?? `Expected ${target}, but ${id} reached ${record.state}.`,
+                    hint: "Read the resource and inspect its error before starting another change.",
+                    details: { id, state: record.state, target, resource: record },
+                    ...(request.idempotencyKey === undefined
+                        ? {}
+                        : { idempotencyKey: request.idempotencyKey }),
+                });
+            await pause();
+            record = await get(id, request);
+        }
+    };
+    return {
+        base,
+        /** Defaults belong to the API, so the SDK does not override them. */
+        create: (input, options) => t.json({ method: "POST", path: base, body: input, ...options }),
+        get,
+        list,
+        update: (id, input, options) => t.json({ method: "POST", path: `${base}/${enc(id)}:update`, body: input, ...options }),
+        wait: (id, target, options = {}) => following(options, (request, pause) => follow(id, target, request, pause)),
+        delete: (id, options = {}) => {
+            const { wait = false, pollMs, ...request } = options;
+            const remove = (rest) => t.json({ method: "DELETE", path: `${base}/${enc(id)}`, ...rest });
+            if (!wait)
+                return remove(request);
+            return following({ ...request, pollMs, idempotencyKey: request.idempotencyKey ?? crypto.randomUUID() }, async (rest, pause) => follow(id, "deleted", rest, pause, await remove(rest)));
+        },
+    };
+}

package/dist/products/secrets.d.ts

@@ -9,6 +9,17 @@ export type SecretRule = {
     methods?: string[];
     paths: string[];
 };
+/** Which sandboxes get a secret: those whose labels hold every pair of any one
+ * selector in `labels` (including sandboxes created or labelled later), and
+ * those named in `sandboxes`. Any other sandbox of the organization sees no
+ * placeholder, and its requests never carry the value. Absent on a secret:
+ * every sandbox of the organization. */
+export type SecretScope = {
+    /** 1 to 8 selectors of 1 to 8 key/value pairs: `[{ role: "hub" }]`. */
+    labels?: Array<Record<string, string>>;
+    /** 1 to 100 sandbox ids of the organization. */
+    sandboxes?: string[];
+};
 /** A secret your sandboxes use without seeing it. Every sandbox of your
  * organization has an environment variable of the secret's name holding
  * `placeholder`; the egress proxy sets `header` on every HTTPS request to
@@ -22,6 +33,8 @@ export type Secret = {
     header?: string;
     format?: string;
     rules?: SecretRule[];
+    /** Absent: every sandbox of the organization. */
+    only?: SecretScope;
     placeholder: string;
     valueBytes: number;
     createdAt: string;
@@ -45,6 +58,10 @@ export type SetSecret = {
      * Absent: every request to the hosts; replacing a secret without rules
      * clears them. */
     rules?: SecretRule[];
+    /** Only these sandboxes get it. Absent when replacing a secret: the scope it
+     * has stays, so a new value never widens who gets it. `{}`: every sandbox of
+     * the organization again. */
+    only?: SecretScope;
     /** Also keep a copy for scheduled jobs, which a job puts into its run's
      * environment (`jobs.create({ secrets: [...] })`). Unlike the sandboxes'
      * copy, the jobs copy is yours rather than the account's, versioned, and can
@@ -98,6 +115,11 @@ export declare function secrets(t: Transport): {
             enforced: boolean;
         }>>;
     };
+    /** Changes which sandboxes get a secret, without its value: `{}` is every
+     * sandbox of the organization again. */
+    scope: (name: string, only: SecretScope, options?: RequestOptions) => Promise<Secret & {
+        enforced: boolean;
+    }>;
     /** The sandboxes' secrets: names, hosts and placeholders. Never values.
      * `all()` includes the jobs copies. */
     list: (options?: RequestOptions) => Promise<Secret[]>;

package/dist/products/secrets.js

@@ -153,6 +153,14 @@ export function secrets(t) {
          * at once store both; if only the first lands, `SecretPartlyStoredError`
          * says so and the same call again finishes it. */
         set,
+        /** Changes which sandboxes get a secret, without its value: `{}` is every
+         * sandbox of the organization again. */
+        scope: (name, only, options) => t.json({
+            method: "PUT",
+            path: `${path(name)}/sandboxes`,
+            body: only,
+            ...options,
+        }),
         /** The sandboxes' secrets: names, hosts and placeholders. Never values.
          * `all()` includes the jobs copies. */
         list,

package/dist/products/volumes.d.ts

@@ -90,6 +90,9 @@ export type VolumeBackup = {
      * the host never began; back it up again. */
     errorCode?: string | null;
     createdAt: string;
+    /** When its copy off the volume's server began; null while it waits its
+     * turn behind other copies there. */
+    copyStartedAt?: string | null;
     readyAt: string | null;
     expiresAt: string;
 };

package/dist/sandbox.d.ts

@@ -8,6 +8,10 @@ import type { StreamUploadSource } from "./file-source.js";
 import { Machine, type MachineProduct } from "./machine.js";
 /** Sandboxes, as a product of the machine engine (machine.ts). */
 export declare const SANDBOXES: MachineProduct;
+/** How long past its timeoutMs a streamed exec waits for an exit that never came. */
+export declare const EXEC_EXIT_GRACE: {
+    ms: number;
+};
 /** A running (or stopped) sandbox. Every method is one API call or a short
  * sequence of them; `await using sbx = await Sandbox.create()` deletes it at
  * the end of the block, or stops it, keeping its disk, if created with

package/dist/sandbox.js

@@ -87,6 +87,8 @@ function commandBody(command, options) {
         ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     };
 }
+/** How long past its timeoutMs a streamed exec waits for an exit that never came. */
+export const EXEC_EXIT_GRACE = { ms: 120_000 };
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Sandbox extends Machine {
     #t;
@@ -147,8 +149,22 @@ export class Sandbox extends Machine {
             let exit;
             let processId;
             let dropped = false;
+            // A command with a time limit ends by it, the server killing it if need
+            // be; an exit that never comes after (a follow that resumes forever)
+            // ends the wait past the limit and EXEC_EXIT_GRACE.ms, as a timeout,
+            // its process named and sent SIGTERM. The hub's release train waited
+            // 29 min on a 10 min command (15 October 2026).
+            // A timer cleared when the call ends, so none outlives the exec.
+            const deadline = options.timeoutMs === undefined ? undefined : new AbortController();
+            const timer = deadline
+                ? setTimeout(() => deadline.abort(), options.timeoutMs + EXEC_EXIT_GRACE.ms)
+                : undefined;
+            timer?.unref?.();
+            const signal = deadline && options.signal
+                ? AbortSignal.any([options.signal, deadline.signal])
+                : (deadline?.signal ?? options.signal);
             try {
-                for await (const event of this.execStream(command, options)) {
+                for await (const event of this.execStream(command, { ...options, signal })) {
                     if (event.type === "start")
                         processId = event.processId;
                     else if (event.type === "stdout" || event.type === "stderr") {
@@ -162,7 +178,16 @@ export class Sandbox extends Machine {
                 }
             }
             catch (error) {
-                throw await this.#unfinished(error, processId, options.signal);
+                if (!deadline?.signal.aborted || options.signal?.aborted)
+                    throw await this.#unfinished(error, processId, signal);
+                if (processId)
+                    await new Process(this.#t, this.id, { id: processId })
+                        .kill("SIGTERM")
+                        .catch(() => { });
+                exit = { type: "exit", exitCode: null, timedOut: true };
+            }
+            finally {
+                clearTimeout(timer);
             }
             result = {
                 exitCode: exit?.exitCode ?? null,

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.12.0";
+export declare const VERSION = "0.14.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -7,6 +7,9 @@ export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
  * because the hop never leaves the machine: it goes from the program to the
  * guest's own proxy and over the sandbox's private channel to its host. */
 export declare const SANDBOX_BASE_URL = "http://runtime.internal";
+/** How a Runtime secret's placeholder starts, the value a sandbox sees in its
+ * place (packages/cloud-guide/docs/security.md). */
+export declare const PLACEHOLDER = "rtsec_";
 /** Every Runtime sandbox has this file; guest-net.py keeps it current. Tests
  * move it, so the machine running them does not decide what they see. */
 export declare const sandboxMarker: {