@promigence/sdk 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/cjs/client.d.ts

@@ -83,6 +83,8 @@ export interface Capacity {
     queued_message?: string;
 }
 export type Outcome = M.Outcome;
+/** `GET /me/outcomes`: what the organization got this month, measured. */
+export type Outcomes = M.Outcomes;
 export interface Percentiles {
     p50: number;
     p95: number;
@@ -631,6 +633,8 @@ export interface HealthResponse {
     build_sha?: string;
     /** Whether the service can start new sandboxes right now. */
     serving?: boolean;
+    /** Where sandboxes run, in plain words (for example "US East Coast"); absent when not said. */
+    location?: string;
     [extra: string]: unknown;
 }
 /** One service's row in `GET /status` (`api`, `sandboxes`): `up`, `degraded` or `down`. */
@@ -1213,6 +1217,10 @@ export interface BackgroundExecRecord {
     stdout_total?: number;
     stderr_total?: number;
     truncated?: boolean;
+    /** Started with `follow`: the newest output is kept, and the handle goes 10 minutes after it ends. */
+    follow?: boolean;
+    /** A range read of a `follow` command: bytes dropped between the asked offset and the first held. */
+    skipped?: number;
     exit?: {
         exit_code: number | null;
         signal: number | null;
@@ -1421,6 +1429,11 @@ export interface PromigenceClientOpts {
      * on `client.notice`.
      */
     onNotice?: (notice: AccountNotice) => void;
+    /**
+     * Called with every answer's timing ([`Timing`]): the round trip this process saw and how long
+     * the answer took on Promigence's side. A CLI uses it to say how far away the caller is.
+     */
+    onTiming?: (timing: Timing) => void;
 }
 /** `GET /sandboxes/:id/network`. */
 export interface SandboxNetwork {
@@ -1857,6 +1870,17 @@ interface RequestOpts {
     /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
     headers?: Record<string, string>;
 }
+/** One answer's timing ([`PromigenceClient.lastTiming`]). */
+export interface Timing {
+    method: string;
+    path: string;
+    /** The round trip as the client saw it, in ms, until the answer's headers arrived. */
+    totalMs: number;
+    /** How long the answer took on Promigence's side, in ms; `null` when the service did not say. */
+    ourMs: number | null;
+}
+/** The `app` span of a `Server-Timing` header (`app;dur=12.35`), in ms; `null` without one. */
+export declare function serverAppMs(header: string | null | undefined): number | null;
 export declare class PromigenceClient {
     #private;
     readonly apiUrl: string;
@@ -1879,9 +1903,16 @@ export declare class PromigenceClient {
         requests: number;
         retries: number;
     };
+    /**
+     * The most recent answer's timing: `totalMs` is the whole round trip as this process saw it,
+     * until the answer's headers arrived; `ourMs` is how long the answer took on Promigence's side
+     * (`null` when the service did not say). `totalMs − ourMs` is the network between you and us.
+     */
+    lastTiming: Timing | null;
     /** The latest account notice any response carried (`Promigence-Notice`), if one did. */
     notice: AccountNotice | undefined;
     private readonly onNotice;
+    private readonly onTiming;
     private readonly noticesSeen;
     constructor(opts?: PromigenceClientOpts);
     /** Read `Promigence-Notice` off a response (its raw value); tell the caller once per distinct notice. */
@@ -1975,6 +2006,13 @@ export declare class PromigenceClient {
     me(opts?: {
         signal?: AbortSignal;
     }): Promise<MeResponse>;
+    /**
+     * `GET /me/outcomes?period=month` — what this organization (with a project's key: that project) got
+     * this month, measured from its own runs and sandboxes. A figure with nothing behind it is `null`.
+     */
+    outcomes(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Outcomes>;
     readonly billing: {
         /** `GET /billing` — plan, card, period, usage, trial, upcoming invoice. */
         usage: () => Promise<BillingUsage>;
@@ -2245,6 +2283,7 @@ export declare class PromigenceClient {
          */
         execBackground: (sandboxId: string, opts: Omit<ExecOpts, "terminal" | "killOnExit" | "signal"> & {
             stdin?: boolean;
+            follow?: boolean;
         }) => Promise<BackgroundExecRecord>;
         /** Background execs of one sandbox (`GET|POST|DELETE /sandboxes/:id/execs/:exec_id…`). */
         execs: {
@@ -2262,10 +2301,14 @@ export declare class PromigenceClient {
             read: (sandboxId: string, execId: string, stream: "stdout" | "stderr", opts?: {
                 offset?: number;
                 len?: number;
+                waitMs?: number;
+                untilOutput?: boolean;
+                signal?: AbortSignal;
             }) => Promise<{
                 data: Uint8Array;
                 offset: number;
                 eof: boolean;
+                skipped: number;
                 record: BackgroundExecRecord;
             }>;
             /**

package/dist/cjs/client.js

@@ -31,6 +31,7 @@ exports.isKeyedCreate = isKeyedCreate;
 exports.checkSandboxId = checkSandboxId;
 exports.checkSpendCap = checkSpendCap;
 exports.newIdempotencyKey = newIdempotencyKey;
+exports.serverAppMs = serverAppMs;
 exports.toCommandResult = toCommandResult;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
@@ -939,6 +940,16 @@ function waitQuery(waitMs) {
         : "";
 }
 const notReleased = (what) => Promise.reject(new core_js_1.NotReleasedError(what));
+function serverAppMs(header) {
+    if (!header)
+        return null;
+    for (const part of header.split(",")) {
+        const m = /^\s*app\s*;(?:.*;)?\s*dur=([0-9]+(?:\.[0-9]+)?)/.exec(part);
+        if (m)
+            return Number(m[1]);
+    }
+    return null;
+}
 function headerOf(res, name) {
     return res instanceof http2_js_1.H2Response ? res.header(name) : res.headers.get(name);
 }
@@ -955,8 +966,10 @@ class PromigenceClient {
     cliErrors;
     caller;
     stats = { requests: 0, retries: 0 };
+    lastTiming = null;
     notice;
     onNotice;
+    onTiming;
     noticesSeen = new Set();
     constructor(opts = {}) {
         (0, trace_js_1.traceEvent)("client:ctor");
@@ -975,6 +988,7 @@ class PromigenceClient {
         this.caller = (0, caller_js_1.resolveCaller)(opts.caller);
         this.userAgent = (0, caller_js_1.userAgentWithCaller)(opts.userAgent ?? `promigence/${core_js_1.VERSION} node/${process.versions.node}`, this.caller);
         this.onNotice = opts.onNotice;
+        this.onTiming = opts.onTiming;
         this.cliErrors = opts.cliErrors === true;
         (0, trace_js_1.traceEvent)("client:ready");
     }
@@ -1080,6 +1094,7 @@ class PromigenceClient {
         for (let attempt = 0;; attempt++) {
             let res;
             this.stats.requests++;
+            const sentAt = performance.now();
             try {
                 if (this.h2) {
                     const init = {
@@ -1109,6 +1124,13 @@ class PromigenceClient {
                     res = await this.fetchImpl(url, init);
                 }
                 (0, trace_js_1.mark)(tr, "res");
+                this.lastTiming = {
+                    method: opts.method,
+                    path: opts.path,
+                    totalMs: performance.now() - sentAt,
+                    ourMs: serverAppMs(headerOf(res, "server-timing")),
+                };
+                this.onTiming?.(this.lastTiming);
             }
             catch (err) {
                 const e = err;
@@ -1426,6 +1448,9 @@ class PromigenceClient {
     me(opts = {}) {
         return this.request({ method: "GET", path: "/me", ...(opts.signal ? { signal: opts.signal } : {}) });
     }
+    outcomes(opts = {}) {
+        return this.request({ method: "GET", path: "/me/outcomes?period=month", ...(opts.signal ? { signal: opts.signal } : {}) });
+    }
     billing = {
         usage: () => this.request({ method: "GET", path: "/billing" }),
         ledger: async (limit = 100) => (await this.billing.ledgerPage({ limit })).items,
@@ -2001,6 +2026,8 @@ class PromigenceClient {
                 body["secrets"] = opts.secrets;
             if (opts.stdin)
                 body["stdin"] = true;
+            if (opts.follow)
+                body["follow"] = true;
             const timeoutMs = commandTimeoutMs(opts.timeoutMs);
             if (timeoutMs !== undefined)
                 body["timeout_ms"] = timeoutMs;
@@ -2033,11 +2060,18 @@ class PromigenceClient {
                 const q = [`stream=${stream}`, `offset=${Math.max(0, Math.floor(opts.offset ?? 0))}`];
                 if (opts.len !== undefined)
                     q.push(`len=${Math.max(0, Math.floor(opts.len))}`);
+                const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
+                if (wait)
+                    q.push(`wait_ms=${wait}`);
+                if (wait && opts.untilOutput)
+                    q.push("until=output");
                 const r = await this.request({
                     method: "GET",
                     path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}?${q.join("&")}`,
+                    ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
+                    ...(opts.signal ? { signal: opts.signal } : {}),
                 });
-                return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), record: r };
+                return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), skipped: r.skipped ?? 0, record: r };
             },
             stdin: (sandboxId, execId, opts = {}) => {
                 if (opts.data === undefined && !opts.eof) {

package/dist/cjs/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.2";
+export declare const VERSION = "0.1.0-beta.4";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";

package/dist/cjs/core.js

@@ -7,7 +7,7 @@ exports.fixBeyondMessage = fixBeyondMessage;
 exports.previewsOff = previewsOff;
 exports.exitForCode = exitForCode;
 const hint_js_1 = require("./hint.js");
-exports.VERSION = "0.1.0-beta.2";
+exports.VERSION = "0.1.0-beta.4";
 exports.DOCS_URL = "https://promigence.ai";
 exports.ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 exports.DEFAULT_API_URL = "https://api.promigence.ai/v1";

package/dist/cjs/models.gen.d.ts

@@ -146,6 +146,11 @@ export interface BackgroundExec {
      * How the command ended; only once `state` is `exited`.
      */
     exit?: BackgroundExecExit | null;
+    /**
+     * Started with `follow`: the newest output is kept, and the handle is freed 10 minutes
+     * after the command ends.
+     */
+    follow?: boolean | null;
     /**
      * Present when the sandbox pauses itself when idle: after this command ends, the idle rule
      * waits up to this many seconds for its result to be read before it pauses the sandbox (a
@@ -166,6 +171,11 @@ export interface BackgroundExec {
     len?: number | null;
     offset?: number | null;
     sandbox_id: string;
+    /**
+     * A `follow` command only: bytes between the `offset` asked for and the first byte still
+     * held, dropped to keep the newest output; `data` then starts at `offset + skipped`.
+     */
+    skipped?: number | null;
     /**
      * Unix nanoseconds.
      */
@@ -1018,6 +1028,14 @@ export interface ExecCreate {
      * Extra environment variables.
      */
     env?: Record<string, string>;
+    /**
+     * With `background`: the command is read as it runs, by a caller that may lose its
+     * connection and come back. The newest `max_output_bytes` of each stream are kept (8 MiB by
+     * default; older bytes are dropped, and a read that asks for them says how many in
+     * `skipped`), and the handle is freed 10 minutes after the command ends, read or not. The
+     * command never stops because a caller went away.
+     */
+    follow?: boolean;
     /**
      * End the sandbox when the command exits (default: the value of `terminal`).
      */
@@ -1904,6 +1922,11 @@ export interface Health {
      * The commit this build came from; empty for a local build.
      */
     build_sha: string;
+    /**
+     * Where sandboxes run, in plain words (for example "US East Coast"). Absent when the service
+     * does not say.
+     */
+    location?: string | null;
     ok: boolean;
     /**
      * Whether new sandboxes can start right now. Answered to a request made with a key; absent
@@ -2325,6 +2348,16 @@ export interface Me {
      */
     key?: KeyRef | null;
     limits: MeLimits;
+    /**
+     * Where sandboxes run, in plain words (for example "US East Coast"), as `GET /v1/health` says
+     * it. Absent when the service does not say.
+     */
+    location?: string | null;
+    /**
+     * The same place as a short code for an icon: `us-east`, `us-west`, `us-midwest`, `eu-west` or
+     * `india`. Only beside `location`; a code you do not know is fine to ignore.
+     */
+    location_code?: string | null;
     /**
      * A notice about a coming change to the trial rules; `null` when there is none.
      */
@@ -2627,6 +2660,67 @@ export interface OtherUsage {
     entries: number;
 }
 export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted";
+/**
+ * `GET /v1/me/outcomes?period=month` — what the organization (with a project's key: that project)
+ * got this period, measured from its own runs and sandboxes. A figure with nothing behind it is
+ * `null`; counts are `0`.
+ */
+export interface Outcomes {
+    /**
+     * Finished runs of two or more sandboxes this period.
+     */
+    batch_runs: number;
+    /**
+     * For those runs: seconds not spent waiting, the sum of their sandboxes' own times minus
+     * the runs' wall time; `null` without such a run.
+     */
+    batch_saved_s?: number | null;
+    /**
+     * For those runs: the sum of their sandboxes' own times divided by the runs' wall time
+     * (how many times faster than one after another); `null` without such a run.
+     */
+    batch_speedup?: number | null;
+    /**
+     * Sandboxes that ended on a failure on our side and were not billed for it.
+     */
+    failures_ours: number;
+    /**
+     * What was given back for those failures, in USD (`0` when they ended before any charge).
+     */
+    failures_ours_usd: number;
+    /**
+     * Failed sandboxes kept to reopen that can still be reopened.
+     */
+    kept_failures: number;
+    /**
+     * Hours this period's sandboxes spent paused, which is not billed; `null` if none paused.
+     */
+    paused_hours?: number | null;
+    /**
+     * What those paused hours would have cost running, in USD; `null` if none paused.
+     */
+    paused_usd?: number | null;
+    /**
+     * `month`: the calendar month so far, UTC.
+     */
+    period: string;
+    /**
+     * The median milliseconds until a sandbox was ready to take work; `null` with no sandbox.
+     */
+    ready_ms_p50?: number | null;
+    /**
+     * Runs started this period.
+     */
+    runs: number;
+    /**
+     * Sandboxes started this period.
+     */
+    sandboxes: number;
+    /**
+     * When the period began (RFC 3339, UTC).
+     */
+    since: string;
+}
 /**
  * What a parked sandbox occupies on disk.
  */
@@ -3956,7 +4050,8 @@ export interface SandboxList {
     next_cursor?: string | null;
     sandboxes: Array<SandboxView>;
     /**
-     * The state filter this list was produced with; empty when none was given.
+     * The state filter this list was produced with; empty when none was given. `queued` keeps
+     * every waiting sandbox; `awaiting_capacity` only those waiting for capacity being added.
      */
     state: Array<string>;
 }
@@ -4256,13 +4351,14 @@ export interface SandboxView {
      */
     billable_seconds?: number | null;
     /**
-     * Once it has ended, what it cost in USD at its run's rates (the run report's `cost`).
-     * Present on `GET /v1/sandboxes/{id}` for an ended sandbox; absent from list rows.
+     * What it has cost in USD at its run's rates: once it has ended, the run report's `cost`; while
+     * it is live, the seconds billed so far (running time only). Present on `GET /v1/sandboxes/{id}`
+     * once it has started; absent from list rows.
      */
     cost_usd?: number | null;
     /**
      * Milliseconds from the start request, after any time queued, to the sandbox being handed
-     * over: it does not include `queued_ms`. `total_ms` is the whole wait.
+     * over: it does not include `queued_ms`. Add `queued_ms` for the whole wait.
      */
     e2e_ms?: number | null;
     /**

package/dist/client.d.ts

@@ -83,6 +83,8 @@ export interface Capacity {
     queued_message?: string;
 }
 export type Outcome = M.Outcome;
+/** `GET /me/outcomes`: what the organization got this month, measured. */
+export type Outcomes = M.Outcomes;
 export interface Percentiles {
     p50: number;
     p95: number;
@@ -631,6 +633,8 @@ export interface HealthResponse {
     build_sha?: string;
     /** Whether the service can start new sandboxes right now. */
     serving?: boolean;
+    /** Where sandboxes run, in plain words (for example "US East Coast"); absent when not said. */
+    location?: string;
     [extra: string]: unknown;
 }
 /** One service's row in `GET /status` (`api`, `sandboxes`): `up`, `degraded` or `down`. */
@@ -1213,6 +1217,10 @@ export interface BackgroundExecRecord {
     stdout_total?: number;
     stderr_total?: number;
     truncated?: boolean;
+    /** Started with `follow`: the newest output is kept, and the handle goes 10 minutes after it ends. */
+    follow?: boolean;
+    /** A range read of a `follow` command: bytes dropped between the asked offset and the first held. */
+    skipped?: number;
     exit?: {
         exit_code: number | null;
         signal: number | null;
@@ -1421,6 +1429,11 @@ export interface PromigenceClientOpts {
      * on `client.notice`.
      */
     onNotice?: (notice: AccountNotice) => void;
+    /**
+     * Called with every answer's timing ([`Timing`]): the round trip this process saw and how long
+     * the answer took on Promigence's side. A CLI uses it to say how far away the caller is.
+     */
+    onTiming?: (timing: Timing) => void;
 }
 /** `GET /sandboxes/:id/network`. */
 export interface SandboxNetwork {
@@ -1857,6 +1870,17 @@ interface RequestOpts {
     /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
     headers?: Record<string, string>;
 }
+/** One answer's timing ([`PromigenceClient.lastTiming`]). */
+export interface Timing {
+    method: string;
+    path: string;
+    /** The round trip as the client saw it, in ms, until the answer's headers arrived. */
+    totalMs: number;
+    /** How long the answer took on Promigence's side, in ms; `null` when the service did not say. */
+    ourMs: number | null;
+}
+/** The `app` span of a `Server-Timing` header (`app;dur=12.35`), in ms; `null` without one. */
+export declare function serverAppMs(header: string | null | undefined): number | null;
 export declare class PromigenceClient {
     #private;
     readonly apiUrl: string;
@@ -1879,9 +1903,16 @@ export declare class PromigenceClient {
         requests: number;
         retries: number;
     };
+    /**
+     * The most recent answer's timing: `totalMs` is the whole round trip as this process saw it,
+     * until the answer's headers arrived; `ourMs` is how long the answer took on Promigence's side
+     * (`null` when the service did not say). `totalMs − ourMs` is the network between you and us.
+     */
+    lastTiming: Timing | null;
     /** The latest account notice any response carried (`Promigence-Notice`), if one did. */
     notice: AccountNotice | undefined;
     private readonly onNotice;
+    private readonly onTiming;
     private readonly noticesSeen;
     constructor(opts?: PromigenceClientOpts);
     /** Read `Promigence-Notice` off a response (its raw value); tell the caller once per distinct notice. */
@@ -1975,6 +2006,13 @@ export declare class PromigenceClient {
     me(opts?: {
         signal?: AbortSignal;
     }): Promise<MeResponse>;
+    /**
+     * `GET /me/outcomes?period=month` — what this organization (with a project's key: that project) got
+     * this month, measured from its own runs and sandboxes. A figure with nothing behind it is `null`.
+     */
+    outcomes(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Outcomes>;
     readonly billing: {
         /** `GET /billing` — plan, card, period, usage, trial, upcoming invoice. */
         usage: () => Promise<BillingUsage>;
@@ -2245,6 +2283,7 @@ export declare class PromigenceClient {
          */
         execBackground: (sandboxId: string, opts: Omit<ExecOpts, "terminal" | "killOnExit" | "signal"> & {
             stdin?: boolean;
+            follow?: boolean;
         }) => Promise<BackgroundExecRecord>;
         /** Background execs of one sandbox (`GET|POST|DELETE /sandboxes/:id/execs/:exec_id…`). */
         execs: {
@@ -2262,10 +2301,14 @@ export declare class PromigenceClient {
             read: (sandboxId: string, execId: string, stream: "stdout" | "stderr", opts?: {
                 offset?: number;
                 len?: number;
+                waitMs?: number;
+                untilOutput?: boolean;
+                signal?: AbortSignal;
             }) => Promise<{
                 data: Uint8Array;
                 offset: number;
                 eof: boolean;
+                skipped: number;
                 record: BackgroundExecRecord;
             }>;
             /**

package/dist/client.js

@@ -904,6 +904,16 @@ function waitQuery(waitMs) {
         : "";
 }
 const notReleased = (what) => Promise.reject(new NotReleasedError(what));
+export function serverAppMs(header) {
+    if (!header)
+        return null;
+    for (const part of header.split(",")) {
+        const m = /^\s*app\s*;(?:.*;)?\s*dur=([0-9]+(?:\.[0-9]+)?)/.exec(part);
+        if (m)
+            return Number(m[1]);
+    }
+    return null;
+}
 function headerOf(res, name) {
     return res instanceof H2Response ? res.header(name) : res.headers.get(name);
 }
@@ -920,8 +930,10 @@ export class PromigenceClient {
     cliErrors;
     caller;
     stats = { requests: 0, retries: 0 };
+    lastTiming = null;
     notice;
     onNotice;
+    onTiming;
     noticesSeen = new Set();
     constructor(opts = {}) {
         traceEvent("client:ctor");
@@ -940,6 +952,7 @@ export class PromigenceClient {
         this.caller = resolveCaller(opts.caller);
         this.userAgent = userAgentWithCaller(opts.userAgent ?? `promigence/${VERSION} node/${process.versions.node}`, this.caller);
         this.onNotice = opts.onNotice;
+        this.onTiming = opts.onTiming;
         this.cliErrors = opts.cliErrors === true;
         traceEvent("client:ready");
     }
@@ -1045,6 +1058,7 @@ export class PromigenceClient {
         for (let attempt = 0;; attempt++) {
             let res;
             this.stats.requests++;
+            const sentAt = performance.now();
             try {
                 if (this.h2) {
                     const init = {
@@ -1074,6 +1088,13 @@ export class PromigenceClient {
                     res = await this.fetchImpl(url, init);
                 }
                 mark(tr, "res");
+                this.lastTiming = {
+                    method: opts.method,
+                    path: opts.path,
+                    totalMs: performance.now() - sentAt,
+                    ourMs: serverAppMs(headerOf(res, "server-timing")),
+                };
+                this.onTiming?.(this.lastTiming);
             }
             catch (err) {
                 const e = err;
@@ -1391,6 +1412,9 @@ export class PromigenceClient {
     me(opts = {}) {
         return this.request({ method: "GET", path: "/me", ...(opts.signal ? { signal: opts.signal } : {}) });
     }
+    outcomes(opts = {}) {
+        return this.request({ method: "GET", path: "/me/outcomes?period=month", ...(opts.signal ? { signal: opts.signal } : {}) });
+    }
     billing = {
         usage: () => this.request({ method: "GET", path: "/billing" }),
         ledger: async (limit = 100) => (await this.billing.ledgerPage({ limit })).items,
@@ -1966,6 +1990,8 @@ export class PromigenceClient {
                 body["secrets"] = opts.secrets;
             if (opts.stdin)
                 body["stdin"] = true;
+            if (opts.follow)
+                body["follow"] = true;
             const timeoutMs = commandTimeoutMs(opts.timeoutMs);
             if (timeoutMs !== undefined)
                 body["timeout_ms"] = timeoutMs;
@@ -1998,11 +2024,18 @@ export class PromigenceClient {
                 const q = [`stream=${stream}`, `offset=${Math.max(0, Math.floor(opts.offset ?? 0))}`];
                 if (opts.len !== undefined)
                     q.push(`len=${Math.max(0, Math.floor(opts.len))}`);
+                const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
+                if (wait)
+                    q.push(`wait_ms=${wait}`);
+                if (wait && opts.untilOutput)
+                    q.push("until=output");
                 const r = await this.request({
                     method: "GET",
                     path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}?${q.join("&")}`,
+                    ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
+                    ...(opts.signal ? { signal: opts.signal } : {}),
                 });
-                return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), record: r };
+                return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), skipped: r.skipped ?? 0, record: r };
             },
             stdin: (sandboxId, execId, opts = {}) => {
                 if (opts.data === undefined && !opts.eof) {

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.2";
+export declare const VERSION = "0.1.0-beta.4";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";

package/dist/core.js

@@ -1,5 +1,5 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.2";
+export const VERSION = "0.1.0-beta.4";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";

package/dist/models.gen.d.ts

@@ -146,6 +146,11 @@ export interface BackgroundExec {
      * How the command ended; only once `state` is `exited`.
      */
     exit?: BackgroundExecExit | null;
+    /**
+     * Started with `follow`: the newest output is kept, and the handle is freed 10 minutes
+     * after the command ends.
+     */
+    follow?: boolean | null;
     /**
      * Present when the sandbox pauses itself when idle: after this command ends, the idle rule
      * waits up to this many seconds for its result to be read before it pauses the sandbox (a
@@ -166,6 +171,11 @@ export interface BackgroundExec {
     len?: number | null;
     offset?: number | null;
     sandbox_id: string;
+    /**
+     * A `follow` command only: bytes between the `offset` asked for and the first byte still
+     * held, dropped to keep the newest output; `data` then starts at `offset + skipped`.
+     */
+    skipped?: number | null;
     /**
      * Unix nanoseconds.
      */
@@ -1018,6 +1028,14 @@ export interface ExecCreate {
      * Extra environment variables.
      */
     env?: Record<string, string>;
+    /**
+     * With `background`: the command is read as it runs, by a caller that may lose its
+     * connection and come back. The newest `max_output_bytes` of each stream are kept (8 MiB by
+     * default; older bytes are dropped, and a read that asks for them says how many in
+     * `skipped`), and the handle is freed 10 minutes after the command ends, read or not. The
+     * command never stops because a caller went away.
+     */
+    follow?: boolean;
     /**
      * End the sandbox when the command exits (default: the value of `terminal`).
      */
@@ -1904,6 +1922,11 @@ export interface Health {
      * The commit this build came from; empty for a local build.
      */
     build_sha: string;
+    /**
+     * Where sandboxes run, in plain words (for example "US East Coast"). Absent when the service
+     * does not say.
+     */
+    location?: string | null;
     ok: boolean;
     /**
      * Whether new sandboxes can start right now. Answered to a request made with a key; absent
@@ -2325,6 +2348,16 @@ export interface Me {
      */
     key?: KeyRef | null;
     limits: MeLimits;
+    /**
+     * Where sandboxes run, in plain words (for example "US East Coast"), as `GET /v1/health` says
+     * it. Absent when the service does not say.
+     */
+    location?: string | null;
+    /**
+     * The same place as a short code for an icon: `us-east`, `us-west`, `us-midwest`, `eu-west` or
+     * `india`. Only beside `location`; a code you do not know is fine to ignore.
+     */
+    location_code?: string | null;
     /**
      * A notice about a coming change to the trial rules; `null` when there is none.
      */
@@ -2627,6 +2660,67 @@ export interface OtherUsage {
     entries: number;
 }
 export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted";
+/**
+ * `GET /v1/me/outcomes?period=month` — what the organization (with a project's key: that project)
+ * got this period, measured from its own runs and sandboxes. A figure with nothing behind it is
+ * `null`; counts are `0`.
+ */
+export interface Outcomes {
+    /**
+     * Finished runs of two or more sandboxes this period.
+     */
+    batch_runs: number;
+    /**
+     * For those runs: seconds not spent waiting, the sum of their sandboxes' own times minus
+     * the runs' wall time; `null` without such a run.
+     */
+    batch_saved_s?: number | null;
+    /**
+     * For those runs: the sum of their sandboxes' own times divided by the runs' wall time
+     * (how many times faster than one after another); `null` without such a run.
+     */
+    batch_speedup?: number | null;
+    /**
+     * Sandboxes that ended on a failure on our side and were not billed for it.
+     */
+    failures_ours: number;
+    /**
+     * What was given back for those failures, in USD (`0` when they ended before any charge).
+     */
+    failures_ours_usd: number;
+    /**
+     * Failed sandboxes kept to reopen that can still be reopened.
+     */
+    kept_failures: number;
+    /**
+     * Hours this period's sandboxes spent paused, which is not billed; `null` if none paused.
+     */
+    paused_hours?: number | null;
+    /**
+     * What those paused hours would have cost running, in USD; `null` if none paused.
+     */
+    paused_usd?: number | null;
+    /**
+     * `month`: the calendar month so far, UTC.
+     */
+    period: string;
+    /**
+     * The median milliseconds until a sandbox was ready to take work; `null` with no sandbox.
+     */
+    ready_ms_p50?: number | null;
+    /**
+     * Runs started this period.
+     */
+    runs: number;
+    /**
+     * Sandboxes started this period.
+     */
+    sandboxes: number;
+    /**
+     * When the period began (RFC 3339, UTC).
+     */
+    since: string;
+}
 /**
  * What a parked sandbox occupies on disk.
  */
@@ -3956,7 +4050,8 @@ export interface SandboxList {
     next_cursor?: string | null;
     sandboxes: Array<SandboxView>;
     /**
-     * The state filter this list was produced with; empty when none was given.
+     * The state filter this list was produced with; empty when none was given. `queued` keeps
+     * every waiting sandbox; `awaiting_capacity` only those waiting for capacity being added.
      */
     state: Array<string>;
 }
@@ -4256,13 +4351,14 @@ export interface SandboxView {
      */
     billable_seconds?: number | null;
     /**
-     * Once it has ended, what it cost in USD at its run's rates (the run report's `cost`).
-     * Present on `GET /v1/sandboxes/{id}` for an ended sandbox; absent from list rows.
+     * What it has cost in USD at its run's rates: once it has ended, the run report's `cost`; while
+     * it is live, the seconds billed so far (running time only). Present on `GET /v1/sandboxes/{id}`
+     * once it has started; absent from list rows.
      */
     cost_usd?: number | null;
     /**
      * Milliseconds from the start request, after any time queued, to the sandbox being handed
-     * over: it does not include `queued_ms`. `total_ms` is the whole wait.
+     * over: it does not include `queued_ms`. Add `queued_ms` for the whole wait.
      */
     e2e_ms?: number | null;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "The fastest sandboxes for AI agents and code. The Promigence TypeScript SDK: snapshot an environment once, fork it as often as you need, run commands in every copy. A simple Sandbox class and the full PromigenceClient, with zero runtime dependencies.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",