@trans-ai/trans-code 0.8.2 → 0.10.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 (38) hide show
  1. package/README.md +20 -2
  2. package/docs/superpowers/plans/2026-11-21-auto-compact.md +84 -0
  3. package/docs/superpowers/plans/2026-11-21-compact-speed.md +85 -0
  4. package/docs/superpowers/plans/2026-11-22-user-memory.md +243 -0
  5. package/docs/superpowers/plans/2026-11-22-web-tools.md +192 -0
  6. package/docs/superpowers/specs/2026-11-21-auto-compact-design.md +25 -0
  7. package/docs/superpowers/specs/2026-11-21-compact-speed-design.md +21 -0
  8. package/docs/superpowers/specs/2026-11-22-user-memory-design.md +48 -0
  9. package/docs/superpowers/specs/2026-11-22-web-tools-design.md +48 -0
  10. package/package.json +1 -1
  11. package/src/acp/server.ts +6 -0
  12. package/src/agent/loop.ts +5 -1
  13. package/src/agent/memory.test.ts +169 -0
  14. package/src/agent/memory.ts +207 -0
  15. package/src/agent/system-prompt.test.ts +87 -1
  16. package/src/agent/system-prompt.ts +23 -1
  17. package/src/agent/tools/index.ts +7 -0
  18. package/src/agent/tools/memory.test.ts +88 -0
  19. package/src/agent/tools/memory.ts +61 -0
  20. package/src/agent/tools/types.ts +2 -0
  21. package/src/agent/tools/web-fetch.test.ts +186 -0
  22. package/src/agent/tools/web-fetch.ts +137 -0
  23. package/src/agent/tools/web-search.test.ts +100 -0
  24. package/src/agent/tools/web-search.ts +41 -0
  25. package/src/commands.test.ts +104 -1
  26. package/src/commands.ts +101 -0
  27. package/src/config.test.ts +25 -0
  28. package/src/config.ts +52 -0
  29. package/src/provider/web-search.test.ts +195 -0
  30. package/src/provider/web-search.ts +143 -0
  31. package/src/screens/REPL.tsx +222 -24
  32. package/src/screens/search-setup.test.ts +89 -0
  33. package/src/screens/search-setup.ts +57 -0
  34. package/src/screens/submit.test.ts +8 -0
  35. package/src/screens/submit.ts +1 -1
  36. package/src/sessions/compact.test.ts +90 -25
  37. package/src/sessions/compact.ts +41 -9
  38. package/src/version.ts +1 -1
@@ -1,6 +1,7 @@
1
1
  import { promises as fs } from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { getRouting } from '../provider/provider.js';
4
+ import { loadUserMemory, renderMemoryIndex, type UserMemory } from './memory.js';
4
5
 
5
6
  const CONTEXT_FILES = ['TRANS.md', 'AGENTS.md', 'CLAUDE.md', 'TRANSCODE.md', '.transcode/AGENTS.md'];
6
7
  const MAX_CONTEXT_CHARS = 40_000;
@@ -22,6 +23,8 @@ export interface ProjectContext {
22
23
  cwd: string;
23
24
  gitBranch?: string;
24
25
  projectFiles: { path: string; content: string }[];
26
+ /** User-level memory (global instructions + memories); loaded alongside project files. */
27
+ userMemory?: UserMemory;
25
28
  }
26
29
 
27
30
  async function readOptional(file: string): Promise<string | null> {
@@ -79,7 +82,7 @@ export async function loadProjectContext(cwd: string): Promise<ProjectContext> {
79
82
  budget -= clipped.length;
80
83
  }
81
84
 
82
- return { cwd, gitBranch: await gitBranch(cwd), projectFiles };
85
+ return { cwd, gitBranch: await gitBranch(cwd), projectFiles, userMemory: await loadUserMemory() };
83
86
  }
84
87
 
85
88
  export function buildSystemPrompt(
@@ -124,8 +127,27 @@ export function buildSystemPrompt(
124
127
  '- Never claim a command succeeded unless you actually ran it and saw the result.',
125
128
  '- When the task is complete, reply with a short summary of what changed and any verification performed.',
126
129
  '- If a tool fails, read the error and adapt instead of repeating the same call.',
130
+ '- When the user corrects your behavior or states a lasting preference, save it with ' +
131
+ 'memory_save; before relying on a possibly stale memory, verify it still holds.',
127
132
  ];
128
133
 
134
+ const memory = context.userMemory;
135
+ if (memory && (memory.globalInstructions || memory.entries.length > 0 || memory.omitted.length > 0)) {
136
+ sections.push('', '## User memory');
137
+ if (memory.globalInstructions) {
138
+ sections.push('', '### Global instructions', memory.globalInstructions);
139
+ }
140
+ if (memory.entries.length > 0) {
141
+ sections.push('', '### Memory', renderMemoryIndex(memory.entries).trim());
142
+ for (const entry of memory.entries) {
143
+ sections.push('', `#### ${entry.name}`, entry.content);
144
+ }
145
+ }
146
+ if (memory.omitted.length > 0) {
147
+ sections.push('', `(omitted: ${memory.omitted.join(', ')})`);
148
+ }
149
+ }
150
+
129
151
  if (context.projectFiles.length > 0) {
130
152
  sections.push('', '## Project instructions');
131
153
  for (const file of context.projectFiles) {
@@ -5,6 +5,9 @@ import { bashTool } from './bash.js';
5
5
  import { editFileTool, readFileTool, writeFileTool } from './files.js';
6
6
  import { globTool, grepTool } from './search.js';
7
7
  import { todoWriteTool } from './todo.js';
8
+ import { memoryDeleteTool, memorySaveTool } from './memory.js';
9
+ import { webFetchTool } from './web-fetch.js';
10
+ import { webSearchTool } from './web-search.js';
8
11
  import { createAskModelTool } from './ask-model.js';
9
12
  import { createDispatchAgentTool } from './dispatch.js';
10
13
  import { readImageBlocks } from './files.js';
@@ -27,6 +30,10 @@ const dispatchPool = [
27
30
  bashOutputTool,
28
31
  todoWriteTool,
29
32
  askModelTool,
33
+ memorySaveTool,
34
+ memoryDeleteTool,
35
+ webFetchTool,
36
+ webSearchTool,
30
37
  ];
31
38
  const dispatchAgentTool = createDispatchAgentTool({
32
39
  runLoop: (options) =>
@@ -0,0 +1,88 @@
1
+ import { describe, expect, test } from 'bun:test';
2
+ import { mkdtempSync, promises as fs, rmSync } from 'node:fs';
3
+ import { tmpdir } from 'node:os';
4
+ import path from 'node:path';
5
+ import { createToolSession, type ToolSession } from './session.js';
6
+ import type { ToolContext } from './types.js';
7
+ import { memoryDeleteTool, memorySaveTool } from './memory.js';
8
+ import { loadUserMemory } from '../memory.js';
9
+
10
+ let root: string;
11
+
12
+ async function withRoot(run: (session: ToolSession) => Promise<void>): Promise<void> {
13
+ root = mkdtempSync(path.join(tmpdir(), 'transcode-memory-tool-'));
14
+ process.env.TRANSCODE_USER_DIR = root;
15
+ const session = createToolSession(root);
16
+ try {
17
+ await run(session);
18
+ } finally {
19
+ delete process.env.TRANSCODE_USER_DIR;
20
+ rmSync(root, { recursive: true, force: true });
21
+ }
22
+ }
23
+
24
+ function ctx(session: ToolSession): ToolContext {
25
+ return { cwd: session.cwd, session };
26
+ }
27
+
28
+ describe('memory tools', () => {
29
+ test('memory_save 经 execute 落盘:文件 + 索引 + 返回含 name/type', async () => {
30
+ await withRoot(async (session) => {
31
+ const out = await memorySaveTool.execute(
32
+ {
33
+ name: 'commit-style-zh',
34
+ type: 'feedback',
35
+ content: 'Commit messages written in Chinese.',
36
+ description: '中文 commit 惯例',
37
+ },
38
+ ctx(session),
39
+ );
40
+
41
+ expect(out).toContain('commit-style-zh');
42
+ expect(out).toContain('feedback');
43
+
44
+ const loaded = await loadUserMemory();
45
+ expect(loaded.entries).toHaveLength(1);
46
+ expect(loaded.entries[0].name).toBe('commit-style-zh');
47
+ const index = await fs.readFile(
48
+ path.join(root, 'memory', 'MEMORY.md'),
49
+ 'utf8',
50
+ );
51
+ expect(index).toContain('- [commit-style-zh](commit-style-zh.md) — 中文 commit 惯例');
52
+ });
53
+ });
54
+
55
+ test('memory_delete 经 execute 删条目,未命中返回 "not found" 文案', async () => {
56
+ await withRoot(async (session) => {
57
+ await memorySaveTool.execute(
58
+ { name: 'temp-note', type: 'user', content: 'soon gone' },
59
+ ctx(session),
60
+ );
61
+
62
+ const out = await memoryDeleteTool.execute({ name: 'temp-note' }, ctx(session));
63
+ expect(out).not.toContain('not found');
64
+ expect((await loadUserMemory()).entries).toHaveLength(0);
65
+
66
+ const miss = await memoryDeleteTool.execute({ name: 'no-such' }, ctx(session));
67
+ expect(miss).toContain('not found');
68
+ });
69
+ });
70
+
71
+ test('两工具 isMutating === true(被 plan/readonly 门禁拒绝的根据)', () => {
72
+ expect(memorySaveTool.isMutating).toBe(true);
73
+ expect(memoryDeleteTool.isMutating).toBe(true);
74
+ });
75
+
76
+ test('危险 name 经工具返回 Error 文案而非抛异常', async () => {
77
+ await withRoot(async (session) => {
78
+ const out = await memorySaveTool.execute(
79
+ { name: 'a/b', type: 'user', content: 'x' },
80
+ ctx(session),
81
+ );
82
+ expect(out).toContain('Error');
83
+
84
+ const del = await memoryDeleteTool.execute({ name: '..' }, ctx(session));
85
+ expect(del).toContain('not found');
86
+ });
87
+ });
88
+ });
@@ -0,0 +1,61 @@
1
+ import { z } from 'zod';
2
+ import type { AgentTool } from './types.js';
3
+ import { deleteMemory, saveMemory, type MemoryType } from '../memory.js';
4
+
5
+ export const memorySaveTool: AgentTool = {
6
+ name: 'memory_save',
7
+ description:
8
+ 'Save or update a user memory — a durable fact that should outlive this conversation: ' +
9
+ 'who the user is and their preferences (user), a correction to your own behavior (feedback), ' +
10
+ 'a lasting project constraint (project), or a pointer to an external resource (reference). ' +
11
+ 'One fact per call. Do NOT save: code structure (read the code instead), git history ' +
12
+ '(git log answers it), temporary task state (use todo_write), or anything TRANS.md already covers.',
13
+ kind: 'edit',
14
+ isMutating: true,
15
+ schema: z.object({
16
+ name: z.string().min(1).describe('Short kebab-case slug identifying the memory'),
17
+ type: z
18
+ .enum(['user', 'feedback', 'project', 'reference'])
19
+ .describe(
20
+ 'user=who the user is/preferences; feedback=correction to agent behavior; ' +
21
+ 'project=lasting project constraint; reference=external resource pointer',
22
+ ),
23
+ content: z.string().min(1).describe('The fact itself'),
24
+ description: z
25
+ .string()
26
+ .optional()
27
+ .describe('One-line hook for the index; defaults to the first line of content'),
28
+ }),
29
+ title: (input) => `memory_save ${input.name}`,
30
+ async execute(input) {
31
+ try {
32
+ const entry = await saveMemory({
33
+ name: String(input.name),
34
+ type: input.type as MemoryType,
35
+ content: String(input.content),
36
+ description: input.description ? String(input.description) : undefined,
37
+ });
38
+ return `Saved memory ${entry.name} (type=${entry.type}).`;
39
+ } catch (error) {
40
+ return `Error: ${error instanceof Error ? error.message : String(error)}`;
41
+ }
42
+ },
43
+ };
44
+
45
+ export const memoryDeleteTool: AgentTool = {
46
+ name: 'memory_delete',
47
+ description:
48
+ 'Delete a saved user memory by name — use when the user asks to forget something ' +
49
+ 'or a memory turned out to be wrong.',
50
+ kind: 'delete',
51
+ isMutating: true,
52
+ schema: z.object({
53
+ name: z.string().min(1).describe('Name of the memory to delete'),
54
+ }),
55
+ title: (input) => `memory_delete ${input.name}`,
56
+ async execute(input) {
57
+ const name = String(input.name);
58
+ const removed = await deleteMemory(name);
59
+ return removed ? `Deleted memory ${name}.` : `not found: no memory named '${name}'`;
60
+ },
61
+ };
@@ -47,6 +47,8 @@ export interface AgentTool {
47
47
  isMutating: boolean;
48
48
  /** When true for a given input, a mutating tool may skip the permission prompt. */
49
49
  isReadOnly?(input: Record<string, unknown>): boolean;
50
+ /** When false, the tool is left out of the per-turn tool table (e.g. unconfigured). */
51
+ isEnabled?: () => boolean;
50
52
  title(input: Record<string, unknown>): string;
51
53
  execute(input: Record<string, unknown>, ctx: ToolContext): Promise<string | ToolOutput>;
52
54
  }
@@ -0,0 +1,186 @@
1
+ import { describe, expect, test } from 'bun:test';
2
+ import {
3
+ FETCH_MAX_CHARS,
4
+ decodeBody,
5
+ htmlToText,
6
+ sniffCharset,
7
+ webFetchTool,
8
+ } from './web-fetch.js';
9
+ import { createToolSession, type ToolSession } from './session.js';
10
+ import type { ToolContext } from './types.js';
11
+
12
+ const GBK = {
13
+ zhongwen: [0xd6, 0xd0, 0xce, 0xc4], // 中文
14
+ ceshi: [0xb2, 0xe2, 0xca, 0xd4], // 测试
15
+ neirong: [0xc4, 0xda, 0xc8, 0xdd], // 内容
16
+ };
17
+
18
+ function ctx(session: ToolSession): ToolContext {
19
+ return { cwd: session.cwd, session };
20
+ }
21
+
22
+ /** Swap globalThis.fetch for the test; restore in finally. Returns captured request inits. */
23
+ async function withFetch(
24
+ impl: typeof fetch,
25
+ run: (calls: RequestInit[]) => Promise<void>,
26
+ ): Promise<void> {
27
+ const original = globalThis.fetch;
28
+ const calls: RequestInit[] = [];
29
+ globalThis.fetch = (async (input: any, init?: any) => {
30
+ calls.push(init ?? {});
31
+ return impl(input, init);
32
+ }) as typeof fetch;
33
+ try {
34
+ await run(calls);
35
+ } finally {
36
+ globalThis.fetch = original;
37
+ }
38
+ }
39
+
40
+ function htmlResponse(body: string | Uint8Array, headers: Record<string, string> = {}) {
41
+ return new Response(body, {
42
+ status: 200,
43
+ headers: { 'content-type': 'text/html; charset=utf-8', ...headers },
44
+ });
45
+ }
46
+
47
+ describe('web_fetch pure helpers', () => {
48
+ test('htmlToText:剥 script/style、留正文、提取 <title>、折叠空行', () => {
49
+ const { title, text } = htmlToText(
50
+ '<html><head><title>Docs</title><style>body{}</style></head>' +
51
+ '<body><h1>Heading</h1><script>alert(1)</script><p>Para one</p>' +
52
+ '<noscript>nope</noscript><p>Para two</p></body></html>',
53
+ );
54
+ expect(title).toBe('Docs');
55
+ expect(text).not.toContain('alert');
56
+ expect(text).not.toContain('body{}');
57
+ expect(text).not.toContain('nope');
58
+ expect(text).toContain('Heading');
59
+ expect(text).toContain('Para one');
60
+ expect(text).toContain('Para two');
61
+ expect(text).not.toMatch(/\n{3,}/);
62
+ });
63
+
64
+ test('sniffCharset:Content-Type charset 优先;meta charset 兜底;默认 utf-8', () => {
65
+ const metaGbk = new TextEncoder().encode('<meta charset="gbk">');
66
+ const metaEquiv = new TextEncoder().encode(
67
+ '<meta http-equiv="Content-Type" content="text/html; charset=gb2312">',
68
+ );
69
+ expect(sniffCharset('text/html; charset=gbk', metaEquiv)).toBe('gbk');
70
+ expect(sniffCharset('text/html', metaGbk)).toBe('gbk');
71
+ expect(sniffCharset('text/html', metaEquiv)).toBe('gb2312');
72
+ expect(sniffCharset('text/html', new TextEncoder().encode('<p>x</p>'))).toBe('utf-8');
73
+ });
74
+
75
+ test('decodeBody:gbk 字节用 TextDecoder 正确解码中文', () => {
76
+ const decoded = decodeBody(new Uint8Array(GBK.zhongwen), 'gbk');
77
+ expect(decoded).toBe('中文');
78
+ // 非法 charset 回落 utf-8 不抛
79
+ expect(decodeBody(new Uint8Array([0x61, 0x62]), 'no-such-charset')).toBe('ab');
80
+ });
81
+ });
82
+
83
+ describe('web_fetch tool', () => {
84
+ test('HTML 响应 → 标题 + 文本 + prompt 原样前置', async () => {
85
+ await withFetch(async () => htmlResponse('<html><head><title>Page T</title></head><body><p>Body text</p></body></html>'), async () => {
86
+ const out = await webFetchTool.execute(
87
+ { url: 'https://example.com/a', prompt: 'find the release date' },
88
+ ctx(createToolSession('/tmp')),
89
+ );
90
+ expect(out).toContain('find the release date');
91
+ expect(out).toContain('Page T');
92
+ expect(out).toContain('Body text');
93
+ });
94
+ });
95
+
96
+ test('text/plain 与 application/json 原样返回(截断)', async () => {
97
+ await withFetch(
98
+ async () => new Response('plain bytes here', { headers: { 'content-type': 'text/plain' } }),
99
+ async () => {
100
+ const out = await webFetchTool.execute({ url: 'https://x/f.txt' }, ctx(createToolSession('/tmp')));
101
+ expect(out).toContain('plain bytes here');
102
+ },
103
+ );
104
+ await withFetch(
105
+ async () => new Response('{"ok":true}', { headers: { 'content-type': 'application/json' } }),
106
+ async () => {
107
+ const out = await webFetchTool.execute({ url: 'https://x/f.json' }, ctx(createToolSession('/tmp')));
108
+ expect(out).toContain('{"ok":true}');
109
+ },
110
+ );
111
+ });
112
+
113
+ test('超 20k 字符截断并注明 "... (truncated)"', async () => {
114
+ const long = 'x'.repeat(FETCH_MAX_CHARS + 5000);
115
+ await withFetch(async () => htmlResponse(`<body><p>${long}</p></body>`), async () => {
116
+ const out = (await webFetchTool.execute({ url: 'https://x/long' }, ctx(createToolSession('/tmp')))) as string;
117
+ expect(out).toContain('... (truncated)');
118
+ expect(out.length).toBeLessThan(FETCH_MAX_CHARS + 200);
119
+ });
120
+ });
121
+
122
+ test('403/404 → 返回含状态码的可读错误;fetch 抛超时 → 可读错误,不向上抛', async () => {
123
+ await withFetch(
124
+ async () => new Response('nope', { status: 403, statusText: 'Forbidden' }),
125
+ async () => {
126
+ const out = await webFetchTool.execute({ url: 'https://x/deny' }, ctx(createToolSession('/tmp')));
127
+ expect(out).toContain('403');
128
+ },
129
+ );
130
+ await withFetch(
131
+ async () => {
132
+ throw new Error('The operation was aborted due to timeout');
133
+ },
134
+ async () => {
135
+ const out = await webFetchTool.execute({ url: 'https://x/slow' }, ctx(createToolSession('/tmp')));
136
+ expect(out).toContain('Error');
137
+ expect(out).toContain('aborted');
138
+ },
139
+ );
140
+ });
141
+
142
+ test('非文本类型(pdf/图片)→ 返回内容类型与大小提示,不尝试解析', async () => {
143
+ await withFetch(
144
+ async () => new Response(new Uint8Array(1024).fill(1), { headers: { 'content-type': 'application/pdf' } }),
145
+ async () => {
146
+ const out = await webFetchTool.execute({ url: 'https://x/a.pdf' }, ctx(createToolSession('/tmp')));
147
+ expect(out).toContain('application/pdf');
148
+ expect(out).toContain('1024');
149
+ expect(out).not.toContain('Error');
150
+ },
151
+ );
152
+ });
153
+
154
+ test('请求头带 transcode UA;gbk 页面端到端解码不乱码', async () => {
155
+ const htmlBytes = new Uint8Array([
156
+ ...new TextEncoder().encode('<html><head><meta charset="gbk"><title>'),
157
+ ...GBK.ceshi,
158
+ ...new TextEncoder().encode('</title></head><body><p>'),
159
+ ...GBK.zhongwen,
160
+ ...GBK.neirong,
161
+ ...new TextEncoder().encode('</p></body></html>'),
162
+ ]);
163
+ await withFetch(
164
+ async () =>
165
+ new Response(htmlBytes, { headers: { 'content-type': 'text/html' } }),
166
+ async (calls) => {
167
+ const out = await webFetchTool.execute({ url: 'https://x/cn' }, ctx(createToolSession('/tmp')));
168
+ const ua = new Headers(calls[0]?.headers as HeadersInit | undefined).get('user-agent') ?? '';
169
+ expect(ua).toMatch(/^Mozilla\/5\.0 \(compatible; transcode\//);
170
+ expect(out).toContain('测试');
171
+ expect(out).toContain('中文内容');
172
+ },
173
+ );
174
+ });
175
+ });
176
+
177
+ describe('htmlToText pathological input', () => {
178
+ test('孤立 < 无 > 的病态输入线性完成(标签剥离不允许二次方冻结)', () => {
179
+ const n = 400_000;
180
+ const start = Date.now();
181
+ const { text } = htmlToText('<'.repeat(n));
182
+ expect(Date.now() - start).toBeLessThan(2_000);
183
+ // 无 > 不构成标签,字符原样保留
184
+ expect(text).toBe('<'.repeat(n));
185
+ });
186
+ });
@@ -0,0 +1,137 @@
1
+ import { z } from 'zod';
2
+ import type { AgentTool } from './types.js';
3
+ import { VERSION } from '../../version.js';
4
+
5
+ /**
6
+ * Zero-dependency web fetch: native fetch + charset sniffing + tag-stripping
7
+ * HTML extraction. Content-type dispatch decides between extraction, raw
8
+ * text, and a binary hint.
9
+ */
10
+
11
+ export const FETCH_MAX_BYTES = 512 * 1024;
12
+ export const FETCH_MAX_CHARS = 20_000;
13
+ const FETCH_TIMEOUT_MS = 15_000;
14
+ const USER_AGENT = `Mozilla/5.0 (compatible; transcode/${VERSION})`;
15
+ const TRUNCATED_NOTE = '... (truncated)';
16
+
17
+ /** Content-Type header charset first, then <meta charset> in the first 2KB, else utf-8. */
18
+ export function sniffCharset(contentType: string, body: Uint8Array): string {
19
+ const header = /charset\s*=\s*["']?([\w-]+)/i.exec(contentType);
20
+ if (header) return header[1].toLowerCase();
21
+ const head = new TextDecoder('latin1').decode(body.slice(0, 2048));
22
+ const meta = /<meta[^>]+charset\s*=\s*["']?\s*([\w-]+)/i.exec(head);
23
+ if (meta) return meta[1].toLowerCase();
24
+ return 'utf-8';
25
+ }
26
+
27
+ /** Decode with the sniffed charset; an unsupported charset falls back to utf-8. */
28
+ export function decodeBody(body: Uint8Array, charset: string): string {
29
+ try {
30
+ return new TextDecoder(charset).decode(body);
31
+ } catch {
32
+ return new TextDecoder('utf-8').decode(body);
33
+ }
34
+ }
35
+
36
+ /**
37
+ * Linear tag stripping: regex `/<[^>]+>/g` is quadratic on pathological
38
+ * input (hundreds of thousands of lone '<'), freezing the process for tens
39
+ * of seconds; this single-pass scan stays O(n).
40
+ */
41
+ function stripTags(html: string): string {
42
+ let out = '';
43
+ let cursor = 0;
44
+ for (;;) {
45
+ const open = html.indexOf('<', cursor);
46
+ if (open === -1) {
47
+ out += html.slice(cursor);
48
+ return out;
49
+ }
50
+ out += html.slice(cursor, open);
51
+ const close = html.indexOf('>', open + 1);
52
+ if (close === -1) {
53
+ // No closing '>': the rest is literal text, not a tag.
54
+ out += html.slice(open);
55
+ return out;
56
+ }
57
+ out += ' ';
58
+ cursor = close + 1;
59
+ }
60
+ }
61
+
62
+ /** Strip head/script/style/noscript noise, tags to whitespace, collapse blank lines. */
63
+ export function htmlToText(html: string): { title: string | null; text: string } {
64
+ const titleMatch = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
65
+ const title = titleMatch ? titleMatch[1].trim().replace(/\s+/g, ' ') || null : null;
66
+ const text = stripTags(
67
+ html
68
+ .replace(/<head[\s\S]*?<\/head>/gi, ' ')
69
+ .replace(/<(script|style|noscript)\b[\s\S]*?<\/\1>/gi, ' '),
70
+ )
71
+ .replace(/&nbsp;/gi, ' ')
72
+ .replace(/&amp;/gi, '&')
73
+ .replace(/&lt;/gi, '<')
74
+ .replace(/&gt;/gi, '>')
75
+ .replace(/&quot;/gi, '"')
76
+ .replace(/[ \t]+/g, ' ')
77
+ .replace(/ *\n */g, '\n')
78
+ .replace(/\n{2,}/g, '\n')
79
+ .trim();
80
+ return { title, text };
81
+ }
82
+
83
+ function isHtmlType(contentType: string): boolean {
84
+ return /html/i.test(contentType);
85
+ }
86
+
87
+ function isTextualType(contentType: string): boolean {
88
+ return contentType === '' || /^text\//i.test(contentType) || /(json|xml|javascript|html)/i.test(contentType);
89
+ }
90
+
91
+ export const webFetchTool: AgentTool = {
92
+ name: 'web_fetch',
93
+ description:
94
+ 'Fetch a URL and return readable text: HTML pages are stripped to text with their ' +
95
+ 'title, text/plain and JSON pass through, binary types return a type/size hint. ' +
96
+ 'Use it to read docs, API responses and raw files. Handles gbk/gb2312 pages.',
97
+ kind: 'fetch',
98
+ isMutating: false,
99
+ schema: z.object({
100
+ url: z.string().url().describe('Absolute URL to fetch'),
101
+ prompt: z.string().optional().describe('What to look for on the page (guidance only)'),
102
+ }),
103
+ title: (input) => `web_fetch ${input.url}`,
104
+ async execute(input) {
105
+ const url = String(input.url);
106
+ const prompt = input.prompt ? String(input.prompt) : '';
107
+ try {
108
+ const res = await fetch(url, {
109
+ headers: { 'user-agent': USER_AGENT },
110
+ redirect: 'follow',
111
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
112
+ });
113
+ if (!res.ok) {
114
+ return `Error: HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''} fetching ${url}`;
115
+ }
116
+ const contentType = res.headers.get('content-type') ?? '';
117
+ let bytes = new Uint8Array(await res.arrayBuffer());
118
+ if (bytes.length > FETCH_MAX_BYTES) bytes = bytes.slice(0, FETCH_MAX_BYTES);
119
+ if (!isTextualType(contentType)) {
120
+ return `Fetched ${url}: ${contentType || 'unknown content type'}, ${bytes.length} bytes (binary; not extracted).`;
121
+ }
122
+ let text = decodeBody(bytes, sniffCharset(contentType, bytes));
123
+ let title: string | null = null;
124
+ if (isHtmlType(contentType) || /^\s*<(?:!doctype|html)/i.test(text)) {
125
+ const parsed = htmlToText(text);
126
+ title = parsed.title;
127
+ text = parsed.text;
128
+ }
129
+ if (text.length > FETCH_MAX_CHARS) {
130
+ text = `${text.slice(0, FETCH_MAX_CHARS)}\n${TRUNCATED_NOTE}`;
131
+ }
132
+ return `${prompt ? `Reading guide: ${prompt}\n\n` : ''}${title ? `# ${title}\n` : ''}${text}`;
133
+ } catch (error) {
134
+ return `Error: web_fetch failed for ${url}: ${error instanceof Error ? error.message : String(error)}`;
135
+ }
136
+ },
137
+ };
@@ -0,0 +1,100 @@
1
+ import { describe, expect, test } from 'bun:test';
2
+ import { mkdtempSync, promises as fs, rmSync, writeFileSync } from 'node:fs';
3
+ import { tmpdir } from 'node:os';
4
+ import path from 'node:path';
5
+ import { createToolSession, type ToolSession } from './session.js';
6
+ import type { ToolContext } from './types.js';
7
+ import { webSearchTool } from './web-search.js';
8
+
9
+ function ctx(session: ToolSession): ToolContext {
10
+ return { cwd: session.cwd, session };
11
+ }
12
+
13
+ /** Point TRANSCODE_USER-style config at a temp file with optional webSearch section. */
14
+ async function withConfig(webSearch: unknown, run: () => Promise<void>): Promise<void> {
15
+ const root = mkdtempSync(path.join(tmpdir(), 'transcode-ws-config-'));
16
+ const configPath = path.join(root, 'config.json');
17
+ const raw: Record<string, unknown> = { apiKeys: { glm: 'keep-me' } };
18
+ if (webSearch !== undefined) raw.webSearch = webSearch;
19
+ writeFileSync(configPath, JSON.stringify(raw));
20
+ process.env.TRANSCODE_CONFIG_PATH = configPath;
21
+ try {
22
+ await run();
23
+ } finally {
24
+ delete process.env.TRANSCODE_CONFIG_PATH;
25
+ rmSync(root, { recursive: true, force: true });
26
+ }
27
+ }
28
+
29
+ describe('web_search tool', () => {
30
+ test('isEnabled 按当前 loadConfig 返回;execute 输出 "title — url\\nsnippet" 列表', async () => {
31
+ await withConfig({ provider: 'tavily', apiKey: 'tvly-5' }, async () => {
32
+ expect(webSearchTool.isEnabled?.()).toBe(true);
33
+
34
+ const original = globalThis.fetch;
35
+ globalThis.fetch = (async () =>
36
+ new Response(
37
+ JSON.stringify({
38
+ results: [
39
+ { title: 'Hit A', url: 'https://a.dev/x', content: 'snippet A' },
40
+ { title: 'Hit B', url: 'https://b.dev/y', content: 'snippet B' },
41
+ ],
42
+ }),
43
+ { status: 200, headers: { 'content-type': 'application/json' } },
44
+ )) as typeof fetch;
45
+ try {
46
+ const out = await webSearchTool.execute({ query: 'test q' }, ctx(createToolSession('/tmp')));
47
+ expect(out).toContain('Hit A — https://a.dev/x');
48
+ expect(out).toContain('snippet A');
49
+ expect(out).toContain('Hit B — https://b.dev/y');
50
+ void original;
51
+ } finally {
52
+ globalThis.fetch = original;
53
+ }
54
+ });
55
+
56
+ await withConfig(undefined, async () => {
57
+ expect(webSearchTool.isEnabled?.()).toBe(false);
58
+ });
59
+ });
60
+
61
+ test('未配置时 execute 返回 not configured 可读错误(兜底路径);坏配置也如此', async () => {
62
+ await withConfig(undefined, async () => {
63
+ const out = await webSearchTool.execute({ query: 'x' }, ctx(createToolSession('/tmp')));
64
+ expect(out).toContain('not configured');
65
+ expect(out).toContain('/search');
66
+ });
67
+ await withConfig({ provider: 'googl', apiKey: '' }, async () => {
68
+ const out = await webSearchTool.execute({ query: 'x' }, ctx(createToolSession('/tmp')));
69
+ expect(out).toContain('not configured');
70
+ });
71
+ });
72
+ });
73
+
74
+ void fs;
75
+
76
+ describe('web_search cancellation wiring', () => {
77
+ test('execute 把 ctx.signal 接进搜索请求(Esc 打断子代理/主回合)', async () => {
78
+ await withConfig({ provider: 'tavily', apiKey: 'tvly-5' }, async () => {
79
+ let captured: AbortSignal | undefined;
80
+ const original = globalThis.fetch;
81
+ globalThis.fetch = (async (_i: any, init?: any) => {
82
+ captured = init?.signal;
83
+ return new Response(
84
+ JSON.stringify({ results: [{ title: 'T', url: 'u', content: 'c' }] }),
85
+ { status: 200, headers: { 'content-type': 'application/json' } },
86
+ );
87
+ }) as typeof fetch;
88
+ try {
89
+ const controller = new AbortController();
90
+ const session = createToolSession('/tmp');
91
+ await webSearchTool.execute({ query: 'q' }, { cwd: session.cwd, session, signal: controller.signal });
92
+ expect(captured).toBeInstanceOf(AbortSignal);
93
+ controller.abort();
94
+ expect(captured!.aborted).toBe(true);
95
+ } finally {
96
+ globalThis.fetch = original;
97
+ }
98
+ });
99
+ });
100
+ });