@deepwhale/coding-agent 1.0.0

package/bin/deepwhale.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * deepwhale CLI 入口 — Sprint 1a
+ *
+ * 3 种运行模式：
+ *   deepwhale                       # interactive REPL（默认）
+ *   deepwhale -p "..."               # print 模式：一次性 chat + tool loop
+ *   deepwhale --rpc                 # RPC 模式：NDJSON over stdio（Sprint 1a stub）
+ *
+ * Sprint 0.3 极简：只启动 REPL。Sprint 1a 加 3 模式路由。
+ *
+ * 通用参数：
+ *   --session <path>    JSONL 持久化路径
+ *   --provider <name>   显式 provider (deepseek | anthropic); 走 createDefaultClient
+ *                       的 env 推断会被覆盖. 拍板 2026-06-04 review P2: 之前
+ *                       解析没接, --provider 走 'unknown flag' 分支当 print prompt.
+ *   --model <id>        显式 model id. 跟 createDefaultClient 的 model 字段对接.
+ *   --no-tool-loop      退化到 Sprint 0.3 单轮 chat（不调工具）
+ *   --max-steps <n>     工具循环上限（默认 5）
+ *   --yes               Sprint 1c-revive-3-D-13 (2026-06-05): bypass require_confirmation
+ *                       (write_file / edit_file / 危险 bash), 不 bypass deny.
+ *   --version | -v      输出版本
+ *   --help | -h         输出帮助
+ */
+
+import { resolve as pathResolve } from 'node:path';
+import process from 'node:process';
+// Sprint 1c-revive-2-D-7 (review, 2026-06-04): 启动时加载项目根 .env (补缺不覆盖,
+// CI / shell export 优先级最高). 必须在 import dist 之前调, 让 createDefaultClient
+// factory 看到 process.env['DEEPSEEK_API_KEY'] / ['ANTHROPIC_AUTH_TOKEN'] 已就位.
+import { loadProjectEnv } from '../dist/env/load-project-env.js';
+loadProjectEnv();
+import { startRepl } from '../dist/index.js';
+import { runPrintMode } from '../dist/modes/print.js';
+import { runRpcMode } from '../dist/modes/rpc.js';
+import { runTuiMode } from '../dist/modes/tui.js';
+import { runVerify } from '../dist/verify/index.js';
+import { buildSummaryAndNext, formatReport } from '../dist/verify/index.js';
+// Sprint 1c-revive-4-D-20.1 (2026-06-05): 友好错误处理.
+//  - APIKeyMissingError: REPL/print/rpc/tui 缺 key 时 → 印 setup hint + exit 2.
+//  - "invalid DEEPWHALE_SANDBOX=..." / "invalid DEEPWHALE_DOCKER_NETWORK=...":
+//    env-gate throw, CLI 入口接住转 stderr + exit 2.
+import { APIKeyMissingError } from '@deepwhale/llm';
+
+/**
+ * @typedef {Object} CliArgs
+ * @property {'interactive'|'print'|'rpc'|'verify'} mode
+ * @property {string|undefined} prompt
+ * @property {string|undefined} sessionPath
+ * @property {string|undefined} provider
+ * @property {string|undefined} model
+ * @property {boolean} enableToolLoop
+ * @property {number} maxSteps
+ * @property {boolean} [yes]    Sprint 1c-revive-3-D-13: --yes flag, 透传 3 mode.
+ */
+
+/**
+ * @param {ReadonlyArray<string>} argv
+ * @returns {CliArgs}
+ */
+function parseArgs(argv) {
+  const args = {
+    mode: 'interactive',
+    prompt: undefined,
+    sessionPath: undefined,
+    provider: undefined,
+    model: undefined,
+    enableToolLoop: true,
+    maxSteps: 5,
+    yes: undefined,
+  };
+
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--version' || a === '-v') {
+      process.stdout.write('deepwhale 0.1.0 (Sprint 1a)\n');
+      process.exit(0);
+    }
+    if (a === '--help' || a === '-h') {
+      process.stdout.write(HELP_TEXT);
+      process.exit(0);
+    }
+    if (a === '--rpc') {
+      args.mode = 'rpc';
+      i += 1;
+      continue;
+    }
+    // Sprint 1c-revive-4-D-20.3 (2026-06-05): TUI mode (D-20.3 P0-B)
+    // `deepwhale tui` 启动 minimal ANSI TUI. 必须出现在 -p/--prompt 检查之前,
+    // 否则 'tui' 会被当 print mode 的 prompt (D-15 拍板: 非 '-' 开头的 argv 走 print).
+    if (a === 'tui') {
+      args.mode = 'tui';
+      i += 1;
+      continue;
+    }
+    if (a === '--verify') {
+      // Sprint 1c-revive-2-D-11-4 (2026-06-04): CLI 接入 verify 模式.
+      // 走 runVerify() → formatReport() 印到 stdout, 不走 LLM / tool loop / session.
+      // 退出码: 0 = passed, 1 = failed (跟 runVerify overallStatus 对应),
+      //         2 = 参数错 (跟现有 mode 退出码一致)
+      args.mode = 'verify';
+      i += 1;
+      continue;
+    }
+    if (a === '-p' || a === '--prompt') {
+      args.mode = 'print';
+      args.prompt = argv[i + 1] ?? '';
+      i += 2;
+      continue;
+    }
+    if (a === '--session') {
+      args.sessionPath = pathResolve(argv[i + 1] ?? '');
+      i += 2;
+      continue;
+    }
+    if (a === '--provider') {
+      // 拍板 2026-06-04 review P2: 之前未接, --provider X 被当 prompt 进入 print 模式.
+      // 校验: deepseek | anthropic (跟 llm-factory.ts 的 Provider 拍板一致).
+      const v = argv[i + 1] ?? '';
+      if (v !== 'deepseek' && v !== 'anthropic') {
+        process.stderr.write(`Error: --provider must be 'deepseek' or 'anthropic', got '${v}'\n`);
+        process.exit(2);
+      }
+      args.provider = v;
+      i += 2;
+      continue;
+    }
+    if (a === '--yes') {
+      // Sprint 1c-revive-3-D-13 (2026-06-05): --yes 透传 3 mode.
+      // 拍板: bypass require_confirmation (write_file/edit_file/bash 危险模式),
+      //       不 bypass deny. 跟 R-3 拍板一致.
+      args.yes = true;
+      i += 1;
+      continue;
+    }
+    if (a === '--model') {
+      args.model = argv[i + 1] ?? '';
+      i += 2;
+      continue;
+    }
+    if (a === '--no-tool-loop') {
+      args.enableToolLoop = false;
+      i += 1;
+      continue;
+    }
+    if (a === '--max-steps') {
+      const n = Number.parseInt(argv[i + 1] ?? '5', 10);
+      args.maxSteps = Number.isFinite(n) && n > 0 ? n : 5;
+      i += 2;
+      continue;
+    }
+    // 未知参数 → 当作 print 模式的 prompt(Sprint 0.3 兼容)
+    if (!a.startsWith('-')) {
+      args.mode = 'print';
+      args.prompt = a;
+    }
+    i += 1;
+  }
+  return args;
+}
+
+const HELP_TEXT = `deepwhale — Coding Agent CLI
+
+Usage:
+  deepwhale                         Start interactive REPL (default)
+  deepwhale -p "<prompt>"           Print mode: single-shot chat + tool loop
+  deepwhale --verify                Verify mode: run build/lint/typecheck/test, no LLM
+  deepwhale --rpc                   RPC mode: NDJSON over stdio (Sprint 1a stub)
+  deepwhale tui                     TUI mode: minimal ANSI TUI (D-20.3, ships in v1.0)
+
+Options:
+  --session <path>    Persist session to JSONL file
+  --provider <name>   LLM provider: deepseek | anthropic (overrides env detection)
+  --model <id>        LLM model id (e.g. deepseek-v4-flash, claude-sonnet-4-5)
+  --no-tool-loop      Disable tool calling (single-turn chat only)
+  --max-steps <n>     Max tool-loop steps (default 5)
+  --yes               Bypass require_confirmation (write/edit/dangerous bash).
+                      Does NOT bypass deny. Sprint 1c-revive-3-D-13.
+  --version, -v       Print version and exit
+  --help, -h          Print this help
+
+Environment:
+  DEEPSEEK_API_KEY        Required for deepseek (or --provider).
+  ANTHROPIC_AUTH_TOKEN    Required for anthropic (or --provider). May also be
+                          DEEPWHALE_SESSION_KEY for session-at-rest encryption.
+  DEEPWHALE_LANG          Optional. 'en' (default) or 'zh-CN'.
+  DEEPWHALE_SANDBOX       Optional. 'local' (default) or 'docker'.
+  DEEPWHALE_DOCKER_IMAGE  Optional. default 'node:22-alpine'.
+  DEEPWHALE_DOCKER_NETWORK  Optional. unset|'none' (default) or 'bridge'.
+                            D-20.1: invalid value → fail-closed (exit 2).
+
+Built-in REPL commands:
+  /help, /verify, /exit, exit, quit
+
+Setup hint:
+  If you see "API key not set" on first run:
+    1. Set DEEPSEEK_API_KEY=<your-key>  (or ANTHROPIC_AUTH_TOKEN=...)
+    2. Or place it in ./.env (project root, see .env.example)
+    3. --verify does not require any key (build/lint/typecheck/test only)
+`;
+
+/**
+ * 路由到 3 种模式之一。
+ * Sprint 1a:interactive/print 接 tool loop + session;rpc 是 NDJSON 框架 stub。
+ * Sprint 1c-revive-2-D-5+ (review P2, 2026-06-04): --provider/--model 透传
+ * 3 mode, 跟 createDefaultClient factory 对接.
+ *
+ * @returns {Promise<number>}
+ */
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  switch (args.mode) {
+    case 'interactive':
+      return startRepl({
+        ...(args.sessionPath !== undefined ? { sessionPath: args.sessionPath } : {}),
+        ...(args.provider !== undefined ? { provider: args.provider } : {}),
+        ...(args.model !== undefined ? { model: args.model } : {}),
+        ...(args.yes ? { yes: true } : {}),
+        enableToolLoop: args.enableToolLoop,
+      });
+    case 'print':
+      if (!args.prompt) {
+        process.stderr.write('Error: print mode requires -p "<prompt>" argument\n');
+        return 2;
+      }
+      return runPrintMode({
+        prompt: args.prompt,
+        ...(args.sessionPath !== undefined ? { sessionPath: args.sessionPath } : {}),
+        ...(args.provider !== undefined ? { provider: args.provider } : {}),
+        ...(args.model !== undefined ? { model: args.model } : {}),
+        ...(args.yes ? { yes: true } : {}),
+        enableToolLoop: args.enableToolLoop,
+        maxSteps: args.maxSteps,
+      });
+    case 'rpc':
+      return runRpcMode({
+        ...(args.sessionPath !== undefined ? { sessionPath: args.sessionPath } : {}),
+        ...(args.provider !== undefined ? { provider: args.provider } : {}),
+        ...(args.model !== undefined ? { model: args.model } : {}),
+        ...(args.yes ? { yes: true } : {}),
+        maxSteps: args.maxSteps,
+      });
+    case 'tui':
+      return runTuiMode({
+        ...(args.sessionPath !== undefined ? { sessionPath: args.sessionPath } : {}),
+        ...(args.provider !== undefined ? { provider: args.provider } : {}),
+        ...(args.model !== undefined ? { model: args.model } : {}),
+        ...(args.yes ? { yes: true } : {}),
+        enableToolLoop: args.enableToolLoop,
+        maxSteps: args.maxSteps,
+      });
+    case 'verify': // Sprint 1c-revive-2-D-11-4: 走 runVerify (4 步 default), formatReport 印到 stdout.
+    // 退出码: passed=0, failed=1 (跟 runVerify overallStatus 对应). 跟 Unix
+    // 惯例一致 (CI 脚本 \`if deepwhale --verify; then ...\`).
+    // 注: 不写 session event (verify 不是 chat 行为, session JSONL 是 chat 持久化,
+    //     verify 跑完不污染 session). 后续 sprint 如要 audit log, 留 --verify-log 选项.
+    {
+      const report = await runVerify();
+      const filled = buildSummaryAndNext(report);
+      const text = formatReport({
+        ...report,
+        summary: filled.summary,
+        nextSuggestedAction: filled.nextSuggestedAction,
+      });
+      process.stdout.write(text + '\n');
+      return report.overallStatus === 'passed' ? 0 : 1;
+    }
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    // Sprint 1c-revive-4-D-20.1 (2026-06-05) review-fix: 友好错误处理, 退出码 2 (跟参数错一致).
+    //  - APIKeyMissingError: REPL/print/rpc/tui 缺 key → 印 setup hint
+    //  - env-gate 抛 'invalid DEEPWHALE_SANDBOX=...' / 'invalid DEEPWHALE_DOCKER_NETWORK=...'
+    //    → 直接 stderr 打印 (message 拼齐了 hint), exit 2
+    if (err instanceof APIKeyMissingError) {
+      process.stderr.write(
+        'Error: API key not set. deepwhale needs DEEPSEEK_API_KEY (or ANTHROPIC_AUTH_TOKEN),\n' +
+          '       or pass --provider. See --help for full setup.\n' +
+          '       Hint: --verify runs build/lint/typecheck/test and does NOT need a key.\n' +
+          `       Underlying: ${err.message}\n`,
+      );
+      process.exit(2);
+    }
+    if (err instanceof Error && /^invalid DEEPWHALE_SANDBOX=/.test(err.message)) {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exit(2);
+    }
+    if (err instanceof Error && /^invalid DEEPWHALE_DOCKER_NETWORK=/.test(err.message)) {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exit(2);
+    }
+    process.stderr.write(`FATAL: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  },
+);

package/dist/agent/agent-compaction.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tool Loop + Compaction 集成 (Sprint 1c-revive-2-D-5 + D-5-2)
+ *
+ * 拍板 (跟 P21 / P27 跨协议 6 cell 一致):
+ *   - runToolLoop 每次 LLM call 前, 测 messages token 数
+ *   - 触发 (>= window * compactRatio) → 调 summaryFn (LLM 走同 client 拍板)
+ *   - 成功 → 替换 working messages, 写 1 条 'compaction' event 到 SessionWriter
+ *   - 失败 → CompactionState 累计; latch → 写 1 条 'compaction_paused' event
+ *   - paused → 跳过 compaction (不浪费 LLM token 调 summaryFn, 防 death loop)
+ *
+ * 协议集成 (P38 拍板 + D-5-2 拍板):
+ *   - protocol: 'openai' | 'anthropic' (用于 summaryFn, 不同协议 system prompt 不同)
+ *   - 集成在 runToolLoop 入口, 跟 tool-loop.ts P21 6 cell 拍板一致:
+ *     DeepSeek + Anthropic 协议都走同一 hook
+ *
+ * 不变量:
+ *   - compaction 永不 throw 给 runToolLoop (防 LLM 续聊死锁)
+ *   - 失败 event 总能写盘 (即使 writer.append 抛错, 也只 warn 不 throw)
+ *   - paused 后仍跑 runToolLoop 正常 (不阻塞用户任务, 仅不再 compact)
+ *
+ * @module @deepwhale/coding-agent/agent-compaction
+ */
+import { type ChatMessage, type LLMClient } from '@deepwhale/llm';
+import { type CompactionConfig, type SummarizeFn, CompactionState } from '@deepwhale/core';
+import type { SessionWriter } from '@deepwhale/core';
+import type { ToolLoopOptions, ToolLoopResult } from './tool-loop.js';
+/**
+ * Compaction 集成配置 (runToolLoop 包装层用).
+ *
+ * 跟 core CompactionConfig 区别:
+ *   - client 来自 coding-agent 包 (P21 拍板: 协议从 LLMClient 推断)
+ *   - state 由集成层管 (caller 用 new CompactionState(...) 注入)
+ *   - protocol 拍板: 'openai' (DeepSeek) | 'anthropic' — summaryFn 的 system prompt 不同
+ */
+export interface AgentCompactionConfig extends CompactionConfig {
+    /** 协议拍板 — 跟 P21 6 cell 一致. summaryFn 内部用此拍 system prompt 模板. */
+    readonly protocol: 'openai' | 'anthropic';
+    /** SessionWriter — 写 'compaction' / 'compaction_paused' event 用 */
+    readonly writer: SessionWriter;
+    /** CompactionState — caller 管, 跨 runToolLoop 调用持久化 */
+    readonly state: CompactionState;
+}
+/**
+ * 跑 runToolLoop 集成 compaction 触发.
+ *
+ * 拍板行为 (跟 P21 6 cell 一致):
+ *   1. 入口测 token → 触发则 compact → 替换 working
+ *   2. runToolLoop 内部每个 LLM call 前不重复触发 (避免 per-step 开销)
+ *   3. 失败 latch → 写 paused event, runToolLoop 继续跑 (不阻塞)
+ *
+ * Sprint 1c-revive-2-D-6 (review P1 修复, 2026-06-04): caller-side system prefix
+ * handling. 拍板: REPL/caller 可能把系统提示拼到 messages 最前面 (e.g. integration
+ * test fixture, 或未来 system prompt 注入). 传 compact() 之前先 **剥掉** 连续
+ * system 前缀, 让 compact 看到的 index 跟 session-adapter 累积 messages
+ * (user/assistant/tool + compaction summary) 同 index 空间, replaced_range
+ * 切 reload replay 同步. compact 后把 system 前缀 **原样 prepend 回** 替换后
+ * 的 messages, LLM 看到的 context 跟 caller 拼的一致.
+ *
+ * @param client  LLM client
+ * @param messages 入口 messages (不变, 内部 copy)
+ * @param options runToolLoop 原生 options
+ * @param compaction 集成配置
+ * @param summaryFn 生成 summary text 的 callback (caller 决定 LLM 协议)
+ * @returns ToolLoopResult
+ */
+export declare function runToolLoopWithCompaction(client: LLMClient, messages: ReadonlyArray<ChatMessage>, options: ToolLoopOptions | undefined, compaction: AgentCompactionConfig, summaryFn: SummarizeFn): Promise<ToolLoopResult>;
+/**
+ * 便捷工具: 估算当前 messages 的 token 数 (供 REPL / footer 拍板显示用).
+ *
+ * 跟 compaction.ts 的 estimateTokens 拍板一致 (char/4 粗估).
+ * 集成在 coding-agent 包, 供 REPL 端零成本 import core.
+ */
+export declare function estimateContextTokens(messages: ReadonlyArray<ChatMessage>): number;
+//# sourceMappingURL=agent-compaction.d.ts.map

package/dist/agent/agent-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-compaction.d.ts","sourceRoot":"","sources":["../../src/agent/agent-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEhB,eAAe,EAGhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGtE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,EACpC,OAAO,EAAE,eAAe,YAAK,EAC7B,UAAU,EAAE,qBAAqB,EACjC,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,cAAc,CAAC,CAUzB;AAyFD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAElF"}

package/dist/agent/agent-compaction.js

@@ -0,0 +1,145 @@
+/**
+ * Tool Loop + Compaction 集成 (Sprint 1c-revive-2-D-5 + D-5-2)
+ *
+ * 拍板 (跟 P21 / P27 跨协议 6 cell 一致):
+ *   - runToolLoop 每次 LLM call 前, 测 messages token 数
+ *   - 触发 (>= window * compactRatio) → 调 summaryFn (LLM 走同 client 拍板)
+ *   - 成功 → 替换 working messages, 写 1 条 'compaction' event 到 SessionWriter
+ *   - 失败 → CompactionState 累计; latch → 写 1 条 'compaction_paused' event
+ *   - paused → 跳过 compaction (不浪费 LLM token 调 summaryFn, 防 death loop)
+ *
+ * 协议集成 (P38 拍板 + D-5-2 拍板):
+ *   - protocol: 'openai' | 'anthropic' (用于 summaryFn, 不同协议 system prompt 不同)
+ *   - 集成在 runToolLoop 入口, 跟 tool-loop.ts P21 6 cell 拍板一致:
+ *     DeepSeek + Anthropic 协议都走同一 hook
+ *
+ * 不变量:
+ *   - compaction 永不 throw 给 runToolLoop (防 LLM 续聊死锁)
+ *   - 失败 event 总能写盘 (即使 writer.append 抛错, 也只 warn 不 throw)
+ *   - paused 后仍跑 runToolLoop 正常 (不阻塞用户任务, 仅不再 compact)
+ *
+ * @module @deepwhale/coding-agent/agent-compaction
+ */
+import { runCompactionWithLatch, estimateTokens, } from '@deepwhale/core';
+import { runToolLoop } from './tool-loop.js';
+/**
+ * 跑 runToolLoop 集成 compaction 触发.
+ *
+ * 拍板行为 (跟 P21 6 cell 一致):
+ *   1. 入口测 token → 触发则 compact → 替换 working
+ *   2. runToolLoop 内部每个 LLM call 前不重复触发 (避免 per-step 开销)
+ *   3. 失败 latch → 写 paused event, runToolLoop 继续跑 (不阻塞)
+ *
+ * Sprint 1c-revive-2-D-6 (review P1 修复, 2026-06-04): caller-side system prefix
+ * handling. 拍板: REPL/caller 可能把系统提示拼到 messages 最前面 (e.g. integration
+ * test fixture, 或未来 system prompt 注入). 传 compact() 之前先 **剥掉** 连续
+ * system 前缀, 让 compact 看到的 index 跟 session-adapter 累积 messages
+ * (user/assistant/tool + compaction summary) 同 index 空间, replaced_range
+ * 切 reload replay 同步. compact 后把 system 前缀 **原样 prepend 回** 替换后
+ * 的 messages, LLM 看到的 context 跟 caller 拼的一致.
+ *
+ * @param client  LLM client
+ * @param messages 入口 messages (不变, 内部 copy)
+ * @param options runToolLoop 原生 options
+ * @param compaction 集成配置
+ * @param summaryFn 生成 summary text 的 callback (caller 决定 LLM 协议)
+ * @returns ToolLoopResult
+ */
+export async function runToolLoopWithCompaction(client, messages, options = {}, compaction, summaryFn) {
+    // 1) 剥掉 caller 拼的连续 system prefix, 保持 replaced_range 跟 JSONL 累积同空间
+    const headSystem = splitSystemPrefix(messages);
+    // 2) 入口测 token, 触发则 compact 替换 messages (在剥掉 system 的子集上跑)
+    const compactedTail = await maybeCompactBeforeLoop(headSystem.tail, compaction, summaryFn);
+    // 3) 拼回 system prefix → 跑原生 runToolLoop
+    const compactedMessages = [...headSystem.prefix, ...compactedTail];
+    return runToolLoop(client, compactedMessages, options);
+}
+/**
+ * 把 messages 切分为 "caller 自带的连续 system prefix" + "其余".
+ *
+ * 拍板 (D-6 review P1 修复, 2026-06-04):
+ *   - prefix = messages[0..n), n = 头连续 system message 数量
+ *   - tail   = messages[n..)
+ *   - 没 system prefix → prefix=[], tail=messages
+ *   - 全 system (只有 1 条 system 也算) → tail=[] (compaction 看到空, 不触发)
+ *
+ * 用途: caller 把 system prompt 拼前面时, 传给 compact() 前先剥掉, 让
+ * replaced_range 的 index 空间 跟 session-adapter replay JSONL 时累积的
+ * messages (user/assistant/tool + 之前 reload 注入的 summary) 同空间,
+ * reload replay 不会 off-by-one.
+ *
+ * **不动** 中间或末尾的 system message (罕见, 但保留 — 不归 compaction 管).
+ * **不动** tool_call_id 关联, 因为 prefix 是 system role, 不会拖 tool pair.
+ */
+function splitSystemPrefix(messages) {
+    let n = 0;
+    while (n < messages.length && messages[n].role === 'system') {
+        n++;
+    }
+    return {
+        prefix: messages.slice(0, n),
+        tail: messages.slice(n),
+    };
+}
+/**
+ * 入口 compaction 触发 (one-shot, 不重入 runToolLoop 内部).
+ *
+ * 行为契约:
+ *   - paused → 返 messages 原样, 不调 summaryFn, 不写 event (latched 拍板)
+ *   - 不该 compact → 返 messages 原样, 不调 summaryFn, 不写 event
+ *   - compact 成功 → 替换 messages, 写 'compaction' event
+ *   - compact 失败 (未 latch) → 返 messages 原样, 不写 event (caller 该 retry)
+ *   - compact latched → 写 'compaction_paused' event, 返 messages 原样
+ */
+async function maybeCompactBeforeLoop(messages, compaction, summaryFn) {
+    const { state, writer, protocol, contextWindow } = compaction;
+    // protocol 显式使用一次, 拍板留位 (跟 P21 6 cell summaryFn 拍 system prompt 模板用)
+    void protocol;
+    if (contextWindow <= 0)
+        return messages;
+    if (messages.length === 0)
+        return messages;
+    if (!state.shouldAttempt())
+        return messages;
+    let result;
+    try {
+        result = await runCompactionWithLatch(messages, compaction, summaryFn, state);
+    }
+    catch {
+        // 未触发 latch 的失败: caller 决定怎么处理 (e.g. 用户改配置), 这里不抛
+        // 拍板不阻塞 runToolLoop
+        return messages;
+    }
+    if (result === null) {
+        // 不该 compact 或 paused
+        return messages;
+    }
+    if (result.kind === 'ok') {
+        // 写 'compaction' event — writer.append 抛错只 warn, 不 throw
+        try {
+            await writer.append(result.event);
+        }
+        catch {
+            // 写盘失败不阻塞 loop
+        }
+        return result.result.messages;
+    }
+    // kind === 'latched'
+    try {
+        await writer.append(result.pausedEvent);
+    }
+    catch {
+        // 写盘失败不阻塞 loop
+    }
+    return messages;
+}
+/**
+ * 便捷工具: 估算当前 messages 的 token 数 (供 REPL / footer 拍板显示用).
+ *
+ * 跟 compaction.ts 的 estimateTokens 拍板一致 (char/4 粗估).
+ * 集成在 coding-agent 包, 供 REPL 端零成本 import core.
+ */
+export function estimateContextTokens(messages) {
+    return estimateTokens(messages);
+}
+//# sourceMappingURL=agent-compaction.js.map

package/dist/agent/agent-compaction.js.map

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

package/dist/agent/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @deepwhale/coding-agent/agent — Tool Loop & 调度
+ *
+ * Sprint 1a 落地：
+ * - runToolLoop: 最小 agent loop（LLM ↔ tool_calls ↔ LLM）
+ * - ToolLoopLimitError: maxSteps 触顶时抛
+ * - session-adapter: tool loop step ↔ JSONL SessionEvent 转换
+ *
+ * Sprint 1b 再加：plan mode、schema 校验、budget cap、onStep 实时回调。
+ * Sprint 2+ 再加：并行 tool_call、recovery 3-way、断点续传。
+ */
+export { runToolLoop, isToolLoopError, TOOL_LOOP_DEFAULT_MAX_STEPS, type ToolLoopOptions, type ToolLoopResult, type ToolLoopStep, ToolLoopLimitError, } from './tool-loop.js';
+export { toolLoopStepToSessionEvent, sessionEventsToMessages, appendUserEvent, appendCompactionEvent, appendCompactionPausedEvent, appendVerificationEvent, persistToolLoopSteps, loadSession, } from './session-adapter.js';
+export { runToolLoopWithCompaction, estimateContextTokens, type AgentCompactionConfig, } from './agent-compaction.js';
+export { CompactionState, type CompactionConfig } from '@deepwhale/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,WAAW,EACX,eAAe,EACf,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,17 @@
+/**
+ * @deepwhale/coding-agent/agent — Tool Loop & 调度
+ *
+ * Sprint 1a 落地：
+ * - runToolLoop: 最小 agent loop（LLM ↔ tool_calls ↔ LLM）
+ * - ToolLoopLimitError: maxSteps 触顶时抛
+ * - session-adapter: tool loop step ↔ JSONL SessionEvent 转换
+ *
+ * Sprint 1b 再加：plan mode、schema 校验、budget cap、onStep 实时回调。
+ * Sprint 2+ 再加：并行 tool_call、recovery 3-way、断点续传。
+ */
+export { runToolLoop, isToolLoopError, TOOL_LOOP_DEFAULT_MAX_STEPS, ToolLoopLimitError, } from './tool-loop.js';
+export { toolLoopStepToSessionEvent, sessionEventsToMessages, appendUserEvent, appendCompactionEvent, appendCompactionPausedEvent, appendVerificationEvent, persistToolLoopSteps, loadSession, } from './session-adapter.js';
+export { runToolLoopWithCompaction, estimateContextTokens, } from './agent-compaction.js';
+// Re-export core compaction types for caller convenience
+export { CompactionState } from '@deepwhale/core';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,WAAW,EACX,eAAe,EACf,2BAA2B,EAI3B,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,GAEtB,MAAM,uBAAuB,CAAC;AAC/B,yDAAyD;AACzD,OAAO,EAAE,eAAe,EAAyB,MAAM,iBAAiB,CAAC"}