promigence 0.1.0-beta.7 → 0.1.0-beta.8

package/README.md

@@ -21,15 +21,13 @@ own (`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to your `
 
 ## Create your account
 
-Promigence is in private beta: you need an invite code.
-
 ```sh
 promigence signup
 ```
 
-It asks for your invite code, then opens your browser to create the account. Your API key is saved
-in your system keychain, or in `~/.config/promigence/credentials` (mode 0600) where there is none. On
-another machine, use `promigence login`: it signs you in with a code we email you, or your password. In CI or on an
+It opens your browser to create the account. Your API key is saved in your system keychain, or in
+`~/.config/promigence/credentials` (mode 0600) where there is none.
+On another machine, use `promigence login`: it signs you in with a code we email you. In CI or on an
 agent's machine, set `PROMIGENCE_API_KEY` instead. `promigence doctor` checks the setup.
 
 ## First commands
@@ -57,7 +55,7 @@ promigence fork --snapshot py --count 5 --cap 2
 
 ## For AI agents
 
-Run `promigence agent-guide` (about 1.2k tokens) before driving the CLI: it covers the model, the
+Run `promigence agent-guide` (about 1.4k tokens) before driving the CLI: it covers the model, the
 JSON output contract, exit codes and errors. `promigence agent-guide --install` writes the same
 guidance into your repo for coding agents, and `promigence mcp` serves the CLI as an MCP server.
 Every command takes `--json`.

package/dist/account.js

@@ -223,6 +223,7 @@ const billingUsage = async (ctx) => {
         usage,
         card_on_file: b.card_on_file ?? false,
         ...(b.card ? { card: b.card } : {}),
+        ...(b.card_note ? { card_note: b.card_note } : {}),
         ...(b.trial ? { trial: b.trial } : {}),
         ...(b.suspended ? { suspended: true, suspend_reason: b.suspend_reason ?? null } : {}),
         upcoming_invoice: b.upcoming_invoice ?? null,
@@ -260,6 +261,8 @@ const billingUsage = async (ctx) => {
     if (trial?.credits_remaining !== undefined)
         lines.push(`  trial credits left: ${usd(trial.credits_remaining)}`);
     lines.push(`  card: ${b.card_on_file ? paymentMethodText(b.card) : `none on file${billingOff ? " (card payments are not open yet)" : ""}`}`);
+    if (b.card_note)
+        lines.push(`  ${b.card_note}`);
     if (b.upcoming_invoice?.amount_due !== undefined && b.upcoming_invoice?.amount_due !== null) {
         lines.push(`  next invoice: ${usd(b.upcoming_invoice.amount_due)}`);
     }
@@ -282,6 +285,86 @@ const billingPortal = async (ctx) => {
     const next = nexts(["promigence billing usage", "this month's spend without leaving the terminal"]);
     return emit(ctx.mode, okEnvelope(ctx.cmd.name, { url: res.url }, next), ["promigence billing portal: open this page to manage the card and past invoices:", `  ${res.url}`], 0, ctx.pointer);
 };
+const HISTORY_KINDS = ["all", "credits", "payments"];
+const CREDIT_WHAT = {
+    free_credit: "Free credit",
+    card_bonus: "Card bonus",
+    referral: "Referral reward",
+    plan: "Included with your plan",
+    from_promigence: "Credit from Promigence",
+    service_restart: "Credit for a service restart",
+    confirmation_credit: "Credit for the $1 confirmation",
+};
+const CREDIT_ENDED = { used: "used", expired: "expired", taken_back: "taken back" };
+const PAYMENT_WHAT = {
+    invoice_paid: "Invoice paid",
+    payment_failed: "Payment failed",
+    refund: "Refund",
+};
+const PAYMENT_STATUS = {
+    paid: "paid",
+    retrying: "will be retried",
+    failed: "not paid",
+    refunded: "refunded",
+    confirmed: "confirmed",
+};
+const wordFor = (m, k) => k && Object.prototype.hasOwnProperty.call(m, k) ? m[k] : undefined;
+const unpaid = (status) => status === "retrying" || status === "failed";
+export function historyLines(entries) {
+    return entries.map((e) => {
+        const day = (e.at ?? "").slice(0, 10);
+        const c = e.credit;
+        if (c) {
+            const state = wordFor(CREDIT_ENDED, c.status) ??
+                `${usd(c.remaining_usd)} left, ${c.expires_at ? `expires ${c.expires_at.slice(0, 10)}` : "no expiry"}`;
+            return `  ${day}  ${wordFor(CREDIT_WHAT, c.kind) ?? "Credit"}  ${usd(c.granted_usd)}  ${state}`;
+        }
+        const p = e.payment;
+        if (!p)
+            return `  ${day}  (a row this version cannot show: see --json)`;
+        const check = p.kind === "method_check";
+        const what = check
+            ? `$${Number.isInteger(p.amount_usd) ? String(p.amount_usd) : p.amount_usd.toFixed(2)} to confirm ${p.method || "your payment method"}`
+            : (wordFor(PAYMENT_WHAT, p.kind) ?? "Payment");
+        const detail = [p.plan ? `${p.plan} plan` : null, p.invoice_number ? `invoice ${p.invoice_number}` : null]
+            .filter(Boolean)
+            .join(", ");
+        const status = check && p.status === "failed" ? "failed" : (wordFor(PAYMENT_STATUS, p.status) ?? p.status);
+        const url = typeof p.invoice_url === "string" && p.invoice_url.startsWith("https://") ? p.invoice_url : null;
+        const link = url && !check ? ` · ${unpaid(p.status) ? "pay at" : "receipt"} ${url}` : "";
+        return `  ${day}  ${what}${detail ? ` (${detail})` : ""}  ${usd(p.amount_usd)}  ${status}${link}`;
+    });
+}
+const billingHistory = async (ctx) => {
+    const kind = str(ctx, "--kind") ?? "all";
+    if (!HISTORY_KINDS.includes(kind)) {
+        throw usageError(`--kind: '${kind}' is not a kind`, `Pass one of ${HISTORY_KINDS.join(" | ")}.`);
+    }
+    const limit = limitOf(ctx, 50, 100);
+    const cursor = str(ctx, "--cursor");
+    const page = await client(ctx).billing.historyPage({
+        kind: kind,
+        limit,
+        ...(cursor === undefined ? {} : { cursor }),
+    });
+    const entries = page.items;
+    const more = page.nextCursor;
+    const owed = entries.some((e) => e.payment && e.payment.kind !== "method_check" && unpaid(e.payment.status));
+    const next = nexts(...(more
+        ? [[`${sh `promigence billing history --limit ${String(limit)}`}${kind === "all" ? "" : sh ` --kind ${kind}`}${sh ` --cursor ${more}`}`, "the next page"]]
+        : []), ...(owed
+        ? [["promigence billing portal", "pay the open invoice, or update the card on file"]]
+        : [["promigence billing usage", "this month's spend and credit"]]));
+    const empty = { all: "no credits or payments yet", credits: "no credit yet", payments: "no payments yet" };
+    const noun = kind === "all" ? "" : ` ${entries.length === 1 ? kind.slice(0, -1) : kind}`;
+    const lines = [
+        `promigence billing history: ${entries.length}${noun}, newest first`,
+        ...historyLines(entries),
+        ...(entries.length ? [] : [`  (${empty[kind]})`]),
+        ...(more ? [`  more: --cursor ${more}`] : []),
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { kind, entries, count: entries.length, next_cursor: more }, next), lines, 0, ctx.pointer);
+};
 const referrals = async (ctx) => {
     const r = await client(ctx).billing.referrals();
     const next = r.code
@@ -745,6 +828,7 @@ export const ACCOUNT_HANDLERS = {
     status,
     "billing usage": billingUsage,
     "billing portal": billingPortal,
+    "billing history": billingHistory,
     referrals,
     "referrals apply": referralsApply,
     "snapshot delete": snapshotDelete,

package/dist/errfix.js

@@ -106,6 +106,7 @@ function notFoundFor(kind, ctx, apiFix) {
 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}.`)

package/dist/generated.js

@@ -106,7 +106,7 @@ export const ERRORS = [
         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 key from that org, or ask an owner." },
+        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`)." },
@@ -191,7 +191,7 @@ export const ERRORS = [
     { 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: 10, billed: "no",
+    { 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",
@@ -199,7 +199,10 @@ export const ERRORS = [
         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. After a failed payment, new work waits until it is paid (owners: `promigence billing portal`)." },
+        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`." },
@@ -266,6 +269,9 @@ export const CLIENT_ERRORS = [
     { 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." },

package/dist/guide.js

@@ -5,11 +5,11 @@ export const BILLED_TEXT = {
     credited: "no: ours, credited back",
     unless_ours: "the time used is billed, unless the cause is shown to be ours: then it is credited back",
 };
-import { DOCS_URL, EXIT_CODES, EXIT_PRECEDENCE_TEXT, GOLDEN_PATH, GROUPS, GUIDE_COMMON_ERRORS, LISTED_COMMANDS, LIVE_SUMMARY, NOT_LIVE_SUMMARY, SCHEMA, VERSION, WAIT_TIMEOUT_DEFAULT, } from "./surface.js";
+import { DOCS_URL, EXIT_CODES, EXIT_PRECEDENCE_TEXT, GOLDEN_PATH, GROUPS, GUIDE_COMMON_ERRORS, LISTED_COMMANDS, NOT_LIVE_SUMMARY, SCHEMA, VERSION, WAIT_TIMEOUT_DEFAULT, compactNames, } from "./surface.js";
 export const SECTIONS = ["core", "commands", "errors", "cost"];
 export const BUDGETS = {
-    core: 1200,
-    commands: 4475,
+    core: 1500,
+    commands: 4500,
     errors: 2325,
     cost: 600,
 };
@@ -20,7 +20,25 @@ export function lookupError(code) {
 export const ALL_ERROR_CODES = [...ERRORS, ...CLIENT_ERRORS].map((e) => e.code);
 export const estimateTokens = (s) => Math.ceil(s.length / 4);
 const exitLine = EXIT_CODES.filter((e) => e.code !== 125 && e.code !== 13).map((e) => `${e.code} ${e.name}`).join(" · ");
+const codesOn = (n) => ERRORS.filter((e) => e.exit === n).map((e) => e.code).join(", ");
+const EXIT_NOTE = {
+    7: codesOn(7),
+    10: `${codesOn(10)} only: retry after Retry-After`,
+    12: `some sandboxes ${codesOn(12)}`,
+    13: "agent-guide --check: files would change",
+    125: "exec --sandbox: ours; else the command's code",
+};
+const exitLegend = EXIT_CODES.map((e) => `${e.code} ${e.name}${EXIT_NOTE[e.code] ? ` (${EXIT_NOTE[e.code]})` : ""}`).join(" · ");
 const liveNames = new Set(LISTED_COMMANDS.map((c) => c.name));
+const HOSTED_LIVE = compactNames(LISTED_COMMANDS.filter((c) => !c.notOnHosted).map((c) => c.name));
+const NOT_ON_HOSTED = LISTED_COMMANDS.filter((c) => c.notOnHosted);
+const COUNT_WORDS = ["no", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"];
+const exitOf = (code) => {
+    const e = ERROR_BY_CODE[code];
+    if (!e)
+        throw new Error(`the guide names ${code}, which is not a known error code`);
+    return e.exit;
+};
 function renderCore() {
     const common = GUIDE_COMMON_ERRORS.map((code) => {
         const e = ERROR_BY_CODE[code];
@@ -63,15 +81,22 @@ function renderCore() {
         "Progress, prices and diagnostics go to **stderr** — never parse them. `next[].cmd` is",
         "id-based, runnable verbatim (fill any UPPERCASE word); use it, never invent one.",
         "",
-        `Exit codes: ${exitLine}.`,
+        `Exit codes: ${exitLegend}.`,
         `Highest-precedence code wins: ${EXIT_PRECEDENCE_TEXT}.`,
         "",
-        "## The six you will actually hit",
+        `## The ${COUNT_WORDS[common.length] ?? common.length} you will actually hit`,
         "",
         "(`{name}` in a fix is filled from the failure's evidence.)",
         "",
         ...common,
         "",
+        "## Limits and stops",
+        "",
+        `- \`setup_required\` (exit ${exitOf("setup_required")}): answer the account's setup questions in the console first.`,
+        `- \`egress_cap_reached\` (exit ${exitOf("egress_cap_reached")}): the month's data out is spent; \`--network none\` still starts; it resets on the 1st (UTC).`,
+        "- A paused sandbox is kept 30 days (`pause_expires_at`); resuming keeps it, else it is deleted (`expired`).",
+        `- \`stopped_by_support\` (exit ${exitOf("stopped_by_support")}): support stopped it; the message says why.`,
+        "",
         "## Do",
         "",
         "- Pass `--cap USD` on every `fork`/`run`: a run over it is refused (exit 5) before anything starts.",
@@ -99,7 +124,10 @@ function renderCore() {
         `· \`promigence <command> --help\` · ${DOCS_URL}`,
         "Same surface as MCP tools: `promigence mcp` (stdio; `claude mcp add promigence -- promigence mcp`).",
         "",
-        `Live in v${VERSION}: ${LIVE_SUMMARY}`,
+        `Live in v${VERSION}: ${HOSTED_LIVE}`,
+        ...(NOT_ON_HOSTED.length
+            ? [`Not on the hosted service yet: ${compactNames(NOT_ON_HOSTED.map((c) => c.name))} (${[...new Set(NOT_ON_HOSTED.map((c) => c.notOnHosted))].join(", ")}).`]
+            : []),
         ...(NOT_LIVE_SUMMARY ? ["Every other command exits 1 `not_released` in the same envelope."] : []),
         "",
     ].join("\n");
@@ -320,7 +348,7 @@ export function renderLlmsTxt() {
         "",
         "## Index",
         "",
-        ...LISTED_COMMANDS.map((c) => `- \`promigence ${c.name}\` — ${c.summary}`),
+        ...LISTED_COMMANDS.map((c) => `- \`promigence ${c.name}\` — ${c.summary}${c.notOnHosted ? ` (not on the hosted service yet)` : ""}`),
         "",
         "- `promigence agent-guide` — this document's first section",
         "- `promigence agent-guide --section commands` — every command with its flags",

package/dist/handlers.js

@@ -1,6 +1,6 @@
 import { existsSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { BUNDLE_EXT, DEFAULT_SNAPSHOT, PromigenceError, VERSION as SDK_VERSION, configDir, credentialsPath, compatApiKey, platformOf, readCredentialsWithStore, renderBundle, verifyBundle, } from "./sdk/index.js";
+import { BUNDLE_EXT, DEFAULT_SNAPSHOT, PromigenceError, VERSION as SDK_VERSION, configDir, credentialsPath, platformOf, readCredentialsWithStore, renderBundle, verifyBundle, } from "./sdk/index.js";
 import { storeLabel } from "./sdk/credstore.js";
 import { bool, client, list, nexts, positional, required, str, } from "./commands.js";
 import { emit, exitWith, forkSummary, markGuideSeen, ms, okEnvelope, parseCount, parseDuration, parseUsd, pickExit, usageError, write, } from "./io.js";
@@ -30,7 +30,7 @@ const agentGuide = async (ctx) => {
         const skipped = res.artifacts.find((a) => a.action === "skipped");
         const next = nexts(...(skipped
             ? [["promigence agent-guide --install --create", "create AGENTS.md and write the fence into it"]]
-            : []), ["promigence agent-guide", "the guide itself (~1.2k tokens)"], ["promigence examples", "what you can fork with no build (the built-in base)"]);
+            : []), ["promigence agent-guide", "the guide itself (~1.4k tokens)"], ["promigence examples", "what you can fork with no build (the built-in base)"]);
         const env = okEnvelope(ctx.cmd.name, {
             mode: checking ? "check" : "install",
             dir: res.dir,
@@ -259,9 +259,6 @@ function keySource(ctx) {
     if (creds.api_key) {
         return { source: store === "file" || store === undefined ? credentialsPath() : `${storeLabel(store)} (item ${credentialsPath()})`, present: true };
     }
-    if (compatApiKey(process.env["E2B_API_KEY"])) {
-        return { source: "E2B_API_KEY (compatibility)", present: true };
-    }
     return { source: "none", present: false };
 }
 async function clientChecks(ctx) {

package/dist/live.js

@@ -8,6 +8,7 @@ const FOLLOW_WAIT_MS = 1_000;
 const FOLLOW_POLL_MS = 250;
 const pause = (ms) => new Promise((r) => { setTimeout(r, ms); });
 const sandboxFlag = (ctx) => required(ctx, "--sandbox", `Pass --sandbox sbx_<id> (from \`promigence run report <run_id>\`), e.g. promigence ${ctx.cmd.name} … --sandbox sbx_01.`);
+export const RECONNECTED_LINE = "the service restarted; reconnected to a new shell";
 const sandboxShell = async (ctx) => {
     const sid = positional(ctx, "a sandbox id", "promigence sandbox shell sbx_01");
     const tail = ctx.cmdTail.length ? ctx.cmdTail.map(shellQuote).join(" ") : undefined;
@@ -45,6 +46,13 @@ const sandboxShell = async (ctx) => {
         ...(cmd === undefined ? {} : { cmd }),
         ...(secrets.length ? { secrets } : {}),
         onData: (d) => { stdout.write(d); },
+        reconnect: inner === undefined,
+        onReconnected: ({ resumed }) => {
+            if (resumed)
+                return;
+            const line = RECONNECTED_LINE;
+            void write(process.stderr, process.stderr.isTTY ? `\r\n\x1b[2m${line}\x1b[0m\r\n` : `promigence sandbox shell: ${line}\n`);
+        },
     });
     const restore = () => {
         if (tty && stdin.isRaw)

package/dist/login.js

@@ -121,7 +121,7 @@ function apiUrlSource() {
         return "PROMIGENCE_API_URL";
     if (readCredentials().api_url)
         return `the api_url in ${credentialsPath()}`;
-    return "E2B_API_URL / E2B_DOMAIN";
+    return "the stored sign-in";
 }
 async function ask(prompt) {
     const rl = createInterface({ input: process.stdin, output: process.stderr });

package/dist/mcp.js

@@ -688,8 +688,11 @@ const mcp = async (ctx) => {
     });
     let cached;
     let cachedFrom = "";
+    const keyGiven = ctx.apiKey !== undefined || Boolean(process.env["PROMIGENCE_API_KEY"]?.trim());
     const session = {
         client: () => {
+            if (keyGiven)
+                return (cached ??= freshClient());
             forgetKeychainReads();
             const from = JSON.stringify(readCredentials());
             if (cached && from === cachedFrom)

package/dist/routes.js

@@ -42,6 +42,7 @@ export const ROUTE_COMMANDS = {
     "GET /orgs/:id/audit": "org audit",
     "GET /pricing": "pricing",
     "GET /billing": "billing usage",
+    "GET /billing/history": "billing history",
     "GET /me/ledger": "billing usage",
     "GET /me/outcomes": "me",
     "POST /billing/checkout": "billing card",

package/dist/sdk/client.d.ts

@@ -748,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;
@@ -906,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?: {
@@ -929,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;
@@ -2033,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;
@@ -2433,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>;

package/dist/sdk/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, 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, 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";
@@ -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 };
@@ -652,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));
@@ -1258,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" }),
@@ -1752,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);
@@ -1987,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 {

package/dist/sdk/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.7";
+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/sdk/core.js

@@ -1,5 +1,5 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.7";
+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,
@@ -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,

package/dist/sdk/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