@agimon-ai/po-cache 0.0.0-alpha.2 → 0.0.0-alpha.4

package/dist/extensions/server.d.mts

@@ -1,5 +1,5 @@
 //#region generated/server.d.ts
-export declare const facet: import("@agimon-ai/po-core/serverFacet").DoomServerFacet;
+export declare const facet: import("@agimon-ai/po-core/serverFacet").PoServerFacet;
 //#endregion
 export { facet as default };
 //# sourceMappingURL=server.d.mts.map

package/dist/extensions/server.mjs

@@ -1,15 +1,13 @@
 import { a as PO_PROMPT_CACHE_ROOT_SESSION_ENV, i as PO_PROMPT_CACHE_PARENT_NAMESPACE_ENV, r as PO_PROMPT_CACHE_CHILD_PROJECTION_ENV } from "../environment-vyw-n84h.mjs";
-import { c as createPromptCacheModelFingerprint, h as sha256Base64Url, i as rewritePromptCacheKey, l as createRootSessionIdentity, o as createParentPromptCacheNamespace, p as PromptCacheTelemetryService, s as createPromptCacheKey, t as PromptCacheTelemetry, u as canonicalJson } from "../promptCacheTelemetry-CguL1ZqT.mjs";
+import { c as createPromptCacheModelFingerprint, h as sha256Base64Url, i as rewritePromptCacheKey, l as createRootSessionIdentity, o as createParentPromptCacheNamespace, p as PromptCacheTelemetryService, s as createPromptCacheKey, t as PromptCacheTelemetry, u as canonicalJson } from "../promptCacheTelemetry-LM1cAPk8.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { composeServerProviderOverrides, defineServerPlugin } from "@agimon-ai/po-core/serverFacet";
 import { composeRootHooks, defineHook, defineRoot } from "@agimon-ai/po-core/extensionFile";
+import { BACKGROUND_CONTEXT, createSerialRunner, getOrThrow, nodeHost, readTextIfExists, requirePoFs, writeFileAtomic } from "@agimon-ai/po-core/platform";
 import { getSessionHarnessState } from "@agimon-ai/po-config/harnessStore";
-import { DOOM_MINOR_MODE_CATALOG_SERVICE, readMinorModeCatalog } from "@agimon-ai/po-minor-mode";
-import { dirname, join } from "node:path";
+import { PO_MINOR_MODE_CATALOG_SERVICE, readMinorModeCatalog } from "@agimon-ai/po-minor-mode";
+import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { readFileSync, statSync } from "node:fs";
-import { lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 //#region src/services/environment/index.ts
 const environmentLeases = /* @__PURE__ */ new WeakMap();
 /** Same-value session leases restore only after the final owner leaves. External writes win. */
@@ -177,7 +175,7 @@ function createCacheRuntime(dependencies, environment) {
 		return parentNamespace;
 	};
 	const plugin = (cordis) => {
-		cordis.inject([DOOM_MINOR_MODE_CATALOG_SERVICE], (context) => {
+		cordis.inject([PO_MINOR_MODE_CATALOG_SERVICE], (context) => {
 			if (isProjectedChild) return void 0;
 			const catalog = readMinorModeCatalog(context);
 			if (!catalog) return void 0;
@@ -212,8 +210,19 @@ function createCacheRuntime(dependencies, environment) {
 	};
 }
 //#endregion
+//#region src/services/agentDirectory/index.ts
+/** Pi's agent directory, where the optimizer keeps its state; the edge build swaps in `index.edge.ts`. */
+function defaultAgentDirectory() {
+	return getAgentDir();
+}
+//#endregion
 //#region src/services/optimizerSupport/index.ts
-function createOptimizerSupport(STATE_DIR, environment) {
+/**
+* Optimizer state under `STATE_DIR`, read and written through the injected file system. Synchronous
+* readers (`getCompat`, `footerStatsMode`) use the files as of the last `refreshFileConfig()`.
+*/
+function createOptimizerSupport(STATE_DIR, environment, fs) {
+	const io = BACKGROUND_CONTEXT;
 	const MODELS_JSON_PATH = join(STATE_DIR, "models.json");
 	function isVirtualRoutingModel(model) {
 		return !!model && (isNativeVirtualModel(model) || model.provider.toLowerCase() === "router");
@@ -492,21 +501,20 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		}
 		return true;
 	}
+	/** Keyed by the file text, so an unchanged models.json is not parsed again. */
 	let modelsConfigCache;
-	function getModelsConfigSignature() {
+	async function refreshModelsConfig() {
+		let text;
 		try {
-			const info = statSync(MODELS_JSON_PATH);
-			return `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}:${info.ctimeMs}`;
+			text = await readTextIfExists(fs, MODELS_JSON_PATH, io);
 		} catch {
-			return "missing";
+			text = void 0;
 		}
-	}
-	function readEffectiveCompatConfig() {
-		const signature = getModelsConfigSignature();
-		if (modelsConfigCache?.signature === signature) return modelsConfigCache.value;
+		const signature = text ?? "missing";
+		if (modelsConfigCache?.signature === signature) return;
 		let value;
-		if (signature !== "missing") try {
-			const parsed = parseJsonc(readFileSync(MODELS_JSON_PATH, "utf8"));
+		if (text !== void 0) try {
+			const parsed = parseJsonc(text);
 			value = isValidModelsConfigForEffectiveCompat(parsed) ? parsed : void 0;
 		} catch {
 			value = void 0;
@@ -515,17 +523,24 @@ function createOptimizerSupport(STATE_DIR, environment) {
 			signature,
 			value
 		};
-		return value;
+	}
+	/** The models.json compat config as of the last refresh. */
+	function effectiveCompatConfig() {
+		return modelsConfigCache?.value;
+	}
+	async function readEffectiveCompatConfig() {
+		await refreshModelsConfig();
+		return effectiveCompatConfig();
 	}
 	function getCompat(model) {
 		if (!model) return {};
-		return resolveEffectiveCompatFromConfig(model, readEffectiveCompatConfig());
+		return resolveEffectiveCompatFromConfig(model, effectiveCompatConfig());
 	}
 	function joinDisplayPath(base, child, platform = process.platform) {
 		const sep = platform.startsWith("win") ? "\\" : "/";
 		return `${base.replace(/[\\/]+$/, "")}${sep}${child}`;
 	}
-	function getAgentDirDisplayPath(platform = process.platform, agentDir = STATE_DIR, homeDir = homedir()) {
+	function getAgentDirDisplayPath(platform = process.platform, agentDir = STATE_DIR, homeDir = nodeHost.homeDirectory()) {
 		const sep = platform.startsWith("win") ? "\\" : "/";
 		const normalizedAgentDir = agentDir.replace(/[\\/]+/g, sep);
 		const normalizedHomeDir = homeDir.replace(/[\\/]+/g, sep).replace(/[\\/]+$/, "");
@@ -537,7 +552,7 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		}
 		return normalizedAgentDir;
 	}
-	function getModelsJsonDisplayPath(platform = process.platform, agentDir = STATE_DIR, homeDir = homedir()) {
+	function getModelsJsonDisplayPath(platform = process.platform, agentDir = STATE_DIR, homeDir = nodeHost.homeDirectory()) {
 		return joinDisplayPath(getAgentDirDisplayPath(platform, agentDir, homeDir), "models.json", platform);
 	}
 	function parseFooterStatsMode(value) {
@@ -601,11 +616,13 @@ function createOptimizerSupport(STATE_DIR, environment) {
 			...features ? { features } : {}
 		};
 	}
-	function readPersistedCacheOptimizerConfig(configPath = CONFIG_FILE_PATH) {
+	async function readPersistedCacheOptimizerConfig(configPath = CONFIG_FILE_PATH) {
 		try {
-			return normalizePersistedCacheOptimizerConfig(parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8"))));
+			const text = await readTextIfExists(fs, configPath, io);
+			if (text === void 0) return { version: 2 };
+			return normalizePersistedCacheOptimizerConfig(parsePersistedCacheOptimizerConfig(JSON.parse(text)));
 		} catch (error) {
-			if (getErrorCode(error) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to read optimizer config; using defaults`, error);
+			console.warn(`${LOG_PREFIX}: failed to read optimizer config; using defaults`, error);
 			return { version: 2 };
 		}
 	}
@@ -626,7 +643,17 @@ function createOptimizerSupport(STATE_DIR, environment) {
 	function footerStatsMode(env = environment, configuredMode = persistedFooterStatsMode) {
 		return resolveFooterStatsMode(configuredMode, env).mode;
 	}
-	const persistedFooterStatsMode = readPersistedCacheOptimizerConfig().footerMode;
+	/** Read once, on the first refresh, like the original read at construction. */
+	let persistedConfigLoaded = false;
+	let persistedFooterStatsMode;
+	/** Loads the persisted optimizer config once and rereads models.json; call before the synchronous readers. */
+	async function refreshFileConfig() {
+		if (!persistedConfigLoaded) {
+			persistedConfigLoaded = true;
+			persistedFooterStatsMode = (await readPersistedCacheOptimizerConfig()).footerMode;
+		}
+		await refreshModelsConfig();
+	}
 	function isAssistantMessage(message) {
 		return asRecord(message)?.role === "assistant";
 	}
@@ -1254,7 +1281,7 @@ function createOptimizerSupport(STATE_DIR, environment) {
 			baseUrl: "",
 			[ROUTED_FALLBACK_MODEL_SYMBOL]: true
 		};
-		const provider = asRecord(asRecord(asRecord(readEffectiveCompatConfig())?.providers)?.[model.provider]);
+		const provider = asRecord(asRecord(asRecord(effectiveCompatConfig())?.providers)?.[model.provider]);
 		const customModel = findLastExactModelDefinition(Array.isArray(provider?.models) ? provider.models : void 0, model.id);
 		const configuredApi = customModel?.api ?? provider?.api;
 		const configuredBaseUrl = customModel?.baseUrl ?? provider?.baseUrl;
@@ -2779,14 +2806,6 @@ function createOptimizerSupport(STATE_DIR, environment) {
 			stats: best.stats
 		} : void 0;
 	}
-	function createSerializedAsyncRunner() {
-		let tail = Promise.resolve();
-		return (operation) => {
-			const result = tail.then(operation);
-			tail = result.catch(() => void 0);
-			return result;
-		};
-	}
 	function modelEpochPath(modelKeyValue) {
 		return join(SHARD_MODEL_EPOCH_DIR, `${createHash("sha256").update(modelKeyValue).digest("hex")}.json`);
 	}
@@ -2799,7 +2818,7 @@ function createOptimizerSupport(STATE_DIR, environment) {
 	}
 	async function readEpochFile(path, fallback) {
 		try {
-			return parseEpochRecord(JSON.parse(await readFile(path, "utf8"))) ?? fallback;
+			return parseEpochRecord(JSON.parse(getOrThrow(await fs.readTextFile(path, io)))) ?? fallback;
 		} catch {
 			return fallback;
 		}
@@ -2811,14 +2830,11 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		return readEpochFile(modelEpochPath(modelKeyValue), initialEpoch(`model:${modelKeyValue}`));
 	}
 	async function writeStatsEpoch(path, epoch) {
-		await mkdir(dirname(path), { recursive: true });
-		const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
-		await writeFile(tempPath, JSON.stringify({
+		await writeFileAtomic(fs, path, JSON.stringify({
 			version: 1,
 			epoch,
 			createdAt: Date.now()
-		}, null, 2) + "\n", "utf8");
-		await rename(tempPath, path);
+		}, null, 2) + "\n", io);
 	}
 	async function advanceGlobalStatsEpoch() {
 		const epoch = `${Date.now()}-${randomUUID()}`;
@@ -2874,27 +2890,34 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		};
 	}
 	async function writeStatsShardV7(path, shard) {
-		await mkdir(dirname(path), { recursive: true });
-		const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
-		await writeFile(tempPath, JSON.stringify(shard, null, 2) + "\n", "utf8");
-		await rename(tempPath, path);
+		await writeFileAtomic(fs, path, JSON.stringify(shard, null, 2) + "\n", io);
 	}
-	async function readValidStatsShardsV7(directory = SHARD_FILES_DIR) {
-		let names;
+	/** Entries of `directory`, or undefined when it does not exist. Entries removed while listing are skipped. */
+	async function listDirectoryEntries(directory) {
+		const opened = await fs.openDirReader(directory, io);
+		if (!opened.ok && opened.error.code === "not_found") return void 0;
+		const reader = getOrThrow(opened);
 		try {
-			names = await readdir(directory);
-		} catch (error) {
-			if (getErrorCode(error) === "ENOENT") return [];
-			throw error;
+			const entries = [];
+			for (;;) {
+				const page = getOrThrow(await reader.next(256, io));
+				entries.push(...page.entries);
+				if (page.done) return entries;
+			}
+		} finally {
+			await reader.close(io);
 		}
+	}
+	async function readValidStatsShardsV7(directory = SHARD_FILES_DIR) {
+		const entries = await listDirectoryEntries(directory);
+		if (!entries) return [];
 		const shards = [];
-		for (const name of names) {
+		for (const { name, kind } of entries) {
 			if (!/^[0-9a-f-]+\.json$/i.test(name)) continue;
 			const path = join(directory, name);
 			try {
-				const info = await lstat(path);
-				if (!info.isFile() || info.isSymbolicLink()) continue;
-				const parsed = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
+				if (kind !== "file") continue;
+				const parsed = parsePersistedStatsShardV7(JSON.parse(getOrThrow(await fs.readTextFile(path, io))));
 				const filenameInstanceId = name.slice(0, -5);
 				if (parsed && parsed.instanceId === filenameInstanceId) shards.push(parsed);
 			} catch {}
@@ -2965,73 +2988,63 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		}
 	}
 	async function removeLegacyStatsFiles() {
-		for (const path of [STATE_FILE_PATH, LEGACY_STATE_FILE_PATH]) try {
-			await unlink(path);
-		} catch (error) {
-			if (getErrorCode(error) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove obsolete stats file ${path}`, error);
+		for (const path of [STATE_FILE_PATH, LEGACY_STATE_FILE_PATH]) {
+			const removed = await fs.remove(path, { force: true }, io);
+			if (!removed.ok) console.warn(`${LOG_PREFIX}: failed to remove obsolete stats file ${path}`, removed.error);
 		}
 	}
 	async function cleanupStatsShardsV7(now = Date.now(), directory = SHARD_FILES_DIR) {
-		let names;
-		try {
-			names = await readdir(directory);
-		} catch (error) {
-			return getErrorCode(error) === "ENOENT" ? 0 : Promise.reject(error);
-		}
+		const entries = await listDirectoryEntries(directory);
+		if (!entries) return 0;
 		const today = currentLocalDay();
 		let removed = 0;
-		for (const name of names) {
+		for (const info of entries) {
+			const { name } = info;
 			const isShard = /^[0-9a-f-]+\.json$/i.test(name);
 			const isTemp = name.endsWith(".tmp");
 			if (!isShard && !isTemp) continue;
 			const path = join(directory, name);
 			try {
-				const info = await lstat(path);
-				if (!info.isFile() || info.isSymbolicLink()) continue;
+				if (info.kind !== "file") continue;
 				if (isTemp) {
 					if (now - info.mtimeMs < SHARD_TEMP_RETENTION_MS) continue;
 				} else {
-					const parsed = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
+					const parsed = parsePersistedStatsShardV7(JSON.parse(getOrThrow(await fs.readTextFile(path, io))));
 					if (parsed?.day === today) continue;
 					if (now - (parsed?.lifecycle.updatedAt ?? info.mtimeMs) < SHARD_RETENTION_MS) continue;
 					if (parsed?.lifecycle.state === "active" && isProcessAlive(parsed.process.pid)) continue;
 				}
-				await unlink(path);
+				getOrThrow(await fs.remove(path, void 0, io));
 				removed += 1;
 			} catch {}
 		}
 		return removed;
 	}
+	/**
+	* Best-effort cross-process maintenance. A non-recursive `createDir` claims the cleanup lock; if two
+	* cleanups ever overlap, each only removes expired shards, so the lock bounds work rather than guarding
+	* correctness.
+	*/
 	async function maybeCleanupStatsShardsV7(now = Date.now()) {
-		await mkdir(SHARD_MAINTENANCE_DIR, { recursive: true });
-		try {
-			if (now - (await stat(SHARD_CLEANUP_MARKER_PATH)).mtimeMs < SHARD_CLEANUP_INTERVAL_MS) return;
-		} catch {}
-		try {
-			await mkdir(SHARD_CLEANUP_LOCK_PATH);
-		} catch (error) {
-			if (getErrorCode(error) !== "EEXIST") return;
-			try {
-				if (now - (await stat(SHARD_CLEANUP_LOCK_PATH)).mtimeMs <= SHARD_CLEANUP_LOCK_STALE_MS) return;
-				await rm(SHARD_CLEANUP_LOCK_PATH, {
-					recursive: true,
-					force: true
-				});
-				await mkdir(SHARD_CLEANUP_LOCK_PATH);
-			} catch {
-				return;
-			}
+		getOrThrow(await fs.createDir(SHARD_MAINTENANCE_DIR, { recursive: true }, io));
+		const marker = await fs.fileInfo(SHARD_CLEANUP_MARKER_PATH, io);
+		if (marker.ok && now - marker.value.mtimeMs < SHARD_CLEANUP_INTERVAL_MS) return;
+		if (!(await fs.createDir(SHARD_CLEANUP_LOCK_PATH, { recursive: false }, io)).ok) {
+			const lock = await fs.fileInfo(SHARD_CLEANUP_LOCK_PATH, io);
+			if (!lock.ok || now - lock.value.mtimeMs <= SHARD_CLEANUP_LOCK_STALE_MS) return;
+			if (!(await fs.remove(SHARD_CLEANUP_LOCK_PATH, {
+				recursive: true,
+				force: true
+			}, io)).ok || !(await fs.createDir(SHARD_CLEANUP_LOCK_PATH, { recursive: false }, io)).ok) return;
 		}
 		try {
 			await cleanupStatsShardsV7(now);
-			const tempPath = `${SHARD_CLEANUP_MARKER_PATH}.${process.pid}.${randomUUID()}.tmp`;
-			await writeFile(tempPath, `${now}\n`, "utf8");
-			await rename(tempPath, SHARD_CLEANUP_MARKER_PATH);
+			await writeFileAtomic(fs, SHARD_CLEANUP_MARKER_PATH, `${now}\n`, io);
 		} finally {
-			await rm(SHARD_CLEANUP_LOCK_PATH, {
+			getOrThrow(await fs.remove(SHARD_CLEANUP_LOCK_PATH, {
 				recursive: true,
 				force: true
-			});
+			}, io));
 		}
 	}
 	function isExplicitPromptCacheRetentionUnsupportedApplicable(model) {
@@ -3182,7 +3195,7 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		advanceModelStatsEpoch,
 		maybeCleanupStatsShardsV7,
 		removeLegacyStatsFiles,
-		createSerializedAsyncRunner,
+		createSerializedAsyncRunner: createSerialRunner,
 		hasReasoningProtocolRejectionErrorMessage,
 		isReasoningProtocolRejectionForModel,
 		hasPromptCacheKeyUnsupportedErrorMessage,
@@ -3201,6 +3214,7 @@ function createOptimizerSupport(STATE_DIR, environment) {
 		parsePersistedStatsShardV7,
 		cleanupStatsShardsV7,
 		readEffectiveCompatConfig,
+		refreshFileConfig,
 		getCompat,
 		SHARD_FILES_DIR,
 		LOG_PREFIX
@@ -3220,8 +3234,8 @@ function asModel(model) {
 	} : void 0;
 }
 /** One native session owner. Only V7 counters, never payloads or credentials, reach disk. */
-function createNativeOptimizer(initial, stateDir = getAgentDir()) {
-	const support = createOptimizerSupport(stateDir, initial.environment);
+function createNativeOptimizer(initial, fs, stateDir = defaultAgentDirectory()) {
+	const support = createOptimizerSupport(stateDir, initial.environment, fs);
 	const serialized = support.createSerializedAsyncRunner();
 	const instanceId = randomUUID();
 	const instanceStartedAt = Date.now();
@@ -3505,6 +3519,7 @@ function createNativeOptimizer(initial, stateDir = getAgentDir()) {
 					if (started || closed) return;
 					started = true;
 					releaseRetention = acquireEnvironmentValue("PI_CACHE_RETENTION", "long");
+					await support.refreshFileConfig();
 					currentGlobalEpoch = await support.readGlobalStatsEpoch();
 					await support.removeLegacyStatsFiles();
 					await refresh();
@@ -3519,6 +3534,7 @@ function createNativeOptimizer(initial, stateDir = getAgentDir()) {
 				handle: (event, context) => serialized(async () => {
 					if (typeof event.parentToolCallId === "string" && event.parentToolCallId.trim()) return;
 					if (started && !closed) {
+						await support.refreshFileConfig();
 						await refresh();
 						await publish(context);
 					}
@@ -3528,6 +3544,7 @@ function createNativeOptimizer(initial, stateDir = getAgentDir()) {
 				event: "agent_settled",
 				handle: (_event, context) => serialized(async () => {
 					if (started && !closed) {
+						await support.refreshFileConfig();
 						await refresh();
 						await publish(context);
 					}
@@ -3537,6 +3554,7 @@ function createNativeOptimizer(initial, stateDir = getAgentDir()) {
 				event: "model_select",
 				handle: (_event, context) => serialized(async () => {
 					if (!started || closed) return;
+					await support.refreshFileConfig();
 					const model = selectedModel(context);
 					support.notifyCacheCompatIfNeeded(model, (text) => notify(context, text), warnedModels);
 					await refresh();
@@ -3546,7 +3564,9 @@ function createNativeOptimizer(initial, stateDir = getAgentDir()) {
 			{
 				event: "message_end",
 				handle: (event, context) => serialized(async () => {
-					if (started && !closed) await observe(event.message, context);
+					if (!started || closed) return;
+					await support.refreshFileConfig();
+					await observe(event.message, context);
 				})
 			},
 			{
@@ -3566,14 +3586,14 @@ function createNativeOptimizer(initial, stateDir = getAgentDir()) {
 }
 //#endregion
 //#region src/extensions/workspaces/sessions/(backend)/root.server.ts
-var root_server_default = defineRoot(({ agent }) => {
+var root_server_default = defineRoot(({ agent, context: root }) => {
 	if (!agent) throw new Error("Cache statistics require the native session host.");
 	const telemetry = new PromptCacheTelemetry();
 	const runtime = createCacheRuntime({
 		telemetry,
 		now: Date.now
 	}, agent.context.environment);
-	const optimizer = createNativeOptimizer(agent.context);
+	const optimizer = createNativeOptimizer(agent.context, requirePoFs(root));
 	return {
 		value: { hooks: optimizer.hooks.map((hook) => {
 			if (hook.event === "session_start") return {