Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(fs): make dsh-file-context an event-gate plugin, not a method service

Browse Source 
Invert the tool↔policy control flow per the file-context event-gate RFC.
dsh-tool-fs becomes the executor — it reads/writes/edits through ctx.fs
directly, owns read windowing, and dispatches fs/write-expectation /
fs/edit-expectation (single-slot waterfalls) plus a contained fs/observed
emit. dsh-file-context drops its ctx.fileContext service and becomes a pure
event-gate plugin (observed-state + read-before-edit + version-guarded
write/edit, decided on those events). The provider's version guard becomes
optional so ctx.fs alone is a complete unconstrained text-storage seam:
removing the policy plugin gracefully loses the policy instead of breaking
the tool at a service-injection boundary.
This commit is contained in:
Dudu-0223
2026-06-28 13:49:02 +08:00
parent d612ebaef1
commit 90dceea0e4
35 changed files with 1229 additions and 793 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
packages/fs/tool-fs/tests/integration.spec.ts
View File

@@ -1,12 +1,20 @@
/**
* Integration tests: the real local backend (`dsh-fs-local`) plus the real
* policy layer (`dsh-file-context`) plus the model tools (`dsh-tool-fs`),
* exercised through `ctx.tools.execute()` so nothing bypasses the tool registry.
* Integration tests: the real local backend (`dsh-fs-local`) plus the model
* tools (`dsh-tool-fs`) as the executor, exercised through `ctx.tools.execute()`
* so nothing bypasses the tool registry. Two deployments:
*
* - DEFAULT — with the real `dsh-file-context` policy gate plugin: read-before-
* write/edit, version-guarded mutation, FS_NOT_OBSERVED for unread edits.
* - BARE — WITHOUT the policy plugin, loading only SUBPATH plugins: every
* `fs/*` waterfall falls through to its undefined default, so write/edit are
* unconditional. This proves the subpaths (not just the root) carry no policy
* dependency.
*
* These verify the WORLD — files are read back from disk and asserted
* byte-for-byte — not the tool's self-report.
*/
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
@@ -15,8 +23,11 @@ import { CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
import FileContext from '@deepseek-ai/dsh-file-context'
import * as FileContext from '@deepseek-ai/dsh-file-context'
import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
import * as readPlugin from '@deepseek-ai/dsh-tool-fs/read'
import * as writePlugin from '@deepseek-ai/dsh-tool-fs/write'
import * as editPlugin from '@deepseek-ai/dsh-tool-fs/edit'
let dir: string
let ctx: Context
@@ -24,20 +35,6 @@ let fiber: Awaited<ReturnType<Context['plugin']>>
// A stable session object stands in for an agent session (the file-state owner).
const session = {}
beforeEach(async () => {
dir = await mkdtemp(join(tmpdir(), 'dsh-tool-fs-'))
ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(LocalFileSystem, { cwd: dir })
await ctx.plugin(FileContext)
fiber = await ctx.plugin(ToolFs)
})
afterEach(async () => {
await fiber.dispose()
await rm(dir, { recursive: true, force: true })
})
let callCounter = 0
function call(name: string, args: unknown) {
return ctx.tools.execute({
@@ -52,137 +49,260 @@ function text(result: { content: { type: string; text?: string }[] }): string {
return result.content.filter(b => b.type === 'text').map(b => b.text).join('')
}
describe('write → disk', () => {
it('creates a file with exactly the requested bytes', async () => {
const result = await call('write', { file_path: 'new.txt', content: 'line one\nline two\n' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'new.txt'), 'utf8')).toBe('line one\nline two\n')
afterEach(async () => {
await fiber.dispose()
await rm(dir, { recursive: true, force: true })
})
// --------------------------------------------------------------------------
// DEFAULT deployment: the policy gate plugin is loaded.
// --------------------------------------------------------------------------
describe('default deployment (with dsh-file-context)', () => {
beforeEach(async () => {
dir = await mkdtemp(join(tmpdir(), 'dsh-tool-fs-'))
ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(LocalFileSystem, { cwd: dir })
await ctx.plugin(FileContext)
fiber = await ctx.plugin(ToolFs)
})
it('rejects overwriting an existing file without reading it first', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
const result = await call('write', { file_path: 'a.txt', content: 'clobber' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('original')
describe('write → disk', () => {
it('creates a file with exactly the requested bytes', async () => {
const result = await call('write', { file_path: 'new.txt', content: 'line one\nline two\n' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'new.txt'), 'utf8')).toBe('line one\nline two\n')
})
it('rejects overwriting an existing file without reading it first', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
const result = await call('write', { file_path: 'a.txt', content: 'clobber' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('original')
})
it('allows overwriting after a read', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
const result = await call('write', { file_path: 'a.txt', content: 'replaced' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('replaced')
})
it('rejects a full overwrite when the file changed since the read (stale)', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
await call('read', { file_path: 'a.txt' })
await writeFile(join(dir, 'a.txt'), 'changed-externally') // out-of-band change
const result = await call('write', { file_path: 'a.txt', content: 'replaced' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
})
})
it('allows overwriting after a read', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
const result = await call('write', { file_path: 'a.txt', content: 'replaced' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('replaced')
describe('read', () => {
it('returns line-numbered content', async () => {
await writeFile(join(dir, 'a.txt'), 'alpha\nbeta')
const result = await call('read', { file_path: 'a.txt' })
expect(text(result)).toContain('1: alpha')
expect(text(result)).toContain('2: beta')
expect(text(result)).toContain('(End of file - total 2 lines)')
})
it('reports a binary file as an error', async () => {
await writeFile(join(dir, 'bin'), Buffer.from([0x00, 0x01, 0x02]))
const result = await call('read', { file_path: 'bin' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_TEXT' })
})
it('paginates a multi-line file with offset/limit', async () => {
await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree\nfour')
const result = await call('read', { file_path: 'a.txt', offset: 2, limit: 2 })
expect(text(result)).toContain('2: two')
expect(text(result)).toContain('3: three')
expect(text(result)).toContain('(Showing lines 2-3 of 4. Use offset=4 to continue.)')
})
})
it('rejects a full overwrite when the file changed since the read (stale)', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
await call('read', { file_path: 'a.txt' })
await writeFile(join(dir, 'a.txt'), 'changed-externally') // out-of-band change
const result = await call('write', { file_path: 'a.txt', content: 'replaced' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
describe('edit → disk', () => {
it('applies a unique literal replacement after a read', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
await call('read', { file_path: 'a.txt' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello there')
})
it('rejects an edit before any read, leaving the file untouched', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello world')
})
it('lets a WINDOWED read authorize an edit when the file is unchanged (freshness, not full-view)', async () => {
// A file with more lines than the read window; read only the first line.
const lines = Array.from({ length: 20 }, (_, i) => `line ${i + 1}`)
await writeFile(join(dir, 'a.txt'), lines.join('\n'))
const read = await call('read', { file_path: 'a.txt', offset: 1, limit: 1 })
expect(read.isError).toBe(false)
expect(text(read)).toContain('(Showing lines 1-1 of 20')
// Editing a line OUTSIDE the window is authorized because the file is unchanged.
const result = await call('edit', { file_path: 'a.txt', old_string: 'line 12', new_string: 'LINE 12' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe(lines.map(l => l === 'line 12' ? 'LINE 12' : l).join('\n'))
})
it('rejects an edit when the file changed since the windowed read (stale before matching)', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
await call('read', { file_path: 'a.txt', offset: 1, limit: 1 })
await writeFile(join(dir, 'a.txt'), 'goodbye') // out-of-band change removes 'world'
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
})
it('rejects an ambiguous match without replace_all', async () => {
await writeFile(join(dir, 'a.txt'), 'a a a')
await call('read', { file_path: 'a.txt' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_AMBIGUOUS_EDIT' })
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('a a a')
})
it('replaces all matches with replace_all', async () => {
await writeFile(join(dir, 'a.txt'), 'a a a')
await call('read', { file_path: 'a.txt' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b', replace_all: true })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('b b b')
})
it('supports a full write→edit cycle without an intervening read', async () => {
await call('write', { file_path: 'a.txt', content: 'one two' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'two', new_string: 'three' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('one three')
})
})
describe('the gate records only through the events (no method coupling)', () => {
it('a direct ctx.fs.readText records no observed-state, so a later edit rejects', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
// Reach AROUND the tool — an explicit escape hatch for non-tool consumers.
await ctx.fs.readText(await ctx.fs.resolve('a.txt'))
// The model-facing edit still rejects: the read did not emit fs/observed.
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
})
})
describe('stat budget', () => {
it('read stats once; write and edit never stat in the tool (the gate stats zero too)', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
const statSpy = vi.spyOn(ctx.fs, 'stat')
// read: exactly one stat (type + size routing + observed version).
await call('read', { file_path: 'a.txt' })
expect(statSpy).toHaveBeenCalledTimes(1)
// edit (guarded, after the read): the gate supplies vObserved; the tool
// does not stat to manufacture a basis. CAS happens in editText's lock.
statSpy.mockClear()
const edited = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(edited.isError).toBe(false)
expect(statSpy).not.toHaveBeenCalled()
// write (guarded replace, after the edit refreshed observed state): zero stat.
statSpy.mockClear()
const written = await call('write', { file_path: 'a.txt', content: 'fresh' })
expect(written.isError).toBe(false)
expect(statSpy).not.toHaveBeenCalled()
statSpy.mockRestore()
})
})
describe('contained fs/observed recording', () => {
it('a synchronously throwing fs/observed listener does not fail the completed write', async () => {
ctx.on('fs/observed', () => { throw new Error('listener boom') })
const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
const result = await call('write', { file_path: 'a.txt', content: 'hi' })
// The write succeeded on disk; the listener throw was logged and swallowed.
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hi')
expect(warn).toHaveBeenCalled()
warn.mockRestore()
})
})
})
describe('read', () => {
it('returns line-numbered content', async () => {
// --------------------------------------------------------------------------
// BARE deployment: SUBPATH plugins only, NO policy gate.
// --------------------------------------------------------------------------
describe('bare provider (subpath plugins, no dsh-file-context)', () => {
beforeEach(async () => {
dir = await mkdtemp(join(tmpdir(), 'dsh-tool-fs-bare-'))
ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(LocalFileSystem, { cwd: dir })
await ctx.plugin(readPlugin)
await ctx.plugin(writePlugin)
fiber = await ctx.plugin(editPlugin)
})
it('read works (it never needed policy)', async () => {
await writeFile(join(dir, 'a.txt'), 'alpha\nbeta')
const result = await call('read', { file_path: 'a.txt' })
expect(result.isError).toBe(false)
expect(text(result)).toContain('1: alpha')
expect(text(result)).toContain('2: beta')
expect(text(result)).toContain('(End of file - total 2 lines)')
})
it('reports a binary file as an error', async () => {
await writeFile(join(dir, 'bin'), Buffer.from([0x00, 0x01, 0x02]))
const result = await call('read', { file_path: 'bin' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_TEXT' })
it('write unconditionally creates a new file', async () => {
const result = await call('write', { file_path: 'new.txt', content: 'fresh' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'new.txt'), 'utf8')).toBe('fresh')
})
it('paginates a multi-line file with offset/limit', async () => {
await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree\nfour')
const result = await call('read', { file_path: 'a.txt', offset: 2, limit: 2 })
expect(text(result)).toContain('2: two')
expect(text(result)).toContain('3: three')
expect(text(result)).toContain('(Showing lines 2-3 of 4. Use offset=4 to continue.)')
it('write unconditionally OVERWRITES an existing unread file', async () => {
await writeFile(join(dir, 'a.txt'), 'original')
const result = await call('write', { file_path: 'a.txt', content: 'clobbered' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('clobbered')
})
})
describe('edit → disk', () => {
it('applies a unique literal replacement after a read', async () => {
it('edit unconditionally edits an UNREAD existing file', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
await call('read', { file_path: 'a.txt' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello there')
})
it('rejects an edit before any read, leaving the file untouched', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello world')
})
it('lets a WINDOWED read authorize an edit when the file is unchanged (freshness, not full-view)', async () => {
// A file with more lines than the read window; read only the first line.
const lines = Array.from({ length: 20 }, (_, i) => `line ${i + 1}`)
await writeFile(join(dir, 'a.txt'), lines.join('\n'))
const read = await call('read', { file_path: 'a.txt', offset: 1, limit: 1 })
expect(read.isError).toBe(false)
expect(text(read)).toContain('(Showing lines 1-1 of 20')
// Editing a line OUTSIDE the window is authorized because the file is unchanged.
const result = await call('edit', { file_path: 'a.txt', old_string: 'line 12', new_string: 'LINE 12' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe(lines.map(l => l === 'line 12' ? 'LINE 12' : l).join('\n'))
})
it('rejects an edit when the file changed since the windowed read (stale before matching)', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
await call('read', { file_path: 'a.txt', offset: 1, limit: 1 })
await writeFile(join(dir, 'a.txt'), 'goodbye') // out-of-band change removes 'world'
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
it('edit of a MISSING target reports FS_STALE_VERSION even on the unguarded path', async () => {
const result = await call('edit', { file_path: 'missing.txt', old_string: 'a', new_string: 'b' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
})
it('rejects an ambiguous match without replace_all', async () => {
await writeFile(join(dir, 'a.txt'), 'a a a')
await call('read', { file_path: 'a.txt' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_AMBIGUOUS_EDIT' })
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('a a a')
})
it('replaces all matches with replace_all', async () => {
await writeFile(join(dir, 'a.txt'), 'a a a')
await call('read', { file_path: 'a.txt' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b', replace_all: true })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('b b b')
})
it('supports a full write→edit cycle without an intervening read', async () => {
await call('write', { file_path: 'a.txt', content: 'one two' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'two', new_string: 'three' })
expect(result.isError).toBe(false)
expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('one three')
})
})
describe('no-bypass / escape-hatch contract', () => {
it('a direct ctx.fs.readText records no observed-state, so a later edit rejects', async () => {
it('edit still enforces literal-match codes (FS_EDIT_NOT_FOUND), unrelated to freshness', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
// Reach AROUND the policy layer — an explicit escape hatch for non-tool consumers.
await ctx.fs.readText(await ctx.fs.resolve('a.txt'))
// The model-facing edit still rejects: the read was not through ctx.fileContext.
const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
const result = await call('edit', { file_path: 'a.txt', old_string: 'absent', new_string: 'x' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
expect(result.error).toMatchObject({ code: 'FS_EDIT_NOT_FOUND' })
})
it('neither write nor edit stats in the tool on the bare path', async () => {
await writeFile(join(dir, 'a.txt'), 'hello world')
const statSpy = vi.spyOn(ctx.fs, 'stat')
expect((await call('write', { file_path: 'a.txt', content: 'x y' })).isError).toBe(false)
expect((await call('edit', { file_path: 'a.txt', old_string: 'y', new_string: 'z' })).isError).toBe(false)
expect(statSpy).not.toHaveBeenCalled()
statSpy.mockRestore()
})
})

13
packages/fs/tool-fs/tests/subpaths.spec.ts
View File

@@ -1,7 +1,10 @@
/**
* Tests for the per-tool subpath plugins (`@deepseek-ai/dsh-tool-fs/read`,
* `/write`, `/edit`): each registers exactly one tool, injects the same
* services (`tools`, `fileContext`, `systemPrompt`), and cleans up on disposal.
* `/write`, `/edit`): each registers exactly one tool, injects the same services
* (`tools`, `fs`, `systemPrompt`) — NOT a policy service — and cleans up on
* disposal. They boot over the bare `ctx.fs` provider with NO
* `@deepseek-ai/dsh-file-context`, proving each subpath carries no policy-plugin
* dependency.
*/
import { describe, expect, it } from 'vitest'
@@ -15,7 +18,6 @@ import type {
FsTarget,
FsWriteOutcome,
} from '@deepseek-ai/dsh-fs'
import FileContext from '@deepseek-ai/dsh-file-context'
import * as readPlugin from '@deepseek-ai/dsh-tool-fs/read'
import * as writePlugin from '@deepseek-ai/dsh-tool-fs/write'
import * as editPlugin from '@deepseek-ai/dsh-tool-fs/edit'
@@ -46,12 +48,11 @@ async function base() {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(StubFs)
await ctx.plugin(FileContext)
return ctx
}
describe('subpath plugins', () => {
it('each registers exactly its one tool', async () => {
it('each registers exactly its one tool (over the bare provider, no policy plugin)', async () => {
const cases: Array<[unknown, string]> = [
[readPlugin, 'read'],
[writePlugin, 'write'],
@@ -72,7 +73,7 @@ describe('subpath plugins', () => {
expect(ctx.tools.schemas()).toHaveLength(0)
})
it('stays pending without a ctx.fileContext provider', async () => {
it('stays pending without a ctx.fs provider', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)

85
packages/fs/tool-fs/tests/tools.spec.ts
View File

@@ -1,13 +1,14 @@
/**
* Consumer-surface tests for the filesystem tools. They run the REAL
* `ctx.fileContext` policy service over a fake `ctx.fs` provider (the genuine
* collaborator, per the prefer-the-real-implementation rule), so they verify
* schemas, argument validation, result formatting, FsError→isError propagation,
* and that each tool records observed-state through `ctx.fileContext` (the
* no-bypass contract) — not just that it moved bytes.
* Consumer-surface tests for the filesystem tools as the EXECUTOR. They run the
* REAL `@deepseek-ai/dsh-file-context` gate plugin (the genuine policy
* collaborator, per the prefer-the-real-implementation rule) over a fake
* `ctx.fs` provider, so they verify schemas, argument validation, result
* formatting, FsError→isError propagation, and that each tool dispatches the
* `fs/*` waterfalls + records observed-state through the gate (read authorizes a
* later edit) — not just that it moved bytes.
*/
import { describe, expect, it } from 'vitest'
import { describe, expect, it, vi } from 'vitest'
import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -21,15 +22,17 @@ import type {
FsWriteExpectation,
FsWriteOutcome,
} from '@deepseek-ai/dsh-fs'
import FileContext from '@deepseek-ai/dsh-file-context'
import type { FileReadOutcome } from '@deepseek-ai/dsh-file-context'
import * as FileContext from '@deepseek-ai/dsh-file-context'
import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
import { formatReadOutput } from '@deepseek-ai/dsh-tool-fs'
import { formatReadOutput, STREAM_MIN_SIZE } from '@deepseek-ai/dsh-tool-fs'
import type { FileReadOutcome } from '@deepseek-ai/dsh-tool-fs'
/** An in-memory fake provider; a test can arm a rejection on any primitive. */
class FakeFs extends FileSystem {
files = new Map<string, string>()
rejectWith?: FsError
writeExpectations: (FsWriteExpectation | undefined)[] = []
editExpectations: ({ version: FsVersion } | undefined)[] = []
private throwIfArmed(): void {
if (this.rejectWith) throw this.rejectWith
@@ -51,14 +54,16 @@ class FakeFs extends FileSystem {
const content = this.files.get(target.targetKey) ?? ''
return (async function* () { yield content })()
}
override async writeText(target: FsTarget, content: string, _expected: FsWriteExpectation): Promise<FsWriteOutcome> {
override async writeText(target: FsTarget, content: string, expected?: FsWriteExpectation): Promise<FsWriteOutcome> {
this.throwIfArmed()
this.writeExpectations.push(expected)
const existed = this.files.has(target.targetKey)
this.files.set(target.targetKey, content)
return { operation: existed ? 'update' : 'create', version: FsVersion('v2') }
}
override async editText(target: FsTarget, edit: FsEditRequest): Promise<FsEditOutcome> {
override async editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }): Promise<FsEditOutcome> {
this.throwIfArmed()
this.editExpectations.push(expected)
const content = this.files.get(target.targetKey) ?? ''
this.files.set(target.targetKey, content.split(edit.oldString).join(edit.newString))
return { replacements: 1, replaceAll: edit.replaceAll, version: FsVersion('v3') }
@@ -104,11 +109,11 @@ describe('registration', () => {
expect(prompt).toContain('Use the edit tool')
})
it('stays pending until ctx.fileContext exists (inject)', async () => {
it('stays pending until ctx.fs exists (inject)', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(ToolFs) // no fileContext provider
await ctx.plugin(ToolFs) // no fs provider
expect(ctx.tools.schemas()).toHaveLength(0)
})
@@ -169,6 +174,7 @@ describe('read tool', () => {
expect((await call(ctx, 'read', { file_path: 'a.txt' }, { session })).isError).toBe(false)
const edited = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'hello', new_string: 'bye' }, { session })
expect(edited.isError).toBe(false)
expect(fs.editExpectations).toEqual([{ version: 'v1' }])
})
it('propagates FS_NOT_FOUND for an absent file', async () => {
@@ -177,6 +183,48 @@ describe('read tool', () => {
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_FOUND' })
})
it('rejects a non-regular target', async () => {
const { ctx, fs } = await setup()
fs.files.set('key:d', '')
fs.stat = async () => ({ version: FsVersion('v1'), type: 'directory' })
const result = await call(ctx, 'read', { file_path: 'd' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
})
it('streams a large file (size at/above the cap) instead of reading whole', async () => {
const { ctx, fs } = await setup()
fs.files.set('key:big.txt', 'alpha\nbeta')
const readSpy = vi.spyOn(fs, 'readText')
const streamSpy = vi.spyOn(fs, 'streamText')
fs.stat = async () => ({ version: FsVersion('v1'), type: 'file', size: STREAM_MIN_SIZE })
const result = await call(ctx, 'read', { file_path: 'big.txt' })
expect(result.isError).toBe(false)
expect(text(result)).toContain('1: alpha')
expect(streamSpy).toHaveBeenCalled()
expect(readSpy).not.toHaveBeenCalled()
})
it('streams when the backend reports no size (never buffers a size-less file)', async () => {
const { ctx, fs } = await setup()
fs.files.set('key:a.txt', 'alpha')
const streamSpy = vi.spyOn(fs, 'streamText')
fs.stat = async () => ({ version: FsVersion('v1'), type: 'file' }) // no size
const result = await call(ctx, 'read', { file_path: 'a.txt' })
expect(result.isError).toBe(false)
expect(streamSpy).toHaveBeenCalled()
})
it('surfaces a byte-capped read as a truncated footer', async () => {
const { ctx, fs } = await setup()
// Many long lines so the window hits the byte cap before EOF.
fs.files.set('key:big.txt', Array.from({ length: 2000 }, () => 'y'.repeat(100)).join('\n'))
const result = await call(ctx, 'read', { file_path: 'big.txt' })
expect(result.isError).toBe(false)
expect(text(result)).toContain('Output capped.')
})
})
describe('formatReadOutput footer variants', () => {
@@ -204,11 +252,12 @@ describe('formatReadOutput footer variants', () => {
})
describe('write tool', () => {
it('formats a create result', async () => {
const { ctx } = await setup()
const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'hi' })
it('formats a create result and uses createIfAbsent (unobserved, with the gate)', async () => {
const { ctx, fs } = await setup()
const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'hi' }, { session: {} })
expect(result.isError).toBe(false)
expect(text(result)).toContain('Created file')
expect(fs.writeExpectations).toEqual([{ kind: 'createIfAbsent' }])
})
it('rejects a blank file_path', async () => {
@@ -258,7 +307,7 @@ describe('edit tool', () => {
expect(text(result)).toContain('file_path must be a non-empty string')
})
it('propagates FS_NOT_OBSERVED when the file was never read', async () => {
it('propagates FS_NOT_OBSERVED when the file was never read (the gate decides)', async () => {
const { ctx, fs } = await setup()
fs.files.set('key:a.txt', 'hello')
const result = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b' }, { session: {} })

102
packages/fs/tool-fs/tests/window.spec.ts Normal file
View File

@@ -0,0 +1,102 @@
/**
* Cordis-free tests for the line-windowing module: offset/limit windows, byte
* caps, per-line truncation, CRLF stripping, offset-past-EOF rejection, and the
* capped line buffer for newline-free giant lines — all over an async-iterable
* of decoded text chunks (so one code path serves whole-file and streamed reads).
*/
import { describe, expect, it } from 'vitest'
import { buildWindow, READ_MAX_LINE_LENGTH } from '@deepseek-ai/dsh-tool-fs'
import type { ReadWindow } from '@deepseek-ai/dsh-tool-fs'
const READ_ALL: ReadWindow = { offset: 1, limit: 2000 }
/** Yield `text` as one chunk (whole-file read shape). */
async function* whole(text: string): AsyncIterable<string> {
yield text
}
/** Yield `text` split into fixed-size chunks (streamed read shape). */
async function* chunked(text: string, size: number): AsyncIterable<string> {
for (let i = 0; i < text.length; i += size) yield text.slice(i, i + size)
}
describe('buildWindow', () => {
it('numbers lines and reports total for a whole-file read', async () => {
const result = await buildWindow(whole('one\ntwo\nthree'), READ_ALL, 'f')
expect(result.lines).toEqual([
{ number: 1, text: 'one' },
{ number: 2, text: 'two' },
{ number: 3, text: 'three' },
])
expect(result.totalLines).toBe(3)
expect(result.truncatedByBytes).toBe(false)
})
it('applies offset/limit', async () => {
const result = await buildWindow(whole('one\ntwo\nthree\nfour'), { offset: 2, limit: 2 }, 'f')
expect(result.lines.map(l => l.number)).toEqual([2, 3])
expect(result.totalLines).toBe(4)
})
it('strips CRLF', async () => {
const result = await buildWindow(whole('one\r\ntwo\r\n'), READ_ALL, 'f')
expect(result.lines.map(l => l.text)).toEqual(['one', 'two'])
})
it('truncates an over-long line', async () => {
const result = await buildWindow(whole('x'.repeat(3000)), READ_ALL, 'f')
expect(result.lines[0]?.text).toContain(`... (line truncated to ${READ_MAX_LINE_LENGTH} chars)`)
})
it('caps output bytes and reports truncatedByBytes', async () => {
const big = Array.from({ length: 2000 }, () => 'y'.repeat(100)).join('\n')
const result = await buildWindow(whole(big), READ_ALL, 'f')
expect(result.truncatedByBytes).toBe(true)
})
it('reads an empty file at offset 1 as zero lines', async () => {
const result = await buildWindow(whole(''), READ_ALL, 'f')
expect(result.lines).toEqual([])
expect(result.totalLines).toBe(0)
})
it('rejects an offset past EOF', async () => {
await expect(buildWindow(whole('one\ntwo'), { offset: 9, limit: 1 }, 'f')).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
})
it('flushes a final line with no trailing newline', async () => {
const result = await buildWindow(whole('one\ntwo'), READ_ALL, 'f')
expect(result.lines.map(l => l.text)).toEqual(['one', 'two'])
})
it('handles a trailing newline (no dangling empty line)', async () => {
const result = await buildWindow(whole('one\ntwo\n'), READ_ALL, 'f')
expect(result.lines.map(l => l.text)).toEqual(['one', 'two'])
expect(result.totalLines).toBe(2)
})
describe('chunked input (streamed read shape)', () => {
it('windows identically when text arrives in small chunks', async () => {
const result = await buildWindow(chunked('one\ntwo\nthree', 2), { offset: 2, limit: 1 }, 'f')
expect(result.lines).toEqual([{ number: 2, text: 'two' }])
expect(result.totalLines).toBe(3)
})
it('caps a newline-free giant line split across chunks without unbounded buffering', async () => {
const result = await buildWindow(chunked('z'.repeat(5000), 256), READ_ALL, 'f')
expect(result.lines[0]?.text).toContain(`... (line truncated to ${READ_MAX_LINE_LENGTH} chars)`)
})
it('caps output bytes mid-stream', async () => {
const big = Array.from({ length: 2000 }, () => 'y'.repeat(100)).join('\n')
const result = await buildWindow(chunked(big, 512), READ_ALL, 'f')
expect(result.truncatedByBytes).toBe(true)
})
it('flushes a final newline-terminated line across a chunk boundary', async () => {
const result = await buildWindow(chunked('one\ntwo\n', 3), READ_ALL, 'f')
expect(result.lines.map(l => l.text)).toEqual(['one', 'two'])
})
})
})