DSH plugin file completion: directory keeps, file closes
DSH plugin file completion is a two-state machine: selecting a directory enters "keep expanding", selecting a file enters "mention complete". A host that infers state from the string alone will keep tripping over directories, trailing slashes, and same-named files.
The two-state machine behind DSH plugin completion
Treating a pick as a state transition is more accurate than treating it as text insertion. (source) Transitions:
| State | Selection | Next state | Input |
|---|---|---|---|
| Expanding | directory | Expanding | Keep prefix, request candidates again |
| Expanding | file | Complete | One finished mention |
| Complete | anything | Complete | Wait for submit or normal text |
The official comment on kind is one sentence: a directory keeps completion open, a file ends the mention. That sentence is the whole state machine; no extra rules are needed.
The benefit is that hosts do not need filesystem knowledge. They answer one question: after this pick, do we request candidates again?
Conversely, the complete state does not lock the user out; it only means this mention is whole. They can keep typing normal text or delete and start over.
DeepSeek Harness: Why a directory candidate must not be inserted as a file
Inserting a directory as a file ends the mention early and removes the way down. (source) The symptom is familiar: type @packages, pick the directory, and the input collapses to @packages with the list closed — so reaching packages/web means typing everything again.
The correct behavior keeps an expandable form such as @packages/ and immediately requests candidates with the new query. The separator comes from the candidate path; the host does not add it.
Directories are usually far fewer than files. If files bury the directories, descending becomes hard — that is a provider ordering problem, not something a frontend should fix by filtering.
Rendering may still distinguish directories with icons or suffixes, as long as it does not change the meaning of path and kind. What the user sees and what gets inserted are separate concerns.
Who owns path joining in DSH plugin
Candidates supply the path; joining belongs to the provider, not the host. (source) This rule prevents three classes of bugs:
- A host appending
/creates paths that do not exist on Windows or in names with spaces. - A host rewriting relative paths into absolute ones makes later tool calls disagree with the discovery boundary.
- A host URL-encoding the path renders fine but fails to parse.
The definition of path — user-visible and accepted by prompts and filesystem tools — means it is already final. The host inserts it verbatim.
If shorter relative paths are desirable for display, that is a pure presentation concern: keep the original value as the submitted one and never replace it with the display variant.
Symlinks are another edge: the same path can point at a directory or a file. Do not probe; follow the candidate's kind, because a probe may disagree with discovery.
DeepSeek Harness: What determinism buys file completion
The same query must produce the same order, or the list jumps while typing. (source) Determinism pays off three ways:
- Users can rely on position memory instead of rescanning the list;
- Hosts can cache the previous result safely;
- Tests can assert the full output rather than "contains this path".
The usual way to break it is a frontend re-sort by modification time, file size, or random weights. Those sorts look smarter but make identical queries return different orders between keystrokes.
If ordering must change, the right place is the provider — and the result must still be deterministic.
Caching also needs a boundary: the key must include the query and the agent's cwd. Without cwd, switching the working directory hits stale results from the previous level and looks like "candidates never refresh".
Three broken DSH plugin implementations
Three reproducible mistakes, one per layer: state, path, ordering. (source) Comparison:
| Broken implementation | Symptom | Root cause |
|---|---|---|
Deciding directories by path.endsWith('/') | A directory without a slash is treated as a file | kind ignored |
Appending / after selection | Double slashes or wrong separators | Host overrides provider joining |
| Re-sorting candidates by mtime | Order differs between calls | Determinism broken |
None of these need source access to reproduce: type the same prefix twice and compare the results.
The repair order is equally simple: honor kind, stop joining paths, remove the second sort.
How to self-test DSH plugin completion
Five actions cover the main branches of the state machine. Steps:
- Type an existing directory name, select it, and confirm the list stays open.
- In the expanding state, type a subdirectory name and confirm candidates narrow.
- Select a file and confirm the list closes with a complete mention.
- Request the same prefix twice and confirm identical order.
- Change the working directory, retype the same prefix, and confirm candidates follow.
If step 1 fails, check whether kind is being dropped; if step 4 fails, look for a second sort.
Step 5 tests the cache key, where most "candidates are stale" reports originate.
Completion is only the entry point. To see why candidates carry just a path, read DSH plugin file reference candidates; to handle input with spaces, read how the file reference query works; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, file-reference types.ts
FAQ
That is the DSH plugin contract, not a bug. DSH plugin uses kind to decide completion state: a directory exists precisely to keep the list open so the user can descend one more level, and only a file ends the mention.
A host should not detect directories itself when DSH plugin already supplies kind. The candidate already supplies kind; probing again adds a filesystem call and can disagree because of permissions or symlinks, leaving completion state out of sync with the candidate.
The DSH plugin candidate path is final, whatever the provider returns. The path is user-visible and accepted by prompts and filesystem tools, so the host inserts it as-is and never adds separators or rewrites levels.
That is DSH plugin determinism, not a stale cache. DSH plugin returns the same set in the same order for the same query in the same environment; content changes appear through a new query.
Related Terms
- kind
- kind is the candidate type field, either file or directory, and decides whether completion continues.— DeepSeek Harness reference - Session references
- completion state machine
- The completion state machine is the host interaction model with two states: directory enters expansion, file enters wrap-up.— DeepSeek Harness reference - Session references
- namespace
- A namespace is the path scope a provider assigns to each file source so identical paths from different sources do not collide.— DeepSeek Harness reference - Session references
- determinism
- Determinism means the same input in the same environment yields the same result set in the same order, which makes candidates cacheable and testable.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- file-reference types.ts· deepseek-ai