@arnilo/prism 0.4.0 → 0.5.0

package/docs/live-testing.md

@@ -0,0 +1,126 @@
+# Live and end-to-end testing
+
+## What it does
+
+Prism ships three network-free test tiers by default (`npm test`, per-package `node --test` suites, and packed-consumer journeys) plus an opt-in **live matrix** that runs the same public surface against real credentials. This page documents how to run the live matrix, which credentials each suite needs, and the guarantees the harness gives you: a missing credential skips its suite (never fails), and secrets never enter the repo, logs, or reports.
+
+## When to use it
+
+- Before a release: prove every public export subpath still works over a real wire or real process, not just against fakes.
+- After adding a provider or protocol adapter: add a live suite, register it in `scripts/live-matrix.json`, and the coverage gate + doc-check keep the docs honest.
+- In CI: scheduled canaries probe deployed endpoints; strict mode is available for release gates.
+
+## Coverage definition (what "100%" means)
+
+- **Functional-surface 100%:** every public export subpath across the ten first-party packages (98 subpaths, tracked in `scripts/e2e-coverage.json`) is exercised by at least one suite — a hermetic unit test, a real-wire live test, a real-binary leg, or the full-surface packed journey (`scripts/e2e-full-surface.test.mjs`). The gate is `node scripts/e2e-coverage-gate.mjs` (baseline mode fails only on regressions).
+- **Line-ratchet caveat:** the per-package line-coverage thresholds in `scripts/coverage-thresholds.json` are measured by the network-free `npm test` run only. Live suites intentionally do not contribute to line coverage; 100% functional-surface coverage does not mean 100% line coverage of every branch under live conditions.
+
+## Running the matrix
+
+```sh
+npm run test:live                 # run active suites whose credentials are present
+node scripts/live-matrix.mjs --check   # validate manifest + per-suite skip/run table (no spawns)
+```
+
+| knob | effect |
+|---|---|
+| `PRISM_LIVE_ENV_FILE` | credential file, loaded with Node `--env-file` semantics. Default: `scripts/live.env` when present. Copy `scripts/live.env.example` to start. |
+| `PRISM_LIVE_FILTER=<sub>` | only suites whose id contains `<sub>` |
+| `PRISM_LIVE_STRICT=1` | any skip fails the **run** (exit 1), not the suite — for release gates |
+| `PRISM_LIVE_DRY_RUN=1` | accounting only, no spawns |
+| `PRISM_LIVE_CONCURRENCY=n` | parallel suites (default 1, sequential) |
+| `PRISM_LIVE_SUITE_TIMEOUT_MS` | per-suite kill timer (default 600000) |
+
+### Skip-not-fail contract
+
+A suite whose required credentials are absent is **skipped with a reason**, never failed. `scripts/live-matrix.json` encodes the contract per suite (`requires` all-of, `requiresAny` any-of, `optional` extras); `resolveSuiteState()` is the pure implementation the runner and the `--check` table share. Strict mode inverts the semantics deliberately: with `PRISM_LIVE_STRICT=1` a skip fails the run, because a release gate wants proof the credentials were present and the wires were exercised.
+
+### Model selection
+
+Every provider suite reads `PRISM_LIVE_<PROVIDER>_MODEL` to pin the model under test (multi-probe suites suffix `_CHAT_MODEL` / `_MESSAGES_MODEL` / `_GPT_MODEL`). Each manifest row records the wired env var and its cost-bounded default, so cost stays predictable. `wired: false` means the suite does not read that env var yet.
+
+### Report
+
+Each run writes `docs/_evidence/live-matrix-report.{json,md}`: per-suite status/duration/detail, totals, a filter/strict/dry-run annotation, and an e2e surface-coverage summary. The report contains env var **names** and model ids — never secret values.
+
+## Credential matrix
+
+Set only the rows you want to run; everything else skips. Least-privilege scope is mandatory per row: issue the narrowest credential that satisfies the named probe. Credentials live in `scripts/live.env` (gitignored) or `~/.config/prism/live.env` (out-of-repo), never in the repository, test fixtures, or CI logs; the journey suites assert the `assertNoSecretLeak` convention (from `@arnilo/prism/testing/*`) over every transcript they produce, and the manifest validator rejects secret-shaped values.
+
+<!-- generated:live-matrix:start -->
+| suite | status | required credentials | model override | least-privilege scope | cost |
+|---|---|---|---|---|---|
+| `providers/openai` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_OPENAI_MODEL` (default `gpt-5.1`) | Project-scoped chat-completion key; least privilege: restrict to chat models. | 2 requests (1 text, 1 tool-call) on the configured model. |
+| `providers/anthropic` | active | `PRISM_LIVE_PROVIDER_TESTS` + `ANTHROPIC_API_KEY` | `PRISM_LIVE_ANTHROPIC_MODEL` (default `claude-haiku-4-5`) | Chat-completion key. | 2 requests. |
+| `providers/google` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `GEMINI_API_KEY` / `GOOGLE_API_KEY` | `PRISM_LIVE_GOOGLE_MODEL` (default `gemini-2.5-flash-lite`) | Gemini API key (either var). | 2 requests. |
+| `providers/alibaba` | active | `PRISM_LIVE_PROVIDER_TESTS` + `PRISM_LIVE_DASHSCOPE_KEY` | `PRISM_LIVE_DASHSCOPE_MODEL` (default `text-embedding-v4`) | DashScope key. | 2 requests (embedding/roundtrip class). |
+| `providers/clinepass` | active | `PRISM_LIVE_PROVIDER_TESTS` + `CLINE_API_KEY` | `PRISM_LIVE_CLINEPASS_MODEL` (default `cline-pass/deepseek-v4-flash`) | Cline provider key. | 2 requests. |
+| `providers/commandcode` | active | `PRISM_LIVE_PROVIDER_TESTS` + `COMMAND_CODE_API_KEY` | `PRISM_LIVE_COMMANDCODE_CHAT_MODEL` (default `Qwen/Qwen3.8-Flash`), `PRISM_LIVE_COMMANDCODE_MESSAGES_MODEL` (default `claude-haiku-4-5-20251001`), `PRISM_LIVE_COMMANDCODE_GPT_MODEL` (default `gpt-5.6-luna`) | Command Code key; probes three cheap routed models. | 3-4 requests on cheap models. |
+| `providers/deepseek` | active | `PRISM_LIVE_PROVIDER_TESTS` + `DEEPSEEK_API_KEY` | `PRISM_LIVE_DEEPSEEK_MODEL` (default `deepseek-v4-flash`) | DeepSeek key. | 2 requests on flash-class model. |
+| `providers/hyper` | active | `PRISM_LIVE_PROVIDER_TESTS` + `HYPER_API_KEY` | `PRISM_LIVE_HYPER_CHAT_MODEL` (default `deepseek-v4-pro`), `PRISM_LIVE_HYPER_MESSAGES_MODEL` (default `qwen3.6-plus`) | Hyper key; second model probes the exact-prefix cache. | ~4 requests incl. ~1 KiB prefix cache write; sub-cent. |
+| `providers/kimi` | active | `PRISM_LIVE_PROVIDER_TESTS` + `KIMI_API_KEY` | `PRISM_LIVE_KIMI_MODEL` (default `kimi-for-coding`) | Kimi coding-plan credential. | 2 requests. |
+| `providers/neuralwatt` | active | `PRISM_LIVE_PROVIDER_TESTS` + `NEURALWATT_API_KEY` | `PRISM_LIVE_NEURALWATT_MODEL` (default `glm-5.2`) | NeuralWatt key. | 2 requests. |
+| `providers/opencode-go` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENCODE_API_KEY` | `PRISM_LIVE_OPENCODE_MODEL` (default `mimo-v2.5`) | OpenCode Go key. | 2 requests. |
+| `providers/openrouter` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENROUTER_API_KEY` | `PRISM_LIVE_OPENROUTER_MODEL` (default `anthropic/claude-sonnet-4`) | OpenRouter key (any routed model id). | 2 requests. |
+| `providers/xai` | active | `PRISM_LIVE_PROVIDER_TESTS` + `XAI_API_KEY`; optional: `PRISM_LIVE_XAI_OAUTH` | `PRISM_LIVE_XAI_MODEL` (default `grok-4.6`) | xAI key; OAuth leg additionally needs PRISM_LIVE_XAI_OAUTH=1. | 2-3 requests. |
+| `providers/zai` | active | `PRISM_LIVE_PROVIDER_TESTS` + `ZAI_API_KEY` | `PRISM_LIVE_ZAI_MODEL` (default `glm-5.2`) | Z.ai key. | 2 requests. |
+| `web-tools/brave` | active | `PRISM_LIVE_WEB` + `PRISM_BRAVE_SEARCH_TOKEN` | — | Brave Search token, least-privilege plan; 1 result per query. | 1 search request. |
+| `web-tools/exa` | active | `PRISM_LIVE_WEB` + `PRISM_EXA_API_KEY` | — | Exa key; 1 result per query. | 1 search request. |
+| `web-tools/firecrawl` | active | `PRISM_LIVE_WEB` + `PRISM_FIRECRAWL_API_KEY` | — | Firecrawl key; bounded 64 KiB markdown fetch. | 1 fetch request. |
+| `web-tools/browser-live` | active | any of: `PRISM_LIVE_PLAYWRIGHT` / `PRISM_TEST_PLAYWRIGHT` | — | Real Chromium, no secret; needs Playwright browsers installed. | Local browser session, no API spend. |
+| `web-tools/obscura-live` | active | `PRISM_LIVE_OBSCURA` + `PRISM_OBSCURA_BIN` | — | Local obscura CLI binary; suite fails closed if flag set without binary. | Local process, no API spend. |
+| `memory/observational-live` | active | `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_OPENAI_MODEL` (not wired yet) | Reuses the OpenAI key as the compaction worker provider. | A few small summarization requests. |
+| `memory/compaction-llm-live` | active | `PRISM_LIVE_COMPACTION_TESTS` | — | Stub leg today: live summary-provider checks are wired by plans/064 Task 6 (provider key + model env TBD there). | n/a until wired. |
+| `office/libreoffice-golden` | active | `PRISM_TEST_LIBREOFFICE` | — | Local LibreOffice binary renders golden documents; no secret. | Local process, no API spend. |
+| `office/drawio-live` | active | any of: `PRISM_LIVE_DRAWIO_URL` / `PRISM_TEST_DRAWIO_URL` | — | Operator-hosted drawio export service URL (not a secret). | 1-2 export requests to your own service. |
+| `core/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Throwaway PostgreSQL database URL (sessions + enterprise + event-source + memory vector legs). | Local/container DB, no API spend. |
+| `core/nats` | active | `PRISM_TEST_NATS_URL` | — | NATS server URL with JetStream enabled. | Local/container server, no API spend. |
+| `coding-tools/docker-sandbox` | active | `PRISM_TEST_DOCKER_SANDBOX` + `PRISM_TEST_DOCKER_BIN` + `PRISM_TEST_DOCKER_IMAGE` + `PRISM_TEST_DOCKER_USER` | — | Local Docker daemon + pinned minimal sandbox image; no secret. | Local containers, no API spend. |
+| `core/keychain` | active | `PRISM_TEST_KEYCHAIN` | — | Real OS keychain; writes throwaway test entries only. | Local, no API spend. |
+| `acp/client-smoke` | active | `PRISM_TEST_ACP_CLIENT` | — | Real ACP SDK client over stdio in a subprocess; sandboxed, policy never disabled. | Local process, no API spend. |
+| `canaries/deployed` | active | `PRISM_LIVE_CANARIES`; optional: `PRISM_CANARY_TIMEOUT_MS` `PRISM_CANARY_REPORT` | — | Deployed prism provider/MCP/A2A endpoints; script itself validates all PRISM_CANARY_* URL/token vars and credential-free HTTPS. | 1-4 bounded requests (64 KiB JSON cap) against your deployments. |
+| `providers/azure` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_API_KEY` + `PRISM_LIVE_AZURE_MODEL` | `PRISM_LIVE_AZURE_MODEL` (default `gpt-5.1`) | Azure OpenAI resource key. | 3-4 requests on the configured deployment. |
+| `providers/bedrock` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` | `PRISM_LIVE_BEDROCK_MODEL` (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`) | AWS access key + secret (SigV4). | 3-4 requests on haiku-class model. |
+| `providers/vertex` | active | `PRISM_LIVE_PROVIDER_TESTS` + `GOOGLE_VERTEX_PROJECT` + `PRISM_VERTEX_ACCESS_TOKEN` | `PRISM_LIVE_VERTEX_MODEL` (default `gemini-2.5-flash`) | Pre-minted Vertex bearer token (e.g. gcloud auth print-access-token). | 3-4 requests on flash-class model. |
+| `providers/ollama` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OLLAMA_BASE_URL` | `PRISM_LIVE_OLLAMA_MODEL` (default `(first model served by OLLAMA_BASE_URL)`) | No credential for local ollama serve; Ollama Cloud key optional via provider options. | 3-4 requests on the first locally pulled model. |
+| `providers/ai-sdk` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_AISDK_MODEL` (default `gpt-5.1`) | Reuses OPENAI_API_KEY through the real @ai-sdk/openai provider. | 3 requests on gpt-5.1. |
+| `providers/model-discovery` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `OPENAI_API_KEY` / `GEMINI_API_KEY` | — | Reuses OPENAI_API_KEY or GEMINI_API_KEY for a real listing request. | 2 GET /models requests (second cached in TTL). |
+| `cli/live-journey` | planned | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | — | Packed CLI: init/provider-add/print/json/rpc over a real provider; transcript secret-scanned. | 1 pack + install, offline scaffold tests, <=3 wire prompts on the selected provider model (wire legs skip on 401/403). |
+| `memory/rag-rerankers-live` | active | any of: `PRISM_TEST_TEI_RERANKER_URL` / `PRISM_TEST_HOSTED_RERANK_URL`; optional: `PRISM_TEST_HOSTED_RERANK_URL` | `PRISM_LIVE_TEI_RERANKER_MODEL` (default `(endpoint default model)`), `PRISM_LIVE_HOSTED_RERANK_MODEL` (default `(endpoint default model)`) | Real TEI / OpenAI-compatible rerank endpoints; each leg self-skips when its endpoint env is unset. | 1 rerank request per configured endpoint (≤2 total). |
+| `coding-tools/openapi-live` | active | `PRISM_LIVE_OPENAPI_TOOLS` | — | Real public OpenAPI 3.1 spec (warnely.com) + real GET tool calls; no credential. | 3 HTTP requests against example.com-class public hosts (plan budget ≤5). |
+| `coding-tools/computer-use-live` | active | `PRISM_TEST_COMPUTER_USE` + `PRISM_COMPUTER_USE_BIN` | — | Real host computer-use-linux MCP binary over stdio; real tool inventory + one bounded read-only screenshot. | Local desktop only; ≤30s ceiling. |
+| `mcp/client-smoke` | active | `PRISM_TEST_MCP_CLIENT` | — | Real @modelcontextprotocol/client SDK over a real stdio subprocess serving createPrismMcpServer. | Local only; ≤30s. |
+| `core/opa-live` | active | `PRISM_TEST_OPA_URL` | — | Operator-hosted OPA REST endpoint (optionally token-gated). | <=3 decision requests to the operator OPA endpoint; fail-closed probe never reaches the wire. |
+| `core/oidc-live` | active | `PRISM_TEST_OIDC_ISSUER` + `PRISM_TEST_OIDC_AUDIENCE` + `PRISM_TEST_OIDC_TOKEN` | — | Real IdP issuer/JWKS + short-lived test bearer token. | 1 JWKS fetch (cached) + 3 local verify calls; no token endpoint traffic. |
+| `core/webhooks-live` | active | `PRISM_TEST_WEBHOOK_URL` | — | Operator-controlled signed webhook receiver. | <=3 webhook deliveries (1 signed target + 1 loopback retry receiver). |
+| `core/artifact-bodies-s3-live` | active | `PRISM_TEST_S3_ENDPOINT` + `PRISM_TEST_S3_KEY` + `PRISM_TEST_S3_SECRET` + `PRISM_TEST_S3_BUCKET` | — | Dedicated throwaway S3-compatible bucket. | <=5 S3 requests (put/get/presign/delete x2). |
+| `cli/journey` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `KIMI_API_KEY` / `ZAI_API_KEY` / `OPENCODE_API_KEY` / `NEURALWATT_API_KEY` / `DASHSCOPE_API_KEY` / `OLLAMA_API_KEY` | — | First init-catalog provider credential present in the environment. | 4-5 one-shot requests on the default catalog model. |
+| `memory/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Postgres memory store + pgvector index round-trips on the operator database. | Bounded insert/query cycles against the configured Postgres. |
+| `memory/graft` | active | — (hermetic leg) | — | Graft upstream CLI child-process protocol (real binary spawns against the in-repo fixture graft bin). | Hermetic; no network. |
+| `memory/wiki` | active | — (hermetic leg) | — | Wiki lifecycle over real fs trees (init/refresh/lint/search fallback; qmd child-process client degrades without the binary). | Hermetic; no network. |
+| `coding-tools/lsp-forge` | active | — (hermetic leg) | — | LSP/language-intelligence + forge suites: real child-process spawns over the real LSP/forge wire protocols against fixture binaries. | Hermetic; no network. |
+| `ag-ui/conformance` | active | — (hermetic leg) | — | AG-UI + ACP conformance suites: real-event replay over the acp/a2a/ag-ui protocol surfaces (fixture agents, real event-source wire semantics). | Hermetic; no network. |
+| `prism-providers/conformance` | active | — (hermetic leg) | — | Plan-065 machine-checked thinking coverage: every first-party reasoning catalog model declares capabilities.thinkingLevels + a compat.thinkingFamily stamp and emits a legal effort field on the wire (14 catalogs walked hermetically). | free |
+<!-- generated:live-matrix:end -->
+
+## Strict CI workflow
+
+The scheduled [`live-canaries` workflow](../.github/workflows/live-canaries.yml) (Tuesdays 05:43 UTC, plus `workflow_dispatch`) runs four restricted protocol canaries — provider, MCP, A2A, and Brave search — from a GitHub `live-canaries` environment, with every value supplied through repository secrets and a 15 s per-canary timeout. It runs `scripts/live-canary.mjs` (gated on `PRISM_LIVE_CANARIES=1`, which requires **all** canary credentials together so A2A never runs standalone) and uploads the status report as a workflow artifact. The full live matrix runs on a weekly schedule (and on demand) via the [`live-matrix` workflow](../.github/workflows/live-matrix.yml): strict-mode filtered run (default `providers/opencode-go`, the credentialed suites) with the report + e2e-coverage evidence uploaded as artifacts; operators also run it from a credentialed checkout with `npm run test:live`, optionally `PRISM_LIVE_STRICT=1` when gating a release.
+
+## Security and performance notes
+
+- Credentials never enter the repo, test fixtures, logs, or reports; only env var names and model ids are persisted. `assertNoSecretLeak` (exported from `@arnilo/prism/testing/*`) runs over live transcripts, and secret-shaped values in `scripts/live-matrix.json` are rejected by the manifest validator.
+- Suite costs are bounded and recorded per row; provider model defaults are the cheapest cost-bounded models that satisfy each probe.
+- Per-suite `PRISM_LIVE_SUITE_TIMEOUT_MS` kill timers and opt-in `PRISM_LIVE_CONCURRENCY` parallelism keep a stuck wire from stalling the run.
+- Packaging tests run under `scripts/with-build-lock.mjs` so parallel suites never race the TypeScript build.
+
+## Extension and configuration notes
+
+- Add a suite: write the env-gated test (skip-not-fail), register it in `scripts/live-matrix.json` (`id`, `package`, `status`, `source`, `command`, `cwd`, `requires`/`requiresAny`, model wiring, least-privilege `scope`, `cost`), then run `node scripts/generate-live-docs.mjs --write` to refresh the table above. `scripts/live-doc-check.test.mjs` fails `npm test` when the doc drifts.
+- Add a credential: extend `scripts/live.env.example` and the relevant manifest `requires` list. Prefer `requiresAny` when a probe accepts several interchangeable providers.
+
+## Related APIs
+
+- `@arnilo/prism/testing/*` conformance helpers (`assertProviderStreamConforms`, `assertNoSecretLeak`): the assertion vocabulary live suites reuse.
+- `scripts/e2e-coverage-gate.mjs` + `scripts/e2e-coverage.json`: the functional-surface coverage ledger this matrix satisfies.
+- [Provider conformance](provider-conformance.md): the network-free contract checks every provider adapter must pass before a live suite is worth running.

package/docs/mcp-tools.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-mcp` has two explicit directions. Its client bridge connects hosts to remote [Model Context Protocol](https://modelcontextprotocol.io) servers and maps discovered tools to ordinary `ToolDefinition`s. Its server API registers selected Prism `ToolDefinition` and `CommandDefinition` values on the official SDK `McpServer`, with required authorization and a bounded optional Web-standard Streamable HTTP handler. The package pins `@modelcontextprotocol/sdk` **1.30.0** (MCP protocol negotiation remains SDK-owned) and adds no MCP branch to core Prism.
+`@arnilo/prism-mcp` has two explicit directions. Its client bridge connects hosts to remote [Model Context Protocol](https://modelcontextprotocol.io) servers and maps discovered tools to ordinary `ToolDefinition`s. Its server API registers selected Prism `ToolDefinition` and `CommandDefinition` values on the official SDK `McpServer`, with required authorization and a bounded optional Web-standard Streamable HTTP handler. The package pins the modular TypeScript SDK v2 packages `@modelcontextprotocol/client` and `@modelcontextprotocol/server` **2.0.0** (MCP protocol negotiation remains SDK-owned; the 2026-07-28 adoption is tracked in plan 063) and adds no MCP branch to core Prism.
 
 Primary API:
 
@@ -32,19 +32,25 @@ const app = await bridge.apps!.readResource("ui://weather/card");
 
 `bridge.apps` exposes reviewed UI metadata, linked bounded `ui://` HTML, and same-server app tools for a host renderer/proxy; it never creates an iframe or executes HTML.
 
+**Conformance and verification record (plan 063 task 7):** the official `@modelcontextprotocol/conformance` suite runs against the dual-era serving stack via `node scripts/mcp-conformance-2026.mjs` — the 20 expressible scenarios pass and the 14 scenarios requiring surface Prism does not expose (server-initiated sampling/elicitation/logging/progress from tool callbacks, `resources/subscribe`, completion capability, session-based SSE polling, non-text tool content blocks) are recorded as documented boundaries in `scripts/mcp-conformance-2026-baseline.yaml`. The CLI publishes scenarios only up to spec version 2025-11-25; the run is repeated when 2026-07-28 scenarios ship upstream. Measured on the loopback fixture (single process): legacy connect ~60ms, auto connect (with the one discovery probe) ~40ms, pinned modern connect ~20ms, steady-state bridge tool call ~4ms, uncached list walk ~5ms, cached list refresh ~2ms — the only added connect cost versus 1.x is the single negotiation probe plus SDK codec work. Security regression coverage lives in the package suites: malformed envelopes/headers, auth mix-up (`ERR_PRISM_MCP_OAUTH_ORIGIN`), SSRF/DNS-rebinding, oversized JSON/schema/results, MRTR round/replay, subscription exhaustion caps, cross-principal cache/session isolation, timeouts, cancellation, and redaction.
+
+**Extension status (revalidated 2026-09-05 against the modular SDK v2, plan 063 task 6):** MCP Apps (`io.modelcontextprotocol/ui`) is the only extension Prism negotiates — on both the 2025 legacy handshake and 2026-07-28 (modern capabilities ride per request in `params._meta`); resource reads/pagination now go through SDK v2 `listResources`/`readResource` with the same per-descriptor byte bounds, item caps, cursor-loop detection, and linked-HTML validation as before. **Tasks (`io.modelcontextprotocol/tasks`) is intentionally not advertised and not supported in this release**: neither the bridge client nor `createPrismMcpServer` declares it, draft-era `task` members on tool results fail closed (`McpBridgeError` surfaced as a `ToolResult.error`, never read as tool output; modern `resultType: "task"` fails SDK decode), and task handles are not accepted without a supported extension codec plus a durable ownership model. Re-evaluate Tasks when the official TypeScript client/server extension codec supports task result dispatch, polling/update/cancel, and subscription notifications with green conformance.
+
 ```ts
 const bridge = await connectMcpCapabilities({
   serverId: "research",
   transport: { type: "streamable-http", url, allowedOrigins: [origin] },
-  roots: () => [{ uri: "file:///workspace", name: "workspace" }],
-  sampling: hostSampling,       // host selects model/provider/credentials
-  elicitation: hostElicitation, // URL mode returns approval; Prism never opens/fetches URL
+  roots: () => [{ uri: "file:///workspace", name: "workspace" }], // deprecated: kept for legacy callers only
+  sampling: hostSampling,       // deprecated: kept for legacy callers only
+  elicitation: hostElicitation, // active; URL mode returns approval; Prism never opens/fetches URL
 });
 await bridge.listResources();
 await bridge.getPrompt("review", { topic: "security" });
 ```
 
-Server capability matrix for SDK 1.30.0: tools/resources/prompts and their list-change notifications are supported through official registrations; roots/sampling/form+URL elicitation are supported as explicit client callbacks. Missing server resources/prompts throw `McpUnsupportedCapabilityError` with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`. Resource/prompt results and sampling/elicitation inputs/results are bounded JSON. Accepted form/URL elicitation requires host-only `humanInteraction: true`; bridge strips marker before protocol output and fails closed when absent. Automatic root discovery/consent, model selection, credential resolution, URL navigation, generic command proxying, and custom JSON-RPC are unsupported.
+Roots and sampling callbacks are **deprecated with MCP 2026-07-28 (SEP-2577)** and kept only for existing legacy callers; Synapta adds nothing on those surfaces and they may be removed when the protocol revision does (earliest per spec: a revision released on or after 2027-07-28). Elicitation is the active capability: on the modern era a server answering a tool call with `input_required` is fulfilled by the SDK's MRTR driver against the same `elicitation` callback, capped by `maxMrtrRounds` (default 10, the SDK's own bound — the option can only tighten it) with the call timeout as the outer ceiling; on the legacy era the same handler serves direct `elicitation/create` requests. `humanInteraction: true` remains mandatory for accepted elicitation, and no hand-written retry/state machinery exists on either path.
+
+Server capability matrix for the modular TypeScript SDK v2 (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0): tools/resources/prompts and their list-change notifications are supported through official registrations; roots/sampling/form+URL elicitation are supported as explicit client callbacks. Missing server resources/prompts throw `McpUnsupportedCapabilityError` with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`. Resource/prompt results and sampling/elicitation inputs/results are bounded JSON. Accepted form/URL elicitation requires host-only `humanInteraction: true`; bridge strips marker before protocol output and fails closed when absent. Automatic root discovery/consent, model selection, credential resolution, URL navigation, generic command proxying, and custom JSON-RPC are unsupported.
 
 Server direction:
 
@@ -66,13 +72,17 @@ const handleMcp = await createPrismMcpWebHandler(server, {
   resolveAuthInfo: authenticateRequest,
   allowedHosts: ["api.example.test"],
   allowedOrigins: ["https://app.example.test"],
-  // Omit these two for bounded stateless JSON mode.
+  // Omit these two for dual-era serving without legacy sessions.
   sessionIdGenerator: crypto.randomUUID,
   resolveIdentity: (_request, auth) => auth ? { id: validatedPrincipalId(auth) } : false,
 });
 ```
 
-`McpServer.connect(transport)` remains available for SDK stdio or in-memory transports. The helper uses SDK `WebStandardStreamableHTTPServerTransport`; it does not start a listener. Default remains bounded stateless JSON-response mode. Supplying `sessionIdGenerator` enables SDK `MCP-Session-Id` POST/GET/DELETE/SSE lifecycle and requires exact `allowedOrigins` plus host `resolveIdentity`. Every request re-authenticates, and a different principal receives non-disclosing 404. SDK owns protocol-version/session headers and SSE semantics. SDK 1.30.0's in-memory event store is not enabled, so `Last-Event-ID` replay is explicitly unsupported; reconnect starts only through SDK-supported active session GET.
+`createPrismMcpWebHandler()` is dual-era on the modular SDK v2 serving entries. Default (factory, no `sessionIdGenerator`): modern 2026-07-28 serving through SDK `createMcpHandler` — one fresh `McpServer` per request, SDK-generated `server/discover`, result metadata, cancellation and modern headers — with the SDK stateless fallback answering 2025-era traffic; modern responses carry no `Mcp-Session-Id`. Supplying `sessionIdGenerator` keeps documented legacy `MCP-Session-Id` POST/GET/DELETE/SSE lifecycle on a sessionful `WebStandardStreamableHTTPServerTransport` beside a strict modern handler (classified legacy traffic routes separately), and still requires exact `allowedOrigins` plus host `resolveIdentity`; every request re-authenticates, and a different principal receives non-disclosing 404. `Last-Event-ID` replay remains explicitly unsupported.
+
+Security gates run in front of the SDK entries because `createMcpHandler` intentionally provides none: exact Host/Origin allowlist checks execute before body parsing, auth, and dispatch; bounded body parsing feeds `parsedBody`; verified `AuthInfo` is passed explicitly; authorization and identity checks run on every request; modern serving state never trusts a transport session id. A bare `McpServer` instance with sessions keeps legacy-only behavior; stateless mode requires a factory (one fresh server per request). The returned value stays callable and carries SDK lifecycle properties: `fetch` (same function), `close()` (tears down both eras), `notify.toolsChanged()/promptsChanged()/resourcesChanged()/resourceUpdated(uri)`, and `bus` for `subscriptions/listen`. `maxSubscriptions` (SDK default 1024) and `keepAliveMs` (SDK default 15000, 0 disables) bound modern subscription streams.
+
+`servePrismMcpStdio(factory, options)` serves dual-era stdio: the opening exchange pins the era (one factory instance per connection; `legacy: "serve"` default keeps 2025 openings working, `"reject"` answers them with the unsupported-protocol-version error), and stdout stays protocol-only. `McpServer.connect(transport)` remains available for in-memory transports; direct `server.connect()` over HTTP is legacy-only. `createPrismMcpServer({ cacheHints })` emits SEP-2549 cache hints on cacheable 2026-07-28 results (default `ttlMs: 0`, `private`). Neither HTTP nor stdio helper starts a listener or process lifecycle for you.
 
 ## When to use it
 
@@ -92,7 +102,7 @@ Do **not** use this package as a sandbox, permission engine, or auto-discovery l
 
 `McpToolBridge` exposes `tools`, optional `apps`, `refresh()`, and `close()`. Normal tools are Prism `ToolDefinition`s. Apps requires server acknowledgement; nested resource metadata wins over flat/deprecated and app-only tools stay outside `tools`. Resource reads require linked bounded `ui://` HTML5 with exact MIME; content metadata wins over list defaults.
 
-`createPrismMcpServer()` returns the SDK `McpServer`. It lists only passed tools/commands and explicitly selected `agentRuns` lifecycle tools; JSON Schema parameters are converted through installed Zod v4 for SDK validation, then Prism tool calls still pass through `dispatchToolCall` permission/validator/redactor gates. Command definitions support explicitly selected direct/background/replay workflow operations and optional ownership-scoped schedule operations from `createWorkflowCommands()`; none are registered unless the host passes those command definitions. Calls return bounded MCP text content and `isError` on denial/failure. `createPrismMcpWebHandler()` returns `(Request) => Promise<Response>`.
+`createPrismMcpServer()` returns the SDK `McpServer`. It lists only passed tools/commands and explicitly selected `agentRuns` lifecycle tools; JSON Schema parameters are converted through installed Zod v4 for SDK validation, then Prism tool calls still pass through `dispatchToolCall` permission/validator/redactor gates. Command definitions support explicitly selected direct/background/replay workflow operations and optional ownership-scoped schedule operations from `createWorkflowCommands()`; none are registered unless the host passes those command definitions. Calls return bounded MCP text content and `isError` on denial/failure. `createPrismMcpWebHandler()` remains callable for source compatibility and additionally carries `fetch`, `close`, `notify`, and `bus` from the SDK serving entry.
 
 ## Request/response example
 
@@ -241,15 +251,27 @@ import { createMcpClientAuth } from "@arnilo/prism-mcp";
 const auth = createMcpClientAuth(
   {
     state, // required persistence seam: load/save tokens, discovery, client info, code verifier
-    strategy: { kind: "static", clientId: "prism", clientSecret: "..." }, // or { kind: "dcr", clientMetadata }
+    strategy: { kind: "cimd", clientMetadataUrl: "https://client.example/oauth/metadata.json" }, // preferred
+    // or { kind: "static", clientId: "prism", clientSecret: "..." }
+    // or { kind: "dcr", clientMetadata } — deprecated (RFC 7591), application_type defaults to "native"
     redirectUri: "http://localhost:33418/callback",
     onRedirectRequired: (url) => openBrowser(url), // interactive flows
+    onInsufficientScope: "reauthorize", // or "throw" to surface SDK InsufficientScopeError instead
   },
   { serverUrl: "https://mcp.example.com/api", fetch },
 );
 ```
 
-The flow reuses the MCP SDK's `auth()` helper (401 → protected-resource metadata → RFC 8414 discovery → PKCE S256 → token exchange/refresh) wrapped in Prism policy: discovery URLs are SSRF-checked, https-only (loopback http opt-in), DNS-pinned, zero-redirect, and byte-bounded; RFC 8707 resource binding is enforced on every token request (`ERR_PRISM_MCP_OAUTH_AUDIENCE` on origin drift); issuer origin must match the discovered authorization server (`ERR_PRISM_MCP_OAUTH_ORIGIN`); bearer tokens are only ever attached to the allow-listed server origin. `McpClientAuthState` has no default implementation — production hosts back it with an encrypted/keychain store (refresh tokens must not live in plaintext persistence).
+The flow reuses the MCP SDK's `auth()` helper (401 → protected-resource metadata → RFC 8414 discovery → PKCE S256 → token exchange/refresh) wrapped in Prism policy: discovery URLs are SSRF-checked, https-only (loopback http opt-in), DNS-pinned, zero-redirect, and byte-bounded; RFC 8707 resource binding is enforced on every token request (`ERR_PRISM_MCP_OAUTH_AUDIENCE` on origin drift); issuer origin must match the discovered authorization server (`ERR_PRISM_MCP_OAUTH_ORIGIN`); bearer tokens are only ever attached to the allow-listed server origin.
+
+2026-07-28 authorization conformance (plan 063 task 5):
+
+- **Callback completion takes the full query**: `await auth.finishAuth(new URL(callbackUrl).searchParams)`. The persisted OAuth `state` is validated first (fail-closed `ERR_PRISM_MCP_OAUTH_STATE` when absent or mismatched), then the RFC 9207 `iss` parameter is checked against the persisted authorization server; the SDK independently validates `iss` against the recorded issuer (RFC 9207 §2.4) and the callback-leg AS binding (SEP-2352) before redeeming the code. Callback `error`/`error_description` fields are never surfaced after an issuer mismatch. A bare code string is accepted as the legacy form (no state/iss validation).
+- **Issuer-keyed credential storage**: persisted token/client records are SDK issuer-stamped (`StoredOAuthTokens`/`StoredOAuthClientInformation`); `McpClientAuthState` credential methods take the validated `issuer` so partitioned stores can key on it. Records stamped for a different issuer are never served, and ambiguous un-stamped pre-upgrade records are refused on issuer-keyed reads rather than guessed — re-authorization runs once and every persisted record is stamped thereafter.
+- **Registration strategy**: CIMD (SEP-991 URL-based client ids) is preferred, `static` remains supported, and `dcr` is deprecated; the DCR metadata defaults `application_type` to `"native"` when the host omits it.
+- **Insufficient-scope policy**: `onInsufficientScope: "reauthorize"` (default) runs the SDK's bounded step-up flow; `"throw"` surfaces the typed SDK `InsufficientScopeError` (with the challenge scope) instead of redirecting. Hosts gate interactive consent either way.
+
+`McpClientAuthState` has no default implementation — production hosts back it with an encrypted/keychain store (refresh tokens must not live in plaintext persistence).
 
 **Server** — advertise protected-resource metadata and challenge unauthenticated requests:
 
@@ -264,12 +286,22 @@ const handler = await createPrismMcpWebHandler(factory, {
 });
 ```
 
-The handler serves `GET /.well-known/oauth-protected-resource` and returns `401 WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"` on rejected requests. Token verification remains entirely host-owned via `resolveIdentity`; Prism only advertises and challenges.
+The handler serves `GET /.well-known/oauth-protected-resource` and returns `401 WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource", scope="<configured scopes>"` on rejected requests. Token verification remains entirely host-owned via `resolveIdentity` — the host token verifier must validate the token audience (`aud`) against the protected resource and enforce the challenged scopes; Prism only advertises and challenges.
 
 ## Vendor web MCP prototype boundary
 
 Official Exa/Firecrawl MCP servers may be tested only as explicit hardened prototypes: pin endpoint/origin/auth, inspect declared capabilities, allow-list individual tools/resources, retain all MCP bounds, and never expose generic remote passthrough. Production web research uses direct host-selected `@arnilo/prism-web-tools` adapters so provider choice, credentials, schema, and costs remain outside model control.
 
+## Real-client smoke (plans/064 Task 8)
+
+An operator-gated smoke drives `createPrismMcpServer` through the real `@modelcontextprotocol/client` SDK over a real stdio subprocess — the same shape a production MCP host uses:
+
+```bash
+PRISM_TEST_MCP_CLIENT=1 node scripts/mcp-client-smoke.mjs
+```
+
+The scenario stays sandboxed (read-only echo tool, authorize-gated denial, no policy bypass) and covers: modern auto + legacy handshakes, `tools/list` of registered capabilities, `tools/call` round-trip, the authorize gate enforced over the wire, and malformed-frame fail-closed (the transport tears the connection down instead of answering garbage). Server-initiated `elicitation/create` is a documented Prism boundary (`scripts/mcp-conformance-2026-baseline.yaml`); the bridge-side MRTR elicitation round-trip is covered over real HTTP by the package's modern-bridge tests. Registered in `scripts/live-matrix.json` as `mcp/client-smoke`.
+
 ## Related APIs
 
 - [Agent identity](agent-identity.md): optional verified identity on MCP authorize results
@@ -278,7 +310,6 @@ Official Exa/Firecrawl MCP servers may be tested only as explicit hardened proto
 - [Tool execution primitives](tool-execution-primitives.md): Plan 055 design and conformance matrix
 - [Host security guide](host-security.md): permission, trust, validation checklist
 - [Web-standard server handler](server.md): agent/workflow HTTP routes and shared remote-boundary rules
-- [Antigravity delegated agent](antigravity-agent.md): per-run loopback HTTP MCP server exposure for the official Antigravity CLI.
 - [ACP coding-host interop](acp.md): ACP clients may attach MCP servers to sessions — bounded configs (8/32 servers, 16 KiB/256 KiB config, 4 KiB/64 KiB header values), http/sse only when advertised, stdio accepted behind the gate, UNSTABLE `acp` always rejected, and every server approved by host `mcp.select` before the bridge connects.
 
 ## Testing

package/docs/middleware-hooks.md

@@ -101,7 +101,7 @@ export const extension: Extension = {
 - `retry` middleware may stop retrying or adjust delay, but runtime still owns retry event emission, abort-aware waiting, and provider-turn boundaries.
 - The registry does not discover packages, read manifests, load config, call providers, execute tools, read resources, or start sessions.
 - Hosts may pass a middleware registry into `createExtensionKernel({ middleware })` to share it with direct host code.
-- For OpenTelemetry export, prefer `session.subscribe()` + `@arnilo/prism-observability-opentelemetry` (see [Observability](observability.md)) rather than adding a parallel event bus. Middleware hooks remain for transforming payloads at named boundaries.
+- For OpenTelemetry export, prefer `session.subscribe()` + `@arnilo/prism-core/governance/observability` (see [Observability](observability.md)) rather than adding a parallel event bus. Middleware hooks remain for transforming payloads at named boundaries.
 
 ## Security and performance notes
 

package/docs/migrate-to-0.4.md

@@ -6,7 +6,7 @@
 
 ## What changes
 
-Prism 0.4 replaces 62 separate 0.3 package manifests with 11 active packages and explicit
+Prism 0.4 replaces 62 separate 0.3 package manifests with 10 active packages and explicit
 subpaths. The code and behavior move; this is not a database/data migration. It is a **package
 name and import-specifier migration**.
 
@@ -50,7 +50,8 @@ name and import-specifier migration**.
 | `@arnilo/prism-mcp` | MCP interop. |
 | `@arnilo/prism-acp-agent` | ACP interop. |
 | `@arnilo/prism-ag-ui` | AG-UI/A2A/A2UI interop. |
-| `@arnilo/prism-antigravity-agent` | Antigravity interop. |
+
+`@arnilo/prism-antigravity-agent` has no 0.4 successor. Remove it and keep delegated CLI execution in the host, composed through generic process, tool, MCP, or A2A contracts as needed.
 
 ## Package and import mapping
 
@@ -204,7 +205,6 @@ subpaths, but do not rename the dependency merely because of 0.4.
 | `@arnilo/prism-mcp` | Unchanged interop package. |
 | `@arnilo/prism-acp-agent` | Unchanged interop package. |
 | `@arnilo/prism-ag-ui` | Unchanged interop package. |
-| `@arnilo/prism-antigravity-agent` | Unchanged interop package. |
 
 ## Optional peers, host binaries, and trust boundaries
 

package/docs/migrate-to-0.5.md

@@ -0,0 +1,122 @@
+# Migrate Prism 0.4 to 0.5
+
+> **Status: released 2026-09-06** (`v0.5.0` tag). Covers every host-visible change from plan 055 onward: new provider adapters (055), security hardening (056), the dead-export cut (058), dependency majors (062), the MCP 2026-07-28 adoption (063), the CLI real-provider contract (064), and model-aware thinking effort (065).
+
+## What changes
+
+Prism 0.5 is a **lockstep cut**: all 10 publishable manifests move `0.4.x` → `0.5.0` and internal first-party ranges move `^0.4.0` → `^0.5.0`. Package names and import subpaths from 0.4 stay valid; the breaking surface is (1) 27 removed unused exports, (2) the MCP SDK module move, (3) two thinking-effort wire moves, and (4) two hardening behavior changes. Everything else is additive.
+
+## 1. New provider adapters — additive (plan 055, shipped as 0.4.1)
+
+`@arnilo/prism-providers/hyper` and `@arnilo/prism-providers/commandcode` join the first-party catalog (Hyper with chat + `/v1/responses` passthrough + intelligent-routing metadata; Command Code with dual-route chat/Anthropic-Messages and GPT-5.6 explicit caching). No action needed for existing hosts; both adapters follow the standard provider factory contract (`factory({ apiKey })`).
+
+## 2. Security hardening — behavior changes (plan 056)
+
+- **Tenant-aware store factories:** session/memory/enterprise store factory signatures now require an explicit tenant scope — constructing a durable store without a tenant fails closed. Pass the tenant in the factory options (see the store pages under `docs/`).
+- **Child process env allow-list:** spawned processes (shell default, LSP client, process sessions, computer-use-linux MCP transport) no longer inherit the ambient `process.env`. A deterministic allow-list (`buildChildEnv` / `DEFAULT_CHILD_ENV_INHERIT`, `src/agent/env.ts`) governs inheritance. If you relied on custom env vars reaching child tools, pass them explicitly through the session/spawn options.
+
+## 3. Dead-export removal — 27 symbols (plan 058, breaking)
+
+Every removed symbol was verified unused (zero in-repo references, no third-party import evidence) and carried `@deprecated` "no replacement" earlier in the same cycle. If your code compiled against 0.4 without importing any symbol below, this section does not affect you.
+
+| package | removed export | kind |
+|---|---|---|
+| `@arnilo/prism` | `statusFromState` | function |
+| `@arnilo/prism` | `isInitProvider` | type-guard function |
+| `@arnilo/prism` | `isInitTemplate` | function |
+| `@arnilo/prism` | `parseContextFile` | function |
+| `@arnilo/prism` | `parseToolFile` | function |
+| `@arnilo/prism` | `defaultUserSettingsPath` | function |
+| `@arnilo/prism` | `resolveProviderMediaBlock` | async function |
+| `@arnilo/prism` | `ProviderSecretLeakConformanceOptions` | interface |
+| `@arnilo/prism` | `runToolEffectStoreConformance` | async function |
+| `@arnilo/prism-core` | `OidcIdentityVerifierResult` | type alias |
+| `@arnilo/prism-core` | `assertDiffLines` | function |
+| `@arnilo/prism-core` | `ResolvedPromptLimits` | type alias |
+| `@arnilo/prism-core` | `encodeMetadata` | function |
+| `@arnilo/prism-core` | `parseListOffsetCursor` | function |
+| `@arnilo/prism-core` | `nodeKindOf` | function |
+| `@arnilo/prism-memory` | `DEFAULT_MAX_PROMPT_CHARS` | const |
+| `@arnilo/prism-memory` | `GRAFT_RESOLVE_ERROR_CODE` | const |
+| `@arnilo/prism-memory` | `LinterOptions` | interface |
+| `@arnilo/prism-memory` | `ResolvedGraftExtension` | interface |
+| `@arnilo/prism-memory` | `WikiCategory` | type alias |
+| `@arnilo/prism-coding-tools` | `codingSha256Hex` | function |
+| `@arnilo/prism-coding-tools` | `DEFAULT_MAX_REVIEW_DELTA_ENTRIES` | const |
+| `@arnilo/prism-coding-tools` | `HARD_MAX_REVIEW_DELTA_ENTRIES` | const |
+| `@arnilo/prism-coding-tools` | `indexErrorCode` | function |
+| `@arnilo/prism-coding-tools` | `PONYTAIL_PEER_RANGE` | const |
+| `@arnilo/prism-coding-tools` | `CavemanSkillName` | type alias |
+| `@arnilo/prism-providers` | `withOpenRouterCacheMarker` | function |
+
+Per-symbol local replacements for the two cases where 0.4 docs showed a usage pattern:
+
+- `defaultUserSettingsPath(appName)` → build the path with stdlib:
+  `join(homedir(), ".config", appName, "settings.json")` (see
+  [`docs/settings-auth-trust-security.md`](settings-auth-trust-security.md)).
+- `parseContextFile` / `parseToolFile` → colocated `CONTEXT.md` / tool-descriptor parsing is
+  host-owned; parse frontmatter with `parseAgentFile` (kept) plus your own file reading
+  (see [`docs/agent-definitions.md`](agent-definitions.md)).
+
+## 4. Dependency majors (plan 062)
+
+- **`pdf-parse` 1.1 → 2.4** (`@arnilo/prism-coding-tools` optional peer): v2 parses in a worker thread and transfers the `data` TypedArray — do not reuse the buffer after `extract`; requires Node ≥ 20.16 (repo engines already `>=20`). Embedded-script execution is hard-disabled (`isEvalSupported: false`). Extracted text is byte-identical to v1 modulo trailing newline.
+- **`better-sqlite3` 12 → 13** (`@arnilo/prism-core` optional peer): N-API rewrite with bundled prebuilt binaries (no per-Node rebuild); unsupported platforms compile from source during install. No API removals.
+- **`@napi-rs/keyring` 1.x → 2.0** (`@arnilo/prism-core`): locked/inaccessible keychain reads and deletes now **reject** with typed errors (`CredentialStoreLockedError`, `CredentialStoreUnavailableError`) instead of silently resolving `undefined`/`false`. A missing credential still resolves `undefined`. If you treated a locked keychain as an empty vault, handle the typed errors.
+
+## 5. MCP: TypeScript SDK v2 modular adoption (plan 063, breaking for MCP hosts)
+
+`@arnilo/prism-mcp` replaces the monolithic `@modelcontextprotocol/sdk` 1.30.0 with the modular v2 packages (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0 exact pins). Prism's public surface (`createPrismMcpServer`, `createPrismMcpWebHandler`) keeps its shape; hosts that imported SDK types directly must move to the v2 module imports. Highlights: modern client negotiation, SDK-managed routing headers (SEP-2243), MRTR-compatible elicitation, dual-era HTTP/stdio serving, 2026-07-28-conformant OAuth (issuer-keyed storage, RFC 9207 `iss` validation). Draft-era task vocabulary fails closed. Full migration table + legacy-session timeline: [`docs/migration.md`](migration.md), canonical API in [`docs/mcp-tools.md`](mcp-tools.md).
+
+## 6. CLI real-provider contract (plan 064)
+
+`prism --provider <id>` runs real providers: ids resolve through the init provider catalog (`templates/init/providers.json`), the factory is imported from the installed `@arnilo/prism-providers/*` package, and the credential comes from the catalog's env var. `--mode print|json|rpc` all honor it. **Contract change:** omitting `--provider` fails with a usage error (exit 2) — the mock provider runs only on explicit `--provider mock`. The RPC session factory is async-capable (`AgentSession | Promise<AgentSession>`).
+
+## 7. Model-aware thinking effort (plan 065, two wire moves)
+
+Thinking/reasoning effort is now model-aware, declared, and snapped: every reasoning-capable model in a first-party catalog declares `capabilities.thinkingLevels` and a `compat.thinkingFamily` stamp, and one adapter resolves, snaps, and merges the level.
+
+Breaking / behavior changes:
+
+1. **Anthropic Messages: `effort` → `output_config.effort`.** Prism emits `output_config: { effort }` (the `output_config_effort` family). Hosts hand-building `compat.effort` / `compat.reasoning_effort` keep working (resolver reads the aliases); hosts *reading* emitted bodies must look at `output_config.effort`. Thinking is generation-aware: 4.6+ models map bare `enabled` to `adaptive`; legacy 4.5 models get `enabled` + `budget_tokens` default 10000 (bare `enabled` without a budget is rejected upstream).
+2. **xAI now sends `reasoning_effort`** (previously dropped): grok-4.6 `low/medium/high/xhigh`, grok-4.5 `low/medium/high`, grok-4.3 `none/low/medium/high`; out-of-set values snap. `grok-build` and unknown models pass through verbatim. `reasoning_content` replay is unchanged.
+3. **Snapping replaces silent drop** on declared models: out-of-set portable levels snap to the nearest declared level (ladder distance, ties up; below-minimum snaps up). Provider-documented tables (DeepSeek, Z.AI GLM-5.2/5.3, Kimi K3, ClinePass slot maps) remain wire authority. Opaque strings on reasoning-capable models still pass through.
+4. **Azure / Vertex / Bedrock forward thinking compat** through a sanitized forwarder (`reasoning_effort` + aliases, or `reasoning` object with `summary` preserved). Unrecognized compat keys are dropped, not leaked. Hand-built `options.extra` workarounds can become `compat`.
+
+New surface on `@arnilo/prism`:
+
+| Export | Purpose |
+|---|---|
+| `applyThinkingLevelForModel(base, level, model)` | One-call adapter: family resolution + snap + merge — prefer over `applyThinkingLevel` |
+| `parseThinkingLevel(value)` | Known level → canonical; other string → opaque passthrough; empty/non-string → `undefined` (fail closed) |
+| `isSupportedThinkingLevel(model, level)` | Is the level in the model's declared set |
+| `thinkingLevelsForModel(model)` | Declared set or `undefined` |
+| `snapThinkingLevel(model, level)` | Snap to the declared set (nearest, ties up) |
+
+New compat families: `google` (`{ thinkingLevel }`) and `output_config_effort` (`{ output_config: { effort } }`). Family inference is stamp-first via `compat.thinkingFamily`.
+
+What to do:
+
+1. Replace `applyThinkingLevel(base, level, family)` call sites with `applyThinkingLevelForModel(base, level, model)`.
+2. Gate level pickers on `model.capabilities?.thinkingLevels` when present.
+3. Update any body assertion reading Anthropic top-level `effort` to `output_config.effort`.
+4. Remove xAI "never send reasoning_effort" workarounds.
+5. Nothing else: `mergeProviderRequestOptions`, `RunOptions`, and persisted shapes are unchanged.
+
+Contract reference: [`docs/thinking-and-reasoning.md`](thinking-and-reasoning.md); per-provider declared levels + wire fields on each `docs/providers/*.md` page.
+
+## Upgrade steps
+
+1. Bump every `@arnilo/*` dependency/peer to `^0.5.0`.
+2. Build; if the compiler flags a removed symbol above, apply the replacement from the table.
+3. If you host MCP: move SDK imports to the v2 modular packages (section 5).
+4. If you spawn child processes with ambient env: pass env explicitly (section 2).
+5. If you construct durable stores: pass the tenant scope (section 2).
+6. If you set thinking levels: move to `applyThinkingLevelForModel` (section 7).
+7. Run your suite. No persisted-data migration exists or is needed.
+
+## Rollback
+
+Pin the previous version: `@arnilo/prism@0.4.x` (exact pins per package). Nothing persisted
+changes under 0.5, so a pin rollback is safe. The MCP module move (section 5) is the only
+migration that touches host import code — keep a 0.4 pin if you need the monolithic SDK.

package/docs/migration.md

@@ -1,5 +1,9 @@
 # Migration guide
 
+## 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.
+
 ## 0.3.3 → 0.4.0 package reorganization (breaking)
 
 Prism 0.4 consolidates package names into explicit family subpaths. It is a dependency and import-specifier migration, not a persisted-data migration. See the complete [legacy 0.3 → 0.4 guide](migrate-to-0.4.md) for all 54 retired package mappings, profile replacements, optional peers/host binaries, security checks, rollback, and npm legacy-warning behavior.
@@ -818,7 +822,31 @@ Existing text `createA2AHandler({ exposure })`, `client.send()`, and `client.str
 
 ## 0.0.7 → 0.0.8 MCP capabilities and sessions
 
-`@arnilo/prism-mcp` now pins official SDK 1.29.0. Existing `connectMcpTools()` and stateless web handlers remain compatible. Use `connectMcpCapabilities()` for bounded resources/prompts and explicit roots/sampling/elicitation callbacks. Server resources/prompts must be selected explicitly and authorize every operation. Stateful Streamable HTTP additionally requires `sessionIdGenerator`, exact `allowedOrigins`, and host `resolveIdentity`; omission preserves stateless mode. `Last-Event-ID` replay is not enabled. Missing capability calls fail with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`.
+`@arnilo/prism-mcp` now pins the modular TypeScript SDK v2 packages (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0). Existing `connectMcpTools()` and stateless web handlers remain compatible. Use `connectMcpCapabilities()` for bounded resources/prompts and explicit callbacks. **Roots (`roots`) and sampling (`sampling`) callbacks are deprecated with protocol revision 2026-07-28 (SEP-2577)** and kept for existing legacy callers only — migrate server-hosted state to explicit tool arguments and host-side model calls; elicitation is the active capability and works across eras (legacy direct `elicitation/create` dispatch, or SDK MRTR `input_required` auto-fulfilment on the modern era, capped by `maxMrtrRounds` with the call timeout as the outer ceiling). Server resources/prompts must be selected explicitly and authorize every operation.
+
+HTTP/stdio serving is dual-era: `createPrismMcpWebHandler(factory)` now serves modern 2026-07-28 traffic through SDK `createMcpHandler` (one fresh `McpServer` per request, no `Mcp-Session-Id`, no sticky routing) with the SDK stateless fallback for 2025 traffic, and stays callable while gaining `fetch`/`close`/`notify`/`bus`. Host/origin allowlists are enforced by Prism before body parsing and auth (the SDK entry provides no validation); `maxRequestBytes`, response bounding, concurrency, and request timeouts are unchanged. Configuring `sessionIdGenerator` keeps legacy sessionful serving (identity-bound POST/GET/DELETE/SSE) beside a strict modern handler; a bare `McpServer` instance with sessions is legacy-only — pass a factory for dual-era serving. `servePrismMcpStdio(factory, options)` replaces hand-wired stdio serving with SDK dual-era `serveStdio` (era pinned by the opening exchange, stdout protocol-only). Stateful Streamable HTTP still requires `sessionIdGenerator`, exact `allowedOrigins`, and host `resolveIdentity`. `Last-Event-ID` replay is not enabled. Missing capability calls fail with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`.
+
+OAuth client behavior is 2026-07-28 conformant: `finishAuth` now takes the full callback `URLSearchParams` (persisted `state` validated fail-closed, RFC 9207 `iss` checked before the code is redeemed; the bare-code string form remains as the unvalidated legacy path — switch to the params form). Persisted token/client records are SDK issuer-stamped; `McpClientAuthState` credential methods take the validated `issuer` (existing implementations ignoring the parameter keep working for single-server hosts, but **un-stamped pre-upgrade records are refused on issuer-keyed reads** rather than guessed — hosts see one interactive re-authorization, after which every record is stamped). CIMD (SEP-991) is the preferred registration strategy, `dcr` is `@deprecated` with `application_type` defaulting to `"native"`, and `onInsufficientScope: "reauthorize" | "throw"` makes the 403 step-up policy explicit. Server 401 challenges now include the configured `scope`; host token verifiers must validate the token audience.
+
+### Monolithic SDK 1.x → modular SDK v2 migration table
+
+| v1 (`@modelcontextprotocol/sdk` 1.30.0) | v2 / current Synapta API | Notes |
+| --- | --- | --- |
+| `new Client(...)` from `sdk/client/index.js` | same name from `@modelcontextprotocol/client` | `ClientOptions` gains `versionNegotiation`, `listChanged`, `inputRequired`, `cachePartition`, `listMaxPages` |
+| `InMemoryTransport` / `StdioClientTransport` / `StreamableHTTPClientTransport` | `InMemoryTransport`/`StreamableHTTPClientTransport` from `@modelcontextprotocol/client`; `StdioClientTransport` from `@modelcontextprotocol/client/stdio` | subpath moves only |
+| `McpServer`, `WebStandardStreamableHTTPServerTransport` from `sdk/server/*` | `@modelcontextprotocol/server` root | `createMcpHandler` (dual-era HTTP) + `serveStdio` (dual-era stdio) replace hand-wired serving |
+| `client.request({method}, Schema, options)` | method-keyed `client.request(...)` or high-level `listTools`/`listResources`/`readResource`/`callTool` | per-page list walks must send an explicit cursor (`{cursor: ""}` on page 0) — the no-cursor form is the SDK's uncapped aggregate |
+| `CompatibilityCallToolResultSchema` (`toolResult` member) | gone from the client codec; `callTool` decodes `CallToolResult` only | draft-era `task` members fail closed at the bridge |
+| `server.setRequestHandler(Schema, handler)` | `setRequestHandler("method/string", handler)` with `ctx.mcpReq.{id,signal}` | `ctx.authInfo` moved to `ctx.http?.authInfo`; unknown tools now error (`-32602`) instead of `isError` results |
+| `sdk/server/auth/types.js` `AuthInfo` | `AuthInfo` from `@modelcontextprotocol/server` | type-only move |
+| `OAuthClientProvider` (string-keyed persistence) | issuer-keyed `StoredOAuthTokens`/`StoredOAuthClientInformation` + optional `ctx: {issuer}` params, `clientMetadataUrl` (CIMD) | see the OAuth paragraph above |
+| `LATEST_PROTOCOL_VERSION` mock fixtures (initialize results) | legacy-era negotiation unchanged; modern (2026-07-28) results need top-level `resultType: "complete"`, `ttlMs`, `cacheScope` | raw mock fixtures only |
+
+### Legacy-session timeline
+
+- **Now (default):** `createPrismMcpWebHandler(factory)` without `sessionIdGenerator` is stateless dual-era — modern 2026-07-28 serving plus the SDK stateless fallback for 2025 clients. No `Mcp-Session-Id`, no sticky routing, `Last-Event-ID` replay not enabled.
+- **Now (opt-in):** configuring `sessionIdGenerator` keeps identity-bound legacy sessions (POST/GET/DELETE/SSE beside the strict modern handler) for hosts that still need them; the pairing requires exact `allowedOrigins` and host `resolveIdentity`.
+- **Planned removal:** the legacy session leg is deprecated once Synapta's clients and documented hosts are modern-era; removal lands as a breaking 0.x cut with a migration note here (the `sessionIdGenerator` option disappears and legacy traffic gets the SDK stateless fallback, which 2025 clients already work against). No date is committed in this release.
 
 ## 0.0.7 → 0.0.8 OpenTelemetry adapter
 

package/docs/model-registry.md

@@ -107,14 +107,51 @@ Provider packages register models through `ProviderPackageAPI.registerModel(mode
 
 `ModelConfig.compat` remains for provider-owned inert JSON. Prefer typed fields (`capabilities`, `limits`, `cost`, `cache`) for generic behavior shared across providers.
 
+### Model-list/capability discovery with provenance
+
+`ModelDiscovery` (plan 062) is the normalized `listModels()` seam: it returns the existing `ModelConfig` contract verbatim (id = `model`, context window = `limits`, pricing hint = `cost`) plus `provenance` (`provider`, `fetchedAt` ISO timestamp, `source: "api" | "catalog"`, and `ttlMs` cache guidance). Discovery execution stays provider/host code — Prism core ships only the result types; adapters live in `@arnilo/prism-providers/model-discovery`:
+
+```ts
+import { createOpenAiCompatibleModelDiscovery, createGoogleModelDiscovery, createFakeModelDiscovery, runModelDiscoveryConformance } from "@arnilo/prism-providers/model-discovery";
+
+const discovery = createOpenAiCompatibleModelDiscovery({
+  baseUrl: "https://gw.internal/v1", // GET <baseUrl>/models
+  apiKey, // CredentialValueSource — sent as Bearer, resolved via the existing credential seam
+  catalog: registry.list(), // host overrides merged by model id; catalog fields win
+});
+const { models, provenance } = await discovery.listModels({ ttlMs: 3_600_000 });
+
+// Independent provider: Google Gemini `GET <baseUrl>/v1beta/models` (x-goog-api-key), paginated:
+const google = createGoogleModelDiscovery({ apiKey: gcpKey });
+
+// Network-free fake + conformance for any ModelDiscovery implementation:
+await runModelDiscoveryConformance(() => createFakeModelDiscovery());
+```
+
+- Passthrough normalization: entries the provider does not describe stay bare (`{provider, model}`); there is no hard-coded catalog in core or adapters. Hosts merge catalog overrides (`capabilities`/`limits`/`cost`/`displayName`) over normalized entries by model id via the `catalog` option.
+- Results cache per discovery instance within the configured TTL (default 3,600,000 ms). `listModels()` in loops performs no network until the TTL expires; `ttlMs: 0` forces a refresh. The provenance `fetchedAt`/`ttlMs` fields let hosts layer their own caching on top.
+- `ModelDiscoveryError` is the typed failure (provider label + HTTP status); credentials are resolved through the existing `CredentialValueSource` seam, redacted from every error message, and responses are byte-bounded through the shared provider transport.
+
 ## Security and performance notes
 
 - Model metadata must not contain credentials or secrets.
 - Declare truthful `capabilities.input` tags. Prism core rejects undeclared modalities in `assembleProviderInput()` when the list is present.
 - Registration is in-memory and O(1) by provider/model key.
 - `ModelConfig.cache` is declarative capability info only; it does not grant permissions, select tools, or bypass auth.
+- Model-discovery listings are untrusted metadata: normalized entries carry no tool authority, cached results stay per discovery instance (no cross-provider cache bleed), and discovery requests reuse the bounded transport with credential redaction. Catalog overrides come from host-owned registries only — provider responses never write into the host's `ModelRegistry` without host code in between.
 - Provider-specific behavior belongs in provider packages, not Prism core.
 
+## Live probe (discovery adapters)
+
+The `@arnilo/prism-providers/model-discovery` adapters have an opt-in live leg that runs `runModelDiscoveryConformance` against a real listing endpoint:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 OPENAI_API_KEY=...   # or GEMINI_API_KEY for the Google route
+node --test packages/prism-providers/dist/model-discovery/__tests__/live.test.js
+```
+
+Chooses the OpenAI-compatible or Google route based on which key is present; neither → skip.
+
 ## Related APIs
 
 - [Multimodal content](multimodal-content.md): `audio`/`file`/`document` blocks and `MODEL_INPUT_CAPABILITIES`.
@@ -122,3 +159,4 @@ Provider packages register models through `ProviderPackageAPI.registerModel(mode
 - [Provider caching](provider-caching.md): `ModelCacheCapabilities` and cache helpers.
 - [Provider packages](provider-packages.md): package registration of model metadata.
 - [Public contracts](public-contracts.md): `ModelConfig`, `ModelCost`, and cache type contracts.
+- [Provider layer](provider-layer.md): `ModelDiscovery` adapters, provenance, and TTL semantics.