diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml index 79b30290b5..9bf1c8cb73 100644 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md -2026-07-27-directory-listing-tool.md: a23cdb0090f1a88b783d9717aa3f0434b6c2782e -2026-07-27-directory-listing-tool.zh.md: bab0138a79ae770ae7e841392b879940e8ac2dc4 +2026-07-27-directory-listing-tool.md: fd8e8fb22d0b75a4d457e800296fa3ce2c2b5bd5 +2026-07-27-directory-listing-tool.zh.md: 7d4e797878858ea1ca09f1eea6c6a3953c9abae6 diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md index a23cdb0090..fd8e8fb22d 100644 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md @@ -62,7 +62,7 @@ Three presentation rules carry the decision: - **Directories sort first, then files, then non-regular children, each alphabetically** before paging, so every offset traverses one stable order and the first page keeps navigable structure. - **The canonical value and Native result carry one recoverable page** of at most `listMaxEntries` (default 200, configurable). The footer states the complete size and composition and gives `offset=` until the final page, so omitted sibling names remain reachable. -- **Filesystem text cannot forge presentation structure.** The path and entry names render as JSON strings with envelope-significant characters escaped; directory `/` and non-regular `@` markers sit outside the quoted name, so a regular filename ending in `@` remains distinguishable. +- **Filesystem text cannot forge presentation structure.** A name is emitted verbatim unless it would make the listing lie — a control character splitting one entry across lines, ``,因此被省略的同级名称仍可取回。 -- **文件系统文本无法伪造展示结构。** 路径和条目名渲染为 JSON 字符串,并转义对包络有意义的字符;目录 `/` 与非常规子项 `@` 标记位于带引号名称之外,因此以 `@` 结尾的常规文件名仍可区分。 +- **文件系统文本无法伪造展示结构。** 条目名默认原样输出;只有当它会让列出结果失真时才转为 JSON 字符串并中和 `\"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\"\ndirectory\n\n\"docs\"/\n\"src\"/\n\"package.json\"\n\"README.txt\"\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} +{"type":"tool/result","seq":50,"time":1785159115944,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","content":[{"type":"text","text":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\ndirectory\n\ndocs/\nsrc/\npackage.json\nREADME.txt\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} {"type":"step/end","seq":51,"time":1785159115950,"data":{"turn":1,"step":1}} {"type":"step/start","seq":52,"time":1785159115951,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":53,"time":1785159116889,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index 687b72d93e..3e7c989373 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md -README.md: 3917356b0e4cf48708f2769a6387249f795115ca -README.zh.md: b1ea0b42ed146241ee35d628825e0152c1bc1669 +README.md: 8fdd54fb36353ca6c1dbcf71cdad38c4bcf26b7d +README.zh.md: 567c8e0df58950369c59785859948e32cbccdef4 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 3917356b0e..8fdd54fb36 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -115,7 +115,7 @@ Prefix-stable while the visible tool definitions and order are unchanged. Regist #### What the model sees -A successful listing is ``, newline, `directory`, newline, ``, one line per page entry, a blank line, one footer, and ``. Each entry name is a JSON string with `<`, `>`, and `&` additionally Unicode-escaped so filesystem text cannot forge the envelope; a directory carries a trailing `/`, a non-regular child a trailing `@`, and a regular file neither. The footer is `(Empty directory)`, `( entries: directories, files)` with optional `, other`, or `(Showing entries - of : . Use offset= to continue.)`; the final page omits the continuation sentence. Every page states the complete count and composition. +A successful listing is ``, newline, `directory`, newline, ``, one line per page entry, a blank line, one footer, and ``. A directory carries a trailing `/`, a non-regular child a trailing `@`, and a regular file neither. A name is emitted verbatim unless it could make the listing say something untrue — a control character, a leading `"`, a backslash, ` entries: directories, files)` with optional `, other`, or `(Showing entries - of : . Use offset= to continue.)`; the final page omits the continuation sentence. Every page states the complete count and composition. #### Token effect diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index b1ea0b42ed..567c8e0df5 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -115,7 +115,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -成功列出结果为 ``、换行、`directory`、换行、``、页面中的每个条目一行、一个空行、一条 footer 和 ``。每个条目名都是 JSON 字符串,并额外对 `<`、`>` 和 `&` 做 Unicode 转义,使文件系统文本无法伪造包络;目录带尾部 `/`,非常规子项带尾部 `@`,常规文件两者都不带。footer 为 `(Empty directory)`、`( entries: directories, files)`(可选追加 `, other`),或 `(Showing entries - of : . Use offset= to continue.)`;最后一页省略继续提示。每一页都会说明完整计数与构成。 +成功列出结果为 ``、换行、`directory`、换行、``、页面中的每个条目一行、一个空行、一条 footer 和 ``。目录带尾部 `/`,非常规子项带尾部 `@`,常规文件两者都不带。条目名默认原样输出,只有当它可能让列出结果失真时才转为 JSON 字符串并中和 ` entries: directories, files)`(可选追加 `, other`),或 `(Showing entries - of : . Use offset= to continue.)`;最后一页省略继续提示。每一页都会说明完整计数与构成。 #### Token 影响 diff --git a/packages/fs/tool-fs/src/list-render.ts b/packages/fs/tool-fs/src/list-render.ts index eef3392ec0..86b57d02b3 100644 --- a/packages/fs/tool-fs/src/list-render.ts +++ b/packages/fs/tool-fs/src/list-render.ts @@ -77,17 +77,41 @@ function breakdown(counts: ListCounts): string { return parts.join(', ') } -/** JSON-string encode untrusted filesystem text and neutralize envelope tags. */ -function encodeFilesystemText(value: string): string { - return JSON.stringify(value) - .replaceAll('<', '\\u003c') - .replaceAll('>', '\\u003e') - .replaceAll('&', '\\u0026') +/** + * Names this renderer cannot emit verbatim, because POSIX allows every byte but + * `/` and NUL in a name and each of these would make the listing say something + * untrue: + * + * - a control character (a newline above all) splits one entry across lines; + * - ` 0 - ? `${page.entries.map(entry => `${encodeFilesystemText(entry.name)}${suffix[entry.type]}`).join('\n')}\n\n${footer}` + ? `${page.entries.map(entry => `${renderName(entry.name)}${suffix[entry.type]}`).join('\n')}\n\n${footer}` : footer - return `${encodeFilesystemText(page.path)} + return `${renderName(page.path)} directory ${body} diff --git a/packages/fs/tool-fs/tests/list-render.spec.ts b/packages/fs/tool-fs/tests/list-render.spec.ts index 2c26c1be2c..792c91bd18 100644 --- a/packages/fs/tool-fs/tests/list-render.spec.ts +++ b/packages/fs/tool-fs/tests/list-render.spec.ts @@ -42,12 +42,12 @@ describe('orderEntries', () => { describe('formatListOutput', () => { it('marks directories and non-regular children, and counts the whole listing', () => { - expect(formatListOutput(page([entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')]))).toBe(`"/w" + expect(formatListOutput(page([entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')]))).toBe(`/w directory -"src"/ -"a.txt" -"sock"@ +src/ +a.txt +sock@ (3 entries: 1 directory, 1 file, 1 other) `) @@ -64,13 +64,13 @@ describe('formatListOutput', () => { it('states the complete size and composition when the view is capped', () => { const entries = [entry('src', 'directory'), ...Array.from({ length: 5 }, (_, i) => entry(`f${i}.txt`))] const rendered = formatListOutput(page(entries.slice(0, 2), { totalEntries: entries.length, all: entries })) - expect(rendered).toContain('"src"/\n"f0.txt"\n') + expect(rendered).toContain('src/\nf0.txt\n') expect(rendered).not.toContain('f2.txt') expect(rendered).toContain('(Showing entries 1-2 of 6: 1 directory, 5 files. Use offset=3 to continue.)') }) it('renders an empty directory as a footer alone', () => { - expect(formatListOutput(page([]))).toBe(`"/w" + expect(formatListOutput(page([]))).toBe(`/w directory (Empty directory) diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts index 74268b72ca..1ab91fb665 100644 --- a/packages/fs/tool-fs/tests/tools.spec.ts +++ b/packages/fs/tool-fs/tests/tools.spec.ts @@ -231,13 +231,13 @@ describe('list tool', () => { totalEntries: 4, counts: { directories: 2, files: 1, other: 1 }, }) - expect(text(result)).toBe(`"/abs/." + expect(text(result)).toBe(`/abs/. directory -"archive"/ -"zeroomega-3.3.23"/ -"notes.md" -"link-to-nowhere"@ +archive/ +zeroomega-3.3.23/ +notes.md +link-to-nowhere@ (4 entries: 2 directories, 1 file, 1 other) `) @@ -248,7 +248,7 @@ describe('list tool', () => { seedDir(fs, 'empty', []) const result = await call(ctx, 'list', { path: 'empty' }) expect(text(result)).toContain('(Empty directory)') - expect(text(result)).toContain('"/abs/empty"') + expect(text(result)).toContain('/abs/empty') }) it('caps the rendered entries but still reports the complete composition', async () => { @@ -268,7 +268,7 @@ describe('list tool', () => { const rendered = text(result) // The one directory survives the cap because directories sort first — the // failure mode this ordering exists to prevent. - expect(rendered).toContain('"src"/\n"a.txt"\n') + expect(rendered).toContain('src/\na.txt\n') expect(rendered).not.toContain('c.txt') expect(rendered).toContain('(Showing entries 1-2 of 4: 1 directory, 3 files. Use offset=3 to continue.)') if (result.isError) throw new Error('expected list success') @@ -281,7 +281,7 @@ describe('list tool', () => { }) const continuation = await call(ctx, 'list', { offset: 3 }) - expect(text(continuation)).toContain('"b.txt"\n"c.txt"') + expect(text(continuation)).toContain('b.txt\nc.txt') expect(text(continuation)).toContain('(Showing entries 3-4 of 4: 1 directory, 3 files.)') }) @@ -313,8 +313,10 @@ describe('list tool', () => { { name: 'fake\n', type: 'file' }, ]) const rendered = text(await call(ctx, 'list', {})) - expect(rendered).toContain('"regular@"\n"special"@') - expect(rendered).toContain('"fake\\n\\u003c/content\\u003e"') + // A regular file really named `regular@` must not read as a socket named + // `regular`, and a newline in a name must not become a second entry. + expect(rendered).toContain('"regular@"\nspecial@') + expect(rendered).toContain('"fake\\n<\\/content>"') expect(rendered.match(/<\/content>/g)).toHaveLength(1) })