withruntime 0.9.0 → 0.10.0

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/index.d.ts

@@ -40,6 +40,16 @@ 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;
@@ -52,6 +62,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

@@ -53,6 +53,16 @@ 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,

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;

package/dist/products/observability.js

@@ -1,3 +1,9 @@
+/** 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 function usageExport(t) {
+    return (query, options = {}) => t.json({ method: "GET", path: "/v1/usage/export", query, ...options });
+}
 /** `sbx.metrics()`: this sandbox's measured CPU and memory. */
 export function sandboxMetrics(t, sandbox) {
     return (options = {}) => {

package/dist/products/previews.d.ts

@@ -29,6 +29,9 @@ export type CreatePreview = {
     visibility?: "private" | "public";
     /** How long the returned token lasts, 60 s to 7 days (default 1 day). */
     ttlSeconds?: number;
+    /** An absolute ISO private-token deadline, a minute to a week ahead.
+     * Used exactly without TTL; with TTL, the earlier expiry wins. */
+    expiresAt?: string;
     /** The sites that may show it in an iframe, as origins
      * (`https://app.example.com`, `https://*.example.com`, `http://localhost:3000`),
      * up to 16. Any other site's iframe is refused. Omitted: a shared port keeps
@@ -47,8 +50,11 @@ export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
     create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
     /** Every shared port, each private one with a fresh token. */
     list: (options?: RequestOptions) => Promise<Preview[]>;
-    /** One preview, with a fresh token of `ttlSeconds` if it is private. */
-    get: (port: number, ttlSeconds?: number, options?: RequestOptions) => Promise<Preview>;
+    /** One preview, with a fresh private token. `expiresAt` bounds its expiry
+     * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */
+    get: (port: number, ttlSeconds?: number, { expiresAt, ...options }?: RequestOptions & {
+        expiresAt?: string;
+    }) => Promise<Preview>;
     /** Refuses every token issued for this port so far and returns a new one. */
     rotate: (port: number, options?: RequestOptions) => Promise<Preview>;
     /** Stops sharing `port`. Its open connections are closed before this returns. */

package/dist/products/previews.js

@@ -12,11 +12,19 @@ export function sandboxPreviews(t, sandbox) {
         create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
         /** Every shared port, each private one with a fresh token. */
         list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
-        /** One preview, with a fresh token of `ttlSeconds` if it is private. */
-        get: (port, ttlSeconds, options) => t.json({
+        /** One preview, with a fresh private token. `expiresAt` bounds its expiry
+         * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */
+        get: (port, ttlSeconds, { expiresAt, ...options } = {}) => t.json({
             method: "GET",
             path: `${base()}/${port}`,
-            ...(ttlSeconds ? { query: { ttlSeconds } } : {}),
+            ...(ttlSeconds !== undefined || expiresAt !== undefined
+                ? {
+                    query: {
+                        ...(ttlSeconds === undefined ? {} : { ttlSeconds }),
+                        ...(expiresAt === undefined ? {} : { expiresAt }),
+                    },
+                }
+                : {}),
             ...options,
         }),
         /** Refuses every token issued for this port so far and returns a new one. */

package/dist/products/volumes.d.ts

@@ -10,6 +10,16 @@ export type Volume = {
     labels: Record<string, string>;
     region: string;
     sizeMiB: number;
+    /** Fixed at creation; shared disks support concurrent writers. */
+    shared?: boolean;
+    resize?: {
+        id: string;
+        operationId: string;
+        sizeMiB: number;
+        state: "pending" | "running" | "completed" | "failed";
+        generation: number;
+        error: string | null;
+    } | null;
     filesystem: "ext4";
     usedMiB: number | null;
     measuredAt: string | null;
@@ -24,6 +34,8 @@ export type Volume = {
     /** The backup this volume was restored from, if any. */
     restoredFrom: string | null;
     attachments: {
+        id?: string;
+        state?: VolumeAttachment["state"];
         sandboxId: string;
         mode: "rw" | "snapshot";
         path: string;
@@ -34,6 +46,8 @@ export type Volume = {
     readyAt: string | null;
 };
 export type CreateVolume = {
+    /** Available where shared disks are enabled. Fixed at creation. */
+    shared?: boolean;
     /** Required unless restoring: a restore is the backup's size. */
     sizeMiB?: number;
     /** A ready backup to restore into the new volume, on any host in its region. */
@@ -42,6 +56,18 @@ export type CreateVolume = {
     labels?: Record<string, string>;
     region?: string;
 };
+export type VolumeAttachment = {
+    id: string;
+    volumeId: string;
+    sandboxId: string;
+    path: string;
+    mode: "rw";
+    state: "attaching" | "active" | "detaching" | "detached";
+    generation: number;
+    error: string | null;
+    attachedAt: string;
+    changedAt: string;
+};
 export type VolumeBackupState = "pending" | "ready" | "failed" | "deleting" | "deleted";
 /** A point-in-time copy of a volume, kept off its host. */
 export type VolumeBackup = {
@@ -78,6 +104,22 @@ export declare function volumes(t: Transport): {
         limit?: number;
         cursor?: string;
     }, options?: RequestOptions) => Promise<Page<Volume>>;
+    /** Grow a detached ordinary disk; wait up to 10 s for the operation. */
+    resize: (id: string, input: {
+        sizeMiB: number;
+    }, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<Volume>;
+    attach: (id: string, input: {
+        sandboxId: string;
+        path: string;
+    }, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<VolumeAttachment>;
+    detach: (id: string, attachmentId: string, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<VolumeAttachment>;
+    getAttachment: (id: string, attachmentId: string, options?: RequestOptions) => Promise<VolumeAttachment>;
     delete: (id: string, options?: RequestOptions) => Promise<Volume>;
     /** Back a volume up now, off its host, and wait (up to a minute, or
      * `wait` seconds) for it to be ready. */

package/dist/products/volumes.js

@@ -29,6 +29,42 @@ export function volumes(t) {
         create: (input, options) => t.json({ method: "POST", path: "/v1/volumes", body: input, wait: 10, ...options }),
         get,
         list,
+        /** Grow a detached ordinary disk; wait up to 10 s for the operation. */
+        resize: (id, input, options = {}) => {
+            const { wait = 10, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}:resize`,
+                body: input,
+                wait,
+                ...rest,
+            });
+        },
+        attach: (id, input, options = {}) => {
+            const { wait = 10, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}:attach`,
+                body: input,
+                wait,
+                ...rest,
+            });
+        },
+        detach: (id, attachmentId, options = {}) => {
+            const { wait = 10, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}/attachments/${enc(attachmentId)}:detach`,
+                body: {},
+                wait,
+                ...rest,
+            });
+        },
+        getAttachment: (id, attachmentId, options) => t.json({
+            method: "GET",
+            path: `/v1/volumes/${enc(id)}/attachments/${enc(attachmentId)}`,
+            ...options,
+        }),
         delete: (id, options) => t.json({
             method: "POST",
             path: `/v1/volumes/${enc(id)}:delete`,

package/dist/products/watch.js

@@ -12,10 +12,13 @@ export class WatchHandle {
     #stopped = false;
     /** stop() was called: deliver what the watch reports until its end. */
     #stopping = false;
+    #stopPending;
+    #remoteStop;
     /** Callbacks under way. */
     #delivering = 0;
     #exitNotified = false;
     #following;
+    #followingActive = false;
     #abort = new AbortController();
     constructor(t, base, id, path, cursor, options, onEvent) {
         this.t = t;
@@ -34,6 +37,8 @@ export class WatchHandle {
     resume() {
         if (this.#stopped || this.#stopping)
             throw new Error("This watch was stopped");
+        if (this.#followingActive)
+            throw new Error("This watch is already delivering");
         this.#abort = new AbortController();
         this.begin();
     }
@@ -41,12 +46,47 @@ export class WatchHandle {
      * delivered: the watch reports it and ends, and this returns once that has
      * arrived (at most 5 s). Called from inside a callback, it stops at once. */
     async stop(options) {
-        if (this.#stopped || this.#stopping)
+        if (this.#stopped)
+            return;
+        if (this.#stopping) {
+            // Even a callback must observe whether the remote delete succeeded.
+            // It cannot join the drain, which is waiting for that callback to finish.
+            await this.#remoteStop;
+            if (this.#delivering === 0)
+                await this.#stopPending;
+            else
+                this.#finishLocalStop();
             return;
+        }
         this.#stopping = true;
-        await this.t
-            .json({ method: "DELETE", path: `${this.base}/${encodeURIComponent(this.id)}`, ...options })
-            .catch(() => undefined);
+        this.#remoteStop = (async () => await this.t.json({
+            method: "DELETE",
+            path: `${this.base}/${encodeURIComponent(this.id)}`,
+            ...options,
+        }))();
+        const pending = this.#finishStop(this.#remoteStop);
+        this.#stopPending = pending;
+        try {
+            await pending;
+        }
+        finally {
+            if (this.#stopPending === pending) {
+                this.#stopPending = undefined;
+                this.#remoteStop = undefined;
+            }
+        }
+    }
+    async #finishStop(remote) {
+        try {
+            await remote;
+        }
+        catch (error) {
+            // A failed delete does not prove the remote watch stopped. Close local
+            // delivery, but let the caller observe the failure and retry the delete.
+            this.#abort.abort();
+            this.#stopping = false;
+            throw error;
+        }
         // Inside a callback, #following is awaiting the caller: waiting for it
         // here would make that callback await itself.
         if (this.#following && this.#delivering === 0) {
@@ -59,6 +99,9 @@ export class WatchHandle {
             ]);
             clearTimeout(timer);
         }
+        this.#finishLocalStop();
+    }
+    #finishLocalStop() {
         this.#stopped = true;
         this.#abort.abort();
         this.#notifyExit("stopped");
@@ -69,7 +112,7 @@ export class WatchHandle {
         this.#exitNotified = true;
         this.options.onExit?.(reason);
     }
-    async #follow() {
+    async #follow(abort) {
         for (;;) {
             let next = "exit";
             try {
@@ -77,7 +120,7 @@ export class WatchHandle {
                     method: "GET",
                     path: `${this.base}/${encodeURIComponent(this.id)}/events`,
                     query: { cursor: this.cursor, follow: true },
-                    signal: this.#abort.signal,
+                    signal: abort.signal,
                     timeoutMs: 150_000,
                 })) {
                     this.cursor = event.cursor ?? this.cursor;
@@ -102,6 +145,9 @@ export class WatchHandle {
                     else if (event.k === "continue")
                         next = "continue";
                     else if (event.k === "end" || event.k === "paused") {
+                        // A paused callback may resume immediately. Retire this reader
+                        // before invoking it, without letting its finalizer retire the new one.
+                        this.#followingActive = false;
                         if (!this.#stopped)
                             this.#notifyExit(event.k === "paused" ? "paused" : event.reason);
                         return;
@@ -119,7 +165,7 @@ export class WatchHandle {
                 }
             }
             catch (error) {
-                if (this.#stopped || this.#abort.signal.aborted)
+                if (this.#stopped || abort.signal.aborted)
                     return;
                 throw error;
             }
@@ -129,8 +175,15 @@ export class WatchHandle {
     }
     /** @internal */
     begin() {
+        if (this.#followingActive)
+            throw new Error("This watch is already delivering");
         this.#exitNotified = false;
-        this.#following = this.#follow();
+        this.#followingActive = true;
+        const abort = this.#abort;
+        this.#following = this.#follow(abort).finally(() => {
+            if (this.#abort === abort)
+                this.#followingActive = false;
+        });
         // An error surfaces through `done`; nothing is left unhandled meanwhile.
         this.#following.catch(() => undefined);
         return this;

package/dist/proxy.js

@@ -72,7 +72,9 @@ export function routeFor(target, env = processEnv()) {
         parsed = new URL(proxy);
     }
     catch {
-        throw invalidProxy(found.name, found.value, "is not an address");
+        // A malformed address cannot be parsed reliably enough to remove its
+        // credentials. Keep the variable name, never its untrusted value.
+        throw invalidProxy(found.name, "invalid address", "is not an address");
     }
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
         throw invalidProxy(found.name, `${parsed.protocol}//${parsed.host}`, "is not an HTTP proxy");

package/dist/runloop/index.d.ts

@@ -152,7 +152,7 @@ export declare class Devboxes {
             resource_size_request: "CUSTOM_SIZE";
         };
     }>;
-    retrieve(id: string): Promise<{
+    retrieve(id: string, options?: RequestOptions): Promise<{
         id: string;
         name: string | null;
         metadata: {
@@ -232,7 +232,7 @@ export declare class Devboxes {
     list(query?: DevboxListParams, options?: RequestOptions): PagePromise<DevboxView, DevboxViewsCursorIDPage<DevboxView>>;
     list(options?: RequestOptions): PagePromise<DevboxView, DevboxViewsCursorIDPage<DevboxView>>;
     private listPage;
-    suspend(id: string): Promise<{
+    suspend(id: string, options?: RequestOptions): Promise<{
         id: string;
         name: string | null;
         metadata: {
@@ -251,26 +251,7 @@ export declare class Devboxes {
             resource_size_request: "CUSTOM_SIZE";
         };
     }>;
-    resume(id: string): Promise<{
-        id: string;
-        name: string | null;
-        metadata: {
-            [k: string]: string;
-        };
-        status: string;
-        create_time_ms: number;
-        end_time_ms: number | null;
-        capabilities: never[];
-        state_transitions: never[];
-        launch_parameters: {
-            custom_cpu_cores: number;
-            custom_gb_memory: number;
-            custom_disk_size: number;
-            keep_alive_time_seconds: number;
-            resource_size_request: "CUSTOM_SIZE";
-        };
-    }>;
-    shutdown(id: string): Promise<{
+    resume(id: string, options?: RequestOptions): Promise<{
         id: string;
         name: string | null;
         metadata: {
@@ -289,16 +270,19 @@ export declare class Devboxes {
             resource_size_request: "CUSTOM_SIZE";
         };
     }>;
+    shutdown(id: string, params?: {
+        force?: string;
+    } | RequestOptions, options?: RequestOptions): Promise<DevboxView>;
     executeSync(id: string, body: DevboxExecuteParams, options?: RequestOptions): Promise<DevboxExecutionDetailView>;
     executeAsync(id: string, body: DevboxExecuteParams, options?: RequestOptions): Promise<DevboxAsyncExecutionDetailView>;
     executeAndAwaitCompletion(id: string, body: DevboxExecuteParams, options?: RequestOptions): Promise<DevboxAsyncExecutionDetailView>;
     readFileContents(id: string, body: {
         file_path: string;
-    }): Promise<string>;
+    }, options?: RequestOptions): Promise<string>;
     writeFileContents(id: string, body: {
         file_path: string;
         contents: string;
-    }): Promise<DevboxExecutionDetailView>;
+    }, options?: RequestOptions): Promise<DevboxExecutionDetailView>;
     snapshotDisk(id: string, body?: DevboxSnapshotDiskParams, options?: RequestOptions): Promise<DevboxSnapshotView>;
     snapshotDisk(id: string, options?: RequestOptions): Promise<DevboxSnapshotView>;
     snapshotDiskAsync(_id: string, _body?: DevboxSnapshotDiskParams | RequestOptions, _options?: RequestOptions): Promise<never>;
@@ -311,15 +295,17 @@ export declare class Executions {
     constructor(runtime: Runtime);
     executeSync(id: string, body: DevboxExecuteParams, options?: RequestOptions): Promise<DevboxExecutionDetailView>;
     executeAsync(id: string, body: DevboxExecuteParams, options?: RequestOptions): Promise<DevboxAsyncExecutionDetailView>;
-    retrieve(id: string, execution: string): Promise<DevboxAsyncExecutionDetailView>;
+    retrieve(id: string, execution: string, query?: {
+        last_n?: string;
+    } | RequestOptions, options?: RequestOptions): Promise<DevboxAsyncExecutionDetailView>;
     awaitCompleted(id: string, execution: string, options?: RequestOptions): Promise<DevboxAsyncExecutionDetailView>;
     kill(id: string, execution: string, body?: {
         kill_process_group?: boolean | null;
-    }): Promise<DevboxAsyncExecutionDetailView>;
+    } | RequestOptions, options?: RequestOptions): Promise<DevboxAsyncExecutionDetailView>;
     sendStdIn(id: string, execution: string, body?: {
         text?: string | null;
         signal?: "EOF" | "INTERRUPT" | null;
-    }): Promise<{
+    } | RequestOptions, options?: RequestOptions): Promise<{
         devbox_id: string;
         execution_id: string;
         success: boolean;