DSH plugin session search: never the transcript
Not finding a session by something you remember saying is not a defect: DSH plugin filters candidates only on label, displayTitle, session id, and cwd, with transcripts explicitly excluded. Finding a session by content requires a different pipeline.
DeepSeek Harness: Why chat text finds nothing
Because the filter input is not message content. (source) A common scene:
User remembers a session that mentioned "payment callback timeout"
Searches the reference picker for "payment callback"
Result: empty
The user assumes "if we talked about it, it should be searchable". But the picker answers a different question: which session's name, id, or directory looks like this — not which session discussed this.
The cost difference is an order of magnitude: one reads messages, the other reads metadata.
The four fields DSH plugin matches
Four fields, all from session metadata or projections. (source) Comparison:
| Field | Source | Role |
|---|---|---|
label | Latest title, id as fallback | Primary readable match |
displayTitle | Subagent durable creation label | Preferred display text |
| session id | Opaque identity | Direct search when the id is known |
cwd | Recorded working directory | Narrow by project path |
Matching is case-insensitive substring matching, and the query may be empty. What an empty query returns is decided by the candidate limit and ordering, not by "everything".
What unites the four: each is available from metadata or a projection without opening the session.
DeepSeek Harness: Three reasons transcripts stay out
Any one of these would be enough to rule it out. (source) Looking closely:
- Cost — candidates fire at keystroke rate; scanning transcripts means a full-text search per character.
- Privacy — the picker only needs "which session", and pulling message content in widens the exposed surface.
- Determinism — messages keep growing, so the same query would return different results over time and the list would never settle.
The third is usually forgotten: even if performance were acceptable, candidates would shift as conversations continue, which is worse for users.
So "never search the transcript" is not laziness; it keeps candidates on stable, lightweight metadata.
DeepSeek Harness: Where content search belongs
Use session query or search, and leave candidates alone. (source) Division:
| Goal | Capability | Result |
|---|---|---|
| Pick a session to reference | Reference candidates | Metadata-matched list |
| Find sessions that discussed a topic | Session query or search | Matching messages or sessions |
| Read one session's history | Session history | Message records |
Decide first whether you need to reference or to find. If it is the latter, even a clever workaround through the candidate API cannot give message-level locations.
This also shapes the UI: a picker search box should not promise content search, or users will keep hitting "we talked about it but it is not here".
DeepSeek Harness: Three substring details
Case, whitespace, and an empty query each behave differently. (source) Details:
- Case — insensitive;
Reviewandrevieware equivalent; - Whitespace — no normalization beyond trimming; spaces inside the query are part of the substring;
- Empty query — legal input, but the returned set depends on the candidate limit and ordering, so do not assume a full listing.
The third detail settles an implementation choice: never skip the request on an empty query and render a local cache instead, or the visible list will disagree with real candidates.
If a product wants a "recent sessions" view, combine a fixed ordering with an empty query instead of inventing a separate local dataset.
DeepSeek Harness: Verifying filter behavior
Four cases cover hits, misses, case, and empty input. Steps:
- Search a fragment of a title and confirm a hit;
- Search a word that appears in chat but not in any title and confirm no hit;
- Search the same title in a different case and confirm identical results;
- Pass an empty query, record the count and order, and confirm the next call matches.
Case two is the expected miss that proves transcripts are not involved; a hit there means the implementation crossed the line.
Case four checks empty-query stability so the list does not jump when the panel opens.
One more rule: filtering affects only the candidate list, never already-selected references. Clearing the search box must not clear references.
Filtering answers "can I find it"; the next question is ordering. Read DSH plugin candidate ranking and self exclusion; for display names, read DSH plugin session candidate names; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/index.ts
FAQ
Because DSH plugin candidate filtering does substring matching on label, displayTitle, session ID, and cwd; the transcript is explicitly excluded. Looking sessions up by content is a different capability.
DSH plugin searches four fields: label, displayTitle, session ID, and cwd. All come from metadata or projections, so none of them requires opening a session or reading its messages.
No, DSH plugin matching is case-insensitive. So Review and review behave the same, and spaces stay part of the substring. Spaces inside the query are part of the substring rather than normalized away.
An empty DSH plugin query returns a valid result set bounded by the candidate limit and ordering, not necessarily everything. Treat it as the provider's decision instead of assuming a full listing.
Related Terms
- label
- label is the newest title, falling back to the opaque session id, and is the primary readable field for matching.— DeepSeek Harness reference - Session references
- displayTitle
- displayTitle is the subagent's durable creation label and the preferred text for display when present.— DeepSeek Harness reference - Session references
- cwd
- cwd is the working directory recorded for a session, useful for narrowing candidates by project path.— DeepSeek Harness reference - Session references
- substring match
- A substring match checks whether the query appears inside a field value, case-insensitively, without semantic analysis.— session-reference/src/index.ts
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/index.ts· deepseek-ai