DSH plugin label escaping: one bracket breaks a mention
One ] in a session title ends a hand-built mention early — not an edge case, but the inevitable result of placing a label inside @[...]. DSH plugin solves it with label-safe JSON serialization; the host's job is to stay out of the way.
DeepSeek Harness: One bracket breaks the mention
Start with a hand-built failure. (source) Suppose the title is:
Fix [payment] callback
Hand-building produces:
@[Fix [payment] callback](dsh-session:xxxx)
The parser ends the label at the first ] and the remainder becomes unrecognizable text. The reference fails, and the user sees odd characters in the input.
The title is not invalid; the concatenation treated it as syntax.
DeepSeek Harness: What label-safe JSON means
It is a serialization rule with one goal: let arbitrary label text enter the bracketed structure safely. (source) The official material lists it alongside byte preservation as part of the session reference contract.
It resolves delimiter collisions specifically:
| Label content | Hand-built risk | After serialization |
|---|---|---|
Fix [payment] callback | Truncated at ] | Preserved whole |
review (v2) | Parentheses read as URI bounds | Preserved whole |
a"b | Quote breaks the structure | Preserved whole |
It is neither URL encoding nor HTML escaping. It serves mention syntax, not network transport.
DeepSeek Harness: Three escaping layers
Each layer handles one segment; do not mix them. (source) Division:
- Label layer — resolves conflicts between label text and brackets;
- URI layer — encodes the identity portion;
- Content layer — prepare removes tokens without rewriting other bytes.
A host normally touches only the output of layer one, the ready-made mention on a candidate. Layers two and three live inside the service.
Understanding the split tells you who to call when something breaks: wrong label display points at serialization, wrong target points at the URI, rewritten content points at the content layer.
DeepSeek Harness: Two rewrites hosts should avoid
Trim and replace: two harmless-looking actions. (source) Comparison:
| Action | Intent | Consequence |
|---|---|---|
mention.trim() | Remove edge whitespace | Label changes; display differs across clients |
Swapping ] for a full-width bracket | Make it look nicer | Characters no longer match parser expectations |
Both share one pattern: editing data for presentation. Presentation belongs to the render layer — extract the label and display it, rather than mutating the mention.
If a shorter display is needed, render the list from displayTitle or label; use the mention only when inserting.
DeepSeek Harness: How escaping relates to byte preservation
One guards structure, one guards content; both mean "do not change the meaning". (source) Relationship:
- Label-safe JSON keeps a label from breaking the mention structure;
- Byte preservation keeps prepare from rewriting the rest of the referenced content;
- Neither permits a host to inject its own encoding rules.
So "normalize first, insert later" violates both: it can break structure and change bytes.
The correct boundary: the service serializes and reads; the host moves text verbatim and renders it.
DeepSeek Harness: A six-character test matrix
Six classes of characters in one pass. Matrix:
| Title content | Expected |
|---|---|
a]b | Mention structure stays intact |
a(b)c | URI boundaries do not shift |
a"b'c | Quotes do not affect parsing |
| Chinese title | Preserved unchanged |
| Emoji title | Preserved unchanged |
| Leading or trailing spaces | Spaces kept, not trimmed |
The last row is the easiest to overlook: spaces are part of the label, and removing them edits the user's title.
Do not stop at "it parses"; also assert that the resolved sessionId matches the candidate. Parsing into the wrong session is worse than failing.
With escaping covered, the next topic is hand-typed mentions. Read DSH plugin hand-typed mentions; for URI structure, read how DSH plugin parses a dsh-session URI; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
Because the label sits inside DSH plugin's @[...] mention structure. A hand-built mention ends at the first ], so the rest becomes unparseable. DSH plugin handles this with label-safe JSON serialization.
No, DSH plugin's label-safe JSON is not URL encoding. It serves the mention's syntax structure, not network transport, and it is distinct from HTML escaping as well. The URI portion has its own encoding rules.
No, trimming a DSH plugin mention is not safe. Trimming changes label content, and leading or trailing spaces are part of the title. Insert the mention verbatim and render the label separately if you need cleaner display.
A DSH plugin test should assert that the resolved sessionId equals the candidate id. Parsing successfully while resolving the wrong session is the more dangerous failure.
Related Terms
- label-safe JSON
- Label-safe JSON is the serialization rule that lets arbitrary label text enter the bracketed mention structure without breaking it.— DeepSeek Harness reference - Session references
- byte preservation
- Byte preservation forbids rewriting referenced content beyond removing host mention tokens.— DeepSeek Harness reference - Session references
- URI encoding
- URI encoding handles the identity portion of the mention, separately from label serialization.— session-reference/src/types.ts
- display rewrite
- A display rewrite changes data for appearance, such as trimming a mention or swapping brackets, and breaks parsing assumptions.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai