@pi-unipi/compactor 2.6.1 → 2.6.2

package/src/compaction/compact-args.ts

@@ -0,0 +1,86 @@
+/**
+ * Parse keep:N and follow-up prompt from compaction custom instructions
+ * (ported from pi-vcc compact-args.ts; marker constant stays ours: COMPACTOR_INSTRUCTION)
+ */
+
+import { COMPACTOR_INSTRUCTION } from "@pi-unipi/core";
+
+const KEEP_TOKEN_RE = /^keep:(\d+)$/;
+
+export interface ParsedCompactionArgs {
+  followUpPrompt: string;
+  keepUserTurns: number | null;
+  keepUserTurnsExplicit: boolean;
+}
+
+const parseKeepUserTurns = (raw: string): number => {
+  const value = Number(raw);
+  return Number.isSafeInteger(value) ? value : Number.MAX_SAFE_INTEGER;
+};
+
+export const parseKeepAndPrompt = (args?: string): ParsedCompactionArgs => {
+  const trimmed = args?.trim() ?? "";
+  if (!trimmed) return { followUpPrompt: "", keepUserTurns: null, keepUserTurnsExplicit: false };
+
+  const startMatch = trimmed.match(/^keep:(\d+)(?:\s+|$)([\s\S]*)$/);
+  if (startMatch) {
+    return {
+      followUpPrompt: startMatch[2].trim(),
+      keepUserTurns: parseKeepUserTurns(startMatch[1]),
+      keepUserTurnsExplicit: true,
+    };
+  }
+
+  const parts = trimmed.split(/\s+/);
+  const endMatch = parts[parts.length - 1].match(KEEP_TOKEN_RE);
+  if (endMatch) {
+    return {
+      followUpPrompt: trimmed.slice(0, trimmed.length - parts[parts.length - 1].length).trim(),
+      keepUserTurns: parseKeepUserTurns(endMatch[1]),
+      keepUserTurnsExplicit: true,
+    };
+  }
+
+  return { followUpPrompt: trimmed, keepUserTurns: null, keepUserTurnsExplicit: false };
+};
+
+export interface ParsedCompactionInstructions {
+  isCompactor: boolean;
+  keepUserTurns: number;
+  keepUserTurnsExplicit: boolean;
+  followUpPrompt: string | null;
+}
+
+/**
+ * Parse customInstructions arriving at session_before_compact.
+ * - Exactly COMPACTOR_INSTRUCTION → default path (keep 1, not explicit).
+ * - COMPACTOR_INSTRUCTION + args → parse keep:N / prompt after the marker.
+ * - Anything else → not ours (parse for a trailing keep:N anyway, pi-vcc parity).
+ */
+export const parseCompactionInstructions = (
+  customInstructions?: string,
+): ParsedCompactionInstructions => {
+  const trimmed = customInstructions?.trim();
+  if (trimmed === COMPACTOR_INSTRUCTION) {
+    return { isCompactor: true, keepUserTurns: 1, keepUserTurnsExplicit: false, followUpPrompt: null };
+  }
+
+  const keepPrefix = `${COMPACTOR_INSTRUCTION} `;
+  if (trimmed?.startsWith(keepPrefix)) {
+    const parsed = parseKeepAndPrompt(trimmed.slice(keepPrefix.length));
+    return {
+      isCompactor: true,
+      keepUserTurns: parsed.keepUserTurns ?? 1,
+      keepUserTurnsExplicit: parsed.keepUserTurnsExplicit,
+      followUpPrompt: null,
+    };
+  }
+
+  const parsed = parseKeepAndPrompt(customInstructions);
+  return {
+    isCompactor: false,
+    keepUserTurns: parsed.keepUserTurns ?? 1,
+    keepUserTurnsExplicit: parsed.keepUserTurnsExplicit,
+    followUpPrompt: parsed.followUpPrompt || null,
+  };
+};

package/src/compaction/cut.ts

@@ -1,17 +1,34 @@
 /**
  * Cut logic — buildOwnCut for determining compaction boundaries
+ * (parity-aligned with pi-vcc before-compact.ts: keep:N user-turn cuts,
+ * token-budget tail rescue, orphan recovery via "" sentinel)
  */
 
-export type OwnCutCancelReason =
-  | "no_live_messages"
-  | "too_few_live_messages"
-  | "no_user_message";
-
 import type { SessionEntry, SessionMessageEntry, CompactionEntry } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import {
+  estimateMessageContentChars,
+  estimateMessageContentTokens,
+  estimateTokensFromChars,
+} from "./token-estimate.js";
+import type { BudgetCutKind } from "../types.js";
+
+export type OwnCutCancelReason =
+  | "no_live_messages"
+  | "too_few_live_messages";
 
 export type OwnCutResult =
-  | { ok: true; messages: AgentMessage[]; firstKeptEntryId: string; compactAll: boolean }
+  | {
+      ok: true;
+      messages: AgentMessage[];
+      firstKeptEntryId: string;
+      compactAll: boolean;
+      keptUserTurns: number;
+      totalUserTurns: number;
+      requestedKeepUserTurns: number;
+      keepFallbackToCompactAll: boolean;
+      budgetCut?: BudgetCutKind;
+    }
   | { ok: false; reason: OwnCutCancelReason };
 
 interface EntryWithMessage {
@@ -19,7 +36,35 @@ interface EntryWithMessage {
   message: AgentMessage;
 }
 
-export function buildOwnCut(branchEntries: SessionEntry[]): OwnCutResult {
+// Convert a non-message entry that carries LLM-context text (custom_message /
+// branch_summary) into its agent-message form, mirroring pi-core's
+// createCustomMessage / createBranchSummaryMessage (not root-exported, so inlined).
+const toLiveMessage = (entry: any): { role: string; content: unknown; [key: string]: unknown } | null => {
+  if (entry.type === "message" && entry.message) return entry.message;
+  if (entry.type === "custom_message") {
+    return {
+      role: "custom",
+      customType: entry.customType,
+      content: entry.content,
+      display: entry.display,
+      details: entry.details,
+      timestamp: entry.timestamp != null ? new Date(entry.timestamp).getTime() : undefined,
+    };
+  }
+  if (entry.type === "branch_summary") {
+    return {
+      role: "branchSummary",
+      summary: entry.summary,
+      fromId: entry.fromId,
+      content: undefined,
+      timestamp: entry.timestamp != null ? new Date(entry.timestamp).getTime() : undefined,
+    };
+  }
+  return null;
+};
+
+export const collectLiveMessages = (branchEntries: any[]): EntryWithMessage[] => {
+  // Find the last compaction entry and its firstKeptEntryId
   let lastCompactionIdx = -1;
   let lastKeptId: string | undefined;
   for (let i = branchEntries.length - 1; i >= 0; i--) {
@@ -31,48 +76,71 @@ export function buildOwnCut(branchEntries: SessionEntry[]): OwnCutResult {
     }
   }
 
+  // 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 hasValidKeptId = !!lastKeptId && branchEntries.some((e: any) => 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 });
-      }
+      const m = toLiveMessage(e);
+      if (m) liveMessages.push({ entry: e, message: m as unknown as AgentMessage });
     }
   } else {
-    let foundKept = !lastKeptId;
+    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 });
-      }
+      const m = toLiveMessage(e);
+      if (m) liveMessages.push({ entry: e, message: m as unknown as AgentMessage });
     }
   }
+  return liveMessages;
+};
+
+export function buildOwnCut(branchEntries: SessionEntry[], keepUserTurns = 1): OwnCutResult {
+  const normalizedKeepUserTurns = Number.isFinite(keepUserTurns)
+    ? Math.max(0, Math.floor(keepUserTurns))
+    : 0;
+  const liveMessages = collectLiveMessages(branchEntries);
 
   if (liveMessages.length === 0) return { ok: false, reason: "no_live_messages" };
-  if (liveMessages.length < 2) return { ok: false, reason: "too_few_live_messages" };
+  if (liveMessages.length <= 2) return { ok: false, reason: "too_few_live_messages" };
 
-  let cutIdx = liveMessages.length - 1;
-  while (cutIdx > 0 && liveMessages[cutIdx].message.role !== "user") {
-    cutIdx--;
-  }
+  const userIndices = liveMessages.reduce<number[]>((acc, e, i) => {
+    if (e.message.role === "user") acc.push(i);
+    return acc;
+  }, []);
+  const compactAll = (keepFallbackToCompactAll: boolean): OwnCutResult => ({
+    ok: true,
+    messages: liveMessages.map((e) => e.message),
+    firstKeptEntryId: "",
+    compactAll: true,
+    keptUserTurns: 0,
+    totalUserTurns: userIndices.length,
+    requestedKeepUserTurns: normalizedKeepUserTurns,
+    keepFallbackToCompactAll,
+  });
+
+  if (normalizedKeepUserTurns <= 0) return compactAll(false);
+
+  // Summarize all messages before the requested kept user-turn tail.
+  const targetUserIdx = userIndices.length - normalizedKeepUserTurns;
+  const cutIdx = targetUserIdx >= 0 ? userIndices[targetUserIdx] : -1;
 
   if (cutIdx <= 0) {
-    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,
-    };
+    // Keep request cannot form a safe boundary (single user prompt, no user prompt,
+    // or keep larger than available user turns), so 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.
+    return compactAll(true);
   }
 
   return {
@@ -80,5 +148,179 @@ export function buildOwnCut(branchEntries: SessionEntry[]): OwnCutResult {
     messages: liveMessages.slice(0, cutIdx).map((e) => e.message),
     firstKeptEntryId: liveMessages[cutIdx].entry.id,
     compactAll: false,
+    keptUserTurns: userIndices.length - targetUserIdx,
+    totalUserTurns: userIndices.length,
+    requestedKeepUserTurns: normalizedKeepUserTurns,
+    keepFallbackToCompactAll: false,
   };
 }
+
+// Token-budget tail cut: rescue default-path sessions when the user-turn
+// anchored tail is absent (autonomous: no user boundary in the live window)
+// or oversized (a single giant last user turn). Cuts at the nearest valid
+// non-toolResult boundary, mirroring pi-core's findCutPoint.
+export type BudgetCutKindLocal = BudgetCutKind;
+export const OVERSIZED_TAIL_FACTOR = 2.5;
+
+export const findBudgetCutIndex = (
+  live: EntryWithMessage[],
+  maxTokens: number,
+  charsPerToken?: number,
+): number => {
+  let acc = 0;
+  let crossed = -1;
+  for (let i = live.length - 1; i >= 0; i--) {
+    acc += estimateMessageContentTokens((live[i].message as any).content, charsPerToken);
+    if (acc >= maxTokens) {
+      crossed = i;
+      break;
+    }
+  }
+  if (crossed < 0) return -1;
+  // Snap forward off any toolResult to the next valid boundary.
+  for (let j = Math.max(crossed, 1); j < live.length; j++) {
+    if (live[j].message.role !== "toolResult") return j;
+  }
+  return -1;
+};
+
+export interface TailBudgetOptions {
+  maxTokens?: number;
+  oversizedFactor?: number;
+  charsPerToken?: number;
+}
+
+export const applyTailBudget = (
+  branchEntries: SessionEntry[],
+  cut: OwnCutResult,
+  opts: TailBudgetOptions = {},
+): OwnCutResult => {
+  if (!cut.ok) return cut;
+  const maxTokens = opts.maxTokens ?? MAX_SMART_TAIL_TOKENS;
+  const factor = opts.oversizedFactor ?? OVERSIZED_TAIL_FACTOR;
+  const live = collectLiveMessages(branchEntries);
+
+  const budgetResult = (idx: number, budgetCut: BudgetCutKind): OwnCutResult => ({
+    ok: true,
+    messages: live.slice(0, idx).map((m) => m.message),
+    firstKeptEntryId: live[idx].entry.id,
+    compactAll: false,
+    keptUserTurns: live.slice(idx).filter((m) => m.message.role === "user").length,
+    totalUserTurns: live.filter((m) => m.message.role === "user").length,
+    requestedKeepUserTurns: cut.requestedKeepUserTurns,
+    keepFallbackToCompactAll: false,
+    budgetCut,
+  });
+
+  // Case A: no user anchor → compact-all. Re-cut to a token budget unless the
+  // compact-all came from explicit keep:0 (which must be respected absolutely).
+  if (cut.compactAll) {
+    if (!cut.keepFallbackToCompactAll) return cut;
+    const idx = findBudgetCutIndex(live, maxTokens, opts.charsPerToken);
+    if (idx < 0) return cut;
+    return budgetResult(idx, "no_anchor");
+  }
+
+  // Case B: oversized user-boundary tail. Only re-cut when the kept tail exceeds
+  // maxTokens * factor (tolerance zone below is unchanged).
+  const tailStart = cut.messages.length; // equals the cut index in the live window
+  let tailTokens = 0;
+  for (let i = tailStart; i < live.length; i++) {
+    tailTokens += estimateMessageContentTokens((live[i].message as any).content, opts.charsPerToken);
+  }
+  if (tailTokens <= maxTokens * factor) return cut;
+  const idx = findBudgetCutIndex(live, maxTokens, opts.charsPerToken);
+  if (idx <= tailStart) return cut;
+  return budgetResult(idx, "oversized_tail");
+};
+
+// ── smart keep-tail: boost default keep when tail is small ──
+
+export const MIN_SMART_TAIL_TOKENS = 5_000;
+export const MAX_SMART_TAIL_TOKENS = 25_000;
+
+export interface ResolveSmartKeepOptions {
+  branchEntries: SessionEntry[];
+  /** Requested keep:N; null when user did not specify (default path). */
+  requestedKeepUserTurns: number | null;
+  /** True when user typed keep:N explicitly — always respected. */
+  explicit: boolean;
+  /** Setting toggle. */
+  smartKeepTail: boolean;
+  /** Injectable thresholds for tests. */
+  minTokens?: number;
+  maxTokens?: number;
+  /** Calibrated chars/token for the current session; defaults to heuristic when omitted. */
+  charsPerToken?: number;
+}
+
+export interface ResolveSmartKeepResult {
+  keepUserTurns: number;
+  smartAdjusted: boolean;
+  /** Original base keep, for toast like "1→3". */
+  fromKeep: number;
+}
+
+/**
+ * Estimate tail tokens for a given keep:N.
+ * Returns null when keep would trigger compact-all (tail lost) or cancel,
+ * so the resolver can stop growing instead of selecting a value that
+ * discards the tail entirely.
+ */
+const tailTokensForKeep = (
+  branchEntries: SessionEntry[],
+  keepUserTurns: number,
+  charsPerToken?: number,
+): number | null => {
+  const cut = buildOwnCut(branchEntries, keepUserTurns);
+  if (!cut.ok || cut.compactAll) return null;
+  const idx = branchEntries.findIndex((e: SessionEntry) => e.id === cut.firstKeptEntryId);
+  if (idx < 0) return null;
+  const kept = branchEntries.slice(idx).filter((e: SessionEntry): e is SessionMessageEntry =>
+    e.type === "message",
+  );
+  const chars = kept.reduce(
+    (sum: number, e: SessionMessageEntry) => sum + estimateMessageContentChars((e.message as any)?.content),
+    0,
+  );
+  return estimateTokensFromChars(chars, charsPerToken);
+};
+
+/**
+ * Resolve the effective keep:N.
+ * - Explicit keep:N from the user is always respected.
+ * - smartKeepTail=false → old behavior (default keep:1).
+ * - smartKeepTail=true → if keep:1 tail <= minTokens, grow keep to the
+ *   largest N whose tail stays <= maxTokens. Stops at compact-all boundary.
+ */
+export const resolveSmartKeepUserTurns = (opts: ResolveSmartKeepOptions): ResolveSmartKeepResult => {
+  const minTokens = opts.minTokens ?? MIN_SMART_TAIL_TOKENS;
+  const maxTokens = opts.maxTokens ?? MAX_SMART_TAIL_TOKENS;
+  const baseKeep = opts.requestedKeepUserTurns ?? 1;
+
+  if (opts.explicit || !opts.smartKeepTail) {
+    return { keepUserTurns: baseKeep, smartAdjusted: false, fromKeep: baseKeep };
+  }
+
+  const baseTokens = tailTokensForKeep(opts.branchEntries, baseKeep, opts.charsPerToken);
+  // base tail already above min (or unmeasurable / compact-all) → don't grow.
+  if (baseTokens == null || baseTokens > minTokens) {
+    return { keepUserTurns: baseKeep, smartAdjusted: false, fromKeep: baseKeep };
+  }
+
+  const baseCut = buildOwnCut(opts.branchEntries, baseKeep);
+  const totalUserTurns = baseCut.ok ? baseCut.totalUserTurns : 0;
+
+  let selected = baseKeep;
+  for (let k = baseKeep + 1; k <= totalUserTurns; k++) {
+    const tokens = tailTokensForKeep(opts.branchEntries, k, opts.charsPerToken);
+    if (tokens == null || tokens > maxTokens) break;
+    selected = k;
+  }
+
+  return {
+    keepUserTurns: selected,
+    smartAdjusted: selected !== baseKeep,
+    fromKeep: baseKeep,
+  };
+};

package/src/compaction/drill-down.ts

@@ -0,0 +1,261 @@
+/**
+ * Drill-down: resolve #N:path syntax to tool call file content (pi-vcc parity).
+ *
+ * Supports: #42:auth.ts (preview), #42:auth.ts:full (full content),
+ * #42:auth.ts:30 (offset), #42:auth.ts:30:20 (offset:limit).
+ */
+
+import type { NormalizedBlock } from "../types.js";
+
+// ── Types ─────────────────────────────────────────────────────────────────
+
+interface ContentBearingCall {
+  name: string;
+  path: string;
+  content?: string;
+  oldText?: string;
+  newText?: string;
+  edits?: Array<{ oldText?: string; newText?: string }>;
+}
+
+const PATH_KEYS = ["path", "file_path", "filePath", "file"] as const;
+
+/** Extract a file path from tool args */
+const extractPath = (args: Record<string, unknown>): string | undefined => {
+  for (const key of PATH_KEYS) {
+    const val = args[key];
+    if (typeof val === "string" && val.length > 0) return val;
+  }
+  return undefined;
+};
+
+/**
+ * A call is content-bearing if it has a path argument AND at least one
+ * large string/array field (content, edits, oldText, newText).
+ */
+export const isContentBearing = (args: Record<string, unknown>): boolean => {
+  if (!args || typeof args !== "object") return false;
+  const hasPath = PATH_KEYS.some((k) => typeof args[k] === "string");
+  if (!hasPath) return false;
+  if (typeof args.content === "string" && args.content.length > 0) return true;
+  if (
+    Array.isArray(args.edits) &&
+    args.edits.length > 0 &&
+    args.edits.every((e) => typeof e === "object" && e !== null)
+  )
+    return true;
+  if (typeof args.oldText === "string" && args.oldText.length > 0 && args.edits === undefined)
+    return true;
+  if (typeof args.newText === "string" && args.newText.length > 0 && args.edits === undefined)
+    return true;
+  return false;
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/** Find content-bearing tool_call blocks with a path arg and content fields. */
+function findContentBearingCalls(blocks: NormalizedBlock[]): ContentBearingCall[] {
+  const results: ContentBearingCall[] = [];
+  for (const b of blocks) {
+    if (b.kind !== "tool_call") continue;
+    if (!isContentBearing(b.args)) continue;
+    const path = extractPath(b.args);
+    if (!path) continue;
+    const entry: ContentBearingCall = { name: b.name, path };
+    if (typeof b.args.content === "string") entry.content = b.args.content;
+    if (Array.isArray(b.args.edits)) {
+      entry.edits = (b.args.edits as unknown[]).filter(
+        (e): e is { oldText?: string; newText?: string } =>
+          e !== null && typeof e === "object",
+      );
+    }
+    if (typeof b.args.oldText === "string" && !Array.isArray(b.args.edits))
+      entry.oldText = b.args.oldText;
+    if (typeof b.args.newText === "string" && !Array.isArray(b.args.edits))
+      entry.newText = b.args.newText;
+    results.push(entry);
+  }
+  return results;
+}
+
+/** Format content for display with optional offset/limit slicing. */
+function formatToolCallContent(
+  tc: ContentBearingCall,
+  entryIndex: number,
+  options?: { full?: boolean; offset?: number; limit?: number },
+): string {
+  let body: string;
+  if (tc.content) {
+    body = tc.content;
+  } else if (tc.edits) {
+    body = tc.edits
+      .map(
+        (e, i) =>
+          `--- edit ${i + 1} ---\n${e.oldText ?? ""}\n--- becomes ---\n${e.newText ?? ""}`,
+      )
+      .join("\n\n");
+  } else if (tc.oldText && tc.newText) {
+    body = `--- old ---\n${tc.oldText}\n--- new ---\n${tc.newText}`;
+  } else {
+    body = "(no file content found in tool call arguments)";
+  }
+
+  const full = options?.full ?? false;
+  const offset = options?.offset;
+  const limit = options?.limit;
+  const allLines = body.split("\n");
+  const totalLines = allLines.length;
+  const previewLimit = 30;
+  const MAX_FULL_BYTES = 50 * 1024;
+
+  if (full) {
+    if (Buffer.byteLength(body, "utf8") > MAX_FULL_BYTES) {
+      const truncated = body.slice(0, MAX_FULL_BYTES);
+      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.)`;
+    }
+    return `File: ${tc.path}
+Tool: ${tc.name}
+
+${body}`;
+  }
+
+  if (offset !== undefined) {
+    const startLine = Math.max(0, offset);
+    const maxLines = limit ?? 30;
+    const endLine = Math.min(startLine + maxLines, totalLines);
+    const visible = allLines.slice(startLine, endLine);
+    const displayStart = startLine + 1;
+
+    if (visible.length === 0) {
+      return `Offset ${startLine} is beyond file length ${totalLines}. Use #${entryIndex}:${tc.path} for the first ${previewLimit} lines.`;
+    }
+
+    let result = `File: ${tc.path}
+Tool: ${tc.name}
+Lines ${displayStart}-${endLine} (of ${totalLines}):
+
+`;
+    result += visible.join("\n");
+
+    if (endLine < totalLines) {
+      result += `\n\n--- Use #${entryIndex}:${tc.path}:${endLine} or #${entryIndex}:${tc.path}:${endLine}:${maxLines} for next ${maxLines} lines, #${entryIndex}:${tc.path}:full for complete ---`;
+    } else if (offset > 0) {
+      result += `\n\n(End of file)`;
+    }
+
+    return result;
+  }
+
+  // Default preview mode: first ${previewLimit} lines
+  if (totalLines > previewLimit) {
+    const preview = allLines.slice(0, previewLimit).join("\n");
+    return `File: ${tc.path}
+Tool: ${tc.name}
+
+${preview}
+
+...(${totalLines - previewLimit} more lines — use #${entryIndex}:${tc.path}:full for complete content, or #${entryIndex}:${tc.path}:${previewLimit} for next ${previewLimit} lines)`;
+  }
+
+  return `File: ${tc.path}
+Tool: ${tc.name}
+
+${body}`;
+}
+
+// ── Parse drill-down query ────────────────────────────────────────────────
+
+/**
+ * Pattern: #N:path, #N:path:full, #N:path:offset, or #N:path:offset:limit.
+ * The ^ anchor requires the entire query to be the drill-down pattern, so
+ * inline mentions like "see #42:auth.ts" are never treated as drill-down.
+ */
+const DRILLDOWN_PATTERN = /^#(\d+):(.+?)(?::(full|\d+(?::\d+)?))?$/;
+
+export function parseDrillDown(query: string): {
+  index: number;
+  pathPattern: string;
+  full: boolean;
+  offset?: number;
+  limit?: number;
+} | null {
+  const match = query.match(DRILLDOWN_PATTERN);
+  if (!match) return null;
+  const index = parseInt(match[1], 10);
+  const pathPattern = match[2];
+  const suffix = match[3];
+
+  if (suffix === "full") {
+    return { index, pathPattern, full: true, offset: undefined, limit: undefined };
+  }
+
+  if (suffix !== undefined) {
+    const parts = suffix.split(":");
+    const offset = parseInt(parts[0], 10);
+    const limit = parts[1] !== undefined ? parseInt(parts[1], 10) : undefined;
+    if (!Number.isNaN(offset)) {
+      return { index, pathPattern, full: false, offset, limit };
+    }
+  }
+
+  return { index, pathPattern, full: false, offset: undefined, limit: undefined };
+}
+
+// ── Main export ───────────────────────────────────────────────────────────
+
+/**
+ * Expand a drill-down query (#N:path) to tool call content from blocks whose
+ * sourceIndex matches the entry index.
+ */
+export function expandEntryFile(
+  blocks: NormalizedBlock[],
+  entryIndex: number,
+  pathPattern: string,
+  full = false,
+  offset?: number,
+  limit?: number,
+): string {
+  const entryBlocks = blocks.filter((b) => b.sourceIndex === entryIndex);
+  if (entryBlocks.length === 0) {
+    return `Entry #${entryIndex} not found in session history.`;
+  }
+
+  const calls = findContentBearingCalls(entryBlocks);
+
+  // Special case: #42:file keyword
+  if (pathPattern === "file") {
+    if (calls.length === 0) {
+      return `No file content found in entry #${entryIndex}.`;
+    }
+    if (calls.length === 1) {
+      return formatToolCallContent(calls[0], entryIndex, { full, offset, limit });
+    }
+    const items = calls.map(
+      (tc) => `  [#${entryIndex}:${tc.path}] ${tc.name}(${tc.path})`,
+    );
+    return `Entry #${entryIndex} has ${calls.length} file operations:\n${items.join("\n")}\n\nUse #${entryIndex}:path to drill into a specific file.`;
+  }
+
+  const matched = calls.filter((tc) => tc.path.includes(pathPattern));
+
+  if (matched.length === 0) {
+    return `No file content found in entry #${entryIndex} for "${pathPattern}".`;
+  }
+
+  if (matched.length > 1) {
+    const items = matched.map(
+      (tc) => `  [#${entryIndex}:${tc.path}] ${tc.name}(${tc.path})`,
+    );
+    return `Entry #${entryIndex} has ${matched.length} file operations matching "${pathPattern}":
+${items.join("\n")}
+
+Use #${entryIndex}:<more-specific-path> to drill into a specific file.`;
+  }
+
+  return formatToolCallContent(matched[0], entryIndex, { full, offset, limit });
+}