DSH plugin reference missing: four steps from a success log
In DSH plugin, the most common shape of "the reference did not come through" is a user who saw nothing and a log with one successful record. Success only says prepare finished; it says nothing about content reaching the model. Diagnose by reading the persistent record in a fixed order, not by suspecting the model first.
DeepSeek Harness: What a success record proves
It proves three things and disproves nothing about three others. (source) Comparison:
| Proves | Does not prove |
|---|---|
| prepare was called and completed | The user's selection actually arrived |
| The reference was written to the record | Content was complete, with no source gap |
| A result object was returned | additionalContext was published to the model |
The third row starts many misdiagnoses: between returning success and "the model saw it" sits a publication step.
So the first move is reading record fields, not model logs.
Why the order cannot change
The four steps depend on each other; skipping one flips the conclusion. Order:
- Is
referencesempty? capturedFormatVersionandcompacted;- The three message counts and
truncated; - Ownership of
capturedThroughSeq.
If step 1 is empty, the next three analyze a reference that never existed.
Skip step 2 and read counts directly, and a compaction gap looks like a budget shortfall.
The order is the method: each step answers exactly one question before the next begins.
DSH plugin step 1: is references empty
An empty array means content never entered; budget is irrelevant. (source) Three common causes:
- The frontend left the mention in input text without parsing it into
SessionReferenceInput; - The host serialized the message with
contentonly and droppedreferences; - The caller built a completion UI but did not pass the selection on submit.
DSH plugin never infers references from dsh-session: strings in the body; the input must be explicit.
The check is fast: no reference entry in the record means the later fields do not matter.
The fix belongs in the host: on submit, reject requests where the body contains a mention but references is empty.
DSH plugin step 2: version and compaction
First confirm the record can be interpreted, then look at content size. (source) Two fields:
capturedFormatVersionabsent → read it as format v0, not unknown or corrupt;compacted: true→ the source was compacted before capture, so early content was never readable.
The second sets the direction for everything after: when the source is compacted, "less content" is a fact, not a bug.
This step also catches another class: a record written by a newer implementation being force-parsed by an older format, yielding empty fields everywhere.
Do not conclude anything from empty values before confirming version dispatch is correct.
DSH plugin step 3: counts and truncation
Three numbers plus one boolean explain how much is missing. (source) Check:
originalMessages = retainedMessages + omittedMessages
Then read truncated:
| Symptom | Conclusion | Next step |
|---|---|---|
| The subtraction fails | Recording logic is broken | Inspect the writer, not the model |
Large omittedMessages, truncated false | Source compaction gap | Switch sessions or reference earlier content |
truncated true | This budget omitted content | Adjust the budget or narrow scope |
| Both true | Gaps stack | Handle the source first, then the budget |
The third case depends on the budget source: automatic budgets use the last assembled route, and a different route moves the truncation point.
DSH plugin step 4: coordinate ownership
When a lookup fails, ask whose seq it is before asking whether it was stored correctly. (source) Three checks:
- Is
capturedThroughSeqstored together with the sourcesessionId? - Was the lookup opened with the source session's identity?
- When the coordinate is absent, does the UI wrongly show message 0?
The second is the most frequent error: interpreting a source coordinate with the current session always lands somewhere unrelated.
The third is a display issue: absence should render as "position unknown", not as a concrete number.
A coordinate has no correctness of its own, only ownership; with the wrong owner, an accurate number is still useless.
DeepSeek Harness: Replaying once
Four replay steps, each leaving one observable result. Steps:
- Replay the request with the same fixture and confirm the
referencescount matches the user's selection; - Print
capturedFormatVersionandcompactedand confirm the interpretation path is right; - Print the three counts and
truncatedand confirm the subtraction holds; - Locate by coordinate with the source identity and confirm it lands on the snapshot's last message.
Four passes mean the record side is sound, so move on to publication and display.
Any failure means fixing that step first instead of guessing further down the chain.
For field-level detail, read DSH plugin truncation fields and DSH plugin referencing a compacted session; for coordinates, read DSH plugin capturedThroughSeq; to start from the record structure, read DSH plugin recall records.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
Check whether references is empty in the DSH plugin record. If it is, the selection never reached prepare; if not, read compacted and truncated to tell a source gap from a budget cut.
DSH plugin sees three common causes: the frontend left the mention in plain text, the host dropped references while serializing, or the caller sent only content. DSH plugin never guesses references from body text.
Address DSH plugin compacted first. A compacted source means that history is already unreadable and raising the budget will not help; only after ruling out a source gap should you judge whether this budget was reasonable.
Not necessarily, so first confirm DSH plugin's coordinate was opened with the source identity. DSH plugin's capturedThroughSeq belongs to the source generation, so reading it with the current session always lands elsewhere.
Related Terms
- empty references
- An empty references array means prepare received no session references, so the context can contain nothing.— DeepSeek Harness reference - Session references
- success record
- A success record shows prepare completed and the reference was persisted; it does not prove content reached the model.— session-reference/src/types.ts
- diagnostic order
- The diagnostic order moves from references to version and compaction, then counts and truncation, then coordinate ownership.— DeepSeek Harness reference - Session references
- coordinate ownership
- Coordinate ownership identifies which source session's generation a capturedThroughSeq belongs to, which decides how it can be read.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai