withruntime 0.11.2 → 0.12.0

package/dist/identity.d.ts

@@ -25,3 +25,6 @@ export declare function identityToken(input: {
     lifetimeSeconds?: number;
     signal?: AbortSignal;
 }): Promise<IdentityToken>;
+/** Headers for a call to the website's connect API: this sandbox's identity
+ * token, or none outside a sandbox or when one cannot be had. Never throws. */
+export declare function sandboxIdentityHeaders(): Promise<Record<string, string>>;

package/dist/identity.js

@@ -55,3 +55,30 @@ export async function identityToken(input) {
         });
     return body;
 }
+/** The header and audience the website keys its per-network limits on
+ * (apps/cloud-web/src/lib/limit-key.ts): inside a sandbox, Runtime's own
+ * sign-in calls count against this sandbox, not the address every sandbox on
+ * its host shares. */
+const LIMIT_HEADER = "x-runtime-sandbox-identity";
+const LIMIT_AUDIENCE = "https://withruntime.com/limits";
+let limitToken;
+/** Headers for a call to the website's connect API: this sandbox's identity
+ * token, or none outside a sandbox or when one cannot be had. Never throws. */
+export async function sandboxIdentityHeaders() {
+    if (limitToken && Date.now() < limitToken.until)
+        return { [LIMIT_HEADER]: limitToken.token };
+    if (!(await requestCredentials()))
+        return {};
+    try {
+        const issued = await identityToken({
+            audience: LIMIT_AUDIENCE,
+            signal: AbortSignal.timeout(3_000),
+        });
+        // Renewed a minute before it lapses, so a slow call never carries a dead one.
+        limitToken = { token: issued.token, until: Date.parse(issued.expiresAt) - 60_000 };
+        return { [LIMIT_HEADER]: issued.token };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/images/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/images`: Images alone. Custom images to start sandboxes from.
+ *
+ *   import { images } from "withruntime/images";
+ *   const client = images(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/images.js";
+/** `runtime.images` of a client made with `options`. */
+export declare function images(options?: RuntimeOptions): Runtime["images"];

package/dist/images/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/images`: Images alone. Custom images to start sandboxes from.
+ *
+ *   import { images } from "withruntime/images";
+ *   const client = images(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.images` of a client made with `options`. */
+export function images(options) {
+    return new Runtime(options).images;
+}

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export type { Volume, VolumeBackup, CreateVolume, VolumeAttachment } from "./pro
 export type { CreateJob, Job, JobCompute, JobDefinition, JobLogs, JobRun, JobRunState, JobSchedule, } 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";
 export { verifyWebhook, WebhookVerificationError, type MetricPoint, type MetricRange, type OtelExport, type RuntimeEvent, type SandboxMetrics, type Webhook, type WebhookDelivery, type WebhookEventType, } from "./products/observability.js";
 export { Snapshots, type Snapshot, type SnapshotOptions } from "./snapshots.js";
 export { Transport, VERSION, apiOrigin, type RequestOptions, type Call } from "./transport.js";

package/dist/ips/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/ips`: IPs alone. Dedicated outbound addresses every sandbox of the account sends from.
+ *
+ *   import { ips } from "withruntime/ips";
+ *   const client = ips(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type { EgressAddress, NetworkFunding } from "../products/network-products.js";
+/** `runtime.ips` of a client made with `options`. */
+export declare function ips(options?: RuntimeOptions): Runtime["ips"];

package/dist/ips/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/ips`: IPs alone. Dedicated outbound addresses every sandbox of the account sends from.
+ *
+ *   import { ips } from "withruntime/ips";
+ *   const client = ips(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.ips` of a client made with `options`. */
+export function ips(options) {
+    return new Runtime(options).ips;
+}

package/dist/jobs/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/jobs`: Jobs alone. A command in a fresh sandbox, once or on a schedule.
+ *
+ *   import { jobs } from "withruntime/jobs";
+ *   const client = jobs(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/jobs.js";
+/** `runtime.jobs` of a client made with `options`. */
+export declare function jobs(options?: RuntimeOptions): Runtime["jobs"];

package/dist/jobs/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/jobs`: Jobs alone. A command in a fresh sandbox, once or on a schedule.
+ *
+ *   import { jobs } from "withruntime/jobs";
+ *   const client = jobs(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.jobs` of a client made with `options`. */
+export function jobs(options) {
+    return new Runtime(options).jobs;
+}

package/dist/keys.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { connectionOrigins } from "./credentials.js";
 import { RuntimeError } from "./errors.js";
 import { named } from "./cli-name.js";
+import { sandboxIdentityHeaders } from "./identity.js";
 import { describeRoute, envFetch } from "./proxy.js";
 const KEY = /^rtcloud_([a-f0-9-]{36})_[A-Za-z0-9_-]{43}$/;
 /** How often to ask whether the owner has answered. The website answers
@@ -79,6 +80,7 @@ export async function createKey(request, env, options = {}) {
                 headers: {
                     "content-type": "application/json",
                     ...(key ? { authorization: `Bearer ${key}` } : {}),
+                    ...(await sandboxIdentityHeaders()),
                 },
                 body: JSON.stringify(body),
             });

package/dist/login.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
 import { checkBrowserOrigins, connectionOrigins, connectionStore } from "./credentials.js";
+import { sandboxIdentityHeaders } from "./identity.js";
 import { describeRoute, envFetch } from "./proxy.js";
 class ConnectionError extends Error {
     status;
@@ -80,6 +81,7 @@ function connection(env, options) {
                 headers: {
                     "content-type": "application/json",
                     ...(key ? { authorization: `Bearer ${key}` } : {}),
+                    ...(await sandboxIdentityHeaders()),
                 },
                 body: JSON.stringify(body ?? {}),
             });

package/dist/machine.d.ts

@@ -17,6 +17,10 @@ export type MachineInfo = {
     expiresAt: string;
     endsAt?: string | null;
     start?: unknown;
+    /** True when getOrCreate found the name already held. */
+    reused?: boolean;
+    /** True when the answer repeats an earlier call under the same idempotency key. */
+    replayed?: boolean;
 };
 /** Any other call's request options, as the caller gave them: `timeoutMs` is
  * the call's whole deadline, and 0 turns it off. */
@@ -29,7 +33,6 @@ export declare function machinePage<M, Info>(product: MachineProduct, t: Transpo
     data: Info[];
     nextCursor: string | null;
 }, query: Record<string, unknown>, options?: RequestOptions): Page<M>;
-/** One machine: its record and the verbs every machine product shares. */
 export declare abstract class Machine<Info extends MachineInfo, Settings extends object, Deleted> implements AsyncDisposable {
     #private;
     constructor(product: MachineProduct, transport: Transport, info: Info);
@@ -104,8 +107,9 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * unless autoWake is off); a stopped 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). */
-    setRetention(days: number, options?: RequestOptions): Promise<this>;
+    /** Days a paused sandbox is kept before deletion (1 to 365), or `null` to
+     * keep it while your account has credit. */
+    setRetention(days: number | null, options?: RequestOptions): Promise<this>;
     /** Keeps this sandbox's whole machine (files, memory, running processes) as
      * a snapshot to start new sandboxes from. A running sandbox is paused for
      * the moment it takes, then woken; a paused one stays paused. Past
@@ -116,6 +120,10 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
     restart(options?: RequestOptions & {
         wait?: boolean;
     }): Promise<this>;
+    /** The end of an `await using` block. A sandbox this client created is
+     * deleted, as E2B's block kills it, unless it was created with
+     * `keep: true`; one it found with `get` or `getOrCreate` is stopped, which
+     * keeps its disk. */
     [Symbol.asyncDispose](): Promise<void>;
     toJSON(): Info;
 }
@@ -133,6 +141,7 @@ export type CreateOptions = RequestOptions & {
 export declare abstract class Machines<M extends Machine<Info, object, Deleted>, Info extends MachineInfo, Create extends {
     name?: string;
     getOrCreate?: boolean;
+    keep?: boolean;
 }, Deleted> {
     #private;
     constructor(product: MachineProduct, t: Transport, wrap: (t: Transport, info: Info) => M);

package/dist/machine.js

@@ -40,6 +40,10 @@ export function machinePage(product, t, wrap, body, query, options = {}) {
     }), query, options));
 }
 /** One machine: its record and the verbs every machine product shares. */
+/** Machines `create` made, which the end of an `await using` block deletes
+ * (Marc, 6 October 2026: deleted unless the code passes `keep: true`). One
+ * from `get`, or an existing one `getOrCreate` found, is only stopped. */
+const deleteAtBlockEnd = new WeakSet();
 export class Machine {
     #info;
     #keepAlive;
@@ -227,7 +231,8 @@ export class Machine {
         void tick();
         return end;
     }
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
+    /** Days a paused sandbox is kept before deletion (1 to 365), or `null` to
+     * keep it while your account has credit. */
     async setRetention(days, options = {}) {
         return this.#lifecycle("retention", { ...options, wait: false }, { days });
     }
@@ -374,8 +379,16 @@ export class Machine {
         }));
         return this;
     }
+    /** The end of an `await using` block. A sandbox this client created is
+     * deleted, as E2B's block kills it, unless it was created with
+     * `keep: true`; one it found with `get` or `getOrCreate` is stopped, which
+     * keeps its disk. */
     async [Symbol.asyncDispose]() {
         this.#keepAlive?.();
+        if (deleteAtBlockEnd.has(this)) {
+            await this.delete().catch(() => undefined);
+            return;
+        }
         if (this.#info.state === "stopped")
             return;
         await this.stop({ wait: false }).catch(() => undefined);
@@ -400,7 +413,7 @@ export class Machines {
      * When every slot without credit or the account's quota is taken, it waits for one to
      * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
     async create(input = {}, options = {}) {
-        const { wait, ...body } = input;
+        const { wait, keep, ...body } = input;
         const began = performance.now();
         // Time spent waiting for capacity is the room's, not the deadline's.
         let waited = 0;
@@ -417,6 +430,8 @@ export class Machines {
             },
         });
         const machine = this.#wrap(this.#t, info);
+        if (!keep && !info.reused)
+            deleteAtBlockEnd.add(machine);
         if (wait !== false && info.state !== "running") {
             // One deadline for the whole create: the wait for running gets what the
             // create left of it (1 ms when nothing is left, so it ends as a timeout).
@@ -431,7 +446,9 @@ export class Machines {
             });
             if (machine.state !== "running")
                 throw new RuntimeError({
-                    message: `${this.#product.noun} ${info.id} is ${machine.state}, not running.`,
+                    message: info.replayed
+                        ? `${this.#product.noun} ${info.id} was made by an earlier call with this idempotency key and is ${machine.state} now. It did not fail to start; create again with a new key.`
+                        : `${this.#product.noun} ${info.id} is ${machine.state}, not running.`,
                     code: "start_failed",
                     status: 0,
                     hint: `Read it with runtime.${this.#product.plural}.get(id); stopReason says why.`,

package/dist/mcp.js

@@ -163,7 +163,7 @@ export async function serveMcp(env = process.env, options = {}) {
                     }));
                     await post(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
                     write({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
-                    return text(`Connected as ${outcome.agentName}. Runtime's tools are available now: list the tools again, then start with runtime_sandbox_create.`);
+                    return text(`Connected as ${outcome.agentName}. Runtime's tools are available now: list the tools again, then start with runtime_sandboxes_create.`);
                 }
                 await new Promise((resolve) => setTimeout(resolve, 3000));
             }