@henryqw/pi-session-recall 0.1.8 → 0.2.1

package/README.md

@@ -1,10 +1,12 @@
 # `@henryqw/pi-session-recall`
 
-FTS5 search over past Pi sessions: single `session_search` tool with four arg-inferred modes, zero LLM calls, raw messages only.
+Search past Pi sessions with local FTS5. The `session_search` tool has four modes and makes no model calls.
+
+The package also includes `pi-session-pattern-miner`. This skill finds repeated work that may be worth automating.
 
 ## Why
 
-- **Created for**: Pi users who need to recover decisions and context from prior sessions without keeping every transcript in the active prompt.
+- **Created for**: Recover decisions and context from prior sessions without keeping every transcript in the active prompt.
 - **Advantage**: Local FTS5 search gives fast, private recall with zero standing context cost and no model calls.
 
 ## Install
@@ -17,32 +19,56 @@ pi install npm:@henryqw/pi-session-recall
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `session_search` | tool | Search past sessions or inspect one: discovery (`query`), scroll (`sessionId` + `aroundMessageId`), read (`sessionId`), browse (no args) |
+| `session_search` | tool | Search past sessions or inspect one. |
+| `pi-session-pattern-miner` | skill | Find repeated work and choose the smallest useful automation. |
+
+BM25 is a text-ranking method. Hydrated results include messages read from saved session files.
+
+| Mode | Call | Result |
+| --- | --- | --- |
+| Discovery | `query` | BM25-ranked top sessions. The top hit is hydrated with a ±5 message window and first/last-3 bookends. Lower hits include the matched anchor message and metadata. `detail:"full"` hydrates all. |
+| Scroll | `sessionId` + `aroundMessageId` | ±`window` messages ([1,20]) around the anchor on its branch. Re-anchor on the last or first message ID to scroll. Across forks, pass the previous response's `branchTip`; `aroundMessageId` only centers the window and must lie on that branch. |
+| Read | `sessionId` | The whole session. Large sessions return head 20 + tail 10. Oversized content is bounded to 50k characters and marked with `contentTruncated`. |
+| Browse | no args | Recent sessions with path, name, cwd, started date, and preview. |
+
+In the interactive TUI, the collapsed tool block shows the last five visual lines and the earlier-line count. Press `Ctrl+O` to expand the full bounded response. The model always receives the complete tool result.
 
-**Discovery** — BM25-ranked top sessions; top hit hydrated with a ±5 message window and first/last-3 bookends; lower hits carry the matched anchor message plus metadata (`detail:"full"` hydrates all).
+### Find work worth automating
 
-**Scroll** — ±`window` messages ([1,20]) around the anchor on its branch; scroll forward/backward by re-anchoring on the last/first message id of the returned window. Across forks, pass the previous response's `branchTip` to select the branch — `aroundMessageId` only centers the window and must lie on that branch.
+Run `/skill:pi-session-pattern-miner` to find repeated workflows in past sessions. It requires evidence from two independent sessions and checks for existing automation. It prefers a fixed script when model judgment is not needed.
 
-**Read** — whole session; head 20 + tail 10 when large, with oversized content bounded to 50k characters and flagged by `contentTruncated`.
+### Query syntax and indexed text
 
-**Browse** — recent sessions: path, name, cwd, started date, preview.
+- Prefer distinctive identifiers, package names, issue numbers, or uncommon terms. Use quoted phrases only when exact wording is known.
+- The FTS5 trigram index uses AND for multiple words by default. Use `OR` for breadth, quoted phrases for exact matches, and `NOT` to exclude. Wildcards help only stems ≥3 characters.
+- Only user and assistant text is indexed. Thinking blocks and tool output are not searchable.
+- For message text over the 20,000-character indexing budget, only the first and last regions are indexed. The middle is omitted. Phrases and `NEAR` cannot cross those regions, but ordinary AND terms can.
+- `sessionId` must be a `.jsonl` file under the Pi sessions directory.
 
-Query syntax: Prefer distinctive identifiers, package names, issue numbers, or uncommon terms; use quoted phrases only when exact wording is known. FTS5 over a trigram index — multi-word = AND by default, `OR` for breadth, quoted phrases for exact match, `NOT` to exclude. Wildcards only help stems ≥3 chars. Only user/assistant text is indexed; thinking blocks and tool output are not searchable. For message text over the 20,000-character indexing budget, only first/last regions are indexed and the middle is omitted; phrases and `NEAR` cannot cross those regions, but ordinary AND terms can. `sessionId` must be a `.jsonl` file under the Pi sessions directory.
+### Context and sync
 
-Hits inside the current session's live context are suppressed; compacted-away or inactive-branch history stays discoverable. Forked sessions collapse into their parent when both match.
+Hits inside the current session's live context are suppressed. Compacted-away or inactive-branch history stays discoverable. Forked sessions collapse into their parent when both match.
 
-If the lazy index sync before browse/discovery cannot fully enumerate the session tree, or throws entirely, results are still served from the current index — potentially partially updated and stale: files discovered before the failure may already reflect their new content, while rows for files the walk never reached remain stale — and carry a top-level `syncWarning`: `{kind:"incomplete-walk"}` for a partial walk (indexed-but-unseen paths are never purged in that case), or `{kind:"sync-failed", error}` with the capped failure message. The warning is omitted once a sync completes.
+Before browse or discovery, lazy index sync can fail while walking the session tree. Results still come from the current index and can be partly updated or stale. Files found before failure may have new content, while rows for files the walk did not reach stay stale.
+
+- A partial walk returns top-level `syncWarning`: `{kind:"incomplete-walk"}`. Indexed-but-unseen paths are never purged in that case.
+- A total sync failure returns top-level `syncWarning`: `{kind:"sync-failed", error}` with the capped failure message.
+- The warning is omitted after a completed sync.
 
 ## State
 
-| Path | Purpose |
-| --- | --- |
-| `~/.pi/agent/config/pi-session-recall/index.db` | Derived SQLite search index, maintained by the extension. |
+The extension maintains the derived SQLite search index at `~/.pi/agent/config/pi-session-recall/index.db`.
 
 ## Deliberate exclusions
 
-Session directories whose encoded path starts with `--tmp-` or `--private-tmp-` (sessions run from `/tmp` or `/private/tmp`) are never indexed. Session files over 32 MiB are excluded from indexing and hydration: discovery cannot newly find them; READ/SCROLL return an explicit size error, while a stale discovery hit retained from before the file grew is returned as metadata with empty messages and that error.
+Session directories whose encoded path starts with `--tmp-` or `--private-tmp-` are never indexed. These sessions run from `/tmp` or `/private/tmp`.
+
+Session files over 32 MiB are excluded from indexing and hydration. Discovery cannot newly find them.
+
+READ and SCROLL return an explicit size error. A stale discovery hit from before a file grew returns metadata with empty messages and that error.
 
 ## Storage & privacy
 
-The SQLite index lives at `~/.pi/agent/config/pi-session-recall/index.db`. It is derived state: delete it and it rebuilds from your session files. Everything stays local — transcripts are read in place and nothing leaves the machine beyond what tool results already show the model.
+This is derived state. Delete it and it rebuilds from your session files.
+
+Everything stays local. Transcripts are read in place, and nothing leaves the machine beyond what tool results already show the model.

package/extensions/session-recall.ts

@@ -1,9 +1,10 @@
 /**
  * pi-session-recall entry point: tool registration and mode dispatch.
  */
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, keyHint, truncateToVisualLines } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { realpathSync } from "node:fs";
 import { join, sep } from "node:path";
@@ -119,6 +120,21 @@ export default function (pi: ExtensionAPI): void {
 			limit: Type.Optional(Type.Number({ description: "Max results, [1,10], default 3." })),
 			detail: Type.Optional(StringEnum(["adaptive", "full"] as const)),
 		}),
+		renderResult(result, { expanded }, theme) {
+			const output = result.content.find((part) => part.type === "text")?.text ?? "";
+			const styledOutput = theme.fg("toolOutput", output);
+			if (expanded) return new Text(`\n${styledOutput}`, 0, 0);
+			return {
+				render(width: number) {
+					const preview = truncateToVisualLines(styledOutput, 5, width);
+					if (preview.skippedCount === 0) return ["", ...preview.visualLines];
+					const hint = theme.fg("muted", `... (${preview.skippedCount} earlier lines,`) +
+						` ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+					return ["", truncateToWidth(hint, width, "..."), ...preview.visualLines];
+				},
+				invalidate() {},
+			};
+		},
 		async execute(_toolCallId, rawParams: ToolParams, _signal, _onUpdate, ctx) {
 			try {
 				// LLMs sometimes send numeric ids/queries despite the string schema.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@henryqw/pi-session-recall",
-	"version": "0.1.8",
-	"description": "FTS5 search over past Pi sessions: single tool, four arg-inferred modes (discovery/scroll/read/browse), zero LLM calls.",
+	"version": "0.2.1",
+	"description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
 	"keywords": [
 		"pi-package",
 		"pi",
@@ -15,9 +15,10 @@
 	},
 	"license": "MIT",
 	"files": [
+		"LICENSE",
 		"extensions",
-		"README.md",
-		"LICENSE"
+		"skills",
+		"README.md"
 	],
 	"scripts": {
 		"test": "node --test test/*.test.ts",
@@ -27,6 +28,7 @@
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "^0.84.4",
 		"@earendil-works/pi-coding-agent": "^0.84.4",
+		"@earendil-works/pi-tui": "^0.84.4",
 		"typebox": "^1.3.15"
 	},
 	"repository": {
@@ -43,6 +45,9 @@
 	"pi": {
 		"extensions": [
 			"./extensions/session-recall.ts"
+		],
+		"skills": [
+			"./skills"
 		]
 	}
 }

package/skills/pi-session-pattern-miner/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: pi-session-pattern-miner
+description: Mine repeated work, corrections, and manual procedures from past Pi sessions with session_search, then identify the smallest deterministic script or reusable skill that would prevent repeating them. Use when the user asks what to automate, which workflows recur, or what skill or script should be extracted from prior Pi sessions.
+---
+
+# Pi Session Pattern Miner
+
+Find repeated work in past Pi sessions and turn the best-supported pattern into an automation candidate. Use `session_search` for session history; do not scan Pi session files directly. The current model mines the evidence once; the resulting automation should remove model judgment from recurring execution wherever the workflow permits it.
+
+## Scope
+
+Use the scope or topic in the request. Otherwise sample recent sessions. If the user specifies the current repository, use the current Git root and session `cwd` metadata to filter where possible; search distinctive repository or package names to find related sessions from other worktrees.
+
+State the sampled scope and its limits. `session_search` browse returns at most ten recent sessions, discovery is query-driven, and current live-context matches are suppressed. Its messages contain user/assistant text, not hidden thinking or tool output. Never claim exhaustive coverage or invent commands that are absent from the evidence.
+
+## Mine
+
+1. Call `session_search` with only `limit: 10` to seed the sample.
+2. Read each in-scope session by `sessionId`. For a truncated session, inspect only relevant gaps with `sessionId`, `aroundMessageId`, and `window: 20`; retain `branchTip` while scrolling a fork.
+3. Extract candidate episodes: repeated user intents, corrections, manual procedures, avoidable retries, and agent-authored steps that recur. Ignore generic coding work such as inspect/edit/test unless the same concrete procedure repeats.
+4. Cluster by underlying job, not wording. A pattern needs evidence from at least two independent sessions; do not count forks, retries, or continuations of one task as separate evidence.
+5. Confirm each candidate with one or more distinctive `query` searches using `limit: 10` and `detail: "full"`. Record session path, date or name, relevant entry id, and a short paraphrase. Do not copy secrets or unnecessary transcript text.
+6. Inspect the current repository's commands, package scripts, executable scripts, skills, and agent instructions before proposing anything. Reuse or repair an existing automation when it already owns the workflow.
+
+Stop with “not enough repeated evidence” when fewer than two independent sessions support a pattern. Do not manufacture a recommendation from one occurrence.
+
+## Choose the owning surface
+
+Stop at the first option that fully handles the pattern:
+
+1. **Existing command or skill** — document, fix, or invoke it instead of adding another path.
+2. **Script** — choose when inputs, decisions, outputs, and failures can be specified without model judgment. Prefer a repository command or standard-library script over a new dependency.
+3. **Script plus thin skill** — choose when an agent must gather inputs or explain results, but the repeated operation itself can be deterministic. The skill must call the script rather than restate its algorithm.
+4. **Skill only** — choose only when the reusable work inherently requires judgment, repository inspection, or user decisions.
+5. **Product change** — choose when the root cause belongs in an extension, API, CI check, or other code rather than agent instructions.
+
+A deterministic candidate must define its trigger, inputs, outputs, side effects, failure behavior, and one runnable check. If those cannot be defined from session evidence plus the current codebase, recommend a focused investigation instead of automation.
+
+## Report
+
+Return at most three ranked patterns:
+
+| Pattern | Independent sessions | Repeated cost or failure | Existing coverage | Smallest automation |
+| --- | ---: | --- | --- | --- |
+
+For each pattern, cite the session paths and entry ids, explain why the proposed owning surface fits, and state what model work it removes. Then give the highest-confidence candidate a minimal implementation contract:
+
+- **Trigger and inputs**
+- **Deterministic steps**
+- **Output and side effects**
+- **Failure behavior**
+- **Runnable check**
+- **Files to add or change**
+
+Do not grade the agent, generate a report site, or modify files unless the user asks to implement a candidate.