@henryqw/pi-session-recall 1.0.2 → 2.0.0

package/README.md

@@ -1,6 +1,8 @@
 # `@henryqw/pi-session-recall`
 
-Find decisions and context in past Pi sessions through a local FTS5 index with no model calls. Local search recalls earlier work without carrying every transcript in current context or adding standing prompt cost.
+Find decisions and context in past Pi sessions through a local FTS5 index.
+
+Saved transcripts are not injected on every turn. The active tool registration still adds standing prompt cost through its schema, descriptions, and guideline. Returned content enters active model context.
 
 The bundled `pi-session-pattern-miner` skill finds repeated work that may deserve automation.
 
@@ -41,9 +43,9 @@ BM25 is a text-ranking method. Hydrated results include messages read from saved
 
 | 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`. |
+| Discovery | `query` | BM25-ranked top sessions. Adaptive retrieval uses user and assistant text for windows, bookends, anchors, and counts. It omits tool-result messages and sets `toolResultsOmitted:true` when it removes one. Lower hits still include their indexed anchor. Use `detail:"full"` to hydrate every hit with tool-result messages included. |
+| Scroll | `sessionId` + `aroundMessageId` | Raw message roles, including tool results, within ±`window` ([1,20]) of the anchor. 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` | Raw message roles, including tool results, from the 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.
@@ -54,6 +56,8 @@ Run `/skill:pi-session-pattern-miner` to find repeated workflows in past session
 
 ## Flow
 
+Search makes no model calls.
+
 ### Query and index
 
 - Prefer distinctive identifiers, package names, issue numbers, or uncommon terms. Use quoted phrases only when exact wording is known.
@@ -68,15 +72,29 @@ Hits inside the current session's live context are suppressed. Compacted-away or
 
 Before browse or discovery, the extension lazily syncs the index from the session tree.
 
+### Retrieval safety
+
+Adaptive discovery leaves tool-result messages out of returned context. Use `detail:"full"`, READ, or SCROLL when you explicitly need them.
+
+Historical tool output may contain secrets or other sensitive data. Raw retrieval places that output in active model context.
+
 ## State and storage
 
 The extension maintains the derived SQLite search index at `~/.pi/agent/config/pi-session-recall/index.db`.
 
 This is derived state. Delete it and it rebuilds from your session files.
 
-## Data, cost, and privacy
+The index and transcript reads stay local. Transcripts are read in place. Returned content follows the data path of your configured model provider.
+
+## Roll back
+
+Pin the previous release:
+
+```bash
+pi install npm:@henryqw/pi-session-recall@1.0.3
+```
 
-Everything stays local. Transcripts are read in place, and nothing leaves the machine beyond what tool results already show the model. Search makes no model calls.
+No index migration or cleanup is needed.
 
 ## Limits and recovery
 

package/extensions/hydrate.ts

@@ -14,6 +14,8 @@ export interface WindowResult {
 	branchMessages: WindowMessage[];
 	messagesBefore: number;
 	messagesAfter: number;
+	/** Present only when discovery filtering removed at least one tool result. */
+	toolResultsOmitted?: true;
 	/** 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;
@@ -198,7 +200,7 @@ export function getWindow(
 	sessionPath: string,
 	anchorEntryId: string,
 	windowN: number,
-	opts?: { branchTip?: string },
+	opts?: { branchTip?: string; userAssistantTextOnly?: boolean },
 ): WindowResult {
 	const n = Math.max(0, Math.min(50, windowN));
 	const entries = parseSessionEntries(sessionPath);
@@ -220,8 +222,15 @@ export function getWindow(
 	} else {
 		tip = deepestDescendant(entriesById, entries, anchorEntryId);
 	}
-	const msgs = branchMessages(entriesById, tip);
+	const rawMessages = branchMessages(entriesById, tip);
+	const toolResultsOmitted = opts?.userAssistantTextOnly && rawMessages.some((m) => m.role === "toolResult")
+		? true
+		: undefined;
+	const msgs = opts?.userAssistantTextOnly
+		? rawMessages.filter((m) => (m.role === "user" || m.role === "assistant") && m.content.length > 0)
+		: rawMessages;
 	const idx = msgs.findIndex((m) => m.entryId === anchorEntryIdMsg);
+	if (idx < 0) throw new Error(`anchor entry ${anchorEntryId} is not a user/assistant text message`);
 	const start = Math.max(0, idx - n);
 	const end = Math.min(msgs.length - 1, idx + n);
 	return {
@@ -231,6 +240,7 @@ export function getWindow(
 		),
 		messagesBefore: idx,
 		messagesAfter: msgs.length - 1 - idx,
+		...(toolResultsOmitted ? { toolResultsOmitted } : {}),
 		branchTip: tip,
 	};
 }

package/extensions/session-recall.ts

@@ -113,6 +113,9 @@ export default function (pi: ExtensionAPI): void {
 		label: "Session Search",
 		description: DESCRIPTION,
 		promptSnippet: "Search past Pi sessions for prior decisions and context",
+		promptGuidelines: [
+			"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({
 			query: Type.Optional(Type.String({ description: "Search query (discovery). FTS5 syntax supported." })),
 			sessionId: Type.Optional(Type.String({ description: "Absolute path of the session file." })),
@@ -319,18 +322,18 @@ export default function (pi: ExtensionAPI): void {
 					if (!hydrateFull) {
 						// Compact hits still carry the matched anchor message.
 						try {
-							const win = getWindow(hit.path, hit.entryId, 0);
+							const win = getWindow(hit.path, hit.entryId, 0, { userAssistantTextOnly: true });
 							// 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);
+							return fitOrTruncate({ ...meta, detail: "compact", ...(overCompactCap ? { contentTruncated: true } : {}), ...(win.toolResultsOmitted ? { toolResultsOmitted: 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);
+						const win = getWindow(hit.path, hit.entryId, 5, full ? undefined : { userAssistantTextOnly: true });
 						// 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) };
@@ -338,6 +341,7 @@ export default function (pi: ExtensionAPI): void {
 							{
 								...meta,
 								detail: "full" as const,
+								...(win.toolResultsOmitted ? { toolResultsOmitted: true } : {}),
 								messages: win.messages,
 								bookends,
 								messagesBefore: win.messagesBefore,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-session-recall",
-	"version": "1.0.2",
+	"version": "2.0.0",
 	"description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
 	"keywords": [
 		"pi-package",