pi-mega-compact 0.13.6 → 0.14.0

package/extensions/dashboard-server/api-contracts/index.ts

@@ -241,8 +241,8 @@ export type {
 	GraphValidationReport,
 } from "./memory-map.js";
 
-// Part B — RAPTOR tree
-export type { RaptorNodeDTO, RaptorTreeResponse } from "./raptor.js";
+// Part B — RAPTOR tree + build history
+export type { RaptorNodeDTO, RaptorTreeResponse, RaptorBuildHistoryDTO, RaptorBuildHistoryResponse } from "./raptor.js";
 
 // A3 — cache stripe distribution + health
 export type {

package/extensions/dashboard-server/api-contracts/raptor.ts

@@ -47,3 +47,22 @@ export interface RaptorTreeResponse {
 	/** True when there are no RAPTOR nodes for the resolved session. */
 	readonly empty: boolean;
 }
+
+/** A single build-history row (client-safe). */
+export interface RaptorBuildHistoryDTO {
+	readonly buildId: string;
+	readonly sessionId: string;
+	readonly startedAt: number;
+	readonly completedAt: number;
+	readonly nodeCount: number;
+	readonly leafCount: number;
+	readonly depth: number;
+	readonly coherenceScore: number | null;
+	readonly timedOut: boolean;
+}
+
+/** Response body for GET /api/raptor-build-history. */
+export interface RaptorBuildHistoryResponse {
+	readonly builds: RaptorBuildHistoryDTO[];
+	readonly empty: boolean;
+}

package/extensions/dashboard-server/index-reader.ts

@@ -17,6 +17,8 @@ import type { IndexRepo, IndexIndex } from "./types.js";
 import {
 	readProviderCacheForRepo,
 } from "../../src/store/sqlite/perf-samples.js";
+import { lookupModelInputRate } from "../../src/pricing.js";
+import { costApiConfig, lookupCostApiPricing } from "../../src/costApi.js";
 
 export function getIndexDir(): string {
 	const override = process.env.MEGACOMPACT_INDEX_DIR;
@@ -40,7 +42,29 @@ export function readIndex(): IndexIndex | null {
 		const rows = db
 			.prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC")
 			.all() as Record<string, unknown>[];
-		const mapped: IndexRepo[] = rows.map((r) => ({
+		// Lazily fetch cost-API pricing once per readIndex call (cached for 1 hour
+		// inside costApi.ts). Avoids per-row network calls.
+		const costApi = costApiConfig();
+		const mapped: IndexRepo[] = rows.map((r) => {
+			const modelName = String(r.model_name ?? "");
+			const localRate = (r.input_rate as number | null) ||
+				lookupModelInputRate(modelName) ||
+				null;
+			let inputRate = localRate;
+			let outputRate = (r.output_rate as number | null) ?? null;
+			// Fall back to the cost API when the local table has no data.
+			if (costApi.enabled && (inputRate == null || outputRate == null) && modelName) {
+				const apiPricing = lookupCostApiPricing(modelName);
+				if (apiPricing) {
+					if (inputRate == null && apiPricing.inputRate != null) {
+						inputRate = apiPricing.inputRate;
+					}
+					if (outputRate == null && apiPricing.outputRate != null) {
+						outputRate = apiPricing.outputRate;
+					}
+				}
+			}
+			return {
 			repoRoot: String(r.repo_root ?? ""),
 			displayName: String(r.display_name ?? ""),
 			stateDir: String(r.state_dir ?? ""),
@@ -51,8 +75,8 @@ export function readIndex(): IndexIndex | null {
 			provider: (r.provider as string | null) ?? null,
 			providerName: (r.provider_name as string | null) ?? null,
 			modelName: (r.model_name as string | null) ?? null,
-			inputRate: (r.input_rate as number | null) ?? null,
-			outputRate: (r.output_rate as number | null) ?? null,
+			inputRate,
+			outputRate,
 			lastSeen: Number(r.last_seen ?? 0),
 			// Defaults — enriched below from each repo's own store.
 			tokensKept: 0,
@@ -64,7 +88,8 @@ export function readIndex(): IndexIndex | null {
 			providerCachePct: null,
 			providerCacheRead: null,
 			providerCacheWrite: null,
-		}));
+		};
+		});
 		// Enrich each repo with per-store token + model detail read directly via
 		// node:sqlite (same zero-dependency invariant as readIndex; no store graph
 		// import). Best-effort: a missing/corrupt store degrades to the defaults

package/extensions/dashboard-server/resolve-snapshot.ts

@@ -0,0 +1,98 @@
+/**
+ * dashboard-server/resolve-snapshot.ts — dynamic per-repo snapshot resolver.
+ *
+ * The dashboard server is launched with a single static stateDir, but the
+ * active pi session may be running in a different repo. This module queries
+ * the repo registry to find the most recently active repo's dashboard.json,
+ * so the Overview always shows live data from the repo pi is actually running
+ * in — not the stale launcher dir.
+ *
+ * Resolution order:
+ * 1. Most recently seen repo (by last_seen in repo_registry) whose
+ *    dashboard.json exists and has a non-null updatedAt
+ * 2. The static launch stateDir's dashboard.json (original behavior)
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { readSnapshot } from "./snapshot.js";
+import type { Snapshot } from "./types.js";
+import { getIndexDir } from "./index-reader.js";
+
+export interface ResolvedSnapshot {
+	snapshot: Snapshot;
+	/** The stateDir that produced this snapshot. */
+	stateDir: string;
+}
+
+const require = createRequire(import.meta.url);
+
+interface RepoRegistryRow {
+	state_dir: string;
+	last_seen: number;
+}
+
+/**
+ * Find the most recently active repo's stateDir by scanning the repo registry
+ * for repos whose dashboard.json exists and was written recently. Returns null
+ * if no suitable repo is found.
+ */
+function mostRecentRepoStateDir(staticStateDir: string): string | null {
+	const indexPath = join(getIndexDir(), "index.sqlite");
+	if (!existsSync(indexPath)) return null;
+	let db;
+	try {
+		const { DatabaseSync } = require("node:sqlite") as typeof import("node:sqlite");
+		db = new DatabaseSync(indexPath, { readOnly: true });
+		const rows = db
+			.prepare(
+				`SELECT state_dir, last_seen FROM repo_registry
+				 WHERE state_dir IS NOT NULL AND state_dir != ?
+				 ORDER BY last_seen DESC`,
+			)
+			.all(staticStateDir) as unknown as RepoRegistryRow[];
+		for (const r of rows) {
+			const dashPath = join(r.state_dir, "dashboard.json");
+			if (!existsSync(dashPath)) continue;
+			const snap = readSnapshot(dashPath);
+			if (snap.updatedAt) {
+				return r.state_dir;
+			}
+		}
+		return null;
+	} catch {
+		return null;
+	} finally {
+		try {
+			db?.close();
+		} catch {
+			/* ignore */
+		}
+	}
+}
+
+/**
+ * Resolve the best snapshot to serve. Tries the most recently active repo's
+ * dashboard.json first, then falls back to the static launch path.
+ */
+export function resolveSnapshot(
+	staticSnapshotPath: string,
+	staticStateDir: string,
+): ResolvedSnapshot {
+	// Try the most recently active repo first.
+	const activeDir = mostRecentRepoStateDir(staticStateDir);
+	if (activeDir) {
+		const activePath = join(activeDir, "dashboard.json");
+		const snap = readSnapshot(activePath);
+		if (snap.updatedAt) {
+			return { snapshot: snap, stateDir: activeDir };
+		}
+	}
+	// Fall back to the static launch path.
+	return {
+		snapshot: readSnapshot(staticSnapshotPath),
+		stateDir: staticStateDir,
+	};
+}
+

package/extensions/dashboard-server/routes-core.ts

@@ -8,7 +8,7 @@
 
 import type { ServerResponse } from "node:http";
 
-import { readSnapshot } from "./snapshot.js";
+import { resolveSnapshot } from "./resolve-snapshot.js";
 import type { IndexIndex, Snapshot } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -53,14 +53,19 @@ function makeOverlayCurrentRepo(
 ): (idx: IndexIndex | null) => void {
 	return (idx: IndexIndex | null): void => {
 		if (!idx || !idx.repos.length) return;
+		// Dynamically resolve the most recently active repo's snapshot so the
+		// overlay matches what /api/snapshot serves (not the stale launch dir).
 		let snap: Snapshot | null = null;
+		let activeStateDir = stateDir;
 		try {
-			snap = readSnapshot(snapshotPath);
+			const resolved = resolveSnapshot(snapshotPath, stateDir);
+			snap = resolved.snapshot;
+			activeStateDir = resolved.stateDir;
 		} catch {
 			return;
 		}
 		if (!snap || !snap.repo) return;
-		const cur = idx.repos.find((r) => r.stateDir === stateDir);
+		const cur = idx.repos.find((r) => r.stateDir === activeStateDir);
 		if (!cur) return;
 		const prevSaved = cur.tokensSaved;
 		const prevCp = cur.checkpointCount;

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -272,6 +272,23 @@ export const SETTINGS: ReadonlyArray<{
 			num("MEGACOMPACT_EMBED_CACHE", "Embed Cache Size", "Embedding cache entries (0 = disabled)", 256, 0, 10000),
 		],
 	},
+	{
+		name: "Cost API",
+		settings: [
+			boolDirect(
+				"MEGACOMPACT_COST_API_ENABLED",
+				"Cost API Lookup",
+				"Fetch model pricing from an external API (PREVENT-PI-004 network exception — opt-in). Enriches the dashboard Cache/Repos tabs with real $/token rates for models not in the local pricing table.",
+				false,
+			),
+			str(
+				"MEGACOMPACT_COST_API_URL",
+				"Cost API URL",
+				"OpenRouter-compatible model pricing endpoint (e.g. https://openrouter.ai/api/v1/models). Only contacted when Cost API Lookup is ON.",
+				"",
+			),
+		],
+	},
 ];
 
 /** Flat index of every setting by key for O(1) lookup + validation. */

package/extensions/dashboard-server/routes-raptor.ts

@@ -10,7 +10,7 @@ import { createRequire } from "node:module";
 import type { ServerResponse, IncomingMessage } from "node:http";
 import { parse as parseUrl } from "node:url";
 import type { RouteContext } from "./routes-core.js";
-import type { RaptorTreeResponse, RaptorNodeDTO } from "./api-contracts/raptor.js";
+import type { RaptorTreeResponse, RaptorNodeDTO, RaptorBuildHistoryResponse, RaptorBuildHistoryDTO } from "./api-contracts/raptor.js";
 import { openStore } from "../../src/store/sqlite.js";
 
 const _req = createRequire(import.meta.url);
@@ -126,3 +126,90 @@ export function handleRaptorTree(
 		return true;
 	}
 }
+
+/** Find the most recent session that has build history rows (else null). */
+function latestBuildSession(stateDir: string): string | null {
+	try {
+		const db = openStore(stateDir);
+		const row = db
+			.prepare(
+				"SELECT DISTINCT session_id FROM raptor_build_history ORDER BY completed_at DESC LIMIT 1",
+			)
+			.get() as { session_id: string } | undefined;
+		return row?.session_id ?? null;
+	} catch {
+		return null;
+	}
+}
+
+export function handleRaptorBuildHistory(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (req.method !== "GET") return false;
+	const parsed = parseUrl(req.url ?? "", true);
+	if (parsed.pathname !== "/api/raptor-build-history") return false;
+
+	try {
+		const { listBuildHistory } = _req(
+			"../../src/dedup/raptor/buildHistory.js",
+		) as {
+			listBuildHistory: (
+				sessionId: string,
+				stateDir: string,
+			) => Array<{
+				buildId: string;
+				sessionId: string;
+				startedAt: number;
+				completedAt: number;
+				nodeCount: number;
+				leafCount: number;
+				depth: number;
+				coherenceScore: number | null;
+				timedOut: boolean;
+			}>;
+		};
+
+		let sessionId =
+			typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : "";
+
+		if (!sessionId) {
+			sessionId = latestBuildSession(ctx.stateDir) ?? "";
+			if (!sessionId) {
+				const body: RaptorBuildHistoryResponse = { builds: [], empty: true };
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(JSON.stringify(body));
+				return true;
+			}
+		}
+
+		const rows = listBuildHistory(sessionId, ctx.stateDir);
+		if (rows.length === 0) {
+			const body: RaptorBuildHistoryResponse = { builds: [], empty: true };
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify(body));
+			return true;
+		}
+
+		const dtos: RaptorBuildHistoryDTO[] = rows.map((r) => ({
+			buildId: r.buildId,
+			sessionId: r.sessionId,
+			startedAt: r.startedAt,
+			completedAt: r.completedAt,
+			nodeCount: r.nodeCount,
+			leafCount: r.leafCount,
+			depth: r.depth,
+			coherenceScore: r.coherenceScore,
+			timedOut: r.timedOut,
+		}));
+		const body: RaptorBuildHistoryResponse = { builds: dtos, empty: false };
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(body));
+		return true;
+	} catch (e) {
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: String(e) }));
+		return true;
+	}
+}

package/extensions/dashboard-server/routes-repo.ts

@@ -7,6 +7,7 @@ import { join } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 import { readSnapshot } from "./snapshot.js";
+import { resolveSnapshot } from "./resolve-snapshot.js";
 import { dashboardHtml } from "./html.js";
 import { readIndex, getIndexDir } from "./index-reader.js";
 import { ACTIVE_WINDOW_SEC } from "./types.js";
@@ -41,7 +42,10 @@ export function handleIndex(
 	}
 
 	if (req.url === "/api/snapshot") {
-		const snap = readSnapshot(snapshotPath);
+		// Dynamically resolve the most recently active session's dashboard.json
+		// so the Overview shows live data from the repo pi is running in — not
+		// the stale launcher dir the server was started with.
+		const { snapshot: snap } = resolveSnapshot(snapshotPath, ctx.stateDir);
 		res.writeHead(200, { "Content-Type": "application/json" });
 		res.end(JSON.stringify(snap));
 		return true;

package/extensions/dashboard-server/routes-sessions.ts

@@ -28,10 +28,13 @@ export function handleEvents(
 		Connection: "keep-alive",
 	});
 
-	// Drain existing events so the client starts with history
+	// Drain existing events so the client starts with history.
+	// Only stream events with a "type" field — events.log also contains
+	// internal monitoring rows (e.g. captureModel:recorded) that use "event"
+	// instead of "type" and aren't part of the SseEvent contract.
 	const { data: existing, offset: initialOffset } = readFrom(eventsPath, 0);
 	eventOffsetRef.value = initialOffset;
-	const lines = existing.split("\n").filter((l: string) => l.trim());
+	const lines = existing.split("\n").filter((l: string) => l.trim() && l.includes('"type"'));
 	for (const line of lines) {
 		res.write(`data: ${line}\n\n`);
 	}
@@ -44,7 +47,7 @@ export function handleEvents(
 			watchTimer = null;
 			const { data, offset } = readFrom(eventsPath, eventOffsetRef.value);
 			eventOffsetRef.value = offset;
-			const newLines = data.split("\n").filter((l: string) => l.trim());
+			const newLines = data.split("\n").filter((l: string) => l.trim() && l.includes('"type"'));
 			for (const line of newLines) {
 				res.write(`data: ${line}\n\n`);
 			}

package/extensions/dashboard-server/routes.ts

@@ -23,7 +23,7 @@ export { handleProviderCache } from "./routes-cache.js";
 export { handleMemoryStatus } from "./routes-memory.js";
 export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
 export { handleMemoryMap } from "./routes-memory-map.js";
-export { handleRaptorTree } from "./routes-raptor.js";
+export { handleRaptorTree, handleRaptorBuildHistory } from "./routes-raptor.js";
 export { handleCacheStripes } from "./routes-cache.js";
 export { handleContextHealth, handleCachePoison, handleHealthSettings } from "./routes-health.js";
 export { handleEmbedderHealth } from "./routes-embedder-health.js";

package/extensions/dashboard-server/server.ts

@@ -46,6 +46,7 @@ import {
 	handleSetupConfigure,
 	handleMemoryMap,
 	handleRaptorTree,
+	handleRaptorBuildHistory,
 	handleContextHealth,
 	handleCachePoison,
 	handleHealthSettings,
@@ -260,6 +261,7 @@ export async function launchDashboardServer(
 		if (handleSetupConfigure(req, res, ctx)) return;
 		if (handleMemoryMap(req, res, ctx)) return;
 		if (handleRaptorTree(req, res, ctx)) return;
+		if (handleRaptorBuildHistory(req, res, ctx)) return;
 		if (handleContextHealth(req, res, ctx)) return;
 		if (handleCachePoison(req, res, ctx)) return;
 		if (handleHealthSettings(req, res, ctx)) return;

package/extensions/mega-pipeline/recall.ts

@@ -107,16 +107,23 @@ export function doRecall(
 		);
 		runtime.lastWhy = `why: recalled@${scorePct}% (${result.toInject.length} chkpt)`;
 	}
+	let sumTokens = 0;
+	for (const h of result.toInject) sumTokens += h.checkpoint.tokenEstimate;
 	if (result.toInject.length > 0) {
-		let sumTokens = 0;
-		for (const h of result.toInject) sumTokens += h.checkpoint.tokenEstimate;
 		runtime.rt.recallInjections += result.toInject.length;
 		runtime.rt.cacheHitTokens += sumTokens;
 		incRecallInjected(result.toInject.length, runtime.currentStateDir);
 		incCacheHitTokens(sumTokens, runtime.currentStateDir);
-		// S43: record recall provenance — which checkpoints/summaries served this
-		// turn, their score + source path. Linked to the turn row written at
-		// turn_end via the conversation+turnIndex. Best-effort + non-fatal.
+	}
+	// S43: record recall provenance — which checkpoints/summaries served this
+	// turn, their score + source path. Linked to the turn row written at
+	// turn_end via the conversation+turnIndex. Best-effort + non-fatal.
+	// Persists telemetry (HyDE + recall metrics) even when recall returned
+	// no hits, so empty-recall HyDE invocations are still visible in the
+	// dashboard Turns/Metrics tabs.
+	const hasTelemetry =
+		result.hydeInfo != null || result.recallMetrics != null;
+	if (result.toInject.length > 0 || hasTelemetry) {
 		try {
 			const convId = ensureConversationIdFor(
 				config,
@@ -136,22 +143,24 @@ export function doRecall(
 				},
 				runtime.currentStateDir,
 			);
-			recordRecallWrite(
-				config,
-				turnId,
-				result.toInject.map((h) => ({
-					checkpointId: h.checkpoint.checkpointId,
-					score: h.score,
-					source:
-						h.raptorLevel !== undefined
-							? "raptor"
-							: h.repoId
-								? "cross-repo"
-								: "flat",
-					raptorLevel: h.raptorLevel,
-				})),
-				runtime.currentStateDir,
-			);
+			if (result.toInject.length > 0) {
+				recordRecallWrite(
+					config,
+					turnId,
+					result.toInject.map((h) => ({
+						checkpointId: h.checkpoint.checkpointId,
+						score: h.score,
+						source:
+							h.raptorLevel !== undefined
+								? "raptor"
+								: h.repoId
+									? "cross-repo"
+									: "flat",
+						raptorLevel: h.raptorLevel,
+					})),
+					runtime.currentStateDir,
+				);
+			}
 		} catch {
 			/* non-fatal: recall provenance never breaks the recall path */
 		}

package/extensions/mega-runtime/capture-model.ts

@@ -10,6 +10,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resolveRepoRoot } from "../mega-config.js";
 import { recordModelSnapshot, recordRepoModel } from "../../src/store/sqlite.js";
 import type { ModelSnapshot } from "../../src/store/sqlite.js";
+import { lookupModelInputRate } from "../../src/pricing.js";
 
 // ---------------------------------------------------------------------- types
 
@@ -42,12 +43,14 @@ export function captureModelImpl(ctx: CaptureModelContext, ectx: ExtensionContex
 	} catch {
 		/* optional */
 	}
+	const modelId = m.id;
+	const fallbackInput = lookupModelInputRate(modelId);
 	const snap: Omit<ModelSnapshot, "capturedAt"> = {
 		provider: m.provider,
 		providerName,
-		modelId: m.id,
+		modelId,
 		modelName: m.name ?? null,
-		inputRate: m.cost?.input ?? 0,
+		inputRate: m.cost?.input || fallbackInput || 0,
 		outputRate: m.cost?.output ?? 0,
 		contextWindow: m.contextWindow ?? 0,
 		maxTokens: m.maxTokens ?? 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.13.6",
+  "version": "0.14.0",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/dedup.ts

@@ -89,7 +89,8 @@ export function loadDedupConfig(): DedupConfigShape {
     L2_ENABLED: envBool("MEGACOMPACT_L2_ENABLED", true),
     // Fix D: RAPTOR promoted to live recall. Default ON; canary.ts sequences it
     // last (L0→L1→L2→RAPTOR) and auto-disables on p95 breach, so promotion is
-    // safe. `RAPTOR_SHADOW_MODE=false` still gates serving during transition.
+    // safe. Shadow mode (RAPTOR_SHADOW_MODE=true) opts out of serving while
+    // still building + persisting the tree (transition/eval use).
     RAPTOR_ENABLED: envBool("MEGACOMPACT_RAPTOR_ENABLED", true),
     MARK_ONLY_L0: envBool("MEGACOMPACT_MARK_ONLY_L0", false),
     MARK_ONLY_L1: envBool("MEGACOMPACT_MARK_ONLY_L1", false),

package/src/costApi.ts

@@ -0,0 +1,131 @@
+/**
+ * costApi.ts — optional model pricing lookup from an external API.
+ *
+ * PREVENT-PI-004 EXEMPTION: This module makes network calls to fetch model
+ * pricing data. It is disabled by default and must be explicitly opted in via
+ * MEGACOMPACT_COST_API_ENABLED=true + MEGACOMPACT_COST_API_URL=<url>.
+ *
+ * The dashboard server uses this to enrich the inputRate/outputRate fields
+ * when the local pricing table (pricing.ts) has no data for a model.
+ *
+ * Results are cached for 1 hour to minimize network calls.
+ */
+
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: user-opted-in cost API — fetches model pricing from a user-configured endpoint, never called unless MEGACOMPACT_COST_API_ENABLED=true
+
+export interface ModelPricing {
+	inputRate: number | null;
+	outputRate: number | null;
+}
+
+export interface CostApiConfig {
+	enabled: boolean;
+	url: string;
+}
+
+let _cache: { timestamp: number; data: Map<string, ModelPricing> } | null = null;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export function costApiConfig(): CostApiConfig {
+	const enabled =
+		process.env.MEGACOMPACT_COST_API_ENABLED === "true" ||
+		process.env.MEGACOMPACT_COST_API_ENABLED === "1";
+	const url = process.env.MEGACOMPACT_COST_API_URL ?? "";
+	return { enabled, url };
+}
+
+/**
+ * Fetch model pricing from the configured API endpoint.
+ *
+ * Expects a JSON response of shape:
+ *   { "data": [{ "id": "model-name", "pricing": { "prompt": "0.000003", "completion": "0.000015" } }] }
+ * (OpenRouter-compatible format). Values are USD per token as strings.
+ *
+ * Returns a map keyed by lowercase model id → { inputRate, outputRate }.
+ * Returns an empty map on any error. Never throws.
+ */
+export function fetchModelPricing(): Map<string, ModelPricing> {
+	const cfg = costApiConfig();
+	if (!cfg.enabled || !cfg.url) return new Map();
+
+	// Return cached data if fresh.
+	if (_cache && Date.now() - _cache.timestamp < CACHE_TTL_MS) {
+		return _cache.data;
+	}
+
+	const result = _doFetch(cfg.url);
+	_cache = { timestamp: Date.now(), data: result };
+	return result;
+}
+
+function _doFetch(url: string): Map<string, ModelPricing> {
+	// Synchronous bridge: spawnSync an inline worker so the call blocks without
+	// deadlocking fetch (mirrors HttpEmbedder / RAPTOR summarizer pattern).
+	const WORKER = String.raw`
+		try {
+			const r = await fetch(process.env.COST_API_URL, { // guardrails-allow PREVENT-PI-004: user-opted-in cost API — fetches model pricing from a user-configured endpoint
+				method: "GET",
+				headers: { "accept": "application/json" },
+			});
+			const j = await r.json();
+			process.stdout.write(JSON.stringify({ ok: r.ok, data: j }));
+		} catch (e) {
+			process.stdout.write(JSON.stringify({ ok: false, error: String(e && e.message ? e.message : e) }));
+		}
+	`;
+	const res = spawnSync(process.execPath, ["-e", WORKER], {
+		encoding: "utf8",
+		timeout: 15_000,
+		env: { ...process.env, COST_API_URL: url },
+	});
+
+	const out = new Map<string, ModelPricing>();
+
+	let parsed: { ok: boolean; data?: unknown; error?: string };
+	try {
+		parsed = JSON.parse(res.stdout);
+	} catch {
+		return out;
+	}
+
+	if (!parsed.ok || !parsed.data) return out;
+
+	// OpenRouter-compatible: { data: [{ id, pricing: { prompt, completion } }] }
+	const models = (parsed.data as { data?: Array<{ id?: string; pricing?: { prompt?: string; completion?: string } }> })?.data;
+	if (!Array.isArray(models)) return out;
+
+	for (const m of models) {
+		if (!m.id) continue;
+		const prompt = m.pricing?.prompt;
+		const completion = m.pricing?.completion;
+		const inputRate = prompt != null ? parseFloat(prompt) : null;
+		const outputRate = completion != null ? parseFloat(completion) : null;
+		if (inputRate != null || outputRate != null) {
+			out.set(m.id.toLowerCase(), { inputRate, outputRate });
+		}
+	}
+
+	return out;
+}
+
+/**
+ * Look up pricing for a model name from the cost API cache.
+ * Tries exact match, then prefix match (same pattern as lookupModelInputRate).
+ */
+export function lookupCostApiPricing(model: string): ModelPricing | null {
+	const data = fetchModelPricing();
+	if (data.size === 0) return null;
+	const lower = model.toLowerCase();
+	// Exact match.
+	if (data.has(lower)) return data.get(lower) ?? null;
+	// Prefix match.
+	for (const [key, pricing] of data) {
+		if (lower.startsWith(key)) return pricing;
+	}
+	return null;
+}
+
+/** Clear the pricing cache (useful for testing). */
+export function clearCostApiCache(): void {
+	_cache = null;
+}