pi-blackhole 0.4.2 → 0.4.3

package/src/om/cooldown.ts

@@ -8,7 +8,7 @@
 
 /**
  * Cooldown persistence for retryable API errors.
- * 
+ *
  * Created by pi-vcc-om. Records per-model cooldowns to disk so rate-limited
  * or down models are skipped until their cooldown window expires.
  *
@@ -28,46 +28,46 @@ const CONFIG_DIR = "pi-blackhole";
 const COOLDOWN_FILE = "pi-blackhole-cooldown.json";
 
 function cooldownPath(): string {
-	return join(getAgentDir(), CONFIG_DIR, COOLDOWN_FILE);
+  return join(getAgentDir(), CONFIG_DIR, COOLDOWN_FILE);
 }
 
 export interface CooldownEntry {
-	until: string; // ISO 8601 timestamp
-	reason: string;
-	stage: string; // "observer" | "reflector" | "dropper"
+  until: string; // ISO 8601 timestamp
+  reason: string;
+  stage: string; // "observer" | "reflector" | "dropper"
 }
 
 type CooldownMap = Record<string, CooldownEntry>;
 
 /** Provider/id key for cooldown lookup. */
 export function modelKey(model: OmModelConfig): string {
-	return `${model.provider}/${model.id}`;
+  return `${model.provider}/${model.id}`;
 }
 
 // ── Load / save ─────────────────────────────────────────────────────────────
 
 function readCooldownMap(): CooldownMap {
-	const path = cooldownPath();
-	if (!existsSync(path)) return {};
-	try {
-		return JSON.parse(readFileSync(path, "utf-8"));
-	} catch {
-		return {};
-	}
+  const path = cooldownPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
 }
 
 function writeCooldownMap(map: CooldownMap): void {
-	try {
-		const path = cooldownPath();
-		const dir = dirname(path);
-		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-		writeFileSync(path, `${JSON.stringify(map, null, 2)}\n`);
-	} catch {
-		// Best-effort: cooldowns are advisory. Losing them means a rate-limited
-		// model might be retried before its cooldown window expires — slightly
-		// more API traffic, no data loss. This also prevents a process crash
-		// on read-only filesystems.
-	}
+  try {
+    const path = cooldownPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(map, null, 2)}\n`);
+  } catch {
+    // Best-effort: cooldowns are advisory. Losing them means a rate-limited
+    // model might be retried before its cooldown window expires — slightly
+    // more API traffic, no data loss. This also prevents a process crash
+    // on read-only filesystems.
+  }
 }
 
 // ── API ─────────────────────────────────────────────────────────────────────
@@ -78,33 +78,39 @@ function writeCooldownMap(map: CooldownMap): void {
  *
  * When cooldownHours is explicitly 0, cooldown is disabled — always returns false.
  */
-export function isCooldownActive(model: OmModelConfig, now: Date = new Date()): boolean {
-	return getCooldownEntry(model, now) !== undefined;
+export function isCooldownActive(
+  model: OmModelConfig,
+  now: Date = new Date(),
+): boolean {
+  return getCooldownEntry(model, now) !== undefined;
 }
 
 /**
  * Returns the active cooldown entry for a model, or undefined if not cooled down.
  * Expired entries are cleaned up lazily.
  */
-export function getCooldownEntry(model: OmModelConfig, now: Date = new Date()): CooldownEntry | undefined {
-	// cooldownHours === 0 means cooldown disabled
-	if (model.cooldownHours === 0) return undefined;
-
-	const map = readCooldownMap();
-	const key = modelKey(model);
-	const entry = map[key];
-	if (!entry) return undefined;
-
-	const until = new Date(entry.until);
-	if (isNaN(until.getTime())) return undefined;
-
-	if (now >= until) {
-		// Expired — clean up
-		delete map[key];
-		writeCooldownMap(map);
-		return undefined;
-	}
-	return entry;
+export function getCooldownEntry(
+  model: OmModelConfig,
+  now: Date = new Date(),
+): CooldownEntry | undefined {
+  // cooldownHours === 0 means cooldown disabled
+  if (model.cooldownHours === 0) return undefined;
+
+  const map = readCooldownMap();
+  const key = modelKey(model);
+  const entry = map[key];
+  if (!entry) return undefined;
+
+  const until = new Date(entry.until);
+  if (isNaN(until.getTime())) return undefined;
+
+  if (now >= until) {
+    // Expired — clean up
+    delete map[key];
+    writeCooldownMap(map);
+    return undefined;
+  }
+  return entry;
 }
 
 /**
@@ -116,15 +122,19 @@ export function getCooldownEntry(model: OmModelConfig, now: Date = new Date()):
  * @param reason  Human-readable error reason (e.g. "429 Too Many Requests").
  * @param stage   Which pipeline stage failed ("observer" | "reflector" | "dropper").
  */
-export function recordCooldown(model: OmModelConfig, reason: string, stage: string): void {
-	// cooldownHours === 0 means cooldown disabled
-	if (model.cooldownHours === 0) return;
-
-	const hours = model.cooldownHours ?? 1;
-	const until = new Date(Date.now() + hours * 3_600_000).toISOString();
-	const map = readCooldownMap();
-	map[modelKey(model)] = { until, reason, stage };
-	writeCooldownMap(map);
+export function recordCooldown(
+  model: OmModelConfig,
+  reason: string,
+  stage: string,
+): void {
+  // cooldownHours === 0 means cooldown disabled
+  if (model.cooldownHours === 0) return;
+
+  const hours = model.cooldownHours ?? 1;
+  const until = new Date(Date.now() + hours * 3_600_000).toISOString();
+  const map = readCooldownMap();
+  map[modelKey(model)] = { until, reason, stage };
+  writeCooldownMap(map);
 }
 
 /**
@@ -132,17 +142,17 @@ export function recordCooldown(model: OmModelConfig, reason: string, stage: stri
  * Call on session_start or config reload to clean up.
  */
 export function expireCooldowns(): void {
-	const map = readCooldownMap();
-	const now = new Date();
-	let changed = false;
-	for (const [key, entry] of Object.entries(map)) {
-		const until = new Date(entry.until);
-		if (isNaN(until.getTime()) || now >= until) {
-			delete map[key];
-			changed = true;
-		}
-	}
-	if (changed) writeCooldownMap(map);
+  const map = readCooldownMap();
+  const now = new Date();
+  let changed = false;
+  for (const [key, entry] of Object.entries(map)) {
+    const until = new Date(entry.until);
+    if (isNaN(until.getTime()) || now >= until) {
+      delete map[key];
+      changed = true;
+    }
+  }
+  if (changed) writeCooldownMap(map);
 }
 
 import { isRetryableError } from "./retryable-error.js";

package/src/om/debug-log.ts

@@ -8,7 +8,14 @@
  * Modified: path changed from observational-memory/ to pi-blackhole/; async buffered.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  appendFileSync,
+} from "node:fs";
 import { appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
@@ -17,16 +24,19 @@ export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
 export const DEBUG_LOG_RELATIVE_PATH = join("pi-blackhole", "debug.ndjson");
 
 interface DebugLogContext {
-	enabled: boolean;
-	cwd?: string;
-	runId?: string;
+  enabled: boolean;
+  cwd?: string;
+  runId?: string;
 }
 
 const storage = new AsyncLocalStorage<DebugLogContext>();
 
-export function withDebugLogContext<T>(context: DebugLogContext, fn: () => T): T {
-	const parent = storage.getStore();
-	return storage.run({ ...parent, ...context }, fn);
+export function withDebugLogContext<T>(
+  context: DebugLogContext,
+  fn: () => T,
+): T {
+  const parent = storage.getStore();
+  return storage.run({ ...parent, ...context }, fn);
 }
 
 // ── Async buffer ────────────────────────────────────────────────────────────
@@ -39,61 +49,69 @@ let flushing = false;
 let lastWriteMs = 0;
 
 function ensureFlushTimer(): void {
-	if (flushTimer) return;
-	flushTimer = setInterval(() => {
-		// Stop the timer if buffer has been empty for a while
-		if (buffer.length === 0 && lastWriteMs > 0 && Date.now() - lastWriteMs > FLUSH_IDLE_MS) {
-			clearInterval(flushTimer!);
-			flushTimer = null;
-			return;
-		}
-		flushBuffer().catch(() => {});
-	}, BUFFER_FLUSH_MS);
-	// Don't prevent process exit
-	if (flushTimer && typeof flushTimer === "object" && "unref" in flushTimer) {
-		flushTimer.unref();
-	}
+  if (flushTimer) return;
+  flushTimer = setInterval(() => {
+    // Stop the timer if buffer has been empty for a while
+    if (
+      buffer.length === 0 &&
+      lastWriteMs > 0 &&
+      Date.now() - lastWriteMs > FLUSH_IDLE_MS
+    ) {
+      clearInterval(flushTimer!);
+      flushTimer = null;
+      return;
+    }
+    flushBuffer().catch(() => {});
+  }, BUFFER_FLUSH_MS);
+  // Don't prevent process exit
+  if (flushTimer && typeof flushTimer === "object" && "unref" in flushTimer) {
+    flushTimer.unref();
+  }
 }
 
 async function flushBuffer(): Promise<void> {
-	if (flushing) return;
-	if (buffer.length === 0) return;
-	flushing = true;
-	// Drain the buffer atomically so flushDebugLog doesn't split entries
-	const batch = buffer;
-	buffer = [];
-	try {
-		const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
-		mkdirSync(dirname(path), { recursive: true });
-		rotateIfNeeded(path);
-		await appendFile(path, batch.join(""), "utf-8");
-	} catch (error) {
-		console.error("blackhole: debug log write failed", error);
-	} finally {
-		flushing = false;
-	}
+  if (flushing) return;
+  if (buffer.length === 0) return;
+  flushing = true;
+  // Drain the buffer atomically so flushDebugLog doesn't split entries
+  const batch = buffer;
+  buffer = [];
+  try {
+    const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    rotateIfNeeded(path);
+    await appendFile(path, batch.join(""), "utf-8");
+  } catch (error) {
+    console.error("blackhole: debug log write failed", error);
+  } finally {
+    flushing = false;
+  }
 }
 
 // Flush remaining buffer on exit — synchronous to work with process.exit() too
 process.on("exit", () => {
-	flushDebugLog();
+  flushDebugLog();
 });
 
-export function debugLog(event: string, data: Record<string, unknown> = {}, forceEnabled?: boolean): void {
-	const context = storage.getStore();
-	const enabled = forceEnabled ?? context?.enabled ?? false;
-	if (enabled !== true) return;
+export function debugLog(
+  event: string,
+  data: Record<string, unknown> = {},
+  forceEnabled?: boolean,
+): void {
+  const context = storage.getStore();
+  const enabled = forceEnabled ?? context?.enabled ?? false;
+  if (enabled !== true) return;
 
-	const payload = {
-		ts: new Date().toISOString(),
-		event,
-		cwd: context?.cwd,
-		runId: context?.runId,
-		data,
-	};
-	buffer.push(JSON.stringify(payload) + "\n");
-	lastWriteMs = Date.now();
-	ensureFlushTimer();
+  const payload = {
+    ts: new Date().toISOString(),
+    event,
+    cwd: context?.cwd,
+    runId: context?.runId,
+    data,
+  };
+  buffer.push(JSON.stringify(payload) + "\n");
+  lastWriteMs = Date.now();
+  ensureFlushTimer();
 }
 
 /**
@@ -102,23 +120,23 @@ export function debugLog(event: string, data: Record<string, unknown> = {}, forc
  * In production, the background timer handles flushing automatically.
  */
 export function flushDebugLog(): void {
-	if (flushing || buffer.length === 0) return;
-	const batch = buffer;
-	buffer = [];
-	try {
-		const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
-		mkdirSync(dirname(path), { recursive: true });
-		rotateIfNeeded(path);
-		appendFileSync(path, batch.join(""), "utf-8");
-	} catch (error) {
-		console.error("blackhole: debug log flush failed", error);
-	}
+  if (flushing || buffer.length === 0) return;
+  const batch = buffer;
+  buffer = [];
+  try {
+    const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    rotateIfNeeded(path);
+    appendFileSync(path, batch.join(""), "utf-8");
+  } catch (error) {
+    console.error("blackhole: debug log flush failed", error);
+  }
 }
 
 function rotateIfNeeded(path: string): void {
-	if (!existsSync(path)) return;
-	if (statSync(path).size < DEBUG_LOG_MAX_BYTES) return;
-	const backupPath = `${path}.1`;
-	if (existsSync(backupPath)) unlinkSync(backupPath);
-	renameSync(path, backupPath);
+  if (!existsSync(path)) return;
+  if (statSync(path).size < DEBUG_LOG_MAX_BYTES) return;
+  const backupPath = `${path}.1`;
+  if (existsSync(backupPath)) unlinkSync(backupPath);
+  renameSync(path, backupPath);
 }

package/src/om/ids.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
 
 export function hashId(content: string): string {
-	return createHash("sha256").update(content).digest("hex").slice(0, 12);
+  return createHash("sha256").update(content).digest("hex").slice(0, 12);
 }

package/src/om/ledger/fold.ts

@@ -5,46 +5,49 @@
  * Unmodified.
  */
 import {
-	isObservationsDroppedData,
-	isObservationsRecordedData,
-	isReflectionsRecordedData,
-	OM_OBSERVATIONS_DROPPED,
-	OM_OBSERVATIONS_RECORDED,
-	OM_REFLECTIONS_RECORDED,
-	type Entry,
-	type Observation,
-	type Reflection,
+  isObservationsDroppedData,
+  isObservationsRecordedData,
+  isReflectionsRecordedData,
+  OM_OBSERVATIONS_DROPPED,
+  OM_OBSERVATIONS_RECORDED,
+  OM_REFLECTIONS_RECORDED,
+  type Entry,
+  type Observation,
+  type Reflection,
 } from "./types.js";
 import { debugLog } from "../debug-log.js";
 
 export type FoldLedgerOptions = {
-	/** Fold entries from branch root through this entry id, inclusive. Omit to fold through branch tip. */
-	upToEntryId?: string;
+  /** Fold entries from branch root through this entry id, inclusive. Omit to fold through branch tip. */
+  upToEntryId?: string;
 };
 
 export type FoldedLedger = {
-	/** All first-valid observation records encountered through the fold boundary, including dropped observations. */
-	observations: Observation[];
-	/** Observation records not tombstoned by a folded drop entry. */
-	activeObservations: Observation[];
-	/** Tombstoned observation ids, including ids that may not have a corresponding folded observation. */
-	droppedObservationIds: Set<string>;
-	/** All first-valid reflection records encountered through the fold boundary. */
-	reflections: Reflection[];
-	/** All first-valid observation records by id, including dropped observations. */
-	observationsById: Map<string, Observation>;
-	/** All first-valid reflection records by id. */
-	reflectionsById: Map<string, Reflection>;
+  /** All first-valid observation records encountered through the fold boundary, including dropped observations. */
+  observations: Observation[];
+  /** Observation records not tombstoned by a folded drop entry. */
+  activeObservations: Observation[];
+  /** Tombstoned observation ids, including ids that may not have a corresponding folded observation. */
+  droppedObservationIds: Set<string>;
+  /** All first-valid reflection records encountered through the fold boundary. */
+  reflections: Reflection[];
+  /** All first-valid observation records by id, including dropped observations. */
+  observationsById: Map<string, Observation>;
+  /** All first-valid reflection records by id. */
+  reflectionsById: Map<string, Reflection>;
 };
 
-function foldEndIndex(entries: Entry[], upToEntryId: string | undefined): number {
-	if (!upToEntryId) return entries.length - 1;
-	const idx = entries.findIndex((entry) => entry.id === upToEntryId);
-	return idx === -1 ? entries.length - 1 : idx;
+function foldEndIndex(
+  entries: Entry[],
+  upToEntryId: string | undefined,
+): number {
+  if (!upToEntryId) return entries.length - 1;
+  const idx = entries.findIndex((entry) => entry.id === upToEntryId);
+  return idx === -1 ? entries.length - 1 : idx;
 }
 
 function isCustomEntry(entry: Entry, customType: string): boolean {
-	return entry.type === "custom" && entry.customType === customType;
+  return entry.type === "custom" && entry.customType === customType;
 }
 
 /**
@@ -54,61 +57,69 @@ function isCustomEntry(entry: Entry, customType: string): boolean {
  * Observations and reflections use first-valid-record-wins semantics. Drops are tombstones and are
  * retained even when the dropped id is unknown at the time of folding.
  */
-export function foldLedger(entries: Entry[], options: FoldLedgerOptions = {}): FoldedLedger {
-	const observationsById = new Map<string, Observation>();
-	const reflectionsById = new Map<string, Reflection>();
-	const droppedObservationIds = new Set<string>();
-	const endIdx = foldEndIndex(entries, options.upToEntryId);
+export function foldLedger(
+  entries: Entry[],
+  options: FoldLedgerOptions = {},
+): FoldedLedger {
+  const observationsById = new Map<string, Observation>();
+  const reflectionsById = new Map<string, Reflection>();
+  const droppedObservationIds = new Set<string>();
+  const endIdx = foldEndIndex(entries, options.upToEntryId);
 
-	for (let i = 0; i <= endIdx; i++) {
-		const entry = entries[i];
-		if (!entry) continue;
+  for (let i = 0; i <= endIdx; i++) {
+    const entry = entries[i];
+    if (!entry) continue;
 
-		if (isCustomEntry(entry, OM_OBSERVATIONS_RECORDED)) {
-			if (!isObservationsRecordedData(entry.data)) continue;
-			for (const observation of entry.data.observations) {
-				if (!observationsById.has(observation.id)) {
-					observationsById.set(observation.id, observation);
-				}
-			}
-			continue;
-		}
+    if (isCustomEntry(entry, OM_OBSERVATIONS_RECORDED)) {
+      if (!isObservationsRecordedData(entry.data)) continue;
+      for (const observation of entry.data.observations) {
+        if (!observationsById.has(observation.id)) {
+          observationsById.set(observation.id, observation);
+        }
+      }
+      continue;
+    }
 
-		if (isCustomEntry(entry, OM_REFLECTIONS_RECORDED)) {
-			if (!isReflectionsRecordedData(entry.data)) continue;
-			for (const reflection of entry.data.reflections) {
-				if (!reflectionsById.has(reflection.id)) {
-					reflectionsById.set(reflection.id, reflection);
-				}
-			}
-			continue;
-		}
+    if (isCustomEntry(entry, OM_REFLECTIONS_RECORDED)) {
+      if (!isReflectionsRecordedData(entry.data)) continue;
+      for (const reflection of entry.data.reflections) {
+        if (!reflectionsById.has(reflection.id)) {
+          reflectionsById.set(reflection.id, reflection);
+        }
+      }
+      continue;
+    }
 
-		if (isCustomEntry(entry, OM_OBSERVATIONS_DROPPED)) {
-			if (!isObservationsDroppedData(entry.data)) continue;
-			for (const observationId of entry.data.observationIds) {
-				droppedObservationIds.add(observationId);
-			}
-			continue;
-		}
+    if (isCustomEntry(entry, OM_OBSERVATIONS_DROPPED)) {
+      if (!isObservationsDroppedData(entry.data)) continue;
+      for (const observationId of entry.data.observationIds) {
+        droppedObservationIds.add(observationId);
+      }
+      continue;
+    }
 
-		// Log unknown custom entry types — they are silently skipped, but
-		// should be visible when debugging extension compatibility issues.
-		if (entry.type === "custom" && entry.customType) {
-			debugLog("fold.unknown_custom_type", { customType: entry.customType, entryId: entry.id });
-		}
-	}
+    // Log unknown custom entry types — they are silently skipped, but
+    // should be visible when debugging extension compatibility issues.
+    if (entry.type === "custom" && entry.customType) {
+      debugLog("fold.unknown_custom_type", {
+        customType: entry.customType,
+        entryId: entry.id,
+      });
+    }
+  }
 
-	const observations = Array.from(observationsById.values());
-	const activeObservations = observations.filter((observation) => !droppedObservationIds.has(observation.id));
-	const reflections = Array.from(reflectionsById.values());
+  const observations = Array.from(observationsById.values());
+  const activeObservations = observations.filter(
+    (observation) => !droppedObservationIds.has(observation.id),
+  );
+  const reflections = Array.from(reflectionsById.values());
 
-	return {
-		observations,
-		activeObservations,
-		droppedObservationIds,
-		reflections,
-		observationsById,
-		reflectionsById,
-	};
+  return {
+    observations,
+    activeObservations,
+    droppedObservationIds,
+    reflections,
+    observationsById,
+    reflectionsById,
+  };
 }