c0de-agent 1.7.0 → 1.9.0

package/dist/core/config.js

@@ -16,7 +16,10 @@ const DEFAULT_CONFIG = {
         keepRecentTokens: 4000,
         midTurnEnabled: false,
     },
-    tools: { enabled: ['read', 'write', 'edit', 'glob', 'grep', 'bash', 'todo', 'websearch'], disabled: [] },
+    tools: {
+        enabled: ['read', 'write', 'edit', 'glob', 'grep', 'bash', 'todo', 'websearch'],
+        disabled: [],
+    },
     plugins: { enabled: [] },
     mcpServers: [],
     slashCommands: { enabled: ['/compact', '/model', '/clear', '/help', '/fork', '/config'] },

package/dist/core/loop/compaction.d.ts

@@ -0,0 +1,31 @@
+import type { AgentEvent, AgentState } from '../../shared/types/agent.js';
+import type { Message } from '../../shared/types/message.js';
+import type { LoopDeps } from '../loop.js';
+/**
+ * 执行会话压缩并刷新 token 预算。
+ *
+ * 自动压缩（agentLoop 阈值触发）与手动 /compact 共用此逻辑：复用
+ * createSummarizer + runCompaction，压缩改写消息历史后标记下一段 trigger='compaction'。
+ *
+ * 成功时 yield 一条 text_delta 通知：手动 /compact 透传给用户；自动压缩由调用方
+ * 静默消费。失败时抛错，由调用方决定是否记录（自动压缩非致命，仅 console.warn）。
+ */
+export declare function compactContext(state: AgentState, deps: LoopDeps): AsyncGenerator<AgentEvent>;
+/**
+ * 响应式溢出恢复（reactive overflow compaction）：context-overflow 时压缩
+ * 历史并刷新内存消息，使下一轮重建出更小的上下文。仅在 assistant 尚未开始
+ * 输出（无 text delta、无 tool_call）时由调用方判定后调用。
+ *
+ * 成功返回 true（已压缩、已重载 messages，调用方 `continue` 重试本轮）；
+ * 压缩失败返回 false，由调用方回退到原始错误处理（透传 error 并停止）。
+ */
+export declare function recoverFromOverflow(state: AgentState, deps: LoopDeps): Promise<boolean>;
+/** 轮末压缩：turn-end 自动压缩（含死锁检测）+ mid-turn 压缩，复用 compactContext。
+ *
+ *  - turn-end：shouldCompact 触发时静默压缩；压缩后仍超阈值（典型成因 keepRecentTokens
+ *    本身已超 historyBudget）则标记死锁暂停后续自动压缩，并发出非致命警告（不中断循环）。
+ *    死锁在下一轮用户输入（agentLoop 重入）时重置。
+ *  - mid-turn：midTurnEnabled 单独 opt-in（默认关闭）时按 enabled:true 阈值静默压缩，
+ *    复用 shouldCompact 逻辑但不发 error/warning，压缩后刷新内存消息视图。
+ *  两者都静默消费 compactContext 的 text_delta 通知（不透传给用户）。 */
+export declare function runCompactionIfNeeded(state: AgentState, deps: LoopDeps, latestMessages: Message[]): AsyncGenerator<AgentEvent>;

package/dist/core/loop/compaction.js

@@ -0,0 +1,137 @@
+import { getMessages } from '../../session/message.js';
+import { createSummarizer, runCompaction } from '../compact.js';
+import { estimateBudget, shouldCompact } from '../context.js';
+/**
+ * 执行会话压缩并刷新 token 预算。
+ *
+ * 自动压缩（agentLoop 阈值触发）与手动 /compact 共用此逻辑：复用
+ * createSummarizer + runCompaction，压缩改写消息历史后标记下一段 trigger='compaction'。
+ *
+ * 成功时 yield 一条 text_delta 通知：手动 /compact 透传给用户；自动压缩由调用方
+ * 静默消费。失败时抛错，由调用方决定是否记录（自动压缩非致命，仅 console.warn）。
+ */
+export async function* compactContext(state, deps) {
+    // summarizer 优先用 compactionModel 覆盖，否则回退当前会话 provider/model。
+    const cm = state.compactionModel;
+    const summarizer = createSummarizer(deps.llmRegistry, cm ? cm.provider : state.config.provider, cm ? cm.model : state.config.model, { signal: state.abortController.signal });
+    const result = await runCompaction(deps.db, state.session.id, summarizer, {
+        keepRecentTokens: deps.config.compaction.keepRecentTokens,
+    });
+    // 压缩改写了消息历史 → 标记下一轮强制开新段（段边界）
+    state.pendingSegmentTrigger = 'compaction';
+    state.tokenBudget.used = estimateBudget(await getMessages(deps.db, state.session.id), state.calibrationFactor);
+    yield {
+        _tag: 'text_delta',
+        text: result.compacted
+            ? `Context compacted: ${result.compactedCount} messages summarized.`
+            : 'Nothing to compact yet.',
+    };
+    // 压缩成功后分发事件（spec: plugin-hooks `session:compact`）：
+    //  - session:compact hook（broadcast，插件可订阅；before=压缩条数，after=保留条数）
+    //  - compaction_done AgentEvent（前端/UI 可观测，携带 summary/archiveId）
+    // 仅在实际发生压缩时触发（nothing_to_compact 无 before/after 语义）。
+    if (result.compacted) {
+        if (deps.hookRunner) {
+            await deps.hookRunner.fireHooks('session:compact', {
+                before: result.compactedCount,
+                after: result.keptCount,
+            });
+        }
+        yield {
+            _tag: 'compaction_done',
+            summary: result.summary,
+            archiveId: result.archiveId,
+            compactedCount: result.compactedCount,
+            keptCount: result.keptCount,
+        };
+        // 压缩成功后初始化退化监测器：监测接下来 5 轮 assistant 回复，
+        // 若连续产生空回复（无实质文本且无 tool_call）则发出警告（不中断循环）。
+        state.postCompactionMonitor = { remaining: 5, noTextStreak: 0 };
+    }
+}
+/**
+ * 响应式溢出恢复（reactive overflow compaction）：context-overflow 时压缩
+ * 历史并刷新内存消息，使下一轮重建出更小的上下文。仅在 assistant 尚未开始
+ * 输出（无 text delta、无 tool_call）时由调用方判定后调用。
+ *
+ * 成功返回 true（已压缩、已重载 messages，调用方 `continue` 重试本轮）；
+ * 压缩失败返回 false，由调用方回退到原始错误处理（透传 error 并停止）。
+ */
+export async function recoverFromOverflow(state, deps) {
+    try {
+        for await (const _ev of compactContext(state, deps)) {
+            // 静默消费压缩通知（与自动压缩一致，不透传给用户）
+        }
+        state.messages = await getMessages(deps.db, state.session.id);
+        return true;
+    }
+    catch (e) {
+        console.warn('[overflow-recovery] compaction failed:', e instanceof Error ? e.message : String(e));
+        return false;
+    }
+}
+/** 轮末压缩：turn-end 自动压缩（含死锁检测）+ mid-turn 压缩，复用 compactContext。
+ *
+ *  - turn-end：shouldCompact 触发时静默压缩；压缩后仍超阈值（典型成因 keepRecentTokens
+ *    本身已超 historyBudget）则标记死锁暂停后续自动压缩，并发出非致命警告（不中断循环）。
+ *    死锁在下一轮用户输入（agentLoop 重入）时重置。
+ *  - mid-turn：midTurnEnabled 单独 opt-in（默认关闭）时按 enabled:true 阈值静默压缩，
+ *    复用 shouldCompact 逻辑但不发 error/warning，压缩后刷新内存消息视图。
+ *  两者都静默消费 compactContext 的 text_delta 通知（不透传给用户）。 */
+export async function* runCompactionIfNeeded(state, deps, latestMessages) {
+    // 死锁时跳过自动压缩：上一轮压缩已证明无法释放足够空间，重试只会无限循环。
+    if (!state.compactionDeadEnd &&
+        shouldCompact(latestMessages, state.tokenBudget, deps.config.compaction)) {
+        // 自动压缩：复用 compactContext；失败非致命，仅记录警告不中断主循环。
+        try {
+            for await (const _ev of compactContext(state, deps)) {
+                // 静默消费压缩通知事件，不透传给用户（保持自动压缩的原有静默语义）
+            }
+            // 进度保护：compactContext 已重算 state.tokenBudget.used。若压缩后仍超阈值
+            // （典型成因：keepRecentTokens 本身已超 historyBudget），压缩无法再释放足够
+            // 空间 → 标记死锁暂停后续自动压缩，并发出非致命警告（不中断循环）。
+            // 死锁在下一轮用户输入（agentLoop 重入）时重置。
+            const postMessages = await getMessages(deps.db, state.session.id);
+            if (shouldCompact(postMessages, state.tokenBudget, deps.config.compaction)) {
+                state.compactionDeadEnd = true;
+                yield {
+                    _tag: 'error',
+                    error: {
+                        _tag: 'unexpected',
+                        message: 'Compaction freed too little context to make progress (keepRecentTokens may exceed the threshold). Auto-compaction paused until the next user message.',
+                    },
+                };
+            }
+        }
+        catch (e) {
+            console.warn('[compaction] failed:', e instanceof Error ? e.message : String(e));
+        }
+    }
+    // —— 中轮压缩（mid-run compaction）——
+    // 单个 turn 内工具结果可能剧增 token（如长 bash 输出），在下一次 LLM 请求前
+    // 按 midTurnEnabled 检查阈值并静默压缩。与上方 turn-end 自动压缩独立：
+    // midTurnEnabled 是单独的 opt-in 闸门（默认关闭），以它为条件复用 shouldCompact
+    // 的阈值逻辑（传入 enabled:true 使阈值判定不受 compaction.enabled 影响），
+    // 便于在保留 turn-end 自动压缩行为的同时精确控制中轮压缩。
+    // 此时 state.tokenBudget.used 已是最新值（上方已重算；若 turn-end 压缩已触发，
+    // compactContext 内部也已重算），shouldCompact 只读取 budget，不依赖 messages。
+    if (deps.config.compaction.midTurnEnabled === true &&
+        !state.compactionDeadEnd &&
+        shouldCompact(latestMessages, state.tokenBudget, {
+            ...deps.config.compaction,
+            enabled: true,
+        })) {
+        // 中轮压缩静默执行：compactContext 内部已发 text_delta 通知，
+        // 不再 yield error/warning（与 turn-end 自动压缩的进度保护语义不同）。
+        try {
+            for await (const _ev of compactContext(state, deps)) {
+                // 静默消费压缩通知，不透传给用户
+            }
+            // 压缩改写了消息历史 → 刷新内存视图，供下一轮上下文重建使用
+            state.messages = await getMessages(deps.db, state.session.id);
+        }
+        catch (e) {
+            console.warn('[mid-turn-compaction] failed:', e instanceof Error ? e.message : String(e));
+        }
+    }
+}

package/dist/core/loop/persist.d.ts

@@ -0,0 +1,11 @@
+import type { AgentEvent, AgentState } from '../../shared/types/agent.js';
+import type { LoopDeps } from '../loop.js';
+import type { CollectedToolCall } from '../tool-exec.js';
+/** 持久化 assistant 消息 + 执行工具调用 + 持久化 tool result + 记录 metrics，
+ *  并透传 tool_call_start/tool_call_end/subagent 事件。
+ *
+ *  - 仅持久化/执行解析成功的调用（isParseErrorInput 过滤容错标记，避免 _raw/_parseError 落库）。
+ *  - tool_call_start 仅在入参解析完成后、携带真实入参时发射（前端拿到的第一帧即完整入参）。
+ *  - subagent 事件缓冲（runSubAgent → eventSink）在工具执行后 yield 出去（spec §4.5 step 7）。
+ *  - metrics 记录为 fire-and-forget，失败绝不阻塞 agent 主流程。 */
+export declare function persistAssistantAndTools(state: AgentState, deps: LoopDeps, collectedText: string[], validCalls: CollectedToolCall[]): AsyncGenerator<AgentEvent>;

package/dist/core/loop/persist.js

@@ -0,0 +1,107 @@
+import { createKanbanStore } from '../../kanban/index.js';
+import { appendMessage } from '../../session/message.js';
+import { inferToolMode, recordToolMetrics } from '../metrics.js';
+import { executeToolCalls } from '../tool-exec.js';
+import { runSubAgent } from './subagent.js';
+function toolResultToContent(toolCallId, toolName, result) {
+    return [{ _tag: 'tool_result', id: toolCallId, tool: toolName, output: result }];
+}
+/** 持久化 assistant 消息 + 执行工具调用 + 持久化 tool result + 记录 metrics，
+ *  并透传 tool_call_start/tool_call_end/subagent 事件。
+ *
+ *  - 仅持久化/执行解析成功的调用（isParseErrorInput 过滤容错标记，避免 _raw/_parseError 落库）。
+ *  - tool_call_start 仅在入参解析完成后、携带真实入参时发射（前端拿到的第一帧即完整入参）。
+ *  - subagent 事件缓冲（runSubAgent → eventSink）在工具执行后 yield 出去（spec §4.5 step 7）。
+ *  - metrics 记录为 fire-and-forget，失败绝不阻塞 agent 主流程。 */
+export async function* persistAssistantAndTools(state, deps, collectedText, validCalls) {
+    // subagent 事件缓冲：runSubAgent 通过 sink 推入事件，executeToolCalls 后 yield 出去
+    const subagentEvents = [];
+    const eventSink = (ev) => {
+        subagentEvents.push(ev);
+    };
+    const assistantContent = [];
+    if (collectedText.length > 0) {
+        assistantContent.push({ _tag: 'text', text: collectedText.join('') });
+    }
+    // 仅持久化解析成功的调用（携带真实入参）。解析失败的入参是容错标记，不能落库。
+    for (const tc of validCalls) {
+        assistantContent.push({
+            _tag: 'tool_call',
+            id: tc.id,
+            tool: tc.tool,
+            input: tc.input,
+        });
+    }
+    if (assistantContent.length > 0) {
+        const savedMsg = await appendMessage(deps.db, state.session.id, {
+            role: 'assistant',
+            content: assistantContent,
+        });
+        if (deps.hookRunner) {
+            await deps.hookRunner.fireHooks('message:after', { message: savedMsg });
+        }
+    }
+    // 工具调用卡只在入参解析完成后、携带真实入参时才向前端发射 tool_call_start。
+    // 这样前端拿到的第一帧就是可渲染的完整入参，不再出现空 pattern 半成品卡。
+    // 解析失败的调用不发射 start，其 tool_call_end 在前端无匹配 part 会被忽略，
+    // 因此解析失败在 UI 中不可见（模型会立即重试），错误仅反馈给模型并落库。
+    for (const tc of validCalls) {
+        yield { _tag: 'tool_call_start', id: tc.id, tool: tc.tool, input: tc.input };
+    }
+    // 仅执行解析成功的工具调用。解析失败的调用（isParseErrorInput 为真）对系统完全透明：
+    // 不执行、不持久化 tool result、不发 tool_call_start/end。其入参是 _parseError/_raw
+    // 容错标记，既不能执行也不能落库；若持久化为 orphan tool 消息（无对应 assistant
+    // tool_call），context.ts 的 sanitizeToolPairs 会在重建上下文时将其丢弃——即模型
+    // 永远收不到这个"错误反馈"，徒增一次注定被忽略的 DB 写。故让 parse-error 对模型
+    // 不可见：模型下轮基于已持久化的 assistant 文本/有效 tool_call 重新生成，通常能
+    // 修正一次性的流截断错误。
+    if (validCalls.length > 0) {
+        const toolExecStart = Date.now();
+        const results = await executeToolCalls(deps.toolRegistry, deps.permission, {
+            cwd: deps.cwd,
+            session: { id: state.session.id, cwd: deps.cwd },
+            abort: state.abortController.signal,
+            ...(deps.urlRegistry ? { urlRegistry: deps.urlRegistry } : {}),
+            ...(deps.debugSpawn ? { debugSpawn: deps.debugSpawn } : {}),
+            runSubAgent: (req) => runSubAgent({ ...deps, _subagentEventSink: eventSink }, state, req),
+            ...(deps._subagentYieldCollector ? { collectYield: deps._subagentYieldCollector } : {}),
+            // todo 工具状态通过 dependency-reversal hook 注入：get/set 直接读写
+            // state.todoPhases（in-memory），tool result 的 metadata.phases 充当
+            // 持久化层——createAgent 时从历史消息恢复。
+            todoState: {
+                get: () => state.todoPhases,
+                set: (phases) => {
+                    state.todoPhases = phases;
+                },
+            },
+            // kanban 工具通过 dependency-reversal 注入：per-project 的 db-backed store。
+            // 仅当 session 有 projectId 时启用（子 session 无 project 时不可用）。
+            ...(state.session.projectId
+                ? { kanbanStore: createKanbanStore(deps.db, state.session.projectId) }
+                : {}),
+        }, validCalls, deps.hookRunner);
+        const toolLatency = Date.now() - toolExecStart;
+        const metricsEnabled = deps.config.toolMetrics.enabled;
+        for (const { id, result } of results) {
+            yield { _tag: 'tool_call_end', id, result };
+            const tc = validCalls.find((c) => c.id === id);
+            if (tc) {
+                await appendMessage(deps.db, state.session.id, {
+                    role: 'tool',
+                    content: toolResultToContent(id, tc.tool, result),
+                });
+                // spec §16.5：记录工具执行结果供后续模式评估。
+                // fire-and-forget：记录失败绝不阻塞 agent 主流程。
+                if (metricsEnabled) {
+                    const mode = inferToolMode(tc.tool, tc.input);
+                    const success = result._tag === 'success' || result._tag === 'truncated';
+                    void recordToolMetrics(deps.db, state.config.model, tc.tool, mode, success, toolLatency).catch(() => { });
+                }
+            }
+        }
+    }
+    // yield 在本轮工具执行中收集的 subagent 事件（subagent_start/end）
+    for (const ev of subagentEvents) {
+        yield ev;
+    }
+}

package/dist/core/loop/segment.d.ts

@@ -0,0 +1,8 @@
+import type { AgentState } from '../../shared/types/agent.js';
+import type { ChatTool, FinishReason } from '../../shared/types/llm.js';
+import type { LoopDeps } from '../loop.js';
+import type { StreamCollectResult } from './stream-collect.js';
+/** 段管理：判断段边界（pending trigger / model / systemPrompt / tools 变化），
+ *  构造本轮 LLMCall 并 push 到当前段，持久化 segments。直接修改 state.segments（引用语义）。
+ *  trigger 判定用于新段元数据；needSegment 决定是否真正开新段（否则复用 activeSeg）。 */
+export declare function manageSegment(state: AgentState, deps: LoopDeps, systemPrompt: string, tools: ChatTool[], requestStartTime: number, totalLatency: number, collectedUsage: StreamCollectResult['usage'], collectedText: string[], collectedThinking: string[], truncated: FinishReason | null, firstTokenTime: number | null, contextWindow: number | undefined, computedCost: number): Promise<void>;

package/dist/core/loop/segment.js

@@ -0,0 +1,72 @@
+import { saveLLMSegments, segmentFingerprint } from '../../session/session.js';
+import { generateId } from '../../shared/index.js';
+/** 段管理：判断段边界（pending trigger / model / systemPrompt / tools 变化），
+ *  构造本轮 LLMCall 并 push 到当前段，持久化 segments。直接修改 state.segments（引用语义）。
+ *  trigger 判定用于新段元数据；needSegment 决定是否真正开新段（否则复用 activeSeg）。 */
+export async function manageSegment(state, deps, systemPrompt, tools, requestStartTime, totalLatency, collectedUsage, collectedText, collectedThinking, truncated, firstTokenTime, contextWindow, computedCost) {
+    // —— 段管理：判断是否开新段 ——
+    const fp = segmentFingerprint(systemPrompt, tools);
+    const activeSeg = state.segments[state.segments.length - 1];
+    const pendingTrigger = state.pendingSegmentTrigger;
+    let trigger;
+    if (pendingTrigger) {
+        trigger = pendingTrigger;
+        state.pendingSegmentTrigger = undefined;
+    }
+    else if (!activeSeg) {
+        trigger = 'initial';
+    }
+    else if (activeSeg.model !== state.config.model) {
+        trigger = 'model_change';
+    }
+    else if (activeSeg.fingerprint !== fp) {
+        trigger = activeSeg.systemPrompt !== systemPrompt ? 'system_prompt_change' : 'tools_change';
+    }
+    else {
+        trigger = 'user_confirmed'; // 占位，实际不会开段
+    }
+    const needSegment = !!pendingTrigger ||
+        !activeSeg ||
+        activeSeg.model !== state.config.model ||
+        activeSeg.fingerprint !== fp;
+    let currentSeg;
+    if (!needSegment && activeSeg) {
+        currentSeg = activeSeg;
+    }
+    else {
+        currentSeg = {
+            id: generateId(),
+            fingerprint: fp,
+            provider: state.config.provider,
+            model: state.config.model,
+            systemPrompt,
+            tools,
+            startedAt: requestStartTime,
+            trigger,
+            agentName: state.config.agentName,
+            ...(contextWindow !== undefined ? { contextWindow } : {}),
+            calls: [],
+        };
+        state.segments.push(currentSeg);
+    }
+    // —— 段内轻量 call ——
+    const call = {
+        id: generateId(),
+        timestamp: requestStartTime,
+        usage: {
+            input: collectedUsage?.inputTokens ?? 0,
+            output: collectedUsage?.outputTokens ?? 0,
+            ...(collectedUsage?.cacheRead !== undefined ? { cacheRead: collectedUsage.cacheRead } : {}),
+        },
+        latency: {
+            firstToken: firstTokenTime ? firstTokenTime - requestStartTime : totalLatency,
+            total: totalLatency,
+        },
+        cost: computedCost,
+        ...(collectedThinking.length > 0 ? { thinking: collectedThinking.join('') } : {}),
+        responseText: collectedText.join(''),
+        ...(truncated ? { finishReason: truncated } : {}),
+    };
+    currentSeg.calls.push(call);
+    await saveLLMSegments(deps.db, state.session.id, state.segments);
+}

package/dist/core/loop/stream-collect.d.ts

@@ -0,0 +1,47 @@
+import type { chatStream as llmChatStream } from '../../llm/provider.js';
+import type { AgentEvent, AgentState } from '../../shared/types/agent.js';
+import type { ChatRequest, FinishReason, StreamChunk } from '../../shared/types/llm.js';
+import type { LoopDeps } from '../loop.js';
+import type { CollectedToolCall } from '../tool-exec.js';
+/** 入参是否为协议层/loop 标记的解析失败（携带 _parseError / _raw 容错标记）。
+ * 这类入参是后端专用、只反馈给模型重试的，绝不能进入持久化消息或渲染层。 */
+export declare function isParseErrorInput(input: unknown): boolean;
+/** collectStreamChunks 的收集结果：单轮 LLM 流的全部产出与状态标记。 */
+export type StreamCollectResult = {
+    /** 完整 chunk 序列（供 provider:after hook 与 LLMDetail.responseChunks） */
+    chunks: StreamChunk[];
+    /** 文本片段累积 */
+    text: string[];
+    /** thinking 片段累积 */
+    thinking: string[];
+    /** 解析后的 tool call（含容错标记的入参） */
+    toolCalls: Map<string, CollectedToolCall>;
+    /** usage 统计（input/output/cacheRead） */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheRead?: number;
+    } | null;
+    /** 非正常停止原因（length / content_filter），完成分支据此判断是否被截断 */
+    truncated: FinishReason | null;
+    /** 流中出现过 error chunk */
+    hadError: boolean;
+    /** 首个非 done chunk 到达时间（latency.firstToken 用） */
+    firstTokenTime: number | null;
+    /** 更新后的溢出恢复标记：true 表示本轮已尝试过一次恢复（防无限循环） */
+    overflowCompacted: boolean;
+    /** 溢出恢复成功 → 调用方需 `continue turnLoop` 重试本轮 */
+    overflowRecovered: boolean;
+    /** 致命错误（abort / provider 抛错）→ 调用方应直接 return 终止 loop */
+    fatalError: boolean;
+};
+/** 流式收集 LLM 输出：遍历 streamFn 的 chunk，分类收集 text/thinking/tool_call/usage/done，
+ *  实时透传 text_delta/thinking/usage/error 给 agentLoop 的消费者（通过 yield）。
+ *
+ *  内部处理响应式溢出恢复：context-overflow 且尚未开始输出（无 text、无 tool_call）
+ *  时压缩历史，成功则置 overflowRecovered=true 由调用方 `continue turnLoop` 重试本轮。
+ *  致命错误（abort / provider 抛错）置 fatalError=true 由调用方终止 loop。
+ *
+ *  注意：tool_call_start 仅登记、不发射 AgentEvent——入参尚未到达，过早发射空入参
+ *  会让前端渲染半成品卡。tool_call_start 由 persistAssistantAndTools 在入参解析完成后统一发射。 */
+export declare function collectStreamChunks(state: AgentState, deps: LoopDeps, streamFn: typeof llmChatStream, request: ChatRequest, overflowCompacted: boolean): AsyncGenerator<AgentEvent, StreamCollectResult>;

package/dist/core/loop/stream-collect.js

@@ -0,0 +1,183 @@
+import { isContextOverflowFailure } from '../../llm/provider-error.js';
+import { isLLMError } from '../../llm/schema/errors.js';
+import { recoverFromOverflow } from './compaction.js';
+/** 入参是否为协议层/loop 标记的解析失败（携带 _parseError / _raw 容错标记）。
+ * 这类入参是后端专用、只反馈给模型重试的，绝不能进入持久化消息或渲染层。 */
+export function isParseErrorInput(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return false;
+    const obj = input;
+    return '_parseError' in obj || '_raw' in obj;
+}
+/** 解析 tool_call_end 的入参：JSON.parse + 容错标记。
+ *  解析成功返回原值；失败返回 { _parseError, _raw } 容错标记（与协议层 finishAll 一致），
+ *  供 isParseErrorInput 识别——这类入参只反馈给模型重试，绝不持久化或渲染。 */
+function parseToolCallArgs(finalArgs) {
+    try {
+        return JSON.parse(finalArgs);
+    }
+    catch (e) {
+        return {
+            _parseError: e instanceof Error ? e.message : String(e),
+            _raw: finalArgs,
+        };
+    }
+}
+/** 流式收集 LLM 输出：遍历 streamFn 的 chunk，分类收集 text/thinking/tool_call/usage/done，
+ *  实时透传 text_delta/thinking/usage/error 给 agentLoop 的消费者（通过 yield）。
+ *
+ *  内部处理响应式溢出恢复：context-overflow 且尚未开始输出（无 text、无 tool_call）
+ *  时压缩历史，成功则置 overflowRecovered=true 由调用方 `continue turnLoop` 重试本轮。
+ *  致命错误（abort / provider 抛错）置 fatalError=true 由调用方终止 loop。
+ *
+ *  注意：tool_call_start 仅登记、不发射 AgentEvent——入参尚未到达，过早发射空入参
+ *  会让前端渲染半成品卡。tool_call_start 由 persistAssistantAndTools 在入参解析完成后统一发射。 */
+export async function* collectStreamChunks(state, deps, streamFn, request, overflowCompacted) {
+    const chunks = [];
+    const text = [];
+    const thinking = [];
+    const toolCalls = new Map();
+    const toolCallArgs = new Map();
+    let usage = null;
+    let hadError = false;
+    // 非正常停止原因（length=被 max_tokens 截断, content_filter=被内容过滤）。
+    // 若在无 tool_call 的完成分支里仍非 null，说明回答被截断/过滤而非正常说完。
+    let truncated = null;
+    let firstTokenTime = null;
+    let recovered = overflowCompacted;
+    const finish = (over) => ({
+        chunks,
+        text,
+        thinking,
+        toolCalls,
+        usage,
+        truncated,
+        hadError,
+        firstTokenTime,
+        overflowCompacted: recovered,
+        overflowRecovered: false,
+        fatalError: false,
+        ...over,
+    });
+    try {
+        for await (const chunk of streamFn({
+            registry: deps.llmRegistry,
+            signal: state.abortController.signal,
+        }, request, { provider: state.config.provider, model: state.config.model })) {
+            if (firstTokenTime === null && chunk._tag !== 'done') {
+                firstTokenTime = Date.now();
+            }
+            chunks.push(chunk);
+            if (state.abortController.signal.aborted) {
+                yield { _tag: 'error', error: { _tag: 'aborted' } };
+                return finish({ fatalError: true });
+            }
+            switch (chunk._tag) {
+                case 'text':
+                    text.push(chunk.text);
+                    yield { _tag: 'text_delta', text: chunk.text };
+                    break;
+                case 'tool_call_start':
+                    // 仅登记，不立即发射 AgentEvent。此时入参尚未到达（流式 delta 累积中），
+                    // 过早发射空入参的 tool_call_start 会让前端渲染 "Glob · " 等半成品卡，
+                    // 且该 part 的入参之后也不会被纠正。tool_call_start 改在入参解析完成后、
+                    // 携带真实入参时统一发射（见 persistAssistantAndTools）。
+                    toolCalls.set(chunk.id, {
+                        id: chunk.id,
+                        tool: chunk.name,
+                        input: {},
+                    });
+                    toolCallArgs.set(chunk.id, '');
+                    break;
+                case 'tool_call_delta': {
+                    const existing = toolCallArgs.get(chunk.id) ?? '';
+                    toolCallArgs.set(chunk.id, existing + chunk.argumentsDelta);
+                    break;
+                }
+                case 'tool_call_end': {
+                    const finalArgs = chunk.argumentsFinal ?? toolCallArgs.get(chunk.id) ?? '{}';
+                    const tc = toolCalls.get(chunk.id);
+                    if (tc)
+                        tc.input = parseToolCallArgs(finalArgs);
+                    break;
+                }
+                case 'thinking':
+                    thinking.push(chunk.text);
+                    yield { _tag: 'thinking', text: chunk.text };
+                    break;
+                case 'usage':
+                    usage = {
+                        inputTokens: chunk.inputTokens,
+                        outputTokens: chunk.outputTokens,
+                        cacheRead: chunk.cacheRead,
+                    };
+                    yield {
+                        _tag: 'usage',
+                        input: chunk.inputTokens,
+                        output: chunk.outputTokens,
+                        cacheRead: chunk.cacheRead,
+                    };
+                    break;
+                case 'done':
+                    if (chunk.finishReason === 'length' || chunk.finishReason === 'content-filter') {
+                        truncated = chunk.finishReason;
+                    }
+                    break;
+                case 'error': {
+                    // 响应式溢出恢复：仅当尚未开始输出且未重试过时，压缩历史并重试本轮
+                    const isOverflow = chunk.error.classification === 'context-overflow';
+                    if (isOverflow && !recovered && text.length === 0 && toolCalls.size === 0) {
+                        recovered = true;
+                        if (await recoverFromOverflow(state, deps)) {
+                            return finish({ overflowRecovered: true });
+                        }
+                    }
+                    yield {
+                        _tag: 'error',
+                        error: {
+                            _tag: 'provider',
+                            message: chunk.error.message,
+                            retryable: chunk.error.retryable ?? false,
+                        },
+                    };
+                    hadError = true;
+                    break;
+                }
+            }
+        }
+    }
+    catch (err) {
+        // 响应式溢出恢复：provider 抛出的 context-overflow 是生产环境的实际路径
+        // （httpPost 在非 2xx 时抛出已分类的 LLMError），与上方 error chunk 分支同理。
+        if (isContextOverflowFailure(err) && !recovered && text.length === 0 && toolCalls.size === 0) {
+            recovered = true;
+            if (await recoverFromOverflow(state, deps)) {
+                return finish({ overflowRecovered: true });
+            }
+        }
+        const message = err instanceof Error
+            ? err.message
+            : isLLMError(err)
+                ? err.message
+                : typeof err === 'object' && err !== null && 'message' in err
+                    ? String(err.message)
+                    : String(err);
+        yield {
+            _tag: 'error',
+            error: {
+                _tag: 'unexpected',
+                message,
+            },
+        };
+        state.status = {
+            _tag: 'stopped',
+            reason: 'error',
+            error: {
+                _tag: 'unexpected',
+                message,
+            },
+        };
+        return finish({ fatalError: true });
+    }
+    return finish({});
+}

package/dist/core/loop/subagent.d.ts

@@ -0,0 +1,12 @@
+import type { AgentState } from '../../shared/types/agent.js';
+import type { SubAgentRequest, SubAgentResult } from '../../shared/types/tool.js';
+import type { LoopDeps } from '../loop.js';
+/** 运行一个按类型派发的子 agent（spec: multi-agent-design §4.5）。
+ *
+ *  Host 端实现：查 agentRegistry 获取 AgentDefinition → 创建隔离子 session（agentType 记录）
+ *  → 构建子 agent（专属 prompt + 受限工具集 + yield）→ 运行到 yield 或完成 → 返回结果。
+ *  发射 subagent_start/subagent_end 事件供父 agent 转发（spec §4.5 step 7）。
+ *  abort 链接父→子。maxRecursion 控制子 agent 能否再递归派生 task（spec §4.5 step 4）。
+ *  def.isolated 时在 git worktree 中运行，结束后把 delta 自动 apply 回父仓库（spec §4.6）。
+ *  request.background 时 fork 异步运行，立即返回 running（spec §4.7）。 */
+export declare function runSubAgent(deps: LoopDeps, parent: AgentState, request: SubAgentRequest): Promise<SubAgentResult>;