@agimon-ai/doompi-cache 0.0.1-alpha.5 → 0.0.1-alpha.50

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.3
+- 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/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/doompi-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,gDAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/doompi-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

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.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/mcp.cjs

@@ -0,0 +1,26 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let _agimon_ai_doompi_core_mcpFacet = require("@agimon-ai/doompi-core/mcpFacet");
+let _agimon_ai_doompi_core_serverFacet = require("@agimon-ai/doompi-core/serverFacet");
+//#region src/extensions/workspaces/sessions/(backend)/skill/doompi-use-cache.mcp.ts
+var doompi_use_cache_mcp_default = (0, _agimon_ai_doompi_core_mcpFacet.defineMcpSkill)({
+	name: "doompi-use-cache",
+	description: "Inspect DoomPi provider prompt cache policy, routing identity, and provider-observed usage.",
+	read: () => (0, _agimon_ai_doompi_core_serverFacet.readPackageResource)(require("url").pathToFileURL(__filename).href, "src/prompts/doompi-use-cache/SKILL.md")
+});
+//#endregion
+//#region generated/mcp.ts
+const at = (value, context) => typeof value === "function" ? value(context) : value;
+const mcp = (0, _agimon_ai_doompi_core_mcpFacet.defineMcpPlugin)({
+	name: "@agimon-ai/doompi-cache",
+	session: (context) => ({ get skills() {
+		return [at(doompi_use_cache_mcp_default, context)];
+	} })
+});
+//#endregion
+exports.default = mcp;
+exports.mcp = mcp;
+
+//# sourceMappingURL=mcp.cjs.map

package/dist/extensions/mcp.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.cjs","names":["defineMcpSkill","readPackageResource","defineMcpPlugin","skillDoompiUseCache"],"sources":["../../src/extensions/workspaces/sessions/(backend)/skill/doompi-use-cache.mcp.ts","../../generated/mcp.ts"],"sourcesContent":["import { defineMcpSkill } from '@agimon-ai/doompi-core/mcpFacet';\nimport { readPackageResource } from '@agimon-ai/doompi-core/serverFacet';\n\nexport default defineMcpSkill({\n  name: 'doompi-use-cache',\n  description: 'Inspect DoomPi provider prompt cache policy, routing identity, and provider-observed usage.',\n  read: () => readPackageResource(import.meta.url, 'src/prompts/doompi-use-cache/SKILL.md'),\n});\n","// Generated by @agimon-ai/doompi-build. Do not edit by hand.\nimport { defineMcpPlugin, type DoomMcpSessionPlugin } from '@agimon-ai/doompi-core/mcpFacet';\n\nimport skillDoompiUseCache from '../src/extensions/workspaces/sessions/(backend)/skill/doompi-use-cache.mcp';\n\ntype Factory<T, C> = (context: C) => T;\nconst at = <T, C>(value: T | Factory<T, C>, context: C): T =>\n  typeof value === 'function' ? (value as Factory<T, C>)(context) : value;\n\nexport const mcp = defineMcpPlugin({\n  name: '@agimon-ai/doompi-cache',\n  session: (context) => ({\n    get skills(): DoomMcpSessionPlugin['skills'] { return [at(skillDoompiUseCache, context)]; },\n  }) satisfies DoomMcpSessionPlugin,\n});\n\nexport default mcp;\n"],"mappings":";;;;;;;AAGA,IAAA,gCAAA,GAAeA,gCAAAA,eAAAA,CAAe;CAC5B,MAAM;CACN,aAAa;CACb,aAAA,GAAYC,mCAAAA,oBAAAA,CAAAA,QAAAA,KAAAA,CAAAA,CAAAA,cAAAA,UAAAA,CAAAA,CAAAA,MAAqC,uCAAuC;AAC1F,CAAC;;;ACDD,MAAM,MAAY,OAA0B,YAC1C,OAAO,UAAU,aAAc,MAAwB,OAAO,IAAI;AAEpE,MAAa,OAAA,GAAMC,gCAAAA,gBAAAA,CAAgB;CACjC,MAAM;CACN,UAAU,aAAa,EACrB,IAAI,SAAyC;EAAE,OAAO,CAAC,GAAGC,8BAAqB,OAAO,CAAC;CAAG,EAC5F;AACF,CAAC"}

package/dist/extensions/mcp.d.mts

@@ -0,0 +1,5 @@
+//#region generated/mcp.d.ts
+export declare const mcp: import("@agimon-ai/doompi-core/mcpFacet").DoomMcpPluginDefinition;
+//#endregion
+export { mcp as default };
+//# sourceMappingURL=mcp.d.mts.map

package/dist/extensions/mcp.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.mts","names":[],"sources":["../../generated/mcp.ts"],"mappings":";qBASa,+CAAG"}

package/dist/extensions/mcp.mjs

@@ -0,0 +1,21 @@
+import { defineMcpPlugin, defineMcpSkill } from "@agimon-ai/doompi-core/mcpFacet";
+import { readPackageResource } from "@agimon-ai/doompi-core/serverFacet";
+//#region src/extensions/workspaces/sessions/(backend)/skill/doompi-use-cache.mcp.ts
+var doompi_use_cache_mcp_default = defineMcpSkill({
+	name: "doompi-use-cache",
+	description: "Inspect DoomPi provider prompt cache policy, routing identity, and provider-observed usage.",
+	read: () => readPackageResource(import.meta.url, "src/prompts/doompi-use-cache/SKILL.md")
+});
+//#endregion
+//#region generated/mcp.ts
+const at = (value, context) => typeof value === "function" ? value(context) : value;
+const mcp = defineMcpPlugin({
+	name: "@agimon-ai/doompi-cache",
+	session: (context) => ({ get skills() {
+		return [at(doompi_use_cache_mcp_default, context)];
+	} })
+});
+//#endregion
+export { mcp as default, mcp };
+
+//# sourceMappingURL=mcp.mjs.map

package/dist/extensions/mcp.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.mjs","names":["skillDoompiUseCache"],"sources":["../../src/extensions/workspaces/sessions/(backend)/skill/doompi-use-cache.mcp.ts","../../generated/mcp.ts"],"sourcesContent":["import { defineMcpSkill } from '@agimon-ai/doompi-core/mcpFacet';\nimport { readPackageResource } from '@agimon-ai/doompi-core/serverFacet';\n\nexport default defineMcpSkill({\n  name: 'doompi-use-cache',\n  description: 'Inspect DoomPi provider prompt cache policy, routing identity, and provider-observed usage.',\n  read: () => readPackageResource(import.meta.url, 'src/prompts/doompi-use-cache/SKILL.md'),\n});\n","// Generated by @agimon-ai/doompi-build. Do not edit by hand.\nimport { defineMcpPlugin, type DoomMcpSessionPlugin } from '@agimon-ai/doompi-core/mcpFacet';\n\nimport skillDoompiUseCache from '../src/extensions/workspaces/sessions/(backend)/skill/doompi-use-cache.mcp';\n\ntype Factory<T, C> = (context: C) => T;\nconst at = <T, C>(value: T | Factory<T, C>, context: C): T =>\n  typeof value === 'function' ? (value as Factory<T, C>)(context) : value;\n\nexport const mcp = defineMcpPlugin({\n  name: '@agimon-ai/doompi-cache',\n  session: (context) => ({\n    get skills(): DoomMcpSessionPlugin['skills'] { return [at(skillDoompiUseCache, context)]; },\n  }) satisfies DoomMcpSessionPlugin,\n});\n\nexport default mcp;\n"],"mappings":";;;AAGA,IAAA,+BAAe,eAAe;CAC5B,MAAM;CACN,aAAa;CACb,YAAY,oBAAoB,YAAY,KAAK,uCAAuC;AAC1F,CAAC;;;ACDD,MAAM,MAAY,OAA0B,YAC1C,OAAO,UAAU,aAAc,MAAwB,OAAO,IAAI;AAEpE,MAAa,MAAM,gBAAgB;CACjC,MAAM;CACN,UAAU,aAAa,EACrB,IAAI,SAAyC;EAAE,OAAO,CAAC,GAAGA,8BAAqB,OAAO,CAAC;CAAG,EAC5F;AACF,CAAC"}