@agimon-ai/po-cache

Provider prompt-cache policy and deterministic routing for Po.

Po 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.

Alpha: cache routing and provider integration may change between releases.

Requirements

• Node.js 24 or newer

Install

A Po installation already includes this package. Do not add it to .po/modes.yaml.

Package behavior

Po 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 native session contribution 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 src/prompts/po-use-cache/SKILL.md. While Po Help is active, the extension adds po-use-cache to the live Help catalog. The contribution follows Help provider replacement and is removed when the extension shuts down.

Public API

import {
  createChildPromptCacheProjection,
  createParentPromptCacheNamespace,
  createPromptCacheKey,
  PromptCacheTelemetry,
} from '@agimon-ai/po-cache';
import { PO_PROMPT_CACHE_PARENT_NAMESPACE_ENV, PO_PROMPT_CACHE_ROOT_SESSION_ENV } from '@agimon-ai/po-cache/env';

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint
pnpm exec vibe-lint check .
npm pack --dry-run

The live OpenAI canary is opt-in. It reports provider cached_tokens; a cold result does not fail the test deterministically:

PO_CACHE_LIVE_OPENAI=1 \
OPENAI_API_KEY=... \
PO_CACHE_LIVE_OPENAI_MODEL=... \
pnpm exec vitest run tests/live/openaiPromptCache.live.test.ts

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

Extension lifecycle and source layout

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.