DSH plugin remote candidates: take mention as-is
In DSH plugin, a browser cannot hold a local agent, so candidates must come from the remote outlet — and every candidate it returns carries a mention. The client inserts it; it does not compose one. Hand-building mentions is the most common rework in this integration.
DeepSeek Harness: Where the mention comes from
From the candidate response, not from the session title. (source) A typical broken implementation:
// wrong: hand-built
const mention = `@[${candidate.label}](dsh-session:${candidate.sessionId})`
That breaks whenever a title contains ], (, a space, or an emoji. The correct approach takes the field the service already returned:
const mention = candidate.mention
The difference is not line count but ownership of serialization. Serialization belongs to the session reference contract, not to a UI.
DeepSeek Harness: What the candidates method returns
A candidate plus one mention; every other field is unchanged. (source) Structure:
| Field | Meaning |
|---|---|
sessionId | Opaque identity |
label | Title or id fallback |
displayTitle | Subagent creation label, optional |
cwd | Working directory, optional |
sameWorkspace | Whether it matches the requester's directory |
createdAt | Creation time |
mention | Canonical mention text, remote-only |
The method is sessionReferenceResolver/candidates, built for consumers such as browsers that cannot hold a local agent.
Note that the mention uses displayTitle as its label when one exists, so it does not always equal label.
DeepSeek Harness: Why the service must generate it
Three reasons: escaping, encoding, and consistency. (source) Breaking them down:
- Escaping — the label sits inside
@[...], so brackets and parentheses need handling; - Encoding — the URI portion must follow the encoding rules, which hand-building often misses;
- Consistency — the same candidate should produce the same text on web, desktop, and terminal.
The third is underestimated: if each client builds its own text, copying a mention from one to another can parse differently.
Generating on the service side keeps all three in one place; the client only inserts.
DeepSeek Harness: Who owns the limit
The service, and the frontend should not truncate again. (source) Rules:
- The remote method applies the configured candidate limit;
- The returned count is already bounded, so render it as-is;
- If fewer rows should be visible, collapse or paginate in the UI rather than discarding data.
Double truncation makes two numbers disagree: configuration says 20, the UI shows 5, and nobody can tell who cut it.
If a product wants "show only five", that is a display policy for the render layer, keeping the full data for an expand action.
DeepSeek Harness: Four steps from candidate to draft
Four steps; none of them may rewrite the mention. (source) Steps:
- The user types
@and the client calls remote candidates; - Render the list using
displayTitleorlabel; - On selection, insert
mentionverbatim into the draft; - On submit, pass the selected
sessionIdas the reference input.
"Verbatim" in step 3 is literal: no trim, no space replacement, no re-encoding.
Step 4 shows that the mention is only draft text while the real identity remains sessionId. Keeping them separate lets users read the draft and lets prepare resolve it precisely.
DeepSeek Harness: End-to-end verification
Four assertions cover fields, escaping, the cap, and resolution. (source) Steps:
- Call the remote method and confirm every candidate has
mention; - Pick a session whose title contains
]and confirm the inserted mention keeps valid syntax; - Confirm the result count does not exceed the configured limit;
- Submit a draft containing the mention and confirm prepare resolves the same
sessionId.
Step 4 closes the loop: if the first three pass but the resolved id differs, something rewrote the text in the frontend.
With the remote outlet working, the next topic is mention syntax. Read how DSH plugin parses a dsh-session URI; for special characters in labels, read DSH plugin session label escaping; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/index.ts
FAQ
The mention comes from each candidate returned by the DSH plugin remote method, not from the session title. DSH plugin attaches a canonical mention per candidate so the client inserts it instead of serializing one.
Because labels can contain brackets, parentheses, spaces, or emoji, which DSH plugin handles during serialization. DSH plugin's service handles escaping, URI encoding, and cross-client consistency in one place.
No, DSH plugin uses displayTitle for the mention when it exists. The inserted text can therefore differ from the label shown in the list.
No, the DSH plugin remote method already applies the candidate limit. Trim the view with collapse or paging while keeping the data, rather than discarding rows twice.
Related Terms
- mention
- mention is the canonical insertable text for a session candidate, provided by the remote method and parsed by prepare.— DeepSeek Harness reference - Session references
- sessionReferenceResolver/candidates
- sessionReferenceResolver/candidates is the remote method serving clients that cannot hold a local agent.— session-reference/src/index.ts
- displayTitle
- displayTitle is the subagent creation label and, when present, the label used inside the mention.— DeepSeek Harness reference - Session references
- candidate limit
- The candidate limit is the configured maximum number of results a remote candidates call returns.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/index.ts· deepseek-ai