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

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;
@@ -733,6 +748,8 @@ export interface CreditOffer {
     state: string;
     credit_usd: number;
     card_bonus_usd: number;
+    /** USD charged to confirm Apple Pay, Google Pay or Amazon Pay when one is added (added to the credit). */
+    method_check_usd?: number;
     expires_at?: string | null;
     campaign?: string | null;
     message: string;
@@ -891,6 +908,16 @@ export interface BillingUsage {
         brand?: string;
         last4?: string;
     } | null;
+    /** Set when the card on file does not unlock paid limits for this organization (it already pays for another one,
+     *  it is being confirmed with a $1 charge, or that charge did not go through). */
+    card_note?: string | null;
+    /** The $1 that confirms Apple Pay, Google Pay or Amazon Pay on file: `confirming`, `paid` or `failed`. */
+    method_check?: {
+        method: string;
+        status: string;
+        amount_usd: number;
+        bonus_usd?: number | null;
+    } | null;
     suspended?: boolean;
     suspend_reason?: string | null;
     period?: {
@@ -914,6 +941,10 @@ export interface BillingUsage {
     upcoming_invoice_error?: string | null;
     [extra: string]: unknown;
 }
+/** One row of `GET /billing/history`: a credit the organization received, or a payment. */
+export type BillingHistoryEntry = M.BillingHistoryEntry;
+/** What `billing.historyPage()` lists: everything, only credits, or only payments. */
+export type BillingHistoryKind = "all" | "credits" | "payments";
 /** One metered row of `GET /me/ledger`. */
 export interface LedgerEntry {
     entry_id: string;
@@ -1184,9 +1215,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 +1349,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 +1384,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 +1695,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 +1997,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;
@@ -2000,6 +2049,16 @@ export declare class PromigenceClient {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<LedgerEntry>>;
+        /**
+         * `GET /billing/history` — the credits the organization received and its payments, newest
+         * first (one page). `kind` narrows it to `credits` or `payments`; feed `nextCursor` back as
+         * `cursor` until it is `null`. An owner's key.
+         */
+        historyPage: (opts?: {
+            kind?: BillingHistoryKind;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<BillingHistoryEntry>>;
         /** `POST /billing/checkout` — the hosted page that puts a card on file. */
         checkout: () => Promise<{
             url: string;
@@ -2400,6 +2459,18 @@ export declare class PromigenceClient {
             onData?: (data: Uint8Array) => void;
             onExit?: (exit: PtyExit) => void;
             timeoutMs?: number;
+            /** Pick the same terminal up again when its connection drops or the service is updated;
+             *  see `PtyConnectOpts.resume`. Default: on. */
+            resume?: boolean;
+            /** Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+             *  terminal cannot be picked up again; see `PtyConnectOpts.reconnect`. Default: on without
+             *  `cmd`, off with one. */
+            reconnect?: boolean;
+            /** Called after each reconnect: `resumed` says whether it is the same terminal or a new
+             *  shell. */
+            onReconnected?: (how: {
+                resumed: boolean;
+            }) => void;
         }) => Promise<PtySession>;
         /** `GET /sandboxes/:id`. */
         get: (sandboxId: string) => Promise<SandboxRecord>;
@@ -2475,6 +2546,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 +2562,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 +2699,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 +2813,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 +2960,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

@@ -2,8 +2,8 @@ import { readFileSync, statSync } from "node:fs";
 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 { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, ServiceRestartError, 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 { buildBundle } from "./bundle.js";
 import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
 import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.js";
 import { connectPty } from "./pty.js";
@@ -135,7 +135,7 @@ function decodeCredentials(buf) {
         return buf.subarray(3).toString("utf8");
     return buf.toString("utf8");
 }
-export function storedCredentials(env = process.env) {
+export function storedCredentials(env = process.env, platform = process.platform) {
     const path = credentialsPath(env);
     let present = true;
     try {
@@ -145,7 +145,7 @@ export function storedCredentials(env = process.env) {
         present = e.code !== "ENOENT";
     }
     if (!present) {
-        const store = keychainStore(env);
+        const store = keychainStore(env, platform);
         if (store === undefined)
             return undefined;
         const r = keychainReadCached(store, path, env);
@@ -259,8 +259,6 @@ export function keyOrigin(env = process.env) {
     const stored = readCredentialsWithStore(env);
     if (stored.creds.api_key)
         return stored.store === "macos-keychain" ? "macOS Keychain" : stored.store === "secret-service" ? "Secret Service keyring" : "credentials file";
-    if (compatApiKey(env["E2B_API_KEY"]))
-        return "E2B_API_KEY (compat)";
     return undefined;
 }
 function resolveCredentials(opts, env = process.env) {
@@ -269,17 +267,19 @@ function resolveCredentials(opts, env = process.env) {
         const t = u.replace(/\/+$/, "");
         return /^https?:\/\/[^/?#]+$/i.test(t) ? `${t}/v1` : t;
     };
-    const { creds, store } = readCredentialsWithStore(env);
     const envKey = set(env["PROMIGENCE_API_KEY"]?.trim());
     const envUrl = set(env["PROMIGENCE_API_URL"]);
     const optKey = opts.apiKey?.trim();
+    const given = optKey !== undefined || envKey !== undefined;
+    const { creds, store } = given
+        ? { creds: {}, store: undefined }
+        : readCredentialsWithStore(env);
     const source = optKey !== undefined ? "opts" : envKey !== undefined ? "env" : creds.api_key !== undefined ? "file" : undefined;
     const ours = optKey ?? envKey ?? creds.api_key;
-    const compat = ours === undefined ? compatApiKey(env["E2B_API_KEY"]) : undefined;
-    const compatUrl = compat === undefined
-        ? undefined
-        : apiUrlFromCompatUrl(env["E2B_API_URL"]) ?? apiUrlFromCompatDomain(env["E2B_DOMAIN"]);
-    const fromFile = trim(creds.api_url ?? compatUrl ?? DEFAULT_API_URL);
+    const fallback = ours === undefined ? opts.fallbackKey : undefined;
+    const fallbackKey = set(fallback?.apiKey.trim());
+    const fallbackUrl = fallbackKey === undefined ? undefined : set(fallback?.apiUrl);
+    const fromFile = trim(creds.api_url ?? fallbackUrl ?? DEFAULT_API_URL);
     const fromEnv = envUrl !== undefined ? trim(envUrl) : fromFile;
     const apiUrl = opts.apiUrl !== undefined ? trim(opts.apiUrl) : fromEnv;
     const paired = source === "file" ? fromFile : source === "env" ? fromEnv : apiUrl;
@@ -291,10 +291,10 @@ function resolveCredentials(opts, env = process.env) {
             : "Pass apiKey together with apiUrl, or set PROMIGENCE_API_URL to that URL instead of passing apiUrl.");
         return { apiKey: undefined, apiUrl, refusal };
     }
-    const key = ours ?? compat;
+    const key = ours ?? fallbackKey;
     if (key) {
         const from = source === "opts" ? "the apiKey option" : source === "env" ? "PROMIGENCE_API_KEY"
-            : source === "file" ? storedName(store, env) : "E2B_API_KEY";
+            : source === "file" ? storedName(store, env) : fallback.from;
         const refusal = keyRefusal(key, from);
         if (refusal)
             return { apiKey: undefined, apiUrl, refusal };
@@ -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/' } }.");
@@ -644,6 +652,7 @@ export function errorFor(code, message, fix, extra = {}) {
         case "invalid_argument":
             return attach(new InvalidArgumentError(message, extra.cli ? fix : withoutCliHelp(fix), code));
         case "not_released": return attach(new NotReleasedError(message));
+        case "service_restart": return attach(new ServiceRestartError(message, fix));
         default:
             if (ENV_CODES.has(code) || extra.category === "env")
                 return attach(new EnvFailedError(code, message, fix));
@@ -1207,12 +1216,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 }),
         });
@@ -1248,6 +1259,14 @@ export class PromigenceClient {
             const r = await this.request({ method: "GET", path: `/me/ledger?${pageQuery(limit, 1000, opts.cursor)}` });
             return pageOf(r, "entries", limit);
         },
+        historyPage: async (opts = {}) => {
+            const limit = opts.limit ?? 50;
+            const q = new URLSearchParams(pageQuery(limit, 100, opts.cursor));
+            if (opts.kind !== undefined && opts.kind !== "all")
+                q.set("kind", opts.kind);
+            const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
+            return pageOf(r, "entries", limit);
+        },
         checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
         portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
         referrals: () => this.request({ method: "GET", path: "/referrals" }),
@@ -1742,6 +1761,10 @@ export class PromigenceClient {
                             on.heartbeat?.();
                             continue;
                         }
+                        if (event === "reconnect") {
+                            reader.cancel().catch(() => { });
+                            throw new ServiceRestartError(`a service restart stopped the command on sandbox ${sandboxId} while its output was streaming`, "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe.");
+                        }
                         let parsed = {};
                         try {
                             parsed = JSON.parse(data);
@@ -1977,6 +2000,9 @@ export class PromigenceClient {
                 ...(opts.onData ? { onData: opts.onData } : {}),
                 ...(opts.onExit ? { onExit: opts.onExit } : {}),
                 ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                ...(opts.reconnect === undefined ? {} : { reconnect: opts.reconnect }),
+                ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
                 refuse: (status, text, retryAfter) => {
                     let payload = {};
                     try {
@@ -2414,19 +2440,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.8";
 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";
@@ -190,6 +190,15 @@ export declare class TimeoutError extends PromigenceError {
         runId?: string;
     });
 }
+/**
+ * A service update may stop a command that was running while its output was streaming to you
+ * (`execStream`, `commands.run` with output callbacks); the time it ran is credited back, and the
+ * sandbox keeps running. `retryable` is `false`: the command may have done part of its work before
+ * it stopped, so run it again only if that is safe. exit 3
+ */
+export declare class ServiceRestartError extends PromigenceError {
+    constructor(message: string, fix: string);
+}
 /** An API error with no more specific class (5xx, unknown code). exit from the table. */
 export declare class ApiError extends PromigenceError {
 }

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.8";
 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";
@@ -194,6 +194,11 @@ export class TimeoutError extends PromigenceError {
         this.runId = ids.runId;
     }
 }
+export class ServiceRestartError extends PromigenceError {
+    constructor(message, fix) {
+        super({ code: "service_restart", message, fix, exitCode: 3, category: "env", retryable: false });
+    }
+}
 export class ApiError extends PromigenceError {
 }
 export class NotReleasedError extends PromigenceError {
@@ -210,6 +215,7 @@ export const EXIT_BY_CODE = {
     invalid_argument: 2, unsupported: 2, not_released: 1, task_failed: 4,
     env_failed: 3, snapshot_rejected: 6, build_failed: 3, snapshot_failed: 4,
     not_connected: 7,
+    service_restart: 3,
     fork_failed: 3, start_timeout: 3, readiness_failed: 3, verify_too_slow: 3,
     verify_each_failed: 3, toolchain_mismatch: 3, sandbox_unresponsive: 3, oom_within_tier: 3,
     disk_full_within_tier: 3, sandbox_interrupted: 3, integrity_mismatch: 3, egress_unavailable: 3,
@@ -226,7 +232,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,
@@ -236,10 +242,11 @@ export const EXIT_BY_CODE = {
     build_timeout: 4,
     image_unresolvable: 2,
     registry_unavailable: 3,
-    trial_credits_exhausted: 5, card_required: 5, credit_unclaimed: 5, concurrency_limit: 5, egress_cap_reached: 10,
+    trial_credits_exhausted: 5, card_required: 5, credit_unclaimed: 5, concurrency_limit: 5, egress_cap_reached: 5,
     billing_unavailable: 5,
     project_cap_reached: 5,
     spend_limit_reached: 5,
+    billing_hold: 5,
     tier_over_plan: 2,
     network_host_refused: 9, network_policy_unsupported: 3,
     secrets_in_snapshot: 2, secrets_unavailable: 3,
@@ -251,6 +258,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/credstore.d.ts

@@ -3,7 +3,8 @@
  * the credentials file (`~/.config/promigence/credentials`, 0600). The CLI writes it
  * (`promigence login`, `promigence auth login`, `promigence logout`); the CLI and both SDKs read it.
  *
- *   macOS            the login Keychain, through `security` (when HOME holds one)
+ *   macOS            the login Keychain, through `security` (when the user's home holds one: HOME,
+ *                    or the account's own home when the environment has no HOME)
  *   Linux and BSD    the Secret Service (GNOME Keyring, KWallet), through `secret-tool`, when a
  *                    desktop session bus is there (a CI job or an SSH shell has none: the file)
  *   Windows          the file: no tool that ships with Windows can read a stored secret back
@@ -34,7 +35,7 @@ export declare function storeLabel(store: CredentialStore, path?: string): strin
  * The keychain this process stores a sign-in in, or undefined for the file. `auto` is decided by
  * the platform and by whether its tool (and, for the Secret Service, a session bus) is there.
  */
-export declare function keychainStore(env?: NodeJS.ProcessEnv, platform?: string): KeychainStore | undefined;
+export declare function keychainStore(env?: NodeJS.ProcessEnv, platform?: string, home?: () => string): KeychainStore | undefined;
 /**
  * The keychains a sign-out (or a sign-in that lands in the file) must clear for this path: the one
  * in use, and the platform's own even when `PROMIGENCE_CREDENTIAL_STORE=file` (an item a previous

package/dist/credstore.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 export const KEYCHAIN_SERVICE = "promigence-cli";
 const KEYCHAIN_LABEL = "Promigence CLI credentials";
@@ -30,8 +31,19 @@ function sessionBus(env) {
     const run = env["XDG_RUNTIME_DIR"];
     return Boolean(run) && existsSync(join(run, "bus"));
 }
+function userHome(env, home = homedir) {
+    const h = env["HOME"];
+    if (h)
+        return h;
+    try {
+        return home() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const warnedSetting = new Set();
-export function keychainStore(env = process.env, platform = process.platform) {
+export function keychainStore(env = process.env, platform = process.platform, home = homedir) {
     const raw = (env["PROMIGENCE_CREDENTIAL_STORE"] ?? "").trim().toLowerCase();
     switch (raw) {
         case "file": return undefined;
@@ -46,8 +58,8 @@ export function keychainStore(env = process.env, platform = process.platform) {
             }
     }
     if (platform === "darwin") {
-        const home = env["HOME"];
-        return home && existsSync(join(home, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
+        const h = userHome(env, home);
+        return h && existsSync(join(h, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
     }
     if (platform === "win32")
         return undefined;
@@ -94,8 +106,9 @@ function runTool(store, args, env, input, timeout) {
     const bin = onPath(toolName(store), env);
     if (bin === undefined)
         throw Object.assign(new Error(`${toolName(store)} not found`), { code: "ENOENT" });
+    const h = store === "macos-keychain" && !env["HOME"] ? userHome(env) : undefined;
     return execFileSync(bin, args, {
-        encoding: "utf8", timeout, env,
+        encoding: "utf8", timeout, env: h ? { ...env, HOME: h } : env,
         ...(input === undefined ? { stdio: ["ignore", "pipe", "pipe"] } : { input, stdio: ["pipe", "pipe", "pipe"] }),
     });
 }