ChatGPTClaudeGrok / X / CursorGemini

DSH plugin file completion: directory keeps, file closes

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessfile referencecompletionkind
kind is not decorative: a directory keeps completion open, a file ends the mention. A state-machine view, path ownership, and three broken implementations.

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:

StateSelectionNext stateInput
ExpandingdirectoryExpandingKeep prefix, request candidates again
ExpandingfileCompleteOne finished mention
CompleteanythingCompleteWait 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:

  1. A host appending / creates paths that do not exist on Windows or in names with spaces.
  2. A host rewriting relative paths into absolute ones makes later tool calls disagree with the discovery boundary.
  3. 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 implementationSymptomRoot cause
Deciding directories by path.endsWith('/')A directory without a slash is treated as a filekind ignored
Appending / after selectionDouble slashes or wrong separatorsHost overrides provider joining
Re-sorting candidates by mtimeOrder differs between callsDeterminism 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:

  1. Type an existing directory name, select it, and confirm the list stays open.
  2. In the expanding state, type a subdirectory name and confirm candidates narrow.
  3. Select a file and confirm the list closes with a complete mention.
  4. Request the same prefix twice and confirm identical order.
  5. 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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why does DSH plugin keep the completion list open after I pick a directory?

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.

For DSH plugin, can a host detect directories itself instead of trusting kind?

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.

Does the DSH plugin candidate path include a trailing separator?

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.

Why do DSH plugin candidates look identical on repeated queries?

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