ChatGPTClaudeGrok / X / CursorGemini

DSH plugin prepare: four inputs, two outputs, one context

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referencepreparecontract
prepare is the only step that reads logs: normalized content plus structured references in, readable content plus at most one aggregated context out.

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:

text
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:

ParameterShapeResponsibility
agentAgentRequester identity, used for ordering and self checks
contentContentBlock[]Already normalized readable message content
referencesSessionReferenceInput[]Source sessions in mention order
signalAbortSignal, optionalCancellation 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:

FieldAlways presentMeaning
contentYesContent blocks after mention tokens are removed
additionalContextNoAggregated 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:

  1. Semantics — a session referencing itself feeds existing content back into the same conversation;
  2. 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 inputIndex in 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:

  1. Pass empty references and confirm content returns with no additionalContext;
  2. Pass one valid session and confirm context exists;
  3. Pass three sessions and confirm there is still one context, with inputIndex matching input order;
  4. 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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, prepare returned success but there is no additionalContext. Is that a failure?

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.

For DSH plugin, what does prepare need in references?

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.

With DSH plugin, why is referencing the current session rejected?

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.

In DSH plugin, does prepare return one context per reference?

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