@armadra/agent 0.3.0 → 0.5.0

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

@@ -12,7 +12,7 @@
  * 任一出现过（含 0）即 `cacheReported: true`，之后的事件不会把它改回 false。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { USER_AGENT, authHeaders, describeErrorJson, mergeHeaders } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { postWithCacheFallback } from "./cache-params.js";
 import { ANTHROPIC_VERSION, anthropicMessagesUrl, buildAnthropicRequest, detectAnthropicCompat, } from "./anthropic-request.js";
@@ -168,11 +168,12 @@ async function run(stream, model, context, options) {
             body,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
         });
         stream.push({ type: "start", partial: tracker.output });
         const state = { blocks: new Map(), stop: undefined, sawMessageStop: false };
-        for await (const sse of readSseEvents(response.body, options.signal)) {
+        for await (const sse of readSseEvents(response.body, options.signal, idleTimeoutOf(options))) {
             if (sse.event === "ping" || sse.data === "")
                 continue;
             let data;

package/dist/ai/apis/anthropic-request.d.ts

@@ -1,22 +1,24 @@
 /**
  * anthropic-messages 请求体（设计 §3.1、§3.3、§3.6）：消息转换、三断点缓存、thinking、工具。
  *
- * 缓存断点（cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
+ * compat 按主机推断见 anthropic-compat.ts（[W5-M2]）。
+ *
+ * 缓存断点（`sendCacheControl` 关时不打；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:"enabled", budget_tokens}`，预算计入 max_tokens（有工具时带交错思考 beta 头，
+ * `sendInterleavedThinkingBeta` 关时不带）；off 发
  * `{type:"disabled"}`（映射表 off 为 null 的模型不发）。思考开启时不发 temperature，
  * 除非 `supportsTemperatureWithThinking`。`toolChoice: "none"`（有工具时）→ `tool_choice:{type:"none"}`。
  */
-import type { AnthropicMessagesCompat, AssistantMessage, Model, ModelThinkingLevel, ProviderData, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
+import type { AssistantMessage, Model, ModelThinkingLevel, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
 export declare const ANTHROPIC_VERSION = "2023-06-01";
 export declare const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
-export declare const DEFAULT_ANTHROPIC_COMPAT: Readonly<AnthropicMessagesCompat>;
-export declare function detectAnthropicCompat(model: Model, provider?: ProviderData): AnthropicMessagesCompat;
+export { DEFAULT_ANTHROPIC_COMPAT, detectAnthropicCompat } from "./anthropic-compat.js";
 type Json = Record<string, unknown>;
 export interface AnthropicRequest {
     body: Json;
@@ -39,4 +41,3 @@ export declare function anthropicMessagesUrl(baseUrl: string): string;
 export declare function normalizeToolId(id: string): string;
 export declare function convertMessages(messages: readonly (UserMessage | AssistantMessage | ToolResultMessage)[]): Json[];
 export declare function buildAnthropicRequest(model: Model, context: TranscriptContext, options: StreamOptions): AnthropicRequest;
-export {};

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

@@ -1,46 +1,27 @@
 /**
  * anthropic-messages 请求体（设计 §3.1、§3.3、§3.6）：消息转换、三断点缓存、thinking、工具。
  *
- * 缓存断点（cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
+ * compat 按主机推断见 anthropic-compat.ts（[W5-M2]）。
+ *
+ * 缓存断点（`sendCacheControl` 关时不打；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:"enabled", budget_tokens}`，预算计入 max_tokens（有工具时带交错思考 beta 头，
+ * `sendInterleavedThinkingBeta` 关时不带）；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 { detectAnthropicCompat } from "./anthropic-compat.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 { DEFAULT_ANTHROPIC_COMPAT, detectAnthropicCompat } from "./anthropic-compat.js";
 export function cacheControlFor(retention) {
     if (retention === "none")
         return undefined;
@@ -227,7 +208,7 @@ function applyThinking(body, model, compat, level, requestedMax, hasTools, betas
     if (plan.budget < 1024)
         return undefined; // 回答上限太小，放弃思考
     body["thinking"] = { type: "enabled", budget_tokens: plan.budget, display: "summarized" };
-    if (hasTools)
+    if (hasTools && compat.sendInterleavedThinkingBeta !== false)
         betas.push(INTERLEAVED_THINKING_BETA);
     return String(plan.budget);
 }
@@ -236,7 +217,8 @@ export function buildAnthropicRequest(model, context, options) {
     const normalized = normalizeContext(context, { model });
     const cacheCompat = resolvePromptCacheCompat(model, "anthropic-messages");
     const retention = effectiveRetention(resolveCacheRetention(options.cacheRetention), cacheCompat);
-    const cacheControl = cacheControlFor(retention);
+    // sendCacheControl:false（端点忽略 cache_control，如 DeepSeek）：不打断点
+    const cacheControl = compat.sendCacheControl === false ? undefined : cacheControlFor(retention);
     const messages = convertMessages(normalized.messages);
     const level = clampThinkingLevel(model, options.thinkingLevel ?? "off");
     const betas = [];

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

@@ -2,8 +2,8 @@
  * 协议层缓存参数（第三波 §1.3）：缓存兼容开关的端点推断、保留层级解析、亲和头。
  *
  * 推断只看最终请求的主机名（不看 provider id：`OPENAI_BASE_URL` 把 openai 指到中转时按中转处理）：
- * - `sendPromptCacheKey`、`supportsLongCacheRetention`：只有官方端点（api.openai.com /
- *   api.anthropic.com）缺省开；
+ * - `sendPromptCacheKey`、`supportsLongCacheRetention`：按 `HOST_CACHE_CAPABILITIES`（[W5-M2]，官方
+ *   文档写明支持的主机才开；其余主机——含全部中转——缺省关）。`sendPromptCacheKey` 只对 OpenAI 两条线有意义；
  * - `sendSessionAffinityHeaders`、`supportsExplicitPromptCacheMode`：缺省一律关（实测中转都接受
  *   但未见命中提升，OpenRouter 未实测，见 docs/providers.md「缓存」）；
  * - `cacheReporting`：`auto`。
@@ -15,6 +15,15 @@
  */
 import { type PostOptions } from "../http.js";
 import type { Api, CacheRetention, Model, PromptCacheCompat } from "../types.js";
+/**
+ * 按主机的缓存能力（精确主机名；docs/research/R1-models-protocols.md §2.1 的官方文档为据）：
+ * - OpenAI：`prompt_cache_key` 路由 + `prompt_cache_retention: "24h"`；
+ * - Anthropic：`ttl: "1h"`；
+ * - xAI、Mistral、Kimi：官方推荐 `prompt_cache_key`（Kimi 的 `prompt_cache_options.ttl` 形状不同，不开）；
+ * - 腾讯 TokenHub：Anthropic 线 `cache_control` 支持 `ttl: "1h"`，OpenAI 线自动缓存 + `prompt_cache_key`。
+ * 通义 Messages 只有 5m（不开长保留）；Groq 的 Responses 不认 `prompt_cache_key`（不开）。
+ */
+export declare const HOST_CACHE_CAPABILITIES: Readonly<Record<string, Partial<Pick<PromptCacheCompat, "sendPromptCacheKey" | "supportsLongCacheRetention">>>>;
 /** 请求实际发往的主机名（小写）；baseUrl 不可解析时返回空串。 */
 export declare function endpointHost(model: Pick<Model, "baseUrl">, api: Api): string;
 /** 解析后的缓存兼容开关：端点推断 ← `model.compat`。 */

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

@@ -2,8 +2,8 @@
  * 协议层缓存参数（第三波 §1.3）：缓存兼容开关的端点推断、保留层级解析、亲和头。
  *
  * 推断只看最终请求的主机名（不看 provider id：`OPENAI_BASE_URL` 把 openai 指到中转时按中转处理）：
- * - `sendPromptCacheKey`、`supportsLongCacheRetention`：只有官方端点（api.openai.com /
- *   api.anthropic.com）缺省开；
+ * - `sendPromptCacheKey`、`supportsLongCacheRetention`：按 `HOST_CACHE_CAPABILITIES`（[W5-M2]，官方
+ *   文档写明支持的主机才开；其余主机——含全部中转——缺省关）。`sendPromptCacheKey` 只对 OpenAI 两条线有意义；
  * - `sendSessionAffinityHeaders`、`supportsExplicitPromptCacheMode`：缺省一律关（实测中转都接受
  *   但未见命中提升，OpenRouter 未实测，见 docs/providers.md「缓存」）；
  * - `cacheReporting`：`auto`。
@@ -19,7 +19,23 @@ const DEFAULT_BASE_URLS = {
     "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"]);
+/**
+ * 按主机的缓存能力（精确主机名；docs/research/R1-models-protocols.md §2.1 的官方文档为据）：
+ * - OpenAI：`prompt_cache_key` 路由 + `prompt_cache_retention: "24h"`；
+ * - Anthropic：`ttl: "1h"`；
+ * - xAI、Mistral、Kimi：官方推荐 `prompt_cache_key`（Kimi 的 `prompt_cache_options.ttl` 形状不同，不开）；
+ * - 腾讯 TokenHub：Anthropic 线 `cache_control` 支持 `ttl: "1h"`，OpenAI 线自动缓存 + `prompt_cache_key`。
+ * 通义 Messages 只有 5m（不开长保留）；Groq 的 Responses 不认 `prompt_cache_key`（不开）。
+ */
+export const HOST_CACHE_CAPABILITIES = {
+    "api.openai.com": { sendPromptCacheKey: true, supportsLongCacheRetention: true },
+    "api.anthropic.com": { supportsLongCacheRetention: true },
+    "api.x.ai": { sendPromptCacheKey: true },
+    "api.mistral.ai": { sendPromptCacheKey: true },
+    "api.moonshot.cn": { sendPromptCacheKey: true },
+    "api.moonshot.ai": { sendPromptCacheKey: true },
+    "tokenhub.tencentmaas.com": { sendPromptCacheKey: true, supportsLongCacheRetention: true },
+};
 const PROMPT_CACHE_KEYS = [
     "sendPromptCacheKey",
     "sendSessionAffinityHeaders",
@@ -39,11 +55,14 @@ export function endpointHost(model, api) {
 }
 /** 解析后的缓存兼容开关：端点推断 ← `model.compat`。 */
 export function resolvePromptCacheCompat(model, api) {
-    const official = OFFICIAL_HOSTS.has(endpointHost(model, api));
+    const name = endpointHost(model, api);
+    const host = Object.hasOwn(HOST_CACHE_CAPABILITIES, name)
+        ? HOST_CACHE_CAPABILITIES[name]
+        : undefined;
     const out = {
-        sendPromptCacheKey: official && api !== "anthropic-messages",
+        sendPromptCacheKey: host?.sendPromptCacheKey === true && api !== "anthropic-messages",
         sendSessionAffinityHeaders: false,
-        supportsLongCacheRetention: official,
+        supportsLongCacheRetention: host?.supportsLongCacheRetention === true,
         supportsExplicitPromptCacheMode: false,
         cacheReporting: "auto",
     };

package/dist/ai/apis/google-generative-ai.js

@@ -16,7 +16,7 @@
  * - 错误体 `{error:{code,status,message}}` 重排为 `429 RESOURCE_EXHAUSTED: …`。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { HttpError, USER_AGENT, authHeaders, joinUrl, mergeHeaders, postJson } from "../http.js";
+import { authHeaders, HttpError, idleTimeoutOf, joinUrl, mergeHeaders, postJson, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { GOOGLE_BASE_URL, buildGoogleRequest, detectGoogleCompat } from "./google-request.js";
 import { BlockTracker, ProviderStopError, STREAM_ENDED_MESSAGE, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
@@ -196,6 +196,7 @@ async function run(stream, model, context, options) {
                 body: replaced === undefined ? request.body : replaced,
                 signal: options.signal,
                 timeoutMs: options.timeoutMs,
+                idleTimeoutMs: idleTimeoutOf(options),
                 onResponse: options.onResponse,
             });
         }
@@ -209,7 +210,7 @@ async function run(stream, model, context, options) {
             idSeed: Date.now().toString(36),
         };
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal)) {
+        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
             const data = sse.data.trim();
             if (data === "" || data === "[DONE]")
                 continue;

package/dist/ai/apis/openai-compat.d.ts

@@ -19,7 +19,10 @@ interface InferenceRule {
     baseUrl: string;
     patch: (modelId: string) => Patch;
 }
-/** 推断表：13 家内置里走 OpenAI 兼容线的 11 家（anthropic / google 不走本协议）。 */
+/**
+ * 推断表：内置里有 OpenAI 兼容线（Chat 渠道或单渠道回落）的各家（anthropic / google 不走本协议）。
+ * [W5-M2] 新增四家暂无已验证的差异，按保守缺省（空补丁）登记。
+ */
 export declare const INFERENCE_RULES: readonly InferenceRule[];
 /** 命中的推断规则（先 provider id，后 baseUrl 子串）。 */
 export declare function findInferenceRule(providerId: string, baseUrl: string): InferenceRule | undefined;

package/dist/ai/apis/openai-compat.js

@@ -39,7 +39,10 @@ export const CONSERVATIVE_COMPAT = {
     supportsStrictTools: false,
     supportsStore: false,
 };
-/** 推断表：13 家内置里走 OpenAI 兼容线的 11 家（anthropic / google 不走本协议）。 */
+/**
+ * 推断表：内置里有 OpenAI 兼容线（Chat 渠道或单渠道回落）的各家（anthropic / google 不走本协议）。
+ * [W5-M2] 新增四家暂无已验证的差异，按保守缺省（空补丁）登记。
+ */
 export const INFERENCE_RULES = [
     {
         provider: "openai",
@@ -102,6 +105,10 @@ export const INFERENCE_RULES = [
         baseUrl: "mistral.ai",
         patch: () => ({ thinkingFormat: "none", requiresToolResultName: true }),
     },
+    { provider: "minimax", baseUrl: "minimax", patch: () => ({}) },
+    { provider: "stepfun", baseUrl: "stepfun", patch: () => ({}) },
+    { provider: "volcengine", baseUrl: "volces.com", patch: () => ({}) },
+    { provider: "tencent", baseUrl: "tencentmaas.com", patch: () => ({}) },
     { provider: "ollama", baseUrl: ":11434", patch: () => ({}) },
     { provider: "lmstudio", baseUrl: ":1234", patch: () => ({}) },
 ];

package/dist/ai/apis/openai-completions.js

@@ -14,7 +14,7 @@
  *   内容推断。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { USER_AGENT, authHeaders, describeErrorJson, joinUrl, mergeHeaders } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
 import { detectCompat } from "./openai-compat.js";
@@ -190,6 +190,7 @@ async function run(stream, model, context, options) {
             body: replaced === undefined ? request.body : replaced,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
         });
         stream.push({ type: "start", partial: tracker.output });
@@ -203,7 +204,7 @@ async function run(stream, model, context, options) {
             sawDone: false,
         };
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal)) {
+        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
             const data = sse.data.trim();
             if (data === "")
                 continue;

package/dist/ai/apis/openai-responses.js

@@ -15,7 +15,7 @@
  *   `cacheReported: true`。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { USER_AGENT, authHeaders, describeErrorJson, joinUrl, mergeHeaders } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
 import { buildResponsesRequest, detectResponsesCompat, encodeMessageSignature, } from "./openai-responses-request.js";
@@ -249,6 +249,7 @@ async function run(stream, model, context, options) {
             body: replaced === undefined ? request.body : replaced,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
         });
         stream.push({ type: "start", partial: tracker.output });
@@ -260,7 +261,7 @@ async function run(stream, model, context, options) {
         };
         let finished = false;
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal)) {
+        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
             const raw = sse.data.trim();
             if (raw === "" || raw === "[DONE]")
                 continue;

package/dist/ai/http.d.ts

@@ -1,9 +1,13 @@
 /**
  * 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 原样透传给运行时处理。
+ * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。CLI 启动时由 cli/proxy.ts 调 Node 内置的
+ * `http.setGlobalProxyFromEnv()`（等价于 `NODE_USE_ENV_PROXY=1`）；SDK 嵌入方自行决定。
+ * 本模块不自行实现代理。
+ *
+ * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）既管等响应头，
+ * 也管流式读取期间两次收到数据之间的间隔（每收到一块字节即重新计时，见 sse.ts）。空闲超时抛
+ * `IdleTimeoutError`，文案含 `idle timeout`，会话层按可重试错误处理。
  *
  * 协议层自身**不重试**（重试在会话层，§3.6）。
  */
@@ -29,6 +33,21 @@ export declare class HttpError extends Error {
 export declare class RequestTimeoutError extends Error {
     constructor(timeoutMs: number);
 }
+/** 流空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 300000;
+/** 请求选项里的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+export declare function idleTimeoutOf(options: {
+    idleTimeoutMs?: number | undefined;
+}): number | undefined;
+/**
+ * 服务端在 `idleTimeoutMs` 内没有任何字节：`response` = 发出请求后迟迟没有响应头，
+ * `stream` = 流读到一半停住。文案含 `idle timeout`（重试分类据此判为可重试）。
+ */
+export declare class IdleTimeoutError extends Error {
+    readonly idleTimeoutMs: number;
+    readonly phase: "response" | "stream";
+    constructor(idleTimeoutMs: number, phase: "response" | "stream");
+}
 /**
  * 从错误体提取文本：识别 `{error:{type,message,code}}`、`{error:"..."}`、`{message}`、
  * `{detail}` 等常见形状；不是 JSON 则截断原文。结果形如 `429 rate_limit_error: ...`。
@@ -41,12 +60,15 @@ export interface PostOptions {
     body: unknown;
     signal: AbortSignal;
     timeoutMs?: number | undefined;
+    /** 等响应头的空闲上限（`timeoutMs` 未给时生效）；undefined 不限。 */
+    idleTimeoutMs?: number | undefined;
     onResponse?: ((status: number, headers: Headers) => void) | undefined;
 }
 /**
- * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError；
- * 调用方的 signal 中止 → 原样抛 AbortError（调用方据 signal.aborted 判 aborted）。
- * 超时只覆盖到拿到响应头为止，流式读取期间由调用方的 signal 控制。
+ * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError
+ * （`timeoutMs`）或 IdleTimeoutError（`idleTimeoutMs`）；调用方的 signal 中止 → 原样抛 AbortError
+ * （调用方据 signal.aborted 判 aborted）。超时只覆盖到拿到响应头为止，流式读取期间的空闲由
+ * `readSseEvents` 的 `idleTimeoutMs` 控制。
  */
 export declare function postJson(url: string, options: PostOptions): Promise<Response>;
 /** undici 的 `fetch failed` 把真正原因藏在 cause 里；拼出来便于重试分类与排错。 */

package/dist/ai/http.js

@@ -1,9 +1,13 @@
 /**
  * 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 原样透传给运行时处理。
+ * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。CLI 启动时由 cli/proxy.ts 调 Node 内置的
+ * `http.setGlobalProxyFromEnv()`（等价于 `NODE_USE_ENV_PROXY=1`）；SDK 嵌入方自行决定。
+ * 本模块不自行实现代理。
+ *
+ * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）既管等响应头，
+ * 也管流式读取期间两次收到数据之间的间隔（每收到一块字节即重新计时，见 sse.ts）。空闲超时抛
+ * `IdleTimeoutError`，文案含 `idle timeout`，会话层按可重试错误处理。
  *
  * 协议层自身**不重试**（重试在会话层，§3.6）。
  */
@@ -76,6 +80,33 @@ export class RequestTimeoutError extends Error {
         this.name = "RequestTimeoutError";
     }
 }
+/** 流空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
+export const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+/** 请求选项里的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+export function idleTimeoutOf(options) {
+    const value = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function formatDuration(ms) {
+    return ms >= 1000 && ms % 1000 === 0 ? `${ms / 1000} s` : `${ms} ms`;
+}
+/**
+ * 服务端在 `idleTimeoutMs` 内没有任何字节：`response` = 发出请求后迟迟没有响应头，
+ * `stream` = 流读到一半停住。文案含 `idle timeout`（重试分类据此判为可重试）。
+ */
+export class IdleTimeoutError extends Error {
+    idleTimeoutMs;
+    phase;
+    constructor(idleTimeoutMs, phase) {
+        const what = phase === "response"
+            ? `No response from the server within ${formatDuration(idleTimeoutMs)}`
+            : `Stream stalled: no data from the server for ${formatDuration(idleTimeoutMs)}`;
+        super(`${what} (idle timeout; adjust with request.idleTimeoutMs or AMA_IDLE_TIMEOUT_MS)`);
+        this.name = "IdleTimeoutError";
+        this.idleTimeoutMs = idleTimeoutMs;
+        this.phase = phase;
+    }
+}
 const MAX_ERROR_BODY = 4000;
 /**
  * 从错误体提取文本：识别 `{error:{type,message,code}}`、`{error:"..."}`、`{message}`、
@@ -141,12 +172,14 @@ function parseRetryAfter(headers) {
     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 控制。
+ * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError
+ * （`timeoutMs`）或 IdleTimeoutError（`idleTimeoutMs`）；调用方的 signal 中止 → 原样抛 AbortError
+ * （调用方据 signal.aborted 判 aborted）。超时只覆盖到拿到响应头为止，流式读取期间的空闲由
+ * `readSseEvents` 的 `idleTimeoutMs` 控制。
  */
 export async function postJson(url, options) {
-    const timeout = options.timeoutMs;
+    const explicit = options.timeoutMs !== undefined && options.timeoutMs > 0;
+    const timeout = explicit ? options.timeoutMs : options.idleTimeoutMs;
     const timer = new AbortController();
     const handle = timeout !== undefined && timeout > 0 ? setTimeout(() => timer.abort(), timeout) : undefined;
     const signal = AbortSignal.any([options.signal, timer.signal]);
@@ -161,7 +194,7 @@ export async function postJson(url, options) {
     }
     catch (error) {
         if (timer.signal.aborted && !options.signal.aborted && timeout !== undefined) {
-            throw new RequestTimeoutError(timeout);
+            throw explicit ? new RequestTimeoutError(timeout) : new IdleTimeoutError(timeout, "response");
         }
         throw normalizeNetworkError(error);
     }

package/dist/ai/image-limits.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 图片大小上限（docs/wave5-plan.md §4、D11；R1 §3.2）。[W5-I]
+ *
+ * 各家的上限都按 **base64 后**的字节数计算：`base64Bytes = ceil(bytes / 3) * 4`。
+ *
+ * | 端点                                   | 单图     | 单请求总量（按协议）            |
+ * | -------------------------------------- | -------- | ------------------------------- |
+ * | 官方 Anthropic（api.anthropic.com）    | 10 MB    | anthropic-messages 32 MB        |
+ * | 官方 Gemini（generativelanguage…）     | 20 MB    | google-generative-ai 20 MB      |
+ * | 官方 OpenAI（api.openai.com）          | 20 MB    | 其它协议 20 MB                  |
+ * | 中转（内置供应商改了 baseUrl）/ 未知   | 5 MB     | 同上，按协议                    |
+ *
+ * 中转背后常是 Bedrock / Vertex（单图 5 MB），所以只认官方主机，其余一律按 5 MB。
+ * 尺寸：任一边 > 8000 px 拒绝；单请求超过 20 张图时每边 ≤ 2000 px（Anthropic）。
+ */
+import type { Api } from "./types.js";
+export declare const MB: number;
+/** 单图任一边上限（像素）。 */
+export declare const MAX_IMAGE_EDGE = 8000;
+/** 单请求图片数超过这个数时，每张图的边长上限收紧为 `MANY_IMAGES_EDGE`。 */
+export declare const MANY_IMAGES_COUNT = 20;
+export declare const MANY_IMAGES_EDGE = 2000;
+/** 未知端点 / 中转的单图上限（base64 后）。 */
+export declare const DEFAULT_IMAGE_BASE64_LIMIT: number;
+export interface ImageLimits {
+    /** 单张图片 base64 后的上限（字节）。 */
+    perImageBase64: number;
+    /** 单次请求全部图片 base64 后的总量预算（字节）。 */
+    perRequestBase64: number;
+}
+export type ImageEndpoint = "anthropic" | "gemini" | "openai" | "other";
+/** 判断端点只需要地址与协议。 */
+export interface ImageModelInfo {
+    baseUrl?: string | undefined;
+    api: Api;
+}
+/** 原始字节数 → base64 后的字节数。 */
+export declare function base64Size(bytes: number): number;
+/** 按 baseUrl 的主机判断是不是官方端点；中转与未知主机都是 `other`。 */
+export declare function imageEndpoint(model: Pick<ImageModelInfo, "baseUrl">): ImageEndpoint;
+/** 单请求图片总量预算按协议：Anthropic 32 MB，其余（含 Gemini）20 MB。 */
+export declare function requestImageBudget(api: Api): number;
+export declare function imageLimits(model: ImageModelInfo, api?: Api): ImageLimits;
+/** 文案用：`10 MB`、`3.8 MB`。 */
+export declare function formatMb(bytes: number): string;

package/dist/ai/image-limits.js

@@ -0,0 +1,68 @@
+/**
+ * 图片大小上限（docs/wave5-plan.md §4、D11；R1 §3.2）。[W5-I]
+ *
+ * 各家的上限都按 **base64 后**的字节数计算：`base64Bytes = ceil(bytes / 3) * 4`。
+ *
+ * | 端点                                   | 单图     | 单请求总量（按协议）            |
+ * | -------------------------------------- | -------- | ------------------------------- |
+ * | 官方 Anthropic（api.anthropic.com）    | 10 MB    | anthropic-messages 32 MB        |
+ * | 官方 Gemini（generativelanguage…）     | 20 MB    | google-generative-ai 20 MB      |
+ * | 官方 OpenAI（api.openai.com）          | 20 MB    | 其它协议 20 MB                  |
+ * | 中转（内置供应商改了 baseUrl）/ 未知   | 5 MB     | 同上，按协议                    |
+ *
+ * 中转背后常是 Bedrock / Vertex（单图 5 MB），所以只认官方主机，其余一律按 5 MB。
+ * 尺寸：任一边 > 8000 px 拒绝；单请求超过 20 张图时每边 ≤ 2000 px（Anthropic）。
+ */
+export const MB = 1024 * 1024;
+/** 单图任一边上限（像素）。 */
+export const MAX_IMAGE_EDGE = 8000;
+/** 单请求图片数超过这个数时，每张图的边长上限收紧为 `MANY_IMAGES_EDGE`。 */
+export const MANY_IMAGES_COUNT = 20;
+export const MANY_IMAGES_EDGE = 2000;
+/** 未知端点 / 中转的单图上限（base64 后）。 */
+export const DEFAULT_IMAGE_BASE64_LIMIT = 5 * MB;
+/** 原始字节数 → base64 后的字节数。 */
+export function base64Size(bytes) {
+    return Math.ceil(bytes / 3) * 4;
+}
+const OFFICIAL_HOSTS = {
+    "api.anthropic.com": "anthropic",
+    "generativelanguage.googleapis.com": "gemini",
+    "api.openai.com": "openai",
+};
+const PER_IMAGE = {
+    anthropic: 10 * MB,
+    gemini: 20 * MB,
+    openai: 20 * MB,
+    other: DEFAULT_IMAGE_BASE64_LIMIT,
+};
+function hostOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 按 baseUrl 的主机判断是不是官方端点；中转与未知主机都是 `other`。 */
+export function imageEndpoint(model) {
+    const host = hostOf(model.baseUrl);
+    return (host !== undefined ? OFFICIAL_HOSTS[host] : undefined) ?? "other";
+}
+/** 单请求图片总量预算按协议：Anthropic 32 MB，其余（含 Gemini）20 MB。 */
+export function requestImageBudget(api) {
+    return api === "anthropic-messages" ? 32 * MB : 20 * MB;
+}
+export function imageLimits(model, api = model.api) {
+    return {
+        perImageBase64: PER_IMAGE[imageEndpoint(model)],
+        perRequestBase64: requestImageBudget(api),
+    };
+}
+/** 文案用：`10 MB`、`3.8 MB`。 */
+export function formatMb(bytes) {
+    const mb = bytes / MB;
+    return `${Number.isInteger(mb) ? mb : mb.toFixed(1)} MB`;
+}

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

@@ -1,22 +1,34 @@
 /**
- * 13 家内置供应商（设计 §3.3）。这里只放供应商级数据；模型来自 catalog/*.json，compat 由
- * 各协议的 detectCompat 推断（openai-compat.ts 的推断表），这里只写推断不出来的东西。
+ * 内置供应商（设计 §3.3、docs/wave5-plan.md §3.2）。这里只放供应商级数据；模型来自 catalog/*.json，
+ * compat 由各协议的 detectCompat 推断（openai-compat.ts、anthropic-compat.ts 的主机表），这里只写推断
+ * 不出来的东西。
  *
- * 这里的 `api` 是供应商级缺省；目录条目可用 `api` 覆盖（openai 推理模型与 xai 目录模型走
- * openai-responses，见 catalog/*.json）。
+ * 内置渠道（[W5-M2]）：一家同时开放多种协议时写 `channels`（首个不一定是缺省，看 `defaultChannel`）。
+ * registry 物化时与用户 config 的 `channels` 合并（同名字段级覆盖、新名追加），用户的 `defaultChannel`
+ * 优先。供应商级 `api` + `baseUrl` 是**单渠道回落**：用户（config / auth.json / `*_BASE_URL`）把
+ * baseUrl 改到别处时内置渠道整体作废，按这一对单渠道处理（与引入内置渠道之前的行为一致）。
+ * 只做按量计费端点；Coding Plan 类订阅端点不做内置渠道（D9），见 docs/providers.md。
  *
  * `baseUrlEnv`（第三波 §2.3）：通行约定的 baseUrl 环境变量（OpenAI SDK 的 `OPENAI_BASE_URL`、
  * Claude Code 的 `ANTHROPIC_BASE_URL`），设了就把内置供应商指向中转站，零配置可用；优先级低于
  * config.json 与 auth.json 的 baseUrl。
  */
-import type { ProviderData } from "../types.js";
+import type { Api, ProviderData } from "../types.js";
 export type BuiltinProvider = Omit<ProviderData, "models" | "builtin"> & {
     baseUrlEnv?: string;
+    /**
+     * 单渠道回落时目录模型的协议（缺省同 `api`）：OpenAI / xAI 的目录模型在中转上仍走 Responses，
+     * 目录外的 id（本地服务、中转自有模型）走 `api`（Chat）。
+     */
+    catalogApi?: Api;
 };
 export declare const BUILTIN_PROVIDERS: readonly BuiltinProvider[];
+/** 内置供应商的官方主机（单渠道回落 + 全部内置渠道）。 */
+export declare function builtinHosts(providerId: string): Set<string>;
 /**
  * 内置供应商的 baseUrl 是否被改到了非官方主机（中转站）：此时目录外的 model id 也接受，
- * compat 走保守缺省。非内置供应商返回 false。
+ * compat 走保守缺省。按渠道比较主机：落在任一内置渠道的主机上（如国际站）不算中转。
+ * 非内置供应商与本地服务返回 false。
  */
 export declare function isRelayedBaseUrl(providerId: string, baseUrl: string): boolean;
 /** 自定义供应商的兜底环境变量名：`AMA_API_KEY_<ID>`（非字母数字转下划线、大写）。 */