@pratikgajjar/pi-recall 0.1.0 → 0.1.2

package/README.md

@@ -41,6 +41,28 @@ pi -e ./packages/pi-recall/src/index.ts
 
 All tools accept `repo` (pass `"."` for the current project), `source` (`cursor` \| `claude` \| `codex` \| `pi`), and `since` (e.g. `7d`).
 
+### Navigating large sessions
+
+Some sessions are huge (thousands of messages). `recall_transcript` takes
+three extra params to slice instead of dumping everything:
+
+- `range` — Python-style slice over the message list: `":100"` first 100,
+  `"-50:"` last 50, `"305:315"` window. Negative indices count from the end.
+- `outline` — one line per message: `[N] role: first-line`. A cheap table of
+  contents you can scan before slicing in.
+- `role` — comma-separated allowlist: `"user,assistant"` (skip tool noise),
+  `"user"` (just the prompts), `"tool"`. Tool-related labels (`toolResult`,
+  `toolCall`, `function_call`, …) all collapse to `tool`. In long agent loops,
+  ~50% of messages are tool noise; in some, 98% — a 30k-msg session shrinks to
+  ~600 with `role="user"`.
+
+Every rendered message carries its own `## msg N/TOTAL role` header so any
+slice is self-locating. **Default-cap:** if a session has more than 200
+messages and you ask for neither `range` nor `outline`, the tool returns the
+outline (plus a one-line note explaining how to drill in) instead of a
+context-blowing wall of text. After a `recall_search` hit at `msg_idx=N`,
+prefer `range: "N-5:N+5"` over reading the whole session.
+
 ### Recommended agent prompt
 
 Drop into your project's `AGENTS.md` / `CLAUDE.md`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pratikgajjar/pi-recall",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "pi extension: search your past AI chat history (Cursor, Claude Code, Codex, pi) via the recall CLI",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -338,37 +338,96 @@ export default function recallExtension(pi: ExtensionAPI) {
     repo: Type.Optional(Type.String({ description: REPO_HELP })),
     source: Type.Optional(Type.String({ description: SOURCE_HELP })),
     since: Type.Optional(Type.String({ description: SINCE_HELP })),
+    range: Type.Optional(
+      Type.String({
+        description:
+          "Python-style slice over the message list. ':100' = first 100, '-50:' = last 50, '305:315' = window around a recall_search hit (msg_idx). Negative indices count from the end.",
+      }),
+    ),
+    outline: Type.Optional(
+      Type.Boolean({
+        description:
+          "One line per message ([N] role: first-line). Use to navigate a large session before slicing in with 'range'.",
+      }),
+    ),
+    role: Type.Optional(
+      Type.String({
+        description:
+          "Comma-separated roles to keep: 'user', 'assistant', 'tool'. Tool-related roles (toolResult, toolCall, function_call, etc.) collapse to 'tool'. Use 'user,assistant' to skip tool noise (~50% of long agent loops are tool messages).",
+      }),
+    ),
   });
 
+  // Above this many messages, recall_transcript called without 'range' or
+  // 'outline' returns the outline instead of the full body — protects the
+  // agent from accidentally pulling a 25 MB transcript into context.
+  const BIG_SESSION_THRESHOLD = 200;
+
+  function parseMsgCount(outlineStdout: string): number {
+    const m = outlineStdout.match(/msgs=(\d+)\s+\(outline\)/);
+    return m ? Number.parseInt(m[1], 10) : 0;
+  }
+
   pi.registerTool({
     name: "recall_transcript",
     label: "recall transcript",
     description:
-      "Read a past AI session as a full transcript. Pass a session_id from recall_search, or omit it to get the most recent session (optionally filtered by repo/source/since).",
+      "Read a past AI session as a transcript. Pass a session_id from recall_search, or omit it to get the most recent session (optionally filtered by repo/source/since). Large sessions: use 'outline' to navigate, then 'range' to slice. After a recall_search hit at msg_idx=N, prefer range='N-5:N+5' over the full session.",
     promptSnippet: "Read a past AI session transcript",
     promptGuidelines: [
       "Call recall_transcript after recall_search to read a specific session before reusing its decisions.",
       "Omit session_id with repo: '.' to pull the most recent conversation in this project.",
+      "After a recall_search hit at msg_idx=N, call recall_transcript with range='N-5:N+5' to read around it instead of dumping the whole session.",
+      "For an unfamiliar large session, call with outline=true first — it returns one line per message so you can pick a range to drill into.",
     ],
     parameters: transcriptSchema,
 
     async execute(_id, params, signal) {
-      const args = params.session_id
-        ? ["show", params.session_id]
-        : ["last", ...buildFilterArgs({
-            repo: params.repo,
-            source: params.source,
-            since: params.since,
-          })];
-      const res = await runRecall(args, signal);
-      if (!res.ok) {
-        const msg = res.stderr || res.stdout.trim() || `recall exited with code ${res.code}`;
+      const filterArgs = buildFilterArgs({
+        repo: params.repo,
+        source: params.source,
+        since: params.since,
+      });
+      const cmd = params.session_id ? ["show", params.session_id] : ["last", ...filterArgs];
+
+      // Honor an explicit slice as-is (range / outline / role all count).
+      if (params.range || params.outline || params.role) {
+        if (params.range) cmd.push("--range", params.range);
+        if (params.outline) cmd.push("--outline");
+        if (params.role) cmd.push("--role", params.role);
+        const res = await runRecall(cmd, signal);
+        if (!res.ok) {
+          const msg = res.stderr || res.stdout.trim() || `recall exited with code ${res.code}`;
+          return { content: [{ type: "text", text: msg }], details: { found: false }, isError: true };
+        }
+        return {
+          content: [{ type: "text", text: capTranscript(res.stdout.trim()) }],
+          details: { found: true },
+        };
+      }
+
+      // No slice asked for: peek at the outline first to size the session.
+      // ~ms; lets us auto-protect the agent's context on huge transcripts.
+      const peek = await runRecall([...cmd, "--outline"], signal);
+      if (!peek.ok) {
+        const msg = peek.stderr || peek.stdout.trim() || `recall exited with code ${peek.code}`;
+        return { content: [{ type: "text", text: msg }], details: { found: false }, isError: true };
+      }
+      const msgCount = parseMsgCount(peek.stdout);
+      if (msgCount > BIG_SESSION_THRESHOLD) {
+        const note =
+          `// session has ${msgCount} messages; defaulting to outline. Call recall_transcript again with range='FROM:TO' (e.g. range='-50:') to read a slice.\n\n`;
         return {
-          content: [{ type: "text", text: msg }],
-          details: { found: false },
-          isError: true,
+          content: [{ type: "text", text: capTranscript(note + peek.stdout.trim()) }],
+          details: { found: true },
         };
       }
+      // Small session — the full transcript is safe.
+      const res = await runRecall(cmd, signal);
+      if (!res.ok) {
+        const msg = res.stderr || res.stdout.trim() || `recall exited with code ${res.code}`;
+        return { content: [{ type: "text", text: msg }], details: { found: false }, isError: true };
+      }
       return {
         content: [{ type: "text", text: capTranscript(res.stdout.trim()) }],
         details: { found: true },
@@ -378,11 +437,10 @@ export default function recallExtension(pi: ExtensionAPI) {
     renderCall(args, theme, context) {
       const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
       const target = args?.session_id ?? (args?.repo ? `last in ${args.repo}` : "last");
-      text.setText(
-        theme.fg("toolTitle", theme.bold("recall transcript")) +
-          " " +
-          theme.fg("accent", target),
-      );
+      let c = theme.fg("toolTitle", theme.bold("recall transcript")) + " " + theme.fg("accent", target);
+      if (args?.outline) c += theme.fg("muted", " [outline]");
+      else if (args?.range) c += theme.fg("muted", ` [${args.range}]`);
+      text.setText(c);
       return text;
     },
     renderResult(result, options, theme, context) {