@promigence/sdk 0.1.0-beta.6 → 0.1.0-beta.7

package/dist/cjs/client.d.ts

@@ -253,6 +253,11 @@ export interface Totals {
     grader_failed?: number;
     snapshot_failed: number;
     aborted_by_client: number;
+    /**
+     * Sandboxes Promigence support stopped (outcome `stopped_by_support`), each with its reason in its
+     * failure's message. Never counted as your own kill (`aborted_by_client`). Absent from an older API.
+     */
+    stopped_by_support?: number;
     expired: number;
     cap_killed: number;
     not_started: number;
@@ -349,7 +354,9 @@ export interface SecretRecord {
     name: string;
     /** Length of the stored value, so a caller can sanity-check without reading it. */
     bytes: number;
+    /** On `secrets.set` only: `false` when an existing secret of that name was overwritten. */
     created?: boolean;
+    /** On `secrets.list` only. */
     created_at?: string;
     updated_at?: string;
     /**
@@ -370,7 +377,7 @@ export interface SecretRecord {
      * `api.anthropic.com`. Absent when there is none. A variable the caller sets itself wins.
      */
     env?: Record<string, string>;
-    /** The request headers the secret authenticates (present when `hosts` is). */
+    /** The request headers the secret authenticates: on `secrets.list`, when `hosts` is present. */
     headers?: string[];
     /** What the variable in a sandbox that names it holds instead of the value (on `set` of a bound secret). */
     placeholder?: string;
@@ -467,13 +474,17 @@ export interface SnapshotRecord {
     source?: SnapshotSource;
     /** `false` for an image snapshot built without `verify` — stored, but nothing was verified. */
     verified?: boolean;
-    start?: string | string[];
     created_at?: string;
     /**
      * Set when the snapshot can no longer be started, saying why (it was lost before it could be
      * kept); a fork of it is refused `snapshot_unavailable`. Absent while it can be started.
      */
     unavailable?: string;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name none:
+     * its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     [extra: string]: unknown;
 }
 /** `GET /snapshots/:id/manifest`: the snapshot's manifest, sealed (`buildBundle` turns it into a `.promigence` bundle). */
@@ -510,8 +521,6 @@ export interface ExecResponse {
     stdout: string;
     stderr: string;
     truncated?: boolean;
-    stdout_ref?: string;
-    stderr_ref?: string;
     /** True when the command was killed at its own timeout. */
     timed_out?: boolean;
     /** True when the command was killed for running out of memory. */
@@ -539,7 +548,13 @@ export interface SandboxRecord extends QueuedInfo {
      */
     pause_reason?: "spend_cap" | "credits_exhausted";
     run_id?: string;
+    /**
+     * The snapshot it was started from, as its run names it (`runs.get(runId).snapshot_id`): the
+     * snapshot's id, or `promigence/base` for the built-in base.
+     */
     snapshot_id?: string;
+    /** When the sandbox was created, RFC 3339. */
+    created_at?: string;
     outcome?: Outcome;
     /**
      * The labels this sandbox inherited from its run — the same map `runs.start({ labels })` took.
@@ -627,7 +642,7 @@ export interface Page<T> {
     /** What the server actually used, which is not always what was asked for (it caps at 500). */
     limit: number;
 }
-/** `GET /health` — unauthenticated: `ok`, `version`, `build_sha` and `serving`. */
+/** `GET /health` — unauthenticated: `ok`, `version`, `serving` and `location`; `build_sha` to a caller with a key. */
 export interface HealthResponse {
     ok?: boolean;
     version?: string;
@@ -1184,9 +1199,15 @@ export interface SearchOpts {
  * `POST /sandboxes/:id/files/archive` — where the tar landed **inside the sandbox** and how big
  * it is. The bytes stay in the sandbox on purpose; see `files.downloadDir`.
  */
-export interface ArchiveResult extends FileInfo {
+export interface ArchiveResult {
+    sandbox_id: string;
+    /** Where the tar landed inside the sandbox. */
     archive_path: string;
+    /** Its size in bytes. */
+    size: number;
+    /** The directory that was packed. */
     source: string;
+    served_by?: ServedBy;
 }
 /** `POST /sandboxes/:id/files/extract`. `entries` is `null` on the fallback path, which cannot
  *  count them without a second pass — a number invented there would be worse than none. */
@@ -1312,8 +1333,6 @@ export interface MeResponse {
         email?: string;
         provider?: string;
     } | null;
-    /** @deprecated Never sent: the key is `key.key_id`. */
-    key_id?: string;
     /**
      * The plan the organisation's limits and prices come from: `hobby` for a trial organisation
      * with no plan assigned. The name `tier_over_plan` and the other refusals use.
@@ -1349,7 +1368,6 @@ export interface MeResponse {
     /** The cap a run gets when it names none, in USD; `0` names none (the run is capped at its quote). */
     default_spend_cap?: number;
     card_on_file?: boolean;
-    default_class?: string;
     /** The free trial: credits, data out and the limits that apply until a card is on file. */
     trial?: TrialStatus;
     /** Something about the account to act on (the card-required switch), or null. */
@@ -1661,6 +1679,18 @@ export interface SnapshotCreateOpts {
     tier?: Tier;
     /** Image forms: the name of a stored secret holding the registry credentials. */
     registrySecret?: string;
+    /**
+     * Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes
+     * run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an
+     * image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run`
+     * does (root when it sets none).
+     */
+    user?: string;
+    /**
+     * Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example
+     * the snapshot's own `user`). Default: `root`.
+     */
+    setupUser?: string;
     alias?: string;
     /**
      * A DEFAULT grader for this snapshot: a run on it with no `grade` of its own uses this one.
@@ -1951,12 +1981,15 @@ export declare class PromigenceClient {
         timeoutMs?: number;
     }): Promise<StatusResponse>;
     /**
-     * `GET /pricing` — the price list, live: the per-second rates, every sandbox shape on sale and
-     * its price, the build price, the limits, the free credit and the plan they come from, read on
-     * every call from what billing charges. With a key: what this key's organization pays. Without
-     * one, or with `newAccount: true` (no key is sent): what a new account gets.
+     * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
+     * shape on sale and its price, the build price, the limits, the free credit and the plan they
+     * come from, read on every call from what billing charges. Needs a key: without one this throws
+     * `AuthError` and sends nothing. The published list prices are on the pricing page.
      *
      * Prices change: read them when you need them rather than keeping a copy.
+     *
+     * @param opts.newAccount No longer supported: there is no key-less price list. Passing `true`
+     *   throws `InvalidArgumentError` and sends nothing.
      */
     pricing(opts?: {
         newAccount?: boolean;
@@ -2475,6 +2508,12 @@ export declare class PromigenceClient {
         /**
          * `POST /sandboxes/:id/probe` — is this environment still the one that was verified?
          *
+         * Compares the sandbox's files under the paths its snapshot's verification recorded with what
+         * was recorded. It is the same check a failed run gets, which decides whether the failure was
+         * the environment's (`integrity_mismatch`, not billed) or a path the snapshot's own `verify`
+         * never covered (`verify_did_not_cover`, billed). Asking for it up front is cheaper than
+         * spending a run to find out.
+         *
          * `first_bad_path` names the **first differing path**, which is the only part of a failed
          * probe anyone can act on.
          */
@@ -2485,8 +2524,7 @@ export declare class PromigenceClient {
             ok: boolean;
             ms: number;
             checked: string | string[];
-            first_bad_path: string | null;
-            probe: Record<string, unknown>;
+            first_bad_path?: string | null;
         }>;
         /** `DELETE /sandboxes/:id`. */
         kill: (sandboxId: string) => Promise<unknown>;
@@ -2623,9 +2661,11 @@ export declare class PromigenceClient {
             /**
              * Write a file of **any size**, in [`FILE_PUT_CHUNK_BYTES`] requests.
              *
-             * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file, and the
-             * thrown error carries how far it got (`written` in the error's evidence).
-             * Re-running the same `put` is safe: chunk 0 truncates.
+             * Chunk 0 goes without `?offset=`, which means "this is the file" (create, truncate);
+             * every later chunk carries one, which appends, so a file has no size limit here.
+             *
+             * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file. Re-running the
+             * same `put` is safe: chunk 0 truncates.
              *
              * `mode` (`0o755`) sets the file's permission bits. Without it a file that already exists
              * keeps its mode, as a shell `>` does, and a new one is `0o644`.
@@ -2735,8 +2775,7 @@ export declare class PromigenceClient {
             ok: boolean;
             ms: number;
             checked: string | string[];
-            first_bad_path: string | null;
-            probe: Record<string, unknown>;
+            first_bad_path?: string | null;
         }>;
     };
     /**
@@ -2883,15 +2922,14 @@ export declare class PromigenceClient {
         manifest: (idOrAlias: string) => Promise<SnapshotManifestResponse>;
         /**
          * The `.promigence` bundle for a snapshot: the sealed form, which names exactly one
-         * environment and verifies offline (`verifyBundle`). `served_by` says whether the API wrote it
-         * (`control`) or this client composed it from the snapshot's manifest (`client`); both are the
-         * same document.
+         * environment and verifies offline (`verifyBundle`). This client composes it from the
+         * snapshot's sealed manifest (`served_by: "client"`); the API serves no bundle of its own.
          */
         bundle: (idOrAlias: string, opts?: {
             alias?: string;
         }) => Promise<{
             bundle: Bundle;
-            served_by: "control" | "client";
+            served_by: "client";
             record?: SnapshotRecord;
         }>;
     };

package/dist/cjs/client.js

@@ -540,6 +540,12 @@ function snapshotCreateBody(opts) {
     if (o.env !== undefined && Object.keys(o.env).length && forms[0] === "repo") {
         throw new core_js_1.InvalidArgumentError("snapshots.create env is for an image or a Dockerfile", "A repository snapshot sets its environment in its setup steps, or pass env on each command.");
     }
+    if ((o.user !== undefined || o.setupUser !== undefined) && forms[0] === "repo") {
+        throw new core_js_1.InvalidArgumentError("snapshots.create user and setupUser are for an image or a Dockerfile", "A repository snapshot runs as root; name a user on each command instead ({ user: 'app' }).");
+    }
+    if (o.setupUser !== undefined && o.user === undefined) {
+        throw new core_js_1.InvalidArgumentError("snapshots.create setupUser needs user", "Pass { user: 'app', setupUser: 'app' }: start, setup and verify as app too (without setupUser they run as root), every later command as app.");
+    }
     if (!github && (o.ref !== undefined || o.from !== undefined || o.track)) {
         throw new core_js_1.InvalidArgumentError("snapshots.create ref, from and track are for a connected repository (repo: 'github:owner/name' or 'gitlab:group/project')", "Pass { repo: 'github:your-org/app', ref: 'main' }, or drop them for this form.");
     }
@@ -549,7 +555,7 @@ function snapshotCreateBody(opts) {
             setup: o.setup, verify, tier: o.tier, alias: o.alias,
             others: [
                 ["sources", Boolean(o.sources?.length)], ["start", o.start !== undefined],
-                ["registrySecret", Boolean(o.registrySecret)], ["cpuClass", Boolean(o.cpuClass)],
+                ["registrySecret", Boolean(o.registrySecret)],
             ],
         });
     }
@@ -597,11 +603,13 @@ function snapshotCreateBody(opts) {
             body["registry_secret"] = o.registrySecret;
         if (o.env !== undefined && Object.keys(o.env).length)
             body["env"] = { ...o.env };
+        if (o.user !== undefined)
+            body["user"] = o.user;
+        if (o.setupUser !== undefined)
+            body["setup_user"] = o.setupUser;
     }
     if (o.alias)
         body["alias"] = o.alias;
-    if (o.cpuClass)
-        body["cpu_class"] = o.cpuClass;
     if (o.grade) {
         if (!o.grade.cmd)
             throw new core_js_1.InvalidArgumentError("snapshots.create grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
@@ -1240,12 +1248,14 @@ class PromigenceClient {
             ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
         });
     }
-    pricing(opts = {}) {
-        const anonymous = opts.newAccount === true || !this.authenticated;
+    async pricing(opts = {}) {
+        if (opts.newAccount === true) {
+            throw new core_js_1.InvalidArgumentError("pricing({ newAccount: true }) is no longer supported: the price list needs a key", "Call pricing() with your API key for your organization's prices. The published list prices are on the pricing page, and `promigence pricing` prints them without a key.");
+        }
+        this.requireKey();
         return this.request({
             method: "GET",
             path: "/pricing",
-            ...(anonymous ? { anonymous: true } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
             ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
         });
@@ -2447,19 +2457,6 @@ class PromigenceClient {
         },
         manifest: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}/manifest` }),
         bundle: async (idOrAlias, opts = {}) => {
-            try {
-                const r = await this.request({
-                    method: "GET", path: `/snapshots/${seg(idOrAlias)}/bundle`,
-                });
-                if (r?.bundle?.schema === bundle_js_1.BUNDLE_SCHEMA) {
-                    return { bundle: r.bundle, served_by: "control" };
-                }
-            }
-            catch (e) {
-                const code = e?.code;
-                if (code !== "not_found" && code !== "enoent" && e?.status !== 405)
-                    throw e;
-            }
             const [record, m] = await Promise.all([
                 this.snapshots.get(idOrAlias).catch(() => undefined),
                 this.snapshots.manifest(idOrAlias),

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.6";
+export declare const VERSION = "0.1.0-beta.7";
 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.6";
+exports.VERSION = "0.1.0-beta.7";
 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";
@@ -249,7 +249,7 @@ exports.EXIT_BY_CODE = {
     nonzero_exit: 4, grade_not_passed: 4, task_timeout: 4, oom_over_tier: 4, disk_over_tier: 4,
     shutdown_by_task: 4, modified_by_task: 4,
     cap_exceeded: 5, cap_killed: 12, cap_paused: 5, credits_paused: 5,
-    aborted_by_client: 130, expired: 12, not_started: 12, superseded: 0,
+    aborted_by_client: 130, stopped_by_support: 12, expired: 12, not_started: 12, superseded: 0,
     usage: 2, internal: 1, auth: 7, not_found: 8, unreachable: 9, rate_limited: 10,
     timeout: 11, not_verified: 6, enoent: 8,
     snapshot_incompatible: 6, storage_limit_reached: 5,
@@ -274,6 +274,8 @@ exports.EXIT_BY_CODE = {
     invite_invalid: 7,
     invite_required: 7,
     key_expired: 7,
+    account_blocked: 7,
+    setup_required: 7,
 };
 function exitForCode(code) {
     return Object.prototype.hasOwnProperty.call(exports.EXIT_BY_CODE, code) ? exports.EXIT_BY_CODE[code] : 1;

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

@@ -72,7 +72,9 @@ export interface AuthConfig {
      */
     console_authorize_url?: string | null;
     /**
-     * The sign-in buttons to offer, as name -> label.
+     * The sign-in methods to offer, as name -> label (`email`, `google`, `github`). A client that
+     * asks the sign-in pages for one method passes the label as their `identity_provider`, except
+     * `email`, which is the pages' own form and needs none.
      */
     identity_providers: Record<string, string>;
     /**
@@ -81,7 +83,6 @@ export interface AuthConfig {
      * account signs in as before either way.
      */
     invite_mode?: boolean;
-    issuer: string;
     /**
      * The redirect URIs a command-line client may listen on.
      */
@@ -90,10 +91,6 @@ export interface AuthConfig {
      * Where a headless sign-in lands instead, to show a code to paste back.
      */
     paste_redirect_uri: string;
-    /**
-     * Which identity service is in front of the API.
-     */
-    provider: string;
     scopes: Array<string>;
     token_url: string;
 }
@@ -660,7 +657,15 @@ export interface CaptureView {
  * The card on file, enough to recognise it.
  */
 export interface CardOnFile {
+    /**
+     * The card's brand (`visa`, `mastercard`, ...); for a card held in a wallet, the wallet
+     * (`apple_pay`, `google_pay`); for another payment method, its kind (`link`, `cashapp`,
+     * `amazon_pay`).
+     */
     brand?: string | null;
+    /**
+     * The card's last four digits; `null` for a payment method without a card number.
+     */
     last4?: string | null;
 }
 /**
@@ -825,7 +830,7 @@ export interface CliTokenCreate {
 /**
  * Every error and failure code the API returns.
  */
-export type Code = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "capacity_busy" | "verify_did_not_cover" | "nonzero_exit" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "cap_killed" | "cap_exceeded" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "enoent" | "trial_credits_exhausted" | "card_required" | "concurrency_limit" | "egress_cap_reached" | "network_policy_unsupported" | "network_host_refused" | "toolchain_mismatch" | "resume_unavailable" | "sandbox_unreachable" | "region_at_capacity" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "builder_unavailable" | "builder_busy" | "overloaded" | "preempted" | "grader_failed" | "grade_not_passed" | "shutdown_by_task" | "modified_by_task" | "cap_paused" | "credits_paused" | "forbidden" | "snapshot_incompatible" | "storage_limit_reached" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "credit_unclaimed" | "billing_unavailable" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired";
+export type Code = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "capacity_busy" | "verify_did_not_cover" | "nonzero_exit" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "cap_killed" | "cap_exceeded" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "enoent" | "trial_credits_exhausted" | "card_required" | "concurrency_limit" | "egress_cap_reached" | "network_policy_unsupported" | "network_host_refused" | "toolchain_mismatch" | "resume_unavailable" | "sandbox_unreachable" | "region_at_capacity" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "builder_unavailable" | "builder_busy" | "overloaded" | "preempted" | "grader_failed" | "grade_not_passed" | "shutdown_by_task" | "modified_by_task" | "cap_paused" | "credits_paused" | "stopped_by_support" | "forbidden" | "snapshot_incompatible" | "storage_limit_reached" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "credit_unclaimed" | "billing_unavailable" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired" | "account_blocked" | "setup_required";
 export interface Concurrency {
 }
 /**
@@ -1070,7 +1075,7 @@ export interface ErrorBody {
 /**
  * Every error code the API returns. `category` decides whether the failure is billed: `env` is ours (not billed before hand-over; after it, the time since the sandbox's last snapshot is credited back, up to 24 hours, when our side shows the cause), `task` is your command and is billed. The full table is `x-promigence-error-codes` at the document root.
  */
-export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credit_unclaimed" | "card_required" | "billing_unavailable" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired";
+export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "stopped_by_support" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credit_unclaimed" | "setup_required" | "card_required" | "billing_unavailable" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired" | "account_blocked";
 /**
  * `POST /v1/sandboxes/{id}/execs`, and the `exec` of `POST /v1/runs`: one command. `argv` (a
  * non-empty list) or `sh` (a shell line) is required.
@@ -1989,9 +1994,10 @@ export interface Guard {
  */
 export interface Health {
     /**
-     * The commit this build came from; empty for a local build.
+     * The commit this build came from; empty for a local build. Answered to a caller with a key;
+     * absent for one without.
      */
-    build_sha: string;
+    build_sha?: string;
     /**
      * Where sandboxes run, in plain words (for example "US East Coast"). Absent when the service
      * does not say.
@@ -2737,7 +2743,7 @@ export interface OtherUsage {
     amount: number;
     entries: number;
 }
-export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted";
+export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted" | "stopped_by_support";
 /**
  * `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
@@ -3075,10 +3081,10 @@ export interface PricingTier {
     vcpus: number;
 }
 /**
- * `GET /v1/pricing` — the prices, sandbox shapes, limits and free credit in force, read on every
- * call from the same place billing charges from. Without a key: what a new account gets. With a
- * key: what that key's organisation pays. A run is billed at the rates in force when it was
- * created, so a later change to these values never reprices a run already started.
+ * `GET /v1/pricing` — the prices, sandbox shapes, limits and free credit in force for the key's
+ * organisation, read on every call from the same place billing charges from. A key is required.
+ * A run is billed at the rates in force when it was created, so a later change to these values
+ * never reprices a run already started.
  */
 export interface PricingView {
     /**
@@ -3118,9 +3124,9 @@ export interface PricingView {
      */
     monthly_minimum_usd: number;
     /**
-     * The organisation these values are for; `null` for `new_account`.
+     * The organisation these values are for.
      */
-    org_id?: string | null;
+    org_id: string;
     plan: PricingPlan;
     rates: PricingRates;
     /**
@@ -3128,8 +3134,7 @@ export interface PricingView {
      */
     schema: string;
     /**
-     * `new_account` (asked without a key): what a new account gets. `organization` (asked with a
-     * key): what that key's organisation pays.
+     * `organization`: what the key's organisation pays.
      */
     scope: string;
     /**
@@ -4434,6 +4439,11 @@ export interface SandboxView {
      * once it has started; absent from list rows.
      */
     cost_usd?: number | null;
+    /**
+     * When the sandbox was created, RFC 3339: when its run was started, or when the retry or
+     * replay that made it was asked for.
+     */
+    created_at: string;
     /**
      * Milliseconds from the start request, after any time queued, to the sandbox being handed
      * over: it does not include `queued_ms`. Add `queued_ms` for the whole wait.
@@ -4491,6 +4501,13 @@ export interface SandboxView {
      * Why it ended; `null` while it is still alive.
      */
     outcome?: string | null;
+    /**
+     * While it is paused: when it will be deleted, with its memory and files, unless it is
+     * resumed before then (RFC 3339). A paused sandbox is kept for 30 days, and resuming it
+     * starts the 30 days again. Absent while it is not paused, and for a paused sandbox that is
+     * not due to be deleted.
+     */
+    pause_expires_at?: string | null;
     /**
      * Why it is paused, when a limit paused it rather than a request: `spend_cap` (its run
      * reached its spend cap) or `credits_exhausted` (the organization's credits ran out). Its
@@ -4528,6 +4545,11 @@ export interface SandboxView {
      */
     run_id: string;
     sandbox_id: string;
+    /**
+     * The snapshot it was started from, as its run names it (`GET /v1/runs/{id}`): the
+     * snapshot's id, or `promigence/base` for the built-in base.
+     */
+    snapshot_id: string;
     /**
      * `queued` | `ready` | `running` | `paused` | `ended`.
      */
@@ -4729,6 +4751,11 @@ export interface SecretStored {
      * otherwise. Present when `hosts` is.
      */
     raw?: string | null;
+    /**
+     * Whether the value is masked out of responses from the bound hosts. Present when `hosts`
+     * is.
+     */
+    scan_responses?: boolean | null;
     /**
      * RFC 3339.
      */
@@ -4990,6 +5017,11 @@ export interface SnapshotCreate {
      * Commands run once, in order, before `verify`.
      */
     setup?: OneOrMany | null;
+    /**
+     * Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example
+     * the snapshot's own `user`). Default: `root`.
+     */
+    setup_user?: string | null;
     /**
      * Extra repositories cloned before `setup` (repository form only, at most 8).
      */
@@ -5008,6 +5040,13 @@ export interface SnapshotCreate {
      * charged to the organization.
      */
     track?: boolean;
+    /**
+     * Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes
+     * run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an
+     * image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run`
+     * does (root when it sets none).
+     */
+    user?: string | null;
     /**
      * The command that must exit 0 for the snapshot to be stored. Required in the repository
      * form.
@@ -5103,6 +5142,11 @@ export interface SnapshotDeduped {
      * while it can be started.
      */
     unavailable?: string | null;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name
+     * none: its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     /**
      * What the verification command did when it last ran.
      */
@@ -5314,6 +5358,11 @@ export interface SnapshotView {
      * while it can be started.
      */
     unavailable?: string | null;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name
+     * none: its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     /**
      * What the verification command did when it last ran.
      */
@@ -5650,6 +5699,11 @@ export interface Totals {
      */
     preempted?: number;
     snapshot_failed: number;
+    /**
+     * Sandboxes Promigence support stopped (`stopped_by_support`), each with its reason. Its own
+     * counter: not the customer's own kills (`aborted_by_client`) and not a failure.
+     */
+    stopped_by_support?: number;
     task_failed: number;
 }
 /**

package/dist/cjs/sandbox.d.ts

@@ -134,7 +134,6 @@ export interface SandboxCreateOpts extends SandboxOpts {
     alias?: string;
     /** Name of a stored secret holding the registry credentials. */
     registrySecret?: string;
-    cpuClass?: string;
     /** Bound on the first build of an image (default 15 min). Expiry cancels nothing. */
     buildTimeoutMs?: number;
     /**
@@ -165,7 +164,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" | "cpuClass" | "buildTimeoutMs">, hooks?: {
+export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
      * The `POST /snapshots` answer, before any wait: `build_price` and whether it was `deduped`
      * or `joined` (nothing new charged). An implicit build costs money, so a caller
@@ -422,8 +421,7 @@ export declare class Sandbox {
         ok: boolean;
         ms: number;
         checked: string | string[];
-        first_bad_path: string | null;
-        probe: Record<string, unknown>;
+        first_bad_path?: string | null;
     }>;
     isRunning(): Promise<boolean>;
     /**

package/dist/cjs/sandbox.js

@@ -97,8 +97,6 @@ async function imageSnapshot(client, opts, hooks = {}) {
         create.alias = opts.alias;
     if (opts.registrySecret !== undefined)
         create.registrySecret = opts.registrySecret;
-    if (opts.cpuClass !== undefined)
-        create.cpuClass = opts.cpuClass;
     let build = (await client.snapshots.create(create)) ?? {};
     if (hooks.onBuild)
         await hooks.onBuild(build);

package/dist/client.d.ts

@@ -253,6 +253,11 @@ export interface Totals {
     grader_failed?: number;
     snapshot_failed: number;
     aborted_by_client: number;
+    /**
+     * Sandboxes Promigence support stopped (outcome `stopped_by_support`), each with its reason in its
+     * failure's message. Never counted as your own kill (`aborted_by_client`). Absent from an older API.
+     */
+    stopped_by_support?: number;
     expired: number;
     cap_killed: number;
     not_started: number;
@@ -349,7 +354,9 @@ export interface SecretRecord {
     name: string;
     /** Length of the stored value, so a caller can sanity-check without reading it. */
     bytes: number;
+    /** On `secrets.set` only: `false` when an existing secret of that name was overwritten. */
     created?: boolean;
+    /** On `secrets.list` only. */
     created_at?: string;
     updated_at?: string;
     /**
@@ -370,7 +377,7 @@ export interface SecretRecord {
      * `api.anthropic.com`. Absent when there is none. A variable the caller sets itself wins.
      */
     env?: Record<string, string>;
-    /** The request headers the secret authenticates (present when `hosts` is). */
+    /** The request headers the secret authenticates: on `secrets.list`, when `hosts` is present. */
     headers?: string[];
     /** What the variable in a sandbox that names it holds instead of the value (on `set` of a bound secret). */
     placeholder?: string;
@@ -467,13 +474,17 @@ export interface SnapshotRecord {
     source?: SnapshotSource;
     /** `false` for an image snapshot built without `verify` — stored, but nothing was verified. */
     verified?: boolean;
-    start?: string | string[];
     created_at?: string;
     /**
      * Set when the snapshot can no longer be started, saying why (it was lost before it could be
      * kept); a fork of it is refused `snapshot_unavailable`. Absent while it can be started.
      */
     unavailable?: string;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name none:
+     * its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     [extra: string]: unknown;
 }
 /** `GET /snapshots/:id/manifest`: the snapshot's manifest, sealed (`buildBundle` turns it into a `.promigence` bundle). */
@@ -510,8 +521,6 @@ export interface ExecResponse {
     stdout: string;
     stderr: string;
     truncated?: boolean;
-    stdout_ref?: string;
-    stderr_ref?: string;
     /** True when the command was killed at its own timeout. */
     timed_out?: boolean;
     /** True when the command was killed for running out of memory. */
@@ -539,7 +548,13 @@ export interface SandboxRecord extends QueuedInfo {
      */
     pause_reason?: "spend_cap" | "credits_exhausted";
     run_id?: string;
+    /**
+     * The snapshot it was started from, as its run names it (`runs.get(runId).snapshot_id`): the
+     * snapshot's id, or `promigence/base` for the built-in base.
+     */
     snapshot_id?: string;
+    /** When the sandbox was created, RFC 3339. */
+    created_at?: string;
     outcome?: Outcome;
     /**
      * The labels this sandbox inherited from its run — the same map `runs.start({ labels })` took.
@@ -627,7 +642,7 @@ export interface Page<T> {
     /** What the server actually used, which is not always what was asked for (it caps at 500). */
     limit: number;
 }
-/** `GET /health` — unauthenticated: `ok`, `version`, `build_sha` and `serving`. */
+/** `GET /health` — unauthenticated: `ok`, `version`, `serving` and `location`; `build_sha` to a caller with a key. */
 export interface HealthResponse {
     ok?: boolean;
     version?: string;
@@ -1184,9 +1199,15 @@ export interface SearchOpts {
  * `POST /sandboxes/:id/files/archive` — where the tar landed **inside the sandbox** and how big
  * it is. The bytes stay in the sandbox on purpose; see `files.downloadDir`.
  */
-export interface ArchiveResult extends FileInfo {
+export interface ArchiveResult {
+    sandbox_id: string;
+    /** Where the tar landed inside the sandbox. */
     archive_path: string;
+    /** Its size in bytes. */
+    size: number;
+    /** The directory that was packed. */
     source: string;
+    served_by?: ServedBy;
 }
 /** `POST /sandboxes/:id/files/extract`. `entries` is `null` on the fallback path, which cannot
  *  count them without a second pass — a number invented there would be worse than none. */
@@ -1312,8 +1333,6 @@ export interface MeResponse {
         email?: string;
         provider?: string;
     } | null;
-    /** @deprecated Never sent: the key is `key.key_id`. */
-    key_id?: string;
     /**
      * The plan the organisation's limits and prices come from: `hobby` for a trial organisation
      * with no plan assigned. The name `tier_over_plan` and the other refusals use.
@@ -1349,7 +1368,6 @@ export interface MeResponse {
     /** The cap a run gets when it names none, in USD; `0` names none (the run is capped at its quote). */
     default_spend_cap?: number;
     card_on_file?: boolean;
-    default_class?: string;
     /** The free trial: credits, data out and the limits that apply until a card is on file. */
     trial?: TrialStatus;
     /** Something about the account to act on (the card-required switch), or null. */
@@ -1661,6 +1679,18 @@ export interface SnapshotCreateOpts {
     tier?: Tier;
     /** Image forms: the name of a stored secret holding the registry credentials. */
     registrySecret?: string;
+    /**
+     * Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes
+     * run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an
+     * image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run`
+     * does (root when it sets none).
+     */
+    user?: string;
+    /**
+     * Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example
+     * the snapshot's own `user`). Default: `root`.
+     */
+    setupUser?: string;
     alias?: string;
     /**
      * A DEFAULT grader for this snapshot: a run on it with no `grade` of its own uses this one.
@@ -1951,12 +1981,15 @@ export declare class PromigenceClient {
         timeoutMs?: number;
     }): Promise<StatusResponse>;
     /**
-     * `GET /pricing` — the price list, live: the per-second rates, every sandbox shape on sale and
-     * its price, the build price, the limits, the free credit and the plan they come from, read on
-     * every call from what billing charges. With a key: what this key's organization pays. Without
-     * one, or with `newAccount: true` (no key is sent): what a new account gets.
+     * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
+     * shape on sale and its price, the build price, the limits, the free credit and the plan they
+     * come from, read on every call from what billing charges. Needs a key: without one this throws
+     * `AuthError` and sends nothing. The published list prices are on the pricing page.
      *
      * Prices change: read them when you need them rather than keeping a copy.
+     *
+     * @param opts.newAccount No longer supported: there is no key-less price list. Passing `true`
+     *   throws `InvalidArgumentError` and sends nothing.
      */
     pricing(opts?: {
         newAccount?: boolean;
@@ -2475,6 +2508,12 @@ export declare class PromigenceClient {
         /**
          * `POST /sandboxes/:id/probe` — is this environment still the one that was verified?
          *
+         * Compares the sandbox's files under the paths its snapshot's verification recorded with what
+         * was recorded. It is the same check a failed run gets, which decides whether the failure was
+         * the environment's (`integrity_mismatch`, not billed) or a path the snapshot's own `verify`
+         * never covered (`verify_did_not_cover`, billed). Asking for it up front is cheaper than
+         * spending a run to find out.
+         *
          * `first_bad_path` names the **first differing path**, which is the only part of a failed
          * probe anyone can act on.
          */
@@ -2485,8 +2524,7 @@ export declare class PromigenceClient {
             ok: boolean;
             ms: number;
             checked: string | string[];
-            first_bad_path: string | null;
-            probe: Record<string, unknown>;
+            first_bad_path?: string | null;
         }>;
         /** `DELETE /sandboxes/:id`. */
         kill: (sandboxId: string) => Promise<unknown>;
@@ -2623,9 +2661,11 @@ export declare class PromigenceClient {
             /**
              * Write a file of **any size**, in [`FILE_PUT_CHUNK_BYTES`] requests.
              *
-             * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file, and the
-             * thrown error carries how far it got (`written` in the error's evidence).
-             * Re-running the same `put` is safe: chunk 0 truncates.
+             * Chunk 0 goes without `?offset=`, which means "this is the file" (create, truncate);
+             * every later chunk carries one, which appends, so a file has no size limit here.
+             *
+             * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file. Re-running the
+             * same `put` is safe: chunk 0 truncates.
              *
              * `mode` (`0o755`) sets the file's permission bits. Without it a file that already exists
              * keeps its mode, as a shell `>` does, and a new one is `0o644`.
@@ -2735,8 +2775,7 @@ export declare class PromigenceClient {
             ok: boolean;
             ms: number;
             checked: string | string[];
-            first_bad_path: string | null;
-            probe: Record<string, unknown>;
+            first_bad_path?: string | null;
         }>;
     };
     /**
@@ -2883,15 +2922,14 @@ export declare class PromigenceClient {
         manifest: (idOrAlias: string) => Promise<SnapshotManifestResponse>;
         /**
          * The `.promigence` bundle for a snapshot: the sealed form, which names exactly one
-         * environment and verifies offline (`verifyBundle`). `served_by` says whether the API wrote it
-         * (`control`) or this client composed it from the snapshot's manifest (`client`); both are the
-         * same document.
+         * environment and verifies offline (`verifyBundle`). This client composes it from the
+         * snapshot's sealed manifest (`served_by: "client"`); the API serves no bundle of its own.
          */
         bundle: (idOrAlias: string, opts?: {
             alias?: string;
         }) => Promise<{
             bundle: Bundle;
-            served_by: "control" | "client";
+            served_by: "client";
             record?: SnapshotRecord;
         }>;
     };

package/dist/client.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { inspect } from "node:util";
 import { dirname, join } from "node:path";
 import { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, ERRORS_DOCS_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, exitForCode, previewsOff, withPreviewsFix, } from "./core.js";
-import { BUNDLE_SCHEMA, buildBundle } from "./bundle.js";
+import { buildBundle } from "./bundle.js";
 import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
 import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.js";
 import { connectPty } from "./pty.js";
@@ -507,6 +507,12 @@ export function snapshotCreateBody(opts) {
     if (o.env !== undefined && Object.keys(o.env).length && forms[0] === "repo") {
         throw new InvalidArgumentError("snapshots.create env is for an image or a Dockerfile", "A repository snapshot sets its environment in its setup steps, or pass env on each command.");
     }
+    if ((o.user !== undefined || o.setupUser !== undefined) && forms[0] === "repo") {
+        throw new InvalidArgumentError("snapshots.create user and setupUser are for an image or a Dockerfile", "A repository snapshot runs as root; name a user on each command instead ({ user: 'app' }).");
+    }
+    if (o.setupUser !== undefined && o.user === undefined) {
+        throw new InvalidArgumentError("snapshots.create setupUser needs user", "Pass { user: 'app', setupUser: 'app' }: start, setup and verify as app too (without setupUser they run as root), every later command as app.");
+    }
     if (!github && (o.ref !== undefined || o.from !== undefined || o.track)) {
         throw new InvalidArgumentError("snapshots.create ref, from and track are for a connected repository (repo: 'github:owner/name' or 'gitlab:group/project')", "Pass { repo: 'github:your-org/app', ref: 'main' }, or drop them for this form.");
     }
@@ -516,7 +522,7 @@ export function snapshotCreateBody(opts) {
             setup: o.setup, verify, tier: o.tier, alias: o.alias,
             others: [
                 ["sources", Boolean(o.sources?.length)], ["start", o.start !== undefined],
-                ["registrySecret", Boolean(o.registrySecret)], ["cpuClass", Boolean(o.cpuClass)],
+                ["registrySecret", Boolean(o.registrySecret)],
             ],
         });
     }
@@ -564,11 +570,13 @@ export function snapshotCreateBody(opts) {
             body["registry_secret"] = o.registrySecret;
         if (o.env !== undefined && Object.keys(o.env).length)
             body["env"] = { ...o.env };
+        if (o.user !== undefined)
+            body["user"] = o.user;
+        if (o.setupUser !== undefined)
+            body["setup_user"] = o.setupUser;
     }
     if (o.alias)
         body["alias"] = o.alias;
-    if (o.cpuClass)
-        body["cpu_class"] = o.cpuClass;
     if (o.grade) {
         if (!o.grade.cmd)
             throw new InvalidArgumentError("snapshots.create grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
@@ -1207,12 +1215,14 @@ export class PromigenceClient {
             ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
         });
     }
-    pricing(opts = {}) {
-        const anonymous = opts.newAccount === true || !this.authenticated;
+    async pricing(opts = {}) {
+        if (opts.newAccount === true) {
+            throw new InvalidArgumentError("pricing({ newAccount: true }) is no longer supported: the price list needs a key", "Call pricing() with your API key for your organization's prices. The published list prices are on the pricing page, and `promigence pricing` prints them without a key.");
+        }
+        this.requireKey();
         return this.request({
             method: "GET",
             path: "/pricing",
-            ...(anonymous ? { anonymous: true } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
             ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
         });
@@ -2414,19 +2424,6 @@ export class PromigenceClient {
         },
         manifest: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}/manifest` }),
         bundle: async (idOrAlias, opts = {}) => {
-            try {
-                const r = await this.request({
-                    method: "GET", path: `/snapshots/${seg(idOrAlias)}/bundle`,
-                });
-                if (r?.bundle?.schema === BUNDLE_SCHEMA) {
-                    return { bundle: r.bundle, served_by: "control" };
-                }
-            }
-            catch (e) {
-                const code = e?.code;
-                if (code !== "not_found" && code !== "enoent" && e?.status !== 405)
-                    throw e;
-            }
             const [record, m] = await Promise.all([
                 this.snapshots.get(idOrAlias).catch(() => undefined),
                 this.snapshots.manifest(idOrAlias),

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.6";
+export declare const VERSION = "0.1.0-beta.7";
 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.6";
+export const VERSION = "0.1.0-beta.7";
 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";
@@ -226,7 +226,7 @@ export const EXIT_BY_CODE = {
     nonzero_exit: 4, grade_not_passed: 4, task_timeout: 4, oom_over_tier: 4, disk_over_tier: 4,
     shutdown_by_task: 4, modified_by_task: 4,
     cap_exceeded: 5, cap_killed: 12, cap_paused: 5, credits_paused: 5,
-    aborted_by_client: 130, expired: 12, not_started: 12, superseded: 0,
+    aborted_by_client: 130, stopped_by_support: 12, expired: 12, not_started: 12, superseded: 0,
     usage: 2, internal: 1, auth: 7, not_found: 8, unreachable: 9, rate_limited: 10,
     timeout: 11, not_verified: 6, enoent: 8,
     snapshot_incompatible: 6, storage_limit_reached: 5,
@@ -251,6 +251,8 @@ export const EXIT_BY_CODE = {
     invite_invalid: 7,
     invite_required: 7,
     key_expired: 7,
+    account_blocked: 7,
+    setup_required: 7,
 };
 export function exitForCode(code) {
     return Object.prototype.hasOwnProperty.call(EXIT_BY_CODE, code) ? EXIT_BY_CODE[code] : 1;

package/dist/models.gen.d.ts

@@ -72,7 +72,9 @@ export interface AuthConfig {
      */
     console_authorize_url?: string | null;
     /**
-     * The sign-in buttons to offer, as name -> label.
+     * The sign-in methods to offer, as name -> label (`email`, `google`, `github`). A client that
+     * asks the sign-in pages for one method passes the label as their `identity_provider`, except
+     * `email`, which is the pages' own form and needs none.
      */
     identity_providers: Record<string, string>;
     /**
@@ -81,7 +83,6 @@ export interface AuthConfig {
      * account signs in as before either way.
      */
     invite_mode?: boolean;
-    issuer: string;
     /**
      * The redirect URIs a command-line client may listen on.
      */
@@ -90,10 +91,6 @@ export interface AuthConfig {
      * Where a headless sign-in lands instead, to show a code to paste back.
      */
     paste_redirect_uri: string;
-    /**
-     * Which identity service is in front of the API.
-     */
-    provider: string;
     scopes: Array<string>;
     token_url: string;
 }
@@ -660,7 +657,15 @@ export interface CaptureView {
  * The card on file, enough to recognise it.
  */
 export interface CardOnFile {
+    /**
+     * The card's brand (`visa`, `mastercard`, ...); for a card held in a wallet, the wallet
+     * (`apple_pay`, `google_pay`); for another payment method, its kind (`link`, `cashapp`,
+     * `amazon_pay`).
+     */
     brand?: string | null;
+    /**
+     * The card's last four digits; `null` for a payment method without a card number.
+     */
     last4?: string | null;
 }
 /**
@@ -825,7 +830,7 @@ export interface CliTokenCreate {
 /**
  * Every error and failure code the API returns.
  */
-export type Code = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "capacity_busy" | "verify_did_not_cover" | "nonzero_exit" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "cap_killed" | "cap_exceeded" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "enoent" | "trial_credits_exhausted" | "card_required" | "concurrency_limit" | "egress_cap_reached" | "network_policy_unsupported" | "network_host_refused" | "toolchain_mismatch" | "resume_unavailable" | "sandbox_unreachable" | "region_at_capacity" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "builder_unavailable" | "builder_busy" | "overloaded" | "preempted" | "grader_failed" | "grade_not_passed" | "shutdown_by_task" | "modified_by_task" | "cap_paused" | "credits_paused" | "forbidden" | "snapshot_incompatible" | "storage_limit_reached" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "credit_unclaimed" | "billing_unavailable" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired";
+export type Code = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "capacity_busy" | "verify_did_not_cover" | "nonzero_exit" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "cap_killed" | "cap_exceeded" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "enoent" | "trial_credits_exhausted" | "card_required" | "concurrency_limit" | "egress_cap_reached" | "network_policy_unsupported" | "network_host_refused" | "toolchain_mismatch" | "resume_unavailable" | "sandbox_unreachable" | "region_at_capacity" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "builder_unavailable" | "builder_busy" | "overloaded" | "preempted" | "grader_failed" | "grade_not_passed" | "shutdown_by_task" | "modified_by_task" | "cap_paused" | "credits_paused" | "stopped_by_support" | "forbidden" | "snapshot_incompatible" | "storage_limit_reached" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "credit_unclaimed" | "billing_unavailable" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired" | "account_blocked" | "setup_required";
 export interface Concurrency {
 }
 /**
@@ -1070,7 +1075,7 @@ export interface ErrorBody {
 /**
  * Every error code the API returns. `category` decides whether the failure is billed: `env` is ours (not billed before hand-over; after it, the time since the sandbox's last snapshot is credited back, up to 24 hours, when our side shows the cause), `task` is your command and is billed. The full table is `x-promigence-error-codes` at the document root.
  */
-export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credit_unclaimed" | "card_required" | "billing_unavailable" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired";
+export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "stopped_by_support" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credit_unclaimed" | "setup_required" | "card_required" | "billing_unavailable" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired" | "account_blocked";
 /**
  * `POST /v1/sandboxes/{id}/execs`, and the `exec` of `POST /v1/runs`: one command. `argv` (a
  * non-empty list) or `sh` (a shell line) is required.
@@ -1989,9 +1994,10 @@ export interface Guard {
  */
 export interface Health {
     /**
-     * The commit this build came from; empty for a local build.
+     * The commit this build came from; empty for a local build. Answered to a caller with a key;
+     * absent for one without.
      */
-    build_sha: string;
+    build_sha?: string;
     /**
      * Where sandboxes run, in plain words (for example "US East Coast"). Absent when the service
      * does not say.
@@ -2737,7 +2743,7 @@ export interface OtherUsage {
     amount: number;
     entries: number;
 }
-export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted";
+export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted" | "stopped_by_support";
 /**
  * `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
@@ -3075,10 +3081,10 @@ export interface PricingTier {
     vcpus: number;
 }
 /**
- * `GET /v1/pricing` — the prices, sandbox shapes, limits and free credit in force, read on every
- * call from the same place billing charges from. Without a key: what a new account gets. With a
- * key: what that key's organisation pays. A run is billed at the rates in force when it was
- * created, so a later change to these values never reprices a run already started.
+ * `GET /v1/pricing` — the prices, sandbox shapes, limits and free credit in force for the key's
+ * organisation, read on every call from the same place billing charges from. A key is required.
+ * A run is billed at the rates in force when it was created, so a later change to these values
+ * never reprices a run already started.
  */
 export interface PricingView {
     /**
@@ -3118,9 +3124,9 @@ export interface PricingView {
      */
     monthly_minimum_usd: number;
     /**
-     * The organisation these values are for; `null` for `new_account`.
+     * The organisation these values are for.
      */
-    org_id?: string | null;
+    org_id: string;
     plan: PricingPlan;
     rates: PricingRates;
     /**
@@ -3128,8 +3134,7 @@ export interface PricingView {
      */
     schema: string;
     /**
-     * `new_account` (asked without a key): what a new account gets. `organization` (asked with a
-     * key): what that key's organisation pays.
+     * `organization`: what the key's organisation pays.
      */
     scope: string;
     /**
@@ -4434,6 +4439,11 @@ export interface SandboxView {
      * once it has started; absent from list rows.
      */
     cost_usd?: number | null;
+    /**
+     * When the sandbox was created, RFC 3339: when its run was started, or when the retry or
+     * replay that made it was asked for.
+     */
+    created_at: string;
     /**
      * Milliseconds from the start request, after any time queued, to the sandbox being handed
      * over: it does not include `queued_ms`. Add `queued_ms` for the whole wait.
@@ -4491,6 +4501,13 @@ export interface SandboxView {
      * Why it ended; `null` while it is still alive.
      */
     outcome?: string | null;
+    /**
+     * While it is paused: when it will be deleted, with its memory and files, unless it is
+     * resumed before then (RFC 3339). A paused sandbox is kept for 30 days, and resuming it
+     * starts the 30 days again. Absent while it is not paused, and for a paused sandbox that is
+     * not due to be deleted.
+     */
+    pause_expires_at?: string | null;
     /**
      * Why it is paused, when a limit paused it rather than a request: `spend_cap` (its run
      * reached its spend cap) or `credits_exhausted` (the organization's credits ran out). Its
@@ -4528,6 +4545,11 @@ export interface SandboxView {
      */
     run_id: string;
     sandbox_id: string;
+    /**
+     * The snapshot it was started from, as its run names it (`GET /v1/runs/{id}`): the
+     * snapshot's id, or `promigence/base` for the built-in base.
+     */
+    snapshot_id: string;
     /**
      * `queued` | `ready` | `running` | `paused` | `ended`.
      */
@@ -4729,6 +4751,11 @@ export interface SecretStored {
      * otherwise. Present when `hosts` is.
      */
     raw?: string | null;
+    /**
+     * Whether the value is masked out of responses from the bound hosts. Present when `hosts`
+     * is.
+     */
+    scan_responses?: boolean | null;
     /**
      * RFC 3339.
      */
@@ -4990,6 +5017,11 @@ export interface SnapshotCreate {
      * Commands run once, in order, before `verify`.
      */
     setup?: OneOrMany | null;
+    /**
+     * Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example
+     * the snapshot's own `user`). Default: `root`.
+     */
+    setup_user?: string | null;
     /**
      * Extra repositories cloned before `setup` (repository form only, at most 8).
      */
@@ -5008,6 +5040,13 @@ export interface SnapshotCreate {
      * charged to the organization.
      */
     track?: boolean;
+    /**
+     * Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes
+     * run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an
+     * image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run`
+     * does (root when it sets none).
+     */
+    user?: string | null;
     /**
      * The command that must exit 0 for the snapshot to be stored. Required in the repository
      * form.
@@ -5103,6 +5142,11 @@ export interface SnapshotDeduped {
      * while it can be started.
      */
     unavailable?: string | null;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name
+     * none: its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     /**
      * What the verification command did when it last ran.
      */
@@ -5314,6 +5358,11 @@ export interface SnapshotView {
      * while it can be started.
      */
     unavailable?: string | null;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name
+     * none: its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     /**
      * What the verification command did when it last ran.
      */
@@ -5650,6 +5699,11 @@ export interface Totals {
      */
     preempted?: number;
     snapshot_failed: number;
+    /**
+     * Sandboxes Promigence support stopped (`stopped_by_support`), each with its reason. Its own
+     * counter: not the customer's own kills (`aborted_by_client`) and not a failure.
+     */
+    stopped_by_support?: number;
     task_failed: number;
 }
 /**

package/dist/sandbox.d.ts

@@ -134,7 +134,6 @@ export interface SandboxCreateOpts extends SandboxOpts {
     alias?: string;
     /** Name of a stored secret holding the registry credentials. */
     registrySecret?: string;
-    cpuClass?: string;
     /** Bound on the first build of an image (default 15 min). Expiry cancels nothing. */
     buildTimeoutMs?: number;
     /**
@@ -165,7 +164,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" | "cpuClass" | "buildTimeoutMs">, hooks?: {
+export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
      * The `POST /snapshots` answer, before any wait: `build_price` and whether it was `deduped`
      * or `joined` (nothing new charged). An implicit build costs money, so a caller
@@ -422,8 +421,7 @@ export declare class Sandbox {
         ok: boolean;
         ms: number;
         checked: string | string[];
-        first_bad_path: string | null;
-        probe: Record<string, unknown>;
+        first_bad_path?: string | null;
     }>;
     isRunning(): Promise<boolean>;
     /**

package/dist/sandbox.js

@@ -87,8 +87,6 @@ export async function imageSnapshot(client, opts, hooks = {}) {
         create.alias = opts.alias;
     if (opts.registrySecret !== undefined)
         create.registrySecret = opts.registrySecret;
-    if (opts.cpuClass !== undefined)
-        create.cpuClass = opts.cpuClass;
     let build = (await client.snapshots.create(create)) ?? {};
     if (hooks.onBuild)
         await hooks.onBuild(build);

package/package.json

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