LeslieWylie/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.

The package ships its own cordis.patch.yml, so once it's installed into the profile's node_modules you can mount it for a single run with the launcher's --patch flag instead of touching dsh.profile.bundles:

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).

Aspect	dsh-session-search (Tieboyh)	dsh-session-search-pro
Search method	Reads and scans session files directly	Harness sessionQuery — FTS5 index when enabled, bounded scan otherwise
Current (in-progress) session	❌ Not searchable	✅ Searchable
Session file format	Parsed directly (zstd frame scan)	Never touched — harness API only
External sources	codex, claude, pi, opencode	DSH only (single runtime)
Tool count	2 tools	3 tools (search + list + read)
Long event text	Capped at 4,000 chars	Capped at 4,000 chars per event
Dependencies	ripgrep, node:zlib	None (zero runtime dependencies)

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.

Parameter	Type	Required	Description
query	string	✅	Text to find. Case-insensitive, whitespace-flexible, and matched literally — regex metacharacters have no special meaning.
limit	number	—	Maximum sessions to return, 1–50. Defaults to the plugin's maxResults config (10 unless overridden).
maxScan	number	—	Maximum sessions to open when falling back to a scan, 1–500. Defaults to the plugin's maxScan config (200). Ignored when the index is in use.

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.

Parameter	Type	Required	Description
limit	number	—	Maximum sessions to return, 1–100. Default 20.
cwd	string	—	Substring filter over the session's working directory.
sort	"newest" | "oldest"	—	Sort order. Default newest.

agent_session_read

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

Parameter	Type	Required	Description
sessionId	string	✅	The session id to read, e.g. "a4d75296-fc89-44b1".
maxEvents	number	—	Maximum events to return, most recent first, 1–200. Default 50.

Plugin config

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

Key	Default	Description
maxResults	10	Default limit for agent_session_search when the caller omits it.
maxScan	200	Default maxScan for agent_session_search — how many sessions the fallback scan may open.

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:

	index (openAt: first-search)	scan (stock openAt: never)
term that matches	3 hits	3 hits
term that matches nothing	17 ms	3,042 ms

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