ChatGPTClaudeGrok / X / CursorGemini

DSH plugin remote candidates: take mention as-is

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referenceremotemention
Browser clients cannot hold a local agent, so candidates come from a remote outlet that also returns a ready mention. Insert it; do not rebuild it.

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:

ts
// 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:

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

FieldMeaning
sessionIdOpaque identity
labelTitle or id fallback
displayTitleSubagent creation label, optional
cwdWorking directory, optional
sameWorkspaceWhether it matches the requester's directory
createdAtCreation time
mentionCanonical 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:

  1. Escaping — the label sits inside @[...], so brackets and parentheses need handling;
  2. Encoding — the URI portion must follow the encoding rules, which hand-building often misses;
  3. 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:

  1. The user types @ and the client calls remote candidates;
  2. Render the list using displayTitle or label;
  3. On selection, insert mention verbatim into the draft;
  4. On submit, pass the selected sessionId as 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:

  1. Call the remote method and confirm every candidate has mention;
  2. Pick a session whose title contains ] and confirm the inserted mention keeps valid syntax;
  3. Confirm the result count does not exceed the configured limit;
  4. 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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, where does the @ mention text come from in a browser client?

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.

For DSH plugin, why not build the mention from label and sessionId directly?

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.

With DSH plugin, does mention always match label?

No, DSH plugin uses displayTitle for the mention when it exists. The inserted text can therefore differ from the label shown in the list.

In DSH plugin, should the frontend apply the candidate limit again?

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