@armadra/agent 0.7.3 → 0.7.5

package/dist/ai/providers/catalog.js

@@ -78,6 +78,10 @@ export function checkCatalogEntry(value, path) {
         problems.push(`${path}.modelsDev`);
     if (value["_reason"] !== undefined && typeof value["_reason"] !== "string")
         problems.push(`${path}._reason`);
+    const aliases = value["aliases"];
+    if (aliases !== undefined &&
+        (!Array.isArray(aliases) || !aliases.every((a) => typeof a === "string" && a.length > 0)))
+        problems.push(`${path}.aliases`);
     if (value["maxTokens"] !== undefined &&
         (!isNonNegative(value["maxTokens"]) || value["maxTokens"] === 0)) {
         problems.push(`${path}.maxTokens`);
@@ -160,7 +164,7 @@ export function inheritedFields(file, entry, index = builtinSnapshotIndex()) {
 }
 /** 合并：快照 ⊕ 目录条目（`cost` 按键合并）；返回模型与从快照继承的字段名。 */
 export function resolveCatalogEntry(entry, inherited) {
-    const { modelsDev: _modelsDev, _reason: _r, ...own } = structuredClone(entry);
+    const { modelsDev: _modelsDev, _reason: _r, aliases: _a, ...own } = structuredClone(entry);
     const model = { ...structuredClone(inherited), ...own };
     if (own.cost !== undefined && inherited.cost !== undefined)
         model.cost = { ...structuredClone(inherited.cost), ...own.cost };
@@ -207,6 +211,9 @@ function fileProblems(value) {
     const modelsDev = value["modelsDev"];
     if (modelsDev !== undefined && modelsDev !== false && typeof modelsDev !== "string")
         problems.push("$.modelsDev");
+    const small = value["small"];
+    if (small !== undefined && (typeof small !== "string" || small.length === 0))
+        problems.push("$.small");
     if (!Array.isArray(value["models"]))
         problems.push("$.models must be an array");
     else {
@@ -220,6 +227,8 @@ function fileProblems(value) {
                 seen.add(id);
             }
         });
+        if (typeof small === "string" && small.length > 0 && !seen.has(small))
+            problems.push(`$.small not in models: ${small}`);
     }
     return problems;
 }
@@ -260,11 +269,7 @@ export function parseCatalogFile(value, source, index) {
 }
 const caches = new WeakMap();
 let lastInherited = new Map();
-/**
- * 内置目录：供应商 id → 模型条目（深拷贝，调用方可随意修改）。`index` 缺省用内置快照；传入
- * 「快照 ⊕ 用户刷新」的索引时目录也吃刷新后的数值（缺字段的条目退回内置快照）。
- */
-export function loadBuiltinCatalog(index) {
+function resolvedCatalog(index) {
     const key = index ?? builtinSnapshotIndex();
     let cache = caches.get(key);
     if (cache === undefined) {
@@ -276,6 +281,14 @@ export function loadBuiltinCatalog(index) {
         }
         caches.set(key, cache);
     }
+    return cache;
+}
+/**
+ * 内置目录：供应商 id → 模型条目（深拷贝，调用方可随意修改）。`index` 缺省用内置快照；传入
+ * 「快照 ⊕ 用户刷新」的索引时目录也吃刷新后的数值（缺字段的条目退回内置快照）。
+ */
+export function loadBuiltinCatalog(index) {
+    const cache = resolvedCatalog(index);
     const copy = new Map();
     lastInherited = new Map();
     for (const [provider, resolved] of cache) {
@@ -289,6 +302,90 @@ export function loadBuiltinCatalog(index) {
 export function catalogInherited(provider, modelId) {
     return lastInherited.get(`${provider}/${modelId}`) ?? [];
 }
+const TIER_SUFFIX = /-(minimal|low|medium|high|xhigh|tiered)$/;
+export function normalizeModelId(id) {
+    return id
+        .trim()
+        .toLowerCase()
+        .replace(/^[a-z0-9_.-]+\//, "")
+        .replace(/:latest$/, "");
+}
+let aliasIndex;
+/** 别名索引（测试可传入自造的目录源）。 */
+export function buildAliasIndex(sources = CATALOG_SOURCES) {
+    const index = new Map();
+    const add = (key, target) => {
+        const seen = index.get(key);
+        if (seen === undefined)
+            index.set(key, target);
+        else if (seen === "ambiguous" || seen.provider !== target.provider || seen.id !== target.id)
+            index.set(key, "ambiguous");
+    };
+    for (const raw of Object.values(sources)) {
+        const file = parseCatalogSource(JSON.parse(raw), "catalog");
+        for (const entry of file.models) {
+            const snapshotRef = snapshotRefOf(file, entry);
+            const target = {
+                provider: file.provider,
+                id: entry.id,
+                ...(snapshotRef ? { snapshotRef } : {}),
+            };
+            if (!entry.id.includes("/"))
+                add(normalizeModelId(entry.id), target);
+            for (const alias of entry.aliases ?? [])
+                add(normalizeModelId(alias), target);
+        }
+    }
+    return index;
+}
+function hitOf(target, tier) {
+    const model = resolvedCatalog()
+        .get(target.provider)
+        ?.file.models.find((m) => m.id === target.id);
+    if (model === undefined)
+        return undefined;
+    return {
+        ref: `${target.provider}/${target.id}`,
+        model: structuredClone(model),
+        ...(target.snapshotRef !== undefined ? { snapshotRef: target.snapshotRef } : {}),
+        ...(tier !== undefined ? { tier } : {}),
+    };
+}
+/** 按 id 唯一命中的目录条目（没有或 ambiguous 返回 undefined）。 */
+export function catalogByAlias(id) {
+    aliasIndex ??= buildAliasIndex();
+    const key = normalizeModelId(id);
+    const exact = aliasIndex.get(key);
+    if (exact !== undefined)
+        return exact === "ambiguous" ? undefined : hitOf(exact);
+    const tier = TIER_SUFFIX.exec(key);
+    if (tier === null)
+        return undefined;
+    const base = aliasIndex.get(key.slice(0, tier.index));
+    return base === undefined || base === "ambiguous" ? undefined : hitOf(base, tier[1]);
+}
+/** 显式指定的目录条目 `provider/id`（`models[].catalog`）。 */
+export function catalogByRef(ref) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0)
+        return undefined;
+    const provider = ref.slice(0, slash);
+    const id = ref.slice(slash + 1);
+    const raw = CATALOG_SOURCES[provider];
+    if (raw === undefined)
+        return undefined;
+    const file = parseCatalogSource(JSON.parse(raw), "catalog");
+    const entry = file.models.find((m) => m.id === id);
+    if (entry === undefined)
+        return undefined;
+    const snapshotRef = snapshotRefOf(file, entry);
+    return hitOf({ provider, id, ...(snapshotRef ? { snapshotRef } : {}) });
+}
+/** [ME-D] 供应商目录里给 auto 模式分类用的小模型 id（D12）。 */
+export function catalogSmall(provider) {
+    const raw = CATALOG_SOURCES[provider];
+    return raw === undefined ? undefined : parseCatalogSource(JSON.parse(raw), "catalog").small;
+}
 /** 目录条目 → Model（补 provider / api 与缺省 input）。 */
 export function toModel(entry, provider, api) {
     return { ...structuredClone(entry), input: entry.input ?? ["text"], provider, api };
@@ -308,6 +405,8 @@ export function withCustomDefaults(entry, provider, api) {
 /** 只改元数据：浅合并，`compat` / `cost` / `thinkingLevelMap` / `headers` 再合并一层。 */
 export function applyModelOverride(model, override) {
     const { id: _id, ...rest } = override;
+    // 配置专用键（[ME-D] `catalog`）不进 Model
+    delete rest.catalog;
     const next = { ...model, ...structuredClone(rest) };
     if (override.compat && model.compat)
         next.compat = { ...model.compat, ...override.compat };

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

@@ -4,11 +4,17 @@
  * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
  * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里：目录在 catalog.ts 里已经
  * 「快照 ⊕ 覆盖」合并好（[W5-M1]），这里只给它们标来源。只读传入的索引，不联网。
+ *
+ * [ME-D] 中转模型继承官方目录（D10）：`catalog` 没关时按 id 别名（或显式 `provider/id`）唯一命中
+ * 内置目录条目，继承模型固有属性 `reasoning`、`input`、`thinkingLevelMap`、`promptCache.minTokens`、
+ * `compat.requiresReasoningContentOnAssistantMessages`（用户写了的不覆盖），并把 models.dev 显式
+ * 匹配改为该条目的快照引用；不继承价格、TTL 与 `thinkingFormat`。去掉思考档后缀才命中时（中转按
+ * id 定思考档）不继承思考设置。models.dev 仍补不出的窗口 / 输出上限取目录值。
  */
 import type { ModelConfig } from "../../config/types.js";
 import type { Model } from "../types.js";
 import { type EnrichableField, type ModelsDevIndex, type ModelsDevMatch } from "./models-dev.js";
-export type FieldSource = "config" | "catalog" | "models.dev" | "default";
+export type FieldSource = "config" | "catalog" | "catalog-alias" | "models.dev" | "default";
 export interface ModelMetadata {
     sources: Record<EnrichableField, FieldSource>;
     /** models.dev 匹配结果；未查（没有缓存或 `modelsDev: false`）为 undefined。 */
@@ -17,16 +23,19 @@ export interface ModelMetadata {
     looked: boolean;
     /** models.dev 的 tool_call。 */
     toolCall?: boolean;
+    /** [ME-D] 按 id 继承的内置目录条目 `provider/id`。 */
+    catalog?: string;
 }
 export type ModelsDevSource = ModelsDevIndex | (() => ModelsDevIndex | undefined) | undefined;
 /** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
 export declare function lazyIndex(source: ModelsDevSource): () => ModelsDevIndex | undefined;
+type EnrichedEntry = Omit<ModelConfig, "modelsDev" | "channels" | "catalog">;
 /**
  * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
- * `modelsDev` / `channels` 这些配置专用键）与每个字段的来源。
+ * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。
  */
 export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined): {
-    entry: Omit<ModelConfig, "modelsDev" | "channels">;
+    entry: EnrichedEntry;
     metadata: ModelMetadata;
 };
 /**
@@ -35,3 +44,4 @@ export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIn
  */
 export declare function catalogMetadata(model: Model): ModelMetadata;
 export declare function sourceText(source: FieldSource): string;
+export {};

package/dist/ai/providers/enrich.js

@@ -4,9 +4,15 @@
  * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
  * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里：目录在 catalog.ts 里已经
  * 「快照 ⊕ 覆盖」合并好（[W5-M1]），这里只给它们标来源。只读传入的索引，不联网。
+ *
+ * [ME-D] 中转模型继承官方目录（D10）：`catalog` 没关时按 id 别名（或显式 `provider/id`）唯一命中
+ * 内置目录条目，继承模型固有属性 `reasoning`、`input`、`thinkingLevelMap`、`promptCache.minTokens`、
+ * `compat.requiresReasoningContentOnAssistantMessages`（用户写了的不覆盖），并把 models.dev 显式
+ * 匹配改为该条目的快照引用；不继承价格、TTL 与 `thinkingFormat`。去掉思考档后缀才命中时（中转按
+ * id 定思考档）不继承思考设置。models.dev 仍补不出的窗口 / 输出上限取目录值。
  */
-import { catalogInherited } from "./catalog.js";
-import { ENRICHABLE_FIELDS, modelsDevFields, } from "./models-dev.js";
+import { catalogByAlias, catalogByRef, catalogInherited } from "./catalog.js";
+import { ENRICHABLE_FIELDS, MODELS_DEV_MAX_OUTPUT, modelsDevFields, } from "./models-dev.js";
 import { msg } from "../../i18n/index.js";
 /** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
 export function lazyIndex(source) {
@@ -32,47 +38,97 @@ const METADATA_FIELDS = ["family", "knowledge", "releaseDate", "inputLimit", "st
 function needsLookup(entry) {
     return ENRICHABLE_FIELDS.some((field) => entry[field] === undefined);
 }
+function catalogHit(entry) {
+    if (entry.catalog === false)
+        return undefined;
+    return typeof entry.catalog === "string" ? catalogByRef(entry.catalog) : catalogByAlias(entry.id);
+}
+/** 目录固有属性（用户写了的不覆盖）。 */
+function inheritIntrinsic(out, hit, sources) {
+    const model = hit.model;
+    if (out.input === undefined && model.input !== undefined) {
+        out.input = [...model.input];
+        sources.input = "catalog-alias";
+    }
+    if (hit.tier === undefined) {
+        if (out.reasoning === undefined) {
+            out.reasoning = model.reasoning;
+            sources.reasoning = "catalog-alias";
+        }
+        if (out.thinkingLevelMap === undefined && model.thinkingLevelMap !== undefined)
+            out.thinkingLevelMap = structuredClone(model.thinkingLevelMap);
+    }
+    const minTokens = model.promptCache?.minTokens;
+    if (minTokens !== undefined && out.promptCache?.minTokens === undefined)
+        out.promptCache = { ...out.promptCache, minTokens };
+    const requires = model.compat?.requiresReasoningContentOnAssistantMessages;
+    if (requires !== undefined &&
+        out.compat?.requiresReasoningContentOnAssistantMessages === undefined)
+        out.compat = { ...out.compat, requiresReasoningContentOnAssistantMessages: requires };
+}
+/** models.dev 之后仍缺的窗口与输出上限取目录值（输出按 models.dev 口径封顶）。 */
+function fillLimits(out, hit, sources) {
+    if (out.contextWindow === undefined && hit.model.contextWindow !== undefined) {
+        out.contextWindow = hit.model.contextWindow;
+        sources.contextWindow = "catalog-alias";
+    }
+    if (out.maxTokens === undefined) {
+        out.maxTokens = Math.min(hit.model.maxTokens, MODELS_DEV_MAX_OUTPUT);
+        sources.maxTokens = "catalog-alias";
+    }
+}
 /**
  * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
- * `modelsDev` / `channels` 这些配置专用键）与每个字段的来源。
+ * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。
  */
 export function enrichEntry(entry, index) {
-    const { modelsDev, channels: _channels, ...rest } = entry;
+    const { modelsDev, channels: _channels, catalog: _catalog, ...rest } = entry;
     const sources = {};
     for (const field of ENRICHABLE_FIELDS) {
         sources[field] = rest[field] !== undefined ? "config" : "default";
     }
     const metadata = { sources, looked: false };
-    if (modelsDev === false || (!needsLookup(rest) && modelsDev === undefined)) {
-        return { entry: rest, metadata };
-    }
-    const idx = index();
-    if (idx === undefined)
-        return { entry: rest, metadata };
-    metadata.looked = true;
-    const match = idx.match(entry.id, typeof modelsDev === "string" ? modelsDev : undefined);
-    metadata.match = match;
-    if (match === undefined)
-        return { entry: rest, metadata };
-    const fields = modelsDevFields(match.model);
-    if (fields.toolCall !== undefined)
-        metadata.toolCall = fields.toolCall;
     const out = { ...rest };
-    for (const field of ENRICHABLE_FIELDS) {
-        if (out[field] !== undefined)
-            continue;
-        const value = fields[field];
-        if (value === undefined)
-            continue;
-        out[field] = structuredClone(value);
-        sources[field] = "models.dev";
+    const hit = catalogHit(entry);
+    if (hit !== undefined) {
+        metadata.catalog = hit.ref;
+        inheritIntrinsic(out, hit, sources);
     }
-    if (out.name === undefined && fields.name !== undefined)
-        out.name = fields.name;
-    for (const field of METADATA_FIELDS) {
-        if (out[field] === undefined && fields[field] !== undefined)
-            out[field] = fields[field];
+    const explicit = typeof modelsDev === "string" ? modelsDev : hit?.snapshotRef;
+    const lookup = modelsDev !== false && (needsLookup(out) || modelsDev !== undefined);
+    const idx = lookup ? index() : undefined;
+    if (idx !== undefined) {
+        metadata.looked = true;
+        // 目录给的快照引用在用户刷新的数据里不存在时，回落按 id 匹配
+        const match = idx.match(entry.id, explicit) ??
+            (modelsDev === undefined && explicit !== undefined ? idx.match(entry.id) : undefined);
+        metadata.match = match;
+        if (match !== undefined) {
+            const fields = modelsDevFields(match.model);
+            if (fields.toolCall !== undefined)
+                metadata.toolCall = fields.toolCall;
+            for (const field of ENRICHABLE_FIELDS) {
+                if (out[field] !== undefined)
+                    continue;
+                // 思考档写在 id 里的中转模型：不让 models.dev 打开思考参数
+                if (field === "reasoning" && hit?.tier !== undefined)
+                    continue;
+                const value = fields[field];
+                if (value === undefined)
+                    continue;
+                out[field] = structuredClone(value);
+                sources[field] = "models.dev";
+            }
+            if (out.name === undefined && fields.name !== undefined)
+                out.name = fields.name;
+            for (const field of METADATA_FIELDS) {
+                if (out[field] === undefined && fields[field] !== undefined)
+                    out[field] = fields[field];
+            }
+        }
     }
+    if (hit !== undefined && modelsDev !== false)
+        fillLimits(out, hit, sources);
     return { entry: out, metadata };
 }
 /**

package/dist/ai/sse.d.ts

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

package/dist/ai/sse.js

@@ -105,8 +105,9 @@ export class SseParser {
 }
 /**
  * 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。
- * `idleTimeoutMs`：等待下一块字节的上限，每收到一块即重新计时（消费者处理事件的时间不计）；
- * 超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
+ * `idleTimeoutMs`：等待下一块字节的上限（调用方传 `streamIdleTimeoutOf(options)`，即
+ * `request.streamIdleTimeoutMs`，与等响应头的上限分开），每收到一块即重新计时（消费者处理事件的
+ * 时间不计）；超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
  */
 export async function* readSseEvents(body, signal, idleTimeoutMs) {
     const reader = body.getReader();

package/dist/ai/types.d.ts

@@ -86,6 +86,8 @@ export interface ToolCallBlock {
     arguments: Record<string, unknown>;
     /** Google thoughtSignature 等。 */
     thoughtSignature?: string;
+    /** 模型输出的原始 arguments 字符串（严格 JSON 可解析时才有）；同协议回放时原样发回。 */
+    rawArguments?: string;
 }
 /** 用户消息与工具结果可携带的块。 */
 export type ContentBlock = TextBlock | ImageBlock;
@@ -163,6 +165,8 @@ export interface AssistantMessage {
     providerThinkingLevel?: string;
     /** 供应商原始 finish / stop reason。 */
     rawStopReason?: string;
+    /** 失败响应的 Retry-After（毫秒）；会话层退避取 max(退避, 它)。可选字段，落盘与 RPC 原样透传。 */
+    retryAfterMs?: number;
     timestamp: number;
 }
 export interface ToolResultMessage {
@@ -385,10 +389,13 @@ export interface StreamOptions {
     headers?: Record<string, string | null>;
     timeoutMs?: number;
     /**
-     * 空闲超时：等响应头、以及流中两块数据之间的最长间隔（每收到字节即重新计时）。缺省 300 000，
-     * 0 关闭。超时报 `idle timeout` 错误，会话层按可重试处理。
+     * 等响应头的空闲超时（毫秒）。缺省 300 000，0 关闭。超时报 `idle timeout` 错误，会话层按可重试处理。
      */
     idleTimeoutMs?: number;
+    /**
+     * [ME-C] 流开始后两块数据之间的最长间隔（毫秒，每收到字节即重新计时）。缺省 180 000，0 关闭。
+     */
+    streamIdleTimeoutMs?: number;
     maxTokens?: number;
     temperature?: number;
     thinkingLevel?: ModelThinkingLevel;