# @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

```ts
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

```bash
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:

```bash
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](https://agimon.ai/about).

## License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See [LICENSE](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`.