@henryqw/pi-session-recall 0.1.4

package/extensions/session-recall.ts

@@ -0,0 +1,379 @@
+/**
+ * pi-session-recall entry point: tool registration and mode dispatch.
+ */
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { realpathSync } from "node:fs";
+import { join, sep } from "node:path";
+import { MAX_QUERY_CHARS, getSessionRows, searchIndex, syncSessions } from "./search-core.ts";
+import { getWindow, readSession } from "./hydrate.ts";
+import type { WindowMessage } from "./types.ts";
+
+const dbPath = () => join(getAgentDir(), "config", "pi-session-recall", "index.db");
+const sessionsDir = () => join(getAgentDir(), "sessions");
+
+const OUTPUT_CHAR_BUDGET = 50_000;
+
+function clamp(n: number | undefined, min: number, max: number, dflt: number): number {
+	if (typeof n !== "number" || !Number.isFinite(n)) return dflt;
+	return Math.max(min, Math.min(max, Math.floor(n)));
+}
+
+/** UTF-16 surrogate halves. */
+const isHighSurrogate = (s: string, i: number) => {
+	const u = s.charCodeAt(i);
+	return u >= 0xd800 && u <= 0xdbff;
+};
+const isLowSurrogate = (s: string, i: number) => {
+	const u = s.charCodeAt(i);
+	return u >= 0xdc00 && u <= 0xdfff;
+};
+
+export function truncateContent(msgs: WindowMessage[], maxChars: number): WindowMessage[] {
+	return msgs.map((m) => {
+		if (m.content.length <= maxChars) return m;
+		const c = m.content;
+		let head = Math.ceil(maxChars / 2);
+		const tail = Math.floor(maxChars / 2);
+		// Shift only cut points that land inside an astral character (surrogate
+		// pair); everything else keeps the exact head/tail split.
+		if (head > 0 && isHighSurrogate(c, head - 1) && isLowSurrogate(c, head)) head--;
+		let tailStart = c.length - tail;
+		if (tail > 0 && tailStart > 0 && isHighSurrogate(c, tailStart - 1) && isLowSurrogate(c, tailStart)) tailStart++;
+		return {
+			...m,
+			content: c.slice(0, head) + "…" + (tail > 0 ? c.slice(tailStart) : ""),
+		};
+	});
+}
+
+/** Binary-search the max uniform per-message content cap whose built result fits
+ *  the budget; null when even empty message arrays don't fit. */
+function maxFittingCap(maxLen: number, budget: number, build: (cap: number) => unknown): number | null {
+	const fits = (cap: number) => JSON.stringify(build(cap)).length <= budget;
+	if (!fits(0)) return null;
+	let lo = 0;
+	for (let hi = maxLen; lo < hi; ) {
+		const mid = Math.ceil((lo + hi) / 2);
+		if (fits(mid)) lo = mid;
+		else hi = mid - 1;
+	}
+	return lo;
+}
+
+/** Build a result bounded to `budget`: largest uniform per-message cap across
+ *  every WindowMessage array, or a metadata-only shape when nothing fits.
+ *  build(null) must return the metadata-only variant with empty arrays. */
+function boundContent(
+	build: (cap: number | null) => Record<string, unknown>,
+	maxLen: number,
+	budget: number,
+): Record<string, unknown> {
+	const cap = maxFittingCap(maxLen, budget, (c) => build(c));
+	return cap === null ? build(null) : { ...build(cap), contentTruncated: true };
+}
+
+interface ToolParams {
+	query?: string;
+	sessionId?: string;
+	aroundMessageId?: string;
+	branchTip?: string;
+	window?: number;
+	limit?: number;
+	detail?: "adaptive" | "full";
+}
+
+const DESCRIPTION = `Search past Pi sessions stored on disk (FTS5-backed over a local SQLite index), or inspect one session in detail. No LLM calls — every shape returns actual messages.
+
+FOUR CALLING SHAPES
+
+  1) DISCOVERY — pass \`query\`:
+     session_search(query="auth refactor", limit=3)
+     Runs FTS5 search and returns the top N sessions with metadata, match snippet, and messages around each match. Adaptive detail (default): the top-ranked result carries a ±5 message window plus first/last bookend messages; lower-ranked results carry only the anchor message. Pass \`detail="full"\` to hydrate every result fully.
+
+  2) SCROLL — pass \`sessionId\` + \`aroundMessageId\`:
+     session_search(sessionId="...", aroundMessageId="e07", window=10)
+     Returns ±window messages centered on the anchor (clamped to [1,20]). Use after discovery when you need more context than the default ±5 window. To scroll forward/backward, pass the last/first message entryId of the previous window back as aroundMessageId; messagesBefore/messagesAfter tell you where you are. Across forks, re-anchoring on a shared ancestor can jump branches — pass the previous response's branchTip as the branchTip argument (aroundMessageId only moves the center) to stay on that branch.
+
+  3) READ — pass \`sessionId\` only:
+     session_search(sessionId="...")
+     Returns the session's active branch (first 20 + last 10 messages when large).
+
+  4) BROWSE — no args:
+     session_search()
+     Returns recent sessions: name, cwd, start time, first-user-message preview. Use when asked "what was I working on" without a topic.
+
+Mode is inferred from args; precedence: scroll > read > browse > discovery.
+
+FTS5 SYNTAX
+  AND is the default — multi-word queries require all terms. Use OR for broader recall (\`alpha OR beta\`), quoted phrases for exact match (\`"docker networking"\`), NOT to exclude (\`python NOT java\`). Wildcards work only as stem expansion of tokens ≥3 chars (trigram tokenizer); very short terms fall back to substring matching. The index covers user/assistant message text only — thinking, tool calls/results are not searchable.`;
+
+export default function (pi: ExtensionAPI): void {
+	// Best-effort sync at startup, deferred so the synchronous walk + SQLite
+	// writes never block session start. The lazy in-tool-call sync retries.
+	pi.on("session_start", (_event, _ctx) => {
+		setTimeout(() => {
+			try {
+				syncSessions(sessionsDir(), dbPath());
+			} catch {
+				// Index stays stale; next tool call retries.
+			}
+		}, 0);
+	});
+
+	pi.registerTool({
+		name: "session_search",
+		label: "Session Search",
+		description: DESCRIPTION,
+		promptSnippet: "Search past Pi sessions for prior decisions and context",
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ description: "Search query (discovery). FTS5 syntax supported." })),
+			sessionId: Type.Optional(Type.String({ description: "Absolute path of the session file." })),
+			aroundMessageId: Type.Optional(Type.String({ description: "Anchor entry id for scroll mode — centers the window (with sessionId)." })),
+			branchTip: Type.Optional(Type.String({ description: "Branch tip entry id from a previous response — selects which branch of a forked session to scroll; aroundMessageId must lie on it." })),
+			window: Type.Optional(Type.Number({ description: "Scroll window radius, [1,20], default 5." })),
+			limit: Type.Optional(Type.Number({ description: "Max results, [1,10], default 3." })),
+			detail: Type.Optional(StringEnum(["adaptive", "full"] as const)),
+		}),
+		async execute(_toolCallId, rawParams: ToolParams, _signal, _onUpdate, ctx) {
+			try {
+				// LLMs sometimes send numeric ids/queries despite the string schema.
+				const params: ToolParams = {
+					query: rawParams.query != null ? String(rawParams.query) : undefined,
+					sessionId: rawParams.sessionId != null ? String(rawParams.sessionId) : undefined,
+					aroundMessageId: rawParams.aroundMessageId != null ? String(rawParams.aroundMessageId) : undefined,
+					branchTip: rawParams.branchTip != null ? String(rawParams.branchTip) : undefined,
+					window: rawParams.window,
+					limit: rawParams.limit,
+					detail: rawParams.detail,
+				};
+				let sessionId = params.sessionId?.trim() || undefined;
+				const anchor = params.aroundMessageId?.trim() || undefined;
+				if (sessionId) {
+					// Trust boundary: canonical target must live under the real
+					// sessions dir (realpath defeats symlink escapes).
+					try {
+						const resolved = realpathSync(sessionId);
+						const root = realpathSync(sessionsDir());
+						if (!resolved.startsWith(root + sep) || !resolved.endsWith(".jsonl")) {
+							return textResult({ success: false, message: "sessionId must be a .jsonl file under the Pi sessions directory" });
+						}
+						// Rebind to the validated canonical path so downstream reads cannot
+						// be redirected by a symlink swapped in after validation (TOCTOU).
+						sessionId = resolved;
+					} catch {
+						return textResult({ success: false, message: `session file not found: ${sessionId}` });
+					}
+				}
+
+				// --- SCROLL ---
+				if (sessionId && anchor) {
+					const w = clamp(params.window, 1, 20, 5);
+					const branchTip = params.branchTip?.trim() || undefined;
+					const win = getWindow(sessionId, anchor, w, branchTip ? { branchTip } : undefined);
+					const base = { mode: "scroll", sessionId, branchTip: win.branchTip, messagesBefore: win.messagesBefore, messagesAfter: win.messagesAfter };
+					let result: Record<string, unknown> = { ...base, messages: win.messages };
+					if (JSON.stringify(result).length > OUTPUT_CHAR_BUDGET && win.messages.length > 0) {
+						result = boundContent(
+							(cap) => ({ ...base, messages: cap === null ? [] : truncateContent(win.messages, cap), contentTruncated: true }),
+							Math.max(...win.messages.map((m) => m.content.length), 0),
+							OUTPUT_CHAR_BUDGET,
+						);
+					}
+					return textResult(result);
+				}
+
+				// --- READ ---
+				if (sessionId) {
+					const r = readSession(sessionId);
+					let result: Record<string, unknown> = { mode: "read", sessionId, ...r };
+					if (JSON.stringify(result).length > OUTPUT_CHAR_BUDGET && r.messages.length > 0) {
+						// contentTruncated is character-level truncation, distinct from
+						// the message-count `truncated`.
+						result = boundContent(
+							(cap) => ({
+								mode: "read",
+								sessionId,
+								totalMessages: r.totalMessages,
+								truncated: r.truncated,
+								messages: cap === null ? [] : truncateContent(r.messages, cap),
+								contentTruncated: true,
+							}),
+							Math.max(...r.messages.map((m) => m.content.length), 0),
+							OUTPUT_CHAR_BUDGET,
+						);
+					}
+					return textResult(result);
+				}
+
+				// Lazy sync: drains any backlog the capped startup pass left.
+				try {
+					syncSessions(sessionsDir(), dbPath());
+				} catch {
+					// Serve from the possibly stale index rather than failing.
+				}
+
+				// --- BROWSE ---
+				if (!params.query?.trim()) {
+					const rows = getSessionRows(dbPath(), clamp(params.limit, 1, 10, 3));
+					return textResult({ mode: "browse", sessions: rows });
+				}
+
+				// --- DISCOVERY ---
+				const limit = clamp(params.limit, 1, 10, 3);
+				const full = params.detail === "full";
+
+				// Current-session guard: suppress hits on the live branch.
+				let liveIds: Set<string> | undefined;
+				let currentSessionPath: string | undefined;
+				try {
+					currentSessionPath = ctx.sessionManager.getSessionFile();
+					liveIds = new Set(
+						ctx.sessionManager
+							.buildContextEntries()
+							.filter((e) => e.type === "message")
+							.map((e) => e.id),
+					);
+				} catch {
+					// Guard unavailable → degrade gracefully, no suppression.
+				}
+
+				const { hits, backlogRemaining } = searchIndex(dbPath(), params.query, {
+					limit,
+					currentLiveEntryIds: liveIds,
+					currentSessionPath,
+				});
+
+				const resultQuery = params.query!.trim().slice(0, MAX_QUERY_CHARS);
+				// Reserve the complete response envelope and divide remaining space
+				// across hits so the first hydrated result cannot starve later metadata.
+				let used = JSON.stringify({ mode: "discovery", query: resultQuery, results: [], backlogRemaining }).length + Math.max(0, hits.length - 1);
+				const results = hits.map((hit, index) => {
+					const remaining = Math.floor((OUTPUT_CHAR_BUDGET - used) / (hits.length - index));
+					const meta = {
+						path: hit.path,
+						snippet: hit.snippet,
+						rank: hit.rank,
+						matchMessageId: hit.entryId,
+						role: hit.role,
+						timestamp: hit.timestamp,
+						cwd: hit.cwd,
+						name: hit.name,
+						startedAt: hit.startedAt,
+					};
+					const hydrateFull = full || hit.rank === 0;
+					// Every hit is sized against the cumulative remaining budget: keep
+					// as-is when it fits, else truncate to the largest uniform cap that
+					// fits across messages and bookends, else metadata-only.
+					// contentTruncated signals either case.
+					const fitOrTruncate = (
+						hitObj: Record<string, unknown>,
+						messages: WindowMessage[],
+						bookends?: { start: WindowMessage[]; end: WindowMessage[] },
+					): Record<string, unknown> => {
+						const out: Record<string, unknown> = { ...hitObj };
+						if (JSON.stringify(out).length > remaining) {
+							const pools = bookends ? [messages, bookends.start, bookends.end] : [messages];
+							const maxLen = Math.max(...pools.flatMap((a) => a.map((m) => m.content.length)), 0);
+							Object.assign(
+								out,
+								boundContent(
+									(cap) => ({
+										...hitObj,
+										messages: cap === null ? [] : truncateContent(messages, cap),
+										...(bookends && cap !== null
+											? { bookends: { start: truncateContent(bookends.start, cap), end: truncateContent(bookends.end, cap) } }
+											: bookends
+												? { bookends: { start: [], end: [] } }
+												: {}),
+										contentTruncated: true,
+									}),
+									maxLen,
+									remaining,
+								),
+							);
+						}
+						used += JSON.stringify(out).length;
+						return out;
+					};
+					const hydrationFallback = (error: unknown) =>
+						fitOrTruncate(
+							{ ...meta, detail: hydrateFull ? "full" : "compact", messages: [], bookends: { start: [], end: [] }, messagesBefore: 0, messagesAfter: 0, error: (error instanceof Error ? error.message : String(error)).slice(0, 512) },
+							[],
+						);
+					if (!hydrateFull) {
+						// Compact hits still carry the matched anchor message.
+						try {
+							const win = getWindow(hit.path, hit.entryId, 0);
+							// Mark when the fixed compact cap already removed content, so a
+							// hit that still fits the budget isn't mistaken for complete.
+							const overCompactCap = win.messages.some((m) => m.content.length > 2000);
+							return fitOrTruncate({ ...meta, detail: "compact", ...(overCompactCap ? { contentTruncated: true } : {}), messages: truncateContent(win.messages, 2000), bookends: { start: [], end: [] }, messagesBefore: win.messagesBefore, messagesAfter: win.messagesAfter }, win.messages);
+						} catch (error) {
+							return hydrationFallback(error);
+						}
+					}
+					try {
+						// One bounded snapshot feeds both window and branch bookends.
+						const win = getWindow(hit.path, hit.entryId, 5);
+						// Same branch as the anchor — following the file's final leaf
+						// would attach unrelated sibling messages.
+						const bookends = { start: win.branchMessages.slice(0, 3), end: win.branchMessages.slice(-3) };
+						return fitOrTruncate(
+							{
+								...meta,
+								detail: "full" as const,
+								messages: win.messages,
+								bookends,
+								messagesBefore: win.messagesBefore,
+								messagesAfter: win.messagesAfter,
+							},
+							win.messages,
+							bookends,
+						);
+					} catch (error) {
+						// Session file unreadable/moved since indexing → anchor-only.
+						return hydrationFallback(error);
+					}
+				});
+
+				const result: Record<string, unknown> = { mode: "discovery", query: resultQuery, results, backlogRemaining };
+				return textResult(result);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return textResult({ success: false, error: message });
+			}
+		},
+	});
+}
+
+function textResult(result: unknown) {
+	let bounded = result;
+	let text = JSON.stringify(bounded);
+	if (text.length > OUTPUT_CHAR_BUDGET && bounded && typeof bounded === "object" && !Array.isArray(bounded)) {
+		const copy: Record<string, unknown> = { ...(bounded as Record<string, unknown>), contentTruncated: true };
+		for (const key of ["results", "sessions", "messages"] as const) {
+			if (Array.isArray(copy[key])) copy[key] = [...copy[key] as unknown[]];
+		}
+		bounded = copy;
+		text = JSON.stringify(bounded);
+		while (text.length > OUTPUT_CHAR_BUDGET) {
+			const array = ["results", "sessions", "messages"]
+				.map((key) => copy[key])
+				.find((value): value is unknown[] => Array.isArray(value) && value.length > 0);
+			if (!array) {
+				bounded = { success: false, error: "session_search result metadata exceeds output budget" };
+				text = JSON.stringify(bounded);
+				break;
+			}
+			array.pop();
+			text = JSON.stringify(bounded);
+		}
+	}
+	return {
+		content: [{ type: "text" as const, text }],
+		details: bounded,
+	};
+}

package/extensions/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared shapes between the index engine (search-core) and hydration (hydrate).
+ * Keep this file types-only.
+ */
+
+/** A hydrated message returned by windows/read. */
+export interface WindowMessage {
+	entryId: string;
+	role: string;
+	content: string;
+	timestamp: string;
+	/** True when this message is the anchor of a scroll/discovery window. */
+	anchor?: boolean;
+}
+
+/** Metadata row for BROWSE mode (served from the index tables, not JSONL). */
+export interface SessionRow {
+	path: string;
+	cwd: string;
+	name?: string;
+	startedAt?: string;
+	preview?: string;
+}
+
+/** One FTS discovery hit before hydration. */
+export interface SearchHit {
+	path: string;
+	entryId: string;
+	role: string;
+	timestamp: string;
+	snippet: string;
+	/** BM25 rank position (0 = best). */
+	rank: number;
+	/** Session metadata joined from the sessions table. */
+	cwd?: string;
+	name?: string;
+	startedAt?: string;
+}
+
+export interface SyncResult {
+	filesProcessed: number;
+	messagesIndexed: number;
+	/** Changed files still unindexed after this pass, including failures. */
+	backlogRemaining: number;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@henryqw/pi-session-recall",
+	"version": "0.1.4",
+	"description": "FTS5 search over past Pi sessions: single tool, four arg-inferred modes (discovery/scroll/read/browse), zero LLM calls.",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"session-recall",
+		"fts5",
+		"recall"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"license": "MIT",
+	"files": [
+		"extensions",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "node --test test/*.test.ts",
+		"typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
+		"pack:check": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "^0.84.2",
+		"@earendil-works/pi-coding-agent": "^0.84.2",
+		"typebox": "^1.3.15"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/HenryQW/pi-packages.git",
+		"directory": "packages/pi-session-recall"
+	},
+	"bugs": {
+		"url": "https://github.com/HenryQW/pi-packages/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/session-recall.ts"
+		]
+	}
+}