@henryqw/pi-session-recall 2.0.0 → 2.1.1

package/extensions/session-recall.ts

@@ -9,15 +9,18 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { realpathSync } from "node:fs";
 import { join, sep } from "node:path";
-import { getSessionRows, searchIndex, syncSessions } from "./search-core.ts";
+import { getPreparationRows, getSessionRows, searchIndex, syncSessions } from "./search-core.ts";
 import { getWindow, readSession } from "./hydrate.ts";
 import { MAX_QUERY_CHARS } from "./query.ts";
-import type { WindowMessage } from "./types.ts";
+import { inventoryRepository, type RepositoryInventory } from "./repository-inventory.ts";
+import type { PreparationSessionRow, WindowMessage } from "./types.ts";
 
 const dbPath = () => join(extensionConfigDir("pi-session-recall"), "index.db");
 const sessionsDir = () => join(getAgentDir(), "sessions");
 
 const OUTPUT_CHAR_BUDGET = 50_000;
+const INVENTORY_CHAR_BUDGET = 10_000;
+const ERROR_MESSAGE_CHARS = 512;
 
 function clamp(n: number | undefined, min: number, max: number, dflt: number): number {
 	if (typeof n !== "number" || !Number.isFinite(n)) return dflt;
@@ -78,7 +81,185 @@ function boundContent(
 	return cap === null ? build(null) : { ...build(cap), contentTruncated: true };
 }
 
+type InventoryCollection = "packageScripts" | "executableScripts" | "skills" | "agentInstructions";
+const INVENTORY_COLLECTIONS: InventoryCollection[] = ["packageScripts", "executableScripts", "skills", "agentInstructions"];
+
+function inventoryShape(
+	source: RepositoryInventory,
+	kept: Record<InventoryCollection, unknown[]>,
+): Record<string, unknown> {
+	const omittedCounts = {
+		packageScripts: source.packageScripts.length - kept.packageScripts.length,
+		executableScripts: source.executableScripts.length - kept.executableScripts.length,
+		skills: source.skills.length - kept.skills.length,
+		agentInstructions: source.agentInstructions.length - kept.agentInstructions.length,
+	};
+	return {
+		available: source.available,
+		...(source.reason ? { reason: source.reason } : {}),
+		...(source.provenance ? { provenance: source.provenance } : {}),
+		worktreeVerified: source.worktreeVerified,
+		packageScripts: kept.packageScripts,
+		executableScripts: kept.executableScripts,
+		skills: kept.skills,
+		agentInstructions: kept.agentInstructions,
+		truncated: Object.values(omittedCounts).some((count) => count > 0),
+		omittedCounts,
+	};
+}
+
+/** Keep stable prefixes from every inventory collection within one bounded,
+ * round-robin allocation so a large first collection cannot starve the rest. */
+function boundInventory(source: RepositoryInventory, maxChars: number): Record<string, unknown> {
+	const all: Record<InventoryCollection, unknown[]> = {
+		packageScripts: source.packageScripts,
+		executableScripts: source.executableScripts,
+		skills: source.skills,
+		agentInstructions: source.agentInstructions,
+	};
+	const full = inventoryShape(source, all);
+	if (JSON.stringify(full).length <= maxChars) return full;
+
+	const kept: Record<InventoryCollection, unknown[]> = {
+		packageScripts: [],
+		executableScripts: [],
+		skills: [],
+		agentInstructions: [],
+	};
+	const blocked = new Set<InventoryCollection>();
+	for (;;) {
+		let advanced = false;
+		for (const key of INVENTORY_COLLECTIONS) {
+			if (blocked.has(key) || kept[key].length >= all[key].length) continue;
+			const candidate = { ...kept, [key]: [...kept[key], all[key][kept[key].length]] };
+			if (JSON.stringify(inventoryShape(source, candidate)).length <= maxChars) {
+				kept[key] = candidate[key];
+				advanced = true;
+			} else {
+				blocked.add(key);
+			}
+		}
+		if (!advanced) break;
+	}
+	return inventoryShape(source, kept);
+}
+
+interface PreparedSession {
+	metadata: Record<string, unknown>;
+	messages: WindowMessage[];
+}
+
+function hydrationError(error: unknown): { kind: "missing" | "oversized" | "unreadable"; message: string } {
+	const message = (error instanceof Error ? error.message : String(error)).slice(0, ERROR_MESSAGE_CHARS);
+	const code = (error as NodeJS.ErrnoException)?.code;
+	return {
+		kind: code === "ENOENT" ? "missing" : message.includes("exceeds 32 MiB snapshot limit") ? "oversized" : "unreadable",
+		message,
+	};
+}
+
+function hydratePreparationSession(row: PreparationSessionRow): PreparedSession {
+	const indexed = {
+		path: row.path,
+		cwd: row.cwd,
+		name: row.name ?? null,
+		startedAt: row.startedAt ?? null,
+		lineageId: row.lineageId,
+	};
+	try {
+		const hydrated = readSession(row.path, 20, 10, { userAssistantTextOnly: true });
+		return {
+			metadata: {
+				...indexed,
+				branchTip: hydrated.branchTip,
+				totalMessages: hydrated.totalMessages,
+				truncated: hydrated.truncated,
+				contentTruncated: false,
+				messages: [],
+			},
+			messages: hydrated.messages,
+		};
+	} catch (error) {
+		return {
+			metadata: {
+				...indexed,
+				branchTip: null,
+				totalMessages: null,
+				truncated: false,
+				contentTruncated: false,
+				messages: [],
+				error: hydrationError(error),
+			},
+			messages: [],
+		};
+	}
+}
+
+function allocatePreparationMessages(session: PreparedSession, budget: number): Record<string, unknown> {
+	if (session.messages.length === 0) return session.metadata;
+	if (JSON.stringify(session.messages).length - 2 <= budget) {
+		return { ...session.metadata, messages: session.messages };
+	}
+	const maxLen = Math.max(...session.messages.map((message) => message.content.length), 0);
+	const cap = maxFittingCap(maxLen, budget + 2, (value) => truncateContent(session.messages, value));
+	return {
+		...session.metadata,
+		contentTruncated: true,
+		messages: cap === null ? [] : truncateContent(session.messages, cap),
+	};
+}
+
+function buildPreparationResult(
+	kind: "repository" | "all",
+	requestedLimit: number,
+	gitRoot: string | undefined,
+	syncResult: ReturnType<typeof syncSessions>,
+	rows: PreparationSessionRow[],
+	repositoryInventory: RepositoryInventory,
+): Record<string, unknown> {
+	const sync = {
+		walkComplete: syncResult.walkComplete,
+		backlogRemaining: syncResult.backlogRemaining,
+		complete: syncResult.walkComplete && syncResult.backlogRemaining === 0,
+	};
+	const sessions = rows.map(hydratePreparationSession);
+	const emptyCollections: Record<InventoryCollection, unknown[]> = {
+		packageScripts: [],
+		executableScripts: [],
+		skills: [],
+		agentInstructions: [],
+	};
+	const minimumInventory = inventoryShape(repositoryInventory, emptyCollections);
+	const build = (
+		preparedSessions: Record<string, unknown>[],
+		inventory: Record<string, unknown>,
+		contentTruncated: boolean,
+	) => ({
+		mode: "prepare-pattern-miner",
+		scope: { kind, gitRoot: gitRoot ?? null, requestedLimit, sampledCount: preparedSessions.length },
+		sync,
+		sessions: preparedSessions,
+		inventory,
+		contentTruncated,
+	});
+
+	const metadataOnlyLength = JSON.stringify(build(sessions.map((session) => session.metadata), minimumInventory, false)).length;
+	if (metadataOnlyLength > OUTPUT_CHAR_BUDGET) throw new Error("Pattern-miner preparation metadata exceeds output budget.");
+	const inventoryBudget = Math.min(
+		INVENTORY_CHAR_BUDGET,
+		JSON.stringify(minimumInventory).length + OUTPUT_CHAR_BUDGET - metadataOnlyLength,
+	);
+	const inventory = boundInventory(repositoryInventory, inventoryBudget);
+	const baseLength = JSON.stringify(build(sessions.map((session) => session.metadata), inventory, false)).length;
+	const perSessionBudget = sessions.length === 0 ? 0 : Math.floor((OUTPUT_CHAR_BUDGET - baseLength) / sessions.length);
+	const allocated = sessions.map((session) => allocatePreparationMessages(session, perSessionBudget));
+	const contentTruncated = allocated.some((session) => session.contentTruncated === true);
+	return build(allocated, inventory, contentTruncated);
+}
+
 interface ToolParams {
+	operation?: "prepare-pattern-miner";
+	scope?: "repository" | "all";
 	query?: string;
 	sessionId?: string;
 	aroundMessageId?: string;
@@ -90,6 +271,7 @@ interface ToolParams {
 
 const DESCRIPTION = `Search past Pi sessions locally with FTS5; returns stored messages.
 
+- \`operation: "prepare-pattern-miner"\` + \`scope\`: prepare one bounded corpus and repository inventory.
 - \`query\`: discover matches. Prefer distinctive identifiers or uncommon terms; multi-word queries are AND. Use \`OR\`/\`NOT\` for Boolean queries and quotes only when exact wording is known.
 - \`sessionId\` + \`aroundMessageId\`: scroll ±\`window\`; retain \`branchTip\` across forks.
 - \`sessionId\` alone: read; no args: browse recent sessions.
@@ -117,12 +299,14 @@ export default function (pi: ExtensionAPI): void {
 			"Use session_search only when the user explicitly asks about past Pi sessions, historical decisions, or repeated work not available in the current conversation. Do not use it for current-session continuation or ordinary repository inspection.",
 		],
 		parameters: Type.Object({
+			operation: Type.Optional(StringEnum(["prepare-pattern-miner"] as const)),
+			scope: Type.Optional(StringEnum(["repository", "all"] as const)),
 			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." })),
+			limit: Type.Optional(Type.Number({ description: "Max results, [1,10]. Defaults to 10 for preparation and 3 otherwise." })),
 			detail: Type.Optional(StringEnum(["adaptive", "full"] as const)),
 		}),
 		renderResult(result, { expanded }, theme) {
@@ -140,8 +324,39 @@ export default function (pi: ExtensionAPI): void {
 				invalidate() {},
 			};
 		},
-		async execute(_toolCallId, rawParams: ToolParams, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, rawParams: ToolParams, signal, _onUpdate, ctx) {
 			try {
+				if (rawParams.operation !== undefined && rawParams.operation !== "prepare-pattern-miner") {
+					throw new Error("Unsupported session_search operation.");
+				}
+				if (rawParams.scope !== undefined && rawParams.operation === undefined) {
+					throw new Error("scope requires operation: prepare-pattern-miner.");
+				}
+				if (rawParams.operation === "prepare-pattern-miner") {
+					const incompatible = (["query", "sessionId", "aroundMessageId", "branchTip", "window", "detail"] as const)
+						.filter((key) => rawParams[key] !== undefined);
+					if (incompatible.length > 0) {
+						throw new Error(`prepare-pattern-miner does not accept: ${incompatible.join(", ")}.`);
+					}
+					if (rawParams.scope !== "repository" && rawParams.scope !== "all") {
+						throw new Error("prepare-pattern-miner requires scope: repository or all.");
+					}
+					const limit = clamp(rawParams.limit, 1, 10, 10);
+					const inventory = await inventoryRepository(
+						pi,
+						{ cwd: ctx.cwd, signal },
+						rawParams.scope === "repository" ? "required" : "optional",
+					);
+					const sync = syncSessions(sessionsDir(), dbPath());
+					const currentSessionPath = ctx.sessionManager.getSessionFile() ?? undefined;
+					const rows = getPreparationRows(dbPath(), {
+						limit,
+						...(rawParams.scope === "repository" ? { repositoryRoot: inventory.gitRoot! } : {}),
+						currentSessionPath,
+					});
+					return textResult(buildPreparationResult(rawParams.scope, limit, inventory.gitRoot, sync, rows, inventory));
+				}
+
 				// LLMs sometimes send numeric ids/queries despite the string schema.
 				const params: ToolParams = {
 					query: rawParams.query != null ? String(rawParams.query) : undefined,
@@ -199,6 +414,7 @@ export default function (pi: ExtensionAPI): void {
 							(cap) => ({
 								mode: "read",
 								sessionId,
+								branchTip: r.branchTip,
 								totalMessages: r.totalMessages,
 								truncated: r.truncated,
 								messages: cap === null ? [] : truncateContent(r.messages, cap),

package/extensions/types.ts

@@ -22,6 +22,12 @@ export interface SessionRow {
 	preview?: string;
 }
 
+/** Indexed metadata selected for pattern-miner preparation. */
+export interface PreparationSessionRow extends SessionRow {
+	/** Stable one-hop fork identity used to avoid duplicate evidence. */
+	lineageId: string;
+}
+
 /** One FTS discovery hit before hydration. */
 export interface SearchHit {
 	path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-session-recall",
-	"version": "2.0.0",
+	"version": "2.1.1",
 	"description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
 	"keywords": [
 		"pi-package",
@@ -18,6 +18,7 @@
 		"LICENSE",
 		"extensions",
 		"skills",
+		"docs",
 		"README.md"
 	],
 	"scripts": {

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

@@ -5,22 +5,60 @@ description: Mine repeated work, corrections, and manual procedures from past Pi
 
 # 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.
+Find repeated work in past Pi sessions. Turn the best-supported pattern into the smallest useful automation.
 
-## Scope
+Use `session_search` for session history. Do not scan Pi session files directly.
 
-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.
+## Prepare once
 
-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.
+Choose the requested scope. Use `repository` for the current Git repository. Use `all` for a cross-repository request or work outside Git.
+
+Before interpretation, call `session_search` exactly once with:
+
+```json
+{
+  "operation": "prepare-pattern-miner",
+  "scope": "repository",
+  "limit": 10
+}
+```
+
+Change only `scope` when needed. Do not run manual browse, read, scroll, or inventory rounds during preparation.
+
+State the returned scope and sample count. If `sync.complete` is false, report the incomplete walk or positive backlog as a sample limitation.
+
+The prepared corpus is recent and bounded. A truncated session can omit middle episodes. Never claim exhaustive coverage.
 
 ## 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.
+The model performs these steps. Do not replace them with mechanical keyword rules.
+
+1. Identify semantic episodes, including repeated intents, corrections, retries, manual procedures, and recurring agent-authored steps.
+2. Ignore generic inspect, edit, and test work unless the same concrete procedure repeats.
+3. Cluster episodes by their underlying job, not their wording.
+4. Treat sessions with equal `lineageId` values as one source.
+5. Choose the owning automation surface from the prepared inventory and targeted repository evidence.
+6. Write the recommendation and implementation contract.
+
+A user-supplied topic is already a candidate. Run a focused confirmation search even when that topic is absent from the prepared sample.
+
+For other work, create a candidate from the prepared corpus before running optional searches. Do not search speculatively when no topic or candidate exists.
+
+Confirm a candidate with one or more distinctive `query` calls. Use `limit: 10`. Record the session path, date or name, relevant entry ID, and a short paraphrase.
+
+Do not copy secrets or unnecessary transcript text. Do not count forks, retries, or continuations of one task as independent evidence.
+
+## Verify ownership
+
+After clustering, use the inventory only to find likely owners. It is not ownership proof and does not verify the current worktree.
+
+Always inspect the current candidate-relevant package manifests, executable scripts, skill files, and instruction files before assigning ownership. Do this even when the inventory is available and complete.
+
+Reuse or repair existing automation when it already owns the workflow. If targeted current-file verification cannot be performed safely, abstain.
+
+## Evidence gate
+
+A recommendation requires two independent examples. This gate is mandatory.
 
 Stop with “not enough repeated evidence” when fewer than two independent sessions support a pattern. Do not manufacture a recommendation from one occurrence.
 
@@ -29,12 +67,14 @@ Stop with “not enough repeated evidence” when fewer than two independent ses
 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.
+2. **Script** — use when inputs, decisions, outputs, and failures need no model judgment.
+3. **Script plus thin skill** — use when an agent gathers inputs, but a script performs the repeated operation.
+4. **Skill only** — use only when the reusable work inherently requires judgment, repository inspection, or user decisions.
+5. **Product change** — use when the root cause belongs in an extension, API, CI check, or other code.
 
-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.
+Prefer a repository command or standard-library script. Add no dependency without evidence that existing tools cannot handle the job.
+
+A deterministic candidate must define its trigger, inputs, outputs, side effects, failure behavior, and one runnable check. Recommend investigation when evidence cannot define these details.
 
 ## Report
 
@@ -43,7 +83,9 @@ 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:
+For each pattern, cite session paths and entry IDs. Explain why the owning surface fits and what model work it removes.
+
+Give the highest-confidence candidate a minimal implementation contract:
 
 - **Trigger and inputs**
 - **Deterministic steps**