@arnilo/prism 0.0.96 → 0.1.0

package/docs/providers/google.md

@@ -0,0 +1,89 @@
+# Google provider package
+
+## What it does
+
+`@arnilo/prism-provider-google` is the first-party Gemini `generateContent` / `streamGenerateContent` provider for Prism (`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`). Setup is side-effect-free: no network, env scan, or keychain lookup during import/setup. Uses native `fetch` + SSE — no `@google/genai` runtime dependency.
+
+## When to use it
+
+Use for first-party Gemini Developer API coding-host semantics (function calling, multimodal `inlineData`, thinking, usage, abort). Prefer this over the AI SDK escape hatch when Gemini is a primary host.
+
+Do **not** use for Vertex enterprise identity (deferred to 0.0.13+), as a substitute for Anthropic Messages, or Gemini CLI OAuth/credential-file/token import. This package is API-key-only.
+
+## Inputs / request
+
+```ts
+import {
+  createGoogleProviderPackage,
+  createGoogleGenerateContentProvider,
+  listGoogleModels,
+  defineGoogleModel,
+} from "@arnilo/prism-provider-google";
+
+createGoogleProviderPackage(options?: GoogleProviderPackageOptions): ProviderPackage
+createGoogleGenerateContentProvider(options?): AIProvider
+listGoogleModels(options?: ListGoogleModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Host-owned Google/Gemini API key (late-bound). |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Override default Gemini REST base. |
+| `id` | `string` | Provider id (default `google`). |
+| `userAgent` | `string` | Optional User-Agent. |
+| `models` | `readonly ModelConfig[]` | Override featured offline models. |
+
+Featured offline aliases include `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, and `gemini-3.5-flash` (see package README for the live curated list). Caller-gated discovery: `listGoogleModels()` — never during setup. Model ids may arrive prefixed with `models/`; Prism strips the prefix.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text, thinking when present, **complete** `tool_call` events (Gemini does not stream argument deltas), usage, `done`, redacted `error`. |
+| Cache | No Anthropic-style `cache_control`; Gemini implicit caching is not exposed as Prism breakpoints in 0.0.11. |
+| Multimodal | `inlineData` parts with MIME + base64; capability checks fail closed for unsupported modalities. |
+| Auth | `api_key`; provider-owned `content-type` + `x-goog-api-key` win over caller headers. No OAuth descriptor or Gemini CLI subscription adapter is registered. |
+
+## Request/response example
+
+```json
+{
+  "contents": [{ "role": "user", "parts": [{ "text": "Hello" }] }],
+  "tools": [{ "functionDeclarations": [{ "name": "lookup", "parameters": { "type": "object" } }] }]
+}
+```
+
+## Implementation example
+
+```ts
+import { createGoogleProviderPackage, listGoogleModels } from "@arnilo/prism-provider-google";
+
+api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey }));
+
+const models = await listGoogleModels({ apiKey: hostKey });
+api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, models }));
+```
+
+## Extension and configuration notes
+
+- Register via `defineProviderPackage` / host registries; no package auto-discovery.
+- AI SDK remains an escape hatch, not the primary Google path.
+- Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `GOOGLE_API_KEY` or `GEMINI_API_KEY`.
+- 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.
+
+## Security and performance notes
+
+- No network during import/setup/default tests; credentials host-owned and late-bound.
+- Provider-owned auth headers cannot be overridden by caller headers.
+- Media bounds reuse shared provider media helpers; tool args arrive complete per chunk (no partial JSON reconstruction required).
+- Offline conformance: `@arnilo/prism/testing/provider-conformance`.
+
+## Related APIs
+
+- [Google Vertex AI](vertex.md): enterprise ADC/workload-identity package (separate from this consumer API-key package).
+- [Provider packages](../provider-packages.md): package setup + discovery contract.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
+- [Provider conformance](../provider-conformance.md): network-free assertions.
+- Package README: [`packages/provider-google/README.md`](../../packages/provider-google/README.md)

package/docs/providers/ollama.md

@@ -0,0 +1,166 @@
+# Ollama Cloud provider package
+
+## What it does
+
+`@arnilo/prism-provider-ollama` is a side-effect-free adapter for Ollama — both
+**Ollama Cloud** (`https://ollama.com`) and a **local** `ollama serve`
+(`http://localhost:11434`) — over the OpenAI-compatible
+`POST {base}/chat/completions` endpoint.
+
+- **Dynamic model discovery** — `listOllamaModels()` calls the OpenAI-compatible
+  `GET {base}/models`. No model catalog is hard-coded: available models vary by cloud
+  account or local pull, so discovery is the source of truth. Package setup never
+  fetches. (The native `GET {base}/api/tags` endpoint is an alternate catalog source;
+  Prism uses the OpenAI-compatible route for a uniform shape.)
+- **Implicit cache only** — Ollama reuses its KV/prompt cache automatically. There is
+  no request knob and no cached-token count in usage, so `Usage.cacheReadTokens` is
+  intentionally left undefined (documented ceiling below).
+- **Reasoning** — `reasoning_effort` passthrough (e.g. gpt-oss models).
+
+Cloud auth is an ollama.com API key sent as `Authorization: Bearer`; local instances
+are typically unauthenticated (omit the key).
+
+## When to use it
+
+Use it when a host app wants Ollama Cloud or local Ollama models through Prism's
+`AgentSession` runtime with OpenAI-compatible serialization and dynamic model
+discovery.
+
+Do not use it for automatic credential discovery, setup-time catalog fetches, explicit
+cache control (Ollama has none), or real-network tests (live tests stay opt-in).
+
+## Inputs / request
+
+```ts
+import {
+  createOllamaProviderPackage,
+  createOllamaProvider,
+  listOllamaModels,
+  defineOllamaModel,
+  ollamaBaseUrl,
+} from "@arnilo/prism-provider-ollama";
+
+createOllamaProviderPackage(options: OllamaProviderPackageOptions): ProviderPackage
+createOllamaProvider(options?: OllamaProviderOptions): AIProvider
+listOllamaModels(options?: ListOllamaModelsOptions): Promise<ModelConfig[]>
+defineOllamaModel(config: OllamaModelConfig): ModelConfig
+ollamaBaseUrl(options?: { baseUrl?: string; preset?: OllamaBasePreset }): string
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Ollama Cloud API key; omit for unauthenticated local. |
+| `baseUrl` | `string` | Explicit OpenAI-compatible base URL (wins over `preset`). |
+| `preset` | `OllamaBasePreset` | `"cloud"` (default) / `"local"`. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `id` | `string` | Provider id (default `ollama`). |
+| `models` | `readonly ModelConfig[]` | Host-supplied models (from `listOllamaModels`) to register. |
+
+Base URLs resolved by preset (each includes the `/v1` segment):
+
+| Preset | Base URL |
+| --- | --- |
+| `cloud` | `https://ollama.com/v1` |
+| `local` | `http://localhost:11434/v1` |
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text deltas, `delta.reasoning_content` → thinking deltas, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Usage | `prompt_tokens` → `inputTokens`, `completion_tokens` → `outputTokens` (native `prompt_eval_count`/`eval_count` are the equivalent). `cacheReadTokens` stays undefined. |
+| Discovery | `listOllamaModels()` maps `GET {base}/models` entries → `ModelConfig` (reasoning/vision inferred from id). |
+| Auth methods | `api_key` for `ollama`. |
+
+The stream parser emits `done` only on completion evidence (`[DONE]` plus a terminal
+`finish_reason` with no dangling tool calls). Truncated streams terminate with an
+`error` event instead. Unsupported block placements or unclaimed images fail before
+fetch.
+
+## Request/response example
+
+```bash
+curl 'https://ollama.com/v1/chat/completions' \
+  -H "Authorization: Bearer $OLLAMA_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "gpt-oss:20b",
+    "messages": [{ "role": "user", "content": "Hello" }],
+    "stream": true,
+    "stream_options": { "include_usage": true }
+  }'
+
+curl 'https://ollama.com/v1/models' -H "Authorization: Bearer $OLLAMA_API_KEY"
+```
+
+Usage in the final streamed chunk:
+
+```json
+{ "usage": { "prompt_tokens": 100, "completion_tokens": 5, "total_tokens": 105 } }
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import {
+  createOllamaProviderPackage,
+  listOllamaModels,
+} from "@arnilo/prism-provider-ollama";
+
+const kernel = createExtensionKernel();
+
+// Caller-gated discovery — never runs during setup.
+const models = await listOllamaModels({ apiKey: process.env.OLLAMA_API_KEY });
+
+await kernel.load([
+  createOllamaProviderPackage({
+    apiKey: process.env.OLLAMA_API_KEY, // omit for local
+    preset: "cloud", // or "local"
+    models,
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL/preset, provider id, model list, credential source, and
+  `fetch` impl. Nothing is hard-coded; register discovered models via `models:`.
+- Reasoning: `compat.reasoning_effort` (request wins over model default) maps to the
+  top-level `reasoning_effort` wire field; omitted unless explicitly a string.
+- Provider-owned compat keys (`route`, `reasoning_effort`, `ollama`) are stripped
+  before the opaque `compat` spread so they never leak into wire bodies.
+
+### Cache behavior
+
+- **Implicit only.** Ollama reuses its KV/prompt cache automatically; there is no
+  request knob and no wire marker. Prism never emits `cache_control` for Ollama.
+- **Documented ceiling:** Ollama exposes no cached-token count, so
+  `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). If a future
+  Ollama release reports cached tokens, map them in `mapOllamaModel`/usage handling.
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- The cloud API key is resolved per request via `resolveCredentialValue` and sent only
+  as `Authorization: Bearer`; keys are redacted from all thrown errors (including
+  discovery failures). Local presets send no auth header when no key is configured.
+  No local filesystem paths enter request payloads.
+- Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
+  provider-owned headers (`content-type`, `authorization`) are applied last and
+  cannot be overridden.
+- Model discovery is caller-gated and never invoked in the provider hot path.
+- Live tests stay opt-in; default tests are network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, OpenAI-compatible routes.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix (Ollama =
+  implicit only).
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/openai-compatible.md

@@ -27,9 +27,27 @@ Options:
 | Field | Type | Purpose |
 | --- | --- | --- |
 | `id` | `string` | Optional provider id. Defaults to `openai-compatible`. |
-| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended. |
+| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended unless `chatCompletionsUrl` is set. |
 | `apiKey` | `CredentialValueSource` | Optional direct/callback/resolver credential source. |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests or custom hosts. |
+| `chatCompletionsUrl` | `string \| ((request) => string)` | Optional full chat-completions URL override (Azure deployment paths). |
+| `authStyle` | `"bearer" \| "api-key" \| "none"` | Auth header style. Default `bearer`. |
+| `buildBodyExtra` | `(request) => JsonObject \| undefined` | Optional provider-specific body fields (thinking/reasoning/cache); merged over the base body. |
+| `mapMessages` | `(request) => readonly Message[]` | Optional message transform before serialization (e.g. cache-control markers). Defaults to `request.messages`. |
+| `mapUsage` | `(usage: unknown) => Usage \| undefined` | Optional usage mapping override (e.g. OpenRouter cost fields). Defaults to `mapOpenAIChatUsage`. |
+| `serializeMessage` | `(message, request) => JsonObject` | Optional custom message serializer (e.g. Z.AI `reasoning_content` replay). Defaults to assert + `serializeOpenAIChatMessage`. |
+| `doneUsage` | `boolean` | Emit the final stream usage on the `done` event (without strict completion checks). |
+| `mapHttpError` | `(response, bodyText, secrets) => Error` | Custom HTTP error mapping (e.g. NeuralWatt retry classification). Receives the response and redacted body text. |
+| `onComment` | `(text) => ProviderEvent \| undefined` | Handle SSE comment lines (text after `:`), e.g. NeuralWatt `: energy` / `: cost` telemetry. Returned events are yielded in stream order. |
+| `extraHeaders` | `(request) => Record<string, string>` | Optional extra request headers; provider auth and `content-type` still win. |
+| `transformBody` | `(body, request) => JsonObject` | Optional final body transform, applied last (token limits, compat stripping); wins over everything. |
+| `strictCompletion` | `boolean` | Require `[DONE]` and a `finish_reason`; truncated streams yield an `error` and `done` carries the final usage. |
+| `requestFailedPrefix` | `string` | Prefix for HTTP error messages. Default `OpenAI-compatible request failed`. |
+
+The subpath also exports the building blocks for provider packages that keep public body/stream helpers:
+
+- `openAIChatEvents(body, { signal, strictCompletion, doneUsage, mapUsage, onComment })`: the shared SSE stream loop as an `AsyncIterable<ProviderEvent>`.
+- `buildOpenAIChatBody(request, { mapMessages, serializeMessage, buildBodyExtra, transformBody })`: the base Chat Completions request body builder.
 
 Provider requests use the standard `ProviderRequest` shape: `model`, `messages`, optional `tools`, `metadata`, and `signal`.
 
@@ -47,7 +65,7 @@ The returned provider emits normalized `ProviderEvent` values:
 | `[DONE]` or stream end | `done` event. |
 | HTTP/stream/parsing error | `error` event with redacted `ErrorInfo`. |
 
-The adapter passes `request.signal` to `fetch` for abort propagation.
+The adapter passes `request.signal` to `fetch` for abort propagation; an already-aborted signal throws before fetch.
 
 ## Request/response example
 
@@ -108,6 +126,17 @@ const provider = createOpenAICompatibleProvider({
 - The adapter resolves `apiKey` per request through `resolveCredentialValue()`.
 - This adapter currently targets Chat Completions streaming only.
 - The serializer preserves text, thinking (downgraded to text), assistant `tool_call` blocks as `tool_calls`, `tool_result` blocks as role `tool` messages, and image blocks when the model declares `capabilities.input` includes `"image"`. Unsupported block placements or unclaimed images fail before fetch.
+- Vendor-specific OpenAI-compatible endpoints (cache markers, thinking bodies, reasoning fields, custom usage) plug in through `buildBodyExtra`/`mapMessages`/`mapUsage`/`extraHeaders` instead of duplicating the stream loop:
+
+```ts
+const provider = createOpenAICompatibleProvider({
+  baseUrl: "https://vendor.example/v1",
+  apiKey: () => process.env.VENDOR_API_KEY,
+  buildBodyExtra: (request) => ({ thinking: { type: "enabled" } }),
+  extraHeaders: () => ({ "x-vendor-app": "my-app" }),
+});
+```
+
 - 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-provider-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`.
 
 ## Security and performance notes

package/docs/providers/openai.md

@@ -50,11 +50,13 @@ uses official Responses `reasoning: { effort, summary? }` via
 
 | Surface | Behavior |
 | --- | --- |
-| Provider stream | Prism text, thinking (downgraded to text), `tool_call` deltas/finals, `usage`, `done`, redacted `error` events. |
-| Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant `tool_call` → top-level `function_call` with `call_id`; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
-| Auth methods | `api_key` for `openai`; `oauth` for `openai-codex`. |
+| Provider stream | Prism text, thinking (downgraded to text), host `tool_call` deltas/finals, provider-hosted `tool_call` events (`authority: "provider-hosted"`), `continuation_required`, `usage`, `done`, and redacted `error` events. |
+| Continuation | An incomplete Responses stream self-resumes at most eight HTTP hops using opaque `previous_response_id`; a cursor is at most 4 KiB, is never replayed, and is observable as `continuation_required`. |
+| Realtime | `createOpenAIRealtimeSession()` exposes server-session creation, audio in/out, transcript deltas, provider-hosted calls, interrupt, and idempotent close through the neutral `RealtimeSession` seam. |
+| Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant host `tool_call` → top-level `function_call` with `call_id`; provider-hosted calls are not replayed; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
+| Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. This is Prism's only first-party subscription OAuth flow in 0.0.12. |
 
-Unsupported block placements or unclaimed images fail before `fetch`.
+Unsupported block placements or unclaimed images fail before `fetch`. Provider-hosted calls are telemetry only: Prism never dispatches them as host tools or sends a `tool_result`.
 
 ## Request/response example
 
@@ -76,6 +78,21 @@ Responses request body (Codex subscription shape, abbreviated):
 }
 ```
 
+Realtime session (OpenAI session creation, abbreviated):
+
+```ts
+import { createOpenAIRealtimeSession } from "@arnilo/prism-provider-openai";
+
+const session = createOpenAIRealtimeSession({
+  model: { provider: "openai", model: "gpt-realtime-2.1" },
+  ownerId: "hashed-host-user-id",
+  apiKey,
+});
+for await (const event of session.events()) {
+  if (event.type === "audio_delta") play(event.audio);
+}
+```
+
 OAuth authorize URL (PKCE, `S256`):
 
 ```
@@ -120,11 +137,12 @@ const challenge = computeS256Challenge(verifier);
 - Hosts/apps control model selection, credential resolution, and cache policy per
   run/model through `RunOptions` and `ModelConfig.compat`.
 - OAuth browser/device-code flows run only when the caller explicitly invokes the
-  OAuth provider.
+  OAuth provider. Login UI and optional durable token storage remain host-owned; no ambient credential discovery or refresh timer is installed.
 - Device-code login polls the token endpoint with server-directed `interval` and
   `expires_in`, honors RFC 8628 `authorization_pending` / `slow_down`, and stops
   on terminal errors or expiry. Pass `signal` on `OAuthLoginCallbacks` to abort
   polling promptly.
+- `createOpenAIRealtimeSession` requires a stable host `ownerId`; it sends that value as OpenAI's safety identifier and binds the stream to the server `session.created` id. An injected `webSocket(url, { headers })` factory supports Node 22 hosts whose global WebSocket does not expose header options.
 
 ### Cache behavior
 
@@ -189,6 +207,7 @@ Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reaso
   access/refresh tokens echoed in token-endpoint failures.
 - The PKCE verifier is exchanged at the token endpoint, never sent on the authorize
   URL.
+- Realtime uses the documented WebSocket `Authorization` header, never a credential query parameter. API keys are redacted from transcript/error events; audio/transcript input is untrusted, realtime queues are bounded, and disconnect, abort, malformed session identity, or audio/byte/wall-time cap breach closes the session.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default `npm test` is network-free.
 

package/docs/providers/openrouter.md

@@ -188,9 +188,11 @@ cache-read pricing exists), and seeds `compat.reasoning.effort` from
   hidden app identity.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default tests are network-free.
+- Enterprise hosts that must gate `compat.openRouterRouting` should wrap selection with `@arnilo/prism-model-router` (`allowOpenRouterRouting`); the OpenRouter adapter itself still passthroughs routing when present on the request.
 
 ## Related APIs
 
+- [Model routing](../model-routing.md): optional allow-list/residency/budget/circuit facade and OpenRouter routing gate.
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
   `ModelConfig`/`compat`, cache policy, caller-gated discovery.
 - [Thinking and reasoning](../thinking-and-reasoning.md): `applyThinkingLevel`

package/docs/providers/vertex.md

@@ -0,0 +1,71 @@
+# Google Vertex AI
+
+## What it does
+
+`@arnilo/prism-provider-vertex` registers a Vertex AI OpenAPI-compatible Chat Completions provider authenticated with host ADC / workload identity tokens. It is intentionally separate from `@arnilo/prism-provider-google` (consumer Gemini API keys).
+
+## When to use it
+
+Use it for GCP enterprise Vertex deployments with Application Default Credentials or workload identity federation. Do not use the consumer Google package for Vertex auth semantics.
+
+## Inputs / request
+
+```ts
+import { createVertexProviderPackage } from "@arnilo/prism-provider-vertex";
+
+createVertexProviderPackage({
+  projectId: "my-gcp-project",
+  location: "europe-west1",
+  credential: () => hostAdcAccessToken(),
+  models: [{ provider: "vertex", model: "google/gemini-2.0-flash-001" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `projectId` | GCP project |
+| `location` | Vertex location / region |
+| `endpoint` | Optional full https OpenAPI base (private/custom); otherwise location-scoped default |
+| `credential` | Bearer access token source (ADC / WIF) |
+
+Default base: `https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/endpoints/openapi`.
+
+## Outputs / response / events
+
+OpenAI-compatible SSE → Prism provider events. Missing ADC token fails closed before `fetch`.
+
+## Request/response example
+
+```http
+POST https://europe-west1-aiplatform.googleapis.com/v1/projects/my-gcp-project/locations/europe-west1/endpoints/openapi/chat/completions
+Authorization: Bearer <adc-token>
+```
+
+## Implementation example
+
+```ts
+const provider = createVertexProvider({
+  projectId: "my-gcp-project",
+  location: "us-central1",
+  credential: async () => (await GoogleAuth.getAccessToken()),
+});
+```
+
+## Extension and configuration notes
+
+`@arnilo/prism-provider-google` remains API-key Gemini (`generativelanguage.googleapis.com`) and must not register Vertex OAuth/ADC. Load this package explicitly for Vertex.
+
+## Security and performance notes
+
+- No Google Cloud SDK dependency in the package.
+- Custom/private endpoint hosts are preserved.
+- Tokens redacted from errors; no import-time credential prefetch.
+- Pair with model-router residency allow-lists on `location`.
+
+## Related APIs
+
+- [Google Gemini (consumer)](google.md)
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Provider packages](../provider-packages.md)
+- [Model routing](../model-routing.md)
+- Package README: [`@arnilo/prism-provider-vertex`](../../packages/provider-vertex/README.md)

package/docs/public-contracts.md

@@ -15,7 +15,8 @@ Current contract groups:
 - Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
 - Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`
 - Stores/resources/settings/credentials/compaction/retry/cache helpers: `SessionEntry`, `SessionStore`, `StoreFactory`, `Resource`, `ResourceLoader`, `ResourceLoadContext`, `SettingsProvider`, `CredentialRequest`, `Credential`, `CredentialResolver`, `CompactionStrategy`, `CompactionContext`, `CompactionResult`, `CompactionOptions`, `CompactionMiddlewarePayload`, `CompactionEntryData`, `DefaultCompactionStrategyOptions`, `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`, `DefaultRetryPolicyOptions`, `CacheUsageReport`, `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, `cacheUsageReport`
-- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
+- Production persistence (adapter-facing): `ProductionPersistenceStore` (optional `lifecycle`), `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`, `PersistenceLifecycleStore`, `LegalHoldRecord`, `TenantQuota`
+- Identity: `Principal`, `AgentIdentity`, `IdentityVerifier`, `assertIdentityActive`, `narrowIdentity`, `ownershipFromIdentity`, `assertIdentityMatchesOwnership`, `assertIdentityPropagation`, `identityTelemetryAttributes`, `resolveRunIdentity`, `IdentityError`, identity limit constants
 
 ## When to use it
 
@@ -121,7 +122,7 @@ Important request shapes:
 | `ToolRegistry` | Host active tool registry shape: `register()`, `get()`, `resolve()`, and `list()`. |
 | `ToolExecutionContext` | Host tool execution context: session/run ids, tool call id, optional abort signal, metadata, and progress callback. |
 | `ContextResolutionContext` | Context provider input: messages plus optional session/run ids, metadata, and signal. |
-| `InputAssemblyLayout` | Default input layout selector: `"legacy"` (default) or opt-in `"cache_aware"`. |
+| `InputAssemblyLayout` | Default input layout selector: `"cache_aware"` (default) or opt-in `"legacy"`. |
 | `DefaultInputBuildContext` | Optional default input assembly context: input layout, instructions, history, summaries, attachments, explicit resources, tool results, middleware, ids, metadata, and signal. |
 | `ResolveContextOptions` | Ordered context resolution input: selected providers, messages, ids, metadata, signal, and optional middleware. |
 | `AssembleProviderInputOptions` | Provider input assembly input: model, input, optional builders, selected context providers/skills, active tools, metadata, and signal. |
@@ -132,6 +133,7 @@ Important request shapes:
 | `AgentSessionConfig` | Session creation input: optional id, agent, store, leaf id, and metadata. |
 | `RunOptions` | Per-run overrides: optional abort signal, model, input layout, max tool rounds, provider options/request policies, system prompt layers, compaction, retry, metadata, skill selection, validate, redactor, and loop. |
 | `SubscribeOptions` / `SubscriberOverflowPolicy` | Live `AgentEvent` subscriber queue limit and overflow policy: `maxQueuedEvents`, `overflow: "close" \| "drop_oldest" \| "drop_newest"`. |
+| `resumeAgentRunStream` / `AgentRunResumeStreamOptions` | One durable-run event stream: existing checkpoint/resume options plus `signal` and bounded subscriber options. `AgentRunLifecycle.resumeStream()` adds host capability resolution; no protocol types enter core. |
 | `AgentConfig.loop` / `RunOptions.loop` | Replaceable per-run control loop: `singleShotLoop` default, `generate-validate-revise` options, or a custom `AgentLoopStrategy`. `RunOptions.loop` wins. See [Agent loops](agent-loops.md). |
 | `AgentLoopStrategy` | `{ name; run(ctx: LoopContext): Promise<Usage \| undefined> }` — orchestrates shared runtime primitives via `LoopContext`. |
 | `LoopContext` | Loop-facing surface: run ids, signal, live `history`, `input`/`inputMessages`/`maxToolRounds`, and bound `assemble`/`generate`/`dispatchToolCall`/`appendMessage`/`emit` primitives. |
@@ -143,7 +145,7 @@ Important request shapes:
 | `ConfigLayer` | Named JSON config layer consumed by `mergeConfigLayers()`. |
 | `PrismManifest` | Data-only package manifest with config defaults, contribution declarations, and resource declarations. |
 | `ProductionPersistenceStore` | Adapter-facing interface for durable, paginated, multi-tenant storage plus optional `checkpoints?: CheckpointStore`, `leases?: LeaseStore`, and `feedback?: RunFeedbackStore`. No SQL/ORM/host file storage/network dependency. |
-| `CheckpointStore` | Generic versioned checkpoint capability: save/load/bounded-list/delete by namespace and key, with ownership, exact-version CAS, and lease fencing. `createMemoryCheckpointStore()` is the reference implementation. |
+| `CheckpointStore` | Generic versioned checkpoint capability: save/load/bounded-list/delete by namespace and key, with ownership, exact-version CAS, and lease fencing. `createMemoryCheckpointStore()` is the reference implementation; it is bounded — `maxRecords` (default 10,000, evicts least-recently-saved) and `maxValueBytes` (default 1 MiB per JSON value). |
 | `LeaseStore` | Atomic acquire/renew/release/get by namespace and key, with opaque claim tokens, expiry, ownership scope, and monotonically increasing takeover fences. `createMemoryLeaseStore()` is the reference implementation. |
 | `RunFeedbackStore` | Immutable append, bounded owned query, and owned deletion for ratings/comments/tags linked to existing run/trace/evaluation IDs. `createMemoryRunFeedbackStore()` is the reference implementation. |
 | `EventMultiplexer<T>` | Generic bounded fan-in from async sources. `createEventMultiplexer()` owns queue limits, overflow policy, abort, source teardown, and close behavior. |
@@ -151,6 +153,10 @@ Important request shapes:
 | `PersistenceQuery` | Common pagination controls: `cursor?`, `limit?`, `order?: "asc" \| "desc"`. |
 | `OwnershipScope` | Multi-tenant scope: `tenantId?`, `accountId?`, `userId?`. Included in records and queries. |
 | `SessionRecord` / `SessionQuery` | Stored session and query filters (parent, agent definition, retention policy, timestamps, ownership). |
+| `SessionIndex` / `SessionSearchQuery` / `SessionSearchHit` | Bounded optional session search seam (`search` / `SessionStore.searchSessions?`). Filters: workspace (`metadata.workspaceRoot`), time, provider/model, label/summary, optional FTS `query`, ownership. Hits return `sessionId` + optional `leafId` for resume; never credentials. Caps via `resolveSessionSearchQuery` / `DEFAULT_*` / `HARD_MAX_*` session-search constants. |
+| `contextBudget` / `getContextBudgetReport` / `ContextBudgetError` | Opt-in assembler budget on `AssembleProviderInputOptions`; deterministic eviction; omission report in `ProviderRequest.metadata` (kinds/ids/sizes only). |
+| `AgentSession.steer` / `SteerOptions` / pending-steer caps | Mid-run enqueue into active run; optional `softInterrupt`; default 8 msgs / 64 KiB UTF-8. |
+| `SessionSearchUnsupportedError` / `sessionSearchMode` | Memory opt-out + JSONL; typed throw (not empty success). |
 | `BranchRecord` / `BranchQuery` | Branch handle/leaf pointer and query filters (session, name, parent branch, leaf presence). |
 | `SessionEntryQuery` | Paginated entry filters: `sessionId`, `runId`, `parentId`, `leafId`, `kind`, timestamp range, ownership. |
 | `RunRecord` / `RunQuery` | Stored run and filters: session, branch, status, timestamps, ownership. |
@@ -160,6 +166,7 @@ Important request shapes:
 | `CacheUsageReport` | Numeric cache diagnostics from normalized `Usage`: read/write tokens, hit rate, estimated savings, and optional currency. |
 | `AgentDefinitionRecord` / `AgentDefinitionQuery` | Versioned agent-definition snapshot and filters. Does not store credentials or provider instances. |
 | `RetentionPolicy` / `RetentionPolicyQuery` | Retention policy and filters: age, entry count, byte limits, archive store, applied kinds. |
+| `PersistenceLifecycleStore` / `LegalHoldRecord` / `TenantQuota` | Optional hold/retention apply/export/quota capability on `ProductionPersistenceStore.lifecycle`. |
 | `MigrationRecord` / `MigrationQuery` | Applied migration record and filters. |
 
 ## Outputs / response / events
@@ -422,6 +429,8 @@ void credentials;
 - `createAgent()` and `createAgentSession()` implement the session runtime. They use explicit providers only; no hidden provider registry is created. Store-backed sessions use explicit `SessionStore` values and branch methods on `AgentSession`. `AgentSession.compact()` and `AgentConfig`/`RunOptions.compaction` provide manual and opt-in auto-compaction. `AgentConfig`/`RunOptions.retry` provide bounded provider-turn retry before observable output.
 - `createMemorySessionStore()` is the built-in in-memory `SessionStore`. Node hosts can opt into file durability with `@arnilo/prism/node/session-store-jsonl`. `createSessionEntry()`, `getSessionBranchEntries()`, `listSessionBranches()`, and `rebuildSessionContext()` are pure helpers for branch-aware session entries. `rebuildSessionContext()` understands compaction entries produced by `createDefaultCompactionStrategy()`, reducing provider-context messages while keeping raw entries. They do not read files or call providers.
 
+Phase 7 contracts: `AgentEventSource`, `ToolEffectDeclaration`/`ToolEffectStore`, and related error codes. Opt-in only; hosts without stores keep prior dispatch behavior.
+
 ## Security and performance notes
 
 - Type-only imports have no runtime side effects.
@@ -430,6 +439,53 @@ void credentials;
 - Use `unknown`/metadata fields for host data, but validate at trust boundaries before executing tools or loading resources.
 - App-specific tool categories and business domains do not belong in public contracts.
 
+## Frozen 0.1.x contract (plan 012 Task 7)
+
+Release 0.1.0 freezes the public contract surface for the 0.1.x line. The
+freeze is recorded in `scripts/phase12-freeze-manifest.json` and machine-checked
+on every `npm test` by the release gates; this section states what is frozen.
+
+**Declaration/exports surface.** Every publishable package's generated `.d.ts`
+export surface is diffed against checked-in baselines in
+`scripts/compat-baseline/` (one file per package, regenerated at 0.1.0). The
+gate fails on any removed export or changed declaration and allows additive
+exports only. **0.1.x patch promise:** additive-only declaration deltas vs the
+0.1.0 baselines, enforced by `node scripts/release.mjs gate`; a genuine break
+requires `--allow-break` plus a `docs/migration.md` entry naming the version.
+
+**Events.** The `AgentEvent` union (`agent_*`/`artifact_*`/`tool_*` variants),
+the durable `AgentEventRecord`/`DurableAgentEventRecord` shapes
+(`turn_started`, `turn_finished`, `tool_execution_started`, `message_finished`;
+run-scoped strictly increasing sequences; `redacted: true` on appends), and
+`AgentEventSource` page/cursor semantics (opaque ownership-bound cursors,
+terminal pages, at-least-once delivery) are frozen as shipped in 0.1.0. See
+[docs/agent-events.md](agent-events.md).
+
+**Protocol payloads.** AG-UI/A2UI surface state and operation payloads, ACP
+(`@arnilo/prism-ag-ui/acp`) capability advertisement and session payloads,
+MCP tool/resource/prompt payloads and OAuth discovery exchanges, A2A messages,
+and provider request/response envelopes are frozen at the 0.1.0 pins recorded
+in the freeze-manifest `support.protocol` table (`@agentclientprotocol/sdk`,
+`@modelcontextprotocol/sdk`, A2A 1.0, AG-UI 0.4.x, OpenAPI 3.1 subset).
+
+**Migration checksums.** The PostgreSQL persistence contract
+(`createPersistenceMigrationContract`, 7 steps `001_init` …
+`007_agent_event_retention_index`, sha256-checksummed rows in
+`prism_migrations`) is frozen; `assertAppliedPersistenceMigrations` fails
+closed on unknown history, incomplete legacy checksums, name mismatch, or
+checksum mismatch. Enterprise state DDL (`enterprise-postgres`) is covered by
+its own checksum contract. See [docs/database-persistence.md](database-persistence.md)
+and [docs/migration.md](migration.md).
+
+**Compatibility promise.** 0.1.x patch releases: additive exports only, no
+schema migration steps, no default-behavior changes, no new runtime
+dependencies, store compatibility maintained with 0.1.0 (persisted data
+remains readable; no upgrade step required). 0.1.0 itself is store-compatible
+with 0.0.28 (no migration) and the `0.0.17 → 0.1.0` upgrade matrix in
+[docs/migration.md](migration.md) documents every intermediate line
+(compatible / tested migration / tested refusal). The 1.x line may break the
+0.1.x surface; any break ships with a migration-guide entry first.
+
 ## Related APIs
 
 - [Input and prompt assembly](input-and-prompt-assembly.md): prompt template expansion and default input builder for strings, messages, history, attachments, resources, summaries, and tool results.
@@ -443,6 +499,7 @@ void credentials;
 - [Agent/session runtime](agent-session-runtime.md): `createAgent()` / `createAgentSession()` runtime, `AgentSession.compact()`, and auto-compaction config built on these contracts.
 - [Agent loops](agent-loops.md): `singleShotLoop` default, `generateValidateReviseLoop`, `resolveLoop`, and the `Artifact*`/`AgentLoop*`/`LoopContext` contracts.
 - [Agent events](agent-events.md): the `AgentEvent` union including `artifact_*` variants and event ordering.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional protocol package consuming `AgentEvent`, `AgentRunLifecycle`, `OwnershipScope`, and `AgentEventRecord`; AG-UI/ACP protocol types do not enter root contracts.
 - [Structured output](structured-output.md): the `ArtifactParser<T>`/`ArtifactValidator<T>`/`ArtifactRepairer<T>` seam — the only typed-output path from a loop.
 - [Session stores](session-stores.md): `SessionStore` contract, branch-aware `SessionEntry` helpers, context rebuild, and store responsibilities.
 - [Database persistence](database-persistence.md): production persistence contracts, paginated query shapes, reference schema, indexes, retention, migrations, and NoSQL mapping.
@@ -455,4 +512,4 @@ void credentials;
 - `@arnilo/prism/providers/transport`: bounded SSE/event parsing, bounded HTTP error-body reads, and JSON-object tool-argument parsing for provider packages.
 - `@arnilo/prism/providers/openai`: OpenAI Chat Completions message/tool serialization, usage mapping, and indexed message validation helpers.
 
-Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; they do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.
+Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; 0.0.16 adds `resolveRedactor(redactor?, secrets?)`, which resolves the active redactor from an explicit redactor plus known secret values (the single survivor of the former per-package copies). They do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.