opencode-sessions-explorer 0.1.1 → 0.1.2

package/docs/reference/configuration.md

@@ -0,0 +1,115 @@
+# Configuration Reference
+
+## Scope
+
+This page documents how to configure `opencode-sessions-explorer`: the OpenCode
+`permission` rule the plugin needs, the environment variables that override every
+filesystem path, and the opt-in switch for running the test suite against real
+session data.
+
+The plugin has no settings object of its own — it is configured entirely through
+OpenCode permissions and environment variables. All defaults work out of the box on
+macOS and Linux; Windows paths resolve via `%LOCALAPPDATA%`.
+
+## Required Permission
+
+The OpenCode session database lives outside your project workspace, so OpenCode
+must be granted access to its data directory. Add an `external_directory` allow rule
+to your OpenCode config and restart:
+
+```jsonc
+// ~/.config/opencode/opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-sessions-explorer"],
+  "permission": {
+    "external_directory": {
+      "~/.local/share/opencode/**": "allow"
+    }
+  }
+}
+```
+
+Without this rule the read-only database handle cannot open the file and tools fail
+with `DB_NOT_FOUND` or a permission error. The change takes effect only after a full
+OpenCode restart. See [Permission Denied / external_directory](../support/troubleshooting.md#permission-denied--external_directory)
+if a tool still cannot reach the database after adding the rule.
+
+The snippet above covers the common macOS/Linux default path. If `$XDG_DATA_HOME`,
+Windows `%LOCALAPPDATA%`, or `OPENCODE_SESSIONS_EXPLORER_DB` points to another
+database location, allow the actual directory that contains `opencode.db` and
+restart OpenCode. Some existing global configs may set `external_directory: "allow"`;
+that grants broad access and is useful for local power users, but the scoped path
+rule is preferred for normal installs.
+
+## Runtime Compatibility
+
+The plugin targets the OpenCode plugin host contract provided by
+`@opencode-ai/plugin >= 1.15.0`. It runs on Bun and uses `bun:sqlite`, which should
+include SQLite `json1`; the bundled health probes (`check-deps` CLI and `db-stats`
+tool) verify `json1`, schema drift, and database runtime settings for the active
+OpenCode database.
+
+## Environment Overrides
+
+Every path the plugin uses is overridable through an environment variable. These are
+the simplest way to point the plugin (or its tests) at non-default locations.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPENCODE_SESSIONS_EXPLORER_DB` | `$XDG_DATA_HOME/opencode/opencode.db` (macOS/Linux) or `%LOCALAPPDATA%\opencode\opencode.db` (Windows); falls back to `~/.local/share/opencode/opencode.db` | Absolute path to the OpenCode SQLite database the plugin reads. Set this when the database is not in the default OpenCode data directory. |
+| `OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT` | `~/.local/share/opencode-sessions-explorer` | Directory where searchable session content is materialized (the `by-session` and `by-channel` export trees that `ck` indexes). |
+| `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` | `$XDG_DATA_HOME/opencode/tool-output` (macOS/Linux) or `%LOCALAPPDATA%\opencode\tool-output` (Windows); falls back to `~/.local/share/opencode/tool-output` | Whitelist root for `get-part` dereference. Only files resolving inside this root may be read when `dereference_output_path:true`; any other path is rejected with `PATH_TRAVERSAL`. |
+| `OPENCODE_SESSIONS_EXPLORER_CK_BIN` | `ck` discovered on `PATH` | Absolute path to the `ck` binary. Set this when `ck` is installed outside `PATH`; only `search-text` and `grep-session` use it. |
+
+### `get-part` Dereference Guard
+
+The `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` whitelist is enforced before any
+externalized tool output is read. Symlinks are resolved before the path is compared
+to the root, so a symlink inside the whitelist that points outside it is also
+rejected. This is why `get-part` returns `PATH_TRAVERSAL` for any path outside the
+tool-output directory — see the troubleshooting page for the recovery steps.
+
+## Testing Override (Dev Only)
+
+`bun test` is hermetic by default and runs against a synthetic fixture database. To
+exercise the suite against real session data instead, opt in with:
+
+```bash
+OPENCODE_SESSIONS_EXPLORER_LIVE=1 bun test
+```
+
+Live runs read real `ses_`/`msg_`/`prt_` ids and minimum counts from your own
+history, so failures there reflect local data rather than a regression. This switch
+is for contributors only and has no effect on the plugin at runtime; see the
+[Development Guide](../maintainers/development.md) for the full contributor loop.
+
+## Examples
+
+Point the plugin at a database in a custom location:
+
+```bash
+export OPENCODE_SESSIONS_EXPLORER_DB="/data/opencode/opencode.db"
+```
+
+Materialize the search export to a dedicated disk:
+
+```bash
+export OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT="/fast-ssd/opencode-search"
+bunx opencode-sessions-explorer-bulk-export
+```
+
+Use a `ck` binary that is not on `PATH`:
+
+```bash
+export OPENCODE_SESSIONS_EXPLORER_CK_BIN="$HOME/.cargo/bin/ck"
+```
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Data exposure and redaction policy: [../../.github/SECURITY.md](../../.github/SECURITY.md)
+- Install walkthrough: [../install.md](../install.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)

package/docs/reference/response-format.md

@@ -0,0 +1,120 @@
+# Response Format Reference
+
+## Scope
+
+This page documents the compact, lossless format that list-shaped tool results use.
+Several tools return arrays of uniform records (sessions, events, tool calls, cost
+groups, search hits). Serializing those as plain arrays-of-objects repeats every
+JSON key on every row and re-serializes the same nested values (model, directory,
+agent) again and again. To cut payload size without losing information, list results
+are encoded as a columnar table with string interning.
+
+Scalar, single-object responses (for example `get-session` or `db-stats`) are
+returned as ordinary JSON objects and are **not** encoded this way.
+
+## The Table Shape
+
+An encoded list result is an object with three keys:
+
+```json
+{
+  "cols": ["id", "title", "agent", "model"],
+  "dict": {
+    "agent": ["build", "executor-gpt"],
+    "model": [{ "id": "claude-opus", "provider": "anthropic" }]
+  },
+  "rows": [
+    ["ses_a1", "Fix retry bug", 0, 0],
+    ["ses_b2", "Cost audit", 1, 0]
+  ]
+}
+```
+
+- `cols` — the column order; each row is an array of cells in this order.
+- `dict` — interning tables for selected columns. A column listed here stores its
+  distinct values once; rows reference them by integer index. Columns absent from
+  `dict` store their literal value inline.
+- `rows` — one array per record.
+
+## Decode Rule
+
+There is a single decode rule:
+
+> A cell in a column whose name is a key in `dict` is an integer index into
+> `dict[col]`. Otherwise the cell is its literal value.
+
+Decoding the example above yields:
+
+```json
+[
+  { "id": "ses_a1", "title": "Fix retry bug", "agent": "build", "model": { "id": "claude-opus", "provider": "anthropic" } },
+  { "id": "ses_b2", "title": "Cost audit", "agent": "executor-gpt", "model": { "id": "claude-opus", "provider": "anthropic" } }
+]
+```
+
+Note that both rows reuse the same `model` object (index `0`) instead of repeating
+it — that is where the savings come from on large result sets.
+
+## Reference Decoder
+
+The plugin ships the inverse function, `decodeTable()`, in
+[`src/lib/table.ts`](../../src/lib/table.ts). It is used by the test suite and is
+safe for consumers to copy. Two behaviors make migration painless:
+
+- A plain array passed to `decodeTable()` is returned unchanged, so callers can
+  treat encoded and unencoded results uniformly.
+- An out-of-range or non-integer cell in a `dict` column is passed through as its
+  literal value rather than throwing.
+
+A minimal equivalent decoder:
+
+```ts
+function decodeTable(t) {
+  if (t == null) return []
+  if (Array.isArray(t)) return t // already plain
+  const dict = t.dict ?? {}
+  return t.rows.map((row) => {
+    const o = {}
+    t.cols.forEach((c, i) => {
+      const v = row[i]
+      const d = dict[c]
+      o[c] = d && typeof v === "number" && v >= 0 && v < d.length ? d[v] : v
+    })
+    return o
+  })
+}
+```
+
+## Examples
+
+A `list-sessions` result interns the repetitive `agent`, `model`, `directory`, and
+`project_id` columns:
+
+```json
+{
+  "sessions": {
+    "cols": ["id", "title", "agent", "model", "directory", "cost"],
+    "dict": {
+      "agent": ["build"],
+      "model": [{ "id": "claude-opus" }],
+      "directory": ["/projects/app"],
+      "project_id": []
+    },
+    "rows": [
+      ["ses_a1", "Fix retry bug", 0, 0, 0, 0.42]
+    ]
+  },
+  "has_more": false
+}
+```
+
+Apply the decode rule to recover the records, then read `cost` (a literal column)
+directly.
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Configuration and environment overrides: [configuration.md](configuration.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)

package/docs/reference/search-surfaces.md

@@ -0,0 +1,106 @@
+# Search Surfaces Reference
+
+## Scope
+
+This page documents the retrieval presets (`surface`) and the underlying channels
+that `search-text` and `grep-session` use to decide *what* exported content to
+search. Raw session data always stays lossless in the database and export tree;
+channels are derived search views that let default recall search high-signal content
+first while preserving raw drill-down through part and message ids.
+
+Both tools accept a `surface` argument and an optional `channels` override. If you
+pass `channels` explicitly, it takes precedence over the surface-derived set.
+
+## Surfaces
+
+A surface is a named preset that expands to a curated set of channels. The default
+is `recall`.
+
+| Surface | Channels Searched | Use For |
+| --- | --- | --- |
+| `recall` | `conversation`, `session-summary` | Default. Session-first, high-signal recall — "where did I mention X", "find sessions about Y". |
+| `debug_trace` | `conversation`, `session-summary`, `tool-error`, `tool-input-summary` | Investigating failures and what led to them — errors, exceptions, stack traces, logs. |
+| `tool_audit` | `tool-input-summary`, `tool-error` | Auditing tool usage — bash commands, tool calls, MCP calls, and their errors. |
+| `code` | `conversation`, `session-summary`, `code-touch`, `patch-summary`, `tool-input-summary` | Tracing file and code changes — paths, diffs, edits, patches. |
+| `forensics` | `raw` | Exhaustive replay over raw exported bodies, including full tool output and reasoning. Slowest; use when curated channels miss something. |
+
+### Surface Inference
+
+When `surface` is left at its default (`recall`), the query text is inspected and
+the surface may be auto-promoted:
+
+- Error vocabulary (`error`, `exception`, `stack trace`, `failed`, `timeout`,
+  `logs`, `stderr`, `stdout`) promotes to `debug_trace`.
+- Tool vocabulary (`tool calls`, `bash`, `command`, `grep`, `read tool`,
+  `edit tool`, `apply_patch`, `mcp`, …) promotes to `tool_audit`.
+- Code vocabulary (`file`, `path`, `class`, `function`, `symbol`, `diff`, `patch`,
+  `edited`, `src/`, `.ts`, `.kt`, `.py`, …) promotes to `code`.
+
+Passing an explicit non-`recall` surface disables inference and uses that surface
+as-is.
+
+## Channels
+
+Channels are the derived views the export tree materializes under
+`by-channel/<channel>/by-session/<ses_id>/`. The raw, lossless export lives under
+`by-session/<ses_id>/` and is reachable through the `raw` channel.
+
+| Channel | Contents |
+| --- | --- |
+| `conversation` | User and assistant text, plus subtask prompts. |
+| `session-summary` | Per-session synthesized summary: title, directory, first and last user prompt. |
+| `tool-input-summary` | Compact summary of each tool invocation's inputs (command, paths, query, ids). |
+| `tool-error` | Normalized error text from failed tool calls. |
+| `code-touch` | File paths touched by file tools and patches. |
+| `tool-output` | Raw output bodies produced by tool calls. |
+| `patch-summary` | Files changed per patch, with hash and file count. |
+| `reasoning` | Assistant reasoning text. |
+| `file` | File-reference parts (filename, URL, source path). |
+| `raw` | The full-fidelity per-session export, including every searchable body. Selected by the `forensics` surface. |
+
+## Grep Defaults
+
+`grep-session` defaults to the same curated channels as the active surface
+(`recall` → `conversation`, `session-summary`) when the curated channel export is
+available. To search the raw exported bodies of a single session — including tool
+output and reasoning — set `surface:'forensics'` or pass `channels:['raw']`.
+
+If the curated channel export is only partial (not yet backfilled), both tools fall
+back to the raw `by-session` export to avoid false negatives and add a warning;
+running `opencode-sessions-explorer-bulk-export --reset` backfills the curated
+channels. See [export-and-maintenance.md](../guides/export-and-maintenance.md).
+
+## Examples
+
+Default recall search across all sessions:
+
+```text
+opencode-sessions-explorer-search-text { "q": "rate limiting" }
+```
+
+Force a raw forensic sweep with explicit channels:
+
+```text
+opencode-sessions-explorer-search-text { "q": "AKIA", "surface": "forensics" }
+```
+
+Grep one session's raw bodies (tool output included):
+
+```text
+opencode-sessions-explorer-grep-session { "session_id": "ses_…", "pattern": "ETIMEDOUT", "channels": ["raw"] }
+```
+
+Audit tool inputs and errors only:
+
+```text
+opencode-sessions-explorer-search-text { "q": "git push", "surface": "tool_audit" }
+```
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Compact result format: [response-format.md](response-format.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Search and grep workflow: [../guides/search-and-grep.md](../guides/search-and-grep.md)
+- Export and maintenance workflow: [../guides/export-and-maintenance.md](../guides/export-and-maintenance.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)

package/docs/reference/tools.md

@@ -0,0 +1,151 @@
+# Tools Reference
+
+## Scope
+
+This page is the complete catalog of the tools `opencode-sessions-explorer`
+registers with the LLM. There are 18 tools: 17 are read-only and one
+(`unarchive-session`) performs a single, deliberate write. Every tool is exposed
+under the public key `opencode-sessions-explorer-<name>`; the short names below
+(for example `get-session`) are used for brevity.
+
+Tools are grouped by intent. The `Read/Write` column states whether the tool only
+reads the OpenCode session database or mutates it. For the curated search surfaces
+and channels that `search-text` and `grep-session` accept, see
+[search-surfaces.md](search-surfaces.md). For the compact result shape that
+list-shaped tools return, see [response-format.md](response-format.md).
+
+## Recall And Navigation
+
+Find your bearings and pull conversation content by id.
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `current-session` | Identifies the session the assistant is currently running in: id, message id, agent, model, directory, worktree, parent, cost-so-far, message/part/tool-call counters, child sessions, and useful filesystem paths (database, export tree, this session's export dir + `meta.json`). Pass `detail:'full'` for counters, children, and paths. | Read |
+| `get-session` | Fetches one session's metadata and aggregate counts by id (parts by type, tool-call status breakdown, immediate child session ids). Returns no message bodies. | Read |
+| `session-summary` | One-call human-readable overview: metadata, first and last user prompt, top files touched, top tools used (with completed/error counts), error count, duration, and cost. | Read |
+| `session-timeline` | Chronological event stream — one row per part with a short per-type summary and no raw bodies. Filter by part type and time window; cursor-paginated. | Read |
+| `get-message` | Fetches one message and its parts by message id. Each part body is capped via `max_part_bytes` to keep the response bounded. | Read |
+| `get-part` | Fetches one fully decoded part by id. Optionally dereferences an externalized tool-output file when `dereference_output_path:true` (path-guarded — see [configuration.md](configuration.md)). | Read |
+
+## Genealogy
+
+Trace how sessions relate.
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `session-genealogy` | Walks the session parent/child tree to trace subagent dispatches and pair-execution chains. `direction` selects `ancestors` (up the `parent_id` chain), `descendants` (down to child sessions), or `both`. Depth-bounded by `max_depth`. | Read |
+
+## Browse And Filter
+
+List and filter sessions by structured metadata. Both return metadata only — never
+message bodies.
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `list-sessions` | Browses sessions newest-first with combinable structured filters: `project_id`, `agent`, `model_id`, `directory_prefix`, `archived`, `since_ms`/`until_ms`, and `title_like`. Cursor-paginated. | Read |
+| `search-sessions-meta` | Filters sessions by structured metadata plus cost/token thresholds (`min_cost`, `min_tokens_input`) — the same envelope as `list-sessions` with spend filters added. | Read |
+
+## Content Search (ck-backed)
+
+Search the bodies of sessions and the tool calls inside them. `search-text` and
+`grep-session` shell out to the optional [`ck`](https://github.com/BeaconBay/ck)
+CLI; if `ck` is absent they return `CK_NOT_FOUND` cleanly and the other tools keep
+working. `search-tool-calls` queries the database directly and does not need `ck`.
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `search-text` | Full-text search across the bodies of all sessions (user prompts, assistant responses, tool input/output, reasoning, file references, patches, subtask prompts). Surface- and channel-aware; supports `regex`, `lex` (BM25), `sem`, and `hybrid` modes, a `role` filter, and `group_by_session` rollups. | Read |
+| `grep-session` | grep/regex search inside one session's exported body content (fast; operates on that session's part files only). Supports `fixed_string`, `case_sensitive`, `whole_word`, and `context_lines`. | Read |
+| `search-tool-calls` | Finds tool invocations across sessions, filtered by tool name (exact or `LIKE` wildcard), status, or substring on input/output/error. Returns capped snippets; cursor-paginated, newest-first. | Read |
+
+## Cost And Usage Analysis
+
+Aggregate spend, tokens, failures, and prompt patterns.
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `cost-by-project` | Aggregates cost and token usage grouped by `project_id`, `directory`, `agent`, or `model`, sorted by cost. Surfaces a `cost_known` flag for groups whose sessions predate the usage-tracking migration. | Read |
+| `cost-by-period` | Time-series cost and tokens bucketed by `day`, `week`, or `month`, newest-first. Supports `tz_offset_min` to shift bucket boundaries to a local day. | Read |
+| `list-tool-failures` | Aggregates tool errors grouped by `tool`, `error` message prefix, or `session`, sorted by count. | Read |
+| `list-repeated-prompts` | Clusters sessions by the normalized prefix of their first user prompt to surface "have I asked this before" patterns. | Read |
+
+## Health
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `db-stats` | Health and schema-drift probe for the OpenCode SQLite database: migration head, table counts (session/message/part), json1 status, `busy_timeout`, and drift warnings. | Read |
+
+## Write
+
+The single mutation surface in the plugin.
+
+| Tool | What It Does | Read/Write |
+| --- | --- | --- |
+| `unarchive-session` | Restores a previously archived session: clears `session.time_archived` **and** refreshes `session.time_updated` so the session resurfaces at the top of OpenCode's recency-ordered list. Returns `NOT_FOUND` only when the id does not exist. | **Write** |
+
+The write is intentionally narrow: it runs through an isolated, short-lived
+read-write connection while every other tool uses a read-only handle. The
+`time_updated` refresh is required, not cosmetic — OpenCode loads sessions ordered
+by `time_updated DESC` with a default limit per directory, so a long-archived
+session would otherwise stay buried below that window and fail to open. See
+[architecture.md](architecture.md) for the single-writer model.
+
+### CLI Executables
+
+These ship as standalone commands (run with `bunx`) for materializing and
+maintaining the search export and for verifying install health.
+
+| Executable | What It Does |
+| --- | --- |
+| `opencode-sessions-explorer-bulk-export` | Materializes (and incrementally refreshes) the filesystem search export tree. `--reset` rebuilds from scratch; `--root <path>` targets a non-default export root. |
+| `opencode-sessions-explorer-dedupe-export` | One-shot maintenance that removes duplicate part files (same part id, different sequence prefix). Dry-run by default; pass `--apply` to delete. |
+| `opencode-sessions-explorer-check-deps` | Install health probe: database reachability, schema head and drift, SQLite `json1`, `busy_timeout`, export tree, channel views, `ck` CLI and index, and tool-output directory. `--json` emits machine-readable output. |
+
+## Examples
+
+Identify the current session, then summarize it:
+
+```text
+opencode-sessions-explorer-current-session   # returns this session's id
+opencode-sessions-explorer-session-summary { "session_id": "ses_…" }
+```
+
+Find every failed `read` tool call in the last week:
+
+```text
+opencode-sessions-explorer-search-tool-calls { "tool": "read", "status": "error", "since_ms": 1717200000000 }
+```
+
+Search all sessions for a topic, rolled up per session:
+
+```text
+opencode-sessions-explorer-search-text { "q": "retry backoff", "group_by_session": true }
+```
+
+Fresh install health flow:
+
+```bash
+bunx opencode-sessions-explorer-check-deps  # warnings for missing export/ck are okay initially
+bunx opencode-sessions-explorer-bulk-export
+bunx opencode-sessions-explorer-check-deps
+```
+
+Restore an archived session you located with `archived:'only'`:
+
+```text
+opencode-sessions-explorer-list-sessions { "archived": "only" }
+opencode-sessions-explorer-unarchive-session { "session_id": "ses_…" }
+```
+
+## Related Docs
+
+- Configuration and environment overrides: [configuration.md](configuration.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Compact result format: [response-format.md](response-format.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Recall and navigation workflow: [../guides/recall-and-navigation.md](../guides/recall-and-navigation.md)
+- Search and grep workflow: [../guides/search-and-grep.md](../guides/search-and-grep.md)
+- Cost and usage analysis workflow: [../guides/cost-and-usage-analysis.md](../guides/cost-and-usage-analysis.md)
+- Export and maintenance workflow: [../guides/export-and-maintenance.md](../guides/export-and-maintenance.md)
+- Managing archived sessions: [../guides/manage-archived-sessions.md](../guides/manage-archived-sessions.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)