dsh-referenced-file

Adds # workspace-file references to the DeepSeek Harness (DSH) composer. Typing # opens file candidates from the current session workspace. A pick inserts the explicit marker #<relative/path>. At submission time, the Host resolves and reads the file again and adds that UTF-8 text snapshot to the current model request.

Install

This installable bundle contains both Host and Web Client halves:

dsh plugin --profile web add /path/to/dsh-referenced-file

Or install a packed artifact:

npm pack
dsh plugin --profile web add ./dsh-referenced-file-0.1.0.tgz

From a DSH source checkout, prefix runtime commands with pnpm:

pnpm dsh plugin --profile web add /path/to/dsh-referenced-file
pnpm dsh --profile web --dump-config
pnpm dsh --profile web

Directory/Git installation receives source and runs prepare to produce lib/ and host/lib/. If the profile's pnpm blocks build scripts, allow dsh-referenced-file in that profile's pnpm-workspace.yaml allowBuilds map. npm tarballs already contain the build output.

Use

1. Type # in a session with a workspace and continue typing path fragments to narrow the match set. The menu shows at most 20 items ordered by modification time, newest first.
2. Move with Arrow keys and pick with Enter or Tab, or click a row. Escape closes the menu.
3. A pick becomes #<src/example.ts>. The encoding also handles spaces, >, and backslashes unambiguously.
4. The Host reads the file on send. A deleted file, directory, binary, oversized file, or outside-workspace target in an explicit marker fails the request with a reason.

A bare #topic is a convenience file reference only when it resolves to an existing workspace file; otherwise it stays ordinary text. Markdown headings beginning with # are not references. The Web menu always inserts explicit #<...> markers.

Design and security boundary

• # is unused in the target DSH checkout (commit 47f943859bef60e4160492346772ded9b24f765a). The built-in input-trigger public implementation still restricts its trigger character to / | @, so this plugin implements # detection and its menu through the public conversation.input.overlay slot without changing DSH core. A selected reference remains plain composer text rather than a native //@ trigger chip.
• The browser receives only workspace-relative paths and optional file sizes, never contents or modification times. The Host uses DSH's filesystem service and checks canonical containment during both traversal and submission; symlinks resolving outside the workspace do not pass.
• Contents are read only in agent/pre-step, just before a model request enters, then inserted after the direct user prompt as a referenced-file plugin snapshot. The snapshot labels file text as untrusted workspace data, not higher-priority instructions.
• Only regular UTF-8 text files are supported. NUL-containing data, invalid UTF-8, directories, and special files are rejected. Use DSH's attachment flow for images and other binary data.
• The Host keeps a bounded, non-persistent path index per canonical workspace. The first query builds it once; later keystrokes search memory, and an expired index refreshes in the background with stale-while-revalidate. Unload/HMR cancels refreshes and clears indexes. No watcher is created and no contents enter logs, caches, or the wire.
• Modification time is read best-effort through the filesystem service's public processPath() coordinate. A remote or non-shared execution world that has no Host-readable mtime still supports path search and falls back deterministically to path ordering. Submission always resolves and reads again, so a briefly stale candidate index does not weaken the read boundary.

Configuration

The Host Loader entry id is referenced-file. Its schema defaults are below. When overriding that entry's config, specify the complete config because later DSH patch layers replace an entry's config rather than deep-merging it.

Field	Default	Purpose
maxCandidates	20	Maximum candidates returned by one query; the schema hard cap is also 20
maxScannedEntries	5000	Maximum directory entries inspected per index refresh
maxDepth	12	Maximum candidate traversal depth
maxReferences	8	Maximum referenced files in one direct prompt batch
maxFileBytes	131072	Per-file byte limit
maxTotalBytes	524288	Combined reference byte limit
excludeDirectories	.git, .cache, .next, .turbo, build, coverage, dist, node_modules	Directory basenames omitted from candidate traversal
indexTtlMs	30000	Age at which a workspace candidate index refreshes in the background
maxCachedWorkspaces	8	Maximum in-memory workspace indexes retained by the Host

Develop and verify

npm install --legacy-peer-deps
npm run typecheck
npm test
npm run build
npm pack --dry-run

TypeScript config reads current public declarations from the fixed sibling checkout at D:\work\workspace\github\deepseek-harness. Runtime code still imports only public package exports and does not depend on sibling source paths.