promigence 0.1.0-beta.12

package/dist/sdk/core.d.ts

@@ -0,0 +1,285 @@
+/** Promigence SDK — constants, error hierarchy and shared types. */
+export declare const VERSION = "0.1.0-beta.12";
+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";
+export declare const DEFAULT_API_URL = "https://api.promigence.ai/v1";
+/** Where to write about a key. A key is self-serve: `promigence login` signs up or in and stores one. */
+export declare const KEY_CONTACT = "support@promigence.ai";
+/** Every bounded wait defaults to this; below agent tool timeouts. */
+export declare const WAIT_TIMEOUT_MS = 100000;
+/**
+ * `Sandbox.create({ image })` bounds the first build of an image by this (15 min): pull +
+ * flatten + boot is minutes, not the 100 s a fork waits. Expiry cancels nothing.
+ */
+export declare const IMAGE_BUILD_TIMEOUT_MS: number;
+/**
+ * The most one new snapshot build of the default tier can cost at the list prices this SDK was
+ * built with, in USD: its time limit (an hour) at that tier's per-second rate. A build is billed per
+ * second for the time it runs; reusing or joining an identical build is free. Prices change: the
+ * live figure is `client.pricing()`'s `rates.build_usd` (this key's organization's), and a build's
+ * own arrives as `build_price` in the `POST /snapshots` answer. This is only the fallback when the
+ * API cannot be asked.
+ */
+export declare const IMAGE_BUILD_LIST_PRICE = 0.1656;
+/** Inline output budget for an exec before `truncated` + `_ref`. */
+export declare const MAX_OUTPUT_BYTES_DEFAULT: number;
+/** One request of a `files.put`. **Not a file-size limit** — `put` loops. */
+export declare const FILE_PUT_CHUNK_BYTES: number;
+export interface PromigenceErrorInit {
+    code: string;
+    message: string;
+    fix: string;
+    docs?: string;
+    exitCode?: number;
+    /** HTTP status, when the error came from the API. */
+    status?: number;
+    /** `request_id` header, when present. */
+    requestId?: string;
+    /** `Retry-After`, in ms, when the answer carried one. */
+    retryAfterMs?: number;
+    /** The API error's `category`: `env` (ours; credited back when our side shows the cause), `task`, `cap`, `other`, ... */
+    category?: string;
+    /** The API error's `retryable`: nothing ran and the same request, sent again as is, can succeed. */
+    retryable?: boolean;
+}
+/** What a caller reads instead: a fact about this beta, not a mistake of theirs. */
+export declare const PREVIEWS_UNAVAILABLE = "preview URLs are not available in this beta yet";
+export declare function previewsFix(sandboxId?: string, port?: string | number): string;
+/**
+ * A `fix` that opens by repeating the message says only what it adds: the API's `usage` fix is
+ * "{detail}. See `promigence … --help`.", and a client that prints both would say the sentence
+ * twice. A fix that is nothing but the message says what to do in general.
+ */
+export declare function fixBeyondMessage(message: string, fix: string): string;
+export declare class PromigenceError extends Error {
+    readonly code: string;
+    readonly fix: string;
+    readonly docs: string;
+    /**
+     * On [`CommandExitError`] this is overridden with the *command's* exit code — see the note
+     * there — so anything that needs the CLI's number must read [`cliExit`], never this.
+     */
+    readonly exitCode: number;
+    /** The CLI's exit code, always. Equal to `exitCode` except on [`CommandExitError`]. */
+    readonly cliExit: number;
+    readonly guide: string;
+    readonly status: number | undefined;
+    readonly requestId: string | undefined;
+    /**
+     * The server's `Retry-After`, in ms, on ANY error that carried one: a 429, and also a 503 env
+     * failure that clears by waiting (`builder_busy`, `registry_unavailable`). `undefined` when the
+     * answer named no time.
+     */
+    readonly retryAfterMs: number | undefined;
+    /**
+     * Whose failure it was, as the API said (`category` in the error): `env` is ours and never
+     * billed, `task` your command's, `cap` a spend limit, `other` a refusal of the request. New
+     * values may appear. `undefined` when the answer did not say (an error the SDK made itself).
+     */
+    readonly category: string | undefined;
+    /**
+     * The API's `retryable`: `true` when nothing of yours ran and the same request, sent again
+     * unchanged (after `retryAfterMs` when set), can succeed. `false` when something must change
+     * first, or when the request may already have done its work. `undefined` when the answer did
+     * not say. The SDK's own retries do not depend on it.
+     */
+    readonly retryable: boolean | undefined;
+    constructor(init: PromigenceErrorInit);
+    toJSON(): {
+        retryable?: boolean;
+        category?: string;
+        request_id?: string;
+        code: string;
+        message: string;
+        fix: string;
+        docs: string;
+        guide: string;
+    };
+}
+/** Bad arguments (e.g. an unknown template, a missing spend cap). exit 2 */
+export declare class InvalidArgumentError extends PromigenceError {
+    /**
+     * `code` defaults to `invalid_argument` — what the SDK raises for a bad argument it catches
+     * itself — but the API's own `usage` maps to this class too, and a client that renames a
+     * code the caller then has to look up is a client the error index cannot help. So the wire
+     * code is carried through when there is one.
+     */
+    constructor(message: string, fix: string, code?: string);
+}
+/** A call this version does not implement; names the alternative in `fix`. exit 2 */
+export declare class UnsupportedError extends PromigenceError {
+    constructor(feature: string, alternative: string);
+    /**
+     * A [`PreviewsUnavailableError`] is one too, as Python's class is (it subclasses both there):
+     * TS has one parent, so it extends `InvalidArgumentError` (what it was raised as before) and
+     * this check admits it. Only on `UnsupportedError` itself; a subclass checks as usual.
+     */
+    static [Symbol.hasInstance](x: unknown): boolean;
+}
+/** True when an API message is the deployment's "previews are not enabled" answer. */
+export declare function previewsOff(message: string): boolean;
+export declare class PreviewsUnavailableError extends InvalidArgumentError {
+    constructor(sandboxId?: string, port?: string | number);
+}
+/** The environment failed (our fault, never the task's). exit 3 */
+export declare class EnvFailedError extends PromigenceError {
+    constructor(code: string, message: string, fix: string);
+}
+/**
+ * `commands.run` foreground with non-zero exit (opt out with `throwOnExit: false`). CLI exit 4.
+ *
+ * **`exitCode` is the COMMAND's exit code**, not the CLI's. That is a deliberate divergence from
+ * every other error in this file, and it is the one place `cliExit` exists for.
+ *
+ * The reason is compatibility, and it is a correctness bug rather than a nicety:
+ * `CommandExitError implements CommandResult`, so a call site reads
+ *
+ * ```ts
+ * catch (e) { if (e.exitCode === 1) retry(); }
+ * ```
+ *
+ * and means the command's code. We used to put `4` there — the CLI's `task_failed` code — and
+ * hide the real one on `exitCodeOfCommand`. That does not throw, it does not warn: it silently
+ * answers a different question, which is the worst failure mode a compatibility shim has.
+ * `exitCodeOfCommand` stays as an alias so existing Promigence-native callers keep working.
+ */
+export declare class CommandExitError extends PromigenceError implements Pick<CommandResult, "stdout" | "stderr"> {
+    /** Alias of `exitCode`, kept for callers written against the pre-compat shape. */
+    readonly exitCodeOfCommand: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    constructor(result: CommandResult);
+}
+/** Quote/PATCH above the spend cap; nothing started. exit 5 */
+export declare class SpendCapError extends PromigenceError {
+    /**
+     * `cap_exceeded` (refused before anything started, nothing billed) and `cap_killed` (stopped
+     * part-way, billed for the seconds it used) are the same class and are NOT the same outcome.
+     * Collapsing both to `cap_exceeded` told a caller nothing had been charged when something had.
+     */
+    constructor(message: string, fix?: string, code?: string);
+}
+/** Fork/run against a snapshot whose build is not verified. exit 6 */
+export declare class NotVerifiedError extends PromigenceError {
+    constructor(message: string, fix?: string);
+}
+/** Missing or invalid API key. exit 7 */
+export declare class AuthError extends PromigenceError {
+    constructor(message?: string, fix?: string);
+}
+/** Snapshot / run / sandbox not found. exit 8 */
+export declare class NotFoundError extends PromigenceError {
+    constructor(message: string, fix?: string);
+}
+/** API unreachable (connection refused, DNS, 5xx after retries). exit 9 */
+export declare class UnreachableError extends PromigenceError {
+    constructor(message: string, fix?: string);
+}
+/** 429 with Retry-After. exit 10 */
+export declare class RateLimitError extends PromigenceError {
+    constructor(message: string, retryAfterMs?: number);
+}
+/** A bounded wait expired. Nothing is killed; `fix` names the id-based command. exit 11 */
+export declare class TimeoutError extends PromigenceError {
+    /** The sandbox an expired wait was for, when it was for one: re-attach or kill it by this. */
+    readonly sandboxId: string | undefined;
+    /** That sandbox's run. */
+    readonly runId: string | undefined;
+    constructor(message: string, fix: string, ids?: {
+        sandboxId?: string;
+        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 {
+}
+/** Placeholder surface that is not implemented in this release. exit 1 */
+export declare class NotReleasedError extends PromigenceError {
+    constructor(what: string);
+}
+export declare const EXIT_BY_CODE: Readonly<Record<string, number>>;
+export declare function exitForCode(code: string): number;
+export type Tier = "xsmall" | "small" | "medium" | "large-16" | "large" | "xlarge" | "2xlarge";
+/**
+ * What a sandbox may reach.
+ *
+ * - `"egress"` (default) — anything, minus the always-on outbound mail block.
+ * - `"none"` — nothing.
+ * - `{ allow: [...] }` — these destinations and nothing else. `"github.com"` is that host
+ *   exactly; `"*.npmjs.org"` is anything under `npmjs.org` but not `npmjs.org` itself; a literal
+ *   IPv4 address is permitted as written. Anything else is refused, and the sandbox's
+ *   `network` view names every host it asked for and did not get.
+ *
+ * Read what an allowed list does and does not promise before you rely on it: it is spelled out
+ * on `SandboxForkOpts.allowHosts`.
+ */
+export type NetworkMode = "none" | "egress" | {
+    allow: string[];
+};
+/**
+ * `compute` makes memory-heavy work in sandboxes of 15 GiB and more run faster — a few percent on a cold build — and makes starting many of them at once slower. It changes nothing on smaller sandboxes. Default: `start`.
+ */
+export type OptimizeFor = "start" | "compute";
+export interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    /** `exec_id`, for `promigence exec output <exec_id>` / `GET /sandboxes/:id/execs/:exec_id`. */
+    execId?: string;
+}
+export interface CommandRunOpts {
+    cwd?: string;
+    envs?: Record<string, string>;
+    user?: string;
+    /**
+     * The command's own bound. `0` means no bound of its own: a background command
+     * then lives as long as the sandbox, a foreground one is bounded by the sandbox's timeout
+     * (or the default 15 minutes).
+     */
+    timeoutMs?: number;
+    /** Throw `CommandExitError` on non-zero exit (default true). */
+    throwOnExit?: boolean;
+    /** Inline output budget; `truncated` beyond it (default 64 KiB). */
+    maxOutputBytes?: number;
+    /** Start it and return a `CommandHandle` now (`wait()`, `kill()`, output callbacks). */
+    background?: boolean;
+}
+export interface ForkOpts {
+    count?: number;
+    /** Required when the sandbox is dirty (any exec/write): fork the origin snapshot. */
+    fromOrigin?: boolean;
+    onReady?: (sandbox: unknown, index: number) => void;
+    waitTimeoutMs?: number;
+}
+export interface SandboxOpts {
+    apiKey?: string;
+    apiUrl?: string;
+    /** `opts.spendCap` > `PROMIGENCE_SPEND_CAP` > `GET /me.default_spend_cap`; none → InvalidArgumentError. */
+    spendCap?: number;
+    /** Sandbox timeout: the most one sandbox can bill (per second used). */
+    timeoutMs?: number;
+    /** `false` → `network: none`. */
+    allowInternetAccess?: boolean;
+    /** Mapped to run labels. */
+    metadata?: Record<string, string>;
+    /**
+     * Plain environment variables for every command this object runs. Kept by this handle, not in
+     * the sandbox: a `Sandbox.connect(id)` elsewhere does not have them (pass them to its
+     * `connect`, or per command). A credential belongs in `secrets`, which every command gets.
+     */
+    envs?: Record<string, string>;
+    /** Bound on readiness (default 100 s). */
+    waitTimeoutMs?: number;
+}

package/dist/sdk/core.js

@@ -0,0 +1,266 @@
+import { hintArg } from "./hint.js";
+export const VERSION = "0.1.0-beta.12";
+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";
+export const KEY_CONTACT = "support@promigence.ai";
+export const WAIT_TIMEOUT_MS = 100_000;
+export const IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
+export const IMAGE_BUILD_LIST_PRICE = 0.1656;
+export const MAX_OUTPUT_BYTES_DEFAULT = 64 * 1024;
+export const FILE_PUT_CHUNK_BYTES = 16 * 1024 * 1024;
+const PREVIEWS_OFF = /^previews are not enabled on this deployment\.?$/i;
+export const PREVIEWS_UNAVAILABLE = "preview URLs are not available in this beta yet";
+export function previewsFix(sandboxId = "SID", port = 8000) {
+    return `Reach the port over SSH instead: \`promigence sandbox ssh ${hintArg(sandboxId)} -- -N -L ${hintArg(`${port}:localhost:${port}`)}\` ` +
+        `forwards http://localhost:${port} here to port ${port} in the sandbox until Ctrl-C.`;
+}
+export async function withPreviewsFix(call, sandboxId, port = "PORT") {
+    try {
+        return await call;
+    }
+    catch (e) {
+        if (e instanceof PromigenceError && e.message === PREVIEWS_UNAVAILABLE) {
+            Object.defineProperty(e, "fix", { value: previewsFix(sandboxId, port), enumerable: true, configurable: true });
+        }
+        throw e;
+    }
+}
+export function fixBeyondMessage(message, fix) {
+    const said = message.trim().replace(/[.\s]+$/, "");
+    if (said === "" || !fix.startsWith(said))
+        return fix;
+    const rest = fix.slice(said.length).replace(/^[.:;,\s]+/, "");
+    return rest === "" ? "Change what the message names, then try again." : rest;
+}
+export class PromigenceError extends Error {
+    code;
+    fix;
+    docs;
+    exitCode;
+    cliExit;
+    guide;
+    status;
+    requestId;
+    retryAfterMs;
+    category;
+    retryable;
+    constructor(init) {
+        const previewsOff = PREVIEWS_OFF.test(init.message.trim());
+        const code = previewsOff && init.code === "usage" ? "unsupported" : init.code;
+        super(previewsOff ? PREVIEWS_UNAVAILABLE : init.message);
+        this.name = new.target.name;
+        this.code = code;
+        this.fix = previewsOff ? previewsFix() : fixBeyondMessage(init.message, init.fix);
+        this.docs = init.docs ?? DOCS_URL;
+        this.exitCode = init.exitCode ?? 1;
+        this.cliExit = init.exitCode ?? 1;
+        this.guide = `promigence agent-guide --section errors --code ${hintArg(code)}`;
+        this.status = init.status;
+        this.requestId = init.requestId;
+        this.retryAfterMs = init.retryAfterMs;
+        this.category = init.category;
+        this.retryable = init.retryable;
+    }
+    toJSON() {
+        return {
+            code: this.code, message: this.message, fix: this.fix, docs: this.docs, guide: this.guide,
+            ...(this.requestId === undefined ? {} : { request_id: this.requestId }),
+            ...(this.category === undefined ? {} : { category: this.category }),
+            ...(this.retryable === undefined ? {} : { retryable: this.retryable }),
+        };
+    }
+}
+export class InvalidArgumentError extends PromigenceError {
+    constructor(message, fix, code = "invalid_argument") {
+        super({ code, message, fix, exitCode: 2 });
+    }
+}
+export class UnsupportedError extends PromigenceError {
+    constructor(feature, alternative) {
+        super({
+            code: "unsupported",
+            message: `${feature} is not supported by Promigence v0.`,
+            fix: alternative,
+            exitCode: 2,
+        });
+    }
+    static [Symbol.hasInstance](x) {
+        if (Function.prototype[Symbol.hasInstance].call(this, x))
+            return true;
+        return this === UnsupportedError && x instanceof PreviewsUnavailableError;
+    }
+}
+export function previewsOff(message) {
+    return PREVIEWS_OFF.test(message.trim());
+}
+export class PreviewsUnavailableError extends InvalidArgumentError {
+    constructor(sandboxId = "SID", port = 8000) {
+        super(PREVIEWS_UNAVAILABLE, previewsFix(sandboxId, port), "unsupported");
+    }
+}
+export class EnvFailedError extends PromigenceError {
+    constructor(code, message, fix) {
+        super({ code, message, fix, exitCode: 3 });
+    }
+}
+export class CommandExitError extends PromigenceError {
+    exitCodeOfCommand;
+    stdout;
+    stderr;
+    exitCode;
+    constructor(result) {
+        super({
+            code: "task_failed",
+            message: `command exited with code ${result.exitCode}`,
+            fix: "Inspect result.stdout / result.stderr; pass { throwOnExit: false } to receive the result instead.",
+            exitCode: 4,
+        });
+        this.exitCode = result.exitCode;
+        this.exitCodeOfCommand = result.exitCode;
+        this.stdout = result.stdout;
+        this.stderr = result.stderr;
+    }
+}
+export class SpendCapError extends PromigenceError {
+    constructor(message, fix, code = "cap_exceeded") {
+        super({
+            code,
+            message,
+            fix: fix ?? "Raise --cap / spendCap, lower count or timeout, or pass allowPartial to launch what fits.",
+            exitCode: exitForCode(code),
+        });
+    }
+}
+export class NotVerifiedError extends PromigenceError {
+    constructor(message, fix) {
+        super({
+            code: "not_verified",
+            message,
+            fix: fix ?? "Wait for the build: `promigence snapshot status <build_id> --wait`.",
+            exitCode: 6,
+        });
+    }
+}
+export class AuthError extends PromigenceError {
+    constructor(message = "missing or invalid API key", fix) {
+        super({
+            code: "auth",
+            message,
+            fix: fix ??
+                "No key yet: `promigence login` signs you up or in and stores one. A key you already " +
+                    "have: set PROMIGENCE_API_KEY, or store it with `promigence auth login --from-env VAR`.",
+            exitCode: 7,
+        });
+    }
+}
+export class NotFoundError extends PromigenceError {
+    constructor(message, fix) {
+        super({
+            code: "not_found",
+            message,
+            fix: fix ?? "Check the id; aliases resolve in your org first, then public snapshots (`promigence examples`).",
+            exitCode: 8,
+        });
+    }
+}
+export class UnreachableError extends PromigenceError {
+    constructor(message, fix) {
+        super({
+            code: "unreachable",
+            message,
+            fix: fix ?? `Check PROMIGENCE_API_URL and connectivity; the API is at ${DEFAULT_API_URL}.`,
+            exitCode: 9,
+        });
+    }
+}
+export class RateLimitError extends PromigenceError {
+    constructor(message, retryAfterMs) {
+        super({
+            code: "rate_limited",
+            message,
+            fix: retryAfterMs ? `Retry after ${retryAfterMs} ms.` : "Retry with backoff; reduce concurrency (see `GET /me` limits).",
+            exitCode: 10,
+            ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+        });
+    }
+}
+export class TimeoutError extends PromigenceError {
+    sandboxId;
+    runId;
+    constructor(message, fix, ids = {}) {
+        super({ code: "timeout", message, fix, exitCode: 11 });
+        this.sandboxId = ids.sandboxId;
+        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 {
+    constructor(what) {
+        super({
+            code: "not_released",
+            message: `${what} is not released yet: promigence@${VERSION} does not implement it. The runtime ships from Oct 2026.`,
+            fix: `Update from the package you were given once a release implements it (support@promigence.ai has the latest); until then see ${DOCS_URL}.`,
+            exitCode: 1,
+        });
+    }
+}
+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,
+    service_timeout: 3, capacity_busy: 3, region_at_capacity: 3,
+    preempted: 3,
+    tier_unavailable: 3,
+    snapshot_unavailable: 3,
+    capacity_limit: 3,
+    builder_unavailable: 3,
+    builder_busy: 3,
+    overloaded: 3,
+    verify_did_not_cover: 4,
+    grader_failed: 3,
+    nonzero_exit: 4, grade_not_passed: 4, task_timeout: 4, oom_over_tier: 4, disk_over_tier: 4,
+    shutdown_by_task: 4, modified_by_task: 4,
+    cap_exceeded: 5, cap_killed: 12, cap_paused: 5, credits_paused: 5,
+    aborted_by_client: 130, stopped_by_support: 12, expired: 12, not_started: 12, superseded: 0,
+    usage: 2, internal: 1, auth: 7, not_found: 8, unreachable: 9, rate_limited: 10,
+    timeout: 11, not_verified: 6, enoent: 8,
+    snapshot_incompatible: 6, storage_limit_reached: 5,
+    resume_unavailable: 3,
+    sandbox_unreachable: 3,
+    dockerfile_build_failed: 2,
+    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: 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,
+    secret_binding_unsupported: 3,
+    idempotency_key_reused: 2, idempotency_key_in_use: 3,
+    repo_credentials_not_supported: 2,
+    forbidden: 7,
+    account_exists: 7,
+    invite_invalid: 7,
+    invite_required: 7,
+    key_expired: 7,
+    account_blocked: 7,
+    setup_required: 7,
+};
+export function exitForCode(code) {
+    return Object.prototype.hasOwnProperty.call(EXIT_BY_CODE, code) ? EXIT_BY_CODE[code] : 1;
+}

package/dist/sdk/credstore.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Where a stored sign-in lives: the operating system's keychain when this machine has one, else
+ * 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 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
+ *                    without a native module or a compiled helper on every command
+ *
+ * `PROMIGENCE_CREDENTIAL_STORE=file` keeps the file on any machine; `macos-keychain` and
+ * `secret-service` name a keychain outright (`auto`, the default, picks by platform).
+ *
+ * One keychain item per credentials path (service `promigence-cli`, account = the path), so two
+ * `XDG_CONFIG_HOME` directories are two sign-ins, exactly as two files were. The item holds the
+ * same JSON the file did. The secret never goes on a command line, where `ps` would show it:
+ * `security` takes the whole command on stdin (`security -i`) with the data hex-encoded, and
+ * `secret-tool store` reads the secret from stdin.
+ *
+ * A file that is present wins over the keychain: the CLI deletes the file once the keychain holds
+ * the same sign-in and reads it back, so a file that is there was written after (by hand, by an
+ * older CLI, or because the keychain was not usable at the time).
+ */
+/** Where a stored sign-in lives. */
+export type CredentialStore = "file" | "macos-keychain" | "secret-service";
+/** An OS keychain: the stores that are not the file. */
+export type KeychainStore = Exclude<CredentialStore, "file">;
+/** The keychain item's service name. The account is the credentials path. */
+export declare const KEYCHAIN_SERVICE = "promigence-cli";
+/** How each store is named in a message. */
+export declare function storeLabel(store: CredentialStore, path?: string): string;
+/**
+ * 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, 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
+ * sign-in left there would otherwise still sign commands in once the file is gone).
+ */
+export declare function keychainsToClear(env?: NodeJS.ProcessEnv, platform?: string): KeychainStore[];
+/** A keychain that holds (or may hold) the sign-in but could not be read. */
+export interface KeychainUnavailable {
+    store: KeychainStore;
+    reason: string;
+    locked: boolean;
+}
+/** What a keychain read found. */
+export type KeychainRead = {
+    status: "found";
+    text: string;
+} | {
+    status: "absent";
+} | {
+    status: "unavailable";
+    reason: string;
+    locked: boolean;
+};
+/** The item for `account` in `store`, read now (no cache). */
+export declare function keychainRead(store: KeychainStore, account: string, env?: NodeJS.ProcessEnv): KeychainRead;
+/** Store `text` as the item for `account`. Never puts `text` on a command line. */
+export declare function keychainWrite(store: KeychainStore, account: string, text: string, env?: NodeJS.ProcessEnv): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Remove the item for `account`. `absent` when there was none. */
+export declare function keychainDelete(store: KeychainStore, account: string, env?: NodeJS.ProcessEnv): {
+    ok: true;
+    absent: boolean;
+} | {
+    ok: false;
+    reason: string;
+    locked: boolean;
+};
+/**
+ * The JSON a store holds, in printable ASCII only (`security -w` prints anything else as hex). The
+ * same object the credentials file holds.
+ */
+export declare function encodeCredentials(body: Record<string, string>): string;
+/** `keychainRead`, remembered for a few seconds per store and account. */
+export declare function keychainReadCached(store: KeychainStore, account: string, env?: NodeJS.ProcessEnv): KeychainRead;
+/** Record what a store now holds for `account` (undefined = nothing), after this process wrote it. */
+export declare function keychainCacheSet(store: KeychainStore, account: string, text: string | undefined): void;
+/** Forget every remembered read, so the next one asks the keychain (a long-lived process, the MCP server). */
+export declare function forgetKeychainReads(): void;