@trans-ai/trans-code 0.2.4 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +68 -17
  2. package/package.json +1 -1
  3. package/src/acp/session.ts +4 -1
  4. package/src/agent/loop.test.ts +337 -1
  5. package/src/agent/loop.ts +166 -2
  6. package/src/agent/system-prompt.test.ts +24 -1
  7. package/src/agent/system-prompt.ts +21 -0
  8. package/src/agent/tools/ask-model.test.ts +54 -0
  9. package/src/agent/tools/ask-model.ts +44 -0
  10. package/src/agent/tools/bash.test.ts +42 -1
  11. package/src/agent/tools/bash.ts +202 -15
  12. package/src/agent/tools/dispatch.test.ts +157 -0
  13. package/src/agent/tools/dispatch.ts +151 -0
  14. package/src/agent/tools/files.test.ts +96 -0
  15. package/src/agent/tools/files.ts +111 -29
  16. package/src/agent/tools/fs-utils.ts +40 -0
  17. package/src/agent/tools/index.ts +29 -2
  18. package/src/agent/tools/powershell.test.ts +61 -0
  19. package/src/agent/tools/read-only.ts +16 -0
  20. package/src/agent/tools/search.test.ts +55 -1
  21. package/src/agent/tools/search.ts +56 -8
  22. package/src/agent/tools/session.ts +21 -0
  23. package/src/agent/tools/shell-paths.test.ts +65 -0
  24. package/src/agent/tools/shell-paths.ts +19 -0
  25. package/src/agent/tools/todo.test.ts +54 -0
  26. package/src/agent/tools/todo.ts +47 -0
  27. package/src/agent/tools/types.ts +15 -1
  28. package/src/cli.ts +2 -0
  29. package/src/commands.ts +55 -2
  30. package/src/config.ts +21 -3
  31. package/src/main.tsx +4 -4
  32. package/src/provider/model-list.test.ts +65 -0
  33. package/src/provider/provider.test.ts +117 -0
  34. package/src/provider/provider.ts +312 -34
  35. package/src/provider/routing.test.ts +109 -0
  36. package/src/screens/REPL.tsx +432 -35
  37. package/src/sessions/store.test.ts +91 -0
  38. package/src/sessions/store.ts +149 -0
  39. package/src/version.ts +1 -1
package/README.md CHANGED
@@ -2,16 +2,18 @@
2
2
 
3
3
  多模型 AI 编码 Agent CLI。当前 MVP 的目标是:**作为本地 Agent 被 transonce、multica 等客户端通过 ACP 调用**。
4
4
 
5
- - 终端侧:Ink REPL(保留原有命令:`help` / `models` / `clear` / `exit`)
5
+ - 终端侧:Ink REPL(命令:`help` / `models` / `mode` / `route` / `init` / `clear` / `exit`)
6
6
  - Agent 侧:`transcode acp` 启动 ACP v1 stdio 服务,供 transonce、multica 等客户端调用
7
- - 模型侧:Anthropic / OpenAI 及任意 OpenAI 兼容网关(DeepSeek、GLM、MiniMax、Kimi、自建网关等)
8
- - 工具侧:`read_file` / `write_file` / `edit_file` / `glob` / `grep` / `bash`
7
+ - 模型侧:档案(Profile)+ 角色(Role)路由——一个模型 ID 对应一个地址,不同任务可派发不同模型(含子 Agent)
8
+ - 工具侧:`read_file` / `write_file` / `edit_file` / `glob` / `grep` / `bash` / `todo_write` / `ask_model` / `dispatch_agent`
9
9
 
10
10
  ## 环境要求
11
11
 
12
12
  - Bun >= 1.3
13
13
  - 至少一个模型提供商的 API Key
14
14
 
15
+ **平台**:macOS / Linux 原生支持。Windows 需安装 [Git Bash](https://git-scm.com/)(bash 工具自动探测 `C:\Program Files\Git\bin\bash.exe` 等常见位置;也可用 `TRANSCODE_SHELL` 显式指定),超时终止走 `taskkill /T /F` 杀进程树,路径在 Windows/Git-Bash 两种形态间自动转换。纯 PowerShell 环境(无 Git Bash)暂不支持。
16
+
15
17
  ```bash
16
18
  bun install
17
19
  ```
@@ -26,10 +28,12 @@ bun link
26
28
 
27
29
  ## 配置模型
28
30
 
29
- 通过环境变量配置,模型可以是注册表 id,也可以是 `provider:model`:
31
+ 三种方式,从简到繁:
32
+
33
+ **1. 环境变量**(注册表 id 或 `provider:model`):
30
34
 
31
35
  ```bash
32
- # 注册表 id: opus | gpt | deepseek | glm | minimax | kimi
36
+ # 注册表 id: opus | gpt | deepseek | glm | glmc | minimax | kimi | custom
33
37
  export ANTHROPIC_API_KEY=...
34
38
  export DEEPSEEK_API_KEY=...
35
39
  export TRANSCODE_MODEL=deepseek
@@ -39,6 +43,30 @@ export OPENAI_API_KEY=...
39
43
  export TRANSCODE_MODEL=openai:gpt-4o
40
44
  ```
41
45
 
46
+ **2. REPL 交互配置**(`/models`):三级流程——选厂商 → 选模型 → 输入 key(已存的可回车沿用)。
47
+ - 模型列表**从网关实时拉取**(`GET /v1/models`,标"网关实时列表"),选的就是实际可用的;网关不提供列表时回退内置精选列表 + "自定义模型名…"自由输入
48
+ - key 确认后**自动测试连通性**,显示端点**实际调度的模型**(如智谱 Coding 端点会把 `glm-4.6` 映射为套餐当前的 `glm-5.3-flash`,测试会如实亮出);失败显示 API 原始报错并可重输
49
+ - `custom` 支持任意 OpenAI 兼容网关:base URL → key → **从网关实时模型列表中选**(OneAPI/NewAPI/自建中转即插即见),无需盲填模型名
50
+
51
+ **3. 档案 + 角色路由**(`~/.transcode.json`,任务级模型分派):
52
+
53
+ ```jsonc
54
+ {
55
+ "apiKeys": { "glm": "…", "deepseek": "…" },
56
+ "profiles": {
57
+ "glm-coding": { "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", "model": "glm-4.6", "keyId": "glm" },
58
+ "glm-vision": { "baseUrl": "https://open.bigmodel.cn/api/paas/v4", "model": "glm-4.6v", "keyId": "glm" }
59
+ },
60
+ "routing": { "default": "glm-coding", "analysis": "glm-coding", "vision": "glm-vision" }
61
+ }
62
+ ```
63
+
64
+ - **Profile**:命名档案 = 地址 + 模型名 + keyId(智谱普通端点 / CodePlan 端点各一个档案,共用一把 key;同名覆盖内置注册表)
65
+ - **Role**:任意命名的角色 → 档案,`/route analysis glmc` 设置、`/route` 查看、`/route design -` 删除
66
+ - ACP `session/set_model` 直接收档案名,宿主可按任务指派不同模型
67
+
68
+ > **GLM Coding Plan 用户**:套餐只在 Coding 专用端点生效,请用 `glmc` 档案(`https://open.bigmodel.cn/api/coding/paas/v4`);普通 `glm` 端点会报"429 余额不足"。
69
+
42
70
  ### 复用 Claude Code 的 Anthropic 兼容配置
43
71
 
44
72
  如果你已经有一个 Anthropic 兼容网关(例如 DeepSeek 的 `/anthropic` 端点),可以直接沿用 Claude Code 的环境变量,不需要改 `TRANSCODE_MODEL`:
@@ -70,15 +98,18 @@ bun run test:acp:real # 完整 ACP + 工具调用(会创建临时 works
70
98
 
71
99
  | 变量 | 说明 |
72
100
  | --- | --- |
73
- | `TRANSCODE_MODEL` | 默认模型。注册表 id、`provider:model`,或裸模型名 |
101
+ | `TRANSCODE_MODEL` | 默认模型。注册表 id、档案名、`provider:model`,或裸模型名 |
74
102
  | `TRANSCODE_DEFAULT_PROVIDER` | 裸模型名走哪个 provider,默认 `openai` |
75
- | `TRANSCODE_PERMISSION_MODE` | `ask`(默认) / `auto` / `readonly` |
103
+ | `TRANSCODE_PERMISSION_MODE` | `ask`(默认) / `auto` / `readonly`;REPL 里可用 `/mode` 运行时切换 |
76
104
  | `TRANSCODE_ALLOW_OUTSIDE_CWD` | 设为 `1` 才允许读写工作区之外的路径 |
77
105
  | `TRANSCODE_BASE_URL` | 覆盖当前模型的 base URL(所有 provider) |
78
106
  | `TRANSCODE_MAX_TOKENS` | 单次回复的 `max_tokens`,默认 `8192` |
107
+ | `TRANSCODE_MAX_TURNS` | Agent 工具回合上限,默认 `200`;触顶会明确提示并写入对话 |
108
+ | `TRANSCODE_SUBAGENT_MAX_TURNS` | 子 Agent 回合上限,默认 `25` |
109
+ | `TRANSCODE_SKIP_MODEL_CHECK` | 设为 `1` 跳过 /models 的连通性测试 |
79
110
  | `TRANSCODE_MOCK` | 设为 `1` 使用本地 mock 模型(仅用于协议测试) |
80
111
 
81
- `provider:model` 支持的前缀:`openai`、`anthropic`、`deepseek`、`glm`、`minimax`、`kimi`、`moonshot`。
112
+ `provider:model` 支持的前缀:`openai`、`anthropic`、`deepseek`、`glm`、`glmc`、`minimax`、`kimi`、`moonshot`。
82
113
  裸模型名会使用 `TRANSCODE_DEFAULT_PROVIDER`;`openai` 前缀和裸模型名可以用 `OPENAI_BASE_URL` 指向兼容网关,`TRANSCODE_BASE_URL` 则可以覆盖任意 provider。
83
114
 
84
115
  ## 本地运行
@@ -167,18 +198,38 @@ ACP 默认权限模式是 `ask`:写文件、改文件、执行命令前会向
167
198
 
168
199
  | 工具 | 说明 | 是否需要授权 |
169
200
  | --- | --- | --- |
170
- | `read_file` | 读取文本文件,带行号,支持 offset/limit | 否 |
171
- | `glob` | 按 glob 查文件 | 否 |
172
- | `grep` | 正则搜索文件内容 | 否 |
173
- | `write_file` | 创建/覆盖文件 | 是 |
174
- | `edit_file` | 精确字符串替换 | 是 |
175
- | `bash` | 在 workspace 内执行 bash 命令 | 是 |
201
+ | `read_file` | 文本文件(带行号、offset/limit、超长行截断);PNG/JPG/GIF/WebP 以多模态图片返回 | 否 |
202
+ | `write_file` | 创建/覆盖文件(已存在的文件需先 read 过;返回新文件/变更 diff) | 是 |
203
+ | `edit_file` | 精确替换,支持单次多处编辑(`edits[]` 原子应用);弯/直引号自动归一化 | 是 |
204
+ | `glob` | 按 glob 查文件(git 仓库内遵循 `.gitignore`) | 否 |
205
+ | `grep` | 正则搜索:上下文行(`context`)、跨行匹配(`multiline`)、`.gitignore` 感知 | 否 |
206
+ | `bash` | 用户 shell 执行;**cd 跨调用持久**、登录环境快照、进程组 kill、头尾截断;`run_in_background` 后台运行 | 是(只读命令免确认) |
207
+ | `bash_output` | 读取后台任务输出(`task_id` 可选,`wait: true` 等待最多 5s;无 id 时列出全部任务) | 否 |
208
+ | `todo_write` | 任务清单(`[x]/[~]/[ ]`),多步任务防漂移 | 否 |
209
+ | `ask_model` | 单次问答式分派:把子问题发给某角色的模型,答案回入对话 | 否 |
210
+ | `dispatch_agent` | 派发子 Agent:独立模型 + 工具白名单 + 自己的回合循环,只回传最终报告 | 是 |
211
+
212
+ **bash 免确认规则**:`ls`/`cat`/`grep`/`git status` 等只读命令(含管道、`2>/dev/null` 等无害重定向)自动放行并在结果行标注 `(read-only)`;写入重定向、命令替换、危险参数(`find -delete`、`sed -i`…)照常逐次确认。连续重复调用(含 A-B-A-B 振荡)会被熔断并引导换路子。
176
213
 
177
214
  所有路径默认限制在任务 workspace(`cwd`)内;`..` 越界会被拒绝,除非显式设置 `TRANSCODE_ALLOW_OUTSIDE_CWD=1`。
178
215
 
216
+ ## 子任务分派
217
+
218
+ 主 Agent 可以把工作派给不同角色的模型(角色经 `/route` 配置,见上文档案与路由):
219
+
220
+ - **`ask_model`**:单次专家问答(分析、设计取舍、审查、看图),无工具、一次调用
221
+ - **`dispatch_agent`**:多步研究型子任务 —— 子 Agent 用角色档案的模型 + 工具白名单(默认只读三件套)跑自己的循环。上下文契约是**任务进、报告出**:子 Agent 看不到主对话,任务描述必须自包含;只有最终报告回入主对话。派发本身需用户 y/n 授权,子 Agent 禁止递归派发,回合上限 25
222
+ - **图片自动代理**:配置了 `routing.vision` 时,工具产生的图片自动经视觉模型转文字描述,主模型无需多模态能力
223
+
224
+ 主对话有防护栏:探索停滞(30 次零写入)自动催促、无视则强制终止(`stalled`);交付后长尾钻探会被收尾提醒;上下文接近上限自动摘要压缩(`TRANSCODE_COMPACT_CHARS`,默认 20 万字符,0 关闭)。
225
+
226
+ ## 方案先行
227
+
228
+ `/plan <任务描述>` 进入只读探索模式:变更类工具全部被拒并引导模型产出**编号实施方案**(以 `PLAN READY` 结束),你确认方案后再让它执行 —— 探索和动手分离,防止一上来就改错。
229
+
179
230
  ## 上下文
180
231
 
181
- 每次 turn 会加载 workspace 下的 `AGENTS.md`、`CLAUDE.md`、`TRANSCODE.md`、`.transcode/AGENTS.md`(存在时)并注入系统提示,因此 multica 写入的任务说明、仓库约定都能被 Agent 看到。
232
+ 每次 turn 按优先级加载 workspace 下的 `TRANS.md`、`AGENTS.md`、`CLAUDE.md`、`TRANSCODE.md`、`.transcode/AGENTS.md`(存在时)注入系统提示。REPL 里 `/init` 可让 Agent 自行探索仓库并生成 `TRANS.md`(项目背景 / 命令 / 架构 / 约定)。
182
233
 
183
234
  ## ACP 协议
184
235
 
@@ -188,8 +239,8 @@ ACP 默认权限模式是 `ask`:写文件、改文件、执行命令前会向
188
239
 
189
240
  - 不支持 MCP(会忽略 `mcpServers` 并在 stderr 提示)
190
241
  - 不支持 ACP session 持久化:`loadSession: false`,进程内 session 在进程退出后丢失
191
- - 只处理文本 prompt;图片/音频/嵌入式资源暂不支持
192
- - 没有 Web 搜索、子 Agent、hooks、自动压缩
242
+ - prompt 仍以文本为主;图片只支持 `read_file` 读取(≤3MB,多模态模型直读,其余经 vision 角色转述)
243
+ - 没有 Web 搜索、hooks、自动压缩;子 Agent 为隔离式(fork 继承上下文模式规划中)
193
244
  - 工具输出有长度上限,避免单次上下文爆炸
194
245
  - `TRANSCODE_MOCK=1` 仅用于协议 smoke test,不会调用真实模型
195
246
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trans-ai/trans-code",
3
- "version": "0.2.4",
3
+ "version": "0.4.0",
4
4
  "description": "AI-powered multi-model coding CLI",
5
5
  "type": "module",
6
6
  "license": "UNLICENSED",
@@ -145,7 +145,10 @@ export class AcpSession {
145
145
  });
146
146
 
147
147
  this.trimHistory();
148
- return { stopReason: result.stopReason as AcpStopReason };
148
+ // 'stalled' has no ACP counterpart; report it as the closest reason.
149
+ const stopReason =
150
+ result.stopReason === 'stalled' ? 'max_turn_requests' : result.stopReason;
151
+ return { stopReason: stopReason as AcpStopReason };
149
152
  } catch (error) {
150
153
  if (signal.aborted) return { stopReason: 'cancelled' };
151
154
 
@@ -50,7 +50,11 @@ function scriptedModel(steps: ScriptStep[]): BaseChatModel {
50
50
  })();
51
51
  },
52
52
  };
53
- return { bindTools: () => runnable } as unknown as BaseChatModel;
53
+ const model = {
54
+ bindTools: () => runnable,
55
+ invoke: async () => ({ content: '摘要:任务是更新 README,已完成探索,接下来写入。' }),
56
+ };
57
+ return model as unknown as BaseChatModel;
54
58
  }
55
59
 
56
60
  const fakeTool: AgentTool = {
@@ -119,6 +123,177 @@ describe('runAgentLoop', () => {
119
123
  .toBe(true);
120
124
  });
121
125
 
126
+ test('tool images flow into the ToolMessage as multimodal blocks', async () => {
127
+ const imageTool: AgentTool = {
128
+ ...fakeTool,
129
+ async execute() {
130
+ return {
131
+ output: 'here is the screenshot',
132
+ images: [{ data: 'aW1hZ2U=', mediaType: 'image/png' }],
133
+ };
134
+ },
135
+ };
136
+
137
+ const result = await runAgentLoop({
138
+ model: stubModel(),
139
+ cwd: '/tmp',
140
+ messages: [],
141
+ systemPrompt: 'test',
142
+ tools: [imageTool],
143
+ onEvent: () => {},
144
+ });
145
+
146
+ const toolMessage = result.messages.find((message) => message.getType() === 'tool');
147
+ const content = toolMessage?.content as unknown;
148
+ expect(Array.isArray(content)).toBe(true);
149
+ const blocks = content as Array<{ type: string; image_url?: { url: string } }>;
150
+ expect(blocks.some((block) => block.type === 'text')).toBe(true);
151
+ const image = blocks.find((block) => block.type === 'image_url');
152
+ expect(image?.image_url?.url).toBe('data:image/png;base64,aW1hZ2U=');
153
+ });
154
+
155
+ test('images are auto-described through the vision proxy when provided', async () => {
156
+ const imageTool: AgentTool = {
157
+ ...fakeTool,
158
+ async execute() {
159
+ return {
160
+ output: 'screenshot captured',
161
+ images: [{ data: 'aW1n', mediaType: 'image/png' }],
162
+ };
163
+ },
164
+ };
165
+
166
+ const result = await runAgentLoop({
167
+ model: stubModel(),
168
+ cwd: '/tmp',
169
+ messages: [],
170
+ systemPrompt: 'test',
171
+ tools: [imageTool],
172
+ onEvent: () => {},
173
+ describeImages: async () => '截图显示 429 余额不足报错',
174
+ });
175
+
176
+ const toolMessage = result.messages.find((message) => message.getType() === 'tool');
177
+ expect(Array.isArray(toolMessage?.content)).toBe(false);
178
+ expect(String(toolMessage?.content)).toContain('截图显示 429 余额不足报错');
179
+ });
180
+
181
+ test('vision proxy failure falls back to raw image blocks', async () => {
182
+ const imageTool: AgentTool = {
183
+ ...fakeTool,
184
+ async execute() {
185
+ return {
186
+ output: 'screenshot captured',
187
+ images: [{ data: 'aW1n', mediaType: 'image/png' }],
188
+ };
189
+ },
190
+ };
191
+
192
+ const result = await runAgentLoop({
193
+ model: stubModel(),
194
+ cwd: '/tmp',
195
+ messages: [],
196
+ systemPrompt: 'test',
197
+ tools: [imageTool],
198
+ onEvent: () => {},
199
+ describeImages: async () => {
200
+ throw new Error('vision model offline');
201
+ },
202
+ });
203
+
204
+ const toolMessage = result.messages.find((message) => message.getType() === 'tool');
205
+ const content = toolMessage?.content as Array<{ type: string }>;
206
+ expect(Array.isArray(content)).toBe(true);
207
+ expect(content[1]?.type).toBe('image_url');
208
+ });
209
+
210
+ test('auto-compacts the conversation when the char budget is exceeded', async () => {
211
+ process.env.TRANSCODE_COMPACT_CHARS = '1200';
212
+ const events: AgentEvent[] = [];
213
+ const chatty: AgentTool = {
214
+ ...fakeTool,
215
+ isMutating: false,
216
+ async execute() {
217
+ return `large chunk ${'x'.repeat(400)} done`;
218
+ },
219
+ };
220
+
221
+ const result = await runAgentLoop({
222
+ model: scriptedModel(
223
+ Array.from({ length: 10 }, (_, i) => ({ tool: 'fake' as const, args: JSON.stringify({ n: i }) })),
224
+ ),
225
+ cwd: '/tmp',
226
+ messages: [],
227
+ systemPrompt: 'test',
228
+ tools: [chatty],
229
+ onEvent: (event) => events.push(event),
230
+ });
231
+
232
+ try {
233
+ const text = events
234
+ .filter((event) => event.type === 'text')
235
+ .map((event) => (event as { text: string }).text)
236
+ .join('');
237
+ expect(text).toContain('自动压缩');
238
+ expect(
239
+ result.messages.some((message) =>
240
+ message.content.toString().includes('[conversation summary]'),
241
+ ),
242
+ ).toBe(true);
243
+ // The compacted history must not start with an orphaned tool message.
244
+ expect(result.messages[1]?.getType()).not.toBe('tool');
245
+ } finally {
246
+ delete process.env.TRANSCODE_COMPACT_CHARS;
247
+ }
248
+ });
249
+
250
+ test('plan mode denies mutations and allows read-only exploration', async () => {
251
+ let writes = 0;
252
+ let reads = 0;
253
+ const tools: AgentTool[] = [
254
+ {
255
+ ...fakeTool,
256
+ name: 'write_file',
257
+ isMutating: true,
258
+ async execute() {
259
+ writes++;
260
+ return 'written';
261
+ },
262
+ },
263
+ {
264
+ ...fakeTool,
265
+ name: 'read_file',
266
+ isMutating: false,
267
+ async execute() {
268
+ reads++;
269
+ return 'content';
270
+ },
271
+ },
272
+ ];
273
+
274
+ const events: AgentEvent[] = [];
275
+ const result = await runAgentLoop({
276
+ model: scriptedModel([
277
+ { tool: 'read_file', args: '{"path":"a"}' },
278
+ { tool: 'write_file', args: '{"path":"a"}' },
279
+ ]),
280
+ cwd: '/tmp',
281
+ messages: [],
282
+ systemPrompt: 'test',
283
+ tools,
284
+ planMode: true,
285
+ onEvent: (event) => events.push(event),
286
+ });
287
+
288
+ expect(result.stopReason).toBe('end_turn');
289
+ expect(reads).toBe(1);
290
+ expect(writes).toBe(0);
291
+ const denied = events.find(
292
+ (event) => event.type === 'tool_result' && event.output.includes('Plan mode'),
293
+ );
294
+ expect(denied).toBeDefined();
295
+ });
296
+
122
297
  test('mutating tools without isReadOnly still request permission', async () => {
123
298
  let permissionAsked = 0;
124
299
  await runAgentLoop({
@@ -353,4 +528,165 @@ describe('runAgentLoop', () => {
353
528
  );
354
529
  expect(nudge).toBeUndefined();
355
530
  });
531
+
532
+ test('nudges the model to wrap up when exploring long after a real file write', async () => {
533
+ const reader: AgentTool = {
534
+ ...fakeTool,
535
+ name: 'reader',
536
+ isMutating: false,
537
+ async execute() {
538
+ return 'ok';
539
+ },
540
+ };
541
+ const writeFile: AgentTool = { ...fakeTool, name: 'write_file' };
542
+
543
+ const steps: Array<{ tool: string; args: string }> = [
544
+ { tool: 'write_file', args: '{"n":-1}' },
545
+ ...Array.from({ length: 44 }, (_, i) => ({
546
+ tool: 'reader',
547
+ args: JSON.stringify({ n: i }),
548
+ })),
549
+ ];
550
+
551
+ const result = await runAgentLoop({
552
+ model: scriptedModel(steps),
553
+ cwd: '/tmp',
554
+ messages: [],
555
+ systemPrompt: 'test',
556
+ tools: [reader, writeFile],
557
+ onEvent: () => {},
558
+ });
559
+
560
+ const nudges = result.messages.filter(
561
+ (message) =>
562
+ message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
563
+ );
564
+ expect(nudges.length).toBe(1);
565
+ });
566
+
567
+ test('mutating bash does not count as a delivered file — no wrap-up nudge', async () => {
568
+ const result = await runAgentLoop({
569
+ model: scriptedModel(
570
+ Array.from({ length: 45 }, (_, i) => ({
571
+ tool: 'fake' as const,
572
+ args: JSON.stringify({ n: i }),
573
+ })),
574
+ ),
575
+ cwd: '/tmp',
576
+ messages: [],
577
+ systemPrompt: 'test',
578
+ tools: [fakeTool], // mutating, but not a file write
579
+ onEvent: () => {},
580
+ });
581
+
582
+ const wrapUp = result.messages.find(
583
+ (message) =>
584
+ message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
585
+ );
586
+ expect(wrapUp).toBeUndefined();
587
+ });
588
+
589
+ test('force-stops when the model keeps exploring after an ignored stall nudge', async () => {
590
+ const reader: AgentTool = {
591
+ ...fakeTool,
592
+ isMutating: false,
593
+ async execute() {
594
+ return 'ok';
595
+ },
596
+ };
597
+
598
+ const result = await runAgentLoop({
599
+ model: scriptedModel(
600
+ Array.from({ length: 60 }, (_, i) => ({
601
+ tool: 'fake' as const,
602
+ args: JSON.stringify({ n: i }),
603
+ })),
604
+ ),
605
+ cwd: '/tmp',
606
+ messages: [],
607
+ systemPrompt: 'test',
608
+ tools: [reader],
609
+ onEvent: () => {},
610
+ });
611
+
612
+ // Stall nudge at 30 calls, grace of 15 more, then a hard stop.
613
+ expect(result.stopReason).toBe('stalled');
614
+ const notice = result.messages.find(
615
+ (message) =>
616
+ message.getType() === 'ai' && message.content.toString().includes('ignored the earlier reminder'),
617
+ );
618
+ expect(notice).toBeDefined();
619
+ });
620
+
621
+ test('starting the deliverable during the grace window cancels the hard stop', async () => {
622
+ const reader: AgentTool = {
623
+ ...fakeTool,
624
+ isMutating: false,
625
+ async execute() {
626
+ return 'ok';
627
+ },
628
+ };
629
+ const writeFile: AgentTool = { ...fakeTool, name: 'write_file' };
630
+
631
+ // 32 reads (past the nudge), then write, then a few more reads.
632
+ const steps: Array<{ tool: string; args: string }> = [
633
+ ...Array.from({ length: 32 }, (_, i) => ({
634
+ tool: 'fake',
635
+ args: JSON.stringify({ n: i }),
636
+ })),
637
+ { tool: 'write_file', args: '{"content":"x"}' },
638
+ ...Array.from({ length: 10 }, (_, i) => ({
639
+ tool: 'fake',
640
+ args: JSON.stringify({ m: i }),
641
+ })),
642
+ ];
643
+
644
+ const result = await runAgentLoop({
645
+ model: scriptedModel(steps),
646
+ cwd: '/tmp',
647
+ messages: [],
648
+ systemPrompt: 'test',
649
+ tools: [reader, writeFile],
650
+ onEvent: () => {},
651
+ });
652
+
653
+ expect(result.stopReason).not.toBe('stalled');
654
+ });
655
+
656
+ test('a single mutating bash followed by reads does not trigger the wrap-up nudge', async () => {
657
+ const reader: AgentTool = {
658
+ ...fakeTool,
659
+ name: 'reader',
660
+ isMutating: false,
661
+ async execute() {
662
+ return 'ok';
663
+ },
664
+ };
665
+ const bashLike: AgentTool = { ...fakeTool, name: 'bash' }; // mutating, not a file write
666
+
667
+ const steps: Array<{ tool: string; args: string }> = [
668
+ { tool: 'bash', args: '{"n":-1}' },
669
+ ...Array.from({ length: 44 }, (_, i) => ({
670
+ tool: 'reader',
671
+ args: JSON.stringify({ n: i }),
672
+ })),
673
+ ];
674
+
675
+ const result = await runAgentLoop({
676
+ model: scriptedModel(steps),
677
+ cwd: '/tmp',
678
+ messages: [],
679
+ systemPrompt: 'test',
680
+ tools: [reader, bashLike],
681
+ onEvent: () => {},
682
+ });
683
+
684
+ const wrapUp = result.messages.find(
685
+ (message) =>
686
+ message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
687
+ );
688
+ // Regression: a misjudged "mutating" bash used to falsely announce
689
+ // "the deliverable has already been written" and abort honest work.
690
+ expect(wrapUp).toBeUndefined();
691
+ });
356
692
  });