pi-vcc 0.4.0

package/src/hooks/before-compact.ts

@@ -0,0 +1,405 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { convertToLlm } from "@mariozechner/pi-coding-agent";
+import { writeFile } from "fs/promises";
+import { compile } from "../core/summarize";
+import { loadSettings, type PiVccSettings } from "../core/settings";
+import type { PiVccCompactionDetails } from "../details";
+
+interface BranchEntry {
+  id: string;
+  type: string;
+  firstKeptEntryId?: string;
+  message?: { role: string; content: unknown };
+}
+
+export const PI_VCC_COMPACT_INSTRUCTION = "__pi_vcc__";
+
+export interface CompactionStats {
+  summarized: number;
+  kept: number;
+  keptTokensEst: number;
+}
+
+interface SessionState {
+  stats: CompactionStats | null;
+  wasPiVcc: boolean;
+}
+const sessionState = new WeakMap<object, SessionState>();
+let currentSessionStats: CompactionStats | null = null;
+
+export const getLastCompactionStats = () => currentSessionStats;
+
+import { formatTokens } from "../core/format";
+
+const UI_SETTLE_DELAY_MS = 500;
+
+const dbg = async (settings: PiVccSettings, data: Record<string, unknown>) => {
+  if (!settings.debug) return;
+  try {
+    await writeFile("/tmp/pi-vcc-debug.json", JSON.stringify(data, null, 2));
+  } catch (e) {
+    // Intentional fallback: UI notifications are best-effort and should not crash the compaction.
+  }
+};
+
+const previewContent = (content: unknown): string => {
+  if (typeof content === "string") return content.slice(0, 300);
+  if (Array.isArray(content)) {
+    return content
+      .map((c: any) => {
+        if (c?.type === "text") return c.text ?? "";
+        if (c?.type === "toolCall") return `[toolCall:${c.name}]`;
+        if (c?.type === "thinking") return `[thinking]`;
+        if (c?.type === "image") return `[image:${c.mimeType}]`;
+        return `[${c?.type ?? "unknown"}]`;
+      })
+      .join("\n")
+      .slice(0, 300);
+  }
+  return "";
+};
+
+interface EntryWithMessage {
+  entry: { id: string; type: string };
+  message: { role: string; content: unknown };
+}
+
+export type OwnCutCancelReason = "no_live_messages" | "too_few_live_messages" | "no_user_message";
+
+export type OwnCutResult =
+  | { ok: true; messages: any[]; firstKeptEntryId: string; compactAll: boolean }
+  | { ok: false; reason: OwnCutCancelReason };
+
+export function buildOwnCut(branchEntries: BranchEntry[]): OwnCutResult {
+  // Find the last compaction entry and its firstKeptEntryId
+  let lastCompactionIdx = -1;
+  let lastKeptId: string | undefined;
+  for (let i = branchEntries.length - 1; i >= 0; i--) {
+    if (branchEntries[i].type === "compaction") {
+      lastCompactionIdx = i;
+      lastKeptId = branchEntries[i].firstKeptEntryId;
+      break;
+    }
+  }
+
+  // Orphan recovery: triggers when lastKeptId is set to "" (sentinel from prior
+  // compact-all) OR set to an id that no longer exists in the branch. In both cases,
+  // start collecting from right after the last compaction entry.
+  const hasPriorCompaction = lastCompactionIdx >= 0;
+  const hasValidKeptId = !!lastKeptId && branchEntries.some((e) => e.id === lastKeptId);
+  const orphanRecovery = hasPriorCompaction && !hasValidKeptId;
+
+  // Collect live messages
+  const liveMessages: EntryWithMessage[] = [];
+  if (orphanRecovery) {
+    for (let i = lastCompactionIdx + 1; i < branchEntries.length; i++) {
+      const e = branchEntries[i];
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) {
+        liveMessages.push({ entry: e, message: e.message });
+      }
+    }
+  } else {
+    let foundKept = !lastKeptId; // if no prior compaction, start collecting immediately
+    for (const e of branchEntries) {
+      if (!foundKept && e.id === lastKeptId) foundKept = true;
+      if (!foundKept) continue;
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) {
+        liveMessages.push({ entry: e, message: e.message });
+      }
+    }
+  }
+
+  if (liveMessages.length === 0) return { ok: false, reason: "no_live_messages" };
+  if (liveMessages.length <= 2) return { ok: false, reason: "too_few_live_messages" };
+
+  // Summarize all messages, keep only the last user message as context
+  let cutIdx = liveMessages.length - 1;
+  while (cutIdx > 0 && liveMessages[cutIdx].message.role !== "user") {
+    cutIdx--;
+  }
+
+  if (cutIdx <= 0) {
+    // Single user prompt scenario (or no user at all).
+    // If there's at least one user message, compact EVERYTHING and keep no tail.
+    // firstKeptEntryId="" is a sentinel: pi-core's buildSessionContext won't match it
+    // (so 0 kept from pre-compaction), and next buildOwnCut triggers orphan recovery.
+    const hasUser = liveMessages.some((m) => m.message.role === "user");
+    if (!hasUser) return { ok: false, reason: "no_user_message" };
+    return {
+      ok: true,
+      messages: liveMessages.map((e) => e.message),
+      firstKeptEntryId: "",
+      compactAll: true,
+    };
+  }
+
+  return {
+    ok: true,
+    messages: liveMessages.slice(0, cutIdx).map((e) => e.message),
+    firstKeptEntryId: liveMessages[cutIdx].entry.id,
+    compactAll: false,
+  };
+}
+
+const REASON_MESSAGES: Record<OwnCutCancelReason, string> = {
+  no_live_messages: "pi-vcc: Nothing to compact (no live messages)",
+  too_few_live_messages: "pi-vcc: Too few messages to compact",
+  no_user_message: "pi-vcc: Cannot compact — no user message found",
+};
+
+export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
+  pi.on("session_before_compact", async (event, ctx) => {
+    const { preparation, branchEntries, customInstructions } = event;
+    const settings = await loadSettings();
+
+    let state = sessionState.get(event);
+    if (!state) {
+      state = { stats: null, wasPiVcc: false };
+      sessionState.set(event, state);
+    }
+
+    // Always handle explicit /pi-vcc marker.
+    // Otherwise, only handle when user opted in via settings.
+    const isPiVcc = customInstructions === PI_VCC_COMPACT_INSTRUCTION;
+    if (!isPiVcc && !settings.overrideDefaultCompaction) return;
+
+    const typedBranchEntries = branchEntries as BranchEntry[];
+    const ownCut = buildOwnCut(typedBranchEntries);
+    if (!ownCut.ok) {
+      const lastComp = [...typedBranchEntries].reverse().find((e) => e.type === "compaction");
+      const lastCompIdx = lastComp ? typedBranchEntries.indexOf(lastComp) : -1;
+
+      // Recompute liveMessages view (same logic as buildOwnCut) for diagnostic
+      const lastKeptId: string | undefined = lastComp?.firstKeptEntryId;
+      const hasPriorCompaction = lastCompIdx >= 0;
+      const hasValidKeptId = !!lastKeptId && typedBranchEntries.some((e) => e.id === lastKeptId);
+      const diagOrphan = hasPriorCompaction && !hasValidKeptId;
+      const liveRoles: string[] = [];
+      if (diagOrphan) {
+        for (let i = lastCompIdx + 1; i < typedBranchEntries.length; i++) {
+          const e = typedBranchEntries[i];
+          if (e.type === "compaction") continue;
+          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+        }
+      } else {
+        let foundKept = !lastKeptId;
+        for (const e of typedBranchEntries) {
+          if (!foundKept && e.id === lastKeptId) foundKept = true;
+          if (!foundKept) continue;
+          if (e.type === "compaction") continue;
+          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+        }
+      }
+      const userIndices = liveRoles.reduce<number[]>((acc, r, i) => (r === "user" ? (acc.push(i), acc) : acc), []);
+
+      await dbg(settings, {
+        cancelled: true,
+        reason: ownCut.reason,
+        isPiVcc,
+        counts: {
+          total: typedBranchEntries.length,
+          messages: typedBranchEntries.filter((e) => e.type === "message").length,
+          compactions: typedBranchEntries.filter((e) => e.type === "compaction").length,
+          entriesAfterLastCompaction: lastCompIdx >= 0 ? typedBranchEntries.length - lastCompIdx - 1 : null,
+        },
+        liveMessages: {
+          count: liveRoles.length,
+          userCount: userIndices.length,
+          firstUserIdx: userIndices[0] ?? null,
+          lastUserIdx: userIndices[userIndices.length - 1] ?? null,
+          roleSequence:
+            liveRoles.length <= 30 ? liveRoles : [...liveRoles.slice(0, 10), "...", ...liveRoles.slice(-10)],
+        },
+        lastCompaction: lastComp
+          ? {
+              hasFirstKeptEntryId: !!lastComp.firstKeptEntryId,
+              foundInBranch: lastComp.firstKeptEntryId
+                ? typedBranchEntries.some((e) => e.id === lastComp.firstKeptEntryId)
+                : null,
+            }
+          : null,
+        tail: typedBranchEntries.slice(-5).map((e) => ({
+          type: e.type,
+          role: e.type === "message" ? e.message?.role : undefined,
+          hasContent: e.type === "message" ? e.message?.content != null : undefined,
+        })),
+      });
+
+      try {
+        ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
+      } catch (e) {
+        // Intentional fallback: UI notifications are best-effort and should not crash the compaction.
+      }
+      return { cancel: true };
+    }
+
+    const agentMessages = ownCut.messages;
+    const firstKeptEntryId = ownCut.firstKeptEntryId;
+    const messages = convertToLlm(agentMessages);
+
+    // Count kept messages and estimate tokens
+    const keptIdx = typedBranchEntries.findIndex((e) => e.id === firstKeptEntryId);
+    const keptEntries =
+      keptIdx >= 0 ? typedBranchEntries.slice(keptIdx).filter((e) => e.type === "message") : [];
+    const keptChars = keptEntries.reduce((sum: number, e: BranchEntry) => {
+      const c = e.message?.content;
+      if (typeof c === "string") return sum + c.length;
+      if (Array.isArray(c))
+        return (
+          sum +
+          c.reduce((s: number, p: any) => {
+            if (p.text) return s + p.text.length;
+            if (p.type === "toolCall")
+              return (
+                s +
+                (p.name?.length ?? 0) +
+                (typeof p.input === "string" ? p.input.length : JSON.stringify(p.input ?? "").length)
+              );
+            if (p.type === "toolResult")
+              return (
+                s +
+                (typeof p.content === "string" ? p.content.length : JSON.stringify(p.content ?? "").length)
+              );
+            return s;
+          }, 0)
+        );
+      return sum;
+    }, 0);
+    state.stats = {
+      summarized: agentMessages.length,
+      kept: keptEntries.length,
+      keptTokensEst: Math.round(keptChars / 4),
+    };
+    currentSessionStats = state.stats;
+
+    const config = settings;
+
+    const summary = await compile({
+      messages,
+      previousSummary: preparation.previousSummary,
+      fileOps: {
+        readFiles: [...preparation.fileOps.read],
+        modifiedFiles: [...preparation.fileOps.written, ...preparation.fileOps.edited],
+      },
+    });
+
+    // ── Guard: empty summary (edge-case #16) ──
+    if (!summary || !summary.trim()) {
+      await dbg(settings, {
+        cancelled: true,
+        reason: "empty-summary-guard",
+        summaryLength: summary?.length ?? 0,
+      });
+      try {
+        ctx?.ui?.notify?.(
+          "pi-vcc: Compaction summary is empty. Cancelling — falling back to pi-core default compaction.",
+          "warning",
+        );
+      } catch (e) {
+        // Intentional fallback: UI notifications are best-effort and should not crash the compaction.
+      }
+      return { cancel: true };
+    }
+
+    // ── Guard: zero-token post-compaction result (edge-case #16) ──
+    // If compaction would leave zero or near-zero context, cancel and let
+    // pi-core default compaction handle it (which keeps keepRecentTokens).
+    const MIN_POST_COMPACTION_TOKENS = 4096;
+    const summaryTokensEst = Math.round(summary.length / 4);
+    const postCompactTokensEst = (state.stats.keptTokensEst ?? 0) + summaryTokensEst;
+    if (postCompactTokensEst < MIN_POST_COMPACTION_TOKENS && ownCut.compactAll) {
+      await dbg(settings, {
+        cancelled: true,
+        reason: "zero-token-guard",
+        postCompactTokensEst,
+        keptTokensEst: state.stats.keptTokensEst,
+        summaryTokensEst,
+        MIN_POST_COMPACTION_TOKENS,
+        compactAll: ownCut.compactAll,
+      });
+      try {
+        ctx?.ui?.notify?.(
+          `pi-vcc: Post-compaction context would be ~${postCompactTokensEst} tokens (min ${MIN_POST_COMPACTION_TOKENS}). ` +
+            "Cancelling — falling back to pi-core default compaction.",
+          "warning",
+        );
+      } catch (e) {
+        // Intentional fallback: UI notifications are best-effort and should not crash the compaction.
+      }
+      return { cancel: true };
+    }
+
+    const branchIds = typedBranchEntries.map((e) => e.id);
+    const cutIdx = branchIds.indexOf(firstKeptEntryId);
+    const cutWindow =
+      cutIdx >= 0
+        ? typedBranchEntries.slice(Math.max(0, cutIdx - 3), Math.min(branchEntries.length, cutIdx + 3)).map((e) => ({
+            id: e.id,
+            type: e.type,
+            role: e.type === "message" ? e.message?.role : undefined,
+            preview: e.type === "message" ? previewContent(e.message?.content) : undefined,
+          }))
+        : [];
+
+    await dbg(config, {
+      usedOwnCut: true,
+      messagesToSummarize: agentMessages.length,
+      messagesPreviewHead: agentMessages
+        .slice(0, 3)
+        .map((m: any) => ({ role: m.role, preview: previewContent(m.content) })),
+      messagesPreviewTail: agentMessages
+        .slice(-3)
+        .map((m: any) => ({ role: m.role, preview: previewContent(m.content) })),
+      convertedMessages: messages.length,
+      firstKeptEntryId,
+      cutWindow,
+      tokensBefore: preparation.tokensBefore,
+      summaryLength: summary.length,
+      summaryPreview: summary.slice(0, 500),
+      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+    });
+
+    const details: PiVccCompactionDetails = {
+      compactor: "pi-vcc",
+      version: 1,
+      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+      sourceMessageCount: agentMessages.length,
+      previousSummaryUsed: Boolean(preparation.previousSummary),
+    };
+
+    state.wasPiVcc = isPiVcc;
+
+    return {
+      compaction: {
+        summary,
+        details,
+        tokensBefore: preparation.tokensBefore,
+        firstKeptEntryId,
+      },
+    };
+  });
+
+  // Fire success toast for /compact path only (delayed to let UI settle).
+  // /pi-vcc path uses its own onComplete callback in the command handler.
+  pi.on("session_compact", (event, ctx) => {
+    const state = sessionState.get(event);
+    if (!event.fromExtension) return;
+    if (state?.wasPiVcc) return; // /pi-vcc handles its own toast via onComplete
+    const stats = state?.stats;
+    if (!stats) return;
+    setTimeout(() => {
+      try {
+        ctx?.ui?.notify?.(
+          `pi-vcc: ${stats.summarized} source entries processed; tail kept ${
+            stats.kept
+          } (~${formatTokens(stats.keptTokensEst)} tok).`,
+          "info",
+        );
+      } catch (e) {
+        // Intentional fallback: UI notifications are best-effort and should not crash the compaction.
+      }
+    }, UI_SETTLE_DELAY_MS);
+  });
+};

package/src/sections.ts

@@ -0,0 +1,14 @@
+import type { TranscriptEntry } from "./core/brief";
+
+export interface SectionData {
+  sessionGoal: string[];
+  outstandingContext: string[];
+  filesAndChanges: string[];
+  commits: string[];
+  references: string[];
+  keySignals: string[];
+  userPreferences: string[];
+  briefTranscript: string;
+  /** Structured transcript entries (verbose object format) */
+  transcriptEntries: TranscriptEntry[];
+}

package/src/tools/recall.ts

@@ -0,0 +1,109 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadAllMessages } from "../core/load-messages";
+import { searchEntries } from "../core/search-entries";
+import { formatRecallOutput } from "../core/format-recall";
+import { getActiveLineageEntryIds } from "../core/lineage";
+import { normalizeRecallScope } from "../core/recall-scope";
+
+const DEFAULT_RECENT = 25;
+const PAGE_SIZE = 5;
+
+export const invalidExpandIndices = (requested: number[], available: Set<number>): number[] =>
+  requested.filter((i) => !Number.isInteger(i) || !available.has(i));
+
+export const registerRecallTool = (pi: ExtensionAPI) => {
+  pi.registerTool({
+    name: "vcc_recall",
+    label: "VCC Recall",
+    description:
+      "Search session history. Defaults to active lineage; use scope:'all' to include off-lineage branches." +
+      " Supports regex queries, paging, and expand indices.",
+    promptSnippet:
+      "vcc_recall: Search history; default scope is active lineage. Use scope:'all' for off-lineage branches.",
+    parameters: Type.Object({
+      query: Type.Optional(
+        Type.String({ description: "Search terms or regex pattern (e.g. 'hook|inject', 'fail.*build'). Multi-word = OR ranked by relevance." }),
+      ),
+      expand: Type.Optional(
+        Type.Array(Type.Number(), { description: "Entry indices to return full untruncated content for" }),
+      ),
+      page: Type.Optional(
+        Type.Number({ description: "Page number (1-based) for paginated search results. Default: 1." }),
+      ),
+      scope: Type.Optional(
+        Type.Union([
+          Type.Literal("lineage"),
+          Type.Literal("all"),
+        ], { description: "Search scope. Default: lineage; all includes off-lineage branches." }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      if (!sessionFile) {
+        return {
+          content: [{ type: "text", text: "No session file available." }],
+          details: undefined,
+        };
+      }
+
+      const scope = normalizeRecallScope(params.scope);
+      const lineageEntryIds = scope === "lineage"
+        ? getActiveLineageEntryIds(ctx.sessionManager)
+        : undefined;
+      const expandSet = new Set(params.expand ?? []);
+      const hasExpand = expandSet.size > 0;
+
+      if (hasExpand && !params.query) {
+        const { rendered: fullMsgs } = await loadAllMessages(sessionFile, true, lineageEntryIds);
+        const requested = [...expandSet];
+        const byIndex = new Map(fullMsgs.map((m) => [m.index, m]));
+        const invalid = invalidExpandIndices(requested, new Set(byIndex.keys()));
+        if (invalid.length > 0) {
+          return {
+            content: [{ type: "text", text: `Cannot expand indices outside ${scope === "all" ? "session history" : "active lineage"}: ${invalid.join(", ")}` }],
+            details: undefined,
+          };
+        }
+
+        const expanded = requested.map((i) => byIndex.get(i)).filter((m): m is NonNullable<typeof m> => Boolean(m));
+        const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(expanded);
+        return {
+          content: [{ type: "text", text: output }],
+          details: undefined,
+        };
+      }
+
+      const { rendered: msgs, rawMessages } = await loadAllMessages(sessionFile, false, lineageEntryIds);
+      const allResults = params.query?.trim()
+        ? searchEntries(msgs, rawMessages, params.query)
+        : msgs.slice(-DEFAULT_RECENT);
+
+      if (params.query?.trim()) {
+        const page = Math.max(1, params.page ?? 1);
+        const start = (page - 1) * PAGE_SIZE;
+        const pageResults = allResults.slice(start, start + PAGE_SIZE);
+        const totalPages = Math.ceil(allResults.length / PAGE_SIZE);
+        const scopeSuffix = scope === "all" ? " (scope: all)" : "";
+        const header = totalPages > 1
+          ? `Page ${page}/${totalPages} (${allResults.length} total matches${scopeSuffix})`
+          : `${allResults.length} matches${scopeSuffix}`;
+        const footer = page < totalPages
+          ? `\n--- Use page:${page + 1}${scope === "all" ? " with scope:'all'" : ""} for more results ---`
+          : "";
+        const output = formatRecallOutput(pageResults, params.query, header) + footer;
+        return {
+          content: [{ type: "text", text: output }],
+          details: undefined,
+        };
+      }
+
+      const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(allResults, params.query);
+      return {
+        content: [{ type: "text", text: output }],
+        details: undefined,
+      };
+    },
+  });
+};
+

package/src/types.ts

@@ -0,0 +1,14 @@
+import type { Message } from "@mariozechner/pi-ai";
+
+export interface FileOps {
+  readFiles?: string[];
+  modifiedFiles?: string[];
+  createdFiles?: string[];
+}
+
+export type NormalizedBlock =
+  | { kind: "user"; text: string; sourceIndex?: number }
+  | { kind: "assistant"; text: string; sourceIndex?: number }
+  | { kind: "tool_call"; name: string; args: Record<string, unknown>; sourceIndex?: number }
+  | { kind: "tool_result"; name: string; text: string; isError: boolean; sourceIndex?: number }
+  | { kind: "thinking"; text: string; redacted: boolean; sourceIndex?: number };