ChatGPTClaudeGrok / X / CursorGemini

DSH plugin candidate ranking: cwd affinity, self, and limit

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referencerankinglimit
Results are ordered by cwd affinity, exclude the requesting session, and stop at a positive limit. A host's extra sort breaks all three.

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:

text
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:

LayerResponsible for self exclusion
listCandidates(agent, …)Yes
Remote candidatesYes, inherits the resolver
Host frontendNo, 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:

  1. Ordering is based on working directory relationship, not time;
  2. createdAt records creation time and plays no part in affinity;
  3. 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);
  • limit is optional but must be positive when supplied;
  • When omitted, the configured candidateLimit applies;
  • 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 sortConsequence
Re-sort by timeSame-directory priority disappears
Re-sort by nameUsers lose position memory
Re-sort by random weightThe 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:

  1. Request with the current session's agent and confirm self is absent;
  2. Create same-directory and other-directory sessions and confirm same-directory ranks first;
  3. Pass limit=3 and confirm at most three results;
  4. 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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, why does the current session appear in its own candidate list?

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.

Does DSH plugin rank candidates by recency?

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.

What values are valid for limit in DSH plugin?

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.

In DSH plugin, should a host sort candidates again for its own UI?

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