dsh-session-search-pro

🔍 dsh-session-search-pro

English | 简体中文

Search every DSH session you've ever had — past and current — without leaving the one you're in.

Three agent tools for DeepSeek Harness, built on the runtime's own indexed sessionQuery service instead of scanning session files by hand.

Install

Nothing here is on npm yet, so install straight from GitHub. Add it to your profile's package.json:

// ~/.dsh/profiles/<profile>/package.json
{
  "dependencies": {
    "dsh-session-search-pro": "github:LeslieWylie/dsh-session-search-pro"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-session-search-pro"]
    }
  }
}

Then reinstall and restart the profile:

cd ~/.dsh/profiles/<profile> && pnpm install
dsh --profile <profile>

Pin a tag instead of tracking the default branch with github:LeslieWylie/dsh-session-search-pro#v0.1.0.

cd ~/.dsh/profiles/<profile> && pnpm add github:LeslieWylie/dsh-session-search-pro
dsh --profile <profile> --patch ./node_modules/dsh-session-search-pro/cordis.patch.yml

Why another session-search plugin?

dsh-session-search by Tieboyh
takes a different route: it reads session files directly, decompressing and
scanning zstd frames itself, which lets it search other runtimes' sessions
too — Codex, Claude Code, PI, OpenCode. If you work across several agent CLIs,
that is the one you want.

This plugin goes through the harness's own sessionQuery service instead. That
buys the live in-progress session, no file-format assumptions, and no external
binaries — and it means the plugin inherits whatever indexing the deployment has
configured, including none (see
Search on a stock profile).

Benefits

• ✅ Zero runtime dependencies — no ripgrep, no zstd parsing, no local database
• ✅ Works on a stock profile — uses the FTS5 index when the deployment enables it, and falls back to a bounded scan when it does not, instead of returning a configuration error as the search result
• ✅ Current session is searchable — not just sessions that have already ended
• ✅ Fails closed, not half-open — if sessionQuery isn't available at all, the plugin logs a warning and registers no tools, rather than registering tools that would throw on first use
• ✅ Read-only — never writes to a session; no database or cache of its own
• ✅ MIT licensed

Usage

The agent has access to these tools automatically once the plugin is bundled. Ask things like:

"Search my past sessions for anything about session search"
"List my recent sessions in ~/Desktop"
"Read session a4d75296-fc89-44b1 for me"

and the model reaches for agent_session_search, agent_session_list, or agent_session_read on its own.

Tool reference

agent_session_search

Full-text search across all DSH sessions, each hit carrying its best-matching snippet.

Two engines, picked automatically — see Search on a stock profile.

The result carries engine: "index" | "scan" so you can tell which path answered, plus scanned and truncated on the scan path.

agent_session_list

Lists sessions — past and current — with an optional working-directory filter, sorted newest- or oldest-first.

agent_session_read

Reads one session by id: title, metadata, and its events in order.

Plugin config

Set in the bundle row of cordis.patch.yml (or your own patch overlay):

Search on a stock profile

agent_session_search has two engines and picks one at call time.

The index. @deepseek-ai/dsh-session-query-sqlite is the concrete sessionQuery
backend in the stock dsh-base bundle, and it exposes a searchSessions() backed by
SQLite FTS5. When it is available, this plugin uses it and returns engine: "index".

But it is off by default. dsh-base wires that backend as:

- id: session-query-sqlite
  name: '@deepseek-ai/dsh-session-query-sqlite'
  config:
    path: ':memory:'
    openAt: never

and the engine's own guard throws SESSION_QUERY_SEARCH_DISABLED whenever
openAt is never. Content search is opt-in: a deployment turns it on by
overriding openAt to first-search or startup in a later patch layer,
normally with a durable path.

So on a stock profile the index call fails. This plugin catches exactly that
error and falls back to scanning sessions newest-first through listSessions()
and filterEvents() — primitives every sessionQuery backend has — and returns
engine: "scan". A failure that is not an unavailable index (a real backend
fault) is reported as an error instead, because answering a broken store with a
slower scan of the same broken store helps nobody.

Measured against a real 24-session corpus on this machine:

The index is worth having — that is why the fast path exists. It just cannot be
the only path, and versions of this plugin up to and including 0.1.0 assumed it
was. On every default install they returned
{"error": "session search is disabled…"} for every query. Nothing threw, so it
looked like a working tool that simply never found anything.

To turn the index on, override the bundle row in your profile's
cordis.patch.yml:

- update:
    id: session-query-sqlite
    config:
      path: '~/.dsh/session-index.db'
      openAt: first-search

How it works

The plugin is a thin layer over the harness's sessionQuery service — no parsing, no indexing, no cache of its own:

• searchSessions() — FTS5 full-text search; backs the engine: "index" path of agent_session_search. Optional: present only on the SQLite backend, and only usable when that backend has search enabled. Always called behind a capability check.
• listSessions() — the full session list in deterministic newest-first order; backs agent_session_list and the engine: "scan" fallback.
• filterEvents() — flat, pre-extracted per-event text; backs agent_session_read's event content and, with a text filter, the scan fallback's matching.
• filterSessions() — a safe existence check by id (returns [] rather than throwing for an unknown id); used by agent_session_read before it tries to fetch content.
• readTitle() / readTitleSnapshots() — single and batched title resolution. Session headers carry no title field of their own, so every tool that shows a title resolves it separately through one of these.

All access is read-only. The plugin creates no database, index, or persistent cache of its own — it reads whatever sessionQuery already maintains.

Limitations

• DSH only — does not search Codex, Claude Code, PI, or OpenCode sessions (unlike dsh-session-search).
• Requires sessionQuery — all three tools depend on it; there's no reduced-functionality mode. If the service isn't injected, the plugin registers nothing rather than registering tools that would fail.
• The scan fallback opens sessions one at a time. filterEvents() works per-session and reads that session's whole log, so a search with no matches walks the corpus. maxScan bounds it, and truncated: true tells you when the bound was hit. Enable the index if your corpus is large.
• agent_session_read's event fetch has no cancellation support — filterEvents() doesn't accept an abort signal in the underlying service, so an aborted read still finishes fetching before its result is discarded.

Development

Pure JavaScript, no build step. Source and release are the same file: lib/index.js.

git clone https://github.com/LeslieWylie/dsh-session-search-pro.git
cd dsh-session-search-pro
pnpm install
npm test

Two suites, both of which execute the real lib/index.js — neither is a
source-text or regex check:

• tests/tools.test.mjs drives apply() against a stubbed sessionQuery,
  covering both engines, the fallback, and the argument-validation paths.
• tests/boot.test.mjs boots a real cordis Context, loads the harness's
  own session services, loads this package the way a profile does, and executes
  the tools through the real tool registry.

The second one exists because of how 0.1.0 shipped broken. Its search tool called
sq.searchSessions(...) unconditionally; the unit-test fixture defined its own
searchSessions stub, so every test passed, while on a stock profile the call
threw SESSION_QUERY_SEARCH_DISABLED and the tool returned that config error as
its answer to every query. A stub you write yourself will confirm your own
misconception. So boot.test.mjs checks every sq.<method>() call site in the
source against the service the harness actually ships — requiring unguarded calls
to exist, allowing guarded ones to be absent, and separately confirming that a
guarded method is real on some shipped backend rather than an invention that
would leave the fast path as dead code.

It needs the harness packages, so it exits 0 (skipped) from a bare clone. To
actually run it:

cd ~/.dsh/profiles/<profile>/node_modules/dsh-session-search-pro && node tests/boot.test.mjs

License

MIT © LeslieWylie