@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/http.js

@@ -0,0 +1,212 @@
+/**
+ * fetch 包装（设计 §1.2 ai/http.ts）：超时、头合并（值为 null 删除）、错误体读取。
+ *
+ * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。Node ≥ 24 设 `NODE_USE_ENV_PROXY=1`
+ * 即可让 fetch 走环境变量代理；Node 22 需在启动参数里加 `--use-env-proxy`（22.21+）。
+ * 本模块不自行实现代理，env 原样透传给运行时处理。
+ *
+ * 协议层自身**不重试**（重试在会话层，§3.6）。
+ */
+import { AMA_VERSION } from "../version.js";
+/** 大小写不敏感地合并头；后者覆盖前者；值为 null 表示删除该头。键保留最后一次出现的写法。 */
+export function mergeHeaders(...sources) {
+    const merged = new Map();
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const [name, value] of Object.entries(source)) {
+            const key = name.toLowerCase();
+            if (value === null)
+                merged.delete(key);
+            else if (value !== undefined)
+                merged.set(key, { name, value });
+        }
+    }
+    const out = {};
+    for (const { name, value } of merged.values())
+        out[name] = value;
+    return out;
+}
+export function hasHeader(headers, name) {
+    if (!headers)
+        return false;
+    const wanted = name.toLowerCase();
+    return Object.entries(headers).some(([key, value]) => key.toLowerCase() === wanted && typeof value === "string" && value.length > 0);
+}
+/** 头里已经带了鉴权（调用方自管 key）时，流函数不再要求 apiKey。 */
+export function hasAuthHeader(headers) {
+    return (hasHeader(headers, "authorization") ||
+        hasHeader(headers, "x-api-key") ||
+        hasHeader(headers, "x-goog-api-key"));
+}
+/** 按 AuthHeader 形状生成鉴权头；无 key 时返回空对象。 */
+export function authHeaders(apiKey, shape, fallback) {
+    if (!apiKey)
+        return {};
+    const resolved = shape ?? fallback;
+    if (resolved === "authorization-bearer")
+        return { Authorization: `Bearer ${apiKey}` };
+    if (resolved === "x-api-key")
+        return { "x-api-key": apiKey };
+    if (resolved === "x-goog-api-key")
+        return { "x-goog-api-key": apiKey };
+    return { [resolved.header]: `${resolved.prefix ?? ""}${apiKey}` };
+}
+export const USER_AGENT = `ama/${AMA_VERSION}`;
+/** baseUrl 与路径拼接（去掉多余斜杠）。 */
+export function joinUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+/** 非 2xx 响应；`message` 已是可展示、可被 overflow / 重试分类器匹配的文本。 */
+export class HttpError extends Error {
+    status;
+    body;
+    retryAfterMs;
+    constructor(status, message, body, retryAfterMs) {
+        super(message);
+        this.name = "HttpError";
+        this.status = status;
+        this.body = body;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class RequestTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs} ms`);
+        this.name = "RequestTimeoutError";
+    }
+}
+const MAX_ERROR_BODY = 4000;
+/**
+ * 从错误体提取文本：识别 `{error:{type,message,code}}`、`{error:"..."}`、`{message}`、
+ * `{detail}` 等常见形状；不是 JSON 则截断原文。结果形如 `429 rate_limit_error: ...`。
+ */
+export function formatErrorBody(status, statusText, body) {
+    const trimmed = body.trim();
+    let detail = "";
+    if (trimmed.length > 0) {
+        try {
+            detail = describeErrorJson(JSON.parse(trimmed)) ?? trimmed;
+        }
+        catch {
+            detail = trimmed;
+        }
+    }
+    if (detail.length > MAX_ERROR_BODY)
+        detail = `${detail.slice(0, MAX_ERROR_BODY)}…`;
+    const head = statusText ? `${status} ${statusText}` : `${status}`;
+    return detail ? `${status} ${detail}` : `${head} (no body)`;
+}
+/** 识别 JSON 错误体；无法识别返回 undefined。也用于 SSE 流内的 error 事件。 */
+export function describeErrorJson(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    const inner = record["error"];
+    if (typeof inner === "string")
+        return inner;
+    if (typeof inner === "object" && inner !== null) {
+        const err = inner;
+        const kind = pickString(err["type"]) ?? pickString(err["code"]) ?? pickString(err["status"]);
+        const message = pickString(err["message"]) ?? JSON.stringify(err);
+        const metadata = err["metadata"];
+        const raw = typeof metadata === "object" && metadata !== null
+            ? pickString(metadata["raw"])
+            : undefined;
+        const base = kind && !message.startsWith(kind) ? `${kind}: ${message}` : message;
+        return raw && !base.includes(raw) ? `${base}\n${raw}` : base;
+    }
+    const message = pickString(record["message"]) ?? pickString(record["detail"]);
+    if (message) {
+        const code = pickString(record["code"]) ?? pickString(record["type"]);
+        return code && !message.startsWith(code) ? `${code}: ${message}` : message;
+    }
+    return undefined;
+}
+function pickString(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    return undefined;
+}
+function parseRetryAfter(headers) {
+    const value = headers.get("retry-after");
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+/**
+ * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError；
+ * 调用方的 signal 中止 → 原样抛 AbortError（调用方据 signal.aborted 判 aborted）。
+ * 超时只覆盖到拿到响应头为止，流式读取期间由调用方的 signal 控制。
+ */
+export async function postJson(url, options) {
+    const timeout = options.timeoutMs;
+    const timer = new AbortController();
+    const handle = timeout !== undefined && timeout > 0 ? setTimeout(() => timer.abort(), timeout) : undefined;
+    const signal = AbortSignal.any([options.signal, timer.signal]);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: options.headers,
+            body: JSON.stringify(options.body),
+            signal,
+        });
+    }
+    catch (error) {
+        if (timer.signal.aborted && !options.signal.aborted && timeout !== undefined) {
+            throw new RequestTimeoutError(timeout);
+        }
+        throw normalizeNetworkError(error);
+    }
+    finally {
+        if (handle)
+            clearTimeout(handle);
+    }
+    options.onResponse?.(response.status, response.headers);
+    if (!response.ok) {
+        let body = "";
+        try {
+            body = await response.text();
+        }
+        catch {
+            body = "";
+        }
+        throw new HttpError(response.status, formatErrorBody(response.status, response.statusText, body), body, parseRetryAfter(response.headers));
+    }
+    if (!response.body)
+        throw new Error("Response has no body");
+    return response;
+}
+/** undici 的 `fetch failed` 把真正原因藏在 cause 里；拼出来便于重试分类与排错。 */
+export function normalizeNetworkError(error) {
+    if (!(error instanceof Error))
+        return error;
+    if (error.name === "AbortError")
+        return error;
+    const cause = error.cause;
+    if (cause instanceof Error && !error.message.includes(cause.message)) {
+        const code = cause.code;
+        const suffix = typeof code === "string" ? `${code} ${cause.message}` : cause.message;
+        return new Error(`${error.message}: ${suffix}`, { cause });
+    }
+    return error;
+}
+export function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}

package/dist/ai/json-partial.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 容错 JSON 片段解析（设计 §1.2 ai/json-partial.ts）：流式 tool_call 参数在每个增量后都要
+ * 能给出「到目前为止」的对象；结束时参数也可能有小毛病（字符串里的裸控制字符、非法转义）。
+ *
+ * `parsePartialJson` 是一个宽松的递归下降解析器：
+ * - 输入在任意位置截断都返回已解析的部分（未完成的字符串保留已收到的字符；未完成的键、
+ *   只有键没有值的成员被丢弃；未完成的数字取能解析的前缀；未完成的字面量按前缀补全）；
+ * - 字符串内的裸控制字符照收，非法转义 `\x` 保留为两个字符；
+ * - 遇到无法继续的语法错误时返回到错误点为止已解析的部分。
+ */
+/** 宽松解析（见文件头）；无可解析内容时返回 undefined。 */
+export declare function parsePartialJson(text: string): unknown;
+/** 先严格解析，失败再宽松解析。 */
+export declare function parseJsonLenient(text: string): unknown;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** 工具调用参数：结果总是对象（流契约要求 toolcall_end 时参数为合法对象）。 */
+export declare function parseToolArguments(text: string): Record<string, unknown>;

package/dist/ai/json-partial.js

@@ -0,0 +1,243 @@
+/**
+ * 容错 JSON 片段解析（设计 §1.2 ai/json-partial.ts）：流式 tool_call 参数在每个增量后都要
+ * 能给出「到目前为止」的对象；结束时参数也可能有小毛病（字符串里的裸控制字符、非法转义）。
+ *
+ * `parsePartialJson` 是一个宽松的递归下降解析器：
+ * - 输入在任意位置截断都返回已解析的部分（未完成的字符串保留已收到的字符；未完成的键、
+ *   只有键没有值的成员被丢弃；未完成的数字取能解析的前缀；未完成的字面量按前缀补全）；
+ * - 字符串内的裸控制字符照收，非法转义 `\x` 保留为两个字符；
+ * - 遇到无法继续的语法错误时返回到错误点为止已解析的部分。
+ */
+class Cursor {
+    text;
+    pos = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    get done() {
+        return this.pos >= this.text.length;
+    }
+    peek() {
+        return this.text.charAt(this.pos);
+    }
+    skipWs() {
+        while (this.pos < this.text.length && /\s/.test(this.text.charAt(this.pos)))
+            this.pos++;
+    }
+}
+/** 解析失败（语法错误）时抛出，携带已解析的部分值。 */
+class Stop extends Error {
+    partial;
+    constructor(partial) {
+        super("stop");
+        this.partial = partial;
+    }
+}
+const NONE = Symbol("none");
+function parseValue(c) {
+    c.skipWs();
+    if (c.done)
+        return NONE;
+    const ch = c.peek();
+    if (ch === "{")
+        return parseObject(c);
+    if (ch === "[")
+        return parseArray(c);
+    if (ch === '"')
+        return parseString(c);
+    if (ch === "-" || (ch >= "0" && ch <= "9"))
+        return parseNumber(c);
+    return parseLiteral(c);
+}
+function parseObject(c) {
+    const out = {};
+    c.pos++; // {
+    while (true) {
+        c.skipWs();
+        if (c.done)
+            return out;
+        const ch = c.peek();
+        if (ch === "}") {
+            c.pos++;
+            return out;
+        }
+        if (ch === ",") {
+            c.pos++;
+            continue;
+        }
+        if (ch !== '"')
+            throw new Stop(out);
+        const start = c.pos;
+        const key = parseString(c);
+        if (c.pos === start)
+            throw new Stop(out);
+        c.skipWs();
+        if (c.done)
+            return out;
+        if (c.peek() !== ":")
+            throw new Stop(out);
+        c.pos++;
+        let value;
+        try {
+            value = parseValue(c);
+        }
+        catch (error) {
+            if (error instanceof Stop) {
+                if (error.partial !== NONE)
+                    out[key] = error.partial;
+                throw new Stop(out);
+            }
+            throw error;
+        }
+        if (value === NONE)
+            return out;
+        out[key] = value;
+    }
+}
+function parseArray(c) {
+    const out = [];
+    c.pos++; // [
+    while (true) {
+        c.skipWs();
+        if (c.done)
+            return out;
+        const ch = c.peek();
+        if (ch === "]") {
+            c.pos++;
+            return out;
+        }
+        if (ch === ",") {
+            c.pos++;
+            continue;
+        }
+        let value;
+        try {
+            value = parseValue(c);
+        }
+        catch (error) {
+            if (error instanceof Stop) {
+                if (error.partial !== NONE)
+                    out.push(error.partial);
+                throw new Stop(out);
+            }
+            throw error;
+        }
+        if (value === NONE)
+            return out;
+        out.push(value);
+    }
+}
+const ESCAPES = {
+    '"': '"',
+    "\\": "\\",
+    "/": "/",
+    b: "\b",
+    f: "\f",
+    n: "\n",
+    r: "\r",
+    t: "\t",
+};
+function parseString(c) {
+    let out = "";
+    c.pos++; // "
+    while (!c.done) {
+        const ch = c.text.charAt(c.pos);
+        if (ch === '"') {
+            c.pos++;
+            return out;
+        }
+        if (ch !== "\\") {
+            out += ch;
+            c.pos++;
+            continue;
+        }
+        const next = c.text.charAt(c.pos + 1);
+        if (next === "") {
+            c.pos = c.text.length; // 截断在转义中间：丢掉反斜杠
+            return out;
+        }
+        if (next === "u") {
+            const hex = c.text.slice(c.pos + 2, c.pos + 6);
+            if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+                out += String.fromCharCode(parseInt(hex, 16));
+                c.pos += 6;
+                continue;
+            }
+            if (c.pos + 6 > c.text.length && /^[0-9a-fA-F]*$/.test(hex)) {
+                c.pos = c.text.length; // 截断在 \uXXXX 中间
+                return out;
+            }
+        }
+        const mapped = ESCAPES[next];
+        if (mapped !== undefined)
+            out += mapped;
+        else
+            out += `\\${next}`; // 非法转义：原样保留
+        c.pos += 2;
+    }
+    return out;
+}
+function parseNumber(c) {
+    const match = /^-?(?:\d+)?(?:\.\d*)?(?:[eE][+-]?\d*)?/.exec(c.text.slice(c.pos));
+    const raw = match?.[0] ?? "";
+    c.pos += raw.length;
+    for (let end = raw.length; end > 0; end--) {
+        const value = Number(raw.slice(0, end));
+        if (raw.slice(0, end) !== "-" && Number.isFinite(value))
+            return value;
+    }
+    if (raw.length === 0)
+        throw new Stop(NONE);
+    return NONE;
+}
+const LITERALS = [
+    ["true", true],
+    ["false", false],
+    ["null", null],
+];
+function parseLiteral(c) {
+    const rest = c.text.slice(c.pos);
+    for (const [word, value] of LITERALS) {
+        if (rest.startsWith(word)) {
+            c.pos += word.length;
+            return value;
+        }
+        if (rest.length < word.length && word.startsWith(rest)) {
+            c.pos = c.text.length;
+            return value;
+        }
+    }
+    throw new Stop(NONE);
+}
+/** 宽松解析（见文件头）；无可解析内容时返回 undefined。 */
+export function parsePartialJson(text) {
+    const cursor = new Cursor(text);
+    try {
+        const value = parseValue(cursor);
+        return value === NONE ? undefined : value;
+    }
+    catch (error) {
+        if (error instanceof Stop)
+            return error.partial === NONE ? undefined : error.partial;
+        throw error;
+    }
+}
+/** 先严格解析，失败再宽松解析。 */
+export function parseJsonLenient(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return parsePartialJson(text);
+    }
+}
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 工具调用参数：结果总是对象（流契约要求 toolcall_end 时参数为合法对象）。 */
+export function parseToolArguments(text) {
+    if (text.trim() === "")
+        return {};
+    const value = parseJsonLenient(text);
+    return isPlainObject(value) ? value : {};
+}

package/dist/ai/overflow.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 上下文溢出识别（设计 §3.6「溢出」）。溢出不走会话层重试，走「压缩后以新 run 重试一次」（§9）。
+ *
+ * 三种情形：
+ * 1. 错误文案：各家 400 / 413 的报错（下表；先排除限流类文案，避免「too many tokens, please
+ *    wait」被误判）；
+ * 2. 静默溢出：请求成功但 `usage.input + cacheRead` 超过窗口（个别网关）；
+ * 3. `stopReason: "length"` 且没有工具调用：由调用方结合 `isLengthStop()` 判断（§3.6）。
+ *
+ * 文案表只记录各家文档或实测中出现过的句式；新增供应商时用真实溢出请求取样后补一条。
+ */
+import type { AssistantMessage } from "./types.js";
+/** [正则, 来源说明]。 */
+export declare const OVERFLOW_PATTERNS: readonly (readonly [RegExp, string])[];
+/** 错误文本是否表示上下文溢出。 */
+export declare function isOverflowErrorText(text: string): boolean;
+/**
+ * 助手消息是否表示上下文溢出（情形 1、2）。`contextWindow` 缺省时不判静默溢出。
+ */
+export declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
+/** `length` 停止且没有工具调用：§9 的「压缩后重试一次」候选。 */
+export declare function isLengthStop(message: AssistantMessage): boolean;

package/dist/ai/overflow.js

@@ -0,0 +1,61 @@
+/**
+ * 上下文溢出识别（设计 §3.6「溢出」）。溢出不走会话层重试，走「压缩后以新 run 重试一次」（§9）。
+ *
+ * 三种情形：
+ * 1. 错误文案：各家 400 / 413 的报错（下表；先排除限流类文案，避免「too many tokens, please
+ *    wait」被误判）；
+ * 2. 静默溢出：请求成功但 `usage.input + cacheRead` 超过窗口（个别网关）；
+ * 3. `stopReason: "length"` 且没有工具调用：由调用方结合 `isLengthStop()` 判断（§3.6）。
+ *
+ * 文案表只记录各家文档或实测中出现过的句式；新增供应商时用真实溢出请求取样后补一条。
+ */
+/** [正则, 来源说明]。 */
+export const OVERFLOW_PATTERNS = [
+    [/prompt is too long/i, "Anthropic: prompt is too long: N tokens > M maximum"],
+    [/request_too_large/i, "Anthropic: 413 request_too_large"],
+    [/exceeds the context window/i, "OpenAI: Your input exceeds the context window of this model"],
+    [/maximum context length is \d+ tokens/i, "OpenAI / OpenRouter / DeepSeek"],
+    [/exceeds (?:the )?(?:model'?s )?maximum context length/i, "OpenAI 兼容网关（vLLM / LiteLLM）"],
+    [/input token count.*exceeds the maximum/i, "Google Gemini"],
+    [
+        /exceeds the maximum number of tokens allowed/i,
+        "Google Gemini（无 input token count 前缀的变体）",
+    ],
+    [/maximum prompt length is \d+/i, "xAI"],
+    [/reduce the length of the messages/i, "Groq"],
+    [/too large for model with \d+ maximum context length/i, "Mistral"],
+    [/exceeded model token limit/i, "Moonshot / Kimi"],
+    [/prompt (?:too long|exceeds max length)/i, "智谱 GLM（code 1261）/ Ollama"],
+    [/range of input length should be/i, "DashScope / Qwen"],
+    [/greater than the context length/i, "LM Studio"],
+    [/exceeds the available context size/i, "llama.cpp server"],
+    [/context[_ ]length[_ ]exceeded/i, "通用：context_length_exceeded"],
+    [/model_context_window_exceeded/i, "通用：finish_reason 文本化"],
+    [/token limit exceeded/i, "通用"],
+];
+/** 命中这些的不算溢出（限流 / 配额）。 */
+const NOT_OVERFLOW = [/rate[ _-]?limit/i, /too many requests/i, /\b429\b/];
+/** 错误文本是否表示上下文溢出。 */
+export function isOverflowErrorText(text) {
+    if (NOT_OVERFLOW.some((re) => re.test(text)))
+        return false;
+    return OVERFLOW_PATTERNS.some(([re]) => re.test(text));
+}
+/**
+ * 助手消息是否表示上下文溢出（情形 1、2）。`contextWindow` 缺省时不判静默溢出。
+ */
+export function isContextOverflow(message, contextWindow) {
+    if (message.stopReason === "error" && message.errorMessage) {
+        if (isOverflowErrorText(message.errorMessage))
+            return true;
+    }
+    if (contextWindow !== undefined && contextWindow > 0 && message.stopReason === "stop") {
+        if (message.usage.input + message.usage.cacheRead > contextWindow)
+            return true;
+    }
+    return false;
+}
+/** `length` 停止且没有工具调用：§9 的「压缩后重试一次」候选。 */
+export function isLengthStop(message) {
+    return (message.stopReason === "length" && !message.content.some((block) => block.type === "toolCall"));
+}

package/dist/ai/providers/auth.d.ts

@@ -0,0 +1,71 @@
+/**
+ * API Key 发现（设计 §3.5）。顺序：
+ *   ① `--api-key`（只对 `--model` 指定的那家供应商）
+ *   ② `--auth-file` / profile.authFile 指向的 auth.json
+ *   ③ 用户级 `<configDir>/auth.json`（不是 0600 → warning 并照用）
+ *   ④ config.json 的 `providers.<id>.apiKey`（`$ENV_NAME`、`${ENV_NAME}`、`!command`；`$$` 转义）
+ *   ⑤ 环境变量：`provider.envKeys` 顺序（profile.authEnv=false 时跳过）
+ *   ⑥ `requiresApiKey: false` 的供应商：无 key 也放行（source "none"）
+ *
+ * auth.json 的 `apiKey` 以 `!` 开头 = 执行命令取值（stdout 去首尾空白；超时 10 s；空输出或
+ * 非零退出视为未配置，继续找下一来源）；同一命令进程内只执行一次。
+ * 密钥只出现在 `resolve()` 的返回值里：warning 文案不含密钥与命令输出。
+ */
+import type { AuthFile } from "../../config/types.js";
+import type { ApiKeyResolution, ProviderData } from "../types.js";
+export type KeyProvider = Pick<ProviderData, "id" | "envKeys" | "requiresApiKey">;
+export interface KeyResolverOptions {
+    /** ① `--api-key`：只对 provider 生效。 */
+    cliApiKey?: {
+        provider: string;
+        apiKey: string;
+    } | undefined;
+    /** ② `--auth-file` / profile.authFile。 */
+    authFile?: string | undefined;
+    /** ③ 用户级 auth.json；缺省 `<configDir>/auth.json`；null 关闭。 */
+    userAuthFile?: string | null | undefined;
+    /** ④ config.json 的 `providers.<id>.apiKey` 原始值。 */
+    configKeys?: Readonly<Record<string, string | undefined>> | undefined;
+    /** ⑤ 是否读环境变量（缺省 true）。 */
+    useEnv?: boolean | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    onWarning?: ((message: string) => void) | undefined;
+    /** `!command` 超时，缺省 10 000。 */
+    commandTimeoutMs?: number | undefined;
+}
+/** 用户级配置目录：AMA_CONFIG_DIR > %APPDATA%\ama > $XDG_CONFIG_HOME/ama > ~/.config/ama。 */
+export declare function defaultConfigDir(env?: NodeJS.ProcessEnv): string;
+type AuthEntry = AuthFile["providers"][string];
+/** 读 auth.json；不存在返回 undefined；格式错误 / 权限过宽记 warning。 */
+export declare function readAuthFile(path: string, onWarning?: (message: string) => void): AuthFile | undefined;
+/**
+ * 展开 config.json 的 `$NAME` / `${NAME}`（`$$` → `$`）。引用的变量未设置或为空 →
+ * undefined（视为未配置）。
+ */
+export declare function expandEnvRefs(value: string, env: NodeJS.ProcessEnv): string | undefined;
+export declare class ApiKeyResolver {
+    private readonly options;
+    private readonly env;
+    private readonly commandCache;
+    private readonly fileCache;
+    constructor(options?: KeyResolverOptions);
+    private warn;
+    private authFiles;
+    private loadFile;
+    /** auth.json 里该供应商的条目（按 ② ③ 顺序第一个）。 */
+    authEntry(providerId: string): {
+        entry: AuthEntry;
+        path: string;
+    } | undefined;
+    private runCommand;
+    private fromAuthFiles;
+    private fromConfig;
+    private fromEnv;
+    resolve(provider: KeyProvider): Promise<ApiKeyResolution>;
+    /**
+     * 同步判断「看起来配置了 key」（不执行 `!command`，只看配置是否存在；env 引用需已设置）。
+     * 供 `findModel()` 在无斜杠引用时过滤候选。
+     */
+    hasConfiguredKey(provider: KeyProvider): boolean;
+}
+export {};