@trans-ai/trans-code 0.2.3 → 0.3.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 +58 -17
- package/package.json +1 -1
- package/src/acp/session.ts +15 -1
- package/src/agent/loop.test.ts +401 -1
- package/src/agent/loop.ts +137 -13
- package/src/agent/system-prompt.test.ts +24 -1
- package/src/agent/system-prompt.ts +25 -0
- package/src/agent/tools/ask-model.test.ts +54 -0
- package/src/agent/tools/ask-model.ts +44 -0
- package/src/agent/tools/dispatch.test.ts +115 -0
- package/src/agent/tools/dispatch.ts +141 -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 +27 -2
- package/src/agent/tools/search.test.ts +55 -1
- package/src/agent/tools/search.ts +56 -8
- package/src/agent/tools/session.ts +9 -0
- package/src/agent/tools/todo.test.ts +54 -0
- package/src/agent/tools/todo.ts +47 -0
- package/src/agent/tools/types.ts +13 -1
- package/src/cli.ts +1 -0
- package/src/commands.ts +37 -2
- package/src/config.ts +21 -3
- package/src/main.tsx +6 -8
- package/src/provider/provider.test.ts +117 -0
- package/src/provider/provider.ts +278 -34
- package/src/provider/routing.test.ts +109 -0
- package/src/screens/REPL.tsx +204 -31
- package/src/screens/banner.test.ts +21 -0
- package/src/screens/banner.ts +9 -0
- package/src/version.ts +1 -1
package/README.md
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
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
|
|
|
@@ -26,10 +26,12 @@ bun link
|
|
|
26
26
|
|
|
27
27
|
## 配置模型
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
三种方式,从简到繁:
|
|
30
|
+
|
|
31
|
+
**1. 环境变量**(注册表 id 或 `provider:model`):
|
|
30
32
|
|
|
31
33
|
```bash
|
|
32
|
-
# 注册表 id: opus | gpt | deepseek | glm | minimax | kimi
|
|
34
|
+
# 注册表 id: opus | gpt | deepseek | glm | glmc | minimax | kimi | custom
|
|
33
35
|
export ANTHROPIC_API_KEY=...
|
|
34
36
|
export DEEPSEEK_API_KEY=...
|
|
35
37
|
export TRANSCODE_MODEL=deepseek
|
|
@@ -39,6 +41,27 @@ export OPENAI_API_KEY=...
|
|
|
39
41
|
export TRANSCODE_MODEL=openai:gpt-4o
|
|
40
42
|
```
|
|
41
43
|
|
|
44
|
+
**2. REPL 交互配置**(`/models`):三级流程——选厂商 → 选模型(常用列表 + 自定义模型名)→ 输入 key(已存的可回车沿用)。key 确认后**自动测试连通性**,失败显示 API 原始报错并可重输。`custom` 支持任意 OpenAI 兼容网关(输入 base URL + 模型名)。
|
|
45
|
+
|
|
46
|
+
**3. 档案 + 角色路由**(`~/.transcode.json`,任务级模型分派):
|
|
47
|
+
|
|
48
|
+
```jsonc
|
|
49
|
+
{
|
|
50
|
+
"apiKeys": { "glm": "…", "deepseek": "…" },
|
|
51
|
+
"profiles": {
|
|
52
|
+
"glm-coding": { "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", "model": "glm-4.6", "keyId": "glm" },
|
|
53
|
+
"glm-vision": { "baseUrl": "https://open.bigmodel.cn/api/paas/v4", "model": "glm-4.6v", "keyId": "glm" }
|
|
54
|
+
},
|
|
55
|
+
"routing": { "default": "glm-coding", "analysis": "glm-coding", "vision": "glm-vision" }
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
- **Profile**:命名档案 = 地址 + 模型名 + keyId(智谱普通端点 / CodePlan 端点各一个档案,共用一把 key;同名覆盖内置注册表)
|
|
60
|
+
- **Role**:任意命名的角色 → 档案,`/route analysis glmc` 设置、`/route` 查看、`/route design -` 删除
|
|
61
|
+
- ACP `session/set_model` 直接收档案名,宿主可按任务指派不同模型
|
|
62
|
+
|
|
63
|
+
> **GLM Coding Plan 用户**:套餐只在 Coding 专用端点生效,请用 `glmc` 档案(`https://open.bigmodel.cn/api/coding/paas/v4`);普通 `glm` 端点会报"429 余额不足"。
|
|
64
|
+
|
|
42
65
|
### 复用 Claude Code 的 Anthropic 兼容配置
|
|
43
66
|
|
|
44
67
|
如果你已经有一个 Anthropic 兼容网关(例如 DeepSeek 的 `/anthropic` 端点),可以直接沿用 Claude Code 的环境变量,不需要改 `TRANSCODE_MODEL`:
|
|
@@ -70,15 +93,18 @@ bun run test:acp:real # 完整 ACP + 工具调用(会创建临时 works
|
|
|
70
93
|
|
|
71
94
|
| 变量 | 说明 |
|
|
72
95
|
| --- | --- |
|
|
73
|
-
| `TRANSCODE_MODEL` | 默认模型。注册表 id
|
|
96
|
+
| `TRANSCODE_MODEL` | 默认模型。注册表 id、档案名、`provider:model`,或裸模型名 |
|
|
74
97
|
| `TRANSCODE_DEFAULT_PROVIDER` | 裸模型名走哪个 provider,默认 `openai` |
|
|
75
|
-
| `TRANSCODE_PERMISSION_MODE` | `ask`(默认) / `auto` / `readonly` |
|
|
98
|
+
| `TRANSCODE_PERMISSION_MODE` | `ask`(默认) / `auto` / `readonly`;REPL 里可用 `/mode` 运行时切换 |
|
|
76
99
|
| `TRANSCODE_ALLOW_OUTSIDE_CWD` | 设为 `1` 才允许读写工作区之外的路径 |
|
|
77
100
|
| `TRANSCODE_BASE_URL` | 覆盖当前模型的 base URL(所有 provider) |
|
|
78
101
|
| `TRANSCODE_MAX_TOKENS` | 单次回复的 `max_tokens`,默认 `8192` |
|
|
102
|
+
| `TRANSCODE_MAX_TURNS` | Agent 工具回合上限,默认 `200`;触顶会明确提示并写入对话 |
|
|
103
|
+
| `TRANSCODE_SUBAGENT_MAX_TURNS` | 子 Agent 回合上限,默认 `25` |
|
|
104
|
+
| `TRANSCODE_SKIP_MODEL_CHECK` | 设为 `1` 跳过 /models 的连通性测试 |
|
|
79
105
|
| `TRANSCODE_MOCK` | 设为 `1` 使用本地 mock 模型(仅用于协议测试) |
|
|
80
106
|
|
|
81
|
-
`provider:model` 支持的前缀:`openai`、`anthropic`、`deepseek`、`glm`、`minimax`、`kimi`、`moonshot`。
|
|
107
|
+
`provider:model` 支持的前缀:`openai`、`anthropic`、`deepseek`、`glm`、`glmc`、`minimax`、`kimi`、`moonshot`。
|
|
82
108
|
裸模型名会使用 `TRANSCODE_DEFAULT_PROVIDER`;`openai` 前缀和裸模型名可以用 `OPENAI_BASE_URL` 指向兼容网关,`TRANSCODE_BASE_URL` 则可以覆盖任意 provider。
|
|
83
109
|
|
|
84
110
|
## 本地运行
|
|
@@ -167,18 +193,33 @@ ACP 默认权限模式是 `ask`:写文件、改文件、执行命令前会向
|
|
|
167
193
|
|
|
168
194
|
| 工具 | 说明 | 是否需要授权 |
|
|
169
195
|
| --- | --- | --- |
|
|
170
|
-
| `read_file` |
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `bash` |
|
|
196
|
+
| `read_file` | 文本文件(带行号、offset/limit、超长行截断);PNG/JPG/GIF/WebP 以多模态图片返回 | 否 |
|
|
197
|
+
| `write_file` | 创建/覆盖文件(已存在的文件需先 read 过;返回新文件/变更 diff) | 是 |
|
|
198
|
+
| `edit_file` | 精确替换,支持单次多处编辑(`edits[]` 原子应用);弯/直引号自动归一化 | 是 |
|
|
199
|
+
| `glob` | 按 glob 查文件(git 仓库内遵循 `.gitignore`) | 否 |
|
|
200
|
+
| `grep` | 正则搜索:上下文行(`context`)、跨行匹配(`multiline`)、`.gitignore` 感知 | 否 |
|
|
201
|
+
| `bash` | 用户 shell 执行;**cd 跨调用持久**、登录环境快照、进程组 kill、头尾截断 | 是(只读命令免确认) |
|
|
202
|
+
| `todo_write` | 任务清单(`[x]/[~]/[ ]`),多步任务防漂移 | 否 |
|
|
203
|
+
| `ask_model` | 单次问答式分派:把子问题发给某角色的模型,答案回入对话 | 否 |
|
|
204
|
+
| `dispatch_agent` | 派发子 Agent:独立模型 + 工具白名单 + 自己的回合循环,只回传最终报告 | 是 |
|
|
205
|
+
|
|
206
|
+
**bash 免确认规则**:`ls`/`cat`/`grep`/`git status` 等只读命令(含管道、`2>/dev/null` 等无害重定向)自动放行并在结果行标注 `(read-only)`;写入重定向、命令替换、危险参数(`find -delete`、`sed -i`…)照常逐次确认。连续重复调用(含 A-B-A-B 振荡)会被熔断并引导换路子。
|
|
176
207
|
|
|
177
208
|
所有路径默认限制在任务 workspace(`cwd`)内;`..` 越界会被拒绝,除非显式设置 `TRANSCODE_ALLOW_OUTSIDE_CWD=1`。
|
|
178
209
|
|
|
210
|
+
## 子任务分派
|
|
211
|
+
|
|
212
|
+
主 Agent 可以把工作派给不同角色的模型(角色经 `/route` 配置,见上文档案与路由):
|
|
213
|
+
|
|
214
|
+
- **`ask_model`**:单次专家问答(分析、设计取舍、审查、看图),无工具、一次调用
|
|
215
|
+
- **`dispatch_agent`**:多步研究型子任务 —— 子 Agent 用角色档案的模型 + 工具白名单(默认只读三件套)跑自己的循环。上下文契约是**任务进、报告出**:子 Agent 看不到主对话,任务描述必须自包含;只有最终报告回入主对话。派发本身需用户 y/n 授权,子 Agent 禁止递归派发,回合上限 25
|
|
216
|
+
- **图片自动代理**:配置了 `routing.vision` 时,工具产生的图片自动经视觉模型转文字描述,主模型无需多模态能力
|
|
217
|
+
|
|
218
|
+
主对话有防护栏:探索停滞(30 次零写入)自动催促、无视则强制终止(`stalled`);交付后长尾钻探会被收尾提醒。
|
|
219
|
+
|
|
179
220
|
## 上下文
|
|
180
221
|
|
|
181
|
-
每次 turn
|
|
222
|
+
每次 turn 按优先级加载 workspace 下的 `TRANS.md`、`AGENTS.md`、`CLAUDE.md`、`TRANSCODE.md`、`.transcode/AGENTS.md`(存在时)注入系统提示。REPL 里 `/init` 可让 Agent 自行探索仓库并生成 `TRANS.md`(项目背景 / 命令 / 架构 / 约定)。
|
|
182
223
|
|
|
183
224
|
## ACP 协议
|
|
184
225
|
|
|
@@ -188,8 +229,8 @@ ACP 默认权限模式是 `ask`:写文件、改文件、执行命令前会向
|
|
|
188
229
|
|
|
189
230
|
- 不支持 MCP(会忽略 `mcpServers` 并在 stderr 提示)
|
|
190
231
|
- 不支持 ACP session 持久化:`loadSession: false`,进程内 session 在进程退出后丢失
|
|
191
|
-
-
|
|
192
|
-
- 没有 Web
|
|
232
|
+
- prompt 仍以文本为主;图片只支持 `read_file` 读取(≤3MB,多模态模型直读,其余经 vision 角色转述)
|
|
233
|
+
- 没有 Web 搜索、hooks、自动压缩;子 Agent 为隔离式(fork 继承上下文模式规划中)
|
|
193
234
|
- 工具输出有长度上限,避免单次上下文爆炸
|
|
194
235
|
- `TRANSCODE_MOCK=1` 仅用于协议 smoke test,不会调用真实模型
|
|
195
236
|
|
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
|
|
|
@@ -195,6 +198,17 @@ export class AcpSession {
|
|
|
195
198
|
return;
|
|
196
199
|
}
|
|
197
200
|
|
|
201
|
+
if (event.type === 'max_turns_reached') {
|
|
202
|
+
this.host.sendUpdate(this.id, {
|
|
203
|
+
sessionUpdate: 'agent_message_chunk',
|
|
204
|
+
content: {
|
|
205
|
+
type: 'text',
|
|
206
|
+
text: `\n⚠ Reached maximum number of turns (${event.maxTurns}). The task is incomplete — say "continue" or raise TRANSCODE_MAX_TURNS.\n`,
|
|
207
|
+
},
|
|
208
|
+
});
|
|
209
|
+
return;
|
|
210
|
+
}
|
|
211
|
+
|
|
198
212
|
if (event.type === 'tool_call') {
|
|
199
213
|
this.host.sendUpdate(this.id, {
|
|
200
214
|
sessionUpdate: 'tool_call',
|
package/src/agent/loop.test.ts
CHANGED
|
@@ -119,6 +119,90 @@ describe('runAgentLoop', () => {
|
|
|
119
119
|
.toBe(true);
|
|
120
120
|
});
|
|
121
121
|
|
|
122
|
+
test('tool images flow into the ToolMessage as multimodal blocks', async () => {
|
|
123
|
+
const imageTool: AgentTool = {
|
|
124
|
+
...fakeTool,
|
|
125
|
+
async execute() {
|
|
126
|
+
return {
|
|
127
|
+
output: 'here is the screenshot',
|
|
128
|
+
images: [{ data: 'aW1hZ2U=', mediaType: 'image/png' }],
|
|
129
|
+
};
|
|
130
|
+
},
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
const result = await runAgentLoop({
|
|
134
|
+
model: stubModel(),
|
|
135
|
+
cwd: '/tmp',
|
|
136
|
+
messages: [],
|
|
137
|
+
systemPrompt: 'test',
|
|
138
|
+
tools: [imageTool],
|
|
139
|
+
onEvent: () => {},
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
const toolMessage = result.messages.find((message) => message.getType() === 'tool');
|
|
143
|
+
const content = toolMessage?.content as unknown;
|
|
144
|
+
expect(Array.isArray(content)).toBe(true);
|
|
145
|
+
const blocks = content as Array<{ type: string; image_url?: { url: string } }>;
|
|
146
|
+
expect(blocks.some((block) => block.type === 'text')).toBe(true);
|
|
147
|
+
const image = blocks.find((block) => block.type === 'image_url');
|
|
148
|
+
expect(image?.image_url?.url).toBe('data:image/png;base64,aW1hZ2U=');
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
test('images are auto-described through the vision proxy when provided', async () => {
|
|
152
|
+
const imageTool: AgentTool = {
|
|
153
|
+
...fakeTool,
|
|
154
|
+
async execute() {
|
|
155
|
+
return {
|
|
156
|
+
output: 'screenshot captured',
|
|
157
|
+
images: [{ data: 'aW1n', mediaType: 'image/png' }],
|
|
158
|
+
};
|
|
159
|
+
},
|
|
160
|
+
};
|
|
161
|
+
|
|
162
|
+
const result = await runAgentLoop({
|
|
163
|
+
model: stubModel(),
|
|
164
|
+
cwd: '/tmp',
|
|
165
|
+
messages: [],
|
|
166
|
+
systemPrompt: 'test',
|
|
167
|
+
tools: [imageTool],
|
|
168
|
+
onEvent: () => {},
|
|
169
|
+
describeImages: async () => '截图显示 429 余额不足报错',
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
const toolMessage = result.messages.find((message) => message.getType() === 'tool');
|
|
173
|
+
expect(Array.isArray(toolMessage?.content)).toBe(false);
|
|
174
|
+
expect(String(toolMessage?.content)).toContain('截图显示 429 余额不足报错');
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
test('vision proxy failure falls back to raw image blocks', async () => {
|
|
178
|
+
const imageTool: AgentTool = {
|
|
179
|
+
...fakeTool,
|
|
180
|
+
async execute() {
|
|
181
|
+
return {
|
|
182
|
+
output: 'screenshot captured',
|
|
183
|
+
images: [{ data: 'aW1n', mediaType: 'image/png' }],
|
|
184
|
+
};
|
|
185
|
+
},
|
|
186
|
+
};
|
|
187
|
+
|
|
188
|
+
const result = await runAgentLoop({
|
|
189
|
+
model: stubModel(),
|
|
190
|
+
cwd: '/tmp',
|
|
191
|
+
messages: [],
|
|
192
|
+
systemPrompt: 'test',
|
|
193
|
+
tools: [imageTool],
|
|
194
|
+
onEvent: () => {},
|
|
195
|
+
describeImages: async () => {
|
|
196
|
+
throw new Error('vision model offline');
|
|
197
|
+
},
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
const toolMessage = result.messages.find((message) => message.getType() === 'tool');
|
|
201
|
+
const content = toolMessage?.content as Array<{ type: string }>;
|
|
202
|
+
expect(Array.isArray(content)).toBe(true);
|
|
203
|
+
expect(content[1]?.type).toBe('image_url');
|
|
204
|
+
});
|
|
205
|
+
|
|
122
206
|
test('mutating tools without isReadOnly still request permission', async () => {
|
|
123
207
|
let permissionAsked = 0;
|
|
124
208
|
await runAgentLoop({
|
|
@@ -196,6 +280,322 @@ describe('runAgentLoop', () => {
|
|
|
196
280
|
onEvent: () => {},
|
|
197
281
|
});
|
|
198
282
|
|
|
199
|
-
|
|
283
|
+
// Windowed rule: the trailing call is the third {"a":1} within the last
|
|
284
|
+
// 6 calls, so it is blocked even though the calls were not consecutive.
|
|
285
|
+
expect(executions).toBe(3);
|
|
286
|
+
});
|
|
287
|
+
|
|
288
|
+
test('alternating A-B-A-B loops are blocked by the windowed counter', async () => {
|
|
289
|
+
let aRuns = 0;
|
|
290
|
+
let bRuns = 0;
|
|
291
|
+
const tools: AgentTool[] = [
|
|
292
|
+
{
|
|
293
|
+
...fakeTool,
|
|
294
|
+
name: 'A',
|
|
295
|
+
async execute() {
|
|
296
|
+
aRuns++;
|
|
297
|
+
return 'ok';
|
|
298
|
+
},
|
|
299
|
+
},
|
|
300
|
+
{
|
|
301
|
+
...fakeTool,
|
|
302
|
+
name: 'B',
|
|
303
|
+
async execute() {
|
|
304
|
+
bRuns++;
|
|
305
|
+
return 'ok';
|
|
306
|
+
},
|
|
307
|
+
},
|
|
308
|
+
];
|
|
309
|
+
|
|
310
|
+
await runAgentLoop({
|
|
311
|
+
model: scriptedModel([
|
|
312
|
+
{ tool: 'A' },
|
|
313
|
+
{ tool: 'B' },
|
|
314
|
+
{ tool: 'A' },
|
|
315
|
+
{ tool: 'B' },
|
|
316
|
+
{ tool: 'A' },
|
|
317
|
+
]),
|
|
318
|
+
cwd: '/tmp',
|
|
319
|
+
messages: [],
|
|
320
|
+
systemPrompt: 'test',
|
|
321
|
+
tools,
|
|
322
|
+
onEvent: () => {},
|
|
323
|
+
});
|
|
324
|
+
|
|
325
|
+
// A appears 3 times within the window → blocked on its third call.
|
|
326
|
+
expect(aRuns).toBe(2);
|
|
327
|
+
expect(bRuns).toBe(2);
|
|
328
|
+
});
|
|
329
|
+
|
|
330
|
+
test('hitting the turn cap is loud: event, notice message, stop reason', async () => {
|
|
331
|
+
const events: AgentEvent[] = [];
|
|
332
|
+
const infiniteTools = scriptedModel(
|
|
333
|
+
Array.from({ length: 20 }, () => ({ tool: 'fake' as const, args: '{"a":1}' })),
|
|
334
|
+
);
|
|
335
|
+
|
|
336
|
+
const result = await runAgentLoop({
|
|
337
|
+
model: infiniteTools,
|
|
338
|
+
cwd: '/tmp',
|
|
339
|
+
messages: [],
|
|
340
|
+
systemPrompt: 'test',
|
|
341
|
+
tools: [fakeTool],
|
|
342
|
+
maxTurns: 2,
|
|
343
|
+
onEvent: (event) => events.push(event),
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
expect(result.stopReason).toBe('max_turn_requests');
|
|
347
|
+
expect(events.some((event) => event.type === 'max_turns_reached')).toBe(true);
|
|
348
|
+
const notice = result.messages.find(
|
|
349
|
+
(message) => message.getType() === 'ai' && message.content.toString().includes('maximum number of turns'),
|
|
350
|
+
);
|
|
351
|
+
expect(notice).toBeDefined();
|
|
352
|
+
});
|
|
353
|
+
|
|
354
|
+
test('TRANSCODE_MAX_TURNS overrides the default cap', async () => {
|
|
355
|
+
process.env.TRANSCODE_MAX_TURNS = '3';
|
|
356
|
+
try {
|
|
357
|
+
const events: AgentEvent[] = [];
|
|
358
|
+
const infiniteTools = scriptedModel(
|
|
359
|
+
Array.from({ length: 20 }, () => ({ tool: 'fake' as const, args: '{"a":1}' })),
|
|
360
|
+
);
|
|
361
|
+
|
|
362
|
+
const result = await runAgentLoop({
|
|
363
|
+
model: infiniteTools,
|
|
364
|
+
cwd: '/tmp',
|
|
365
|
+
messages: [],
|
|
366
|
+
systemPrompt: 'test',
|
|
367
|
+
tools: [fakeTool],
|
|
368
|
+
onEvent: (event) => events.push(event),
|
|
369
|
+
});
|
|
370
|
+
|
|
371
|
+
expect(result.stopReason).toBe('max_turn_requests');
|
|
372
|
+
// Circuit breaker blocks execution from the 3rd identical call, but
|
|
373
|
+
// every turn still emits a tool_result event.
|
|
374
|
+
expect(events.filter((event) => event.type === 'tool_result').length).toBe(3);
|
|
375
|
+
} finally {
|
|
376
|
+
delete process.env.TRANSCODE_MAX_TURNS;
|
|
377
|
+
}
|
|
378
|
+
});
|
|
379
|
+
|
|
380
|
+
test('nudges the model after prolonged exploration without any mutation', async () => {
|
|
381
|
+
// read-only tool (isMutating false): pure exploration, never "acts".
|
|
382
|
+
const exploreTool: AgentTool = {
|
|
383
|
+
...fakeTool,
|
|
384
|
+
isMutating: false,
|
|
385
|
+
async execute() {
|
|
386
|
+
return 'ok';
|
|
387
|
+
},
|
|
388
|
+
};
|
|
389
|
+
// Vary args each call so the circuit breaker does not fire.
|
|
390
|
+
const steps = Array.from({ length: 40 }, (_, i) => ({
|
|
391
|
+
tool: 'fake' as const,
|
|
392
|
+
args: JSON.stringify({ n: i }),
|
|
393
|
+
}));
|
|
394
|
+
|
|
395
|
+
const result = await runAgentLoop({
|
|
396
|
+
model: scriptedModel(steps),
|
|
397
|
+
cwd: '/tmp',
|
|
398
|
+
messages: [],
|
|
399
|
+
systemPrompt: 'test',
|
|
400
|
+
tools: [exploreTool],
|
|
401
|
+
onEvent: () => {},
|
|
402
|
+
});
|
|
403
|
+
|
|
404
|
+
const nudge = result.messages.find(
|
|
405
|
+
(message) =>
|
|
406
|
+
message.getType() === 'ai' && message.content.toString().includes('Stop exploring'),
|
|
407
|
+
);
|
|
408
|
+
expect(nudge).toBeDefined();
|
|
409
|
+
});
|
|
410
|
+
|
|
411
|
+
test('no exploration nudge when the model acted early', async () => {
|
|
412
|
+
const writer: AgentTool = {
|
|
413
|
+
...fakeTool,
|
|
414
|
+
isMutating: true,
|
|
415
|
+
async execute() {
|
|
416
|
+
return 'ok';
|
|
417
|
+
},
|
|
418
|
+
};
|
|
419
|
+
// Mutate on call 1, keep exploring afterwards.
|
|
420
|
+
const steps = Array.from({ length: 40 }, (_, i) => ({
|
|
421
|
+
tool: 'fake' as const,
|
|
422
|
+
args: JSON.stringify({ n: i }),
|
|
423
|
+
}));
|
|
424
|
+
|
|
425
|
+
const result = await runAgentLoop({
|
|
426
|
+
model: scriptedModel(steps),
|
|
427
|
+
cwd: '/tmp',
|
|
428
|
+
messages: [],
|
|
429
|
+
systemPrompt: 'test',
|
|
430
|
+
tools: [writer],
|
|
431
|
+
onEvent: () => {},
|
|
432
|
+
});
|
|
433
|
+
|
|
434
|
+
const nudge = result.messages.find(
|
|
435
|
+
(message) =>
|
|
436
|
+
message.getType() === 'ai' && message.content.toString().includes('Stop exploring'),
|
|
437
|
+
);
|
|
438
|
+
expect(nudge).toBeUndefined();
|
|
439
|
+
});
|
|
440
|
+
|
|
441
|
+
test('nudges the model to wrap up when exploring long after a real file write', async () => {
|
|
442
|
+
const reader: AgentTool = {
|
|
443
|
+
...fakeTool,
|
|
444
|
+
name: 'reader',
|
|
445
|
+
isMutating: false,
|
|
446
|
+
async execute() {
|
|
447
|
+
return 'ok';
|
|
448
|
+
},
|
|
449
|
+
};
|
|
450
|
+
const writeFile: AgentTool = { ...fakeTool, name: 'write_file' };
|
|
451
|
+
|
|
452
|
+
const steps: Array<{ tool: string; args: string }> = [
|
|
453
|
+
{ tool: 'write_file', args: '{"n":-1}' },
|
|
454
|
+
...Array.from({ length: 44 }, (_, i) => ({
|
|
455
|
+
tool: 'reader',
|
|
456
|
+
args: JSON.stringify({ n: i }),
|
|
457
|
+
})),
|
|
458
|
+
];
|
|
459
|
+
|
|
460
|
+
const result = await runAgentLoop({
|
|
461
|
+
model: scriptedModel(steps),
|
|
462
|
+
cwd: '/tmp',
|
|
463
|
+
messages: [],
|
|
464
|
+
systemPrompt: 'test',
|
|
465
|
+
tools: [reader, writeFile],
|
|
466
|
+
onEvent: () => {},
|
|
467
|
+
});
|
|
468
|
+
|
|
469
|
+
const nudges = result.messages.filter(
|
|
470
|
+
(message) =>
|
|
471
|
+
message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
|
|
472
|
+
);
|
|
473
|
+
expect(nudges.length).toBe(1);
|
|
474
|
+
});
|
|
475
|
+
|
|
476
|
+
test('mutating bash does not count as a delivered file — no wrap-up nudge', async () => {
|
|
477
|
+
const result = await runAgentLoop({
|
|
478
|
+
model: scriptedModel(
|
|
479
|
+
Array.from({ length: 45 }, (_, i) => ({
|
|
480
|
+
tool: 'fake' as const,
|
|
481
|
+
args: JSON.stringify({ n: i }),
|
|
482
|
+
})),
|
|
483
|
+
),
|
|
484
|
+
cwd: '/tmp',
|
|
485
|
+
messages: [],
|
|
486
|
+
systemPrompt: 'test',
|
|
487
|
+
tools: [fakeTool], // mutating, but not a file write
|
|
488
|
+
onEvent: () => {},
|
|
489
|
+
});
|
|
490
|
+
|
|
491
|
+
const wrapUp = result.messages.find(
|
|
492
|
+
(message) =>
|
|
493
|
+
message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
|
|
494
|
+
);
|
|
495
|
+
expect(wrapUp).toBeUndefined();
|
|
496
|
+
});
|
|
497
|
+
|
|
498
|
+
test('force-stops when the model keeps exploring after an ignored stall nudge', async () => {
|
|
499
|
+
const reader: AgentTool = {
|
|
500
|
+
...fakeTool,
|
|
501
|
+
isMutating: false,
|
|
502
|
+
async execute() {
|
|
503
|
+
return 'ok';
|
|
504
|
+
},
|
|
505
|
+
};
|
|
506
|
+
|
|
507
|
+
const result = await runAgentLoop({
|
|
508
|
+
model: scriptedModel(
|
|
509
|
+
Array.from({ length: 60 }, (_, i) => ({
|
|
510
|
+
tool: 'fake' as const,
|
|
511
|
+
args: JSON.stringify({ n: i }),
|
|
512
|
+
})),
|
|
513
|
+
),
|
|
514
|
+
cwd: '/tmp',
|
|
515
|
+
messages: [],
|
|
516
|
+
systemPrompt: 'test',
|
|
517
|
+
tools: [reader],
|
|
518
|
+
onEvent: () => {},
|
|
519
|
+
});
|
|
520
|
+
|
|
521
|
+
// Stall nudge at 30 calls, grace of 15 more, then a hard stop.
|
|
522
|
+
expect(result.stopReason).toBe('stalled');
|
|
523
|
+
const notice = result.messages.find(
|
|
524
|
+
(message) =>
|
|
525
|
+
message.getType() === 'ai' && message.content.toString().includes('ignored the earlier reminder'),
|
|
526
|
+
);
|
|
527
|
+
expect(notice).toBeDefined();
|
|
528
|
+
});
|
|
529
|
+
|
|
530
|
+
test('starting the deliverable during the grace window cancels the hard stop', async () => {
|
|
531
|
+
const reader: AgentTool = {
|
|
532
|
+
...fakeTool,
|
|
533
|
+
isMutating: false,
|
|
534
|
+
async execute() {
|
|
535
|
+
return 'ok';
|
|
536
|
+
},
|
|
537
|
+
};
|
|
538
|
+
const writeFile: AgentTool = { ...fakeTool, name: 'write_file' };
|
|
539
|
+
|
|
540
|
+
// 32 reads (past the nudge), then write, then a few more reads.
|
|
541
|
+
const steps: Array<{ tool: string; args: string }> = [
|
|
542
|
+
...Array.from({ length: 32 }, (_, i) => ({
|
|
543
|
+
tool: 'fake',
|
|
544
|
+
args: JSON.stringify({ n: i }),
|
|
545
|
+
})),
|
|
546
|
+
{ tool: 'write_file', args: '{"content":"x"}' },
|
|
547
|
+
...Array.from({ length: 10 }, (_, i) => ({
|
|
548
|
+
tool: 'fake',
|
|
549
|
+
args: JSON.stringify({ m: i }),
|
|
550
|
+
})),
|
|
551
|
+
];
|
|
552
|
+
|
|
553
|
+
const result = await runAgentLoop({
|
|
554
|
+
model: scriptedModel(steps),
|
|
555
|
+
cwd: '/tmp',
|
|
556
|
+
messages: [],
|
|
557
|
+
systemPrompt: 'test',
|
|
558
|
+
tools: [reader, writeFile],
|
|
559
|
+
onEvent: () => {},
|
|
560
|
+
});
|
|
561
|
+
|
|
562
|
+
expect(result.stopReason).not.toBe('stalled');
|
|
563
|
+
});
|
|
564
|
+
|
|
565
|
+
test('a single mutating bash followed by reads does not trigger the wrap-up nudge', async () => {
|
|
566
|
+
const reader: AgentTool = {
|
|
567
|
+
...fakeTool,
|
|
568
|
+
name: 'reader',
|
|
569
|
+
isMutating: false,
|
|
570
|
+
async execute() {
|
|
571
|
+
return 'ok';
|
|
572
|
+
},
|
|
573
|
+
};
|
|
574
|
+
const bashLike: AgentTool = { ...fakeTool, name: 'bash' }; // mutating, not a file write
|
|
575
|
+
|
|
576
|
+
const steps: Array<{ tool: string; args: string }> = [
|
|
577
|
+
{ tool: 'bash', args: '{"n":-1}' },
|
|
578
|
+
...Array.from({ length: 44 }, (_, i) => ({
|
|
579
|
+
tool: 'reader',
|
|
580
|
+
args: JSON.stringify({ n: i }),
|
|
581
|
+
})),
|
|
582
|
+
];
|
|
583
|
+
|
|
584
|
+
const result = await runAgentLoop({
|
|
585
|
+
model: scriptedModel(steps),
|
|
586
|
+
cwd: '/tmp',
|
|
587
|
+
messages: [],
|
|
588
|
+
systemPrompt: 'test',
|
|
589
|
+
tools: [reader, bashLike],
|
|
590
|
+
onEvent: () => {},
|
|
591
|
+
});
|
|
592
|
+
|
|
593
|
+
const wrapUp = result.messages.find(
|
|
594
|
+
(message) =>
|
|
595
|
+
message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
|
|
596
|
+
);
|
|
597
|
+
// Regression: a misjudged "mutating" bash used to falsely announce
|
|
598
|
+
// "the deliverable has already been written" and abort honest work.
|
|
599
|
+
expect(wrapUp).toBeUndefined();
|
|
200
600
|
});
|
|
201
601
|
});
|