DSH plugin session references: URI, discovery and prompts

A session reference is not “copy another conversation’s history”; it is structured cross-session reading: input uses sessionId, label is display-only, discovery searches metadata rather than transcripts, and prepare turns the referenced log into readable content plus one aggregated untrusted context. The two most common mistakes are treating label as identity and treating referenced content as trusted instructions.

DeepSeek Harness: Input and candidates

Separate identity from display: sessionId is authoritative, label is metadata. Two sides:(source)

1. SessionReferenceInput — a host selects a source session with sessionId and optional label. Expected: later reads use only the ID.
2. SessionReferenceCandidate — discovery output with sessionId, label, optional displayTitle, cwd, sameWorkspace, and creation time. Expected: no chat content in the candidate.

label prefers the latest session title and falls back to the opaque ID; displayTitle prefers a subagent’s durable creation label when present. Filtering searches label, displayTitle, session ID, and cwd, never the transcript.

sameWorkspace is true only when cwd exists and equals the requesting agent’s cwd. It lets a host avoid comparing paths it never received.

DeepSeek Harness: Mention format

The canonical mention is @[label](dsh-session:…), returned by the remote candidate method. Key points:(source)

• The service generates the mention — the host should not build it. Expected: label and URI encoding stay consistent.
• Insert into the prompt draft — the host places the mention in the composer. Expected: users see a readable label while parsing gets the ID.
• prepare removes the token — readable content excludes the mention token, and context is generated separately. Expected: the model does not treat the token as body text.

A host that builds dsh-session: strings itself tends to break on parentheses or special characters. Use the returned mention.

DeepSeek Harness: What prepare returns

prepare returns two parts: readable content and at most one aggregated untrusted context. Structure:(source)

The persistent source record stores each reference: sessionId, label, source format version, capturedThroughSeq, whether compacted, original/retained/omitted message counts, omitted bytes, truncation, and input order.

capturedThroughSeq is a coordinate in the referenced session’s original generation, not the current session’s seq. That distinction matters when stitching across sessions.

DeepSeek Harness: Budget and truncation

References are not unlimited reads; budget and truncation are part of the contract. Rules:(source)

1. Automatic budget — use the last assembled route, or agent options before assembly. Expected: matches the session’s actual model capacity.
2. Missing capacity or adapter — use 64 KiB. Expected: no unbounded read because metadata is missing.
3. Truncation — return omission facts and a full-snapshot spill locator, or an explicit unavailable notice. Expected: the caller knows content is incomplete.
4. Cancellation — do not publish context after cancellation, even if storage completes. Expected: no “cancelled but still injected”.

Other metadata lookup failures and cancellation reject prepare; do not treat failure as an empty reference and continue.

DeepSeek Harness: Seven error codes

Error codes are a stable contract; branch on the code, not on prompt text. Seven:(source)

• SESSION_REFERENCE_INVALID_CONFIG — invalid configuration.
• SESSION_REFERENCE_INVALID_REFERENCE — malformed or invalid reference.
• SESSION_REFERENCE_SELF_REFERENCE — referencing itself.
• SESSION_REFERENCE_TOO_MANY — too many references.
• SESSION_REFERENCE_READ_FAILED — source session read failure.
• SESSION_REFERENCE_BUDGET_EXCEEDED — budget exceeded.
• SESSION_REFERENCE_CANCELLED — cancelled.

Host protocols map these codes to their own error wrappers without inspecting prompt bytes. Also check whether prepare published additionalContext; absence is not necessarily failure.

DeepSeek Harness: Mention and prepare field map

Separate selection input from preparation result to avoid treating label as identity. Compare:(source)

The persistent source also records capturedThroughSeq, format version, omitted counts, and bytes. It is not the current session’s seq; do not mix them when tracing across sessions.

Three usage forms

Host mention, resolver API, and direct input cover different layers. Three:

1. Host mention — insert the returned mention into the draft. Expected: best UX; parsing is delegated to prepare.
2. resolver.listCandidates — implement your own search and ranking by cwd affinity. Expected: good for a custom UI.
3. Direct SessionReferenceInput — reference a known sessionId. Expected: good for automation and tests.

All three must go through prepare to get readable content and context.

DeepSeek Harness FAQ

Does a session reference include the full history of the referenced session? No. prepare is budgeted and may compact, truncate, or omit; the result includes omission facts and a locator.

Can I reference a running session? Yes, but the read is a snapshot coordinate; later messages are not appended to this reference.

Why is referenced content marked untrusted? It comes from another session log and may contain user input or tool output. As additional context it must be handled as untrusted data, not system instructions.

The short version: ID locates, metadata discovers, budget reads, and context stays untrusted; treating label as identity or content as instruction crosses the boundary.