promigence 0.1.0-beta.12

package/dist/guide.js

@@ -0,0 +1,366 @@
+import { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_MAX_S, PRICING, } from "./generated.js";
+export const BILLED_TEXT = {
+    no: "no: nothing is billed for this",
+    yes: "yes: the time used is billed",
+    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, NOT_LIVE_SUMMARY, SCHEMA, VERSION, WAIT_TIMEOUT_DEFAULT, compactNames, } from "./surface.js";
+export const SECTIONS = ["core", "commands", "errors", "cost"];
+export const BUDGETS = {
+    core: 1500,
+    commands: 4500,
+    errors: 2325,
+    cost: 600,
+};
+export function lookupError(code) {
+    const own = (t) => Object.prototype.hasOwnProperty.call(t, code) ? t[code] : undefined;
+    return own(ERROR_BY_CODE) ?? own(CLIENT_ERROR_BY_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];
+        if (!e)
+            throw new Error(`GUIDE_COMMON_ERRORS names ${code}, which is not a known error code`);
+        return `- \`${e.code}\` (exit ${e.exit}) — ${e.fix}`;
+    });
+    return [
+        `# Promigence — agent guide (promigence@${VERSION})`,
+        "",
+        "Promigence is an **environment runtime**: verified, reproducible, forkable execution",
+        "environments, billed per second (vCPU + memory). The model is one line:",
+        "",
+        "    verify → snapshot → fork(N) → exec → validity report",
+        "",
+        "- **snapshot** — an image (pinned) + ordered `setup` steps + a `verify` command that, if given, must exit 0.",
+        "  If verify fails nothing is stored; the build's own time is billed. A branch is not a pin.",
+        "- **fork** — a warm copy of that workspace, with its `start` service ready;",
+        "  N at once, each checked before you get it.",
+        "- **validity report** — per sandbox, and this split is the product: **env** failures are ours",
+        "  (exit 3, replayable; when our side shows the cause, the time since your last snapshot is",
+        "  credited back, up to 24 h) and **task** failures are yours (exit 4, billed).",
+        "",
+        "## Golden path",
+        "",
+        `    ${GOLDEN_PATH}`,
+        "",
+        "That forks 2 sandboxes of the built-in base, runs the command in each, prints the report and",
+        "kills them. Find public snapshots with `promigence examples` (no API key needed).",
+        "Build your own: `promigence init` in a repo prints the `snapshot create --image … --wait` to run.",
+        "",
+        "## Output contract",
+        "",
+        "Exactly one JSON document on stdout per invocation, whenever `--json` is passed or stdout is",
+        "not a TTY; `exec --sandbox` needs `--json` for it:",
+        "",
+        `    {"schema":"${SCHEMA}","command":…,"ok":…,`,
+        '     "error":{"code","message","fix","docs","guide"},"next":[{"cmd","why"}]}',
+        "",
+        "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: ${exitLegend}.`,
+        `Highest-precedence code wins: ${EXIT_PRECEDENCE_TEXT}.`,
+        "",
+        `## 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.",
+        "- Pass `--json`, and read `ok`, `error.code` and `next` — not the text.",
+        `- Use \`--wait\`. **Every wait is bounded to ${WAIT_TIMEOUT_DEFAULT}**: exit 11 means the wait expired and`,
+        "  **nothing was killed** — run the id-based `next` command to keep waiting.",
+        "- Treat exit 3 as ours (re-run or `run replay`) and exit 4 as yours (fix the task).",
+        "- Pass the full 40-character commit sha to `snapshot create`.",
+        "",
+        "## Don't",
+        "",
+        "- Never put a key or a secret on argv: `auth login` reads `--from-env VAR` or stdin, `secrets",
+        "  set` also `--from-file P`. Secrets are given at run time, never baked in.",
+        "- Don't poll in a loop — `--wait` long-polls server-side and costs one request.",
+        ...(liveNames.has("run replay")
+            ? ["- Don't re-fork blindly on an env failure: `promigence run replay <run_id>` re-runs it."]
+            : [
+                "- Don't re-fork on exit 3 without reading the report: an env failure is already retried",
+                "  once before hand-off, at no charge — so a blind re-fork hides our bug.",
+            ]),
+        "",
+        "## More",
+        "",
+        "`promigence agent-guide --section commands|errors|cost` · `promigence agent-guide --code <code>`",
+        `· \`promigence <command> --help\` · ${DOCS_URL}`,
+        "Same surface as MCP tools: `promigence mcp` (stdio; `claude mcp add promigence -- promigence mcp`).",
+        "",
+        `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");
+}
+function commandUsage(c) {
+    const req = c.flags.filter((f) => f.required).map((f) => `${f.name} ${f.arg ?? ""}`.trim());
+    return `promigence ${c.name}${req.length ? " " + req.join(" ") : ""}${c.args ? " " + c.args : ""}`;
+}
+const SAID_ONCE = new Set(["--json", "--no-browser", "--yes"]);
+function optionalFlags(c) {
+    const opt = c.flags.filter((f) => !f.required && !f.hidden && !SAID_ONCE.has(f.name)).map((f) => f.name);
+    return opt.length ? opt.join(" ") : "";
+}
+function chainEdges() {
+    const edges = new Map();
+    for (const c of LISTED_COMMANDS) {
+        if (c.next.length === 0)
+            continue;
+        const from = edges.get(c.next[0]);
+        if (from)
+            from.push(c.name);
+        else
+            edges.set(c.next[0], [c.name]);
+    }
+    return [...edges].map(([to, from]) => `- \`${to}\` ← ${from.join(" · ")}`);
+}
+function renderCommands() {
+    const out = [
+        `# Promigence — every command (promigence@${VERSION})`,
+        "",
+        "`✓` = live now. Required flags are shown; optional ones are",
+        "listed after `+` (every command also takes `--json`; one that signs in, `--no-browser` and",
+        "`--yes`). Full detail: `promigence <command> --help`.",
+    ];
+    for (const g of GROUPS) {
+        out.push("", `## ${g}`, "");
+        for (const c of LISTED_COMMANDS) {
+            if (c.group !== g)
+                continue;
+            out.push(`- ✓ \`${commandUsage(c)}\` — ${c.summary}`);
+            const opt = optionalFlags(c);
+            if (opt)
+                out.push(`  + ${opt}`);
+            if (c.note)
+                out.push(`  ! ${c.note}`);
+        }
+    }
+    out.push("", "## Chaining", "", "Every envelope carries `next`. Each next command, then the commands that name it first:", "", ...chainEdges(), "", `Golden path: \`${GOLDEN_PATH}\``, "");
+    return out.join("\n");
+}
+const CATEGORY_NOTE = {
+    env: "ours, replayable; a run with a command retries once first. Not billed before hand-over; after it, credited back from your last snapshot (≤ 24 h) when our side shows the cause, else billed as used",
+    snapshot: "billed — the snapshot's `verify` did not cover what broke",
+    task: "billed — the environment was verified and your command failed",
+    grader: "the episode is billed, the grade is not — your work was never judged",
+    cap: "the spend cap did its job",
+    preempt: "ours — the capacity was given back; credited back from your last snapshot (≤ 24 h), and replayable",
+    other: "client / API conditions",
+};
+const CATEGORY_ORDER = ["env", "preempt", "snapshot", "task", "grader", "cap", "other"];
+function renderErrors() {
+    const out = [
+        `# Promigence — error codes (promigence@${VERSION})`,
+        "",
+        `Envelope: \`error:{code,message,fix,docs,guide}\`. ${EXIT_PRECEDENCE_TEXT} (highest wins).`,
+        "One entry, with its `fix` and HTTP status: `promigence agent-guide --code <code>`.",
+    ];
+    const seen = new Set(CATEGORY_ORDER);
+    const cats = [...CATEGORY_ORDER, ...[...new Set(ERRORS.map((e) => e.category))].filter((c) => !seen.has(c)).sort()];
+    for (const cat of cats) {
+        const rows = ERRORS.filter((e) => e.category === cat);
+        if (!rows.length)
+            continue;
+        out.push("", `## ${cat}${CATEGORY_NOTE[cat] ? ` — ${CATEGORY_NOTE[cat]}` : ""}`, "");
+        for (const e of rows)
+            out.push(`- \`${e.code}\` exit ${e.exit} — ${e.message}`);
+    }
+    out.push("", "## client — made by the SDK or the CLI itself; never sent by the API", "");
+    for (const e of CLIENT_ERRORS)
+        out.push(`- \`${e.code}\` exit ${e.exit} — ${e.message}`);
+    out.push("", "## Exit codes", "", exitLine, "125 passthrough (`exec --sandbox`: Promigence's own failure; the child's code passes through", "otherwise, a command not found exits 127, and the real code travels as `promigence_exit`).", "13 changes_pending (`agent-guide --check`: the files would change; nothing was written).", "", `Fixes for the commonest: ${GUIDE_COMMON_ERRORS.map((c) => `\`${c}\``).join(" ")}`, "— `promigence agent-guide --section errors --code <code>`.", "");
+    return out.join("\n");
+}
+function renderCode(code) {
+    const e = lookupError(code);
+    if (!e) {
+        const near = ALL_ERROR_CODES.filter((c) => c.includes(code) || code.includes(c));
+        return [
+            `# ${code} — not an error code`,
+            "",
+            near.length ? `Did you mean: ${near.map((c) => `\`${c}\``).join(", ")}?` : "",
+            "Every code: `promigence agent-guide --section errors`.",
+            "",
+        ].filter(Boolean).join("\n");
+    }
+    const client = CLIENT_ERROR_BY_CODE[e.code] !== undefined;
+    return [
+        client
+            ? `# \`${e.code}\` — ${e.category}, exit ${e.exit}; made by the SDK or the CLI (the API never sends it)`
+            : `# \`${e.code}\` — ${e.category}, exit ${e.exit}, HTTP ${e.http}`,
+        "",
+        `**Message** (\`{name}\` is filled from the failure's evidence): ${e.message}`,
+        "",
+        `**Fix**: ${e.fix}`,
+        "",
+        `**Billed**: ${BILLED_TEXT[e.billed] ?? e.billed}`,
+        "",
+        `**Category**: ${e.category} — ${CATEGORY_NOTE[e.category] ?? ""}`,
+        "",
+    ].join("\n");
+}
+function renderCost(prices) {
+    const perHour = (r) => `$${(r * 3600).toFixed(4)}`;
+    const tiers = prices?.tiers ?? TIERS.filter((t) => t.sellable);
+    const vcpu = prices?.vcpu_second_usd ?? PRICING.vcpu_second_usd;
+    const gib = prices?.gib_second_usd ?? PRICING.gib_second_usd;
+    const granularity = prices?.granularity_seconds ?? PRICING.granularity_seconds;
+    const buildMax = prices?.build_max_s ?? BUILD_MAX_S;
+    const buildHours = buildMax % 3600 === 0 ? `${buildMax / 3600} h` : `${Math.ceil(buildMax / 60)} min`;
+    const view = prices?.view;
+    const source = prices === undefined
+        ? "List prices when this CLI was built. Live, and your plan's: `promigence pricing`."
+        : 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.note ?? "list prices at build time; could not reach the API"} (\`promigence pricing\` asks again).`;
+    const limit = view?.limits.max_sandbox_vcpus;
+    const out = [
+        `# Promigence — what it costs (promigence@${VERSION})`,
+        "",
+        source,
+        "",
+        "Billing is **per second**, like the rest of the market: a sandbox bills",
+        `$${vcpu} per vCPU-second + $${gib} per GiB-second, from hand-over`,
+        `to end, rounded up to ${granularity} s, no minimum. Paused time is not billed.`,
+        "",
+        "| tier | vCPU | RAM | disk | $/second | $/hour |",
+        "|---|---|---|---|---|---|",
+        ...tiers.map((t) => `| \`${t.name}\` | ${t.vcpus} | ${t.mem_gib} GiB | ${t.disk_gib} GiB | $${t.per_second_usd} | ${perHour(t.per_second_usd)} |`),
+        ...(typeof limit === "number" ? ["", `Your plan runs sandboxes of up to ${limit} vCPU.`] : []),
+        "",
+        `Building a snapshot bills per second at its tier's rate while it runs, at most ${buildHours} (the most it can`,
+        "cost is printed on stderr **before** the build starts; what it cost, when it ends). A build that",
+        "fails `verify` or a guard stores nothing and is billed the time it ran; one that fails on our",
+        "side is not billed, and reusing an identical build is free.",
+        "",
+        "`env` failures (`promigence agent-guide --section errors`): one before hand-over is not billed,",
+        "e.g. " + ERRORS.filter((e) => e.category === "env").slice(0, 3).map((e) => `\`${e.code}\``).join(", ") + ". After hand-over, a failure our",
+        "side shows was ours (a lost host, a memory or disk fault under the tier) is billed to the",
+        "failure and the time since your last snapshot of that sandbox is credited back, up to 24 h; one",
+        "it cannot show (a sandbox that goes silent on its own) is billed as used. A replay bills as new.",
+        "",
+        "Controls:",
+        "",
+        "- `--cap USD` — refused (exit 5) before anything starts if the quote",
+        "  (count × timeout × rate) exceeds it; a sandbox is paused, its state kept, when its accrued spend reaches its share.",
+        "- `--allow-partial` — start what fits; the rest report `not_started` (exit 12).",
+        "- `--timeout DUR` — the most one sandbox can cost; finishing early costs less.",
+        `- \`promigence run quote\` — the most the run's sandbox time can cost, before you run (data out is not in it); \`promigence me\` — spend to date.`,
+        "",
+    ];
+    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);
+    switch (opts.section ?? "core") {
+        case "commands": return renderCommands();
+        case "errors": return renderErrors();
+        case "cost": return renderCost(opts.prices);
+        default: return renderCore();
+    }
+}
+export function guideJson(opts = {}) {
+    const section = opts.code ? "errors" : (opts.section ?? "core");
+    const guide = renderGuide(opts);
+    const body = {
+        format: "md",
+        section,
+        tokens: estimateTokens(guide),
+        budget: BUDGETS[section] ?? BUDGETS.core,
+        guide,
+    };
+    if (opts.code)
+        body["error"] = lookupError(opts.code) ?? null;
+    else if (section === "errors") {
+        body["errors"] = ERRORS;
+        body["client_errors"] = CLIENT_ERRORS;
+    }
+    else if (section === "cost") {
+        body["tiers"] = opts.prices?.tiers ?? TIERS.filter((t) => t.sellable);
+        body["prices_source"] = opts.prices?.source ?? "compiled";
+        body["prices_note"] = opts.prices === undefined ? "list prices when this CLI was built" : (opts.prices.note ?? null);
+    }
+    else if (section === "commands") {
+        body["commands"] = LISTED_COMMANDS.map((c) => ({
+            name: c.name, group: c.group, summary: c.summary, status: c.status,
+            usage: commandUsage(c), args: c.args ?? null,
+            flags: c.flags.filter((f) => !f.hidden).map((f) => f.name), next: c.next,
+        }));
+    }
+    else {
+        body["model"] = "verify → snapshot → fork(N) → exec → validity report";
+        body["golden_path"] = GOLDEN_PATH;
+        body["exit_codes"] = EXIT_CODES;
+        body["common_errors"] = GUIDE_COMMON_ERRORS.map((c) => ERROR_BY_CODE[c]).filter(Boolean);
+    }
+    return body;
+}
+export function renderLlmsTxt() {
+    return [
+        `# Promigence — promigence@${VERSION}`,
+        "",
+        "> Verified, reproducible, forkable execution environments for agents. The CLI is the",
+        "> `promigence` command (package `promigence`, which is also the TypeScript SDK).",
+        "",
+        "## Index",
+        "",
+        ...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",
+        "- `promigence agent-guide --section errors` — every error code and exit code",
+        "- `promigence agent-guide --section cost` — tiers and per-second prices",
+        `- ${DOCS_URL}`,
+        "",
+        "---",
+        "",
+        renderCore(),
+    ].join("\n");
+}