@agimon-ai/doompi-cache 0.0.1-alpha.4 → 0.0.1-alpha.42

package/README.md

@@ -1,35 +1,50 @@
 # @agimon-ai/doompi-cache
 
-Provider prompt cache policy and deterministic routing for DoomPi
+Provider prompt-cache policy and deterministic routing for DoomPi.
 
-This package is a composable [DoomPi](https://www.npmjs.com/package/@agimon-ai/doompi) subsystem. Use it with the distribution or install it independently in [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
+DoomPi loads this package as fixed core. It derives stable provider cache keys from the active
+session composition and applies them only to supported provider requests. The package can also run
+as a standalone [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) extension.
+
+> **Alpha:** cache routing and provider integration may change between releases.
 
 ## Requirements
 
 - Node.js 22.19.0 or newer
-- `@earendil-works/pi-coding-agent` 0.84.2
+- Pi 0.85.0 for standalone extension use
 
 ## Install
 
+A DoomPi installation already includes this package. Do not add it to `.doom/modes.yaml`.
+
+To load it directly in Pi:
+
 ```bash
 pi install npm:@agimon-ai/doompi-cache
 ```
 
-The package declares its Pi extension entry, so Pi loads it after installation. DoomPi users can include the package through their normal profile and domain composition instead.
+Pi reads the extension entry from `package.json.pi.extensions` and loads it after installation.
 
 ## Package behavior
 
-DoomPi derives an opaque provider cache key from stable model-visible state, including the composition fingerprint, ordered domains, profile, persona, active minor modes, effective model, and child prompt projection. Returning to equivalent state restores the same key, but provider expiry or eviction can still make that namespace cold.
+DoomPi derives an opaque provider cache key from stable model-visible state: the composition
+fingerprint, ordered domains, profile, persona, active minor modes, effective model, and child prompt
+projection. Returning to equivalent state restores the same key. Provider expiry or eviction can
+still make the cache cold.
 
-The Pi extension rewrites only a nonblank cache key already emitted for an allowlisted OpenAI-family wire API. It preserves supported retention and provider cache markers, avoids adding unsupported fields to proxies, and reports only provider-observed token usage. Telemetry always reports current provider residency as `unknown`.
+The Pi extension rewrites only a nonblank cache key already emitted for an allowlisted OpenAI-family
+wire API. It preserves supported retention and provider cache markers, does not add unsupported
+fields to proxies, and reports only provider-observed token usage. Telemetry reports current
+provider residency as `unknown`.
 
 ## Help
 
-The published package includes `llms.txt` and the package-owned `src/prompts/doompi-use-cache/SKILL.md`. When the DoomPi Help minor mode is active, the extension contributes `doompi-use-cache` to its live Help catalog. The contribution follows Help provider replacement and is withdrawn when the extension shuts down.
-
-Help remains optional. Loading the standalone Pi extension does not require DoomPi Help or any other DoomPi runtime service.
+The published package includes `llms.txt` and `src/prompts/doompi-use-cache/SKILL.md`. While DoomPi
+Help is active, the extension adds `doompi-use-cache` to the live Help catalog. The contribution
+follows Help provider replacement and is removed when the extension shuts down.
 
-To add another package-owned Help prompt, use the `scaffold-doom-prompt` feature with a `doompi-author-*` or `doompi-use-*` name and a concise description. Then link the generated `SKILL.md` from `llms.txt` and register a matching descriptor through the optional `DOOM_HELP_SERVICE` injection in the Pi adapter. Keep prompts as published resources under `src/prompts`; do not export them or copy them into `dist`.
+Help is optional. The standalone Pi extension does not require DoomPi Help or another DoomPi runtime
+service.
 
 ## Public API
 
@@ -46,7 +61,8 @@ import {
 } from '@agimon-ai/doompi-cache/env';
 ```
 
-The Pi host entry is available at `@agimon-ai/doompi-cache/extensions/pi`. The root API has no import-time extension side effects.
+The Pi host entry is `@agimon-ai/doompi-cache/extensions/pi`. Importing the root API does not install
+the extension.
 
 ## Development
 
@@ -59,7 +75,8 @@ pnpm exec vibe-lint check .
 npm pack --dry-run
 ```
 
-The official OpenAI canary is opt-in and reports provider `cached_tokens` without treating a cold result as a deterministic failure:
+The live OpenAI canary is opt-in. It reports provider `cached_tokens`; a cold result does not fail
+the test deterministically:
 
 ```bash
 DOOMPI_CACHE_LIVE_OPENAI=1 \
@@ -73,3 +90,9 @@ Maintained by [Agimon](https://agimon.ai/about).
 ## License
 
 MIT
+
+## Extension lifecycle and source layout
+
+`src/extensions/pi.ts` awaits the upstream optimizer before mounting Cache so its provider hook runs after the optimizer. The named declaration contributes the telemetry service, optional mode-catalog subscription, events, and Help resource. `onDispose` restores owned environment values and resets telemetry after registrations are removed.
+
+`src/extensions/server.ts` declares session hooks and resources from `controllers/cacheHooks.ts`. Shared policy and runtime logic live in `services/<name>/`, telemetry state lives in `models/`, and environment keys live in `constants/`. Flat `src/exports/` files publish reusable capabilities. The server plugin is exported only through `extensions/server`.

package/dist/api-contracts.cjs

@@ -0,0 +1,7 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+const require_apiContracts = require("./src/schemas/apiContracts.cjs");
+exports.apiContracts = require_apiContracts.apiContracts;
+exports.default = require_apiContracts.apiContracts;

package/dist/api-contracts.d.cts

@@ -0,0 +1,2 @@
+import { apiContracts } from "./src/schemas/apiContracts.cjs";
+export { apiContracts, apiContracts as default };

package/dist/api-contracts.d.mts

@@ -0,0 +1,2 @@
+import { apiContracts } from "./src/schemas/apiContracts.mjs";
+export { apiContracts, apiContracts as default };

package/dist/api-contracts.mjs

@@ -0,0 +1,2 @@
+import { apiContracts } from "./src/schemas/apiContracts.mjs";
+export { apiContracts, apiContracts as default };

package/dist/env.cjs

@@ -1 +1,7 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./types/environment.cjs");exports.DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV=e.DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV,exports.DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV=e.DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV,exports.DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV=e.DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV,exports.PI_CACHE_RETENTION_ENV=e.PI_CACHE_RETENTION_ENV,exports.PI_CACHE_RETENTION_LONG=e.PI_CACHE_RETENTION_LONG;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_environment = require("./src/constants/environment.cjs");
+exports.DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV = require_environment.DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV;
+exports.DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV = require_environment.DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV;
+exports.DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV = require_environment.DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV;
+exports.PI_CACHE_RETENTION_ENV = require_environment.PI_CACHE_RETENTION_ENV;
+exports.PI_CACHE_RETENTION_LONG = require_environment.PI_CACHE_RETENTION_LONG;

package/dist/env.d.cts

@@ -1,2 +1,2 @@
-import { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG } from "./types/environment.cjs";
+import { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG } from "./src/constants/environment.cjs";
 export { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG };

package/dist/env.d.mts

@@ -1,2 +1,2 @@
-import { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG } from "./types/environment.mjs";
+import { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG } from "./src/constants/environment.mjs";
 export { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG };

package/dist/env.mjs

@@ -1 +1,2 @@
-import{DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV as e,DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV as t,DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV as n,PI_CACHE_RETENTION_ENV as r,PI_CACHE_RETENTION_LONG as i}from"./types/environment.mjs";export{e as DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV,t as DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV,n as DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV,r as PI_CACHE_RETENTION_ENV,i as PI_CACHE_RETENTION_LONG};
+import { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG } from "./src/constants/environment.mjs";
+export { DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV, DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV, DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV, PI_CACHE_RETENTION_ENV, PI_CACHE_RETENTION_LONG };

package/dist/extensions/pi.cjs

@@ -1,2 +1,459 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});let e=require("@agimon-ai/doompi-config/harnessStore"),t=require("@agimon-ai/doompi-extension-contracts/cordis-host"),n=require("@agimon-ai/doompi-extension-contracts/help"),r=require("@agimon-ai/doompi-extension-contracts/mode"),i=require("node:crypto"),a=require("@deepseek-ai/cordis");var o=class{#e;#t={capability:`unknown`};#n=[];constructor(e=64){if(!Number.isInteger(e)||e<1)throw Error(`Prompt cache telemetry limit must be a positive integer.`);this.#e=e}beginRequest(e){this.#t={...e}}observe(e,t){let n=this.#t.namespace,r=this.#t.modelFingerprint;!n||!r||(this.#n.push({namespace:n,modelFingerprint:r,cacheRead:e.cacheRead,cacheWrite:e.cacheWrite,totalInput:e.totalInput,observedAt:t}),this.#n.length>this.#e&&this.#n.splice(0,this.#n.length-this.#e))}snapshot(){let e=[...this.#n];return{...this.#t,residency:`unknown`,observations:e,...e.length>0?{lastObservation:e.at(-1)}:{}}}reset(){this.#t={capability:`unknown`},this.#n=[]}};function s(e={}){return{telemetry:e.telemetry??new o,now:e.now??Date.now}}var c=class{#e;#t;#n;#r;constructor(e,t=process.env){this.#t=e,this.#e=t,this.#n={present:Object.hasOwn(t,e),value:t[e]}}set(e){this.#e[this.#t]=e,this.#r=e}restore(){this.#r!==void 0&&this.#e[this.#t]===this.#r&&(this.#n.present?this.#e[this.#t]=this.#n.value:delete this.#e[this.#t],this.#r=void 0)}};function l(e){return(0,i.createHash)(`sha256`).update(e).digest(`base64url`)}var u=class extends a.Service{telemetry;constructor(e,t){super(e,`doom/prompt-cache-telemetry`),this.telemetry=t}snapshot(){return this.telemetry.snapshot()}};function d(e){if(!Number.isFinite(e))throw Error(`Prompt cache identity cannot contain a non-finite number.`);return Object.is(e,-0)?0:e}function f(e){if(e===null)return null;if(typeof e==`string`)return e.normalize(`NFC`);if(typeof e==`boolean`)return e;if(typeof e==`number`)return d(e);if(Array.isArray(e))return e.map(e=>f(e));if(typeof e!=`object`)throw Error(`Unsupported prompt cache identity value: ${typeof e}.`);let t=e,n={};for(let e of Object.keys(t).sort((e,t)=>e.localeCompare(t))){let r=t[e];r!==void 0&&(n[e.normalize(`NFC`)]=f(r))}return n}function p(e){return JSON.stringify(f(e))}function m(e,t,n){return`${e}${n(p(t))}`}function h(e){return e?.trim().replaceAll(`\\`,`/`)||void 0}function g(e){return e.filter(({activation:e})=>e===`active`||e===`activating`).map(({source:e,id:t,modelContextVariant:n})=>({source:e,id:t,...n?{modelContextVariant:n}:{}})).sort((e,t)=>e.source.localeCompare(t.source)||e.id.localeCompare(t.id))}function _(e,t){return m(`dpr1_`,{version:1,rootSessionId:e},t)}function v(e,t){return m(`dpn1_`,{version:1,rootSession:_(e.rootSessionId,t),compositionFingerprint:e.compositionFingerprint??null,majorMode:e.majorMode,domains:[...e.domains],profile:e.profile??null,persona:h(e.persona)??null,minorModes:g(e.minorModes)},t)}function y(e,t){return m(`dpm1_`,{version:1,virtualProvider:e.virtualProvider??null,virtualModel:e.virtualModel??null,api:e.api??null,baseUrl:e.baseUrl??null,wireModel:e.wireModel??null},t)}function b(e,t,n,r,i){return m(`dpc1_`,{version:1,parentNamespace:e,scope:t,childProjection:i??null,modelFingerprint:n},r)}function x(e){let t=e.__internals_for_tests;return typeof t?.isRuntimeOptimizerEnabled==`function`&&typeof t.shouldInjectOpenAIPromptCacheKey==`function`&&t.isRuntimeOptimizerEnabled()&&t.shouldInjectOpenAIPromptCacheKey()}const S=new Set([`openai-completions`,`openai-responses`,`openai-codex-responses`,`azure-openai-responses`]),C=new Set([`anthropic-messages`,`bedrock-converse-stream`]),w=new Set([`google-generative-ai`,`google-vertex`,`google-vertex-anthropic`]);function T(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function E(e){return e.api===`openai-responses`||e.api===`openai-completions`?e.virtualProvider===`openai`?`key-and-long-retention`:`key-only`:e.api&&S.has(e.api)?`key-only`:e.api&&C.has(e.api)?`marker-only`:e.api&&w.has(e.api)?`automatic`:`unknown`}function D(e,t,n,r){if(!r||!t||!S.has(t)||!T(e))return;let i=e.prompt_cache_key;if(!(typeof i!=`string`||!i.trim()||i===n))return{...e,prompt_cache_key:n}}function O(e){if(!T(e))return;let t=e.prompt_cache_retention;return typeof t==`string`&&t.trim()?t.trim():void 0}function k(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:void 0}function A(e){return typeof e==`number`&&Number.isFinite(e)&&e>=0?e:void 0}function j(...e){for(let t of e){let e=A(t);if(e!==void 0)return e}}function M(e){let t=A(e.cacheRead),n=A(e.cacheWrite);if(t===void 0&&n===void 0)return;let r=A(e.input)??0;return{cacheRead:t??0,cacheWrite:n??0,totalInput:r+(t??0)+(n??0)}}function N(e){let t=k(e.prompt_tokens_details)??k(e.promptTokensDetails),n=k(e.input_tokens_details)??k(e.inputTokensDetails),r=j(t?.cached_tokens,t?.cachedTokens,n?.cached_tokens,n?.cachedTokens),i=j(t?.cache_write_tokens,t?.cacheWriteTokens,n?.cache_write_tokens,n?.cacheWriteTokens);if(r===void 0&&i===void 0)return;let a=(r??0)+(i??0),o=j(e.prompt_tokens,e.promptTokens,e.input_tokens,e.inputTokens);return{cacheRead:r??0,cacheWrite:i??0,totalInput:Math.max(o??a,a)}}function P(e){let t=j(e.cache_read_input_tokens,e.cacheReadInputTokens),n=j(e.cache_creation_input_tokens,e.cacheCreationInputTokens);if(t===void 0&&n===void 0)return;let r=j(e.input_tokens,e.inputTokens)??0;return{cacheRead:t??0,cacheWrite:n??0,totalInput:r+(t??0)+(n??0)}}function F(e){let t=k(e.usage_metadata)??k(e.usageMetadata)??e,n=j(t.cachedContentTokenCount,t.cached_content_token_count);if(n===void 0)return;let r=j(t.promptTokenCount,t.prompt_token_count,e.input_tokens,e.inputTokens,e.prompt_tokens,e.promptTokens);return{cacheRead:n,cacheWrite:0,totalInput:Math.max(r??n,n)}}function I(e){let t=k(k(e)?.usage);if(t)return M(t)??N(t)??P(t)??F(t)}const L=`DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE`,R=`@agimon-ai/doompi-cache`;function z(e){return typeof e==`string`&&e.trim()?e.trim():void 0}function B(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:void 0}function V(e){let t=e.state;return{source:e.descriptor.source,id:e.descriptor.id,activation:t.activation,...t.modelContextVariant?{modelContextVariant:t.modelContextVariant}:{}}}function H(e,t){let n=B(e.model),r=B(t);return{virtualProvider:z(n?.provider),virtualModel:z(n?.id),api:z(n?.api),baseUrl:z(n?.baseUrl),wireModel:z(r?.model)}}function U(e){let t=B(e);return t?.stopReason===`error`||t?.stopReason===`aborted`}function W(e){return O(e)??(process.env.PI_CACHE_RETENTION===`long`?`long`:void 0)}function G(t,n,i,a){let o=new c(L),s=new c(`DOOMPI_PROMPT_CACHE_ROOT_SESSION`),u=z(process.env[L]),d=z(process.env.DOOMPI_PROMPT_CACHE_CHILD_PROJECTION),f=!!(u&&d),p,m=u,h=[],g=()=>{if(f)return m;if(!p)return;let t=(0,e.getHarnessState)();return m=v({rootSessionId:p,compositionFingerprint:t.compositionFingerprint,majorMode:t.majorMode,domains:t.domains,profile:t.profile,persona:t.personaFile,minorModes:h},l),o.set(m),s.set(_(p,l)),m};return t.inject([r.DOOM_MINOR_MODE_CATALOG_SERVICE],e=>{if(f)return;let t=(0,r.readMinorModeCatalog)(e);if(!t)return;let n=()=>{h=t.getSnapshot().modes.map(V),g()};return n(),t.subscribe(n)}),n.on(`session_start`,(e,t)=>{f||(p=z(t.sessionManager.getSessionId()),g())}),n.on(`before_provider_request`,(e,t)=>{let n=f?u:g();if(!n)return;let r=H(t,e.payload),o=y(r,l),s=b(n,f?`child`:`parent`,o,l,d),c=D(e.payload,r.api,s,x(a));return i.telemetry.beginRequest({capability:E(r),namespace:n,modelFingerprint:o,requestedRetention:W(c??e.payload),...c?{keySuffix:s.slice(-8)}:{}}),c}),n.on(`message_end`,e=>{if(U(e.message))return;let t=I(e.message);t&&i.telemetry.observe(t,i.now())}),()=>{o.restore(),s.restore(),i.telemetry.reset()}}function K(e,t){e.inject([n.DOOM_HELP_SERVICE],e=>{let t=(0,n.requireDoomHelpService)(e).register({source:R,moduleUrl:require("url").pathToFileURL(__filename).href,skills:[{name:`doompi-use-cache`,description:`Inspect DoomPi provider prompt cache policy, routing identity, and provider-observed usage.`}]});return()=>t.dispose()}),e.effect(function*(){new u(e,t.dependencies.telemetry),yield G(e,t.pi,t.dependencies,t.optimizer)},R)}async function q(e,n=s()){let r=await Promise.resolve().then(()=>require("../pi-cache-optimizer-B7B911Pz.cjs"));if(typeof r.default!=`function`)throw Error(`Pi Cache Optimizer does not export an extension factory.`);await r.default(e);let i=await(0,t.connectDoomCordisHost)(e,R),a=i.root.plugin(K,{pi:e,dependencies:n,optimizer:r});try{await a}catch(e){try{await a.dispose()}finally{await i.dispose()}throw e}let o;e.on(`session_shutdown`,()=>o??=(async()=>{try{await a.dispose()}finally{await i.dispose()}})())}exports.activateCacheExtension=q,exports.default=q;
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let _agimon_ai_doompi_core_pi_extension = require("@agimon-ai/doompi-core/pi-extension");
+let _agimon_ai_doompi_core_extension_file = require("@agimon-ai/doompi-core/extension-file");
+let _agimon_ai_doompi_config_harnessStore = require("@agimon-ai/doompi-config/harnessStore");
+let _agimon_ai_doompi_minor_mode = require("@agimon-ai/doompi-minor-mode");
+let node_crypto = require("node:crypto");
+let _deepseek_ai_cordis = require("@deepseek-ai/cordis");
+//#region src/models/promptCacheTelemetry.ts
+const DEFAULT_OBSERVATION_LIMIT = 64;
+var PromptCacheTelemetry = class {
+	#limit;
+	#request = { capability: "unknown" };
+	#observations = [];
+	constructor(limit = DEFAULT_OBSERVATION_LIMIT) {
+		if (!Number.isInteger(limit) || limit < 1) throw new Error("Prompt cache telemetry limit must be a positive integer.");
+		this.#limit = limit;
+	}
+	beginRequest(status) {
+		this.#request = { ...status };
+	}
+	observe(usage, observedAt) {
+		const namespace = this.#request.namespace;
+		const modelFingerprint = this.#request.modelFingerprint;
+		if (!namespace || !modelFingerprint) return;
+		this.#observations.push({
+			namespace,
+			modelFingerprint,
+			cacheRead: usage.cacheRead,
+			cacheWrite: usage.cacheWrite,
+			totalInput: usage.totalInput,
+			observedAt
+		});
+		if (this.#observations.length > this.#limit) this.#observations.splice(0, this.#observations.length - this.#limit);
+	}
+	snapshot() {
+		const observations = [...this.#observations];
+		return {
+			...this.#request,
+			residency: "unknown",
+			observations,
+			...observations.length > 0 ? { lastObservation: observations.at(-1) } : {}
+		};
+	}
+	reset() {
+		this.#request = { capability: "unknown" };
+		this.#observations = [];
+	}
+};
+//#endregion
+//#region src/constants/cache.ts
+const PACKAGE_SOURCE = "@agimon-ai/doompi-cache";
+const CACHE_HELP_SKILL = {
+	name: "doompi-use-cache",
+	description: "Inspect DoomPi provider prompt cache policy, routing identity, and provider-observed usage."
+};
+//#endregion
+//#region src/constants/environment.ts
+const DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV = "DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE";
+const DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV = "DOOMPI_PROMPT_CACHE_ROOT_SESSION";
+const DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV = "DOOMPI_PROMPT_CACHE_CHILD_PROJECTION";
+//#endregion
+//#region src/services/digest/index.ts
+function sha256Base64Url(value) {
+	return (0, node_crypto.createHash)("sha256").update(value).digest("base64url");
+}
+//#endregion
+//#region src/services/environment/index.ts
+var OwnedEnvironmentValue = class {
+	#environment;
+	#name;
+	#baseline;
+	#ownedValue;
+	constructor(name, environment = process.env) {
+		this.#name = name;
+		this.#environment = environment;
+		this.#baseline = {
+			present: Object.hasOwn(environment, name),
+			value: environment[name]
+		};
+	}
+	set(value) {
+		this.#environment[this.#name] = value;
+		this.#ownedValue = value;
+	}
+	restore() {
+		if (this.#ownedValue === void 0 || this.#environment[this.#name] !== this.#ownedValue) return;
+		if (this.#baseline.present) this.#environment[this.#name] = this.#baseline.value;
+		else delete this.#environment[this.#name];
+		this.#ownedValue = void 0;
+	}
+};
+//#endregion
+//#region src/services/canonical/index.ts
+function canonicalNumber(value) {
+	if (!Number.isFinite(value)) throw new Error("Prompt cache identity cannot contain a non-finite number.");
+	return Object.is(value, -0) ? 0 : value;
+}
+function canonicalValue(value) {
+	if (value === null) return null;
+	if (typeof value === "string") return value.normalize("NFC");
+	if (typeof value === "boolean") return value;
+	if (typeof value === "number") return canonicalNumber(value);
+	if (Array.isArray(value)) return value.map((entry) => canonicalValue(entry));
+	if (typeof value !== "object") throw new Error(`Unsupported prompt cache identity value: ${typeof value}.`);
+	const record = value;
+	const result = {};
+	for (const key of Object.keys(record).sort((left, right) => left.localeCompare(right))) {
+		const entry = record[key];
+		if (entry !== void 0) result[key.normalize("NFC")] = canonicalValue(entry);
+	}
+	return result;
+}
+function canonicalJson(value) {
+	return JSON.stringify(canonicalValue(value));
+}
+//#endregion
+//#region src/services/namespace/index.ts
+const KEY_PREFIX = "dpc1_";
+const PARENT_PREFIX = "dpn1_";
+const ROOT_PREFIX = "dpr1_";
+const MODEL_PREFIX = "dpm1_";
+function digestIdentity(prefix, value, digest) {
+	return `${prefix}${digest(canonicalJson(value))}`;
+}
+function normalizedPersona(value) {
+	return value?.trim().replaceAll("\\", "/") || void 0;
+}
+function activeMinorModes(modes) {
+	return modes.filter(({ activation }) => activation === "active" || activation === "activating").map(({ source, id, modelContextVariant }) => ({
+		source,
+		id,
+		...modelContextVariant ? { modelContextVariant } : {}
+	})).sort((left, right) => left.source.localeCompare(right.source) || left.id.localeCompare(right.id));
+}
+function createRootSessionIdentity(rootSessionId, digest) {
+	return digestIdentity(ROOT_PREFIX, {
+		version: 1,
+		rootSessionId
+	}, digest);
+}
+function createParentPromptCacheNamespace(state, digest) {
+	return digestIdentity(PARENT_PREFIX, {
+		version: 1,
+		rootSession: createRootSessionIdentity(state.rootSessionId, digest),
+		compositionFingerprint: state.compositionFingerprint ?? null,
+		majorMode: state.majorMode,
+		domains: [...state.domains],
+		profile: state.profile ?? null,
+		persona: normalizedPersona(state.persona) ?? null,
+		minorModes: activeMinorModes(state.minorModes)
+	}, digest);
+}
+function createPromptCacheModelFingerprint(model, digest) {
+	return digestIdentity(MODEL_PREFIX, {
+		version: 1,
+		virtualProvider: model.virtualProvider ?? null,
+		virtualModel: model.virtualModel ?? null,
+		api: model.api ?? null,
+		baseUrl: model.baseUrl ?? null,
+		wireModel: model.wireModel ?? null
+	}, digest);
+}
+function createPromptCacheKey(parentNamespace, scope, modelFingerprint, digest, childProjection) {
+	return digestIdentity(KEY_PREFIX, {
+		version: 1,
+		parentNamespace,
+		scope,
+		childProjection: childProjection ?? null,
+		modelFingerprint
+	}, digest);
+}
+//#endregion
+//#region src/services/optimizerPolicy/index.ts
+/** Fail closed unless the pinned optimizer confirms both runtime and key routing are enabled. */
+function optimizerAllowsPromptCacheKey(optimizer) {
+	const internals = optimizer.__internals_for_tests;
+	return typeof internals?.isRuntimeOptimizerEnabled === "function" && typeof internals.shouldInjectOpenAIPromptCacheKey === "function" && internals.isRuntimeOptimizerEnabled() && internals.shouldInjectOpenAIPromptCacheKey();
+}
+//#endregion
+//#region src/services/promptCacheUsage/index.ts
+function recordValue$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function nonNegativeNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function firstNumber(...values) {
+	for (const value of values) {
+		const number = nonNegativeNumber(value);
+		if (number !== void 0) return number;
+	}
+}
+function normalizedUsage(usage) {
+	const cacheRead = nonNegativeNumber(usage.cacheRead);
+	const cacheWrite = nonNegativeNumber(usage.cacheWrite);
+	if (cacheRead === void 0 && cacheWrite === void 0) return void 0;
+	const input = nonNegativeNumber(usage.input) ?? 0;
+	return {
+		cacheRead: cacheRead ?? 0,
+		cacheWrite: cacheWrite ?? 0,
+		totalInput: input + (cacheRead ?? 0) + (cacheWrite ?? 0)
+	};
+}
+function openAiUsage(usage) {
+	const promptDetails = recordValue$1(usage.prompt_tokens_details) ?? recordValue$1(usage.promptTokensDetails);
+	const inputDetails = recordValue$1(usage.input_tokens_details) ?? recordValue$1(usage.inputTokensDetails);
+	const cacheRead = firstNumber(promptDetails?.cached_tokens, promptDetails?.cachedTokens, inputDetails?.cached_tokens, inputDetails?.cachedTokens);
+	const cacheWrite = firstNumber(promptDetails?.cache_write_tokens, promptDetails?.cacheWriteTokens, inputDetails?.cache_write_tokens, inputDetails?.cacheWriteTokens);
+	if (cacheRead === void 0 && cacheWrite === void 0) return void 0;
+	const floor = (cacheRead ?? 0) + (cacheWrite ?? 0);
+	const reportedTotal = firstNumber(usage.prompt_tokens, usage.promptTokens, usage.input_tokens, usage.inputTokens);
+	return {
+		cacheRead: cacheRead ?? 0,
+		cacheWrite: cacheWrite ?? 0,
+		totalInput: Math.max(reportedTotal ?? floor, floor)
+	};
+}
+function anthropicUsage(usage) {
+	const cacheRead = firstNumber(usage.cache_read_input_tokens, usage.cacheReadInputTokens);
+	const cacheWrite = firstNumber(usage.cache_creation_input_tokens, usage.cacheCreationInputTokens);
+	if (cacheRead === void 0 && cacheWrite === void 0) return void 0;
+	const input = firstNumber(usage.input_tokens, usage.inputTokens) ?? 0;
+	return {
+		cacheRead: cacheRead ?? 0,
+		cacheWrite: cacheWrite ?? 0,
+		totalInput: input + (cacheRead ?? 0) + (cacheWrite ?? 0)
+	};
+}
+function geminiUsage(usage) {
+	const metadata = recordValue$1(usage.usage_metadata) ?? recordValue$1(usage.usageMetadata) ?? usage;
+	const cacheRead = firstNumber(metadata.cachedContentTokenCount, metadata.cached_content_token_count);
+	if (cacheRead === void 0) return void 0;
+	const totalInput = firstNumber(metadata.promptTokenCount, metadata.prompt_token_count, usage.input_tokens, usage.inputTokens, usage.prompt_tokens, usage.promptTokens);
+	return {
+		cacheRead,
+		cacheWrite: 0,
+		totalInput: Math.max(totalInput ?? cacheRead, cacheRead)
+	};
+}
+/** Normalize only usage values carried by a provider-produced assistant message. */
+function normalizePromptCacheUsage(message) {
+	const usage = recordValue$1(recordValue$1(message)?.usage);
+	if (!usage) return void 0;
+	return normalizedUsage(usage) ?? openAiUsage(usage) ?? anthropicUsage(usage) ?? geminiUsage(usage);
+}
+//#endregion
+//#region src/services/providerPolicy/index.ts
+const ROUTING_KEY_APIS = /* @__PURE__ */ new Set([
+	"openai-completions",
+	"openai-responses",
+	"openai-codex-responses",
+	"azure-openai-responses"
+]);
+const MARKER_APIS = /* @__PURE__ */ new Set(["anthropic-messages", "bedrock-converse-stream"]);
+const AUTOMATIC_APIS = /* @__PURE__ */ new Set([
+	"google-generative-ai",
+	"google-vertex",
+	"google-vertex-anthropic"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function classifyPromptCacheCapability(model) {
+	if (model.api === "openai-responses" || model.api === "openai-completions") return model.virtualProvider === "openai" ? "key-and-long-retention" : "key-only";
+	if (model.api && ROUTING_KEY_APIS.has(model.api)) return "key-only";
+	if (model.api && MARKER_APIS.has(model.api)) return "marker-only";
+	if (model.api && AUTOMATIC_APIS.has(model.api)) return "automatic";
+	return "unknown";
+}
+function rewritePromptCacheKey(payload, api, key, enabled) {
+	if (!enabled || !api || !ROUTING_KEY_APIS.has(api) || !isRecord(payload)) return void 0;
+	const current = payload.prompt_cache_key;
+	if (typeof current !== "string" || !current.trim() || current === key) return void 0;
+	return {
+		...payload,
+		prompt_cache_key: key
+	};
+}
+function requestedPromptCacheRetention(payload) {
+	if (!isRecord(payload)) return void 0;
+	const retention = payload.prompt_cache_retention;
+	return typeof retention === "string" && retention.trim() ? retention.trim() : void 0;
+}
+//#endregion
+//#region src/services/cacheRuntime/index.ts
+function stringValue(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function recordValue(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function minorModeState(record) {
+	const state = record.state;
+	return {
+		source: record.descriptor.source,
+		id: record.descriptor.id,
+		activation: state.activation,
+		...state.modelContextVariant ? { modelContextVariant: state.modelContextVariant } : {}
+	};
+}
+function modelIdentity(ctx, payload) {
+	const model = recordValue(ctx.model);
+	const request = recordValue(payload);
+	return {
+		virtualProvider: stringValue(model?.provider),
+		virtualModel: stringValue(model?.id),
+		api: stringValue(model?.api),
+		baseUrl: stringValue(model?.baseUrl),
+		wireModel: stringValue(request?.model)
+	};
+}
+function isErrorMessage(message) {
+	const record = recordValue(message);
+	return record?.stopReason === "error" || record?.stopReason === "aborted";
+}
+function requestedRetention(payload) {
+	return requestedPromptCacheRetention(payload) ?? (process.env["PI_CACHE_RETENTION"] === "long" ? "long" : void 0);
+}
+function createCacheRuntime(dependencies, optimizer) {
+	const parentNamespaceEnvironment = new OwnedEnvironmentValue(DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV);
+	const rootSessionEnvironment = new OwnedEnvironmentValue(DOOMPI_PROMPT_CACHE_ROOT_SESSION_ENV);
+	const projectedParentNamespace = stringValue(process.env[DOOMPI_PROMPT_CACHE_PARENT_NAMESPACE_ENV]);
+	const childProjection = stringValue(process.env[DOOMPI_PROMPT_CACHE_CHILD_PROJECTION_ENV]);
+	const isProjectedChild = Boolean(projectedParentNamespace && childProjection);
+	let rootSessionId;
+	let parentNamespace = projectedParentNamespace;
+	let minorModes = [];
+	const refreshParentNamespace = () => {
+		if (isProjectedChild) return parentNamespace;
+		if (!rootSessionId) return void 0;
+		const harness = (0, _agimon_ai_doompi_config_harnessStore.getHarnessState)();
+		parentNamespace = createParentPromptCacheNamespace({
+			rootSessionId,
+			compositionFingerprint: harness.compositionFingerprint,
+			majorMode: harness.majorMode,
+			domains: harness.domains,
+			profile: harness.profile,
+			persona: harness.personaFile,
+			minorModes
+		}, sha256Base64Url);
+		parentNamespaceEnvironment.set(parentNamespace);
+		rootSessionEnvironment.set(createRootSessionIdentity(rootSessionId, sha256Base64Url));
+		return parentNamespace;
+	};
+	const plugin = (cordis) => {
+		cordis.inject([_agimon_ai_doompi_minor_mode.DOOM_MINOR_MODE_CATALOG_SERVICE], (context) => {
+			if (isProjectedChild) return void 0;
+			const catalog = (0, _agimon_ai_doompi_minor_mode.readMinorModeCatalog)(context);
+			if (!catalog) return void 0;
+			const refreshModes = () => {
+				minorModes = catalog.getSnapshot().modes.map(minorModeState);
+				refreshParentNamespace();
+			};
+			refreshModes();
+			return catalog.subscribe(refreshModes);
+		});
+	};
+	return {
+		plugin,
+		events: {
+			session_start: (_event, ctx) => {
+				if (!isProjectedChild) {
+					rootSessionId = stringValue(ctx.sessionManager.getSessionId());
+					refreshParentNamespace();
+				}
+			},
+			before_provider_request: (event, ctx) => {
+				const namespace = isProjectedChild ? projectedParentNamespace : refreshParentNamespace();
+				if (!namespace) return void 0;
+				const identity = modelIdentity(ctx, event.payload);
+				const modelFingerprint = createPromptCacheModelFingerprint(identity, sha256Base64Url);
+				const key = createPromptCacheKey(namespace, isProjectedChild ? "child" : "parent", modelFingerprint, sha256Base64Url, childProjection);
+				const rewritten = rewritePromptCacheKey(event.payload, identity.api, key, optimizerAllowsPromptCacheKey(optimizer));
+				dependencies.telemetry.beginRequest({
+					capability: classifyPromptCacheCapability(identity),
+					namespace,
+					modelFingerprint,
+					requestedRetention: requestedRetention(rewritten ?? event.payload),
+					...rewritten ? { keySuffix: key.slice(-8) } : {}
+				});
+				return rewritten;
+			},
+			message_end: (event) => {
+				if (isErrorMessage(event.message)) return;
+				const usage = normalizePromptCacheUsage(event.message);
+				if (usage) dependencies.telemetry.observe(usage, dependencies.now());
+			}
+		},
+		dispose: () => {
+			parentNamespaceEnvironment.restore();
+			rootSessionEnvironment.restore();
+			dependencies.telemetry.reset();
+		}
+	};
+}
+//#endregion
+//#region src/services/promptCacheTelemetry/index.ts
+const DOOM_PROMPT_CACHE_TELEMETRY_SERVICE = "doom/prompt-cache-telemetry";
+var PromptCacheTelemetryService = class extends _deepseek_ai_cordis.Service {
+	telemetry;
+	constructor(context, telemetry) {
+		super(context, DOOM_PROMPT_CACHE_TELEMETRY_SERVICE);
+		this.telemetry = telemetry;
+	}
+	snapshot() {
+		return this.telemetry.snapshot();
+	}
+};
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/root.cli.ts
+var root_cli_default = (0, _agimon_ai_doompi_core_extension_file.defineRoot)(async ({ pi, options }) => {
+	const dependencies = options ?? {
+		telemetry: new PromptCacheTelemetry(),
+		now: Date.now
+	};
+	const optimizer = await Promise.resolve().then(() => require("../pi-cache-optimizer-BBOw28o_.cjs"));
+	if (typeof optimizer.default !== "function") throw new Error("Pi Cache Optimizer does not provide an extension factory.");
+	await optimizer.default(pi);
+	const runtime = createCacheRuntime(dependencies, optimizer);
+	return {
+		value: runtime,
+		services: [(context) => {
+			new PromptCacheTelemetryService(context, dependencies.telemetry);
+		}, runtime.plugin],
+		onDispose: () => runtime.dispose()
+	};
+});
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/resource/doompi-use-cache.cli.ts
+var doompi_use_cache_cli_default = (0, _agimon_ai_doompi_core_extension_file.defineResource)({
+	source: PACKAGE_SOURCE,
+	moduleUrl: require("url").pathToFileURL(__filename).href,
+	skills: [CACHE_HELP_SKILL]
+});
+//#endregion
+//#region generated/pi.ts
+const at = (value, context) => typeof value === "function" ? value(context) : value;
+const extension = (0, _agimon_ai_doompi_core_pi_extension.definePiExtension)("@agimon-ai/doompi-cache", async (context) => {
+	const scopeSession = await root_cli_default(context);
+	const contextSession = {
+		...context,
+		root: scopeSession.value
+	};
+	return {
+		...(0, _agimon_ai_doompi_core_extension_file.composeRootHooks)(scopeSession),
+		get resources() {
+			return [at(doompi_use_cache_cli_default, contextSession)];
+		},
+		services: [...scopeSession.services ?? []]
+	};
+});
+//#endregion
+exports.default = extension;
+exports.extension = extension;
+
 //# sourceMappingURL=pi.cjs.map