@promigence/sdk 0.1.0-beta.15 → 0.1.0-beta.16

package/dist/core.js

@@ -1,7 +1,10 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.15";
+export const VERSION = "0.1.0-beta.16";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
+export function errorsDocsFor(code) {
+    return `${ERRORS_DOCS_URL}#${code}`;
+}
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";
 export const KEY_CONTACT = "support@promigence.ai";
 export const WAIT_TIMEOUT_MS = 100_000;
@@ -10,10 +13,11 @@ export const IMAGE_BUILD_LIST_PRICE = 0.1656;
 export const MAX_OUTPUT_BYTES_DEFAULT = 64 * 1024;
 export const FILE_PUT_CHUNK_BYTES = 16 * 1024 * 1024;
 const PREVIEWS_OFF = /^previews are not enabled on this deployment\.?$/i;
-export const PREVIEWS_UNAVAILABLE = "preview URLs are not available in this beta yet";
+export const PREVIEWS_UNAVAILABLE = "preview URLs are not turned on for this account";
 export function previewsFix(sandboxId = "SID", port = 8000) {
     return `Reach the port over SSH instead: \`promigence sandbox ssh ${hintArg(sandboxId)} -- -N -L ${hintArg(`${port}:localhost:${port}`)}\` ` +
-        `forwards http://localhost:${port} here to port ${port} in the sandbox until Ctrl-C.`;
+        `forwards http://localhost:${port} here to port ${port} in the sandbox until Ctrl-C. ` +
+        "Write to support@promigence.ai to have preview URLs turned on.";
 }
 export async function withPreviewsFix(call, sandboxId, port = "PORT") {
     try {
@@ -52,7 +56,7 @@ export class PromigenceError extends Error {
         this.name = new.target.name;
         this.code = code;
         this.fix = previewsOff ? previewsFix() : fixBeyondMessage(init.message, init.fix);
-        this.docs = init.docs ?? DOCS_URL;
+        this.docs = init.docs ?? errorsDocsFor(code);
         this.exitCode = init.exitCode ?? 1;
         this.cliExit = init.exitCode ?? 1;
         this.guide = `promigence agent-guide --section errors --code ${hintArg(code)}`;
@@ -99,6 +103,21 @@ export class PreviewsUnavailableError extends InvalidArgumentError {
         super(PREVIEWS_UNAVAILABLE, previewsFix(sandboxId, port), "unsupported");
     }
 }
+const SANDBOX_ENDED = /^sandbox (\S+) has ended \(`([a-z_]+)`\)/;
+export function sandboxEndedIn(message) {
+    const m = SANDBOX_ENDED.exec(message.trim());
+    return m ? { sandboxId: m[1], state: m[2] } : undefined;
+}
+export const SANDBOX_ENDED_FIX = "Start a new sandbox: Sandbox.create(). This one's getInfo() says how it ended (`outcome`).";
+export class SandboxEndedError extends InvalidArgumentError {
+    sandboxId;
+    state;
+    constructor(message, sandboxId, state, fix = SANDBOX_ENDED_FIX) {
+        super(message, fix, "usage");
+        this.sandboxId = sandboxId;
+        this.state = state;
+    }
+}
 export class EnvFailedError extends PromigenceError {
     constructor(code, message, fix) {
         super({ code, message, fix, exitCode: 3 });
@@ -216,6 +235,7 @@ export const EXIT_BY_CODE = {
     env_failed: 3, snapshot_rejected: 6, build_failed: 3, snapshot_failed: 4,
     not_connected: 7,
     service_restart: 3,
+    digest_mismatch: 4,
     fork_failed: 3, start_timeout: 3, readiness_failed: 3, verify_too_slow: 3,
     verify_each_failed: 3, toolchain_mismatch: 3, sandbox_unresponsive: 3, oom_within_tier: 3,
     disk_full_within_tier: 3, sandbox_interrupted: 3, integrity_mismatch: 3, egress_unavailable: 3,

package/dist/http2.d.ts

@@ -197,10 +197,18 @@ export declare const __http2Internals: {
         gapUs: number;
         pace: string;
     };
+    /** The offset that turns the thread's stamps into trace times (`clockOffset`), read from the two clocks given. */
+    clockOffset(hr: () => number, now: () => number): number;
     /** Tests: make the transport thread stop answering (it reads nothing more), as a stuck one would. */
     wedgeThreadForTest(): void;
     /** Tests: make the transport thread fail as a crash would. */
     crashThreadForTest(): void;
+    /**
+     * Tests: the transport thread gives no spaced request its turn until `releaseTurnsForTest`. Both go as messages, in order
+     * with the requests and their cancels, so what is sent between them reaches the thread while every spaced request waits.
+     */
+    holdTurnsForTest(): void;
+    releaseTurnsForTest(): void;
     /** The early lookup, for tests: start one with a platform, DNS servers and hosts file of the test's own. */
     early: {
         start(host: string): boolean;

package/dist/http2.js

@@ -1340,6 +1340,12 @@ const THREAD_GRACE_MS = 1_000;
 const THREAD_SWEEP_MS = 250;
 const THREAD_MARKS = 4096;
 const THREAD_PHASES = ["w.got", "w.sent", "w.head", "w.end"];
+function clockOffset(hr = () => Number(process.hrtime.bigint()) / 1e6, now = () => performance.now(), n = 5) {
+    let best = -Infinity;
+    for (let i = 0; i < n; i++)
+        best = Math.max(best, hr() - now());
+    return best;
+}
 class TransportThread {
     origin;
     worker;
@@ -1365,7 +1371,7 @@ class TransportThread {
     posts = 0;
     answered = 0;
     pace = THREAD_DEFAULTS.pace;
-    hrOffset = Number(process.hrtime.bigint()) / 1e6 - performance.now();
+    hrOffset = clockOffset();
     constructor(origin, worker, port, acks) {
         this.origin = origin;
         this.worker = worker;
@@ -2054,6 +2060,9 @@ export const __http2Internals = {
     threadKnobs(env) {
         return threadKnobs(env);
     },
+    clockOffset(hr, now) {
+        return clockOffset(hr, now);
+    },
     wedgeThreadForTest() {
         try {
             transportThread?.port.postMessage({ t: "wedge-for-test" });
@@ -2066,6 +2075,18 @@ export const __http2Internals = {
         }
         catch { }
     },
+    holdTurnsForTest() {
+        try {
+            transportThread?.port.postMessage({ t: "hold-turns-for-test" });
+        }
+        catch { }
+    },
+    releaseTurnsForTest() {
+        try {
+            transportThread?.port.postMessage({ t: "release-turns-for-test" });
+        }
+        catch { }
+    },
     early: {
         start(host) {
             return earlyLookupFor(host.toLowerCase()) !== undefined;

package/dist/models.gen.d.ts

@@ -739,6 +739,11 @@ export interface BuildQueued {
      * True when a verification command was given.
      */
     verified: boolean;
+    /**
+     * What to know before the build ends: with `move_alias`, which snapshot gives up the alias
+     * to it once it is stored.
+     */
+    warnings?: Array<string>;
 }
 /**
  * Builds in the period.
@@ -3074,7 +3079,7 @@ export interface NameCreate {
      */
     name: string;
 }
-export type Network = "none" | "egress";
+export type Network = "none" | "egress" | "allow";
 /**
  * An allowlist: the only hosts the sandbox may reach.
  */
@@ -3528,6 +3533,11 @@ export interface Port {
      * Unix nanoseconds.
      */
     created_unix_ns?: number | null;
+    /**
+     * When the URL stops working on its own, Unix nanoseconds; `null` when it works until it is
+     * revoked or the sandbox ends.
+     */
+    expires_unix_ns?: number | null;
     /**
      * The same publication addressed by name rather than by path. Apps that emit absolute paths
      * need this form.
@@ -3539,8 +3549,8 @@ export interface Port {
     port?: number | null;
     sandbox_id: string;
     /**
-     * The token the URL carries. Pass it to `DELETE /v1/sandboxes/{id}/ports/{token_or_port}` to
-     * revoke this one URL.
+     * The token the URL carries. Pass it in the body of `POST /v1/sandboxes/{id}/ports/revoke`
+     * (`{"token": …}`) to revoke this one URL.
      */
     token?: string | null;
     /**
@@ -3563,6 +3573,25 @@ export interface PortOpen {
      * 1–65535.
      */
     port: number;
+    /**
+     * Seconds until the URL stops working on its own, 1 to 2592000 (30 days). Absent: it works
+     * until it is revoked or the sandbox ends.
+     */
+    ttl_s?: number | null;
+}
+/**
+ * `POST /v1/sandboxes/{id}/ports/revoke`: revoke one URL by its token, or every URL of a port,
+ * with what it names in the body. The token never travels in a URL.
+ */
+export interface PortRevoke {
+    /**
+     * A port: every URL minted for it is revoked. Exactly one of `token` and `port`.
+     */
+    port?: number | null;
+    /**
+     * The token of the one URL to revoke.
+     */
+    token?: string | null;
 }
 /**
  * `POST /v1/billing/portal` — a link to the billing portal.
@@ -3571,7 +3600,7 @@ export interface PortalSession {
     url: string;
 }
 /**
- * `DELETE /v1/sandboxes/{id}/ports/{token_or_port}`.
+ * `POST /v1/sandboxes/{id}/ports/revoke` and `DELETE /v1/sandboxes/{id}/ports/{token_or_port}`.
  */
 export interface PortsRevoked {
     ok: boolean;
@@ -4158,6 +4187,11 @@ export interface ReplayStats {
     success_pct: number;
 }
 export interface Requested {
+    /**
+     * With `network: "allow"`: the only destinations the run's sandboxes may reach, as the run
+     * named them. Absent for the other modes.
+     */
+    allow?: Array<string>;
     allow_partial: boolean;
     count: number;
     /**
@@ -4736,6 +4770,12 @@ export interface Sandbox {
      */
     holdout_passed?: boolean | null;
     holdout_score?: number | null;
+    /**
+     * `PROMIGENCE_INDEX`: this sandbox's place in its run, from 0. A retry, a replay or a
+     * reopened failure keeps its original's. Absent when the run's command set the variable
+     * itself.
+     */
+    index?: number | null;
     /**
      * True when this is a one-time wait: once the waiting sandboxes can start, the rest of the
      * run starts at once too. False otherwise.
@@ -4763,6 +4803,12 @@ export interface Sandbox {
     retry_of?: string | null;
     sandbox_id: string;
     score?: number | null;
+    /**
+     * `PROMIGENCE_SEED`: the number this sandbox's commands were given in that variable. A
+     * retry, a replay or a reopened failure keeps its original's. Absent when the run's command
+     * set the variable itself.
+     */
+    seed?: number | null;
     state: SandboxState;
     t_end?: string | null;
     t_handoff?: string | null;
@@ -5692,6 +5738,11 @@ export interface SessionTrial {
  */
 export interface SnapshotAliasSet {
     alias: string | null;
+    /**
+     * Take the name from the snapshot of the project that has it, which stays, unnamed. Without
+     * it, a name another snapshot has is refused.
+     */
+    move_alias?: boolean;
 }
 /**
  * What an image occupies in storage: `allocated`, which can be less than its size.
@@ -5745,6 +5796,11 @@ export interface SnapshotCreate {
      * A container image, `REF@sha256:<digest>`; a tag is resolved to its digest first.
      */
     image?: string | null;
+    /**
+     * With `alias`: take the name from the snapshot of the project that has it, which stays,
+     * unnamed. Without it, an `alias` another snapshot has is refused and nothing is built.
+     */
+    move_alias?: boolean;
     /**
      * `github:` repositories: a branch, a tag or a commit sha, resolved to the commit it names
      * when the build is accepted. Default: the repository's default branch.
@@ -5815,9 +5871,10 @@ export interface SnapshotDeduped {
     alias_applied?: boolean | null;
     /**
      * The alias that was asked for, when the snapshot did not hold it. The snapshot takes it
-     * (`alias_applied: true`) as a new build would: another snapshot of the project that had it
-     * keeps its row, without a name. A snapshot has one alias, so a name it had before gives
-     * way, and `warnings` says which.
+     * (`alias_applied: true`) as a new build would: a name another snapshot of the project has
+     * is taken only with `move_alias`, and that snapshot keeps its row, without a name. A
+     * snapshot has one alias, so a name it had before gives way. `warnings` says which names
+     * moved.
      */
     alias_requested?: string | null;
     /**

package/dist/sandbox.d.ts

@@ -14,6 +14,8 @@ import { type CommandResult, type CommandRunOpts, type ForkOpts, type OptimizeFo
 import { PromigenceClient, type BackgroundExecRecord, type DirEntry, type DirListOpts, type ExtractResult, type FileInfo, type FileMatch, type Page, type PortRecord, type AutoPauseMode, type SandboxRecord, type SearchOpts, type SecretBinding, type SnapshotBuild, type VerifySpec } from "./client.js";
 import { CommandHandle } from "./handles.js";
 import type { PtyExit, PtySession, PtySize } from "./pty.js";
+/** `setTimeout`'s fix when the longer timeout does not fit under the run's spend cap. */
+export declare const EXTEND_OVER_CAP_FIX: string;
 /**
  * `commands.run` options for a foreground command. The call resolves with the whole result when
  * the command ends; `onStdout` / `onStderr` also receive its output as it is written.
@@ -150,6 +152,8 @@ export interface SandboxCreateOpts extends SandboxOpts {
     start?: string | string[];
     tier?: Tier;
     alias?: string;
+    /** With `alias`: take the name from the snapshot that has it (refused without this). */
+    moveAlias?: boolean;
     /** Name of a stored secret holding the registry credentials. */
     registrySecret?: string;
     /** Bound on the first build of an image (default 15 min). Expiry cancels nothing. */
@@ -196,7 +200,7 @@ export interface SandboxCreateOpts extends SandboxOpts {
  * inputs) was built before, or 202 with a `build_id`. The **body**, not the status, decides: an
  * idempotency replay answers 202 with a document that may already be `verified`.
  */
-export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
+export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "moveAlias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
      * The `POST /snapshots` answer, before any wait: `build_price` (the most it can cost) and
      * whether it was `deduped` or `joined` (nothing new charged). An implicit build costs money, so a caller that prints prices prints this one too.
@@ -312,7 +316,14 @@ export declare class Sandbox {
         resize(pid: number, size: PtySize): Promise<void>;
         kill(pid: number): Promise<boolean>;
     };
-    /** Preview URLs for ports inside the sandbox (`getHost` gives the address alone). */
+    /**
+     * Preview URLs for ports inside the sandbox (`getHost` gives the address alone).
+     *
+     * Anyone holding a preview URL can open it; revoke it any time, and it ends with the sandbox.
+     * If your account's preview URLs aren't on, `expose` throws `PreviewsUnavailableError`; write to
+     * support@promigence.ai to have them turned on, and meanwhile reach the port with
+     * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
+     */
     readonly ports: {
         expose(port: number): Promise<PortRecord>;
         list(): Promise<PortRecord[]>;
@@ -458,13 +469,16 @@ export declare class Sandbox {
     }>;
     isRunning(): Promise<boolean>;
     /**
-     * `PATCH /sandboxes/:id` — extend this sandbox's timeout.
+     * `PATCH /sandboxes/:id` — set this sandbox's timeout, in milliseconds.
      *
-     * The timeout is the sandbox's total lifetime, not "from now", and the difference is billing:
-     * commits *seconds* up front and `billable_seconds <= committed_seconds`, so an extension is a new
-     * commitment that has to fit under the spend cap you set (the run's, or the org default). It throws
-     * `SpendCapError` (409) rather than silently extending — which is the behaviour a spend
-     * cap exists to produce, and the one difference here worth a caller knowing about.
+     * The timeout is the sandbox's total lifetime, counted from its start, not from now:
+     * `setTimeout(600_000)` on a sandbox that has run 2 minutes leaves it 8 more.
+     *
+     * - Raising it commits the added seconds, which has to fit in what is left of the spend cap you set
+     *   (the run's, or the org default): past it, it throws `SpendCapError` (409) rather than silently
+     *   extending.
+     * - Lowering it goes down to what the sandbox has run plus 60 s, and no further
+     *   (`InvalidArgumentError` below that). To stop it now, `kill()` it.
      */
     setTimeout(ms: number): Promise<void>;
     /**
@@ -500,6 +514,10 @@ export declare class Sandbox {
      *
      * Async, because the address is a capability minted on demand rather than
      * a hostname derived from the id. An existing URL for the port is reused, not re-minted.
+     *
+     * If your account's preview URLs aren't on, this throws `PreviewsUnavailableError`; write to
+     * support@promigence.ai to have them turned on, and meanwhile reach the port with
+     * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
      */
     getHost(port: number): Promise<string>;
     /**

package/dist/sandbox.js

@@ -1,9 +1,11 @@
 import { inspect } from "node:util";
-import { ApiError, CommandExitError, EnvFailedError, IMAGE_BUILD_TIMEOUT_MS, InvalidArgumentError, NotFoundError, TimeoutError, UnsupportedError, WAIT_TIMEOUT_MS, withPreviewsFix, } from "./core.js";
+import { ApiError, CommandExitError, EnvFailedError, IMAGE_BUILD_TIMEOUT_MS, InvalidArgumentError, NotFoundError, SpendCapError, TimeoutError, UnsupportedError, WAIT_TIMEOUT_MS, withPreviewsFix, } from "./core.js";
 import { PromigenceClient, LONG_POLL_MS, checkImageRef, checkImageVersioned, checkSandboxId, errorFor, newIdempotencyKey, toCommandResult, isWaiting, } from "./client.js";
 import { CommandHandle } from "./handles.js";
 import { CommandTimeoutError, answerTimedOut } from "./command-errors.js";
 import { hintArg } from "./hint.js";
+export const EXTEND_OVER_CAP_FIX = "Raising the timeout must fit in what is left of the run's spend cap, and this does not: start a new " +
+    "sandbox with the longer `timeoutMs` and a `spendCap` that covers it.";
 const EXEC_TIMEOUT_DEFAULT_MS = 15 * 60_000;
 function textSink(cb) {
     if (!cb)
@@ -37,6 +39,15 @@ export function ptyCommand(opts) {
     parts.push(opts.cmd ?? DEFAULT_PTY_CMD);
     return parts.join(" ");
 }
+function allowList(hosts) {
+    if (!Array.isArray(hosts)) {
+        throw new InvalidArgumentError("allowHosts must be a list of hosts", 'Pass allowHosts: ["github.com"].');
+    }
+    if (!hosts.some((h) => typeof h !== "string" || h.trim() !== "")) {
+        throw new InvalidArgumentError("allowHosts names no host, so the allow-list is empty", 'Name each host the sandbox may reach: allowHosts: ["github.com"]. For no network pass allowInternetAccess: false; to reach anything leave allowHosts out.');
+    }
+    return hosts;
+}
 function permString(mode) {
     const r = (m) => `${m & 4 ? "r" : "-"}${m & 2 ? "w" : "-"}${m & 1 ? "x" : "-"}`;
     return r((mode >> 6) & 7) + r((mode >> 3) & 7) + r(mode & 7);
@@ -89,6 +100,8 @@ export async function imageSnapshot(client, opts, hooks = {}) {
         create.tier = opts.tier;
     if (opts.alias !== undefined)
         create.alias = opts.alias;
+    if (opts.moveAlias)
+        create.moveAlias = true;
     if (opts.registrySecret !== undefined)
         create.registrySecret = opts.registrySecret;
     let build = (await client.snapshots.create(create)) ?? {};
@@ -362,6 +375,9 @@ export class Sandbox {
                 return format === "bytes" ? bytes : new TextDecoder().decode(bytes);
             }),
             write: async (path, data, opts = {}) => {
+                if (typeof path !== "string") {
+                    throw new InvalidArgumentError(`files.write takes one path and its data; got ${Array.isArray(path) ? "an array" : path === null ? "null" : typeof path} as the path`, "Write each file with its own call: for (const f of files) await sandbox.files.write(f.path, f.data).");
+                }
                 let body;
                 if (typeof data === "string" || data instanceof Uint8Array)
                     body = data;
@@ -556,8 +572,8 @@ export class Sandbox {
             start.timeoutMs = opts.timeoutMs;
         if (opts.allowInternetAccess === false)
             start.network = "none";
-        if (opts.allowHosts?.length)
-            start.network = { allow: opts.allowHosts };
+        if (opts.allowHosts !== undefined && opts.allowHosts !== null)
+            start.network = { allow: allowList(opts.allowHosts) };
         if (opts.metadata)
             start.labels = opts.metadata;
         if (opts.secrets?.length)
@@ -695,7 +711,15 @@ export class Sandbox {
         return rec.state === "ready" || rec.state === "running";
     }
     async setTimeout(ms) {
-        await this.#client.sandboxes.patch(this.sandboxId, { timeoutMs: ms });
+        try {
+            await this.#client.sandboxes.patch(this.sandboxId, { timeoutMs: ms });
+        }
+        catch (e) {
+            if (e instanceof SpendCapError && e.code === "cap_exceeded") {
+                Object.defineProperty(e, "fix", { value: EXTEND_OVER_CAP_FIX, enumerable: true, configurable: true });
+            }
+            throw e;
+        }
         this.timeoutMs = ms;
     }
     async setAutoPause(seconds, mode) {

package/dist/transport-worker.js

@@ -290,6 +290,7 @@ function start(init) {
     let rrAny = 0;
     let pumpTimer;
     let pumpSoon;
+    let turnsHeld = false;
     const freeNow = (l, now) => {
         for (let i = 0; i < l.length; i++) {
             const k = (rr + i) % l.length;
@@ -304,6 +305,8 @@ function start(init) {
     const pump = () => {
         pumpTimer = undefined;
         pumpSoon = undefined;
+        if (turnsHeld)
+            return;
         while (waiting.length > 0) {
             const l = live();
             if (l.length === 0) {
@@ -346,7 +349,7 @@ function start(init) {
             rrAny = (rrAny % l.length) + 1;
             return e;
         }
-        if (waiting.length === 0) {
+        if (waiting.length === 0 && !turnsHeld) {
             const now = hrNow();
             const e = freeNow(l, now);
             if (e !== undefined) {
@@ -527,6 +530,12 @@ function start(init) {
         }
         else if (m?.t === "crash-for-test")
             setImmediate(() => { throw new Error("transport thread crash (test)"); });
+        else if (m?.t === "hold-turns-for-test")
+            turnsHeld = true;
+        else if (m?.t === "release-turns-for-test") {
+            turnsHeld = false;
+            pump();
+        }
     });
     void open();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.15",
+  "version": "0.1.0-beta.16",
   "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",