@armadra/agent 0.3.0 → 0.5.0

package/dist/drivers/runner.js

@@ -0,0 +1,388 @@
+/**
+ * ProcessRunner：把 AgentDriver 适配成 SubagentRunner（docs/wave5-plan.md §7.6、§5.3–§5.4）。[W5-E]
+ *
+ * 外部 CLI Agent 由此与 ama 子 Agent 共用 `task(agent=…)` 入口（D13）。`start()`：
+ * 1. 只在已信任目录里起（§5.4 信任；`claude -p` 会跳过目录信任对话框并执行项目 hooks）；
+ * 2. 模式夹到父会话当前模式（`agents.<id>.maxMode` 例外），再取驱动支持的不更宽的模式；
+ *    按候选顺序选第一个已安装且支持该模式的驱动（D14 优先级；oneshot 只在只读下可选）；
+ * 3. 会话级美元预算 `agents.sessionBudgetUsd` 用尽则不再起；
+ * 4. 子进程环境按 D16 清理；并发池（总 3 / claude 2）每回合取一个名额，排队可被 abort；
+ * 5. 权限请求只交给人（{@link askHuman}）；中断 / stop / 超时时挂起的请求回 cancelled；
+ * 6. 每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`；
+ *    只回 finalText + 工具摘要（原始事件不落盘，§5.4 敏感数据）；
+ * 7. 看门狗：单回合缺省 30 min；空闲 10 min 关进程（能续接的下次 `send` 以 resume 重开）。
+ */
+import { agentEntry } from "../config/types-w5.js";
+import { AmaError } from "../errors.js";
+import { defaultSetTimer } from "./base.js";
+import { buildChildEnv } from "./env.js";
+import { askHuman, clampMode, supportedMode } from "./permissions.js";
+export const RUN_TIMEOUT_MS = 30 * 60 * 1000;
+export const IDLE_CLOSE_MS = 10 * 60 * 1000;
+function toUsage(turn) {
+    const u = turn.usage ?? {};
+    const input = u.input ?? 0;
+    const output = u.output ?? 0;
+    const cacheRead = u.cacheRead ?? 0;
+    const usage = {
+        input,
+        output,
+        cacheRead,
+        cacheWrite: 0,
+        totalTokens: input + output + cacheRead,
+    };
+    if (u.costUsd !== undefined)
+        usage.cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: u.costUsd };
+    return usage;
+}
+function statusOf(turn, timedOut, stopped) {
+    if (timedOut)
+        return "failed";
+    switch (turn.stopReason) {
+        case "end_turn":
+        case "max_tokens":
+            return "completed";
+        case "max_turn_requests":
+            return "max_turns";
+        case "cancelled":
+            return stopped ? "aborted" : "failed";
+        case "refusal":
+            return "failed";
+    }
+}
+/** 最终报告：最终文本 + 工具摘要 / 触及文件（给协调者当资料，不是指令）。 */
+export function reportText(turn) {
+    const parts = [turn.finalText.trim()];
+    if (turn.toolSummary.length > 0)
+        parts.push(`工具调用：\n${turn.toolSummary.map((l) => `- ${l}`).join("\n")}`);
+    if (turn.filesTouched.length > 0)
+        parts.push(`修改的文件：\n${turn.filesTouched.map((f) => `- ${f}`).join("\n")}`);
+    return parts.filter((p) => p !== "").join("\n\n");
+}
+function failed(text, sessionId, runner) {
+    return {
+        text,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 },
+        stopReason: "error",
+        isError: true,
+        status: "failed",
+        ...(sessionId !== "" ? { sessionRef: { runner, sessionId } } : {}),
+    };
+}
+export class ProcessRunner {
+    deps;
+    id;
+    drivers;
+    constructor(driver, deps) {
+        this.deps = deps;
+        this.drivers = Array.isArray(driver) ? driver : [driver];
+        if (this.drivers.length === 0)
+            throw new AmaError("invalid_arguments", "ProcessRunner 需要至少一个驱动");
+        this.id = deps.id ?? this.drivers[0].agentId;
+    }
+    get agentId() {
+        return this.drivers[0].agentId;
+    }
+    unattended() {
+        const u = this.deps.unattended;
+        return typeof u === "function" ? u() : u === true;
+    }
+    /** 选驱动：第一个已安装、且支持（不宽于）目标模式的候选。 */
+    async choose(mode) {
+        const reasons = [];
+        for (const driver of this.drivers) {
+            const probe = await driver.probe();
+            if (!probe.installed) {
+                reasons.push(`${driver.kind} 未安装`);
+                continue;
+            }
+            const usable = supportedMode(mode, probe.capabilities.modes);
+            if (usable === undefined) {
+                reasons.push(`${driver.kind} 不支持「${mode}」`);
+                continue;
+            }
+            const warning = probe.warning;
+            return {
+                driver,
+                mode: usable,
+                capabilities: probe.capabilities,
+                ...(warning !== undefined ? { warning } : {}),
+            };
+        }
+        throw new AmaError("agent_unavailable", `外部 Agent ${this.id} 不可用（${reasons.join("；")}）`);
+    }
+    async start(request) {
+        if (!this.deps.trusted(request.cwd))
+            throw new AmaError("agent_untrusted", `目录 ${request.cwd} 尚未被 ama 信任，不能在这里启动外部 Agent（它会执行项目里的 hooks 与配置）；先运行 ama trust`);
+        const budget = this.deps.config?.sessionBudgetUsd;
+        if (budget !== undefined && (this.deps.store?.totalUsd() ?? 0) >= budget)
+            throw new AmaError("budget_exhausted", `本会话外部 Agent 预算 $${budget} 已用尽`);
+        const entry = agentEntry(this.deps.config, this.agentId);
+        const mode = clampMode(request.mode, this.deps.parentMode?.(), entry?.maxMode);
+        const chosen = await this.choose(mode);
+        const handle = new ProcessHandle(this, chosen, request, {
+            ...this.deps,
+            model: request.model ?? entry?.model,
+            unattended: this.unattended(),
+        });
+        await handle.open(request.resume);
+        handle.begin();
+        return handle;
+    }
+    /** ProcessHandle 用。 */
+    get options() {
+        return this.deps;
+    }
+}
+class ProcessHandle {
+    runner;
+    chosen;
+    request;
+    deps;
+    session;
+    sessionId = "";
+    chain = Promise.resolve(failed("尚未运行", "", ""));
+    busy = false;
+    turns = 0;
+    stopped = false;
+    lifetime = new AbortController();
+    clearIdle;
+    agent;
+    constructor(runner, chosen, request, deps) {
+        this.runner = runner;
+        this.chosen = chosen;
+        this.request = request;
+        this.deps = deps;
+        this.agent = runner.agentId;
+        const onAbort = () => void this.stop();
+        if (request.signal.aborted)
+            this.lifetime.abort();
+        else
+            request.signal.addEventListener("abort", onAbort, { once: true });
+        if (chosen.warning !== undefined)
+            request.onEvent({ type: "notice", level: "warn", text: chosen.warning });
+        if (chosen.mode !== request.mode)
+            request.onEvent({
+                type: "notice",
+                level: "info",
+                text: `${this.agent} 以「${chosen.mode}」模式运行（请求的是「${request.mode}」，外部 Agent 不得比 ama 当前模式宽）`,
+            });
+    }
+    get id() {
+        return this.sessionId;
+    }
+    async open(resume) {
+        const env = buildChildEnv(this.deps.env, this.agent, this.deps.config);
+        const session = await this.chosen.driver.open({
+            cwd: this.request.cwd,
+            mode: this.chosen.mode,
+            env,
+            signal: this.lifetime.signal,
+            unattended: this.deps.unattended,
+            ...(this.deps.model !== undefined ? { model: this.deps.model } : {}),
+            ...(resume !== undefined ? { resume } : {}),
+            ...(this.request.budgetUsd !== undefined ? { budgetUsd: this.request.budgetUsd } : {}),
+        });
+        this.session = session;
+        this.sessionId = session.sessionId;
+        this.deps.store?.recordSession({
+            agent: this.agent,
+            runner: this.chosen.driver.kind,
+            sessionId: session.sessionId,
+            cwd: this.request.cwd,
+            ...(this.request.taskId !== undefined ? { taskId: this.request.taskId } : {}),
+        });
+    }
+    /** 第一回合。 */
+    begin() {
+        this.chain = this.runTurn(this.request.prompt);
+    }
+    async send(text) {
+        if (this.stopped)
+            throw new AmaError("agent_closed", `${this.agent} 已停止`);
+        if (this.busy && this.session?.steer !== undefined && this.chosen.capabilities.steer) {
+            await this.session.steer([{ type: "text", text }]);
+            return;
+        }
+        this.chain = this.chain.then(() => this.runTurn(text));
+    }
+    wait() {
+        return this.chain;
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.lifetime.abort();
+        this.clearIdle?.();
+        const session = this.session;
+        this.session = undefined;
+        if (session !== undefined) {
+            await session.cancel().catch(() => undefined);
+            await session.close().catch(() => undefined);
+        }
+    }
+    emit(event) {
+        try {
+            this.request.onEvent(event);
+        }
+        catch (error) {
+            this.deps.log?.("warn", `subagent onEvent failed: ${String(error)}`);
+        }
+    }
+    onDriverEvent(event, turnCost, cancel) {
+        switch (event.type) {
+            case "message_delta":
+                this.emit({ type: "text", delta: event.text });
+                return;
+            case "thought_delta":
+                this.emit({ type: "thought", delta: event.text });
+                return;
+            case "tool_call":
+                if (event.status === "pending")
+                    return;
+                this.emit({
+                    type: "tool",
+                    toolName: event.title,
+                    status: event.status === "in_progress"
+                        ? "started"
+                        : event.status === "failed"
+                            ? "failed"
+                            : "completed",
+                });
+                return;
+            case "notice":
+                this.emit({ type: "notice", level: event.level, text: event.text });
+                return;
+            case "usage":
+                if (event.costUsd !== undefined) {
+                    turnCost.usd = event.costUsd;
+                    const budget = this.request.budgetUsd;
+                    const session = this.deps.config?.sessionBudgetUsd;
+                    const spent = this.deps.store?.totalUsd() ?? 0;
+                    if ((budget !== undefined && turnCost.usd > budget) ||
+                        (session !== undefined && spent + turnCost.usd > session)) {
+                        this.emit({
+                            type: "notice",
+                            level: "warn",
+                            text: `${this.agent} 超出美元预算，已中断`,
+                        });
+                        cancel();
+                    }
+                }
+                return;
+            default:
+                return;
+        }
+    }
+    /** 关掉空闲进程后再续聊：能续接的以 resume 重开。 */
+    async ensureSession() {
+        if (this.session !== undefined)
+            return this.session;
+        if (this.chosen.capabilities.resume === "none" || this.sessionId === "")
+            throw new AmaError("agent_closed", `${this.agent} 会话已因空闲关闭且不支持续接`);
+        await this.open(this.sessionId);
+        return this.session;
+    }
+    async runTurn(text) {
+        if (this.stopped)
+            return failed(`${this.agent} 已停止`, this.sessionId, this.runner.id);
+        this.clearIdle?.();
+        let release;
+        const setTimer = this.deps.setTimer ?? defaultSetTimer;
+        let timedOut = false;
+        try {
+            release = await this.deps.pool.acquire(this.agent, this.lifetime.signal);
+            const session = this.session ?? (await this.ensureSession());
+            this.busy = true;
+            this.turns += 1;
+            this.emit({ type: "turn", turn: this.turns });
+            const turnCost = { usd: 0 };
+            const cancel = () => void session.cancel();
+            const clearTimeout = setTimer(() => {
+                timedOut = true;
+                this.emit({ type: "notice", level: "warn", text: `${this.agent} 运行超时，已中断` });
+                cancel();
+            }, this.deps.timeoutMs ?? RUN_TIMEOUT_MS);
+            const onAbort = () => cancel();
+            this.lifetime.signal.addEventListener("abort", onAbort, { once: true });
+            let turn;
+            try {
+                turn = await session.prompt([{ type: "text", text }], {
+                    onEvent: (e) => this.onDriverEvent(e, turnCost, cancel),
+                    onPermission: (req, signal) => askHuman(req, {
+                        agent: this.agent,
+                        sessionId: session.sessionId,
+                        unattended: this.deps.unattended,
+                        approve: this.deps.approve,
+                        signal: AbortSignal.any([signal, this.lifetime.signal]),
+                        ...(this.request.taskId !== undefined ? { taskId: this.request.taskId } : {}),
+                    }),
+                });
+            }
+            finally {
+                clearTimeout();
+                this.lifetime.signal.removeEventListener("abort", onAbort);
+                this.busy = false;
+            }
+            this.sessionId = session.sessionId;
+            const usage = toUsage(turn);
+            const unit = this.chosen.capabilities.usage;
+            if (unit !== "none") {
+                const amount = unit === "usd"
+                    ? (turn.usage?.costUsd ?? turnCost.usd)
+                    : unit === "tokens"
+                        ? usage.input + usage.output
+                        : 1;
+                this.deps.store?.recordUsage({
+                    agent: this.agent,
+                    sessionId: this.sessionId,
+                    unit,
+                    amount,
+                    ...(usage.totalTokens > 0 ? { tokens: usage.totalTokens } : {}),
+                });
+                this.emit({ type: "usage", usage, unit, amount });
+            }
+            const status = statusOf(turn, timedOut, this.stopped);
+            this.armIdle();
+            return {
+                text: timedOut
+                    ? `${this.agent} 运行超时被中断。${turn.finalText !== "" ? `\n\n${reportText(turn)}` : ""}`
+                    : reportText(turn),
+                usage,
+                stopReason: timedOut ? "timeout" : turn.stopReason,
+                isError: status === "failed",
+                status,
+                sessionRef: { runner: this.runner.id, sessionId: this.sessionId },
+            };
+        }
+        catch (error) {
+            if (this.stopped)
+                return {
+                    ...failed(`${this.agent} 已停止`, this.sessionId, this.runner.id),
+                    status: "aborted",
+                };
+            return failed(`${this.agent} 失败：${error.message}`, this.sessionId, this.runner.id);
+        }
+        finally {
+            release?.();
+        }
+    }
+    /** 空闲一段时间关进程（不占资源）；能续接的下次 send 再起。 */
+    armIdle() {
+        if (this.chosen.capabilities.resume === "none")
+            return;
+        const setTimer = this.deps.setTimer ?? defaultSetTimer;
+        this.clearIdle = setTimer(() => {
+            if (this.busy || this.stopped)
+                return;
+            const session = this.session;
+            this.session = undefined;
+            void session?.close().catch(() => undefined);
+        }, this.deps.idleMs ?? IDLE_CLOSE_MS);
+    }
+}
+/** §10.2 的签名：`createProcessRunner(driver, { approve, pool, store, … })`。 */
+export function createProcessRunner(driver, deps) {
+    return new ProcessRunner(driver, deps);
+}

package/dist/drivers/store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 外部 Agent 的会话引用与记账（docs/wave5-plan.md §5.4 记账 / 敏感数据，session-format 登记）。[W5-E]
+ *
+ * - `custom{ama.agent-session}`：`{ agent, runner, sessionId, cwd?, taskId? }`——外部 CLI 自己的
+ *   会话 id，续聊（`taskId` / resume）用；不含原始事件与转录。
+ * - `custom{ama.agent-usage}`：每个回合结束一条 `{ agent, sessionId, unit, amount, tokens? }`；
+ *   无美元单位的按各自单位记，不换算。
+ * - `SessionStats.external` 由 {@link createExternalStatsExtension} 从活动分支汇总（扩展点
+ *   `contributeStats`，主会话才装）。
+ */
+import type { SessionExtension } from "../agent/session-extensions.js";
+import type { ExternalAgentStats, ExternalUsageUnit } from "../agent/types-w5.js";
+import type { SessionEntry } from "../session/types.js";
+export declare const AGENT_SESSION_CUSTOM = "ama.agent-session";
+export declare const AGENT_USAGE_CUSTOM = "ama.agent-usage";
+export interface AgentSessionRecord {
+    agent: string;
+    /** 驱动种类（`claude-stream` / `codex-app-server` / `acp` …）或宿主 runner id。 */
+    runner: string;
+    sessionId: string;
+    cwd?: string;
+    taskId?: string;
+}
+export interface AgentUsageRecord {
+    agent: string;
+    sessionId: string;
+    unit: ExternalUsageUnit;
+    amount: number;
+    tokens?: number;
+}
+/** 会话一侧的最小接口（`ToolContext.session` 或 SessionCore 都能提供）。 */
+export interface AgentStoreBackend {
+    appendCustom(customType: string, data: unknown): void;
+    /** 活动分支上的条目（求会话级美元合计；不给则只算本进程记下的）。 */
+    entries?(): readonly SessionEntry[];
+}
+export interface AgentStore {
+    recordSession(record: AgentSessionRecord): void;
+    recordUsage(record: AgentUsageRecord): void;
+    /** 本会话外部 Agent 的美元合计（`agents.sessionBudgetUsd`）。 */
+    totalUsd(): number;
+    /** 最近一条该 Agent（可按 taskId 过滤）的会话引用。 */
+    lastSession(agent: string, taskId?: string): AgentSessionRecord | undefined;
+}
+export declare function createAgentStore(backend: AgentStoreBackend): AgentStore;
+/** 活动分支上的 `ama.agent-usage` → `SessionStats.external`；没有外部运行时 undefined。 */
+export declare function aggregateExternal(entries: readonly SessionEntry[]): ExternalAgentStats | undefined;
+/** 会话扩展：`getStats()` 时补 `external`（只装在主会话）。 */
+export declare function createExternalStatsExtension(entries: () => readonly SessionEntry[]): SessionExtension;

package/dist/drivers/store.js

@@ -0,0 +1,91 @@
+/**
+ * 外部 Agent 的会话引用与记账（docs/wave5-plan.md §5.4 记账 / 敏感数据，session-format 登记）。[W5-E]
+ *
+ * - `custom{ama.agent-session}`：`{ agent, runner, sessionId, cwd?, taskId? }`——外部 CLI 自己的
+ *   会话 id，续聊（`taskId` / resume）用；不含原始事件与转录。
+ * - `custom{ama.agent-usage}`：每个回合结束一条 `{ agent, sessionId, unit, amount, tokens? }`；
+ *   无美元单位的按各自单位记，不换算。
+ * - `SessionStats.external` 由 {@link createExternalStatsExtension} 从活动分支汇总（扩展点
+ *   `contributeStats`，主会话才装）。
+ */
+export const AGENT_SESSION_CUSTOM = "ama.agent-session";
+export const AGENT_USAGE_CUSTOM = "ama.agent-usage";
+function customs(entries, type) {
+    const out = [];
+    for (const entry of entries)
+        if (entry.type === "custom" && entry.customType === type && typeof entry.data === "object")
+            out.push(entry.data);
+    return out;
+}
+export function createAgentStore(backend) {
+    const sessions = [];
+    let usd = 0;
+    const all = () => {
+        const entries = backend.entries?.();
+        if (entries === undefined)
+            return undefined;
+        return {
+            sessions: customs(entries, AGENT_SESSION_CUSTOM),
+            usage: customs(entries, AGENT_USAGE_CUSTOM),
+        };
+    };
+    return {
+        recordSession(record) {
+            sessions.push(record);
+            backend.appendCustom(AGENT_SESSION_CUSTOM, record);
+        },
+        recordUsage(record) {
+            if (record.unit === "usd")
+                usd += record.amount;
+            backend.appendCustom(AGENT_USAGE_CUSTOM, record);
+        },
+        totalUsd() {
+            const persisted = all();
+            if (persisted === undefined)
+                return usd;
+            return persisted.usage.reduce((sum, u) => (u.unit === "usd" ? sum + u.amount : sum), 0);
+        },
+        lastSession(agent, taskId) {
+            const list = all()?.sessions ?? sessions;
+            for (let i = list.length - 1; i >= 0; i--) {
+                const r = list[i];
+                if (r.agent === agent && (taskId === undefined || r.taskId === taskId))
+                    return r;
+            }
+            return undefined;
+        },
+    };
+}
+/** 活动分支上的 `ama.agent-usage` → `SessionStats.external`；没有外部运行时 undefined。 */
+export function aggregateExternal(entries) {
+    const usage = customs(entries, AGENT_USAGE_CUSTOM);
+    if (usage.length === 0)
+        return undefined;
+    const byAgent = {};
+    for (const u of usage) {
+        if (typeof u.agent !== "string" || typeof u.amount !== "number")
+            continue;
+        const row = (byAgent[u.agent] ??= { runs: 0, unit: u.unit, amount: 0 });
+        row.runs += 1;
+        // 同一 Agent 换了单位（换了驱动）时以最新单位重新计
+        if (row.unit !== u.unit) {
+            row.unit = u.unit;
+            row.amount = 0;
+        }
+        row.amount += u.amount;
+        if (typeof u.tokens === "number")
+            row.tokens = (row.tokens ?? 0) + u.tokens;
+    }
+    return { byAgent };
+}
+/** 会话扩展：`getStats()` 时补 `external`（只装在主会话）。 */
+export function createExternalStatsExtension(entries) {
+    return {
+        id: "external-agents",
+        contributeStats(stats) {
+            const external = aggregateExternal(entries());
+            if (external !== undefined)
+                stats.external = external;
+        },
+    };
+}

package/dist/drivers/turn.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 一个回合的结果汇总（各驱动共用）。[W5-E]
+ *
+ * 驱动把归一化后的 {@link DriverEvent} 交给收集器：它转发给 `onEvent`，同时累计最终文本、
+ * 工具摘要（≤ 20 行，§5.2）、触及的文件（edit / delete / move 类工具的 locations）与用量。
+ * 原始事件只在内存里流过，不落盘（§5.4 敏感数据）。
+ */
+import type { AcpToolKind, DriverEvent, DriverTurnResult } from "./types.js";
+export declare const TOOL_SUMMARY_LINES = 20;
+interface ToolState {
+    title: string;
+    kind: AcpToolKind;
+    status: "pending" | "in_progress" | "completed" | "failed";
+    locations: string[];
+}
+export declare class TurnCollector {
+    private readonly onEvent;
+    private text;
+    private readonly tools;
+    private readonly order;
+    private usage;
+    constructor(onEvent: (event: DriverEvent) => void);
+    /** 归一化事件：累计后转发给 onEvent。 */
+    push(event: DriverEvent): void;
+    /** 工具调用的最近状态（驱动做 tool_call_update 时补全标题与种类）。 */
+    tool(id: string): Readonly<ToolState> | undefined;
+    /** 回合结束时的累计用量合并（`result.usage` 等）。 */
+    mergeUsage(usage: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        costUsd?: number;
+    }): void;
+    get finalText(): string;
+    /** 原生协议以整条消息给出最终文本时覆盖（流式增量与整条只取其一）。 */
+    setFinalText(text: string): void;
+    result(stopReason: DriverTurnResult["stopReason"]): DriverTurnResult;
+}
+/** 单行、截断（标题与摘要用）。 */
+export declare function oneLine(text: string, max?: number): string;
+export {};

package/dist/drivers/turn.js

@@ -0,0 +1,99 @@
+/**
+ * 一个回合的结果汇总（各驱动共用）。[W5-E]
+ *
+ * 驱动把归一化后的 {@link DriverEvent} 交给收集器：它转发给 `onEvent`，同时累计最终文本、
+ * 工具摘要（≤ 20 行，§5.2）、触及的文件（edit / delete / move 类工具的 locations）与用量。
+ * 原始事件只在内存里流过，不落盘（§5.4 敏感数据）。
+ */
+export const TOOL_SUMMARY_LINES = 20;
+const WRITE_KINDS = new Set(["edit", "delete", "move"]);
+export class TurnCollector {
+    onEvent;
+    text = "";
+    tools = new Map();
+    order = [];
+    usage = {};
+    constructor(onEvent) {
+        this.onEvent = onEvent;
+    }
+    /** 归一化事件：累计后转发给 onEvent。 */
+    push(event) {
+        switch (event.type) {
+            case "message_delta":
+                this.text += event.text;
+                break;
+            case "tool_call": {
+                const known = this.tools.get(event.id);
+                const next = {
+                    title: event.title !== "" ? event.title : (known?.title ?? event.id),
+                    kind: event.kind,
+                    status: event.status,
+                    locations: event.locations ?? known?.locations ?? [],
+                };
+                if (known === undefined)
+                    this.order.push(event.id);
+                this.tools.set(event.id, next);
+                break;
+            }
+            case "usage":
+                this.mergeUsage(event);
+                break;
+            default:
+                break;
+        }
+        this.onEvent(event);
+    }
+    /** 工具调用的最近状态（驱动做 tool_call_update 时补全标题与种类）。 */
+    tool(id) {
+        return this.tools.get(id);
+    }
+    /** 回合结束时的累计用量合并（`result.usage` 等）。 */
+    mergeUsage(usage) {
+        if (usage.input !== undefined)
+            this.usage.input = usage.input;
+        if (usage.output !== undefined)
+            this.usage.output = usage.output;
+        if (usage.cacheRead !== undefined)
+            this.usage.cacheRead = usage.cacheRead;
+        if (usage.costUsd !== undefined)
+            this.usage.costUsd = usage.costUsd;
+    }
+    get finalText() {
+        return this.text;
+    }
+    /** 原生协议以整条消息给出最终文本时覆盖（流式增量与整条只取其一）。 */
+    setFinalText(text) {
+        this.text = text;
+    }
+    result(stopReason) {
+        const files = new Set();
+        for (const tool of this.tools.values())
+            if (WRITE_KINDS.has(tool.kind) && tool.status === "completed")
+                for (const path of tool.locations)
+                    files.add(path);
+        const lines = this.order.map((id) => {
+            const tool = this.tools.get(id);
+            return `${tool.status === "failed" ? "✗" : tool.status === "completed" ? "✓" : "…"} ${tool.kind} ${tool.title}`;
+        });
+        const summary = lines.length > TOOL_SUMMARY_LINES
+            ? [
+                ...lines.slice(0, TOOL_SUMMARY_LINES - 1),
+                `… 另有 ${lines.length - TOOL_SUMMARY_LINES + 1} 次工具调用`,
+            ]
+            : lines;
+        const result = {
+            stopReason,
+            finalText: this.text,
+            filesTouched: [...files],
+            toolSummary: summary,
+        };
+        if (Object.keys(this.usage).length > 0)
+            result.usage = { ...this.usage };
+        return result;
+    }
+}
+/** 单行、截断（标题与摘要用）。 */
+export function oneLine(text, max = 120) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}