DSH plugin file refs: abstraction seam vs remote adapter
In DSH plugin, similar names do not imply similar jobs: ctx.fileReferences is the abstraction seam plugin authors implement, while ctx.sessionFileReferences is the remote outlet hosts consume. Wire the wrong one and you get either an implementation nobody can reach or a UI with nothing behind it.
Two DSH plugin services with similar names
Look at the definition first, then at the caller. (source) Comparison:
| Service | Official description | Who uses it |
|---|---|---|
ctx.fileReferences | Cancellable file reference discovery; the abstraction seam | Provider authors |
ctx.sessionFileReferences | Host remote adapter above the composed provider | Hosts and remote consumers |
Both list signatures look identical: agent, query, signal. What differs is where the agent comes from and what sits behind it.
The seam receives the agent directly from its caller; the remote adapter resolves the agent from the live Session identity. That single difference makes them non-interchangeable.
A common misreading is "the seam is lower level, therefore more advanced". They actually point in different directions: one offers a capability upward, the other exposes it outward. Neither outranks the other.
DeepSeek Harness: What the abstraction seam solves
It turns file discovery into a replaceable capability instead of hard-coding one implementation. (source) Three benefits:
- Replaceable — a workspace, a plugin, and a remote source can each implement it and be merged by the composition layer.
- Testable — a test can inject a provider with fixed output and avoid the real filesystem.
- Constrainable — the interface only asks for path and kind, so implementations struggle to smuggle in content reads.
When implementing the seam, two rules matter most: no content reads, and determinism. They are not style advice; they are what let candidates be cached and called repeatedly.
The seam's return value carries no source identifier, because source distinction belongs to composition. An implementation that quietly adds such a field captures every host that adopts it.
DeepSeek Harness: What the remote adapter adds
It adds exactly one thing: translating live identity into an agent. (source) The flow has three steps:
- A request arrives carrying Session identity;
- The adapter resolves the corresponding agent;
- It calls the composed provider's
listwith that agent's cwd.
Beyond that it changes neither the query nor the candidate shape. The result is still deterministic candidates containing only paths.
This explains why remote consumers should not invent an agent: once identity disagrees with the real session, cwd is wrong, and candidates look like they are "missing files" when the scope is simply wrong.
The adapter also forwards cancellation. If it swallows the signal, an upstream stop leaves the provider scanning.
DeepSeek Harness: Three wiring options by role
Choose by role, not by name similarity. (source) Comparison:
| Your role | Wire this | Why |
|---|---|---|
| Plugin author adding a file source | ctx.fileReferences | You implement discovery |
| Host frontend rendering completion | ctx.sessionFileReferences | You need identity-to-agent resolution |
| Test or local tool with an agent | Either; prefer the seam | No live identity involved |
If you do both jobs, wire both: one implements sources, the other exposes an outlet. Missing one breaks the chain.
Organizationally, keep both wirings in one module. Otherwise the implementation and the outlet evolve separately until their parameters stop matching.
DeepSeek Harness: Why mention syntax stays out of the core
UI mention syntax belongs to hosts, not to the agent core. (source) The overview states it plainly: host adapters use these types and do not pass their own mention syntax into the core.
Three reasons:
- Different hosts use different mention syntax, and pushing one into the core lets a single UI capture it;
- Syntax changes over time, while the core contract should not;
- The core needs only paths and kinds; parsing syntax is a host concern.
That is why list takes path text rather than a full @[...] string. Pass the whole mention and the provider treats it as a path, which matches nothing.
If a host supports several mention forms, parse before submit and hand only the path text to list; the syntax layer never enters the core.
DeepSeek Harness: Verifying the wiring
Run the same query through both entry points and compare. Steps:
- Prepare a fixed directory, a fixed query, and a fixed cwd.
- Call the seam directly and record the path set and order.
- Call the same query through the remote outlet and record the result.
- Compare the two.
- Cancel one request and confirm both entry points stop.
Step 1 sets the baseline: without a fixed cwd, the two calls may land in different directories and the comparison means nothing.
If step 4 differs, check whether the remote side resolved the wrong agent; if step 5 fails, check whether the adapter dropped the signal.
With wiring done, the next topics are ordering and presentation. Read composing DSH plugin providers; for input parsing, read how the DSH plugin file reference query works; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-controller file-references.ts
FAQ
The answer depends on your role in DSH plugin. DSH plugin uses ctx.fileReferences to implement providers and ctx.sessionFileReferences for hosts that consume completion. Wiring one will not error, but you end up with either no source or no outlet.
The DSH plugin remote adapter performs identity resolution first. The remote outlet resolves an agent from the live Session identity, then uses that agent's cwd to bound discovery; the query is just a later parameter.
Technically yes, but you lose DSH plugin's live-identity-to-agent mapping. Browser or remote consumers have no local agent object, so bypassing the adapter usually means inventing an identity that disagrees with the real session.
A DSH plugin seam should return deterministic candidates containing only paths. DSH plugin does not forbid caching inside a provider, but a cache may not change ordering for the same query or make cancellation ineffective.
Related Terms
- abstraction seam
- An abstraction seam defines a capability without binding an implementation; DSH plugin uses it so different providers share one discovery surface.— DeepSeek Harness reference - Session references
- remote adapter
- The remote adapter is the outlet for remote consumers; it resolves the live Session identity into an agent and calls the composed provider.— session-controller file-references.ts
- provider
- A provider supplies file references within its own scope and guarantees deterministic ordering.— DeepSeek Harness reference - Session references
- agent resolution
- Agent resolution is how the remote layer finds the target agent from the Session identity on a request, which then fixes the cwd scope.— session-controller file-references.ts
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-controller file-references.ts· deepseek-ai