promigence 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/account.js

@@ -3,6 +3,8 @@ import { queuedLines } from "./capacity.js";
 import { duration } from "./report.js";
 import { emit, ms, okEnvelope, overMost, parseCount, parseDuration, parseUsd, usageError } from "./io.js";
 import { sh } from "./term.js";
+import { autoReloadShort, creditsLine, resumeAllPausedForCredits } from "./billing.js";
+import { dollars } from "./money.js";
 const usd = (n) => n === undefined ? "—" : `$${n.toFixed(n < 0.01 && n > 0 ? 4 : 2)}`;
 export const PAYMENT_METHOD_NAMES = {
     apple_pay: "Apple Pay",
@@ -115,10 +117,10 @@ const me = async (ctx) => {
         lines.push(`  plan: ${plan}${trial?.on_trial ? " (trial)" : ""}`);
     if (conc)
         lines.push(`  concurrency: ${concurrencyText(conc)}`);
-    if (trial?.on_trial) {
-        const left = trial.credits_available ?? trial.credits_remaining;
-        lines.push(`  trial credit: ${usd(left)} left of ${usd(trial.credits_granted)}` +
-            `${trial.credits_reserved ? ` (${usd(trial.credits_reserved)} held for running sandboxes)` : ""}`);
+    if (trial) {
+        const available = trial.credits_available ?? trial.credits_remaining;
+        const held = trial.credits_reserved ?? 0;
+        lines.push(`  credits: ${dollars(available)} available${held > 0 ? ` (${dollars(held)} held by running work)` : ""}`);
     }
     if (typeof info.spend === "number") {
         const kinds = Object.entries(info.spend_detail?.by_kind ?? {}).filter(([, v]) => v > 0);
@@ -213,7 +215,7 @@ const billingUsage = async (ctx) => {
         ? [["promigence me", "your limits, concurrency and trial credit"]]
         : b.card_on_file
             ? [["promigence billing portal", "the card on file and past invoices"]]
-            : [["promigence billing card", "an owner adds a card (nothing is charged now)"]]), ...(moreLedger.length ? moreLedger : [["promigence billing usage --ledger", "this key's project's metered rows"]]));
+            : [["promigence billing card", "an owner adds a card"]]), ...(moreLedger.length ? moreLedger : [["promigence billing usage --ledger", "this key's project's metered rows"]]));
     const plan = planName(me, b);
     const onTrial = (b.trial?.on_trial ?? me?.trial?.on_trial) === true;
     const env = okEnvelope(ctx.cmd.name, {
@@ -255,22 +257,26 @@ const billingUsage = async (ctx) => {
         lines.push(`  ${k}: ${detail(row)}`);
     }
     if (typeof usage["credits_applied"] === "number" && usage["credits_applied"] > 0) {
-        lines.push(`  paid by trial credits: ${usd(usage["credits_applied"])} · to the card: ${usd(usage["billable"])}`);
+        lines.push(`  paid from credits: ${usd(usage["credits_applied"])}`);
     }
     const trial = b.trial;
-    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)" : ""}`}`);
+    const credits = creditsLine(b.credits) ?? (trial?.credits_remaining === undefined ? undefined : `credits: ${dollars(trial.credits_remaining)} available`);
+    if (credits)
+        lines.push(`  ${credits}`);
+    if (b.auto_reload)
+        lines.push(`  auto-reload: ${autoReloadShort(b.auto_reload)}`);
+    lines.push(`  card: ${b.card_on_file ? paymentMethodText(b.card) : `none on file${billingOff ? " (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) {
+    const invoiceComes = b.plan_status === undefined || !!b.plan_status.renews_at || b.model === "postpaid";
+    if (invoiceComes && b.upcoming_invoice?.amount_due !== undefined && b.upcoming_invoice?.amount_due !== null) {
         lines.push(`  next invoice: ${usd(b.upcoming_invoice.amount_due)}`);
     }
-    else if (b.upcoming_invoice_error) {
+    else if (invoiceComes && b.upcoming_invoice_error) {
         lines.push(`  next invoice: not available (${b.upcoming_invoice_error})`);
     }
     if (b.suspended)
-        lines.push(`  SUSPENDED: ${b.suspend_reason ?? "see promigence billing card"}`);
+        lines.push(`  SUSPENDED: ${b.suspend_reason ?? "see promigence billing"}`);
     for (const e of entries) {
         lines.push(`  ${e.created_at ?? ""} ${e.kind}${e.tier ? ` ${e.tier}` : ""} ${usd(e.amount)}${e.seconds ? ` · ${e.seconds}s` : ""}${e.run_id ? ` · ${e.run_id}` : ""}`);
     }
@@ -294,12 +300,19 @@ const CREDIT_WHAT = {
     from_promigence: "Credit from Promigence",
     service_restart: "Credit for a service restart",
     confirmation_credit: "Credit for the $1 confirmation",
+    credits_bought: "Credits bought",
+    auto_reload: "Auto-reload",
+    credit_taken_back: "Credit taken back",
+    credit_regranted: "Credit given back",
 };
 const CREDIT_ENDED = { used: "used", expired: "expired", taken_back: "taken back" };
 const PAYMENT_WHAT = {
     invoice_paid: "Invoice paid",
     payment_failed: "Payment failed",
     refund: "Refund",
+    credits_bought: "Credits bought",
+    auto_reload: "Auto-reload",
+    dispute_repaid: "Repayment",
 };
 const PAYMENT_STATUS = {
     paid: "paid",
@@ -323,15 +336,30 @@ export function historyLines(entries) {
         if (!p)
             return `  ${day}  (a row this version cannot show: see --json)`;
         const check = p.kind === "method_check";
+        const planFee = p.kind === "plan_invoice";
         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]
+            : planFee
+                ? `Plan: ${p.plan ?? "your plan"}`
+                : (wordFor(PAYMENT_WHAT, p.kind) ?? "Payment");
+        const detail = [p.plan && !planFee ? `${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}` : "";
+        const https = (u) => (typeof u === "string" && u.startsWith("https://") ? u : null);
+        const linked = [
+            https(p.invoice_pdf) ? `invoice ${p.invoice_pdf}` : null,
+            https(p.receipt_url) ? `receipt ${p.receipt_url}` : null,
+            https(p.pay_url) ? `pay at ${p.pay_url}` : null,
+        ].filter(Boolean);
+        const url = https(p.invoice_url);
+        const link = check
+            ? ""
+            : linked.length
+                ? ` · ${linked.join(" · ")}`
+                : url
+                    ? ` · ${unpaid(p.status) ? "pay at" : "receipt"} ${url}`
+                    : "";
         return `  ${day}  ${what}${detail ? ` (${detail})` : ""}  ${usd(p.amount_usd)}  ${status}${link}`;
     });
 }
@@ -378,11 +406,11 @@ const referrals = async (ctx) => {
         const o = r.offer;
         lines.push(`promigence referrals: ${o.headline}`);
         lines.push(`  your code: ${r.code}  (a friend signs up with: ${sh `promigence login --ref ${r.code}`})`);
-        lines.push(`  they get ${usd(o.give_usd)} of compute credit when they pay their first plan invoice` +
-            `${o.qualifying_plans.length ? ` on ${o.qualifying_plans.join(" / ")}` : ""}; you get ${usd(o.get_usd)} ` +
-            `${o.hold_days > 0 ? `${o.hold_days} day(s) later` : "then"}`);
+        lines.push(`  they get ${usd(o.give_usd)} of compute credit once they first pay at least ${usd(o.give_usd)}, for credits or a plan` +
+            `${o.qualifying_plans.length ? ` (plans: ${o.qualifying_plans.join(" / ")})` : ""}; you get ${usd(o.get_usd)} ` +
+            `${o.hold_days > 0 ? `${o.hold_days} ${o.hold_days === 1 ? "day" : "days"} later` : "then"}`);
         if (o.credit_expiry_days !== null)
-            lines.push(`  credit lasts ${o.credit_expiry_days} day(s) from its grant`);
+            lines.push(`  credit lasts ${o.credit_expiry_days} ${o.credit_expiry_days === 1 ? "day" : "days"} from its grant`);
         if (o.ends_at)
             lines.push(`  offer ends ${o.ends_at}`);
     }
@@ -405,8 +433,8 @@ const referralsApply = async (ctx) => {
         ? [`promigence referrals apply: ${r.code} recorded; it is being checked before any credit is granted`]
         : [
             `promigence referrals apply: ${r.code} applied`,
-            `  you get ${usd(r.reward_usd)} of compute credit when you pay your first plan invoice` +
-                `${r.qualifying_plans.length ? ` on ${r.qualifying_plans.join(" / ")}` : ""}`,
+            `  you get ${usd(r.reward_usd)} of compute credit once you first pay at least ${usd(r.reward_usd)}, for credits or a plan` +
+                `${r.qualifying_plans.length ? ` (plans: ${r.qualifying_plans.join(" / ")})` : ""}`,
         ];
     return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), lines, 0, ctx.pointer);
 };
@@ -636,7 +664,7 @@ const sandboxInfo = async (ctx) => {
     const limitNext = s.pause_reason === "spend_cap"
         ? [[sh `promigence sandbox resume ${sid} --cap USD`, "raise its run's cap and go on (paused time is not billed)"]]
         : s.pause_reason === "credits_exhausted"
-            ? [["promigence billing card", "add a card, then resume it"], [sh `promigence sandbox resume ${sid}`, "go on once credits are added"]]
+            ? [["promigence billing buy USD", "add credits, then resume it"], [sh `promigence sandbox resume ${sid}`, "go on once credits are added"]]
             : [];
     const next = nexts(...limitNext, ...(execs.length ? [[sh `promigence exec output ${execs[execs.length - 1].exec_id} --sandbox ${sid}`, "what its last command printed"]] : []), ...(ended
         ? (s.run_id ? [[sh `promigence run report ${s.run_id} --sandbox ${sid}`, "how it ended, in its run's report"]] : [])
@@ -684,6 +712,12 @@ const sandboxPause = async (ctx) => {
     return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...res, sandbox_id: sid, state: "paused" }, next), lines, 0, ctx.pointer);
 };
 const sandboxResume = async (ctx) => {
+    if (bool(ctx, "--all-paused-for-credits")) {
+        if (ctx.args[0] !== undefined) {
+            throw usageError("--all-paused-for-credits takes no sandbox id", "Pass a sandbox id, or --all-paused-for-credits alone.");
+        }
+        return resumeAllPausedForCredits(ctx);
+    }
     const sid = positional(ctx, "a sandbox id", "promigence sandbox resume sbx_01");
     const optimizeFor = optimizeForFlag(ctx);
     const cap = str(ctx, "--cap");

package/dist/billing.js

@@ -0,0 +1,266 @@
+import { bool, client, nexts, str, waitBound } from "./commands.js";
+import { emit, errorEnvelope, okEnvelope, parseUsd, usageError } from "./io.js";
+import { dollars } from "./money.js";
+import { PromigenceError, TimeoutError } from "./sdk/index.js";
+import { sh } from "./term.js";
+export const BILLING_PAGE = "https://console.promigence.ai/settings/org/billing";
+export const MIN_PURCHASE_USD = 5;
+export function cardWords(card) {
+    const NAMES = {
+        visa: "Visa", mastercard: "Mastercard", amex: "American Express", discover: "Discover", diners: "Diners Club",
+        jcb: "JCB", unionpay: "UnionPay", apple_pay: "Apple Pay", google_pay: "Google Pay", link: "Link",
+        cashapp: "Cash App Pay", amazon_pay: "Amazon Pay",
+    };
+    const brand = card?.brand ?? "";
+    const named = brand ? (Object.prototype.hasOwnProperty.call(NAMES, brand) ? NAMES[brand] : brand) : "";
+    const last4 = card?.last4 ?? "";
+    if (named && last4)
+        return `your ${named} ending ${last4}`;
+    if (named)
+        return `your ${named}`;
+    if (last4)
+        return `your card ending ${last4}`;
+    return "your card";
+}
+export function dateWords(at) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(at ?? "");
+    const MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+    if (!m)
+        return at ?? "";
+    const month = MONTHS[Number(m[2]) - 1];
+    return month ? `${Number(m[3])} ${month} ${m[1]}` : (at ?? "");
+}
+const PAUSED_PAYMENT = {
+    declined: "the card was declined",
+    authentication_required: "your bank asks you to confirm the payment",
+};
+const LOWER_IT = "promigence billing auto-reload --on --below <usd> --add <usd> --accept";
+export function autoReloadLines(a, trust) {
+    if (!a)
+        return ["Auto-reload is off."];
+    if (a.unavailable_reason === "card_country") {
+        return ["Auto-reload isn't available yet for cards issued in India. Top up by hand: promigence billing buy <usd>."];
+    }
+    if (a.paused_reason) {
+        switch (a.paused_reason) {
+            case "declined":
+            case "authentication_required": {
+                const pay = a.last?.pay_url ? ` (${a.last.pay_url})` : "";
+                return [`Auto-reload is paused: ${PAUSED_PAYMENT[a.paused_reason]}. Finish the payment${pay} or add credits to turn it back on.`];
+            }
+            case "daily_limit":
+                return ["Auto-reload is paused: it starts again tomorrow (UTC)."];
+            case "disputed":
+                return ["Auto-reload is paused while a payment for this organization is disputed."];
+            case "amount_over_limit":
+                return [`Auto-reload is paused: its amount is above this organization's limit (${dollars(trust?.reload_max_usd)}). Lower it: ${LOWER_IT}`];
+            case "support":
+                return ["Auto-reload is paused by Promigence support. Write to support@promigence.ai to turn it back on."];
+            default:
+                return [`Auto-reload is paused: ${a.paused_reason}.`];
+        }
+    }
+    if (!a.on)
+        return ["Auto-reload is off."];
+    return [`Auto-reload is on: when available credits fall below ${dollars(a.threshold_usd)}, add ${dollars(a.amount_usd)} from ${cardWords(a.card)}.`];
+}
+export function autoReloadShort(a) {
+    if (!a || !a.on)
+        return "off";
+    const base = `below ${dollars(a.threshold_usd)}, add ${dollars(a.amount_usd)}`;
+    return a.paused_reason ? `${base} (paused: ${a.paused_reason.replaceAll("_", " ")})` : base;
+}
+export function creditsLine(c) {
+    if (!c)
+        return undefined;
+    return `credits: ${dollars(c.available_usd)} available${c.held_usd > 0 ? ` (${dollars(c.held_usd)} held by running work)` : ""}`;
+}
+const billing = async (ctx) => {
+    const c = client(ctx);
+    const [b, me] = await Promise.all([c.billing.usage(), c.me().catch(() => undefined)]);
+    const org = me?.org && me.org !== me.org_id ? me.org : (b.org_id ?? me?.org_id ?? "org");
+    const lines = [`promigence billing: ${org}`];
+    const plan = b.plan_status;
+    if (plan?.name)
+        lines.push(`  plan: ${plan.name}${plan.renews_at ? ` (renews ${dateWords(plan.renews_at)})` : ""}`);
+    if (plan?.renewal) {
+        const said = plan.renewal.state === "action_required"
+            ? `Your bank asks you to confirm the ${plan.name} payment.`
+            : `Your ${plan.name} renewal did not go through.${plan.renewal.next_try_at ? ` We try again on ${dateWords(plan.renewal.next_try_at)}.` : ""}`;
+        lines.push(`  renewal: ${said}${plan.renewal.pay_url ? ` ${plan.renewal.pay_url}` : ""}`);
+    }
+    if (b.credits)
+        lines.push(`  credits: ${dollars(b.credits.available_usd)} available`);
+    if (b.model === "postpaid" && b.switch) {
+        lines.push(`  moves to credits on ${dateWords(b.switch.at)} (${dollars(b.switch.credits_waiting_usd)} ready)`);
+    }
+    lines.push(`  auto-reload: ${autoReloadShort(b.auto_reload)}`);
+    if (b.hold)
+        lines.push(`  on hold: ${b.hold.reason}: ${b.hold.url ?? BILLING_PAGE}`);
+    lines.push(`  change plan: ${BILLING_PAGE}`);
+    const next = nexts(...(b.hold?.dispute_id ? [[sh `promigence billing repay ${b.hold.dispute_id}`, "repay the disputed payment, which lifts the hold"]] : []), ["promigence billing buy USD", "add credits on a payment page"], ["promigence billing auto-reload", "add credits from the saved card when available credits run low"], ["promigence billing usage", "this month's spend"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { billing: b }, next), lines, 0, ctx.pointer);
+};
+const FINAL = new Set(["paid", "paid_awaiting_switch", "expired", "failed"]);
+const delay = (msMs) => new Promise((r) => setTimeout(r, msMs));
+function settledLine(s) {
+    switch (s.state) {
+        case "paid":
+            return `${dollars(s.amount_usd)} of credits added.${s.available_usd === undefined || s.available_usd === null ? "" : ` Available: ${dollars(s.available_usd)}.`}`;
+        case "paid_awaiting_switch":
+            return `${dollars(s.amount_usd)} of credits are ready on ${dateWords(s.switch_at)}.`;
+        case "expired":
+            return "No payment was made.";
+        case "failed":
+            return "The payment did not go through. No credits were added.";
+        default:
+            return "Payment received. Your credits will appear in a minute.";
+    }
+}
+const billingBuy = async (ctx) => {
+    const c = client(ctx);
+    const session = str(ctx, "--session");
+    const bound = waitBound(ctx);
+    let page;
+    if (session === undefined) {
+        const raw = ctx.args[0];
+        if (raw === undefined)
+            throw usageError("billing buy needs an amount in dollars", "Example: promigence billing buy 50.");
+        const amount = parseUsd(raw.replace(/^\$/, ""), "USD");
+        if (amount < MIN_PURCHASE_USD) {
+            throw usageError(`promigence billing buy: the smallest purchase is ${dollars(MIN_PURCHASE_USD)}.`, "Choose an amount from $5 to $10,000.");
+        }
+        page = await c.billing.buyCredits(amount);
+        process.stderr.write(`promigence billing buy: open this page to pay ${dollars(page.amount_usd)} for credits:\n  ${page.url}\n`);
+        if (bool(ctx, "--no-wait")) {
+            const next = nexts([sh `promigence billing buy --session ${page.session_id}`, "check the payment and add its credits"]);
+            return emit(ctx.mode, okEnvelope(ctx.cmd.name, { page }, next), [
+                `promigence billing buy: open this page to pay ${dollars(page.amount_usd)} for credits:`,
+                `  ${page.url}`,
+            ], 0, ctx.pointer);
+        }
+    }
+    const id = session ?? page.session_id;
+    const settle = () => c.billing.settleCredits(id);
+    const until = Date.now() + bound;
+    if (page)
+        process.stderr.write("Waiting for the payment (Ctrl-C stops waiting; a payment still counts)\n");
+    let s = await settle();
+    while (!FINAL.has(s.state) && Date.now() < until) {
+        await delay(Math.min(2000, Math.max(0, until - Date.now())));
+        s = await settle();
+    }
+    if (!FINAL.has(s.state)) {
+        const err = new TimeoutError(`the payment page was not paid within the ${Math.round(bound / 1000)} s wait; nothing was charged by this command`, `A payment on the page still counts. Check it: ${sh `promigence billing buy --session ${id}`}.`);
+        const next = nexts([sh `promigence billing buy --session ${id}`, "check the payment and add its credits"]);
+        return emit(ctx.mode, { ...errorEnvelope(ctx.cmd.name, err, next), ...(page ? { page } : {}), settle: s }, [`promigence billing buy: ${err.message}`, `  ${err.fix}`], 11, ctx.pointer);
+    }
+    const ok = s.state === "paid" || s.state === "paid_awaiting_switch";
+    const next = ok
+        ? nexts(["promigence billing", "the credits, auto-reload and the plan"])
+        : nexts(["promigence billing buy USD", "open a new payment page"]);
+    const line = settledLine(s);
+    if (!ok) {
+        const err = new PromigenceError({ code: "usage", message: line, fix: "Open a new payment page: promigence billing buy <usd>.", exitCode: 2 });
+        return emit(ctx.mode, { ...errorEnvelope(ctx.cmd.name, err, next), settle: s }, [`promigence billing buy: ${line}`], 2, ctx.pointer);
+    }
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...(page ? { page } : {}), settle: s }, next), [line], 0, ctx.pointer);
+};
+export function authorizationText(b, threshold, amount) {
+    const a = b.auto_reload;
+    const template = a?.authorization?.template ?? "";
+    return template
+        .replaceAll("{card}", cardWords(a?.card))
+        .replaceAll("{amount}", dollars(amount))
+        .replaceAll("{threshold}", dollars(threshold))
+        .replaceAll("{n}", String(b.trust?.reloads_per_day ?? ""))
+        .replaceAll("{day_max}", dollars(b.trust?.per_day_max_usd));
+}
+const billingAutoReload = async (ctx) => {
+    const c = client(ctx);
+    const on = bool(ctx, "--on");
+    const off = bool(ctx, "--off");
+    const below = str(ctx, "--below");
+    const add = str(ctx, "--add");
+    if (on && off)
+        throw usageError("--on and --off together", "Pass one of them.");
+    if (!on && (below !== undefined || add !== undefined || bool(ctx, "--accept"))) {
+        throw usageError("--below, --add and --accept go with --on", "Example: promigence billing auto-reload --on --below 10 --add 50 --accept.");
+    }
+    const next = nexts(["promigence billing", "the credits and the plan"]);
+    if (!on && !off) {
+        const a = await c.billing.autoReload();
+        const trust = a.paused_reason === "amount_over_limit" ? (await c.billing.usage()).trust : undefined;
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { auto_reload: a }, next), autoReloadLines(a, trust), 0, ctx.pointer);
+    }
+    if (off) {
+        const a = await c.billing.setAutoReload({ on: false });
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { auto_reload: a }, next), autoReloadLines(a), 0, ctx.pointer);
+    }
+    const b = await c.billing.usage();
+    if (b.auto_reload?.unavailable_reason === "card_country") {
+        throw usageError("Auto-reload isn't available yet for cards issued in India.", "Top up by hand: promigence billing buy <usd>.");
+    }
+    const threshold = below === undefined ? (b.auto_reload?.threshold_usd ?? 10) : parseUsd(below, "--below");
+    const amount = add === undefined ? (b.auto_reload?.amount_usd ?? 50) : parseUsd(add, "--add");
+    if (!bool(ctx, "--accept")) {
+        throw usageError(authorizationText(b, threshold, amount), "Pass --accept to agree.");
+    }
+    const a = await c.billing.setAutoReload({
+        on: true,
+        thresholdUsd: threshold,
+        amountUsd: amount,
+        ...(b.auto_reload?.authorization?.version === undefined ? {} : { authorizationVersion: b.auto_reload.authorization.version }),
+    });
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { auto_reload: a }, next), autoReloadLines(a, b.trust), 0, ctx.pointer);
+};
+const billingHolds = async (ctx) => {
+    const h = await client(ctx).billing.holds();
+    const n = h.sandboxes.length;
+    const lines = [`promigence billing holds: ${dollars(h.held_usd)} held by ${n} ${n === 1 ? "sandbox" : "sandboxes"}`];
+    for (const s of h.sandboxes) {
+        lines.push(`  ${s.sandbox_id}  ${dollars(s.held_usd)}  ${s.state === "paused" || !s.ends_at ? "paused" : `ends ${s.ends_at}`}`);
+    }
+    for (const b of h.builds)
+        lines.push(`  ${b.build_id}  ${dollars(b.held_usd)}  build`);
+    if (h.data_out_usd > 0)
+        lines.push(`  data out not yet charged  ${dollars(h.data_out_usd)}`);
+    if (h.storage_usd > 0)
+        lines.push(`  storage, the next 7 days  ${dollars(h.storage_usd)}`);
+    const first = h.sandboxes[0];
+    const next = first
+        ? nexts([sh `promigence sandbox kill ${first.sandbox_id}`, "end it, and free what it holds"], [sh `promigence sandbox extend ${first.sandbox_id} --timeout DUR`, "change its lifetime (a shorter one holds less)"])
+        : nexts(["promigence billing", "the credits and the plan"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { holds: h }, next), lines, 0, ctx.pointer);
+};
+const billingRepay = async (ctx) => {
+    const dispute = ctx.args[0];
+    if (dispute === undefined) {
+        throw usageError("billing repay needs a dispute id", "`promigence billing` names the hold; its dispute id is in `promigence billing --json` (hold.dispute_id).");
+    }
+    const page = await client(ctx).billing.repayDispute(dispute);
+    const next = nexts(["promigence billing", "once it is paid: the hold is lifted"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { page }, next), [
+        `promigence billing repay: open this page to repay ${dollars(page.amount_usd)}:`,
+        `  ${page.url}`,
+    ], 0, ctx.pointer);
+};
+export const BILLING_HANDLERS = {
+    billing,
+    "billing repay": billingRepay,
+    "billing buy": billingBuy,
+    "billing auto-reload": billingAutoReload,
+    "billing holds": billingHolds,
+};
+export async function resumeAllPausedForCredits(ctx) {
+    const r = await client(ctx).sandboxes.resumePausedForCredits();
+    const n = r.resumed.length;
+    const m = r.still_need_credits.length;
+    const line = m > 0
+        ? `${n} resumed. ${m} still need credits: add credits with promigence billing buy <usd>.`
+        : `${n} resumed. ${m} still need credits.`;
+    const next = m > 0
+        ? nexts(["promigence billing buy USD", "add credits, then resume the rest"])
+        : nexts(["promigence sandbox list", "your sandboxes"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [line], 0, ctx.pointer);
+}

package/dist/bin.js

@@ -18,6 +18,7 @@ import { RUNNERS_HANDLERS } from "./runners.js";
 import { PRICING_HANDLERS } from "./pricing.js";
 import { GITHUB_HANDLERS } from "./github.js";
 import { GITLAB_HANDLERS } from "./gitlab.js";
+import { BILLING_HANDLERS } from "./billing.js";
 import { emit, errorEnvelope, errorTextLines, parseDuration, setBeforeExit, toPromigenceError, usageError as usageFailure, USAGE_DOCS, write, } from "./io.js";
 import { setCaller } from "./sdk/caller.js";
 import { sh } from "./term.js";
@@ -270,7 +271,7 @@ async function main(argv) {
         await write(process.stdout, renderCommandHelp(cmd));
         return;
     }
-    const handler = HANDLERS[cmd.name] ?? EXTRA_HANDLERS[cmd.name] ?? BUNDLE_HANDLERS[cmd.name] ?? LOGIN_HANDLERS[cmd.name] ?? ORG_HANDLERS[cmd.name] ?? LIVE_HANDLERS[cmd.name] ?? SSH_HANDLERS[cmd.name] ?? ACCOUNT_HANDLERS[cmd.name] ?? MCP_HANDLERS[cmd.name] ?? AGENT_HANDLERS[cmd.name] ?? CREDITS_HANDLERS[cmd.name] ?? RUNNERS_HANDLERS[cmd.name] ?? PRICING_HANDLERS[cmd.name] ?? GITHUB_HANDLERS[cmd.name] ?? GITLAB_HANDLERS[cmd.name] ?? TEMPLATES_HANDLERS[cmd.name];
+    const handler = HANDLERS[cmd.name] ?? EXTRA_HANDLERS[cmd.name] ?? BUNDLE_HANDLERS[cmd.name] ?? LOGIN_HANDLERS[cmd.name] ?? ORG_HANDLERS[cmd.name] ?? LIVE_HANDLERS[cmd.name] ?? SSH_HANDLERS[cmd.name] ?? ACCOUNT_HANDLERS[cmd.name] ?? MCP_HANDLERS[cmd.name] ?? AGENT_HANDLERS[cmd.name] ?? CREDITS_HANDLERS[cmd.name] ?? RUNNERS_HANDLERS[cmd.name] ?? PRICING_HANDLERS[cmd.name] ?? GITHUB_HANDLERS[cmd.name] ?? GITLAB_HANDLERS[cmd.name] ?? TEMPLATES_HANDLERS[cmd.name] ?? BILLING_HANDLERS[cmd.name];
     if (!handler)
         return void (await notReleased(mode, cmd));
     const ctx = {

package/dist/commands.js

@@ -1864,7 +1864,7 @@ const runComposite = async (ctx) => {
     const next = nexts(...(capPaused
         ? [limitPauseOf(capPaused) === "spend_cap"
                 ? [sh `promigence sandbox resume ${capPaused.sandbox_id} --cap USD`, "go on: a cap above the run's (its files and state are kept)"]
-                : ["promigence billing card", `add a card, then ${sh `promigence sandbox resume ${capPaused.sandbox_id}`}`]]
+                : ["promigence billing buy USD", `add credits, then ${sh `promigence sandbox resume ${capPaused.sandbox_id}`}`]]
         : []), [sh `promigence run report ${runId} --json`, "the full validity report (per-sandbox evidence)"], ...((report.totals?.env_failed ?? 0) > 0
         ? [[sh `promigence run replay ${runId}`, "re-fork the env failures (a replay is a new sandbox, billed like any other)"]]
         : []), ...(kept.length
@@ -2062,7 +2062,7 @@ export function limitPauseLines(report) {
         }
         else {
             lines.push(`  ${s.sandbox_id}: paused: the organization's credits ran out; its files and state are kept`);
-            lines.push(`    go on: add a card (owners: promigence billing card), then ${sh `promigence sandbox resume ${s.sandbox_id}`}, or end it: ${sh `promigence sandbox kill ${s.sandbox_id}`}`);
+            lines.push(`    go on: add credits (owners: promigence billing buy <usd>), then ${sh `promigence sandbox resume ${s.sandbox_id}`}, or end it: ${sh `promigence sandbox kill ${s.sandbox_id}`}`);
         }
     }
     if (paused.length > FAILURES_SHOWN) {

package/dist/errfix.js

@@ -103,18 +103,24 @@ function notFoundFor(kind, ctx, apiFix) {
             };
     }
 }
-const BILLING_CMD = /`promigence billing (?:card|portal)`/;
+const BILLING_CMD = /`promigence billing (?:card|portal|buy <usd>)`|Change plan in Billing/;
 export function withoutBilling(text) {
+    const more = `Payments are not open yet: for more credits, email ${SUPPORT}.`;
     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 move to a plan that allows it: (?:`promigence billing (?:card|portal)`|Change plan in Billing \(`promigence billing` prints the link\))\.?/, `, 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(/or lift it by adding a card \(`promigence billing card`\) or buying credits \(`promigence billing buy <usd>`\)/, `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);
+        .replace(/Add credits(?: to keep going)? \(owners: `promigence billing buy <usd>`, or Add credits in Billing; members ask an owner\)(?:, or turn on auto-reload)?\./, more)
+        .replace(/Add credits to go on \(owners: `promigence billing buy <usd>`; members ask an owner\), then resume it:/, `Payments are not open yet: email ${SUPPORT} for more credits, then resume it:`)
+        .replace(/Add credits by hand: `promigence billing buy <usd>`\./, `For more credits, email ${SUPPORT}.`)
+        .replace(/ Or add credits: `promigence billing buy <usd>`\./, "")
+        .replace(/Add a card(?: to keep going)? \(owners: `promigence billing (?:card|portal)`[^)]*\)\.?/, more)
+        .replace(/\(?owners: `promigence billing (?:card|portal|buy <usd>)`(?:; members ask an owner)?\)?/g, `email ${SUPPORT}`)
+        .replace(/`promigence billing (?:card|portal|buy <usd>)`/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`.";
+export const CREDIT_UNCLAIMED_FIX = "Claim your free credit first: `promigence credits claim` (owners; members ask an owner). Or add credits: `promigence billing buy <usd>`.";
 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))}\``],

package/dist/generated.js

@@ -79,7 +79,7 @@ export const ERRORS = [
         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}`." },
+        fix: "Its files and state are kept, and paused time is not billed. Add credits to go on (owners: `promigence billing buy <usd>`; 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." },
@@ -175,19 +175,34 @@ export const ERRORS = [
         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." },
+        fix: "Add credits to keep going (owners: `promigence billing buy <usd>`, or Add credits in Billing; members ask an owner). Running sandboxes finish the time they reserved." },
+    { code: "credits_exhausted", category: "cap", http: 402, exit: 5, billed: "no",
+        message: "available credits ({remaining}) do not cover this ({needed})",
+        fix: "Add credits (owners: `promigence billing buy <usd>`, or Add credits in Billing; members ask an owner), or turn on auto-reload. Running sandboxes finish the time they reserved." },
     { 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." },
+        fix: "Claim it in your browser: `promigence credits claim` (owners; members ask an owner). Or add credits: `promigence billing buy <usd>`. 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." },
+        fix: "Add a card (owners: `promigence billing card`, or POST /v1/billing/checkout; members ask an owner). Your credits are kept, and 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." },
+        message: "payments are not available right now",
+        fix: "Nothing was charged. Your credits and running work are unaffected. Try again later, or write to support@promigence.ai." },
+    { code: "purchase_limit", category: "other", http: 402, exit: 5, billed: "no",
+        message: "{needed} is more than this organization can buy at once right now (up to {limit})",
+        fix: "Buy {limit} or less, or choose a smaller plan. The limit rises as the organization's payment history grows; for more now, write to support@promigence.ai." },
+    { code: "card_needed", category: "other", http: 409, exit: 5, billed: "no",
+        message: "auto-reload needs a saved card",
+        fix: "Add credits once, or add a card in Billing, then turn auto-reload on." },
+    { code: "auto_reload_unavailable", category: "other", http: 409, exit: 5, billed: "no",
+        message: "auto-reload isn't available yet for cards issued in India",
+        fix: "Add credits by hand: `promigence billing buy <usd>`." },
+    { code: "purchases_blocked", category: "other", http: 409, exit: 5, billed: "no",
+        message: "this organization cannot buy credits right now: a payment for this organization is disputed",
+        fix: "Write to 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." },
@@ -202,10 +217,10 @@ export const ERRORS = [
         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." },
+        fix: "Running sandboxes finish, and files and results stay available. An owner sees why, and what lifts it, in Billing (`promigence billing` prints the link), or 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`." },
+        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: Change plan in Billing (`promigence billing` prints the link)." },
     { 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." },

package/dist/guide.js

@@ -9,8 +9,8 @@ import { DOCS_URL, EXIT_CODES, EXIT_PRECEDENCE_TEXT, GOLDEN_PATH, GROUPS, GUIDE_
 export const SECTIONS = ["core", "commands", "errors", "cost"];
 export const BUDGETS = {
     core: 1500,
-    commands: 4500,
-    errors: 2325,
+    commands: 4825,
+    errors: 2475,
     cost: 600,
 };
 export function lookupError(code) {
@@ -253,7 +253,9 @@ function renderCost(prices) {
         : prices.source === "api"
             ? `Live from the API (${view?.as_of ?? "now"}): your organization's prices. \`promigence pricing\` shows the rest.`
             : prices.source === "published"
-                ? "Published list prices. Your organization's own: `promigence login`, then `promigence pricing`."
+                ? prices.reason !== undefined
+                    ? "Published list prices: the API refused this key. Your organization's own: `promigence login`, then `promigence pricing`."
+                    : "Published list prices. Your organization's own: `promigence login`, then `promigence pricing`."
                 : `${prices.note ?? "list prices at build time; could not reach the API"} (\`promigence pricing\` asks again).`;
     const limit = view?.limits.max_sandbox_vcpus;
     const out = [

package/dist/handlers.js

@@ -4,7 +4,7 @@ import { BUNDLE_EXT, DEFAULT_SNAPSHOT, PromigenceError, VERSION as SDK_VERSION,
 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";
-import { ALL_ERROR_CODES, BUDGETS, estimateTokens, guideJson, humanHeader, lookupError, renderGuide } from "./guide.js";
+import { ALL_ERROR_CODES, BUDGETS, estimateTokens, guideJson, humanHeader, lookupError, renderGuide, renderLlmsTxt } from "./guide.js";
 import { livePricing, quickClient } from "./pricing.js";
 import { install, installLines } from "./install.js";
 import { backgroundOutput } from "./live.js";
@@ -20,6 +20,15 @@ const agentGuide = async (ctx) => {
         throw usageError(`--format: '${format}' is not a format`, "Pass --format md (default) or --format json.");
     }
     const json = format === "json";
+    if (bool(ctx, "--llms")) {
+        const other = ["--section", "--code", "--install", "--check", "--create"].find((f) => ctx.flags.has(f));
+        if (other !== undefined || str(ctx, "--format") !== undefined) {
+            throw usageError(`--llms takes no other flag (got ${other ?? "--format"})`, "Run promigence agent-guide --llms on its own.");
+        }
+        markGuideSeen();
+        await write(process.stdout, renderLlmsTxt());
+        return exitWith(0);
+    }
     if (bool(ctx, "--create") && !bool(ctx, "--install") && !bool(ctx, "--check")) {
         throw usageError("--create needs --install", "Pass --install --create to write AGENTS.md (and the skill and rule files) here.");
     }