pi-goosedump 0.8.1 → 0.9.1

package/README.md

@@ -1,93 +1,66 @@
 # pi-goosedump
 
-<img alt="pi-goosedump browser dialog" src="screenshot.png">
+`pi-goosedump` is a pi extension for goosedump-backed session-history search,
+entry expansion, and compaction. It exposes goosedump tools under the `goose_`
+prefix and replaces Pi's default LLM compaction with goosedump-generated
+summaries.
 
-Coding agent context data browser plugin for [pi](https://pi.dev/) using
-[`goosedump`](https://github.com/jarkkojs/goosedump).
-
-## Install
+## Installation
 
 ```bash
 pi install npm:pi-goosedump
 ```
 
-This installs `pi-goosedump` and its `@jarkkojs/goosedump` dependency, which
-includes platform-specific native binaries for Linux, macOS, and Windows.
-
-The upstream `@jarkkojs/goosedump` packages are licensed separately as
-`Apache-2.0 AND LGPL-2.1-or-later`.
-
-## Usage
-
-Once installed, pi-goosedump registers a tool and a slash command:
+This installs `pi-goosedump` and its `@jarkkojs/goosedump` dependency (`^0.9.0`),
+which includes platform-specific native binaries for Linux, macOS, and Windows.
+If the goosedump binary cannot be resolved, the extension disables itself and
+the footer status goes dark.
 
-### Tool: `goosedump`
+## Tools
 
-The agent can browse the current Pi session by default, or any session by its
-8-hex `contextId` (the id shown by `list`):
+- **goose_search:** ranks messages by query relevance; returns compact entry
+  overviews with IDs.
+- **goose_get:** expands specific entry IDs to their full content.
+- **goose_grep:** filters messages by glob pattern; returns compact entries
+  with IDs.
+- **goose_compact:** triggers a goosedump compaction now, optionally keeping
+  the last N user turns verbatim while summarizing everything before.
 
-| Action   | Description                              |
-| -------- | ---------------------------------------- |
-| `list`   | List all available sessions              |
-| `search` | Rank messages by query relevance         |
-| `grep`   | Filter messages by glob pattern          |
-| `expand` | Show full content for specific entry IDs |
-| `view`   | View the full session transcript         |
-
-Examples:
+The read tools (`goose_search`, `goose_get`, `goose_grep`) each accept an
+optional `provider` (default `pi`; also `claude`, `codex`, `crush`, `gemini`,
+`goose`, `opencode`) and `session` id. `session` defaults to the current Pi
+session for `pi` and is required otherwise. `scope` is `lineage` (default,
+current branch) or `all`. Targets are always provider-qualified
+(`provider:id`); a bare id is never sent to goosedump.
 
 ```
-goosedump({ action: "list" })
-goosedump({ action: "search", query: "bug fix" })
-goosedump({ action: "search", contextId: "0000001f", query: "bug fix" })
-goosedump({ action: "grep", pattern: "*rand*" })
-goosedump({ action: "expand", ids: ["entry-a", "entry-b"] })
-goosedump({ action: "view" })
+goose_search({ query: "bug fix" })
+goose_search({ query: "auth", scope: "all", page: 2 })
+goose_get({ ids: ["entry-a", "entry-b"] })
+goose_get({ ids: ["entry-a"], provider: "claude", session: "1f6b1eba-…" })
+goose_grep({ pattern: "*rand*" })
+goose_compact({ keep: 2 })
 ```
 
-#### Other providers
+## Commands
 
-By default the tool browses Pi sessions. Set `provider` (one of `claude`,
-`codex`, `crush`, `gemini`, `goose`, `opencode`, `pi`) with a `contextId` to
-browse another tool's sessions; results render the same way as Pi sessions.
-Non-pi providers have no current session, so they require an explicit
-`contextId`.
+- **`/goose-search [query]`:** search the current session history; accepts a
+  query argument or prompts inline when bare. Shows ranked results in a
+  scrollable panel; press enter to expand an entry to its full content.
+- **`/goose-compact [keep:N]`:** compact now with goosedump. With `keep:N`
+  (N ≥ 1) the last N user turns stay verbatim and everything before is
+  summarized; with no argument goosedump summarizes up to Pi's cut.
+- **`/goose-settings`:** edit the global and project compaction settings.
 
-```
-goosedump({ action: "list", provider: "claude" })
-goosedump({ action: "view", provider: "claude", contextId: "0000001f" })
-```
+## Settings
 
-#### Raw native output
+`pi-goosedump` reads optional JSON settings from:
 
-By default every action renders through the normal structured view. Set
-`outputFormat` to emit the raw native session instead — one of `claude`,
-`codex`, `crush`, `gemini`, `goose`, `opencode`, `pi`, or `json`. JSONL providers
-(`claude`, `codex`, `pi`, `gemini`) emit the raw session file; SQLite providers
-(`crush`, `goose`, `opencode`) emit a row-oriented JSON projection of their
-tables; `json` emits goosedump's structured JSON. This is round-trippable and
-applies to `view`, `expand`, `grep`, and `search`.
+- `~/.pi/agent/settings.json` — Global
+- `.pi/settings.json` — Project
 
-```
-goosedump({ action: "view", outputFormat: "goose" })
-goosedump({ action: "grep", pattern: "*rand*", outputFormat: "claude" })
-```
-
-### Command: `/goosedump`
-
-Opens an interactive dashboard. The sessions tab lists Pi sessions from the
-current working directory only. The settings tab edits the global and project
-`goosedump` settings sections.
-
-### Compaction
-
-pi-goosedump hooks Pi's `/compact` and auto-compaction flow. It resolves the
-current session to its goosedump id and runs `goosedump compact <id>` with Pi's
-compaction range (`--from`, `--until`, and `--scope`) so the generated summary
-matches the entries Pi is about to replace.
-
-An optional goosedump counter can also trigger compaction. `0` disables the counter;
-when it fires, it resets to its configured value.
+Project settings override global settings. All settings live in a `goosedump`
+section and are optional (defaults shown):
 
 ```json
 {
@@ -97,6 +70,32 @@ when it fires, it resets to its configured value.
 }
 ```
 
+`turnsBeforeCompact` sets how many LLM turns elapse before goosedump triggers
+compaction, as an integer 0–255. `0` disables the counter; when enabled, the
+footer status shows `GD: XX` counting down in hex (e.g. `GD: 0A`), or
+`GD: 00` when the counter is disabled.
+
+### Compaction flow
+
+pi-goosedump hooks Pi's `session_before_compact` event — fired by manual
+`/compact`, the turn counter above, and Pi's own auto-compaction — and
+substitutes a goosedump summary for Pi's LLM summary. It resolves the current
+session to its goosedump context by reading the `id` field from the session
+header line, then runs `goosedump compact` over the replacement range:
+
+- `--from` is the entry following the most recent prior compaction (so the
+  summary starts where the previous one left off); omitted on the first
+  compaction.
+- `--until` is the first entry Pi is keeping (`firstKeptEntryId`).
+
+goosedump composes the structured summary itself — including merging any prior
+summary — and emits a native Pi compaction entry, from which the extension
+extracts the `summary` field. A `keep:N` override (via `/goose-compact` or the
+`goose_compact` tool) replaces Pi's token-based cut with a turn-based one:
+summarize everything before the Nth-from-last user entry and keep the tail
+verbatim. Fewer than N user turns cancels with a notice. On completion Pi
+notifies the token reduction.
+
 ## License
 
 `pi-goosedump` is licensed under `MIT`. See [LICENSE](LICENSE) for more