DSH plugin session query: bounded reads, traces and search

DSH plugin session query has two faces: exact reads and trace relationships, which are backend-independent, and full-text search, whose index lifetime belongs to the provider. Both share the live-preferred premise — when an id exists in memory and on disk, data comes from the live source, with live and persisted flags reported separately. The most common misuse is filter combination semantics: arrays AND together, values within a clause OR together, ranges are inclusive; and text clauses scan semantic text literally rather than acting as executable FTS syntax.

DSH plugin session query API: exact reads and full-text search

Bottom line: exact reads, filters and traces share one abstract service; the provider owns indexing and swapping it keeps the vocabulary.

1. Backend-independent: bounded reads, filters, traces, lineage and title observation.
2. Backend-related: full-text observation, reconciliation, ranking, cursor generations and query execution.
3. One entry point: everything hangs off ctx.sessionQuery.
4. Selection: exact reads when you need a specific event and its context; search when you need "which sessions mention X."
5. Rule of thumb: require stable order and exact seqs for reads, relevance ranking for search.

DSH plugin logical records: availability flags and one-shot snapshots

Bottom line: SessionRecord reports availability; the snapshot types are observations, not subscriptions.

1. Listings cover the corpus: listSessions() returns deterministic newest-first records.
2. Snapshots are one-shot: re-read to refresh.
3. Surface classification: current, shadowed, log-only distinguish current context, replaced context and raw-log-only.
4. Title observation follows the same rule: batch results come in request order, one failure affects only that id, and cancellation rejects the whole call.
5. Do not treat persisted as live: persisted-only sessions go through cold reads with different semantics.

DSH plugin filters: AND, OR and literal text scans

Bottom line: arrays AND, clauses OR, ranges inclusive; text is a literal scan, not an executable query language.

const sessions = await ctx.sessionQuery.filterSessions([
  { kind: 'cwd', values: ['/work/a', '/work/b'] },
  { kind: 'created-at', from, to },
])

1. Session filters: id, cwd, created-at, parent, availability.
2. Event filters: seq, time, type, surface, text.
3. Text rule: literal, Unicode case-insensitive, whitespace-flexible.
4. Semantic text scope: messages, tool calls and results, todos, failures and status details are included; reasoning blocks, blocked prompts, structural events and stream chunks are not.
5. Ordering: filterEvents returns matching documents by ascending seq.

DSH plugin full-text search: grouped hits, in-session hits and cursors

Bottom line: cross-session search groups by strongest event; in-session search returns events and always the target header.

1. Cross-session: searchSessions({ query, sessionFilters, eventFilters, limit, cursor }), each group carrying bestMatch.
2. In-session: searchEvents({ sessionId, query, filters, limit, cursor }), returning the target header even with zero hits.
3. Query is data: text is interpreted as data, never as executable FTS syntax.
4. Cursor binding: a cursor is bound to the normalized query, metadata filters and limit; changing any of them restarts the search.
5. Metadata filters only: provider filters exclude text scanning and apply before ranking.
6. Pagination: items plus an optional nextCursor, absent on the last page.

DSH plugin bounded reads, event traces and lineage

Bottom line: reads give raw windows, traces give replacement chains and citations, lineage gives ancestors and descendant trees.

1. Bounded reads: a request specifies the target seq plus before/after counts and returns a window with startSeq/endSeq; the result carries a header rather than availability flags.
2. Replacement relations: replacedBy is the immediate replacer, replacementChain reaches the final replacement, and replacedEventSeqs lists positional nodes this event removed.
3. Citation relations: sourceEventSeqs are earlier cited events, derivedEventSeqs are later events citing this one.
4. Lineage: ancestors nearest-first, descendants as a recursive forest; complete: false supplies unresolvedParentId rather than pretending to be a root.
5. Stable errors: EVENT_NOT_FOUND, INVALID_CURSOR, STALE_CURSOR, SEARCH_DISABLED, INDEX_FAILED and SOURCE_CONFLICT are codes — branch on them, not on message text.

DSH plugin session query troubleshooting

Bottom line: separate no results, slow results and odd order — filter semantics, indexing and ordering contracts.

1. No results — check AND/OR semantics and whether text was treated as syntax.
2. Zero in-session hits — normal: items is empty but the header is still returned.
3. Stale cursor — the query or limit changed; restart the search.
4. Unexpected order — search ranks by relevance; only exact reads are seq-ascending.
5. Incomplete lineage — read complete and unresolvedParentId; do not invent a root.
6. Repair status, stated honestly: record types, filter semantics, search requests and error codes follow the official Session query page; confirm signatures against its Cordis API and your version.

Sources: Session query, session-query package, Session persistence.