c0de-agent 1.0.0 → 1.2.0

package/dist/core/loop.js

@@ -1,4 +1,5 @@
 import { chatStream as llmChatStream } from '../llm/provider.js';
+import { isContextOverflowFailure } from '../llm/provider-error.js';
 import { resolveRoute } from '../llm/registry.js';
 import { isLLMError } from '../llm/schema/errors.js';
 import { detectProjectInfo } from '../project/detect.js';
@@ -9,13 +10,46 @@ import { estimateTokens } from '../session/token.js';
 import { generateId } from '../shared/index.js';
 import { createAgent, runAgent } from './agent.js';
 import { createSummarizer, runCompaction } from './compact.js';
-import { calibrateEstimate, estimateBudget, shouldCompact } from './context.js';
+import { calibrateEstimate, createTokenBudget, estimateBudget, shouldCompact } from './context.js';
 import { DEFAULT_EDIT_MODE, getToolMetrics, inferToolMode, recordToolMetrics, selectBestMode, } from './metrics.js';
 import { buildDynamicPrompt, createPromptRegistry, registerPromptSection, } from './prompt-registry.js';
 import { drainSteering } from './steering.js';
 import { executeToolCalls } from './tool-exec.js';
 import { applyPatchToParent, captureBaseline, captureDeltaPatch, createWorktree, removeWorktree, } from './worktree.js';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** provider 未声明 contextWindow 时回填的保守下限（避免估计过大不压缩、过小过度压缩）。 */
+const FALLBACK_CONTEXT_WINDOW = 32_000;
+/** 每个 agent 已解析的有效 contextWindow 缓存（真实值或保守估计）。
+ *  避免每轮重复解析/告警，并防止估计值随每轮 input token 抖动导致预算基准漂移。 */
+const effectiveContextWindowCache = new WeakMap();
+/**
+ * 解析本轮有效 contextWindow，确保 shouldCompact 始终有合理基准：
+ *  - provider 已声明（capabilities.contextWindow 为正数）→ 原样采用，不改变正常配置行为。
+ *  - 缺失（provider 未注册 / 模型未知 / 未声明 contextWindow）→ 以本轮真实 input token
+ *    为下限回填保守估计 max(inputTokens × 2, FALLBACK_CONTEXT_WINDOW)，并在首次回填时
+ *    console.warn 告警（非致命——provider 未配置 contextWindow 不是致命错误）。
+ *
+ * 结果按 agent 缓存：首轮回填后后续轮次复用同一估计值，告警仅触发一次，
+ * 使 contextWindow 缺失时不再静默退化压缩阈值。
+ */
+function resolveEffectiveContextWindow(state, raw, inputTokens, provider, model) {
+    // provider 已声明有效 contextWindow → 直接采用并缓存
+    if (typeof raw === 'number' && raw > 0) {
+        effectiveContextWindowCache.set(state, raw);
+        return raw;
+    }
+    // 已缓存（首轮已回填的估计值）→ 复用，避免重复告警与基准抖动
+    const cached = effectiveContextWindowCache.get(state);
+    if (cached !== undefined)
+        return cached;
+    // 缺失：以本轮真实 input token 作下限回填保守估计
+    const estimated = Math.max(inputTokens * 2, FALLBACK_CONTEXT_WINDOW);
+    console.warn(`[loop] provider "${provider}" / model "${model}" 未声明 contextWindow，` +
+        `使用保守估算值 ${estimated}（基于本轮 input token）。压缩阈值可能不准——` +
+        `建议在 provider 配置中声明 contextWindow。`);
+    effectiveContextWindowCache.set(state, estimated);
+    return estimated;
+}
 async function waitForResume(state) {
     while (true) {
         await sleep(100);
@@ -194,19 +228,479 @@ function isParseErrorInput(input) {
     const obj = input;
     return '_parseError' in obj || '_raw' in obj;
 }
+/**
+ * 执行会话压缩并刷新 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 并停止）。
+ */
+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;
+    }
+}
+/** 解析 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 在入参解析完成后统一发射。 */
+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({});
+}
+/** 段管理：判断段边界（pending trigger / model / systemPrompt / tools 变化），
+ *  构造本轮 LLMCall 并 push 到当前段，持久化 segments。直接修改 state.segments（引用语义）。
+ *  trigger 判定用于新段元数据；needSegment 决定是否真正开新段（否则复用 activeSeg）。 */
+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);
+}
+/** 持久化 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 主流程。 */
+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 } : {}),
+        }, 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;
+    }
+}
+/** 轮末压缩：turn-end 自动压缩（含死锁检测）+ mid-turn 压缩，复用 compactContext。
+ *
+ *  - turn-end：shouldCompact 触发时静默压缩；压缩后仍超阈值（典型成因 keepRecentTokens
+ *    本身已超 historyBudget）则标记死锁暂停后续自动压缩，并发出非致命警告（不中断循环）。
+ *    死锁在下一轮用户输入（agentLoop 重入）时重置。
+ *  - mid-turn：midTurnEnabled 单独 opt-in（默认关闭）时按 enabled:true 阈值静默压缩，
+ *    复用 shouldCompact 逻辑但不发 error/warning，压缩后刷新内存消息视图。
+ *  两者都静默消费 compactContext 的 text_delta 通知（不透传给用户）。 */
+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));
+        }
+    }
+}
 export async function* agentLoop(state, deps) {
     const maxTurns = state.config.maxTurns ?? 50;
     const streamFn = deps.chatStream ?? llmChatStream;
+    // 响应式溢出恢复：context-overflow 时压缩后重试，最多 1 次（防无限循环）
+    let overflowCompacted = false;
+    // 新一轮用户输入：重置压缩死锁标记（新消息改变上下文，压缩或许能再次生效）
+    state.compactionDeadEnd = false;
     for (let turn = 0; turn < maxTurns; turn++) {
         if (state.abortController.signal.aborted) {
             yield { _tag: 'error', error: { _tag: 'aborted' } };
             return;
         }
-        // subagent 事件缓冲：runSubAgent 通过 sink 推入事件，executeToolCalls 后 yield 出去
-        const subagentEvents = [];
-        const eventSink = (ev) => {
-            subagentEvents.push(ev);
-        };
         if (state.status._tag === 'paused') {
             state.status = { _tag: 'running', turnCount: turn };
             yield { _tag: 'status_change', status: state.status };
@@ -297,137 +791,18 @@ export async function* agentLoop(state, deps) {
             }
             request = hookResult.request;
         }
-        // 总是收集完整 chunk 序列：既供 hookRunner 触发 provider:after，
-        // 也是 LLMDetail.responseChunks 的来源（用于调用详情展示）。
-        const collectedChunks = [];
-        const collectedText = [];
-        const collectedThinking = [];
-        const collectedToolCalls = new Map();
-        const toolCallArgs = new Map();
-        let collectedUsage = null;
-        let hadError = false;
-        // 非正常停止原因（length=被 max_tokens 截断, content_filter=被内容过滤）。
-        // 若在无 tool_call 的完成分支里仍非 null，说明回答被截断/过滤而非正常说完。
-        let truncated = null;
         const requestStartTime = Date.now();
-        let firstTokenTime = null;
-        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();
-                }
-                collectedChunks.push(chunk);
-                if (state.abortController.signal.aborted) {
-                    yield { _tag: 'error', error: { _tag: 'aborted' } };
-                    return;
-                }
-                switch (chunk._tag) {
-                    case 'text':
-                        collectedText.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 改在入参解析完成后、
-                        // 携带真实入参时统一发射（见本轮流结束后的处理）。
-                        collectedToolCalls.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 id = chunk.id;
-                        const finalArgs = chunk.argumentsFinal ?? toolCallArgs.get(id) ?? '{}';
-                        let parsed = {};
-                        try {
-                            parsed = JSON.parse(finalArgs);
-                        }
-                        catch (e) {
-                            // 与协议层 finishAll 的容错标记保持一致：同时带 _parseError（可读）与 _raw。
-                            parsed = {
-                                _parseError: e instanceof Error ? e.message : String(e),
-                                _raw: finalArgs,
-                            };
-                        }
-                        const tc = collectedToolCalls.get(id);
-                        if (tc)
-                            tc.input = parsed;
-                        break;
-                    }
-                    case 'thinking':
-                        collectedThinking.push(chunk.text);
-                        yield { _tag: 'thinking', text: chunk.text };
-                        break;
-                    case 'usage':
-                        collectedUsage = {
-                            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':
-                        yield {
-                            _tag: 'error',
-                            error: {
-                                _tag: 'provider',
-                                message: chunk.error.message,
-                                retryable: chunk.error.retryable ?? false,
-                            },
-                        };
-                        hadError = true;
-                        break;
-                }
-            }
-        }
-        catch (err) {
-            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,
-                },
-            };
+        // —— 流式收集 LLM 输出（透传 text_delta/thinking/usage/error，内部处理溢出恢复）——
+        const collected = yield* collectStreamChunks(state, deps, streamFn, request, overflowCompacted);
+        overflowCompacted = collected.overflowCompacted;
+        // 溢出恢复成功 → 压缩历史后重试本轮（collectStreamChunks 已 reload messages）
+        if (collected.overflowRecovered)
+            continue;
+        // 致命错误（abort / provider 抛错）→ collectStreamChunks 已 yield error 并设状态，直接终止
+        if (collected.fatalError)
             return;
-        }
         if (deps.hookRunner) {
-            await deps.hookRunner.fireHooks('provider:after', { request, chunks: collectedChunks });
+            await deps.hookRunner.fireHooks('provider:after', { request, chunks: collected.chunks });
         }
         const totalLatency = Date.now() - requestStartTime;
         let contextWindow;
@@ -435,8 +810,8 @@ export async function* agentLoop(state, deps) {
         try {
             const { capabilities } = resolveRoute(deps.llmRegistry, state.config.provider, state.config.model);
             contextWindow = capabilities.contextWindow;
-            const inputTokens = collectedUsage?.inputTokens ?? 0;
-            const outputTokens = collectedUsage?.outputTokens ?? 0;
+            const inputTokens = collected.usage?.inputTokens ?? 0;
+            const outputTokens = collected.usage?.outputTokens ?? 0;
             computedCost =
                 (inputTokens / 1000) * capabilities.costPer1kInput +
                     (outputTokens / 1000) * capabilities.costPer1kOutput;
@@ -444,73 +819,21 @@ export async function* agentLoop(state, deps) {
         catch {
             // provider 未注册或模型未知：保留 contextWindow=undefined、cost=0
         }
-        // —— 段管理：判断是否开新段 ——
-        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);
+        // —— contextWindow 兜底 + token 预算同步 ——
+        // provider 未声明 contextWindow 时回填保守估计（见 resolveEffectiveContextWindow），
+        // 并把 token 预算同步到真实/估计 contextWindow（总数变化时重算，保留 used），
+        // 使后续 shouldCompact 判断有合理基准，避免压缩阈值静默退化。
+        const effectiveWindow = resolveEffectiveContextWindow(state, contextWindow, collected.usage?.inputTokens ?? 0, state.config.provider, state.config.model);
+        contextWindow = effectiveWindow;
+        if (state.tokenBudget.total !== effectiveWindow) {
+            const used = state.tokenBudget.used;
+            state.tokenBudget = createTokenBudget(effectiveWindow);
+            state.tokenBudget.used = used;
+        }
+        // —— 段管理：判断段边界 + 构造 LLMCall + 持久化 ——
+        await manageSegment(state, deps, systemPrompt, tools, requestStartTime, totalLatency, collected.usage, collected.text, collected.thinking, collected.truncated, collected.firstTokenTime, contextWindow, computedCost);
         yield { _tag: 'llm_detail' };
-        if (hadError) {
+        if (collected.hadError) {
             state.status = { _tag: 'stopped', reason: 'error' };
             return;
         }
@@ -518,87 +841,44 @@ export async function* agentLoop(state, deps) {
         // 会把单个 tool call 的 arguments 流式片段拆成多个独立 delta，每片
         // id/name 为空——这些碎片无法执行，且其空 id 在下一轮发回 provider 时
         // 触发 "invalid tool_call_id"。这里在持久化/执行前将其丢弃。
-        const validToolCalls = Array.from(collectedToolCalls.values()).filter((c) => c.id.length > 0 && c.tool.length > 0);
+        const validToolCalls = Array.from(collected.toolCalls.values()).filter((c) => c.id.length > 0 && c.tool.length > 0);
         // 区分入参解析成功 / 失败的调用。解析失败（模型输出不完整 JSON，常见于流被截断）
-        // 的调用对系统完全透明：不执行、不持久化、不发前端事件（见下方工具执行块说明），
+        // 的调用对系统完全透明：不执行、不持久化、不发前端事件（见 persistAssistantAndTools），
         // 仅保留解析成功的调用供执行与持久化，避免 _raw/_parseError 容错标记泄漏。
         const validCalls = validToolCalls.filter((tc) => !isParseErrorInput(tc.input));
-        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 });
+        // —— 压缩退化监测（spec: degradation-monitor）——
+        // 压缩成功后监测接下来若干轮 assistant 回复：连续产生空回复（无实质文本且
+        // 无 tool_call）说明 agent 可能在"沉默退化"。仅发警告、不中断循环、不设
+        // hadError；remaining 耗尽即清除监测器。有 tool_call 的轮次不算退化
+        // （正常的工具调用轮次不是"沉默"）。参考 progress guard 的非致命 error 模式。
+        const monitor = state.postCompactionMonitor;
+        if (monitor && monitor.remaining > 0) {
+            const replyText = collected.text.join('').trim();
+            const noMeaningfulOutput = replyText.length < 10 && validCalls.length === 0;
+            if (noMeaningfulOutput) {
+                monitor.noTextStreak += 1;
             }
-        }
-        // 工具调用卡只在入参解析完成后、携带真实入参时才向前端发射 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 } : {}),
-            }, 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(() => { });
-                    }
-                }
+            monitor.remaining -= 1;
+            if (monitor.noTextStreak >= 3) {
+                yield {
+                    _tag: 'error',
+                    error: {
+                        _tag: 'unexpected',
+                        message: 'Agent may be degraded after compaction (no meaningful output for 3 consecutive turns)',
+                    },
+                };
+            }
+            if (monitor.remaining === 0) {
+                state.postCompactionMonitor = undefined;
             }
         }
-        // yield 在本轮工具执行中收集的 subagent 事件（subagent_start/end）
-        for (const ev of subagentEvents) {
-            yield ev;
-        }
+        // —— 持久化 assistant + 执行工具 + 透传 tool_call/subagent 事件 ——
+        yield* persistAssistantAndTools(state, deps, collected.text, validCalls);
         if (validToolCalls.length === 0) {
             // finish_reason=length/content_filter 表示响应被截断或被内容过滤，而非正常说完。
-            // 若当作 completed，被截断的半截回答会静默成功（用户看到“中断但无报错”）。
-            if (truncated !== null) {
-                const message = truncated === 'length'
+            // 若当作 completed，被截断的半截回答会静默成功（用户看到"中断但无报错"）。
+            if (collected.truncated !== null) {
+                const message = collected.truncated === 'length'
                     ? 'Response truncated: the model hit max_tokens before finishing (finish_reason=length)'
                     : 'Response filtered by content policy (finish_reason=content_filter)';
                 yield { _tag: 'error', error: { _tag: 'unexpected', message } };
@@ -612,32 +892,16 @@ export async function* agentLoop(state, deps) {
         const latestMessages = await getMessages(deps.db, state.session.id);
         // 校准估算系数：本轮真实 input token（system prompt + 工具描述 + 消息序列全口径）
         // 反算 estimateTokens 的系统性系数，反哺 used/fitToBudget 的裁剪与压缩判断。
-        if (collectedUsage && collectedUsage.inputTokens > 0) {
+        if (collected.usage && collected.usage.inputTokens > 0) {
             const estimatedRequest = estimateTokens(systemPrompt) +
                 tools.reduce((sum, t) => sum + estimateTokens(JSON.stringify(t)), 0) +
                 estimateTokens(JSON.stringify(chatMessages));
-            state.calibrationFactor = calibrateEstimate(state.calibrationFactor, estimatedRequest, collectedUsage.inputTokens);
+            state.calibrationFactor = calibrateEstimate(state.calibrationFactor, estimatedRequest, collected.usage.inputTokens);
         }
         state.tokenBudget.used = estimateBudget(latestMessages, state.calibrationFactor);
         state.messages = latestMessages;
-        if (shouldCompact(latestMessages, state.tokenBudget, deps.config.compaction)) {
-            const summarizer = state.compactionModel
-                ? createSummarizer(deps.llmRegistry, state.compactionModel.provider, state.compactionModel.model, { signal: state.abortController.signal })
-                : createSummarizer(deps.llmRegistry, state.config.provider, state.config.model, {
-                    signal: state.abortController.signal,
-                });
-            try {
-                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);
-            }
-            catch {
-                // Compaction failure is non-fatal
-            }
-        }
+        // —— 轮末压缩（turn-end 自动压缩 + mid-turn 压缩）——
+        yield* runCompactionIfNeeded(state, deps, latestMessages);
     }
     yield {
         _tag: 'error',