@whiteroom-ai/cli 1.1.0 → 2.0.1

package/dist/practice/adapter.js

@@ -0,0 +1,169 @@
+// Runs one practice task through the adapter (spec §5 Agents, §9.4): one
+// child per task in its own process group, NDJSON over stdin/stdout, the
+// provider key in its environment and nothing of WhiteRoom's. Stderr is
+// passed through; stdout that isn't JSON is shown here and never uploaded.
+import { spawn } from "node:child_process";
+import { isKeyVar } from "./preflight.js";
+import { clean, say } from "./text.js";
+export const MAX_LINE_BYTES = 1024 * 1024;
+export const MAX_TOOL_CALLS = 200;
+/** A tool call's request to WhiteRoom must fit its 64 KiB body limit. */
+export const MAX_TOOL_BODY_BYTES = 64 * 1024;
+/** After SIGTERM, how long the group has before SIGKILL. */
+export const KILL_GRACE_MS = 5_000;
+/** The adapter's environment: the CLI's, minus WhiteRoom's settings and every provider key, with only the run's key added. */
+export function childEnv(parent, keyVar, key) {
+    const env = {};
+    for (const [k, v] of Object.entries(parent)) {
+        if (!/^WHITEROOM_/i.test(k) && !isKeyVar(k))
+            env[k] = v;
+    }
+    env[keyVar] = key;
+    return env;
+}
+const live = new Set();
+const groupAlive = (pid) => {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const signalGroup = (pid, sig) => {
+    try {
+        process.kill(-pid, sig);
+    }
+    catch {
+        // Already gone.
+    }
+};
+/** SIGTERM to the adapter's whole process group, then SIGKILL if anything is left after KILL_GRACE_MS. */
+export async function killGroup(child) {
+    const pid = child.pid;
+    if (!pid) {
+        live.delete(child); // Never started: nothing to kill.
+        return;
+    }
+    signalGroup(pid, "SIGTERM");
+    const until = Date.now() + KILL_GRACE_MS;
+    while (groupAlive(pid) && Date.now() < until)
+        await new Promise((r) => setTimeout(r, 100));
+    if (groupAlive(pid))
+        signalGroup(pid, "SIGKILL");
+    // Only now: if the CLI exits during the grace period, the exit handler still SIGKILLs the group.
+    live.delete(child);
+}
+// Whatever happens to the CLI, no adapter outlives it.
+process.on("exit", () => {
+    for (const c of live)
+        if (c.pid)
+            signalGroup(c.pid, "SIGKILL");
+});
+/** Calls `onLine` per line; a line over MAX_LINE_BYTES calls `onTooLong` instead and drops the rest of the stream. */
+function readLines(stream, onLine, onTooLong) {
+    let buf = "";
+    let over = false;
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => {
+        if (over)
+            return;
+        buf += chunk;
+        const tooLong = () => {
+            over = true;
+            buf = "";
+            onTooLong();
+        };
+        for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
+            const line = buf.slice(0, i).replace(/\r$/, "");
+            buf = buf.slice(i + 1);
+            if (Buffer.byteLength(line) > MAX_LINE_BYTES)
+                return tooLong();
+            onLine(line);
+        }
+        if (Buffer.byteLength(buf) > MAX_LINE_BYTES)
+            tooLong();
+    });
+    stream.on("end", () => {
+        if (buf && !over)
+            onLine(buf);
+    });
+}
+export function runAdapter(o) {
+    const child = "shell" in o.launch
+        ? spawn(o.launch.shell, { shell: true, detached: true, stdio: ["pipe", "pipe", "pipe"], env: o.env })
+        : spawn(o.launch.file, o.launch.args, { detached: true, stdio: ["pipe", "pipe", "pipe"], env: o.env });
+    live.add(child);
+    const tail = [];
+    let toolCalls = 0;
+    let settled = false;
+    // Lines are handled one at a time, in order: a tool call finishes before the next line is read.
+    let chain = Promise.resolve();
+    return new Promise((resolve) => {
+        const finish = (out) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            o.signal.removeEventListener("abort", onAbort);
+            void killGroup(child).then(() => resolve(out));
+        };
+        const onAbort = () => finish({ kind: "stopped" });
+        // setTimeout fires at once past 2^31-1 ms, so a far deadline is clamped.
+        const timer = setTimeout(() => finish({ kind: "deadline" }), Math.min(2 ** 31 - 1, Math.max(0, o.deadline - Date.now())));
+        o.signal.addEventListener("abort", onAbort, { once: true });
+        if (o.signal.aborted)
+            onAbort();
+        const write = (msg) => {
+            if (!settled)
+                child.stdin.write(JSON.stringify(msg) + "\n");
+        };
+        child.stdin.on("error", () => { }); // The adapter closed stdin: its exit is reported below.
+        child.on("error", (err) => finish({ kind: "exited", how: err.message, tail }));
+        const handle = async (line) => {
+            if (settled || !line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                say(`  adapter: ${line}`);
+                return;
+            }
+            if (!msg || typeof msg !== "object" || Array.isArray(msg))
+                return say(`  adapter: ${line}`);
+            if (msg.type === "final") {
+                return finish({ kind: "final", output: typeof msg.output === "string" ? msg.output : JSON.stringify(msg.output ?? null) });
+            }
+            if (msg.type !== "tool_call")
+                return finish({ kind: "broke", why: "sent a message the CLI doesn't know" });
+            const { id, name, input } = msg;
+            if (typeof id !== "string" || !id || id.length > 128 || typeof name !== "string" || !name || name.length > 64) {
+                return finish({ kind: "broke", why: "sent a tool call without a valid id and name" });
+            }
+            if (++toolCalls > MAX_TOOL_CALLS)
+                return finish({ kind: "broke", why: `made more than ${MAX_TOOL_CALLS} tool calls in one practice task` });
+            if (Buffer.byteLength(JSON.stringify(input ?? null)) > MAX_TOOL_BODY_BYTES - 512) {
+                return finish({ kind: "broke", why: "sent a tool call bigger than 64 KiB" });
+            }
+            const answer = await o.tool({ id, name, input: input ?? null });
+            if ("end" in answer)
+                return finish({ kind: "ended", by: answer.end });
+            write({ type: "tool_result", id, result: answer.result });
+        };
+        readLines(child.stdout, (l) => { chain = chain.then(() => handle(l)).then(() => { }); }, () => finish({ kind: "broke", why: "sent a line longer than 1 MiB" }));
+        readLines(child.stderr, (l) => {
+            process.stderr.write(clean(l) + "\n");
+            tail.push(clean(l).slice(0, 500));
+            if (tail.length > 5)
+                tail.shift();
+        }, () => { });
+        child.on("close", (code, sig) => {
+            chain = chain.then(() => finish({ kind: "exited", how: sig ? `stopped by ${sig}` : `exit code ${code}`, tail }));
+        });
+        write(o.message);
+    });
+}
+//# sourceMappingURL=adapter.js.map

package/dist/practice/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/practice/adapter.ts"],"names":[],"mappings":"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"}

package/dist/practice/catalog.d.ts

@@ -0,0 +1,27 @@
+/** A provider's name, its key's variable, the header the key travels in (`bearer`: Authorization: Bearer) and its API. */
+export interface ProviderInfo {
+    label: string;
+    keyVar: string;
+    header: "x-api-key" | "api-key" | "bearer";
+    api: "messages" | "chat_completions";
+}
+export declare const CATALOG: {
+    taskNames: Record<string, string>;
+    disclaimer: string;
+    providers: Record<string, ProviderInfo>;
+    keyRefusals: Record<string, string>;
+    runCallCap: number;
+    statusLabels: Record<"passed" | "failed" | "not_tested" | "unsupported" | "error", string>;
+    verdictLabels: Record<"passed" | "not_passed" | "incomplete", string>;
+    /** The seven pre-flight rows: members are check-id prefixes ("a." takes every agent check under it; "ctl.spend_cap" its rules). */
+    rows: Array<{
+        id: string;
+        name: string;
+        group: string;
+        members: string[];
+    }>;
+    rowStatusLabels: Record<"passed" | "failed" | "not_set_up" | "not_checked", string>;
+    controls: {
+        modes: Record<"enforce" | "watch" | "off", string>;
+    };
+};

package/dist/practice/catalog.js

@@ -0,0 +1,6 @@
+// The engine's practice-test catalog (contract/catalog.json): the CLI ships it
+// and the dashboard imports the same file, so task, status, provider and
+// refusal words are the engine's. Refreshed by scripts/sync-practice-contract.sh.
+import { readFileSync } from "node:fs";
+export const CATALOG = JSON.parse(readFileSync(new URL("../../contract/catalog.json", import.meta.url), "utf8"));
+//# sourceMappingURL=catalog.js.map

package/dist/practice/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/practice/catalog.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,yEAAyE;AACzE,kFAAkF;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAKvC,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,6BAA6B,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAO9G,CAAC"}

package/dist/practice/engine.d.ts

@@ -0,0 +1,52 @@
+/** How long the CLI keeps retrying while WhiteRoom can't be reached or asks it to wait. */
+export declare const OFFLINE_MS: number;
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+/** Waits until one more request keeps the last minute at or under PER_MINUTE. */
+export declare function pace(): Promise<void>;
+/** A reply from WhiteRoom; `body` is null when it wasn't JSON. */
+export interface Reply {
+    status: number;
+    /** The route's JSON, read field by field by the caller. */
+    body: any;
+}
+/**
+ * A reply that tried to send the CLI somewhere else. Requests that carry the
+ * key or the session never follow a redirect (`redirect: "error"`): nothing is
+ * resent, and the caller stops with plain copy.
+ */
+export declare const REDIRECTED = 0;
+export declare const isRedirectError: (err: unknown) => boolean;
+/** WhiteRoom couldn't be reached (or kept asking the CLI to wait) for OFFLINE_MS. */
+export declare class Unreachable extends Error {
+}
+/** The session's stop signal fired (Ctrl+C, or WhiteRoom ended the test). */
+export declare class Stopped extends Error {
+}
+export declare class Engine {
+    readonly origin: string;
+    private readonly offlineMs;
+    private readonly timeoutMs;
+    session: string | null;
+    /** Aborts any request in flight when the session stops. */
+    signal: AbortSignal | null;
+    /** `offlineMs`: how long to keep retrying; `timeoutMs`: one request, body included (tests shorten both). */
+    constructor(origin: string, offlineMs?: number, timeoutMs?: number);
+    /** One request, its body read inside the same timeout: a server that stalls mid-body fails like one that never answers. */
+    private send;
+    /**
+     * Ends the run (best effort, one try, not paced): after Ctrl+C, or a crashed adapter
+     * (`keepResults`: with a result over the tasks done). Null if WhiteRoom didn't answer.
+     */
+    cancel(keepResults?: boolean): Promise<Reply | null>;
+    /** One request, best effort: not paced, not retried, not stopped by the session's signal. Null if WhiteRoom didn't answer. */
+    once(path: string, body: unknown, timeoutMs?: number): Promise<Reply | null>;
+    /**
+     * POSTs to a route. WhiteRoom's waits (503, a 429 that isn't an answer) are
+     * retried as Retry-After says. `retryNetwork`: also retry a network error or
+     * another 5xx, for requests that are safe to repeat; otherwise those throw
+     * Unreachable. A redirect is returned as status REDIRECTED, never followed.
+     */
+    post(path: string, body: unknown, o?: {
+        retryNetwork?: boolean;
+    }): Promise<Reply>;
+}

package/dist/practice/engine.js

@@ -0,0 +1,151 @@
+// The CLI's requests to WhiteRoom's /api/readiness routes (spec §4, §7):
+// plain fetch, paced to 60 a minute (§4 Run), with WhiteRoom's own waits
+// (an IP-limit 429, a 503 while it switches servers) retried.
+import { copy, warn } from "./text.js";
+/** The CLI's own requests stay at or under this many a minute; WhiteRoom allows 120 per IP. */
+const PER_MINUTE = 60;
+/** How long the CLI keeps retrying while WhiteRoom can't be reached or asks it to wait. */
+export const OFFLINE_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 90_000;
+const sent = [];
+export const sleep = (ms, signal) => new Promise((resolve) => {
+    const done = () => {
+        clearTimeout(t);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    };
+    const t = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+});
+/** Waits until one more request keeps the last minute at or under PER_MINUTE. */
+export async function pace() {
+    for (;;) {
+        const now = Date.now();
+        while (sent.length && sent[0] <= now - 60_000)
+            sent.shift();
+        if (sent.length < PER_MINUTE) {
+            sent.push(now);
+            return;
+        }
+        await sleep(sent[0] + 60_000 - now);
+    }
+}
+/**
+ * A reply that tried to send the CLI somewhere else. Requests that carry the
+ * key or the session never follow a redirect (`redirect: "error"`): nothing is
+ * resent, and the caller stops with plain copy.
+ */
+export const REDIRECTED = 0;
+export const isRedirectError = (err) => /redirect/i.test(String(err?.cause?.message ?? ""));
+/** WhiteRoom couldn't be reached (or kept asking the CLI to wait) for OFFLINE_MS. */
+export class Unreachable extends Error {
+}
+/** The session's stop signal fired (Ctrl+C, or WhiteRoom ended the test). */
+export class Stopped extends Error {
+}
+/** 429s that are answers, not a request to wait. */
+const ANSWERS_429 = new Set(["busy", "tool_limit", "starts_today", "owner_busy"]);
+export class Engine {
+    origin;
+    offlineMs;
+    timeoutMs;
+    session = null;
+    /** Aborts any request in flight when the session stops. */
+    signal = null;
+    /** `offlineMs`: how long to keep retrying; `timeoutMs`: one request, body included (tests shorten both). */
+    constructor(origin, offlineMs = OFFLINE_MS, timeoutMs = REQUEST_TIMEOUT_MS) {
+        this.origin = origin;
+        this.offlineMs = offlineMs;
+        this.timeoutMs = timeoutMs;
+    }
+    /** One request, its body read inside the same timeout: a server that stalls mid-body fails like one that never answers. */
+    async send(path, body, timeoutMs, signal) {
+        const ac = new AbortController();
+        const abort = () => ac.abort();
+        const timer = setTimeout(abort, timeoutMs);
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            const res = await fetch(this.origin + path, {
+                method: "POST",
+                headers: { "content-type": "application/json", ...(this.session && { authorization: `Bearer ${this.session}` }) },
+                body: JSON.stringify(body),
+                redirect: "error",
+                signal: ac.signal,
+            });
+            const text = await res.text();
+            let json = null;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                // Not JSON: the caller reads a null body.
+            }
+            return { status: res.status, retryAfter: res.headers.get("retry-after"), json };
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    /**
+     * Ends the run (best effort, one try, not paced): after Ctrl+C, or a crashed adapter
+     * (`keepResults`: with a result over the tasks done). Null if WhiteRoom didn't answer.
+     */
+    async cancel(keepResults = false) {
+        return this.once("/api/readiness/cancel", keepResults ? { keepResults } : {});
+    }
+    /** One request, best effort: not paced, not retried, not stopped by the session's signal. Null if WhiteRoom didn't answer. */
+    async once(path, body, timeoutMs = 5_000) {
+        return this.send(path, body, timeoutMs, null).then((r) => ({ status: r.status, body: r.json }), () => null);
+    }
+    /**
+     * POSTs to a route. WhiteRoom's waits (503, a 429 that isn't an answer) are
+     * retried as Retry-After says. `retryNetwork`: also retry a network error or
+     * another 5xx, for requests that are safe to repeat; otherwise those throw
+     * Unreachable. A redirect is returned as status REDIRECTED, never followed.
+     */
+    async post(path, body, o = {}) {
+        const started = Date.now();
+        let warned = false;
+        for (;;) {
+            await pace();
+            if (this.signal?.aborted)
+                throw new Stopped();
+            let res;
+            try {
+                res = await this.send(path, body, this.timeoutMs, this.signal);
+            }
+            catch (err) {
+                if (this.signal?.aborted)
+                    throw new Stopped();
+                if (isRedirectError(err))
+                    return { status: REDIRECTED, body: { reason: "redirected" } };
+                if (!o.retryNetwork || Date.now() - started > this.offlineMs)
+                    throw new Unreachable();
+                if (!warned)
+                    warn(copy.offline);
+                warned = true;
+                await sleep(Math.min(5_000, this.offlineMs), this.signal ?? undefined);
+                continue;
+            }
+            const { json } = res;
+            if (res.status >= 500 && res.status !== 503) {
+                // It may have been handled: only a request that is safe to repeat is sent again.
+                if (!o.retryNetwork || Date.now() - started > this.offlineMs)
+                    throw new Unreachable();
+                await sleep(Math.min(5_000, this.offlineMs), this.signal ?? undefined);
+                continue;
+            }
+            const wait = res.status === 503 || (res.status === 429 && !ANSWERS_429.has(json?.reason));
+            if (wait) {
+                if (Date.now() - started > this.offlineMs)
+                    throw new Unreachable();
+                const after = res.retryAfter;
+                await sleep(after === null ? 5_000 : Math.min(Math.max(Number(after) || 0, 1), 60) * 1000, this.signal ?? undefined);
+                continue;
+            }
+            return { status: res.status, body: json };
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/practice/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/practice/engine.ts"],"names":[],"mappings":"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"}

package/dist/practice/index.d.ts

@@ -0,0 +1,2 @@
+export declare const PRACTICE_USAGE: string;
+export declare function practice(argv: string[]): Promise<number>;

package/dist/practice/index.js

@@ -0,0 +1,79 @@
+// `whiteroom practice` (hidden alias `readiness`), spec §10 CLI. Usage
+// problems exit 2, never 1 (§8); so does anything unexpected.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { practiceRun, STARTERS_DIR } from "./run.js";
+import { CATALOG } from "./catalog.js";
+import { parseRequire, warn } from "./text.js";
+const ROW_IDS = CATALOG.rows.map((r) => r.id).join(", ");
+export const PRACTICE_USAGE = `whiteroom practice — run a WhiteRoom practice test on your agent
+
+Usage:
+  whiteroom practice run [--adapter "<command>"] [--key-env <VAR>] [--require <checks>] [--code-stdin] [--url <https url>]
+  whiteroom practice adapter --lang js|python
+
+  run       Starts the practice test from the run code shown in the dashboard.
+            Without --adapter, WhiteRoom's sample agent runs the practice tasks.
+  adapter   Prints a starter adapter to connect your own agent, for example:
+            whiteroom practice adapter --lang js > wr-adapter.mjs
+
+Options:
+  --adapter "<command>"  The command that starts your agent's adapter, e.g. "node wr-adapter.mjs"
+  --key-env <VAR>        The variable your agent's key is in, e.g. ANTHROPIC_API_KEY, when several are set
+  --require <checks>     Exit 1 unless these checks pass in Enforce, e.g. spend_cap,keyword (for CI). Checks:
+                         ${ROW_IDS}
+  --code-stdin           Read the run code from stdin instead of asking for it
+  --url <https url>      Only for testing WhiteRoom itself (a whiteroom.tech address or localhost)
+`;
+const STARTERS = { js: "wr-adapter.mjs", python: "wr_adapter.py" };
+function usage(problem) {
+    if (!problem)
+        return process.stdout.write(PRACTICE_USAGE), 0;
+    warn(`${problem}\nRun whiteroom practice --help to see the commands.`);
+    return 2;
+}
+export async function practice(argv) {
+    const [sub, ...rest] = argv;
+    if (!sub || sub === "--help" || sub === "-h" || sub === "help")
+        return usage();
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rest,
+            strict: true,
+            allowPositionals: false,
+            options: sub === "run"
+                ? { adapter: { type: "string" }, "key-env": { type: "string" }, require: { type: "string" }, "code-stdin": { type: "boolean" }, url: { type: "string" }, help: { type: "boolean", short: "h" } }
+                : { lang: { type: "string" }, help: { type: "boolean", short: "h" } },
+        }));
+    }
+    catch (err) {
+        return usage(err.message);
+    }
+    if (values.help)
+        return usage();
+    try {
+        if (sub === "run") {
+            if (values.adapter !== undefined && !values.adapter.trim())
+                return usage("--adapter needs the command that starts your adapter.");
+            const require = values.require === undefined ? [] : parseRequire(values.require);
+            if (!Array.isArray(require))
+                return usage(require.problem);
+            return await practiceRun({ adapter: values.adapter, codeStdin: !!values["code-stdin"], url: values.url, keyEnv: values["key-env"], require });
+        }
+        if (sub === "adapter") {
+            const file = STARTERS[values.lang];
+            if (!file)
+                return usage("Choose a starter with --lang js or --lang python.");
+            process.stdout.write(readFileSync(new URL(file, STARTERS_DIR), "utf8"));
+            return 0;
+        }
+        return usage(`Unknown practice command: ${sub}`);
+    }
+    catch (err) {
+        // Any adapter still running is killed as the process exits (adapter.ts).
+        warn(`Something went wrong in the CLI: ${err?.message ?? String(err)}`);
+        return 2;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/practice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/practice/index.ts"],"names":[],"mappings":"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"}

package/dist/practice/preflight.d.ts

@@ -0,0 +1,64 @@
+export declare const PRODUCTION = "https://proxy.whiteroom.tech";
+export declare const RUN_CODE: RegExp;
+/**
+ * The origin practice commands talk to: production, or `--url` if it is
+ * WhiteRoom's own (https on whiteroom.tech) or loopback, since the provider
+ * key goes there. Any other https host only with WHITEROOM_PRACTICE_DEV=1
+ * (testing WhiteRoom itself). Null if `--url` isn't allowed.
+ */
+export declare function targetOrigin(url: string | undefined, env?: NodeJS.ProcessEnv): string | null;
+/** Splits a command line into words as a POSIX shell would for plain words and quotes (enough to find files). */
+export declare function words(cmd: string): string[];
+/**
+ * Why `--adapter` can't start, or null: its program is on PATH (or a file), and
+ * script files it names (by extension) exist. Commands with shell syntax or a
+ * builtin first word are left to the shell.
+ */
+export declare function adapterProblem(cmd: string, cwd?: string, path?: string): string | null;
+/**
+ * The adapter as reported to WhiteRoom (§7 "What was tested"): only the
+ * program's name and its script file's name, e.g. "python3 wr_adapter.py".
+ * Never environment assignments, flags, flag values or directories.
+ */
+export declare function adapterLabel(cmd: string): string;
+/** Where a practice test's model calls go, as the claim names it: one of the catalog's providers. */
+export type Provider = string;
+export declare const isProvider: (v: unknown) => v is Provider;
+/** The variable a provider's key is read from, and the adapter gets it in. */
+export declare const keyVarOf: (p: Provider) => string;
+export declare const isKeyVar: (v: string) => boolean;
+/** OpenAI and Azure OpenAI take chat completions (their SDKs want a base URL ending in /v1); the others Anthropic's Messages API. */
+export declare const chatCompletions: (p: Provider) => boolean;
+/** The header a provider's key travels in, as the catalog says: Azure's api-key, a Bearer token, or x-api-key. */
+export declare function keyHeader(p: Provider, key: string): Record<string, string>;
+/** A direct key's provider, by its shape: what an older WhiteRoom that names no provider means. */
+export declare const providerByShape: (key: string) => Provider;
+/**
+ * What's wrong with a key's shape, before it's sent (uses no try), or null:
+ * pasted twice (a hidden prompt shows nothing, so a second paste is easy),
+ * or with spaces or line breaks inside.
+ */
+export declare function keyShapeProblem(key: string): "twice" | "spaces" | null;
+/** Short-term Bedrock keys can expire during a test; WhiteRoom refuses them without using a try. */
+export declare const isShortTermBedrockKey: (key: string) => boolean;
+export interface KeyChoice {
+    /** The variable the key came from; null when it was pasted. */
+    from: string | null;
+    key: string;
+}
+/**
+ * The key from `keyEnv` (`--key-env`, the variable the dashboard's command
+ * names), else from the one provider variable that is set; null to prompt.
+ * When more than one is set, the variables: before the claim the CLI can't
+ * tell which provider the run uses, and a guess could use a try.
+ */
+export declare function keyFromEnv(env: NodeJS.ProcessEnv, keyEnv?: string): KeyChoice | string[] | null;
+export declare class Interrupted extends Error {
+}
+type Terminal = Pick<NodeJS.ReadStream, "setRawMode" | "setEncoding" | "resume" | "pause" | "on" | "off">;
+/** Reads a line from the terminal without echoing it. Ctrl+C rejects with Interrupted. */
+export declare function hiddenPrompt(question: string, stdin?: Terminal): Promise<string>;
+/** The first line of stdin (`--code-stdin`). */
+export declare function firstLineOfStdin(): Promise<string>;
+export declare const nodeTooOld: (version?: string) => string | null;
+export {};