DSH plugin composed providers: order, namespaces, dedupe
In DSH plugin, with a workspace, plugins, and a remote each offering files, the question stops being "does it exist" and becomes "who ranks first, how do duplicates differ, whose duplicate is it" — all three belong to the composed provider, not the host. The earlier a frontend takes over merging, the more the list drifts with paging and concurrency.
Two README files at once in DSH plugin
Identical paths are not bad data; they are a namespace decision the composition layer has not made yet. (source) A typical scene:
README.md <- workspace source
docs/README.md <- docs source
plugin/README.md <- plugin source
All three can supply the relative path README.md, yet they mean different things to a user. If the composition layer simply concatenates, the user sees three identical rows and picking one becomes luck.
The point is not dedupe but "distinguish, then merge": namespaces separate, and dedupe happens only inside one namespace.
A counterexample shows why timing matters. If a user sees three identical README entries and discovers only after selecting that the reference points into the plugin directory, the distinction arrived too late — selection had already become a guess.
DeepSeek Harness: What the composed provider is (and is not)
It is the implementation behind the remote adapter, not another public interface. (source) Layers:
| Layer | Responsibility |
|---|---|
ctx.sessionFileReferences | Remote outlet; resolves the agent from Session identity |
| composed provider | Merges sources; ordering, namespaces, dedupe |
| source providers | List paths within their own scope |
Externally there is only list(agent, query, signal); composition happens inside. The host cannot see how many sources exist, and should not.
The payoff: adding a source requires no host change, and a misbehaving source only affects its own portion of candidates.
It is also worth isolating source failures: when one source cannot be read, return candidates from the others and record the error instead of emptying the whole list.
DeepSeek Harness: Why ordering must stay in the provider
Because only the composition layer sees all sources at once. (source) Three reasons:
- Cross-source comparison — a frontend only receives the merged list and cannot tell which source a row came from, so it cannot apply source priority.
- Stability — composition can fix source order; a second frontend sort destroys it.
- Consistency — the same query should yield the same order across hosts and clients, which requires a single ordering implementation.
A practical smell test: if sorting code mentions the current time, randomness, or Map iteration order, it does not belong in the candidate pipeline.
DeepSeek Harness: How namespaces and dedupe divide the work
Namespaces come first; dedupe only applies within one namespace. (source) A workable split:
- Namespaces make same-named paths from different sources distinguishable, for example with a source prefix or grouping;
- Dedupe runs inside one namespace so different sources'
README.mdfiles are not treated as duplicates; - The presentation layer does not merge; it renders in the order the provider returned.
Do it the other way around and source information disappears; after selecting, the user cannot tell which file was referenced.
This matters most for plugin authors: when adding a source, declare its namespace before deciding whether it merges with existing sources.
DeepSeek Harness: Determinism gets harder with composition
More sources mean more unstable inputs. (source) Three common ones:
| Unstable input | Symptom | Handling |
|---|---|---|
| Concurrent arrival order | Different merge order each time | Fixed source order, merge per source |
| Filesystem traversal order | Random order inside a directory | Sort before merging |
| Paging or truncation | Dedupe results change per batch | Truncate after merging |
The third is the most subtle: dedupe before truncation lets batch one and batch two disagree, so scrolling down reveals duplicates.
The correct sequence is "collect fully per source → merge → dedupe → order → truncate". Truncation comes last so prefixes remain stable.
Dedupe keys also need one definition: raw path or normalized path must be decided once by the composition layer, never per source.
DeepSeek Harness: Self-testing the composed layer
Four assertions cover merging, distinction, stability, and truncation. Steps:
- Give two sources a
README.mdeach and confirm candidates distinguish them. - Request the same query twice and confirm identical order and content.
- Reverse the order sources return in and confirm the merged result is unchanged.
- Lower the limit and confirm truncation happens after merging with a stable prefix.
Step three exposes implementation problems best: if reversing arrival order changes the result, composition depends on it.
Read steps two and three together: a single stable call does not prove independence from arrival order.
Once composition is stable, wire the host. Read choosing between the two file reference services; for scope boundaries, read the DSH plugin cwd boundary; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, file-reference/src/index.ts
FAQ
DSH plugin lets the composed provider's namespace rules decide, not a random frontend pick. Ordering and namespace access belong to providers, so duplicates are settled at the composition layer.
No, they are different layers in DSH plugin. The remote adapter is the outward outlet for session file references; the composed provider is the implementation behind it. The adapter resolves agent identity, while composition merges sources into one deterministic candidate list.
Frontend dedupe looks faster in DSH plugin but only sees the current page. DSH plugin candidates must stay consistent across sources and batches; only the composition layer sees every source at once, so dedupe does not shift with paging or truncation.
DSH plugin order changes usually because the composition layer depends on something unstable, such as concurrent arrival order, mtime, or hash iteration. DSH plugin requires deterministic candidates, so composition needs a fixed source priority and a stable merge.
Related Terms
- composed provider
- A composed provider merges multiple file reference sources into one candidate list and owns ordering and namespace access.— DeepSeek Harness reference - Session references
- namespace
- A namespace is the path scope a provider assigns to a source, used to distinguish identical paths and decide presentation.— DeepSeek Harness reference - Session references
- source priority
- Source priority is the fixed order the composition layer assigns to each provider, keeping merged results predictable.— DeepSeek Harness reference - Session references
- deterministic candidates
- Deterministic candidates return the same set in the same order for the same query in the same environment, enabling caching and testing.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- file-reference/src/index.ts· deepseek-ai