@henryqw/pi-session-recall 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# `@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.
+
+## Why
+
+- **Created for**: Pi users who need to 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
+
+```bash
+pi install npm:@henryqw/pi-session-recall
+```
+
+## Use
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `session_search` | tool | Search past sessions or inspect one: discovery (`query`), scroll (`sessionId` + `aroundMessageId`), read (`sessionId`), browse (no args) |
+
+**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).
+
+**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.
+
+**Read** — whole session; head 20 + tail 10 when large, with oversized content bounded to 50k characters and flagged by `contentTruncated`.
+
+**Browse** — recent sessions: path, name, cwd, started date, preview.
+
+Query syntax: 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.
+
+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.
+
+## 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.
+
+## 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.
+
+## Remove
+
+```bash
+pi remove npm:@henryqw/pi-session-recall
+```
+
+Delete `~/.pi/agent/config/pi-session-recall/` to reclaim index disk space.
+
+## Development
+
+```bash
+npm test --workspace @henryqw/pi-session-recall
+npm run typecheck --workspace @henryqw/pi-session-recall
+npm run pack:check --workspace @henryqw/pi-session-recall
+```

package/extensions/hydrate.ts

@@ -0,0 +1,253 @@
+/**
+ * Hydration: direct JSONL parsing of Pi session files (never SessionManager.open —
+ * it rewrites legacy files), branch-aware windows/bookends, READ head/tail.
+ * Pure functions over file paths; no SQLite access.
+ */
+/// <reference types="node" />
+import { MAX_SESSION_FILE_BYTES, readBoundedSnapshot } from "./search-core.ts";
+import type { WindowMessage } from "./types.ts";
+
+export interface WindowResult {
+	messages: WindowMessage[];
+	/** Every message on the resolved branch, root→tip chronological. Callers
+ *  derive bookends from this instead of re-parsing the transcript. */
+	branchMessages: WindowMessage[];
+	messagesBefore: number;
+	messagesAfter: number;
+	/** Tip of the branch the window was resolved on — pass back as branchTip to
+	 *  keep scrolling on this branch across forks. May be a non-message entry id. */
+	branchTip: string;
+}
+
+export interface ReadResult {
+	messages: WindowMessage[];
+	totalMessages: number;
+	truncated: boolean;
+}
+
+interface Entry {
+	id: string;
+	parentId: string | null;
+	type: string;
+	timestamp?: string;
+	message?: {
+		role?: string;
+		content?: string | Array<{ type?: string; text?: string }>;
+	};
+}
+
+/** Parse JSONL lines; malformed lines are skipped. Header line (no id) skipped. */
+function parseSessionEntries(sessionPath: string): Entry[] {
+	// O_NONBLOCK + descriptor validation + fixed-size snapshot read are shared
+	// with the index engine; the fd pins the inode so a concurrent append after
+	// fstat waits until the next hydration call.
+	const raw = readBoundedSnapshot(sessionPath, MAX_SESSION_FILE_BYTES);
+	const entries: Entry[] = [];
+	const seenIds = new Set<string>();
+	for (const line of raw.split("\n")) {
+		if (!line.trim()) continue;
+		let obj: unknown;
+		try {
+			obj = JSON.parse(line);
+		} catch {
+			continue; // skip malformed line
+		}
+		const e = obj as Entry;
+		if (
+			e &&
+			typeof e.id === "string" &&
+			e.id.length > 0 &&
+			e.id.length <= 256 &&
+			!seenIds.has(e.id) &&
+			(e.parentId == null || (typeof e.parentId === "string" && e.parentId.length <= 256))
+		) {
+			seenIds.add(e.id);
+			entries.push(e);
+		}
+	}
+	return entries;
+}
+
+/** Leaf = last entry in file order whose ancestry contains a message; detached
+ *  trailing metadata must not hide the transcript.
+ *  Linear time: each entry's ancestry verdict is memoized, so every parent
+ *  chain segment is traversed once regardless of how many trailing candidates
+ *  share ancestry. Cycle handling matches branch(): truncation at the first
+ *  revisit means every path node's truncated chain is a suffix of the path,
+ *  so one walk's verdict covers all its memoized nodes. */
+function leafId(entriesById: Map<string, Entry>, entries: Entry[]): string | null {
+	const hasMessageAncestor = new Map<string, boolean>();
+	let leaf: string | null = null;
+	for (const start of entries) {
+		const path: Entry[] = [];
+		const onPath = new Set<string>();
+		let cur: Entry = start;
+		for (;;) {
+			const known = hasMessageAncestor.get(cur.id);
+			if (known !== undefined) {
+				for (const e of path) hasMessageAncestor.set(e.id, known);
+				break;
+			}
+			if (onPath.has(cur.id)) {
+				// No message was found before revisiting (we exit on message first).
+				for (const e of path) hasMessageAncestor.set(e.id, false);
+				break;
+			}
+			onPath.add(cur.id);
+			path.push(cur);
+			if (cur.type === "message") {
+				// Every node above the first message has one in its ancestry too.
+				for (const e of path) hasMessageAncestor.set(e.id, true);
+				break;
+			}
+			const parent = cur.parentId ? entriesById.get(cur.parentId) : undefined;
+			if (!parent) {
+				for (const e of path) hasMessageAncestor.set(e.id, false);
+				break;
+			}
+			cur = parent;
+		}
+		if (hasMessageAncestor.get(start.id)) leaf = start.id;
+	}
+	return leaf;
+}
+
+/** Walk parentId chain from entry to root, reversed (root→entry). */
+function branch(entriesById: Map<string, Entry>, entryId: string): Entry[] {
+	const chain: Entry[] = [];
+	let cur: Entry | undefined = entriesById.get(entryId);
+	// ponytail: cycle guard for corrupt files — revisit only if real sessions ever contain cycles
+	const seen = new Set<string>();
+	while (cur && !seen.has(cur.id)) {
+		seen.add(cur.id);
+		chain.push(cur);
+		cur = cur.parentId ? entriesById.get(cur.parentId) : undefined;
+	}
+	return chain.reverse();
+}
+
+/** Deepest entry in file order whose ancestry contains tipId (tipId itself if none). */
+function deepestDescendant(
+	entriesById: Map<string, Entry>,
+	entries: Entry[],
+	anchorId: string,
+): string {
+	const onBranch = new Set([anchorId]);
+	let tip = anchorId;
+	for (const e of entries) {
+		if (e.parentId && onBranch.has(e.parentId)) {
+			onBranch.add(e.id);
+			tip = e.id;
+		}
+	}
+	return tip;
+}
+
+function toWindowMessage(e: Entry): WindowMessage {
+	const m = e.message ?? {};
+	const content =
+		typeof m.content === "string"
+			? m.content
+			: Array.isArray(m.content)
+				? m.content
+						.filter((p) => p?.type === "text" && typeof p.text === "string")
+						.map((p) => p.text)
+						.join("\n")
+				: "";
+	return {
+		entryId: e.id,
+		role: typeof m.role === "string" ? m.role.slice(0, 32) : "",
+		content,
+		timestamp: typeof e.timestamp === "string" ? e.timestamp.slice(0, 128) : "",
+	};
+}
+
+/** Active-branch messages for a given tip, root→tip chronological. */
+function branchMessages(
+	entriesById: Map<string, Entry>,
+	tipId: string,
+): WindowMessage[] {
+	return branch(entriesById, tipId)
+		.filter((e) => e.type === "message")
+		.map(toWindowMessage);
+}
+
+/** Resolve a scroll cursor to a message: the cursor itself when it is a
+ *  message, otherwise its nearest message ancestor. Throws when the cursor is
+ *  unknown or has no message ancestor. */
+function resolveMessageCursor(
+	entriesById: Map<string, Entry>,
+	anchorEntryId: string,
+): Entry {
+	const anchor = entriesById.get(anchorEntryId);
+	if (!anchor) throw new Error(`anchor entry ${anchorEntryId} not found in session`);
+	let cur: Entry | undefined = anchor;
+	const seen = new Set<string>();
+	while (cur && cur.type !== "message" && !seen.has(cur.id)) {
+		seen.add(cur.id);
+		cur = cur.parentId ? entriesById.get(cur.parentId) : undefined;
+	}
+	if (!cur || cur.type !== "message") throw new Error(`anchor entry ${anchorEntryId} has no message ancestor`);
+	return cur;
+}
+
+export function getWindow(
+	sessionPath: string,
+	anchorEntryId: string,
+	windowN: number,
+	opts?: { branchTip?: string },
+): WindowResult {
+	const n = Math.max(0, Math.min(50, windowN));
+	const entries = parseSessionEntries(sessionPath);
+	const entriesById = new Map(entries.map((e) => [e.id, e]));
+	// A non-message branch-tip cursor centers on its nearest message ancestor;
+	// the non-message tip itself stays branchTip so scrolling remains on branch.
+	const messageAnchor = resolveMessageCursor(entriesById, anchorEntryId);
+	const anchorEntryIdMsg = messageAnchor.id;
+
+	let tip: string;
+	if (opts?.branchTip) {
+		// Explicit branch selection: resolve the branch from its tip (deepest
+		// descendant), independent of where the window centers.
+		resolveMessageCursor(entriesById, opts.branchTip); // unknown tip → throw
+		tip = deepestDescendant(entriesById, entries, opts.branchTip);
+		if (!branch(entriesById, tip).some((e) => e.id === messageAnchor.id)) {
+			throw new Error(`anchor entry ${anchorEntryId} is not on branch ${opts.branchTip}`);
+		}
+	} else {
+		tip = deepestDescendant(entriesById, entries, anchorEntryId);
+	}
+	const msgs = branchMessages(entriesById, tip);
+	const idx = msgs.findIndex((m) => m.entryId === anchorEntryIdMsg);
+	const start = Math.max(0, idx - n);
+	const end = Math.min(msgs.length - 1, idx + n);
+	return {
+		branchMessages: msgs,
+		messages: msgs.slice(start, end + 1).map((m) =>
+			m.entryId === anchorEntryIdMsg ? { ...m, anchor: true } : m,
+		),
+		messagesBefore: idx,
+		messagesAfter: msgs.length - 1 - idx,
+		branchTip: tip,
+	};
+}
+
+export function readSession(
+	sessionPath: string,
+	head = 20,
+	tail = 10,
+): ReadResult {
+	const entries = parseSessionEntries(sessionPath);
+	const entriesById = new Map(entries.map((e) => [e.id, e]));
+	const leaf = leafId(entriesById, entries);
+	if (!leaf) return { messages: [], totalMessages: 0, truncated: false };
+	const msgs = branchMessages(entriesById, leaf);
+	if (msgs.length > head + tail) {
+		return {
+			messages: [...msgs.slice(0, head), ...msgs.slice(-tail)],
+			totalMessages: msgs.length,
+			truncated: true,
+		};
+	}
+	return { messages: msgs, totalMessages: msgs.length, truncated: false };
+}