@deepwhale/coding-agent 1.0.0

package/dist/agent/session-adapter.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Session ↔ Tool Loop 适配器（Sprint 1a）
+ *
+ * 把 tool loop 的 ToolLoopStep 事件 → SessionEvent JSONL 持久化，
+ * 同时支持从已有 JSONL 重建 messages 列表（让 LLM 看到"上次聊到哪"）。
+ *
+ * Sprint 1a 范围（极简）：
+ *   - assistant step → 'assistant' event（保留 tool_calls）
+ *   - tool step → 'tool' event（保留 tool_call_id + name + result）
+ *   - 不持久化 user 消息（REPL 层自己 append 'user'）
+ *   - 不持久化 limit/error 事件（runtime 状态，不进 LLM context）
+ *   - 不做 compaction、加密、压缩、分片（v1.5+）
+ *
+ * 重建 messages 规则（让 LLM 续聊）：
+ *   - 遍历 events，遇到 user/assistant/tool 都 push 成 ChatMessage
+ *   - tool 消息需保留 tool_call_id
+ *   - assistant 消息需保留 tool_calls
+ *   - 系统提示由 caller 单独组装（repl.ts 拼），不存 JSONL
+ *
+ * @module @deepwhale/coding-agent/session-adapter
+ */
+import type { ChatMessage } from '@deepwhale/llm';
+import type { SessionEvent, SessionWriter, SessionReader } from '@deepwhale/core';
+import type { ToolLoopStep } from './tool-loop.js';
+/**
+ * 把 tool loop step 翻译成 SessionEvent。
+ *
+ * 只翻译能放进 LLM context 的 step:
+ *   - 'assistant' → { kind: 'assistant', ts, content, tool_calls }
+ *   - 'tool'      → { kind: 'tool', ts, tool_call_id, name, result }
+ *
+ * limit/error 是 runtime 状态，**不**持久化（避免重启时把它们当 LLM context 喂回）。
+ */
+export declare function toolLoopStepToSessionEvent(step: ToolLoopStep): SessionEvent | null;
+/**
+ * 把 SessionEvent 列表重建为 LLM 的 ChatMessage 列表（用于 LLM 续聊）。
+ *
+ * Sprint 1c P2 修复: 过滤 dangling tool_call transcript.
+ *
+ * 背景: 二次启动恢复时, JSONL 里可能存在 "assistant(tool_calls=[c2]) 但
+ * tool(c2) 没落盘" 的孤立 assistant (crash 写完 assistant 还没写 tool result
+ * 就被杀). 旧实现直接 push 这个 assistant → LLM continuation 看到无对应
+ * tool result 的 tool_call, 形成非法 transcript, OpenAI API 拒收.
+ *
+ * 修复规则 (按 user 拍板 2026-06-04):
+ *   1. assistant(tool_calls): 只有在下一个 user/assistant 前, 所有
+ *      tool_call_id 都有对应 tool event, 才保留 (整个 assistant message)
+ *   2. tool: 只有它的 tool_call_id 属于"当前未结算的 assistant tool_calls",
+ *      才保留; 否则丢 (孤儿)
+ *   3. 普通 assistant(content) / user 不受影响
+ *   4. **不改写 JSONL events**, 只在重建 messages 时过滤 — 后续补 tool
+ *      result 后完整 tool_call 组自然重新合法化 (Sprint 1c P2 spec)
+ *
+ * 实现: 延迟 push 模式 — assistant(tool_calls) 进入 buffer, tool events
+ * 配对删除 pending. user/assistant 边界触发 buffer 结算: pending 非空
+ * → 整体 roll back (不 push); pending 空 → push buffer.
+ *
+ * Sprint 1c-revive-2-D-5+ reload 修复 (review P1, 2026-06-04):
+ *   - JSONL 中的 'compaction' event 必须 **replay** 到 LLM context, 否则
+ *     reload 后 messages 会从原始 user/assistant/tool events 重建, 旧
+ *     compacted head 重新出现, 上下文不被压缩 (内存压缩成功但 reload
+ *     失效 = P1).
+ *   - replay 协议: 见到 'compaction' event 时, 把当前累积 messages 的
+ *     `replaced_range[0..replaced_range[1])` 段 (按 JSONL 累积 index)
+ *     替换为 1 条 system summary.
+ *   - index 空间 (拍板 2026-06-04 review): compact() 入参 messages 来自
+ *     caller 的 working 列表. REPL 路径下 working = loadSession() 返回
+ *     的 JSONL 累积 (纯 user/assistant/tool) + REPL startup 拼的 system
+ *     prompt. 拍板 compact() 只对 working[0..end] 操作, 不含外部 system
+ *     prompt, 所以 replaced_range 索引的就是 "JSONL 累积 messages" 的
+ *     index. reload 时 messages 仍按 JSONL 累积重建, replaced_range 同
+ *     index 空间, 不偏移. (多个 'compaction' event 串行: 第 1 次 applied
+ *     后累积 messages = 1 summary + N tail, 第 2 次 compact 入参就是
+ *     reload 后的累积, index 重新从 0 计 — protocol 自洽.)
+ *   - 'compaction_paused' event: 不入 messages. caller 决定是否 reset
+ *     latch; UI/footer 可读 paused event 显式提示.
+ */
+export declare function sessionEventsToMessages(events: ReadonlyArray<SessionEvent>): ChatMessage[];
+/**
+ * 写一个 user event 到 session。
+ * Sprint 1a 简化：user 消息也走 SessionWriter（统一审计）。
+ */
+export declare function appendUserEvent(writer: SessionWriter, content: string, ts?: number): Promise<void>;
+/**
+ * 写一条 'compaction' event 到 session (Sprint 1c-revive-2-D-5-1 拍板).
+ *
+ * 用途: agent-compaction.ts 在 runCompactionWithLatch 返 kind='ok' 时调,
+ * 把 summary 拍板落盘 (供 reload 重建 messages 时知道哪段被总结过).
+ *
+ * 拍板: SessionReader 读到 kind='compaction' 时**不**重放进 LLM context
+ * (跟 sessionEventsToMessages L132 'system' 跳过 一致 — compaction event 是 metadata,
+ *  不是 LLM 看到的对话轮次).
+ */
+export declare function appendCompactionEvent(writer: SessionWriter, summary: string, replacedRange: readonly [number, number], meta?: Record<string, unknown>, ts?: number): Promise<void>;
+/**
+ * 写一条 'compaction_paused' event 到 session (Sprint 1c-revive-2-D-5-2 拍板).
+ *
+ * 用途: agent-compaction.ts 在 CompactionState latch 触发时调,
+ * 记录"自动暂停, 防 death loop" 拍板 (供 reload 时 caller 知道状态).
+ *
+ * 拍板: SessionReader 读到 kind='compaction_paused' 时**不**重放进 LLM context
+ * (caller 该决定是否 reset CompactionState / 改 summaryFn / 改 config).
+ */
+export declare function appendCompactionPausedEvent(writer: SessionWriter, consecutiveFailures: number, reason: string, lastError: string, meta?: Record<string, unknown>, ts?: number): Promise<void>;
+/**
+ * 把 tool loop 跑完后产出的 steps 全部落盘（assistant + tool）。
+ * limit/error 跳过（toSessionEvent 返回 null 时不 append）。
+ */
+export declare function persistToolLoopSteps(writer: SessionWriter, steps: ReadonlyArray<ToolLoopStep>): Promise<void>;
+/**
+ * 加载已有 session 并重建 messages。
+ *
+ * Sprint 1b: 内部自动调 reader.truncate() 把 partial last line 清掉。
+ * 之前 caller 必须自己记得调, Sprint 1a 全部漏调 → partial line 累积,
+ * 下次 append 拼坏 JSON。Sprint 1b 闭环在 adapter 里, 3 个 mode (repl/print/rpc) 自动受益。
+ *
+ * 行为契约:
+ * - 加载完整 events + 重建 messages
+ * - 若文件末尾有 partial line(崩溃恢复), 自动 truncate
+ * - truncate 失败不抛(不阻塞 agent 启动, 跟 Sprint 1a 容错语义一致)
+ *
+ * Sprint 1a 简化:返回 (events, messages) 两份数据, caller 决定要不要 ignore events。
+ */
+export declare function loadSession(reader: SessionReader): Promise<{
+    events: ReadonlyArray<SessionEvent>;
+    messages: ChatMessage[];
+}>;
+/**
+ * 写一个 'verification' event 到 session (Sprint 1c-revive-2-D-11-3, 2026-06-04).
+ *
+ * 调用场景: `deepwhale --verify` 或 REPL `/verify` 跑完, 把 VerificationReport
+ * 摘要写 1 条到 session JSONL. 跟 `appendUserEvent` / `appendCompactionEvent` 模式一致.
+ *
+ * 字段 (跟 core/src/session/jsonl.ts 'verification' union 一致):
+ *   - status: 整体结果 passed / failed
+ *   - durationMs: 整体耗时
+ *   - command_count: 跑的 step 数
+ *   - failed_count: 失败 step 数
+ *   - summary: 人类可读 summary (来自 formatter.buildSummaryAndNext)
+ *   - meta: 可选扩展 (e.g. log file path, git sha)
+ *
+ * 不变量 (跟其它 event 写入一致):
+ *   - ts 默认 Date.now(), 单测可注入
+ *   - 走 SessionWriter.append → fsync 串行化, 顺序保证
+ *   - 'verification' 是 metadata, reload session 时 sessionEventsToMessages 跳过
+ *     (跟 compaction_paused 同语义), 不污染 LLM 看到的 messages
+ */
+export declare function appendVerificationEvent(writer: SessionWriter, args: {
+    status: 'passed' | 'failed';
+    durationMs: number;
+    commandCount: number;
+    failedCount: number;
+    summary: string;
+    meta?: Record<string, unknown>;
+    ts?: number;
+}): Promise<void>;
+/**
+ * 写一条 'policy_decision' event (Sprint 1c-revive-3-D-13, 2026-06-05).
+ * 拍板 (用户 2026-06-05): 'allow' 不调本函数 (避免 JSONL 刷爆). 只对
+ *   'deny' / 'require_confirmation' / 'user_approved' / 'user_denied' 4 个
+ *   终态落盘.
+ *
+ * 字段拍板:
+ *   - tool_call_id: 跟后续 'tool' event 配对 (reload 时 audit trace 完整)
+ *   - argsDigest: sha256:<12hex>, 不存原始 args
+ *   - reason: 已过 sanitize (长度 / 换行 / NUL, 拍板红线: 不存 secret)
+ */
+export declare function appendPolicyDecisionEvent(writer: SessionWriter, args: {
+    tool_call_id: string;
+    name: string;
+    decision: 'deny' | 'require_confirmation' | 'user_approved' | 'user_denied';
+    argsDigest: string;
+    reason?: string;
+    meta?: Record<string, unknown>;
+    ts?: number;
+}): Promise<void>;
+//# sourceMappingURL=session-adapter.d.ts.map

package/dist/agent/session-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-adapter.d.ts","sourceRoot":"","sources":["../../src/agent/session-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,IAAI,CA2BlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,WAAW,EAAE,CA+F1F;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,MAAmB,GACtB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,EAAE,GAAE,MAAmB,GACtB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,aAAa,EACrB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,EAAE,GAAE,MAAmB,GACtB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAAC,QAAQ,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CAS3E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE;IACJ,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,GACA,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,eAAe,GAAG,aAAa,CAAC;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,GACA,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/agent/session-adapter.js

@@ -0,0 +1,340 @@
+/**
+ * Session ↔ Tool Loop 适配器（Sprint 1a）
+ *
+ * 把 tool loop 的 ToolLoopStep 事件 → SessionEvent JSONL 持久化，
+ * 同时支持从已有 JSONL 重建 messages 列表（让 LLM 看到"上次聊到哪"）。
+ *
+ * Sprint 1a 范围（极简）：
+ *   - assistant step → 'assistant' event（保留 tool_calls）
+ *   - tool step → 'tool' event（保留 tool_call_id + name + result）
+ *   - 不持久化 user 消息（REPL 层自己 append 'user'）
+ *   - 不持久化 limit/error 事件（runtime 状态，不进 LLM context）
+ *   - 不做 compaction、加密、压缩、分片（v1.5+）
+ *
+ * 重建 messages 规则（让 LLM 续聊）：
+ *   - 遍历 events，遇到 user/assistant/tool 都 push 成 ChatMessage
+ *   - tool 消息需保留 tool_call_id
+ *   - assistant 消息需保留 tool_calls
+ *   - 系统提示由 caller 单独组装（repl.ts 拼），不存 JSONL
+ *
+ * @module @deepwhale/coding-agent/session-adapter
+ */
+/**
+ * 把 tool loop step 翻译成 SessionEvent。
+ *
+ * 只翻译能放进 LLM context 的 step:
+ *   - 'assistant' → { kind: 'assistant', ts, content, tool_calls }
+ *   - 'tool'      → { kind: 'tool', ts, tool_call_id, name, result }
+ *
+ * limit/error 是 runtime 状态，**不**持久化（避免重启时把它们当 LLM context 喂回）。
+ */
+export function toolLoopStepToSessionEvent(step) {
+    if (step.kind === 'assistant') {
+        return {
+            kind: 'assistant',
+            ts: step.ts,
+            content: step.message.content,
+            ...(step.message.tool_calls ? { tool_calls: [...step.message.tool_calls] } : {}),
+        };
+    }
+    if (step.kind === 'tool') {
+        return {
+            kind: 'tool',
+            ts: step.ts,
+            tool_call_id: step.tool_call.id,
+            name: step.tool_call.name,
+            result: {
+                success: step.result.success,
+                content: step.result.content,
+                ...(step.result.success === false && step.result.error !== undefined
+                    ? { error: step.result.error }
+                    : {}),
+            },
+            duration_ms: step.duration_ms,
+        };
+    }
+    // 'limit' / 'error' 不持久化
+    return null;
+}
+/**
+ * 把 SessionEvent 列表重建为 LLM 的 ChatMessage 列表（用于 LLM 续聊）。
+ *
+ * Sprint 1c P2 修复: 过滤 dangling tool_call transcript.
+ *
+ * 背景: 二次启动恢复时, JSONL 里可能存在 "assistant(tool_calls=[c2]) 但
+ * tool(c2) 没落盘" 的孤立 assistant (crash 写完 assistant 还没写 tool result
+ * 就被杀). 旧实现直接 push 这个 assistant → LLM continuation 看到无对应
+ * tool result 的 tool_call, 形成非法 transcript, OpenAI API 拒收.
+ *
+ * 修复规则 (按 user 拍板 2026-06-04):
+ *   1. assistant(tool_calls): 只有在下一个 user/assistant 前, 所有
+ *      tool_call_id 都有对应 tool event, 才保留 (整个 assistant message)
+ *   2. tool: 只有它的 tool_call_id 属于"当前未结算的 assistant tool_calls",
+ *      才保留; 否则丢 (孤儿)
+ *   3. 普通 assistant(content) / user 不受影响
+ *   4. **不改写 JSONL events**, 只在重建 messages 时过滤 — 后续补 tool
+ *      result 后完整 tool_call 组自然重新合法化 (Sprint 1c P2 spec)
+ *
+ * 实现: 延迟 push 模式 — assistant(tool_calls) 进入 buffer, tool events
+ * 配对删除 pending. user/assistant 边界触发 buffer 结算: pending 非空
+ * → 整体 roll back (不 push); pending 空 → push buffer.
+ *
+ * Sprint 1c-revive-2-D-5+ reload 修复 (review P1, 2026-06-04):
+ *   - JSONL 中的 'compaction' event 必须 **replay** 到 LLM context, 否则
+ *     reload 后 messages 会从原始 user/assistant/tool events 重建, 旧
+ *     compacted head 重新出现, 上下文不被压缩 (内存压缩成功但 reload
+ *     失效 = P1).
+ *   - replay 协议: 见到 'compaction' event 时, 把当前累积 messages 的
+ *     `replaced_range[0..replaced_range[1])` 段 (按 JSONL 累积 index)
+ *     替换为 1 条 system summary.
+ *   - index 空间 (拍板 2026-06-04 review): compact() 入参 messages 来自
+ *     caller 的 working 列表. REPL 路径下 working = loadSession() 返回
+ *     的 JSONL 累积 (纯 user/assistant/tool) + REPL startup 拼的 system
+ *     prompt. 拍板 compact() 只对 working[0..end] 操作, 不含外部 system
+ *     prompt, 所以 replaced_range 索引的就是 "JSONL 累积 messages" 的
+ *     index. reload 时 messages 仍按 JSONL 累积重建, replaced_range 同
+ *     index 空间, 不偏移. (多个 'compaction' event 串行: 第 1 次 applied
+ *     后累积 messages = 1 summary + N tail, 第 2 次 compact 入参就是
+ *     reload 后的累积, index 重新从 0 计 — protocol 自洽.)
+ *   - 'compaction_paused' event: 不入 messages. caller 决定是否 reset
+ *     latch; UI/footer 可读 paused event 显式提示.
+ */
+export function sessionEventsToMessages(events) {
+    // Sprint 1c P2 修复: 过滤 dangling tool_call transcript. 延迟 push 模式
+    // — assistant(tool_calls) 进入 buffer, tool events 配对删除 pending.
+    // user/assistant 边界触发 flushBuffer 结算: pending 非空 → 整体 roll
+    // back; pending 空 → push buffer.
+    const out = [];
+    let buffer = [];
+    let pendingToolCalls = new Set();
+    const flushBuffer = () => {
+        if (pendingToolCalls.size > 0) {
+            // 上一个 assistant(tool_calls) 未完成 (user/assistant 边界), 整个 roll back
+            buffer = [];
+        }
+        else {
+            out.push(...buffer);
+            buffer = [];
+        }
+        pendingToolCalls = new Set();
+    };
+    for (const ev of events) {
+        if (ev.kind === 'user') {
+            flushBuffer();
+            out.push({ role: 'user', content: ev.content });
+        }
+        else if (ev.kind === 'assistant') {
+            flushBuffer();
+            if (ev.tool_calls && ev.tool_calls.length > 0) {
+                // 进入延迟 push 模式
+                pendingToolCalls = new Set(ev.tool_calls.map((tc) => tc.id));
+                const msg = { role: 'assistant', content: ev.content };
+                msg.tool_calls = [...ev.tool_calls];
+                buffer.push(msg);
+            }
+            else {
+                // 普通 assistant(content) 无 tool_calls, 立即 commit
+                out.push({ role: 'assistant', content: ev.content });
+            }
+        }
+        else if (ev.kind === 'tool') {
+            if (pendingToolCalls.has(ev.tool_call_id)) {
+                pendingToolCalls.delete(ev.tool_call_id);
+                buffer.push({
+                    role: 'tool',
+                    content: ev.result.content,
+                    tool_call_id: ev.tool_call_id,
+                    name: ev.name,
+                });
+            }
+            // 孤儿 tool (没匹配 assistant tool_call): 丢 — 不会出现无主 tool message
+        }
+        else if (ev.kind === 'compaction') {
+            // Sprint 1c-revive-2-D-5+ (review P1 修复, 2026-06-04): replay 到 messages.
+            // 协议 (see header comment L88-L102 for index space):
+            //   1. flushBuffer first, to flush any un-settled assistant(tool_calls)
+            //      and prevent a dangling transcript (tool_call mid-way + compaction
+            //      event = invalid half-transcript).
+            //   2. replaced_range is the JSONL-accumulated index space, equal to
+            //      the current out accumulation.
+            //   3. Splice out[start..end) and insert 1 system summary at position
+            //      start.
+            // 容错 (safe-fail):
+            //   - start > out.length: skip (replaced_range is the trailing-tail
+            //     index, already covered by a prior compaction; this event
+            //     shouldn't occur unless JSONL was hand-edited, we take the
+            //     safe path).
+            //   - end > out.length but start <= out.length: splice out the
+            //     remaining tail and insert summary at position start (a new
+            //     user event may have pushed the tail off the end).
+            //   - start < 0 or end < start: skip (corrupt event).
+            // 'compaction_paused' event: does NOT enter messages. The caller
+            // decides whether to reset the latch; UI/footer reads paused event
+            // explicitly for status display.
+            flushBuffer();
+            const [start, end] = ev.replaced_range;
+            if (start < 0 || end < start)
+                continue; // 损坏 event
+            if (start > out.length)
+                continue; // out 没积累到, 跳过 (见上)
+            const removeCount = Math.min(end - start, out.length - start);
+            out.splice(start, removeCount, {
+                role: 'system',
+                content: `[Session compaction summary]\n${ev.summary}`,
+            });
+        }
+        // 'system' / 'compaction_paused' / 'verification' / 'policy_decision' 跳过 — 4 种都是 metadata, 不进 LLM context:
+        //   - 'system' caller 决定要不要用
+        //   - 'compaction_paused' UI/footer 显式读
+        //   - 'verification' (Sprint 1c-revive-2-D-11-3, 2026-06-04) audit log / viewer 显式读
+        //     reload session 时验证历史不污染 LLM 看到的 messages 列表
+        //   - 'policy_decision' (Sprint 1c-revive-3-D-13, 2026-06-05) tool policy 决策审计, 同 verification
+        //     不进 LLM context. 'allow' 不写 (避免 JSONL 刷爆), 只 deny / require_confirmation /
+        //     user_approved / user_denied 4 个终态落盘, 跟 verification 同 metadata 拍板.
+    }
+    // EOF: 调 flushBuffer 而非硬清空.
+    // 修复: 旧实现 `buffer = []` 把"assistant(tool_calls) → tool 已配对完成但
+    // final assistant 还没落盘" 的合法 transcript 也丢了 — 这种 crash 真实存在
+    // (工具结果已 fsync, 进程在生成最终回答前被杀, LLM 续聊需要看到 tool result
+    // 才能继续生成). 现在 EOF 走 flushBuffer, pending 空时正常 push buffer.
+    flushBuffer();
+    return out;
+}
+/**
+ * 写一个 user event 到 session。
+ * Sprint 1a 简化：user 消息也走 SessionWriter（统一审计）。
+ */
+export async function appendUserEvent(writer, content, ts = Date.now()) {
+    await writer.append({ kind: 'user', ts, content });
+}
+/**
+ * 写一条 'compaction' event 到 session (Sprint 1c-revive-2-D-5-1 拍板).
+ *
+ * 用途: agent-compaction.ts 在 runCompactionWithLatch 返 kind='ok' 时调,
+ * 把 summary 拍板落盘 (供 reload 重建 messages 时知道哪段被总结过).
+ *
+ * 拍板: SessionReader 读到 kind='compaction' 时**不**重放进 LLM context
+ * (跟 sessionEventsToMessages L132 'system' 跳过 一致 — compaction event 是 metadata,
+ *  不是 LLM 看到的对话轮次).
+ */
+export async function appendCompactionEvent(writer, summary, replacedRange, meta, ts = Date.now()) {
+    await writer.append({
+        kind: 'compaction',
+        ts,
+        summary,
+        replaced_range: replacedRange,
+        ...(meta !== undefined ? { meta } : {}),
+    });
+}
+/**
+ * 写一条 'compaction_paused' event 到 session (Sprint 1c-revive-2-D-5-2 拍板).
+ *
+ * 用途: agent-compaction.ts 在 CompactionState latch 触发时调,
+ * 记录"自动暂停, 防 death loop" 拍板 (供 reload 时 caller 知道状态).
+ *
+ * 拍板: SessionReader 读到 kind='compaction_paused' 时**不**重放进 LLM context
+ * (caller 该决定是否 reset CompactionState / 改 summaryFn / 改 config).
+ */
+export async function appendCompactionPausedEvent(writer, consecutiveFailures, reason, lastError, meta, ts = Date.now()) {
+    await writer.append({
+        kind: 'compaction_paused',
+        ts,
+        consecutive_failures: consecutiveFailures,
+        reason,
+        last_error: lastError,
+        ...(meta !== undefined ? { meta } : {}),
+    });
+}
+/**
+ * 把 tool loop 跑完后产出的 steps 全部落盘（assistant + tool）。
+ * limit/error 跳过（toSessionEvent 返回 null 时不 append）。
+ */
+export async function persistToolLoopSteps(writer, steps) {
+    for (const step of steps) {
+        const ev = toolLoopStepToSessionEvent(step);
+        if (ev !== null) {
+            await writer.append(ev);
+        }
+    }
+}
+/**
+ * 加载已有 session 并重建 messages。
+ *
+ * Sprint 1b: 内部自动调 reader.truncate() 把 partial last line 清掉。
+ * 之前 caller 必须自己记得调, Sprint 1a 全部漏调 → partial line 累积,
+ * 下次 append 拼坏 JSON。Sprint 1b 闭环在 adapter 里, 3 个 mode (repl/print/rpc) 自动受益。
+ *
+ * 行为契约:
+ * - 加载完整 events + 重建 messages
+ * - 若文件末尾有 partial line(崩溃恢复), 自动 truncate
+ * - truncate 失败不抛(不阻塞 agent 启动, 跟 Sprint 1a 容错语义一致)
+ *
+ * Sprint 1a 简化:返回 (events, messages) 两份数据, caller 决定要不要 ignore events。
+ */
+export async function loadSession(reader) {
+    const events = await reader.readAll();
+    // Sprint 1b: 闭环 truncate, 防止 partial line 累积污染下次 append
+    try {
+        await reader.truncate();
+    }
+    catch {
+        // truncate 失败不阻塞启动(可能是权限/磁盘满等, 但 events 已读到内存)
+    }
+    return { events, messages: sessionEventsToMessages(events) };
+}
+/**
+ * 写一个 'verification' event 到 session (Sprint 1c-revive-2-D-11-3, 2026-06-04).
+ *
+ * 调用场景: `deepwhale --verify` 或 REPL `/verify` 跑完, 把 VerificationReport
+ * 摘要写 1 条到 session JSONL. 跟 `appendUserEvent` / `appendCompactionEvent` 模式一致.
+ *
+ * 字段 (跟 core/src/session/jsonl.ts 'verification' union 一致):
+ *   - status: 整体结果 passed / failed
+ *   - durationMs: 整体耗时
+ *   - command_count: 跑的 step 数
+ *   - failed_count: 失败 step 数
+ *   - summary: 人类可读 summary (来自 formatter.buildSummaryAndNext)
+ *   - meta: 可选扩展 (e.g. log file path, git sha)
+ *
+ * 不变量 (跟其它 event 写入一致):
+ *   - ts 默认 Date.now(), 单测可注入
+ *   - 走 SessionWriter.append → fsync 串行化, 顺序保证
+ *   - 'verification' 是 metadata, reload session 时 sessionEventsToMessages 跳过
+ *     (跟 compaction_paused 同语义), 不污染 LLM 看到的 messages
+ */
+export async function appendVerificationEvent(writer, args) {
+    await writer.append({
+        kind: 'verification',
+        ts: args.ts ?? Date.now(),
+        status: args.status,
+        durationMs: args.durationMs,
+        command_count: args.commandCount,
+        failed_count: args.failedCount,
+        summary: args.summary,
+        ...(args.meta !== undefined ? { meta: args.meta } : {}),
+    });
+}
+/**
+ * 写一条 'policy_decision' event (Sprint 1c-revive-3-D-13, 2026-06-05).
+ * 拍板 (用户 2026-06-05): 'allow' 不调本函数 (避免 JSONL 刷爆). 只对
+ *   'deny' / 'require_confirmation' / 'user_approved' / 'user_denied' 4 个
+ *   终态落盘.
+ *
+ * 字段拍板:
+ *   - tool_call_id: 跟后续 'tool' event 配对 (reload 时 audit trace 完整)
+ *   - argsDigest: sha256:<12hex>, 不存原始 args
+ *   - reason: 已过 sanitize (长度 / 换行 / NUL, 拍板红线: 不存 secret)
+ */
+export async function appendPolicyDecisionEvent(writer, args) {
+    await writer.append({
+        kind: 'policy_decision',
+        ts: args.ts ?? Date.now(),
+        tool_call_id: args.tool_call_id,
+        name: args.name,
+        decision: args.decision,
+        argsDigest: args.argsDigest,
+        ...(args.reason !== undefined ? { reason: args.reason } : {}),
+        ...(args.meta !== undefined ? { meta: args.meta } : {}),
+    });
+}
+//# sourceMappingURL=session-adapter.js.map

package/dist/agent/session-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-adapter.js","sourceRoot":"","sources":["../../src/agent/session-adapter.ts"],"names":[],"mappings":"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"}

package/dist/agent/tool-loop.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Tool Loop — minimal agent loop (Sprint 1a)
+ *
+ * 协议（Codex/oh-my-pi 借鉴）：
+ *   1. 把 system + history 喂给 LLM
+ *   2. 如果 LLM 返回 tool_calls:
+ *      - 用 ToolRegistry 调工具（schema 校验 Sprint 1b 加）
+ *      - 把结果作为 tool 消息 push 回 messages
+ *      - 回到 (1)
+ *   3. 如果 LLM 返回 content（finish_reason='stop'）→ 终结
+ *   4. 如果 max_steps 触顶 → 抛 ToolLoopLimitError
+ *
+ * Sprint 1a 范围（极简）：
+ *   - 同步（不并发 tool_calls；DeepSeek V4 Flash 一次只调 1 个常见）
+ *   - 不做 budget cap（v2.0）
+ *   - 不做 schema 校验（trust LLM 输出，argparse 失败时 tool 返回 error 即可）
+ *   - 不做 plan mode（v2.5）
+ *   - 不做 cost accounting（1b 加）
+ *   - 流式：可选 onChunk 回调（REPL 用）
+ *
+ * 错误处理：
+ *   - tool 自身失败 → tool 消息 content 是 error，loop 继续
+ *   - LLM 失败 → 抛 LLMError（caller 决定是否 retry/终止）
+ *   - max_steps 触顶 → 抛 ToolLoopLimitError（caller 决定是否放弃）
+ *
+ * @module @deepwhale/coding-agent/agent
+ */
+import type { ChatMessage, ChatResult, LLMClient, ToolCall } from '@deepwhale/llm';
+import type { ToolResult } from '../types.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { ToolPolicy } from '../policy/types.js';
+import type { SessionWriter } from '@deepwhale/core';
+/** Sprint 1a 默认：跟 LLM 来回 5 轮（够用 coding agent 短任务，长任务 caller 调高）。 */
+export declare const TOOL_LOOP_DEFAULT_MAX_STEPS = 5;
+export interface ToolLoopOptions {
+    /** 注入工具注册表（默认 createDefaultRegistry()）。 */
+    registry?: ToolRegistry;
+    /** 上限：单次 loop LLM call 次数（含 tool_calls 触发的回传）。默认 5。 */
+    maxSteps?: number;
+    /** 给所有 tool 调用的 timeout ms。Sprint 1a 不支持单 tool 自定义 timeout。 */
+    toolTimeoutMs?: number;
+    /** 流式 chunk 回调（null/undefined = 不流式）。REPL 接 onChunk 实时打印。 */
+    onChunk?: (chunk: {
+        content?: string;
+        tool_calls?: ReadonlyArray<ToolCall>;
+    }) => void;
+    /** 外部 abort signal（Ctrl-C / session 结束）。 */
+    signal?: AbortSignal;
+    /**
+     * Sprint 1c-revive-3-D-13 (2026-06-05): tool call policy.
+     * 默认 staticToolPolicy. 显式传 null = 不检查 (单测用).
+     * 拍板: 'allow' 不写 session, 只有 deny / require_confirmation 落 policy_decision.
+     */
+    policy?: ToolPolicy | null;
+    /** Sprint 1c-revive-3-D-13: 模式是否可交互 (REPL = true, print/rpc 默认 = false). */
+    isInteractive?: boolean;
+    /** Sprint 1c-revive-3-D-13: --yes 标志. yes=true bypass require_confirmation, 不 bypass deny. */
+    yes?: boolean;
+    /** Sprint 1c-revive-3-D-13: session writer 注入 (写 policy_decision event 用). */
+    writer?: SessionWriter | null;
+}
+export type ToolLoopStep = {
+    kind: 'assistant';
+    ts: number;
+    message: ChatMessage;
+    result: ChatResult;
+} | {
+    kind: 'tool';
+    ts: number;
+    tool_call: ToolCall;
+    result: ToolResult;
+    duration_ms: number;
+} | {
+    kind: 'limit';
+    ts: number;
+    steps: number;
+    lastResult: ChatResult;
+} | {
+    kind: 'error';
+    ts: number;
+    error: Error;
+};
+export interface ToolLoopResult {
+    /** 全部 messages（含 tool_calls 步骤），caller 用来继续下一轮。 */
+    messages: ChatMessage[];
+    /** 最后一次 assistant ChatResult（content + tool_calls + usage）。 */
+    final: ChatResult;
+    /**
+     * 完整 step 序列（含 tool 调用、limit、error），caller 用来回放/审计/持久化。
+     * Sprint 1a 极简：caller 通过 runToolLoop 后读取 .steps 自己落盘。
+     * Sprint 1b 加 onStep 实时回调（避免 caller 等跑完才落）。
+     */
+    steps: ToolLoopStep[];
+}
+/**
+ * 错误：maxSteps 触顶、LLM 一直在调工具不收敛。
+ * caller 通常应当：缩短 prompt / 拆任务 / 主动放弃。
+ */
+export declare class ToolLoopLimitError extends Error {
+    readonly steps: number;
+    readonly lastResult: ChatResult;
+    readonly name: "ToolLoopLimitError";
+    readonly isToolLoopError: true;
+    constructor(steps: number, lastResult: ChatResult);
+}
+/** 类型守卫。 */
+export declare function isToolLoopError(err: unknown): err is ToolLoopLimitError;
+/**
+ * 执行一轮 tool loop。
+ *
+ * 行为契约：
+ *   - 不修改输入 messages（immutable），返回**新**数组（带 tool 步骤）
+ *   - 任何 LLM 调用失败 → 抛 LLMError（ToolLoopStep.error 事件也写入 steps）
+ *   - tool 自身失败 → 不抛，包成 tool 消息的 error content 继续
+ *   - maxSteps 触顶 → 抛 ToolLoopLimitError（steps 同时写入）
+ *   - 外部 abort → 抛带 cause 的 LLMUnknownError（包装 AbortError）
+ *
+ * Sprint 1a 限制：
+ *   - 只支持非流式调用时 onChunk=null；有 onChunk 时走 stream()。
+ *   - onChunk 触发的内容**也**写入最终 final.content（assembled）
+ */
+export declare function runToolLoop(client: LLMClient, messages: ReadonlyArray<ChatMessage>, options?: ToolLoopOptions): Promise<ToolLoopResult>;
+//# sourceMappingURL=tool-loop.d.ts.map

package/dist/agent/tool-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.d.ts","sourceRoot":"","sources":["../../src/agent/tool-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAiB,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAGlG,OAAO,KAAK,EAAQ,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,oEAAoE;AACpE,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IACtF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC3E;IACE,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,QAAQ,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,+DAA+D;IAC/D,KAAK,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAIzB,KAAK,EAAE,MAAM;aACb,UAAU,EAAE,UAAU;IAJxC,SAAkB,IAAI,EAAG,oBAAoB,CAAU;IACvD,QAAQ,CAAC,eAAe,EAAG,IAAI,CAAU;gBAEvB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,UAAU;CAIzC;AAED,YAAY;AACZ,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,kBAAkB,CAEvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,EACpC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAqFzB"}