@armadra/agent 0.3.0 → 0.5.0

package/dist/ai/providers/registry.js

@@ -19,8 +19,14 @@
  * 重新物化（协议、地址、headers、compat 取渠道的，模型级 api / baseUrl 仍覆盖）；渠道 key 经
  * `resolveApiKey(provider, channel)`。没有 `channels` 的供应商行为不变。
  *
+ * 内置渠道（[W5-M2]，builtin.ts）：用户 `channels` 同名字段级覆盖、新名追加，`defaultChannel` 用户优先
+ * （也可只写 `defaultChannel`，或只写 `api` 选同协议的内置渠道）；目录模型缺省挂全部渠道、缺省渠道在前。
+ * 用户（config / auth.json / `*_BASE_URL`）改了供应商级 baseUrl 而没写自己的 `channels` 时，内置渠道作废，
+ * 按单渠道回落（`api` 取用户写的或内置的回落协议）。
+ *
  * models.dev（enrich.ts）：config 里缺元数据的自定义模型与合成模型，用传入的索引（只读缓存）补
- * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录不补。
+ * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录按同一索引
+ * （快照 ⊕ `ama models refresh` 的覆盖）在 catalog.ts 合并，缺字段的条目退回内置快照。
  */
 import { ApiRegistry, createDefaultApiRegistry } from "../apis/api.js";
 import { fakeProviderData } from "../fake/fake-provider.js";
@@ -28,33 +34,10 @@ import { mergeHeaders } from "../http.js";
 import { ApiKeyResolver } from "./auth.js";
 import { BUILTIN_PROVIDERS, fallbackEnvKey, isRelayedBaseUrl } from "./builtin.js";
 import { applyModelOverride, loadBuiltinCatalog, toModel, withCustomDefaults } from "./catalog.js";
-import { channelKeyId, modelChannels, parseChannels, splitChannelRef } from "./channels.js";
+import { catalogChannels, channelKeyId, dropChannels, materializeModel, pickBuiltinChannel, modelChannels, parseChannels, splitChannelRef, } from "./channels.js";
 import { catalogMetadata, enrichEntry, lazyIndex, } from "./enrich.js";
-/**
- * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
- * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
- */
-export function materializeModel(model, provider, channel, explicit) {
-    const out = {
-        ...model,
-        provider: provider.id,
-        baseUrl: model.baseUrl ?? provider.baseUrl,
-    };
-    if (channel !== undefined) {
-        out.api = explicit?.api ?? channel.api;
-        out.baseUrl = explicit?.baseUrl ?? channel.baseUrl;
-        out.channel = channel.name;
-    }
-    if (provider.headers || channel?.headers || model.headers)
-        out.headers = mergeHeaders(provider.headers, channel?.headers, model.headers);
-    if (provider.compat || channel?.compat || model.compat)
-        out.compat = { ...provider.compat, ...channel?.compat, ...model.compat };
-    const authHeader = channel?.authHeader ?? provider.authHeader;
-    if (authHeader !== undefined)
-        out.authHeader = model.authHeader ?? authHeader;
-    out.requiresApiKey = provider.requiresApiKey;
-    return out;
-}
+import { closest } from "./suggest.js";
+export { materializeModel } from "./channels.js";
 function configKeysOf(config) {
     const keys = {};
     for (const [id, provider] of Object.entries(config?.providers ?? {})) {
@@ -74,6 +57,10 @@ export class ProviderRegistry {
     envBaseUrls = new Map();
     /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
     relayed = new Set();
+    /** config 里写了自己 `channels` 的供应商（内置渠道不因改 baseUrl 作废）。 */
+    userChannels = new Set();
+    /** config 里写了供应商级 `api` 的供应商（单渠道回落时目录模型跟它走）。 */
+    userApi = new Set();
     /** `provider/model` → 物化前的模型（多渠道供应商切换渠道时重新物化）。 */
     raw = new Map();
     /** `provider/model` → 元数据来源与 models.dev 匹配。 */
@@ -91,9 +78,9 @@ export class ProviderRegistry {
             configKeys: options.keys?.configKeys ?? configKeysOf(options.config),
             onWarning: (message) => this.warn(message),
         });
-        const catalog = loadBuiltinCatalog();
+        const catalog = this.loadCatalog();
         const env = options.keys?.useEnv === false ? {} : (options.keys?.env ?? process.env);
-        for (const { baseUrlEnv, ...base } of BUILTIN_PROVIDERS) {
+        for (const { baseUrlEnv, catalogApi: _catalogApi, ...base } of BUILTIN_PROVIDERS) {
             const models = (catalog.get(base.id) ?? []).map((entry) => {
                 const api = entry.api ?? base.api;
                 this.sources.set(`${base.id}/${entry.id}`, "builtin");
@@ -106,12 +93,12 @@ export class ProviderRegistry {
             const fromEnv = baseUrlEnv !== undefined ? env[baseUrlEnv]?.trim() : undefined;
             if (baseUrlEnv !== undefined && fromEnv)
                 this.envBaseUrls.set(base.id, baseUrlEnv);
-            this.providers.set(base.id, {
-                ...base,
-                ...(fromEnv ? { baseUrl: fromEnv } : {}),
-                models,
-                builtin: true,
-            });
+            const provider = { ...structuredClone(base), models, builtin: true };
+            if (fromEnv) {
+                provider.baseUrl = fromEnv;
+                dropChannels(provider);
+            }
+            this.providers.set(base.id, provider);
         }
         for (const [id, config] of Object.entries(options.config?.providers ?? {})) {
             this.applyConfig(id, config);
@@ -121,6 +108,8 @@ export class ProviderRegistry {
             if (baseUrl) {
                 provider.baseUrl = baseUrl;
                 this.envBaseUrls.delete(provider.id);
+                if (provider.builtin && !this.userChannels.has(provider.id))
+                    dropChannels(provider);
             }
             if (provider.builtin && isRelayedBaseUrl(provider.id, provider.baseUrl)) {
                 this.relayed.add(provider.id);
@@ -135,9 +124,52 @@ export class ProviderRegistry {
             this.providers.set(fake.id, fake);
         }
         for (const provider of this.providers.values()) {
+            if (provider.builtin)
+                this.settleBuiltinChannels(provider);
             provider.models = provider.models.map((model) => this.materialize(provider, model));
         }
     }
+    /** 内置目录（快照 ⊕ 用户刷新）；刷新数据出任何问题都退回内置快照，不让启动失败。 */
+    loadCatalog() {
+        try {
+            return loadBuiltinCatalog(this.modelsDev());
+        }
+        catch (error) {
+            this.warn(`models.dev refresh data ignored: ${error.message}`);
+            return loadBuiltinCatalog();
+        }
+    }
+    /**
+     * 内置供应商定渠道：供应商级 api / baseUrl 取缺省渠道的（discover 等单地址的用法看它）；用户没指定渠道的
+     * 模型挂全部渠道（缺省在前）。渠道已作废的去掉模型上残留的 `channels`。
+     */
+    settleBuiltinChannels(provider) {
+        const channels = provider.channels;
+        if (channels === undefined || channels.length === 0) {
+            // 单渠道回落：没有模型级协议的目录模型走 catalogApi（用户改了 api 时走用户的）
+            const builtin = BUILTIN_PROVIDERS.find((p) => p.id === provider.id);
+            const api = builtin === undefined || this.userApi.has(provider.id)
+                ? provider.api
+                : (builtin.catalogApi ?? builtin.api);
+            for (const model of provider.models) {
+                delete model.channels;
+                const key = `${provider.id}/${model.id}`;
+                if (this.sources.get(key) === "builtin" && this.raw.get(key)?.explicit.api === undefined)
+                    model.api = api;
+            }
+            return;
+        }
+        const first = channels.find((c) => c.name === provider.defaultChannel) ?? channels[0];
+        if (first === undefined)
+            return;
+        provider.defaultChannel = first.name;
+        provider.api = first.api;
+        provider.baseUrl = first.baseUrl;
+        for (const model of provider.models) {
+            if (this.sources.get(`${provider.id}/${model.id}`) === "builtin" || !model.channels)
+                model.channels = catalogChannels(model.channels, channels, first.name);
+        }
+    }
     warn(message) {
         this.warnings.push(message);
         this.onWarning?.(message);
@@ -159,7 +191,15 @@ export class ProviderRegistry {
     }
     applyConfig(id, config) {
         const existing = this.providers.get(id);
-        const parsed = config.channels !== undefined ? parseChannels(id, config) : undefined;
+        const builtinChannels = existing?.builtin ? existing.channels : undefined;
+        const parsed = config.channels !== undefined
+            ? parseChannels(id, config, builtinChannels && {
+                channels: builtinChannels,
+                defaultChannel: existing?.defaultChannel,
+            })
+            : undefined;
+        if (config.channels !== undefined)
+            this.userChannels.add(id);
         for (const warning of parsed?.warnings ?? [])
             this.warn(warning);
         const first = parsed?.channels.find((c) => c.name === parsed.defaultChannel);
@@ -179,12 +219,16 @@ export class ProviderRegistry {
         };
         if (config.name !== undefined)
             provider.name = config.name;
-        if (config.api !== undefined)
+        if (config.api !== undefined) {
             provider.api = config.api;
+            this.userApi.add(id);
+        }
         if (config.baseUrl !== undefined) {
             provider.baseUrl = config.baseUrl;
             this.envBaseUrls.delete(id);
         }
+        if (builtinChannels !== undefined && parsed === undefined)
+            pickBuiltinChannel(provider, config, (m) => this.warn(m));
         if (parsed !== undefined && first !== undefined) {
             // 有渠道时供应商级 api / baseUrl 取首选渠道的（discover 等单地址的用法看它）。
             provider.channels = parsed.channels;
@@ -214,7 +258,8 @@ export class ProviderRegistry {
             if (typeof entry.modelsDev === "string" && metadata.looked && metadata.match === undefined)
                 this.warn(`modelsDev "${entry.modelsDev}" for "${id}/${entry.id}" not found`);
             const model = withCustomDefaults(filled, id, entry.api ?? provider.api);
-            if (provider.channels !== undefined)
+            // 内置供应商上没写 channels 的模型：定渠道时挂全部渠道（settleBuiltinChannels）
+            if (provider.channels !== undefined && (entry.channels !== undefined || !provider.builtin))
                 model.channels = channelsOf(entry.channels, entry.id);
             const index = provider.models.findIndex((m) => m.id === entry.id);
             if (index >= 0)
@@ -262,11 +307,6 @@ export class ProviderRegistry {
                     if (fields[field] !== undefined)
                         meta.sources[field] = "config";
         }
-        if (provider.channels !== undefined) {
-            // 目录模型（给内置供应商加了渠道时）挂到首选渠道。
-            for (const model of provider.models)
-                model.channels ??= [provider.defaultChannel ?? ""];
-        }
         this.providers.set(id, provider);
     }
     /** baseUrl 来自哪个环境变量（未生效返回 undefined）。 */
@@ -326,36 +366,40 @@ export class ProviderRegistry {
         const channelData = provider.channels?.find((c) => c.name === (channel ?? model.channels?.[0]));
         return materializeModel(model, provider, channelData);
     }
-    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    /** 按渠道取模型：渠道不在模型的 channels 里 → channel_not_found，列出可用渠道。 */
     withChannel(provider, model, channel) {
         const available = model.channels ?? [];
-        if (!available.includes(channel)) {
+        if (!available.includes(channel) || !provider.channels?.some((c) => c.name === channel)) {
             return {
                 ok: false,
-                reason: "not_found",
-                candidates: available.map((c) => `${provider.id}/${model.id}@${c}`),
+                reason: "channel_not_found",
+                candidates: available.filter(Boolean).map((c) => `${provider.id}/${model.id}@${c}`),
             };
         }
         if (channel === model.channel)
             return { ok: true, model, provider };
         return { ok: true, model: this.materialize(provider, model, channel), provider };
     }
+    /**
+     * `provider/model`、`provider/model@渠道` 或裸模型 id。`@` 先按渠道解析（id 里本来就带 `@` 且已登记的
+     * 模型除外），中转供应商的「未登记即合成」不会把 `@渠道` 吞进模型 id。失败的 reason：供应商不存在 →
+     * provider_not_found（候选是编辑距离最近的供应商）；渠道不存在 → channel_not_found；模型不存在 →
+     * not_found（候选是最接近的模型）。
+     */
     findModel(ref) {
         const trimmed = ref.trim();
-        const direct = this.findPlain(trimmed);
-        if (direct.ok)
-            return direct;
         const split = splitChannelRef(trimmed);
         if (split === undefined)
-            return direct;
+            return this.findPlain(trimmed);
+        const exact = this.findPlain(trimmed, undefined, false);
+        if (exact.ok)
+            return exact;
         const base = this.findPlain(split.base, split.channel);
         if (!base.ok)
-            return base.reason === "ambiguous" ? base : direct;
-        if (!base.provider.channels?.some((c) => c.name === split.channel))
-            return direct;
+            return base;
         return this.withChannel(base.provider, base.model, split.channel);
     }
-    findPlain(trimmed, channel) {
+    findPlain(trimmed, channel, synthesize = true) {
         const slash = trimmed.indexOf("/");
         if (slash > 0) {
             const provider = this.providers.get(trimmed.slice(0, slash));
@@ -364,7 +408,8 @@ export class ProviderRegistry {
                 const model = provider.models.find((m) => m.id === id);
                 if (model)
                     return { ok: true, model, provider };
-                if ((provider.models.length === 0 || this.relayed.has(provider.id)) && id.length > 0) {
+                const relayed = provider.models.length === 0 || this.relayed.has(provider.id);
+                if (synthesize && relayed && id.length > 0) {
                     const synthesized = this.synthesize(provider, id);
                     if (channel !== undefined && provider.channels?.some((c) => c.name === channel))
                         synthesized.channels = [...new Set([...(synthesized.channels ?? []), channel])];
@@ -374,6 +419,14 @@ export class ProviderRegistry {
             }
         }
         const matches = this.listModels().filter((entry) => entry.model.id === trimmed);
+        if (matches.length === 0 && slash > 0) {
+            const ids = [...this.providers.keys()];
+            return {
+                ok: false,
+                reason: "provider_not_found",
+                candidates: closest(trimmed.slice(0, slash), ids),
+            };
+        }
         if (matches.length === 1 && matches[0]) {
             return { ok: true, model: matches[0].model, provider: matches[0].provider };
         }
@@ -390,16 +443,10 @@ export class ProviderRegistry {
             candidates: (configured.length > 0 ? configured : matches).map((entry) => `${entry.provider.id}/${entry.model.id}`),
         };
     }
+    /** 最接近的模型（包含关系优先，其次编辑距离），`provider/id` 形式。 */
     similar(id, providerId) {
-        const needle = id.toLowerCase();
-        return this.listModels()
-            .filter((entry) => providerId === undefined || entry.provider.id === providerId)
-            .filter((entry) => {
-            const candidate = entry.model.id.toLowerCase();
-            return needle.length > 0 && (candidate.includes(needle) || needle.includes(candidate));
-        })
-            .slice(0, 10)
-            .map((entry) => `${entry.provider.id}/${entry.model.id}`);
+        const entries = this.listModels().filter((entry) => providerId === undefined || entry.provider.id === providerId);
+        return closest(id, entries, 5, (entry) => entry.model.id).map((entry) => `${entry.provider.id}/${entry.model.id}`);
     }
     hasConfiguredKey(providerId) {
         const provider = this.providers.get(providerId);

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

@@ -0,0 +1,18 @@
+/**
+ * 模型 / 供应商 / 渠道写错时的候选与报错文案（W4-C）。
+ *
+ * 候选排序：包含关系（`sonnet` ⊂ `claude-sonnet-5`）优先，其次按编辑距离；距离超过
+ * `max(2, ⌈长度 / 3⌉)` 的不算接近。只比较 id 本身（不含 `provider/` 前缀），大小写不敏感。
+ */
+import type { ModelLookup } from "../types.js";
+/** Levenshtein 距离（插入 / 删除 / 替换各计 1）。 */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * 从 `candidates` 里挑与 `needle` 最接近的至多 `limit` 个。`key` 取参与比较的部分
+ * （缺省整串），返回原值。
+ */
+export declare function closest<T>(needle: string, candidates: readonly T[], limit?: number, key?: (item: T) => string): T[];
+/** 解析失败的一行说明（不含前缀标签）：`渠道不存在：x；该模型可用渠道：…` 等。 */
+export declare function describeLookupFailure(ref: string, failure: Extract<ModelLookup, {
+    ok: false;
+}>): string;

package/dist/ai/providers/suggest.js

@@ -0,0 +1,72 @@
+/**
+ * 模型 / 供应商 / 渠道写错时的候选与报错文案（W4-C）。
+ *
+ * 候选排序：包含关系（`sonnet` ⊂ `claude-sonnet-5`）优先，其次按编辑距离；距离超过
+ * `max(2, ⌈长度 / 3⌉)` 的不算接近。只比较 id 本身（不含 `provider/` 前缀），大小写不敏感。
+ */
+/** Levenshtein 距离（插入 / 删除 / 替换各计 1）。 */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min((prev[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * 从 `candidates` 里挑与 `needle` 最接近的至多 `limit` 个。`key` 取参与比较的部分
+ * （缺省整串），返回原值。
+ */
+export function closest(needle, candidates, limit = 5, key = String) {
+    const target = needle.toLowerCase();
+    if (target === "")
+        return [];
+    const budget = Math.max(2, Math.ceil(target.length / 3));
+    const scored = [];
+    candidates.forEach((item, index) => {
+        const value = key(item).toLowerCase();
+        if (value === "")
+            return;
+        if (value.includes(target) || target.includes(value)) {
+            scored.push({ item, score: Math.abs(value.length - target.length) / 1000, index });
+            return;
+        }
+        const distance = editDistance(target, value);
+        if (distance <= budget)
+            scored.push({ item, score: distance, index });
+    });
+    return scored
+        .sort((a, b) => a.score - b.score || a.index - b.index)
+        .slice(0, limit)
+        .map((entry) => entry.item);
+}
+/** 解析失败的一行说明（不含前缀标签）：`渠道不存在：x；该模型可用渠道：…` 等。 */
+export function describeLookupFailure(ref, failure) {
+    const list = failure.candidates.slice(0, 20).join(", ");
+    switch (failure.reason) {
+        case "channel_not_found":
+            return failure.candidates.length > 0
+                ? `渠道不存在：${ref}；该模型可用渠道：${list}`
+                : `渠道不存在：${ref}；该模型没有可选渠道（去掉 @ 后缀）`;
+        case "provider_not_found":
+            return failure.candidates.length > 0
+                ? `供应商不存在：${ref}；最接近的供应商：${list}`
+                : `供应商不存在：${ref}（ama providers list 查看已配置的供应商）`;
+        case "ambiguous":
+            return `模型名有歧义：${ref}；候选：${list}`;
+        default:
+            return failure.candidates.length > 0
+                ? `模型不存在：${ref}；最接近的模型：${list}`
+                : `模型不存在：${ref}（ama models list 查看可用模型）`;
+    }
+}

package/dist/ai/sse.d.ts

@@ -28,5 +28,9 @@ export declare class SseParser {
     private processLine;
     private dispatch;
 }
-/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
-export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseEvent>;
+/**
+ * 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。
+ * `idleTimeoutMs`：等待下一块字节的上限，每收到一块即重新计时（消费者处理事件的时间不计）；
+ * 超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
+ */
+export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal, idleTimeoutMs?: number): AsyncGenerator<SseEvent>;

package/dist/ai/sse.js

@@ -6,6 +6,7 @@
  * 第一个空格去掉；多条 data 以 LF 连接。为兼容不规范服务端，流结束时未以空行收尾的最后一个
  * 事件也会分派。
  */
+import { IdleTimeoutError } from "./http.js";
 export class SseParser {
     buffer = "";
     event;
@@ -102,8 +103,12 @@ export class SseParser {
         return hadContent ? event : undefined;
     }
 }
-/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
-export async function* readSseEvents(body, signal) {
+/**
+ * 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。
+ * `idleTimeoutMs`：等待下一块字节的上限，每收到一块即重新计时（消费者处理事件的时间不计）；
+ * 超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
+ */
+export async function* readSseEvents(body, signal, idleTimeoutMs) {
     const reader = body.getReader();
     const decoder = new TextDecoder("utf-8");
     const parser = new SseParser();
@@ -112,11 +117,25 @@ export async function* readSseEvents(body, signal) {
     };
     signal?.addEventListener("abort", onAbort, { once: true });
     let drained = false;
+    let idle;
+    let stalled = false;
+    const arm = () => {
+        if (idleTimeoutMs === undefined || idleTimeoutMs <= 0)
+            return;
+        idle = setTimeout(() => {
+            stalled = true;
+            reader.cancel().catch(() => undefined);
+        }, idleTimeoutMs);
+    };
     try {
         while (true) {
             if (signal?.aborted)
                 return;
+            arm();
             const { value, done } = await reader.read();
+            clearTimeout(idle);
+            if (stalled && !signal?.aborted)
+                throw new IdleTimeoutError(idleTimeoutMs ?? 0, "stream");
             if (done)
                 break;
             if (signal?.aborted)
@@ -131,6 +150,7 @@ export async function* readSseEvents(body, signal) {
             yield event;
     }
     finally {
+        clearTimeout(idle);
         signal?.removeEventListener("abort", onAbort);
         // 消费者提前退出（读到终止事件即 break）或中止：取消底层流，释放连接
         if (!drained)

package/dist/ai/types.d.ts

@@ -15,6 +15,11 @@
  * - [W3-C0] 第三波 §1.3 的五个缓存兼容开关单列为 `PromptCacheCompat`（各协议共用），只并入
  *   `ProviderCompat`（全部可选），不改各协议 compat 接口——`detectCompat` 的返回形状不变，
  *   缺省值由 C1a 在协议层按端点推断。
+ * - [W5-C0] 第五波（docs/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
+ *   （`family / knowledge / releaseDate / inputLimit / status`）；`AnthropicMessagesCompat` 加
+ *   `sendInterleavedThinkingBeta / sendCacheControl`、`OpenAIResponsesCompat` 加
+ *   `explicitCacheField`，全部可选（缺省由 W5-M2 的主机推断表给出）；`ProviderData.channels /
+ *   defaultChannel` 已有，内置供应商（`BuiltinProvider`）同样可带。
  */
 export type KnownApi = "anthropic-messages" | "openai-completions" | "openai-responses" | "google-generative-ai";
 export type Api = KnownApi | (string & {});
@@ -27,7 +32,8 @@ export type CacheRetention = "none" | "short" | "long";
  * 真实回合，`summary` 是压缩 / 分支摘要，`warm` 是缓存保温重放，`probe` 是 `models check` /
  * `cache-probe` 一类的探测。缺省视为 `turn`。协议层只透传，不改变请求体。
  */
-export type RequestPurpose = "turn" | "summary" | "warm" | "probe";
+/** `classify`：auto 权限模式的分类请求（独立请求，不经会话层缓存观测、不触发保温）。 */
+export type RequestPurpose = "turn" | "summary" | "warm" | "probe" | "classify";
 /** `provider/model-id` 拆开后的引用。 */
 export interface ModelRef {
     provider: string;
@@ -206,6 +212,12 @@ export interface AnthropicMessagesCompat {
     /** true：新模型用 `effort` 参数；false：老模型用 `budget_tokens`。 */
     adaptiveThinking: boolean;
     maxCacheBreakpoints: number;
+    /**
+     * [W5-C0] 发 `interleaved-thinking` beta 头；缺省（W5-M2 主机表）：官方端点 true、其它主机 false。
+     */
+    sendInterleavedThinkingBeta?: boolean;
+    /** [W5-C0] 打 `cache_control`；缺省 true，忽略它的端点（DeepSeek 等）可关以减小请求体。 */
+    sendCacheControl?: boolean;
 }
 /** B8 补全。 */
 export interface GoogleCompat {
@@ -216,6 +228,8 @@ export interface GoogleCompat {
 export interface OpenAIResponsesCompat {
     supportsReasoningSummary: boolean;
     supportsStore: boolean;
+    /** [W5-C0] 端点私有的显式缓存字段：`volcengine` = 火山方舟 `caching: { type: "enabled" }`。 */
+    explicitCacheField?: "volcengine";
 }
 /**
  * [W3-C0] 供应商不报缓存时的处理（第三波 §1.6）：`auto` 按响应自动判定三态；`silent` /
@@ -301,6 +315,16 @@ export interface Model {
     channel?: string;
     /** 该模型挂载的全部渠道，首个为首选（多渠道供应商才有）。 */
     channels?: string[];
+    /** 模型家族（如 `claude-sonnet`）。 */
+    family?: string;
+    /** 知识截止（`YYYY-MM` 或 `YYYY-MM-DD`）。 */
+    knowledge?: string;
+    /** 发布日期（`YYYY-MM-DD`）。 */
+    releaseDate?: string;
+    /** 输入上限（token），与 `contextWindow` 不同的模型才有。 */
+    inputLimit?: number;
+    /** 发布状态；正式版不填（deprecated 的模型在快照里已过滤）。 */
+    status?: "beta";
 }
 /** 物化后的渠道（docs/providers.md「渠道」）；key 不在这里，经 `resolveApiKey(provider, channel)` 取。 */
 export interface ProviderChannel {
@@ -325,9 +349,12 @@ export interface ProviderData {
     /** 本地服务 false：无 key 也能用。 */
     requiresApiKey: boolean;
     builtin: boolean;
-    /** 显式配置的渠道（没有 `channels` 的供应商不填，按单渠道处理）。 */
+    /**
+     * 渠道（没有 `channels` 的供应商不填，按单渠道处理）。[W5-C0] 内置供应商也可带内置渠道，
+     * 用户配置同名字段级覆盖、新名追加（物化归 W5-M2）。
+     */
     channels?: ProviderChannel[];
-    /** 首选渠道名（有 `channels` 时）。 */
+    /** 首选渠道名（有 `channels` 时；用户配置优先）。 */
     defaultChannel?: string;
 }
 /** `catalog/*.json` 文件形状（§3.4）。 */
@@ -342,6 +369,11 @@ export interface StreamOptions {
     /** 值为 null 表示删除该头。 */
     headers?: Record<string, string | null>;
     timeoutMs?: number;
+    /**
+     * 空闲超时：等响应头、以及流中两块数据之间的最长间隔（每收到字节即重新计时）。缺省 300 000，
+     * 0 关闭。超时报 `idle timeout` 错误，会话层按可重试处理。
+     */
+    idleTimeoutMs?: number;
     maxTokens?: number;
     temperature?: number;
     thinkingLevel?: ModelThinkingLevel;
@@ -434,7 +466,8 @@ export type ModelLookup = {
     provider: ProviderData;
 } | {
     ok: false;
-    reason: "not_found" | "ambiguous" | "provider_not_found";
+    /** `channel_not_found`：模型在，`@渠道` 不在（候选是该模型可用的 `provider/model@渠道`）。 */
+    reason: "not_found" | "ambiguous" | "provider_not_found" | "channel_not_found";
     candidates: string[];
 };
 export interface ProviderRegistryApi {

package/dist/ai/types.js

@@ -15,5 +15,10 @@
  * - [W3-C0] 第三波 §1.3 的五个缓存兼容开关单列为 `PromptCacheCompat`（各协议共用），只并入
  *   `ProviderCompat`（全部可选），不改各协议 compat 接口——`detectCompat` 的返回形状不变，
  *   缺省值由 C1a 在协议层按端点推断。
+ * - [W5-C0] 第五波（docs/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
+ *   （`family / knowledge / releaseDate / inputLimit / status`）；`AnthropicMessagesCompat` 加
+ *   `sendInterleavedThinkingBeta / sendCacheControl`、`OpenAIResponsesCompat` 加
+ *   `explicitCacheField`，全部可选（缺省由 W5-M2 的主机推断表给出）；`ProviderData.channels /
+ *   defaultChannel` 已有，内置供应商（`BuiltinProvider`）同样可带。
  */
 export {};