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

package/dist/cjs/sandbox.d.ts

@@ -11,9 +11,11 @@
  */
 import { inspect, type InspectOptions } from "node:util";
 import { type CommandResult, type CommandRunOpts, type ForkOpts, type OptimizeFor, type SandboxOpts, type Tier } from "./core.js";
-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 { PromigenceClient, type BackgroundExecRecord, type DirEntry, type DirListOpts, type ExtractResult, type FileInfo, type FileMatch, type Page, type PortExposeOpts, 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.
@@ -285,6 +289,7 @@ export declare class Sandbox {
         /**
          * Run `cmd` and resolve with its result. A non-zero exit throws `CommandExitError`; a command
          * killed at its own `timeoutMs` throws `CommandTimeoutError` (a `CommandExitError` too).
+         * With `throwOnExit: false` both resolve instead, and the result's `timedOut` tells them apart.
          */
         run(cmd: string, opts?: ForegroundRunOpts): Promise<CommandResult>;
         /** Background commands in this sandbox (running and ended, until killed with forget). */
@@ -312,9 +317,20 @@ 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>;
+        /**
+         * Publish `port`: `{ length: "long" }` for a longer, harder-to-guess URL (apps with sensitive
+         * data); omitted, the length this sandbox's project or organization chose (short by default).
+         */
+        expose(port: number, opts?: PortExposeOpts): Promise<PortRecord>;
         list(): Promise<PortRecord[]>;
         /** A token revokes that URL; a port number every URL for it. Returns the revoked tokens. */
         revoke(tokenOrPort: string | number): Promise<string[]>;
@@ -458,13 +474,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, counted from its start, not from now:
+     * `setTimeout(600_000)` on a sandbox that has run 2 minutes leaves it 8 more.
      *
-     * 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.
+     * - 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>;
     /**
@@ -476,8 +495,9 @@ export declare class Sandbox {
      * the window may be. Bring it back with `resume()`, which is the warm path.
      *
      * `mode: "activity"` is for an agent that runs inside the sandbox on its own: it also waits
-     * until nothing inside has used CPU, moved a byte or held a connection open for the window
-     * (`AutoPauseMode`). Omitted, the mode is left as it is (`"requests"` unless set).
+     * until, for the whole window, the sandbox has used under 5% of one core, sent and received no
+     * network byte and held no connection out open; disk writes do not count (`AutoPauseMode`).
+     * Omitted, the mode is left as it is (`"requests"` unless set).
      */
     setAutoPause(seconds: number, mode?: AutoPauseMode): Promise<void>;
     /** The idle rule in force: seconds before it pauses itself, `0` when it never does. */
@@ -499,7 +519,12 @@ export declare class Sandbox {
      * full `url` with its scheme.
      *
      * 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.
+     * a hostname derived from the id. An existing URL for the port is reused, not re-minted; a new
+     * one has the length this sandbox's project or organization chose (short by default).
+     *
+     * 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/cjs/sandbox.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Sandbox = exports.DEFAULT_SNAPSHOT = exports.DEFAULT_PTY_CMD = void 0;
+exports.Sandbox = exports.DEFAULT_SNAPSHOT = exports.DEFAULT_PTY_CMD = exports.EXTEND_OVER_CAP_FIX = void 0;
 exports.shellQuote = shellQuote;
 exports.ptyCommand = ptyCommand;
 exports.toEntryInfo = toEntryInfo;
@@ -14,6 +14,8 @@ const client_js_1 = require("./client.js");
 const handles_js_1 = require("./handles.js");
 const command_errors_js_1 = require("./command-errors.js");
 const hint_js_1 = require("./hint.js");
+exports.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)
@@ -47,6 +49,15 @@ function ptyCommand(opts) {
     parts.push(opts.cmd ?? exports.DEFAULT_PTY_CMD);
     return parts.join(" ");
 }
+function allowList(hosts) {
+    if (!Array.isArray(hosts)) {
+        throw new core_js_1.InvalidArgumentError("allowHosts must be a list of hosts", 'Pass allowHosts: ["github.com"].');
+    }
+    if (!hosts.some((h) => typeof h !== "string" || h.trim() !== "")) {
+        throw new core_js_1.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);
@@ -99,6 +110,8 @@ 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)) ?? {};
@@ -358,7 +371,7 @@ class Sandbox {
             },
         };
         this.ports = {
-            expose: (port) => this.#client.sandboxes.ports.expose(this.sandboxId, port),
+            expose: (port, opts) => this.#client.sandboxes.ports.expose(this.sandboxId, port, opts),
             list: () => this.#client.sandboxes.ports.list(this.sandboxId),
             revoke: async (tokenOrPort) => (await this.#client.sandboxes.ports.revoke(this.sandboxId, tokenOrPort)).revoked,
         };
@@ -372,6 +385,9 @@ class Sandbox {
                 return format === "bytes" ? bytes : new TextDecoder().decode(bytes);
             }),
             write: async (path, data, opts = {}) => {
+                if (typeof path !== "string") {
+                    throw new core_js_1.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;
@@ -566,8 +582,8 @@ 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)
@@ -705,7 +721,15 @@ 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 core_js_1.SpendCapError && e.code === "cap_exceeded") {
+                Object.defineProperty(e, "fix", { value: exports.EXTEND_OVER_CAP_FIX, enumerable: true, configurable: true });
+            }
+            throw e;
+        }
         this.timeoutMs = ms;
     }
     async setAutoPause(seconds, mode) {

package/dist/cjs/transport-worker.js

@@ -292,6 +292,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;
@@ -306,6 +307,8 @@ function start(init) {
     const pump = () => {
         pumpTimer = undefined;
         pumpSoon = undefined;
+        if (turnsHeld)
+            return;
         while (waiting.length > 0) {
             const l = live();
             if (l.length === 0) {
@@ -348,7 +351,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) {
@@ -529,6 +532,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/dist/client.d.ts

@@ -2,6 +2,7 @@
 import { inspect, type InspectOptions } from "node:util";
 import { PromigenceError, type CommandResult, type NetworkMode, type OptimizeFor, type Tier } from "./core.js";
 import { type Bundle } from "./bundle.js";
+import { type CredentialStore } from "./credstore.js";
 import { type PtyExit, type PtySession } from "./pty.js";
 import { type SshTunnel } from "./ssh.js";
 import type * as M from "./models.gen.js";
@@ -177,6 +178,8 @@ export interface SandboxRef extends QueuedInfo {
 }
 /** How a grader's result is read. */
 export type ScoreMode = M.ScoreMode;
+/** Which of a run's sandboxes are kept to reopen where they ended (`RunStartOpts.capture`). */
+export type CaptureMode = M.CaptureMode;
 /**
  * Score the agent's work after the episode, in a clean copy of the snapshot with the agent's
  * changes applied. `holdout_cmd` is your own second test set; the report carries the gap
@@ -280,6 +283,10 @@ export interface ReportSandbox extends QueuedInfo {
     sandbox_id: string;
     state: SandboxState;
     attempt?: number;
+    /** `PROMIGENCE_INDEX`: its place in the run, from 0. Absent when the run's command set it itself. */
+    index?: number;
+    /** `PROMIGENCE_SEED`: the number its commands were given. Absent when the run's command set it itself. */
+    seed?: number;
     queued_ms?: number;
     ready_ms?: number;
     e2e_ms?: number;
@@ -319,11 +326,16 @@ export interface RunReport {
     snapshot_id?: string;
     alias?: string;
     labels?: Record<string, string>;
+    /**
+     * What the run asked for. `network` is `"allow"` for a run behind an allowlist, whose hosts are
+     * `allow` (a service before it said `"egress"` for one).
+     */
     requested?: {
         count: number;
         timeout_ms: number;
         verify_each: boolean;
-        network: NetworkMode;
+        network: NetworkMode | "allow";
+        allow?: string[];
         allow_partial: boolean;
         secrets?: string[];
         grade?: GradeSpec;
@@ -386,6 +398,12 @@ export interface SecretRecord {
     raw?: "allowed" | "refused";
     /** Whether the value is kept out of the bound hosts' answers (present when `hosts` is). */
     scan_responses?: boolean;
+    /**
+     * On `secrets.set` only: things to know about the value just stored, one `code: sentence` each;
+     * absent when there are none. `api_key_value`: the value holds an API key of this service, which
+     * any command in a sandbox given this secret can use.
+     */
+    warnings?: string[];
 }
 /**
  * `secrets.set` options: bind the secret to hosts. Requests a sandbox sends to the host's address
@@ -437,13 +455,19 @@ export interface SnapshotBuild {
     repo?: string;
     commit?: string;
     verification?: Record<string, unknown>;
-    /** A rejected build names the guard and the measured value; nothing was stored. */
+    /**
+     * A rejected build names the guard and the measured value; nothing was stored. `log_tail` is
+     * your build's own output: for a step of yours that failed (its start command, a setup step, its
+     * verify), that step's last lines. `fix`, when present, is what to change.
+     */
     error?: {
         code?: string;
         guard?: string;
         message?: string;
         values?: number[];
         stored?: boolean;
+        log_tail?: string[];
+        fix?: string;
     } | null;
     /** Set when an identical build already existed. */
     deduped?: boolean;
@@ -729,8 +753,25 @@ export interface OrgRecord {
     created_at: string;
     /** Days command output is kept after a sandbox ends; `null` = the default, 7. */
     output_retention_days?: number | null;
-    /** Keep a failed sandbox to reopen where it broke, when a run does not say; absent or `null` = the default. */
+    /**
+     * This organization's choice: keep a failed sandbox to reopen where it broke, when a run does not say (`capture`);
+     * absent or `null` = not chosen, so the default applies: not kept unless the organization or project chose to keep
+     * them. What applies is `failure_captures_effective`.
+     */
     failure_captures?: boolean | null;
+    /** The length of new preview URLs when a request does not say; absent or `null` = the default, short. */
+    preview_link_length?: PreviewLinkLength | null;
+    /** What applies to a failed run that does not say: kept or not, and whose choice decided it. */
+    failure_captures_effective?: CapturesEffective;
+}
+/**
+ * What applies to a failed run's sandboxes when the run does not say (`capture`): `kept`, and `from`, whose choice
+ * decided it: `project`, `org`, or `default` (neither chose: not kept unless the organization or project chose to
+ * keep them). A run's own `capture` is followed either way.
+ */
+export interface CapturesEffective {
+    kept: boolean;
+    from: "project" | "org" | "default" | (string & {});
 }
 export interface ProjectRecord {
     project_id: string;
@@ -742,8 +783,16 @@ export interface ProjectRecord {
     monthly_cap_usd?: number | null;
     /** Days this project's command output is kept after a sandbox ends; `null` = the organization's. */
     output_retention_days?: number | null;
-    /** Keep this project's failed sandboxes to reopen, when a run does not say; absent or `null` = the organization's. */
+    /**
+     * This project's choice: keep its failed sandboxes to reopen, when a run does not say (`capture`); absent or `null` =
+     * the organization's choice, and where neither chose, the default: not kept unless the organization or project
+     * chose to keep them. What applies is `failure_captures_effective`.
+     */
     failure_captures?: boolean | null;
+    /** The length of this project's new preview URLs when a request does not say; absent or `null` = the organization's. */
+    preview_link_length?: PreviewLinkLength | null;
+    /** What applies to its failed runs that do not say: kept or not, and whose choice decided it. */
+    failure_captures_effective?: CapturesEffective;
     created_at: string;
 }
 /** The longest command output may be kept after a sandbox ends, in days. */
@@ -1153,8 +1202,9 @@ export interface SandboxPatchResponse {
 /**
  * What the idle rule counts as idle. `"requests"` (the default): nobody has called the sandbox
  * for the window and no command, terminal or SSH session is open. `"activity"`: all of that, and
- * for the whole window nothing inside used CPU or sent or received a byte, and no network
- * connection to the outside is open — for an agent that runs inside the sandbox on its own.
+ * for the whole window the sandbox used under 5% of one core, sent and received no network byte
+ * (disk writes do not count), and no network connection to the outside is open — for an agent
+ * that runs inside the sandbox on its own.
  */
 export type AutoPauseMode = M.AutoPauseMode;
 /** `POST /snapshots/:id/verify` — re-run the recorded `verify` in a fresh fork. */
@@ -1366,12 +1416,33 @@ export interface SshRevoked {
 export interface PortRecord {
     sandbox_id: string;
     port: number;
-    /** 256-bit capability; anyone with the URL reaches the port. */
+    /** The URL's own name: anyone with the URL reaches the port. Pass it to `revoke` to take this one URL down. */
     token: string;
     url: string;
     /** The same token as a DNS label, for a wildcard-DNS deployment (`<label>.<suffix>`). */
     host_url_label?: string;
     created_unix_ns?: number;
+    /** When the URL stops working on its own (`ttl_s`); `null` for one that works until revoked. */
+    expires_unix_ns?: number | null;
+    /**
+     * `"short"` (`https://brave-otter-48213.<domain>/`, the default) or `"long"` (a longer,
+     * harder-to-guess URL, for apps with sensitive data).
+     */
+    length?: PreviewLinkLength;
+}
+/**
+ * How long a preview URL is: `"short"` (the default, `https://brave-otter-48213.<domain>/`) or
+ * `"long"` (a longer, harder-to-guess URL, for apps with sensitive data). Custom domains are
+ * coming soon.
+ */
+export type PreviewLinkLength = "short" | "long";
+/** Options of `ports.expose`. */
+export interface PortExposeOpts {
+    /**
+     * `"short"` or `"long"`. Omitted: the length the sandbox's project chose, else its
+     * organization's, else short.
+     */
+    length?: PreviewLinkLength;
 }
 /** A key named without its secret (`/me`'s `key`, the key lists). */
 export interface KeyRef {
@@ -1403,8 +1474,31 @@ export interface MeResponse {
         max_concurrency?: number;
         max_session_s?: number | null;
         max_sandbox_vcpus?: number | null;
+        /** Everything stored together, in GB: snapshots, paused sandboxes and saved failures; `null` for no limit. */
+        max_storage_gb?: number | null;
+        /**
+         * The storage saved failures may use, in GB: when a new one would pass it, the oldest are removed to make room;
+         * `null` for no limit.
+         */
+        max_capture_storage_gb?: number | null;
+        /** Snapshots that may be kept; `null` for no limit. */
+        max_snapshots?: number | null;
+        /** Paused sandboxes that may be kept; `null` for no limit. */
+        max_paused?: number | null;
         [extra: string]: number | null | undefined;
     };
+    /**
+     * What the organisation stores now, in bytes (a GB of `limits` is 2^30 bytes): everything together (`used_bytes`,
+     * against `limits.max_storage_gb`) and its saved failures (`captures_bytes`, against
+     * `limits.max_capture_storage_gb`), with the counts. Absent from a server before it.
+     */
+    storage?: {
+        used_bytes: number;
+        captures_bytes: number;
+        snapshots: number;
+        paused: number;
+        captures: number;
+    } | null;
     /**
      * Sandboxes holding capacity now (queued, starting, ready or running; paused ones hold none)
      * against the limit.
@@ -1518,6 +1612,12 @@ export interface PromigenceClientOpts {
      */
     onTiming?: (timing: Timing) => void;
 }
+/** Where a client's key came from: the option, PROMIGENCE_API_KEY (`env`), the stored sign-in, or a fallback. */
+export interface KeyOrigin {
+    source: "option" | "env" | "stored" | "fallback";
+    /** The stored sign-in's store, for `stored`. */
+    store?: CredentialStore;
+}
 /** `GET /sandboxes/:id/network`. */
 export interface SandboxNetwork {
     sandbox_id: string;
@@ -1578,6 +1678,12 @@ export interface RunStartOpts {
     verifyEach?: boolean;
     network?: NetworkMode;
     optimizeFor?: OptimizeFor;
+    /**
+     * Which of this run's sandboxes are kept to reopen where they ended (`runs.open`): `on_failure`
+     * keeps one whose command failed, `off` keeps none, `always` keeps every one. Left out, the
+     * default applies.
+     */
+    capture?: CaptureMode;
     /**
      * Secrets for every sandbox of this run. An `exec` is no longer required: a run that names
      * its secrets here gives them to every command run against every one of its sandboxes,
@@ -1641,9 +1747,9 @@ export interface ExecOpts {
      */
     secrets?: SecretBinding[];
     /**
-     * Cancel an in-flight exec, streamed or not: the client stops waiting and the request is closed,
-     * which ends the command in the sandbox. A buffered exec then throws `TimeoutError` ("aborted by
-     * the caller's signal"); a streamed one rejects with the signal's `AbortError`.
+     * Cancel an in-flight exec, streamed or not: the client stops waiting and tells the service to
+     * stop the command in the sandbox. A buffered exec then throws `TimeoutError` ("aborted by the
+     * caller's signal"); a streamed one rejects with the signal's `AbortError`.
      */
     signal?: AbortSignal;
     /**
@@ -1756,6 +1862,11 @@ export interface SnapshotCreateOpts {
      */
     setupUser?: string;
     alias?: string;
+    /**
+     * With `alias`: take the name from the snapshot that has it, which stays, unnamed. Without it, an
+     * alias another snapshot has is refused (`usage`, 400) and nothing is built.
+     */
+    moveAlias?: boolean;
     /**
      * A DEFAULT grader for this snapshot: a run on it with no `grade` of its own uses this one.
      * The same shape as `runs.start({ grade })`.
@@ -1841,11 +1952,12 @@ export declare function credentialsExposure(path: string): string | undefined;
  * `credentialsTrustProblem`).
  */
 export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials;
-export declare function apiUrlFromCompatUrl(url: string | undefined): string | undefined;
-export declare function apiUrlFromCompatDomain(domain: string | undefined): string | undefined;
-export declare function compatApiKey(key: string | undefined): string | undefined;
 /** Which variable a key came from, for `promigence doctor`. */
 export declare function keyOrigin(env?: NodeJS.ProcessEnv): string | undefined;
+/** A request with no key found anywhere: none passed, none in the environment, none stored. */
+export declare const NO_KEY_MESSAGE = "no API key: none was given, PROMIGENCE_API_KEY is not set, and none is stored";
+/** What a caller of this SDK does about it. */
+export declare const NO_KEY_FIX = "Pass { apiKey } or set PROMIGENCE_API_KEY. No key yet: `promigence login` signs you up or in and stores one.";
 /** `name@sha256:<64 hex>`, optionally with a tag before the `@`: a reference already pinned. */
 export declare const IMAGE_DIGEST_RE: RegExp;
 /**
@@ -2031,6 +2143,9 @@ export declare class PromigenceClient {
     private guardDispatcher;
     private dispatcherFor;
     private againKeyed;
+    private heldExec;
+    private reattachBuffered;
+    private cancelHeldExec;
     request<T>(opts: RequestOpts): Promise<T>;
     /**
      * A request whose body — in either direction — is **bytes, not JSON** (`files get|put`).
@@ -2228,15 +2343,29 @@ export declare class PromigenceClient {
             /** `PATCH /orgs/:org/projects/:project {name}` — rename it (the `default` project keeps its name). */
             rename: (org: string, project: string, name: string) => Promise<ProjectRecord>;
             /**
-             * `PATCH /orgs/:org/projects/:project` — rename it, set how long its command output is kept, or
-             * whether its failed sandboxes are kept to reopen (that one on its own). The settings need an owner signed in.
+             * `PATCH /orgs/:org/projects/:project` — rename it, set how long its command output is kept,
+             * whether its failed sandboxes are kept to reopen (on its own; `null` = the organization's choice, and
+             * where neither chose, not kept unless the organization or project chose to keep them), or how long
+             * its new preview URLs are (on its own). The settings need an owner signed in.
              */
             update: (org: string, project: string, update: {
                 name?: string;
                 outputRetentionDays?: number | null;
                 failureCaptures?: boolean | null;
+                previewLinkLength?: PreviewLinkLength | null;
             }) => Promise<ProjectRecord>;
         };
+        /**
+         * `PATCH /orgs/:org` — rename it, set how long its command output is kept, whether its failed
+         * sandboxes are kept to reopen, or how long its new preview URLs are (those two each on their
+         * own). The settings need an owner signed in.
+         */
+        update: (org: string, update: {
+            name?: string;
+            outputRetentionDays?: number | null;
+            failureCaptures?: boolean | null;
+            previewLinkLength?: PreviewLinkLength | null;
+        }) => Promise<OrgRecord>;
     };
     private group_orgs;
     readonly credits: {
@@ -2410,7 +2539,13 @@ export declare class PromigenceClient {
      */
     private waitLoop;
     readonly sandboxes: {
-        /** `POST /sandboxes/:id/execs` — foreground exec, inline output up to `maxOutputBytes`. */
+        /**
+         * `POST /sandboxes/:id/execs` — foreground exec, inline output up to `maxOutputBytes`.
+         *
+         * If the connection drops while the command runs, the SDK picks the command up again where the
+         * service keeps it and returns its own answer; when it cannot, it throws `ExecLostError`. The
+         * command is never sent a second time.
+         */
         exec: (sandboxId: string, opts: ExecOpts) => Promise<ExecResponse>;
         /**
          * `POST /sandboxes/:id/execs` with `Accept: text/event-stream`.
@@ -2422,6 +2557,10 @@ export declare class PromigenceClient {
          *
          * Uses `fetch`'s streaming body rather than `res.text()`, which is what `request()` does and
          * why it cannot be reused here: `await res.text()` is precisely the buffering this removes.
+         *
+         * If the connection drops while the command runs, the SDK picks the command up again where the
+         * service keeps it, and the stream goes on where it left off; when it cannot, it throws
+         * `ExecLostError`. The command is never sent a second time.
          */
         execStream: (sandboxId: string, opts: ExecOpts, on?: {
             stdout?: (chunk: Uint8Array) => void;
@@ -2510,9 +2649,18 @@ export declare class PromigenceClient {
         /**
          * Preview URLs for ports inside the sandbox. A URL is a capability — anyone holding it reaches
          * that port — and dies with `revoke`, with a pause, or 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>`.
          */
         ports: {
-            expose: (sandboxId: string, port: number) => Promise<PortRecord>;
+            /**
+             * Publish a port: `{ length: "long" }` for a longer, harder-to-guess URL (apps with
+             * sensitive data); omitted, the length the sandbox's project or organization chose
+             * (short by default).
+             */
+            expose: (sandboxId: string, port: number, opts?: PortExposeOpts) => Promise<PortRecord>;
             list: (sandboxId: string) => Promise<PortRecord[]>;
             /** A token revokes that URL; a port number revokes every URL for that port. */
             revoke: (sandboxId: string, tokenOrPort: string | number) => Promise<{
@@ -3049,8 +3197,14 @@ export declare class PromigenceClient {
             alias?: string | null;
             deleted: boolean;
         }>;
-        /** `PUT /snapshots/:id/alias` — the sidecar's one mutable field. */
-        alias: (idOrAlias: string, alias: string | null) => Promise<SnapshotRecord>;
+        /**
+         * `PUT /snapshots/:id/alias` — the sidecar's one mutable field. A name another snapshot
+         * has is refused (`usage`, 400) unless `moveAlias: true`, which takes it; that one stays,
+         * unnamed.
+         */
+        alias: (idOrAlias: string, alias: string | null, opts?: {
+            moveAlias?: boolean;
+        }) => Promise<SnapshotRecord>;
         /**
          * Wait for a build to leave `running`, bounded by `waitTimeoutMs` (default 100 s).
          *