promigence 0.1.0-beta.5 → 0.1.0-beta.6

package/dist/bin.js

@@ -13,7 +13,7 @@ import { TEMPLATES_HANDLERS } from "./templates.js";
 import { ACCOUNT_HANDLERS } from "./account.js";
 import { MCP_HANDLERS } from "./mcp.js";
 import { AGENT_HANDLERS } from "./agent.js";
-import { CREDITS_HANDLERS } from "./credits.js";
+import { CREDITS_HANDLERS, canAsk, claimOnRefusal } from "./credits.js";
 import { RUNNERS_HANDLERS } from "./runners.js";
 import { PRICING_HANDLERS } from "./pricing.js";
 import { GITHUB_HANDLERS } from "./github.js";
@@ -321,6 +321,11 @@ async function main(argv) {
             env.promigence_exit = exit;
             exit = e.code === "enoent" ? 127 : cmd.passthroughExit;
         }
+        if (e.code === "credit_unclaimed" && mode === "text" && canAsk()) {
+            const lines = await claimOnRefusal(ctx).catch(() => undefined);
+            if (lines)
+                return void (await emit(mode, env, lines, exit, false));
+        }
         await emit(mode, env, errorTextLines(cmd.name, e, exit, next), exit, !cmd.noGuidePointer);
     }
 }

package/dist/credits.js

@@ -1,7 +1,8 @@
+import { createInterface } from "node:readline";
 import { PromigenceClient } from "./sdk/index.js";
 import { bool, clientOpts, nexts } from "./commands.js";
 import { deviceFetch, deviceHeader } from "./device.js";
-import { emit, okEnvelope, recordNotice } from "./io.js";
+import { emit, okEnvelope, recordNotice, write } from "./io.js";
 import { headless, openBrowser } from "./login.js";
 import { usd } from "./money.js";
 export function dollars(n) {
@@ -104,6 +105,51 @@ export async function offerAfterLogin(ctx, apiUrl, apiKey, consoleHome) {
         lines: claimLines(offer, link, opened),
     };
 }
+async function askLine(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await new Promise((resolve) => rl.question(prompt, resolve));
+    }
+    finally {
+        rl.close();
+    }
+}
+export function canAsk(env = process.env) {
+    const ci = (env["CI"] ?? "").trim().toLowerCase();
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && (ci === "" || ci === "0" || ci === "false");
+}
+export async function claimOnRefusal(ctx, io = {}) {
+    const opts = { ...clientOpts(ctx), onNotice: recordNotice };
+    let o;
+    try {
+        o = await getOffer(new PromigenceClient(opts));
+    }
+    catch {
+        return undefined;
+    }
+    if (!o || o.state !== "claimable")
+        return undefined;
+    const credit = typeof o.credit_usd === "number" ? `${dollars(o.credit_usd)} of free credit` : "free credit";
+    await write(process.stderr, `This account has ${credit} waiting to be claimed; nothing was started or charged.\n`);
+    const answer = await (io.ask ?? askLine)("Claim it now? It opens the claim page in your browser, where you accept the terms. [y/N] ");
+    if (!/^\s*y(es)?\s*$/i.test(answer))
+        return ["Not claimed. When you are ready: promigence credits claim"];
+    let link;
+    try {
+        link = await getClaimLink(claimClient(opts));
+        if (!link || typeof link.url !== "string")
+            throw new Error("no claim link in the answer");
+    }
+    catch (e) {
+        const err = e;
+        return [
+            `Could not open the claim page: ${err?.message ?? String(e)}`,
+            `  Try again: promigence credits claim${err?.code === "forbidden" ? " (owners; members ask an owner)" : ""}`,
+        ];
+    }
+    const opened = maybeOpen(ctx, link.url);
+    return [...claimLines(o, link, opened), "Once it is claimed, run the command again."];
+}
 async function cardsOff(c, o) {
     if (!(typeof o.card_bonus_usd === "number" && o.card_bonus_usd > 0) || o.state === "none")
         return false;

package/dist/errfix.js

@@ -17,11 +17,17 @@ 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) {
+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.`,
@@ -195,7 +201,7 @@ export async function refineError(e, ctx) {
     }
     if (e.code === "not_found") {
         const nf = notFoundKind(e.message);
-        const fitted = nf ? notFoundFor(nf.kind, ctx) : undefined;
+        const fitted = nf ? notFoundFor(nf.kind, ctx, err.fix ?? "") : undefined;
         if (fitted) {
             err = reworded(err, fitted.fix);
             next = fitted.next;

package/dist/guide.d.ts

@@ -7,6 +7,8 @@ export declare const BUDGETS: Readonly<Record<Section, number>>;
 export declare function lookupError(code: string): ErrorEntry | undefined;
 export declare const ALL_ERROR_CODES: readonly string[];
 export declare const estimateTokens: (s: string) => number;
+export declare const HUMAN_START = "promigence run --count 1 --cap 1 -- python3 -c 'print(6*7)'";
+export declare function humanHeader(): string;
 export interface GuideOpts {
     section?: Section;
     code?: string;

package/dist/guide.js

@@ -259,6 +259,10 @@ function renderCost(prices) {
     ];
     return out.filter((l) => l !== undefined).join("\n");
 }
+export const HUMAN_START = "promigence run --count 1 --cap 1 -- python3 -c 'print(6*7)'";
+export function humanHeader() {
+    return `For people: this is the guide your coding agent reads, dense on purpose.\nStart here: ${HUMAN_START}\n\n`;
+}
 export function renderGuide(opts = {}) {
     if (opts.code)
         return renderCode(opts.code);

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, lookupError, renderGuide } from "./guide.js";
+import { ALL_ERROR_CODES, BUDGETS, estimateTokens, guideJson, humanHeader, lookupError, renderGuide } from "./guide.js";
 import { livePricing, quickClient } from "./pricing.js";
 import { install, installLines } from "./install.js";
 import { backgroundOutput } from "./live.js";
@@ -66,6 +66,8 @@ const agentGuide = async (ctx) => {
         await write(process.stdout, jsonLine(process.stdout, env));
         return exitWith(0);
     }
+    if (section === "core" && code === undefined && process.stdout.isTTY)
+        await write(process.stdout, humanHeader());
     await write(process.stdout, guide);
     const budget = BUDGETS[section] ?? BUDGETS.core;
     const used = estimateTokens(guide);

package/dist/mcp.js

@@ -132,7 +132,7 @@ function reportSummary(report) {
 export const MCP_TOOLS = [
     {
         name: "sandbox_create",
-        description: "Create a sandbox from a Promigence snapshot (id or alias; default promigence/base: Debian with Python 3.12, node, git, gcc) or from a container image (a tag, which the API pins, or NAME@sha256:…), and return its sandbox_id.",
+        description: "Create a sandbox from a Promigence snapshot (id or alias; default promigence/base: Debian with Python 3.12, Node 24, Go, Docker, git, gcc and the Claude Code, Codex, Gemini and OpenCode CLIs) or from a container image (a tag, which the API pins, or NAME@sha256:…), and return its sandbox_id.",
         readOnly: false,
         inputSchema: {
             type: "object",

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.5";
+export declare const VERSION = "0.1.0-beta.6";
 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";

package/dist/sdk/core.js

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

package/dist/sdk/sandbox.d.ts

@@ -224,9 +224,10 @@ interface SandboxInit {
     timeoutMs?: number;
 }
 /**
- * The snapshot `Sandbox.create()` forks when it is given none: Debian 12 + Python 3.12, node/npm,
- * git, curl, jq, gcc/make, `small` tier (built in, not verified). It is always ready to start. The template
- * name `'base'` means the same thing.
+ * The snapshot `Sandbox.create()` forks when it is given none: Debian 12 + Python 3.12 (pip, venv, uv),
+ * Node 24 (npm), Bun, Go 1.27, Docker, git, Git LFS, the GitHub CLI, curl, jq, ripgrep, rsync, gcc/make,
+ * and the Claude Code, Codex, Gemini CLI and OpenCode agents, `small` tier (built in, not verified). It
+ * is always ready to start. The template name `'base'` means the same thing.
  */
 export declare const DEFAULT_SNAPSHOT = "promigence/base";
 /**

package/llms.txt

@@ -1,4 +1,4 @@
-# Promigence — promigence@0.1.0-beta.5
+# Promigence — promigence@0.1.0-beta.6
 
 > Verified, reproducible, forkable execution environments for agents. The CLI is the
 > `promigence` command (package `promigence`, which is also the TypeScript SDK).
@@ -126,7 +126,7 @@
 
 ---
 
-# Promigence — agent guide (promigence@0.1.0-beta.5)
+# Promigence — agent guide (promigence@0.1.0-beta.6)
 
 Promigence is an **environment runtime**: verified, reproducible, forkable execution
 environments, billed per second (vCPU + memory). The model is one line:
@@ -196,4 +196,4 @@ Highest-precedence code wins: 2 > 5 > 6 > 7/8/9/10 > 11 > 3 > 12 > 4 > 1 > 0.
 · `promigence <command> --help` · https://promigence.ai
 Same surface as MCP tools: `promigence mcp` (stdio; `claude mcp add promigence -- promigence mcp`).
 
-Live in v0.1.0-beta.5: login · signup · logout · auth login · keys list/create/revoke · org list/create/switch/members/invite/invites/uninvite/resend/role/remove/leave/join/audit/rename/delete · project list/create/rename/delete/cap/move · me · billing card/usage/portal · doctor · ping · init · examples · templates +show · agent-guide · mcp · snapshot create/status/list/inspect/verify/export/delete/builds/alias · image resolve · github connect/status/disconnect/untrack · repos · gitlab connect/status/disconnect/untrack · run +quote/report/status/cancel/kill/replay/open/captures/list · fork · exec +output/ps/stdin/kill · files put/get/ls/search/mkdir/mv/cp/chmod/rm · agent start · sandbox kill/network/shell/ssh/list/pause/resume/snapshot/info/extend/autopause/probe · port expose/list/revoke · secrets set/list/delete · bench burst · runners github/gitlab · status · referrals +apply · pricing · credits +claim
+Live in v0.1.0-beta.6: login · signup · logout · auth login · keys list/create/revoke · org list/create/switch/members/invite/invites/uninvite/resend/role/remove/leave/join/audit/rename/delete · project list/create/rename/delete/cap/move · me · billing card/usage/portal · doctor · ping · init · examples · templates +show · agent-guide · mcp · snapshot create/status/list/inspect/verify/export/delete/builds/alias · image resolve · github connect/status/disconnect/untrack · repos · gitlab connect/status/disconnect/untrack · run +quote/report/status/cancel/kill/replay/open/captures/list · fork · exec +output/ps/stdin/kill · files put/get/ls/search/mkdir/mv/cp/chmod/rm · agent start · sandbox kill/network/shell/ssh/list/pause/resume/snapshot/info/extend/autopause/probe · port expose/list/revoke · secrets set/list/delete · bench burst · runners github/gitlab · status · referrals +apply · pricing · credits +claim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promigence",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.6",
   "description": "The fastest sandboxes for AI agents and code. Snapshot an environment once, fork it as often as you need, run commands in every copy, and get a report that tells environment failures from task failures. Billed per second, with a quote before a run and a hard spend cap. One package: the promigence command and the TypeScript SDK.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",