@monotykamary/pi-supervisor 0.5.9

package/src/compaction/extract/goals.ts

@@ -0,0 +1,79 @@
+import type { NormalizedBlock } from '../types';
+import { nonEmptyLines, clip } from '../content';
+import { collapseSkillLines } from '../skill-collapse';
+
+const SCOPE_CHANGE_RE =
+  /\b(instead|actually|change of plan|forget that|new task|switch to|now I want|pivot|let'?s do|stop .* and)\b/i;
+
+const TASK_RE =
+  /\b(fix|implement|add|create|build|refactor|debug|investigate|update|remove|delete|migrate|deploy|test|write|set up)\b/i;
+
+const NOISE_SHORT_RE = /^(ok|yes|no|sure|yeah|yep|go|hi|hey|thx|thanks|ok\b.*|y|n|k)\s*[.!?]*$/i;
+
+// Reject lines that are clearly not user goals (pasted output, code, paths, tool dumps)
+// or meta-prompt boilerplate (command templates like `/issues` that start with "For each issue:"
+// followed by numbered "Read the issue in full..." steps).
+const NON_GOAL_RE =
+  /^\s*[\[│├└─╭╰]|```|^\s*(=[A-Z]+\(|function |const |let |var |import |export |class )|^(https?:|file:|\/[A-Za-z])|\\n|^\s*For each\b|\bin full\b[^\n]*\b(comments|issue|issues|PRs?|linked)\b/;
+
+// Signals that the rest of the user message is a command template (e.g. /issues),
+// in which case we should stop collecting goals at the signal line.
+const TEMPLATE_SIGNAL_RE =
+  /^\s*(For each\b|Do NOT implement\b|Analyze and propose\b|If Task\/context\b|Output:\s*$)/i;
+
+const truncateAtTemplate = (lines: string[]): string[] => {
+  const idx = lines.findIndex((l) => TEMPLATE_SIGNAL_RE.test(l));
+  return idx >= 0 ? lines.slice(0, idx) : lines;
+};
+
+const stripLeadingBullet = (line: string): string =>
+  line.replace(/^\s*(?:[-*+]|\d+\.)\s+/, '').trim();
+
+const MAX_GOAL_CHARS = 200;
+
+const isSubstantiveGoal = (text: string): boolean => {
+  const t = text.trim();
+  if (t.length <= 5) return false;
+  if (t.length > MAX_GOAL_CHARS) return false;
+  if (NOISE_SHORT_RE.test(t)) return false;
+  if (NON_GOAL_RE.test(t)) return false;
+  return true;
+};
+
+// Test scope-change / task intent only on the leading portion of a user block
+// so that pasted outputs below the actual instruction do not trigger matches.
+const LEADING_CHARS = 200;
+
+export const extractGoals = (blocks: NormalizedBlock[]): string[] => {
+  const goals: string[] = [];
+  let latestScopeChange: string[] | null = null;
+
+  for (const b of blocks) {
+    if (b.kind !== 'user') continue;
+    const rawLines = nonEmptyLines(b.text);
+    const truncated = truncateAtTemplate(rawLines);
+    const lines = collapseSkillLines(truncated.filter(isSubstantiveGoal))
+      .map(stripLeadingBullet)
+      .filter((l) => l.length > 5);
+    if (lines.length === 0) continue;
+
+    if (goals.length === 0) {
+      goals.push(...lines.slice(0, 6));
+      continue;
+    }
+
+    const leading = b.text.slice(0, LEADING_CHARS);
+    if (SCOPE_CHANGE_RE.test(leading)) {
+      latestScopeChange = lines.slice(0, 3).map((l) => clip(l, MAX_GOAL_CHARS));
+    } else if (TASK_RE.test(leading) && lines[0].length > 15) {
+      latestScopeChange = lines.slice(0, 2).map((l) => clip(l, MAX_GOAL_CHARS));
+    }
+  }
+
+  // Only emit the [Scope change] marker when we actually captured bullets.
+  if (latestScopeChange && latestScopeChange.length > 0) {
+    goals.push('[Scope change]', ...latestScopeChange);
+  }
+
+  return goals.slice(0, 8);
+};

package/src/compaction/extract/preferences.ts

@@ -0,0 +1,52 @@
+import type { NormalizedBlock } from '../types';
+import { clip, nonEmptyLines } from '../content';
+
+// Tightened patterns: require a clear preference construction, not bare keywords.
+const PREF_PATTERNS = [
+  /\bprefer(?:s|red|ring)?\s+\w/i,
+  /\bdon'?t want\b/i,
+  /\balways (?:use|do|run|prefer|keep|make|format|write|add|set|put|prefix|start|include|append)\b/i,
+  /\bnever (?:use|do|run|push|commit|write|ignore|add|set|put|remove|delete|include|deploy)\b/i,
+  /\bplease (?:use|avoid|keep|make|don'?t|do not|format|write)\b/i,
+  /\b(?:style|format|language|naming)\s*[:=]\s*\S/i,
+];
+
+export const extractPreferences = (blocks: NormalizedBlock[]): string[] => {
+  const prefs: string[] = [];
+  const seen = new Set<string>();
+
+  for (const b of blocks) {
+    if (b.kind !== 'user') continue;
+
+    let perBlock = 0;
+    for (const line of nonEmptyLines(b.text)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.length < 5) continue;
+      if (trimmed.length > 200) continue;
+      // Reject questions.
+      if (trimmed.endsWith('?') || trimmed.includes('?...')) continue;
+      if (!PREF_PATTERNS.some((p) => p.test(trimmed))) continue;
+
+      const clipped = clip(trimmed, 200);
+      const key = clipped.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      prefs.push(clipped);
+
+      // Cap per user block to avoid pasting long rule lists as many prefs.
+      if (++perBlock >= 1) break;
+    }
+  }
+
+  return prefs.slice(0, 10);
+};
+
+/**
+ * Remove preferences that duplicate goals (case-insensitive, trimmed).
+ * Called by `buildSections` so that the two sections do not overlap.
+ */
+export const dedupPreferencesAgainstGoals = (prefs: string[], goals: string[]): string[] => {
+  const norm = (s: string) => s.trim().toLowerCase();
+  const goalSet = new Set(goals.map(norm));
+  return prefs.filter((p) => !goalSet.has(norm(p)));
+};

package/src/compaction/extract/shared-symbols.ts

@@ -0,0 +1,376 @@
+import type { NormalizedBlock, ToolResultIndex } from '../types';
+import { extractPath } from '../tool-args';
+
+const FILE_WRITE_TOOLS = new Set([
+  'Edit',
+  'Write',
+  'edit',
+  'write',
+  'edit_file',
+  'write_file',
+  'MultiEdit',
+]);
+
+const FILE_READ_TOOLS = new Set(['Read', 'read', 'read_file', 'View']);
+
+const FILE_CREATE_TOOLS = new Set(['Write', 'write', 'write_file']);
+
+// Declaration regexes — consolidated from files.ts, symbol-changes.ts, type-catalog.ts
+// Order: more specific patterns first, generic fallbacks last.
+
+const TS_EXPORT_DECL_RE =
+  /^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function|class|type|interface|const|let|enum)\s+(\w+)/;
+const TS_TYPE_DECL_RE = /^\s*(?:export\s+)?(?:type|interface)\s+(\w+)/;
+const TS_EXPORT_SIG_RE =
+  /^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function|class|type|interface|const|let|enum)\s+\w+[^;{]*[;{]?/;
+
+const RUST_DECL_RE =
+  /^\s*(?:pub(?:\s*\([^)]*\))?\s+)?(?:fn|struct|enum|trait|type|const|union|var)\s+(\w+)/;
+const RUST_IMPL_RE =
+  /^\s*(?:pub(?:\s*\([^)]*\))?\s+)?impl\s+(?:<[^>]+>\s+)?(\w+)(?:\s+for\s+(\w+))?/;
+const RUST_SIG_RE = /^\s*pub\s+(?:async\s+)?(?:fn|struct|enum|trait|type)\s+\w+/;
+
+const ELIXIR_DEF_RE = /^\s*def(?:p|macro|macrop|guard|guardp)?\s+(\w+)/;
+const ELIXIR_MODULE_RE = /^\s*defmodule\s+(\w+)/;
+const ELIXIR_SPECIAL_RE = /^\s*def(?:struct|protocol|impl)\s+(\w+)/;
+
+const JAVA_TYPE_RE =
+  /^\s*(?:(?:public|private|protected)\s+)?(?:abstract\s+|static\s+|final\s+|sealed\s+)?(?:class|interface|enum|@interface|record)\s+(\w+)/;
+const JAVA_METHOD_RE =
+  /^\s*(?:public|protected)\s+(?:static\s+|abstract\s+|final\s+)?(?:\S+(?:\s*\[\])?\s+)(\w+)\s*\(/;
+
+const C_TYPE_RE = /^\s*(?:typedef\s+)?(?:struct|class|enum|union)\s+(\w+)/;
+const C_FUNC_RE =
+  /^\s*(?!func\b)(?:(?:static|extern|inline|virtual)\s+)?[\w][\w:*&\s]*?(\b\w+)\s*\(/;
+
+const RUBY_DEF_RE = /^\s*def\s+(?:self\.)?(\w+)/;
+const RUBY_TYPE_RE = /^\s*(?:class|module)\s+(\w+)/;
+
+const PY_DECL_RE = /^\s*(?:async\s+)?def\s+(\w+)|^\s*class\s+(\w+)/;
+const PY_SIG_RE = /^\s*(?:async\s+)?(?:def|class)\s+\w+\s*(?:\([^)]*\))?/;
+
+const GO_DECL_RE = /^\s*func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)/;
+const GO_SIG_RE = /^\s*func\s+(?:\(\w+\s+\*?\w+\)\s+)?\w+\s*(?:\([^)]*\))?\s*(?:\([^)]*\))?/;
+
+interface SymbolInfo {
+  /** Simple declaration name (used by files.ts, symbol-changes.ts) */
+  name: string;
+  /** Declaration kind */
+  kind: 'function' | 'type' | 'class' | 'variable' | 'unknown';
+  /** Full signature line (used by type-catalog.ts) */
+  signature?: string;
+}
+
+interface ToolCallSymbols {
+  /** Symbols found in the tool_result text */
+  resultSymbols: SymbolInfo[];
+  /** Symbols found in Edit/Write args (newText/content) */
+  argSymbols: SymbolInfo[];
+}
+
+// Fast screening regex: rejects lines that can't start any declaration.
+// Avoids running the full 15-regex cascade on body code / comments / blank lines.
+const DECL_SCREEN_RE =
+  /^\s*(?:export|pub|func|def|class|type|interface|async|abstract|static|public|private|protected|struct|enum|trait|impl|module|const|fn|sealed|record|typedef|union|virtual|extern|inline)/;
+
+const parseDeclName = (line: string): { name: string; kind: SymbolInfo['kind'] } | null => {
+  // Quick reject: lines that can't start any declaration keyword
+  if (!DECL_SCREEN_RE.test(line)) return null;
+
+  let m = line.match(TS_EXPORT_DECL_RE);
+  if (m) {
+    const kind = line.includes('function')
+      ? 'function'
+      : line.includes('class')
+        ? 'class'
+        : line.includes('type')
+          ? 'type'
+          : line.includes('interface')
+            ? 'type'
+            : line.includes('enum')
+              ? 'variable'
+              : 'variable';
+    return { name: m[1], kind };
+  }
+  m = line.match(TS_TYPE_DECL_RE);
+  if (m) return { name: m[1], kind: 'type' };
+  m = line.match(RUST_DECL_RE);
+  if (m) return { name: m[1], kind: 'function' };
+  m = line.match(RUST_IMPL_RE);
+  if (m) return { name: m[1], kind: 'class' };
+  m = line.match(ELIXIR_MODULE_RE);
+  if (m) return { name: m[1], kind: 'class' };
+  m = line.match(ELIXIR_SPECIAL_RE);
+  if (m) return { name: m[1], kind: 'class' };
+  m = line.match(ELIXIR_DEF_RE);
+  if (m) return { name: m[1], kind: 'function' };
+  m = line.match(JAVA_TYPE_RE);
+  if (m) return { name: m[1], kind: 'class' };
+  m = line.match(JAVA_METHOD_RE);
+  if (m) return { name: m[1], kind: 'function' };
+  m = line.match(C_TYPE_RE);
+  if (m) return { name: m[1], kind: 'class' };
+  m = line.match(C_FUNC_RE);
+  if (m) return { name: m[1], kind: 'function' };
+  m = line.match(RUBY_TYPE_RE);
+  if (m) return { name: m[1], kind: 'class' };
+  m = line.match(RUBY_DEF_RE);
+  if (m) return { name: m[1], kind: 'function' };
+  m = line.match(PY_DECL_RE);
+  if (m) return { name: m[1] || m[2], kind: m[2] ? 'class' : 'function' };
+  m = line.match(GO_DECL_RE);
+  if (m && m[1][0] === m[1][0].toUpperCase()) return { name: m[1], kind: 'function' };
+  return null;
+};
+
+const parseSignature = (line: string): string | null => {
+  if (TS_EXPORT_SIG_RE.test(line)) return line.trim();
+  if (
+    PY_SIG_RE.test(line) &&
+    !line.trim().startsWith('def _') &&
+    !line.trim().startsWith('class _')
+  )
+    return line.trim();
+  if (GO_SIG_RE.test(line)) {
+    const nameMatch = line.match(/func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)/);
+    if (nameMatch && nameMatch[1] && nameMatch[1][0] === nameMatch[1][0].toUpperCase())
+      return line.trim();
+  }
+  if (RUST_SIG_RE.test(line)) return line.trim();
+  return null;
+};
+
+/**
+ * Line-by-line iteration over text using indexOf("\n") instead of split().
+ * Avoids allocating an intermediate string array — for a 300-line, 12KB
+ * tool result this saves ~30μs/scan vs split().  Over 600 tool results
+ * in a large session, that's ~18ms reclaimed.
+ */
+const eachLine = function* (text: string, maxLines: number): Generator<string> {
+  let pos = 0;
+  let count = 0;
+  const len = text.length;
+  while (pos < len && count < maxLines) {
+    const nl = text.indexOf('\n', pos);
+    if (nl === -1) {
+      yield text.slice(pos);
+      return;
+    }
+    yield text.slice(pos, nl);
+    pos = nl + 1;
+    count++;
+  }
+};
+
+const extractSymbolsFromText = (
+  text: string,
+  maxLines: number,
+  includeSigs: boolean
+): SymbolInfo[] => {
+  const names: SymbolInfo[] = [];
+  const seen = new Set<string>();
+  for (const line of eachLine(text, maxLines)) {
+    const decl = parseDeclName(line);
+    if (decl && !seen.has(decl.name)) {
+      seen.add(decl.name);
+      const sig = includeSigs ? parseSignature(line) : undefined;
+      names.push({ name: decl.name, kind: decl.kind, signature: sig ?? undefined });
+    }
+  }
+  return names;
+};
+
+interface FileActivity {
+  read: Set<string>;
+  modified: Set<string>;
+  created: Set<string>;
+  symbols: Map<string, string[]>;
+}
+
+interface ExportSig {
+  file: string;
+  signatures: string[];
+  modified: boolean;
+}
+
+export interface SymbolRef {
+  name: string;
+  file: string;
+  kind: 'function' | 'type' | 'class' | 'variable' | 'unknown';
+  access: 'modified' | 'read';
+}
+
+export interface UnifiedExtractResult {
+  fileActivity: FileActivity;
+  typeCatalog: ExportSig[];
+  symbolChanges: SymbolRef[];
+}
+
+/**
+ * Single-pass extraction of all file/symbol information from tool calls.
+ *
+ * Replaces the triple-redundant scan performed by:
+ *   - extractFiles() — path collection + 200-line symbol scan
+ *   - extractSymbolChanges() — 300-line symbol scan
+ *   - extractTypeCatalog() — 150-line signature scan
+ *
+ * All three scanned the same tool_result content with overlapping regex
+ * patterns. This unified pass does it once and returns all three datasets.
+ */
+export const extractFileAndSymbolData = (
+  blocks: NormalizedBlock[],
+  tri?: ToolResultIndex
+): UnifiedExtractResult => {
+  const read = new Set<string>();
+  const modified = new Set<string>();
+  const created = new Set<string>();
+  // Parallel dedup set for symbols Map — avoids O(n) Array.includes()
+  // on symbol arrays that can grow to 200+ entries per file.
+  const symbols = new Map<string, string[]>();
+  const symbolsSeen = new Map<string, Set<string>>();
+  const symbolRefs: SymbolRef[] = [];
+  const refSeen = new Set<string>();
+
+  // Type catalog state
+  const fileSigs = new Map<string, { sigs: string[]; modified: boolean }>();
+  const fileOrder: string[] = [];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b.kind !== 'tool_call') continue;
+    const p = extractPath(b.args);
+    if (!p) continue;
+
+    const isRead = FILE_READ_TOOLS.has(b.name);
+    const isWrite = FILE_WRITE_TOOLS.has(b.name);
+    const isCreate = FILE_CREATE_TOOLS.has(b.name);
+
+    if (isRead) read.add(p);
+    if (isWrite) modified.add(p);
+    if (isCreate) created.add(p);
+
+    // Extract symbols from Edit/Write args
+    if (isWrite) {
+      const newText = (b.args.newText ?? b.args.new_text ?? b.args.content ?? '') as string;
+      if (newText && typeof newText === 'string') {
+        const syms = extractSymbolsFromText(newText, 100, true);
+
+        // File activity symbols
+        let seen = symbolsSeen.get(p);
+        if (!seen) {
+          seen = new Set();
+          symbolsSeen.set(p, seen);
+        }
+        if (!symbols.has(p)) symbols.set(p, []);
+        const existing = symbols.get(p)!;
+        for (const s of syms) {
+          if (!seen.has(s.name)) {
+            seen.add(s.name);
+            existing.push(s.name);
+          }
+        }
+
+        // Type catalog
+        if (!fileSigs.has(p)) {
+          fileSigs.set(p, { sigs: [], modified: true });
+          fileOrder.push(p);
+        } else {
+          fileSigs.get(p)!.modified = true;
+        }
+        const sigs = fileSigs.get(p)!.sigs;
+        for (const s of syms) {
+          if (s.signature && !sigs.includes(s.signature)) sigs.push(s.signature);
+        }
+
+        // Symbol changes
+        const access = 'modified' as const;
+        for (const s of syms) {
+          const key = `${s.name}@${p}`;
+          if (!refSeen.has(key)) {
+            refSeen.add(key);
+            symbolRefs.push({ name: s.name, file: p, kind: s.kind, access });
+          }
+        }
+      }
+    }
+
+    // Extract from tool_result (shared look-ahead via index)
+    if (isRead || isWrite) {
+      const r = tri
+        ? tri.get(i)
+        : (() => {
+            for (let j = i + 1; j < Math.min(blocks.length, i + 4); j++) {
+              const b2 = blocks[j];
+              if (b2.kind === 'tool_result')
+                return b2 as Extract<NormalizedBlock, { kind: 'tool_result' }>;
+            }
+            return null;
+          })();
+
+      if (r && r.text && !r.isError) {
+        const resultText = r.text;
+
+        // Parse symbols once — 200 lines covers all three extractors' needs
+        const syms = extractSymbolsFromText(resultText, 200, true);
+
+        // File activity symbols
+        let seen = symbolsSeen.get(p);
+        if (!seen) {
+          seen = new Set();
+          symbolsSeen.set(p, seen);
+        }
+        if (!symbols.has(p)) symbols.set(p, []);
+        const existing = symbols.get(p)!;
+        for (const s of syms) {
+          if (!seen.has(s.name)) {
+            seen.add(s.name);
+            existing.push(s.name);
+          }
+        }
+
+        // Type catalog (Read results)
+        if (isRead) {
+          if (!fileSigs.has(p)) {
+            fileSigs.set(p, { sigs: [], modified: false });
+            fileOrder.push(p);
+          }
+          const sigs = fileSigs.get(p)!.sigs;
+          for (const s of syms) {
+            if (s.signature && !sigs.includes(s.signature)) sigs.push(s.signature);
+          }
+        }
+
+        // Symbol changes
+        const access = isWrite ? ('modified' as const) : ('read' as const);
+        for (const s of syms) {
+          const key = `${s.name}@${p}`;
+          if (!refSeen.has(key)) {
+            refSeen.add(key);
+            symbolRefs.push({ name: s.name, file: p, kind: s.kind, access });
+          }
+        }
+      }
+    }
+  }
+
+  // Dedup: if already Modified, drop from Created
+  for (const p of modified) created.delete(p);
+
+  // Build type catalog — modified files first, then read files
+  const modifiedSigs: ExportSig[] = [];
+  const readSigs: ExportSig[] = [];
+  for (const file of fileOrder) {
+    const entry = fileSigs.get(file)!;
+    if (entry.sigs.length === 0) continue;
+    const esig: ExportSig = { file, signatures: entry.sigs.slice(0, 8), modified: entry.modified };
+    if (esig.modified) modifiedSigs.push(esig);
+    else readSigs.push(esig);
+  }
+  const typeCatalog = [...modifiedSigs, ...readSigs].slice(0, 12);
+
+  return {
+    fileActivity: { read, modified, created, symbols },
+    typeCatalog,
+    symbolChanges: symbolRefs,
+  };
+};

package/src/compaction/filter-noise.ts

@@ -0,0 +1,47 @@
+import type { NormalizedBlock } from './types';
+
+const NOISE_TOOLS = new Set([
+  'TodoWrite',
+  'TodoRead',
+  'ToolSearch',
+  'WebSearch',
+  'AskUser',
+  'ExitSpecMode',
+  'GenerateDroid',
+]);
+
+const NOISE_STRINGS = [
+  'Continue from where you left off.',
+  'No response requested.',
+  'IMPORTANT: TodoWrite was not called yet.',
+];
+
+const XML_WRAPPER_RE =
+  /<(system-reminder|ide_opened_file|command-message|context-window-usage)[^>]*>[\s\S]*?<\/\1>/g;
+
+const isNoiseUserBlock = (text: string): boolean => {
+  const trimmed = text.trim();
+  if (NOISE_STRINGS.some((s) => trimmed.includes(s))) return true;
+  const stripped = trimmed.replace(XML_WRAPPER_RE, '').trim();
+  return stripped.length === 0;
+};
+
+const cleanUserText = (text: string): string => text.replace(XML_WRAPPER_RE, '').trim();
+
+export const filterNoise = (blocks: NormalizedBlock[]): NormalizedBlock[] => {
+  const out: NormalizedBlock[] = [];
+  for (const b of blocks) {
+    if (b.kind === 'thinking') continue;
+    if (b.kind === 'tool_call' && NOISE_TOOLS.has(b.name)) continue;
+    if (b.kind === 'tool_result' && NOISE_TOOLS.has(b.name)) continue;
+    if (b.kind === 'user') {
+      if (isNoiseUserBlock(b.text)) continue;
+      const cleaned = cleanUserText(b.text);
+      if (!cleaned) continue;
+      out.push({ kind: 'user', text: cleaned });
+      continue;
+    }
+    out.push(b);
+  }
+  return out;
+};

package/src/compaction/format.ts

@@ -0,0 +1,89 @@
+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;
+  const crumbLine = `...(${omitted} earlier lines omitted)`;
+  return `${crumbLine}\n\n${clean.join('\n')}`;
+};
+
+/** 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),
+  ].filter(Boolean);
+
+  const volatileSections = [
+    section('Type Catalog', data.typeCatalog),
+    section('Outstanding Context', data.outstandingContext),
+    section('Earlier Turns', data.turnSummaries),
+  ].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'));
+
+  return result;
+};

package/src/compaction/index.ts

@@ -0,0 +1,38 @@
+import type { Message } from '@earendil-works/pi-ai';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { SectionData } from './sections';
+import { normalize } from './normalize';
+import { filterNoise } from './filter-noise';
+import { buildSections } from './build-sections';
+import { formatSummary } from './format';
+
+/**
+ * Extract Message[] from the active branch entries.
+ */
+export function extractMessages(ctx: ExtensionContext): Message[] {
+  const entries = ctx.sessionManager.getBranch();
+  const messages: Message[] = [];
+  for (const entry of entries) {
+    if (entry.type === 'message' && (entry as any).message) {
+      messages.push((entry as any).message);
+    }
+  }
+  return messages;
+}
+
+/**
+ * Build a structured compaction summary from branch messages.
+ * One-shot, no merge, no state — fresh each time.
+ */
+export function buildCompactionSummary(messages: Message[]): SectionData {
+  const blocks = filterNoise(normalize(messages));
+  return buildSections({ blocks });
+}
+
+/**
+ * Format SectionData as text for the supervisor prompt.
+ * Uses cache-friendly section ordering (stable first, volatile last).
+ */
+export function formatForSupervisor(data: SectionData): string {
+  return formatSummary(data);
+}