@arnilo/prism 0.4.0 → 0.5.0

package/docs/server.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, cross-replica durable agent-event reconnect, opt-in durable agent status/resume, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, resource ceilings, and optional deployment seams (health/readiness, drain, host rate-limit adapter, ownership-scoped event replay, worker/coordinator lease election).
+`@arnilo/prism-core/runtime/server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, cross-replica durable agent-event reconnect, opt-in durable agent status/resume, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, resource ceilings, and optional deployment seams (health/readiness, drain, host rate-limit adapter, ownership-scoped event replay, worker/coordinator lease election).
 
 No listener starts on import. Empty `agents`/`workflows` maps expose nothing. Authentication, authorization, route selection, durable stores, TLS, distributed rate limiting, queues, and framework/serverless adaptation remain host-owned.
 
@@ -82,7 +82,7 @@ Errors use `{ "error": { "code", "message" } }`. Unknown routes/capabilities are
 
 ```ts
 import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
-import { createPrismHandler } from "@arnilo/prism-server";
+import { createPrismHandler } from "@arnilo/prism-core/runtime/server";
 
 const agent = createAgent({
   model: { provider: "mock", model: "offline" },
@@ -183,7 +183,7 @@ const valid = request.headers.get("x-prism-signature") === `sha256=${expected}`;
 
 ```ts
 import { createSecretRedactor, type AgentSession } from "@arnilo/prism";
-import { createWebhookNotifier } from "@arnilo/prism-server";
+import { createWebhookNotifier } from "@arnilo/prism-core/runtime/server";
 
 const notifier = createWebhookNotifier({
   targets: [{ url: "https://ops.example.test/prism", events: ["run.failed", "workflow.suspended"] }],
@@ -228,7 +228,7 @@ Compose beside `createPrismHandler` — Prism starts no listener, container orch
 | `rateLimit` on handler | Host adapter after authorize, before session create. Return denial `{ retryAfterMs, code, message }` → `429` + optional `Retry-After`. `createMemoryRateLimiter` is single-process only. |
 | `createPrismAgentEventReplay` | Shared `AgentEventSource` page/follow semantics for exact-owned runs. |
 | `createPrismEventReplay` / `createPrismReplayHandler` | Compatible ownership-scoped legacy `queryEvents` pages (`redacted: true`). Does not re-run work. Unauthorized replay denies. |
-| `createPrismDeploymentLease` | Lease election under `prism.server.deployment`. Coordinator replica holds `key: "coordinator"` before schedule ticks; workers run `@arnilo/prism-workflows` `createWorkflowCoordinator` for queued runs (fencing tokens). |
+| `createPrismDeploymentLease` | Lease election under `prism.server.deployment`. Coordinator replica holds `key: "coordinator"` before schedule ticks; workers run `@arnilo/prism-core/runtime/workflows` `createWorkflowCoordinator` for queued runs (fencing tokens). |
 | `createConversationService` / `createConversationHandler` | Durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) over session + event-ledger seams, with thread-bound reconnectable replay. Mounts beside the handler; see [Conversations](conversations.md). |
 | `createArtifactService` / `createArtifactHandler` | Durable artifact co-work review (attach/revise/compare/approve/reject/last-validated/delivery-link + authorized download) over the versioned checkpoint store; records persist metadata/revisions/approvals only, never file bodies. Mounts beside the handler; see [Work artifacts and review](work-artifacts-and-review.md). |
 
@@ -251,7 +251,7 @@ Network-free demo: [`examples/server-deployment-seams.ts`](../examples/server-de
 - Schedule routes never accept ownership from JSON. Services carry mandatory ownership and explicit workflow/calculator registries; route authorization cannot broaden either. Replay applies workflow ownership/hash/approval checks.
 - Agent status/resume routes exist only for keys in `agentRuns`. Supply one core `createAgentRunLifecycle({ checkpoints, resolveAgent })` capability per selected agent; its resolver returns current `{ agent, definitionRevision }`. It reuses core checkpoint parsing/CAS/fingerprint checks, returns only public state/version, and needs a durable `SessionStore` as well as checkpoints for restart-safe resume. Empty/default configuration adds no agent lifecycle route, polling, or server cache.
 
-A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-supervisor` and explicitly mount `createA2AHandler()` when protocol interoperability is required; this keeps cards and remote invoke absent from ordinary Prism servers.
+A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-core/runtime/supervisor` and explicitly mount `createA2AHandler()` when protocol interoperability is required; this keeps cards and remote invoke absent from ordinary Prism servers.
 
 ## Related APIs
 

package/docs/settings-auth-trust-security.md

@@ -34,11 +34,13 @@ console.log(await settings.get("demo.enabled"));
 ## Implementation example
 ```ts
 import { createAgent, createMemoryCredentialStore, createSecretRedactor, resolveCredentialValue } from "@arnilo/prism";
-import { loadSettingsFiles, defaultUserSettingsPath } from "@arnilo/prism/node/settings";
+import { loadSettingsFiles } from "@arnilo/prism/node/settings";
 import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 const settings = await loadSettingsFiles([
-  { name: "user", path: defaultUserSettingsPath(), optional: true },
+  { name: "user", path: join(homedir(), ".config", "prism", "settings.json"), optional: true },
 ]);
 const credentials = createMemoryCredentialStore();
 credentials.set({ name: "api", provider: "demo", credential: { type: "api_key", value: "token-value" } });
@@ -57,7 +59,7 @@ void agent;
 ```
 
 ## Extension and configuration notes
-Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-credentials-node`](credential-storage.md) provides encrypted-file and system-keychain backends. Pass concrete settings values or credential resolvers to the provider/request edge that needs them; do not place them on `AgentConfig`.
+Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-core/credentials/node`](credential-storage.md) provides encrypted-file and system-keychain backends. Pass concrete settings values or credential resolvers to the provider/request edge that needs them; do not place them on `AgentConfig`.
 
 ## Security and performance notes
 Prism does not sandbox host tools or extensions. Prism does not read environment variables, keychains, user config files, package manifests, resources, settings providers, credential resolvers, or project-local extensions unless the host explicitly wires those operations. Redaction is exact known-secret replacement only; it is not secret detection. Permission and trust checks are one operation per guarded call and add no workers, watchers, retries, network, or filesystem scans.
@@ -81,8 +83,8 @@ Boundary hardening summary:
 - `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `resolveCredentialValue`
 - `createStaticTrustPolicy`, `assertTrusted`, `isTrusted`, `TrustDeniedError`
 - `createStaticPermissionPolicy`, `assertPermission`, `checkPermission`, `PermissionDeniedError`
-- `ExecutionPolicy`, `assertExecutionAllowed`, `checkExecution`, `ExecutionDeniedError` (core); `@arnilo/prism-coding-security` for coding-tool approval adapters — see [Coding execution approval and sandboxing](coding-security.md)
+- `ExecutionPolicy`, `assertExecutionAllowed`, `checkExecution`, `ExecutionDeniedError` (core); `@arnilo/prism-coding-tools/security` for coding-tool approval adapters — see [Coding execution approval and sandboxing](coding-security.md)
 - `createSecretRedactor`, `redactMessage`, `redactAgentEvent`, `redactSessionEntry`, `redactProviderRequest`
-- `@arnilo/prism/node/settings`: `defaultUserSettingsPath`, `readSettingsFile`, `loadSettingsFiles`
+- `@arnilo/prism/node/settings`: `readSettingsFile`, `loadSettingsFiles` (`defaultUserSettingsPath` was removed in 0.5.0 — build the path with `node:os`/`node:path`)
 - `@arnilo/prism/node/trust`: `createPathTrustPolicy`, `isPathInside`, `isPathInsideReal`
 - [Contribution discovery (workspace)](contribution-discovery.md): `createPathTrustPolicy` + `isPathInsideReal` gate workspace contribution roots fail-closed.

package/docs/sheets.md

@@ -225,5 +225,5 @@ const telemetry: SheetsTelemetry = {
 ## Related APIs
 
 - [`@arnilo/prism-office/documents`](./documents.md): Specification-compliant OpenXML document generation, parsing, patching, and preview rendering for DOCX, XLSX, and PPTX.
-- [`@arnilo/prism-document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
-- [`@arnilo/prism-observability-opentelemetry`](./observability.md): OpenTelemetry instrumentation and trace adapters.
+- [`@arnilo/prism-coding-tools/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
+- [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.

package/docs/speech.md

@@ -0,0 +1,126 @@
+# Speech synthesis and transcription
+
+## What it does
+
+`SpeechProvider` is the provider-neutral speech contract: text→audio via
+`synthesize` (full bytes) and `synthesizeStream` (first chunk as soon as the
+provider responds). `TranscriptionProvider` is audio→text via `transcribe`
+(one-shot) and `transcribeStream` (partial `TranscriptDelta` events, then one
+`done`), sharing the Realtime `transcript_delta` event naming. Adapters ship in
+[`@arnilo/prism-providers/openai`](providers/openai.md) (`/v1/audio/speech`,
+`/v1/audio/transcriptions`); offline conformance runs via `runSpeechConformance`
+and `runTranscriptionConformance` from `@arnilo/prism/testing/provider-conformance`.
+
+## When to use it
+
+Use it for one-shot voice output and batch/stream transcription where the host
+owns playback, capture, and audio storage. Do not use it for interactive
+bidirectional voice — that is the Realtime session contract
+([`RealtimeSession`](public-contracts.md)), which keeps its own
+`audio_delta`/`transcript_delta` events. Streaming here is one-directional:
+synthesis streams audio out, transcription streams text in.
+
+## Inputs / request
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | `string` | Speech model (`tts-1`, `gpt-4o-mini-tts`) or transcription model (`whisper-1`, `gpt-4o-transcribe`). |
+| `input` | `string` (speech) | Text to speak; non-empty, within the provider input cap (OpenAI: 4,096 chars). |
+| `audio` | `Uint8Array` (transcription) | Audio bytes; non-empty, within the provider cap (OpenAI: 25 MiB). |
+| `voice` / `format` / `speed` | `string?` / `string?` / `number?` (speech) | Voice id, audio container (`mp3`, `wav`, `opus`), playback speed. Adapter defaults when omitted. |
+| `format` / `language` / `prompt` | `string?` | Audio container hint (maps to the upload filename), ISO-639-1 hint, spelling hint. |
+| `signal` | `AbortSignal?` | Cancellation; observed by the adapter transport. |
+
+Adapter options: `apiKey` (`CredentialValueSource` — the existing credential
+seam, resolved per call and redacted from errors), `baseUrl`, `fetch` (inject a
+fake transport for offline tests), `headers`, provider defaults
+(`voice`/`format`), and `maxAudioBytes` (response ceiling for synthesis,
+input ceiling for transcription).
+
+## Outputs / response / events
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `audio` | `Uint8Array` / `ReadableStream<Uint8Array>` | Full synthesized bytes, or chunks in order — the first chunk is available as soon as the provider responds. |
+| `format` | `string` | Actual audio container (request value or provider default). |
+| `text` | `string` | Transcript; `TranscriptDone.text` is the final full text. |
+| `usage` | `Usage?` | Transcription token usage (streaming `done` reports it; one-shot when the provider includes it). |
+
+Streaming transcription yields `TranscriptDelta` (`{ type: "transcript_delta",
+text }`, naming aligned with `RealtimeEvent.transcript_delta` — no `role`) then
+exactly one `TranscriptDone`.
+
+Failures throw `SpeechError` / `TranscriptionError` with a stable `code`:
+`empty_input` (no text / no audio), `input_too_large` (speech text over the
+provider cap), `audio_too_large` (transcription audio over the cap),
+`request_failed` (non-2xx or stream error, secret-redacted message),
+`response_malformed` (missing text, over-ceiling audio bytes),
+`unsupported_model` (via `assertSpeechSupported` / `assertTranscriptionSupported`
+when the host checks `ModelCapabilities.speech` / `transcription`).
+
+## Request/response example
+
+```json
+{ "model": "tts-1", "input": "hello", "voice": "alloy", "response_format": "mp3" }
+```
+
+## Implementation example
+
+```ts
+import { createOpenAISpeechProvider, createOpenAITranscriptionProvider } from "@arnilo/prism-providers/openai";
+import { runSpeechConformance, runTranscriptionConformance } from "@arnilo/prism/testing/provider-conformance";
+
+const speech = createOpenAISpeechProvider({ apiKey: process.env.OPENAI_API_KEY });
+const { audio } = await speech.synthesize({ model: "tts-1", input: "hi", voice: "alloy" });
+const streamed = await speech.synthesizeStream({ model: "tts-1", input: "hi" });
+// streamed.audio is a ReadableStream<Uint8Array>; first chunk resolves at first response bytes
+
+const transcription = createOpenAITranscriptionProvider({ apiKey: process.env.OPENAI_API_KEY });
+const { text } = await transcription.transcribe({ model: "whisper-1", audio, format: "mp3" });
+for await (const event of transcription.transcribeStream({ model: "whisper-1", audio })) {
+  if (event.type === "transcript_delta") process.stdout.write(event.text);
+}
+
+// Offline conformance (fake transport, no network):
+await runSpeechConformance({
+  provider: createOpenAISpeechProvider({ apiKey: "sk-test", fetch: fakeFetch }),
+  model: "tts-1",
+  maxInputChars: 4096,
+  sample: { input: "hi", voice: "alloy" },
+});
+```
+
+## Extension and configuration notes
+
+- Implement `SpeechProvider` / `TranscriptionProvider` for other vendors; the
+  contracts are structural — no base class, no registry.
+- Models declare support with `capabilities.speech` / `capabilities.transcription`;
+  hosts gate with the `modelSupports*` / `assert*Supported` guards, mirroring the
+  structured-output and embeddings guard pattern.
+- `synthesizeStream` returns a Web `ReadableStream` and `transcribeStream` an
+  `AsyncIterable` — the repo's streaming conventions; no Node-only stream types.
+- Adapters never truncate: over-cap inputs and responses reject with typed
+  errors, so callers own splitting long text or large audio.
+
+## Security and performance notes
+
+- API keys resolve through the existing `CredentialValueSource` seam and are
+  redacted from every thrown error (`redactSecrets`); no new secret paths.
+- Synthesized audio is consumed under a byte ceiling
+  (`DEFAULT_SPEECH_MAX_AUDIO_BYTES`, 25 MiB; `maxAudioBytes` override) — the
+  stream errors instead of buffering without bound; transcription input is
+  capped before any network I/O.
+- Audio content and transcript text are never logged; error messages carry
+  status and a redacted body only.
+- One HTTP request per call; streaming paths forward provider chunks as they
+  arrive (first byte at provider RTT, no full-response buffering).
+
+## Related APIs
+
+- [Realtime sessions](public-contracts.md): `RealtimeSession` for interactive
+  bidirectional voice; `RealtimeEvent.transcript_delta` is this contract's
+  naming anchor.
+- [Provider conformance](provider-conformance.md): `runSpeechConformance` /
+  `runTranscriptionConformance` and the offline conformance matrix.
+- [Provider packages](provider-packages.md): subpath import rules for
+  `@arnilo/prism-providers/openai`.

package/docs/sqlite-persistence.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-The optional `@arnilo/prism-session-store-sqlite` package ships a production-oriented SQLite adapter that implements:
+The optional `@arnilo/prism-core/sessions/sqlite` package ships a production-oriented SQLite adapter that implements:
 
 - `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath` / bounded `searchSessions` / bounded `searchSessions`
 - `RunLedger` — durable run, event, tool-call, and usage rows
@@ -24,12 +24,12 @@ Use this package when you want a small, file-backed persistence layer on Node wi
 - single-writer or low-concurrency deployments
 - integration tests that need durable reopen semantics
 
-Do **not** use it as a substitute for PostgreSQL when you need heavy multi-writer concurrency, server-side pooling, or managed TLS. See [`@arnilo/prism-session-store-postgres`](postgres-persistence.md) for that path.
+Do **not** use it as a substitute for PostgreSQL when you need heavy multi-writer concurrency, server-side pooling, or managed TLS. See [`@arnilo/prism-core/sessions/postgres`](postgres-persistence.md) for that path.
 
 ## Inputs / request
 
 ```ts
-import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
 ```
 
 | Field | Type | Purpose |
@@ -73,7 +73,7 @@ Migrations run automatically on open and are idempotent across reopen. Under the
 
 ```ts
 import { createAgentSession } from "@arnilo/prism";
-import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
 import { runSessionStoreConformance } from "@arnilo/prism/testing/session-store-conformance";
 
 const persistence = createSqlitePersistence({ filename: "./prism.db" });

package/docs/supervisors.md

@@ -2,11 +2,11 @@
 
 ## What it does
 
-`@arnilo/prism-supervisor` adds optional runtime-selected delegation to an explicit local child allow-list. It returns normal `AgentRunResult` values and does not modify core `createAgent()` or deterministic workflows.
+`@arnilo/prism-core/runtime/supervisor` adds optional runtime-selected delegation to an explicit local child allow-list. It returns normal `AgentRunResult` values and does not modify core `createAgent()` or deterministic workflows.
 
 ## When to use it
 
-Use a supervisor when a host or agent must choose a child dynamically. Use `@arnilo/prism-workflows` for known DAGs, durable checkpoints, schedules, replay, or human suspension.
+Use a supervisor when a host or agent must choose a child dynamically. Use `@arnilo/prism-core/runtime/workflows` for known DAGs, durable checkpoints, schedules, replay, or human suspension.
 
 ## Inputs / request
 
@@ -36,7 +36,7 @@ Use a supervisor when a host or agent must choose a child dynamically. Use `@arn
 ## Implementation example
 
 ```ts
-import { createSupervisor } from "@arnilo/prism-supervisor";
+import { createSupervisor } from "@arnilo/prism-core/runtime/supervisor";
 
 const supervisor = createSupervisor({
   ownership: { tenantId: "tenant", userId: "user" },

package/docs/thinking-and-reasoning.md

@@ -2,100 +2,133 @@
 
 ## What it does
 
-Prism keeps thinking/reasoning **provider-owned on the wire** while giving hosts one portable way to set effort per turn. Model defaults live on `ModelConfig.compat` (and `capabilities.reasoning` where declared). Per-turn overrides live on `ProviderRequestOptions.compat` and win through existing `mergeProviderRequestOptions`. Shared helpers map a portable `ThinkingLevel` into the official compat fields each family already reads — they do **not** invent a second options tree.
+Prism gives hosts one portable way to set thinking/reasoning effort per model and per turn, and guarantees the level actually reaches the wire on every provider Prism ships. The single entry point is **`applyThinkingLevelForModel`**: it resolves the model's compat family, snaps the requested level to the model's **declared levels** (`capabilities.thinkingLevels`), and merges the family's compat patch into your base options. Every first-party provider catalog stamps the family and declares the per-model level set; provider resolvers translate the patch into official wire fields. Model defaults live on `ModelConfig.compat`; per-turn overrides live on `ProviderRequestOptions.compat` and win through the existing `mergeProviderRequestOptions` merge.
 
 ## When to use it
 
-- Session runs: pass `providerOptions.compat` (or `applyThinkingLevel`) on `RunOptions`.
-- Use-case workers (LLM compaction, observational memory): pass `thinkingLevel`; packages map it into `compat` via the shared helpers.
-- Provider authors: keep reading official fields from `options.compat` / `model.compat`; add package-local escape hatches only when the official API has unique knobs.
+- Session runs: pass `providerOptions` from `applyThinkingLevelForModel` on `RunOptions` — one call, no per-provider branching.
+- Use-case workers (LLM compaction, observational memory): pass `thinkingLevel`; workers call `applyThinkingLevelForModel` with the bound model.
+- Hosts building UI: read `model.capabilities.thinkingLevels` (when declared) to render a legal level picker; `isSupportedThinkingLevel` tells you whether a value is declared before sending.
+- Provider authors: read official wire fields from the compat patches below; keep unique knobs package-local.
 
-## Contract
+## Inputs / request
 
-| Layer | Surface |
-| --- | --- |
-| Model default | `ModelConfig.compat` (+ `capabilities.reasoning` when the model can reason) |
-| Per-turn override | `ProviderRequestOptions.compat` (request wins over model via merge) |
-| Portable level | `ThinkingLevel`: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` |
-| Helpers | `thinkingCompatFor`, `applyThinkingLevel`, `thinkingFamilyForModel`, `isThinkingLevel`, `normalizeThinkingLevel`, `THINKING_LEVELS` |
-| Not used | Inert `options.extra.thinkingLevel` — providers do not read `extra` for effort |
+| Input | Type | Notes |
+| --- | --- | --- |
+| `base` | `ProviderRequestOptions \| undefined` | Existing options; the patch is merged on top |
+| `level` | `string \| undefined` | Portable `ThinkingLevel` (`none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`) or an opaque provider-specific string (forward-compat passthrough) |
+| `model` | `Pick<ModelConfig, "provider" \| "compat" \| "capabilities">` | Model view used for family resolution, declared levels, and reasoning gating |
 
-```ts
-import { applyThinkingLevel, thinkingCompatFor, thinkingFamilyForModel } from "@arnilo/prism";
+## Outputs / response / events
 
-// Per-turn override on a session run (OpenAI / OpenRouter family)
-await session.run(input, {
-  providerOptions: applyThinkingLevel(undefined, "low", "openai_reasoning"),
-});
+Returns the merged `ProviderRequestOptions` (a new object when a patch applies; `base` unchanged when there is nothing to do — non-reasoning model, `noop` family, or `level` undefined).
+
+## Request/response example
+
+```json
+{ "compat": { "reasoning_effort": "high" } }
+```
+
+## Implementation example
+
+```ts
+import { applyThinkingLevelForModel } from "@arnilo/prism";
 
-// Equivalent explicit compat
+// Per-turn override on a session run
 await session.run(input, {
-  providerOptions: { compat: thinkingCompatFor("openai_reasoning", "low") },
-  // → { reasoning: { effort: "low" } }
+  providerOptions: applyThinkingLevelForModel(base, "high", model),
 });
 
-// Use-case worker: family from model metadata (or pass an explicit family)
-const family = thinkingFamilyForModel(model);
-await runObserver({
-  ...,
-  providerOptions: applyThinkingLevel(base, "low", family === "noop" ? "reasoning_effort" : family),
-});
+// Declared-level-aware UI
+const levels = model.capabilities?.thinkingLevels; // e.g. ["low","medium","high","xhigh","max"]
 ```
 
+## Contract
+
+| Layer | Surface |
+| --- | --- |
+| Adapter (use this) | `applyThinkingLevelForModel(base, level, model)` — family resolution + snap + merge in one call |
+| Model default | `ModelConfig.compat` (+ `capabilities.reasoning`, `capabilities.thinkingLevels` when declared) |
+| Per-turn override | `ProviderRequestOptions.compat` (request wins over model via merge) |
+| Portable level | `ThinkingLevel`: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` |
+| Parse / validate | `parseThinkingLevel` (known level → canonical; other non-empty string → opaque passthrough; empty/non-string → `undefined`), `isSupportedThinkingLevel(model, level)`, `thinkingLevelsForModel(model)`, `snapThinkingLevel(model, level)` |
+| Legacy helpers | `thinkingCompatFor`, `applyThinkingLevel`, `thinkingFamilyForModel`, `isThinkingLevel`, `normalizeThinkingLevel`, `THINKING_LEVELS` (still exported; prefer the adapter) |
+| Not used | Inert `options.extra.thinkingLevel` — providers do not read `extra` for effort |
+
 ## Compat families
 
-Core maps only shapes shared by ≥2 packages (or an explicit no-op). Unique knobs stay package-local.
+Core maps only shapes shared by ≥2 packages (or an explicit no-op). Unique knobs stay package-local. Family inference is **stamp-first**: `compat.thinkingFamily` set by the catalog wins, then compat-shape heuristics, then provider-id heuristics, then `capabilities.reasoning`.
 
-| Family | Compat patch | Used by (official fields) |
+| Family | Compat patch | Used by (official wire fields) |
 | --- | --- | --- |
 | `openai_reasoning` | `{ reasoning: { effort } }` | OpenAI Responses `reasoning.effort`; OpenRouter `reasoning.effort` |
-| `reasoning_effort` | `{ reasoning_effort }` | Z.AI `reasoning_effort`; NeuralWatt `reasoning_effort`; Kimi K3 `reasoning_effort`; DeepSeek `reasoning_effort`; ClinePass `reasoning_effort` |
-| `thinking_type` | `{ thinking: { type: "enabled" \| "disabled" } }` | Z.AI `thinking.type`; Kimi K2.x `thinking.type` (`none` → `disabled`); DeepSeek `thinking.type` |
+| `reasoning_effort` | `{ reasoning_effort }` | Z.AI, NeuralWatt, Kimi K3, DeepSeek, xAI, ClinePass, Hyper, Ollama, gateways (OpenAI routes) |
+| `thinking_type` | `{ thinking: { type: "enabled" \| "disabled" } }` | Z.AI `thinking.type`; Kimi K2.x; DeepSeek toggle; Qwen `enable_thinking` (via `alibabaEnableThinking`) |
+| `google` | `{ thinkingLevel }` | Google `generationConfig.thinkingConfig.thinkingLevel` (3.x) / `thinkingBudget` (2.5) |
+| `output_config_effort` | `{ output_config: { effort } }` | Anthropic Messages `output_config.effort`; DeepSeek anthropic-format endpoint |
 | `noop` | `{}` | AI SDK / host-owned adapters — effort is host-model settings |
 
-`applyThinkingLevel` defaults `family` to `reasoning_effort` when omitted. For `openai_reasoning`, an existing `compat.reasoning.summary` (or other reasoning keys) is preserved when merging `effort`.
+**Removed guidance:** do not use the `thinking_type` family to carry effort on Anthropic-routed providers — `thinking.type` is a toggle, and `enabled` without `budget_tokens` is rejected by current Anthropic APIs. Anthropic effort travels in `output_config.effort` (`output_config_effort` family).
 
-### Recommended family by first-party package
+### First-party packages
 
-| Package | Recommended family | Notes |
-| --- | --- | --- |
-| `@arnilo/prism-providers/openai` | `openai_reasoning` | First-class body `reasoning` from model + per-turn compat merge; `summary`/`mode`/`context` via compat |
-| `@arnilo/prism-providers/openrouter` | `openai_reasoning` | First-class `resolveOpenRouterReasoning` merge; prefer `reasoning` object over legacy `reasoning_effort` shorthand; `preserveThinking` replays as body `reasoning` |
-| `@arnilo/prism-providers/zai` | `reasoning_effort` (+ optional `thinking_type`) | Official `thinking` / `reasoning_effort` / `tool_stream` / `clear_thinking`; Preserved Thinking via `reasoning_content` |
-| `@arnilo/prism-providers/neuralwatt` | `reasoning_effort` | Budgets / `preserve_thinking` / `clear_thinking` / `chat_template_kwargs` stay package-local on `compat` |
-| `@arnilo/prism-providers/kimi` | K3: `reasoning_effort`; K2.x: `thinking_type` | K2.7-code thinking is always on; do not send conflicting `thinking` + `reasoning_effort` |
-| `@arnilo/prism-providers/opencode-go` | Anthropic route: thinking blocks (`thinking_type` family); OpenAI route: `reasoning_content` preserve + optional `thinking`/`reasoning_effort`/`reasoning` passthrough | Official dual endpoints; MiniMax/Qwen → Anthropic, others → OpenAI |
-| `@arnilo/prism-providers/ai-sdk` | `noop` | Host `LanguageModelV4` owns reasoning settings |
-| `@arnilo/prism-providers/deepseek` | `thinking_type` + `reasoning_effort` | Thinking on by default (`high`). `cacheRetention: "none"` or `thinking: false` disables. Tool turns must replay `reasoning_content` or the API returns 400. |
-| `@arnilo/prism-providers/xai` | replay only | Featured Completions do not send `reasoning_effort`. Reasoning models must replay `reasoning_content` or the prefix cache breaks. Do not flatten thinking into text. |
-| `@arnilo/prism-providers/clinepass` | `reasoning_effort` | Per-model `compat.thinkingLevelMap`. GLM `xhigh` passthrough (never send `max`). K3 `high` → `max`. Unsupported slots omit the field. |
+| Package | Family / behavior |
+| --- | --- |
+| `@arnilo/prism-providers/openai` | `openai_reasoning`; per-family effort tables, Responses-side clamp, `summary` preserved |
+| `@arnilo/prism-providers/openrouter` | `openai_reasoning`; API-derived `supported_efforts` levels; `preserveThinking` replays as body `reasoning` / `reasoning_content` |
+| `@arnilo/prism-providers/anthropic` | `output_config_effort`; generation-aware `adaptive`/legacy thinking |
+| `@arnilo/prism-providers/google` | `google`; 3.x `thinkingLevel` sets, 2.5 budget ranges |
+| `@arnilo/prism-providers/zai` | `reasoning_effort` (GLM-5.2/5.3 snap tables) + `thinking_type` toggle; Preserved Thinking via `reasoning_content` |
+| `@arnilo/prism-providers/kimi` | K3: `reasoning_effort` (`low/high/max`); K2.x: `thinking_type` |
+| `@arnilo/prism-providers/deepseek` | `reasoning_effort` (`low/high/max`) + `thinking_type` toggle; thinking on by default; tool turns must replay `reasoning_content` or the API returns 400 |
+| `@arnilo/prism-providers/xai` | `reasoning_effort` with declared per-model ladders; `reasoning_content` replay still required |
+| `@arnilo/prism-providers/clinepass` | `reasoning_effort` through per-model slot maps (`compat.thinkingLevelMap`); GLM `xhigh` passthrough, never `max` |
+| `@arnilo/prism-providers/neuralwatt` | `reasoning_effort` (`low/medium/high/max`); budgets + preserve/clear thinking stay package-local |
+| `@arnilo/prism-providers/hyper` | `reasoning_effort` derived from live `effort_levels`; snap instead of drop; Anthropic route emits `output_config.effort` |
+| `@arnilo/prism-providers/commandcode` / `@arnilo/prism-providers/opencode-go` | Gateway level tables (`claude-*` → `output_config_effort`, `gpt-5.6*` → `openai_reasoning`, K3/DeepSeek/GLM → `reasoning_effort`, K2.x/MiniMax/Qwen → `thinking_type`) |
+| `@arnilo/prism-providers/alibaba` | `thinking_type` mapped onto Qwen `enable_thinking` (toggle, no effort levels) |
+| `@arnilo/prism-providers/ollama` | `reasoning_effort`; `gpt-oss*` declares `low/medium/high`; native `think` field never mixed in |
+| `@arnilo/prism-providers/azure` / `.../vertex` / `.../bedrock` | OpenAI-compat sanitized forwarder (`reasoning_effort` / `reasoning` object), snapped to declared levels |
+| `@arnilo/prism-providers/ai-sdk` | `noop` — host `LanguageModelV4` owns reasoning settings |
+
+## Declared levels and snapping
 
-`thinkingFamilyForModel` infers family from existing `compat` shape, then safe provider heuristics (`openai*` → `openai_reasoning`, `neuralwatt` → `reasoning_effort`), then `capabilities.reasoning` → `reasoning_effort`, else `noop`. Docs and packages may map other provider ids explicitly; core avoids provider-specific literals beyond those heuristics.
+Every reasoning-capable model in a first-party catalog declares its legal level set (`capabilities.thinkingLevels`) and, where meaningful, a `compat.thinkingFamily` stamp. The source of truth is the [thinking coverage evidence matrix](_evidence/thinking-coverage-2026-09-05.md) — generated from the compiled catalogs, with per-model source (API-derived vs doc-pinned) and the wire/live test that pins each row.
 
-## Merge order
+Snap semantics (`snapThinkingLevel`, applied by the adapter and by provider resolvers when the model declares a set):
 
-1. `ModelConfig.compat` / model defaults inside the provider
-2. `ProviderRequestOptions.compat` from agent / session policies
-3. Per-turn `RunOptions.providerOptions` or use-case `applyThinkingLevel` patch (wins)
+1. The requested level is in the declared set → forwarded unchanged.
+2. Below the declared minimum (typically `none`/`minimal` on a set without them) → snaps **up** to the minimum.
+3. Otherwise → nearest declared level by ladder distance, **ties breaking up**.
+4. Provider-documented tables (DeepSeek, Z.AI GLM-5.2/5.3, ClinePass slot maps, Kimi K3) are wire authority and take precedence over the generic rule.
+5. Undeclared levels (opaque strings) on a reasoning-capable model → passthrough (forward compat); a non-reasoning model → options unchanged.
 
-Providers already prefer `request.options.compat.*` over `request.model.compat.*`.
+OpenRouter and Hyper derive their sets from each provider's models API (`supported_efforts` / `effort_levels`); all other catalogs are doc-pinned because those upstreams expose no enumeration API.
 
-## Use-case workers
+## Extension and configuration notes
 
-LLM compaction and observational memory accept `thinkingLevel?: string`. They call `applyThinkingLevel` into `compat` (not `extra.thinkingLevel`). When model inference returns `noop`, an explicit `thinkingLevel` still falls back to `reasoning_effort` so the host setting is never inert. Model selection for those workers (including session-model fallback) is documented in [Use-case model selection](use-case-model-selection.md).
+- `thinkingFamilyForModel(model)` resolves a family without applying it; hosts that build their own options can use `thinkingCompatFor(family, level)` directly. `compat.thinkingFamily` on a model or request overrides all heuristics.
+- For `openai_reasoning`, an existing `compat.reasoning.summary` (or other reasoning keys) is preserved when merging `effort`.
+- Package-local knobs (`thinking_budget`, `thinking_token_budget`, `chat_template_kwargs`, `cacheRetention`-coupled switches) remain on `compat` — see each provider page.
+
+## Security and performance notes
+
+- Declared levels prevent 400s from illegal effort values on strict upstreams; snapping is deterministic and ladder-based, never a silent drop.
+- `none` semantics are provider-specific (off, or minimum effort where off is unsupported — e.g. Anthropic Opus 5 cannot disable thinking at `xhigh`/`max`, GLM-5.3 cannot disable thinking at all); the per-provider pages call these out.
+- No secrets or credentials flow through any helper here; patches are plain compat objects.
 
 ## Non-reasoning models
 
-- Helper with `noop`: returns options unchanged — no invented body fields.
-- Helper with a real family on a model that rejects the field: provider/API error — hosts should gate on `capabilities.reasoning` or package docs.
+- The adapter returns options unchanged — no invented body fields.
 - `thinking_type` + `none` sets `{ type: "disabled" }`; other levels set `{ type: "enabled" }` without encoding effort (compose with `reasoning_effort` when the API supports both).
 
-## Related pages
+## Related APIs
 
-- [Use-case model selection](use-case-model-selection.md) — session vs worker/summary model binding
-- [Provider packages](provider-packages.md) — package boundaries and discovery
 - [Provider caching](provider-caching.md) — cache retention can disable thinking on some providers (e.g. Z.AI / DeepSeek when `cacheRetention: "none"`)
 - [Provider request policies](provider-request-policies.md) — `mergeProviderRequestOptions`
+- [Use-case model selection](use-case-model-selection.md) — session vs worker/summary model binding (workers take `thinkingLevel`)
 - [Agent/session runtime](agent-session-runtime.md) — prior-reasoning preservation across turns
-- Per-provider pages under [docs/providers](providers/)
-- Evidence matrix: [Review coverage (2026-07-17 provider validation)](_evidence/review-coverage-2026-07-17-provider-validation.md)
+- [Provider packages](provider-packages.md) — package boundaries and discovery
+- Per-provider pages under [docs/providers](providers/) — declared levels, wire field, and snapping per provider
+- [Thinking coverage evidence matrix](_evidence/thinking-coverage-2026-09-05.md) — per-model legality, source, and test pins
+- [Review coverage (2026-07-17 provider validation)](_evidence/review-coverage-2026-07-17-provider-validation.md)

package/docs/tool-conformance.md

@@ -101,7 +101,7 @@ await assertToolDispatchConforms(createToolRegistry(), {
 ## Security and performance notes
 
 - No credentials, no network required.
-- Supply `validate` to exercise your policy; use `createJsonSchemaToolArgumentValidator()` from `@arnilo/prism-tool-validator-json-schema` for standards-based `parameters` validation.
+- Supply `validate` to exercise your policy; use `createJsonSchemaToolArgumentValidator()` from `@arnilo/prism-core/validation/json-schema` for standards-based `parameters` validation.
 - The helper uses an allow-all permission policy by default; supply `permission` to validate your fail-closed policy.
 - Blocked calls are proven not to execute by the absence of `tool_execution_started`.
 

package/docs/tool-execution-primitives.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-This page freezes the reusable tool validation, parallel dispatch, MCP bridge, and coding execution-policy designs for Plan 055. It inventories existing `@arnilo/prism` tool harness seams, `@arnilo/prism-coding-agent` behavior, extension/contribution boundaries, and the MCP mapping surface Tasks 1–6 will implement against.
+This page freezes the reusable tool validation, parallel dispatch, MCP bridge, and coding execution-policy designs for Plan 055. It inventories existing `@arnilo/prism` tool harness seams, `@arnilo/prism-coding-tools/agent` behavior, extension/contribution boundaries, and the MCP mapping surface Tasks 1–6 will implement against.
 
 Implementation is **shipped** for JSON Schema tool argument validation (Plan 055 Task 1), parallel single-shot tool dispatch (Task 2), the MCP client bridge (Task 3), coding execution policy (Task 4), and bounded image reads (Task 5). Task 6 verification evidence is recorded in [review coverage](_evidence/review-coverage-2026-07-14.md).
 
@@ -40,7 +40,7 @@ All paths converge on normal `ToolResult` values and `tool_execution_*` events.
 
 ```ts
 import { createAgent } from "@arnilo/prism";
-import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-tool-validator-json-schema";
+import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
 
 const agent = createAgent({
   model,
@@ -123,7 +123,7 @@ Package performs **no** `PermissionPolicy`, `ToolValidator`, or trust checks of
 | --- | --- |
 | `ToolDefinition.parameters` | Stored and forwarded to providers; **not validated** by core |
 | `ToolValidator` | Host function hook; Phase 25 threads through agent runtime |
-| Standards-based schema validation | Optional `@arnilo/prism-tool-validator-json-schema`; host wires it through `ToolValidator` |
+| Standards-based schema validation | Optional `@arnilo/prism-core/validation/json-schema`; host wires it through `ToolValidator` |
 | Schema compile cache | Adapter-owned finite LRU; core never compiles schemas |
 
 ### MCP mapping (shipped — Task 3)
@@ -178,10 +178,10 @@ export function createToolParameterValidator(
 ): ToolValidator;
 ```
 
-Optional package `@arnilo/prism-tool-validator-json-schema`:
+Optional package `@arnilo/prism-core/validation/json-schema`:
 
 ```ts
-import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-tool-validator-json-schema";
+import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
 
 createAgent({ model, validator: createJsonSchemaToolArgumentValidator() });
 ```
@@ -271,7 +271,7 @@ export async function assertExecutionAllowed(
 ): Promise<ExecutionAction>;
 ```
 
-`@arnilo/prism-coding-agent` tools call `executionPolicy.check()` **inside** `execute` before side effects (after dispatch permission + argument validation). Optional `@arnilo/prism-coding-security` supplies `createCodingApprovalPolicy({ roots, approve, readOnly, commandRules })` with realpath containment, default deny patterns, metacharacter approval, approval caching, and `createSandboxBashOperations()` for pluggable sandbox backends.
+`@arnilo/prism-coding-tools/agent` tools call `executionPolicy.check()` **inside** `execute` before side effects (after dispatch permission + argument validation). Optional `@arnilo/prism-coding-tools/security` supplies `createCodingApprovalPolicy({ roots, approve, readOnly, commandRules })` with realpath containment, default deny patterns, metacharacter approval, approval caching, and `createSandboxBashOperations()` for pluggable sandbox backends.
 
 **Permission vs execution policy:** `PermissionPolicy` remains `tool:<name>:execute` at dispatch. `ExecutionPolicy` adds command/path context for coding tools only — no MCP-specific branches in core.
 
@@ -366,9 +366,9 @@ Core remains dependency-free: validators, MCP bridges, coding policy, sandboxes,
 
 | Finding / capability | Plan 055 task | Primitive / doc |
 | --- | --- | --- |
-| C-001 JSON Schema tool validation | 1 | **shipped** — `ToolArgumentValidator`, `createToolParameterValidator`, `@arnilo/prism-tool-validator-json-schema` |
+| C-001 JSON Schema tool validation | 1 | **shipped** — `ToolArgumentValidator`, `createToolParameterValidator`, `@arnilo/prism-core/validation/json-schema` |
 | C-003 MCP client bridge | 3 | **shipped** — `@arnilo/prism-mcp` |
-| C-006 Approval/sandbox for coding tools | 4 | **shipped** — `ExecutionPolicy`, `@arnilo/prism-coding-security` |
+| C-006 Approval/sandbox for coding tools | 4 | **shipped** — `ExecutionPolicy`, `@arnilo/prism-coding-tools/security` |
 | C-007 Parallel tool execution | 2 | **shipped** — `toolConcurrency`, `dispatchToolCallsInOrder`, `resolveToolConcurrency` |
 | R-011 Image size / resize option | 5 | **shipped** — `maxImageBytes`, `transformImage`, `DEFAULT_MAX_IMAGE_BYTES` on read tool |
 | Phase verification | 6 | **verified** — `npm run sdk:ready` + audit + threat-model fixtures; evidence in review coverage |

package/docs/tools.md

@@ -198,11 +198,11 @@ Core exposes schema-agnostic adapters that wrap into the same `ToolValidator` se
 - `ToolArgumentValidator` — `validate(schema, value)` with structured errors
 - `createToolParameterValidator(adapter, { missingSchema?: "allow" | "reject" })` — maps `tool.parameters` through the adapter
 
-For standards-based validation install `@arnilo/prism-tool-validator-json-schema`:
+For standards-based validation install `@arnilo/prism-core/validation/json-schema`:
 
 ```ts
 import { createAgent } from "@arnilo/prism";
-import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-tool-validator-json-schema";
+import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
 
 const agent = createAgent({
   model,
@@ -242,7 +242,7 @@ await session.run(input, {
 
 ## JSON Schema validator limits
 
-Core stores `ToolDefinition.parameters` but does not compile schemas. Hosts that install `@arnilo/prism-tool-validator-json-schema` receive pre-Ajv schema limits: 256 KiB bytes, depth 64, 10,000 properties/keywords, 128 refs, and a 256-entry LRU compiled cache by default. All reject invalid values and have finite hard ceilings. Only fragment-local `$ref` values are accepted; non-local refs, cycles, forbidden keys, and non-finite schema numbers fail before tool execution.
+Core stores `ToolDefinition.parameters` but does not compile schemas. Hosts that install `@arnilo/prism-core/validation/json-schema` receive pre-Ajv schema limits: 256 KiB bytes, depth 64, 10,000 properties/keywords, 128 refs, and a 256-entry LRU compiled cache by default. All reject invalid values and have finite hard ceilings. Only fragment-local `$ref` values are accepted; non-local refs, cycles, forbidden keys, and non-finite schema numbers fail before tool execution.
 
 ```ts
 createJsonSchemaToolArgumentValidator({
@@ -275,7 +275,7 @@ Limits (mirroring the skill-disclosure DEFAULT/HARD cap pattern):
 - `search_tools({ query, k? })` returns inert `name: short description [matched: …]` lines — no schemas or tool bodies — and marks returned tools active for the session. Activation is names-only in run persistence (`sessionState.activatedToolNames`, capped at 128 names) and inert for tools absent from the current registry; a host can reset it with `session.clearActivatedTools()`.
 - Fail closed: any index or scoring error discloses the full input list — never zero tools, never wider than the input list. Exhausting the frozen 1024-tool index cap is surfaced the same way.
 - Disclosure never grants access: dispatch re-checks registry membership and allow/deny (`unknown_tool` / `tool_denied`) on every call regardless of what was described. Search results are intersected with the disclosed list structurally — searched tools are only ever selected from that list, never widened.
-- Scoring is BM25-lite lexical (name tokens weigh ×3, IDF from the registry): bounded, dependency-free, deterministic tie-breaks. ponytail ceiling: embedder-backed scoring via `@arnilo/prism-rag` if accuracy fixtures fall short.
+- Scoring is BM25-lite lexical (name tokens weigh ×3, IDF from the registry): bounded, dependency-free, deterministic tie-breaks. ponytail ceiling: embedder-backed scoring via `@arnilo/prism-memory/rag` if accuracy fixtures fall short.
 - Cross-link: skills apply the same discipline to prompt text — see [Context and skills](context-and-skills.md).
 
 ## Guardrails

package/docs/web-tools.md

@@ -44,7 +44,7 @@ Fetch returns bounded Markdown and selected attribution. Extract validates host
 
 ```ts
 import { createEnvCredentialResolver } from "@arnilo/prism";
-import { createJsonSchemaArgumentValidator } from "@arnilo/prism-tool-validator-json-schema";
+import { createJsonSchemaArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
 import { createBraveSearch, createFirecrawlExtractor, createFirecrawlFetch, createWebTools } from "@arnilo/prism-web-tools";
 
 const credentials = createEnvCredentialResolver(process.env, {