@ai21/gateway 0.5.3

package/dist/router.js

@@ -0,0 +1,271 @@
+/**
+ * Verb dispatch. Handlers return streams and an exit code rather than writing or
+ * exiting, so a command can be asserted end to end without spawning a process.
+ */
+import { containsControlCharacters, dashboardUrl } from "./args.js";
+import { resolvePaths, writeConfig } from "./config.js";
+import { promptForKey } from "./prompt.js";
+import { EXIT_FOR, collectWarnings, report, reportRevert } from "./report.js";
+import { revertConfig } from "./revert.js";
+import { runLogin } from "./login/session.js";
+import { EXIT } from "./result.js";
+import { AI21_KEY_PLACEHOLDER, ccSettings, ccSettingsEnv } from "./snippets.js";
+import { readVersion } from "./cli.js";
+import { verify } from "./verify.js";
+/* Identifies traffic this tool configured, so the gateway can tell a CLI-configured
+ * agent from a hand-pasted one without the CLI reporting anything.
+ *
+ * Read per call, not at module load: readVersion() throws on a corrupt install, and at
+ * import time that would crash every command — including `--version`, which handles
+ * the same failure cleanly on its own. */
+function clientTag() {
+    return `ai21-gateway-cli/${readVersion()}`;
+}
+function snippetInputs(args) {
+    return {
+        gatewayUrl: args.urls.gateway,
+        // Only `login --print` reaches this fallback: `install` requires --agent-id,
+        // and login learns the agent from the callback. Rendering an empty value read as
+        // a bug in the preview rather than as a value the sign-in will supply.
+        agentId: args.agentId ?? AGENT_ID_PLACEHOLDER,
+        ai21Key: args.key ?? AI21_KEY_PLACEHOLDER,
+        userId: args.userId,
+        client: clientTag(),
+    };
+}
+/** Stand-in shown instead of a supplied key. */
+const REDACTED_KEY = "****";
+/** Stand-in for the agent id a `login` preview cannot know yet. */
+const AGENT_ID_PLACEHOLDER = "<agent-id-from-sign-in>";
+/**
+ * A preview shows the shape and the endpoint, neither of which needs the key visible —
+ * and `--print` output lands in scrollback and CI logs, so a supplied key is always
+ * masked. The placeholder is left alone when no key was given: it is not a secret, and
+ * hiding it would obscure that the preview is incomplete.
+ */
+function previewInputs(args) {
+    const inputs = snippetInputs(args);
+    if (args.key === undefined)
+        return inputs;
+    return { ...inputs, ai21Key: REDACTED_KEY };
+}
+/** `--print`: render what *would* be written, without touching the filesystem. */
+function printConfig(args) {
+    const inputs = previewInputs(args);
+    if (args.json) {
+        const payload = {
+            target: args.target,
+            urls: args.urls,
+            settings: { env: ccSettingsEnv(inputs) },
+        };
+        return { code: EXIT.OK, out: `${JSON.stringify(payload, null, 2)}\n`, err: "" };
+    }
+    return { code: EXIT.OK, out: `${ccSettings(inputs)}\n`, err: "" };
+}
+/**
+ * Blanks the AI21 key wherever it appears in a header value. Conflict output
+ * quotes both the existing and the new value, and both carry a live credential —
+ * which would otherwise land in a terminal scrollback or a CI log.
+ */
+function redactKey(value) {
+    return value.replace(/(x-ai21-key:\s*)\S+/gi, "$1****");
+}
+/**
+ * Header values are `\n`-joined, so a raw one breaks out of the indented block
+ * and the two sides stop being comparable at a glance. Continuation lines are
+ * aligned under the first.
+ */
+function indentContinuations(value, pad) {
+    return value.split("\n").join(`\n${pad}`);
+}
+/** Renders the per-key breakdown under the refusal headline. */
+function describeConflicts(conflicts) {
+    const pad = " ".repeat("    current: ".length);
+    const lines = conflicts.map((c) => `  ${c.key}\n` +
+        `    current: ${indentContinuations(redactKey(c.current), pad)}\n` +
+        `    new:     ${indentContinuations(redactKey(c.desired), pad)}`);
+    return [
+        ...lines,
+        "",
+        "Nothing was written. Re-run with --yes to overwrite; the previous file is backed up first.",
+        "",
+    ].join("\n");
+}
+/** Human-only detail appended under the one-line outcome. */
+function detailFor(outcome) {
+    switch (outcome.kind) {
+        case "conflict":
+            return describeConflicts(outcome.conflicts);
+        case "malformed":
+            return "Nothing was written. Fix or move the file, then re-run.\n";
+        case "failed":
+            return "The existing file was left unchanged.\n";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Resolves the key: the flag if given, otherwise a masked prompt. Returns a
+ * `RunResult` when it could not be obtained, so the caller just forwards it.
+ */
+async function resolveKey(args, io) {
+    if (args.key !== undefined)
+        return { key: args.key };
+    const outcome = await promptForKey(io);
+    switch (outcome.kind) {
+        case "key": {
+            // An empty line is a mistake, not a key. Refusing beats writing a config
+            // that looks fine and fails every request.
+            if (outcome.value.trim() === "") {
+                return { code: EXIT.USAGE, out: "", err: "No key entered. Nothing was written.\n" };
+            }
+            // The prompt already drops control characters, but the invariant belongs
+            // to whatever feeds a header value — asserting it here means a future
+            // input path cannot quietly become a way around it.
+            if (containsControlCharacters(outcome.value)) {
+                return {
+                    code: EXIT.USAGE,
+                    out: "",
+                    err: "The key contains control characters. Nothing was written.\n",
+                };
+            }
+            return { key: outcome.value };
+        }
+        case "cancelled":
+            return { code: EXIT.USAGE, out: "", err: "Cancelled. Nothing was written.\n" };
+        case "no-tty":
+            // The alternative is blocking forever on a stdin that will never deliver
+            // a line, which is how a CLI wedges a CI job.
+            return {
+                code: EXIT.USAGE,
+                out: "",
+                err: "--key is required when stdin is not a terminal. Pass --key <key>.\n",
+            };
+    }
+}
+/**
+ * Verification runs only once the config is actually on disk — there is nothing to
+ * verify after a refusal, and a request fired anyway would report on whatever
+ * config was already there.
+ */
+async function verifyWrite(args, ctx, outcome, inputs) {
+    if (EXIT_FOR[outcome.kind] !== EXIT.OK)
+        return undefined;
+    if (args.noVerify)
+        return { kind: "disabled" };
+    return verify({
+        urls: args.urls,
+        agentId: inputs.agentId,
+        ai21Key: inputs.ai21Key,
+        userId: args.userId,
+        anthropicKey: args.anthropicKey,
+        processEnv: ctx.processEnv,
+        // Verify from wherever the file we just wrote is the authoritative one — see
+        // VerifyContext.cwd. A --user config verified from the project directory
+        // would be shadowed by any repo-local settings.json.
+        cwd: args.target === "user" ? ctx.paths.home : ctx.paths.cwd,
+    }, ctx.verify);
+}
+/**
+ * Write, verify, report. Shared by `install` and `login` so the two cannot drift:
+ * whichever way the credentials were obtained, they go through one writer with one
+ * set of conflict, backup and idempotency rules.
+ */
+async function writeAndReport(args, ctx, inputs) {
+    const paths = resolvePaths(args.target, ctx.paths, args.client);
+    const outcome = writeConfig(paths, ccSettingsEnv(inputs), { force: args.yes });
+    const verification = await verifyWrite(args, ctx, outcome, inputs);
+    const result = report({
+        outcome,
+        warnings: collectWarnings({ urls: args.urls, processEnv: ctx.processEnv }),
+        json: args.json,
+        detail: detailFor(outcome),
+        urls: args.urls,
+        verification,
+    });
+    return { result, verification };
+}
+async function install(args, ctx) {
+    const resolved = await resolveKey(args, ctx.prompt);
+    if (!("key" in resolved))
+        return resolved;
+    return (await writeAndReport(args, ctx, { ...snippetInputs(args), ai21Key: resolved.key })).result;
+}
+/**
+ * `login`: the browser hands us the credentials, then the ordinary writer takes
+ * over. A failed or abandoned handshake writes nothing at all.
+ */
+async function login(args, ctx) {
+    return handedOff(args, ctx, await runLogin(args.urls, ctx.login, { notify: ctx.notify }));
+}
+/** Shared by both handoff directions: write, verify, then offer the dashboard. */
+async function handedOff(args, ctx, outcome) {
+    switch (outcome.kind) {
+        case "credentials": {
+            /* Overwrites without asking, unlike a hand-typed `install`.
+             *
+             * The conflict guard exists to catch someone clobbering a config they had
+             * forgotten about. That premise does not hold here: the reader asked the
+             * dashboard to connect this repo and ran the command it printed, so replacing
+             * whatever is there IS the request. The previous file is still backed up, and
+             * `uninstall --from-backup` still restores it.
+             *
+             * Refusing was also a dead end. Every handoff mints a fresh key, so
+             * ANTHROPIC_CUSTOM_HEADERS always differs from what is on disk and the guard
+             * always fired — and its advice, "re-run with --yes", cannot be followed: the
+             * page latches after one delivery, so the same code will never be sent again.
+             * The reader had to go back and spend another one-time key to get past it. */
+            const { result, verification } = await writeAndReport({ ...args, yes: true }, ctx, {
+                gatewayUrl: args.urls.gateway,
+                agentId: outcome.agentId,
+                ai21Key: outcome.ai21Key,
+                userId: args.userId,
+            });
+            // Only once the gateway has actually answered: sending someone to the dashboard
+            // to admire a setup that does not work would be worse than not sending them.
+            if (result.code === EXIT.OK && verification?.kind === "passed" && outcome.workspaceId !== undefined) {
+                const dashboard = dashboardUrl(args.urls, outcome.workspaceId);
+                ctx.login.openBrowser(dashboard);
+                ctx.notify(`Verified. Opening the dashboard: ${dashboard}`);
+            }
+            return result;
+        }
+        case "timeout":
+            return {
+                code: EXIT.LOGIN_INCOMPLETE,
+                out: "",
+                err: `Timed out waiting for the sign-in to complete. Nothing was written.\nRe-run \`ai21-gateway login\`, or install directly with --agent-id and --key.\n`,
+            };
+        case "rejected":
+            // Refusing beats writing: this is remote input that failed validation, and
+            // the reason is never the value itself.
+            return {
+                code: EXIT.LOGIN_INCOMPLETE,
+                out: "",
+                err: `Refusing the login response — ${outcome.reason}. Nothing was written.\n`,
+            };
+        case "failed":
+            return { code: EXIT.INTERNAL, out: "", err: `Login could not start: ${outcome.reason}.\n` };
+    }
+}
+/** `uninstall`: hand the resolved paths to the reverter and report what it did. */
+function uninstall(args, ctx) {
+    const outcome = revertConfig(resolvePaths(args.target, ctx.paths, args.client), {
+        fromBackup: args.fromBackup,
+        force: args.yes,
+        agentIdGuard: args.agentIdGuard,
+    });
+    return reportRevert(outcome, args.json);
+}
+export async function dispatch(args, ctx) {
+    if (args.verb === "uninstall")
+        return uninstall(args, ctx);
+    // --print is a preview of the resolved config, which needs no credentials and so
+    // has nothing to sign in for.
+    if (args.print)
+        return printConfig(args);
+    if (args.verb === "login")
+        return login(args, ctx);
+    return install(args, ctx);
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

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

package/dist/snippets.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Snippet builders duplicated from the gateway webapp, so what the CLI writes is
+ * byte-identical to what the UI tells people to copy.
+ *
+ * Copied from AI21Labs/ai21-intelligent-gateway-webapp:
+ *   src/pages/docs/integrations.tsx    — the builders
+ *   src/pages/docs/snippetContext.tsx  — the placeholder constants
+ *
+ * A webapp edit cannot fail our CI, so this drifts silently — re-copy when the
+ * gateway's snippets change. `test/fixtures/webapp-snippets.json` is what catches
+ * a divergence. Only the Claude Code path is mirrored; the LangChain snippets are
+ * now a four-way client matrix whose port is a design question, not a copy job.
+ *
+ * One deliberate divergence: the webapp always emits `x-ai21-user-id`, having a
+ * signed-in user. The CLI is unauthenticated, so that line is absent entirely
+ * unless `--user-id` supplies one — not blank, and no trailing newline.
+ */
+/** Stand-in for the caller's own Anthropic key, which the CLI never holds. */
+export declare const ANTHROPIC_KEY_PLACEHOLDER = "<your-anthropic-api-key>";
+/** Stand-in for the AI21 key in a preview, before one has been supplied. */
+export declare const AI21_KEY_PLACEHOLDER = "<your-ai21-api-key>";
+export interface SnippetInputs {
+    readonly gatewayUrl: string;
+    readonly agentId: string;
+    readonly ai21Key: string;
+    /** Signed-in user id for per-user attribution. Absent on a normal CLI run. */
+    readonly userId?: string | undefined;
+    /**
+     * Marks the traffic as configured by this tool, e.g. `ai21-gateway-cli/0.4.0`.
+     *
+     * Set on what the CLI writes, and deliberately absent from the snippet builders the
+     * contract test pins against the webapp: a config someone pasted by hand did not
+     * come from here and must not claim to have. Lets the gateway tell the two apart
+     * without the CLI reporting anything itself.
+     */
+    readonly client?: string | undefined;
+}
+/** Claude Code's `ANTHROPIC_CUSTOM_HEADERS` value. Header order is contractual. */
+export declare function ccCustomHeaders({ agentId, ai21Key, userId, client }: SnippetInputs): string;
+/**
+ * The `env` block merged into `settings.json`. Three keys, matching the live
+ * builder — no `ANTHROPIC_API_KEY`, because Claude Code supplies its own
+ * Anthropic credential.
+ */
+export declare function ccSettingsEnv(inputs: SnippetInputs): Record<string, string>;
+/** The full `settings.json` document, formatted as the UI renders it. */
+export declare function ccSettings(inputs: SnippetInputs): string;
+/**
+ * The canonical verifying request. Carries all three credentials the gateway
+ * requires — `x-ai21-key`, `x-agent-id`, and the caller's `x-api-key`.
+ */
+export declare function genericCurl({ gatewayUrl, agentId, ai21Key, userId }: SnippetInputs): string;

package/dist/snippets.js

@@ -0,0 +1,71 @@
+/**
+ * Snippet builders duplicated from the gateway webapp, so what the CLI writes is
+ * byte-identical to what the UI tells people to copy.
+ *
+ * Copied from AI21Labs/ai21-intelligent-gateway-webapp:
+ *   src/pages/docs/integrations.tsx    — the builders
+ *   src/pages/docs/snippetContext.tsx  — the placeholder constants
+ *
+ * A webapp edit cannot fail our CI, so this drifts silently — re-copy when the
+ * gateway's snippets change. `test/fixtures/webapp-snippets.json` is what catches
+ * a divergence. Only the Claude Code path is mirrored; the LangChain snippets are
+ * now a four-way client matrix whose port is a design question, not a copy job.
+ *
+ * One deliberate divergence: the webapp always emits `x-ai21-user-id`, having a
+ * signed-in user. The CLI is unauthenticated, so that line is absent entirely
+ * unless `--user-id` supplies one — not blank, and no trailing newline.
+ */
+/** Stand-in for the caller's own Anthropic key, which the CLI never holds. */
+export const ANTHROPIC_KEY_PLACEHOLDER = "<your-anthropic-api-key>";
+/** Stand-in for the AI21 key in a preview, before one has been supplied. */
+export const AI21_KEY_PLACEHOLDER = "<your-ai21-api-key>";
+/** Drops the lines that only exist when a user id was supplied. */
+function joinLines(lines) {
+    return lines.filter((line) => line !== undefined).join("\n");
+}
+/** Claude Code's `ANTHROPIC_CUSTOM_HEADERS` value. Header order is contractual. */
+export function ccCustomHeaders({ agentId, ai21Key, userId, client }) {
+    return joinLines([
+        `x-ai21-key: ${ai21Key}`,
+        `x-agent-id: ${agentId}`,
+        userId === undefined ? undefined : `x-ai21-user-id: ${userId}`,
+        client === undefined ? undefined : `x-ai21-client: ${client}`,
+    ]);
+}
+/**
+ * The `env` block merged into `settings.json`. Three keys, matching the live
+ * builder — no `ANTHROPIC_API_KEY`, because Claude Code supplies its own
+ * Anthropic credential.
+ */
+export function ccSettingsEnv(inputs) {
+    return {
+        ANTHROPIC_BASE_URL: inputs.gatewayUrl,
+        ANTHROPIC_CUSTOM_HEADERS: ccCustomHeaders(inputs),
+        // "true", not "auto", to match what the dashboard tells people to set — see the
+        // webapp's Claude Code onboarding snippet (integrations.tsx). Same key written by
+        // both halves, so a repo configured here has to agree with the docs it followed.
+        ENABLE_TOOL_SEARCH: "true",
+    };
+}
+/** The full `settings.json` document, formatted as the UI renders it. */
+export function ccSettings(inputs) {
+    return JSON.stringify({ env: ccSettingsEnv(inputs) }, null, 2);
+}
+/**
+ * The canonical verifying request. Carries all three credentials the gateway
+ * requires — `x-ai21-key`, `x-agent-id`, and the caller's `x-api-key`.
+ */
+export function genericCurl({ gatewayUrl, agentId, ai21Key, userId }) {
+    return joinLines([
+        `curl ${gatewayUrl}/v1/messages \\`,
+        `  -H "x-ai21-key: ${ai21Key}" \\`,
+        `  -H "x-api-key: ${ANTHROPIC_KEY_PLACEHOLDER}" \\`,
+        `  -H "anthropic-version: 2023-06-01" \\`,
+        `  -H "x-agent-id: ${agentId}" \\`,
+        userId === undefined ? undefined : `  -H "x-ai21-user-id: ${userId}" \\`,
+        `  -H "content-type: application/json" \\`,
+        `  -d '{"model": "claude-sonnet-4-5", "max_tokens": 64,`,
+        `       "messages": [{"role": "user", "content": "Hello through the gateway"}]}'`,
+    ]);
+}
+//# sourceMappingURL=snippets.js.map

package/dist/snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../src/snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAEpE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAmB1D,mEAAmE;AACnE,SAAS,SAAS,CAAC,KAAsC;IACvD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAiB;IACjF,OAAO,SAAS,CAAC;QACf,eAAe,OAAO,EAAE;QACxB,eAAe,OAAO,EAAE;QACxB,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,MAAM,EAAE;QAC9D,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,MAAM,EAAE;KAC9D,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO;QACL,kBAAkB,EAAE,MAAM,CAAC,UAAU;QACrC,wBAAwB,EAAE,eAAe,CAAC,MAAM,CAAC;QACjD,gFAAgF;QAChF,kFAAkF;QAClF,iFAAiF;QACjF,kBAAkB,EAAE,MAAM;KAC3B,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,MAAqB;IAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAiB;IACjF,OAAO,SAAS,CAAC;QACf,QAAQ,UAAU,iBAAiB;QACnC,qBAAqB,OAAO,MAAM;QAClC,oBAAoB,yBAAyB,MAAM;QACnD,yCAAyC;QACzC,qBAAqB,OAAO,MAAM;QAClC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,yBAAyB,MAAM,MAAM;QACxE,0CAA0C;QAC1C,wDAAwD;QACxD,iFAAiF;KAClF,CAAC,CAAC;AACL,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,96 @@
+import { type ResolvedUrls } from "./args.js";
+export declare const CLAUDE_COMMAND = "claude";
+export declare const CLAUDE_PROMPT = "ai21-gateway CLI connectivity check \u2014 reply with OK and nothing else.";
+export declare const PING_PATH = "/v1/messages";
+/**
+ * Both tiers are bounded; the spawn gets longer because it waits on a full model
+ * round trip. 20s is measured, not guessed: a working `claude -p` returns in ~5s,
+ * and a rejected one hangs rather than failing, so this budget is what turns that
+ * hang into a message.
+ */
+export declare const PING_TIMEOUT_MS = 10000;
+export declare const CLAUDE_TIMEOUT_MS = 20000;
+/** Mirrors the `genericCurl` snippet; a contract test holds the two together. */
+export declare const PING_BODY: {
+    readonly model: "claude-sonnet-4-5";
+    readonly max_tokens: 64;
+    readonly messages: readonly [{
+        readonly role: "user";
+        readonly content: "Hello through the gateway";
+    }];
+};
+export type VerifyVia = "claude-cli" | "direct-ping";
+/** How verification ended. Never maps to a non-zero exit code. */
+export type VerifyOutcome = {
+    readonly kind: "disabled";
+} | {
+    readonly kind: "skipped";
+    readonly hint: string;
+} | {
+    readonly kind: "passed";
+    readonly via: VerifyVia;
+} | {
+    readonly kind: "failed";
+    readonly via: VerifyVia;
+    readonly reason: string;
+};
+export interface VerifyContext {
+    readonly urls: ResolvedUrls;
+    readonly agentId: string;
+    readonly ai21Key: string;
+    readonly userId?: string | undefined;
+    /** `--anthropic-key`, which outranks the environment. */
+    readonly anthropicKey?: string | undefined;
+    readonly processEnv: Record<string, string | undefined>;
+    /**
+     * Where to run `claude`: the directory in which the file we wrote is the one that
+     * wins. Home for `--user`, since a project-local settings.json outranks it.
+     */
+    readonly cwd: string;
+}
+export interface CommandResult {
+    /** `null` when the process was killed or could not be started at all. */
+    readonly code: number | null;
+    readonly timedOut: boolean;
+    /** Combined stdout+stderr, used only to explain a failure. */
+    readonly output: string;
+}
+/** Just enough of `fetch` to ping with. `text` is optional; absent means inconclusive. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text?: () => Promise<string>;
+}>;
+export interface PathLookup {
+    readonly platform: string;
+    readonly processEnv: Record<string, string | undefined>;
+    /** Injected so the tier-1 tests never depend on what is installed. */
+    readonly isExecutableFile: (candidate: string) => boolean;
+}
+export interface VerifyDeps {
+    readonly lookup: PathLookup;
+    readonly runCommand: (executable: string, args: readonly string[], opts: {
+        readonly cwd: string;
+        readonly timeoutMs: number;
+    }) => Promise<CommandResult>;
+    readonly fetchImpl: FetchLike;
+}
+/**
+ * Hand-rolled rather than shelling out to `which`/`where`, which is slower and
+ * absent from stripped Windows images. `node:path`'s `join` and `delimiter` follow
+ * the *host* platform, so they cannot resolve a Windows PATH under test on macOS.
+ */
+export declare function findOnPath(command: string, lookup: PathLookup): string | undefined;
+/**
+ * Which side rejected us, without needing an Anthropic key: a deliberately invalid
+ * `x-api-key` cannot succeed, so whichever layer answers is the answer.
+ */
+export type CredentialVerdict = "ai21-rejected" | "ai21-accepted" | "inconclusive";
+export declare function verify(ctx: VerifyContext, deps: VerifyDeps): Promise<VerifyOutcome>;
+/** The real-world adapters, kept here so `cli.ts` stays a thin edge. */
+export declare function nodeVerifyDeps(processEnv: Record<string, string | undefined>): VerifyDeps;