@hcflabs/pi-session-recall 0.0.0-stage → 5.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,556 @@
1
+ /**
2
+ * pi-session-recall entry point: tool registration and mode dispatch.
3
+ */
4
+ import { getAgentDir, keyHint, truncateToVisualLines } from "@earendil-works/pi-coding-agent";
5
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
6
+ import { StringEnum } from "@earendil-works/pi-ai";
7
+ import { extensionConfigDir } from "@hcflabs/pi-config-store";
8
+ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
9
+ import { Type, type TSchema } from "typebox";
10
+ import { realpathSync } from "node:fs";
11
+ import { join, sep } from "node:path";
12
+ import { getPreparationRows, getSessionRows, searchIndex, syncSessions } from "./search-core.ts";
13
+ import { getWindow, readSession } from "./hydrate.ts";
14
+ import { MAX_QUERY_CHARS } from "./query.ts";
15
+ import { inventoryRepository, type RepositoryInventory } from "./repository-inventory.ts";
16
+ import type { PreparationSessionRow, WindowMessage } from "./types.ts";
17
+
18
+ const dbPath = () => join(extensionConfigDir("pi-session-recall"), "index.db");
19
+ const sessionsDir = () => join(getAgentDir(), "sessions");
20
+
21
+ const OUTPUT_CHAR_BUDGET = 50_000;
22
+ const INVENTORY_CHAR_BUDGET = 10_000;
23
+ const ERROR_MESSAGE_CHARS = 512;
24
+
25
+ function clamp(n: number | undefined, min: number, max: number, dflt: number): number {
26
+ if (typeof n !== "number" || !Number.isFinite(n)) return dflt;
27
+ return Math.max(min, Math.min(max, Math.floor(n)));
28
+ }
29
+
30
+ /** UTF-16 surrogate halves. */
31
+ const isHighSurrogate = (s: string, i: number) => {
32
+ const u = s.charCodeAt(i);
33
+ return u >= 0xd800 && u <= 0xdbff;
34
+ };
35
+ const isLowSurrogate = (s: string, i: number) => {
36
+ const u = s.charCodeAt(i);
37
+ return u >= 0xdc00 && u <= 0xdfff;
38
+ };
39
+
40
+ export function truncateContent(msgs: WindowMessage[], maxChars: number): WindowMessage[] {
41
+ return msgs.map((m) => {
42
+ if (m.content.length <= maxChars) return m;
43
+ const c = m.content;
44
+ let head = Math.ceil(maxChars / 2);
45
+ const tail = Math.floor(maxChars / 2);
46
+ // Shift only cut points that land inside an astral character (surrogate
47
+ // pair); everything else keeps the exact head/tail split.
48
+ if (head > 0 && isHighSurrogate(c, head - 1) && isLowSurrogate(c, head)) head--;
49
+ let tailStart = c.length - tail;
50
+ if (tail > 0 && tailStart > 0 && isHighSurrogate(c, tailStart - 1) && isLowSurrogate(c, tailStart)) tailStart++;
51
+ return {
52
+ ...m,
53
+ content: c.slice(0, head) + "…" + (tail > 0 ? c.slice(tailStart) : ""),
54
+ };
55
+ });
56
+ }
57
+
58
+ /** Binary-search the max uniform per-message content cap whose built result fits
59
+ * the budget; null when even empty message arrays don't fit. */
60
+ function maxFittingCap(maxLen: number, budget: number, build: (cap: number) => unknown): number | null {
61
+ const fits = (cap: number) => JSON.stringify(build(cap)).length <= budget;
62
+ if (!fits(0)) return null;
63
+ let lo = 0;
64
+ for (let hi = maxLen; lo < hi; ) {
65
+ const mid = Math.ceil((lo + hi) / 2);
66
+ if (fits(mid)) lo = mid;
67
+ else hi = mid - 1;
68
+ }
69
+ return lo;
70
+ }
71
+
72
+ /** Bound a read or scroll result to the output budget: the largest uniform
73
+ * per-message content cap, or empty messages when even that does not fit.
74
+ * contentTruncated is character-level truncation, distinct from `truncated`. */
75
+ function boundMessages(base: Record<string, unknown>, messages: WindowMessage[]): Record<string, unknown> {
76
+ const result = { ...base, messages };
77
+ if (JSON.stringify(result).length <= OUTPUT_CHAR_BUDGET || messages.length === 0) return result;
78
+ const build = (cap: number) => ({ ...base, messages: truncateContent(messages, cap), contentTruncated: true });
79
+ const cap = maxFittingCap(Math.max(...messages.map((m) => m.content.length), 0), OUTPUT_CHAR_BUDGET, build);
80
+ return cap === null ? { ...base, messages: [], contentTruncated: true } : build(cap);
81
+ }
82
+
83
+ const INVENTORY_COLLECTIONS = ["packageScripts", "executableScripts", "skills", "agentInstructions"] as const;
84
+ type InventoryCollection = (typeof INVENTORY_COLLECTIONS)[number];
85
+ type InventoryCollections = Record<InventoryCollection, unknown[]>;
86
+
87
+ const collectionRecord = <T>(value: (key: InventoryCollection) => T) =>
88
+ Object.fromEntries(INVENTORY_COLLECTIONS.map((key) => [key, value(key)])) as Record<InventoryCollection, T>;
89
+
90
+ function inventoryShape(source: RepositoryInventory, kept: InventoryCollections): Record<string, unknown> {
91
+ const omittedCounts = collectionRecord((key) => source[key].length - kept[key].length);
92
+ return {
93
+ available: source.available,
94
+ ...(source.reason ? { reason: source.reason } : {}),
95
+ ...(source.provenance ? { provenance: source.provenance } : {}),
96
+ worktreeVerified: source.worktreeVerified,
97
+ ...collectionRecord((key) => kept[key]),
98
+ truncated: Object.values(omittedCounts).some((count) => count > 0),
99
+ omittedCounts,
100
+ };
101
+ }
102
+
103
+ /** Keep stable prefixes from every inventory collection within one bounded,
104
+ * round-robin allocation so a large first collection cannot starve the rest. */
105
+ function boundInventory(source: RepositoryInventory, maxChars: number): Record<string, unknown> {
106
+ const full = inventoryShape(source, source);
107
+ if (JSON.stringify(full).length <= maxChars) return full;
108
+
109
+ const kept = collectionRecord((): unknown[] => []);
110
+ const blocked = new Set<InventoryCollection>();
111
+ for (;;) {
112
+ let advanced = false;
113
+ for (const key of INVENTORY_COLLECTIONS) {
114
+ if (blocked.has(key) || kept[key].length >= source[key].length) continue;
115
+ const candidate = { ...kept, [key]: [...kept[key], source[key][kept[key].length]] };
116
+ if (JSON.stringify(inventoryShape(source, candidate)).length <= maxChars) {
117
+ kept[key] = candidate[key];
118
+ advanced = true;
119
+ } else {
120
+ blocked.add(key);
121
+ }
122
+ }
123
+ if (!advanced) break;
124
+ }
125
+ return inventoryShape(source, kept);
126
+ }
127
+
128
+ interface PreparedSession {
129
+ metadata: Record<string, unknown>;
130
+ messages: WindowMessage[];
131
+ }
132
+
133
+ function hydrationError(error: unknown): { kind: "missing" | "oversized" | "unreadable"; message: string } {
134
+ const message = (error instanceof Error ? error.message : String(error)).slice(0, ERROR_MESSAGE_CHARS);
135
+ const code = (error as NodeJS.ErrnoException)?.code;
136
+ return {
137
+ kind: code === "ENOENT" ? "missing" : message.includes("exceeds 32 MiB snapshot limit") ? "oversized" : "unreadable",
138
+ message,
139
+ };
140
+ }
141
+
142
+ function hydratePreparationSession(row: PreparationSessionRow): PreparedSession {
143
+ const indexed = {
144
+ path: row.path,
145
+ cwd: row.cwd,
146
+ name: row.name ?? null,
147
+ startedAt: row.startedAt ?? null,
148
+ lineageId: row.lineageId,
149
+ };
150
+ try {
151
+ const hydrated = readSession(row.path, 20, 10, { userAssistantTextOnly: true });
152
+ return {
153
+ metadata: {
154
+ ...indexed,
155
+ branchTip: hydrated.branchTip,
156
+ totalMessages: hydrated.totalMessages,
157
+ truncated: hydrated.truncated,
158
+ contentTruncated: false,
159
+ messages: [],
160
+ },
161
+ messages: hydrated.messages,
162
+ };
163
+ } catch (error) {
164
+ return {
165
+ metadata: {
166
+ ...indexed,
167
+ branchTip: null,
168
+ totalMessages: null,
169
+ truncated: false,
170
+ contentTruncated: false,
171
+ messages: [],
172
+ error: hydrationError(error),
173
+ },
174
+ messages: [],
175
+ };
176
+ }
177
+ }
178
+
179
+ function allocatePreparationMessages(session: PreparedSession, budget: number): Record<string, unknown> {
180
+ if (session.messages.length === 0) return session.metadata;
181
+ if (JSON.stringify(session.messages).length - 2 <= budget) {
182
+ return { ...session.metadata, messages: session.messages };
183
+ }
184
+ const maxLen = Math.max(...session.messages.map((message) => message.content.length), 0);
185
+ const cap = maxFittingCap(maxLen, budget + 2, (value) => truncateContent(session.messages, value));
186
+ return {
187
+ ...session.metadata,
188
+ contentTruncated: true,
189
+ messages: cap === null ? [] : truncateContent(session.messages, cap),
190
+ };
191
+ }
192
+
193
+ function buildPreparationResult(
194
+ kind: "repository" | "all",
195
+ requestedLimit: number,
196
+ gitRoot: string | undefined,
197
+ syncResult: ReturnType<typeof syncSessions>,
198
+ rows: PreparationSessionRow[],
199
+ repositoryInventory: RepositoryInventory,
200
+ ): Record<string, unknown> {
201
+ const sync = {
202
+ walkComplete: syncResult.walkComplete,
203
+ backlogRemaining: syncResult.backlogRemaining,
204
+ complete: syncResult.walkComplete && syncResult.backlogRemaining === 0,
205
+ };
206
+ const sessions = rows.map(hydratePreparationSession);
207
+ const minimumInventory = inventoryShape(repositoryInventory, collectionRecord(() => []));
208
+ const build = (
209
+ preparedSessions: Record<string, unknown>[],
210
+ inventory: Record<string, unknown>,
211
+ contentTruncated: boolean,
212
+ ) => ({
213
+ mode: "prepare-pattern-miner",
214
+ scope: { kind, gitRoot: gitRoot ?? null, requestedLimit, sampledCount: preparedSessions.length },
215
+ sync,
216
+ sessions: preparedSessions,
217
+ inventory,
218
+ contentTruncated,
219
+ });
220
+
221
+ const metadataOnlyLength = JSON.stringify(build(sessions.map((session) => session.metadata), minimumInventory, false)).length;
222
+ if (metadataOnlyLength > OUTPUT_CHAR_BUDGET) throw new Error("Pattern-miner preparation metadata exceeds output budget.");
223
+ const inventoryBudget = Math.min(
224
+ INVENTORY_CHAR_BUDGET,
225
+ JSON.stringify(minimumInventory).length + OUTPUT_CHAR_BUDGET - metadataOnlyLength,
226
+ );
227
+ const inventory = boundInventory(repositoryInventory, inventoryBudget);
228
+ const baseLength = JSON.stringify(build(sessions.map((session) => session.metadata), inventory, false)).length;
229
+ const perSessionBudget = sessions.length === 0 ? 0 : Math.floor((OUTPUT_CHAR_BUDGET - baseLength) / sessions.length);
230
+ const allocated = sessions.map((session) => allocatePreparationMessages(session, perSessionBudget));
231
+ const contentTruncated = allocated.some((session) => session.contentTruncated === true);
232
+ return build(allocated, inventory, contentTruncated);
233
+ }
234
+
235
+ // Output schema: one variant per mode, discriminated by `mode`. Codemode scripts
236
+ // receive this structured value; the model receives the identical JSON text.
237
+ const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()]);
238
+ const WindowMessageSchema = Type.Object({
239
+ entryId: Type.String(),
240
+ role: Type.String(),
241
+ content: Type.String(),
242
+ timestamp: Type.String(),
243
+ anchor: Type.Optional(Type.Boolean()),
244
+ });
245
+ const SyncWarningSchema = Type.Union([
246
+ Type.Object({ kind: Type.Literal("incomplete-walk") }),
247
+ Type.Object({ kind: Type.Literal("sync-failed"), error: Type.String() }),
248
+ ]);
249
+ /** Character-level trimming to the 50,000-character result budget. */
250
+ const contentTruncated = Type.Optional(Type.Boolean());
251
+ const OUTPUT_SCHEMA = Type.Union([
252
+ Type.Object({
253
+ mode: Type.Literal("browse"),
254
+ sessions: Type.Array(Type.Object({
255
+ path: Type.String(),
256
+ cwd: Type.String(),
257
+ name: Type.Optional(Type.String()),
258
+ startedAt: Type.Optional(Type.String()),
259
+ preview: Type.Optional(Type.String()),
260
+ })),
261
+ syncWarning: Type.Optional(SyncWarningSchema),
262
+ contentTruncated,
263
+ }),
264
+ Type.Object({
265
+ mode: Type.Literal("discovery"),
266
+ query: Type.String(),
267
+ results: Type.Array(Type.Object({
268
+ path: Type.String(),
269
+ snippet: Type.String(),
270
+ rank: Type.Number(),
271
+ matchMessageId: Type.String(),
272
+ role: Type.String(),
273
+ timestamp: Type.String(),
274
+ cwd: Type.Optional(Type.String()),
275
+ name: Type.Optional(Type.String()),
276
+ startedAt: Type.Optional(Type.String()),
277
+ })),
278
+ backlogRemaining: Type.Number(),
279
+ syncWarning: Type.Optional(SyncWarningSchema),
280
+ contentTruncated,
281
+ }),
282
+ Type.Object({
283
+ mode: Type.Literal("read"),
284
+ sessionId: Type.String(),
285
+ messages: Type.Array(WindowMessageSchema),
286
+ totalMessages: Type.Number(),
287
+ truncated: Type.Boolean(),
288
+ branchTip: Nullable(Type.String()),
289
+ contentTruncated,
290
+ }),
291
+ Type.Object({
292
+ mode: Type.Literal("scroll"),
293
+ sessionId: Type.String(),
294
+ branchTip: Type.String(),
295
+ messagesBefore: Type.Number(),
296
+ messagesAfter: Type.Number(),
297
+ messages: Type.Array(WindowMessageSchema),
298
+ contentTruncated,
299
+ }),
300
+ Type.Object({
301
+ mode: Type.Literal("prepare-pattern-miner"),
302
+ scope: Type.Object({
303
+ kind: StringEnum(["repository", "all"] as const),
304
+ gitRoot: Nullable(Type.String()),
305
+ requestedLimit: Type.Number(),
306
+ sampledCount: Type.Number(),
307
+ }),
308
+ sync: Type.Object({ walkComplete: Type.Boolean(), backlogRemaining: Type.Number(), complete: Type.Boolean() }),
309
+ sessions: Type.Array(Type.Object({
310
+ path: Type.String(),
311
+ cwd: Type.String(),
312
+ name: Nullable(Type.String()),
313
+ startedAt: Nullable(Type.String()),
314
+ lineageId: Type.String(),
315
+ branchTip: Nullable(Type.String()),
316
+ totalMessages: Nullable(Type.Number()),
317
+ truncated: Type.Boolean(),
318
+ contentTruncated: Type.Boolean(),
319
+ messages: Type.Array(WindowMessageSchema),
320
+ error: Type.Optional(Type.Object({
321
+ kind: StringEnum(["missing", "oversized", "unreadable"] as const),
322
+ message: Type.String(),
323
+ })),
324
+ })),
325
+ inventory: Type.Object({
326
+ available: Type.Boolean(),
327
+ reason: Type.Optional(StringEnum(["not-a-git-repository", "inventory-failed"] as const)),
328
+ provenance: Type.Optional(Type.Object({
329
+ packageScripts: Type.Literal("git-index"),
330
+ executableScripts: Type.Literal("git-index"),
331
+ agentInstructions: Type.Literal("git-index"),
332
+ skills: Type.Literal("pi-effective-registry"),
333
+ })),
334
+ worktreeVerified: Type.Literal(false),
335
+ packageScripts: Type.Array(Type.Object({ path: Type.String(), name: Type.String(), command: Type.String() })),
336
+ executableScripts: Type.Array(Type.String()),
337
+ skills: Type.Array(Type.Object({ name: Type.String(), description: Type.String(), sourcePath: Type.String() })),
338
+ agentInstructions: Type.Array(Type.String()),
339
+ truncated: Type.Boolean(),
340
+ omittedCounts: Type.Object({
341
+ packageScripts: Type.Number(),
342
+ executableScripts: Type.Number(),
343
+ skills: Type.Number(),
344
+ agentInstructions: Type.Number(),
345
+ }),
346
+ }),
347
+ contentTruncated: Type.Boolean(),
348
+ }),
349
+ ]);
350
+
351
+ const DESCRIPTION = `Search past Pi sessions locally with FTS5; returns indexed metadata and snippets.
352
+
353
+ - \`operation: "prepare-pattern-miner"\` + \`scope\`: prepare one bounded corpus and repository inventory.
354
+ - \`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.
355
+ - \`sessionId\` + \`aroundMessageId\`: scroll ±\`window\`; retain \`branchTip\` across forks.
356
+ - \`sessionId\` alone: read; no args: browse recent sessions.
357
+ - Discovery returns metadata and snippets. Use a result's \`path\` and \`matchMessageId\` for a follow-up scroll.
358
+ - Invalid arguments, refused or missing session files, and failed preparation are tool errors.`;
359
+
360
+ export default function (pi: ExtensionAPI): void {
361
+ // Best-effort sync at startup, deferred so the synchronous walk + SQLite
362
+ // writes never block session start. The lazy in-tool-call sync retries.
363
+ pi.on("session_start", (_event, _ctx) => {
364
+ setTimeout(() => {
365
+ try {
366
+ syncSessions(sessionsDir(), dbPath());
367
+ } catch {
368
+ // Index stays stale; next tool call retries.
369
+ }
370
+ }, 0);
371
+ });
372
+
373
+ pi.registerTool({
374
+ name: "session_search",
375
+ label: "Session Search",
376
+ description: DESCRIPTION,
377
+ promptSnippet: "Search past Pi sessions for prior decisions and context",
378
+ promptGuidelines: [
379
+ "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.",
380
+ ],
381
+ parameters: Type.Object({
382
+ operation: Type.Optional(StringEnum(["prepare-pattern-miner"] as const)),
383
+ scope: Type.Optional(StringEnum(["repository", "all"] as const)),
384
+ query: Type.Optional(Type.String({ description: "Search query (discovery). FTS5 syntax supported." })),
385
+ sessionId: Type.Optional(Type.String({ description: "Absolute path of the session file." })),
386
+ aroundMessageId: Type.Optional(Type.String({ description: "Anchor entry id for scroll mode — centers the window (with sessionId)." })),
387
+ 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." })),
388
+ window: Type.Optional(Type.Number({ description: "Scroll window radius, [1,20], default 5." })),
389
+ limit: Type.Optional(Type.Number({ description: "Max results, [1,10]. Defaults to 10 for preparation and 3 otherwise." })),
390
+ }, { additionalProperties: false }),
391
+ outputSchema: OUTPUT_SCHEMA,
392
+ annotations: { readOnlyHint: true, openWorldHint: false },
393
+ renderResult(result, { expanded }, theme) {
394
+ const output = result.content.find((part) => part.type === "text")?.text ?? "";
395
+ const styledOutput = theme.fg("toolOutput", output);
396
+ if (expanded) return new Text(`\n${styledOutput}`, 0, 0);
397
+ // Pi renders every transcript component on every frame, so cache lines per width.
398
+ let cachedWidth: number | undefined;
399
+ let cachedLines: string[] | undefined;
400
+ return {
401
+ render(width: number) {
402
+ if (cachedLines !== undefined && cachedWidth === width) return cachedLines;
403
+ const preview = truncateToVisualLines(styledOutput, 5, width);
404
+ if (preview.skippedCount === 0) {
405
+ cachedLines = ["", ...preview.visualLines];
406
+ } else {
407
+ const hint = theme.fg("muted", `... (${preview.skippedCount} earlier lines,`) +
408
+ ` ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
409
+ cachedLines = ["", truncateToWidth(hint, width, "..."), ...preview.visualLines];
410
+ }
411
+ cachedWidth = width;
412
+ return cachedLines;
413
+ },
414
+ invalidate() {
415
+ cachedWidth = undefined;
416
+ cachedLines = undefined;
417
+ },
418
+ };
419
+ },
420
+ // Failures throw: Pi marks the result as an error for the model, and
421
+ // codemode scripts reject instead of receiving a success-shaped value.
422
+ async execute(_toolCallId, params, signal, _onUpdate, ctx) {
423
+ if (params.scope !== undefined && params.operation === undefined) {
424
+ throw new Error("scope requires operation: prepare-pattern-miner.");
425
+ }
426
+ if (params.operation === "prepare-pattern-miner") {
427
+ const incompatible = (["query", "sessionId", "aroundMessageId", "branchTip", "window"] as const)
428
+ .filter((key) => params[key] !== undefined);
429
+ if (incompatible.length > 0) {
430
+ throw new Error(`prepare-pattern-miner does not accept: ${incompatible.join(", ")}.`);
431
+ }
432
+ if (params.scope !== "repository" && params.scope !== "all") {
433
+ throw new Error("prepare-pattern-miner requires scope: repository or all.");
434
+ }
435
+ const limit = clamp(params.limit, 1, 10, 10);
436
+ const inventory = await inventoryRepository(
437
+ pi,
438
+ { cwd: ctx.cwd, signal },
439
+ params.scope === "repository" ? "required" : "optional",
440
+ );
441
+ const sync = syncSessions(sessionsDir(), dbPath());
442
+ const currentSessionPath = ctx.sessionManager.getSessionFile() ?? undefined;
443
+ const rows = getPreparationRows(dbPath(), {
444
+ limit,
445
+ ...(params.scope === "repository" ? { repositoryRoot: inventory.gitRoot! } : {}),
446
+ currentSessionPath,
447
+ });
448
+ return textResult(buildPreparationResult(params.scope, limit, inventory.gitRoot, sync, rows, inventory));
449
+ }
450
+
451
+ let sessionId = params.sessionId?.trim() || undefined;
452
+ const anchor = params.aroundMessageId?.trim() || undefined;
453
+ if (sessionId) {
454
+ // Trust boundary: canonical target must live under the real
455
+ // sessions dir (realpath defeats symlink escapes).
456
+ let resolved: string;
457
+ let root: string;
458
+ try {
459
+ resolved = realpathSync(sessionId);
460
+ root = realpathSync(sessionsDir());
461
+ } catch {
462
+ throw new Error(`session file not found: ${sessionId}`.slice(0, OUTPUT_CHAR_BUDGET));
463
+ }
464
+ if (!resolved.startsWith(root + sep) || !resolved.endsWith(".jsonl")) {
465
+ throw new Error("sessionId must be a .jsonl file under the Pi sessions directory");
466
+ }
467
+ // Rebind to the validated canonical path so downstream reads cannot
468
+ // be redirected by a symlink swapped in after validation (TOCTOU).
469
+ sessionId = resolved;
470
+ }
471
+
472
+ // --- SCROLL ---
473
+ if (sessionId && anchor) {
474
+ const w = clamp(params.window, 1, 20, 5);
475
+ const branchTip = params.branchTip?.trim() || undefined;
476
+ let win: ReturnType<typeof getWindow>;
477
+ try {
478
+ win = getWindow(sessionId, anchor, w, branchTip ? { branchTip } : undefined);
479
+ } catch (error) {
480
+ if (error instanceof Error && error.message.length > OUTPUT_CHAR_BUDGET) {
481
+ throw new Error(error.message.slice(0, OUTPUT_CHAR_BUDGET), { cause: error });
482
+ }
483
+ throw error;
484
+ }
485
+ const base = { mode: "scroll", sessionId, branchTip: win.branchTip, messagesBefore: win.messagesBefore, messagesAfter: win.messagesAfter };
486
+ return textResult(boundMessages(base, win.messages));
487
+ }
488
+
489
+ // --- READ ---
490
+ if (sessionId) {
491
+ const { messages, ...metadata } = readSession(sessionId);
492
+ return textResult(boundMessages({ mode: "read", sessionId, ...metadata }, messages));
493
+ }
494
+
495
+ // Lazy sync: drains any backlog the capped startup pass left. A partial
496
+ // or failed sync degrades to a warning; the stale index stays usable.
497
+ let syncWarning: { kind: "incomplete-walk" } | { kind: "sync-failed"; error: string } | undefined;
498
+ try {
499
+ const sync = syncSessions(sessionsDir(), dbPath());
500
+ if (!sync.walkComplete) syncWarning = { kind: "incomplete-walk" };
501
+ } catch (error) {
502
+ syncWarning = { kind: "sync-failed", error: (error instanceof Error ? error.message : String(error)).slice(0, 512) };
503
+ }
504
+
505
+ // --- BROWSE ---
506
+ if (!params.query?.trim()) {
507
+ const rows = getSessionRows(dbPath(), clamp(params.limit, 1, 10, 3));
508
+ return textResult({ mode: "browse", sessions: rows, ...(syncWarning ? { syncWarning } : {}) });
509
+ }
510
+
511
+ // --- DISCOVERY ---
512
+ const limit = clamp(params.limit, 1, 10, 3);
513
+ const { hits, backlogRemaining } = searchIndex(dbPath(), params.query, {
514
+ limit,
515
+ // Exclude the whole current file.
516
+ currentSessionPath: ctx.sessionManager.getSessionFile() ?? undefined,
517
+ });
518
+
519
+ const resultQuery = params.query!.trim().slice(0, MAX_QUERY_CHARS);
520
+ return textResult({
521
+ mode: "discovery",
522
+ query: resultQuery,
523
+ results: hits,
524
+ backlogRemaining,
525
+ ...(syncWarning ? { syncWarning } : {}),
526
+ });
527
+ },
528
+ });
529
+ }
530
+
531
+ function textResult(result: Record<string, unknown>) {
532
+ let bounded = result;
533
+ let text = JSON.stringify(bounded);
534
+ if (text.length > OUTPUT_CHAR_BUDGET) {
535
+ const copy: Record<string, unknown> = { ...bounded, contentTruncated: true };
536
+ for (const key of ["results", "sessions", "messages"] as const) {
537
+ if (Array.isArray(copy[key])) copy[key] = [...copy[key] as unknown[]];
538
+ }
539
+ bounded = copy;
540
+ text = JSON.stringify(bounded);
541
+ while (text.length > OUTPUT_CHAR_BUDGET) {
542
+ const array = ["results", "sessions", "messages"]
543
+ .map((key) => copy[key])
544
+ .find((value): value is unknown[] => Array.isArray(value) && value.length > 0);
545
+ if (!array) throw new Error("session_search result metadata exceeds output budget");
546
+ array.pop();
547
+ text = JSON.stringify(bounded);
548
+ }
549
+ }
550
+ // structuredContent is the parsed text, so scripts and the model see one value.
551
+ return {
552
+ content: [{ type: "text" as const, text }],
553
+ details: bounded,
554
+ structuredContent: JSON.parse(text),
555
+ };
556
+ }
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Neutral JSONL trust boundary for Pi session transcripts: one bounded,
3
+ * descriptor-validated snapshot per read, parsed into entries whose only
4
+ * trusted fields are the validated id/parentId pair. No pi runtime imports —
5
+ * shared by the index engine (search-core) and hydration (hydrate).
6
+ */
7
+ import fs from "node:fs";
8
+
9
+ /** Hard byte ceiling per session file: larger files are skipped (and retried
10
+ * behind fresh work) instead of being read whole into memory. */
11
+ export const MAX_SESSION_FILE_BYTES = 32 * 1024 * 1024;
12
+
13
+ /** Open the path once, validate that exact descriptor (type + size), and read
14
+ * only the validated snapshot from it. A concurrent append/replacement between
15
+ * the walk's stat and this open cannot grow the allocation or the read beyond
16
+ * maxBytes: the fd pins the inode, and fstat on that fd fixes both bounds.
17
+ * Deliberately not fs.readFileSync(fd) — that re-reads to EOF unbounded.
18
+ * Shared with hydration: callers pass their own byte ceiling (both use
19
+ * MAX_SESSION_FILE_BYTES in production). */
20
+ export function readBoundedSnapshot(filePath: string, maxBytes: number): string {
21
+ // O_NONBLOCK keeps a writerless FIFO (regular .jsonl swapped mid-walk) from
22
+ // blocking this open before fstat rejects it; O_NOFOLLOW (absent on Windows)
23
+ // rejects a symlink swapped in after the walk instead of following it.
24
+ const fd = fs.openSync(
25
+ filePath,
26
+ fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | (fs.constants.O_NOFOLLOW ?? 0),
27
+ );
28
+ try {
29
+ const st = fs.fstatSync(fd);
30
+ if (!st.isFile()) throw new Error(`session path is not a regular file: ${filePath}`);
31
+ if (st.size > maxBytes) {
32
+ throw new Error(`session file exceeds ${Math.round(maxBytes / (1024 * 1024))} MiB snapshot limit: ${filePath}`);
33
+ }
34
+ const buf = Buffer.allocUnsafe(st.size);
35
+ let read = 0;
36
+ while (read < buf.length) {
37
+ const n = fs.readSync(fd, buf, read, buf.length - read, read);
38
+ if (n === 0) break; // truncated concurrently after fstat: index what was there
39
+ read += n;
40
+ }
41
+ return buf.toString("utf-8", 0, read);
42
+ } finally {
43
+ fs.closeSync(fd);
44
+ }
45
+ }
46
+
47
+ /** One parseable JSONL line. `data` is the raw parsed JSON value — any JSON
48
+ * type, never assumed to be an object. `id`/`parentId` exist only when both
49
+ * passed validation at this boundary; consumers may rely on them without
50
+ * re-validating. */
51
+ export interface TranscriptEntry {
52
+ data: unknown;
53
+ /** Nonempty string ≤256 chars; absent when missing or invalid. */
54
+ id?: string;
55
+ /** null or string ≤256 chars; defined only when `id` is present. */
56
+ parentId?: string | null;
57
+ }
58
+
59
+ /** Validate the id pair exactly as both previous parsers did: a valid entry
60
+ * needs a usable id AND a nullish-or-valid parentId; anything else is treated
61
+ * as id-less data (still projected for headers, never hydrated). */
62
+ function validateIds(data: unknown): { id: string; parentId: string | null } | undefined {
63
+ const rec = data !== null && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
64
+ const id = rec?.id;
65
+ if (typeof id !== "string" || id.length === 0 || id.length > 256) return undefined;
66
+ const parentId = rec?.parentId;
67
+ if (parentId == null) return { id, parentId: null };
68
+ if (typeof parentId === "string" && parentId.length <= 256) return { id, parentId };
69
+ return undefined;
70
+ }
71
+
72
+ /** Lazily yield one bounded snapshot of `filePath` as JSONL entries in file
73
+ * order — no materialized entry array, and lines are located by newline
74
+ * scan rather than splitting the whole snapshot into a string array.
75
+ * Blank and malformed JSON lines are skipped. The first occurrence of
76
+ * every valid id is reserved across all entry types; later duplicates are
77
+ * dropped entirely. Entries without a valid id pair are retained so index
78
+ * header/session_info projection can still use them — hydration projects to
79
+ * entries carrying a validated `id`. The snapshot is read once when iteration
80
+ * starts (fd-pinned descriptor validation still applies); consumers iterate
81
+ * immediately via for-of. */
82
+ export function* readTranscriptEntries(
83
+ filePath: string,
84
+ maxBytes: number = MAX_SESSION_FILE_BYTES,
85
+ ): Generator<TranscriptEntry> {
86
+ const content = readBoundedSnapshot(filePath, maxBytes);
87
+ const seenIds = new Set<string>();
88
+ let start = 0;
89
+ while (start < content.length) {
90
+ const nl = content.indexOf("\n", start);
91
+ const end = nl === -1 ? content.length : nl;
92
+ const line = content.slice(start, end);
93
+ start = end + 1;
94
+ if (!line.trim()) continue;
95
+ let data: unknown;
96
+ try {
97
+ data = JSON.parse(line);
98
+ } catch {
99
+ continue; // skip malformed lines
100
+ }
101
+ const ids = validateIds(data);
102
+ if (!ids) {
103
+ yield { data };
104
+ continue;
105
+ }
106
+ // Hydration is first-wins across every entry type; reserve IDs here so
107
+ // no consumer can ever point at a different duplicate.
108
+ if (seenIds.has(ids.id)) continue;
109
+ seenIds.add(ids.id);
110
+ yield { data, id: ids.id, parentId: ids.parentId };
111
+ }
112
+ }