omp-vcc 0.1.13 → 0.1.14

package/extensions/main.ts

@@ -5,7 +5,7 @@
 // pi-vcc port: sting8k/pi-vcc @0.7.0 — algorithmic, zero-LLM, brief transcript + 5 sections, token-budgeted
 
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
-import { scaffoldSettings } from "./vcc-core/core/settings";
+import { scaffoldSettings, loadSettings, loadSettingsWithPluginOverlay } from "./vcc-core/core/settings";
 import { migrateStalePluginEntries } from "./vcc-core/core/migrate-stale";
 import { loadAllMessages } from "./vcc-core/core/load-messages";
 import {
@@ -26,8 +26,9 @@ import {
 import { searchEntriesDetailed, getTouchedFiles } from "./vcc-core/core/search-entries";
 import { formatRecallOutput, formatTouchedOutput } from "./vcc-core/core/format-recall";
 import { getActiveLineageEntryIds } from "./vcc-core/core/lineage";
-import { normalizeRecallScope, normalizeRecallMode, parseRecallScope } from "./vcc-core/core/recall-scope";
+import { normalizeRecallScope, normalizeRecallMode, parseRecallScope, parseRecallMode } from "./vcc-core/core/recall-scope";
 import { parseDrillDown, expandEntryFile, parseEntryRef, expandEntry } from "./vcc-core/core/drill-down";
+import { capRecallBlocks, type RecallBudgetBlock } from "./vcc-core/core/recall-budget";
 import { buildPiVccCustomInstructions, parseKeepAndPrompt } from "./vcc-core/core/compact-args";
 
 // Build omp sentinel instructions; keep pi sentinel for backward compat in hook
@@ -39,14 +40,25 @@ const buildOmpCustomInstructions = (keepUserTurns: number | null): string => {
 // Helper to parse recall command text: supports `query ... scope:all page:N`
 const parseRecallCommandArgs = (
   raw: string,
-): { query: string; scope: "lineage" | "all"; page: number } => {
-  const parsed = parseRecallScope(raw);
+): { query: string; scope: "lineage" | "all"; mode: "hybrid" | "touched" | "file"; page: number } => {
+  const scoped = parseRecallScope(raw);
+  const parsed = parseRecallMode(scoped.text);
   const pageMatch = parsed.text.match(/\bpage:(\d+)\b/i);
   const page = pageMatch ? Math.max(1, Number.parseInt(pageMatch[1] ?? "1", 10)) : 1;
   const query = parsed.text.replace(/\bpage:\d+\b/i, "").trim();
-  return { query, scope: parsed.scope, page };
+  return { query, scope: scoped.scope, mode: normalizeRecallMode(parsed.mode), page };
 };
 
+const capModelRecall = (settings: { recallResponseMaxChars: number }, blocks: Array<RecallBudgetBlock | string>, blockKind = "entry"): string =>
+  capRecallBlocks(blocks, settings.recallResponseMaxChars, { blockKind });
+const loadRecallMessages = (ctx: unknown, sessionFile: string, full: boolean, lineageEntryIds?: Set<string>) =>
+  loadAllMessages(sessionFile, full, lineageEntryIds, (event) => {
+    if (!loadSettings(ctx).debug) return;
+    try {
+      (ctx as any)?.ui?.notify?.(`omp-vcc: ${event.kind} (${event.parseErrors} malformed lines)`, "warning");
+    } catch {}
+  });
+
 const DEFAULT_RECENT = 25;
 const PAGE_SIZE = 5;
 export default function (pi: ExtensionAPI): void {
@@ -63,14 +75,14 @@ export default function (pi: ExtensionAPI): void {
     name: "vcc_recall",
     label: "VCC Recall",
     description:
-      "Recall earlier parts of the current session — decisions made, files touched, commands run, including anything dropped by compaction. Reach for this before telling the user you no longer have the context. Plain keywords work best; a regex pattern is also accepted. Results are paged (page); pass expand with entry indices to read full untruncated content. Use mode:'touched' to list files worked on in this session with their entry indices, and #N:path to drill into a file's content from an entry (#N:path:full for all lines). Note: apply_patch paths (inside the diff payload) and bash redirects do not appear in the touched index. Only the current session is searchable — earlier sessions are not.",
+      "Recall earlier parts of the current session — decisions made, files touched, commands run, including anything dropped by compaction. Reach for this before telling the user you no longer have the context. Plain keywords work best; a regex pattern is also accepted. Results are paged (page); pass expand with entry indices to read full untruncated content. Use mode:'touched' to list files worked on in this session with their entry indices, mode:'file' to search only file tool arguments, and #N:path to drill into a file's content from an entry (#N:path:full for all lines). Note: apply_patch paths (inside the diff payload) and bash redirects do not appear in the touched index. Only the current session is searchable — earlier sessions are not.",
     approval: "read",
     parameters: pi.zod.object({
       query: pi.zod.string().optional().describe("What to recall, in plain keywords (e.g. 'redis cache decision'). Multi-word queries are ranked by relevance. A regex pattern also works."),
       expand: pi.zod.array(pi.zod.number()).optional().describe("Entry indices to return full untruncated content for"),
       page: pi.zod.number().optional().describe("Page number (1-based) for paginated search results. Default: 1."),
       scope: pi.zod.enum(["lineage", "all", "active"]).optional().describe("Default 'lineage' covers the active conversation path. Use 'all' to also reach messages from other branches, such as turns that were edited or retried."),
-      mode: pi.zod.enum(["hybrid", "touched"]).optional().describe("What to show. hybrid (default) = normal search; touched = aggregated files-by-path with entry indices."),
+      mode: pi.zod.enum(["hybrid", "touched", "file"]).optional().describe("What to show. hybrid (default) = normal search; touched = aggregated files-by-path; file = only file tool arguments."),
     }),
     async execute(_toolCallId: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: unknown) {
       const p = params as {
@@ -83,6 +95,7 @@ export default function (pi: ExtensionAPI): void {
       const c = ctx as {
         sessionManager?: { getSessionFile?: () => string | undefined; getBranch?: () => unknown[]; getEntries?: () => unknown[] };
       };
+      const settings = await loadSettingsWithPluginOverlay(ctx);
       const sessionFile = c.sessionManager?.getSessionFile?.();
       if (!sessionFile) {
         return {
@@ -95,12 +108,14 @@ export default function (pi: ExtensionAPI): void {
       const lineageEntryIds = scope === "lineage" ? getActiveLineageEntryIds(c.sessionManager as unknown as { getBranch: () => { id?: string }[] }) : undefined;
 
       const q = p.query?.trim();
+      const mode = normalizeRecallMode(p.mode);
+      const bounded = (text: string, id: string | number, kind = "entry"): string => capModelRecall(settings, [{ id, text }], kind);
 
       const entryRef = q ? parseEntryRef(q) : null;
       if (entryRef) {
         const ref = entryRef;
         if (lineageEntryIds) {
-          const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+          const { rendered } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
           const exists = rendered.some((m) => m.index === ref.index);
           if (!exists) {
             return {
@@ -110,14 +125,31 @@ export default function (pi: ExtensionAPI): void {
           }
         }
         const text = expandEntry(sessionFile, ref.index, ref.full, ref.offset, ref.limit);
-        return { content: [{ type: "text", text }], details: undefined };
+        return { content: [{ type: "text", text: bounded(text, `#${ref.index}`) }], details: undefined };
+      }
+      const textMatch = q?.match(/^#(\d+):text(?::(full|\d+(?::\d+)?))?$/);
+      if (textMatch) {
+        const index = Number.parseInt(textMatch[1] ?? "0", 10);
+        const suffix = textMatch[2];
+        const full = suffix === "full";
+        const parts = suffix && !full ? suffix.split(":") : [];
+        const offset = parts[0] !== undefined ? Number.parseInt(parts[0], 10) : undefined;
+        const limit = parts[1] !== undefined ? Number.parseInt(parts[1], 10) : undefined;
+        if (lineageEntryIds) {
+          const { rendered } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
+          if (!rendered.some((m) => m.index === index)) {
+            return { content: [{ type: "text", text: `Cannot expand indices outside active lineage: ${index}. Use scope:'all' to reach other branches.` }], details: undefined };
+          }
+        }
+        const text = expandEntry(sessionFile, index, full, offset, limit);
+        return { content: [{ type: "text", text: bounded(text, `#${index}:text`) }], details: undefined };
       }
 
       const drill = q ? parseDrillDown(q) : null;
       if (drill) {
         const parsed = drill;
         if (lineageEntryIds) {
-          const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+          const { rendered } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
           const exists = rendered.some((m) => m.index === parsed.index);
           if (!exists) {
             return {
@@ -127,20 +159,26 @@ export default function (pi: ExtensionAPI): void {
           }
         }
         const text = expandEntryFile(sessionFile, parsed.index, parsed.pathPattern, parsed.full, parsed.offset, parsed.limit);
-        return { content: [{ type: "text", text }], details: undefined };
+        return { content: [{ type: "text", text: bounded(text, `#${parsed.index}:path`) }], details: undefined };
       }
 
-      if (normalizeRecallMode(p.mode) === "touched") {
-        const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+      if (mode === "touched") {
+        const { rendered, rawMessages } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
         const touched = getTouchedFiles(rawMessages as unknown[], rendered);
         const text = formatTouchedOutput(touched, p.page);
-        return { content: [{ type: "text", text }], details: undefined };
+        return { content: [{ type: "text", text: bounded(text, `page:${p.page ?? 1}`, "page") }], details: undefined };
+      }
+      if (mode === "file" && !q) {
+        const { rendered, rawMessages } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
+        const { hits } = searchEntriesDetailed(rendered, rawMessages as unknown[], undefined, { mode });
+        const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(hits);
+        return { content: [{ type: "text", text: capModelRecall(settings, [{ id: "file", text: output }], "file") }], details: undefined };
       }
 
       const expandSet = new Set(p.expand ?? []);
       const hasExpand = expandSet.size > 0;
       if (hasExpand) {
-        const { rendered: fullMsgs } = loadAllMessages(sessionFile, true, lineageEntryIds);
+        const { rendered: fullMsgs } = loadRecallMessages(ctx, sessionFile, true, lineageEntryIds);
         const requested = [...expandSet];
         const byIndex = new Map(fullMsgs.map((m) => [m.index, m]));
         const invalid = invalidExpandIndices(requested, new Set(byIndex.keys()));
@@ -151,13 +189,14 @@ export default function (pi: ExtensionAPI): void {
           };
         }
         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);
+        const blocks = expanded.map((entry) => ({ id: `#${entry.index}`, text: formatRecallOutput([entry]) }));
+        const output = (scope === "all" ? "Scope: all\n\n" : "") + capModelRecall(settings, blocks, "entry");
         return { content: [{ type: "text", text: output }], details: undefined };
       }
 
-      const { rendered: msgs, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+      const { rendered: msgs, rawMessages } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
       if (q) {
-        const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(msgs, rawMessages as unknown[], q);
+        const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(msgs, rawMessages as unknown[], q, { mode });
         const page = Math.max(1, p.page ?? 1);
         const totalPages = Math.ceil(hits.length / PAGE_SIZE);
         const scopeSuffix = scope === "all" ? " (scope: all)" : "";
@@ -165,16 +204,18 @@ export default function (pi: ExtensionAPI): void {
         if (hits.length > 0 && page > totalPages) {
           const guidance = truncated ? `Use a page between 1 and ${totalPages}.` : `Use a page between 1 and ${totalPages}, or refine your query.`;
           const text = `Page ${page} is outside the available range 1-${totalPages} (${hits.length} matches${scopeSuffix}${truncationNote}). ${guidance}`;
-          return { content: [{ type: "text", text }], details: undefined };
+          return { content: [{ type: "text", text: bounded(text, `page:${page}`, "page") }], details: undefined };
         }
         const start = (page - 1) * PAGE_SIZE;
         const pageResults = hits.slice(start, start + PAGE_SIZE);
         const header = totalPages > 1 ? `Page ${page}/${totalPages} (${hits.length} total matches${scopeSuffix}${truncationNote})` : `${hits.length} matches${scopeSuffix}${truncationNote}`;
         const footer = page < totalPages ? `\n--- Use page:${page + 1}${scope === "all" ? " with scope:'all'" : ""} for more results ---` : "";
         const output = formatRecallOutput(pageResults, q, header, { truncated, totalBeforeCap }) + footer;
-        return { content: [{ type: "text", text: output }], details: undefined };
+        return { content: [{ type: "text", text: bounded(output, `page:${page}`, "page") }], details: undefined };
       }
-      const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(msgs.slice(-DEFAULT_RECENT), q);
+      const recent = msgs.slice(-DEFAULT_RECENT);
+      const blocks = recent.map((entry) => ({ id: `#${entry.index}`, text: formatRecallOutput([entry]) }));
+      const output = (scope === "all" ? "Scope: all\n\n" : "") + capModelRecall(settings, blocks, "entry");
       return { content: [{ type: "text", text: output }], details: undefined };
     },
   } as unknown as Parameters<ExtensionAPI["registerTool"]>[0]);
@@ -219,7 +260,7 @@ export default function (pi: ExtensionAPI): void {
       settled = true;
       const stats = getLastCompactionStats(pi);
       if (stats) {
-        scheduleCompactionStatsNotify(c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
+        scheduleCompactionStatsNotify(pi, c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
       } else {
         try { c.ui.notify(fallbackToast, "info"); } catch {}
       }
@@ -295,19 +336,30 @@ export default function (pi: ExtensionAPI): void {
         try { c.ui.notify("No session file available.", "error"); } catch {}
         return;
       }
-      const { query, scope, page } = parseRecallCommandArgs(args);
+      const { query, scope, mode, page } = parseRecallCommandArgs(args);
       const lineageEntryIds = scope === "lineage" ? getActiveLineageEntryIds(c.sessionManager as unknown as { getBranch: () => { id?: string }[] }) : undefined;
       const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
       if (!query) {
-        const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+        const { rendered, rawMessages } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
+        if (mode === "file") {
+          const { hits } = searchEntriesDetailed(rendered, rawMessages as unknown[], undefined, { mode });
+          const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(hits);
+          try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
+          return;
+        }
+        if (mode === "touched") {
+          const output = formatTouchedOutput(getTouchedFiles(rawMessages as unknown[], rendered), page);
+          try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
+          return;
+        }
         const recent = rendered.slice(-DEFAULT_RECENT);
         const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
         try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
         try { c.ui.notify(`vcc_recall: ${recent.length} recent`, "info"); } catch {}
         return;
       }
-      const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
-      const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(rendered, rawMessages as unknown[], query);
+      const { rendered, rawMessages } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
+      const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(rendered, rawMessages as unknown[], query, { mode });
       const totalPages = Math.ceil(hits.length / PAGE_SIZE);
       const scopeSuffix = scope === "all" ? " (scope: all)" : "";
       const scopeArg = scope === "all" ? " scope:all" : "";
@@ -341,17 +393,28 @@ export default function (pi: ExtensionAPI): void {
         try { c.ui.notify("No session file available.", "error"); } catch {}
         return;
       }
-      const { query, scope, page } = parseRecallCommandArgs(args);
+      const { query, scope, mode, page } = parseRecallCommandArgs(args);
       const lineageEntryIds = scope === "lineage" ? getActiveLineageEntryIds(c.sessionManager as unknown as { getBranch: () => { id?: string }[] }) : undefined;
       const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
-      const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+      const { rendered, rawMessages } = loadRecallMessages(ctx, sessionFile, false, lineageEntryIds);
       if (!query) {
+        if (mode === "file") {
+          const { hits } = searchEntriesDetailed(rendered, rawMessages as unknown[], undefined, { mode });
+          const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(hits);
+          try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
+          return;
+        }
+        if (mode === "touched") {
+          const output = formatTouchedOutput(getTouchedFiles(rawMessages as unknown[], rendered), page);
+          try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
+          return;
+        }
         const recent = rendered.slice(-DEFAULT_RECENT);
         const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
         try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
         return;
       }
-      const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(rendered, rawMessages as unknown[], query);
+      const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(rendered, rawMessages as unknown[], query, { mode });
       const totalPages = Math.ceil(hits.length / PAGE_SIZE);
       const scopeSuffix = scope === "all" ? " (scope: all)" : "";
       const scopeArg = scope === "all" ? " scope:all" : "";

package/extensions/vcc-core/core/compaction-chain.ts

@@ -0,0 +1,301 @@
+// @ts-nocheck
+import type { PiVccAppendDetails, PiVccAppendSegment } from "../details";
+import { estimateScriptAwareTokens } from "./token-estimate";
+
+export type ChainEntry = Record<string, unknown>;
+
+export interface ActiveCompactionChain {
+  details: PiVccAppendDetails[];
+  segments: PiVccAppendSegment[];
+  trailingSummary: string;
+  fallbackSummary?: string;
+}
+
+export interface CollectActiveSegmentsOptions {
+  /** The complete summary returned to the host for the latest compaction. */
+  fallbackSummary?: string;
+}
+
+export interface CoverageForMessagesInput {
+  selectedIds: Array<string | undefined>;
+  firstKeptEntryId: string;
+  sourceMessageCount?: number;
+}
+
+export interface AppendDetailsInput {
+  segment: Omit<PiVccAppendSegment, "sequence">;
+  chainStart: boolean;
+  trailingSummary: string;
+  sections: string[];
+  sourceMessageCount: number;
+  previousSummaryUsed: boolean;
+  previous?: ActiveCompactionChain | null;
+  retainedToolOutputProjection?: PiVccAppendDetails["retainedToolOutputProjection"];
+}
+
+export interface CompactionThresholds {
+  contextWindow?: number;
+  chainThreshold: number;
+  contextThreshold?: number;
+  minimumSaving: number;
+  capacity?: number;
+}
+
+export interface CompactionDecisionInput {
+  manual?: boolean;
+  overflow?: boolean;
+  willRetry?: boolean;
+  pressure?: boolean;
+  chainTokens: number;
+  rebaseChainTokens?: number;
+  contextWindow?: number;
+  reserveTokens?: number;
+  fullContextTokens?: number;
+}
+
+export interface CompactionDecision {
+  chainStart: boolean;
+  mode: "append" | "rebase";
+  pressure: boolean;
+  capacityPressure: boolean;
+  chainThreshold: number;
+  contextThreshold?: number;
+  minimumSaving: number;
+  capacity?: number;
+  chainTokens: number;
+  rebaseChainTokens?: number;
+  /** Present only when the caller supplied a trusted full-context estimate. */
+  fullContextTokens?: number;
+}
+const nonEmptyString = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+
+const finitePositive = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+const finiteNonNegative = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+const uniqueEntryPositions = (entries: ChainEntry[]): Map<string, number> => {
+  const positions = new Map<string, number>();
+  for (let i = 0; i < entries.length; i++) {
+    const id = entries[i]?.id;
+    if (typeof id !== "string") continue;
+    if (positions.has(id)) positions.set(id, -1);
+    else positions.set(id, i);
+  }
+  return positions;
+};
+
+const isCompactionEntry = (entry: ChainEntry): boolean => entry.type === "compaction";
+
+/** Runtime parser for the immutable v3 persisted details record. */
+export const isPiVccAppendDetails = (value: unknown): value is PiVccAppendDetails => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  if (candidate.compactor !== "omp-vcc" || candidate.version !== 3 || candidate.summaryMode !== "append") return false;
+  if (typeof candidate.chainStart !== "boolean" || typeof candidate.trailingSummary !== "string") return false;
+  if (!nonEmptyString(candidate.trailingSummary)) return false;
+  if (!Array.isArray(candidate.sections) || !candidate.sections.every(nonEmptyString)) return false;
+  if (typeof candidate.sourceMessageCount !== "number" || !Number.isInteger(candidate.sourceMessageCount) || candidate.sourceMessageCount < 0) return false;
+  if (typeof candidate.previousSummaryUsed !== "boolean" || candidate.segment === null || typeof candidate.segment !== "object" || Array.isArray(candidate.segment)) return false;
+  const segment = candidate.segment as Record<string, unknown>;
+  if (typeof segment.sequence !== "number" || !Number.isInteger(segment.sequence) || segment.sequence < 1) return false;
+  if (!nonEmptyString(segment.summary) || !finiteNonNegative(segment.tokensBefore)) return false;
+  if (segment.coverage === null || typeof segment.coverage !== "object" || Array.isArray(segment.coverage)) return false;
+  const coverage = segment.coverage as Record<string, unknown>;
+  if (!nonEmptyString(coverage.firstCoveredEntryId) || !nonEmptyString(coverage.lastCoveredEntryId) || typeof coverage.firstKeptEntryId !== "string") return false;
+  if (typeof coverage.sourceMessageCount !== "number" || !Number.isInteger(coverage.sourceMessageCount) || coverage.sourceMessageCount < 1) return false;
+  if (coverage.includesLegacySummary !== undefined && typeof coverage.includesLegacySummary !== "boolean") return false;
+  if (coverage.rebasedFromCompactionId !== undefined && typeof coverage.rebasedFromCompactionId !== "string") return false;
+  if (candidate.retainedToolOutputProjection !== undefined) {
+    const projection = candidate.retainedToolOutputProjection;
+    if (projection === null || typeof projection !== "object" || Array.isArray(projection)) return false;
+    const record = projection as Record<string, unknown>;
+    if (record.version !== 1 || !finiteNonNegative(record.retainedTokens) || !finiteNonNegative(record.omittedTokens)) return false;
+    if (typeof record.pendingCount !== "number" || !Number.isInteger(record.pendingCount) || record.pendingCount < 0) return false;
+    if (!Array.isArray(record.omissions) || !record.omissions.every((value) => value !== null && typeof value === "object" && !Array.isArray(value) &&
+        nonEmptyString((value as Record<string, unknown>).entryId) && nonEmptyString((value as Record<string, unknown>).marker))) return false;
+  }
+  return true;
+};
+
+const validCoverageForBranch = (coverage: PiVccAppendSegment["coverage"], positions: Map<string, number>): boolean => {
+  const first = positions.get(coverage.firstCoveredEntryId);
+  const last = positions.get(coverage.lastCoveredEntryId);
+  if (first === undefined || last === undefined || first < 0 || last < 0 || first > last) return false;
+  if (coverage.firstKeptEntryId.length === 0) return true;
+  const kept = positions.get(coverage.firstKeptEntryId);
+  return kept !== undefined && kept > last;
+};
+
+
+/**
+ * Collect the append chain ending at the latest compaction. A non-append
+ * compaction before the chain start is a legal legacy base; any malformed v3
+ * record, summary mismatch, branch mismatch, or sequence gap invalidates the
+ * entire chain.
+ */
+export const collectActiveSegments = (
+  branchEntries: ChainEntry[],
+  options: CollectActiveSegmentsOptions = {},
+): ActiveCompactionChain | null => {
+  if (!Array.isArray(branchEntries)) return null;
+  const compactions = branchEntries.filter(isCompactionEntry);
+  if (compactions.length === 0) return null;
+  const collected: Array<{ details: PiVccAppendDetails; compaction: ChainEntry }> = [];
+  const positions = uniqueEntryPositions(branchEntries);
+  for (let i = compactions.length - 1; i >= 0; i--) {
+    const compaction = compactions[i];
+    const candidate = compaction.details;
+    if (!isPiVccAppendDetails(candidate)) {
+      if (collected.length === 0) return null;
+      break;
+    }
+    if (compaction.summary !== candidate.trailingSummary || compaction.firstKeptEntryId !== candidate.segment.coverage.firstKeptEntryId || !validCoverageForBranch(candidate.segment.coverage, positions)) return null;
+    collected.push({ details: candidate, compaction });
+    if (candidate.chainStart) break;
+  }
+  if (collected.length === 0 || !collected[collected.length - 1].details.chainStart) return null;
+  collected.reverse();
+  const details = collected.map((value) => value.details);
+  for (let i = 0; i < details.length; i++) {
+    if (details[i].segment.sequence !== i + 1 || (i > 0 && details[i].chainStart)) return null;
+    if (i > 0 && details[i - 1].segment.coverage.firstKeptEntryId.length > 0 &&
+        details[i].segment.coverage.firstCoveredEntryId !== details[i - 1].segment.coverage.firstKeptEntryId) return null;
+  }
+  const firstCoverage = details[0].segment.coverage;
+  if (firstCoverage.rebasedFromCompactionId !== undefined &&
+      !compactions.some((value) => value.id === firstCoverage.rebasedFromCompactionId)) return null;
+  const latest = details[details.length - 1];
+  if (options.fallbackSummary !== undefined && options.fallbackSummary !== latest.trailingSummary) return null;
+  return {
+    details,
+    segments: details.map((detail) => detail.segment),
+    trailingSummary: latest.trailingSummary,
+    fallbackSummary: latest.trailingSummary,
+  };
+};
+
+/** Derive immutable coverage from selected ids; an undefined id fails closed. */
+export const coverageForMessages = (input: CoverageForMessagesInput): PiVccAppendSegment["coverage"] | null => {
+  const ids = input.selectedIds;
+  if (!Array.isArray(ids) || ids.length === 0 || ids.some((id) => !nonEmptyString(id))) return null;
+  const first = ids[0];
+  const last = ids[ids.length - 1];
+  if (!nonEmptyString(first) || !nonEmptyString(last)) return null;
+  const sourceMessageCount = input.sourceMessageCount ?? ids.length;
+  if (!Number.isInteger(sourceMessageCount) || sourceMessageCount < 1) return null;
+  return {
+    firstCoveredEntryId: first,
+    lastCoveredEntryId: last,
+    firstKeptEntryId: typeof input.firstKeptEntryId === "string" ? input.firstKeptEntryId : "",
+    sourceMessageCount,
+  };
+};
+
+/** Build a v3 details record and reject a missing/invalid prior chain. */
+export const buildAppendOnlyDetails = (input: AppendDetailsInput): PiVccAppendDetails | null => {
+  if (!input || !input.segment || !nonEmptyString(input.segment.summary) || !nonEmptyString(input.trailingSummary)) return null;
+  if (!input.segment.coverage || !nonEmptyString(input.segment.coverage.firstCoveredEntryId) || !nonEmptyString(input.segment.coverage.lastCoveredEntryId)) return null;
+  if (typeof input.segment.coverage.firstKeptEntryId !== "string" || input.segment.coverage.sourceMessageCount < 1) return null;
+  if (!input.chainStart && (!input.previous || input.previous.segments.length === 0)) return null;
+  const priorDetails = input.previous?.details[input.previous.details.length - 1];
+  if (!input.chainStart && (!priorDetails || !isPiVccAppendDetails(priorDetails) || priorDetails.segment.sequence !== input.previous?.segments.length)) return null;
+  const prior = input.previous?.segments[input.previous.segments.length - 1];
+  const sequence = input.chainStart ? 1 : (prior?.sequence ?? 0) + 1;
+  if (!Number.isInteger(sequence) || sequence < 1) return null;
+  const details: PiVccAppendDetails = {
+    compactor: "omp-vcc",
+    version: 3,
+    summaryMode: "append",
+    chainStart: input.chainStart,
+    segment: { ...input.segment, sequence },
+    trailingSummary: input.trailingSummary,
+    sections: input.sections.slice(),
+    sourceMessageCount: input.sourceMessageCount,
+    previousSummaryUsed: input.previousSummaryUsed,
+  };
+  if (input.retainedToolOutputProjection !== undefined) details.retainedToolOutputProjection = input.retainedToolOutputProjection;
+  return isPiVccAppendDetails(details) ? details : null;
+};
+
+export const estimateChainTokens = (chain: ActiveCompactionChain): number => {
+  let total = estimateScriptAwareTokens(chain.trailingSummary);
+  for (const segment of chain.segments) total += estimateScriptAwareTokens(segment.summary);
+  return total;
+};
+
+export const compactionThresholds = (contextWindow?: number, reserveTokens?: number): CompactionThresholds => {
+  if (!finitePositive(contextWindow)) {
+    return { chainThreshold: 34_000, minimumSaving: 24_000 };
+  }
+  const capacity = typeof reserveTokens === "number" && Number.isFinite(reserveTokens) && reserveTokens >= 0
+    ? Math.max(0, contextWindow - reserveTokens)
+    : undefined;
+  return {
+    contextWindow,
+    chainThreshold: Math.floor(contextWindow / 8),
+    contextThreshold: Math.floor(contextWindow / 2),
+    minimumSaving: Math.max(1, Math.min(24_000, Math.floor(24_000 * contextWindow / 272_000))),
+    capacity,
+  };
+};
+
+export const decideAppendMode = (input: CompactionDecisionInput): CompactionDecision => {
+  const thresholds = compactionThresholds(input.contextWindow, input.reserveTokens);
+  const capacityPressure = thresholds.capacity !== undefined && finiteNonNegative(input.fullContextTokens) && input.fullContextTokens > thresholds.capacity;
+  const pressure = input.pressure === true || input.chainTokens >= thresholds.chainThreshold;
+  const explicit = input.overflow === true || input.willRetry === true || capacityPressure;
+  const rebaseTokens = finiteNonNegative(input.rebaseChainTokens) ? input.rebaseChainTokens : undefined;
+  const saving = finiteNonNegative(input.fullContextTokens) && rebaseTokens !== undefined
+    ? Math.max(0, input.fullContextTokens - rebaseTokens)
+    : undefined;
+  let mode: "append" | "rebase" = "append";
+  if (input.manual === true) mode = "rebase";
+  else if (explicit && rebaseTokens !== undefined) mode = rebaseTokens < input.chainTokens ? "rebase" : "append";
+  else if (pressure && saving !== undefined && saving >= thresholds.minimumSaving && (rebaseTokens === undefined || rebaseTokens < input.chainTokens)) mode = "rebase";
+  const decision: CompactionDecision = {
+    chainStart: input.manual === true && mode === "rebase",
+    mode,
+    pressure,
+    capacityPressure,
+    chainThreshold: thresholds.chainThreshold,
+    minimumSaving: thresholds.minimumSaving,
+    chainTokens: input.chainTokens,
+    rebaseChainTokens: rebaseTokens,
+  };
+  if (thresholds.contextThreshold !== undefined) decision.contextThreshold = thresholds.contextThreshold;
+  if (thresholds.contextWindow !== undefined) decision.contextWindow = thresholds.contextWindow;
+  if (thresholds.capacity !== undefined) decision.capacity = thresholds.capacity;
+  if (finiteNonNegative(input.fullContextTokens)) decision.fullContextTokens = input.fullContextTokens;
+  return decision;
+};
+
+export const APPEND_SEGMENT_CUSTOM_TYPE = "omp-vcc-append-segment";
+export const APPEND_TRAILING_CUSTOM_TYPE = "omp-vcc-append-trailing";
+
+export interface AppendContextProjectionInput {
+  messages: ChainEntry[];
+  chain: ActiveCompactionChain;
+  fallbackSummary: string;
+}
+
+/** Replace exactly one host fallback summary with hidden segment + trailing messages. */
+export const projectAppendOnlyContext = (input: AppendContextProjectionInput): ChainEntry[] => {
+  if (!input || !Array.isArray(input.messages) || !input.chain || !nonEmptyString(input.fallbackSummary)) return input?.messages;
+  if (input.fallbackSummary !== input.chain.fallbackSummary && input.fallbackSummary !== input.chain.trailingSummary) return input.messages;
+  const matches: number[] = [];
+  for (let i = 0; i < input.messages.length; i++) {
+    const message = input.messages[i];
+    if ((message.role === "compactionSummary" || message.role === "branchSummary") && message.summary === input.fallbackSummary) matches.push(i);
+  }
+  if (matches.length !== 1) return input.messages;
+  const replacement: ChainEntry[] = input.chain.segments.map((segment) => ({
+    role: "custom",
+    customType: APPEND_SEGMENT_CUSTOM_TYPE,
+    display: false,
+    content: segment.summary,
+  }));
+  replacement.push({ role: "custom", customType: APPEND_TRAILING_CUSTOM_TYPE, display: false, content: input.chain.trailingSummary });
+  const result = input.messages.slice();
+  result.splice(matches[0], 1, ...replacement);
+  return result;
+};

package/extensions/vcc-core/core/drill-down.ts

@@ -99,15 +99,22 @@ function formatToolCallContent(
   const MAX_FULL_BYTES = 50 * 1024;
 
   if (full) {
-    // Full content: capped at 50KB
-    if (Buffer.byteLength(body, "utf8") > MAX_FULL_BYTES) {
-      const truncated = body.slice(0, MAX_FULL_BYTES);
+    // Full content is capped at 50 KiB of UTF-8 without splitting a code point.
+    const totalBytes = Buffer.byteLength(body, "utf8");
+    if (totalBytes > MAX_FULL_BYTES) {
+      const bytes = Buffer.from(body, "utf8");
+      let end = MAX_FULL_BYTES;
+      if (end < bytes.length && (bytes[end] & 0xc0) === 0x80) {
+        while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+      }
+      const truncated = bytes.subarray(0, end).toString("utf8");
+      const omittedBytes = bytes.length - end;
       return `File: ${tc.path}
 Tool: ${tc.name}
 
 ${truncated}
 
-... (${Buffer.byteLength(body, "utf8") - MAX_FULL_BYTES} more bytes — file exceeds 50KB display limit. Use #${entryIndex}:${tc.path}:${previewLimit} for next page.)`;
+... (${omittedBytes} more bytes — file exceeds 50KB display limit. Use #${entryIndex}:${tc.path}:${previewLimit} for next page.)`;
     }
     return `File: ${tc.path}
 Tool: ${tc.name}

package/extensions/vcc-core/core/format-recall.ts

@@ -94,14 +94,30 @@ export const formatRecallOutput = (
 
   const lines = entries.map((e) => {
     const fileSuffix = e.files?.length ? ` files:[${e.files.join(", ")}]` : "";
+    const fileDetails = e.fileMatches?.length
+      ? `\n${e.fileMatches
+          .map((m) => {
+            const header = `  ${m.path} (${m.toolName}, ${m.lineCount} lines)`;
+            if (!m.snippet) return header;
+            const snippet = m.snippet
+              .split("\n")
+              .map((line) => `    ${line}`)
+              .join("\n");
+            return `${header}\n${snippet}`;
+          })
+          .join("\n")}`
+      : "";
     const body = query && e.snippet ? e.snippet : e.summary;
-    return `#${e.index} [${e.role}]${fileSuffix} ${body}`;
+    const separator = fileDetails ? "\n" : " ";
+    return `#${e.index} [${e.role}]${fileSuffix}${fileDetails}${separator}${body}`;
   });
 
   const body = `${header}\n\n${lines.join("\n\n")}`;
   // Every hit ref resolves: #N expands the full entry (see expandEntry in
   // drill-down.ts). Surface the hint when results are capped or clipped.
-  const clipped = entries.some((e) => e.snippet?.includes("...("));
+  const clipped = entries.some(
+    (e) => e.snippet?.includes("...(") || e.fileMatches?.some((m) => m.snippet.includes("...(")),
+  );
   if (opts?.truncated || clipped) {
     return `${body}\n\n--- Use #N for full entry text ---`;
   }