promigence 0.1.0-beta.12

package/dist/errfix.js

@@ -0,0 +1,262 @@
+import { PREVIEWS_UNAVAILABLE, previewsFix } from "./sdk/index.js";
+import { findCommand } from "./surface.js";
+import { duration } from "./report.js";
+import { sh } from "./term.js";
+const SUPPORT = "support@promigence.ai";
+const SDK_CALL = /^(?:secrets|snapshots|sandboxes|runs|execs|files|billing|keys|ports|images|orgs|projects|captures|referrals|credits)(?:\.[a-zA-Z]+)+:?\s/;
+function reworded(e, fix, message = e.message) {
+    if (fix === e.fix && message === e.message)
+        return e;
+    const out = Object.create(Object.getPrototypeOf(e));
+    Object.assign(out, e);
+    out.fix = fix;
+    Object.defineProperty(out, "message", { value: message, writable: true, configurable: true, enumerable: false });
+    return out;
+}
+export function notFoundKind(message) {
+    const m = /^(.+?) `([^`]*)` not found$/.exec(message.trim());
+    return m ? { kind: m[1].toLowerCase(), id: m[2] } : undefined;
+}
+function notFoundFor(kind, ctx, apiFix) {
+    const sid = ctx.sandbox ?? "SID";
+    switch (kind) {
+        case "snapshot":
+            return undefined;
+        case "ref":
+        case "commit":
+            return {
+                fix: apiFix,
+                next: [{ cmd: "promigence repos", why: "the repositories you can build, each with its default branch" }],
+            };
+        case "exec":
+            return {
+                fix: `Check the exec id: \`${sh `promigence exec ps --sandbox ${sid}`}\` lists the background ones, \`${sh `promigence sandbox info ${sid}`}\` every one.`,
+                next: [{ cmd: sh `promigence exec ps --sandbox ${sid}`, why: "the background execs of this sandbox and their ids" }],
+            };
+        case "sandbox":
+            return {
+                fix: "Check the sandbox id: `promigence sandbox list` shows the live ones, `--state ended` the ones that finished.",
+                next: [{ cmd: "promigence sandbox list", why: "your sandboxes and their ids" }],
+            };
+        case "run":
+            return {
+                fix: "Check the run id: `promigence run list` shows your recent runs.",
+                next: [{ cmd: "promigence run list", why: "your recent runs and their ids" }],
+            };
+        case "capture": {
+            const run = ctx.args[0] ?? "RUN";
+            return {
+                fix: `This run has no preserved failure left (deleted or expired): \`${sh `promigence run captures ${run}`}\` shows what is kept.`,
+                next: [{ cmd: sh `promigence run captures ${run}`, why: "what of this run is still preserved" }],
+            };
+        }
+        case "build":
+            return {
+                fix: "Check the build id: `promigence snapshot builds` shows your recent builds.",
+                next: [{ cmd: "promigence snapshot builds", why: "your recent builds and their ids" }],
+            };
+        case "key":
+            return {
+                fix: "Check the key id: `promigence keys list` shows this organization's keys.",
+                next: [{ cmd: "promigence keys list", why: "the keys and their ids" }],
+            };
+        case "secret":
+            return {
+                fix: "Check the name: `promigence secrets list` shows the secrets stored for this project.",
+                next: [{ cmd: "promigence secrets list", why: "the secrets stored here" }],
+            };
+        case "file":
+            return {
+                fix: `Check the path: \`${sh `promigence files ls DIR --sandbox ${sid}`}\` lists a directory.`,
+                next: [{ cmd: sh `promigence files ls / --sandbox ${sid}`, why: "what is in the sandbox" }],
+            };
+        case "port":
+            return {
+                fix: `Check the port: \`${sh `promigence port list --sandbox ${sid}`}\` shows the published ones.`,
+                next: [{ cmd: sh `promigence port list --sandbox ${sid}`, why: "the published ports" }],
+            };
+        case "referral":
+        case "referral code":
+            return {
+                fix: "Check the code with whoever gave it to you; it is not one this service knows. Your own code is in `promigence referrals`.",
+                next: [{ cmd: "promigence referrals", why: "your own code and your referrals" }],
+            };
+        case "project":
+            return {
+                fix: "Check the project: `promigence project list` shows this organization's projects.",
+                next: [{ cmd: "promigence project list", why: "the projects and their ids" }],
+            };
+        case "org":
+            return {
+                fix: "Check the organization: `promigence org list --all` shows every one you belong to.",
+                next: [{ cmd: "promigence org list", why: "your organizations" }],
+            };
+        case "template":
+            return {
+                fix: "Check the name: `promigence templates` lists every template by name.",
+                next: [{ cmd: "promigence templates", why: "the templates and their names" }],
+            };
+        default:
+            return {
+                fix: "Check the id, and that it belongs to the organization and project of the key you are using (`promigence me`).",
+                next: [{ cmd: "promigence me", why: "which organization this key acts in" }],
+            };
+    }
+}
+const BILLING_CMD = /`promigence billing (?:card|portal)`/;
+export function withoutBilling(text) {
+    return text
+        .replace(/Owners: update the card with `promigence billing portal`; the hold lifts once the invoice is paid\.(?: For a disputed payment, write to support@promigence\.ai\.)?/, `To lift it, email ${SUPPORT}.`)
+        .replace(/,? or move to a plan that allows it: `promigence billing (?:card|portal)`\.?/, `, or email ${SUPPORT} for a plan that allows it.`)
+        .replace(/or add a card to lift it: `promigence billing (?:card|portal)`/, `or email ${SUPPORT} to lift it`)
+        .replace(/adding a card raises it \(owners: `promigence billing (?:card|portal)`\)\.?/, `to raise it, email ${SUPPORT}.`)
+        .replace(/Add a card to keep going \(owners: `promigence billing (?:card|portal)`[^)]*\)\.?/, `Card payments are not open yet: for more credits, email ${SUPPORT}.`)
+        .replace(/\(?owners: `promigence billing (?:card|portal)`(?:; members ask an owner)?\)?/g, `email ${SUPPORT}`)
+        .replace(/`promigence billing (?:card|portal)`/g, SUPPORT);
+}
+export const CREDIT_UNCLAIMED_FIX = "Claim your free credit first: `promigence credits claim` (owners; members ask an owner). Or add a card: `promigence billing card`.";
+const ANY_HELP = /See `promigence [a-z][a-z -]* --help`\.?$/;
+const API_WORDS = [
+    [/`timeout_ms`\s+(\d+)/g, "--timeout", (_m, ms) => `\`--timeout ${duration(Number(ms))}\``],
+    [/`timeout_ms`/g, "--timeout", "`--timeout`"],
+    [/`recursive(?:=true|: true)?`/g, "--recursive", "`--recursive`"],
+    [/\bpass recursive\b/g, "--recursive", "pass `--recursive`"],
+    [/`registry_secret`/g, "--registry-secret", "`--registry-secret`"],
+    [/`force(?:=true|: true)?`/g, "--force", "`--force`"],
+    [/`move_alias(?:=true|: true)?`/g, "--move-alias", "`--move-alias`"],
+    [/`state` is a comma-separated list/g, "--state", "`--state` is a comma-separated list"],
+    [/`network\.allow`/g, "--allow", "`--allow`"],
+];
+export function inCliWords(text, command) {
+    const c = findCommand(command.split(" "));
+    if (!c)
+        return text;
+    let out = text;
+    for (const [re, flag, to] of API_WORDS) {
+        if (!c.flags.some((f) => f.name === flag))
+            continue;
+        out = out.replace(re, (...m) => {
+            const match = m[0];
+            const at = m[m.length - 2];
+            const whole = m[m.length - 1];
+            const clause = whole.slice(at + match.length).split(/[,;]|\.(?:\s|$)/)[0] ?? "";
+            if (/\bin the API\b/.test(clause))
+                return match;
+            return typeof to === "string" ? to : to(...m);
+        });
+    }
+    return out;
+}
+const SNAPSHOT_READS = new Set(["snapshot export", "snapshot inspect", "snapshot verify"]);
+export async function refineError(e, ctx) {
+    let err = e;
+    let next;
+    if (/\{(sandbox_id|run_id)\}/.test(`${err.message} ${err.fix ?? ""}`)) {
+        const sid = ctx.sandbox ?? (ctx.command.startsWith("sandbox ") ? ctx.args[0] : undefined);
+        const fill = (t) => {
+            let out = t;
+            if (sid !== undefined)
+                out = out.replaceAll("{sandbox_id}", sid);
+            out = out.replaceAll("{sandbox_id}", "SID").replaceAll("{run_id}", "RUN_ID");
+            return out;
+        };
+        const fix = fill(err.fix ?? "");
+        const where = /RUN_ID/.test(fix) ? ` (RUN_ID: ${sid !== undefined ? sh `promigence sandbox info ${sid}` : "promigence sandbox info SID"} prints it)` : "";
+        err = reworded(err, fix ? `${fix}${where}` : fix, fill(err.message));
+    }
+    if (e.code === "sandbox_unresponsive") {
+        const sid = ctx.sandbox ?? (ctx.command.startsWith("sandbox ") ? ctx.args[0] : undefined);
+        next = [
+            ...(sid !== undefined
+                ? [{ cmd: sh `promigence sandbox kill ${sid}`, why: "end it: a sandbox that stopped answering does not come back by itself" }]
+                : []),
+            { cmd: "promigence fork --count 1 --cap 1", why: "a new sandbox" },
+        ];
+    }
+    if ((e.code === "usage" || e.code === "invalid_argument") && SDK_CALL.test(err.message)) {
+        err = reworded(err, err.fix ?? "", err.message.replace(SDK_CALL, (m) => (m.trim().endsWith(":") ? "" : `${ctx.command} `)));
+    }
+    if (e.code === "usage" || e.code === "invalid_argument") {
+        let fix = inCliWords(err.fix ?? "", ctx.command);
+        if (ANY_HELP.test(fix)) {
+            fix = fix.replace(ANY_HELP, `See \`promigence ${ctx.command} --help\`.`);
+        }
+        err = reworded(err, fix, inCliWords(err.message, ctx.command));
+        if (ctx.command === "snapshot delete" && /still has \d+ sandbox/.test(e.message)) {
+            fix = "End those sandboxes first (`promigence sandbox list` shows them; `promigence run kill RUN` ends a whole run), then delete it again.";
+            next = [{ cmd: "promigence sandbox list", why: "the sandboxes still running from it" }];
+        }
+        err = reworded(err, fix);
+    }
+    if (err.message === PREVIEWS_UNAVAILABLE) {
+        const sid = ctx.sandbox ?? "SID";
+        const port = /^\d+$/.test(ctx.args[0] ?? "") ? ctx.args[0] : "8000";
+        err = reworded(err, previewsFix(sid, port));
+        next = [{ cmd: sh `promigence sandbox ssh ${sid} -- -N -L ${`${port}:localhost:${port}`}`, why: "reach the port from this machine over SSH, until Ctrl-C" }];
+    }
+    if (e.code === "auth" && ctx.command === "sandbox ssh" && /^(this ssh access|sandbox \S+ has ended)/.test(e.message)) {
+        const sid = ctx.args[0] ?? "SID";
+        next = /has ended$/.test(e.message)
+            ? [{ cmd: "promigence sandbox list", why: "the sandboxes still running" }]
+            : [{ cmd: sh `promigence sandbox ssh ${sid}`, why: "new ssh access to the sandbox" }];
+    }
+    if (e.code === "not_found") {
+        const nf = notFoundKind(e.message);
+        const fitted = nf ? notFoundFor(nf.kind, ctx, err.fix ?? "") : undefined;
+        if (fitted) {
+            err = reworded(err, fitted.fix);
+            next = fitted.next;
+        }
+    }
+    if (e.code === "cap_exceeded" && ctx.command === "sandbox extend") {
+        const sid = ctx.args[0] ?? "SID";
+        err = reworded(err, "A sandbox can be extended only within what its run was quoted at launch (and at most its --cap), " +
+            "and that is used up. Start a new sandbox with the longer --timeout and a --cap that covers it.");
+        next = [
+            { cmd: sh `promigence sandbox info ${sid}`, why: "its timeout and what it has used" },
+            { cmd: "promigence fork --count 1 --timeout DUR --cap USD", why: "a sandbox with the longer timeout from the start" },
+        ];
+    }
+    if (e.code === "cap_exceeded" && ctx.command === "run open") {
+        const rid = ctx.args[0] ?? "RUN";
+        err = reworded(err, "The reopened sandbox is paid from what is left of its run's cap, and that does not cover it. " +
+            "Give the reopened sandbox its own --cap (and a --timeout).");
+        next = [
+            { cmd: sh `promigence run open ${rid} --cap 1 --timeout 10m`, why: "reopen it with its own cap" },
+            { cmd: sh `promigence run captures ${rid}`, why: "what of this run is preserved, and until when" },
+        ];
+    }
+    if (e.code === "unreachable" && /the sandbox host/.test(e.message)) {
+        const sid = ctx.sandbox ?? (ctx.command.startsWith("sandbox ") ? ctx.args[0] : undefined);
+        const snap = SNAPSHOT_READS.has(ctx.command) ? ctx.args[0] : undefined;
+        if (snap !== undefined) {
+            err = reworded(err, `The API is up but could not read this snapshot just now. Retry in a moment; if it keeps ` +
+                `happening, email ${SUPPORT} with the snapshot id.`);
+            next = [{ cmd: sh `promigence snapshot inspect ${snap}`, why: "the snapshot's state" }];
+        }
+        else if (sid !== undefined) {
+            err = reworded(err, `The API is up but could not reach this sandbox. Retry once; if it still does not answer, the sandbox has stopped responding ` +
+                `(\`sandbox info\` can still say ready): end it with \`${sh `promigence sandbox kill ${sid}`}\` and start a new one. ` +
+                `If it keeps happening, email ${SUPPORT} with the sandbox id.`);
+            next = [
+                { cmd: sh `promigence sandbox kill ${sid}`, why: "end it: a sandbox that stopped answering does not come back by itself" },
+                { cmd: "promigence fork --count 1 --cap 1", why: "a new sandbox" },
+            ];
+        }
+        else {
+            err = reworded(err, `The API is up but could not reach what this needed. Retry in a moment; if it keeps ` +
+                `happening, email ${SUPPORT} with the sandbox, run or snapshot id.`);
+        }
+    }
+    if (e.code === "credit_unclaimed") {
+        err = reworded(err, CREDIT_UNCLAIMED_FIX);
+        next = [
+            { cmd: "promigence credits claim", why: "open the claim page and accept the terms" },
+            { cmd: "promigence credits", why: "the free-credit offer for this account" },
+        ];
+    }
+    if ((BILLING_CMD.test(err.fix ?? "") || BILLING_CMD.test(err.message)) && await ctx.billingOff()) {
+        err = reworded(err, withoutBilling(err.fix ?? ""), withoutBilling(err.message));
+    }
+    return next ? { err, next } : { err };
+}

package/dist/generated.d.ts

@@ -0,0 +1,35 @@
+export interface ErrorEntry {
+    code: string;
+    category: string;
+    http: number;
+    exit: number;
+    billed: string;
+    message: string;
+    fix: string;
+}
+export declare const ERRORS: readonly ErrorEntry[];
+export declare const ERROR_BY_CODE: Readonly<Record<string, ErrorEntry>>;
+export declare const CLIENT_ERRORS: readonly ErrorEntry[];
+export declare const CLIENT_ERROR_BY_CODE: Readonly<Record<string, ErrorEntry>>;
+export interface TierEntry {
+    name: string;
+    vcpus: number;
+    mem_gib: number;
+    disk_gib: number;
+    sellable: boolean;
+    per_second_usd: number;
+}
+export declare const TIERS: readonly TierEntry[];
+export declare const BUILD_MAX_S = 3600;
+export declare const PRICING: {
+    readonly vcpu_second_usd: 0.000014;
+    readonly gib_second_usd: 0.0000045;
+    readonly preemptible_vcpu_second_usd: 0.000007;
+    readonly preemptible_gib_second_usd: 0.00000225;
+    readonly egress_gib_usd: 0;
+    readonly storage_gib_month_usd: 0;
+    readonly min_billable_seconds: 1;
+    readonly granularity_seconds: 1;
+    readonly interim_interval_seconds: 60;
+};
+export declare const SANDBOX_STATES: readonly ["queued", "awaiting_capacity", "ready", "running", "paused", "ended"];

package/dist/generated.js

@@ -0,0 +1,307 @@
+export const ERRORS = [
+    { code: "fork_failed", category: "env", http: 502, exit: 3, billed: "no",
+        message: "the sandbox could not be started",
+        fix: "Not billed. A run with a command is retried once automatically; otherwise re-run. If it repeats, re-verify the snapshot: `promigence snapshot verify {snapshot_id}`." },
+    { code: "start_timeout", category: "env", http: 502, exit: 3, billed: "no",
+        message: "the sandbox did not answer its first command within {deadline_ms} ms",
+        fix: "Not billed. A run with a command is retried once automatically; otherwise start it again. If it keeps happening, tell support@promigence.ai the run id." },
+    { code: "readiness_failed", category: "env", http: 502, exit: 3, billed: "no",
+        message: "the sandbox failed its readiness check",
+        fix: "Not billed: the sandbox was set aside before it was handed to you. A run with a command is retried once automatically; otherwise start it again. If it keeps failing, re-verify the snapshot: `promigence snapshot verify {snapshot_id}`." },
+    { code: "verify_too_slow", category: "env", http: 502, exit: 3, billed: "no",
+        message: "the snapshot's verify step took longer in this sandbox than its limit allows",
+        fix: "Not billed. A run with a command is retried once automatically; otherwise start it again. If it keeps happening, re-verify the snapshot: `promigence snapshot verify {snapshot_id}`." },
+    { code: "verify_each_failed", category: "env", http: 502, exit: 3, billed: "no",
+        message: "verify_each run failed in the fork (exit {exit_code}, digest {digest})",
+        fix: "Not billed. A run with a command is retried once automatically. If it repeats, the snapshot no longer reproduces: rebuild with `promigence snapshot create ...`." },
+    { code: "toolchain_mismatch", category: "env", http: 502, exit: 3, billed: "no",
+        message: "toolchain check `{argv}` in the fork gave digest {got}, the verified snapshot recorded {expected}",
+        fix: "The fork's toolchain differs from the verified snapshot; not billed. Re-run; if it repeats, rebuild the snapshot." },
+    { code: "sandbox_unresponsive", category: "env", http: 502, exit: 3, billed: "unless_ours",
+        message: "the sandbox stopped responding",
+        fix: "Billed for the time used, unless our side shows the cause was ours: then it is credited back (after a review if many are credited in one day), as the run report shows. Not retried automatically once your command has started. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`. If you think the cause was ours, tell support@promigence.ai the run id." },
+    { code: "oom_within_tier", category: "env", http: 502, exit: 3, billed: "credited",
+        message: "the sandbox stopped on our side while within the tier's {tier_mib} MiB",
+        fix: "Our fault, not yours: credited back (at least the work lost since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is not charged), after a review if many are credited in one day. Replay: `promigence run replay {run_id} --sandbox {sandbox_id}`." },
+    { code: "disk_full_within_tier", category: "env", http: 502, exit: 3, billed: "credited",
+        message: "the sandbox stopped on our side while within its {tier_disk_gib} GiB of disk",
+        fix: "Our fault, not yours: credited back (at least the work lost since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is not charged), after a review if many are credited in one day. Replay: `promigence run replay {run_id} --sandbox {sandbox_id}`." },
+    { code: "sandbox_interrupted", category: "env", http: 502, exit: 3, billed: "credited",
+        message: "the sandbox was interrupted by a platform event",
+        fix: "Not caused by your work, and credited back: at least the work since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is never charged. To run it again: `promigence run replay {run_id}`." },
+    { code: "integrity_mismatch", category: "env", http: 502, exit: 3, billed: "unless_ours",
+        message: "the environment differs from the verified snapshot at {path}",
+        fix: "Not billed when we confirm the stored snapshot itself differs at that path; otherwise (only this sandbox's copy changed, or the check could not be made) the time used is billed. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`; if it happens again, rebuild the snapshot." },
+    { code: "egress_unavailable", category: "env", http: 502, exit: 3, billed: "unless_ours",
+        message: "the sandbox's outbound network was unavailable",
+        fix: "Not billed when we confirm the outage on our side, after a review if many are credited in one day; otherwise the time used is billed. To run it again: `promigence run replay {run_id}`." },
+    { code: "service_timeout", category: "env", http: 504, exit: 3, billed: "unless_ours",
+        message: "the service's own time limit ({deadline_ms} ms) was reached before your command's timeout",
+        fix: "When the cause was ours (our service restarted), it is credited back: at least the work since your last snapshot of this sandbox, up to 24 hours. Otherwise the time used is billed. For long commands, set `timeout_ms`. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`." },
+    { code: "preempted", category: "preempt", http: 502, exit: 3, billed: "credited",
+        message: "the preemptible sandbox was stopped early, as preemptible runs can be",
+        fix: "Our doing, not yours: credited back (at least the work lost since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is never charged). This run asked to be preemptible, which is priced below the standard rate for exactly this reason. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`; or run it without `preemptible` to pay the standard rate and not be stopped early." },
+    { code: "verify_did_not_cover", category: "snapshot", http: 422, exit: 4, billed: "yes",
+        message: "`{path}` is missing but was not under a verified path; the snapshot's verify did not cover it",
+        fix: "Billed: the environment matched what `verify` checked. Broaden `verify` (or `setup`) so the path is produced and covered, then `promigence snapshot create ...`." },
+    { code: "grader_failed", category: "grader", http: 422, exit: 3, billed: "unless_ours",
+        message: "the grade could not be computed ({kind})",
+        fix: "Not a task failure. The time your grader ran is billed like the sandbox's own; a grade that failed on our side is not. Check that `grade.cmd` exits within `grade.timeout_ms` and that its output matches `grade.score` (exit | last_line_json | tap), then re-run." },
+    { code: "nonzero_exit", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "command exited {exit_code}",
+        fix: "The environment was verified; the command failed. Inspect: `promigence exec output {exec_id}`." },
+    { code: "grade_not_passed", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "the task completed and its grade did not pass (the grader exited {exit_code})",
+        fix: "Your grader failed the work; the task's command succeeded." },
+    { code: "task_timeout", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "command exceeded timeout_ms={timeout_ms}",
+        fix: "Raise `--timeout` (billed per second used, so a longer timeout only costs what runs) or shorten the task." },
+    { code: "oom_over_tier", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "the process was killed for exceeding the tier's {tier_mib} MiB of memory",
+        fix: "Rebuild the snapshot on a larger tier (`promigence snapshot create … --tier medium|large`; see `promigence agent-guide --section cost`) or reduce the task's memory." },
+    { code: "disk_over_tier", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "the sandbox ran out of its {tier_disk_gib} GiB of disk",
+        fix: "Pick a larger tier or write less; the disk is sized to the tier quota." },
+    { code: "shutdown_by_task", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "the sandbox shut itself down ({kind})",
+        fix: "Billed as the task's outcome: a command in the sandbox shut it down. Keep the task from doing that; if nothing in it should have, check what the agent ran." },
+    { code: "modified_by_task", category: "task", http: 422, exit: 4, billed: "yes",
+        message: "`{missing}` was removed or changed inside the sandbox; the snapshot's copy is intact",
+        fix: "Billed as the task's outcome: the sandbox started verified and something it ran deleted or changed `{path}`. Keep the task from modifying verified paths, or recreate what it needs first." },
+    { code: "cap_killed", category: "cap", http: 402, exit: 12, billed: "yes",
+        message: "sandbox killed when its accrued spend reached the spend cap ({spend_cap})",
+        fix: "The seconds it ran are billed, up to the cap. Raise `--cap` or `PATCH /sandboxes/:id` earlier." },
+    { code: "cap_exceeded", category: "cap", http: 409, exit: 5, billed: "no",
+        message: "quote {max_cost} exceeds remaining spend cap {remaining}",
+        fix: "Raise `--cap`, lower `--count`/`--timeout`, or pass `--allow-partial` to launch what fits." },
+    { code: "cap_paused", category: "cap", http: 402, exit: 5, billed: "no",
+        message: "sandbox {sandbox_id} is paused: its run reached its spend cap ({spend_cap})",
+        fix: "Its files and state are kept, and paused time is not billed. Raise the run's cap to go on: `promigence sandbox resume {sandbox_id} --cap <usd>` (`spend_cap` on POST /v1/sandboxes/{sandbox_id}/resume). Or end it: `promigence sandbox kill {sandbox_id}`." },
+    { code: "credits_paused", category: "cap", http: 402, exit: 5, billed: "no",
+        message: "sandbox {sandbox_id} is paused: the organization's credits ran out",
+        fix: "Its files and state are kept, and paused time is not billed. Add a card to go on (owners: `promigence billing card`; members ask an owner), then resume it: `promigence sandbox resume {sandbox_id}`. Or end it: `promigence sandbox kill {sandbox_id}`." },
+    { code: "aborted_by_client", category: "other", http: 200, exit: 130, billed: "yes",
+        message: "sandbox killed by the client",
+        fix: "Nothing to fix; billed for the seconds used." },
+    { code: "stopped_by_support", category: "other", http: 200, exit: 12, billed: "unless_ours",
+        message: "Stopped by Promigence support: {reason}",
+        fix: "Billed for the seconds it ran, as a kill is, unless support found the cause was on our side; then that time is credited back. Questions: tell support@promigence.ai the sandbox id." },
+    { code: "expired", category: "other", http: 200, exit: 12, billed: "yes",
+        message: "sandbox timeout reached (counted from hand-off)",
+        fix: "Raise `--timeout` if the task needs longer." },
+    { code: "not_started", category: "other", http: 200, exit: 12, billed: "no",
+        message: "sandbox not started: outside the spend cap",
+        fix: "Raise `--cap`; with `--allow-partial` only what fits is launched." },
+    { code: "superseded", category: "other", http: 200, exit: 0, billed: "no",
+        message: "attempt 1 superseded by a successful retry",
+        fix: "Nothing to fix; attempt 1 is unbilled." },
+    { code: "usage", category: "other", http: 400, exit: 2, billed: "no",
+        message: "{detail}",
+        fix: "{detail}. See `promigence {command} --help`." },
+    { code: "internal", category: "other", http: 500, exit: 1, billed: "no",
+        message: "internal error",
+        fix: "Not your fault. Re-run; if it repeats, tell support@promigence.ai the run or sandbox id and the time." },
+    { code: "auth", category: "other", http: 401, exit: 7, billed: "no",
+        message: "missing or invalid API key",
+        fix: "Set PROMIGENCE_API_KEY or run `promigence auth login --from-env VAR`. No key yet: `promigence login` (sign in) or https://promigence.ai." },
+    { code: "forbidden", category: "other", http: 403, exit: 7, billed: "no",
+        message: "{detail}",
+        fix: "Do what the message names: sign in (`promigence login`), use a full-access key (`promigence keys create`) or one from that org, or ask an owner." },
+    { code: "not_found", category: "other", http: 404, exit: 8, billed: "no",
+        message: "{kind} `{id}` not found",
+        fix: "Check the id; aliases resolve in your org first, then public snapshots (`promigence examples`)." },
+    { code: "unreachable", category: "other", http: 503, exit: 9, billed: "no",
+        message: "cannot reach {url}",
+        fix: "Retry in a moment. If the API answered this, the fault is ours: if it repeats, email support@promigence.ai with the sandbox or run id. If the API itself did not answer, check PROMIGENCE_API_URL and your connection." },
+    { code: "rate_limited", category: "other", http: 429, exit: 10, billed: "no",
+        message: "rate limited by {host}; retry after {retry_after_s} s",
+        fix: "Wait `Retry-After` seconds, then retry. If the limit is an image registry's, not this API's, a `registry_secret` holding your own login for it usually raises it. Otherwise lower concurrency (see `GET /me` limits)." },
+    { code: "timeout", category: "other", http: 504, exit: 11, billed: "no",
+        message: "wait of {wait_timeout} expired; nothing was killed",
+        fix: "Run the id-based command: `{next}`." },
+    { code: "not_verified", category: "other", http: 409, exit: 6, billed: "no",
+        message: "snapshot {snapshot_id} is not verified (build {build_id}: {state})",
+        fix: "Wait for the build: `promigence snapshot status {build_id} --wait`." },
+    { code: "snapshot_incompatible", category: "other", http: 409, exit: 6, billed: "no",
+        message: "snapshot {snapshot_id} can no longer run on the platform",
+        fix: "Nothing was started or billed. Rebuild it from the same source: POST /v1/snapshots (`promigence snapshot create`)." },
+    { code: "storage_limit_reached", category: "other", http: 409, exit: 5, billed: "no",
+        message: "{detail}",
+        fix: "Nothing was stored or charged, and nothing already stored was removed: delete what you no longer need, or move to a plan that keeps more." },
+    { code: "resume_unavailable", category: "env", http: 503, exit: 3, billed: "no",
+        message: "sandbox {sandbox_id} is safe and still paused; it could not be resumed right now",
+        fix: "Your files are kept and nothing was billed. Retry in a minute. If it keeps happening, email support@promigence.ai with the sandbox id." },
+    { code: "sandbox_unreachable", category: "env", http: 503, exit: 3, billed: "no",
+        message: "sandbox {sandbox_id} could not be reached just now; nothing was changed",
+        fix: "Not billed for this call, and the sandbox is as it was. Retry in a few seconds. If it keeps happening, email support@promigence.ai with the sandbox id." },
+    { code: "capacity_busy", category: "env", http: 503, exit: 3, billed: "no",
+        message: "no capacity free right now",
+        fix: "Not billed, and nothing was started. Nothing was free in time: start it again in a few minutes, or lower `--count` to need fewer at once." },
+    { code: "region_at_capacity", category: "env", http: 503, exit: 3, billed: "no",
+        message: "capacity is full right now",
+        fix: "Not billed, and nothing was started. Retry shortly, or lower `--count`." },
+    { code: "builder_unavailable", category: "env", http: 503, exit: 3, billed: "no",
+        message: "new snapshots cannot be built right now",
+        fix: "Not billed, and nothing was stored. Nothing here can build at all, so this is not a busy queue and does not clear itself by waiting, and a smaller run does not help. Snapshots you have already built still run, so re-use one (`promigence snapshot list`). If you asked for a specific CPU, drop that and retry; otherwise retry shortly, and tell support@promigence.ai the time if it keeps happening." },
+    { code: "builder_busy", category: "env", http: 503, exit: 3, billed: "no",
+        message: "snapshot builds are backed up; retry after {retry_after_s} s",
+        fix: "Not billed, and nothing was stored. Other builds are ahead of this one: submit it again in {retry_after_s} s. Builds already accepted keep their place in the queue and finish on their own (`promigence snapshot status <build_id> --wait`)." },
+    { code: "overloaded", category: "env", http: 503, exit: 3, billed: "no",
+        message: "the API is at capacity; retry in {retry_after_s} s",
+        fix: "Not billed, and nothing was started. Send the same request again in {retry_after_s} s; the SDKs and the CLI do this for you." },
+    { code: "tier_unavailable", category: "env", http: 503, exit: 3, billed: "no",
+        message: "the {tier} tier ({vcpus} vCPU / {mem_gib} GiB) is not available yet",
+        fix: "Not billed. Use a smaller tier (`promigence snapshot create … --tier`; a fork runs on its snapshot's), or write to support@promigence.ai to have {tier} enabled for your account." },
+    { code: "snapshot_unavailable", category: "env", http: 409, exit: 3, billed: "no",
+        message: "snapshot {snapshot_id} is no longer available: it could not be saved",
+        fix: "Not billed, and nothing was started. It cannot be started again: take a new snapshot of a running sandbox (`promigence sandbox snapshot <sandbox_id>`) or build it again (`promigence snapshot create ...`), then remove this one: `promigence snapshot delete {snapshot_id}`." },
+    { code: "capacity_limit", category: "env", http: 409, exit: 3, billed: "no",
+        message: "{requested} {tier} sandboxes at once is more than one run can start at once; at most {max_at_once}",
+        fix: "Not billed; nothing started. Run at most {max_at_once} at once (lower `--count`), or use a smaller tier." },
+    { code: "build_timeout", category: "other", http: 422, exit: 4, billed: "yes",
+        message: "the build ran past its {limit_min}-minute limit",
+        fix: "Nothing was stored; the {limit_min} minutes it ran are billed. Shorten `setup` (at most 64 steps, {limit_min} minutes in all) or bake the slow part into the image." },
+    { code: "dockerfile_build_failed", category: "other", http: 400, exit: 2, billed: "yes",
+        message: "your image could not be built from the Dockerfile: {detail}",
+        fix: "Nothing was stored; the time the build ran is billed. Fix the Dockerfile (the lines above are the end of your own build output) and run `promigence snapshot create --dockerfile PATH ...` again." },
+    { code: "image_unresolvable", category: "other", http: 422, exit: 2, billed: "no",
+        message: "`{image}` could not be resolved to a digest: {detail}",
+        fix: "Nothing was stored and nothing was billed. Check the name and tag; a private image needs `registry_secret` naming a stored secret that holds `user:password` (`promigence secrets set`). You can also pass the image already pinned as NAME@sha256:<digest>." },
+    { code: "registry_unavailable", category: "env", http: 503, exit: 3, billed: "no",
+        message: "`{image}` could not be resolved to a digest because its registry did not answer usably: {detail}",
+        fix: "Not billed, and nothing was stored. Your image is not at fault: submit it again in {retry_after_s} s. Snapshots you have already built from it still run (`promigence snapshot list`)." },
+    { code: "enoent", category: "other", http: 404, exit: 8, billed: "no",
+        message: "`{argv0}` not found in the sandbox",
+        fix: "Check the command name; install the program in the image or in a setup step; for a shell builtin or a pipeline, run it through a shell: `-- sh -c '...'`." },
+    { code: "trial_credits_exhausted", category: "cap", http: 402, exit: 5, billed: "no",
+        message: "trial credits left ({remaining}) do not cover this ({needed})",
+        fix: "Add a card to keep going (owners: `promigence billing card`, or POST /v1/billing/checkout; members ask an owner). Remaining credits are used first; running sandboxes finish." },
+    { code: "credit_unclaimed", category: "other", http: 402, exit: 5, billed: "no",
+        message: "this account has free credit waiting to be claimed",
+        fix: "Claim it in your browser: `promigence credits claim` (owners; members ask an owner). Or add a card: `promigence billing card`. Nothing was started or charged." },
+    { code: "setup_required", category: "other", http: 403, exit: 7, billed: "no",
+        message: "finish setting up your account before starting new work",
+        fix: "Open {setup_url} and answer the setup questions (under a minute), then run this again. Nothing was started or charged." },
+    { code: "card_required", category: "other", http: 402, exit: 5, billed: "no",
+        message: "a card is required for new work since {effective_at}",
+        fix: "Add a card (owners: `promigence billing card`, or POST /v1/billing/checkout; members ask an owner). Your trial credits are kept and used first; reads and results stay available." },
+    { code: "billing_unavailable", category: "other", http: 503, exit: 5, billed: "no",
+        message: "card payments are not open yet",
+        fix: "Nothing was charged. Your trial credits are kept and used first; for more credits, email support@promigence.ai." },
+    { code: "concurrency_limit", category: "other", http: 409, exit: 5, billed: "no",
+        message: "{live} live + {requested} requested sandboxes is over your limit of {limit}",
+        fix: "Wait for sandboxes to end or lower `--count` (`--allow-partial` covers the spend cap only); a retry of the same request fails the same way. Trial orgs get {trial_limit}; to raise it, email support@promigence.ai." },
+    { code: "egress_cap_reached", category: "other", http: 403, exit: 5, billed: "no",
+        message: "monthly data-out cap reached: {used_gb} of {cap_gb} GB",
+        fix: "Use `--network none` (still allowed) or wait for the 1st (UTC). For more data out a month, email support@promigence.ai." },
+    { code: "project_cap_reached", category: "cap", http: 403, exit: 5, billed: "no",
+        message: "project {project} has {remaining} of its {limit} monthly cap left; this needs {needed}",
+        fix: "Ask for less (`--count`, `--cap`, a shorter extension), wait for the 1st (UTC), or have an owner raise it: `promigence project cap {project} <usd>`." },
+    { code: "spend_limit_reached", category: "cap", http: 402, exit: 5, billed: "no",
+        message: "today's spend limit {limit} has {remaining} left; this needs {needed}",
+        fix: "Running sandboxes finish. The limit resets at 00:00 UTC and grows with each paid invoice; ask for less, or email support@promigence.ai." },
+    { code: "billing_hold", category: "other", http: 402, exit: 5, billed: "no",
+        message: "new work is on hold: {reason}",
+        fix: "Running sandboxes finish. Owners: update the card with `promigence billing portal`; the hold lifts once the invoice is paid. For a disputed payment, write to support@promigence.ai." },
+    { code: "tier_over_plan", category: "other", http: 403, exit: 2, billed: "no",
+        message: "the {tier} tier ({vcpus} vCPU) is over the {limit} vCPU per-sandbox limit of your {plan} plan",
+        fix: "Use a tier of at most {limit} vCPU (`promigence snapshot create … --tier {max_tier}` is the largest; a fork runs on its snapshot's), or move to a plan that allows it: `promigence billing portal`." },
+    { code: "network_host_refused", category: "other", http: 403, exit: 9, billed: "no",
+        message: "{host} is not on this sandbox's allowed list, so the connection was refused",
+        fix: "Add it when you start the sandbox — `--allow {host}` — or drop `--allow` to let the sandbox reach anything. `promigence sandbox network <id>` lists everything that has been refused." },
+    { code: "network_policy_unsupported", category: "env", http: 502, exit: 3, billed: "no",
+        message: "this sandbox asked to reach only {allow}, and that could not be applied",
+        fix: "Nothing ran and nothing was billed: the sandbox was discarded rather than started without the restriction you asked for. Re-run; if it repeats, tell support@promigence.ai the run id." },
+    { code: "secrets_in_snapshot", category: "other", http: 409, exit: 2, billed: "no",
+        message: "sandbox {sandbox_id} was given a secret's value, so a snapshot of it can contain that value",
+        fix: "To take it anyway, pass `force: true` (`promigence sandbox snapshot {sandbox_id} --force`): that snapshot, and every sandbox started from it, can then contain the secret. Otherwise snapshot a sandbox that was never given a secret, and name the secret on the runs you start from it." },
+    { code: "secrets_unavailable", category: "env", http: 503, exit: 3, billed: "no",
+        message: "secrets cannot be used right now",
+        fix: "Not billed, and nothing that names a secret was started. Runs, commands and terminals that name no secret are unaffected, and stored secrets can still be listed and deleted. Retry shortly; if it keeps happening, tell support@promigence.ai the time." },
+    { code: "secret_binding_unsupported", category: "env", http: 502, exit: 3, billed: "no",
+        message: "a secret bound to a host could not be set up for this sandbox",
+        fix: "Nothing ran, nothing was billed, and the value never entered the sandbox. Re-run; if it repeats, tell support@promigence.ai the run id." },
+    { code: "idempotency_key_reused", category: "other", http: 409, exit: 2, billed: "no",
+        message: "this Idempotency-Key was used for a different request",
+        fix: "Nothing was started. Use a new key for a new request; send the original request again to get its original answer." },
+    { code: "idempotency_key_in_use", category: "env", http: 409, exit: 3, billed: "no",
+        message: "a request with this Idempotency-Key is still running",
+        fix: "Not billed; nothing new was started. Send the same request again in {retry_after_s} s for the first one's answer; the SDKs do this for you." },
+    { code: "repo_credentials_not_supported", category: "other", http: 400, exit: 2, billed: "no",
+        message: "credentials in repository URLs are not accepted ({field})",
+        fix: "Nothing was built or billed. A repository URL never carries a credential. For a private repository, connect its host once for your organization (`promigence github connect` or `promigence gitlab connect`) and name it as `--repo owner/name` (`--repo gitlab:group/project`); a public one is named by its plain https:// URL, with no user name, password, token, query string or fragment in it." },
+    { code: "account_exists", category: "other", http: 409, exit: 7, billed: "no",
+        message: "this email address has an account that signs in with {sign_in_with}",
+        fix: "Nothing was created. Sign in with {sign_in_with} instead: `{sign_in_command}`. If the browser signs you in with the method you just used, open the sign-in link in a private window. If you did not create that account, write to support@promigence.ai." },
+    { code: "invite_invalid", category: "other", http: 403, exit: 7, billed: "no",
+        message: "this invite code is not valid",
+        fix: "Nothing was created. Check the code and try `promigence signup` again, or ask the person who invited you for a new code." },
+    { code: "invite_required", category: "other", http: 403, exit: 7, billed: "no",
+        message: "new accounts need an invite code right now",
+        fix: "Nothing was created. Run `promigence signup` and enter your invite code when asked. If you already have an account, sign in with the method you used before (`promigence login`)." },
+    { code: "key_expired", category: "other", http: 401, exit: 7, billed: "no",
+        message: "this API key expired at {expired_at}",
+        fix: "Create a new key (`promigence keys create`, or sign in again with `promigence login`) and replace this one wherever it is used." },
+    { code: "account_blocked", category: "other", http: 401, exit: 7, billed: "no",
+        message: "this account is blocked",
+        fix: "Write to support@promigence.ai to have it reviewed." },
+];
+export const ERROR_BY_CODE = Object.fromEntries(ERRORS.map((e) => [e.code, e]));
+export const CLIENT_ERRORS = [
+    { code: "invalid_argument", category: "other", http: 0, exit: 2, billed: "no",
+        message: "an argument the SDK refused before sending it",
+        fix: "Nothing was sent or billed. The message names the argument and the form it takes: change it and call again. From the CLI, `promigence <command> --help` lists every flag." },
+    { code: "unsupported", category: "other", http: 0, exit: 2, billed: "no",
+        message: "not available in this version or on this deployment",
+        fix: "Nothing was sent or billed. The fix in the error names what to use instead." },
+    { code: "not_released", category: "other", http: 0, exit: 1, billed: "no",
+        message: "not released in this version",
+        fix: "Nothing was sent or billed. Update the CLI or SDK once a release implements it (support@promigence.ai has the latest)." },
+    { code: "task_failed", category: "task", http: 0, exit: 4, billed: "yes",
+        message: "the command exited non-zero (the SDK's CommandExitError)",
+        fix: "The environment was verified and the command failed: read stdout and stderr on the error, or pass `throwOnExit: false` to get the result instead. A run's report calls the same failure `nonzero_exit`." },
+    { code: "env_failed", category: "env", http: 0, exit: 3, billed: "no",
+        message: "the sandbox ended before hand-over",
+        fix: "Ours, not billed. The run's report names the failure's own code (`promigence run report RUN`); start the sandbox again." },
+    { code: "snapshot_rejected", category: "other", http: 0, exit: 6, billed: "unless_ours",
+        message: "a build guard refused it; nothing was stored",
+        fix: "The time the build ran is billed, unless it ended on our side. Read the build log (`promigence snapshot status BUILD --log 80`): the guard named in the error says what to change (verify exited non-zero, a setup step failed, a time or size bound), then build again." },
+    { code: "build_failed", category: "env", http: 0, exit: 3, billed: "no",
+        message: "the build could not finish; nothing was stored",
+        fix: "Not charged. Build again; if it repeats, email support@promigence.ai with the build id." },
+    { code: "service_restart", category: "env", http: 0, exit: 3, billed: "no",
+        message: "a service restart stopped the command while its output was streaming",
+        fix: "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." },
+    { code: "not_connected", category: "other", http: 0, exit: 7, billed: "no",
+        message: "the connection request ended without connecting anything",
+        fix: "Nothing was connected. Do what the message names, then run the connect command again; `promigence github status` (or `gitlab status`) lists what is connected." },
+    { code: "snapshot_failed", category: "snapshot", http: 0, exit: 4, billed: "unless_ours",
+        message: "a build ended with no snapshot, or the snapshot did not hold",
+        fix: "A build: read its log (`promigence snapshot status BUILD --log 80`), fix what it names, build again. A run: the sandbox's own failure code says what (usually `verify_did_not_cover`: broaden `verify`)." },
+];
+export const CLIENT_ERROR_BY_CODE = Object.fromEntries(CLIENT_ERRORS.map((e) => [e.code, e]));
+export const TIERS = [
+    { name: "xsmall", vcpus: 1, mem_gib: 1, disk_gib: 10, sellable: true, per_second_usd: 0.0000185 },
+    { name: "small", vcpus: 2, mem_gib: 4, disk_gib: 10, sellable: true, per_second_usd: 0.000046 },
+    { name: "medium", vcpus: 4, mem_gib: 16, disk_gib: 20, sellable: true, per_second_usd: 0.000128 },
+    { name: "large-16", vcpus: 8, mem_gib: 16, disk_gib: 40, sellable: true, per_second_usd: 0.000184 },
+    { name: "large", vcpus: 8, mem_gib: 32, disk_gib: 40, sellable: true, per_second_usd: 0.000256 },
+    { name: "xlarge", vcpus: 16, mem_gib: 32, disk_gib: 80, sellable: true, per_second_usd: 0.000368 },
+    { name: "2xlarge", vcpus: 32, mem_gib: 64, disk_gib: 160, sellable: true, per_second_usd: 0.000736 },
+    { name: "bench-8x8", vcpus: 8, mem_gib: 8, disk_gib: 20, sellable: false, per_second_usd: 0 },
+    { name: "bench-8x16", vcpus: 8, mem_gib: 16, disk_gib: 20, sellable: false, per_second_usd: 0 },
+    { name: "bench-4x8", vcpus: 4, mem_gib: 8, disk_gib: 40, sellable: false, per_second_usd: 0 },
+];
+export const BUILD_MAX_S = 3600;
+export const PRICING = {
+    vcpu_second_usd: 0.000014,
+    gib_second_usd: 0.0000045,
+    preemptible_vcpu_second_usd: 0.000007,
+    preemptible_gib_second_usd: 0.00000225,
+    egress_gib_usd: 0,
+    storage_gib_month_usd: 0,
+    min_billable_seconds: 1,
+    granularity_seconds: 1,
+    interim_interval_seconds: 60,
+};
+export const SANDBOX_STATES = ["queued", "awaiting_capacity", "ready", "running", "paused", "ended"];