@agimon-ai/po-cache

Provider prompt cache policy and deterministic routing for Po

Packages

Package details

extension

Install @agimon-ai/po-cache from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@agimon-ai/po-cache
Package
@agimon-ai/po-cache
Version
0.0.0-alpha.183
Published
Nov 22, 2026
Downloads
35.6K/mo · 5,793/wk
Author
agiflow-ai
License
BUSL-1.1
Types
extension
Size
929.6 KB
Dependencies
5 dependencies · 1 peer

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@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/presets.yaml.

Package behavior

Po derives an opaque provider cache key from stable model-visible state: the composition fingerprint, ordered domains, profile, persona, active 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.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint
npm pack --dry-run

Repository agents run architectural checks through the lint code-mode namespace.

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.