DSH plugin compacted sources: what is still readable
Referencing a session that ran for three days and getting a dozen messages usually has nothing to do with budget: the source was compacted long ago. DSH plugin records that as a compacted flag plus three message counts; ignore them and you will blame this preparation for a historical gap.
DeepSeek Harness: What is missing when the source was compacted
What disappeared at compaction time, not what this read skipped. (source) A typical scene:
Source session: 400 messages accumulated, compacted once
After referencing: additionalContext covers only the latest 18
UI: no error, no omission notice
The caller sees "success" and assumes the full history arrived. What arrived is the segment still readable after compaction.
The first question is not "raise the budget" but "how much readable history does the source itself still have?"
DeepSeek Harness: What the compacted flag means
It describes the source session at capture time, not a parameter of this call. (source) Three points:
- The flag sits on each reference entry in the persistent source, per session;
- It is decided by the source session's history; no host parameter changes it;
- It is unrelated to this budget — no budget increase brings pre-compaction messages back.
So compacted: true declares limited readable scope, not a failure; seeing it should adjust user expectations, not trigger retries.
DeepSeek Harness: Three counts that must subtract
Three numbers form one subtraction, not three independent metrics. (source) Relationship:
originalMessages = retainedMessages + omittedMessages
Together with omittedBytes, the gap is measurable in both message count and volume.
A worked example makes it clearer:
| Scenario | originalMessages | retainedMessages | omittedMessages | Gap source |
|---|---|---|---|---|
| No compaction, no truncation | 40 | 40 | 0 | none |
| Source compacted | 400 | 18 | 382 | compaction |
| Compacted and truncated | 400 | 9 | 391 | compaction plus budget |
The second row is the key: omittedMessages is already 382 while truncated is false. Concluding "it was truncated" from the omission count alone attributes the gap to the wrong side.
The third row shows the gaps can stack. There, omittedMessages is a combined total; isolating what this budget removed requires reading truncated alongside the budget fields.
DeepSeek Harness: Source gap vs budget truncation
The difference is not magnitude but who can change it. (source) Comparison:
| Dimension | Source compaction | This budget's truncation |
|---|---|---|
| When it happened | Before the reference | During this prepare |
| Recorded by | compacted | truncated |
| Removable by changing settings | No | Yes, with a larger model or narrower scope |
| User action | Reference an earlier or different session | Fewer references or a larger budget |
The "no" in the first column matters: if a host treats a compaction gap as a budget problem, users retry forever without ever getting more content.
The second column is not magic either: a larger budget only recovers what this preparation omitted, never what compaction already removed.
A one-line memory aid: compacted is a historical fact; truncated is this call's decision.
DeepSeek Harness: Explaining it to users
Copy must distinguish "not read" from "no longer there". (source) Three treatments:
- Mark the reference card as "source compacted, recent content only";
- Avoid wording like "reference failed" — the read itself succeeded;
- When earlier content is needed, point users to the source session or to an uncompacted one.
The third is easy to skip: users want that early discussion, not more bytes. Telling them where to find it beats telling them to raise the budget.
If the product can show originalMessages and retainedMessages, say "the source has 400 messages, 18 readable now", which is far more concrete than "content may be incomplete".
Compaction and recall coordinates
Compaction decides which span is readable; the coordinate decides where that span sits in the source session. Two points:
capturedThroughSeqrecords the source generation position the snapshot reached, and compaction never turns it into the current session's seq;- Compaction narrows the readable interval, so recall must first confirm the coordinate still belongs to the source generation.
Read them together: compacted tells you something is missing, and the coordinate tells you which part.
The full coordinate reading is covered elsewhere; here it is enough to remember not to mix sequence numbers from two sessions.
DeepSeek Harness: Verifying the counts
Four assertions verify one compacted reference record. Steps:
- Pick a source session that was explicitly compacted and reference it;
- Assert
compactedis true; - Assert
originalMessages = retainedMessages + omittedMessages; - Assert
omittedBytesmatches the gap andtruncatedmatches the budget setting.
Step 3 is the most valuable assertion: if the three numbers disagree, the record itself is broken and every later judgment is unreliable.
Step 4 separates the two gaps. If the budget is ample but truncated is still true, the host's budget did not take effect, so go back to the budget article.
Add a reverse case: find a short session that was never compacted and confirm compacted is false with omittedMessages at 0. Only when both directions pass do you know the fields are not permanently true.
After source compaction, the next topic is coordinates. Read DSH plugin capturedThroughSeq belongs to the source generation; to review the truncation facts, read DSH plugin truncation fields; for the record structure overall, read DSH plugin recall records.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
The DSH plugin source session was likely compacted earlier. DSH plugin marks that state with compacted and records the gap through originalMessages and retainedMessages.
No, a positive DSH plugin omittedMessages count can also come from compaction. DSH plugin uses compacted for the source-side gap and truncated for this preparation's budget gap, so read both fields.
No, a larger DSH plugin budget cannot recover compacted messages. Compaction already happened in the source session; the reference can only read what remains. DSH plugin does not expand pre-compaction messages for a reference.
No, DSH plugin's originalMessages is the count before compaction. retainedMessages is what is currently readable, and the difference is omittedMessages, so do not treat originalMessages as the live total.
Related Terms
- compacted
- compacted is the persistent source flag saying the referenced session was compacted before capture.— DeepSeek Harness reference - Session references
- originalMessages
- originalMessages is the message count before source compaction, measuring the original scale.— session-reference/src/types.ts
- retainedMessages
- retainedMessages is how many messages were readable when the reference was captured, usually far fewer after compaction.— session-reference/src/types.ts
- source-side gap
- A source-side gap is content lost to compaction before capture, independent of whether this preparation had budget.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai