@trans-ai/trans-code 0.2.4 → 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 CHANGED
@@ -2,10 +2,10 @@
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
 
@@ -26,10 +26,12 @@ bun link
26
26
 
27
27
  ## 配置模型
28
28
 
29
- 通过环境变量配置,模型可以是注册表 id,也可以是 `provider:model`:
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、`provider:model`,或裸模型名 |
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` | 读取文本文件,带行号,支持 offset/limit | 否 |
171
- | `glob` | 按 glob 查文件 | 否 |
172
- | `grep` | 正则搜索文件内容 | 否 |
173
- | `write_file` | 创建/覆盖文件 | 是 |
174
- | `edit_file` | 精确字符串替换 | 是 |
175
- | `bash` | 在 workspace 内执行 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 会加载 workspace 下的 `AGENTS.md`、`CLAUDE.md`、`TRANSCODE.md`、`.transcode/AGENTS.md`(存在时)并注入系统提示,因此 multica 写入的任务说明、仓库约定都能被 Agent 看到。
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
- - 只处理文本 prompt;图片/音频/嵌入式资源暂不支持
192
- - 没有 Web 搜索、子 Agent、hooks、自动压缩
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trans-ai/trans-code",
3
- "version": "0.2.4",
3
+ "version": "0.3.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
 
@@ -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({
@@ -353,4 +437,165 @@ describe('runAgentLoop', () => {
353
437
  );
354
438
  expect(nudge).toBeUndefined();
355
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();
600
+ });
356
601
  });
package/src/agent/loop.ts CHANGED
@@ -17,6 +17,7 @@ import {
17
17
  type ToolKind,
18
18
  type ToolSession,
19
19
  } from './tools/index.js';
20
+ import { askRole, getRouting } from '../provider/provider.js';
20
21
 
21
22
  export type AgentEvent =
22
23
  | { type: 'text'; text: string }
@@ -56,6 +57,7 @@ export type StopReason =
56
57
  | 'end_turn'
57
58
  | 'cancelled'
58
59
  | 'max_turn_requests'
60
+ | 'stalled'
59
61
  | 'refusal';
60
62
 
61
63
  export interface AgentLoopOptions {
@@ -70,6 +72,8 @@ export interface AgentLoopOptions {
70
72
  requestPermission?: RequestPermission;
71
73
  /** Session state shared across tool calls (shell cwd, read files). Created when absent. */
72
74
  toolSession?: ToolSession;
75
+ /** Vision proxy override (tests). Default: routing.vision → askRole('vision'). */
76
+ describeImages?: (images: Array<{ data: string; mediaType: string }>) => Promise<string>;
73
77
  }
74
78
 
75
79
  export interface AgentLoopResult {
@@ -205,6 +209,7 @@ async function runMockTurn(
205
209
  cwd: toolSession.cwd,
206
210
  signal: options.signal,
207
211
  session: toolSession,
212
+ requestPermission: options.requestPermission,
208
213
  })
209
214
  : { ok: false, output: 'Permission denied.' };
210
215
 
@@ -277,9 +282,18 @@ export async function runAgentLoop(
277
282
  // the model is drilling instead of delivering (observed with DeepSeek:
278
283
  // 272 read-only calls to "update a README"). Nudge it once mid-run.
279
284
  const EXPLORE_STALL_THRESHOLD = 30;
285
+ // Hard rail: when the stall nudge is ignored, stop burning turns.
286
+ const STALL_GRACE_CALLS = 15;
287
+ // Wrap-up detection: the deliverable was already written, but the model
288
+ // keeps exploring instead of summarizing and ending its turn.
289
+ const WRAP_UP_GAP = 20;
280
290
  let totalToolCalls = 0;
291
+ let callsSinceAction = 0;
281
292
  let hasActed = false;
293
+ let hasDelivered = false; // a real file write happened (write_file/edit_file)
282
294
  let stallNudged = false;
295
+ let callsAtStallNudge = 0;
296
+ let wrapUpNudged = false;
283
297
 
284
298
  for (let turn = 0; turn < maxTurns; turn++) {
285
299
  if (options.signal?.aborted) return { stopReason: 'cancelled', messages };
@@ -333,7 +347,7 @@ export async function runAgentLoop(
333
347
  input,
334
348
  });
335
349
 
336
- let result: { ok: boolean; output: string; diff?: string };
350
+ let result: { ok: boolean; output: string; diff?: string; images?: Array<{ data: string; mediaType: string }> };
337
351
  let skippedPermission = false;
338
352
 
339
353
  // Circuit breaker (windowed): see recentKeys declaration.
@@ -366,14 +380,22 @@ export async function runAgentLoop(
366
380
  cwd: toolSession.cwd,
367
381
  signal: options.signal,
368
382
  session: toolSession,
383
+ requestPermission: options.requestPermission,
369
384
  })
370
385
  : { ok: false, output: 'Permission denied by the client.' };
371
386
 
372
387
  if (allowed && tool.isMutating && tool.isReadOnly?.(input) !== true) {
373
388
  hasActed = true;
389
+ callsSinceAction = 0;
390
+ // "Delivered" means a file write; mutating bash is not a deliverable
391
+ // and must not trigger the wrap-up message.
392
+ if (tool.name === 'write_file' || tool.name === 'edit_file') {
393
+ hasDelivered = true;
394
+ }
374
395
  }
375
396
  }
376
397
  totalToolCalls++;
398
+ callsSinceAction++;
377
399
 
378
400
  await options.onEvent({
379
401
  type: 'tool_result',
@@ -385,9 +407,50 @@ export async function runAgentLoop(
385
407
  skippedPermission,
386
408
  });
387
409
 
410
+ // Image auto-proxy: when a vision role is routed (or a test describer
411
+ // is injected), images are converted to a text description so the
412
+ // primary model does not need multimodal support.
413
+ let toolContent:
414
+ | string
415
+ | Array<{ type: string; text?: string; image_url?: { url: string } }> = result.output;
416
+ if (result.images?.length) {
417
+ const describer =
418
+ options.describeImages ??
419
+ (getRouting().vision
420
+ ? (images: Array<{ data: string; mediaType: string }>) =>
421
+ askRole(
422
+ 'vision',
423
+ '简要描述图片的关键信息;如果是报错/截图,逐字给出其中文本。',
424
+ images,
425
+ )
426
+ : undefined);
427
+ if (describer) {
428
+ try {
429
+ const description = await describer(result.images);
430
+ toolContent = `${result.output}\n\n[vision] ${description}`;
431
+ } catch {
432
+ toolContent = [
433
+ { type: 'text', text: `${result.output}\n[vision 转述失败,原图已直接传入]` },
434
+ ...result.images.map((image) => ({
435
+ type: 'image_url',
436
+ image_url: { url: `data:${image.mediaType};base64,${image.data}` },
437
+ })),
438
+ ];
439
+ }
440
+ } else {
441
+ toolContent = [
442
+ { type: 'text', text: result.output },
443
+ ...result.images.map((image) => ({
444
+ type: 'image_url',
445
+ image_url: { url: `data:${image.mediaType};base64,${image.data}` },
446
+ })),
447
+ ];
448
+ }
449
+ }
450
+
388
451
  messages.push(
389
452
  new ToolMessage({
390
- content: result.output,
453
+ content: toolContent,
391
454
  tool_call_id: toolCallId,
392
455
  name: call.name,
393
456
  }),
@@ -396,6 +459,7 @@ export async function runAgentLoop(
396
459
 
397
460
  if (!hasActed && !stallNudged && totalToolCalls >= EXPLORE_STALL_THRESHOLD) {
398
461
  stallNudged = true;
462
+ callsAtStallNudge = totalToolCalls;
399
463
  const nudge =
400
464
  `You have made ${totalToolCalls} tool calls without producing any edits or output. ` +
401
465
  'Stop exploring: synthesize what you already have and complete the task now ' +
@@ -403,6 +467,32 @@ export async function runAgentLoop(
403
467
  'read_file returns up to 2000 lines in one call — do not paginate with grep/sed windows.';
404
468
  messages.push(new AIMessage({ content: nudge }));
405
469
  await options.onEvent({ type: 'text', text: `\n⚠ ${nudge}\n` });
470
+ } else if (
471
+ !hasActed &&
472
+ stallNudged &&
473
+ totalToolCalls - callsAtStallNudge >= STALL_GRACE_CALLS
474
+ ) {
475
+ // Hard rail: the nudge was ignored. Fail fast and loudly instead of
476
+ // burning the remaining turns.
477
+ const notice =
478
+ `The agent made ${totalToolCalls} tool calls without starting the deliverable and ` +
479
+ 'ignored the earlier reminder. Stopping to avoid wasting turns. Re-prompt with a more ' +
480
+ 'specific instruction (name the exact file and what to change) or switch to a stronger model.';
481
+ messages.push(new AIMessage({ content: notice }));
482
+ await options.onEvent({ type: 'text', text: `\n⚠ ${notice}\n` });
483
+ return { stopReason: 'stalled', messages };
484
+ } else if (
485
+ hasDelivered &&
486
+ !wrapUpNudged &&
487
+ callsSinceAction >= WRAP_UP_GAP
488
+ ) {
489
+ wrapUpNudged = true;
490
+ const nudge =
491
+ `The deliverable has already been written, but you have made ${callsSinceAction} ` +
492
+ 'more tool calls since. Run any final verification now if truly needed, then ' +
493
+ 'reply with a summary of what changed and stop — further exploration is not needed.';
494
+ messages.push(new AIMessage({ content: nudge }));
495
+ await options.onEvent({ type: 'text', text: `\n⚠ ${nudge}\n` });
406
496
  }
407
497
  }
408
498
 
@@ -1,8 +1,9 @@
1
1
  import { afterEach, describe, expect, test } from 'bun:test';
2
- import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
2
+ import { mkdtempSync, promises as fs, rmSync, writeFileSync } from 'node:fs';
3
3
  import { tmpdir } from 'node:os';
4
4
  import path from 'node:path';
5
5
  import { INIT_PROMPT, buildSystemPrompt, loadProjectContext } from './system-prompt.js';
6
+ import { setRouting } from '../provider/provider.js';
6
7
 
7
8
  describe('buildSystemPrompt', () => {
8
9
  test('steers file inspection away from whole-file cat/sed dumps', () => {
@@ -14,6 +15,28 @@ describe('buildSystemPrompt', () => {
14
15
  expect(prompt).toContain('offset');
15
16
  expect(prompt.toLowerCase()).toContain('do not cat');
16
17
  });
18
+
19
+ test('warns that grep -c counts definition lines too', () => {
20
+ const prompt = buildSystemPrompt({ cwd: '/tmp', projectFiles: [] });
21
+ expect(prompt).toContain('grep -c');
22
+ });
23
+
24
+ test('advertises configured role routing for ask_model delegation', async () => {
25
+ const configDir = await fs.mkdtemp(path.join(tmpdir(), 'transcode-prompt-route-'));
26
+ process.env.TRANSCODE_CONFIG_PATH = path.join(configDir, 'config.json');
27
+ try {
28
+ setRouting('analysis', 'glmc');
29
+ setRouting('design', 'opus');
30
+ const prompt = buildSystemPrompt({ cwd: '/tmp', projectFiles: [] });
31
+ expect(prompt).toContain('ask_model');
32
+ expect(prompt).toContain('dispatch_agent');
33
+ expect(prompt).toContain('analysis→glmc');
34
+ expect(prompt).toContain('design→opus');
35
+ } finally {
36
+ delete process.env.TRANSCODE_CONFIG_PATH;
37
+ await fs.rm(configDir, { recursive: true, force: true });
38
+ }
39
+ });
17
40
  });
18
41
 
19
42
  const cleanups: Array<() => void> = [];
@@ -1,5 +1,6 @@
1
1
  import { promises as fs } from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { getRouting } from '../provider/provider.js';
3
4
 
4
5
  const CONTEXT_FILES = ['TRANS.md', 'AGENTS.md', 'CLAUDE.md', 'TRANSCODE.md', '.transcode/AGENTS.md'];
5
6
  const MAX_CONTEXT_CHARS = 40_000;
@@ -32,6 +33,21 @@ async function readOptional(file: string): Promise<string | null> {
32
33
  }
33
34
  }
34
35
 
36
+ /** Advertises configured role routing so the model knows it can delegate. */
37
+ function roleRoutingLines(): string[] {
38
+ const entries = Object.entries(getRouting()).filter(([role]) => role !== 'default');
39
+ if (entries.length === 0) return [];
40
+ const roles = entries.map(([role, profile]) => `${role}→${profile}`).join(', ');
41
+ return [
42
+ `- Sub-task delegation. Configured roles: ${roles}. Three tiers — ` +
43
+ 'do it yourself for simple lookups; ask_model({role, prompt}) for one-shot expert ' +
44
+ 'questions (analysis, design trade-offs, reviews, image description); ' +
45
+ 'dispatch_agent({role, task, tools}) for multi-step research that needs file access — ' +
46
+ 'the sub-agent runs its own tool loop and returns a final report (it cannot see this ' +
47
+ 'conversation, so the task must be fully self-contained; dispatch asks the user first).',
48
+ ];
49
+ }
50
+
35
51
  async function gitBranch(cwd: string): Promise<string | undefined> {
36
52
  try {
37
53
  const { execFile } = await import('node:child_process');
@@ -95,6 +111,11 @@ export function buildSystemPrompt(
95
111
  'grep/sed window commands — that wastes dozens of turns; read the file once instead.',
96
112
  '- For synthesis tasks (update docs/README): explore briefly (aim for ~15 tool calls), ' +
97
113
  'then state a short plan and write the result. Exploration is not the deliverable.',
114
+ '- Multi-step tasks (3+ steps): create the list with todo_write first, keep exactly one ' +
115
+ 'step in_progress, and mark steps completed as you finish them.',
116
+ ...roleRoutingLines(),
117
+ '- Reporting counts (tests, checks, matches): grep -c counts matching LINES, including ' +
118
+ 'definitions like `def check(` — read the actual item list instead of trusting a raw count.',
98
119
  '- The bash working directory persists across calls; you do not need to cd again each time.',
99
120
  '- Never repeat an identical tool call; refine it or switch tools.',
100
121
  '- Use edit_file for targeted changes and write_file for new files.',