@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/apis/anthropic-request.js

@@ -0,0 +1,282 @@
+/**
+ * anthropic-messages 请求体（设计 §3.1、§3.3、§3.6）：消息转换、三断点缓存、thinking、工具。
+ *
+ * 缓存断点（cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
+ * `ttl: "1h"`，仅 `supportsLongCacheRetention`——官方端点缺省开，中转缺省关、降为 short；最后做 TTL
+ * 顺序校验，5m 之后出现 1h 则全部降为 5m）按优先级取前
+ * `maxCacheBreakpoints` 个：① 最后一条 user 消息（含工具结果）的最后一个块 ② system 末块
+ * ③ 最后一个工具定义（`supportsCacheControlOnTools`）。
+ *
+ * thinking：`adaptiveThinking` 模型发 `{type:"adaptive"}` + `output_config.effort`；
+ * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens；off 发
+ * `{type:"disabled"}`（映射表 off 为 null 的模型不发）。思考开启时不发 temperature，
+ * 除非 `supportsTemperatureWithThinking`。`toolChoice: "none"`（有工具时）→ `tool_choice:{type:"none"}`。
+ */
+import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { budgetedMaxTokens, clampThinkingLevel, mappedThinkingValue, thinkingBudget, } from "../thinking.js";
+import { effectiveRetention, resolveCacheRetention, resolvePromptCacheCompat, } from "./cache-params.js";
+export const ANTHROPIC_VERSION = "2023-06-01";
+export const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
+const ANTHROPIC_COMPAT_KEYS = [
+    "supportsCacheControlOnTools",
+    "supportsTemperatureWithThinking",
+    "adaptiveThinking",
+    "maxCacheBreakpoints",
+];
+export const DEFAULT_ANTHROPIC_COMPAT = {
+    supportsCacheControlOnTools: true,
+    supportsTemperatureWithThinking: false,
+    adaptiveThinking: false,
+    maxCacheBreakpoints: 4,
+};
+function pick(compat) {
+    const out = {};
+    for (const key of ANTHROPIC_COMPAT_KEYS) {
+        const value = compat?.[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+export function detectAnthropicCompat(model, provider) {
+    return { ...DEFAULT_ANTHROPIC_COMPAT, ...pick(provider?.compat), ...pick(model.compat) };
+}
+export function cacheControlFor(retention) {
+    if (retention === "none")
+        return undefined;
+    return retention === "long" ? { type: "ephemeral", ttl: "1h" } : { type: "ephemeral" };
+}
+/**
+ * TTL 顺序校验：Anthropic 按 tools → system → messages 的顺序处理断点，要求 1h 条目都在 5m 之前。
+ * 出现「5m 之后的 1h」→ 全部降为 5m（去掉 ttl）。返回是否做了降级。
+ */
+export function enforceCacheTtlOrder(body) {
+    const marks = [];
+    const collect = (value) => {
+        if (Array.isArray(value))
+            value.forEach(collect);
+        else if (typeof value === "object" && value !== null) {
+            const record = value;
+            const mark = record["cache_control"];
+            if (typeof mark === "object" && mark !== null)
+                marks.push(mark);
+            if (Array.isArray(record["content"]))
+                collect(record["content"]);
+        }
+    };
+    collect(body["tools"]);
+    collect(body["system"]);
+    collect(body["messages"]);
+    const firstShort = marks.findIndex((mark) => mark["ttl"] !== "1h");
+    if (firstShort < 0 || !marks.slice(firstShort).some((mark) => mark["ttl"] === "1h"))
+        return false;
+    for (const mark of marks)
+        delete mark["ttl"];
+    return true;
+}
+/** `{baseUrl}/v1/messages`；baseUrl 已以 `/v1` 结尾（中转常见写法）时不再重复。 */
+export function anthropicMessagesUrl(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    return /\/v1$/i.test(trimmed) ? `${trimmed}/messages` : `${trimmed}/v1/messages`;
+}
+/** Anthropic 要求 tool_use id 匹配 `^[a-zA-Z0-9_-]+$` 且 ≤ 64。 */
+export function normalizeToolId(id) {
+    const cleaned = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+    return cleaned.length > 0 ? cleaned : "tool_call";
+}
+function convertBlocks(content) {
+    const blocks = [];
+    for (const block of content) {
+        if (block.type === "text") {
+            if (block.text.trim().length > 0)
+                blocks.push({ type: "text", text: sanitizeText(block.text) });
+        }
+        else {
+            blocks.push({
+                type: "image",
+                source: { type: "base64", media_type: block.mimeType, data: block.data },
+            });
+        }
+    }
+    return blocks;
+}
+function convertUser(message) {
+    if (typeof message.content === "string") {
+        if (message.content.trim().length === 0)
+            return undefined;
+        return { role: "user", content: sanitizeText(message.content) };
+    }
+    const blocks = convertBlocks(message.content);
+    return blocks.length > 0 ? { role: "user", content: blocks } : undefined;
+}
+function convertAssistant(message) {
+    const blocks = [];
+    for (const block of message.content) {
+        if (block.type === "text") {
+            if (block.text.trim().length > 0)
+                blocks.push({ type: "text", text: sanitizeText(block.text) });
+        }
+        else if (block.type === "thinking") {
+            const signature = block.thinkingSignature ?? "";
+            if (block.redacted && signature) {
+                blocks.push({ type: "redacted_thinking", data: signature });
+            }
+            else if (signature.trim().length > 0) {
+                blocks.push({ type: "thinking", thinking: sanitizeText(block.thinking), signature });
+            }
+            else if (block.thinking.trim().length > 0) {
+                // 无签名（中止或来自别家）的思考不能作为 thinking 回放，降级为文本
+                blocks.push({ type: "text", text: sanitizeText(block.thinking) });
+            }
+        }
+        else {
+            blocks.push({
+                type: "tool_use",
+                id: normalizeToolId(block.id),
+                name: block.name,
+                input: block.arguments,
+            });
+        }
+    }
+    return blocks.length > 0 ? { role: "assistant", content: blocks } : undefined;
+}
+function convertToolResult(message) {
+    const content = typeof message.content === "string" || !message.content.some((b) => b.type === "image")
+        ? sanitizeText(contentText(message.content))
+        : convertBlocks(message.content);
+    return {
+        type: "tool_result",
+        tool_use_id: normalizeToolId(message.toolCallId),
+        content,
+        ...(message.isError ? { is_error: true } : {}),
+    };
+}
+export function convertMessages(messages) {
+    const out = [];
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
+        if (!message)
+            continue;
+        if (message.role === "toolResult") {
+            const results = [];
+            while (i < messages.length && messages[i]?.role === "toolResult") {
+                results.push(convertToolResult(messages[i]));
+                i++;
+            }
+            i--;
+            out.push({ role: "user", content: results });
+            continue;
+        }
+        const converted = message.role === "user" ? convertUser(message) : convertAssistant(message);
+        if (converted)
+            out.push(converted);
+    }
+    return out;
+}
+function convertTools(tools) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: { ...tool.parameters, type: "object" },
+    }));
+}
+/** 在最后一条 user 消息的最后一个块上打断点；返回是否打上。 */
+function markLastUser(messages, cacheControl) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (!message || message["role"] !== "user")
+            continue;
+        const content = message["content"];
+        if (typeof content === "string") {
+            message["content"] = [{ type: "text", text: content, cache_control: cacheControl }];
+            return true;
+        }
+        if (Array.isArray(content) && content.length > 0) {
+            const last = content[content.length - 1];
+            last["cache_control"] = cacheControl;
+            return true;
+        }
+        return false;
+    }
+    return false;
+}
+const DEFAULT_EFFORT = {
+    minimal: "low",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+};
+function applyThinking(body, model, compat, level, requestedMax, hasTools, betas) {
+    if (!model.reasoning)
+        return undefined;
+    if (level === "off") {
+        if (model.thinkingLevelMap?.off !== null)
+            body["thinking"] = { type: "disabled" };
+        return undefined;
+    }
+    if (compat.adaptiveThinking) {
+        const mapped = mappedThinkingValue(model, level);
+        const effort = typeof mapped === "string" ? mapped : DEFAULT_EFFORT[level];
+        body["thinking"] = { type: "adaptive", display: "summarized" };
+        body["output_config"] = { effort };
+        return effort;
+    }
+    const plan = budgetedMaxTokens(model.maxTokens, requestedMax, thinkingBudget(model, level));
+    body["max_tokens"] = plan.maxTokens;
+    if (plan.budget < 1024)
+        return undefined; // 回答上限太小，放弃思考
+    body["thinking"] = { type: "enabled", budget_tokens: plan.budget, display: "summarized" };
+    if (hasTools)
+        betas.push(INTERLEAVED_THINKING_BETA);
+    return String(plan.budget);
+}
+export function buildAnthropicRequest(model, context, options) {
+    const compat = detectAnthropicCompat(model);
+    const normalized = normalizeContext(context, { model });
+    const cacheCompat = resolvePromptCacheCompat(model, "anthropic-messages");
+    const retention = effectiveRetention(resolveCacheRetention(options.cacheRetention), cacheCompat);
+    const cacheControl = cacheControlFor(retention);
+    const messages = convertMessages(normalized.messages);
+    const level = clampThinkingLevel(model, options.thinkingLevel ?? "off");
+    const betas = [];
+    const body = {
+        model: model.id,
+        max_tokens: options.maxTokens ?? model.maxTokens,
+        stream: true,
+    };
+    const system = normalized.systemSections.map((section) => ({
+        type: "text",
+        text: sanitizeText(section.text),
+    }));
+    const tools = convertTools(normalized.tools);
+    let budget = cacheControl ? Math.max(0, compat.maxCacheBreakpoints) : 0;
+    if (cacheControl && budget > 0 && markLastUser(messages, cacheControl))
+        budget--;
+    const lastSystem = system[system.length - 1];
+    if (cacheControl && budget > 0 && lastSystem) {
+        lastSystem["cache_control"] = cacheControl;
+        budget--;
+    }
+    const lastTool = tools[tools.length - 1];
+    if (cacheControl && budget > 0 && lastTool && compat.supportsCacheControlOnTools) {
+        lastTool["cache_control"] = cacheControl;
+    }
+    if (system.length > 0)
+        body["system"] = system;
+    body["messages"] = messages;
+    if (tools.length > 0)
+        body["tools"] = tools;
+    if (tools.length > 0 && options.toolChoice === "none")
+        body["tool_choice"] = { type: "none" };
+    const providerLevel = applyThinking(body, model, compat, level, options.maxTokens, tools.length > 0, betas);
+    const thinkingOn = body["thinking"] !== undefined && level !== "off";
+    if (options.temperature !== undefined &&
+        (!thinkingOn || compat.supportsTemperatureWithThinking)) {
+        body["temperature"] = options.temperature;
+    }
+    if (model.samplingParams)
+        Object.assign(body, model.samplingParams);
+    enforceCacheTtlOrder(body);
+    return { body, betas, thinkingLevel: level, providerThinkingLevel: providerLevel };
+}

package/dist/ai/apis/api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 协议实现注册表（设计 §3.1）：按协议 id 懒加载实现模块。
+ *
+ * `get(id)` 同步返回一个包装实现：`stream()` 先同步做 key 预检（缺 key 同步抛
+ * `AmaError{code:"no_api_key"}`），再在首次调用时 `import()` 真正的实现并转发事件。bundle 里
+ * esbuild 把这些 `import()` 内联成同步 require，懒加载只在 ESM 产物里省启动时间。
+ *
+ * 内置四条协议（anthropic-messages、openai-completions、openai-responses、google-generative-ai）
+ * 与 fake；新增协议在 `createDefaultApiRegistry()` 里加一条 `register({ id, load, detectCompat })`。
+ */
+import type { Api, ApiImplementation, Model, ProviderData } from "../types.js";
+export interface ApiEntry {
+    readonly id: Api;
+    load(): Promise<ApiImplementation>;
+    /** 同步可用的 compat 推断（不必等实现模块加载）。 */
+    detectCompat?(model: Model, provider: ProviderData): unknown;
+}
+export declare class ApiRegistry {
+    private readonly entries;
+    /** 注册（同 id 覆盖）：可以是现成实现，也可以是懒加载条目。 */
+    register(entry: ApiEntry | ApiImplementation): void;
+    unregister(id: Api): boolean;
+    get(id: Api): ApiImplementation | undefined;
+    has(id: Api): boolean;
+    ids(): Api[];
+}
+/** 内置协议 + fake。每次返回新实例（测试可自由覆盖）。 */
+export declare function createDefaultApiRegistry(): ApiRegistry;

package/dist/ai/apis/api.js

@@ -0,0 +1,102 @@
+/**
+ * 协议实现注册表（设计 §3.1）：按协议 id 懒加载实现模块。
+ *
+ * `get(id)` 同步返回一个包装实现：`stream()` 先同步做 key 预检（缺 key 同步抛
+ * `AmaError{code:"no_api_key"}`），再在首次调用时 `import()` 真正的实现并转发事件。bundle 里
+ * esbuild 把这些 `import()` 内联成同步 require，懒加载只在 ESM 产物里省启动时间。
+ *
+ * 内置四条协议（anthropic-messages、openai-completions、openai-responses、google-generative-ai）
+ * 与 fake；新增协议在 `createDefaultApiRegistry()` 里加一条 `register({ id, load, detectCompat })`。
+ */
+import { AssistantEventStreamImpl } from "../event-stream.js";
+import { errorText } from "../http.js";
+import { detectAnthropicCompat } from "./anthropic-request.js";
+import { detectGoogleCompat } from "./google-request.js";
+import { detectCompat as detectOpenAICompat } from "./openai-compat.js";
+import { detectResponsesCompat } from "./openai-responses-request.js";
+import { createOutput, requireApiKey } from "./shared.js";
+function isImplementation(value) {
+    return typeof value.stream === "function";
+}
+function lazyImplementation(entry) {
+    let loaded;
+    const impl = {
+        id: entry.id,
+        stream(model, context, options) {
+            requireApiKey(model, options);
+            const outer = new AssistantEventStreamImpl();
+            loaded ??= entry.load();
+            void loaded
+                .then(async (inner) => {
+                for await (const event of inner.stream(model, context, options))
+                    outer.push(event);
+                outer.end();
+            })
+                .catch((error) => {
+                const message = outer.partial ?? createOutput(model);
+                message.stopReason = options.signal.aborted ? "aborted" : "error";
+                message.errorMessage = errorText(error);
+                outer.push({
+                    type: "error",
+                    reason: options.signal.aborted ? "aborted" : "error",
+                    message,
+                });
+                outer.end();
+            });
+            return outer;
+        },
+    };
+    if (entry.detectCompat) {
+        const detect = entry.detectCompat.bind(entry);
+        impl.detectCompat = (model, provider) => detect(model, provider);
+    }
+    return impl;
+}
+export class ApiRegistry {
+    entries = new Map();
+    /** 注册（同 id 覆盖）：可以是现成实现，也可以是懒加载条目。 */
+    register(entry) {
+        this.entries.set(entry.id, isImplementation(entry) ? entry : lazyImplementation(entry));
+    }
+    unregister(id) {
+        return this.entries.delete(id);
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    has(id) {
+        return this.entries.has(id);
+    }
+    ids() {
+        return [...this.entries.keys()];
+    }
+}
+/** 内置协议 + fake。每次返回新实例（测试可自由覆盖）。 */
+export function createDefaultApiRegistry() {
+    const registry = new ApiRegistry();
+    registry.register({
+        id: "anthropic-messages",
+        load: async () => (await import("./anthropic-messages.js")).anthropicMessagesApi,
+        detectCompat: (model, provider) => detectAnthropicCompat(model, provider),
+    });
+    registry.register({
+        id: "openai-completions",
+        load: async () => (await import("./openai-completions.js")).openAICompletionsApi,
+        detectCompat: (model, provider) => detectOpenAICompat(model, provider),
+    });
+    registry.register({
+        id: "openai-responses",
+        load: async () => (await import("./openai-responses.js")).openAIResponsesApi,
+        detectCompat: (model, provider) => detectResponsesCompat(model, provider),
+    });
+    registry.register({
+        id: "google-generative-ai",
+        load: async () => (await import("./google-generative-ai.js")).googleGenerativeAiApi,
+        detectCompat: (model, provider) => detectGoogleCompat(model, provider),
+    });
+    registry.register({
+        id: "fake",
+        load: async () => (await import("../fake/fake-provider.js")).fakeApi,
+    });
+    return registry;
+}

package/dist/ai/apis/cache-params.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 协议层缓存参数（第三波 §1.3）：缓存兼容开关的端点推断、保留层级解析、亲和头。
+ *
+ * 推断只看最终请求的主机名（不看 provider id：`OPENAI_BASE_URL` 把 openai 指到中转时按中转处理）：
+ * - `sendPromptCacheKey`、`supportsLongCacheRetention`：只有官方端点（api.openai.com /
+ *   api.anthropic.com）缺省开；
+ * - `sendSessionAffinityHeaders`、`supportsExplicitPromptCacheMode`：缺省一律关（实测中转都接受
+ *   但未见命中提升，OpenRouter 未实测，见 docs/providers.md「缓存」）；
+ * - `cacheReporting`：`auto`。
+ * 显式 `model.compat`（registry 已把 provider.compat 合进来）逐字段覆盖推断。
+ *
+ * 400 自动剥离（`postWithCacheFallback`）：端点以 400 拒收并点名 prompt_cache_* / cache_control 时，
+ * 把 `${provider}/${model}` 记入进程级 `strippedCacheParams`，去掉这些字段在 `start` 之前重发一次，
+ * 并提示一次（实测：某中转的 Responses 对 DeepSeek 拒收 prompt_cache_retention / _options）。
+ */
+import { type PostOptions } from "../http.js";
+import type { Api, CacheRetention, Model, PromptCacheCompat } from "../types.js";
+/** 请求实际发往的主机名（小写）；baseUrl 不可解析时返回空串。 */
+export declare function endpointHost(model: Pick<Model, "baseUrl">, api: Api): string;
+/** 解析后的缓存兼容开关：端点推断 ← `model.compat`。 */
+export declare function resolvePromptCacheCompat(model: Pick<Model, "baseUrl" | "compat">, api: Api): PromptCacheCompat;
+/**
+ * 本次请求的保留层级：显式 `options.cacheRetention` 优先；否则 `AMA_CACHE_RETENTION`
+ * （none | short | long，非法值忽略）；都没有 → short。
+ */
+export declare function resolveCacheRetention(retention: CacheRetention | undefined, env?: NodeJS.ProcessEnv): CacheRetention;
+/** `long` 在不支持长保留的端点上降为 `short`。 */
+export declare function effectiveRetention(retention: CacheRetention, compat: Pick<PromptCacheCompat, "supportsLongCacheRetention">): CacheRetention;
+/**
+ * 会话亲和头（`sendSessionAffinityHeaders`）：OpenRouter 用 `x-session-id`，其余
+ * `x-session-affinity` + 每请求一个 `x-client-request-id`。无 sessionId 或 retention 为 none 时不发。
+ */
+export declare function affinityHeaders(model: Pick<Model, "baseUrl" | "compat">, api: Api, sessionId: string | undefined, retention: CacheRetention, newId?: () => string): Record<string, string>;
+type Json = Record<string, unknown>;
+/** 遇到过拒收的 `${provider}/${model}`：进程内之后的请求直接不带缓存参数。 */
+export declare const strippedCacheParams: Set<string>;
+/** 替换剥离提示的输出（宿主 / 测试用）；返回原来的函数。 */
+export declare function setCacheParamWarn(next: (message: string) => void): (message: string) => void;
+/** HTTP 400 且错误体点名了缓存参数 → 返回被拒字段名（小写）；否则 undefined。 */
+export declare function isCacheParamRejection(error: unknown): string | undefined;
+/** 去掉顶层 prompt_cache_* 与任意层级的 cache_control（返回新对象，不改入参）。 */
+export declare function stripCacheParams(body: Json): Json;
+/**
+ * `postJson` 加缓存参数兜底：已记入 `strippedCacheParams` 的模型直接剥离后发；否则照发，
+ * 遇到点名缓存参数的 400 且请求里确有可剥离字段 → 记入集合、提示一次、剥离后重发一次。
+ */
+export declare function postWithCacheFallback(model: Pick<Model, "provider" | "id">, url: string, options: PostOptions): Promise<Response>;
+export {};

package/dist/ai/apis/cache-params.js

@@ -0,0 +1,163 @@
+/**
+ * 协议层缓存参数（第三波 §1.3）：缓存兼容开关的端点推断、保留层级解析、亲和头。
+ *
+ * 推断只看最终请求的主机名（不看 provider id：`OPENAI_BASE_URL` 把 openai 指到中转时按中转处理）：
+ * - `sendPromptCacheKey`、`supportsLongCacheRetention`：只有官方端点（api.openai.com /
+ *   api.anthropic.com）缺省开；
+ * - `sendSessionAffinityHeaders`、`supportsExplicitPromptCacheMode`：缺省一律关（实测中转都接受
+ *   但未见命中提升，OpenRouter 未实测，见 docs/providers.md「缓存」）；
+ * - `cacheReporting`：`auto`。
+ * 显式 `model.compat`（registry 已把 provider.compat 合进来）逐字段覆盖推断。
+ *
+ * 400 自动剥离（`postWithCacheFallback`）：端点以 400 拒收并点名 prompt_cache_* / cache_control 时，
+ * 把 `${provider}/${model}` 记入进程级 `strippedCacheParams`，去掉这些字段在 `start` 之前重发一次，
+ * 并提示一次（实测：某中转的 Responses 对 DeepSeek 拒收 prompt_cache_retention / _options）。
+ */
+import { HttpError, postJson } from "../http.js";
+const DEFAULT_BASE_URLS = {
+    "anthropic-messages": "https://api.anthropic.com",
+    "openai-completions": "https://api.openai.com/v1",
+    "openai-responses": "https://api.openai.com/v1",
+};
+const OFFICIAL_HOSTS = new Set(["api.openai.com", "api.anthropic.com"]);
+const PROMPT_CACHE_KEYS = [
+    "sendPromptCacheKey",
+    "sendSessionAffinityHeaders",
+    "supportsLongCacheRetention",
+    "supportsExplicitPromptCacheMode",
+    "cacheReporting",
+];
+/** 请求实际发往的主机名（小写）；baseUrl 不可解析时返回空串。 */
+export function endpointHost(model, api) {
+    const baseUrl = model.baseUrl ?? DEFAULT_BASE_URLS[api] ?? "";
+    try {
+        return new URL(baseUrl).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/** 解析后的缓存兼容开关：端点推断 ← `model.compat`。 */
+export function resolvePromptCacheCompat(model, api) {
+    const official = OFFICIAL_HOSTS.has(endpointHost(model, api));
+    const out = {
+        sendPromptCacheKey: official && api !== "anthropic-messages",
+        sendSessionAffinityHeaders: false,
+        supportsLongCacheRetention: official,
+        supportsExplicitPromptCacheMode: false,
+        cacheReporting: "auto",
+    };
+    for (const key of PROMPT_CACHE_KEYS) {
+        const value = model.compat?.[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+const RETENTIONS = ["none", "short", "long"];
+/**
+ * 本次请求的保留层级：显式 `options.cacheRetention` 优先；否则 `AMA_CACHE_RETENTION`
+ * （none | short | long，非法值忽略）；都没有 → short。
+ */
+export function resolveCacheRetention(retention, env = process.env) {
+    if (retention !== undefined)
+        return retention;
+    const fromEnv = env["AMA_CACHE_RETENTION"]?.trim().toLowerCase();
+    return RETENTIONS.find((value) => value === fromEnv) ?? "short";
+}
+/** `long` 在不支持长保留的端点上降为 `short`。 */
+export function effectiveRetention(retention, compat) {
+    return retention === "long" && !compat.supportsLongCacheRetention ? "short" : retention;
+}
+/**
+ * 会话亲和头（`sendSessionAffinityHeaders`）：OpenRouter 用 `x-session-id`，其余
+ * `x-session-affinity` + 每请求一个 `x-client-request-id`。无 sessionId 或 retention 为 none 时不发。
+ */
+export function affinityHeaders(model, api, sessionId, retention, newId = () => crypto.randomUUID()) {
+    if (!sessionId || retention === "none")
+        return {};
+    if (!resolvePromptCacheCompat(model, api).sendSessionAffinityHeaders)
+        return {};
+    if (endpointHost(model, api).endsWith("openrouter.ai"))
+        return { "x-session-id": sessionId };
+    return { "x-session-affinity": sessionId, "x-client-request-id": newId() };
+}
+const CACHE_PARAM_PATTERN = /prompt_cache_key|prompt_cache_retention|prompt_cache_options|cache_control/i;
+const TOP_LEVEL_PARAMS = ["prompt_cache_key", "prompt_cache_retention", "prompt_cache_options"];
+/** 工具 schema 与调用参数原样保留（里面的同名属性是用户数据，不是缓存参数）。 */
+const SCHEMA_KEYS = new Set(["parameters", "input_schema", "input", "arguments"]);
+/** 遇到过拒收的 `${provider}/${model}`：进程内之后的请求直接不带缓存参数。 */
+export const strippedCacheParams = new Set();
+const SUGGESTION = {
+    prompt_cache_key: "compat.sendPromptCacheKey: false",
+    prompt_cache_retention: "compat.supportsLongCacheRetention: false",
+    prompt_cache_options: "compat.supportsExplicitPromptCacheMode: false",
+    cache_control: 'compat.cacheControlFormat: "none"',
+};
+let warn = (message) => {
+    if ((process.env["AMA_LOG"] ?? "warn") !== "error")
+        process.stderr.write(`ama: [warn] ${message}\n`);
+};
+/** 替换剥离提示的输出（宿主 / 测试用）；返回原来的函数。 */
+export function setCacheParamWarn(next) {
+    const previous = warn;
+    warn = next;
+    return previous;
+}
+/** HTTP 400 且错误体点名了缓存参数 → 返回被拒字段名（小写）；否则 undefined。 */
+export function isCacheParamRejection(error) {
+    if (!(error instanceof HttpError) || error.status !== 400)
+        return undefined;
+    return CACHE_PARAM_PATTERN.exec(`${error.body}\n${error.message}`)?.[0].toLowerCase();
+}
+function stripInto(value, removed) {
+    if (Array.isArray(value))
+        return value.map((item) => stripInto(item, removed));
+    if (typeof value !== "object" || value === null)
+        return value;
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+        if (key === "cache_control")
+            removed.count++;
+        else
+            out[key] = SCHEMA_KEYS.has(key) ? inner : stripInto(inner, removed);
+    }
+    return out;
+}
+function stripWithCount(body) {
+    const removed = { count: 0 };
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return { body, removed: 0 };
+    const out = stripInto(body, removed);
+    for (const key of TOP_LEVEL_PARAMS) {
+        if (key in out) {
+            delete out[key];
+            removed.count++;
+        }
+    }
+    return { body: out, removed: removed.count };
+}
+/** 去掉顶层 prompt_cache_* 与任意层级的 cache_control（返回新对象，不改入参）。 */
+export function stripCacheParams(body) {
+    return stripWithCount(body).body;
+}
+/**
+ * `postJson` 加缓存参数兜底：已记入 `strippedCacheParams` 的模型直接剥离后发；否则照发，
+ * 遇到点名缓存参数的 400 且请求里确有可剥离字段 → 记入集合、提示一次、剥离后重发一次。
+ */
+export async function postWithCacheFallback(model, url, options) {
+    const key = `${model.provider}/${model.id}`;
+    const body = strippedCacheParams.has(key) ? stripWithCount(options.body).body : options.body;
+    try {
+        return await postJson(url, { ...options, body });
+    }
+    catch (error) {
+        const field = isCacheParamRejection(error);
+        const stripped = field && !options.signal.aborted ? stripWithCount(body) : undefined;
+        if (!field || !stripped || stripped.removed === 0)
+            throw error;
+        strippedCacheParams.add(key);
+        warn(`${key}：该端点不支持 ${field}，已自动去掉缓存参数重发；可在 config 里设 ${SUGGESTION[field] ?? "相应的 compat 开关"}`);
+        return postJson(url, { ...options, body: stripped.body });
+    }
+}

package/dist/ai/apis/google-generative-ai.d.ts

@@ -0,0 +1,32 @@
+/**
+ * google-generative-ai 协议（设计 §3.1）：POST `{baseUrl}/models/{id}:streamGenerateContent?alt=sse`，
+ * 每个 `data:` 是一个完整的 GenerateContentResponse（没有 `[DONE]`）。
+ *
+ * - `candidates[0].content.parts`：`text`（`thought: true` 为思考）→ 文本 / 思考块，相邻同类 part
+ *   并入同一块；`functionCall` 整块到达 → toolcall_start / delta（整段 JSON）/ end；
+ * - `thoughtSignature` 可挂在任何 part 上：思考 → `thinkingSignature`，文本 → `textSignature`，
+ *   工具调用 → `thoughtSignature`；同一块后到的空签名不覆盖先到的（签名常在末尾的空文本 part 上）；
+ * - 工具调用缺 id（Gemini 2.5 起常见）时按 responseId + 内容下标生成确定的 id；
+ * - `finishReason`：STOP → stop（有工具调用则 toolUse）、MAX_TOKENS → length，其余（SAFETY、
+ *   RECITATION、MALFORMED_FUNCTION_CALL…）→ error；`promptFeedback.blockReason` → error；
+ *   流里没出现过 finishReason → 断流错误；
+ * - `usageMetadata`（每块累计，取最后一次）：input = promptTokenCount − cachedContentTokenCount，
+ *   output = candidatesTokenCount + thoughtsTokenCount（思考按输出计费），reasoning = thoughts；
+ *   cachedContentTokenCount 出现（含 0）即 `cacheReported: true`（隐式缓存未命中时常常不给该字段）；
+ * - 错误体 `{error:{code,status,message}}` 重排为 `429 RESOURCE_EXHAUSTED: …`。
+ */
+import type { ApiImplementation, GoogleCompat, Model, Usage } from "../types.js";
+type Json = Record<string, unknown>;
+export declare function parseGoogleUsage(raw: Json): Usage;
+type MappedFinish = {
+    reason: "stop" | "length" | "toolUse";
+} | {
+    reason: "error";
+    message: string;
+};
+export declare function mapGoogleFinishReason(raw: string): MappedFinish;
+/** Google 错误体 `{error:{code,status,message}}` → `status: message`；其它形状返回 undefined。 */
+export declare function describeGoogleError(value: unknown): string | undefined;
+export declare function googleStreamUrl(model: Model): string;
+export declare const googleGenerativeAiApi: ApiImplementation<GoogleCompat>;
+export {};