@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.
- package/README.md +68 -17
- package/package.json +1 -1
- package/src/acp/session.ts +4 -1
- package/src/agent/loop.test.ts +337 -1
- package/src/agent/loop.ts +166 -2
- package/src/agent/system-prompt.test.ts +24 -1
- package/src/agent/system-prompt.ts +21 -0
- package/src/agent/tools/ask-model.test.ts +54 -0
- package/src/agent/tools/ask-model.ts +44 -0
- package/src/agent/tools/bash.test.ts +42 -1
- package/src/agent/tools/bash.ts +202 -15
- package/src/agent/tools/dispatch.test.ts +157 -0
- package/src/agent/tools/dispatch.ts +151 -0
- package/src/agent/tools/files.test.ts +96 -0
- package/src/agent/tools/files.ts +111 -29
- package/src/agent/tools/fs-utils.ts +40 -0
- package/src/agent/tools/index.ts +29 -2
- package/src/agent/tools/powershell.test.ts +61 -0
- package/src/agent/tools/read-only.ts +16 -0
- package/src/agent/tools/search.test.ts +55 -1
- package/src/agent/tools/search.ts +56 -8
- package/src/agent/tools/session.ts +21 -0
- package/src/agent/tools/shell-paths.test.ts +65 -0
- package/src/agent/tools/shell-paths.ts +19 -0
- package/src/agent/tools/todo.test.ts +54 -0
- package/src/agent/tools/todo.ts +47 -0
- package/src/agent/tools/types.ts +15 -1
- package/src/cli.ts +2 -0
- package/src/commands.ts +55 -2
- package/src/config.ts +21 -3
- package/src/main.tsx +4 -4
- package/src/provider/model-list.test.ts +65 -0
- package/src/provider/provider.test.ts +117 -0
- package/src/provider/provider.ts +312 -34
- package/src/provider/routing.test.ts +109 -0
- package/src/screens/REPL.tsx +432 -35
- package/src/sessions/store.test.ts +91 -0
- package/src/sessions/store.ts +149 -0
- 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
|
|
5
|
+
- 终端侧:Ink REPL(命令:`help` / `models` / `mode` / `route` / `init` / `clear` / `exit`)
|
|
6
6
|
- Agent 侧:`transcode acp` 启动 ACP v1 stdio 服务,供 transonce、multica 等客户端调用
|
|
7
|
-
-
|
|
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
|
-
|
|
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
|
|
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` |
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `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
|
|
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
|
-
-
|
|
192
|
-
- 没有 Web
|
|
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
package/src/acp/session.ts
CHANGED
|
@@ -145,7 +145,10 @@ export class AcpSession {
|
|
|
145
145
|
});
|
|
146
146
|
|
|
147
147
|
this.trimHistory();
|
|
148
|
-
|
|
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
|
|
package/src/agent/loop.test.ts
CHANGED
|
@@ -50,7 +50,11 @@ function scriptedModel(steps: ScriptStep[]): BaseChatModel {
|
|
|
50
50
|
})();
|
|
51
51
|
},
|
|
52
52
|
};
|
|
53
|
-
|
|
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
|
});
|