pi-blackhole 0.2.0

package/src/core/settings.ts

@@ -0,0 +1,34 @@
+/**
+ * Pi-vcc settings — reads from unified pi-blackhole/pi-blackhole-config.json.
+ *
+ * Upstream: https://github.com/sting8k/pi-vcc (src/core/settings.ts)
+ * Modified by pi-vcc-om: loadSettings wraps loadUnifiedConfig.
+ */
+import { loadUnifiedConfig, scaffoldConfig } from "./unified-config.js";
+
+export interface PiVccSettings {
+	/** When true, pi-vcc handles all compactions. */
+	overrideDefaultCompaction: boolean;
+	/** Write debug snapshots to /tmp/pi-blackhole-debug.json. */
+	debug: boolean;
+}
+
+export const DEFAULT_SETTINGS: PiVccSettings = {
+	overrideDefaultCompaction: false,
+	debug: false,
+};
+
+export function loadSettings(): PiVccSettings {
+	const config = loadUnifiedConfig(process.cwd());
+	return {
+		overrideDefaultCompaction: config.overrideDefaultCompaction,
+		debug: config.debug,
+	};
+}
+
+export function scaffoldSettings(): void {
+	scaffoldConfig();
+}
+
+// For compatibility with code that imports saveSettings
+export { loadUnifiedConfig as loadConfig } from "./unified-config.js";

package/src/core/skill-collapse.ts

@@ -0,0 +1,35 @@
+/** Shared skill-tag collapse utilities */
+
+const SKILL_TAG_RE = /^-?\s*<skill\s+name="([^"]+)"/;
+const SKILL_CLOSE_RE = /^-?\s*<\/skill>/;
+
+/** Collapse skill tags in an array of lines — dedup by name, drop all content inside block */
+export const collapseSkillLines = (lines: string[]): string[] => {
+  const result: string[] = [];
+  const seenSkills = new Set<string>();
+  let insideSkill = false;
+
+  for (const line of lines) {
+    const skillMatch = line.match(SKILL_TAG_RE);
+    if (skillMatch) {
+      insideSkill = true;
+      const name = skillMatch[1];
+      if (!seenSkills.has(name)) {
+        seenSkills.add(name);
+        result.push(`[skill: ${name}]`);
+      }
+      continue;
+    }
+    if (insideSkill) {
+      if (SKILL_CLOSE_RE.test(line)) insideSkill = false;
+      continue;
+    }
+    result.push(line);
+  }
+  return result;
+};
+
+/** Collapse <skill name="X" ...>...</skill> blocks in raw text */
+const SKILL_BLOCK_RE = /<skill\s+name="([^"]+)"[^>]*>[\s\S]*?(?:<\/skill>|$)/g;
+export const collapseSkillText = (text: string): string =>
+  text.replace(SKILL_BLOCK_RE, (_, name) => `[skill: ${name}]`);

package/src/core/summarize.ts

@@ -0,0 +1,213 @@
+/**
+ * Pi-vcc compile entry — orchestrates normalization → noise filtering → section building.
+ *
+ * Upstream: https://github.com/sting8k/pi-vcc (src/core/summarize.ts)
+ * Unmodified.
+ */
+import type { Message } from "@earendil-works/pi-ai";
+import type { FileOps } from "../types";
+import { normalize } from "./normalize";
+import { filterNoise } from "./filter-noise";
+import { buildSections } from "./build-sections";
+import { formatSummary, capBrief, RECALL_NOTE, wrapLongLines } from "./format";
+
+export interface CompileInput {
+  messages: Message[];
+  previousSummary?: string;
+  fileOps?: FileOps;
+}
+
+const HEADER_NAMES = ["Session Goal", "Files And Changes", "Commits", "Outstanding Context", "User Preferences"];
+
+const SEPARATOR = "\n\n---\n\n";
+
+/** Extract a named section from summary text */
+const sectionOf = (text: string, header: string): string => {
+  const tag = `[${header}]`;
+  const start = text.indexOf(tag);
+  if (start < 0) return "";
+  const after = text.slice(start);
+  // Find next section header or separator
+  const nextSection = HEADER_NAMES
+    .filter((h) => h !== header)
+    .map((h) => after.indexOf(`[${h}]`))
+    .filter((n) => n > 0);
+  const nextSep = after.indexOf("\n\n---\n\n");
+  const candidates = [...nextSection, ...(nextSep > 0 ? [nextSep] : [])].sort((a, b) => a - b);
+  const end = candidates[0];
+  return (end ? after.slice(0, end) : after).trim();
+};
+
+/** Extract the brief transcript part (everything after ---) */
+const briefOf = (text: string): string => {
+  const idx = text.indexOf(SEPARATOR);
+  if (idx < 0) return "";
+  return text.slice(idx + SEPARATOR.length).trim();
+};
+
+/** Merge a header section */
+const mergeHeaderSection = (header: string, prev: string, fresh: string): string => {
+  // Outstanding Context is volatile -- always use fresh only
+  if (header === "Outstanding Context") return fresh;
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+
+  // Files And Changes: merge by category (Modified/Created/Read), dedup paths
+  if (header === "Files And Changes") {
+    return mergeFileLines(prev, fresh);
+  }
+
+  // Session Goal, User Preferences: line-level dedup, cap
+  const isClean = (l: string) => l.startsWith("- ") && !l.includes("<skill") && !l.includes("</skill");
+  const prevLines = prev.split("\n").filter(isClean);
+  const freshLines = fresh.split("\n").filter(isClean);
+  const combined = [...new Set([...prevLines, ...freshLines])];
+  const CAP = header === "Session Goal" ? 8 : header === "Commits" ? 8 : 15;
+  const capped = combined.length > CAP ? combined.slice(-CAP) : combined;
+  if (capped.length === 0) return "";
+  return `[${header}]\n${capped.join("\n")}`;
+};
+
+/** Merge Files And Changes by category, dedup paths across compactions */
+const mergeFileLines = (prev: string, fresh: string): string => {
+  const categories = ["Modified", "Created", "Read"] as const;
+  const merged: Record<string, Set<string>> = {};
+  for (const cat of categories) merged[cat] = new Set();
+
+  // Parse "- Modified: a, b, c (+N more)" lines from both prev and fresh
+  for (const text of [prev, fresh]) {
+    for (const line of text.split("\n")) {
+      for (const cat of categories) {
+        const prefix = `- ${cat}: `;
+        if (!line.startsWith(prefix)) continue;
+        let rest = line.slice(prefix.length);
+        // Strip "(+N more)" suffix
+        rest = rest.replace(/\s*\(\+\d+ more\)\s*$/, "");
+        for (const p of rest.split(",")) {
+          const trimmed = p.trim();
+          if (trimmed) merged[cat].add(trimmed);
+        }
+      }
+    }
+  }
+
+  // Dedup: if already in Modified, drop from Created (file existed before)
+  for (const p of merged.Modified) merged.Created.delete(p);
+
+  const cap = (set: Set<string>, limit: number) => {
+    const arr = [...set];
+    if (arr.length <= limit) return arr.join(", ");
+    return arr.slice(0, limit).join(", ") + ` (+${arr.length - limit} more)`;
+  };
+
+  const lines: string[] = [];
+  if (merged.Modified.size > 0) lines.push(`- Modified: ${cap(merged.Modified, 10)}`);
+  if (merged.Created.size > 0) lines.push(`- Created: ${cap(merged.Created, 10)}`);
+  if (merged.Read.size > 0) lines.push(`- Read: ${cap(merged.Read, 10)}`);
+  if (lines.length === 0) return "";
+  return `[Files And Changes]\n${lines.join("\n")}`;
+};
+
+const mergeBriefTranscript = (prev: string, fresh: string): string => {
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+  return prev + "\n\n" + fresh;
+};
+
+const mergePrevious = (prev: string, fresh: string): string => {
+  // Merge header sections
+  const headers = HEADER_NAMES
+    .map((header) => {
+      const freshSec = sectionOf(fresh, header);
+      const prevSec = sectionOf(prev, header);
+      return mergeHeaderSection(header, prevSec, freshSec);
+    })
+    .filter(Boolean);
+
+  // Merge brief transcript
+  const prevBrief = briefOf(prev);
+  const freshBrief = briefOf(fresh);
+  const mergedBrief = mergeBriefTranscript(prevBrief, freshBrief);
+
+  const parts: string[] = [];
+  if (headers.length > 0) {
+    parts.push(headers.join("\n\n"));
+  }
+  if (mergedBrief) {
+    parts.push(capBrief(mergedBrief));
+  }
+
+  return parts.join(SEPARATOR);
+};
+
+export const compile = (input: CompileInput): string => {
+  const blocks = filterNoise(normalize(input.messages));
+  const data = buildSections({ blocks });
+  const fresh = formatSummary(data);
+  // Strip any legacy RECALL_NOTE baked into prev summary (pre-fix format)
+  // so merge doesn't re-stack it inside the brief.
+  // Also strip OM content (## Reflections / ## Observations) from previous
+  // compactions — these are re-rendered fresh by the before-compact hook.
+  let prev = input.previousSummary
+    ? stripRecallNote(input.previousSummary)
+    : undefined;
+  prev = prev ? stripOMContent(prev) : undefined;
+  const merged = prev ? mergePrevious(prev, fresh) : fresh;
+  if (!merged) return "";
+  return wrapLongLines(merged);
+  // RECALL_NOTE is now part of OM_FOOTER in render-summary.ts, appended
+  // by the before-compact hook after observations/reflections.
+};
+
+const stripRecallNote = (text: string): string => {
+  // Remove trailing RECALL_NOTE (and any separators surrounding it) if present.
+  // Handles both current format (---\n\nNOTE) and bare trailing NOTE.
+  const idx = text.lastIndexOf(RECALL_NOTE);
+  if (idx < 0) return text;
+  return text.slice(0, idx).replace(/\s*(?:\n\n---\n\n)?\s*$/, "").trimEnd();
+};
+
+/**
+ * Strip OM content (## Reflections, ## Observations, and the
+ * CONTEXT_USAGE_INSTRUCTIONS preamble) from a previous compaction summary.
+ *
+ * OM content is appended after compile() by the before-compact hook, so it
+ * must be stripped from the previous summary to prevent compounding across
+ * compactions. The fresh OM projection is re-rendered each time.
+ */
+const stripOMContent = (text: string): string => {
+  // Remove everything from "## Reflections" or "## Observations" onward,
+  // plus the instructions preamble that precedes them.
+  // The preamble starts with "These are condensed memories from earlier in this session."
+  const reflIdx = text.indexOf("## Reflections");
+  const obsIdx = text.indexOf("## Observations");
+
+  // Find the start of OM content: either the instructions preamble or the first section header
+  let stripFrom = -1;
+  if (reflIdx >= 0 || obsIdx >= 0) {
+    const preambleIdx = text.indexOf("These are condensed memories from earlier in this session.");
+    const minSectionIdx = Math.min(
+      reflIdx >= 0 ? reflIdx : Infinity,
+      obsIdx >= 0 ? obsIdx : Infinity,
+    );
+    // Old format: preamble before sections -> strip from preamble.
+    // New format: preamble after sections -> strip from first section header.
+    if (preambleIdx >= 0 && preambleIdx < minSectionIdx) {
+      stripFrom = preambleIdx;
+    } else if (minSectionIdx < Infinity) {
+      stripFrom = minSectionIdx;
+    }
+  }
+
+  if (stripFrom < 0) return text;
+
+  // Also strip any trailing separators before the OM content
+  let end = stripFrom;
+  while (end > 0 && /\s/.test(text[end - 1])) end--;
+  // Strip trailing "---" separator if present
+  const beforeEnd = text.slice(0, end).trimEnd();
+  if (beforeEnd.endsWith("---")) {
+    return beforeEnd.slice(0, beforeEnd.length - 3).trimEnd();
+  }
+  return beforeEnd;
+};

package/src/core/tool-args.ts

@@ -0,0 +1,14 @@
+export const extractPath = (args: Record<string, unknown>): string | null => {
+  for (const key of ["path", "file_path", "filePath", "file"]) {
+    if (typeof args[key] === "string") return args[key] as string;
+  }
+  return null;
+};
+
+export const summarizeToolArgs = (args: Record<string, unknown>): string => {
+  const path = extractPath(args);
+  if (path) return `path=${path}`;
+  if (typeof args.command === "string") return `command=${args.command}`;
+  if (typeof args.query === "string") return `query=${args.query}`;
+  return Object.keys(args).join(", ");
+};

package/src/core/unified-config.ts

@@ -0,0 +1,285 @@
+/**
+ * Unified configuration loader — merges pi-vcc + OM settings into one file.
+ *
+ * Created by pi-vcc-om.
+ * Reads ~/.pi/agent/pi-blackhole/pi-blackhole-config.json with legacy fallback support.
+ * Model configs support cooldownHours and fallbackModel arrays.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+
+// ── Config path ──────────────────────────────────────────────────────────────
+
+const CONFIG_DIR = "pi-blackhole";
+const CONFIG_FILE = "pi-blackhole-config.json";
+
+function configPath(): string {
+	return join(getAgentDir(), CONFIG_DIR, CONFIG_FILE);
+}
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface OmModelConfig {
+	provider: string;
+	id: string;
+	thinking?: ModelThinkingLevel;
+	/** Cooldown duration in hours after a retryable error (429/5xx/timeout).
+	 *  Defaults to 1 hour when omitted. */
+	cooldownHours?: number;
+}
+
+export interface UnifiedConfig {
+	/** When true, pi-vcc handles all compactions (not just /pi-vcc). */
+	overrideDefaultCompaction: boolean;
+	/** Write debug snapshots to /tmp/pi-blackhole-debug.json. */
+	debug: boolean;
+
+	/** Token threshold for observer runs. */
+	observeAfterTokens: number;
+	/** Token threshold for reflector and dropper. */
+	reflectAfterTokens: number;
+	/** Token threshold for proactive auto-compaction. */
+	compactAfterTokens: number;
+	/** Observation pool token pressure for full fold. */
+	observationsPoolMaxTokens: number;
+	/** Max prompt tokens for reflector model input (rolling window cap). */
+	reflectorInputMaxTokens: number;
+	/** Max prompt tokens for dropper model input (rolling window cap). */
+	dropperInputMaxTokens: number;
+	/** Max source entries tokens sent to observer per chunk. */
+	observerChunkMaxTokens: number;
+	/** Shared turn cap for background memory agents. */
+	agentMaxTurns: number;
+
+	/** Base model override for all memory workers. */
+	model?: OmModelConfig;
+	/** Model override for observer (most frequent worker). */
+	observerModel?: OmModelConfig;
+	/** Model override for reflector (synthesizes durable facts). */
+	reflectorModel?: OmModelConfig;
+	/** Model override for dropper (prunes observations). */
+	dropperModel?: OmModelConfig;
+
+	/** Fallback models for observer, tried in order after primary model fails. */
+	observerFallbackModels?: OmModelConfig[];
+	/** Fallback models for reflector, tried in order after primary model fails. */
+	reflectorFallbackModels?: OmModelConfig[];
+	/** Fallback models for dropper, tried in order after primary model fails. */
+	dropperFallbackModels?: OmModelConfig[];
+
+	/** When true, observations/reflections are saved to pending.json
+	 *  instead of appended to the conversation. Auto-compaction is
+	 *  disabled.  User triggers /blackhole to flush and compact. */
+	noAutoCompact: boolean;
+	/** Disables background workers and auto-compaction entirely. */
+	passive: boolean;
+	/** Enables observational memory (workers + content injection). Set to false for pi-vcc only. */
+	memory: boolean;
+	/** Writes debug JSONL to agent directory. */
+	debugLog: boolean;
+}
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+export const DEFAULTS: UnifiedConfig = {
+	overrideDefaultCompaction: false,
+	debug: false,
+
+	observeAfterTokens: 10_000,
+	reflectAfterTokens: 20_000,
+	compactAfterTokens: 81_000,
+	observationsPoolMaxTokens: 20_000,
+	reflectorInputMaxTokens: 80_000,
+	dropperInputMaxTokens: 80_000,
+	observerChunkMaxTokens: 40_000,
+	agentMaxTurns: 16,
+
+	noAutoCompact: false,
+	passive: false,
+	memory: true,
+	debugLog: false,
+};
+
+// ── Parsing helpers ──────────────────────────────────────────────────────────
+
+const THINKING_LEVELS: readonly string[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null;
+}
+
+function nonEmptyString(v: unknown): string | undefined {
+	return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function isThinkingLevel(v: unknown): v is ModelThinkingLevel {
+	return typeof v === "string" && THINKING_LEVELS.includes(v);
+}
+
+function positiveInt(v: unknown): number | undefined {
+	return Number.isInteger(v) && typeof v === "number" && v > 0 ? v : undefined;
+}
+
+function parseModel(v: unknown): OmModelConfig | undefined {
+	if (!isRecord(v)) return undefined;
+	const provider = nonEmptyString(v.provider);
+	const id = nonEmptyString(v.id);
+	if (!provider || !id) return undefined;
+	const model: OmModelConfig = { provider, id };
+	if (isThinkingLevel(v.thinking)) model.thinking = v.thinking;
+	const cooldown = positiveInt(v.cooldownHours);
+	if (cooldown !== undefined) model.cooldownHours = cooldown;
+	return model;
+}
+
+function parseModelArray(v: unknown): OmModelConfig[] | undefined {
+	if (!Array.isArray(v)) return undefined;
+	const parsed = v.map(parseModel).filter((m): m is OmModelConfig => m !== undefined);
+	return parsed.length > 0 ? parsed : undefined;
+}
+
+function parseConfig(raw: Record<string, unknown>): Partial<UnifiedConfig> {
+	const c: Partial<UnifiedConfig> = {};
+
+	// Booleans — pi-vcc
+	if (typeof raw.overrideDefaultCompaction === "boolean") c.overrideDefaultCompaction = raw.overrideDefaultCompaction;
+	if (typeof raw.debug === "boolean") c.debug = raw.debug;
+
+	// Booleans — om
+	if (typeof raw.noAutoCompact === "boolean") c.noAutoCompact = raw.noAutoCompact;
+	if (typeof raw.passive === "boolean") c.passive = raw.passive;
+	if (typeof raw.memory === "boolean") c.memory = raw.memory;
+	if (typeof raw.debugLog === "boolean") c.debugLog = raw.debugLog;
+
+	// Positive integers
+	const numKeys = ["observeAfterTokens", "reflectAfterTokens", "compactAfterTokens", "observationsPoolMaxTokens", "reflectorInputMaxTokens", "dropperInputMaxTokens", "observerChunkMaxTokens", "agentMaxTurns"] as const;
+	for (const k of numKeys) {
+		const v = positiveInt(raw[k]);
+		if (v !== undefined) (c as Record<string, unknown>)[k] = v;
+	}
+
+	// Models
+	const model = parseModel(raw.model);
+	if (model) c.model = model;
+	const obsModel = parseModel(raw.observerModel);
+	if (obsModel) c.observerModel = obsModel;
+	const refModel = parseModel(raw.reflectorModel);
+	if (refModel) c.reflectorModel = refModel;
+	const dropModel = parseModel(raw.dropperModel);
+	if (dropModel) c.dropperModel = dropModel;
+
+	// Fallback model arrays
+	const obsFallback = parseModelArray(raw.observerFallbackModels);
+	if (obsFallback) c.observerFallbackModels = obsFallback;
+	const refFallback = parseModelArray(raw.reflectorFallbackModels);
+	if (refFallback) c.reflectorFallbackModels = refFallback;
+	const dropFallback = parseModelArray(raw.dropperFallbackModels);
+	if (dropFallback) c.dropperFallbackModels = dropFallback;
+
+	return c;
+}
+
+// ── Load and save ────────────────────────────────────────────────────────────
+
+function readJson(path: string): Record<string, unknown> | null {
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Load unified configuration from ~/.pi/agent/pi-blackhole/pi-blackhole-config.json.
+ * Falls back to legacy sources if the unified file doesn't exist.
+ */
+export function loadUnifiedConfig(cwd: string): UnifiedConfig {
+	const path = configPath();
+	let raw = readJson(path);
+
+	// Fallback to legacy sources if unified file doesn't exist
+	if (!raw) {
+		// Try legacy pi-vcc config
+		const piVccPath = join(getAgentDir(), "pi-vcc-config.json");
+		const piVccRaw = readJson(piVccPath);
+
+		// Try legacy om config from settings.json
+		const settingsPath = join(getAgentDir(), "settings.json");
+		const settingsRaw = readJson(settingsPath);
+		const omRaw = settingsRaw?.["pi-blackhole"] ?? settingsRaw?.["observational-memory"];
+		const projectSettingsPath = join(cwd, ".pi", "settings.json");
+		const projectRaw = readJson(projectSettingsPath);
+		const projectOmRaw = projectRaw?.["pi-blackhole"] ?? projectRaw?.["observational-memory"];
+
+		// Merge legacy sources
+		const merged: Record<string, unknown> = {};
+		if (piVccRaw && isRecord(piVccRaw)) Object.assign(merged, piVccRaw);
+		if (omRaw && isRecord(omRaw)) Object.assign(merged, omRaw);
+		if (projectOmRaw && isRecord(projectOmRaw)) Object.assign(merged, projectOmRaw);
+		raw = merged;
+	}
+
+	const parsed = parseConfig(raw);
+
+	// Env override
+	const envPassive = process.env.PI_BLACKHOLE_PASSIVE ?? process.env.PI_VCC_OM_PASSIVE ?? process.env.PI_OBSERVATIONAL_MEMORY_PASSIVE;
+	if (envPassive !== undefined) {
+		const v = envPassive.trim().toLowerCase();
+		if (["1", "true", "yes", "on"].includes(v)) parsed.passive = true;
+		else if (["0", "false", "no", "off"].includes(v)) parsed.passive = false;
+	}
+
+	return { ...DEFAULTS, ...parsed };
+}
+
+/**
+ * Write settings back to disk. Preserves unknown keys.
+ */
+export function saveUnifiedConfig(settings: Partial<UnifiedConfig>): boolean {
+	try {
+		const path = configPath();
+		const dir = dirname(path);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		const existing = readJson(path) ?? {};
+		const next = { ...existing, ...settings };
+		writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Ensure ~/.pi/agent/pi-blackhole/pi-blackhole-config.json exists with defaults.
+ * If the file exists but is missing keys, fill them in.
+ */
+export function scaffoldConfig(): void {
+	try {
+		const path = configPath();
+		const dir = dirname(path);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+		if (!existsSync(path)) {
+			writeFileSync(path, `${JSON.stringify(DEFAULTS, null, 2)}\n`);
+			return;
+		}
+
+		const parsed = readJson(path);
+		if (!parsed || typeof parsed !== "object") return;
+
+		let changed = false;
+		const next: Record<string, unknown> = { ...parsed };
+		for (const [key, value] of Object.entries(DEFAULTS)) {
+			if (!(key in next)) {
+				next[key] = value;
+				changed = true;
+			}
+		}
+		if (changed) writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+	} catch {
+		// best-effort
+	}
+}

package/src/details.ts

@@ -0,0 +1,13 @@
+/**
+ * Pi-vcc compaction details type.
+ *
+ * Upstream: https://github.com/sting8k/pi-vcc (src/details.ts)
+ * Unmodified.
+ */
+export interface PiVccCompactionDetails {
+  compactor: "blackhole";
+  version: number;
+  sections: string[];
+  sourceMessageCount: number;
+  previousSummaryUsed: boolean;
+}

package/src/extract/commits.ts

@@ -0,0 +1,69 @@
+import type { NormalizedBlock } from "../types";
+
+interface CommitInfo {
+  hash?: string;
+  message: string;
+}
+
+const COMMIT_MSG_RE = /git\s+commit[^\n]*?-m\s+(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|\$?'((?:[^'\\]|\\.)*)')/;
+// Match short hash from git output: "[branch hash]" or "main hash" or 7-12 hex
+const HASH_RE = /\b([0-9a-f]{7,12})\b/;
+
+const firstLineOf = (text: string): string => {
+  const line = text.split(/\\n|\n/)[0] ?? "";
+  return line.trim();
+};
+
+const cleanMessage = (msg: string): string =>
+  msg.replace(/\\"/g, '"').replace(/\\'/g, "'").trim();
+
+/**
+ * Extract git commits from bash tool calls (`git commit -m "..."`) and pair
+ * with hash from the immediately following tool_result.
+ */
+export const extractCommits = (blocks: NormalizedBlock[]): CommitInfo[] => {
+  const commits: CommitInfo[] = [];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b.kind !== "tool_call" || b.name !== "bash") continue;
+    const cmd = typeof b.args.command === "string" ? b.args.command : "";
+    if (!/\bgit\s+commit\b/.test(cmd)) continue;
+    const m = cmd.match(COMMIT_MSG_RE);
+    if (!m) continue;
+    const message = firstLineOf(cleanMessage(m[1] ?? m[2] ?? m[3] ?? ""));
+    if (!message) continue;
+
+    let hash: string | undefined;
+    // Look at next tool_result for hash
+    for (let j = i + 1; j < Math.min(blocks.length, i + 3); j++) {
+      const r = blocks[j];
+      if (r.kind !== "tool_result") continue;
+      // Common git commit output: `[branch <hash>] message` or `<branch> <hash>..<hash>`
+      const bracket = r.text.match(/\[\S+\s+([0-9a-f]{7,12})\]/);
+      if (bracket) { hash = bracket[1]; break; }
+      const range = r.text.match(/\b([0-9a-f]{7,12})\.\.([0-9a-f]{7,12})\b/);
+      if (range) { hash = range[2]; break; }
+      const plain = r.text.match(HASH_RE);
+      if (plain) { hash = plain[1]; break; }
+    }
+
+    // Dedup by message+hash
+    const key = `${hash ?? ""}::${message}`;
+    if (!commits.some((c) => `${c.hash ?? ""}::${c.message}` === key)) {
+      commits.push({ hash, message });
+    }
+  }
+
+  return commits;
+};
+
+export const formatCommits = (commits: CommitInfo[], limit = 8): string[] => {
+  const lines: string[] = [];
+  const items = commits.slice(-limit); // keep most recent
+  for (const c of items) {
+    const prefix = c.hash ? `${c.hash}: ` : "";
+    lines.push(`${prefix}${c.message}`);
+  }
+  return lines;
+};