@armadra/agent 0.4.0 → 0.5.1

package/dist/agents/parse.js

@@ -0,0 +1,116 @@
+/**
+ * 子 Agent 定义文件解析（docs/wave5-plan.md §7.1，D22）。[W5-G]
+ *
+ * 一个 `*.md` = 一个类型：frontmatter 与 Skill 同一套 YAML 子集（skills/frontmatter.ts），字段名
+ * kebab-case；正文 = 追加到子会话系统提示末尾的角色说明。不合格的文件不加载并给出 warning（拼错的
+ * 字段比静默按缺省运行更容易发现）。不支持的字段（`hooks`、`mcpServers`、`memory`、`color`、
+ * `initialPrompt`、`skills`）与未知字段忽略。
+ */
+import { basename } from "node:path";
+import { parseFrontmatter } from "../skills/frontmatter.js";
+export const AGENT_NAME_RE = /^[a-z0-9-]{1,64}$/;
+export const MAX_AGENT_DESCRIPTION = 1024;
+export const DEFAULT_AGENT_MAX_TURNS = 30;
+const THINKING = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+/** 字符串或数组 → 名字列表（`read, grep` / `[read, grep]` / 块数组）。 */
+function nameList(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const items = Array.isArray(value) ? value.map(String) : String(value).split(/[\s,]+/);
+    return items.map((item) => item.trim()).filter((item) => item !== "");
+}
+function isRunner(value) {
+    return value === "ama" || value === "claude" || value === "codex" || /^acp:[^\s]+$/.test(value);
+}
+function permissionModeOf(value) {
+    if (value === undefined || value === null)
+        return "inherit";
+    const text = String(value).trim();
+    if (text === "inherit")
+        return "inherit";
+    // R4 草案写作 read-only；与 plan 同义（D22：只读复用 plan 模式）
+    if (text === "plan" || text === "read-only" || text === "readonly")
+        return "plan";
+    return undefined;
+}
+/** 解析一份定义文件；`filePath` 用于缺省名与 warning。 */
+export function parseAgentDefinition(text, filePath, source) {
+    const warnings = [];
+    const fail = (message) => {
+        warnings.push(`${filePath}: ${message}`);
+        return { warnings };
+    };
+    const fm = parseFrontmatter(text);
+    for (const error of fm.errors)
+        warnings.push(`${filePath}: ${error}`);
+    const data = fm.data;
+    const rawName = data["name"];
+    const name = typeof rawName === "string" && rawName !== "" ? rawName : basename(filePath, ".md");
+    if (!AGENT_NAME_RE.test(name))
+        return fail(`invalid agent name "${name}" (lowercase letters, digits, -; at most 64)`);
+    const description = data["description"];
+    if (typeof description !== "string" || description.trim() === "")
+        return fail(`missing description; agent "${name}" not loaded`);
+    if (description.length > MAX_AGENT_DESCRIPTION)
+        return fail(`description longer than ${MAX_AGENT_DESCRIPTION} characters`);
+    const runnerRaw = data["runner"] ?? "ama";
+    const runner = String(runnerRaw).trim();
+    if (!isRunner(runner))
+        return fail(`unknown runner "${runner}" (ama | claude | codex | acp:<program>)`);
+    const tools = nameList(data["tools"]);
+    const disallowedTools = nameList(data["disallowed-tools"]);
+    if (tools !== undefined && disallowedTools !== undefined)
+        return fail("tools and disallowed-tools are mutually exclusive");
+    const permissionMode = permissionModeOf(data["permission-mode"]);
+    if (permissionMode === undefined)
+        return fail(`permission-mode must be plan or inherit (got "${String(data["permission-mode"])}")`);
+    const model = data["model"] === undefined || data["model"] === null ? "inherit" : data["model"];
+    if (typeof model !== "string" || model.trim() === "")
+        return fail("model must be a string");
+    const thinking = data["thinking"];
+    if (thinking !== undefined &&
+        thinking !== null &&
+        !THINKING.includes(thinking))
+        return fail(`thinking must be one of ${THINKING.join(", ")}`);
+    const maxTurns = data["max-turns"] ?? DEFAULT_AGENT_MAX_TURNS;
+    if (typeof maxTurns !== "number" || !Number.isInteger(maxTurns) || maxTurns < 1)
+        return fail("max-turns must be an integer ≥ 1");
+    const isolation = data["isolation"] ?? "none";
+    if (isolation !== "none" && isolation !== "worktree")
+        return fail("isolation must be none or worktree");
+    const background = data["background"] ?? false;
+    if (typeof background !== "boolean")
+        return fail("background must be true or false");
+    if (runner !== "ama") {
+        const ignored = ["tools", "disallowed-tools", "permission-mode"].filter((key) => data[key] !== undefined);
+        if (ignored.length > 0)
+            warnings.push(`${filePath}: ${ignored.join(", ")} ignored for external runner ${runner} (it keeps its own policy)`);
+    }
+    const agent = {
+        name,
+        description: description.trim(),
+        permissionMode,
+        model: model.trim(),
+        maxTurns,
+        isolation,
+        background,
+        runner,
+        prompt: fm.body.trim(),
+        source,
+        filePath,
+    };
+    if (tools !== undefined)
+        agent.tools = tools;
+    if (disallowedTools !== undefined)
+        agent.disallowedTools = disallowedTools;
+    if (typeof thinking === "string")
+        agent.thinking = thinking;
+    return { agent, warnings };
+}

package/dist/agents/result.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 子 Agent 结果的上限、落盘与通知文本（docs/wave5-plan.md §7.4，D23–D24）。[W5-G]
+ *
+ * - 结果 > 50 KB（UTF-8 字节）保留头 70% + 尾 30%，中间一行说明省略了多少、全文在哪；
+ * - 后台任务完成后以 `<task-notification>` 作为 followUp 投递给父会话（系统提示 rules 里由 task
+ *   工具的 guideline 说明这不是用户发言）。
+ */
+import type { Usage } from "../ai/types.js";
+import type { SubagentStatus } from "../tools/types.js";
+export declare const TASK_RESULT_LIMIT_BYTES: number;
+export declare const MAX_TURNS_NOTE = "[Turn limit reached; the sub-agent's last output follows.]";
+/** 超过上限时保留头尾；返回 `truncated` 供调用方决定是否落盘。 */
+export declare function capTaskText(text: string, outputFile: string | undefined, limit?: number): {
+    text: string;
+    truncated: boolean;
+};
+/** 全文写到 `<dir>/<name>`；失败返回 undefined（结果仍按截断返回）。 */
+export declare function writeTaskOutput(dir: string, name: string, text: string): string | undefined;
+export declare function formatTokens(count: number): string;
+export interface NotificationInput {
+    taskId: string;
+    agent: string;
+    status: SubagentStatus;
+    turns?: number;
+    usage?: Usage;
+    outputFile?: string;
+    /** 已按上限截断的最终报告。 */
+    report: string;
+}
+export declare function taskNotification(input: NotificationInput): string;
+/** 系统提示 rules 节的一句（task 工具的 promptGuidelines；会话开始即固定）。 */
+export declare const TASK_NOTIFICATION_RULE = "A <task-notification> message is a background task's report, not the user speaking.";

package/dist/agents/result.js

@@ -0,0 +1,67 @@
+/**
+ * 子 Agent 结果的上限、落盘与通知文本（docs/wave5-plan.md §7.4，D23–D24）。[W5-G]
+ *
+ * - 结果 > 50 KB（UTF-8 字节）保留头 70% + 尾 30%，中间一行说明省略了多少、全文在哪；
+ * - 后台任务完成后以 `<task-notification>` 作为 followUp 投递给父会话（系统提示 rules 里由 task
+ *   工具的 guideline 说明这不是用户发言）。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const TASK_RESULT_LIMIT_BYTES = 50 * 1024;
+const HEAD_SHARE = 0.7;
+export const MAX_TURNS_NOTE = "[Turn limit reached; the sub-agent's last output follows.]";
+/** 去掉按字节切开时残留的半个字符（U+FFFD）。 */
+function trimReplacement(text, side) {
+    return side === "end" ? text.replace(/�+$/, "") : text.replace(/^�+/, "");
+}
+/** 超过上限时保留头尾；返回 `truncated` 供调用方决定是否落盘。 */
+export function capTaskText(text, outputFile, limit = TASK_RESULT_LIMIT_BYTES) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.length <= limit)
+        return { text, truncated: false };
+    const headBytes = Math.floor(limit * HEAD_SHARE);
+    const tailBytes = limit - headBytes;
+    const head = trimReplacement(bytes.subarray(0, headBytes).toString("utf8"), "end");
+    const tail = trimReplacement(bytes.subarray(bytes.length - tailBytes).toString("utf8"), "start");
+    const omitted = bytes.length - headBytes - tailBytes;
+    const where = outputFile === undefined ? "" : `; full output: ${outputFile}`;
+    return { text: `${head}\n\n[… ${omitted} bytes omitted${where} …]\n\n${tail}`, truncated: true };
+}
+/** 全文写到 `<dir>/<name>`；失败返回 undefined（结果仍按截断返回）。 */
+export function writeTaskOutput(dir, name, text) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const file = join(dir, name);
+        writeFileSync(file, text);
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function formatTokens(count) {
+    if (count < 1000)
+        return String(count);
+    if (count < 1_000_000)
+        return `${(count / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+    return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+function attr(value) {
+    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+export function taskNotification(input) {
+    const attrs = [
+        `taskId="${attr(input.taskId)}"`,
+        `agent="${attr(input.agent)}"`,
+        `status="${input.status}"`,
+    ];
+    if (input.turns !== undefined)
+        attrs.push(`turns="${input.turns}"`);
+    if (input.usage !== undefined)
+        attrs.push(`tokens="${formatTokens(input.usage.totalTokens)}"`);
+    if (input.outputFile !== undefined)
+        attrs.push(`outputFile="${attr(input.outputFile)}"`);
+    return `<task-notification ${attrs.join(" ")}>\n${input.report}\n</task-notification>`;
+}
+/** 系统提示 rules 节的一句（task 工具的 promptGuidelines；会话开始即固定）。 */
+export const TASK_NOTIFICATION_RULE = "A <task-notification> message is a background task's report, not the user speaking.";

package/dist/agents/task-control.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 会话 id → 任务控制面（`task_ctl` 工具、RPC `get_tasks`、`/tasks` 用）。[W5-G]
+ *
+ * 注册表（agent/subagent-registry.ts）建好后登记、会话 dispose 时注销。单独成文件是为了让
+ * tools/task-ctl.ts 不 import agent/ 的实现（agent/tool-runner → tools/registry → task-ctl 会成环）。
+ */
+import type { SubagentResult, TaskRegistryView } from "../tools/types.js";
+export interface TaskControl extends TaskRegistryView {
+    /** 运行中是已有输出，结束后是最终文本。 */
+    output(taskId: string): string | undefined;
+    /** 等结束或超时（超时返回 undefined）；未知 taskId 抛 `task_not_found`。 */
+    wait(taskId: string, timeoutMs: number): Promise<SubagentResult | undefined>;
+    stop(taskId: string): Promise<SubagentResult | undefined>;
+}
+export declare function registerTaskControl(sessionId: string, control: TaskControl): void;
+export declare function unregisterTaskControl(sessionId: string, control: TaskControl): void;
+export declare function taskControl(sessionId: string): TaskControl | undefined;

package/dist/agents/task-control.js

@@ -0,0 +1,17 @@
+/**
+ * 会话 id → 任务控制面（`task_ctl` 工具、RPC `get_tasks`、`/tasks` 用）。[W5-G]
+ *
+ * 注册表（agent/subagent-registry.ts）建好后登记、会话 dispose 时注销。单独成文件是为了让
+ * tools/task-ctl.ts 不 import agent/ 的实现（agent/tool-runner → tools/registry → task-ctl 会成环）。
+ */
+const controls = new Map();
+export function registerTaskControl(sessionId, control) {
+    controls.set(sessionId, control);
+}
+export function unregisterTaskControl(sessionId, control) {
+    if (controls.get(sessionId) === control)
+        controls.delete(sessionId);
+}
+export function taskControl(sessionId) {
+    return controls.get(sessionId);
+}

package/dist/agents/task-record.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 子 Agent 任务记录：并发池、单条任务的状态、runner 进度 → `subagent_update`、父会话
+ * `custom{ama.task}` 快照的写入形状与 resume 重建（docs/wave5-plan.md §7.4–§7.5）。[W5-G]
+ * 编排在 agent/subagent-registry.ts。
+ */
+import type { SubagentUpdateEvent } from "../agent/types-w5.js";
+import type { Worktree, WorktreeOutcome } from "../agent/worktree.js";
+import type { SessionEntry } from "../session/types.js";
+import type { RunnerHandle, SubagentEvent, SubagentRequest, SubagentResult, TaskInfo } from "../tools/types.js";
+import type { AgentCatalog } from "./catalog.js";
+import type { AgentDefinition } from "./types.js";
+export declare const TASK_CUSTOM_TYPE = "ama.task";
+/** `subagent_update{kind:"text"}` 的合并间隔。 */
+export declare const TEXT_THROTTLE_MS = 250;
+/** 计数信号量；`waiting` 供排队上限判断；排队中 abort → 抛 aborted 并让出位置。 */
+export declare class SubagentPool {
+    private readonly limit;
+    private running;
+    private readonly waiters;
+    constructor(limit: number);
+    get waiting(): number;
+    acquire(signal: AbortSignal): Promise<void>;
+    release(): void;
+}
+/** ama runner 的创建参数（registry → session-subagent.ts）。 */
+export interface AmaRunnerSpec {
+    taskId: string;
+    agent: AgentDefinition;
+    request: SubagentRequest;
+    /** `provider/model`；undefined = 继承父。 */
+    modelRef?: string;
+    cwd: string;
+    /** 续聊被释放 / resume 后的任务：重开这个子会话文件。 */
+    resumeFile?: string;
+    /** worktree 里运行：不记父会话检查点。 */
+    isolated: boolean;
+}
+/** runner 句柄的可选扩展（ama 子会话提供）。 */
+export type TaskHandle = RunnerHandle & {
+    readonly sessionFile?: string;
+    readonly model?: string;
+    dispose?(): Promise<void>;
+};
+export interface TaskRecord {
+    info: TaskInfo;
+    agent: AgentDefinition;
+    parentToolCallId: string;
+    isolation: "none" | "worktree";
+    cwd: string;
+    modelRef?: string;
+    handle?: TaskHandle;
+    running?: Promise<SubagentResult>;
+    controller?: AbortController;
+    /** 本次运行的文本（运行中是已有输出，结束后是最终文本）。 */
+    text: string;
+    pendingText: string;
+    lastFlush: number;
+    worktree?: Worktree;
+    worktreeOutcome?: WorktreeOutcome;
+    last?: SubagentResult;
+    onUpdate?: (partial: string) => void;
+}
+export declare function newRecord(info: TaskInfo, agent: AgentDefinition, parentToolCallId: string, cwd: string, isolation?: "none" | "worktree"): TaskRecord;
+export interface ProgressSink {
+    emit(event: SubagentUpdateEvent): void;
+    log(level: "info" | "warn", message: string): void;
+    now(): number;
+}
+export declare function flushText(record: TaskRecord, sink: ProgressSink): void;
+/** runner 进度 → 记录与 `subagent_update`（文本 ≥ 250 ms 合并，轮次与结束时冲刷）。 */
+export declare function applyRunnerEvent(record: TaskRecord, event: SubagentEvent, sink: ProgressSink): void;
+/** 父会话 `custom{ama.task}` 的 data：TaskInfo + 父 toolCallId + 运行目录（带 `status`）。 */
+export declare function recordData(record: TaskRecord): Record<string, unknown>;
+/** 从父会话分支重建（同一 taskId 取最后一条；未结束的标 interrupted）；返回最大序号。 */
+export declare function rebuildRecords(branch: readonly SessionEntry[], catalog: AgentCatalog, cwd: string): {
+    records: Map<string, TaskRecord>;
+    seq: number;
+};

package/dist/agents/task-record.js

@@ -0,0 +1,141 @@
+/**
+ * 子 Agent 任务记录：并发池、单条任务的状态、runner 进度 → `subagent_update`、父会话
+ * `custom{ama.task}` 快照的写入形状与 resume 重建（docs/wave5-plan.md §7.4–§7.5）。[W5-G]
+ * 编排在 agent/subagent-registry.ts。
+ */
+import { AmaError } from "../errors.js";
+import { DEFAULT_AGENT } from "./builtin.js";
+export const TASK_CUSTOM_TYPE = "ama.task";
+/** `subagent_update{kind:"text"}` 的合并间隔。 */
+export const TEXT_THROTTLE_MS = 250;
+/** 计数信号量；`waiting` 供排队上限判断；排队中 abort → 抛 aborted 并让出位置。 */
+export class SubagentPool {
+    limit;
+    running = 0;
+    waiters = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    get waiting() {
+        return this.waiters.length;
+    }
+    async acquire(signal) {
+        while (this.running >= this.limit) {
+            if (signal.aborted)
+                throw new AmaError("aborted", "aborted");
+            await new Promise((resolve) => {
+                const wake = () => {
+                    signal.removeEventListener("abort", wake);
+                    const at = this.waiters.indexOf(wake);
+                    if (at >= 0)
+                        this.waiters.splice(at, 1);
+                    resolve();
+                };
+                this.waiters.push(wake);
+                signal.addEventListener("abort", wake, { once: true });
+            });
+        }
+        if (signal.aborted)
+            throw new AmaError("aborted", "aborted");
+        this.running++;
+    }
+    release() {
+        this.running--;
+        this.waiters[0]?.();
+    }
+}
+export function newRecord(info, agent, parentToolCallId, cwd, isolation = "none") {
+    return { info, agent, parentToolCallId, isolation, cwd, text: "", pendingText: "", lastFlush: 0 };
+}
+export function flushText(record, sink) {
+    if (record.pendingText === "")
+        return;
+    sink.emit({
+        type: "subagent_update",
+        taskId: record.info.taskId,
+        kind: "text",
+        textDelta: record.pendingText,
+        turn: record.info.turns ?? 0,
+    });
+    record.pendingText = "";
+    record.lastFlush = sink.now();
+}
+/** runner 进度 → 记录与 `subagent_update`（文本 ≥ 250 ms 合并，轮次与结束时冲刷）。 */
+export function applyRunnerEvent(record, event, sink) {
+    const taskId = record.info.taskId;
+    switch (event.type) {
+        case "text":
+            record.text += event.delta;
+            record.pendingText += event.delta;
+            if (sink.now() - record.lastFlush >= TEXT_THROTTLE_MS)
+                flushText(record, sink);
+            return;
+        case "tool":
+            if (event.status !== "started")
+                return;
+            record.onUpdate?.(`[task] ${event.toolName}`);
+            sink.emit({
+                type: "subagent_update",
+                taskId,
+                kind: "tool",
+                toolName: event.toolName,
+                turn: record.info.turns ?? 0,
+            });
+            return;
+        case "turn": {
+            flushText(record, sink);
+            record.info.turns = event.turn;
+            const update = {
+                type: "subagent_update",
+                taskId,
+                kind: "turn",
+                turn: event.turn,
+            };
+            if (record.info.usage !== undefined)
+                update.usage = record.info.usage;
+            sink.emit(update);
+            return;
+        }
+        case "usage":
+            if (event.usage !== undefined)
+                record.info.usage = event.usage;
+            if (event.unit === "usd" && event.amount !== undefined)
+                record.info.costUsd = event.amount;
+            return;
+        case "notice":
+            sink.log(event.level, `[task ${taskId}] ${event.text}`);
+            return;
+        default:
+            return;
+    }
+}
+/** 父会话 `custom{ama.task}` 的 data：TaskInfo + 父 toolCallId + 运行目录（带 `status`）。 */
+export function recordData(record) {
+    return { ...record.info, parentToolCallId: record.parentToolCallId, cwd: record.cwd };
+}
+/** 从父会话分支重建（同一 taskId 取最后一条；未结束的标 interrupted）；返回最大序号。 */
+export function rebuildRecords(branch, catalog, cwd) {
+    const records = new Map();
+    let seq = 0;
+    for (const entry of branch) {
+        if (entry.type !== "custom" || entry.customType !== TASK_CUSTOM_TYPE)
+            continue;
+        // 子会话自己的首条 ama.task 没有 status，跳过
+        const data = entry.data;
+        if (typeof data.taskId !== "string" || data.status === undefined)
+            continue;
+        const { parentToolCallId = "", cwd: runCwd = cwd, ...rest } = data;
+        const info = { ...rest };
+        if (info.status === "running")
+            info.status = "interrupted";
+        const agent = catalog.get(info.agent) ?? {
+            ...catalog.get(DEFAULT_AGENT),
+            name: info.agent,
+        };
+        records.set(info.taskId, newRecord(info, agent, parentToolCallId, runCwd));
+        const n = /^t(\d+)$/.exec(info.taskId);
+        if (n !== null)
+            seq = Math.max(seq, Number(n[1]));
+    }
+    return { records, seq };
+}

package/dist/agents/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 子 Agent 定义契约（docs/wave5-plan.md §7.1–§7.2，D22）。[W5-C0] 契约文件，发现与解析归 W5-G。
+ *
+ * 定义文件：`--agent-dir`（可重复）→ profile `agentDirs` → `~/.config/ama/agents/*.md` →
+ * `<cwd>/.ama/agents/*.md`（需信任）；frontmatter 与 Skill 同风格（kebab-case），正文追加到子会话
+ * 系统提示末尾。这里是解析后（缺省已补齐）的形状。
+ */
+import type { ModelThinkingLevel } from "../ai/types.js";
+/** `ama`（缺省）| `claude` | `codex` | `acp:<program>`。 */
+export type AgentRunnerSpec = "ama" | "claude" | "codex" | `acp:${string}`;
+export type AgentSource = "builtin" | "cli" | "profile" | "user" | "project" | "host";
+export interface AgentDefinition {
+    /** `^[a-z0-9-]{1,64}$`，缺省取文件名。 */
+    name: string;
+    /** ≤ 1024 字符，进 task 工具描述。 */
+    description: string;
+    /** 工具白名单（与 `disallowedTools` 二选一）；缺省 = 父活动集。 */
+    tools?: string[];
+    disallowedTools?: string[];
+    /** `plan` 强制只读；`inherit` = 父当前模式（只能更严）。 */
+    permissionMode: "plan" | "inherit";
+    /** `inherit` | `fast` | `strong`（`models.aliases`）| `provider/model[@channel]`。 */
+    model: string;
+    thinking?: ModelThinkingLevel;
+    /** 缺省 30。 */
+    maxTurns: number;
+    isolation: "none" | "worktree";
+    background: boolean;
+    runner: AgentRunnerSpec;
+    /** 正文：追加到子会话系统提示末尾的角色说明。 */
+    prompt: string;
+    source: AgentSource;
+    /** 定义文件路径（内置与宿主类型没有）。 */
+    filePath?: string;
+}
+/** RPC `get_agents` / `/agents` 的一行。 */
+export interface AgentInfo {
+    name: string;
+    description: string;
+    runner: AgentRunnerSpec | (string & {});
+    source: AgentSource;
+    filePath?: string;
+    /** 外部 Agent：探测到的版本与是否已安装。 */
+    installed?: boolean;
+    version?: string;
+}

package/dist/agents/types.js

@@ -0,0 +1,8 @@
+/**
+ * 子 Agent 定义契约（docs/wave5-plan.md §7.1–§7.2，D22）。[W5-C0] 契约文件，发现与解析归 W5-G。
+ *
+ * 定义文件：`--agent-dir`（可重复）→ profile `agentDirs` → `~/.config/ama/agents/*.md` →
+ * `<cwd>/.ama/agents/*.md`（需信任）；frontmatter 与 Skill 同风格（kebab-case），正文追加到子会话
+ * 系统提示末尾。这里是解析后（缺省已补齐）的形状。
+ */
+export {};

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

@@ -0,0 +1,36 @@
+/**
+ * anthropic-messages 的 compat 推断（[W5-M2]，docs/wave5-plan.md §3.1、D10）：按请求主机给缺省。
+ *
+ * 顺序：保守缺省 ← 主机表（`model.baseUrl` 的主机名子串，先命中先用）← `provider.compat` ←
+ * `model.compat`（字段级覆盖，undefined 不覆盖）。registry 物化后的模型已把供应商 / 渠道 compat 合进
+ * `model.compat`，所以显式配置永远胜过推断。
+ *
+ * - `sendInterleavedThinkingBeta`：官方端点开；表里的第三方端点关（DeepSeek 文档写明忽略 beta 头，其余
+ *   未写明接受，不发未知 beta 头最稳）；不在表里的主机（中转）只对 `claude*` 模型开——中转转发 Claude
+ *   时仍需要交错思考。
+ * - `sendCacheControl`：缺省开；DeepSeek 文档写明 `cache_control` 被忽略，关掉以减小请求体。
+ * - `adaptiveThinking` 只由目录 / 配置给（官方模型逐条写在 catalog/anthropic.json），表里不推断。
+ * - 缓存保留层级（1h TTL）等缓存能力在 cache-params.ts 的 `HOST_CACHE_CAPABILITIES`，不在这里。
+ * - OpenRouter：流式 usage 只出现在 `message_delta`，`applyAnthropicUsage` 本就按非 null 字段合并，
+ *   不需要开关（anthropic-compat.test.ts 核对）。
+ *
+ * 表里每一项都对应厂商文档或实测（docs/research/R1-models-protocols.md §2.1、docs/providers.md「渠道实测」）。
+ */
+import type { AnthropicMessagesCompat, Model, ProviderData } from "../types.js";
+export type ResolvedAnthropicCompat = Required<AnthropicMessagesCompat>;
+export declare const ANTHROPIC_COMPAT_KEYS: readonly ["supportsCacheControlOnTools", "supportsTemperatureWithThinking", "adaptiveThinking", "maxCacheBreakpoints", "sendInterleavedThinkingBeta", "sendCacheControl"];
+/** 未知主机的保守缺省（`sendInterleavedThinkingBeta` 另按模型 id 定，见 `hostDefaults`）。 */
+export declare const DEFAULT_ANTHROPIC_COMPAT: Readonly<ResolvedAnthropicCompat>;
+export interface AnthropicHostRule {
+    /** 主机名子串（小写）。 */
+    host: string;
+    patch: Partial<AnthropicMessagesCompat>;
+}
+/** 主机表：先命中先用。 */
+export declare const ANTHROPIC_HOST_RULES: readonly AnthropicHostRule[];
+/** 命中的主机规则（没有返回 undefined）。 */
+export declare function findAnthropicHostRule(baseUrl: string | undefined): AnthropicHostRule | undefined;
+/** 主机推断（不含显式配置）。未知主机：`claude*` 模型发交错思考 beta（中转转发 Claude）。 */
+export declare function hostDefaults(baseUrl: string | undefined, modelId: string): ResolvedAnthropicCompat;
+/** 完整 compat：主机推断 ← provider.compat ← model.compat。 */
+export declare function detectAnthropicCompat(model: Model, provider?: ProviderData): ResolvedAnthropicCompat;

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

@@ -0,0 +1,92 @@
+/**
+ * anthropic-messages 的 compat 推断（[W5-M2]，docs/wave5-plan.md §3.1、D10）：按请求主机给缺省。
+ *
+ * 顺序：保守缺省 ← 主机表（`model.baseUrl` 的主机名子串，先命中先用）← `provider.compat` ←
+ * `model.compat`（字段级覆盖，undefined 不覆盖）。registry 物化后的模型已把供应商 / 渠道 compat 合进
+ * `model.compat`，所以显式配置永远胜过推断。
+ *
+ * - `sendInterleavedThinkingBeta`：官方端点开；表里的第三方端点关（DeepSeek 文档写明忽略 beta 头，其余
+ *   未写明接受，不发未知 beta 头最稳）；不在表里的主机（中转）只对 `claude*` 模型开——中转转发 Claude
+ *   时仍需要交错思考。
+ * - `sendCacheControl`：缺省开；DeepSeek 文档写明 `cache_control` 被忽略，关掉以减小请求体。
+ * - `adaptiveThinking` 只由目录 / 配置给（官方模型逐条写在 catalog/anthropic.json），表里不推断。
+ * - 缓存保留层级（1h TTL）等缓存能力在 cache-params.ts 的 `HOST_CACHE_CAPABILITIES`，不在这里。
+ * - OpenRouter：流式 usage 只出现在 `message_delta`，`applyAnthropicUsage` 本就按非 null 字段合并，
+ *   不需要开关（anthropic-compat.test.ts 核对）。
+ *
+ * 表里每一项都对应厂商文档或实测（docs/research/R1-models-protocols.md §2.1、docs/providers.md「渠道实测」）。
+ */
+export const ANTHROPIC_COMPAT_KEYS = [
+    "supportsCacheControlOnTools",
+    "supportsTemperatureWithThinking",
+    "adaptiveThinking",
+    "maxCacheBreakpoints",
+    "sendInterleavedThinkingBeta",
+    "sendCacheControl",
+];
+/** 未知主机的保守缺省（`sendInterleavedThinkingBeta` 另按模型 id 定，见 `hostDefaults`）。 */
+export const DEFAULT_ANTHROPIC_COMPAT = {
+    supportsCacheControlOnTools: true,
+    supportsTemperatureWithThinking: false,
+    adaptiveThinking: false,
+    maxCacheBreakpoints: 4,
+    sendInterleavedThinkingBeta: false,
+    sendCacheControl: true,
+};
+const THIRD_PARTY = { sendInterleavedThinkingBeta: false };
+/** 主机表：先命中先用。 */
+export const ANTHROPIC_HOST_RULES = [
+    { host: "api.anthropic.com", patch: { sendInterleavedThinkingBeta: true } },
+    {
+        host: "api.deepseek.com",
+        patch: { sendCacheControl: false, sendInterleavedThinkingBeta: false, adaptiveThinking: false },
+    },
+    { host: "open.bigmodel.cn", patch: THIRD_PARTY },
+    { host: "api.z.ai", patch: THIRD_PARTY },
+    { host: "api.moonshot.", patch: THIRD_PARTY },
+    { host: "dashscope", patch: THIRD_PARTY },
+    { host: "maas.aliyuncs.com", patch: THIRD_PARTY },
+    { host: "api.minimax", patch: THIRD_PARTY },
+    { host: "api.stepfun.", patch: THIRD_PARTY },
+    { host: "tokenhub.tencentmaas.com", patch: THIRD_PARTY },
+    { host: "volces.com", patch: THIRD_PARTY },
+    // openrouter.ai 不进表：按未知主机处理（anthropic/claude-* 带交错思考 beta）
+];
+function hostOf(baseUrl) {
+    try {
+        return new URL(baseUrl ?? "https://api.anthropic.com").hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/** 命中的主机规则（没有返回 undefined）。 */
+export function findAnthropicHostRule(baseUrl) {
+    const host = hostOf(baseUrl);
+    return host === "" ? undefined : ANTHROPIC_HOST_RULES.find((rule) => host.includes(rule.host));
+}
+/** 主机推断（不含显式配置）。未知主机：`claude*` 模型发交错思考 beta（中转转发 Claude）。 */
+export function hostDefaults(baseUrl, modelId) {
+    const rule = findAnthropicHostRule(baseUrl);
+    if (rule !== undefined)
+        return { ...DEFAULT_ANTHROPIC_COMPAT, ...rule.patch };
+    const claude = /(^|\/)claude/i.test(modelId);
+    return { ...DEFAULT_ANTHROPIC_COMPAT, sendInterleavedThinkingBeta: claude };
+}
+function pick(compat) {
+    const out = {};
+    for (const key of ANTHROPIC_COMPAT_KEYS) {
+        const value = compat?.[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** 完整 compat：主机推断 ← provider.compat ← model.compat。 */
+export function detectAnthropicCompat(model, provider) {
+    return {
+        ...hostDefaults(model.baseUrl ?? provider?.baseUrl, model.id),
+        ...pick(provider?.compat),
+        ...pick(model.compat),
+    };
+}