pi-blackhole 0.3.3 → 0.3.5

package/src/om/retryable-error.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared retryable-error regex and detection function.
+ *
+ * Extracted from compaction-trigger.ts and cooldown.ts which had diverging
+ * copies of the same logic. This is the single source of truth.
+ *
+ * Now also re-exports Pi's context-overflow detection from @earendil-works/pi-ai,
+ * avoiding the need to duplicate 20+ provider-specific overflow patterns.
+ */
+
+/** Regex matching retryable API error messages. */
+export const RETRYABLE_ERROR_RE =
+  /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i;
+
+/** Check whether an error string or Error indicates a retryable error. */
+export function isRetryableError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error || "");
+  return RETRYABLE_ERROR_RE.test(message);
+}
+
+/**
+ * Re-export Pi's context-overflow detection so blackhole callers use one
+ * authoritative source instead of maintaining their own provider-specific patterns.
+ * @see @earendil-works/pi-ai/dist/utils/overflow.d.ts
+ */
+export { isContextOverflow } from "@earendil-works/pi-ai";

package/src/om/reverse-recall.ts

@@ -82,7 +82,7 @@ export function findReflectionsForEntryIds(
 
 export function formatRelatedObservations(
 	observations: RelatedObservation[],
-	_reflections: RelatedReflection[],
+	reflections: RelatedReflection[],
 ): string {
 	const parts: string[] = [];
 
@@ -97,6 +97,14 @@ export function formatRelatedObservations(
 		}
 	}
 
+	if (reflections.length > 0) {
+		if (parts.length > 0) parts.push("");
+		parts.push("Related reflections:");
+		for (const ref of reflections) {
+			parts.push(`  [${ref.memoryId}] ${ref.content}`);
+		}
+	}
+
 	return parts.join("\n");
 }
 

package/src/om/runtime.ts

@@ -10,7 +10,7 @@
  * - markConsolidationError sets 30s retry gate for failed runs.
  */
 import { type Config, type ConfiguredModel, DEFAULTS, loadConfig } from "./config.js";
-import { isCooldownActive, recordCooldown, expireCooldowns, modelKey } from "./cooldown.js";
+import { isCooldownActive, getCooldownEntry, recordCooldown, expireCooldowns, modelKey } from "./cooldown.js";
 
 export type ResolveResult =
 	| { ok: true; model: any; apiKey: string; headers?: Record<string, string>; cooldownApplied?: boolean }
@@ -45,6 +45,13 @@ export class Runtime {
 	consolidationInFlight = false;
 	consolidationPromise: Promise<void> | null = null;
 	consolidationPhase: ConsolidationPhase | undefined;
+	/**
+	 * Models that failed in the current consolidation stage (in-memory only).
+	 * Used when cooldownHours is 0 — avoids disk writes while still letting
+	 * the retry loop advance past the failed model within this stage.
+	 * Cleared between stages at the pipeline level.
+	 */
+	failedInCycle: Set<string> = new Set();
 	compactInFlight = false;
 	compactHookInFlight = false;
 	resolveFailureNotified = false;
@@ -87,13 +94,17 @@ export class Runtime {
 	 * Tries the candidate list in order:
 	 * 1. Primary stage model → 2. Stage fallbacks → 3. Base config.model → 4. Session model.
 	 *
+	 * Session model fallback can be disabled via config.sessionFallback: false.
+	 * When disabled, returns { ok: false } instead of using the session model,
+	 * allowing the stage to be skipped entirely when all configured OM models fail.
+	 *
 	 * Skips models that are currently in a cooldown window.
 	 * On retryable error (after the agent runs), the model that failed is cooled down
 	 * and the next candidate is tried.  The caller must call `recordRetryableError`
 	 * after the API attempt to mark the failed model.
 	 *
 	 * Returns `ok: true` with the resolved model, or `ok: false` with a reason
-	 * if all candidates (including session model) are exhausted or unavailable.
+	 * if all candidates (including session model, if enabled) are exhausted or unavailable.
 	 */
 	async resolveModel(ctx: ResolveCtx): Promise<ResolveResult> {
 		const candidates = this.buildCandidateList(ctx.stageModel, ctx.stageFallbacks);
@@ -101,10 +112,25 @@ export class Runtime {
 
 		// Try configured candidates
 		for (const candidate of candidates) {
+			const key = modelKey(candidate);
+
+			// In-memory skip: model failed earlier in this stage with cooldownHours 0
+			if (this.failedInCycle.has(key)) {
+				if (ctx.hasUI && ctx.ui) {
+					ctx.ui.notify(
+						`Observational memory: ${stageName} skipping ${key} (failed this cycle, cooldown disabled)`,
+						"info",
+					);
+				}
+				continue;
+			}
+
 			if (isCooldownActive(candidate)) {
 				if (ctx.hasUI && ctx.ui) {
+					const entry = getCooldownEntry(candidate);
+					const reason = entry ? `: ${entry.reason}` : "";
 					ctx.ui.notify(
-						`Observational memory: ${stageName} skipping ${modelKey(candidate)} (cooldown active)`,
+						`Observational memory: ${stageName} skipping ${key} (cooldown${reason})`,
 						"info",
 					);
 				}
@@ -142,25 +168,40 @@ export class Runtime {
 			};
 		}
 
-		// Fall back to session model
-		const sessionModel = ctx.model;
-		if (!sessionModel) {
-			return { ok: false, reason: `no model available for ${stageName} (all candidates exhausted, no session model)` };
+		// Fall back to session model (if enabled)
+		if (this.config.sessionFallback !== false) {
+			const sessionModel = ctx.model;
+			if (!sessionModel) {
+				return { ok: false, reason: `no model available for ${stageName} (all candidates exhausted, no session model)` };
+			}
+
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(sessionModel);
+			if (!auth.ok || !auth.apiKey) {
+				const provider = (sessionModel as { provider?: string }).provider ?? "unknown";
+				return { ok: false, reason: `no API key for session model provider "${provider}"` };
+			}
+
+			return {
+				ok: true,
+				model: sessionModel,
+				apiKey: auth.apiKey as string,
+				headers: auth.headers as Record<string, string> | undefined,
+				cooldownApplied: false,
+			};
 		}
 
-		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(sessionModel);
-		if (!auth.ok || !auth.apiKey) {
-			const provider = (sessionModel as { provider?: string }).provider ?? "unknown";
-			return { ok: false, reason: `no API key for session model provider "${provider}"` };
+		// All configured candidates exhausted and session fallback disabled —
+		// skip the stage entirely.  Info-level to match cooldown-disabled pattern.
+		// Set resolveFailureNotified so the consolidation layer doesn't duplicate.
+		if (ctx.hasUI && ctx.ui) {
+			ctx.ui.notify(
+				`Observational memory: ${stageName} skipped — all candidates failed (sessionFallback disabled, won't use main model)`,
+				"info",
+			);
 		}
+		this.resolveFailureNotified = true;
 
-		return {
-			ok: true,
-			model: sessionModel,
-			apiKey: auth.apiKey as string,
-			headers: auth.headers as Record<string, string> | undefined,
-			cooldownApplied: false,
-		};
+		return { ok: false, reason: `no model available for ${stageName} (all candidates exhausted, sessionFallback disabled)` };
 	}
 
 	/**
@@ -179,9 +220,19 @@ export class Runtime {
 	/**
 	 * Record a retryable error for a model.  The model must be one of the candidates
 	 * (not the session model).  If it's the session model we don't cool it down.
+	 *
+	 * When cooldownHours is explicitly 0, the model is tracked in-memory for the
+	 * current consolidation stage (no disk writes). Otherwise a persisted cooldown
+	 * is recorded.
 	 */
 	recordRetryableError(modelConfig: ConfiguredModel | undefined, error: unknown, stage: ConsolidationPhase): void {
 		if (!modelConfig) return;
+		if (modelConfig.cooldownHours === 0) {
+			// In-memory only: skip this model for the rest of this stage.
+			// No disk writes, no persistent cooldown.
+			this.failedInCycle.add(modelKey(modelConfig));
+			return;
+		}
 		const reason = error instanceof Error ? error.message : String(error || "unknown error");
 		recordCooldown(modelConfig, reason, stage);
 	}

package/src/om/status-overlay.ts

@@ -7,7 +7,8 @@
  * Esc to close.
  */
 
-import { matchKey, visibleWidth } from "./key-matcher.js";
+import { visibleWidth } from "./key-matcher.js";
+import { matchesKey } from "@earendil-works/pi-tui";
 
 // ---------------------------------------------------------------------------
 // Theme shape (duck-typed from what pi provides)
@@ -117,12 +118,12 @@ export function createStatusOverlay(
 	}
 
 	function handleInput(data: string): void {
-		if (matchKey(data, "escape")) {
+		if (matchesKey(data, "escape")) {
 			done({ action: "close" });
 			return;
 		}
 
-		if (matchKey(data, "enter") || matchKey(data, "space")) {
+		if (matchesKey(data, "enter") || matchesKey(data, "space")) {
 			if (navIsAction(selectedIndex)) {
 				const actionIdx = selectedIndex - selectableConfigCount - selectablePipelineCount - selectableErrorCount;
 				const action = actionItems[actionIdx]!;
@@ -132,12 +133,12 @@ export function createStatusOverlay(
 			return;
 		}
 
-		if (matchKey(data, "up")) {
+		if (matchesKey(data, "up")) {
 			selectedIndex = Math.max(0, selectedIndex - 1);
 			invalidate();
 			return;
 		}
-		if (matchKey(data, "down")) {
+		if (matchesKey(data, "down")) {
 			selectedIndex = Math.min(totalSelectable - 1, selectedIndex + 1);
 			invalidate();
 			return;

package/src/sections.ts

@@ -4,7 +4,6 @@
  * Upstream: https://github.com/sting8k/pi-vcc (src/sections.ts)
  * Unmodified.
  */
-import type { TranscriptEntry } from "./core/brief";
 
 export interface SectionData {
   sessionGoal: string[];
@@ -13,6 +12,4 @@ export interface SectionData {
   commits: string[];
   userPreferences: string[];
   briefTranscript: string;
-  /** Structured transcript entries (verbose object format) */
-  transcriptEntries: TranscriptEntry[];
 }

package/src/tools/recall.ts

@@ -138,7 +138,11 @@ async function vccRecall(params: { query?: string; expand?: number[]; page?: num
 
 	// Merge expanded entries into full result set BEFORE pagination
 	// so pagination counts and positioning stay consistent
+	let appendedExpandCount = 0;
 	if (expandedFullEntries) {
+		// Track expand-only entries that don't match the query so the header can distinguish them
+		const existingIndices = new Set(allResults.map((r) => r.index));
+		appendedExpandCount = expandedFullEntries.filter((fe) => !existingIndices.has(fe.index)).length;
 		allResults = mergeExpandedIntoSearchResults(allResults, expandedFullEntries);
 	}
 
@@ -148,9 +152,10 @@ async function vccRecall(params: { query?: string; expand?: number[]; page?: num
 		const pageResults: SearchHit[] = allResults.slice(start, start + PAGE_SIZE);
 		const totalPages = Math.ceil(allResults.length / PAGE_SIZE);
 		const scopeSuffix = scope === "all" ? " (scope: all)" : "";
+		const matchCount = allResults.length - appendedExpandCount;
 		const header = totalPages > 1
-			? `Page ${page}/${totalPages} (${allResults.length} total matches${scopeSuffix})`
-			: `${allResults.length} matches${scopeSuffix}`;
+			? `Page ${page}/${totalPages} (${matchCount} matches${appendedExpandCount > 0 ? ` + ${appendedExpandCount} expanded` : ""}${scopeSuffix})`
+			: `${matchCount} matches${appendedExpandCount > 0 ? ` (+ ${appendedExpandCount} expanded)` : ""}${scopeSuffix}`;
 		const footer = page < totalPages
 			? `\n--- Use page:${page + 1}${scope === "all" ? " with scope:'all'" : ""} for more results ---`
 			: "";