ChatGPTClaudeGrok / X / CursorGemini

DSH plugin truncation: the five facts a host must show

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referencetruncationspill
When the model says it missed the beginning, the record already knows. Five fields, two omission dimensions, spill locators, and what truncated really means.

Truncation is not silent failure: DSH plugin leaves truncated, omittedMessages, and omittedBytes in the persistent source and tries to return a spill locator for the full snapshot. If the model says it missed content while the UI shows nothing, the host is not reading these fields.

DeepSeek Harness: The model says it missed the beginning

A classic truncation symptom, not a comprehension problem. (source) Scene:

text
The user references a long session
The model answers: "I only see the second half"
The UI: no omission notice at all

If truncated is true in the source record, preparation did omit content. The model did not lie; the interface failed to pass the fact along.

The order should be: check truncated, then measure the omission, and only then discuss model behavior.

DeepSeek Harness: Five facts on the persistent source

Five fields answering "was anything missing", "how much", and "where". (source) Comparison:

FieldMeaning
originalMessagesTotal messages in the source session
retainedMessagesMessages kept for this preparation
omittedMessagesMessages omitted this time
omittedBytesBytes omitted this time
truncatedWhether truncation happened

They live on each reference entry in the source, not as one summary for the whole context.

That means referencing several sessions lets you see how much each one lost.

DeepSeek Harness: Reading omittedMessages and omittedBytes together

Two dimensions together, or averages mislead. (source) Three combinations:

  1. Few messages, many bytes — long messages were dropped, and the impact can be large;
  2. Many messages, few bytes — short exchanges were dropped, with smaller impact;
  3. Both large — the budget is clearly insufficient; prompt the user to narrow the reference.

Message count alone underestimates the first case; bytes alone underestimates the second. Good UI copy reports both.

A useful threshold: when omittedBytes exceeds some proportion of what was retained, show an "omitted" badge directly on the reference card.

DeepSeek Harness: Truncated vs compacted

One describes this call, the other describes the source; conflating them misattributes the gap. (source) Comparison:

FieldSourceDirection
compactedSource session was compactedSwitch sessions or accept the gap
truncatedThis preparation ran out of budgetNarrow the reference or use a larger model

When both are true, the source was compacted first and truncation happened again, so gaps stack.

Check compacted first during diagnosis: once the source is compacted, no budget increase can read back the compacted content.

DeepSeek Harness: Spill locators and unavailable notices

Give a location when recovery is possible; say so plainly when it is not. (source) Rules:

  • The truncated preview includes omission facts and a spill locator for the full snapshot;
  • When the locator is unavailable, return an explicit unavailable notice;
  • Never use an empty string or null to pretend nothing was truncated.

The third rule matters most: missing and unavailable are different states, and one value for both makes diagnosis hopeless.

Hosts should map the two states to distinct copy, such as "omitted, full snapshot available" and "omitted, full snapshot currently unavailable".

DeepSeek Harness: Verifying truncation visibility

Five assertions cover fields, visible notice, and location. Steps:

  1. Build an over-budget reference and confirm truncated is true;
  2. Confirm originalMessages = retainedMessages + omittedMessages;
  3. Confirm omittedBytes is greater than zero;
  4. Confirm the UI shows an omission notice rather than staying silent;
  5. If a spill locator is returned, confirm the full snapshot can be recovered from it.

Step 2 is the easiest assertion to get wrong: if the arithmetic fails, the recording logic has a bug.

Step 4 is a product-level assertion: complete fields shown to nobody are equivalent to no fields.

The notice belongs on the reference card, not only in developer logs; if users cannot see it, it did not happen.

With truncation covered, the next topic is source compaction. Read DSH plugin referencing a compacted session; for where the budget comes from, read the DSH plugin reference budget; for the wider picture, read how DSH plugin implements session references.

Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, the model says it only saw the second half. How do I confirm truncation?

Check truncated in the DSH plugin persistent source. DSH plugin also records omittedMessages and omittedBytes, and all three together describe how much was left out.

For DSH plugin, what is the difference between omittedMessages and omittedBytes?

DSH plugin's omittedMessages counts messages while omittedBytes counts bytes. Two dimensions prevent a small number of very long messages from being underestimated.

With DSH plugin, both truncated and compacted are true. Is that the same thing?

No, DSH plugin records truncated and compacted for different causes. compacted means the source session was compacted before capture; truncated means this preparation omitted content because of budget. DSH plugin records them separately so the gap can be attributed.

In DSH plugin, what is the spill locator, and can it be read directly?

A DSH plugin spill locator points to the full snapshot for retrieving omitted content later. DSH plugin also returns omission facts; when the location is unavailable it returns an explicit unavailable notice rather than letting callers guess.

Related Terms

truncated
truncated is the persistent source flag stating whether preparation omitted content because of budget.— DeepSeek Harness reference - Session references
omittedMessages
omittedMessages counts messages omitted during truncation, measuring the size of the gap.— DeepSeek Harness reference - Session references
omittedBytes
omittedBytes counts bytes omitted during truncation, capturing volume that message count alone misses.— DeepSeek Harness reference - Session references
spill locator
A spill locator points to the full snapshot so omitted content can be recovered after truncation.— DeepSeek Harness reference - Session references

Sources