opencode-sessions-explorer 0.1.0 → 0.1.2

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)

package/docs/support/troubleshooting.md

@@ -0,0 +1,230 @@
+# Troubleshooting
+
+## How To Use This Page
+
+Find the symptom that matches what you are seeing, run its quick checks, then apply
+the fix. Each block is phrased the way the problem usually appears — an error code in
+a tool response, an empty result, or a failed restore. Run the baseline checks below
+first; they resolve or explain most issues on their own.
+
+## Baseline Checks
+
+Two commands cover the health of every layer the plugin depends on.
+
+1. Probe the install end to end:
+
+   ```bash
+   bunx opencode-sessions-explorer-check-deps
+   ```
+
+   This reports database reachability, schema head and drift, SQLite `json1`,
+   `busy_timeout`, export tree presence, curated channel views, `ck` CLI, `ck`
+   index, and the tool-output directory. Add `--json` for machine-readable output.
+
+2. Probe the database from inside OpenCode with the `db-stats` tool. It returns the
+   migration head, table counts, json1 status, `busy_timeout`, and any schema-drift
+   warnings.
+
+If both come back clean, the plugin core is healthy and the issue is likely scoped
+to one tool or to the optional `ck` search path.
+
+## Plugin Tools Do Not Appear After Config Change
+
+OpenCode starts, but the `opencode-sessions-explorer-*` tools are not available to
+the model after editing config.
+
+Quick checks:
+
+- Confirm you edited the active OpenCode config path, usually
+  `~/.config/opencode/opencode.json`.
+- Confirm the `plugin` array contains either the package spec
+  (`"opencode-sessions-explorer"` or a pinned version) or an absolute local path.
+- Confirm you fully quit and restarted OpenCode; do not assume plugin hot reload.
+- If using source TypeScript, confirm the path to `src/plugin.ts` exists.
+- If using built JavaScript, confirm `bun run build` produced `dist/plugin.js`.
+- Confirm `src/plugin.ts` exports only the plugin function; extra non-function
+  exports can make OpenCode reject the plugin entrypoint.
+
+Fix:
+
+- Correct the config, then fully restart OpenCode.
+- For source checkouts, see the supported source TS and built JS options in
+  [install.md#from-source-dev](../install.md#from-source-dev).
+- If a local source path still fails, run a local import check from the checkout:
+
+  ```bash
+  bun -e 'import("./src/plugin.ts").then((m) => { if (typeof m.default !== "function") throw new Error("default export is not a function") })'
+  ```
+
+## Search Returns CK_NOT_FOUND
+
+`search-text` or `grep-session` returns the error code `CK_NOT_FOUND`.
+
+Quick checks:
+
+- Confirm whether `ck` is installed and on `PATH`: `ck --version`.
+- Run `bunx opencode-sessions-explorer-check-deps` and look at the `ck` line.
+
+Fix:
+
+- Install [`ck`](https://github.com/BeaconBay/ck) (>= 0.7). If it is installed
+  outside `PATH`, point the plugin at it with
+  `OPENCODE_SESSIONS_EXPLORER_CK_BIN=/abs/path/to/ck`.
+- `ck` is only needed for `search-text` and `grep-session`. The other 16 tools work
+  without it, so recall, browse, cost, and analysis tools remain available
+  meanwhile. See [configuration.md](../reference/configuration.md).
+
+## Database Not Found
+
+A tool returns `DB_NOT_FOUND`, or `check-deps` fails the "OpenCode DB" line.
+
+Quick checks:
+
+- Confirm the database exists at the default path
+  (`~/.local/share/opencode/opencode.db` on common macOS/Linux installs).
+- Confirm OpenCode has run at least once so the database has been created.
+
+Fix:
+
+- If the database lives elsewhere, set `OPENCODE_SESSIONS_EXPLORER_DB` to its
+  absolute path. If `$XDG_DATA_HOME` or Windows `%LOCALAPPDATA%` changes the data
+  root, use that actual path.
+- If the path is correct but access is blocked, add the `external_directory`
+  permission rule (next block) and restart OpenCode.
+- See [configuration.md](../reference/configuration.md) for the full override table.
+
+## Search Finds Nothing
+
+A search returns zero hits for a term you expect to exist.
+
+Quick checks:
+
+- Confirm the export tree has been materialized at least once.
+- Note whether the session you expect is very new — its parts may not be exported
+  yet.
+- Confirm the term is not being narrowed away by `role`, `surface`, or a time/scope
+  filter.
+
+Fix:
+
+- Run the one-time export, then retry:
+
+  ```bash
+  bunx opencode-sessions-explorer-bulk-export
+  ```
+
+- New parts are delta-synced automatically before each `search-text` /
+  `grep-session` call, so a missing recent part usually resolves on the next search.
+- Widen the search: try `surface:'forensics'` (or `channels:['raw']`) to include raw
+  bodies, and confirm `role` is `any`. See
+  [search-surfaces.md](../reference/search-surfaces.md).
+
+## grep-session Returns INDEX_MISSING
+
+`grep-session` returns `INDEX_MISSING`, usually with a message that the session is
+not in the export tree.
+
+Quick checks:
+
+- Verify the `session_id` is correct with `get-session` or `list-sessions`.
+- Confirm the export tree exists and includes that session under `by-session/`.
+- If you requested a curated surface/channel, confirm channel views are complete in
+  `check-deps`.
+
+Fix:
+
+- Run the one-time export, then retry `grep-session`:
+
+  ```bash
+  bunx opencode-sessions-explorer-bulk-export
+  ```
+
+- If the session is very new, retry after the tool's auto-sync has had a chance to
+  export recent parts.
+- If channel views are partial or missing, rebuild them:
+
+  ```bash
+  bunx opencode-sessions-explorer-bulk-export --reset
+  ```
+
+## Permission Denied / external_directory
+
+A tool cannot reach the database even though the path is correct, or OpenCode
+reports an external-directory permission error.
+
+Quick checks:
+
+- Confirm the `external_directory` allow rule is present in your OpenCode config.
+- Confirm you fully restarted OpenCode after editing the config.
+
+Fix:
+
+- Add the allow rule and restart OpenCode:
+
+  ```jsonc
+  // ~/.config/opencode/opencode.json
+  {
+    "permission": {
+      "external_directory": {
+        "~/.local/share/opencode/**": "allow"
+      }
+    }
+  }
+  ```
+
+- The database lives outside your project workspace, so this rule is required. The
+  default snippet covers the common macOS/Linux path. If `$XDG_DATA_HOME`, Windows
+  `%LOCALAPPDATA%`, or `OPENCODE_SESSIONS_EXPLORER_DB` points elsewhere, allow the
+  actual containing directory and restart. Some global configs use
+  `external_directory: "allow"`; that also permits access, but a scoped allow rule is
+  preferred for normal users. The change only takes effect after a full restart. See
+  [configuration.md](../reference/configuration.md).
+
+## Schema Drift Warnings
+
+A tool returns `SCHEMA_DRIFT`, or `db-stats` / `check-deps` reports drift warnings.
+
+Quick checks:
+
+- Run `db-stats` and read `migrations_head` and `drift_warnings`.
+- Run `bunx opencode-sessions-explorer-check-deps` and check the schema line.
+- Note whether you recently upgraded OpenCode.
+
+Fix:
+
+- Drift warnings usually mean the installed OpenCode version moved the database
+  schema ahead of (or behind) what the plugin expects. Align the plugin version with
+  your OpenCode version.
+- If the warning is soft, read tools still work; treat the warning as a prompt to
+  update. If `hard_drift` is reported, update the plugin before relying on affected
+  tools.
+
+## get-part Returns PATH_TRAVERSAL
+
+`get-part` with `dereference_output_path:true` returns `PATH_TRAVERSAL`.
+
+Quick checks:
+
+- Confirm the part's externalized output path resolves inside the tool-output
+  directory.
+- Confirm `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR`, if set, points at the
+  directory that actually holds the externalized files.
+
+Fix:
+
+- Dereference is deliberately whitelisted to the tool-output directory; any path
+  outside it (including a symlink that escapes the root) is rejected by design. This
+  is a guardrail, not a bug.
+- If your externalized output lives in a non-default location, set
+  `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` to that root and retry. See
+  [configuration.md](../reference/configuration.md) and the redaction/guard policy in
+  [SECURITY.md](../../.github/SECURITY.md).
+
+## Related Docs
+
+- Tool catalog: [../reference/tools.md](../reference/tools.md)
+- Configuration and environment overrides: [../reference/configuration.md](../reference/configuration.md)
+- Search surfaces and channels: [../reference/search-surfaces.md](../reference/search-surfaces.md)
+- Four-layer architecture: [../reference/architecture.md](../reference/architecture.md)
+- Export and maintenance workflow: [../guides/export-and-maintenance.md](../guides/export-and-maintenance.md)
+- Data exposure and redaction policy: [../../.github/SECURITY.md](../../.github/SECURITY.md)

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-sessions-explorer",
-  "version": "0.1.0",
-  "description": "OpenCode plugin: access to every prior OpenCode session on this machine — recall, search/grep, and historical analysis via 18 LLM-discoverable tools (17 read-only plus one write, unarchive-session).",
+  "version": "0.1.2",
+  "description": "OpenCode plugin for recall and analysis of past OpenCode sessions: search, grep, and cost/usage insights across your session history via 18 LLM tools (17 read-only plus one write, unarchive-session).",
   "keywords": [
     "opencode",
     "opencode-plugin",
@@ -34,6 +34,7 @@
   "files": [
     "dist/",
     "types/",
+    "docs/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -67,8 +68,8 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.15.10",
+    "@opencode-ai/plugin": "1.17.4",
     "@types/bun": "latest",
-    "typescript": "^5.4.0"
+    "typescript": "^6.0.3"
   }
 }