DSH plugin candidate ranking: cwd affinity, self, and limit
Candidate ordering is not "newest first" but "closest to the current working directory first": DSH plugin ranks by cwd affinity, excludes the requesting session, and caps results with candidateLimit. Any sorting a host adds beyond those three rules moves results away from the contract.
DeepSeek Harness: The current session shows up in its own list
Suspect the agent before suspecting the sort. (source) Scene:
current session A, typing @
candidate list contains A
The official note on listCandidates is explicit: self is excluded, and its cwd participates in ordering. In other words, exclusion is decided by the requesting agent.
If the current session appears, the usual cause is a host requesting with a generic agent instead of the one tied to this session. Wrong identity, no exclusion.
The other possibility is caching: a result fetched earlier with a different agent was never invalidated and got reused.
DeepSeek Harness: Which layer excludes self
Inside the resolver, not in the frontend. (source) Division:
| Layer | Responsible for self exclusion |
|---|---|
listCandidates(agent, …) | Yes |
Remote candidates | Yes, inherits the resolver |
| Host frontend | No, and should not duplicate it |
A second frontend filter feels safer but hides identity bugs: the real defect stays concealed and reappears through another entry point.
The diagnostic is simple: call the resolver directly and check whether self is present. If it is absent there, the frontend is not holding the agent you think it is.
DeepSeek Harness: What cwd affinity ordering means
Same directory first, then other directories; ties do not promise "most recently used". (source) Three points:
- Ordering is based on working directory relationship, not time;
createdAtrecords creation time and plays no part in affinity;- Sessions without cwd still appear, but cannot enter the same-directory tier.
This explains a familiar puzzle: a session used moments ago ranks lower because its directory differs from the current one.
If a product wants "recently used", that is a separate ordering dimension and cannot be produced by rewriting candidate order.
DeepSeek Harness: The limit boundary
limit is a positive upper bound; omit it and the configured value applies. (source) Rules:
- The signature is
listCandidates(agent, query, limit, signal); limitis optional but must be positive when supplied;- When omitted, the configured
candidateLimitapplies; - Remote methods inherit the configured cap, so hosts should not truncate again.
Two mistakes are common: passing 0 to mean "unlimited", or passing a huge number to "get everything". The first is invalid; the second makes keystroke-rate requests heavy.
Pass the number of rows the UI can actually show; that is the steadiest choice.
DeepSeek Harness: Why hosts should not sort again
Because ordering is a contract, not a suggestion. (source) Three consequences:
| Second sort | Consequence |
|---|---|
| Re-sort by time | Same-directory priority disappears |
| Re-sort by name | Users lose position memory |
| Re-sort by random weight | The same query becomes unstable |
The third is worst: the list jumps during typing and the row a user was about to click moves away.
If another order is genuinely needed, add an explicit ordering dimension with its own contract instead of overriding it in the frontend.
DeepSeek Harness: Verifying ranking
Four assertions cover exclusion, affinity, the cap, and stability. Steps:
- Request with the current session's agent and confirm self is absent;
- Create same-directory and other-directory sessions and confirm same-directory ranks first;
- Pass
limit=3and confirm at most three results; - Request the same query twice and confirm identical order.
For step 2, check the relative order of the whole group, not just the first row. Step 4 is a stability assertion; failures usually mean time or randomness leaked into ordering.
One more cap detail: limit must be positive. Reading 0 as "unlimited" lets callers accidentally pull everything, and ranking loses meaning.
If a host needs a "recently used" view, build a separate index rather than reusing the candidate ranking rules.
Ordering settled, presentation is next. Read DSH plugin session candidate names; for the remote mention outlet, read DSH plugin remote candidates; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/index.ts
FAQ
Most likely the host requested with a generic agent or reused a cached result, which bypasses DSH plugin self exclusion. DSH plugin excludes self based on the requesting agent.
No, DSH plugin ranks by cwd affinity rather than recency. Ordering follows cwd affinity, so same-directory sessions come first. createdAt records creation time and does not drive affinity, which is why a recently used session can still rank low.
DSH plugin expects a positive integer for limit. When omitted, the configured candidateLimit applies. Zero is not a way to say unlimited, and passing a huge value makes keystroke-rate requests expensive.
No, ordering is part of the DSH plugin contract. Ordering is part of the contract; a second sort invalidates affinity, breaks position memory, and can make the same query unstable between keystrokes.
Related Terms
- cwd affinity
- cwd affinity ranks candidates whose working directory matches the requester ahead of others.— DeepSeek Harness reference - Session references
- self exclusion
- Self exclusion removes the requesting session from its own candidate list based on the agent passed to listCandidates.— session-reference/src/index.ts
- candidateLimit
- candidateLimit is the configured upper bound used when a caller omits limit.— DeepSeek Harness reference - Session references
- createdAt
- createdAt is the session creation timestamp carried on candidates; it does not participate in affinity ordering.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/index.ts· deepseek-ai