ChatGPTClaudeGrok / X / CursorGemini

DSH plugin reference missing: four steps from a success log

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referencetroubleshootingpersistent record
The user saw nothing while the log says success. Four fixed steps separate a missing input, a compaction gap, a budget cut, and a bad coordinate.

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:

ProvesDoes not prove
prepare was called and completedThe user's selection actually arrived
The reference was written to the recordContent was complete, with no source gap
A result object was returnedadditionalContext 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:

  1. Is references empty?
  2. capturedFormatVersion and compacted;
  3. The three message counts and truncated;
  4. 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 content only and dropped references;
  • 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:

  • capturedFormatVersion absent → 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:

text
originalMessages = retainedMessages + omittedMessages

Then read truncated:

SymptomConclusionNext step
The subtraction failsRecording logic is brokenInspect the writer, not the model
Large omittedMessages, truncated falseSource compaction gapSwitch sessions or reference earlier content
truncated trueThis budget omitted contentAdjust the budget or narrow scope
Both trueGaps stackHandle 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:

  1. Is capturedThroughSeq stored together with the source sessionId?
  2. Was the lookup opened with the source session's identity?
  3. 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:

  1. Replay the request with the same fixture and confirm the references count matches the user's selection;
  2. Print capturedFormatVersion and compacted and confirm the interpretation path is right;
  3. Print the three counts and truncated and confirm the subtraction holds;
  4. 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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, the record says the reference succeeded, but the model saw nothing. What comes first?

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.

For DSH plugin, what usually causes an empty references array?

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.

With DSH plugin, both compacted and truncated are true. Which do I address first?

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.

In DSH plugin, a coordinate lands in the wrong place. Is the stored value wrong?

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