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

package/dist/client.d.ts

@@ -2,6 +2,7 @@
 import { inspect, type InspectOptions } from "node:util";
 import { PromigenceError, type CommandResult, type NetworkMode, type OptimizeFor, type Tier } from "./core.js";
 import { type Bundle } from "./bundle.js";
+import { type CredentialStore } from "./credstore.js";
 import { type PtyExit, type PtySession } from "./pty.js";
 import { type SshTunnel } from "./ssh.js";
 import type * as M from "./models.gen.js";
@@ -280,6 +281,10 @@ export interface ReportSandbox extends QueuedInfo {
     sandbox_id: string;
     state: SandboxState;
     attempt?: number;
+    /** `PROMIGENCE_INDEX`: its place in the run, from 0. Absent when the run's command set it itself. */
+    index?: number;
+    /** `PROMIGENCE_SEED`: the number its commands were given. Absent when the run's command set it itself. */
+    seed?: number;
     queued_ms?: number;
     ready_ms?: number;
     e2e_ms?: number;
@@ -319,11 +324,16 @@ export interface RunReport {
     snapshot_id?: string;
     alias?: string;
     labels?: Record<string, string>;
+    /**
+     * What the run asked for. `network` is `"allow"` for a run behind an allowlist, whose hosts are
+     * `allow` (a service before it said `"egress"` for one).
+     */
     requested?: {
         count: number;
         timeout_ms: number;
         verify_each: boolean;
-        network: NetworkMode;
+        network: NetworkMode | "allow";
+        allow?: string[];
         allow_partial: boolean;
         secrets?: string[];
         grade?: GradeSpec;
@@ -437,13 +447,19 @@ export interface SnapshotBuild {
     repo?: string;
     commit?: string;
     verification?: Record<string, unknown>;
-    /** A rejected build names the guard and the measured value; nothing was stored. */
+    /**
+     * A rejected build names the guard and the measured value; nothing was stored. `log_tail` is
+     * your build's own output: for a step of yours that failed (its start command, a setup step, its
+     * verify), that step's last lines. `fix`, when present, is what to change.
+     */
     error?: {
         code?: string;
         guard?: string;
         message?: string;
         values?: number[];
         stored?: boolean;
+        log_tail?: string[];
+        fix?: string;
     } | null;
     /** Set when an identical build already existed. */
     deduped?: boolean;
@@ -1153,8 +1169,9 @@ export interface SandboxPatchResponse {
 /**
  * What the idle rule counts as idle. `"requests"` (the default): nobody has called the sandbox
  * for the window and no command, terminal or SSH session is open. `"activity"`: all of that, and
- * for the whole window nothing inside used CPU or sent or received a byte, and no network
- * connection to the outside is open — for an agent that runs inside the sandbox on its own.
+ * for the whole window the sandbox used under 5% of one core, sent and received no network byte
+ * (disk writes do not count), and no network connection to the outside is open — for an agent
+ * that runs inside the sandbox on its own.
  */
 export type AutoPauseMode = M.AutoPauseMode;
 /** `POST /snapshots/:id/verify` — re-run the recorded `verify` in a fresh fork. */
@@ -1372,6 +1389,8 @@ export interface PortRecord {
     /** The same token as a DNS label, for a wildcard-DNS deployment (`<label>.<suffix>`). */
     host_url_label?: string;
     created_unix_ns?: number;
+    /** When the URL stops working on its own (`ttl_s`); `null` for one that works until revoked. */
+    expires_unix_ns?: number | null;
 }
 /** A key named without its secret (`/me`'s `key`, the key lists). */
 export interface KeyRef {
@@ -1518,6 +1537,12 @@ export interface PromigenceClientOpts {
      */
     onTiming?: (timing: Timing) => void;
 }
+/** Where a client's key came from: the option, PROMIGENCE_API_KEY (`env`), the stored sign-in, or a fallback. */
+export interface KeyOrigin {
+    source: "option" | "env" | "stored" | "fallback";
+    /** The stored sign-in's store, for `stored`. */
+    store?: CredentialStore;
+}
 /** `GET /sandboxes/:id/network`. */
 export interface SandboxNetwork {
     sandbox_id: string;
@@ -1756,6 +1781,11 @@ export interface SnapshotCreateOpts {
      */
     setupUser?: string;
     alias?: string;
+    /**
+     * With `alias`: take the name from the snapshot that has it, which stays, unnamed. Without it, an
+     * alias another snapshot has is refused (`usage`, 400) and nothing is built.
+     */
+    moveAlias?: boolean;
     /**
      * A DEFAULT grader for this snapshot: a run on it with no `grade` of its own uses this one.
      * The same shape as `runs.start({ grade })`.
@@ -1841,11 +1871,12 @@ export declare function credentialsExposure(path: string): string | undefined;
  * `credentialsTrustProblem`).
  */
 export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials;
-export declare function apiUrlFromCompatUrl(url: string | undefined): string | undefined;
-export declare function apiUrlFromCompatDomain(domain: string | undefined): string | undefined;
-export declare function compatApiKey(key: string | undefined): string | undefined;
 /** Which variable a key came from, for `promigence doctor`. */
 export declare function keyOrigin(env?: NodeJS.ProcessEnv): string | undefined;
+/** A request with no key found anywhere: none passed, none in the environment, none stored. */
+export declare const NO_KEY_MESSAGE = "no API key: none was given, PROMIGENCE_API_KEY is not set, and none is stored";
+/** What a caller of this SDK does about it. */
+export declare const NO_KEY_FIX = "Pass { apiKey } or set PROMIGENCE_API_KEY. No key yet: `promigence login` signs you up or in and stores one.";
 /** `name@sha256:<64 hex>`, optionally with a tag before the `@`: a reference already pinned. */
 export declare const IMAGE_DIGEST_RE: RegExp;
 /**
@@ -2510,6 +2541,10 @@ export declare class PromigenceClient {
         /**
          * Preview URLs for ports inside the sandbox. A URL is a capability — anyone holding it reaches
          * that port — and dies with `revoke`, with a pause, or with the sandbox.
+         *
+         * If your account's preview URLs aren't on, `expose` throws `PreviewsUnavailableError`; write to
+         * support@promigence.ai to have them turned on, and meanwhile reach the port with
+         * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
          */
         ports: {
             expose: (sandboxId: string, port: number) => Promise<PortRecord>;
@@ -3049,8 +3084,14 @@ export declare class PromigenceClient {
             alias?: string | null;
             deleted: boolean;
         }>;
-        /** `PUT /snapshots/:id/alias` — the sidecar's one mutable field. */
-        alias: (idOrAlias: string, alias: string | null) => Promise<SnapshotRecord>;
+        /**
+         * `PUT /snapshots/:id/alias` — the sidecar's one mutable field. A name another snapshot
+         * has is refused (`usage`, 400) unless `moveAlias: true`, which takes it; that one stays,
+         * unnamed.
+         */
+        alias: (idOrAlias: string, alias: string | null, opts?: {
+            moveAlias?: boolean;
+        }) => Promise<SnapshotRecord>;
         /**
          * Wait for a build to leave `running`, bounded by `waitTimeoutMs` (default 100 s).
          *

package/dist/client.js

@@ -2,7 +2,7 @@ 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, 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 { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, ServiceRestartError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, SANDBOX_ENDED_FIX, SandboxEndedError, errorsDocsFor, exitForCode, previewsOff, sandboxEndedIn, withPreviewsFix, } from "./core.js";
 import { buildBundle } from "./bundle.js";
 import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
 import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.js";
@@ -276,30 +276,6 @@ export function readCredentials(env = process.env) {
 function storedName(store, env) {
     return store === undefined || store === "file" ? `the credentials file (${credentialsPath(env)})` : storeLabel(store);
 }
-const COMPAT_REFUSED_HOSTS = /(^|\.)e2b(-staging)?\.(app|dev|pro)$/i;
-export function apiUrlFromCompatUrl(url) {
-    const u = (url ?? "").trim();
-    if (!u)
-        return undefined;
-    let host = "";
-    try {
-        host = new URL(u.includes("://") ? u : `https://${u}`).hostname;
-    }
-    catch {
-        return undefined;
-    }
-    return COMPAT_REFUSED_HOSTS.test(host) ? undefined : u;
-}
-export function apiUrlFromCompatDomain(domain) {
-    const d = (domain ?? "").trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
-    if (!d || COMPAT_REFUSED_HOSTS.test(d))
-        return undefined;
-    return `https://api.${d}/v1`;
-}
-export function compatApiKey(key) {
-    const k = key?.trim();
-    return k && !k.startsWith("e2b_") ? k : undefined;
-}
 export function keyOrigin(env = process.env) {
     if (env["PROMIGENCE_API_KEY"]?.trim())
         return "PROMIGENCE_API_KEY";
@@ -326,12 +302,13 @@ function resolveCredentials(opts, env = process.env) {
     const inputs = optKey === undefined && envKey === undefined
         ? undefined
         : `${optKey ?? "\0"}\n${envKey ?? "\0"}\n${envUrl ?? "\0"}\n${opts.apiUrl ?? "\0"}`;
-    if (inputs !== undefined && inputs === credsLastInputs && credsLast !== undefined)
-        return { apiKey: credsLast.apiKey, apiUrl: credsLast.apiUrl };
+    if (inputs !== undefined && inputs === credsLastInputs && credsLast !== undefined) {
+        return { apiKey: credsLast.apiKey, apiUrl: credsLast.apiUrl, ...(credsLast.origin ? { origin: credsLast.origin } : {}) };
+    }
     const worked = resolveCredentialsFrom(opts, env, set, trim, optKey, envKey, envUrl);
     if (inputs !== undefined && worked.refusal === undefined) {
         credsLastInputs = inputs;
-        credsLast = { apiKey: worked.apiKey, apiUrl: worked.apiUrl };
+        credsLast = { apiKey: worked.apiKey, apiUrl: worked.apiUrl, ...(worked.origin ? { origin: worked.origin } : {}) };
     }
     return worked;
 }
@@ -365,8 +342,15 @@ function resolveCredentialsFrom(opts, env, set, trim, optKey, envKey, envUrl) {
         if (refusal)
             return { apiKey: undefined, apiUrl, refusal };
     }
-    return { apiKey: key, apiUrl };
+    const origin = !key ? undefined
+        : source === "opts" ? { source: "option" }
+            : source === "env" ? { source: "env" }
+                : source === "file" ? { source: "stored", ...(store === undefined ? {} : { store }) }
+                    : { source: "fallback" };
+    return { apiKey: key, apiUrl, ...(origin ? { origin } : {}) };
 }
+export const NO_KEY_MESSAGE = "no API key: none was given, PROMIGENCE_API_KEY is not set, and none is stored";
+export const NO_KEY_FIX = "Pass { apiKey } or set PROMIGENCE_API_KEY. No key yet: `promigence login` signs you up or in and stores one.";
 function keyRefusal(key, from) {
     if (/^[\x21-\x7E]+$/.test(key))
         return undefined;
@@ -646,6 +630,8 @@ export function snapshotCreateBody(opts) {
     }
     if (o.alias)
         body["alias"] = o.alias;
+    if (o.alias && o.moveAlias)
+        body["move_alias"] = true;
     if (o.grade) {
         if (!o.grade.cmd)
             throw new InvalidArgumentError("snapshots.create grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
@@ -680,6 +666,9 @@ const REFUSED_503_CODES = new Set([
     "builder_unavailable", "builder_busy", "overloaded", "tier_unavailable", "registry_unavailable",
     "secrets_unavailable",
 ]);
+const SDK_FIXES = {
+    cap_exceeded: "Raise `spendCap`, lower `timeoutMs` or `count`, or pass `allowPartial` to launch what fits.",
+};
 function withoutCliHelp(fix) {
     const out = fix.replace(/\s*See `promigence [^`]*--help`\.?\s*$/, "").trim();
     if (out === fix.trim())
@@ -689,7 +678,7 @@ function withoutCliHelp(fix) {
 export function errorFor(code, message, fix, extra = {}) {
     const attach = (e) => {
         const w = e;
-        w.docs = extra.docs ?? `${ERRORS_DOCS_URL}#${code}`;
+        w.docs = extra.docs !== undefined && e.code === code ? extra.docs : errorsDocsFor(e.code);
         if (extra.status !== undefined)
             w.status = extra.status;
         if (extra.requestId !== undefined)
@@ -705,6 +694,8 @@ export function errorFor(code, message, fix, extra = {}) {
     if ((code === "usage" || code === "invalid_argument" || code === "unsupported") && previewsOff(message)) {
         return attach(new PreviewsUnavailableError());
     }
+    if (!extra.cli && Object.prototype.hasOwnProperty.call(SDK_FIXES, code))
+        fix = SDK_FIXES[code];
     switch (code) {
         case "auth": return attach(new AuthError(message, fix));
         case "not_found": return attach(new NotFoundError(message, fix));
@@ -718,8 +709,13 @@ export function errorFor(code, message, fix, extra = {}) {
         case "not_verified": return attach(new NotVerifiedError(message, fix));
         case "timeout": return attach(new TimeoutError(message, fix));
         case "usage":
-        case "invalid_argument":
+        case "invalid_argument": {
+            const ended = code === "usage" ? sandboxEndedIn(message) : undefined;
+            if (ended !== undefined) {
+                return attach(new SandboxEndedError(message, ended.sandboxId, ended.state, extra.cli ? fix : SANDBOX_ENDED_FIX));
+            }
             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:
@@ -790,6 +786,21 @@ const WAIT_MS_CAP = 30_000;
 export const LONG_POLL_MS = 5_000;
 const BUILD_POLL_MS = 10_000;
 const PROGRESS_POLL_MS = 200;
+export const RUN_SETTLE_MS = 5_000;
+export function runWorkDone(run, endedSince, now = Date.now()) {
+    if (run.state === "completed" || run.state === "cap_killed" || run.state === "aborted")
+        return true;
+    const sbs = Array.isArray(run.sandboxes) ? run.sandboxes : [];
+    const allDone = sbs.length > 0 && sbs.every((s) => s.state === "ended" || s.command_outcome != null);
+    if (!allDone) {
+        delete endedSince.at;
+        return false;
+    }
+    if (sbs.some((s) => s.state !== "ended"))
+        return true;
+    endedSince.at ??= now;
+    return now - endedSince.at >= RUN_SETTLE_MS;
+}
 const WAITED_HEADER = "promigence-waited-ms";
 const seg = (s) => encodeURIComponent(s).replace(/%40/g, "@");
 function waitQuery(waitMs) {
@@ -827,6 +838,9 @@ export class PromigenceClient {
     apiUrl;
     #apiKey;
     #keyRefusal;
+    #keyOrigin;
+    #onKeyUse;
+    #keyUseSaid = false;
     #bearer;
     fetchImpl;
     ownFetch;
@@ -848,6 +862,8 @@ export class PromigenceClient {
         const resolved = resolveCredentials(opts);
         this.#apiKey = resolved.apiKey;
         this.#keyRefusal = resolved.refusal;
+        this.#keyOrigin = resolved.origin;
+        this.#onKeyUse = opts.onKeyUse;
         this.apiUrl = resolved.apiUrl;
         const env = opts.fetch === undefined ? transportEnv() : undefined;
         const proxy = env !== undefined ? proxyFor(this.apiUrl, env) : undefined;
@@ -913,11 +929,18 @@ export class PromigenceClient {
         catch {
         }
     }
+    get keyOrigin() {
+        return this.#keyOrigin;
+    }
     requireKey() {
         if (this.#keyRefusal)
             throw this.#keyRefusal;
         if (!this.#apiKey)
-            throw new AuthError();
+            throw this.cliErrors ? new AuthError(NO_KEY_MESSAGE) : new AuthError(NO_KEY_MESSAGE, NO_KEY_FIX);
+        if (!this.#keyUseSaid && this.#onKeyUse !== undefined && this.#keyOrigin !== undefined) {
+            this.#keyUseSaid = true;
+            this.#onKeyUse(this.#keyOrigin);
+        }
         return this.#apiKey;
     }
     bearer() {
@@ -1239,10 +1262,12 @@ export class PromigenceClient {
                 continue;
             }
             const code = payload.error?.code ?? codeForStatus(res.status);
+            const rid = headerOf(res, "request-id") ?? headerOf(res, "x-request-id");
             throw errorFor(code, payload.error?.message ?? `HTTP ${res.status} from ${method} ${path}`, payload.error?.fix ?? "See the API response for details.", {
                 status: res.status,
                 ...bodyExtra(payload),
                 ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                ...(rid ? { requestId: rid } : {}),
             });
         }
     }
@@ -1322,10 +1347,12 @@ export class PromigenceClient {
                 continue;
             }
             const code = payload.error?.code ?? codeForStatus(res.status);
+            const rid = headerOf(res, "request-id") ?? headerOf(res, "x-request-id");
             throw errorFor(code, payload.error?.message ?? `HTTP ${res.status} from ${method} ${path}`, payload.error?.fix ?? "See the API response for details.", {
                 status: res.status,
                 ...bodyExtra(payload),
                 ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                ...(rid ? { requestId: rid } : {}),
             });
         }
     }
@@ -1701,12 +1728,8 @@ export class PromigenceClient {
                 return { sandboxes: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
             },
             waitDone: async (runId, opts = {}) => {
-                const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => {
-                    const terminal = run.state === "completed" || run.state === "cap_killed" || run.state === "aborted";
-                    const allDone = Array.isArray(run.sandboxes) && run.sandboxes.length > 0 &&
-                        run.sandboxes.every((s) => s.state === "ended" || s.command_outcome != null);
-                    return terminal || allDone;
-                });
+                const endedSince = {};
+                const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => runWorkDone(run, endedSince));
                 return { run: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
             },
         };
@@ -2115,10 +2138,19 @@ export class PromigenceClient {
                     }), sandboxId);
                     return r.ports ?? [];
                 },
-                revoke: (sandboxId, tokenOrPort) => this.request({
-                    method: "DELETE",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${encodeURIComponent(String(tokenOrPort))}`,
-                }),
+                revoke: (sandboxId, tokenOrPort) => {
+                    const which = String(tokenOrPort).trim();
+                    return /^[0-9]+$/.test(which)
+                        ? this.request({
+                            method: "DELETE",
+                            path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${which}`,
+                        })
+                        : this.request({
+                            method: "POST",
+                            path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/revoke`,
+                            body: { token: which },
+                        });
+                },
             },
             ssh: {
                 open: (sandboxId, opts) => {
@@ -2615,10 +2647,10 @@ export class PromigenceClient {
                     throw new InvalidArgumentError("snapshots.delete needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
                 return this.request({ method: "DELETE", path: `/snapshots/${seg(idOrAlias)}` });
             },
-            alias: (idOrAlias, alias) => this.request({
+            alias: (idOrAlias, alias, opts = {}) => this.request({
                 method: "PUT",
                 path: `/snapshots/${seg(idOrAlias)}/alias`,
-                body: { alias },
+                body: { alias, ...(alias !== null && opts.moveAlias ? { move_alias: true } : {}) },
             }),
             waitBuild: async (buildId, opts = {}) => {
                 const r = await this.waitLoop(opts, BUILD_POLL_MS, { build_id: buildId, state: "running" }, (read) => this.snapshots.status(buildId, read), (b) => b.state !== "running" && b.state !== "queued");

package/dist/command-errors.d.ts

@@ -18,6 +18,7 @@ export declare class CommandTimeoutError extends CommandExitError {
     readonly code: string;
     readonly fix: string;
     readonly guide: string;
+    readonly docs: string;
     constructor(result: CommandResult, timeoutMs: number | undefined);
 }
 /**

package/dist/command-errors.js

@@ -1,4 +1,4 @@
-import { CommandExitError } from "./core.js";
+import { CommandExitError, errorsDocsFor } from "./core.js";
 import { hintArg } from "./hint.js";
 export function secondsText(ms) {
     const s = ms / 1000;
@@ -10,9 +10,11 @@ export class CommandTimeoutError extends CommandExitError {
     code;
     fix;
     guide;
+    docs;
     constructor(result, timeoutMs) {
         super(result);
         this.code = "task_timeout";
+        this.docs = errorsDocsFor(this.code);
         this.timeoutMs = timeoutMs;
         this.message = timeoutMs === undefined
             ? `command timed out (killed at its timeout, exit ${result.exitCode})`

package/dist/context.d.ts

@@ -15,9 +15,11 @@
  * - Empty directories and permission bits travel as they are on disk; a set-user-ID or
  *   set-group-ID bit is cleared, with a note.
  * - Files that look like credentials (`.env`, private keys, cloud credentials, ...) are refused,
- *   by name, unless `allowSecrets` says otherwise. The check goes by file name: it is
- *   best-effort and cannot see what a file holds, so look over the list (`listContext`) before
- *   you send a directory.
+ *   by name, unless `allowSecretFiles` names them (each one) or `allowSecrets` says otherwise. The
+ *   check goes by file name and reads only two kinds of file, to clear the plain false
+ *   positives: a `.pem` holding certificates or public keys and no private key, and an `.npmrc`
+ *   with no token or password in it. It is best-effort, so look over the list (`listContext`)
+ *   before you send a directory.
  * - Symbolic links travel as links, never as the file they point at.
  */
 /** The prefix a packed directory travels under in `dockerfile.context`. */
@@ -65,9 +67,17 @@ export declare function dockerignoreMatcher(text: string): {
 /**
  * Does this path look like a credential (`.env`, a private key, cloud or registry credentials, a
  * token file, ...)? By name only: best-effort, it cannot see what a file holds. Templates such as
- * `.env.example` are not.
+ * `.env.example` are not. [`secretLikeFile`] also reads the few files whose contents can clear them.
  */
 export declare function secretLike(path: string): boolean;
+/** The most of a file [`secretLikeFile`] reads; a larger one is judged by its name alone. */
+export declare const CONTENT_CHECK_MAX_BYTES: number;
+/**
+ * [`secretLike`] for a file on disk at `abs` (`rel` is its path in the upload): a name that looks
+ * like a credential, unless what the file holds clears it ([`clearedByContent`]). A link, a file
+ * over [`CONTENT_CHECK_MAX_BYTES`] and a file that cannot be read keep the name's verdict.
+ */
+export declare function secretLikeFile(rel: string, abs: string): boolean;
 /** What a build context is packed from and sent with. */
 export interface ContextOptions {
     /**
@@ -84,6 +94,11 @@ export interface ContextOptions {
      * nothing is sent.
      */
     allowSecrets?: boolean;
+    /**
+     * Send these files that look like credentials, and only these: paths inside the context,
+     * `/`-separated, as `listContext` names them. Every other one is still refused.
+     */
+    allowSecretFiles?: readonly string[];
     /** Called with each note: what was left out by default, or changed on the way. */
     onNote?: (note: string) => void;
 }

package/dist/context.js

@@ -387,6 +387,74 @@ export function secretLike(path) {
         return false;
     return SECRET_NAMES.some((re) => re.test(name));
 }
+export const CONTENT_CHECK_MAX_BYTES = 1024 * 1024;
+const PUBLIC_PEM = new Set([
+    "CERTIFICATE", "TRUSTED CERTIFICATE", "X509 CERTIFICATE", "X509 CRL", "CERTIFICATE REQUEST",
+    "NEW CERTIFICATE REQUEST", "PUBLIC KEY", "RSA PUBLIC KEY", "PKCS7", "CMS", "DH PARAMETERS",
+    "X9.42 DH PARAMETERS", "EC PARAMETERS",
+]);
+function publicPem(text) {
+    if (/private[\s_-]*key/i.test(text))
+        return false;
+    const types = [...text.matchAll(/-----BEGIN ([^\r\n-]+)-----/g)].map((m) => m[1].trim().toUpperCase());
+    if (types.length === 0 || !types.every((t) => PUBLIC_PEM.has(t)))
+        return false;
+    const outside = text.replace(/-----BEGIN ([^\r\n-]+)-----[\s\S]*?-----END \1-----/g, "");
+    if (/-----(BEGIN|END) /.test(outside))
+        return false;
+    return !outside.split(/\r?\n/).some((l) => /^(?=.*[A-Za-z0-9+/])[A-Za-z0-9+/=]{40,}$/.test(l.trim()));
+}
+const NPMRC_CREDENTIAL = /_auth|token|passw|secret|credential|certfile|keyfile|otp|username/i;
+function npmrcWithoutCredentials(text) {
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim().replace(/^[;#]+\s*/, "");
+        if (!line)
+            continue;
+        if (NPMRC_CREDENTIAL.test(line) || /:\/\/[^\s/]*@/.test(line))
+            return false;
+        const eq = line.indexOf("=");
+        const key = (eq < 0 ? line : line.slice(0, eq)).trim();
+        const own = key.startsWith("//") ? key.slice(key.lastIndexOf(":") + 1) : key;
+        if (/^(key|cert|email)$/i.test(own.trim()))
+            return false;
+    }
+    return true;
+}
+export function clearedByContent(path, content) {
+    const name = path.split("/").filter(Boolean).pop() ?? "";
+    let text;
+    if (typeof content === "string") {
+        text = content;
+    }
+    else {
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+        }
+        catch {
+            return false;
+        }
+    }
+    if (text.includes("\u0000"))
+        return false;
+    if (/\.pem$/i.test(name))
+        return publicPem(text);
+    if (/^\.npmrc$/i.test(name))
+        return npmrcWithoutCredentials(text);
+    return false;
+}
+export function secretLikeFile(rel, abs) {
+    if (!secretLike(rel))
+        return false;
+    try {
+        const st = lstatSync(abs);
+        if (!st.isFile() || st.size > CONTENT_CHECK_MAX_BYTES)
+            return true;
+        return !clearedByContent(rel, readFileSync(abs));
+    }
+    catch {
+        return true;
+    }
+}
 function namedList(items) {
     const more = items.length > NAMED ? ` and ${items.length - NAMED} more` : "";
     return items.slice(0, NAMED).join(", ") + more;
@@ -395,7 +463,7 @@ export function credentialRefusalMessage(hits) {
     const one = hits.length === 1;
     return `${hits.length} file${one ? " looks" : "s look"} like ${one ? "a credential" : "credentials"} and ${one ? "was" : "were"} not uploaded: ${namedList(hits)}; nothing was created`;
 }
-export const CREDENTIAL_CHECK_NOTE = "The check goes by file name and is best-effort: it cannot see what a file holds, so look over what you send.";
+export const CREDENTIAL_CHECK_NOTE = "The check goes by file name and is best-effort: it reads only a .pem (one with no private key passes) and an .npmrc (one with no token or password passes), so look over what you send.";
 function insidePath(p) {
     return goClean(p.split(sep).join("/").replace(/^\.\/+/, ""));
 }
@@ -495,7 +563,7 @@ function collect(dir, opts) {
     if (special.length > 0) {
         notes.push(`Left out ${namedList(special)}: a socket, device or pipe; a build context holds only files, directories and links.`);
     }
-    const secrets = entries.filter((e) => e.kind === "file" && secretLike(e.rel)).map((e) => e.rel);
+    const secrets = entries.filter((e) => e.kind === "file" && secretLikeFile(e.rel, e.abs)).map((e) => e.rel);
     return { entries, bytes, notes, secrets, ignore };
 }
 export function listContext(dir, opts = {}) {
@@ -518,8 +586,10 @@ export function packContext(dir, opts = {}) {
         const ig = c.ignore?.file;
         throw new InvalidArgumentError(`the build context is over ${max} bytes${ig ? ` even without what its ${ig} excludes` : ""}`, `${ig ? `Exclude more in ${ig}` : "Add a .dockerignore"}, point --context at a smaller directory, or pass a git URL pinned to a full 40-character sha.`);
     }
-    if (c.secrets.length > 0 && !opts.allowSecrets) {
-        throw new InvalidArgumentError(credentialRefusalMessage(c.secrets), `A snapshot keeps every file it holds, and every sandbox started from it has them. Exclude them in ${c.ignore?.file ?? ".dockerignore"}, pass the values as secrets, or pass { allowSecrets: true } if they are not real credentials. ${CREDENTIAL_CHECK_NOTE}`);
+    const allowed = new Set((opts.allowSecretFiles ?? []).map(insidePath));
+    const refused = c.secrets.filter((s) => !allowed.has(s));
+    if (refused.length > 0 && !opts.allowSecrets) {
+        throw new InvalidArgumentError(credentialRefusalMessage(refused), `A snapshot keeps every file it holds, and every sandbox started from it has them. Exclude them in ${c.ignore?.file ?? ".dockerignore"}, pass the values as secrets, or name each that is not a real credential in { allowSecretFiles: [...] } ({ allowSecrets: true } for all of them). ${CREDENTIAL_CHECK_NOTE}`);
     }
     if (c.entries.length === 0) {
         throw new InvalidArgumentError(`the build context ${JSON.stringify(dir)} is empty`, "Point --context at the directory holding your Dockerfile.");

package/dist/core.d.ts

@@ -1,8 +1,10 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.15";
+export declare const VERSION = "0.1.0-beta.16";
 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";
+/** The row of `code` in the error reference. */
+export declare function errorsDocsFor(code: string): string;
 export declare const DEFAULT_API_URL = "https://api.promigence.ai/v1";
 /** Where to write about a key. A key is self-serve: `promigence login` signs up or in and stores one. */
 export declare const KEY_CONTACT = "support@promigence.ai";
@@ -43,8 +45,8 @@ export interface PromigenceErrorInit {
     /** The API error's `retryable`: nothing ran and the same request, sent again as is, can succeed. */
     retryable?: boolean;
 }
-/** What a caller reads instead: a fact about this beta, not a mistake of theirs. */
-export declare const PREVIEWS_UNAVAILABLE = "preview URLs are not available in this beta yet";
+/** What a caller reads instead: a fact about their account, not a mistake of theirs. */
+export declare const PREVIEWS_UNAVAILABLE = "preview URLs are not turned on for this account";
 export declare function previewsFix(sandboxId?: string, port?: string | number): string;
 /**
  * A `fix` that opens by repeating the message says only what it adds: the API's `usage` fix is
@@ -97,7 +99,13 @@ export declare class PromigenceError extends Error {
         guide: string;
     };
 }
-/** Bad arguments (e.g. an unknown template, a missing spend cap). exit 2 */
+/**
+ * Bad arguments (e.g. an unknown template, a missing spend cap). exit 2
+ *
+ * `code` says who refused: `invalid_argument` is the SDK, before anything was sent; `usage` is the
+ * API, refusing what it was sent. Nothing ran and nothing was billed either way, so catch this
+ * class (or exit 2) to handle both.
+ */
 export declare class InvalidArgumentError extends PromigenceError {
     /**
      * `code` defaults to `invalid_argument` — what the SDK raises for a bad argument it catches
@@ -122,6 +130,26 @@ export declare function previewsOff(message: string): boolean;
 export declare class PreviewsUnavailableError extends InvalidArgumentError {
     constructor(sandboxId?: string, port?: string | number);
 }
+/** The sandbox and its state when an API message is the "has ended" refusal, else `undefined`. */
+export declare function sandboxEndedIn(message: string): {
+    sandboxId: string;
+    state: string;
+} | undefined;
+/** What a caller of this SDK does about an ended sandbox. */
+export declare const SANDBOX_ENDED_FIX = "Start a new sandbox: Sandbox.create(). This one's getInfo() says how it ended (`outcome`).";
+/**
+ * A call to a sandbox that has ended (`state` `ended` or `failed`): it does not come back. Still an
+ * `InvalidArgumentError` with code `usage` and exit 2, as the API answers it, so a catch written
+ * against earlier releases still catches it; catch this class to tell an ended sandbox from a bad
+ * argument. `sandboxId` and `state` name the sandbox and how it stands.
+ */
+export declare class SandboxEndedError extends InvalidArgumentError {
+    /** The sandbox that has ended. */
+    readonly sandboxId: string;
+    /** Its state: `ended`, or `failed` for one that ended on a failure. */
+    readonly state: string;
+    constructor(message: string, sandboxId: string, state: string, fix?: string);
+}
 /** The environment failed (our fault, never the task's). exit 3 */
 export declare class EnvFailedError extends PromigenceError {
     constructor(code: string, message: string, fix: string);