@monotykamary/pi-vcc 0.3.16

package/src/core/format-recall.ts

@@ -0,0 +1,177 @@
+import type { SearchHit } from "./search-entries";
+
+// Roles that start a new conversation segment (turn).
+// A segment begins at a user or bashExecution (user-initiated action)
+// and continues through assistant responses, tool calls, and tool results
+// until the next user/bash boundary.
+const SEGMENT_START_ROLES = new Set(["user", "bash"]);
+
+/**
+ * A segment is a contiguous group of entries forming one conversational turn:
+ * a user/assistant message followed by its associated tool calls, tool results,
+ * and bash executions. The next user/assistant message starts a new segment.
+ */
+interface RecallSegment {
+  /** Entry indices covered by this segment (e.g. "#42-#47") */
+  range: string;
+  /** All entries in this segment, in order */
+  entries: SearchHit[];
+  /** Which entries within this segment matched the query */
+  matchedIndices: Set<number>;
+}
+
+/**
+ * Group entries into conversation segments (turns).
+ *
+ * A segment starts at a user or assistant message and includes all
+ * subsequent tool calls, tool results, and bash executions until
+ * the next user/assistant boundary.
+ *
+ * When entries lack explicit `snippet` markers (e.g. called from
+ * external code or tests), all entries in query mode are treated
+ * as matched.
+ */
+const groupSegments = (entries: SearchHit[], hasQuery: boolean): RecallSegment[] => {
+  if (entries.length === 0) return [];
+
+  // Detect whether entries have snippet markers set.
+  // If none do but we have a query, treat the entire set as matched.
+  const anySnippet = entries.some((e) => e.snippet !== undefined);
+  const assumeAllMatched = hasQuery && !anySnippet;
+
+  const segments: RecallSegment[] = [];
+  let start = 0;
+
+  for (let i = 1; i < entries.length; i++) {
+    const role = entries[i].role;
+    if (SEGMENT_START_ROLES.has(role)) {
+      const slice = entries.slice(start, i);
+      const matched = new Set<number>();
+      for (let j = 0; j < slice.length; j++) {
+        if (assumeAllMatched || slice[j].snippet) matched.add(j);
+      }
+      segments.push({
+        range: `#${slice[0].index}` +
+          (slice.length > 1 ? `-#${slice[slice.length - 1].index}` : ""),
+        entries: slice,
+        matchedIndices: matched,
+      });
+      start = i;
+    }
+  }
+
+  // Last segment
+  const slice = entries.slice(start);
+  if (slice.length > 0) {
+    const matched = new Set<number>();
+    for (let j = 0; j < slice.length; j++) {
+      if (assumeAllMatched || slice[j].snippet) matched.add(j);
+    }
+    segments.push({
+      range: `#${slice[0].index}` +
+        (slice.length > 1 ? `-#${slice[slice.length - 1].index}` : ""),
+      entries: slice,
+      matchedIndices: matched,
+    });
+  }
+
+  return segments;
+};
+
+/** Format a single entry line with optional match indicator. */
+const formatEntry = (e: SearchHit, matched: boolean): string => {
+  const prefix = matched ? ">" : " ";
+  const fileSuffix = e.files?.length ? ` files:[${e.files.join(", ")}]` : "";
+  const body = matched && e.snippet ? e.snippet : e.summary;
+  return `${prefix} #${e.index} [${e.role}]${fileSuffix} ${body}`;
+};
+
+/** Format a segment with its entries. */
+const formatSegment = (seg: RecallSegment): string => {
+  const lines: string[] = [];
+
+  // Segment header with match count
+  const matchCount = seg.matchedIndices.size;
+  if (matchCount > 0 && matchCount < seg.entries.length) {
+    lines.push(`--- ${seg.range} (${matchCount}/${seg.entries.length} entries match) ---`);
+  } else if (matchCount > 0) {
+    lines.push(`--- ${seg.range} ---`);
+  } else {
+    lines.push(`--- ${seg.range} (context) ---`);
+  }
+
+  for (let i = 0; i < seg.entries.length; i++) {
+    const matched = seg.matchedIndices.has(i);
+    lines.push(formatEntry(seg.entries[i], matched));
+  }
+
+  return lines.join("\n");
+};
+
+/** Count total unique matches across all segments. */
+const countMatches = (segments: RecallSegment[]): number => {
+  let total = 0;
+  for (const seg of segments) {
+    total += seg.matchedIndices.size;
+  }
+  return total;
+};
+
+export const formatRecallOutput = (
+  entries: SearchHit[],
+  query?: string,
+  headerOverride?: string,
+): string => {
+  if (entries.length === 0) {
+    return query
+      ? `No matches for "${query}" in session history.`
+      : "No entries in session history.";
+  }
+
+  // Browse mode (no query): keep flat format, no structure needed
+  if (!query) {
+    const header = headerOverride || `Session history (${entries.length} entries):`;
+    const lines = entries.map((e) => {
+      const fileSuffix = e.files?.length ? ` files:[${e.files.join(", ")}]` : "";
+      return `#${e.index} [${e.role}]${fileSuffix} ${e.summary}`;
+    });
+    return `${header}\n\n${lines.join("\n\n")}`;
+  }
+
+  // Search mode: group into structure-preserving segments
+  const header = headerOverride
+    ? `${headerOverride} for "${query}":`
+    : `Found ${entries.length} matches for "${query}":`;
+
+  const segments = groupSegments(entries, true);
+  const matchedCount = countMatches(segments);
+
+  const prefix = segments.length > 1
+    ? `${matchedCount} matches across ${segments.length} segments`
+    : `${matchedCount} matches in 1 segment`;
+
+  const formatted = segments
+    .filter((seg) => seg.matchedIndices.size > 0)
+    .map(formatSegment);
+
+  // Add adjacent non-matching segments as context around the first
+  // matched segment (so the agent sees the conversation flow).
+  if (segments.length > 1) {
+    const firstMatchIdx = segments.findIndex((s) => s.matchedIndices.size > 0);
+    if (firstMatchIdx >= 0) {
+      // Show the segment before for context (only if it has no matches itself)
+      if (firstMatchIdx > 0 && segments[firstMatchIdx - 1].matchedIndices.size === 0) {
+        formatted.unshift(formatSegment(segments[firstMatchIdx - 1]));
+      }
+      // Show the segment after for context (only if not already shown)
+      if (firstMatchIdx < segments.length - 1) {
+        const next = segments[firstMatchIdx + 1];
+        if (next.matchedIndices.size === 0) {
+          formatted.push(formatSegment(next));
+        }
+      }
+    }
+  }
+
+  return `${header} \u2014 ${prefix}\n\n${formatted.join("\n\n")}`;
+};

package/src/core/format.ts

@@ -0,0 +1,98 @@
+import type { SectionData } from "../sections";
+
+const section = (title: string, items?: string[]): string => {
+  if (!items || items.length === 0) return "";
+  const body = items.map((i) => `- ${i}`).join("\n");
+  return `[${title}]\n${body}`;
+};
+
+const BRIEF_MAX_LINES = 120;
+const TUI_SAFE_LINE_CHARS = 120;
+
+const wrapLine = (line: string, maxChars: number): string[] => {
+  if (line.length <= maxChars) return [line];
+
+  const indent = line.match(/^\s*(?:[-*]\s+|\d+\.\s+)?/)?.[0] ?? "";
+  const continuationIndent = indent ? " ".repeat(Math.min(indent.length, 8)) : "";
+  const wrapped: string[] = [];
+  let remaining = line;
+  let prefix = "";
+
+  while (prefix.length + remaining.length > maxChars) {
+    const available = Math.max(20, maxChars - prefix.length);
+    let splitAt = remaining.lastIndexOf(" ", available);
+    if (splitAt < Math.floor(available * 0.5)) splitAt = available;
+
+    wrapped.push(prefix + remaining.slice(0, splitAt).trimEnd());
+    remaining = remaining.slice(splitAt).trimStart();
+    prefix = continuationIndent;
+  }
+
+  if (remaining) wrapped.push(prefix + remaining);
+  return wrapped;
+};
+
+export const wrapLongLines = (text: string, maxChars = TUI_SAFE_LINE_CHARS): string =>
+  text.split("\n").flatMap((line) => wrapLine(line, maxChars)).join("\n");
+
+export const capBrief = (text: string): string => {
+  const lines = text.split("\n");
+  if (lines.length <= BRIEF_MAX_LINES) return text;
+  const omitted = lines.length - BRIEF_MAX_LINES;
+  const kept = lines.slice(-BRIEF_MAX_LINES);
+  // Find first section header to avoid cutting mid-section
+  const firstHeader = kept.findIndex((l) => /^\[.+\]/.test(l));
+  const clean = firstHeader > 0 ? kept.slice(firstHeader) : kept;
+  return `...(${omitted} earlier lines omitted)\n\n${clean.join("\n")}`;
+};
+
+export const RECALL_NOTE =
+  "Use `vcc_recall` to search for prior work, decisions, and context from before this summary. " +
+  "Do not redo work already completed.";
+
+/**
+ * Format the summary with cache-friendly section ordering.
+ *
+ * Stable (merged/accumulated) sections come first so the prompt prefix
+ * stays cacheable across compactions. Volatile (always-fresh) sections
+ * come last.
+ */
+export const formatSummary = (
+  data: SectionData,
+): string => {
+  // Cache-friendly ordering: stable first, volatile last
+  const stableSections = [
+    section("Session Goal", data.sessionGoal),
+    section("User Preferences", data.userPreferences),
+    section("Files And Changes", data.filesAndChanges),
+    section("Commits", data.commits),
+    section("Anchors", data.anchors),
+  ].filter(Boolean);
+
+  const volatileSections = [
+    section("Type Catalog", data.typeCatalog),
+    section("Outstanding Context", data.outstandingContext),
+    section("Earlier Turns", data.turnSummaries),
+    section("Current Status", data.currentStatus),
+  ].filter(Boolean);
+
+  // All header sections (stable + volatile) form the header block
+  const allHeaders = [...stableSections, ...volatileSections];
+
+  const parts: string[] = [];
+  if (allHeaders.length > 0) {
+    parts.push(allHeaders.join("\n\n"));
+  }
+  if (data.briefTranscript) {
+    parts.push(capBrief(data.briefTranscript));
+  }
+
+  if (parts.length === 0) return "";
+
+  let result = wrapLongLines(parts.join("\n\n---\n\n"));
+
+  // NOTE: RECALL_NOTE is intentionally NOT appended here.
+  // It is appended once by `compile()` at the very end, after merge-with-previous,
+  // to avoid the note compounding inside the brief transcript across compactions.
+  return result;
+};

package/src/core/invisible-continue.ts

@@ -0,0 +1,172 @@
+import { Agent } from "@earendil-works/pi-agent-core";
+
+/**
+ * Invisible continue — resume the agent loop after compaction without
+ * injecting any message into context.
+ *
+ * Same mechanism as pi-retry: capture the live Agent instance via
+ * subscribe() monkey-patch, then call agent.prompt([]) to start a
+ * fresh agent loop that picks up where the compacted transcript left off.
+ * The LLM sees the exact same message list — no new user prompt.
+ *
+ * Used after threshold compaction when the agent would otherwise stall
+ * (willRetry=false, no queued messages).
+ */
+
+let _agent: Agent | null = null;
+let _continueInProgress = false;
+
+// Timestamp of the last completed triggerInvisibleContinue().
+// Used by the continue() monkey-patch to detect when triggerInvisibleContinue
+// just ran (so it shouldn't fall back to prompt([]) again — the agent
+// already continued). This prevents double continuation when both
+// pi-retry and pi-vcc are installed.
+let _lastInvisibleContinueTime = 0;
+
+// Monkey-patch Agent.prototype.subscribe to capture the live instance.
+// Chain the previous patch (if pi-retry already patched it) so both
+// extensions can coexist.
+const _prevSubscribe = Agent.prototype.subscribe;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+Agent.prototype.subscribe = function (this: Agent, ...args: any[]) {
+  _agent = this;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (_prevSubscribe as any).apply(this, args);
+};
+
+// Monkey-patch continue() so that after compaction, when the rebuilt
+// context ends with an assistant message, the agent loop can still
+// continue. Without this patch, the session's continue() call throws
+// "Cannot continue from message role: assistant" and the agent loop
+// exits — leaving mid-task work unfinished.
+//
+// The fix: when continue() would throw because the last message is an
+// assistant, fall back to prompt([]) instead. prompt([]) doesn't check
+// the last message role — it starts a fresh agent loop with the current
+// context. This is equivalent to the invisible-continue mechanism
+// (same call the extension fires from session_compact), but triggered
+// from the session's own continue() path so the while loop stays alive.
+//
+// Chains the previous patch (pi-retry, pi-invisible-continue) so all
+// mutexes are respected.
+const _prevContinue = Agent.prototype.continue;
+Agent.prototype.continue = function (this: Agent): Promise<void> {
+  const self = this;
+  return (async () => {
+    while (_continueInProgress) {
+      await new Promise(r => setTimeout(r, 10));
+    }
+    try {
+      return await (_prevContinue as any).call(self);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+
+      // After compaction, the rebuilt context often ends with an assistant
+      // message. The original continue() throws "Cannot continue from
+      // message role: assistant". Instead of swallowing the error and
+      // letting the agent loop die (which leaves mid-task work unfinished),
+      // fall back to prompt([]). This restarts the agent loop with the
+      // compacted context — the LLM picks up where it left off.
+      //
+      // prompt([]) is safe regardless of last message role. The agent
+      // processes the current context and continues.
+      //
+      // We only do this when the agent is NOT currently processing
+      // (no other triggerInvisibleContinue in flight) to avoid races.
+      if (msg.includes("Cannot continue from message role") ||
+          msg.includes("Cannot continue from an assistant message")) {
+        // Check stopReason of the last message — only continue if
+        // the agent was mid-task (not a clean stop or user abort).
+        const lastMsg = self.state.messages[self.state.messages.length - 1];
+        if (lastMsg?.role === "assistant" &&
+            lastMsg.stopReason !== "stop" &&
+            lastMsg.stopReason !== "aborted") {
+          // Agent was mid-task — fall through to prompt([])
+          // (after the error-handling block)
+        } else {
+          // Agent finished cleanly or was aborted — don't continue.
+          // The session loop should exit (task complete).
+          return;
+        }
+        // Fall back to prompt([]) to actually continue the agent.
+        // The while loop in _runAgentPrompt stays alive because prompt([])
+        // runs the agent (which emits events, updates _lastAssistantMessage,
+        // etc.).
+        //
+        // Guard: if triggerInvisibleContinue() just completed (within the
+        // last 500ms), the agent already continued — skip the fallback to
+        // avoid double continuation. This happens when both pi-retry and
+        // pi-vcc are installed: pi-retry's triggerInvisibleContinue runs
+        // first, then the session's continue() wrapper unblocks and would
+        // fall back to prompt([]) again.
+        if (!_continueInProgress && Date.now() - _lastInvisibleContinueTime > 500) {
+          _continueInProgress = true;
+          try {
+            await self.prompt([]);
+          } catch {
+            // Agent already processing or other transient error
+          } finally {
+            _continueInProgress = false;
+          }
+        }
+        return;
+      }
+
+      if (msg.includes("Agent is already processing")) {
+        // Another extension is driving the agent — wait it out.
+        return;
+      }
+      throw e;
+    }
+  })();
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Fire an invisible continue after the agent becomes idle.
+ *
+ * MUST NOT be awaited — it schedules work that runs after the current
+ * session loop iteration finishes.  Awaiting would deadlock inside the
+ * session's _handlePostAgentRun → _runAutoCompaction call stack.
+ */
+export function triggerInvisibleContinue(): void {
+  if (!_agent) return;
+  if (_continueInProgress) return;
+  _continueInProgress = true;
+
+  const run = async () => {
+    try {
+      // Wait for the current run to finish (activeRun resolves in
+      // finishRun() after agent_end listeners return).
+      await _agent!.waitForIdle();
+
+      // Small delay to ensure the session's while-loop has exited
+      // after _handlePostAgentRun returns false.
+      await sleep(50);
+
+      try {
+        // Await so _continueInProgress stays true for the full cycle.
+        await _agent!.prompt([]);
+      } catch {
+        // Ignore — if prompt throws, something else is driving.
+      }
+    } finally {
+      _continueInProgress = false;
+      // Record completion time so the continue() monkey-patch can
+      // detect that an invisible continue just ran and avoid firing
+      // a duplicate prompt([]) (RC7: double continuation guard).
+      _lastInvisibleContinueTime = Date.now();
+    }
+  };
+
+  void run();
+}
+
+/** Reset state on new session. */
+export function resetInvisibleContinue(): void {
+  _continueInProgress = false;
+  _lastInvisibleContinueTime = 0;
+}

package/src/core/lineage.ts

@@ -0,0 +1,26 @@
+interface LineageEntryLike {
+  id?: string;
+}
+
+interface LineageSessionManagerLike {
+  getBranch: () => LineageEntryLike[];
+  getEntries?: () => LineageEntryLike[];
+}
+
+export const getActiveLineageEntryIds = (sessionManager: LineageSessionManagerLike): Set<string> => {
+  try {
+    const branch = sessionManager.getBranch() ?? [];
+    if (branch.length > 0) {
+      return new Set(branch.map((e) => e.id).filter((id): id is string => Boolean(id)));
+    }
+  } catch {
+    // fall through to defensive fallback
+  }
+
+  try {
+    const all = sessionManager.getEntries?.() ?? [];
+    return new Set(all.map((e) => e.id).filter((id): id is string => Boolean(id)));
+  } catch {
+    return new Set();
+  }
+};

package/src/core/load-messages.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from "fs";
+import type { Message } from "@earendil-works/pi-ai";
+import { renderMessage, type RenderedEntry } from "./render-entries";
+
+interface LoadedMessages {
+  rendered: RenderedEntry[];
+  rawMessages: Message[];
+}
+
+export const loadAllMessages = (
+  sessionFile: string,
+  full: boolean,
+  allowedEntryIds?: Set<string>,
+  /** Optional filter by global message index (for compaction-scoped searches) */
+  entryFilter?: (globalIndex: number) => boolean,
+): LoadedMessages => {
+  const content = readFileSync(sessionFile, "utf-8");
+  const entries: any[] = [];
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try { entries.push(JSON.parse(line)); } catch {}
+  }
+  const rendered: RenderedEntry[] = [];
+  const rawMessages: Message[] = [];
+  let messageIndex = 0;
+  for (const e of entries) {
+    const isMessage = e.type === "message" && e.message;
+    if (!isMessage) continue;
+
+    const allowed = (!allowedEntryIds || allowedEntryIds.has(e.id)) &&
+      (!entryFilter || entryFilter(messageIndex));
+    if (allowed) {
+      rendered.push(renderMessage(e.message, messageIndex, full));
+      rawMessages.push(e.message);
+    }
+    messageIndex++;
+  }
+
+  return { rendered, rawMessages };
+};

package/src/core/normalize.ts

@@ -0,0 +1,73 @@
+import type { Message } from "@earendil-works/pi-ai";
+import type { NormalizedBlock } from "../types";
+import { textOf } from "./content";
+import { sanitize } from "./sanitize";
+
+const normalizeOne = (msg: Message, msgIndex: number): NormalizedBlock[] => {
+  if (msg.role === "user") {
+    const blocks: NormalizedBlock[] = [];
+    const text = sanitize(textOf(msg.content));
+    if (text) blocks.push({ kind: "user", text, sourceIndex: msgIndex });
+    if (msg.content && typeof msg.content !== "string") {
+      for (const part of msg.content) {
+        if (part.type === "image") {
+          blocks.push({ kind: "user", text: `[image: ${part.mimeType}]`, sourceIndex: msgIndex });
+        }
+      }
+    }
+    return blocks.length > 0 ? blocks : [{ kind: "user", text: "", sourceIndex: msgIndex }];
+  }
+
+  if ((msg as any).role === "bashExecution") {
+    const cmd = (msg as any).command ?? "";
+    const out = (msg as any).output ?? "";
+    const exit = (msg as any).exitCode;
+    return [{ kind: "bash", command: cmd, output: out, exitCode: exit, sourceIndex: msgIndex }];
+  }
+
+  if (msg.role === "toolResult") {
+    return [{
+      kind: "tool_result",
+      name: msg.toolName,
+      text: sanitize(textOf(msg.content)),
+      isError: msg.isError,
+      sourceIndex: msgIndex,
+    }];
+  }
+
+  if (msg.role === "assistant") {
+    if (!msg.content) return [];
+    if (typeof msg.content === "string") {
+      return [{ kind: "assistant", text: sanitize(msg.content), sourceIndex: msgIndex }];
+    }
+
+    const blocks: NormalizedBlock[] = [];
+    for (const part of msg.content) {
+      if (part.type === "text") {
+        blocks.push({ kind: "assistant", text: sanitize(part.text), sourceIndex: msgIndex });
+      } else if (part.type === "thinking") {
+        blocks.push({
+          kind: "thinking",
+          text: sanitize(part.thinking),
+          redacted: part.redacted ?? false,
+          sourceIndex: msgIndex,
+        });
+      } else if (part.type === "toolCall") {
+        blocks.push({
+          kind: "tool_call",
+          name: part.name,
+          args: part.arguments,
+          sourceIndex: msgIndex,
+        });
+      }
+    }
+    return blocks;
+  }
+
+  return [];
+};
+
+export const normalize = (messages: Message[]): NormalizedBlock[] =>
+  messages.flatMap((msg, i) => normalizeOne(msg, i));
+
+

package/src/core/recall-scope.ts

@@ -0,0 +1,49 @@
+type RecallScope = "lineage" | "all" | `compaction:${string}`;
+
+interface ParsedRecallScope {
+  scope: RecallScope;
+  compactionIndex?: number; // 0-based compaction number to scope to
+  text: string;
+}
+
+const SCOPE_RE = /\bscope:(lineage|all|compaction:(\d+|latest))\b/i;
+
+export const normalizeRecallScope = (
+  scope?: unknown,
+): RecallScope => {
+  if (typeof scope !== "string") return "lineage";
+  const lower = scope.toLowerCase();
+  if (lower === "all") return "all";
+  if (lower.startsWith("compaction:")) return lower as RecallScope;
+  return "lineage";
+};
+
+/**
+ * Parse scope directive from a recall query string or structured scope.
+ * Returns the parsed scope and the cleaned query text.
+ */
+export const parseRecallScope = (text: string): ParsedRecallScope => {
+  const match = text.match(SCOPE_RE);
+  if (!match) {
+    return { scope: "lineage", text: text.replace(/\s+/g, " ").trim() };
+  }
+
+  const rawScope = match[0];
+  const cleaned = text.replace(SCOPE_RE, "").replace(/\s+/g, " ").trim();
+
+  // compaction:N or compaction:latest
+  if (match[1]?.toLowerCase().startsWith("compaction")) {
+    const val = match[2];
+    if (val?.toLowerCase() === "latest") {
+      return { scope: "compaction:latest", text: cleaned };
+    }
+    const num = parseInt(val ?? "0", 10);
+    return {
+      scope: `compaction:${num}` as RecallScope,
+      compactionIndex: isNaN(num) ? undefined : num,
+      text: cleaned,
+    };
+  }
+
+  return { scope: normalizeRecallScope(match[1]), text: cleaned };
+};