agent-mcp-hub 0.5.2

package/dist/failure.js

@@ -0,0 +1,210 @@
+import { AgentStalledError, InvalidCwdError, OutputLimitError, ServerBusyError, SpawnError, TimeoutError, } from "./exec.js";
+import { stripAnsi } from "./ansi.js";
+export { stripAnsi } from "./ansi.js";
+/** Lowercased, ANSI-free view of `s` used for phrase matching (never shown). */
+export function normalize(s) {
+    return stripAnsi(s).toLowerCase();
+}
+/** Upstream-overload markers — checked FIRST so they never become auth. */
+const BUSY_PHRASES = ["rate limit", "429", "overloaded", "try again later", "503", "server busy"];
+/**
+ * High-confidence, adapter-specific auth phrases (R10). Only these trigger
+ * `not_authenticated`; broad HTTP/token markers (`401`, `unauthorized`, …) are
+ * deliberately absent so a bare log line like `HTTP 401 GET /x` stays a
+ * `tool_failure`.
+ */
+const PRIMARY_AUTH_PHRASES = [
+    "not logged in",
+    "not authenticated",
+    "sign in",
+    "sign-in",
+    "please log in",
+    "please run /login",
+    "login required",
+    "authentication required",
+    "no credentials",
+    "no api key",
+    "set openai_api_key",
+    "set anthropic_api_key",
+    "invalid api key",
+    "api key not found",
+    "press any key to sign in",
+    // NB: only the specific "please run /login" (above) — bare "please run" is too
+    // broad (e.g. "please run `npm install`" is NOT an auth failure).
+    "auth login",
+];
+/** Quota/billing is a spend problem, never an auth problem — suppresses auth. */
+const QUOTA_PHRASES = ["insufficient_quota", "billing"];
+const CONFIG_PHRASES = [
+    "not configured",
+    "no default model",
+    "no model",
+    "no provider",
+    "missing config",
+    "model not found",
+];
+const CAUSE_MAX = 160;
+const TAIL_MAX = 500;
+/** Clip to the first `max` chars, appending an ellipsis marker when truncated. */
+function clipHead(s, max) {
+    return s.length <= max ? s : s.slice(0, max) + "…";
+}
+/** Clip to the last `max` chars, prefixing an ellipsis marker when truncated. */
+function clipTail(s, max) {
+    return s.length <= max ? s : "…" + s.slice(s.length - max);
+}
+/** First non-empty ANSI-stripped line of stderr (falling back to stdout), clipped. */
+function causeSnippet(result) {
+    const source = result.stderr.trim().length > 0 ? result.stderr : result.stdout;
+    const line = stripAnsi(source)
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return clipHead(line ?? "", CAUSE_MAX);
+}
+/** Trimmed, ANSI-stripped stderr/stdout tail for tool_failure bodies. */
+function outputTail(result) {
+    const source = result.stderr.trim().length > 0 ? result.stderr : result.stdout;
+    const cleaned = stripAnsi(source).trim();
+    return cleaned.length === 0 ? "(no output)" : clipTail(cleaned, TAIL_MAX);
+}
+/** `Fix: run \`<loginCommand>\`` plus an optional `(or set <ENV>)` clause. */
+function remediation(adapter) {
+    const env = adapter.apiKeyEnv ? ` (or set ${adapter.apiKeyEnv})` : "";
+    return `Fix: run \`${adapter.loginCommand}\`${env}.`;
+}
+function classifyError(adapter, error) {
+    // Before SpawnError: a missing cwd also surfaces as ENOENT, and reporting it as
+    // "not installed" sends the caller after the wrong fault entirely.
+    if (error instanceof InvalidCwdError) {
+        return {
+            code: "invalid_cwd",
+            message: `${adapter.name} failed: cwd is not a directory this server can see.\n` +
+                `${error.cwd}\n` +
+                `Fix: pass an absolute path that exists on this machine — the path must be ` +
+                `resolvable by the server process itself.`,
+        };
+    }
+    if (error instanceof SpawnError) {
+        return {
+            code: "not_installed",
+            message: `${adapter.name} failed: not installed.\n` +
+                `${adapter.name} was not found on PATH (spawn failed).\n` +
+                `Fix: install the CLI and ensure it is on PATH.`,
+        };
+    }
+    if (error instanceof ServerBusyError) {
+        return {
+            code: "server_busy",
+            message: `${adapter.name} failed: server busy.\n` +
+                `The agent pool/queue is full.\n` +
+                `Fix: retry shortly.`,
+        };
+    }
+    if (error instanceof AgentStalledError) {
+        // Matched BEFORE TimeoutError: a stalled agent is a network-path problem, not
+        // a "wait longer" problem. The message names the agent, quotes the matched
+        // signature, points at the common cause (TLS-intercepting proxy), and tells
+        // the caller to treat the agent as unavailable. Never suggests raising the
+        // timeout — that is what the timed_out message wrongly says.
+        return {
+            code: "stream_stalled",
+            message: `${adapter.name} failed: stream stalled.\n` +
+                `Detected diagnostic reconnect pattern: "${error.signature}" (strike ${error.strikes}).\n` +
+                `The agent cannot complete a run in this environment — common cause is a TLS-intercepting ` +
+                `proxy or a network path that drops the agent's backend connection.\n` +
+                `Treat ${adapter.name} as unavailable until the network path is fixed.`,
+        };
+    }
+    if (error instanceof TimeoutError) {
+        // Split by WHICH cap fired: an idle timeout means the agent went silent
+        // (likely hung or its backend is unreachable) — raising the cap won't help,
+        // so we point at the CLI/model/connection instead. A total timeout means a
+        // genuinely long run outgrew the runtime cap, so raising it is the fix.
+        if (error.kind === "idle") {
+            return {
+                code: "timed_out",
+                message: `${adapter.name} failed: no output (idle timeout).\n` +
+                    `The agent produced no output for ${error.timeoutMs}ms — it may be hung, ` +
+                    `or its model/backend is unreachable.\n` +
+                    `Fix: check the ${adapter.name} CLI, its model, and the network connection.`,
+            };
+        }
+        return {
+            code: "timed_out",
+            message: `${adapter.name} failed: timed out after ${error.timeoutMs}ms.\n` +
+                `The total runtime cap was exceeded before the agent finished.\n` +
+                `Fix: raise timeoutMs (or MCP_AGENT_TIMEOUT_MS), or check the agent/model is responsive.`,
+        };
+    }
+    if (error instanceof OutputLimitError) {
+        return {
+            code: "output_limit",
+            message: `${adapter.name} failed: output limit exceeded.\n` +
+                `The agent produced more than ${error.maxOutputBytes} bytes.\n` +
+                `Fix: narrow the prompt, or raise maxOutputBytes.`,
+        };
+    }
+    // Default class — every thrown error (incl. the opencode dash-guard) lands here.
+    const raw = error instanceof Error ? error.message : String(error);
+    return {
+        code: "tool_failure",
+        message: `${adapter.name} failed:\n${clipHead(stripAnsi(raw).trim(), TAIL_MAX)}`,
+    };
+}
+function classifyResult(adapter, result) {
+    const text = normalize(`${result.stderr}\n${result.stdout}`);
+    // 1. Overload first: these must never be read as auth.
+    if (BUSY_PHRASES.some((p) => text.includes(p))) {
+        return {
+            code: "server_busy",
+            message: `${adapter.name} failed: server busy.\n` +
+                `${causeSnippet(result)}\n` +
+                `Fix: retry shortly.`,
+        };
+    }
+    // 2. Auth — precision over recall: a primary phrase is required, and quota
+    //    always wins (it is a spend problem, not an auth problem).
+    const hasPrimaryAuth = PRIMARY_AUTH_PHRASES.some((p) => text.includes(p));
+    const hasQuota = QUOTA_PHRASES.some((p) => text.includes(p));
+    if (hasPrimaryAuth && !hasQuota) {
+        return {
+            code: "not_authenticated",
+            message: `${adapter.name} failed: not authenticated.\n` +
+                `${causeSnippet(result)}\n` +
+                remediation(adapter),
+        };
+    }
+    // 3. Configuration.
+    if (CONFIG_PHRASES.some((p) => text.includes(p))) {
+        return {
+            code: "not_configured",
+            message: `${adapter.name} failed: not configured.\n` +
+                `${causeSnippet(result)}\n` +
+                `Fix: set a model/provider (run \`${adapter.loginCommand}\` or configure the CLI)` +
+                `${adapter.apiKeyEnv ? ` — or set ${adapter.apiKeyEnv}` : ""}.`,
+        };
+    }
+    // 4. Default.
+    return {
+        code: "tool_failure",
+        message: `${adapter.name} failed (exit ${result.exitCode ?? "unknown"}).\n${outputTail(result)}`,
+    };
+}
+/**
+ * Map any agent failure to a stable `{ code, message }` with clean, ANSI-free,
+ * actionable text. Pure — no I/O. Precedence (R3): the error branch (classified
+ * by TYPE) takes priority over the result branch; within the result branch,
+ * overload → auth → config → generic tool_failure.
+ */
+export function classifyFailure(adapter, outcome) {
+    if (outcome.error !== undefined && outcome.error !== null) {
+        return classifyError(adapter, outcome.error);
+    }
+    if (outcome.result) {
+        return classifyResult(adapter, outcome.result);
+    }
+    // Neither supplied — defensive fallback, should not happen in practice.
+    return { code: "tool_failure", message: `${adapter.name} failed.\n(no output)` };
+}
+//# sourceMappingURL=failure.js.map

package/dist/failure.js.map

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

package/dist/git.d.ts

@@ -0,0 +1,59 @@
+import type { Exec } from "./exec.js";
+/**
+ * Hardening for running git against an UNTRUSTED working tree. git config is a
+ * code-execution surface: a hostile `.git/config` / `.gitattributes` in the repo
+ * being inspected can make a plain `git diff`/`git status` run an arbitrary
+ * command (CVE-2025-27613/27614 family). Every git call below goes through
+ * `git()`, which neutralises the known execution vectors:
+ *
+ *  - `-c core.fsmonitor=` / `-c core.hooksPath=/dev/null` — a command-line `-c`
+ *    is the HIGHEST-precedence config source (above the repo's own `.git/config`),
+ *    so this disables a hostile local fsmonitor/hook even though the local config
+ *    is still read.
+ *  - `GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM=/dev/null` —
+ *    ignore system/global config entirely.
+ *  - `--no-pager` / `GIT_PAGER=cat`, `GIT_TERMINAL_PROMPT=0` — no pager, no prompt.
+ *  - diff subcommands additionally pass `--no-ext-diff --no-textconv` (see
+ *    `diffArgs`), disabling external-diff and textconv drivers from ANY config.
+ *
+ * Documented RESIDUAL: an attacker-named `filter.<driver>.clean` assigned via the
+ * repo's own `.gitattributes` cannot be disabled by a flag for a fully
+ * attacker-controlled `.git/`. Closing that requires operating on a clean clone
+ * (git's own guidance); it is out of scope for this in-place hardening and is
+ * tracked as a follow-up.
+ */
+export declare const GIT_HARDENING_ENV: Readonly<Record<string, string>>;
+export declare const GIT_HARDENING_TOPLEVEL: string[];
+/** The full argv a hardened git call uses for `subcommand` (exported for tests). */
+export declare function hardenedGitArgs(subcommand: string[]): string[];
+/** A newly-created file surfaced to the reviewer with its bounded contents. */
+export interface UntrackedFile {
+    path: string;
+    /**
+     * The file as a git add-diff (leading `+`, `diff --git`/`Binary files …`
+     * headers), decoded as UTF-8 and capped at MAX_UNTRACKED_FILE_BYTES. A
+     * placeholder when the file could not be read.
+     */
+    content: string;
+    /** True when `content` was cut at the byte cap OR the file was unreadable. */
+    truncated: boolean;
+}
+/**
+ * Per-file byte cap. A malicious or generated file must not blow up the review
+ * prompt, so contents past this point are dropped and `truncated` is set.
+ */
+export declare const MAX_UNTRACKED_FILE_BYTES: number;
+/**
+ * Cap on how many untracked files we read contents for. Beyond this the review
+ * would be unusably large; the overflow is signalled via `untrackedTruncated`.
+ */
+export declare const MAX_UNTRACKED_FILES = 50;
+export declare function isGitRepo(exec: Exec, cwd: string): Promise<boolean>;
+export declare function worktreeDirty(exec: Exec, cwd: string): Promise<boolean>;
+export declare function captureChange(exec: Exec, cwd: string): Promise<{
+    stat: string;
+    diff: string;
+    untracked: UntrackedFile[];
+    /** True when more than MAX_UNTRACKED_FILES exist; the overflow is not read. */
+    untrackedTruncated: boolean;
+}>;

package/dist/git.js

@@ -0,0 +1,127 @@
+// Routes git AND file reads through the injected Exec — no direct process
+// spawning and no node:fs, keeping this module free of I/O side effects (C1).
+/**
+ * Hardening for running git against an UNTRUSTED working tree. git config is a
+ * code-execution surface: a hostile `.git/config` / `.gitattributes` in the repo
+ * being inspected can make a plain `git diff`/`git status` run an arbitrary
+ * command (CVE-2025-27613/27614 family). Every git call below goes through
+ * `git()`, which neutralises the known execution vectors:
+ *
+ *  - `-c core.fsmonitor=` / `-c core.hooksPath=/dev/null` — a command-line `-c`
+ *    is the HIGHEST-precedence config source (above the repo's own `.git/config`),
+ *    so this disables a hostile local fsmonitor/hook even though the local config
+ *    is still read.
+ *  - `GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM=/dev/null` —
+ *    ignore system/global config entirely.
+ *  - `--no-pager` / `GIT_PAGER=cat`, `GIT_TERMINAL_PROMPT=0` — no pager, no prompt.
+ *  - diff subcommands additionally pass `--no-ext-diff --no-textconv` (see
+ *    `diffArgs`), disabling external-diff and textconv drivers from ANY config.
+ *
+ * Documented RESIDUAL: an attacker-named `filter.<driver>.clean` assigned via the
+ * repo's own `.gitattributes` cannot be disabled by a flag for a fully
+ * attacker-controlled `.git/`. Closing that requires operating on a clean clone
+ * (git's own guidance); it is out of scope for this in-place hardening and is
+ * tracked as a follow-up.
+ */
+export const GIT_HARDENING_ENV = {
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_CONFIG_SYSTEM: "/dev/null",
+    GIT_PAGER: "cat",
+    GIT_TERMINAL_PROMPT: "0",
+};
+export const GIT_HARDENING_TOPLEVEL = [
+    "-c",
+    "core.fsmonitor=",
+    "-c",
+    "core.hooksPath=/dev/null",
+    "--no-pager",
+];
+/** The full argv a hardened git call uses for `subcommand` (exported for tests). */
+export function hardenedGitArgs(subcommand) {
+    return [...GIT_HARDENING_TOPLEVEL, ...subcommand];
+}
+/** Run a read-only git subcommand hardened against the worktree's own config. */
+function git(exec, cwd, subcommand, extra) {
+    return exec("git", hardenedGitArgs(subcommand), {
+        cwd,
+        env: GIT_HARDENING_ENV,
+        ...extra,
+    });
+}
+/** Diff args with the external-diff and textconv execution vectors disabled. */
+function diffArgs(...rest) {
+    return ["diff", "--no-ext-diff", "--no-textconv", ...rest];
+}
+/**
+ * Per-file byte cap. A malicious or generated file must not blow up the review
+ * prompt, so contents past this point are dropped and `truncated` is set.
+ */
+export const MAX_UNTRACKED_FILE_BYTES = 64 * 1024;
+/**
+ * Cap on how many untracked files we read contents for. Beyond this the review
+ * would be unusably large; the overflow is signalled via `untrackedTruncated`.
+ */
+export const MAX_UNTRACKED_FILES = 50;
+export async function isGitRepo(exec, cwd) {
+    const result = await git(exec, cwd, ["rev-parse", "--is-inside-work-tree"]);
+    return result.exitCode === 0 && result.stdout.trim() === "true";
+}
+export async function worktreeDirty(exec, cwd) {
+    const result = await git(exec, cwd, ["status", "--porcelain"]);
+    return result.stdout.length > 0;
+}
+/**
+ * Read one untracked file's contents through the injected Exec, bounded to
+ * MAX_UNTRACKED_FILE_BYTES. `git diff --no-index -- /dev/null <path>` prints the
+ * file as an addition diff and, crucially, collapses BINARY files to a short
+ * "Binary files … differ" line — so a binary blob can never flood the prompt.
+ * git exits 1 when a diff exists (the normal case) and 0 for an empty file; any
+ * other code means it could not read the file. Surfacing that as an explicit
+ * placeholder (truncated) is safer than a silent empty body, which a reviewer
+ * would read as "nothing to see here".
+ */
+async function readUntracked(exec, cwd, path) {
+    // `--` fences `path` as a positional, so a path starting with `-` is safe; the
+    // hardened `git()` disables ext-diff/textconv so reading the file can't execute.
+    const result = await git(exec, cwd, diffArgs("--no-index", "--", "/dev/null", path));
+    if (result.exitCode !== 0 && result.exitCode !== 1) {
+        return { path, content: "(unreadable — git could not read this file)", truncated: true };
+    }
+    const raw = result.stdout;
+    const bytes = Buffer.from(raw, "utf8");
+    if (bytes.length > MAX_UNTRACKED_FILE_BYTES) {
+        return {
+            path,
+            content: bytes.subarray(0, MAX_UNTRACKED_FILE_BYTES).toString("utf8"),
+            truncated: true,
+        };
+    }
+    return { path, content: raw, truncated: false };
+}
+export async function captureChange(exec, cwd) {
+    const statResult = await git(exec, cwd, diffArgs("--stat", "HEAD"));
+    const diffResult = await git(exec, cwd, diffArgs("HEAD"));
+    // `-z`: NUL-delimited, verbatim paths. Splitting on "\n" + trim would drop or
+    // corrupt filenames containing newlines/leading/trailing whitespace, letting a
+    // runner hide a payload file from the review.
+    const untrackedResult = await git(exec, cwd, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+    ]);
+    const paths = untrackedResult.stdout.split("\0").filter((p) => p.length > 0);
+    const untrackedTruncated = paths.length > MAX_UNTRACKED_FILES;
+    const untracked = [];
+    for (const path of paths.slice(0, MAX_UNTRACKED_FILES)) {
+        untracked.push(await readUntracked(exec, cwd, path));
+    }
+    return {
+        stat: statResult.stdout,
+        diff: diffResult.stdout,
+        untracked,
+        untrackedTruncated,
+    };
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { enabledAdapters } from "./registry.js";
+import { buildServer } from "./server.js";
+async function main() {
+    const server = buildServer(enabledAdapters());
+    await server.connect(new StdioServerTransport());
+    // stdio server stays alive until the client closes the pipe
+}
+main().catch((err) => {
+    console.error("agent-mcp-hub fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9C,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,4DAA4D;AAC9D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,70 @@
+import type { Exec } from "./exec.js";
+import type { AgentAdapter } from "./types.js";
+export declare function allAdapters(): AgentAdapter[];
+/**
+ * Union of every adapter's credential env var, DERIVED from the adapter list so a
+ * new agent's key is covered automatically — there is no hand-maintained
+ * duplicate to forget (forgetting one silently leaked the new key to every other
+ * agent). This is the set of secrets that must be isolated between agents.
+ */
+export declare function allCredentialEnvVars(): readonly string[];
+/**
+ * The credential keys to STRIP from `adapter`'s child environment: every OTHER
+ * agent's key. An adapter with its own `apiKeyEnv` keeps exactly that one. A
+ * provider-agnostic adapter (no `apiKeyEnv`, e.g. opencode) owns none, so ALL
+ * tracked keys are stripped — it must never inherit a sibling's secret. Applied
+ * to real runs AND to availability probes, so no spawn path leaks a key.
+ */
+export declare function credentialStripKeys(adapter: AgentAdapter): readonly string[];
+/**
+ * Selects which adapters to expose based on MCP_AGENTS (comma-separated,
+ * whitespace-tolerant, case-sensitive). Unset or empty-after-parse yields all
+ * adapters (never an empty server). Unknown names fail fast with an actionable
+ * message so typos are surfaced at wiring time rather than silently dropped.
+ */
+export declare function enabledAdapters(agentsSpec?: string | undefined): AgentAdapter[];
+/**
+ * Availability has THREE independent axes, and collapsing them is how a broken
+ * agent passes for a healthy one:
+ *
+ *  - `installed` — the binary resolves on PATH with the exec bit. A filesystem
+ *    fact; never inferred from running the binary.
+ *  - `usable` — a probe actually succeeded. `available` mirrors this and is kept
+ *    for callers written against the old boolean shape.
+ *  - `reason` — why not, when not.
+ *
+ * The old implementation asked `--version` the availability question and trusted
+ * its exit code. `codex --version` exits 0 while printing
+ * "WARNING: … could not create PATH aliases: Read-only file system", so a codex
+ * that could not run a single task reported `available: true`. Exit codes are the
+ * weakest possible evidence; the output is where the truth is.
+ */
+export interface AgentAvailability {
+    name: string;
+    installed: boolean;
+    usable: boolean;
+    /** Mirrors `usable`. Retained so existing callers keep working. */
+    available: boolean;
+    reason?: string;
+}
+/**
+ * Resolves a binary the way spawn will: absolute paths as-is, otherwise the first
+ * executable match walking PATH. Returns undefined when nothing matches, which is
+ * the ONLY thing that may set `installed: false`.
+ */
+export declare function resolveOnPath(binary: string, pathEnv?: string | undefined): string | undefined;
+/**
+ * Identifier-shaped lines only. A CLI can exit 0 while emitting a banner, an
+ * update notice, or "you are not logged in" prose — none of which are ids. Lines
+ * containing whitespace are prose; lines without it are candidate ids.
+ */
+export declare function parseProbeIds(stdout: string): string[];
+/** Injected so availability stays testable without depending on the host's PATH. */
+export type ResolveBinary = (binary: string) => string | undefined;
+/**
+ * Probes one adapter. Never throws: a probe failure is data, not an exception.
+ * The probe command is per-adapter because the CLIs disagree — `opencode models`
+ * lists models, `codex models` is not a subcommand at all — so there is no single
+ * command that proves usability across all four.
+ */
+export declare function checkAvailability(adapter: AgentAdapter, exec: Exec, resolve?: ResolveBinary): Promise<AgentAvailability>;