@arnilo/prism 0.1.6 → 0.1.7

package/docs/index.md

@@ -8,7 +8,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 ## Identity and governance
 - [Agent identity](agent-identity.md): host-verified `Principal` / `AgentIdentity`, delegation narrowing, ownership projection, and redacted telemetry refs for enterprise runs/tools/MCP/A2A/workflows; optional OIDC/JWKS verifier adapter (`@arnilo/prism-credentials-node/oidc` — pinned issuer/audience/JWKS, bounded claims, fail closed).
 - [Policy and audit](policy-and-audit.md): optional `@arnilo/prism-policy` decision ledger (allow/deny/modify/approval), evidence refs only, cursor-paginated WORM export, and durable PostgreSQL composition; 0.0.28 adds the OPA REST evaluator (`@arnilo/prism-policy/opa` — pinned SSRF-checked endpoint, redacted input, fail-closed deny, optional bundle-revision pin).
-- [Model routing](model-routing.md): optional `@arnilo/prism-model-router` allow-list/residency/budget/rate/circuit/fallback governance with redacted diagnostics; durable state requires awaited identity-scoped calls.
+- [Model routing](model-routing.md): optional `@arnilo/prism-model-router` allow-list/residency/budget/rate/circuit/fallback governance with redacted diagnostics; durable state requires awaited identity-scoped calls; host-configurable selection policies (reference cost/latency policy ranks by `ModelCost` then in-memory latency EMA fed from `recordOutcome`).
 
 ## Agent/session runtime
 - [Agent/session runtime](agent-session-runtime.md): create explicit or opt-in secure agents/sessions, get direct `AgentRunResult` values from `run`/`prompt`, mid-run `steer` (turn-boundary or softInterrupt), use integrated `stream()`/`resumeAgentRunStream()`, shared batch pending-decisions / sticky run-scope approvals, subscribe to normalized events, and expose opted-in durable lifecycle capabilities (0.1.6 plan 018 closeout `checkpoint-bodies`: optional `includeSkillBodies` persists the exact loaded-skill instructions with the names-only `persistSessionState`, so resume re-renders bodies registry-independently; ≤64 bodies, `maxStateBytes` refuses oversize).
@@ -43,7 +43,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Provider primitives](provider-primitives.md): shared bounded transport and OpenAI serialization helpers — migrated across first-party providers; native structured-output and observability contracts.
 - [Provider layer](provider-layer.md): register and resolve host-owned providers/models, choose replace-or-error duplicate policy, create provider events, stream/reconstruct tool-call deltas, use generic provider request options, and test with the mock provider; deprecated provider-level timeout/retry hints point to runtime abort/retry.
 - [Model registry](model-registry.md): register and resolve `ModelConfig` records with capabilities, limits, cost, cache support metadata, compat data, and duplicate policy.
-- [Provider caching](provider-caching.md): use `PromptCacheHints`, `PromptCacheBreakpoint`, `ModelCacheCapabilities`, cache-aware stable-prefix guidance, and shared cache diagnostics helpers; includes the complete per-provider explicit/implicit cache matrix plus no-Prism-cache entries (including Anthropic, Google, Alibaba, Ollama, cloud adapters, and host-owned AI SDK); cache hints are best-effort and cache keys are never secrets.
+- [Provider caching](provider-caching.md): use `PromptCacheHints`, `PromptCacheBreakpoint`, `ModelCacheCapabilities`, cache-aware stable-prefix guidance, and shared cache diagnostics helpers; includes the complete per-provider explicit/implicit cache matrix plus no-Prism-cache entries (including Anthropic, Google, Alibaba, Ollama, cloud adapters, and host-owned AI SDK); cache hints are best-effort and cache keys are never secrets; `createCacheTelemetry()` aggregates per-provider/model hit rate and cache-token totals from the `usage` event stream for tuning the `cache_aware` layout.
 - [Thinking and reasoning](thinking-and-reasoning.md): portable `ThinkingLevel` helpers (`applyThinkingLevel` / `thinkingCompatFor`) map per-turn effort into provider `compat` fields; model defaults stay on `ModelConfig.compat`; no second options tree.
 - [Use-case model selection](use-case-model-selection.md): bind `{ model?, provider?, thinkingLevel? }` for observational memory, LLM compaction, and other non-session LLM jobs with explicit session-model fallback via `resolveUseCaseModel`.
 - [Provider request policies](provider-request-policies.md): chain `ProviderRequestPolicy` hooks, use `createSessionCachePolicy`, and merge legacy/structured cache options safely.
@@ -103,7 +103,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [AG-UI adoption evaluation](ag-ui-adoption.md): official 0.0.57 input/event/capability matrix and shipped hardened MCP/MCP Apps/A2A handshake boundaries.
 
 ## CLI/RPC
-- [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including mid-run `steer`, branch-handle results, fixed `forkSession`, and `checkout`. `prism init` scaffolds a tiny TypeScript project with one selected provider and an offline mock test.
+- [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including mid-run `steer`, branch-handle results, fixed `forkSession`, and `checkout`. `prism init` scaffolds a tiny TypeScript project with one selected provider and an offline mock test; `prism providers add <name>` scaffolds an OpenAI-compatible provider package (manifest, provider, models, cache helpers, conformance test, docs stub).
 - [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume, schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Interactive TUI (C-012) deferred.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): architecture inventory — workflow adapters consume core `CheckpointStore`, `LeaseStore`, and bounded `EventMultiplexer`; run control and optional RPC commands stay package-local.
 - [Workflow/TUI scope](workflow-tui-primitives.md): records why 0.0.5 ships workflow APIs/RPC control but no interactive terminal UI.
@@ -129,7 +129,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-ponytail` — upstream Ponytail skills/commands, `ponytail-mode` injector, session `ponytail-mode` persistence; resolves peer `@dietrichgebert/ponytail` or `upstreamPath`; opt-in (not in code/sdk profiles).
 
 ## Release and install
-- [Release and install](release-and-install.md): current **0.1.6** 50-package graph (root + 49 workspace packages, including the plan 018 optional `@arnilo/prism-document-reader` — the graph grew 49 → 50 because its doc-reader closeout was demanded; plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates.
+- [Release and install](release-and-install.md): current **0.1.7** 50-package graph (root + 49 workspace packages, including the plan 018 optional `@arnilo/prism-document-reader` — the graph grew 49 → 50 because its doc-reader closeout was demanded; plan 019 the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates.
 - [0.1.0 / 1.0 readiness gates](0.1.0-readiness.md): command-per-gate 1.0 readiness table — frozen API surface + compat gate, migration/docs tripwires, budget table, live-suite matrix, security matrix, current-line status (**0.0.23** published target), signed-publication/live-canary prerequisites for 1.0, and Phase 12 demand-evidence entry criteria.
 - [Review coverage archive](_evidence/): per-phase evidence freezes (plans 067–079, releases 0.0.4–0.0.16) — traceability matrices, provider validation, capability/primitive/limit matrices, benchmark budgets, and artifact-diet findings; tarball-excluded, kept in-repo for audit.
 

package/docs/model-routing.md

@@ -91,6 +91,51 @@ await enterprise.close();
 
 Router is optional. Chain returned `providerRequestPolicy` with other `ProviderRequestPolicy` values. Wire `onDiagnostics` to `@arnilo/prism-policy` when audit export is required. OpenRouter package behavior is unchanged; routing metadata participates only when this gate allows it.
 
+### Selection policies (0.1.7)
+
+By default the router tries candidates in input order: the primary model, then
+`fallbacks` in order. A host can instead supply a `selection` policy on
+`createModelRouter` to rank the candidates before the governance checks run:
+
+```ts
+import { createCostLatencySelection, createModelRouter } from "@arnilo/prism-model-router";
+
+const router = createModelRouter({
+  resolver,
+  selection: createCostLatencySelection({ latencyWeight: 0.5 }),
+  fallbacks: [cheaperModel],
+});
+
+// host-measured provider-call latency feeds the policy's EMA:
+await router.recordOutcome({ identity, provider, model, success: true, latencyMs: 412 });
+```
+
+`ModelRouterSelectionPolicy` is `{ name, rank(candidates, request), observe? }`:
+
+- `rank` must return a **permutation** of the input candidates. Any other
+  result (added, dropped, or duplicated candidates) fails closed with
+  `ERR_PRISM_MODEL_ROUTER_POLICY` — a policy can never widen the allow-list,
+  residency, or budget decisions, because those checks still run per candidate
+  after ranking.
+- `observe` receives outcome feedback from `router.recordOutcome`, including
+  the host-supplied `latencyMs` (validated finite non-negative).
+- The policy name is recorded in selection diagnostics (the redaction cap
+  still applies). Absent `selection`, behavior is identical to 0.1.6.
+
+`createCostLatencySelection()` is the reference policy:
+
+- Ranks by unit price first: `ModelCost.input` + `output` + `cacheRead`,
+  normalized by the cost unit (`per_million_tokens` vs per-token). Models
+  without valid cost metadata rank after all priced models, preserving their
+  relative input order.
+- Breaks cost ties by recent measured latency — an in-memory per-
+  provider/model EMA fed from `recordOutcome` `latencyMs`. Cold start (no
+  samples) is pure cost order.
+- `latencyWeight` (default 0.5) is the EMA smoothing factor: 0 keeps the
+  first sample, 1 tracks only the latest. `ponytail:` the EMA is in-memory and
+  process-local; durable latency statistics would require a
+  `ModelRouterStateStore` contract change and are demand-gated.
+
 ## Security and performance notes
 
 - Allow-list and residency denies never call the underlying resolver.

package/docs/provider-caching.md

@@ -220,6 +220,69 @@ Static featured catalogs remain offline bootstrap and must **not** invent pricin
 - Cache usage reports contain only usage counts and optional pricing/currency; they do not include prompt text, cache keys, headers, credentials, or provider payloads.
 - `applyCacheControl()` returns new message objects for stamped anchors and does not mutate input messages.
 
+## Cache telemetry
+
+### What it does
+
+`createCacheTelemetry()` is a dependency-free aggregator that turns the per-call
+`Usage.cacheReadTokens`/`cacheWriteTokens` counters into per-provider/model
+statistics hosts can use to tune the `cache_aware` input layout: request count,
+cache-read/write token totals, hit rate, and an estimated read-token savings
+when the model carries cost metadata.
+
+### When to use it
+
+Use it when you want to observe cache effectiveness per provider/model over a
+session, a day, or a run ledger. It is opt-in by construction: importing the
+module never collects anything — the host explicitly wires `record()` to its
+`usage` `ProviderEvent` stream or to run-ledger usage records.
+
+### Inputs / request
+
+| Input | Meaning |
+| --- | --- |
+| `usage` (`Usage`) | One usage record: `cacheReadTokens`, `cacheWriteTokens`, `inputTokens` are validated (non-negative safe integers; a violation throws `CacheTelemetryError` and mutates nothing). |
+| `model` (`ModelConfig?`) | Attribution key (`provider` + `model`). Omit it for provider-only aggregation into the `unknown` bucket. Cost metadata (`ModelCost.input`/`cacheRead`) enables `estimatedSavings`. |
+| `options.maxKeys` | Distinct provider/model keys before excess keys collapse into the `__overflow__` bucket (default `DEFAULT_CACHE_TELEMETRY_CAP` = 256). |
+
+### Outputs / response / events
+
+`report()` returns `{ samples, overflowed, totalRequests, totalCacheReadTokens,
+totalCacheWriteTokens }`. Each sample carries `provider`, `model`, `requests`,
+`cacheReadTokens`, `cacheWriteTokens`, `inputTokens`, `hitRate` (total reads /
+total input — the same math as `cacheHitRate()`), and `estimatedSavings` with
+`currency` only when the model has cost metadata. Samples are sorted by
+provider then model. `reset()` clears all samples; `size` reports the current
+distinct-key count.
+
+### Request/response example
+
+```ts
+import { createCacheTelemetry } from "@arnilo/prism";
+
+const telemetry = createCacheTelemetry();
+for await (const event of provider.generate(request)) {
+  if (event.type === "usage") telemetry.record(event.usage, request.model);
+}
+
+const report = telemetry.report();
+for (const sample of report.samples) {
+  console.log(sample.provider, sample.model, sample.hitRate, sample.cacheReadTokens);
+}
+```
+
+### Security and performance notes
+
+- Reports carry token counters, rates, currency, and provider/model names only
+  — never prompt content, cache keys, headers, credentials, or identity fields
+  (redaction-safe by construction).
+- Cardinality is bounded: beyond `maxKeys` distinct provider/model keys, excess
+  keys accumulate in a single `__overflow__` bucket; memory cannot grow with
+  hostile model names (`ponytail:` ceiling — upgrade to host-configurable caps
+  or LRU eviction only if a real deployment exceeds it).
+- `record()` is O(1) per usage event; `report()` is O(keys). No secrets or
+  cache keys are accepted or stored.
+
 ## Related APIs
 
 - [Input and prompt assembly](input-and-prompt-assembly.md): opt-in cache-aware ordering for stable provider payload prefixes.

package/docs/provider-packages.md

@@ -74,6 +74,8 @@ First-party providers map generic `ModelConfig.parameters.maxTokens` to real out
 
 ## First-party provider package skeletons
 
+Scaffold new OpenAI-compatible provider packages with `prism providers add <name>` (see [CLI/RPC](cli-rpc.md#prism-providers-add-017)): it generates the manifest, provider (`createOpenAICompatibleProvider`), starter models, cache-hint helpers, an offline conformance test, and a docs stub — mirroring the first-party skeleton conventions below. Scaffold output is host-chosen and never auto-registered.
+
 Phase 12 adds explicit npm workspaces for [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), [`@arnilo/prism-provider-kimi`](providers/kimi.md), and [`@arnilo/prism-provider-neuralwatt`](providers/neuralwatt.md). Each package starts with a side-effect-free `create*ProviderPackage()` export, README, TypeScript build, network-free default tests, and real opt-in live smoke tests.
 
 Phase 6 also adds optional [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md), which adapts a host-owned AI SDK `LanguageModelV4` to Prism's `AIProvider`. It joins `@arnilo/prism-providers` as the seventh adapter while remaining independent from the six HTTP implementations.

package/docs/release-and-install.md

@@ -274,6 +274,30 @@ git push origin v0.1.2        # tag push triggers release.yml publish job (prove
 
 **Rollback notes.** `release:publish --version 0.1.2 --resume --report release-artifacts/publish-report.json` resumes an interrupted publication and skips only registry versions whose internal dependency fingerprint matches the local manifest. A failed package aborts the run with its status written to the report; re-run after fixing the cause. npm cannot unpublish the `0.1.2` line after 72 hours — a post-publication defect ships as a `0.1.x` patch (additive-only compat promise, `release:gate` enforced), or as a documented break in the next line with a `docs/migration.md` entry. `0.1.2` is store-compatible with `0.1.1` in **both directions** (no migration ran — same checksum-protected contract), so an operator may defer or roll back the patch without a database rollback.
 
+### 0.1.7 publish handoff (plan 019 Task 6)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.1.7** (plan 019) is the performance-and-DX patch on the frozen 0.1.x line — **additive-only** vs 0.1.6 (plain compat gate at 0.1.7 passed with 0 breaking declaration deltas; the baseline text was regenerated with `--update-baseline` for the version literal only, no `--allow-break` anywhere; freeze manifest `scripts/phase19-freeze-manifest.json` machine-checks each task's diff stayed inside its allowed files). Shipped: (1) **prompt-cache telemetry surface** — dependency-free `createCacheTelemetry()` aggregator in core, host-activated, per-provider/model request counts + aggregate hit rate + cache-read/write token totals + estimated savings, bounded cardinality (cap 256 distinct keys, `__overflow__` bucket), token counters/rates only (never prompt content, cache keys, or identity), O(1) `record()`; (2) **model-router selection policies** — additive `ModelRouterSelectionPolicy` on `createModelRouter` (default ordered behavior byte-identical) with the reference `createCostLatencySelection` ranking by `ModelCost` then in-memory latency EMA fed from `recordOutcome({ latencyMs })`, permutation-only reorder of already-allowed candidates, misbehavior fails closed `ERR_PRISM_MODEL_ROUTER_POLICY`; (3) **async AgUiProjection closeout** — plan 009 Task 15 surface verified with evidence (`asyncHooks: {verified: true, gapFound: false}` in `scripts/phase19-baseline.json`), no new code; (4) **`prism providers add <name>` scaffold** — new CLI subcommand generating an OpenAI-compatible provider package (manifest, provider via `createOpenAICompatibleProvider`, starter models, cache helpers, offline conformance test, docs stub) with npm-name/traversal/symlink-escape validation and placeholders only — never secrets; scaffold output is host-chosen and never auto-registered. Store compatibility with 0.1.6: **compatible, no migration** (additive-only; no persisted-shape change; `docs/migration.md` gains no entries). Exit gate green: npm test core + script gates (incl. phase19-freeze done-phase), `sdk:ready` exit 0, audit 0 moderate, pack dry-run 50/50 twice byte-identical, budget/benchmark gates green; evidence in `scripts/phase19-baseline.json` `exitGate`. Rollback = restore the 0.1.6 manifests/tag.
+
+```bash
+# Operator prerequisites recorded: clean tree at the v0.1.7 tag candidate, GPG key, npm OIDC publisher.
+npm test                                        # core + workspace suites + all script gates
+npm run sdk:ready                               # typecheck, lint, format, test, pack, release:gate
+node scripts/release.mjs gate --version 0.1.7   # plain additive gate, 0 breaking deltas
+npm run pack:dry-run                            # twice; diff reports — deterministic
+npm audit --audit-level=moderate
+npm run release:check -- --version 0.1.7 --report /tmp/prism-0.1.7-preflight.json
+npm run release:publish -- --version 0.1.7 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.1.7-dry-run.json
+#   run the dry-run twice and diff the reports: deterministic, byte-identical
+
+# Sign the release on the clean tagged tree (operator GPG key):
+git tag -s v0.1.7 -m "Prism 0.1.7 — performance and DX (additive)"
+git verify-tag v0.1.7
+git push origin v0.1.7        # tag push triggers release.yml publish job (provenance, attestations)
+
+# Real publication never bypasses the gates: release.mjs refuses
+# --allow-dirty/--allow-untagged without --dry-run.
+```
+
 ### 0.1.6 publish handoff (plan 018 Task 7)
 
 **Decision: GO when the operator prerequisites below are recorded.** Release **0.1.6** (plan 018) is the coding-agent capability-closeouts patch on the frozen 0.1.x line — **additive-only** vs 0.1.5 (plain compat gate at 0.1.6 passed with 0 breaking declaration deltas; the baseline text was regenerated with `--update-baseline` for the version literal only, no `--allow-break` anywhere). Five demand-gated closeouts shipped, each flipped to `demanded` by named demand evidence (operator `arn` for native-sandbox/doc-reader/delete-glob/checkpoint-bodies, user `Clay` for acp-session-store) before its task landed; the demand-gate registry (`scripts/phase18-freeze-manifest.json`) machine-checks demanded ⇒ implemented, deferred ⇒ untouched. Shipped: (1) **durable ACP session store** — `@arnilo/prism-ag-ui` `AcpSessionStore` host seam (`save`/`loadAll`/`evict`), persisted `{sessionId, ownership, modeId, configValues, cwd, additionalDirectories, updatedAt}`, lazy ownership-scoped restore, fail-closed drops, absent seam = 0.1.5 behavior; (2) **network-free native sandbox** — `createNativeSandbox` in `@arnilo/prism-coding-security` (fresh netns per command via the OS `unshare` binary, chained ulimits with `|| exit 126`, argv-only exec, cwd containment, process-group kill, env allow-list, Linux-only fail-closed); (3) **bounded PDF/Office document reader** — new optional package `@arnilo/prism-document-reader` (the 50th manifest, graph 49 → 50) with optional `pdf-parse`/`mammoth` peers fail-closed at creation, magic-byte gating, null fall-through, caps + redaction at the adapter boundary; (4) **recursive delete + brace-expanding glob** — per-call `recursive: true` with fan-out cap and symlink-unlink-not-follow, host-selected/per-call `braceExpansion` bounded to 128 alternatives / 4096 expanded bytes, fail-closed on overflow/malformed braces; (5) **checkpoint persistence for loaded-skill bodies** — opt-in `includeSkillBodies` on run + resume options (names-only stays default, 0.1.3 shapes byte-identical), ≤64 bodies / ≤256-char names / ≤262144-byte bodies / ≤1 MiB total, `maxStateBytes` refusal, redacted at rest, registry-independent resume render. Store compatibility with 0.1.5: **compatible, no migration** (additive-only; no persisted-shape change; `docs/migration.md` gains no entries). Exit gate green: npm test core 1,433/1,433 + 190 script gates (incl. phase18-freeze done-phase), `sdk:ready` exit 0, audit 0 moderate, pack dry-run 50/50 twice byte-identical, budget/benchmark gates green; evidence in `scripts/phase18-baseline.json` `exitGate`. Rollback = restore the 0.1.5 manifests/tag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -143,7 +143,7 @@
     "build": "npm run build:core && npm run build --workspaces --if-present",
     "typecheck": "npm run build && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
     "sweep:unused": "node scripts/sweep-unused.mjs",
-    "test": "npm run build && node --test dist/__tests__/*.test.js && node --test scripts/release-gate.test.mjs scripts/tooling-gate.test.mjs scripts/budget-gate.test.mjs scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase11-freeze.test.mjs scripts/phase12-freeze.test.mjs scripts/phase13-freeze.test.mjs scripts/phase14-freeze.test.mjs scripts/phase15-freeze.test.mjs scripts/phase16-freeze.test.mjs scripts/phase17-freeze.test.mjs scripts/phase18-freeze.test.mjs scripts/benchmark-0.1.0.test.mjs scripts/sweep-unused.test.mjs scripts/e2e-enterprise-journey.test.mjs scripts/e2e-coding-journey.test.mjs && npm run test --workspaces --if-present",
+    "test": "npm run build && node --test dist/__tests__/*.test.js && node --test scripts/release-gate.test.mjs scripts/tooling-gate.test.mjs scripts/budget-gate.test.mjs scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase11-freeze.test.mjs scripts/phase12-freeze.test.mjs scripts/phase13-freeze.test.mjs scripts/phase14-freeze.test.mjs scripts/phase15-freeze.test.mjs scripts/phase16-freeze.test.mjs scripts/phase17-freeze.test.mjs scripts/phase18-freeze.test.mjs scripts/phase19-freeze.test.mjs scripts/benchmark-0.1.0.test.mjs scripts/sweep-unused.test.mjs scripts/e2e-enterprise-journey.test.mjs scripts/e2e-coding-journey.test.mjs && npm run test --workspaces --if-present",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=60 --test-coverage-functions=70 --test-coverage-branches=75 --test-coverage-exclude='**/__tests__/**' --test-coverage-exclude='**/node_modules/**' --test-coverage-exclude='**/scripts/**' --test-coverage-exclude='**/packages/**' --test-coverage-exclude='**/examples/**' dist/__tests__/*.test.js && node scripts/coverage-summary.mjs",
     "coverage:summary": "node scripts/coverage-summary.mjs",
     "lint": "biome lint .",

package/templates/provider/CHANGELOG.md.tmpl

@@ -0,0 +1,5 @@
+# Changelog
+
+## __PRISM_VERSION__ — initial scaffold
+
+- Generated by `prism providers add __PROVIDER_ID__` (OpenAI-compatible provider package).

package/templates/provider/README.md.tmpl

@@ -0,0 +1,41 @@
+# __PACKAGE_NAME__
+
+__PROVIDER_ID__ provider package for Prism (OpenAI-compatible Chat Completions).
+
+## Quick start
+
+```bash
+npm install __PACKAGE_NAME__ @arnilo/prism
+```
+
+Wire the provider and models into your Prism host. The package registers an
+`api_key` auth method; hosts resolve the credential value — typically from the
+`__ENV_KEY__` environment variable:
+
+```ts
+import { createResolver } from "@arnilo/prism";
+import { create__PROVIDER_PASCAL__ProviderPackage } from "__PACKAGE_NAME__";
+
+const resolver = createResolver();
+resolver.registerProviderPackage(
+  create__PROVIDER_PASCAL__ProviderPackage({
+    apiKey: () => process.env.__ENV_KEY__,
+  }),
+);
+```
+
+## Models
+
+Starter catalog in `src/models.ts` (`__MODEL_ID__`). Replace with
+docs-verified model metadata (limits, costs, cache behavior) before publishing.
+
+## Conformance
+
+`npm test` builds the package and runs the offline conformance suite wired to
+`@arnilo/prism/testing/provider-conformance` (stream shape, tool-call delta
+reconstruction, header ownership, secret-leak redaction, serialized content
+coverage).
+
+## Docs
+
+See `docs/providers/__PROVIDER_ID__.md`.

package/templates/provider/docs/providers/NAME.md.tmpl

@@ -0,0 +1,61 @@
+# __PROVIDER_ID__ provider
+
+> Scaffold stub — replace with docs-verified provider documentation before publishing.
+
+## What it does
+
+`__PACKAGE_NAME__` is an OpenAI-compatible provider package for Prism
+(chat-completions style). It builds on `createOpenAICompatibleProvider` from
+`@arnilo/prism/providers/openai-compatible`.
+
+## When to use it
+
+Use it for OpenAI-compatible endpoints that follow the Chat Completions
+convention. Skip it for providers with bespoke serialization or auth.
+
+## Inputs / request
+
+- Base URL: `__BASE_URL__` (`--base-url` at scaffold time).
+- Auth: `api_key` auth method; hosts resolve the credential value (e.g. from
+  `__ENV_KEY__`).
+
+## Outputs / response / events
+
+Standard `ProviderEvent` stream: `content_delta`, `done` (with usage), or
+`error`. Tool calls arrive as deltas and are reconstructed by the host.
+
+## Request/response example
+
+```ts
+import { createResolver } from "@arnilo/prism";
+import { create__PROVIDER_PASCAL__ProviderPackage } from "__PACKAGE_NAME__";
+
+const resolver = createResolver();
+resolver.registerProviderPackage(
+  create__PROVIDER_PASCAL__ProviderPackage({ apiKey: () => process.env.__ENV_KEY__ }),
+);
+```
+
+## Implementation example
+
+`src/provider.ts` calls `createOpenAICompatibleProvider` with the scaffolded
+base URL, api key, and `doneUsage: true`. Model metadata lives in `src/models.ts`;
+cache-hint mapping helpers live in `src/cache.ts`.
+
+## Extension and configuration notes
+
+- Override `baseUrl`, `id`, `models`, `apiKey`, and `fetch` per provider
+  package/instance.
+- Cache behavior is scaffolded as `cache: { kind: "implicit" }` — confirm
+  against the provider's actual caching before relying on it.
+
+## Security and performance notes
+
+- API keys are host-resolved credentials; generated code stores no secrets.
+- Cache keys are identifiers only, sanitized via shared core helpers.
+
+## Related APIs
+
+- [OpenAI-compatible provider base](../../providers/openai-compatible.md)
+- [Provider conformance](../../provider-conformance.md)
+- [Provider layer](../../provider-layer.md)

package/templates/provider/package.json.tmpl

@@ -0,0 +1,49 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "__PRISM_VERSION__",
+  "description": "__PROVIDER_ID__ provider package for Prism.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/**/*.map",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/__tests__/*.test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@arnilo/prism": "__PRISM_VERSION__"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "prism",
+    "provider",
+    "__PROVIDER_ID__",
+    "agent",
+    "llm"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/provider/src/cache.ts.tmpl

@@ -0,0 +1,20 @@
+import type { ModelConfig, ProviderRequestOptions } from "@arnilo/prism";
+import { mapCacheRetention, sanitizeCacheKey } from "@arnilo/prism";
+
+/** OpenAI-compatible `prompt_cache_key` accepted length cap. */
+export const __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+
+export function __PROVIDER_ID__PromptCacheKey(options: ProviderRequestOptions | undefined): string | undefined {
+  // Sanitize + clamp via the shared core helper so cache keys cannot carry
+  // disallowed characters or exceed the provider limit. Cache keys are
+  // session/customer identifiers only, never credentials.
+  return sanitizeCacheKey(options?.cacheKey ?? options?.sessionId, __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH);
+}
+
+/** Retention mapping via the shared core helper; `"short"`/`"long"` only when the model supports it. */
+export function __PROVIDER_ID__PromptCacheRetention(
+  retention: ProviderRequestOptions["cacheRetention"] | undefined,
+  model: ModelConfig,
+): "short" | "long" | undefined {
+  return mapCacheRetention(retention, model);
+}

package/templates/provider/src/index.ts.tmpl

@@ -0,0 +1,33 @@
+import { type CredentialValueSource, defineProviderPackage, type ModelConfig, type ProviderPackage } from "@arnilo/prism";
+import { __PROVIDER_ID__Models } from "./models.js";
+import { create__PROVIDER_PASCAL__Provider } from "./provider.js";
+
+export interface __PROVIDER_PASCAL__ProviderPackageOptions {
+  readonly apiKey?: CredentialValueSource;
+  readonly fetch?: typeof fetch;
+  readonly baseUrl?: string;
+  readonly id?: string;
+  readonly models?: readonly ModelConfig[];
+}
+
+export function create__PROVIDER_PASCAL__ProviderPackage(options: __PROVIDER_PASCAL__ProviderPackageOptions = {}): ProviderPackage {
+  const providerId = options.id ?? "__PROVIDER_ID__";
+  return defineProviderPackage({
+    name: "__PACKAGE_NAME__",
+    description: "__PROVIDER_ID__ provider package for Prism.",
+    docs: { links: ["docs/providers/__PROVIDER_ID__.md"] },
+    setup(api) {
+      api.registerProvider(create__PROVIDER_PASCAL__Provider(options));
+      for (const model of options.models ?? __PROVIDER_ID__Models) api.registerModel({ ...model, provider: providerId });
+      api.registerAuthMethod({ kind: "api_key", provider: providerId, credentialName: "apiKey" });
+    },
+  });
+}
+
+export { __PROVIDER_ID__Models, type __PROVIDER_PASCAL__ModelConfig } from "./models.js";
+export { create__PROVIDER_PASCAL__Provider, __PROVIDER_UPPER___DEFAULT_BASE_URL, type __PROVIDER_PASCAL__ProviderOptions } from "./provider.js";
+export {
+  __PROVIDER_ID__PromptCacheKey,
+  __PROVIDER_ID__PromptCacheRetention,
+  __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH,
+} from "./cache.js";

package/templates/provider/src/models.ts.tmpl

@@ -0,0 +1,16 @@
+import type { ModelConfig } from "@arnilo/prism";
+
+/** Starter catalog for __PROVIDER_ID__: replace with docs-verified model metadata. */
+export interface __PROVIDER_PASCAL__ModelConfig extends Omit<ModelConfig, "provider"> {
+  readonly provider: "__PROVIDER_ID__";
+}
+
+export const __PROVIDER_ID__Models: readonly __PROVIDER_PASCAL__ModelConfig[] = [
+  {
+    provider: "__PROVIDER_ID__",
+    model: "__MODEL_ID__",
+    limits: { contextWindow: 128_000 },
+    cost: { input: 1, output: 2, cacheRead: 0.5, unit: "per_million_tokens" },
+    cache: { kind: "implicit" },
+  },
+];

package/templates/provider/src/provider.ts.tmpl

@@ -0,0 +1,23 @@
+import type { AIProvider, CredentialValueSource } from "@arnilo/prism";
+import { createOpenAICompatibleProvider } from "@arnilo/prism/providers/openai-compatible";
+
+/** Default Chat Completions base URL for __PROVIDER_ID__ (override per provider docs). */
+export const __PROVIDER_UPPER___DEFAULT_BASE_URL = "__BASE_URL__";
+
+export interface __PROVIDER_PASCAL__ProviderOptions {
+  readonly id?: string;
+  readonly baseUrl?: string;
+  readonly apiKey?: CredentialValueSource;
+  readonly fetch?: typeof fetch;
+}
+
+export function create__PROVIDER_PASCAL__Provider(options: __PROVIDER_PASCAL__ProviderOptions = {}): AIProvider {
+  return createOpenAICompatibleProvider({
+    id: options.id ?? "__PROVIDER_ID__",
+    baseUrl: (options.baseUrl ?? __PROVIDER_UPPER___DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    apiKey: options.apiKey,
+    fetch: options.fetch,
+    doneUsage: true,
+    requestFailedPrefix: "__PROVIDER_PASCAL__ request failed",
+  });
+}

package/templates/provider/src/tests/provider.test.ts.tmpl

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ProviderRequest } from "@arnilo/prism";
+import {
+  assertNoSecretLeak,
+  assertProviderOwnedHeadersWin,
+  assertProviderStreamConforms,
+  assertSerializedRequestCoversContent,
+  assertToolCallDeltasReconstruct,
+} from "@arnilo/prism/testing/provider-conformance";
+import { create__PROVIDER_PASCAL__Provider } from "../index.js";
+import { __PROVIDER_ID__Models } from "../models.js";
+
+const request: ProviderRequest = {
+  model: __PROVIDER_ID__Models[0],
+  messages: [
+    { role: "system", content: [{ type: "text", text: "developer instructions" }] },
+    { role: "user", content: [{ type: "text", text: "hi" }] },
+  ],
+  tools: [{ name: "lookup", parameters: { type: "object" }, execute: () => ({ toolCallId: "call_1", name: "lookup", content: [] }) }],
+};
+
+const API_KEY = "fake-__PROVIDER_ID__-key";
+
+describe("__PROVIDER_ID__ provider scaffold", () => {
+  it("streams text, usage, and done; owns its headers; leaks no secrets", async () => {
+    let captured: RequestInit | undefined;
+    const provider = create__PROVIDER_PASCAL__Provider({
+      apiKey: API_KEY,
+      fetch: (async (_input, init) => {
+        captured = init;
+        return ok(
+          sse([
+            { id: "chatcmpl-1", object: "chat.completion.chunk", choices: [{ index: 0, delta: { role: "assistant", content: "hi" } }] },
+            {
+              id: "chatcmpl-1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: {} }],
+              usage: { prompt_tokens: 5, completion_tokens: 2, total_tokens: 7 },
+            },
+          ]),
+        );
+      }) as typeof fetch,
+    });
+    const events = await assertProviderStreamConforms({
+      provider,
+      request: {
+        ...request,
+        options: {
+          ...request.options,
+          headers: { authorization: "Bearer caller-key", "content-type": "text/plain", "x-caller": "kept" },
+        },
+      },
+      expect: { text: "hi", usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } },
+    });
+    assertNoSecretLeak(events, [API_KEY]);
+    const headers = new Headers(captured?.headers);
+    assertProviderOwnedHeadersWin(headers, {
+      owned: { authorization: `Bearer ${API_KEY}`, "content-type": "application/json" },
+      caller: { authorization: "Bearer caller-key", "content-type": "text/plain", "x-caller": "kept" },
+    });
+  });
+
+  it("serializes request content and reconstructs tool-call deltas", async () => {
+    let body: unknown;
+    const provider = create__PROVIDER_PASCAL__Provider({
+      apiKey: API_KEY,
+      fetch: (async (_input, init) => {
+        body = JSON.parse(String(init?.body));
+        return ok(
+          sse([
+            {
+              id: "c1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: "call_1", function: { name: "lookup", arguments: "" } }] } }],
+            },
+            {
+              id: "c1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { tool_calls: [{ index: 0, function: { arguments: '{"q":"x"}' } }] } }],
+            },
+          ]),
+        );
+      }) as typeof fetch,
+    });
+    const events = await assertProviderStreamConforms({ provider, request });
+    assertToolCallDeltasReconstruct(events, [{ index: 0, id: "call_1", name: "lookup", arguments: { q: "x" } }]);
+    assertSerializedRequestCoversContent(request, body);
+  });
+});
+
+function ok(body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, { status: 200 });
+}
+
+function sse(events: readonly object[]): ReadableStream<Uint8Array> {
+  const text = `${events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join("")}data: [DONE]\n\n`;
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(text));
+      controller.close();
+    },
+  });
+}

package/templates/provider/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}