Files
deepseek-harness/packages/prompt/project-instructions/tests/project-instructions.spec.ts
T
2026-07-05 18:18:32 +08:00

1017 lines
42 KiB
TypeScript

import { chmod, mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import { describe, expect, it, vi } from 'vitest'
import { Context } from 'cordis'
import Loader from '@cordisjs/plugin-loader'
import * as projectInstructions from '@deepseek-ai/dsh-project-instructions'
import { CallId, type GenerateOptions } from '@deepseek-ai/dsh-llm'
import { Session, SessionId, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session'
import type { Agent } from '@deepseek-ai/dsh-agent'
import { AgentId } from '@deepseek-ai/dsh-agent'
import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
import type {
FsDirEntry,
FsEditOutcome,
FsEditRequest,
FsInfo,
FsTarget,
FsWriteIntent,
FsWriteOutcome,
} from '@deepseek-ai/dsh-fs'
import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
import {
discoverBaselineInstructionFiles,
loadBaselineInstructions,
renderProjectInstructions,
type InstructionContentCache,
} from '@deepseek-ai/dsh-project-instructions'
async function tempRepo(): Promise<string> {
return mkdtemp(join(tmpdir(), 'dsh-project-instructions-'))
}
async function write(path: string, content: string): Promise<void> {
await mkdir(join(path, '..'), { recursive: true })
await writeFile(path, content)
}
class RecordingFileSystem extends FileSystem {
entries = new Map<string, { type: FsInfo['type']; content?: string }>()
throwOnStat = new Set<string>()
readTargets: string[] = []
override async resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget> {
const absolute = join(opts?.cwd ?? '/', path)
return { targetKey: FsTargetKey(absolute), displayPath: absolute }
}
override async stat(target: FsTarget): Promise<FsInfo | undefined> {
if (this.throwOnStat.has(target.targetKey)) throw new Error(`stat failed: ${target.displayPath}`)
const entry = this.entries.get(target.targetKey)
if (entry === undefined) return undefined
const info: FsInfo = {
version: FsVersion(`v:${target.targetKey}`),
type: entry.type,
}
if (entry.content !== undefined) info.size = Buffer.byteLength(entry.content, 'utf8')
return info
}
override async readText(target: FsTarget): Promise<string> {
this.readTargets.push(target.targetKey)
return this.entries.get(target.targetKey)?.content ?? ''
}
override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
const content = await this.readText(target)
return (async function* () { yield content })()
}
override async listDir(_target: FsTarget): Promise<FsDirEntry[]> {
return []
}
override async writeText(_target: FsTarget, _content: string, _expected?: FsWriteIntent): Promise<FsWriteOutcome> {
return { operation: 'update', version: FsVersion('unused'), before: '', after: _content }
}
override async editText(_target: FsTarget, _edit: FsEditRequest): Promise<FsEditOutcome> {
return { version: FsVersion('unused'), before: '', after: '' }
}
}
async function mountProjectInstructions(ctx: Context, config: projectInstructions.Config): Promise<Awaited<ReturnType<Context['plugin']>>> {
await ctx.plugin(LocalFileSystem, { cwd: '/' })
return ctx.plugin(projectInstructions, config)
}
async function mountFileToolsAndProjectInstructions(ctx: Context, config: projectInstructions.Config): Promise<Awaited<ReturnType<Context['plugin']>>> {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(LocalFileSystem, { cwd: '/' })
await ctx.plugin(ToolFs)
return ctx.plugin(projectInstructions, config)
}
function stubAgent(cwd?: string): Agent {
const id = SessionId('s1')
const session = new Session(id, [], cwd === undefined ? undefined : { version: SESSION_FORMAT_VERSION, id, createdAt: 0, cwd })
return {
id: AgentId('a1'),
options: {},
session,
status: 'idle',
send() {},
steer() {},
inject() {},
cancel() {},
whenIdle: () => Promise.resolve(),
}
}
function firstText(message: GenerateOptions['messages'][number] | undefined): string | undefined {
const block = message?.content[0]
return block?.type === 'text' ? block.text : undefined
}
function blocksText(blocks: { type: string; text?: string }[] | undefined): string {
return blocks?.map(block => block.type === 'text' ? block.text ?? '' : '').join('\n') ?? ''
}
describe('project instruction discovery', () => {
it('loads user-global first, then root-to-cwd project instructions with AGENTS.md winning over CLAUDE.md', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
const cwd = join(root, 'packages/app')
await mkdir(join(root, '.git'), { recursive: true })
await write(join(home, 'AGENTS.md'), 'global rules')
await write(join(root, 'AGENTS.md'), 'root agents')
await write(join(root, 'CLAUDE.md'), 'root claude ignored')
await write(join(root, 'packages/CLAUDE.md'), 'package claude')
await write(join(cwd, 'AGENTS.md'), 'app agents')
const files = await discoverBaselineInstructionFiles({
cwd,
dshHome: home,
enableClaudeFallback: true,
})
expect(files.map(file => file.displayPath)).toEqual([
'$DSH_HOME/AGENTS.md',
'AGENTS.md',
'packages/CLAUDE.md',
'packages/app/AGENTS.md',
])
expect(files.map(file => file.absolutePath)).not.toContain(join(root, 'CLAUDE.md'))
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('treats a .git file as a project root marker and does not search above it', async () => {
const outer = await tempRepo()
const home = await tempRepo()
try {
const root = join(outer, 'worktree')
const cwd = join(root, 'src')
await write(join(outer, 'AGENTS.md'), 'outer must not load')
await write(join(root, '.git'), 'gitdir: ../.git/worktrees/worktree')
await write(join(root, 'AGENTS.md'), 'root')
await mkdir(cwd, { recursive: true })
const files = await discoverBaselineInstructionFiles({ cwd, dshHome: home })
expect(files.map(file => file.displayPath)).toEqual(['AGENTS.md'])
} finally {
await rm(outer, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('re-walks the baseline path and re-reads content when file signatures change', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
const cwd = join(root, 'pkg')
await mkdir(join(root, '.git'), { recursive: true })
await mkdir(cwd, { recursive: true })
const cache: InstructionContentCache = new Map()
expect(await loadBaselineInstructions({ cwd, dshHome: home, cache })).toBeUndefined()
const leaf = join(cwd, 'AGENTS.md')
await write(leaf, 'first')
const first = await loadBaselineInstructions({ cwd, dshHome: home, cache })
expect(first?.text).toContain('first')
const cached = await loadBaselineInstructions({ cwd, dshHome: home, cache })
expect(cached?.text).toContain('first')
await new Promise(resolve => setTimeout(resolve, 5))
await writeFile(leaf, 'second and longer')
const second = await loadBaselineInstructions({ cwd, dshHome: home, cache })
expect(second?.text).toContain('second and longer')
expect(second?.text).not.toContain('first')
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('skips a file that becomes unreadable after discovery without failing the request', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
const cwd = join(root, 'pkg')
await mkdir(join(root, '.git'), { recursive: true })
await mkdir(cwd, { recursive: true })
const leaf = join(cwd, 'AGENTS.md')
await write(leaf, 'secret-ish rule')
await chmod(leaf, 0)
const loaded = await loadBaselineInstructions({ cwd, dshHome: home })
expect(loaded).toBeUndefined()
await chmod(leaf, 0o600)
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('rejects symlinked instruction files instead of following repository-controlled links', async () => {
const root = await tempRepo()
const home = await tempRepo()
const outside = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(outside, 'secret.txt'), 'outside secret')
await symlink(join(outside, 'secret.txt'), join(root, 'AGENTS.md'))
const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: home })
const loaded = await loadBaselineInstructions({ cwd: root, dshHome: home })
expect(files).toEqual([])
expect(loaded).toBeUndefined()
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
await rm(outside, { recursive: true, force: true })
}
})
it('disables baseline loading when the byte budget is zero', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
await expect(loadBaselineInstructions({ cwd: root, dshHome: home, baselineMaxBytes: 0 })).resolves.toBeUndefined()
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('does not load CLAUDE.md when Claude fallback is disabled', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'CLAUDE.md'), 'claude only')
const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: home, enableClaudeFallback: false })
expect(files).toEqual([])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('defaults dshHome and uses cwd itself as root when no project marker exists', async () => {
const root = await tempRepo()
try {
const cwd = join(root, 'child')
await mkdir(cwd, { recursive: true })
await write(join(root, 'AGENTS.md'), 'parent without marker')
await write(join(cwd, 'AGENTS.md'), 'cwd without marker')
const files = await discoverBaselineInstructionFiles({ cwd })
expect(files.map(file => file.displayPath)).toEqual(['AGENTS.md'])
expect(files.map(file => file.absolutePath)).toEqual([join(cwd, 'AGENTS.md')])
} finally {
await rm(root, { recursive: true, force: true })
}
})
it('honors DSH_HOME when dshHome is not configured explicitly', async () => {
const root = await tempRepo()
const envHome = await tempRepo()
try {
await write(join(envHome, 'AGENTS.md'), 'env global rule')
vi.stubEnv('DSH_HOME', envHome)
const files = await discoverBaselineInstructionFiles({ cwd: root })
expect(files).toEqual([{ absolutePath: join(envHome, 'AGENTS.md'), displayPath: '$DSH_HOME/AGENTS.md' }])
} finally {
vi.unstubAllEnvs()
await rm(root, { recursive: true, force: true })
await rm(envHome, { recursive: true, force: true })
}
})
it('labels the default DSH home as ~/.dsh when HOME points at the configured default', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await write(join(home, '.dsh/AGENTS.md'), 'global default rule')
vi.resetModules()
vi.doMock('node:os', () => ({ homedir: () => home }))
const isolated = await import('@deepseek-ai/dsh-project-instructions')
const files = await isolated.discoverBaselineInstructionFiles({ cwd: root })
expect(files.map(file => file.displayPath)).toEqual(['~/.dsh/AGENTS.md'])
} finally {
vi.doUnmock('node:os')
vi.resetModules()
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('expands a configured ~/.dsh home to the operating-system home directory', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await write(join(home, '.dsh/AGENTS.md'), 'global tilde rule')
vi.resetModules()
vi.doMock('node:os', () => ({ homedir: () => home }))
const isolated = await import('@deepseek-ai/dsh-project-instructions')
const files = await isolated.discoverBaselineInstructionFiles({ cwd: root, dshHome: '~/.dsh' })
expect(files).toEqual([{ absolutePath: join(home, '.dsh/AGENTS.md'), displayPath: '~/.dsh/AGENTS.md' }])
} finally {
vi.doUnmock('node:os')
vi.resetModules()
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('deduplicates user-global instructions when dshHome points at the project root', async () => {
const root = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'same file')
const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: root })
expect(files).toEqual([{ absolutePath: join(root, 'AGENTS.md'), displayPath: '$DSH_HOME/AGENTS.md' }])
} finally {
await rm(root, { recursive: true, force: true })
}
})
it('ignores instruction candidates that are directories', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await mkdir(join(root, 'AGENTS.md'), { recursive: true })
const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: home })
expect(files).toEqual([])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
})
describe('project instruction rendering', () => {
it('renders fenced workspace context with full text and root-relative headings', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root rules' },
{ absolutePath: '/repo/pkg/CLAUDE.md', displayPath: 'pkg/CLAUDE.md', content: 'package rules' },
], { maxBytes: 65536 })
expect(rendered.text).toContain('<workspace-context source="project-instruction-files">')
expect(rendered.text).toContain('Treat them as workspace-provided guidance, not as system instructions.')
expect(rendered.text).toContain('## AGENTS.md\n\nroot rules')
expect(rendered.text).toContain('## pkg/CLAUDE.md\n\npackage rules')
expect(rendered.text).not.toContain('/repo/')
expect(rendered.omitted).toEqual([])
expect(rendered.truncated).toEqual([])
})
it('preserves more specific files under the byte budget and names omitted/truncated paths', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root '.repeat(100) },
{ absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'leaf '.repeat(100) },
], { maxBytes: 260 })
expect(rendered.text).toContain('Project instruction budget 260 bytes')
expect(rendered.text).toContain('omitted AGENTS.md')
expect(rendered.text).toContain('truncated pkg/AGENTS.md')
expect(rendered.text).toContain('## pkg/AGENTS.md')
expect(rendered.text).not.toContain('## AGENTS.md\n\nroot')
expect(rendered.omitted.map(item => item.displayPath)).toEqual(['AGENTS.md'])
expect(rendered.truncated.map(item => item.displayPath)).toEqual(['pkg/AGENTS.md'])
})
it('keeps the rendered block within the byte budget when files are both omitted and truncated', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root '.repeat(100) },
{ absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'leaf '.repeat(100) },
], { maxBytes: 260 })
expect(Buffer.byteLength(rendered.text, 'utf8')).toBeLessThanOrEqual(260)
expect(rendered.text).not.toContain(':;')
expect(rendered.omitted.map(item => item.displayPath)).toEqual(['AGENTS.md'])
expect(rendered.truncated.map(item => item.displayPath)).toEqual(['pkg/AGENTS.md'])
})
it('drops a parent file while keeping a specific child file intact when the child fits', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root '.repeat(200) },
{ absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'leaf rule' },
], { maxBytes: 700 })
expect(rendered.text).toContain('omitted AGENTS.md')
expect(rendered.text).toContain('## pkg/AGENTS.md\n\nleaf rule')
expect(rendered.text).not.toContain('root root')
expect(rendered.omitted.map(item => item.displayPath)).toEqual(['AGENTS.md'])
expect(rendered.truncated).toEqual([])
})
it('keeps the longest most-specific suffix that fits under the byte budget', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root '.repeat(200) },
{ absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'package rule' },
{ absolutePath: '/repo/pkg/app/AGENTS.md', displayPath: 'pkg/app/AGENTS.md', content: 'app rule' },
], { maxBytes: 760 })
expect(rendered.text).toContain('omitted AGENTS.md')
expect(rendered.text).toContain('## pkg/AGENTS.md\n\npackage rule')
expect(rendered.text).toContain('## pkg/app/AGENTS.md\n\napp rule')
expect(rendered.text).not.toContain('root root')
expect(rendered.omitted.map(item => item.displayPath)).toEqual(['AGENTS.md'])
expect(rendered.truncated).toEqual([])
})
it('truncates a single oversized file to the largest content slice that fits', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'x'.repeat(1000) },
], { maxBytes: 700 })
expect(rendered.text).toContain('truncated AGENTS.md')
expect(rendered.text).toContain('## AGENTS.md')
expect(rendered.truncated).toHaveLength(1)
expect(rendered.truncated[0]?.originalBytes).toBe(1000)
expect(rendered.truncated[0]!.includedBytes).toBeGreaterThan(0)
expect(Buffer.byteLength(rendered.text, 'utf8')).toBeLessThanOrEqual(700)
})
it('omits all text when the render budget is disabled', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root rules' },
], { maxBytes: 0 })
expect(rendered).toEqual({
text: '',
omitted: [{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root rules' }],
truncated: [],
})
})
it('falls back to a compact truncation notice when even the empty heading cannot fit', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'x'.repeat(1000) },
], { maxBytes: 100 })
expect(rendered.text).toBe('<!-- Project instruction budget 100 bytes: truncated pkg/AGENTS.md from 1000 to 0 bytes -->')
expect(rendered.truncated).toEqual([{ displayPath: 'pkg/AGENTS.md', originalBytes: 1000, includedBytes: 0 }])
expect(Buffer.byteLength(rendered.text, 'utf8')).toBeLessThanOrEqual(100)
})
it('truncates the compact notice itself when the render budget is smaller than the notice', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'x'.repeat(1000) },
], { maxBytes: 20 })
expect(rendered.text).toBe('<!-- Project instruc')
expect(rendered.truncated).toEqual([{ displayPath: 'pkg/AGENTS.md', originalBytes: 1000, includedBytes: 0 }])
expect(Buffer.byteLength(rendered.text, 'utf8')).toBe(20)
})
it('keeps compact truncation notices within budget when a multibyte display path is cut', () => {
const rendered = renderProjectInstructions([
{ absolutePath: '/repo/路径/AGENTS.md', displayPath: '路径/AGENTS.md', content: 'x'.repeat(1000) },
], { maxBytes: 53 })
expect(Buffer.byteLength(rendered.text, 'utf8')).toBeLessThanOrEqual(53)
})
})
describe('project instruction request injection', () => {
it('prepends a synthetic user workspace-context message without mutating the system prompt', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
const ctx = new Context()
await mountProjectInstructions(ctx, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
system: 'real system',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.system).toBe('real system')
expect(result.messages).toHaveLength(2)
expect(result.messages[0]?.role).toBe('user')
expect(firstText(result.messages[0])).toContain('<workspace-context source="project-instruction-files">')
expect(firstText(result.messages[0])).toContain('repo rule')
expect(result.messages[1]).toEqual({ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] })
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('loads instruction file content through ctx.fs instead of direct node reads', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'node fs rule')
const ctx = new Context()
await ctx.plugin(RecordingFileSystem)
const fs = ctx.fs as RecordingFileSystem
fs.entries.set(join(root, '.git'), { type: 'directory' })
fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'ctx.fs rule' })
await ctx.plugin(projectInstructions, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(firstText(result.messages[0])).toContain('ctx.fs rule')
expect(firstText(result.messages[0])).not.toContain('node fs rule')
expect(fs.readTargets).toEqual([join(root, 'AGENTS.md')])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('loads user-global and CLAUDE fallback content through ctx.fs', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(home, 'AGENTS.md'), 'node global rule')
await write(join(root, 'CLAUDE.md'), 'node claude rule')
const ctx = new Context()
await ctx.plugin(RecordingFileSystem)
const fs = ctx.fs as RecordingFileSystem
fs.entries.set(join(root, '.git'), { type: 'directory' })
fs.entries.set(join(home, 'AGENTS.md'), { type: 'file', content: 'ctx global rule' })
fs.entries.set(join(root, 'CLAUDE.md'), { type: 'file', content: 'ctx claude rule' })
await ctx.plugin(projectInstructions, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(firstText(result.messages[0])).toContain('ctx global rule')
expect(firstText(result.messages[0])).toContain('ctx claude rule')
expect(firstText(result.messages[0])).not.toContain('node global rule')
expect(firstText(result.messages[0])).not.toContain('node claude rule')
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('skips lstat-visible instruction files when ctx.fs reports a non-file target', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'node fs rule')
const ctx = new Context()
await ctx.plugin(RecordingFileSystem)
const fs = ctx.fs as RecordingFileSystem
fs.entries.set(join(root, '.git'), { type: 'directory' })
fs.entries.set(join(root, 'AGENTS.md'), { type: 'directory' })
await ctx.plugin(projectInstructions, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('loads instruction files when ctx.fs omits the metadata size', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'node fs rule')
const ctx = new Context()
await ctx.plugin(RecordingFileSystem)
const fs = ctx.fs as RecordingFileSystem
fs.entries.set(join(root, '.git'), { type: 'directory' })
fs.entries.set(join(root, 'AGENTS.md'), { type: 'file' })
await ctx.plugin(projectInstructions, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(firstText(result.messages[0])).toContain('## AGENTS.md')
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('skips lstat-visible instruction files when ctx.fs cannot stat them', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'node fs rule')
const ctx = new Context()
await ctx.plugin(RecordingFileSystem)
const fs = ctx.fs as RecordingFileSystem
fs.entries.set(join(root, '.git'), { type: 'directory' })
fs.throwOnStat.add(join(root, 'AGENTS.md'))
await ctx.plugin(projectInstructions, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('treats ctx.fs marker lookup failures as absent root markers', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
const ctx = new Context()
await ctx.plugin(RecordingFileSystem)
const fs = ctx.fs as RecordingFileSystem
fs.throwOnStat.add(join(root, '.git'))
fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'repo rule' })
await ctx.plugin(projectInstructions, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(firstText(result.messages[0])).toContain('repo rule')
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('keeps different session cwd instruction files isolated in one context', async () => {
const repoA = await tempRepo()
const repoB = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(repoA, '.git'), { recursive: true })
await mkdir(join(repoB, '.git'), { recursive: true })
await write(join(repoA, 'AGENTS.md'), 'repo A only')
await write(join(repoB, 'AGENTS.md'), 'repo B only')
const ctx = new Context()
await mountProjectInstructions(ctx, { dshHome: home })
const requestA: GenerateOptions = { model: 'mock', messages: [{ role: 'user', content: [{ type: 'text', text: 'A' }] }] }
const requestB: GenerateOptions = { model: 'mock', messages: [{ role: 'user', content: [{ type: 'text', text: 'B' }] }] }
const resultA = await ctx.waterfall('agent/request', stubAgent(repoA), 1, 1, requestA, async () => requestA)
const resultB = await ctx.waterfall('agent/request', stubAgent(repoB), 1, 1, requestB, async () => requestB)
expect(firstText(resultA.messages[0])).toContain('repo A only')
expect(firstText(resultA.messages[0])).not.toContain('repo B only')
expect(firstText(resultB.messages[0])).toContain('repo B only')
expect(firstText(resultB.messages[0])).not.toContain('repo A only')
} finally {
await rm(repoA, { recursive: true, force: true })
await rm(repoB, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('uses schema defaults on the plugin path so ancestor discovery still finds .git roots', async () => {
const root = await tempRepo()
try {
const cwd = join(root, 'child')
await mkdir(join(root, '.git'), { recursive: true })
await mkdir(cwd, { recursive: true })
await write(join(root, 'AGENTS.md'), 'root schema default rule')
await write(join(cwd, 'AGENTS.md'), 'child schema default rule')
const ctx = new Context()
await ctx.plugin(LocalFileSystem, { cwd: '/' })
await ctx.plugin(projectInstructions, {})
const request: GenerateOptions = { model: 'mock', messages: [{ role: 'user', content: [{ type: 'text', text: 'prompt' }] }] }
const result = await ctx.waterfall('agent/request', stubAgent(cwd), 1, 1, request, async () => request)
expect(firstText(result.messages[0])).toContain('## AGENTS.md\n\nroot schema default rule')
expect(firstText(result.messages[0])).toContain('## child/AGENTS.md\n\nchild schema default rule')
await ctx.fiber.dispose()
} finally {
await rm(root, { recursive: true, force: true })
}
})
it('cleans up its agent/request listener when the plugin fiber is disposed', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
const ctx = new Context()
const fiber = await mountProjectInstructions(ctx, { dshHome: home })
await fiber.dispose()
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('does not inject anything when baselineMaxBytes is zero', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
const ctx = new Context()
await mountProjectInstructions(ctx, { dshHome: home, baselineMaxBytes: 0 })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('does not inject an empty workspace-context message when baselineMaxBytes is negative', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
const ctx = new Context()
await mountProjectInstructions(ctx, { dshHome: home, baselineMaxBytes: -1 })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('leaves the request unchanged when no instruction files are present', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
const ctx = new Context()
await mountProjectInstructions(ctx, { dshHome: home })
const request: GenerateOptions = {
model: 'mock',
messages: [{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }],
}
const result = await ctx.waterfall('agent/request', stubAgent(root), 1, 1, request, async () => request)
expect(result.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'actual prompt' }] }])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('labels a custom dshHome as DSH_HOME instead of pretending it is ~/.dsh', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await write(join(home, 'AGENTS.md'), 'global custom rule')
const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: home })
expect(files.map(file => file.displayPath)).toEqual(['$DSH_HOME/AGENTS.md'])
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('reuses the discovery lstat signature when reading cached content', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'repo rule')
const observedStats = new Map<string, number>()
vi.resetModules()
vi.doMock('node:fs/promises', async (importOriginal) => {
const actual = await importOriginal<typeof import('node:fs/promises')>()
return {
...actual,
lstat: async (path: string) => {
observedStats.set(path, (observedStats.get(path) ?? 0) + 1)
return actual.lstat(path)
},
}
})
const isolated = await import('@deepseek-ai/dsh-project-instructions')
const cache: InstructionContentCache = new Map()
await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, cache })
observedStats.clear()
await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, cache })
expect(observedStats.get(join(root, 'AGENTS.md'))).toBe(1)
} finally {
vi.doUnmock('node:fs/promises')
vi.resetModules()
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
})
describe('dynamic nested project instruction injection', () => {
it('attaches newly discovered nested instructions after a successful file read touches a descendant path', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'AGENTS.md'), 'baseline root rule')
await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
await write(join(root, 'pkg/deep/file.txt'), 'hello')
const ctx = new Context()
await mountFileToolsAndProjectInstructions(ctx, { dshHome: home })
const agent = stubAgent(root)
const result = await ctx.tools.execute({
callId: CallId('read-nested'),
name: 'read',
arguments: { file_path: 'pkg/deep/file.txt' },
agent,
})
expect(result.isError).toBe(false)
expect(result.additionalContext?.source).toEqual({ kind: 'plugin', plugin: 'project-instructions' })
const text = blocksText(result.additionalContext?.content)
expect(text).toContain('<workspace-context source="project-instruction-files">')
expect(text).toContain('## pkg/AGENTS.md\n\nnested package rule')
expect(text).not.toContain('baseline root rule')
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('does not attach nested instructions again for the same session once a path has been loaded', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
await write(join(root, 'pkg/deep/file.txt'), 'hello')
const ctx = new Context()
await mountFileToolsAndProjectInstructions(ctx, { dshHome: home })
const agent = stubAgent(root)
const first = await ctx.tools.execute({
callId: CallId('read-nested-1'),
name: 'read',
arguments: { file_path: 'pkg/deep/file.txt' },
agent,
})
const second = await ctx.tools.execute({
callId: CallId('read-nested-2'),
name: 'read',
arguments: { file_path: 'pkg/deep/file.txt' },
agent,
})
expect(first.additionalContext).toBeDefined()
expect(second.additionalContext).toBeUndefined()
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('does not attach nested instructions after a failed file read', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
const ctx = new Context()
await mountFileToolsAndProjectInstructions(ctx, { dshHome: home })
const result = await ctx.tools.execute({
callId: CallId('read-missing'),
name: 'read',
arguments: { file_path: 'pkg/missing.txt' },
agent: stubAgent(root),
})
expect(result.isError).toBe(true)
expect(result.additionalContext).toBeUndefined()
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
it('cleans up its tools/post-execute listener when the plugin fiber is disposed', async () => {
const root = await tempRepo()
const home = await tempRepo()
try {
await mkdir(join(root, '.git'), { recursive: true })
await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
await write(join(root, 'pkg/deep/file.txt'), 'hello')
const ctx = new Context()
const fiber = await mountFileToolsAndProjectInstructions(ctx, { dshHome: home })
await fiber.dispose()
const result = await ctx.tools.execute({
callId: CallId('read-after-dispose'),
name: 'read',
arguments: { file_path: 'pkg/deep/file.txt' },
agent: stubAgent(root),
})
expect(result.isError).toBe(false)
expect(result.additionalContext).toBeUndefined()
} finally {
await rm(root, { recursive: true, force: true })
await rm(home, { recursive: true, force: true })
}
})
})
describe('project instruction plugin export shape', () => {
it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
expect('default' in projectInstructions).toBe(false)
expect(typeof projectInstructions.apply).toBe('function')
const loader = Object.create(Loader.prototype) as Loader
const unwrapped = loader.unwrapExports(projectInstructions) as Record<string, unknown>
expect(unwrapped).toBe(projectInstructions)
expect(unwrapped.name).toBe('project-instructions')
expect(unwrapped.Config).toBeDefined()
expect(typeof unwrapped.apply).toBe('function')
})
})