@echo-agent/coding 0.1.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.
@@ -0,0 +1,194 @@
1
+ // 搜索两件套:glob(找文件)/ grep(找内容)。用 Bun.Glob,零依赖。
2
+ // node_modules / .git 恒排除——那里面的匹配对写代码没用,还会把结果挤爆。
3
+ //
4
+ // **`path` 指到文件就只搜这一个文件**(2026-09-01,实测 bug):模型把 grep 当 `grep <pattern> <file>` 用是常态,
5
+ // 此前把文件当 cwd 交给 Bun.Glob,甩给模型一句 `ENOTDIR: not a directory`,相对、绝对路径都炸。
6
+ // glob 拿到文件则明说「要目录」并指回 grep——静默返回 0 个匹配是「写了没生效」。
7
+ //
8
+ // **结果路径一律相对工作区**:read_file / edit_file 收的是工作区相对路径,搜索若按 `path` 相对报
9
+ // (在 `packages/core/src` 里搜到 `agent.ts:260`),模型拿着 `agent.ts` 去读就找不到。
10
+ //
11
+ // **边界与文件三件套同一条**(review 2026-09-07):`path` 经 fs.ts 的 `resolveSafe` 解析,越界(含经软链)一律拒。
12
+ // 此前这三件没有任何边界,而 system 段对模型说的是「工作区之外的路径会被拒」——契约与实现两张皮,
13
+ // 且凡是把 bash 设成 ask 的策略,grep 都是绕开那道门读整块盘的路。
14
+
15
+ import { readdir, readFile, stat } from "node:fs/promises";
16
+ import { relative, resolve } from "node:path";
17
+ import { toolError, toolOk, type ModelTool, type ToolExecutionContext } from "@echo-agent/core";
18
+ import { resolveSafe } from "./fs.ts";
19
+
20
+ const GLOB_CAP = 500;
21
+ const GREP_CAP = 200;
22
+ const GREP_FILE_MAX = 1_000_000; // >1MB 的文件跳过(多半是产物/数据,不是代码)
23
+ const LINE_CAP = 250;
24
+ const LIST_CAP = 500;
25
+
26
+ const EXCLUDED = /(^|\/)(node_modules|\.git)(\/|$)/;
27
+
28
+ /** 搜索三件:glob / grep / list_dir。`list_dir` 是 2026-09-02 补的——glob 只出文件,模型看不到目录结构,只能 `bash ls`。 */
29
+ export function makeSearchTools(): ModelTool[] {
30
+ return [globTool(), grepTool(), listDirTool()] as ModelTool[];
31
+ }
32
+
33
+ /** 结果里怎么报这个文件:相对工作区——起点已经过了越界守卫,结果只可能在工作区内。 */
34
+ function display(ctx: ToolExecutionContext, abs: string): string {
35
+ return relative(ctx.workspace, abs);
36
+ }
37
+
38
+ type Target = { ok: true; kind: "file" | "dir"; abs: string } | { ok: false; error: string };
39
+
40
+ /** `path` → 搜索起点。越界、不存在、是文件、是目录分开说,错误文案要让模型知道下一步怎么办。 */
41
+ async function resolveTarget(ctx: ToolExecutionContext, path?: string): Promise<Target> {
42
+ const abs = path === undefined || path === "" ? resolve(ctx.workspace) : await resolveSafe(ctx, path);
43
+ if (abs === null) return { ok: false, error: `Path outside the workspace: '${path}'` };
44
+ const st = await stat(abs).catch(() => null);
45
+ if (st === null) return { ok: false, error: `path not found: ${path ?? abs}` };
46
+ return { ok: true, kind: st.isFile() ? "file" : "dir", abs };
47
+ }
48
+
49
+ /** 目录里按 glob 扫,产出绝对路径;node_modules / .git 恒排除。 */
50
+ async function* scanDir(dir: string, pattern: string): AsyncGenerator<string> {
51
+ for await (const p of new Bun.Glob(pattern).scan({ cwd: dir, onlyFiles: true, dot: false })) {
52
+ if (EXCLUDED.test(p)) continue;
53
+ yield resolve(dir, p);
54
+ }
55
+ }
56
+
57
+ function globTool(): ModelTool<{ pattern: string; path?: string }> {
58
+ return {
59
+ kind: "model",
60
+ name: "glob",
61
+ label: "找文件",
62
+ concurrent: true, // 只读
63
+ description:
64
+ 'Find files by glob pattern, e.g. "**/*.ts" or "src/**/*.test.ts". Returns paths relative to the workspace.',
65
+ parameters: {
66
+ type: "object",
67
+ properties: {
68
+ pattern: { type: "string" },
69
+ path: { type: "string", description: "Directory to start from, default the workspace" },
70
+ },
71
+ required: ["pattern"],
72
+ },
73
+ async execute({ pattern, path }, ctx) {
74
+ const target = await resolveTarget(ctx, path);
75
+ if (!target.ok) return toolError(target.error);
76
+ if (target.kind === "file") {
77
+ return toolError(`path is a file, glob needs a directory: ${path}. To search inside one file, use grep with path=${path}.`);
78
+ }
79
+ const out: string[] = [];
80
+ try {
81
+ for await (const abs of scanDir(target.abs, pattern)) {
82
+ out.push(display(ctx, abs));
83
+ if (out.length >= GLOB_CAP) break;
84
+ }
85
+ } catch (e) {
86
+ return toolError(`glob failed: ${String(e)}`);
87
+ }
88
+ out.sort();
89
+ const cap = out.length >= GLOB_CAP ? `\n…[hit the ${GLOB_CAP}-result limit; narrow the pattern]` : "";
90
+ return toolOk(out.length === 0 ? "(no matches)" : out.join("\n") + cap, { count: out.length });
91
+ },
92
+ };
93
+ }
94
+
95
+ function listDirTool(): ModelTool<{ path?: string }> {
96
+ return {
97
+ kind: "model",
98
+ name: "list_dir",
99
+ label: "列目录",
100
+ concurrent: true, // 只读
101
+ description:
102
+ "List the entries of one directory, not recursive: subdirectories first and marked with a trailing '/'. Default the workspace root. To find files by pattern use glob.",
103
+ parameters: {
104
+ type: "object",
105
+ properties: {
106
+ path: { type: "string", description: "Directory to list, default the workspace" },
107
+ },
108
+ },
109
+ async execute({ path }, ctx) {
110
+ const target = await resolveTarget(ctx, path);
111
+ if (!target.ok) return toolError(target.error);
112
+ if (target.kind === "file") return toolError(`path is a file, list_dir needs a directory: ${path}. Use read_file to read it.`);
113
+ let entries: { name: string; isDirectory(): boolean }[];
114
+ try {
115
+ entries = await readdir(target.abs, { withFileTypes: true });
116
+ } catch (e) {
117
+ return toolError(`list_dir failed: ${String(e)}`);
118
+ }
119
+ // 目录在前、各自按名排:一眼分得出结构。node_modules / .git 照列——这是目录的真相,不是搜索结果
120
+ const dirs = entries.filter((e) => e.isDirectory()).map((e) => `${e.name}/`).sort();
121
+ const files = entries.filter((e) => !e.isDirectory()).map((e) => e.name).sort();
122
+ const all = [...dirs, ...files];
123
+ const shown = all.slice(0, LIST_CAP);
124
+ const cap = all.length > LIST_CAP ? `\n…[${all.length - LIST_CAP} more entries not shown]` : "";
125
+ return toolOk(shown.length === 0 ? "(empty directory)" : shown.join("\n") + cap, { count: all.length });
126
+ },
127
+ };
128
+ }
129
+
130
+ function grepTool(): ModelTool<{ pattern: string; path?: string; glob?: string }> {
131
+ return {
132
+ kind: "model",
133
+ name: "grep",
134
+ label: "找内容",
135
+ concurrent: true, // 只读
136
+ description:
137
+ "Search file contents with a regular expression; returns file:line:text with paths relative to the workspace. " +
138
+ "path may be a directory (searched recursively, narrowed by glob) or a single file (searched alone).",
139
+ parameters: {
140
+ type: "object",
141
+ properties: {
142
+ pattern: { type: "string", description: "JavaScript regular expression (without slashes)" },
143
+ path: { type: "string", description: "Directory or file to search, default the workspace" },
144
+ glob: { type: "string", description: 'Limit to these files when path is a directory, default "**/*"' },
145
+ },
146
+ required: ["pattern"],
147
+ },
148
+ async execute({ pattern, path, glob }, ctx) {
149
+ let re: RegExp;
150
+ try {
151
+ re = new RegExp(pattern);
152
+ } catch (e) {
153
+ return toolError(`Invalid regular expression: ${String(e)}`);
154
+ }
155
+ const target = await resolveTarget(ctx, path);
156
+ if (!target.ok) return toolError(target.error);
157
+ // 单文件:用户点名的那一个,不过 glob 也不过排除表——点名了就是要搜它
158
+ const files: Iterable<string> | AsyncIterable<string> =
159
+ target.kind === "file" ? [target.abs] : scanDir(target.abs, glob ?? "**/*");
160
+ const lines: string[] = [];
161
+ let scanned = 0;
162
+ try {
163
+ for await (const abs of files) {
164
+ const st = await stat(abs).catch(() => null);
165
+ if (st === null || st.size > GREP_FILE_MAX) continue;
166
+ scanned += 1;
167
+ let raw: string;
168
+ try {
169
+ raw = await readFile(abs, "utf8");
170
+ } catch {
171
+ continue; // 读不动的(二进制、权限)跳过
172
+ }
173
+ if (raw.includes("\u0000")) continue; // 二进制
174
+ const shown = display(ctx, abs);
175
+ const fileLines = raw.split("\n");
176
+ for (let i = 0; i < fileLines.length; i++) {
177
+ const line = fileLines[i]!;
178
+ if (!re.test(line)) continue;
179
+ lines.push(`${shown}:${i + 1}:${line.length > LINE_CAP ? line.slice(0, LINE_CAP) + "…" : line}`);
180
+ if (lines.length >= GREP_CAP) break;
181
+ }
182
+ if (lines.length >= GREP_CAP) break;
183
+ }
184
+ } catch (e) {
185
+ return toolError(`grep failed: ${String(e)}`);
186
+ }
187
+ const cap = lines.length >= GREP_CAP ? `\n…[hit the ${GREP_CAP}-match limit; narrow the pattern or glob]` : "";
188
+ return toolOk(lines.length === 0 ? `(no matches in ${scanned} files)` : lines.join("\n") + cap, {
189
+ matches: lines.length,
190
+ scanned,
191
+ });
192
+ },
193
+ };
194
+ }
@@ -0,0 +1,267 @@
1
+ // web 一组(2026-09-03/04):`web_fetch` 取一个 URL 的正文;`web_search` 走 Brave Search API 拿结果列表。
2
+ // 不做出网确认(用户拍板:缺省全放行)。HTML 在这层剥成可读文本,不加依赖。
3
+ // 两件都是延迟工具(`deferred`):多数编码任务用不上,经 tool_search 取过才上菜单。
4
+ //
5
+ // 搜索源选 Brave(2026-09-04 用户拍板):与模型无关,一把 key 五家 provider 通用;厂商自带搜索要改 core 的
6
+ // dialect 且 deepseek 没有,另议。key 的解析顺序与模型 key 一样:环境变量 `BRAVE_API_KEY` → 凭据 store 的
7
+ // `brave` 条目 → 没有(工具如实报「没配」,不猜)。key 的值不进任何错误信息。
8
+
9
+ import { toolError, toolOk, type CredentialStore, type ModelTool } from "@echo-agent/core";
10
+
11
+ const TIMEOUT_MS = 30_000;
12
+ /** 响应体最多读这么多字节:超过就截,避免一个大文件把内存与上下文一起吃掉。 */
13
+ const MAX_BYTES = 4_000_000;
14
+ const DEFAULT_MAX_CHARS = 20_000;
15
+
16
+ const BRAVE_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
17
+ const BRAVE_ENV = "BRAVE_API_KEY";
18
+ /** 凭据 store 里的条目名:`{ "brave": { "apiKey": "…" } }`。 */
19
+ const BRAVE_CREDENTIAL = "brave";
20
+ const SEARCH_TIMEOUT_MS = 20_000;
21
+ const SEARCH_COUNT_DEFAULT = 5;
22
+ const SEARCH_COUNT_MAX = 10;
23
+
24
+ export type WebDeps = {
25
+ /** 搜索 key 的第二来源(第一是环境变量)。不给 = 只认环境变量。 */
26
+ credentials?: Pick<CredentialStore, "read">;
27
+ /** 测试用:把 Brave 的接口指到假服务。 */
28
+ searchEndpoint?: string;
29
+ };
30
+
31
+ export function makeWebTools(deps: WebDeps = {}): ModelTool[] {
32
+ return [webFetchTool(), webSearchTool(deps)] as ModelTool[];
33
+ }
34
+
35
+ /** 环境变量 → 凭据 store → 没有。值只在这里经手,不进返回给模型的任何文字。 */
36
+ async function searchKey(deps: WebDeps): Promise<string | undefined> {
37
+ const env = process.env[BRAVE_ENV];
38
+ if (env !== undefined && env !== "") return env;
39
+ const stored = await deps.credentials?.read(BRAVE_CREDENTIAL);
40
+ return stored?.type === "api_key" && stored.key !== "" ? stored.key : undefined;
41
+ }
42
+
43
+ type BraveResult = { title?: unknown; url?: unknown; description?: unknown; age?: unknown; page_age?: unknown };
44
+
45
+ const FRESHNESS: Record<string, string> = { day: "pd", week: "pw", month: "pm", year: "py" };
46
+
47
+ function webSearchTool(deps: WebDeps): ModelTool<{ query: string; count?: number; freshness?: string }> {
48
+ return {
49
+ kind: "model",
50
+ name: "web_search",
51
+ label: "搜网页",
52
+ deferred: true,
53
+ description:
54
+ "Search the web (Brave Search) and return the top results as title, URL and snippet; read a result with web_fetch. " +
55
+ "count is 1-10 (default 5); freshness limits results to the last day, week, month or year. " +
56
+ `Needs a Brave Search API key: the ${BRAVE_ENV} environment variable or a '${BRAVE_CREDENTIAL}' entry in the credentials file.`,
57
+ parameters: {
58
+ type: "object",
59
+ properties: {
60
+ query: { type: "string" },
61
+ count: { type: "number", description: "How many results, 1-10 (default 5)" },
62
+ freshness: { type: "string", enum: ["day", "week", "month", "year"], description: "Only results from the last day/week/month/year" },
63
+ },
64
+ required: ["query"],
65
+ },
66
+ async execute({ query, count, freshness }, ctx) {
67
+ const q = query.trim();
68
+ if (q === "") return toolError("query is empty");
69
+ const key = await searchKey(deps);
70
+ if (key === undefined) {
71
+ return toolError(
72
+ `No search service configured: set ${BRAVE_ENV}, or add { "${BRAVE_CREDENTIAL}": { "apiKey": "…" } } to $ECHO_HOME/credentials.json ` +
73
+ "(a Brave Search API key, see https://brave.com/search/api/).",
74
+ );
75
+ }
76
+ const url = new URL(deps.searchEndpoint ?? BRAVE_ENDPOINT);
77
+ url.searchParams.set("q", q);
78
+ url.searchParams.set("count", String(Math.min(SEARCH_COUNT_MAX, Math.max(1, Math.floor(count ?? SEARCH_COUNT_DEFAULT)))));
79
+ if (freshness !== undefined) {
80
+ const code = FRESHNESS[freshness];
81
+ if (code === undefined) return toolError(`freshness must be one of day, week, month, year (got '${freshness}')`);
82
+ url.searchParams.set("freshness", code);
83
+ }
84
+ const timeout = AbortSignal.timeout(SEARCH_TIMEOUT_MS);
85
+ const signal = ctx.signal === undefined ? timeout : AbortSignal.any([ctx.signal, timeout]);
86
+ let res: Response;
87
+ let text: string;
88
+ try {
89
+ res = await fetch(url, { signal, headers: { accept: "application/json", "x-subscription-token": key } });
90
+ text = await res.text();
91
+ } catch (e) {
92
+ return toolError(`Search request failed: ${e instanceof Error ? e.message : String(e)}`);
93
+ }
94
+ if (res.status === 401 || res.status === 403) return toolError(`Brave Search rejected the API key (HTTP ${res.status}); check ${BRAVE_ENV} or the '${BRAVE_CREDENTIAL}' credential`);
95
+ if (res.status === 429) return toolError("Brave Search rate limit or quota exceeded (HTTP 429); wait or check the plan");
96
+ if (!res.ok) return toolError(`Brave Search returned HTTP ${res.status} ${res.statusText}\n${text.slice(0, 300)}`);
97
+ let results: BraveResult[];
98
+ try {
99
+ const parsed = JSON.parse(text) as { web?: { results?: unknown } };
100
+ results = Array.isArray(parsed.web?.results) ? (parsed.web.results as BraveResult[]) : [];
101
+ } catch {
102
+ return toolError("Brave Search returned a response that is not JSON");
103
+ }
104
+ if (results.length === 0) return toolOk(`No results for "${q}"`, { query: q, count: 0 });
105
+ const lines = results.map((r, i) => {
106
+ const title = typeof r.title === "string" ? stripTags(r.title) : "(untitled)";
107
+ const link = typeof r.url === "string" ? r.url : "";
108
+ const snippet = typeof r.description === "string" ? stripTags(r.description) : "";
109
+ const age = typeof r.age === "string" ? r.age : typeof r.page_age === "string" ? r.page_age : "";
110
+ return `${i + 1}. ${title}${age === "" ? "" : ` (${age})`}\n ${link}${snippet === "" ? "" : `\n ${snippet}`}`;
111
+ });
112
+ return toolOk(`Results for "${q}":\n${lines.join("\n")}`, { query: q, count: results.length });
113
+ },
114
+ };
115
+ }
116
+
117
+ /** Brave 的标题与摘要里带 `<strong>` 之类的高亮标签:剥掉、解实体、压空白。 */
118
+ function stripTags(s: string): string {
119
+ return decodeEntities(s.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
120
+ }
121
+
122
+ function webFetchTool(): ModelTool<{ url: string; max_chars?: number }> {
123
+ return {
124
+ kind: "model",
125
+ name: "web_fetch",
126
+ label: "取网页",
127
+ deferred: true,
128
+ description:
129
+ "Fetch a URL (http or https) and return its content as text: HTML is reduced to readable text with headings and " +
130
+ "links kept as [text](url); JSON and plain text come back as they are. Follows redirects, 30 s timeout, " +
131
+ "output capped at max_chars (default 20000). Find pages with web_search.",
132
+ parameters: {
133
+ type: "object",
134
+ properties: {
135
+ url: { type: "string" },
136
+ max_chars: { type: "number", description: "Cap on returned characters, default 20000" },
137
+ },
138
+ required: ["url"],
139
+ },
140
+ async execute({ url, max_chars }, ctx) {
141
+ let target: URL;
142
+ try {
143
+ target = new URL(url);
144
+ } catch {
145
+ return toolError(`Not a valid URL: ${url}`);
146
+ }
147
+ if (target.protocol !== "http:" && target.protocol !== "https:") return toolError(`Only http and https are supported: ${url}`);
148
+ const timeout = AbortSignal.timeout(TIMEOUT_MS);
149
+ const signal = ctx.signal === undefined ? timeout : AbortSignal.any([ctx.signal, timeout]);
150
+ let res: Response;
151
+ let bytes: Uint8Array;
152
+ let clipped = false;
153
+ try {
154
+ res = await fetch(target, {
155
+ signal,
156
+ redirect: "follow",
157
+ headers: { "user-agent": "echo-coding", accept: "text/html, text/plain, application/json;q=0.9, */*;q=0.5" },
158
+ });
159
+ // 流式读、到上限就取消:`arrayBuffer()` 会先把整个响应体收进内存再截,MAX_BYTES 那时限不住内存(review 2026-09-07)
160
+ const chunks: Uint8Array[] = [];
161
+ let total = 0;
162
+ const reader = res.body?.getReader();
163
+ if (reader !== undefined) {
164
+ for (;;) {
165
+ const { done, value } = await reader.read();
166
+ if (done) break;
167
+ if (value === undefined) continue;
168
+ if (total + value.byteLength > MAX_BYTES) {
169
+ chunks.push(value.subarray(0, MAX_BYTES - total));
170
+ total = MAX_BYTES;
171
+ clipped = true;
172
+ await reader.cancel();
173
+ break;
174
+ }
175
+ chunks.push(value);
176
+ total += value.byteLength;
177
+ }
178
+ }
179
+ bytes = new Uint8Array(total);
180
+ let offset = 0;
181
+ for (const c of chunks) {
182
+ bytes.set(c, offset);
183
+ offset += c.byteLength;
184
+ }
185
+ } catch (e) {
186
+ return toolError(`Fetch failed for ${url}: ${e instanceof Error ? e.message : String(e)}`);
187
+ }
188
+ const raw = new TextDecoder().decode(bytes);
189
+ const type = (res.headers.get("content-type") ?? "").toLowerCase();
190
+ if (!res.ok) return toolError(`HTTP ${res.status} ${res.statusText} for ${res.url !== "" ? res.url : url}\n${raw.slice(0, 500)}`);
191
+ let text: string;
192
+ if (type.includes("html")) text = htmlToText(raw);
193
+ else if (type === "" || type.startsWith("text/") || type.includes("json") || type.includes("xml")) text = raw;
194
+ else return toolError(`Unsupported content type '${type}' (${clipped ? `over ${MAX_BYTES}` : String(bytes.byteLength)} bytes) at ${url}`);
195
+ const cap = Math.max(1, max_chars ?? DEFAULT_MAX_CHARS);
196
+ const head = res.url !== "" && res.url !== url ? `(redirected to ${res.url})\n` : "";
197
+ const body =
198
+ text.length > cap ? `${text.slice(0, cap)}\n…[truncated: ${text.length} characters in total; raise max_chars to see more]` : text;
199
+ return toolOk(`${head}${body === "" ? "(empty)" : body}${clipped ? `\n…[response body over ${MAX_BYTES} bytes, cut]` : ""}`, {
200
+ url: res.url !== "" ? res.url : url,
201
+ status: res.status,
202
+ contentType: type,
203
+ });
204
+ },
205
+ };
206
+ }
207
+
208
+ /** HTML → 可读文本:去 script/style/head,标题成 `#`、列表成 `-`、绝对链接留成 `[text](url)`,块级标签换行,实体解码。 */
209
+ export function htmlToText(html: string): string {
210
+ let s = html.replace(/<!--[\s\S]*?-->/g, "").replace(/<(script|style|noscript|svg|template)\b[\s\S]*?<\/\1\s*>/gi, "");
211
+ const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(s)?.[1];
212
+ s = s.replace(/<head\b[\s\S]*?<\/head\s*>/i, "");
213
+ s = s.replace(/<a\b[^>]*?href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a\s*>/gi, (_m, href: string, inner: string) => {
214
+ const label = inner.replace(/<[^>]+>/g, "").trim();
215
+ return /^https?:\/\//i.test(href) && label !== "" && label !== href ? `[${label}](${href})` : label;
216
+ });
217
+ s = s
218
+ .replace(/<(br|hr)\b[^>]*\/?>/gi, "\n")
219
+ .replace(/<h([1-6])\b[^>]*>/gi, (_m, n: string) => `\n${"#".repeat(Number(n))} `)
220
+ .replace(/<\/(p|div|section|article|header|footer|main|nav|aside|h[1-6]|li|tr|blockquote|pre|table|ul|ol|dd|dt|figure)\s*>/gi, "\n")
221
+ .replace(/<li\b[^>]*>/gi, "- ")
222
+ .replace(/<(td|th)\b[^>]*>/gi, " ")
223
+ .replace(/<[^>]+>/g, "");
224
+ s = decodeEntities(s);
225
+ const text = s
226
+ .split("\n")
227
+ .map((l) => l.replace(/[ \t\r ]+/g, " ").trim())
228
+ .join("\n")
229
+ .replace(/\n{3,}/g, "\n\n")
230
+ .trim();
231
+ const t = title === undefined ? "" : decodeEntities(title).trim();
232
+ return t === "" ? text : `${t}\n\n${text}`;
233
+ }
234
+
235
+ const NAMED_ENTITIES: Record<string, string> = {
236
+ amp: "&",
237
+ lt: "<",
238
+ gt: ">",
239
+ quot: '"',
240
+ apos: "'",
241
+ nbsp: " ",
242
+ copy: "©",
243
+ reg: "®",
244
+ mdash: "—",
245
+ ndash: "–",
246
+ hellip: "…",
247
+ laquo: "«",
248
+ raquo: "»",
249
+ lsquo: "‘",
250
+ rsquo: "’",
251
+ ldquo: "“",
252
+ rdquo: "”",
253
+ };
254
+
255
+ function decodeEntities(s: string): string {
256
+ return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e: string) => {
257
+ if (e.startsWith("#")) {
258
+ const code = e[1]?.toLowerCase() === "x" ? Number.parseInt(e.slice(2), 16) : Number.parseInt(e.slice(1), 10);
259
+ try {
260
+ return String.fromCodePoint(code);
261
+ } catch {
262
+ return m;
263
+ }
264
+ }
265
+ return NAMED_ENTITIES[e.toLowerCase()] ?? m;
266
+ });
267
+ }
@@ -0,0 +1,151 @@
1
+ // worktree 隔离(2026-09-03 用户拍板 B):`worktree_enter` 在仓库里开一个 git worktree,并把 session 的工作目录
2
+ // 切过去——走 core 的 `AgentRuntime.setWorkspace`,**会话不断**(对话、任务清单都还在);`worktree_exit` 切回
3
+ // 主检出,可顺手删掉 worktree。目录固定在 `<仓库根>/.echo/worktrees/<name>`,分支同名、基于本地 HEAD;
4
+ // 路径写进 `.git/info/exclude`,不碰 tracked 文件。
5
+ //
6
+ // core 不解释路径(纯 JS),「是不是 git 仓库、目录在不在」这些宿主知识全在这层。
7
+
8
+ import { execFile } from "node:child_process";
9
+ import { existsSync } from "node:fs";
10
+ import { appendFile, mkdir, readFile } from "node:fs/promises";
11
+ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
12
+ import { toolError, toolOk, type ModelTool } from "@echo-agent/core";
13
+ import type { AgentRuntime } from "@echo-agent/core/extension";
14
+
15
+ export type WorktreeDeps = {
16
+ /** 给了才能真的切目录(`echo:worktree` 从 `AgentRuntimeService` 拿);不给的实例只用来报名字(identity)。 */
17
+ runtime?: Pick<AgentRuntime, "setWorkspace">;
18
+ };
19
+
20
+ /** 一组共享的状态:进 worktree 之前的目录。resume 之后没有它,退出时从 `git worktree list` 找主检出。 */
21
+ type WorktreeState = { home: string | undefined };
22
+
23
+ const WORKTREES_DIR = join(".echo", "worktrees");
24
+ const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
25
+
26
+ /** worktree 一组:`worktree_enter`(常驻)+ `worktree_exit`(延迟:进过才用得上)。 */
27
+ export function makeWorktreeTools(deps: WorktreeDeps = {}): ModelTool[] {
28
+ const state: WorktreeState = { home: undefined };
29
+ return [enterTool(deps, state), exitTool(deps, state)] as ModelTool[];
30
+ }
31
+
32
+ type GitResult = { ok: true; out: string } | { ok: false; err: string };
33
+
34
+ function git(cwd: string, args: string[]): Promise<GitResult> {
35
+ return new Promise((resolvePromise) => {
36
+ execFile("git", args, { cwd, encoding: "utf8", maxBuffer: 4_000_000 }, (error, stdout, stderr) => {
37
+ if (error !== null) resolvePromise({ ok: false, err: (stderr.trim() !== "" ? stderr : error.message).trim() });
38
+ else resolvePromise({ ok: true, out: stdout.trim() });
39
+ });
40
+ });
41
+ }
42
+
43
+ /** 在不在本产品开的 worktree 里——按路径判(`…/.echo/worktrees/<name>`),不认别人开的 worktree。 */
44
+ function inEchoWorktree(dir: string): boolean {
45
+ return dir.includes(`${sep}${WORKTREES_DIR}${sep}`);
46
+ }
47
+
48
+ /**
49
+ * 把 `.echo/worktrees/` 写进 `.git/info/exclude`(仓库私有、不 tracked):不然主检出的 `git status`
50
+ * 会把整个 worktree 目录当成未跟踪文件。写不进去不挡路,把原因带回给模型。
51
+ */
52
+ async function excludeFromGit(root: string): Promise<string> {
53
+ const p = await git(root, ["rev-parse", "--git-path", "info/exclude"]);
54
+ if (!p.ok) return `\n(could not locate .git/info/exclude: ${p.err})`;
55
+ const file = isAbsolute(p.out) ? p.out : resolve(root, p.out);
56
+ const line = ".echo/worktrees/";
57
+ try {
58
+ const current = existsSync(file) ? await readFile(file, "utf8") : "";
59
+ if (current.split("\n").some((l) => l.trim() === line)) return "";
60
+ await mkdir(dirname(file), { recursive: true });
61
+ await appendFile(file, `${current === "" || current.endsWith("\n") ? "" : "\n"}${line}\n`);
62
+ return "";
63
+ } catch (e) {
64
+ return `\n(could not add ${line} to ${file}: ${e instanceof Error ? e.message : String(e)})`;
65
+ }
66
+ }
67
+
68
+ function enterTool(deps: WorktreeDeps, state: WorktreeState): ModelTool<{ name?: string }> {
69
+ return {
70
+ kind: "model",
71
+ name: "worktree_enter",
72
+ label: "进 worktree",
73
+ description:
74
+ "Create a git worktree for this repository at .echo/worktrees/<name> on a new branch <name> (from the current HEAD) " +
75
+ "and make it the workspace: from then on file tools, search and bash resolve paths there, while the original checkout " +
76
+ "stays untouched. Use it when the work must not disturb the user's working copy or when tasks run in parallel. " +
77
+ "Nothing is installed in the new worktree (no node_modules); run the project's install command if the task needs it. " +
78
+ "Go back with worktree_exit.",
79
+ parameters: {
80
+ type: "object",
81
+ properties: {
82
+ name: { type: "string", description: "Worktree and branch name (letters, digits, . _ -); default: a generated one" },
83
+ },
84
+ },
85
+ async execute({ name }, ctx) {
86
+ if (deps.runtime === undefined) return toolError("This agent cannot switch its workspace (no runtime)");
87
+ if (inEchoWorktree(ctx.workspace)) return toolError(`Already inside a worktree (${ctx.workspace}); worktree_exit first`);
88
+ const top = await git(ctx.workspace, ["rev-parse", "--show-toplevel"]);
89
+ if (!top.ok) return toolError(`Not a git repository: ${ctx.workspace}\n${top.err}`);
90
+ const wtName = name ?? `wt-${Date.now().toString(36)}`;
91
+ if (!NAME_RE.test(wtName)) return toolError(`Invalid worktree name '${wtName}': use letters, digits, '.', '_' or '-'`);
92
+ const root = top.out;
93
+ const path = join(root, WORKTREES_DIR, wtName);
94
+ if (existsSync(path)) return toolError(`${path} already exists; pick another name or remove it first (git worktree remove)`);
95
+ const excludeNote = await excludeFromGit(root);
96
+ const added = await git(root, ["worktree", "add", path, "-b", wtName, "HEAD"]);
97
+ if (!added.ok) return toolError(`git worktree add failed:\n${added.err}`);
98
+ const switched = await deps.runtime.setWorkspace(path);
99
+ if (switched.kind === "rejected") {
100
+ return toolError(`Worktree created at ${path} but the workspace could not be switched: ${switched.reason}`);
101
+ }
102
+ state.home = ctx.workspace;
103
+ const head = await git(path, ["rev-parse", "--short", "HEAD"]);
104
+ return toolOk(
105
+ `Entered worktree ${path} on new branch ${wtName}${head.ok ? ` (from ${head.out})` : ""}. ` +
106
+ `The workspace is now this directory; the checkout at ${root} is untouched. Dependencies are not installed here.${excludeNote}`,
107
+ { path, branch: wtName },
108
+ );
109
+ },
110
+ };
111
+ }
112
+
113
+ function exitTool(deps: WorktreeDeps, state: WorktreeState): ModelTool<{ remove?: boolean }> {
114
+ return {
115
+ kind: "model",
116
+ name: "worktree_exit",
117
+ label: "出 worktree",
118
+ deferred: true,
119
+ description:
120
+ "Leave the worktree entered with worktree_enter: the workspace goes back to the main checkout. " +
121
+ "With remove: true the worktree directory is deleted afterwards (git refuses while it has uncommitted changes); " +
122
+ "the branch is kept either way.",
123
+ parameters: {
124
+ type: "object",
125
+ properties: { remove: { type: "boolean", description: "Delete the worktree directory after leaving (default false)" } },
126
+ },
127
+ async execute({ remove }, ctx) {
128
+ if (deps.runtime === undefined) return toolError("This agent cannot switch its workspace (no runtime)");
129
+ const here = ctx.workspace;
130
+ if (!inEchoWorktree(here)) return toolError(`Not inside a worktree: ${here}`);
131
+ let home = state.home;
132
+ if (home === undefined) {
133
+ // resume 之后没有记忆:`git worktree list` 的第一条就是主检出
134
+ const list = await git(here, ["worktree", "list", "--porcelain"]);
135
+ if (!list.ok) return toolError(`git worktree list failed:\n${list.err}`);
136
+ home = /^worktree (.+)$/m.exec(list.out)?.[1];
137
+ if (home === undefined) return toolError("Could not find the main checkout in git worktree list");
138
+ }
139
+ const branch = await git(here, ["rev-parse", "--abbrev-ref", "HEAD"]);
140
+ const b = branch.ok ? branch.out : "?";
141
+ const switched = await deps.runtime.setWorkspace(home);
142
+ if (switched.kind === "rejected") return toolError(`Could not switch the workspace back to ${home}: ${switched.reason}`);
143
+ state.home = undefined;
144
+ const meta = { path: home, worktree: here, branch: b };
145
+ if (remove !== true) return toolOk(`Back in ${home}. Worktree ${here} kept (branch ${b}).`, { ...meta, removed: false });
146
+ const removed = await git(home, ["worktree", "remove", here]);
147
+ if (!removed.ok) return toolError(`Back in ${home}, but the worktree ${here} was not removed (branch ${b}):\n${removed.err}`);
148
+ return toolOk(`Back in ${home}. Worktree ${here} removed (branch ${b} kept).`, { ...meta, removed: true });
149
+ },
150
+ };
151
+ }