withruntime 0.9.0 → 0.11.0

package/dist/network-cli.js

@@ -1,4 +1,7 @@
-import { chmod, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { RuntimeError } from "./errors.js";
 import { named } from "./cli-name.js";
 import { generateWireGuardKeyPair } from "./wireguard.js";
@@ -67,6 +70,12 @@ export const NETWORK_HELP = {
   upstream-proxy remove                  Connections leave directly again
   A proxy that refuses or cannot be reached fails the connection; nothing goes
   around it. Paid accounts only.
+
+  private on                             Your sandboxes reach each other by name, over TCP:
+                                         <name>.sandbox.internal:<port> or <id>.sandbox.internal:<port>
+  private off                            They stop; open connections between them are cut
+  private status                         On or off
+  Only your own sandboxes answer. Paid accounts only, and free.
 `,
 };
 function usage(product, message) {
@@ -92,15 +101,63 @@ function portNumber(product, text) {
         throw usage(product, "Give a port from 1 to 65535.");
     return value;
 }
+/** A fresh private inode prevents disclosure through permissive files, symlinks
+ * and hard links. Rename publishes complete contents without a readable window. */
+async function privateOutput(path, text) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+        try {
+            await handle.writeFile(text);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return temporary;
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+/** Check and stage before changing a remote peer. If the request or final write
+ * fails, this private draft preserves the newly generated key for recovery. */
+async function prepareOutput(path, privateKey) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw usage("tunnel", "The output must be a regular file, not a directory or symbolic link.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const recovery = await privateOutput(path, `# DRAFT: request or output incomplete. Keep this file for recovery.\n[Interface]\nPrivateKey = ${privateKey ?? "<your private key>"}\n`);
+    return {
+        recovery,
+        async publish(config) {
+            const temporary = await privateOutput(path, config);
+            try {
+                await rename(temporary, path);
+            }
+            finally {
+                await unlink(temporary).catch(() => undefined);
+            }
+            await unlink(recovery);
+        },
+    };
+}
 /** Writes a wg-quick file readable by its owner alone, or prints it. */
-async function deliver(out, config, path, hint, ready = true) {
+async function deliver(out, config, path, hint, ready = true, prepared) {
     if (!config) {
         out.error(hint);
         return;
     }
     if (path) {
-        await writeFile(path, config, { mode: 0o600 });
-        await chmod(path, 0o600);
+        if (!prepared)
+            throw new Error("Tunnel output was not prepared.");
+        await prepared.publish(config);
         out.error(ready
             ? `Wrote ${path}. Bring it up with: sudo wg-quick up ${path.startsWith("/") ? path : `./${path}`}`
             : `Wrote ${path}. ${hint}`);
@@ -276,52 +333,69 @@ export async function networkProductCommand(product, argv, args, out, client) {
             case "peers": {
                 const action = rest[0];
                 if (action === "add" || action === "rotate") {
+                    const argument = need(rest[1], action === "add" ? "the peer's name, such as office" : "a peer id");
                     // The pair is made here unless a key is given: the private key never
                     // leaves this machine, and goes only into the file written below.
                     const given = flag("public-key");
                     const pair = given ? undefined : generateWireGuardKeyPair();
                     const publicKey = given ?? pair.publicKey;
-                    const answer = action === "add"
-                        ? await runtime.tunnel.addPeer({
-                            name: need(rest[1], "the peer's name, such as office"),
-                            publicKey,
-                            routes: args.flags.get("route") ?? [],
-                        })
-                        : await runtime.tunnel.rotatePeer(need(rest[1], "a peer id"), { publicKey });
-                    const configReady = answer.configReady ?? !!answer.config;
-                    const draftHint = "Keep this file: it preserves your private key. Read runtime tunnel get when the gateway is ready, replace PublicKey in [Peer] with gatewayPublicKey, then run wg-quick up.";
-                    // Older servers returned no config while the gateway was starting.
-                    // Preserve the locally generated key in a draft rather than discard it.
-                    const supplied = answer.config ??
-                        [
-                            "# DRAFT: gateway key missing. Keep this file; it preserves your private key.",
-                            "[Interface]",
-                            `PrivateKey = ${pair?.privateKey ?? "<your private key>"}`,
-                            `Address = ${answer.peer.address}/32`,
-                            "",
-                            "[Peer]",
-                            `PublicKey = ${answer.tunnel.gatewayPublicKey ?? "<gatewayPublicKey from runtime tunnel get>"}`,
-                            `Endpoint = ${answer.tunnel.endpoint}`,
-                            `AllowedIPs = ${answer.tunnel.subnet}`,
-                            "PersistentKeepalive = 25",
-                            "",
-                        ].join("\n");
-                    const config = pair
-                        ? supplied.replace(/^PrivateKey = .*$/m, `PrivateKey = ${pair.privateKey}`)
-                        : supplied;
-                    if (out.json) {
-                        print("", {
-                            ...answer,
-                            config,
-                            configReady,
-                            ...(!configReady ? { hint: draftHint } : {}),
-                        });
+                    const path = out.json ? undefined : (flag("out") ?? (pair ? "runtime.conf" : undefined));
+                    const prepared = path ? await prepareOutput(path, pair?.privateKey) : undefined;
+                    try {
+                        const answer = action === "add"
+                            ? await runtime.tunnel.addPeer({
+                                name: argument,
+                                publicKey,
+                                routes: args.flags.get("route") ?? [],
+                            })
+                            : await runtime.tunnel.rotatePeer(argument, { publicKey });
+                        const configReady = answer.configReady ?? !!answer.config;
+                        const draftHint = "Keep this file: it preserves your private key. Read runtime tunnel get when the gateway is ready, replace PublicKey in [Peer] with gatewayPublicKey, then run wg-quick up.";
+                        // Older servers returned no config while the gateway was starting.
+                        // Preserve the locally generated key in a draft rather than discard it.
+                        const supplied = answer.config ??
+                            [
+                                "# DRAFT: gateway key missing. Keep this file; it preserves your private key.",
+                                "[Interface]",
+                                `PrivateKey = ${pair?.privateKey ?? "<your private key>"}`,
+                                `Address = ${answer.peer.address}/32`,
+                                "",
+                                "[Peer]",
+                                `PublicKey = ${answer.tunnel.gatewayPublicKey ?? "<gatewayPublicKey from runtime tunnel get>"}`,
+                                `Endpoint = ${answer.tunnel.endpoint}`,
+                                `AllowedIPs = ${answer.tunnel.subnet}`,
+                                "PersistentKeepalive = 25",
+                                "",
+                            ].join("\n");
+                        const privateKeyRow = /^[ \t]*PrivateKey[ \t]*=[^\r\n]*$/gm;
+                        if (pair && (supplied.match(privateKeyRow)?.length ?? 0) !== 1)
+                            throw new RuntimeError({
+                                code: "invalid_response",
+                                status: 0,
+                                message: "Runtime returned a tunnel configuration without exactly one private-key field.",
+                            });
+                        const config = pair
+                            ? supplied.replace(privateKeyRow, `PrivateKey = ${pair.privateKey}`)
+                            : supplied;
+                        if (out.json) {
+                            print("", {
+                                ...answer,
+                                config,
+                                configReady,
+                                ...(!configReady ? { hint: draftHint } : {}),
+                            });
+                            return 0;
+                        }
+                        if (answer.tunnel.funded === false)
+                            out.error(fundingState(answer.tunnel));
+                        await deliver(out, config, path, configReady ? answer.hint : draftHint, configReady, prepared);
                         return 0;
                     }
-                    if (answer.tunnel.funded === false)
-                        out.error(fundingState(answer.tunnel));
-                    await deliver(out, config, flag("out") ?? (pair ? "runtime.conf" : undefined), configReady ? answer.hint : draftHint, configReady);
-                    return 0;
+                    catch (error) {
+                        if (prepared)
+                            out.error(`The peer request or output did not finish. Your private draft is saved at ${prepared.recovery}; keep it for recovery.`);
+                        throw error;
+                    }
                 }
                 if (action === "rm" || action === "remove") {
                     const after = await runtime.tunnel.removePeer(need(rest[1], "a peer id"));
@@ -332,6 +406,28 @@ export async function networkProductCommand(product, argv, args, out, client) {
             }
         }
     }
+    if (product === "network" && verb === "private") {
+        const describe = (state) => state.enabled
+            ? "On: your sandboxes reach each other at <name>.sandbox.internal:<port> over TCP."
+            : state.allowed
+                ? "Off. Turn it on: runtime network private on"
+                : "Off. Reaching your sandboxes by name is for paid accounts; add credit to turn it on.";
+        switch (rest[0]) {
+            case "on":
+            case "off": {
+                const state = await runtime.network.private.set({ enabled: rest[0] === "on" });
+                print(state.enabled ? describe(state) : "Off. Open connections between your sandboxes are cut.", state);
+                return 0;
+            }
+            case "status":
+            case undefined: {
+                const state = await runtime.network.private.get();
+                print(describe(state), state);
+                return 0;
+            }
+        }
+        throw usage(product, "private takes on, off or status.");
+    }
     if (product === "network") {
         if (verb !== "upstream-proxy")
             throw usage(product, `Unknown network command ${verb}.`);

package/dist/openai-agents/index.js

@@ -531,29 +531,11 @@ export class RuntimeCloudSandboxSession {
     // Workspace archives.
     async persistWorkspace() {
         const root = this.state.manifest.root;
-        const staging = `${STAGING}/${crypto.randomUUID()}.tar`;
-        const skip = root === FILES_HOME ? ["--exclude=./.openai-agents-staging"] : [];
-        try {
-            const packed = await this.#call((sbx) => sbx.exec([
-                "sh",
-                "-c",
-                `mkdir -p -- ${STAGING} && tar ${skip.join(" ")} -C "$1" -cf - . > "$2"`,
-                "sh",
-                root,
-                staging,
-            ], {
-                cwd: "/",
-                timeoutMs: this.state.execTimeoutMs,
-            }));
-            if (packed.exitCode !== 0)
-                throw new SandboxProviderError(`${PROVIDER} could not archive the workspace.`, {
-                    stderr: packed.stderr,
-                });
-            return await this.#call((sbx) => sbx.files.read(staging));
-        }
-        finally {
-            await this.#call((sbx) => sbx.files.remove(staging)).catch(() => undefined);
-        }
+        return this.#call((sbx) => sbx.files.archive(root, {
+            gzip: false,
+            ...(root === FILES_HOME ? { exclude: [".openai-agents-staging"] } : {}),
+            timeoutMs: this.state.execTimeoutMs,
+        }));
     }
     async hydrateWorkspace(data) {
         const bytes = typeof data === "string"
@@ -561,28 +543,10 @@ export class RuntimeCloudSandboxSession {
             : data instanceof Uint8Array
                 ? data
                 : new Uint8Array(data);
-        const staging = `${STAGING}/${crypto.randomUUID()}.tar`;
-        try {
-            await this.#call((sbx) => sbx.files.write(staging, bytes));
-            const unpacked = await this.#call((sbx) => sbx.exec([
-                "sh",
-                "-c",
-                'mkdir -p -- "$1" && tar -C "$1" -xf "$2"',
-                "sh",
-                this.state.manifest.root,
-                staging,
-            ], {
-                cwd: "/",
-                timeoutMs: this.state.execTimeoutMs,
-            }));
-            if (unpacked.exitCode !== 0)
-                throw new SandboxProviderError(`${PROVIDER} could not restore the workspace.`, {
-                    stderr: unpacked.stderr,
-                });
-        }
-        finally {
-            await this.#call((sbx) => sbx.files.remove(staging)).catch(() => undefined);
-        }
+        await this.#call((sbx) => sbx.files.unarchive(this.state.manifest.root, bytes, {
+            gzip: false,
+            timeoutMs: this.state.execTimeoutMs,
+        }));
     }
     // Lifecycle.
     async running() {

package/dist/page.d.ts

@@ -5,7 +5,7 @@ export declare class Page<T> implements AsyncIterable<T> {
     private readonly fetchPage;
     constructor(data: T[], nextCursor: string | null, fetchPage: (cursor: string) => Promise<Page<T>>);
     get hasMore(): boolean;
-    next(): Promise<Page<T> | null>;
+    next(cursor?: string | null): Promise<Page<T> | null>;
     /** Every page, fetched as you go. */
     pages(): AsyncGenerator<Page<T>>;
     [Symbol.asyncIterator](): AsyncGenerator<T>;

package/dist/page.js

@@ -11,8 +11,8 @@ export class Page {
     get hasMore() {
         return this.nextCursor !== null;
     }
-    async next() {
-        return this.nextCursor === null ? null : this.fetchPage(this.nextCursor);
+    async next(cursor = this.nextCursor) {
+        return cursor === null ? null : this.fetchPage(cursor);
     }
     /** Every page, fetched as you go. */
     async *pages() {

package/dist/products/browser.d.ts

@@ -0,0 +1,60 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type SandboxBrowser = {
+    running: false;
+} | {
+    running: true;
+    headless: boolean;
+    /** Chromium's version, e.g. "Chrome/154.0.8037.92". */
+    version: string;
+    /** The browser's DevTools WebSocket with its private token: give it as it
+     * is to Playwright's `chromium.connectOverCDP`, `puppeteer.connect({
+     * browserWSEndpoint })`, browser-use or Stagehand. */
+    cdpUrl: string;
+    /** The DevTools HTTP endpoint; send `headers` with it. */
+    httpUrl: string;
+    headers: Record<string, string>;
+    /** When the token in cdpUrl ends; `get()` returns a fresh one. */
+    expiresAt: string | null;
+    /** headless: false only: the desktop's live view. */
+    streamUrl?: string;
+};
+export type BrowserStartOptions = {
+    /** true (the default): no window. false: on the sandbox's desktop, with a live view. */
+    headless?: boolean;
+    width?: number;
+    height?: number;
+};
+/** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
+ *
+ *   const { cdpUrl } = await sbx.browser.start();
+ *   const browser = await chromium.connectOverCDP(cdpUrl);
+ *
+ * Inside the sandbox the same browser is at http://127.0.0.1:9222. */
+export declare function sandboxBrowser(t: Transport, sandbox: Sandbox): {
+    /** Starts Chromium and returns its CDP address. The first start in a
+     * sandbox installs Chromium, about a minute; this waits for it (up to 10
+     * minutes). Starting a running browser returns it as it is. */
+    start(input?: BrowserStartOptions, options?: RequestOptions): Promise<{
+        running: true;
+        headless: boolean;
+        /** Chromium's version, e.g. "Chrome/154.0.8037.92". */
+        version: string;
+        /** The browser's DevTools WebSocket with its private token: give it as it
+         * is to Playwright's `chromium.connectOverCDP`, `puppeteer.connect({
+         * browserWSEndpoint })`, browser-use or Stagehand. */
+        cdpUrl: string;
+        /** The DevTools HTTP endpoint; send `headers` with it. */
+        httpUrl: string;
+        headers: Record<string, string>;
+        /** When the token in cdpUrl ends; `get()` returns a fresh one. */
+        expiresAt: string | null;
+        /** headless: false only: the desktop's live view. */
+        streamUrl?: string;
+    }>;
+    /** Whether it runs, and a fresh cdpUrl when it does. */
+    get: (options?: RequestOptions) => Promise<SandboxBrowser>;
+    stop: (options?: RequestOptions) => Promise<{
+        stopped: boolean;
+    }>;
+};

package/dist/products/browser.js

@@ -0,0 +1,37 @@
+/** `sbx.browser`: Chromium in the sandbox, for agents that speak CDP.
+ *
+ *   const { cdpUrl } = await sbx.browser.start();
+ *   const browser = await chromium.connectOverCDP(cdpUrl);
+ *
+ * Inside the sandbox the same browser is at http://127.0.0.1:9222. */
+export function sandboxBrowser(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/browser`;
+    return {
+        /** Starts Chromium and returns its CDP address. The first start in a
+         * sandbox installs Chromium, about a minute; this waits for it (up to 10
+         * minutes). Starting a running browser returns it as it is. */
+        async start(input = {}, options) {
+            const deadline = Date.now() + 600_000;
+            for (;;) {
+                try {
+                    return await t.json({
+                        method: "POST",
+                        path: `${base()}:start`,
+                        body: input,
+                        ...options,
+                    });
+                }
+                catch (error) {
+                    const code = error.code;
+                    if ((code !== "browser_installing" && code !== "desktop_installing") ||
+                        Date.now() > deadline)
+                        throw error;
+                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
+                }
+            }
+        },
+        /** Whether it runs, and a fresh cdpUrl when it does. */
+        get: (options) => t.json({ method: "GET", path: base(), ...options }),
+        stop: (options) => t.json({ method: "POST", path: `${base()}:stop`, ...options }),
+    };
+}

package/dist/products/desktop.d.ts

@@ -115,8 +115,8 @@ export declare function sandboxDesktop(t: Transport, sandbox: Sandbox): {
     focus: (windowId: string, options?: RequestOptions) => Promise<{
         ok: true;
     }>;
-    /** Opens `url` in Firefox on the desktop. Right after a sandbox's first
-     * start, Firefox may still be installing; this waits for it. */
+    /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
+     * start, Chromium may still be installing; this waits for it. */
     open(url: string, options?: RequestOptions): Promise<{
         ok: true;
     }>;

package/dist/products/desktop.js

@@ -50,8 +50,8 @@ export function sandboxDesktop(t, sandbox) {
         cursor: (options) => act({ action: "cursor" }, options),
         windows: async (options) => (await act({ action: "windows" }, options)).windows,
         focus: (windowId, options) => act({ action: "focus", windowId }, options),
-        /** Opens `url` in Firefox on the desktop. Right after a sandbox's first
-         * start, Firefox may still be installing; this waits for it. */
+        /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
+         * start, Chromium may still be installing; this waits for it. */
         async open(url, options) {
             const deadline = Date.now() + 600_000;
             for (;;) {

package/dist/products/images.d.ts

@@ -212,7 +212,9 @@ export declare function images(t: Transport): {
     /** Point `tag` of the image's name at this version. */
     tag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
     untag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
-    /** Delete one version (by id, name:tag or name@version) and its tags. */
+    /** Delete one version (by id, name:tag or name@version) and its tags. A
+     * bare name deletes its latest tag's version, or its only version when
+     * it has one and no latest tag; with several, the error names its tags. */
     delete(ref: string, options?: RequestOptions): Promise<Image>;
     /** Credentials for private registries. The secret is sealed on arrival
      * and never returned. */

package/dist/products/images.js

@@ -1,3 +1,4 @@
+import { RuntimeError } from "../errors.js";
 import { Page } from "../page.js";
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
 const PARALLEL_UPLOADS = 4;
@@ -189,11 +190,22 @@ export function images(t) {
                 ...options,
             });
         },
-        /** Delete one version (by id, name:tag or name@version) and its tags. */
+        /** Delete one version (by id, name:tag or name@version) and its tags. A
+         * bare name deletes its latest tag's version, or its only version when
+         * it has one and no latest tag; with several, the error names its tags. */
         async delete(ref, options) {
+            const id = await idOf(ref, options).catch(async (error) => {
+                if (!(error instanceof RuntimeError && error.code === "image_not_found") ||
+                    /[:@]/.test(ref))
+                    throw error;
+                const live = (await list({ name: ref, limit: 100 }, options)).data.filter((image) => image.state !== "deleted" && image.state !== "deleting");
+                if (live.length !== 1)
+                    throw error;
+                return live[0].id;
+            });
             return t.json({
                 method: "POST",
-                path: `/v1/images/${enc(await idOf(ref, options))}:delete`,
+                path: `/v1/images/${enc(id)}:delete`,
                 body: {},
                 ...options,
             });

package/dist/products/index.d.ts

@@ -2,6 +2,7 @@ import type { Transport } from "../transport.js";
 import type { Sandbox } from "../sandbox.js";
 import { images } from "./images.js";
 import { sandboxDesktop } from "./desktop.js";
+import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { addresses, domains, network, ports, tunnel } from "./network-products.js";
@@ -40,11 +41,22 @@ export declare const clientExtensions: {
     tunnel: typeof tunnel;
     network: typeof network;
 };
+/** Canonical CLI product names share the existing factory instance. Account
+ * commands such as secrets, events and billing retain their current names. */
+export declare const clientProductAliases: {
+    readonly image: "images";
+    readonly volume: "volumes";
+    readonly job: "jobs";
+    readonly domain: "domains";
+    readonly port: "ports";
+    readonly address: "addresses";
+};
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;
     previews: typeof sandboxPreviews;
     network: typeof sandboxNetwork;
     desktop: typeof sandboxDesktop;
+    browser: typeof sandboxBrowser;
     mounts: typeof sandboxMounts;
     tailscale: typeof sandboxTailscale;
     metrics: typeof sandboxMetrics;
@@ -52,6 +64,8 @@ export declare const sandboxExtensions: {
 };
 export type ClientExtensions = {
     readonly [K in keyof typeof clientExtensions]: ReturnType<(typeof clientExtensions)[K]>;
+} & {
+    readonly [K in keyof typeof clientProductAliases]: ReturnType<(typeof clientExtensions)[(typeof clientProductAliases)[K]]>;
 };
 export type SandboxExtensions = {
     readonly [K in keyof typeof sandboxExtensions]: ReturnType<(typeof sandboxExtensions)[K]>;

package/dist/products/index.js

@@ -1,5 +1,6 @@
 import { images } from "./images.js";
 import { sandboxDesktop } from "./desktop.js";
+import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { addresses, domains, network, ports, tunnel } from "./network-products.js";
@@ -53,11 +54,22 @@ export const clientExtensions = {
     tunnel,
     network,
 };
+/** Canonical CLI product names share the existing factory instance. Account
+ * commands such as secrets, events and billing retain their current names. */
+export const clientProductAliases = {
+    image: "images",
+    volume: "volumes",
+    job: "jobs",
+    domain: "domains",
+    port: "ports",
+    address: "addresses",
+};
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,
     previews: sandboxPreviews,
     network: sandboxNetwork,
     desktop: sandboxDesktop,
+    browser: sandboxBrowser,
     mounts: sandboxMounts,
     tailscale: sandboxTailscale,
     metrics: sandboxMetrics,

package/dist/products/network-products.d.ts

@@ -195,6 +195,13 @@ export type SetUpstreamProxy = {
  * logs apply. A proxy that refuses or cannot be reached fails the connection
  * (upstream-proxy-failed); nothing goes around it. Paid accounts only. */
 export declare function network(t: Transport): {
+    /** Your sandboxes reaching each other by name (`private-network.ts`). */
+    private: {
+        get: (options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
+        set: (input: {
+            enabled: boolean;
+        }, options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
+    };
     upstreamProxy: {
         /** Send outbound connections through your proxy, replacing any set before. */
         set: (input: SetUpstreamProxy, options?: RequestOptions) => Promise<UpstreamProxy & {

package/dist/products/network-products.js

@@ -1,3 +1,4 @@
+import { privateNetwork } from "./private-network.js";
 const enc = encodeURIComponent;
 /** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
 export function domains(t) {
@@ -91,6 +92,8 @@ export function tunnel(t) {
 export function network(t) {
     const path = "/v1/network/upstream-proxy";
     return {
+        /** Your sandboxes reaching each other by name (`private-network.ts`). */
+        private: privateNetwork(t),
         upstreamProxy: {
             /** Send outbound connections through your proxy, replacing any set before. */
             set: (input, options) => t.json({

package/dist/products/observability.d.ts

@@ -10,6 +10,11 @@ export type MetricPoint = {
     cpuCores: number | null;
     /** The busiest interval between two readings in the bucket. */
     cpuPeakPercent: number | null;
+    /** Measured wall-time percentage ready to run while waiting for CPU; null
+     * without two complete readings of the same run. Older servers omit it. */
+    cpuWaitPercent?: number | null;
+    /** Measured wall-time percentage with a thread waiting for memory. */
+    memoryStallPercent?: number | null;
     /** Average resident memory, bytes. */
     memoryBytes: number;
     memoryPeakBytes: number;
@@ -96,6 +101,45 @@ type List<T> = {
     data: T[];
     nextCursor: string | null;
 };
+export type UsageExportQuery = {
+    since: string;
+    until: string;
+    cursor?: string;
+    limit?: number;
+};
+export type UsageExportRow = {
+    intervalId: string;
+    resourceId: string;
+    name: string | null;
+    kind: string;
+    meter: string;
+    fundedBy: "credit" | "trial";
+    startsAt: string;
+    endsAt: string;
+    settledAt: string;
+    billedMilliseconds: string | null;
+    chargedMicros: string;
+    quotedRates: Array<{
+        component: string;
+        unit: string;
+        rateMicros: string;
+    }>;
+    /** Exact JSON text, preserving integers beyond JavaScript's number range. */
+    measurementsJson: string | null;
+    evidence: "measured" | "partial" | "missing" | null;
+};
+export type UsageExportPage = {
+    since: string;
+    until: string;
+    data: UsageExportRow[];
+    nextCursor: string | null;
+    /** Concatenate pages in order; only the first page includes the header. */
+    csv: string;
+};
+/** Top-level cross-product settled usage, selected by UTC settlement timestamps
+ * in [since, until). Pending holds are excluded. Follow nextCursor using the
+ * same range; each page checks current permissions. Pages are live reads. */
+export declare function usageExport(t: Transport): (query: UsageExportQuery, options?: RequestOptions) => Promise<UsageExportPage>;
 /** `sbx.metrics()`: this sandbox's measured CPU and memory. */
 export declare function sandboxMetrics(t: Transport, sandbox: Sandbox): (options?: {
     range?: MetricRange;