@arnilo/prism 0.5.0 → 0.5.2

package/docs/migration.md

@@ -1,5 +1,13 @@
 # Migration guide
 
+## 0.5.1 → 0.5.2 (additive)
+
+Stream tokens coalesce on persist (adjacent `text`/`thinking` deltas merge). Replay serializers join those parts with an empty string instead of a newline. No import, store, or peer-range break; bump `@arnilo/prism*` to `^0.5.2`.
+
+## 0.5.0 → 0.5.1 (additive)
+
+Kernel constructs valid provider requests: session correlation, default cache breakpoints, and `thinkingLevel` on `AgentConfig` / `RunOptions`. Clay may drop host-only `createSessionCachePolicy`. OpenCode Go raw `generate` without `sessionId` throws `ProviderRequirementError` (`ERR_PRISM_PROVIDER_REQUIREMENT`) before fetch instead of an upstream 400. Observational memory uses derived `om:{session.id}`; LLM compaction uses the agent session id. See [migrate-to-0.5.md](migrate-to-0.5.md#8-provider-request-construction--additive-plan-066--051).
+
 ## 0.4.x → 0.5.0 lockstep cut (breaking)
 
 Prism 0.5 (plans 055–065) ships four breaking surfaces: the 27 removed unused exports from the plan 058 sweep (symbol-surface only), the MCP TypeScript SDK v2 module move (plan 063 — hosts importing `@modelcontextprotocol/sdk` directly must move to the modular `client`/`server` 2.0.0 packages), the thinking-effort wire moves (plan 065 — Anthropic `effort` → `output_config.effort`, xAI `reasoning_effort` now sent, snap-on-declared semantics), and the plan 056 hardening behavior changes (tenant-scoped store factories, child env allow-list). Dependency majors (plan 062: pdf-parse 2.4 with Node ≥ 20.16, better-sqlite3 13, keyring 2 with typed locked-store errors) and the CLI real-provider contract (plan 064: explicit `--provider` required, exit 2 when omitted) are behavior changes without import impact. See the complete guide with per-symbol replacements and upgrade steps in [migrate-to-0.5.md](migrate-to-0.5.md). All 10 publishable manifests bump to `0.5.0` lockstep; internal first-party ranges move `^0.4.0` → `^0.5.0`. Security keeper surface (ownership/checkpoint guards, `secureCompare`, `zeroBuffer`, sandbox path-escape guard, RAG scope guard, MCP content-bounds guard, secret-leak conformance assert) is unchanged.

package/docs/provider-caching.md

@@ -12,6 +12,8 @@ Provider caching documents Prism's cache intent surface:
 
 Cache hints are best-effort. They describe intent; providers decide whether their native API can use them. Prism does not guarantee cache hits.
 
+**Kernel defaults (0.5.1).** `applyDefaultProviderRequestOptions` fills `cache.breakpoints` with `{ location: "system_prompt" }` and `{ location: "last_stable_message" }` plus `cacheRetention: "short"` when `model.cache.kind === "cache_control"` or `model.cache.explicitBreakpoints === true`, unless the host set `cache.mode: "off"`, `cacheRetention: "none"`, or a non-empty breakpoint list. Implicit / `none` / host-owned (Azure, Bedrock, Vertex, AI SDK) models get no Prism markers. Session and cache keys are correlation ids — Cache keys must never be credentials.
+
 ## When to use it
 
 Use this page when a host or provider package needs to:
@@ -150,7 +152,7 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 | `@arnilo/prism-providers/openai` | `openai_key` | Sends sanitized `prompt_cache_key`; pre-5.6 models emit `prompt_cache_retention: "24h"` when `longRetention`; GPT-5.6+ models (`explicitBreakpoints`) map `cache.breakpoints`/`cache.mode: "on"` to `prompt_cache_options: { mode: "explicit" }` + `prompt_cache_breakpoint` markers (≤4 writes). | Stable cache key + stable prefix can improve reuse; keep selected anchors stable. | Best-effort only; `"short"`/`"none"` omit retention; `"30m"` TTL is the default and never emitted. |
 | `@arnilo/prism-providers/anthropic` | `cache_control` | Marks only selected Anthropic message anchors; `system_prompt` breakpoints emit native `system` text blocks with the marker; `"long"` maps to documented `ttl: "1h"`. | Keep selected anchors stable. | Best-effort; never stamp every block. |
 | `@arnilo/prism-providers/google` | none | Sends no Prism cache marker. | Host/model may have upstream behavior. | Gemini cache controls are not mapped in this package. |
-| `@arnilo/prism-providers/openrouter` | `cache_control` | Top-level automatic `cache_control` when enabled without breakpoints; otherwise markers only on caller-selected `cache.breakpoints`; `"long"` may add `ttl: "1h"`. Sticky `session_id` routing. | Breakpoint-stable / automatic prefixes can be reused by upstream providers. | Best-effort only; top-level automatic may exclude some backends from routing. |
+| `@arnilo/prism-providers/openrouter` | `cache_control` | Kernel defaults (agent session / helper) emit **per-message** `cache_control` on `system_prompt` + `last_stable_message`. Raw `generate` with empty breakpoints may still send top-level automatic `cache_control`. `"long"` may add `ttl: "1h"`. Sticky `session_id` routing. | Breakpoint-stable prefixes can be reused by upstream providers. | Best-effort only; top-level automatic may exclude some backends from routing. |
 | `@arnilo/prism-providers/opencode-go` | route-specific | Sends sanitized `x-opencode-session`; Anthropic route applies selected `cache_control` breakpoints; OpenAI route sends none. | Session id + unchanged selected anchors can help route-native caches. | Best-effort and route-dependent. |
 | `@arnilo/prism-providers/hyper` | route-specific implicit / `cache_control` | Chat route sends no markers (implicit prefix caching); `qwen3.6-*` messages route applies `cache_control` only to caller-selected `cache.breakpoints` (max 4); **no `ttl`** (undocumented). Opt-in responses route emits OpenAI-standard `prompt_cache_key` from hints only, never retention/options. | Keep selected Anthropic anchors and prior history stable. | Best-effort only; `402 billing_error` when Hypercredits run out. |
 | `@arnilo/prism-providers/commandcode` | route-specific implicit / `cache_control` | Chat route sends no markers (implicit prefix caching); `claude-*` messages route applies `cache_control` only to caller-selected `cache.breakpoints` (max 4); **no `ttl`** (undocumented). GPT-5.6 tiers keep docs `cacheWrite` prices in `cost` but stay implicit until the live probe verifies `prompt_cache_key`. | Keep selected Anthropic anchors and prior history stable. | Best-effort only; GPT-5.6 explicit `prompt_cache_key` upgrade pending probe (plan 055 Task 9); OSS models bill at mean per-provider price; DeepSeek off-peak 17h/day, peak 2×. |
@@ -173,7 +175,7 @@ Detailed first-party provider notes:
 - OpenAI-compatible Chat Completions adapter: minimal scope, sends no cache payload; see [OpenAI-compatible provider](providers/openai-compatible.md).
 - Anthropic (`@arnilo/prism-providers/anthropic`): `kind: "cache_control"`; selected Anthropic message anchors receive `cache_control` and eligible long retention maps to `ttl: "1h"`. A `system_prompt` breakpoint serializes `system` as native text blocks carrying the marker (shared `systemCacheControlField()` helper; plain joined string when unmarked). Cache read/create usage maps to normalized cache read/write tokens.
 - Google (`@arnilo/prism-providers/google`): sends no Prism cache-control payload. Do not infer cache hits or cache token counts from absent Gemini fields.
-- OpenRouter (`@arnilo/prism-providers/openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing (from `cache.key` ?? legacy `cacheKey` ?? `sessionId`); with no breakpoints emits top-level automatic `cache_control: { type: "ephemeral" }`; with breakpoints applies Anthropic-style markers only to caller-selected locations (last content block of each selected message); `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Optional `listOpenRouterModels()` may populate `ModelConfig.cache`/`cost` from live pricing.
+- OpenRouter (`@arnilo/prism-providers/openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing (from `cache.key` ?? legacy `cacheKey` ?? `sessionId`); kernel defaults supply `system_prompt` + `last_stable_message` breakpoints so agent-session requests use per-message markers (not top-level automatic). Raw `generate` with empty breakpoints still emits top-level automatic `cache_control: { type: "ephemeral" }`; `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Optional `listOpenRouterModels()` may populate `ModelConfig.cache`/`cost` from live pricing.
 - OpenCode Go (`@arnilo/prism-providers/opencode-go`): default base `https://opencode.ai/zen/go/v1`; `x-opencode-session` from `cacheKey ?? sessionId`, sanitized to 128 chars; the Anthropic route (MiniMax/Qwen) applies `cache_control` markers only to selected breakpoints (`"long"` → `ttl: "1h"`), the OpenAI route (Grok/GLM/Kimi/MiMo/DeepSeek) sends none and preserves `reasoning_content`. OpenAI route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens`; Anthropic route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. Caller-gated `listOpenCodeGoModels` against official `GET /zen/go/v1/models`.
 - Hyper (`@arnilo/prism-providers/hyper`): `kind: "implicit"` on the chat route, `kind: "cache_control"` on the messages route. Model route selection follows the live catalog's pricing shape: models with explicit cache-write pricing (qwen3.6-*) default to the Anthropic route; the rest stay chat-route implicit with the write fee recorded in `cost.cacheWrite`. The messages route applies `cache_control: { type: "ephemeral" }` only to caller-selected `cache.breakpoints` (shared `applyCacheControl`, max 4) — never every block, and **never a `ttl`** (Hyper documents no TTL values). Chat route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens` (and `prompt_cache_hit_tokens`); messages route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. `parseHyperUsageCost` surfaces USD/cost/remaining Hypercredits from the OpenAI usage chunk for cost telemetry; `402 billing_error` is the drained-balance signal. Caller-gated `listHyperModels`; operator-gated `getHyperCredits`.
 - Command Code (`@arnilo/prism-providers/commandcode`): `kind: "implicit"` on the chat route, `kind: "cache_control"` on the messages route. `claude-*` tiers (the only Anthropic-route models by server-enforced routing) default to `cache_control` with markers only on caller-selected `cache.breakpoints` max 4 — never every block, and **never a `ttl`** (the upstream TTL window is undocumented). GPT-5.6 sol/terra/luna keep the docs cache-write price in `cost.cacheWrite` but stay `implicit` until the live `prompt_cache_key` probe passes (plan 055 Task 9); all other chat-route models are implicit with `prompt_cache_hit_tokens`/`cached_tokens` mapped by the shared OpenAI usage mapping. Messages route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. Billing caveats: OSS models bill at the mean per-provider price; DeepSeek off-peak rates (17h/day) with ~2× peak 01–04 & 06–10 UTC; deals (MiniMax M3, MiMo) auto-applied. Caller-gated `listCommandCodeModels`; optional ZDR (`zdr: true`) adds `x-cmd-zdr: 1` and may route to costlier upstreams or fail `422 cmd_zdr_no_providers`.

package/docs/provider-packages.md

@@ -25,26 +25,26 @@ Do not use provider packages as a package manager, credential store, env loader,
 
 | adapter package | version |
 | --- | --- |
-| `@arnilo/prism-providers/ai-sdk` | 0.5.0 |
-| `@arnilo/prism-providers/alibaba` | 0.5.0 |
-| `@arnilo/prism-providers/anthropic` | 0.5.0 |
-| `@arnilo/prism-providers/azure` | 0.5.0 |
-| `@arnilo/prism-providers/bedrock` | 0.5.0 |
-| `@arnilo/prism-providers/clinepass` | 0.5.0 |
-| `@arnilo/prism-providers/commandcode` | 0.5.0 |
-| `@arnilo/prism-providers/deepseek` | 0.5.0 |
-| `@arnilo/prism-providers/google` | 0.5.0 |
-| `@arnilo/prism-providers/hyper` | 0.5.0 |
-| `@arnilo/prism-providers/kimi` | 0.5.0 |
-| `@arnilo/prism-providers/model-discovery` | 0.5.0 |
-| `@arnilo/prism-providers/neuralwatt` | 0.5.0 |
-| `@arnilo/prism-providers/ollama` | 0.5.0 |
-| `@arnilo/prism-providers/openai` | 0.5.0 |
-| `@arnilo/prism-providers/opencode-go` | 0.5.0 |
-| `@arnilo/prism-providers/openrouter` | 0.5.0 |
-| `@arnilo/prism-providers/vertex` | 0.5.0 |
-| `@arnilo/prism-providers/xai` | 0.5.0 |
-| `@arnilo/prism-providers/zai` | 0.5.0 |
+| `@arnilo/prism-providers/ai-sdk` | 0.5.2 |
+| `@arnilo/prism-providers/alibaba` | 0.5.2 |
+| `@arnilo/prism-providers/anthropic` | 0.5.2 |
+| `@arnilo/prism-providers/azure` | 0.5.2 |
+| `@arnilo/prism-providers/bedrock` | 0.5.2 |
+| `@arnilo/prism-providers/clinepass` | 0.5.2 |
+| `@arnilo/prism-providers/commandcode` | 0.5.2 |
+| `@arnilo/prism-providers/deepseek` | 0.5.2 |
+| `@arnilo/prism-providers/google` | 0.5.2 |
+| `@arnilo/prism-providers/hyper` | 0.5.2 |
+| `@arnilo/prism-providers/kimi` | 0.5.2 |
+| `@arnilo/prism-providers/model-discovery` | 0.5.2 |
+| `@arnilo/prism-providers/neuralwatt` | 0.5.2 |
+| `@arnilo/prism-providers/ollama` | 0.5.2 |
+| `@arnilo/prism-providers/openai` | 0.5.2 |
+| `@arnilo/prism-providers/opencode-go` | 0.5.2 |
+| `@arnilo/prism-providers/openrouter` | 0.5.2 |
+| `@arnilo/prism-providers/vertex` | 0.5.2 |
+| `@arnilo/prism-providers/xai` | 0.5.2 |
+| `@arnilo/prism-providers/zai` | 0.5.2 |
 <!-- generated:package-truth:providers end -->
 
 
@@ -90,18 +90,15 @@ export default defineProviderPackage({
 
 `compat` is provider-owned inert JSON. Core does not branch on provider names or interpret vendor-specific fields.
 
-Provider packages can also contribute auth descriptors and request policies without resolving credentials:
+Provider packages can also contribute auth descriptors and prompt layers without resolving credentials:
 
 ```ts
-import { createSessionCachePolicy } from "@arnilo/prism";
-
 api.registerAuthMethod({ provider: "demo", kind: "api_key", credentialName: "apiKey" });
 api.registerAuthMethod({ provider: "demo", kind: "oauth", oauth: demoOAuthProvider });
-api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short" }));
 api.registerSystemPromptContribution({ id: "demo-prompt", source: "package", mode: "append", text: "Use demo provider rules." });
 ```
 
-Hosts decide which credential resolvers, env objects, OAuth stores, request policies, and prompt contributions become active. Request policies can set generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, `compat`, and opaque `extra`; provider adapters decide how to map those options to provider payloads. Caller headers are extension headers only: provider adapters must apply provider-owned headers (auth, content type, session/cache/security, attribution) after caller headers so requests cannot override credentials or provider policy.
+Host picks provider + model + intent (messages, tools, optional `thinkingLevel` / cache retention). Prism constructs a valid wire request for every generate site it owns. Host request policies are overlays — they are never required for success. Hosts still own credentials, env objects, OAuth stores, extra headers, custom `cacheKey`, `compat`/`extra` overlays, and which prompt contributions become active. Request policies can overlay generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, `compat`, and opaque `extra`; provider adapters map those options to provider payloads. Caller headers are extension headers only: provider adapters must apply provider-owned headers (auth, content type, session/cache/security, attribution) after caller headers so requests cannot override credentials or provider policy.
 
 Provider request options: `ProviderRequestOptions` carries session/cache/header/compat/extra hints only. Timeouts are host-owned (`RunOptions.signal`/host abort controllers); retries are runtime-owned (`AgentConfig.retry`/`RunOptions.retry`). Provider-level timeout/retry hints were removed in 0.1.5. Provider packages should not add provider-specific retry loops unless the vendor protocol requires it and runtime retry cannot cover the failure mode.
 
@@ -294,10 +291,10 @@ Provider package manifest contribution and the generic request options a provide
 
 ## Implementation example
 
-Wire a provider package with model metadata plus a session cache policy through the extension kernel:
+Wire a provider package with model metadata through the extension kernel. Session correlation and cache defaults are kernel-constructed — do not register `createSessionCachePolicy` for request success:
 
 ```ts
-import { createExtensionKernel, defineProviderPackage, createSessionCachePolicy } from "@arnilo/prism";
+import { createExtensionKernel, defineProviderPackage } from "@arnilo/prism";
 
 const pkg = defineProviderPackage({
   name: "demo-provider",
@@ -312,7 +309,6 @@ const pkg = defineProviderPackage({
       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, currency: "USD" },
       compat: { vendorSpecific: true },
     });
-    api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short" }));
   },
 });
 
@@ -322,13 +318,13 @@ await kernel.load([pkg]);
 
 ## Extension and configuration notes
 
-- Hosts decide which credential resolvers, env objects, OAuth stores, request
-  policies, and prompt contributions become active; the package only *declares*
-  them.
-- `createSessionCachePolicy()` acts as a concrete cache policy hook
-  (`provider_request`) that sets generic `ProviderRequest.options`
+- Hosts own credentials, env objects, OAuth stores, extra headers, custom `cacheKey`,
+  `compat`/`extra`, and which prompt contributions become active; the package only *declares*
+  them. Prism constructs session/cache/thinking options for owned generate sites.
+- `createSessionCachePolicy()` is an optional host overlay (`provider_request` cache policy hook)
+  that sets generic `ProviderRequest.options`
   (`sessionId`, `cacheKey`, `cacheRetention`, `headers`, opaque `extra`) before
-  `AIProvider.generate()`; provider adapters map those options to provider payloads.
+  `AIProvider.generate()`; provider adapters map those options to provider payloads. Not required for request success.
 - `ModelConfig.cache` is the generic cache capability metadata documented in [Model registry](model-registry.md); `ModelConfig.compat` remains provider-owned inert JSON for behavior that has no generic field yet.
 - `ModelConfig.compat` is provider-owned inert JSON: cache policy overrides,
   reasoning/thinking formats, and provider-specific usage mapping live there

package/docs/provider-request-policies.md

@@ -6,15 +6,17 @@ Provider request policies are small host/package hooks that can adjust `Provider
 
 Public helpers:
 
+- `applyDefaultProviderRequestOptions(request, { sessionId, thinkingLevel })` is the kernel constructor. Fill-if-missing `sessionId` / `cacheKey`; default cache breakpoints + `cacheRetention: "short"` when `model.cache.kind` is `cache_control` or `explicitBreakpoints` is true; optional `thinkingLevel` patches via `applyThinkingLevelForModel` after those fills. Host values win. Agent sessions, observational-memory workers, and LLM compaction already call it.
+- `ProviderRequirementError` (`ERR_PRISM_PROVIDER_REQUIREMENT`) is the fail-fast typed error adapters throw when a mandatory option is still missing (OpenCode Go `sessionId` → `x-opencode-session`). Thrown before fetch; messages contain no request bodies or secrets.
 - `createProviderRequestPolicyChain(policies)` runs policies in order.
-- `createSessionCachePolicy(options)` sets legacy `cacheKey` / `cacheRetention` aliases from `sessionId`.
+- `createSessionCachePolicy(options)` is a host overlay that sets legacy `cacheKey` / `cacheRetention` aliases from `sessionId`. Not required for request success.
 - `mergeProviderRequestOptions(base, patch)` merges request options, including structured `cache` hints.
 
 ## When to use it
 
-Use provider request policies when an app or provider package needs to set generic per-request options such as cache hints, caller-owned headers, `compat`, or `extra` without changing every provider call site.
+Use `createAgent({ thinkingLevel })` / `session.run(input, { thinkingLevel })` for session intent. Use `applyDefaultProviderRequestOptions` on custom `provider.generate` sites. Use provider request policies only as overlays (custom `cacheKey`, extra headers, `compat`/`extra`) — never to make a request valid.
 
-Do not use request policies to resolve credentials, read env vars, perform OAuth refresh, fetch model lists, or override provider-owned auth/session/security headers.
+Do not use request policies to resolve credentials, read env vars, perform OAuth refresh, fetch model lists, or override provider-owned auth/session/security headers. Session and cache keys are correlation ids, never secrets.
 
 ## Inputs / request
 
@@ -24,9 +26,11 @@ import type { ProviderRequestPolicy, ProviderRequestPolicyContext, ProviderReque
 
 | API | Input | Purpose |
 | --- | --- | --- |
+| `applyDefaultProviderRequestOptions(request, ctx)` | `{ sessionId?, thinkingLevel? }` | Fill-if-missing `sessionId` / `cacheKey`; cache defaults from `model.cache`; thinking patch. |
+| `ProviderRequirementError` | `message`, `{ requirement, providerId? }` | Typed missing-requirement error. |
 | `ProviderRequestPolicy.apply(context)` | `{ sessionId?, request, options? }` | Returns a patched request or options. |
 | `createProviderRequestPolicyChain(policies)` | ordered policies | Applies patches in order. |
-| `createSessionCachePolicy({ retention?, cacheKey? })` | optional cache defaults | Sets legacy aliases. |
+| `createSessionCachePolicy({ retention?, cacheKey? })` | optional cache overlay | Sets legacy aliases after kernel defaults. |
 | `mergeProviderRequestOptions(base, patch)` | two option bags | Shallow merges scalars and structurally merges `cache`. |
 
 `mergeProviderRequestOptions()` behavior:
@@ -62,12 +66,21 @@ No agent events are emitted by the policy chain itself.
 
 ```ts
 import {
+  applyDefaultProviderRequestOptions,
   createProviderRequestPolicyChain,
   createSessionCachePolicy,
   mergeProviderRequestOptions,
+  ProviderRequirementError,
   type ProviderRequestPolicy,
 } from "@arnilo/prism";
 
+const stamped = applyDefaultProviderRequestOptions(request, {
+  sessionId: session.id,
+  thinkingLevel: "low",
+});
+// stamped.options.sessionId === request.options?.sessionId ?? session.id
+// cache_control models also get default cache.breakpoints unless the host set mode/off / retention/none / explicit breakpoints
+
 const structuredCache: ProviderRequestPolicy = {
   name: "demo.structured-cache",
   apply({ request }) {
@@ -93,7 +106,7 @@ const chain = createProviderRequestPolicyChain([
 
 ## Extension and configuration notes
 
-Provider packages can register request policies during `defineProviderPackage().setup(api)`. Hosts decide which packages/policies load and in which order. Prism has no hidden provider request policy registry and no automatic provider-specific cache behavior in core.
+Provider packages can register request policies during `defineProviderPackage().setup(api)`. Hosts decide which overlay policies load and in which order. Prism has no hidden provider request policy registry. Kernel construction (`applyDefaultProviderRequestOptions`) already fills session/cache/thinking from `model.cache` and run intent — package-registered policies are never auto-activated and never required for success.
 
 Policy output should stay generic: use `ProviderRequestOptions.cache`, `headers`, `compat`, and `extra` instead of provider-name branches in core.
 

package/docs/providers/ai-sdk.md

@@ -150,6 +150,18 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 - `options.compat` / `options.extra` pass through as AI SDK `providerOptions.prism`.
 - Export helpers `toAiSdkCallOptions`, `toAiSdkPrompt`, and `mapAiSdkStream` for tests and custom hosts.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - Host credentials stay inside the supplied AI SDK model. The adapter never reads env keys or credential stores.

package/docs/providers/alibaba.md

@@ -245,6 +245,18 @@ await kernel.load([
 - Usage accounting: `cached_tokens` → `Usage.cacheReadTokens`,
   `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | only if `model.cache.kind === "cache_control"` |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`

package/docs/providers/anthropic.md

@@ -77,6 +77,18 @@ api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, mo
 - Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `ANTHROPIC_API_KEY`.
 - Anthropic says OAuth is for purchasers' ordinary Claude Code/native-app use; developers building products must use Claude Console API keys or a supported cloud provider and may not offer Claude.ai login or route Free/Pro/Max credentials ([legal and compliance](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance)). Prism therefore has no Anthropic subscription OAuth API or token-import shortcut.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-client-request-id` from `sessionId` |
+| Mandatory | no |
+| P2 default cache | `cache_control` on `system_prompt` + `last_stable_message`; `cacheRetention: "short"` |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No network during import/setup/default tests; credentials host-owned and late-bound.

package/docs/providers/azure.md

@@ -58,6 +58,18 @@ Opt-in live canaries: inject real `fetch` + host credential behind host CI secre
 
 Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-core/governance/model-router` for residency allow-lists on Azure regions/endpoints.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No credential prefetch at import; the credential is resolved exactly once per request (a rotating `CredentialValueSource` is never consumed twice — the same resolved token drives the wrapper check and the inner auth header).

package/docs/providers/bedrock.md

@@ -57,6 +57,18 @@ Live canaries stay opt-in behind host credentials; default tests are network-fre
 
 Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hosts needing Converse-only models should supply a custom provider or AI SDK bridge.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No AWS SDK; package-local SigV4 only for `bedrock` service.

package/docs/providers/clinepass.md

@@ -98,6 +98,18 @@ await session.prompt("Plan the refactor", {
 - Multi-backend gateway: key compat off `api.cline.bot`, not the upstream vendor.
 - Reference USD-per-million costs are catalog metadata; ClinePass itself is a subscription.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none; strips `cache_control` |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No network on import, setup, build, or default tests.

package/docs/providers/commandcode.md

@@ -212,6 +212,18 @@ PRISM_LIVE_PROVIDER_TESTS=1 COMMAND_CODE_API_KEY=cmd_... \
   npm run test --workspace=@arnilo/prism-providers/commandcode
 ```
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | Anthropic: `cache_control`; OpenAI: implicit (no `prompt_cache_key`) |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers.

package/docs/providers/deepseek.md

@@ -119,6 +119,18 @@ await session.prompt("Plan the refactor", {
 - Tool-turn assistants must replay `reasoning_content` or the API returns 400.
   Non-tool multi-turn may omit it (the API ignores it).
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded transport helpers.

package/docs/providers/google.md

@@ -73,6 +73,18 @@ api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, model
 - Vertex / enterprise identity stays out of 0.0.11.
 - Gemini CLI says third-party software accessing its backend through Gemini CLI OAuth violates applicable terms, and its FAQ directs third-party coding agents to Vertex AI or Google AI Studio API keys ([terms](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md), [FAQ](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/faq.md)). Prism therefore has no Gemini CLI OAuth API or token-import shortcut.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-client-request-id` from `sessionId` |
+| Mandatory | no |
+| P2 default cache | none (no Prism cache markers) |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No network during import/setup/default tests; credentials host-owned and late-bound.

package/docs/providers/hyper.md

@@ -245,6 +245,18 @@ PRISM_LIVE_PROVIDER_TESTS=1 HYPER_API_KEY=sk-hyper-... \
   npm run test --workspace=@arnilo/prism-providers/hyper
 ```
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | Responses: `prompt_cache_key`; chat/Anthropic: no session header |
+| Mandatory | no |
+| P2 default cache | Anthropic: `cache_control`; Responses: openai_key rules; chat: implicit |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers.

package/docs/providers/kimi.md

@@ -185,6 +185,18 @@ await kernel.load([
 - Coding usage: `cache_read_input_tokens` → `Usage.cacheReadTokens`,
   `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none extra |
+| Mandatory | no |
+| P2 default cache | Anthropic/Coding: `cache_control`; Moonshot: none |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`

package/docs/providers/neuralwatt.md

@@ -360,6 +360,18 @@ const decision = classifyNeuralWattError({ status: 429, headers: { "retry-after"
 // { retryable: true, code: 429, retryAfterMs: 1000, errorCode: "concurrent_budget_exceeded", strategy: undefined }
 ```
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams, HTTP error bodies, and quota/model-discovery failures use bounded `@arnilo/prism/providers/transport` helpers (`readSseEvents`, `readBoundedResponseText`). NeuralWatt `: energy` / `: cost` comment frames are surfaced via `readSseEvents` `comments` and mapped locally.

package/docs/providers/ollama.md

@@ -139,6 +139,18 @@ await kernel.load([
   `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). If a future
   Ollama release reports cached tokens, map them in `mapOllamaModel`/usage handling.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`

package/docs/providers/openai-compatible.md

@@ -139,6 +139,18 @@ const provider = createOpenAICompatibleProvider({
 
 - Cache behavior is intentionally minimal: this Chat Completions adapter sends no `prompt_cache_key`, `prompt_cache_retention`, or `cache_control` fields. Endpoints that cache implicitly do so automatically; hosts needing OpenAI `prompt_cache_key`/`prompt_cache_retention` should use the [`@arnilo/prism-providers/openai`](openai.md) Responses package. The adapter still normalizes cache usage from `prompt_tokens_details.cached_tokens` (and `prompt_cache_hit_tokens`) into `Usage.cacheReadTokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none (factory sends no session/cache wire) |
+| Mandatory | no |
+| P2 default cache | none unless the vendor adapter maps options |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - Credentials are host-owned and resolved only when `generate()` runs.

package/docs/providers/openai.md

@@ -207,6 +207,18 @@ Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reaso
   `response.output_item.added` + `response.function_call_arguments.delta`
   (string `delta`), not Chat Completions object deltas.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `prompt_cache_key` from `cacheKey??sessionId`; `x-client-request-id` from `sessionId` |
+| Mandatory | no |
+| P2 default cache | GPT-5.6+ `explicitBreakpoints` → `prompt_cache_breakpoint` + `cacheRetention: "short"`; older families none |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).

package/docs/providers/opencode-go.md

@@ -233,6 +233,18 @@ Owned compat keys (`route`, `thinking`, `reasoning`, `reasoning_effort`,
   `Usage.cacheReadTokens`/`cacheWriteTokens`; the Anthropic route maps
   `cache_read_input_tokens`/`cache_creation_input_tokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-opencode-session` from `cacheKey??sessionId` |
+| Mandatory | **yes** — missing id throws `ProviderRequirementError` (`ERR_PRISM_PROVIDER_REQUIREMENT`) before fetch; message has no request body |
+| P2 default cache | Anthropic route: `cache_control` markers; OpenAI route: none |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).

package/docs/providers/openrouter.md

@@ -174,6 +174,18 @@ for Anthropic/Qwen/Gemini families with cache pricing; otherwise `implicit` when
 cache-read pricing exists), and seeds `compat.reasoning.effort` from
 `reasoning.default_effort` when present.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-session-id` + body `session_id` |
+| Mandatory | no |
+| P2 default cache | kernel defaults → per-message `cache_control` (not top-level automatic) |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).

package/docs/providers/vertex.md

@@ -55,6 +55,18 @@ const provider = createVertexProvider({
 
 `@arnilo/prism-providers/google` remains API-key Gemini (`generativelanguage.googleapis.com`) and must not register Vertex OAuth/ADC. Load this package explicitly for Vertex.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No Google Cloud SDK dependency in the package.

package/docs/providers/xai.md

@@ -115,6 +115,18 @@ await kernel.load([
 - Reasoning models replay `reasoning_content` and do not flatten thinking into text.
 - Generate always hits `https://api.x.ai/v1/chat/completions` (same backend for API key and SuperGrok access).
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-grok-conv-id` from `cache.key??cacheKey??sessionId` |
+| Mandatory | no |
+| P2 default cache | implicit; header is the correlation |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - Public client id is documented as not a secret. Device/user/access/refresh codes are redacted.

package/docs/providers/zai.md

@@ -139,6 +139,18 @@ await session.prompt("Plan the refactor", {
   and `prompt_tokens_details.cache_write_tokens` → `Usage.cacheWriteTokens` when
   the server reports them.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`