DSH plugin hand-typed mentions: text vs structured input
In DSH plugin, pasting a mention from a document produces a normal message with no referenced content, because the paste carries display text rather than a selection. The missing piece is not syntax; it is the absence of that session from references.
DeepSeek Harness: Why a pasted mention does nothing
Because the user copied display text, not a choice. (source) Scene:
Copied from docs: @[Fix login timeout](dsh-session:abc123)
Pasted into the input, sent
Result: the message goes out, but the referenced session is not loaded
The user assumes "the text contains a reference, so it must have been read". The chain is missing the crucial step: that session never entered references.
Text is for humans; references are for the program. They can coexist, but neither substitutes for the other.
DeepSeek Harness: references is a separate input
It is a prepare argument, not something derived from the body. (source) Structurally:
| Input | Shape | Role |
|---|---|---|
content | Readable content blocks | What the user actually says |
references | Structured array | Which sessions to read |
signal | Cancellation boundary | Whether this turn is still valid |
Each entry in references is a SessionReferenceInput with an authoritative sessionId and an optional label.
Passing them separately means "what the body says" and "which sessions are read" are independent facts.
DeepSeek Harness: prepare removes tokens, it does not resolve them
It subtracts, it does not parse. (source) The official description of content is the readable content after host mention tokens are removed.
In practice:
- prepare deletes mention markers from the body;
- It never takes those characters and looks up sessions;
- Every session to read comes from
references.
This design avoids "the body is the instruction": the model sees clean text, while the read set is decided by structured input.
Expect prepare to be a fallback parser and you will observe "the text disappeared but the context never arrived".
DeepSeek Harness: Two honest host choices
Either parse it into a selection, or reject it clearly — never leave it ambiguous. (source) Two options:
- Parse before submit — recognize mentions in the input, convert them into
SessionReferenceInputentries, and pass them inreferences. - Do not support it — treat a hand-typed mention as plain text and tell the user to pick a session from the list.
The first is better UX but requires the host to parse, validate, and deduplicate. The second is simple but leaves users wondering why their paste does not work.
Whichever you choose, never highlight it in the UI without adding it to references. That makes users believe the reference worked.
A middle path is worth considering: allow the paste, then immediately convert it into a visible reference chip and write it into references. Habits stay intact and structured input survives.
DeepSeek Harness: The security value of explicit selection
Explicit selection makes "what was read" auditable. (source) Three benefits:
- Users know which session they chose instead of being led by a string;
- Permission checks can happen at selection time, before any text parsing;
- Logs record a list of session ids rather than a forgeable string.
The third matters most: text can be copied, edited, and concatenated; structured input cannot.
So "hand-typed mentions should just work" is not a convenience feature; it moves the trust boundary from a selection gesture to arbitrary text.
DeepSeek Harness: Verifying separation
Three steps confirm text and references stay apart. Steps:
- Put only a mention in the body with empty
referencesand confirm noadditionalContext; - Put plain text in the body with one session in
referencesand confirm context exists; - Put a mention in the body and the same session in
referencesand confirm context appears once.
Step 1 proves text does not trigger reads; step 2 proves reads depend only on references; step 3 confirms no duplicate aggregation.
Three passes mean the two pipelines are not entangled.
Do not stop at whether a chip appears in the UI — open the request and confirm references contains the session id. A chip can be decoration while the real reference lives in the structured field.
Storing a mention as plain text has another side effect: import and export pollute the body, and if a host later parses it again, that is a back door.
That closes the A list. Next comes preparation and governance: read the DSH plugin prepare contract; for candidates carrying mentions, 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
Because the paste carries display text, not a DSH plugin selection. DSH plugin reads sessions only from references; without a SessionReferenceInput, prepare has nothing to fetch even if the text looks like a mention.
No, DSH plugin prepare never searches the body for mentions. It removes host mention tokens from readable content as a subtraction step and never resolves those characters back into sessions.
Either DSH plugin host choice is defensible: parse pasted mentions into references before submit, or explicitly reject them and ask users to pick from the list. Highlighting without adding a reference is the one unacceptable option.
DSH plugin's explicit selection produces an auditable record of which sessions were read. Text can be copied, edited, or concatenated, while references carries authoritative session ids that logs and permission checks can trust.
Related Terms
- references
- references is the structured array telling prepare which sessions to read; it is not derived from message text.— DeepSeek Harness reference - Session references
- SessionReferenceInput
- SessionReferenceInput is one reference item with an authoritative sessionId and an optional label.— DeepSeek Harness reference - Session references
- mention token
- A mention token is the host's textual marker inside content, which prepare removes without resolving it.— session-reference/src/index.ts
- explicit selection
- Explicit selection means the user chooses a session in the UI, producing structured input rather than text to be parsed.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/index.ts· deepseek-ai