DSH plugin prepare: four inputs, two outputs, one context
In DSH plugin, prepare is the only session reference step that actually reads logs: it takes readable content plus structured references and returns the same content with at most one aggregated context. When it misbehaves, the cause is usually the input shape or the reference relationship, not the reading itself.
DeepSeek Harness: Called prepare and got no context
Separate "no references" from "references failed". (source) Three scenes:
Case A references empty -> normal return, no additionalContext
Case B references present, read fails -> throws with a stable code
Case C references point at self -> rejected with a self-reference error
Only A is "success with nothing to add". B and C are diagnosable failures.
Many integrations treat A as failure, then retry or inject defaults, which buries the actual problem.
DeepSeek Harness: The four inputs
Four parameters, each with one job. (source) Comparison:
| Parameter | Shape | Responsibility |
|---|---|---|
agent | Agent | Requester identity, used for ordering and self checks |
content | ContentBlock[] | Already normalized readable message content |
references | SessionReferenceInput[] | Source sessions in mention order |
signal | AbortSignal, optional | Cancellation boundary for this turn |
"Already normalized" is the host's job: turn rich text and mention markers into readable blocks before calling prepare.
Each references item needs only sessionId and an optional label; full paths and titles are unnecessary.
DeepSeek Harness: Two outputs, nothing else
One readable content, one optional context, no third field. (source) Structure:
| Field | Always present | Meaning |
|---|---|---|
content | Yes | Content blocks after mention tokens are removed |
additionalContext | No | Aggregated untrusted context |
additionalContext is a UserMessage, not a system message. That decides its role on the model side: reference material, not instructions.
With no referenced content, the field is absent rather than an empty object. Hosts should branch on presence, not on "empty array".
DeepSeek Harness: Why self references are rejected
Because they are meaningless and recursive. (source) Two reasons:
- Semantics — a session referencing itself feeds existing content back into the same conversation;
- Implementation — reads and writes hit the same log, which invites an inconsistent snapshot.
The method documentation states that references pointing at the agent itself are rejected. Hosts should filter at selection time rather than wait for the error.
Filtering early also means users never pick a candidate that is guaranteed to fail.
DeepSeek Harness: One aggregation per message
Multiple references become one context, not one section per reference. (source) Rules:
- prepare snapshots one accepted message;
- All referenced material aggregates into one
additionalContext; - Order is preserved through
inputIndexin the persistent source; - Compression and truncation happen during aggregation and are recorded as facts.
This explains why the return type has no "contexts array". The host does not stitch multiple contexts together.
If a UI wants to display sections per session, that is a presentation concern; it should not require prepare to return multiple contexts.
DeepSeek Harness: Verifying the call sequence
Four steps, from empty to many, adding references layer by layer. Steps:
- Pass empty
referencesand confirm content returns with noadditionalContext; - Pass one valid session and confirm context exists;
- Pass three sessions and confirm there is still one context, with
inputIndexmatching input order; - Pass the current session itself and confirm a self-reference error.
Step 3 is the aggregation assertion: three contexts mean the caller invoked prepare in a loop.
Step 4 is the boundary assertion: the error code should be readable, not a generic "reference failed".
If a host keeps references in message attachments, parse them into references before calling; prepare accepts explicit references only and will not guess from attachment text.
The caller should also not delete mention text before or after prepare; that blurs the byte preservation boundary and makes later debugging unable to tell who edited what.
With prepare working, budgeting is next. Read the DSH plugin reference budget and 64 KiB fallback; for what truncation returns, read DSH plugin truncation fields; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/index.ts
FAQ
Not necessarily, because DSH plugin returns success with empty references. Only read failures or self references are errors; the empty case is not. Treating the empty case as failure hides the real problem.
DSH plugin expects each item to be a SessionReferenceInput with sessionId and an optional label. DSH plugin does not need paths or titles, because identity is what selects the session.
DSH plugin rejects it because the reference is meaningless and recursive: the session would feed its own content back, and reading and writing the same log can produce an inconsistent snapshot. For that reason the host should filter the current session out at selection time.
No, DSH plugin aggregates all references into at most one context. The aggregation uses inputIndex to preserve the order references were passed in.
Related Terms
- prepare
- prepare is the session reference step that reads referenced logs and returns readable content plus at most one aggregated context.— DeepSeek Harness reference - Session references
- additionalContext
- additionalContext is the optional aggregated UserMessage carrying referenced material as untrusted context.— DeepSeek Harness reference - Session references
- SessionReferenceInput
- SessionReferenceInput is one source session with an authoritative sessionId and an optional label.— DeepSeek Harness reference - Session references
- inputIndex
- inputIndex records the order in which references were supplied so the aggregated snapshot keeps that order.— session-reference/src/index.ts
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/index.ts· deepseek-ai