Merge remote-tracking branch 'origin/v2' into sync-engine-plan

refactor(client): replace store adapter with signal of view
The engine's immutable views are now held in one signal per session; the Data facade keeps its shape, backed by signal reads instead of store paths. Deletes the identity diff, per-path reconcile, deep clone into the store, the rendered shadow map, the mutable StoreSessionView type, and both hand-maintained invariants (new fields must be diffed; per-index writes cannot shrink). Views alias engine state directly, which is safe because views are immutable and consumers receive fresh arrays from the facade. Clones remain only where values cross into the legacy layer's store.
2026-08-20 00:26:02 +00:00 · 2026-08-19 15:33:47 -04:00 · 2026-08-19 14:40:31 -04:00 · 2026-08-19 14:40:31 -04:00 · 2026-08-19 14:06:09 -04:00 · 2026-08-18 23:03:29 -04:00
115 changed files with 5771 additions and 1027 deletions
@@ -49,7 +49,7 @@ Filter or narrow `LLMEvent` streams with `LLMEvent.is.*` (camelCase guards, e.g.

 ### Routes

-A route is the runnable composition of four orthogonal pieces:
+A route is the registered, runnable composition of four orthogonal pieces:

 - **`Protocol`** (`src/route/protocol.ts`) — semantic API contract. Owns request body construction (`body.from`), the body schema (`body.schema`), the streaming-event schema (`stream.event`), and the event-to-`LLMEvent` state machine (`stream.step`). `Route.make(...)` validates and JSON-encodes the body from `body.schema` and decodes frames with `stream.event`. Examples: `OpenAIChat.protocol`, `OpenResponses.protocol`, `OpenAIResponses.protocol`, `AnthropicMessages.protocol`, `Gemini.protocol`, `BedrockConverse.protocol`.
 - **`Endpoint`** (`src/route/endpoint.ts`) — URL construction. The host, path, and route query live on the endpoint. `Endpoint.path("/chat/completions", { baseURL })` is the common case; pass a function for paths that embed the model id or a body field (e.g. `Endpoint.path(({ body }) => `/model/${body.modelId}/converse-stream`)`).
@@ -66,7 +66,7 @@ export const route = Route.make({
  endpoint: Endpoint.path("/chat/completions", {
    baseURL: "https://api.openai.com/v1",
  }),
-  auth: Auth.bearer(Auth.config("OPENAI_API_KEY")),
+  auth: Auth.bearer(),
  framing: Framing.sse,
 })
 ```
@@ -79,7 +79,7 @@ When a provider supports multiple physical transports, selection remains executi

 ### URL Construction

-`Endpoint` owns `{ baseURL, path, query }`. Each protocol route includes a canonical endpoint when the provider has one (e.g. `https://api.openai.com/v1`); provider helpers override endpoint fields by configuring the route before selecting a model. Generic OpenAI-compatible routes have no canonical URL and require configuration before execution.
+`Endpoint` owns `{ baseURL, path, query }`. Each protocol route includes a canonical endpoint when the provider has one (e.g. `https://api.openai.com/v1`); provider helpers override endpoint fields by configuring the route before selecting a model. Routes that have no canonical URL (OpenAI-compatible Chat, GitHub Copilot) require configuration before execution.

 For providers where the URL is derived from typed inputs (Azure resource name, Bedrock region), the provider helper configures the route endpoint before calling `.model(...)`. Use `AtLeastOne<T>` from `route/auth-options.ts` for inputs that accept either of two derivation paths (Azure: `resourceName` or `baseURL`).

@@ -126,6 +126,54 @@ Keep semantic APIs as separate entrypoints, such as OpenAI `chat` and `responses

 Do not expose `Route` in provider package settings. Route composition stays an implementation detail behind `model(...)`.

+### Folder layout
+
+```
+packages/ai/src/
+  schema/                   canonical Schema model, split by concern
+    ids.ts                  branded IDs, literal types, ProviderMetadata
+    options.ts              Generation/Provider/Http options, Limits, LanguageModel, cache policy
+    messages.ts             content parts, Message, ToolDefinition, LLMRequest
+    events.ts               Usage, individual events, LLMEvent, LLMResponse
+    errors.ts               error reasons, AIError, ToolFailure
+    index.ts                barrel
+  llm.ts                    request constructors and convenience helpers
+  route/
+    index.ts                @opencode-ai/ai/route advanced barrel
+    client.ts               Route.make + LLMClient.stream/generate
+    executor.ts             RequestExecutor service + transport error mapping
+    protocol.ts             Protocol type + Protocol.make
+    endpoint.ts             Endpoint type + Endpoint.path
+    auth.ts                 Auth type + Auth.bearer / Auth.apiKeyHeader / Auth.passthrough
+    auth-options.ts         ProviderAuthOption shape, AuthOptions.bearer, AtLeastOne helper
+    framing.ts              Framing type + Framing.sse
+    transport/              transport implementations
+      index.ts              Transport execution types + HttpTransport / WebSocketTransport namespaces
+      websocket-channel.ts  generic sequential channel executor/driver contract
+      http.ts               HttpTransport.httpJson — POST + framing
+      websocket.ts          direct one-request channel executor + raw socket adapter
+  protocols/
+    shared.ts               ProviderShared toolkit used inside protocol impls
+    openai-chat.ts          protocol + route (compose OpenAIChat.protocol)
+    open-responses.ts         provider-neutral Responses protocol baseline
+    open-responses-channel.ts provider-neutral Responses WebSocket transport factory
+    openai-responses.ts       OpenAI tools/events and channel policy composed over OpenResponses
+    anthropic-messages.ts
+    gemini.ts
+    bedrock-converse.ts
+    bedrock-event-stream.ts framing for AWS event-stream binary frames
+    openai-compatible-chat.ts route that reuses OpenAIChat.protocol, no canonical URL
+    openai-compatible-responses.ts deployment adapter that reuses OpenResponses.protocol, no canonical URL
+    utils/                  per-protocol helpers (auth, cache, media, tool-stream, ...)
+  providers/
+    openai-compatible.ts    generic Chat helper + family model helpers
+    openai-compatible-responses.ts generic Responses helper
+    openai-compatible-profile.ts family defaults (deepseek, togetherai, ...)
+    azure.ts / amazon-bedrock.ts / cloudflare.ts / github-copilot.ts / google.ts / xai.ts / openai.ts / anthropic.ts / openrouter.ts
+  tool.ts                   typed tool() helper
+  tool-runtime.ts           narrow one-call typed tool dispatcher
+```
+
 The dependency arrow points down: `providers/*.ts` files import protocol routes and auth-option utilities; protocol modules import `endpoint`, `auth`, `framing`, and transport pieces. Protocols do not import provider facades. Lower-level modules know nothing about provider catalog metadata. `OpenAIResponses` composes the provider-neutral `OpenResponses` protocol; the baseline never imports the OpenAI extension.

 ### Shared protocol helpers
@@ -173,17 +221,19 @@ Routes lower these into provider-native assistant tool-call messages and tool-re

 ### Tool dispatch

-`LLM.stream(request)` and `LLM.generate(request)` each run exactly one model call. Add tool schemas to `request.tools` with `Tool.toDefinitions(tools)`. When a caller wants the package's typed one-call execution behavior, pass each canonical local `tool-call` event to `ToolRuntime.dispatch(tools, call)`.
+`LLM.stream(request)` and `LLM.generate(request)` each run exactly one provider turn. Add tool schemas to `request.tools` with `Tool.toDefinitions(tools)`. When a caller wants the package's typed one-call execution behavior, pass each canonical local `tool-call` event to `ToolRuntime.dispatch(tools, call)`.

 ```ts
-const get_weather = Tool.make({
+const get_weather = tool({
  description: "Get current weather for a city",
  parameters: Schema.Struct({ city: Schema.String }),
  success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
-  execute: (input) =>
+  execute: ({ city }) =>
    Effect.gen(function* () {
-      const data = yield* WeatherApi.fetch(input.city)
+      // city: string  — typed from parameters Schema
+      const data = yield* WeatherApi.fetch(city)
      return { temperature: data.temp, condition: data.cond }
+      // return type checked against success Schema
    }),
 })

@@ -237,11 +237,11 @@ Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "aut

 ### Auto placement

-`"auto"` places up to four breakpoints — the last tool definition, the first system part, the last system part when distinct, and the final message boundary. These expose successively larger reusable prefixes for tools, the base agent, project instructions, and the active conversation. The rolling final-message boundary advances on every request so recent conversation prefixes remain reusable during tool loops.
+`"auto"` places up to four breakpoints — the last tool definition, the first system part, the last system part when distinct, and the final message boundary. These expose successively larger reusable prefixes for tools, the base agent, project instructions, and the active conversation. The rolling final-message boundary is the load-bearing detail in tool loops: it advances on every request so the previous cache entry stays within Anthropic's 20-block lookback.

 Tools precede every system and conversation block in the provider prefix, so tool definitions must remain byte-stable and deterministically ordered for downstream breakpoints to remain reusable.

-Requests below a provider's minimum cacheable size simply do not produce a reusable cache entry.
+The math justifies the default: Anthropic's 5-minute cache write is 1.25× base, read is 0.1×, so a single reuse within 5 minutes already wins. One-shot completions below the per-model minimum-cacheable-token threshold silently no-op on the wire, so the worst case is harmless.

 ### Opting out

@@ -285,7 +285,6 @@ LLM.request({
 | ----------------------- | ------------------------------------------------------------------------- |
 | Anthropic Messages      | emits up to 4 `cache_control` markers (4-breakpoint cap enforced)         |
 | Bedrock Converse        | emits up to 4 `cachePoint` blocks (4-breakpoint cap enforced)             |
-| OpenRouter              | emits up to 4 `cache_control` markers                                     |
 | OpenAI Chat / Responses | no-op (implicit caching above 1024 tokens)                                |
 | Gemini                  | no-op (implicit caching on 2.5+; explicit `CachedContent` is out-of-band) |

@@ -372,23 +371,11 @@ Request options in order of stability:

 1. **`generation`** — portable knobs (`maxTokens`, `temperature`, `topP`, `topK`, penalties, seed, stop).
 2. **`promptCacheKey`** — stable cache affinity lowered by every protocol that supports it.
-3. **`providerOptions: { ... }`** — flat options inferred from the selected model (OpenAI `store`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
+3. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `store`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
 4. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.

 Route/provider defaults are overridden by request-level values for each axis.

-The selected model supplies the provider-specific option type, so per-request overrides stay flat while the canonical runtime request remains provider-neutral:
-
-```ts
-LLM.request({
-  model,
-  prompt,
-  providerOptions: {
-    reasoningEffort: "low",
-  },
-})
-```
-
 ## Routes

 Adding a new model or deployment is usually 5-15 lines using `Route.make({ protocol, endpoint, auth, framing, ... })`. The route owns endpoint/auth/framing and the protocol owns body construction plus stream parsing. Transports are reusable IO templates that receive route endpoint/auth at compile time. Capability/catalog metadata lives outside this low-level package; unsupported request shapes fail during protocol lowering. See `AGENTS.md` for the architectural detail.
@@ -400,5 +387,6 @@ This package is built on Effect. Public methods return `Effect` or `Stream`; pro
 ## See also

 - `AGENTS.md` — architecture, route construction, contributor guide
+- `STATUS.md` — native provider parity status and AI SDK migration gaps
 - `example/tutorial.ts` — runnable end-to-end walkthrough
 - `test/provider/*.test.ts` — fixture-first protocol tests; `*.recorded.test.ts` files cover live cassettes
@@ -0,0 +1,107 @@
+# LLM Provider Parity Status
+
+Last reviewed: 2026-08-07
+
+This file tracks the gap between the native `@opencode-ai/ai` package and the AI SDK provider packages that opencode still depends on for many catalog/runtime paths.
+
+## Existing Status Sources
+
+| File                                | What it tracks                                                          | Limitation                                              |
+| ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
+| `packages/ai/DESIGN.md`             | Future clean-break API proposal for `@opencode-ai/ai`.                  | Not a provider parity tracker.                          |
+| `packages/ai/example/call-sites.md` | Route/value/provider-facade migration checklist and call-site sketches. | Architecture migration only; not AI SDK package parity. |
+
+## Current Implementation Snapshot
+
+| Native slice                       | Source                                                                                                                            | Current state                                                                                                                                                            | Main gaps                                                                                                                                                                                                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI Chat                        | `src/protocols/openai-chat.ts`, `src/providers/openai.ts`                                                                         | Usable. Streams text, reasoning deltas, tool calls, usage, images, and common generation controls.                                                                       | No typed structured-output / `response_format` path. Limited typed OpenAI option surface compared with SDK escape hatches.                                                                                                                                |
+| OpenAI Responses                   | `src/protocols/open-responses.ts`, `src/protocols/openai-responses.ts`, `src/providers/openai.ts`                                 | Usable over HTTP by default, with optional per-call WebSocket channel execution on the same model and route identity.                                                    | No incremental `previous_response_id` path or persistent Session channel manager yet. Typed options cover only a subset of Responses fields. Structured output is still mostly synthetic-tool based.                                                      |
+| OpenAI-compatible Chat             | `src/protocols/openai-compatible-chat.ts`, `src/providers/openai-compatible.ts`                                                   | Usable for generic Chat and several profiles: Baseten, Cerebras, DeepInfra, DeepSeek, Fireworks, Groq, TogetherAI.                                                       | Family quirks are mostly endpoint defaults, not full typed behavior.                                                                                                                                                                                      |
+| Open Responses-compatible          | `src/protocols/open-responses.ts`, `src/protocols/openai-compatible-responses.ts`, `src/providers/openai-compatible-responses.ts` | Usable for deployments that implement the provider-neutral Open Responses protocol. The deployment adapter does not inherit OpenAI tools, events, metadata, or defaults. | No named family profiles or recorded deployment coverage yet.                                                                                                                                                                                             |
+| Anthropic-compatible Messages      | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic-compatible.ts`                                                    | Usable for deployments that implement the Anthropic Messages wire protocol. Named Anthropic composes this base; MiniMax M3 has recorded text and tool-loop coverage.     | No named compatible family profiles yet.                                                                                                                                                                                                                  |
+| Anthropic Messages                 | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic.ts`                                                               | Usable. Supports tools, thinking, cache control, images, server-hosted tool events, and usage.                                                                           | Provider option surface is small. Beta/header handling, metadata, and newer Messages fields need a typed parity pass.                                                                                                                                     |
+| Gemini Developer API               | `src/protocols/gemini.ts`, `src/providers/google.ts`                                                                              | Usable for Google API key flow. Supports text, images, tools, thinking signatures, and cache usage.                                                                      | This is not Vertex. Typed provider options are narrow; many Gemini request fields currently require raw `http.body` overlays.                                                                                                                             |
+| Vertex Gemini                      | `src/protocols/gemini.ts`, `src/providers/google-vertex.ts`                                                                       | Usable through API-key express mode, explicit OAuth tokens, or ADC with project/location endpoint derivation, including tuned `endpoints/...` deployments.               | Core runner/catalog mapping and recorded provider coverage are missing.                                                                                                                                                                                   |
+| Vertex Chat                        | `src/protocols/openai-chat.ts`, `src/providers/google-vertex-chat.ts`                                                             | Usable for MaaS models through OpenAI-compatible Chat Completions with explicit OAuth tokens or ADC and project/location endpoint derivation.                            | Core runner/catalog mapping and recorded provider coverage are missing; MaaS family-specific request parity needs review.                                                                                                                                 |
+| Vertex Responses                   | `src/protocols/open-responses.ts`, `src/providers/google-vertex-responses.ts`                                                     | Usable for Grok models through Open Responses with explicit OAuth tokens or ADC, project/location endpoint derivation, and an explicit `store: false` Vertex default.    | Core runner/catalog mapping and recorded provider coverage are missing; stateful continuation is not supported by Vertex.                                                                                                                                 |
+| Vertex Messages                    | `src/protocols/anthropic-messages.ts`, `src/providers/google-vertex-messages.ts`                                                  | Usable through explicit OAuth tokens or ADC, including global, regional, and `eu`/`us` multi-region endpoints.                                                           | Core runner/catalog mapping and recorded provider coverage are missing; Vertex-specific hosted-tool parity needs review.                                                                                                                                  |
+| Bedrock Converse                   | `src/protocols/bedrock-converse.ts`, `src/providers/amazon-bedrock.ts`                                                            | Partial but real. Supports AWS event-stream framing, SigV4 with supplied credentials, bearer auth, tools, reasoning signatures, media, cache points, and recorded tests. | Native facade does not mirror the AI SDK plugin's default AWS credential chain/profile behavior. Runner/catalog mapping is missing. Guardrails, inference profiles, region-specific model ID fixes, and model-specific request fields need a parity pass. |
+| Azure OpenAI                       | `src/providers/azure.ts` using OpenAI Chat/Responses protocols                                                                    | Partial. Supports resource/base URL setup, API key auth, API version query, Chat, and Responses selectors.                                                               | Core runner does not map `@ai-sdk/azure` to this native facade. AAD/token auth and Azure-specific endpoint variants need review.                                                                                                                          |
+| Cloudflare AI Gateway / Workers AI | `src/providers/cloudflare.ts`                                                                                                     | Present via OpenAI-compatible Chat routes.                                                                                                                               | Useful but not part of the critical AI SDK replacement set yet. Needs per-product recorded coverage before relying on it broadly.                                                                                                                         |
+| OpenRouter                         | `src/providers/openrouter.ts`                                                                                                     | Present with OpenRouter-specific usage/reasoning/prompt-cache options over Chat.                                                                                         | Responses-style OpenRouter support is absent.                                                                                                                                                                                                             |
+| xAI                                | `src/providers/xai.ts`                                                                                                            | Present with Responses and Chat selectors.                                                                                                                               | Needs package-parity review against the AI SDK xAI provider.                                                                                                                                                                                              |
+| GitHub Copilot                     | `src/providers/github-copilot.ts`                                                                                                 | Present as explicit-base-URL OpenAI Chat/Responses facade.                                                                                                               | Runtime/catalog integration remains specialized and should stay separate from public OpenAI-compatible defaults.                                                                                                                                          |
+
+## V2 Runner Status
+
+`packages/core/src/session/runner/model.ts` currently resolves only this native subset from catalog `aisdk` metadata:
+
+| Catalog API                                         | Native route used today      |
+| --------------------------------------------------- | ---------------------------- |
+| `aisdk:@ai-sdk/openai`                              | `OpenAIResponses.route`      |
+| `aisdk:@ai-sdk/anthropic`                           | `AnthropicMessages.route`    |
+| `aisdk:@ai-sdk/openai-compatible` with explicit URL | `OpenAICompatibleChat.route` |
+
+Other `aisdk:` packages, including Google Vertex, Azure, and Bedrock, currently fall back through the AI SDK loader in the production runner. The dependency-free resolver seam rejects them with `SessionRunnerModel.UnsupportedPackageError`; they are not native route mappings yet.
+
+## AI SDK Package Parity Matrix
+
+| AI SDK package                    | Intended native target                                    | Status           | Biggest gaps                                                                                                                                                                                                        |
+| --------------------------------- | --------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@ai-sdk/openai`                  | `OpenAI.chat`, `OpenAI.responses`                         | Partial / usable | Add complete typed option coverage, structured output strategy, explicit Responses continuation support, and runner execution policy for optional WebSocket channels.                                               |
+| `@ai-sdk/openai-compatible`       | Generic OpenAI-compatible Chat and Responses              | Partial / usable | Decide per-family namespace/profile behavior and runner API selection for providers that support Responses versus Chat only.                                                                                        |
+| `@ai-sdk/anthropic`               | `AnthropicMessages`                                       | Partial / usable | Finish Messages API parity for headers/betas/metadata/newer fields and document hosted-tool continuation expectations.                                                                                              |
+| `@ai-sdk/google`                  | Gemini Developer API                                      | Partial / usable | Add typed options for safety, response schema/modalities, cached content, grounding/search/code execution, and non-text output modes where supported.                                                               |
+| `@ai-sdk/google-vertex`           | Vertex Gemini namespace/facade                            | Partial / usable | Add runner/catalog mapping, recorded coverage, and broader provider-option parity.                                                                                                                                  |
+| `@ai-sdk/google-vertex/anthropic` | Anthropic Messages over Vertex namespace/facade           | Partial / usable | Add runner/catalog mapping, recorded coverage, and Vertex-specific hosted-tool parity.                                                                                                                              |
+| `@ai-sdk/google-vertex/maas`      | Vertex Chat                                               | Partial / usable | Add runner/catalog mapping, recorded coverage, and MaaS family-specific request parity.                                                                                                                             |
+| `@ai-sdk/google-vertex/xai`       | Vertex Chat / Responses                                   | Partial / usable | Decide Chat/Responses selection for catalog models, add runner mapping and recorded coverage, and review xAI-specific request options.                                                                              |
+| `@ai-sdk/azure`                   | Azure OpenAI Chat/Responses facade                        | Partial          | Map runner/catalog metadata to native Azure, handle resourceName/baseURL/apiVersion variants, add AAD/token auth story, and verify Chat vs Responses deployment selection.                                          |
+| `@ai-sdk/amazon-bedrock`          | Bedrock Converse                                          | Partial          | Add default AWS credential chain/profile support, region/inference-profile model ID handling, provider option parity via `additionalModelRequestFields`, guardrails/performance config, and runner/catalog mapping. |
+| `@ai-sdk/amazon-bedrock/mantle`   | Bedrock Mantle OpenAI-compatible Chat/Responses namespace | Partial / usable | Add default AWS credential chain/profile support; native catalog mapping currently requires bearer auth or explicit static credentials.                                                                             |
+
+## Highest-Risk Gaps
+
+1. Runner support is narrower than the LLM package. The package has native provider facades for Google, Azure, and Bedrock, but the V2 Session runner only maps OpenAI, Anthropic, and explicit OpenAI-compatible Chat from `aisdk` catalog metadata.
+2. The Open Responses adapter is available through a separate package entrypoint, but the V2 runner still maps `@ai-sdk/openai-compatible` to Chat only. Catalog selection must become API-aware before Responses deployments can use it.
+3. Bedrock native auth is not AI SDK parity. The AI SDK plugin uses the default AWS provider chain, profile, container credentials, and Bedrock bearer token env behavior. Native Bedrock currently expects explicit credentials or bearer auth on the facade.
+4. Vertex Gemini, Vertex Chat, Vertex Responses, and Vertex Messages now have native package entrypoints, but the core runner does not map catalog metadata to them yet and recorded provider coverage is still missing.
+5. Azure is only a provider facade, not a full runtime replacement. Native Azure exists, but the catalog runner does not select it, and token auth/resource variants need review.
+6. Provider option typing is uneven. OpenAI, Anthropic, Gemini, Bedrock, and OpenRouter each expose a small typed subset plus raw HTTP overlays; this is useful but not equivalent to AI SDK provider option coverage.
+7. Structured output is not provider-native yet. `LLM.generateObject` still uses a synthetic tool strategy, while the future design expects native structured output where reliable and tool fallback where needed.
+8. Package/namespace boundaries for the current native loading set are explicit in docs and exports. Other exported provider facades are not catalog package entrypoints until they implement the contract. Vertex xAI still needs catalog API selection.
+9. Recorded coverage is uneven. OpenAI, Anthropic, Gemini, Bedrock Converse, Bedrock Mantle, Cloudflare, OpenRouter, and several OpenAI-compatible Chat providers have cassettes. Azure and Vertex still need first-class recorded scenarios before switching defaults.
+
+## Native Namespace Shape
+
+These are implementation/API slices, not separate npm packages.
+
+| API slice                     | Package-like entrypoint                                     | Purpose                                                                                    |
+| ----------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| OpenAI Chat                   | `@opencode-ai/ai/providers/openai/chat`                     | OpenAI `/chat/completions` semantics.                                                      |
+| OpenAI Responses              | `@opencode-ai/ai/providers/openai/responses`                | OpenAI `/responses` semantics with HTTP default and optional per-call WebSocket execution. |
+| OpenAI-compatible Chat        | `@opencode-ai/ai/providers/openai-compatible`               | Generic OpenAI-compatible `/chat/completions`.                                             |
+| Open Responses-compatible     | `@opencode-ai/ai/providers/openai-compatible/responses`     | Generic provider-neutral `/responses`.                                                     |
+| Anthropic-compatible Messages | `@opencode-ai/ai/providers/anthropic-compatible`            | Generic Anthropic-compatible `/messages`.                                                  |
+| Anthropic Messages            | `@opencode-ai/ai/providers/anthropic`                       | Anthropic Messages API.                                                                    |
+| Gemini Developer API          | `@opencode-ai/ai/providers/google`                          | Google AI Studio Gemini API.                                                               |
+| Vertex Gemini                 | `@opencode-ai/ai/providers/google-vertex/gemini`            | Vertex Gemini API; `providers/google-vertex` is the default alias.                         |
+| Vertex Chat                   | `@opencode-ai/ai/providers/google-vertex/chat`              | Vertex OpenAI-compatible Chat Completions for MaaS models.                                 |
+| Vertex Responses              | `@opencode-ai/ai/providers/google-vertex/responses`         | Vertex Open Responses for Grok models.                                                     |
+| Vertex Messages               | `@opencode-ai/ai/providers/google-vertex/messages`          | Vertex-hosted Anthropic Messages API.                                                      |
+| Bedrock Converse              | `@opencode-ai/ai/providers/amazon-bedrock`                  | AWS Bedrock Converse API.                                                                  |
+| Bedrock Mantle Chat           | `@opencode-ai/ai/providers/amazon-bedrock/mantle/chat`      | AWS Bedrock Mantle OpenAI-compatible Chat API.                                             |
+| Bedrock Mantle Responses      | `@opencode-ai/ai/providers/amazon-bedrock/mantle/responses` | AWS Bedrock Mantle OpenAI-compatible Responses API.                                        |
+| Azure OpenAI Chat             | `@opencode-ai/ai/providers/azure/chat`                      | Azure specialization of OpenAI Chat.                                                       |
+| Azure OpenAI Responses        | `@opencode-ai/ai/providers/azure/responses`                 | Azure specialization of OpenAI Responses.                                                  |
+
+## Suggested Next Work Slices
+
+1. Add native runner/catalog mappings for `@ai-sdk/azure`, `@ai-sdk/google`, and `@ai-sdk/amazon-bedrock` where the existing native facades are already close.
+2. Add API-aware runner/catalog selection between OpenAI-compatible Chat and Responses.
+3. Bring Bedrock native auth/config to AI SDK parity: region, profile, default AWS credential chain, bearer token env, endpoint override, and cross-region inference profile handling.
+4. Add runner/catalog mappings and recorded scenarios for the native Vertex Gemini, Chat, Responses, and Messages entrypoints.
+5. Decide Chat/Responses selection for `@ai-sdk/google-vertex/xai` catalog models.
+6. Expand typed provider options from the existing V1 lowerer knowledge in `packages/core/src/v1/config/provider-options.ts` before adding more raw overlay examples.
+7. Add recorded provider tests for Azure, Vertex Gemini, Vertex Chat, Vertex Responses, Vertex Messages, and Bedrock credential-chain behavior before making native runtime the default for those packages.
@@ -0,0 +1,606 @@
+# LLM Call Site Sketches
+
+Scratchpad for examples first, abstractions second. Current direction: routes
+execute, provider facades organize configured route sets, and models carry route
+values directly.
+
+## Conversation Summary
+
+Kit and Aidan want provider-specific LLM behavior to move out of opencode's AI
+SDK transform path and into `packages/ai` where possible. The goal is not a big
+generic transform layer; the goal is small composable route definitions backed by
+recorded golden tests.
+
+Things to keep testing against:
+
+- Cache placement: `cache: "auto"`, manual cache breakpoints, provider cache usage.
+- Images: golden image tests for providers/protocols that claim image support.
+- Reasoning: canonical reasoning parts/events versus provider-native knobs.
+- Auth: bearer, custom headers, multiple credentials, query auth, SigV4, OAuth, no auth.
+- OpenAI-compatible providers: DeepSeek, Together, Groq, Alibaba/DashScope, custom routers.
+- Provider switching: stale signatures, encrypted reasoning, provider metadata, incompatible parts.
+- Error quality: typed errors instead of generic SDK/server failures.
+
+## Final Guide: Routes Execute, Providers Organize
+
+Do not introduce a first-class `Deployment` abstraction unless it gains real
+semantics. Provider facades are ergonomic configured route groups, not execution
+registries. The executable/composable thing is still a route. Do not make route
+construction publish to a global registry; models should carry their route value
+directly.
+
+Keep durable identity separate from runtime capability:
+
+- Durable identity is small serializable data like `{ providerID, modelID }` for
+  config, sessions, logs, and catalogs.
+- Runtime capability is a `LanguageModel` with a route value, protocol, transport, auth,
+  and defaults. It is allowed to contain functions and schemas.
+- If persisted identity needs to become executable, resolve it through an app
+  boundary first. Do not make `LLMRequest` recover behavior from a global route
+  side table.
+
+Keep unconfigured behavior values as values, not factories. A transport like
+`HttpTransport.sseJson` should be a reusable immutable value. Use a function only
+when the caller supplies options or when construction needs fresh state.
+
+Use constants to remove repetition before inventing abstractions. Provider ids
+are branded once per provider facade and reused across routes; a plain exported
+object is enough for the provider-facing API unless a helper earns its keep by
+removing repeated route projection.
+
+Expose default configured provider instances, and put provider-specific setup on
+`.configure(...)`. Model selectors stay pure: `model(id)`, `responses(id)`,
+`chat(id)`, etc. Endpoint/auth/resource/api-version configuration happens before
+model selection, not as a second argument to model selection.
+
+Use provider/product facades consistently:
+
+- One coherent provider/product config surface gets one top-level facade.
+- APIs/model kinds that share that config are methods on the facade.
+- Different products with different required config get separate top-level
+  facades, not a shared namespace with unrelated children.
+- Default facades are exposed only when concrete defaults or lazy env/credential
+  defaults make the facade valid.
+
+Examples:
+
+```ts
+OpenAI.responses("gpt-4o")
+OpenAI.chat("gpt-4o")
+
+Azure.configure({ resourceName, apiKey }).responses("my-deployment")
+AmazonBedrock.configure({ region, credentials }).model("anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+CloudflareAIGateway.configure({ accountId, gatewayId, gatewayApiKey, apiKey }).model("openai/gpt-4o")
+CloudflareWorkersAI.configure({ accountId, apiKey }).model("@cf/meta/llama-3.1-8b-instruct")
+
+OpenAICompatible.configure({
+  provider: "custom",
+  baseURL: "https://custom.example/v1",
+  auth: Auth.bearer(apiKey),
+}).model("custom-model")
+```
+
+Standardize the provider facade contract before abstracting construction. A
+plain object is enough at first; add a helper only if repeated route projection
+starts hiding the real provider-specific config.
+
+`Route.with(...)` patch semantics should be boring and explicit:
+
+- Omitted fields inherit from the original route.
+- `endpoint` patches merge with the existing endpoint, so overriding `baseURL`
+  keeps the existing `path`.
+- `endpoint.query` merges by default; later values win.
+- `auth` replaces.
+- `headers` merge by default; undefined values are omitted.
+- `id` is optional in patches. Route ids are diagnostic/provider API labels, not
+  global runtime registry keys.
+
+1. **Route**
+   - route id
+   - provider id
+   - protocol
+   - body schema
+   - body builder
+   - stream event schema
+   - parser/state machine
+   - transport
+     - method / IO shape
+     - framing
+     - request preparation
+     - constants when unconfigured; functions only when configured
+   - endpoint
+     - base URL
+     - static path
+     - body/model-derived path
+     - query params
+   - auth
+     - bearer
+     - custom header
+     - multiple credentials
+     - SigV4
+     - none
+   - defaults
+     - headers
+     - generation defaults
+     - provider options
+     - limits
+2. **Provider Facade**
+   - default configured provider instance
+   - provider-specific `.configure(...)`
+   - plain object/function facade over one or more routes
+   - top-level export only when it represents one coherent config surface
+   - no passive `Provider.make(...)` wrapper unless it gains runtime behavior
+3. **Model Selector**
+   - route/provider-owned selector
+   - accepts model id only
+   - returns executable models
+   - does not accept endpoint/auth/deployment overrides
+4. **Language Model**
+   - model id
+   - route value
+   - provider id
+   - configured route value at selection time
+5. **LLM Request**
+   - model
+   - messages/tools
+   - generation/cache/reasoning/response-format options
+   - request-level HTTP overlays for per-request headers/query/body additions,
+     not provider endpoint/auth reconfiguration
+6. **Compile**
+   - read route from model
+   - merge route defaults and request overrides
+   - build final URL from route endpoint
+   - apply auth from the configured route
+   - build body with protocol
+   - execute with transport and parse with protocol
+
+## Provider Facade Shape
+
+The provider abstraction is a facade over configured routes, not the runtime
+execution mechanism:
+
+```ts
+type ProviderFacade<APIs, Config> = {
+  readonly id: ProviderID
+  readonly model: (id: string) => LanguageModel
+  readonly configure: (input?: Config) => ProviderFacade<APIs, Config>
+} & APIs
+```
+
+Manual construction is fine and should be the default until duplication earns a
+helper:
+
+```ts
+export const OpenAI = {
+  id: openAIProvider,
+  model: openAIResponses.model,
+  responses: openAIResponses.model,
+  chat: openAIChat.model,
+  configure: configureOpenAI,
+} satisfies ProviderFacade<
+  {
+    responses: (id: string) => LanguageModel
+    chat: (id: string) => LanguageModel
+  },
+  OpenAIConfig
+>
+```
+
+If several providers repeat the same projection from route values to model
+methods, the helper can stay deliberately tiny:
+
+```ts
+const configureOpenAI = (input: OpenAIConfig = {}) =>
+  Provider.define({
+    id: openAIProvider,
+    routes: {
+      responses: openAIResponses.with(openAIConfig(input)),
+      chat: openAIChat.with(openAIConfig(input)),
+    },
+    default: "responses",
+    configure: configureOpenAI,
+  })
+
+export const OpenAI = configureOpenAI()
+```
+
+`Provider.define(...)` would only project route methods and preserve types:
+
+```ts
+OpenAI.model("gpt-4o")
+OpenAI.responses("gpt-4o")
+OpenAI.chat("gpt-4o")
+OpenAI.configure({ apiKey }).responses("gpt-4o")
+```
+
+It must not register routes, select routes dynamically, or participate in
+execution. Execution still reads the route value carried by the model.
+
+## Ideal Call Sites
+
+Define concrete routes for a native provider, then project them through a
+provider facade:
+
+```ts
+const openAIProvider = ProviderID.make("openai")
+
+const openAIResponses = Route.make({
+  id: "openai-responses",
+  provider: openAIProvider,
+  protocol: OpenAIResponses.protocol,
+  transport: HttpTransport.sseJson,
+  endpoint: {
+    baseURL: "https://api.openai.com/v1",
+    path: "/responses",
+  },
+  auth: Auth.envBearer("OPENAI_API_KEY"),
+})
+
+const openAIChat = Route.make({
+  id: "openai-chat",
+  provider: openAIProvider,
+  protocol: OpenAIChat.protocol,
+  transport: HttpTransport.sseJson,
+  endpoint: {
+    baseURL: "https://api.openai.com/v1",
+    path: "/chat/completions",
+  },
+  auth: Auth.envBearer("OPENAI_API_KEY"),
+})
+
+const openAIConfig = (input: OpenAIConfig) => ({
+  endpoint: input.endpoint,
+  auth: input.auth ?? (input.apiKey ? Auth.bearer(input.apiKey) : undefined),
+  headers: {
+    "OpenAI-Organization": input.organization,
+    "OpenAI-Project": input.project,
+  },
+})
+
+const configureOpenAI = (input: OpenAIConfig = {}) => {
+  const responses = openAIResponses.with(openAIConfig(input))
+  const chat = openAIChat.with(openAIConfig(input))
+
+  return {
+    id: openAIProvider,
+    responses: responses.model,
+    chat: chat.model,
+    model: responses.model,
+    configure: configureOpenAI,
+  }
+}
+
+export const OpenAI = configureOpenAI()
+```
+
+Specialize it functionally for concrete providers:
+
+```ts
+const deepSeekProvider = ProviderID.make("deepseek")
+
+const deepseekChat = openAIChat.with({
+  id: "deepseek-chat",
+  provider: deepSeekProvider,
+  endpoint: {
+    baseURL: "https://api.deepseek.com/v1",
+  },
+  auth: Auth.envBearer("DEEPSEEK_API_KEY"),
+})
+
+const configureDeepSeek = (input: OpenAICompatibleConfig = {}) => {
+  const route = deepseekChat.with({
+    endpoint: input.endpoint,
+    auth: input.auth ?? (input.apiKey ? Auth.bearer(input.apiKey) : undefined),
+  })
+
+  return {
+    id: deepSeekProvider,
+    model: route.model,
+    configure: configureDeepSeek,
+  }
+}
+
+export const DeepSeek = {
+  id: deepSeekProvider,
+  model: deepseekChat.model,
+  configure: configureDeepSeek,
+}
+```
+
+Provider-specific configuration happens before model selection:
+
+```ts
+const deepseek = DeepSeek.configure({
+  endpoint: {
+    baseURL: "https://proxy.example.com/v1",
+  },
+  auth: Auth.bearer(apiKey),
+})
+
+const model = deepseek.model("deepseek-chat")
+```
+
+Final request call site stays boring:
+
+```ts
+const response =
+  yield *
+  LLM.generate(
+    LLM.request({
+      model: DeepSeek.model("deepseek-chat"),
+      prompt: "Hello.",
+    }),
+  )
+```
+
+For direct provider-facade calls, Responses has one semantic model and route:
+
+```ts
+OpenAI.responses("gpt-4o")
+```
+
+The package-like OpenAI Responses entrypoint has the same transport-neutral
+`model(...)` contract:
+
+```ts
+import { model } from "@opencode-ai/ai/providers/openai/responses"
+
+model("gpt-4o", { apiKey })
+```
+
+Vertex keeps Gemini, Chat, Responses, and Messages as separate package-like entrypoints,
+while sharing project/location resolution and ADC authentication internally:
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/gemini"
+
+model("gemini-3.5-flash", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/chat"
+
+model("deepseek-ai/deepseek-v3.2-maas", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/responses"
+
+model("xai/grok-4.20-reasoning", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/messages"
+
+model("claude-sonnet-4-6", { project, location: "global" })
+```
+
+The client does not require a different public layer for WebSocket execution.
+Responses routes use HTTP by default, and callers may pass a channel executor per
+call. Routes without channel support simply ignore that execution capability.
+
+Azure is a route specialization with auth/path/default changes plus input
+mapping. The public API configures the Azure resource once, then selects
+deployment ids with pure model selectors:
+
+```ts
+const azureProvider = ProviderID.make("azure")
+
+const azureResponses = openAIResponses.with({
+  id: "azure-openai-responses",
+  provider: azureProvider,
+  auth: Auth.envHeader("api-key", "AZURE_OPENAI_API_KEY"),
+})
+
+const configureAzure = (input: AzureConfig = {}) => {
+  const route = azureResponses.with({
+    endpoint: {
+      baseURL:
+        input.baseURL ??
+        Endpoint.envBaseURL(
+          "AZURE_RESOURCE_NAME",
+          (resourceName) => `https://${resourceName}.openai.azure.com/openai/v1`,
+        ),
+      query: { "api-version": input.apiVersion ?? "v1" },
+    },
+    auth: input.apiKey ? Auth.header("api-key", input.apiKey) : Auth.envHeader("api-key", "AZURE_OPENAI_API_KEY"),
+  })
+
+  return {
+    id: azureProvider,
+    model: route.model,
+    responses: route.model,
+    configure: configureAzure,
+  }
+}
+
+export const Azure = configureAzure()
+
+const azure = Azure.configure({
+  resourceName: "my-resource",
+  apiVersion: "v1",
+})
+
+const model = azure.responses("my-deployment")
+```
+
+Default provider facades are only valid when required configuration has a lazy
+default source. `Azure.responses("my-deployment")` can be valid if endpoint
+resolution reads `AZURE_RESOURCE_NAME` lazily and fails with a typed
+configuration error when missing. If a provider has no sensible lazy default,
+do not expose a default model selector; expose only a configured entrypoint.
+
+Cloudflare AI Gateway and Workers AI are separate product facades because their
+configuration surfaces differ. Do not make a root `Cloudflare.configure(...)`
+pretend there is one coherent Cloudflare provider configuration:
+
+```ts
+const cloudflareProvider = ProviderID.make("cloudflare-ai-gateway")
+
+const cloudflareOpenAIChat = openAIChat.with({
+  id: "cloudflare-ai-gateway-openai-chat",
+  provider: cloudflareProvider,
+  auth: Auth.bearerHeader("cf-aig-authorization").andThen(Auth.bearer()),
+})
+
+const configureCloudflareAIGateway = (input: CloudflareAIGatewayConfig) => {
+  const route = cloudflareOpenAIChat.with({
+    endpoint: {
+      baseURL: `https://gateway.ai.cloudflare.com/v1/${input.accountId}/${input.gatewayId}/openai`,
+    },
+    auth: Auth.bearerHeader("cf-aig-authorization", input.gatewayApiKey).andThen(Auth.bearer(input.apiKey)),
+  })
+
+  return {
+    id: cloudflareProvider,
+    model: (modelID: string) => route.model({ id: modelID }),
+    configure: configureCloudflareAIGateway,
+  }
+}
+
+export const CloudflareAIGateway = {
+  id: cloudflareProvider,
+  configure: configureCloudflareAIGateway,
+}
+
+const gateway = CloudflareAIGateway.configure({
+  accountId: "account",
+  gatewayId: "gateway",
+  gatewayApiKey,
+  apiKey,
+})
+
+const model = gateway.model("openai/gpt-4o")
+```
+
+If a Cloudflare product gains a full lazy env default, it can expose a direct
+selector too. Until then, omitting `CloudflareAIGateway.model(...)` makes missing
+account/gateway configuration unrepresentable.
+
+opencode's dynamic runtime should construct executable models at its app
+boundary instead of exposing a giant unstructured public model constructor or a
+generic dynamic resolver:
+
+```ts
+const model =
+  providerID === "azure" ? Azure.configure(resolvedAzureConfig).responses(apiModelID) : OpenAI.responses(apiModelID)
+```
+
+That boundary can branch on durable config/catalog metadata and call typed
+provider APIs directly. Transport selection remains execution policy: a Session
+or other caller may pass a WebSocket channel executor per call without changing
+the model constructed by this boundary.
+
+## Competitive Shape
+
+This follows the strongest parts of adjacent libraries:
+
+- AI SDK: configured provider instances expose provider-specific model methods.
+- Effect AI: executable models carry provider requirements and can be resolved by
+  an app boundary.
+- LiteLLM/opencode config: dynamic `providerID/modelID` branching belongs at the
+  app boundary, not in the typed public provider API or a global runtime
+  resolver.
+- LangChain/LlamaIndex: constructor-style config plus model id is convenient,
+  but we avoid making model selection also configure endpoint/auth.
+
+The chosen split is:
+
+```txt
+Route = execution mechanics
+Provider facade = configured route group
+LanguageModel = selected executable model carrying route value
+App boundary = explicit durable-config -> typed-provider call
+```
+
+## What This Removes
+
+- No `Provider.make(...)` as a core abstraction.
+- No `Provider.make(...)` wrapper just to bind an id to model functions. Use a
+  branded provider id constant and a plain exported provider facade.
+- No `Deployment.define(...)` unless future examples force it.
+- No global route registry as the normal execution path.
+- No import side effects required before a model can execute.
+- No duplicate `provider.id` object when selected models already carry provider
+  id.
+- No `model(id, overrides)` escape hatch. Model selection takes the model id;
+  endpoint/auth/deployment customization happens by configuring the route first.
+- No transport setting on a provider or executable model. OpenAI Responses uses
+  HTTP by default and accepts an optional per-call channel executor as execution policy.
+- No separate public `LLMClient.layerWithWebSocket`. The runtime should expose one
+  client layer with the available transport capabilities.
+- No executable `ModelRef`. The executable handle is `LanguageModel`; durable model
+  identity stays separate and cannot execute on its own.
+
+## Implementation Todo
+
+- [x] Replace the current executable `ModelRef` with `LanguageModel`.
+- [x] Change `LanguageModel.route` to carry a route value, not a `RouteID` string.
+- [ ] Keep a separate durable model identity type for persisted/session/catalog
+      data, likely `{ providerID, modelID }`, and make it clear that it cannot
+      execute without resolver context.
+- [x] Change route model selectors so `route.model(id)` returns an executable
+      model with the route value attached, not a globally registered route id.
+- [x] Remove the standalone `Route.model(route, defaults, mapInput)` helper;
+      configured route instances own model selection.
+- [x] Remove endpoint/auth escape hatches from route model selection; callers must
+      configure endpoint/auth through `route.with(...)` or provider facades before
+      calling `.model(...)`.
+- [x] Remove request-shaping defaults from `LanguageModel`; selected models now carry only
+      id, provider, and configured route while defaults live on routes or requests.
+- [x] Rework `LLMClient.stream` / `generate` to read
+      `request.model.route` directly instead of calling `registeredRoute(...)`.
+- [x] Remove `Route.make(...)` global registration from the normal execution
+      path; keep route ids only as diagnostics/provider API labels.
+- [x] Model endpoint as `{ baseURL, path, query }` on routes, then remove the
+      current split where host/query live on the model and path lives in route
+      transport setup.
+- [x] Define `Route.with(...)` with explicit patch semantics for endpoint merge,
+      query merge, header merge, auth replacement, and optional diagnostic id.
+- [x] Make unconfigured transports reusable constants such as
+      `HttpTransport.sseJson`; keep transport functions only for configured/fresh
+      state construction.
+- [x] Collapse the public WebSocket runtime split so one `LLMClient.layer` accepts
+      optional per-call channel execution without changing route identity.
+- [x] Convert OpenAI provider APIs to provider-facade shape:
+      `OpenAI.configure(config).responses(id)` and `.chat(id)`.
+- [x] Convert Azure to a configured facade where resource/base URL/api version
+      setup happens before selecting deployment ids.
+- [x] Split Cloudflare products into separate facades such as
+      `CloudflareAIGateway` and `CloudflareWorkersAI`; do not expose a shared root
+      config surface unless one product actually exists.
+- [x] Migrate remaining built-in provider facades one at a time so configuration
+      happens before model selection and selectors accept only ids:
+      xAI, GitHub Copilot, OpenRouter, OpenAI-compatible families, Anthropic,
+      Google/Gemini, and Amazon Bedrock now use configured facades such as
+      `Provider.configure(options).model(id)` with named selectors where needed.
+- [ ] Decide whether a tiny `Provider.define(...)` helper is warranted after two
+      or three provider conversions; start with plain objects if duplication is not
+      yet painful.
+- [x] Keep executable model construction transport-neutral at the Session boundary;
+      Session-scoped execution policy supplies channel capability separately.
+- [ ] Update tests so direct route/provider tests assert route values are carried
+      by executable models, and opencode/native tests assert boundary-based route
+      selection.
+- [ ] Remove compatibility exports or stale docs only after internal call sites
+      are migrated; do not keep duplicate constructor paths without an external
+      compatibility need.
+
+## Open Questions
+
+- Default facades with required setup: should providers like Azure and Bedrock
+  expose default model selectors only when all required setup has lazy env or
+  credential-chain defaults? If not, omit the default selector so missing config
+  is impossible at the type/API level.
+- Lazy endpoint/auth values: should `Endpoint.envBaseURL(...)` and env-backed
+  auth produce typed configuration/authentication errors at compile/prepare time
+  or only when executing the transport?
+- `Route.with(...)` clearing semantics: endpoint/query/header patches merge by
+  default, but what is the explicit way to remove an inherited value?
+- Provider facade helper: keep plain objects until duplication hurts, or add a
+  tiny `Provider.define(...)` immediately to enforce shape and method projection?
+- Auth shape: should auth stay as today's composable `Auth`, or split into an
+  auth placement/strategy and credential sources?
+- Naming: is `baseURL` still the right endpoint field name, or should it be
+  `origin` / `urlPrefix` to clarify that route `path` is appended?
@@ -22,7 +22,7 @@ const model = OpenAI.configure({
  apiKey,
  generation: { maxTokens: 160 },
  providerOptions: {
-    store: false,
+    openai: { store: false },
  },
 }).model("gpt-4o-mini")

@@ -34,7 +34,7 @@ const model = OpenAI.configure({
 //   - `generation`: common controls such as max tokens, temperature, topP/topK,
 //     penalties, seed, and stop sequences.
 //   - `promptCacheKey`: stable cache affinity for protocols that support it.
-//   - `providerOptions`: model-typed provider-native behavior. For example,
+//   - `providerOptions`: namespaced provider-native behavior. For example,
 //     OpenAI store behavior, Anthropic thinking, Gemini thinking config, or
 //     OpenRouter routing/reasoning.
 //   - `http`: last-resort serializable overlays for final request body, headers,
@@ -188,7 +188,7 @@ const FakeProtocol = Protocol.make<FakeBody, string, string, void>({
  },
 })

-// A route is the runnable binding for that protocol. It adds the deployment
+// An route is the runnable binding for that protocol. It adds the deployment
 // axes that the protocol deliberately does not know: URL, auth, and framing.
 const FakeAdapter = Route.make({
  id: "fake-echo",
@@ -5,8 +5,8 @@
 // The default `"auto"` shape places breakpoints at the last tool definition,
 // the first and last distinct system parts, and the conversation tail. This
 // exposes reusable tool, base-agent, project, and session prefixes while
-// advancing the tail after each tool result keeps recent conversation prefixes
-// reusable during long agent runs.
+// advancing the tail after each tool result keeps the previous cache entry
+// within Anthropic's 20-block lookback during long agent turns.
 //
 // Manual `cache: CacheHint` placements on individual parts are preserved and
 // count against the four-breakpoint budget; auto only fills remaining slots.
@@ -23,7 +23,9 @@ const NONE: CachePolicyObject = {}
 const BREAKPOINT_CAP = 4

 // Resolution rules:
-//   - undefined   → "auto" — caching is on by default.
+//   - undefined   → "auto" — caching is on by default. The math favors it:
+//                   Anthropic 5m-cache write is 1.25x base, read is 0.1x,
+//                   so a single reuse within 5 minutes already wins.
 //   - "auto"      → tools + first/last system + final message boundary.
 //   - "none"      → no auto placement; manual `CacheHint`s still flow.
 //   - object form → exactly what the caller asked for.
@@ -16,6 +16,7 @@ import {
  type JsonSchema,
  type LLMRequest,
  type MediaPart,
+  type ProviderOptions,
  type ProviderMetadata,
  type ToolCallPart,
  type ToolDefinition,
@@ -51,7 +52,9 @@ export interface OptionsInput {
  readonly effort?: string
 }

-export type ProviderOptionsInput = OptionsInput
+export type ProviderOptionsInput = ProviderOptions & {
+  readonly anthropic?: OptionsInput
+}

 // =============================================================================
 // Request Body Schema
@@ -590,7 +593,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
 })

 const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (request: LLMRequest) {
-  const input = request.providerOptions
+  const input = request.providerOptions?.anthropic
  return {
    thinking: yield* resolveThinking(input?.thinking),
    effort: typeof input?.effort === "string" ? input.effort : undefined,
@@ -1012,8 +1015,8 @@ const step = (state: ParserState, event: AnthropicEvent) => {
 // =============================================================================
 /**
 * The Anthropic Messages protocol — request body construction, body schema,
- * and the streaming-event state machine shared by Anthropic-compatible and
- * Vertex-hosted Messages routes.
+ * and the streaming-event state machine. Used by native Anthropic Cloud and
+ * (once registered) Vertex Anthropic / Bedrock-hosted Anthropic passthrough.
 */
 export const protocol = Protocol.make({
  id: ADAPTER,
@@ -12,6 +12,7 @@ import {
  type JsonSchema,
  type LLMRequest,
  type MediaPart,
+  type ProviderOptions,
  type ProviderMetadata,
  type TextPart,
  type ToolCallPart,
@@ -66,7 +67,9 @@ export interface OptionsInput {
  }
 }

-export type ProviderOptionsInput = OptionsInput
+export type ProviderOptionsInput = ProviderOptions & {
+  readonly gemini?: OptionsInput
+}

 // =============================================================================
 // Request Body Schema
@@ -384,7 +387,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
 })

 const resolveOptions = (request: LLMRequest) => {
-  const input = request.providerOptions
+  const input = request.providerOptions?.gemini
  const value = input?.thinkingConfig
  const thinkingConfig = {
    thinkingBudget:
@@ -627,7 +630,8 @@ const step = (state: ParserState, event: GeminiEvent) => {
 // =============================================================================
 /**
 * The Gemini protocol — request body construction, body schema, and the
- * streaming-event state machine shared by Google AI Studio and Vertex Gemini.
+ * streaming-event state machine. Used by Google AI Studio Gemini and (once
+ * registered) Vertex Gemini.
 */
 export const protocol = Protocol.make({
  id: ADAPTER,
@@ -340,7 +340,7 @@ export const lowerTool = Effect.fn("OpenResponses.lowerTool")(function* (
    name: tool.name,
    description: tool.description,
    parameters: ToolSchemaProjection.responses(inputSchema),
-    // The common tool definition does not currently express Responses strict-schema policy.
+    // TODO: Read this from Responses tool options so direct LLM callers can opt into strict schemas.
    strict: false,
  }
 })
@@ -261,7 +261,7 @@ export const route = Route.make({
  endpoint,
  auth,
  transport,
-  defaults: { providerOptions: { store: false } },
+  defaults: { providerOptions: { openai: { store: false } } },
 })

 export * as OpenAIResponses from "./openai-responses.js"
@@ -41,10 +41,12 @@ export interface ToolAccumulator {
 * when at least one is defined. Returns `undefined` when neither input nor
 * output is known so routes don't publish a misleading `0`.
 *
- * Under the inclusive `AI.Usage` contract, `inputTokens` includes cached input
- * and `outputTokens` includes reasoning. Protocol mappers normalize those
- * inclusive values before calling this helper. The provider-supplied total is
- * the source of truth when present; otherwise their sum is the canonical total.
+ * Under the additive `AI.Usage` contract, `inputTokens` and `outputTokens`
+ * are the non-cached input and visible output only. The provider-supplied
+ * `total` is the source of truth when present; the computed fallback
+ * under-counts cache and reasoning by design and exists mainly so
+ * Anthropic-style providers (which don't surface a total) still get a
+ * sensible aggregate on the input + output axes.
 */
 export const totalTokens = (
  inputTokens: number | undefined,
@@ -65,7 +67,7 @@ export const totalTokens = (
 *
 * If `total` is `undefined`, returns `undefined` (we don't fabricate
 * counts). If `subtrahend` is `undefined`, returns `total` unchanged. The
- * provider-native breakdown stays available on `Usage.providerMetadata` for debugging.
+ * provider-native breakdown stays available on `Usage.native` for debugging.
 */
 export const subtractTokens = (total: number | undefined, subtrahend: number | undefined): number | undefined => {
  if (total === undefined) return undefined
@@ -197,8 +199,8 @@ export const errorText = (error: unknown) => {

 /**
 * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
- * decoder, and drops empty / `[DONE]` keep-alive events so the protocol event
- * schema sees one JSON string per element. The SSE channel emits a
+ * decoder, and drops empty / `[DONE]` keep-alive events so the downstream
+ * `decodeChunk` sees one JSON string per element. The SSE channel emits a
 * `Retry` control event on its error channel; we drop it here (we don't
 * implement client-driven retries). Decoder failures become provider output
 * errors so the public error channel stays `AIError`.
@@ -214,7 +216,11 @@ export const sseFraming = (bytes: Stream.Stream<Uint8Array, AIError>): Stream.St
  )

 /**
- * Canonical invalid-request constructor shared by protocol lowering.
+ * Canonical invalid-request constructor. Lift one-line `const invalid =
+ * (message) => invalidRequest(message)` aliases out of every
+ * route so the error constructor lives in one place. If we ever extend
+ * `InvalidRequestReason` with route context or trace metadata, the change
+ * lands here.
 */
 export const invalidRequest = (message: string) =>
  new AIError({
@@ -4,7 +4,7 @@ import { newBreakpoints, ttlBucket, type Breakpoints } from "./cache.js"

 // Bedrock cache markers are positional: emit a `cachePoint` block immediately
 // after the content the caller wants treated as a cacheable prefix. Bedrock
-// accepts optional `ttl: "5m" | "1h"` on cachePoint.
+// accepts optional `ttl: "5m" | "1h"` on cachePoint, mirroring Anthropic.
 export const CachePointBlock = Schema.Struct({
  cachePoint: Schema.Struct({
    type: Schema.tag("default"),
@@ -13,8 +13,9 @@ export const CachePointBlock = Schema.Struct({
 })
 export type CachePointBlock = Schema.Schema.Type<typeof CachePointBlock>

-// Callers pass a shared counter through every `block()` call site so the
-// four-breakpoint budget is respected across `system`, `messages`, and `tools`.
+// Bedrock-Claude enforces the same 4-breakpoint cap as the Anthropic Messages
+// API. Callers pass a shared counter through every `block()` call site so the
+// budget is respected across `system`, `messages`, and `tools`.
 export const BEDROCK_BREAKPOINT_CAP = 4

 export type { Breakpoints } from "./cache.js"
@@ -1,4 +1,6 @@
-// Shared counter and TTL mapping for provider cache-marker lowering.
+// Shared helpers for provider cache-marker lowering. Anthropic and Bedrock
+// both enforce a 4-breakpoint cap per request and accept the same `5m`/`1h`
+// TTL buckets, so the counter and TTL mapping live here.

 export interface Breakpoints {
  remaining: number
@@ -7,7 +9,8 @@ export interface Breakpoints {

 export const newBreakpoints = (cap: number): Breakpoints => ({ remaining: cap, dropped: 0 })

-// Requests of at least one hour use the explicit `"1h"` bucket; shorter
-// requests omit the wire TTL and use the provider default.
+// Returns `"1h"` for any `ttlSeconds >= 3600`, otherwise `undefined` (the
+// provider default 5m). Anthropic & Bedrock both treat anything shorter than
+// an hour as 5m.
 export const ttlBucket = (ttlSeconds: number | undefined): "1h" | undefined =>
  ttlSeconds !== undefined && ttlSeconds >= 3600 ? "1h" : undefined
@@ -1,19 +1,5 @@
 import { Option, Schema } from "effect"
-import type { LLMRequest } from "../../schema/index.js"
-
-export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
-export type ReasoningEffort = (typeof ReasoningEfforts)[number] | (string & {})
-export const ReasoningEffort = Schema.declare<ReasoningEffort>(
-  (value): value is ReasoningEffort => typeof value === "string",
-  { title: "ReasoningEffort" },
-)
-
-export const TextVerbosities = ["low", "medium", "high"] as const
-export type TextVerbosity = (typeof TextVerbosities)[number] | (string & {})
-export const TextVerbosity = Schema.declare<TextVerbosity>(
-  (value): value is TextVerbosity => typeof value === "string",
-  { title: "TextVerbosity" },
-)
+import { TextVerbosity, type LLMRequest } from "../../schema/index.js"

 export const ResponseIncludables = [
  "file_search_call.results",
@@ -33,6 +19,7 @@ export type ServiceTier = (typeof ServiceTiers)[number]
 export const Truncations = ["auto", "disabled"] as const
 export type Truncation = (typeof Truncations)[number]

+export const ReasoningEffort = Schema.String
 export const TextVerbositySchema = TextVerbosity
 export const ResponseIncludableSchema = Schema.declare<ResponseIncludable>(
  (value): value is ResponseIncludable => typeof value === "string",
@@ -69,7 +56,9 @@ export type Resolved = Omit<Options, "allowedTools"> & {
 const decodeOptions = Schema.decodeUnknownOption(Options)

 export const resolve = (request: LLMRequest): Resolved => {
-  const input = Option.getOrUndefined(decodeOptions(request.providerOptions))
+  const input = Option.getOrUndefined(
+    decodeOptions(request.providerOptions?.[request.model.route.providerMetadataKey ?? "openresponses"]),
+  )
  if (!input) return {}
  return {
    ...input,
@@ -1,9 +1,8 @@
+import { ReasoningEfforts } from "../../schema/index.js"
 import { OpenResponsesOptions } from "./open-responses-options.js"

-export const OpenAIReasoningEfforts = OpenResponsesOptions.ReasoningEfforts
-export type OpenAIReasoningEffort = OpenResponsesOptions.ReasoningEffort
-export const OpenAITextVerbosities = OpenResponsesOptions.TextVerbosities
-export type OpenAITextVerbosity = OpenResponsesOptions.TextVerbosity
+export const OpenAIReasoningEfforts = ReasoningEfforts
+export type OpenAIReasoningEffort = string

 // Mirrors OpenAI's `ResponseIncludable` union from the official SDK. Keep this
 // in lockstep with `openai-node/src/resources/responses/responses.ts`.
@@ -13,7 +12,7 @@ export const OpenAIServiceTiers = OpenResponsesOptions.ServiceTiers
 export type OpenAIServiceTier = OpenResponsesOptions.ServiceTier

 export const OpenAIReasoningEffort = OpenResponsesOptions.ReasoningEffort
-export const OpenAITextVerbosity = OpenResponsesOptions.TextVerbosity
+export const OpenAITextVerbosity = OpenResponsesOptions.TextVerbositySchema
 export const OpenAIResponseIncludable = OpenResponsesOptions.ResponseIncludableSchema
 export const OpenAIServiceTier = OpenResponsesOptions.ServiceTierSchema

@@ -27,7 +27,7 @@ export interface Settings extends ProviderPackage.Settings {
 const route = OpenAICompatibleResponses.route.with({
  id: "google-vertex-responses",
  provider: id,
-  providerOptions: { store: false },
+  providerOptions: { openresponses: { store: false } },
 })

 export const routes = [route]
@@ -6,14 +6,16 @@ import { Auth } from "../route/auth.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
-import { ProviderID, type LLMRequest, type ModelID } from "../schema/index.js"
+import { ProviderID, type LLMRequest, type ModelID, type ProviderOptions } from "../schema/index.js"
 import { GoogleVertexShared } from "./google-vertex-shared.js"

 export interface GeminiOptionsInput extends Gemini.OptionsInput {
  readonly labels?: Readonly<Record<string, string>>
 }

-export type GeminiProviderOptionsInput = GeminiOptionsInput
+export type GeminiProviderOptionsInput = ProviderOptions & {
+  readonly gemini?: GeminiOptionsInput
+}

 export const id = ProviderID.make("google-vertex")

@@ -38,7 +40,7 @@ export type Settings = ProviderPackage.Settings &

 const fromRequest = Effect.fn("GoogleVertex.fromRequest")(function* (request: LLMRequest) {
  const body = yield* Gemini.protocol.body.from(request)
-  const value = request.providerOptions?.labels
+  const value = request.providerOptions?.gemini?.labels
  const labels = ProviderShared.isRecord(value)
    ? Object.fromEntries(
        Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
@@ -1,6 +1,10 @@
 import type { Options } from "../protocols/utils/open-responses-options.js"
+import type { ProviderOptions } from "../schema/index.js"

 export type OpenResponsesOptionsInput = Options & { readonly [key: string]: unknown }
-export type OpenResponsesProviderOptionsInput = OpenResponsesOptionsInput
+
+export type OpenResponsesProviderOptionsInput = ProviderOptions & {
+  readonly openresponses?: OpenResponsesOptionsInput
+}

 export * as OpenResponsesProviderOptions from "./open-responses-options.js"
@@ -1,17 +1,20 @@
-import { mergeProviderOptions, type ProviderOptions } from "../schema/index.js"
+import type { ProviderOptions } from "../schema/index.js"
+import { mergeProviderOptions } from "../schema/index.js"
 import type { OpenResponsesOptionsInput } from "./open-responses-options.js"

 export type { OpenAIResponseIncludable, OpenAIServiceTier } from "../protocols/utils/openai-options.js"

 export type OpenAIOptionsInput = OpenResponsesOptionsInput

-export type OpenAIProviderOptionsInput = OpenAIOptionsInput
+export type OpenAIProviderOptionsInput = ProviderOptions & {
+  readonly openai?: OpenAIOptionsInput
+}

 const definedEntries = (input: Record<string, unknown>) =>
  Object.entries(input).filter((entry) => entry[1] !== undefined)

 const openAIProviderOptions = (options: OpenAIOptionsInput | undefined): ProviderOptions | undefined => {
-  const result = Object.fromEntries(
+  const openai = Object.fromEntries(
    definedEntries({
      store: options?.store,
      reasoningEffort: options?.reasoningEffort,
@@ -21,8 +24,8 @@ const openAIProviderOptions = (options: OpenAIOptionsInput | undefined): Provide
      serviceTier: options?.serviceTier,
    }),
  )
-  if (Object.keys(result).length === 0) return undefined
-  return result
+  if (Object.keys(openai).length === 0) return undefined
+  return { openai }
 }

 export const gpt5DefaultOptions = (
@@ -4,7 +4,7 @@ import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
 import { Protocol } from "../route/protocol.js"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { ProviderID, type CacheHint, type ModelID } from "../schema/index.js"
+import { ProviderID, type CacheHint, type ModelID, type ProviderOptions } from "../schema/index.js"
 import type { ProviderPackage } from "../provider-package.js"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
@@ -71,7 +71,9 @@ export interface OpenRouterOptions {
  }>
 }

-export type OpenRouterProviderOptionsInput = OpenRouterOptions
+export type OpenRouterProviderOptionsInput = ProviderOptions & {
+  readonly openrouter?: OpenRouterOptions
+}

 export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
  ProviderAuthOption<"optional"> & {
@@ -118,7 +120,7 @@ export const protocol = Protocol.make({
          return {
            ...body,
            messages,
-            ...bodyOptions(request.providerOptions),
+            ...bodyOptions(request.providerOptions?.openrouter),
            ...(request.promptCacheKey ? { prompt_cache_key: request.promptCacheKey } : {}),
          } as OpenRouterBody
        }),
@@ -1,7 +1,7 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { HttpOptions, ProviderID, type ModelID, type ProviderOptions } from "../schema/index.js"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile.js"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
@@ -12,7 +12,9 @@ import type { ProviderPackage } from "../provider-package.js"

 export const id = ProviderID.make("xai")

-export type XAIProviderOptionsInput = OpenAIOptionsInput
+export type XAIProviderOptionsInput = ProviderOptions & {
+  readonly xai?: OpenAIOptionsInput
+}

 export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
  ProviderAuthOption<"optional"> & {
@@ -35,7 +37,7 @@ const responsesRoute = Route.make({
  protocol: OpenAIResponses.protocol,
  endpoint: Endpoint.path("/responses", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
  transport: OpenAIResponses.httpTransport,
-  defaults: { providerOptions: { store: false } },
+  defaults: { providerOptions: { xai: { store: false } } },
 })

 const chatRoute = Route.make({
@@ -13,8 +13,8 @@ import type { AIError } from "../schema/index.js"
 * - AWS event stream — length-prefixed binary frames with CRC checksums.
 *   Each emitted frame is one parsed binary event record.
 *
- * The frame type is opaque to this layer; the protocol's event schema decodes
- * each frame before its state machine handles it.
+ * The frame type is opaque to this layer; the protocol's `decode` step turns
+ * a frame into a typed chunk.
 */
 export interface Definition<Frame> {
  readonly id: string
@@ -73,7 +73,8 @@ export interface ProtocolStream<Frame, Event, State> {
 *
 * Provider implementations should usually call `Protocol.make({ ... })`
 * without explicit type arguments; the schemas and parser functions are the
- * source of truth.
+ * source of truth. The constructor remains as the public seam for future
+ * cross-cutting concerns such as tracing or instrumentation.
 */
 export const make = <Body, Frame, Event, State>(
  input: Protocol<Body, Frame, Event, State>,
@@ -1,7 +1,6 @@
 import { Schema } from "effect"
 import { Tool } from "@opencode-ai/schema/tool"
-import { ModelID, ProviderID, RouteID } from "./ids.js"
-import { ProviderMetadata } from "./messages.js"
+import { ModelID, ProviderID, ProviderMetadata, RouteID } from "./ids.js"

 export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"])
 export type ProviderFailureClassification = typeof ProviderFailureClassification.Type
@@ -1,21 +1,8 @@
 import { Schema } from "effect"
-import { LLM } from "@opencode-ai/schema/llm"
-import { ContentBlockID, ToolCallID } from "./ids.js"
-import {
-  Message,
-  ProviderMetadata,
-  ToolCallPart,
-  ToolOutput,
-  ToolResultPart,
-  ToolResultValue,
-  type ContentPart,
-} from "./messages.js"
+import { ContentBlockID, FinishReason, ProviderMetadata, ToolCallID } from "./ids.js"
+import { Message, ToolCallPart, ToolOutput, ToolResultPart, ToolResultValue, type ContentPart } from "./messages.js"
 import { ProviderFailureClassification } from "./errors.js"

-export const FinishReason = LLM.FinishReason
-export type FinishReason = Schema.Schema.Type<typeof FinishReason>
-export { ProviderMetadata } from "./messages.js"
-
 /**
 * Token usage reported by an LLM provider.
 *
@@ -1,4 +1,8 @@
 import { Schema } from "effect"
+import { ProviderMetadata } from "@opencode-ai/schema/ai"
+import { LLM } from "@opencode-ai/schema/llm"
+
+export { ProviderMetadata }

 /** Stable string identifier for a protocol implementation. */
 export const ProtocolID = Schema.String
@@ -22,3 +26,19 @@ export type ContentBlockID = Schema.Schema.Type<typeof ContentBlockID>

 export const ToolCallID = Schema.String
 export type ToolCallID = Schema.Schema.Type<typeof ToolCallID>
+
+export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
+export const ReasoningEffort = Schema.String
+export type ReasoningEffort = Schema.Schema.Type<typeof ReasoningEffort>
+
+export const TextVerbosity = Schema.Literals(["low", "medium", "high"])
+export type TextVerbosity = Schema.Schema.Type<typeof TextVerbosity>
+
+export const MessageRole = Schema.Literals(["system", "user", "assistant", "tool"])
+export type MessageRole = Schema.Schema.Type<typeof MessageRole>
+
+export const FinishReason = LLM.FinishReason
+export type FinishReason = Schema.Schema.Type<typeof FinishReason>
+
+export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
+export type JsonSchema = Schema.Schema.Type<typeof JsonSchema>
@@ -1,24 +1,16 @@
 import { Schema } from "effect"
 import { Tool } from "@opencode-ai/schema/tool"
+import { JsonSchema, MessageRole, ProviderMetadata } from "./ids.js"
 import {
  CacheHint,
  CachePolicy,
  GenerationOptions,
  HttpOptions,
-  JsonSchema,
  LanguageModelSchema,
  ProviderOptions,
 } from "./options.js"
 import { isRecord } from "../utils/record.js"

-export const MessageRole = Schema.Literals(["system", "user", "assistant", "tool"])
-export type MessageRole = Schema.Schema.Type<typeof MessageRole>
-
-export const ProviderMetadata = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown)).annotate({
-  identifier: "LLM.ProviderMetadata",
-})
-export type ProviderMetadata = Schema.Schema.Type<typeof ProviderMetadata>
-
 const systemPartSchema = Schema.Struct({
  type: Schema.Literal("text"),
  text: Schema.String,
@@ -1,11 +1,8 @@
 import { Schema } from "effect"
-import { ModelID, ProviderID } from "./ids.js"
+import { JsonSchema, ModelID, ProviderID } from "./ids.js"
 import type { AnyRoute } from "../route/client.js"
 import { isRecord } from "../utils/record.js"

-export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
-export type JsonSchema = Schema.Schema.Type<typeof JsonSchema>
-
 export const mergeJsonRecords = (
  ...items: ReadonlyArray<Record<string, unknown> | undefined>
 ): Record<string, unknown> | undefined => {
@@ -36,12 +33,22 @@ const mergeStringRecords = (
  return Object.keys(result).length === 0 ? undefined : result
 }

-export const ProviderOptions = Schema.Record(Schema.String, Schema.Unknown)
+export const ProviderOptions = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown))
 export type ProviderOptions = Schema.Schema.Type<typeof ProviderOptions>

 export const mergeProviderOptions = (
  ...items: ReadonlyArray<ProviderOptions | undefined>
-): ProviderOptions | undefined => mergeJsonRecords(...items)
+): ProviderOptions | undefined => {
+  const result: Record<string, Record<string, unknown>> = {}
+  for (const item of items) {
+    if (!item) continue
+    for (const [provider, options] of Object.entries(item)) {
+      const merged = mergeJsonRecords(result[provider], options)
+      if (merged) result[provider] = merged
+    }
+  }
+  return Object.keys(result).length === 0 ? undefined : result
+}

 export class HttpOptions extends Schema.Class<HttpOptions>("AI.HttpOptions")({
  body: Schema.optional(JsonSchema),
@@ -262,9 +269,10 @@ export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({
 // Auto-placement policy for prompt caching. The protocol-neutral lowering step
 // reads this and injects `CacheHint`s at the configured boundaries; the
 // per-protocol body builders then translate those hints into wire markers as
-// usual. `"auto"` is the default for agent loops — it places
+// usual. `"auto"` is the recommended default for agent loops — it places
 // breakpoints at the last tool definition, the first and last distinct system
-// parts, and the conversation tail so recent prefixes remain reusable during
+// parts, and the conversation tail. The rolling message breakpoint keeps a
+// prior cache entry within Anthropic/Bedrock's 20-block lookback during long
 // tool loops.
 //
 // Pass `"none"` to opt out entirely (the legacy behavior). Pass the granular
@@ -81,7 +81,7 @@ OpenAI.configure({
 }).responses("gpt-4.1-mini")
 OpenAI.configure({
  generation: { maxTokens: 100 },
-  providerOptions: { store: false },
+  providerOptions: { openai: { store: false } },
 }).responses("gpt-4.1-mini")

 // @ts-expect-error OpenAI model selectors only accept model ids.
@@ -97,7 +97,7 @@ OpenAI.configure({ bogus: true })
 OpenAI.configure({ generation: { maxTokens: "many" } })

 // @ts-expect-error provider-native options remain typed.
-OpenAI.configure({ providerOptions: { store: "false" } })
+OpenAI.configure({ providerOptions: { openai: { store: "false" } } })

 // @ts-expect-error auth is an override, so OpenAI rejects apiKey with auth.
 OpenAI.configure({ apiKey: "sk-test", auth: Auth.bearer("oauth-token") })
@@ -139,8 +139,7 @@ Anthropic.configure({ apiKey: "anthropic-key" }).model("claude-haiku")
 Anthropic.configure({
  apiKey: "anthropic-key",
  providerOptions: {
-    thinking: { type: "enabled", budgetTokens: 1_024 },
-    effort: "high",
+    anthropic: { thinking: { type: "enabled", budgetTokens: 1_024 }, effort: "high" },
  },
 }).model("claude-haiku")
 // @ts-expect-error Anthropic model selectors only accept model ids.
@@ -148,15 +147,15 @@ Anthropic.configure({ apiKey: "anthropic-key" }).model("claude-haiku", {})
 // @ts-expect-error Anthropic package settings accept only one auth source.
 Anthropic.model("claude-sonnet-4-6", { apiKey: "anthropic-key", authToken: "anthropic-token" })
 // @ts-expect-error Enabled Anthropic thinking requires a token budget.
-Anthropic.configure({ providerOptions: { thinking: { type: "enabled" } } })
+Anthropic.configure({ providerOptions: { anthropic: { thinking: { type: "enabled" } } } })
 // @ts-expect-error Anthropic thinking budgets must be numbers.
-Anthropic.configure({ providerOptions: { thinking: { type: "enabled", budgetTokens: "large" } } })
+Anthropic.configure({ providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: "large" } } } })

 AnthropicCompatible.configure({
  apiKey: "messages-key",
  baseURL: "https://messages.example.com/v1",
  provider: "example",
-  providerOptions: { thinking: { type: "disabled" } },
+  providerOptions: { anthropic: { thinking: { type: "disabled" } } },
 }).model("compatible-model")
 // @ts-expect-error Anthropic-compatible providers require a base URL.
 AnthropicCompatible.configure({ apiKey: "messages-key" })
@@ -172,16 +171,16 @@ AnthropicCompatible.model("compatible-model", {
 Google.configure({ apiKey: "google-key" }).model("gemini-2.5-flash")
 Google.configure({
  apiKey: "google-key",
-  providerOptions: { thinkingConfig: { thinkingBudget: 0, includeThoughts: false } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 0, includeThoughts: false } } },
 }).model("gemini-2.5-flash")
 // @ts-expect-error Google model selectors only accept model ids.
 Google.configure({ apiKey: "google-key" }).model("gemini-2.5-flash", {})
 // @ts-expect-error Gemini thinking budgets must be numbers.
-Google.configure({ providerOptions: { thinkingConfig: { thinkingBudget: "large" } } })
+Google.configure({ providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "large" } } } })

 GoogleVertex.configure({
  apiKey: "vertex-key",
-  providerOptions: { thinkingConfig: { thinkingBudget: 1_024 } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1_024 } } },
 }).model("gemini-3.5-flash")
 GoogleVertex.configure({ accessToken: "vertex-token", project: "project" }).model("gemini-3.5-flash")
 GoogleVertex.configure({ auth: Auth.bearer("vertex-token"), project: "project" }).model("gemini-3.5-flash")
@@ -231,7 +230,7 @@ GoogleVertexResponses.configure({
 GoogleVertexMessages.configure({
  accessToken: "vertex-token",
  project: "project",
-  providerOptions: { thinking: { type: "adaptive", display: "omitted" }, effort: "low" },
+  providerOptions: { anthropic: { thinking: { type: "adaptive", display: "omitted" }, effort: "low" } },
 }).model("claude-sonnet-4-6")
 // @ts-expect-error Vertex Messages package settings do not accept API keys.
 GoogleVertexMessages.model("claude-sonnet-4-6", { apiKey: "vertex-key", project: "project" })
@@ -17,25 +17,31 @@ describe("request option precedence", () => {
  test("deep-merges provider option records and replaces arrays, primitives, and null", () => {
    const merged = mergeProviderOptions(
      {
-        include: ["route"],
-        metadata: { route: true, shared: "route" },
-        nullable: "route",
-        primitive: "route",
+        openai: {
+          include: ["route"],
+          metadata: { route: true, shared: "route" },
+          nullable: "route",
+          primitive: "route",
+        },
      },
      {
-        include: ["model"],
-        metadata: { model: true, shared: "model" },
-        nullable: null,
-        primitive: "model",
+        openai: {
+          include: ["model"],
+          metadata: { model: true, shared: "model" },
+          nullable: null,
+          primitive: "model",
+        },
      },
-      { metadata: { request: true }, primitive: false },
+      { openai: { metadata: { request: true }, primitive: false } },
    )

    expect(merged).toEqual({
-      include: ["model"],
-      metadata: { route: true, model: true, request: true, shared: "model" },
-      nullable: null,
-      primitive: false,
+      openai: {
+        include: ["model"],
+        metadata: { route: true, model: true, request: true, shared: "model" },
+        nullable: null,
+        primitive: false,
+      },
    })
  })

@@ -45,13 +51,13 @@ describe("request option precedence", () => {
        endpoint: { baseURL: "https://api.openai.test/v1/" },
        auth: Auth.bearer("test"),
        generation: { maxTokens: 10, temperature: 1, stop: ["route"] },
-        providerOptions: { store: false, reasoningEffort: "low" },
+        providerOptions: { openai: { store: false, reasoningEffort: "low" } },
      })
      const model = route.model({
        id: "gpt-4o-mini",
        defaults: {
          generation: { maxTokens: 20, temperature: 0.5, frequencyPenalty: 0.25, stop: ["model"] },
-          providerOptions: { reasoningEffort: "medium" },
+          providerOptions: { openai: { reasoningEffort: "medium" } },
        },
      })
      const prepared = yield* compileRequest(
@@ -59,7 +65,7 @@ describe("request option precedence", () => {
          model,
          prompt: "Say hello.",
          generation: { maxTokens: 30, topP: 0.9, stop: ["request"] },
-          providerOptions: { store: true },
+          providerOptions: { openai: { store: true } },
        }),
      )

@@ -105,7 +105,7 @@ export function continuationRequest(input: {
    tools: features.has("tool-call") ? [continuationTool] : [],
    cache: "none",
    providerOptions: features.has("encrypted-reasoning")
-      ? { store: false, include: ["reasoning.encrypted_content"], reasoningSummary: "auto" }
+      ? { openai: { store: false, include: ["reasoning.encrypted_content"], reasoningSummary: "auto" } }
      : undefined,
    generation: { maxTokens: 80, temperature: 0 },
  })
@@ -13,7 +13,9 @@ interface ExampleOptions {
  readonly mode?: "fast" | "thorough"
 }

-type ExampleProviderOptions = ProviderOptions & ExampleOptions
+type ExampleProviderOptions = ProviderOptions & {
+  readonly example?: ExampleOptions
+}

 const model = OpenAIChat.route
  .with({ endpoint: { baseURL: "https://example.com/v1" } })
@@ -24,7 +26,7 @@ type StreamRequirements<T> = T extends Stream.Stream<infer _A, infer _E, infer R
 type Equal<A, B> = [A, B] extends [B, A] ? true : false
 type Assert<T extends true> = T

-LLM.request({ model, prompt: "Hello", providerOptions: { mode: "fast" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { example: { mode: "fast" } } })
 LLM.request({ model, prompt: "Hello", providerOptions: { future: { option: true } } })

 const generated = LLM.generate(LLM.request({ model, prompt: "Hello" }))
@@ -36,14 +38,14 @@ LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Known provider options preserve their value types.
-  providerOptions: { mode: "slow" },
+  providerOptions: { example: { mode: "slow" } },
 })

 const generatedObject = LLM.generateObject({
  model,
  prompt: "Hello",
  schema: Schema.Struct({ answer: Schema.String }),
-  providerOptions: { mode: "thorough" },
+  providerOptions: { example: { mode: "thorough" } },
 })
 type GenerateObjectRequirements = Assert<Equal<Requirements<typeof generatedObject>, LLMClientService>>

@@ -59,13 +61,13 @@ LLM.generateObject({
  prompt: "Hello",
  jsonSchema: { type: "object" },
  // @ts-expect-error Dynamic object generation uses the selected model's provider options.
-  providerOptions: { mode: false },
+  providerOptions: { example: { mode: false } },
 })

 declare const generic: LanguageModel
 LLM.request({ model: generic, prompt: "Hello", providerOptions: { arbitrary: { option: true } } })

-const options: LanguageModelProviderOptions<typeof model> = { mode: "fast" }
+const options: LanguageModelProviderOptions<typeof model> = { example: { mode: "fast" } }
 void (options satisfies LanguageModelProviderOptions<typeof model>)
 void (true satisfies GenerateRequirements)
 void (true satisfies StreamClientRequirements)
@@ -59,18 +59,18 @@ describe("llm constructors", () => {
        provider: "fake",
        route: chatRoute.with({
          generation: { maxTokens: 100, temperature: 1 },
-          providerOptions: { store: false, metadata: { model: true } },
+          providerOptions: { openai: { store: false, metadata: { model: true } } },
          http: { body: { metadata: { model: true } }, headers: { "x-shared": "model" }, query: { model: "1" } },
        }),
      }),
      prompt: "Say hello.",
      generation: { temperature: 0 },
-      providerOptions: { store: true, metadata: { request: true } },
+      providerOptions: { openai: { store: true, metadata: { request: true } } },
      http: { body: { metadata: { request: true } }, headers: { "x-shared": "request" }, query: { request: "1" } },
    })

    expect(request.generation).toEqual({ temperature: 0 })
-    expect(request.providerOptions).toEqual({ store: true, metadata: { request: true } })
+    expect(request.providerOptions).toEqual({ openai: { store: true, metadata: { request: true } } })
    expect(request.http).toEqual({
      body: { metadata: { request: true } },
      headers: { "x-shared": "request" },
@@ -123,7 +123,7 @@ describe("llm constructors", () => {
      defaults: {
        limits: { context: 128_000, output: 8_192 },
        generation: { maxTokens: 1_024, stop: ["END"] },
-        providerOptions: { parallelToolCalls: false },
+        providerOptions: { openai: { parallelToolCalls: false } },
        http: { body: { extra_body: true } },
      },
      compatibility: { toolSchema: "moonshot" },
@@ -132,7 +132,7 @@ describe("llm constructors", () => {

    expect(request.model.defaults?.limits).toEqual({ context: 128_000, output: 8_192 })
    expect(request.model.defaults?.generation).toEqual({ maxTokens: 1_024, stop: ["END"] })
-    expect(request.model.defaults?.providerOptions).toEqual({ parallelToolCalls: false })
+    expect(request.model.defaults?.providerOptions).toEqual({ openai: { parallelToolCalls: false } })
    expect(request.model.defaults?.http).toEqual({ body: { extra_body: true } })
    expect(request.model.compatibility).toEqual({ toolSchema: "moonshot" })
    expect(request.generation).toBeUndefined()
@@ -3,11 +3,11 @@ import { AnthropicCompatible } from "../../src/providers.js"

 const model = AnthropicCompatible.configure({ baseURL: "https://example.com" }).model("claude")

-LLM.request({ model, prompt: "Hello", providerOptions: { effort: "high" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { anthropic: { effort: "high" } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Anthropic effort must be a string.
-  providerOptions: { effort: 1 },
+  providerOptions: { anthropic: { effort: 1 } },
 })
@@ -3,11 +3,11 @@ import { Anthropic } from "../../src/providers.js"

 const model = Anthropic.provider.model("claude-sonnet-4-5")

-LLM.request({ model, prompt: "Hello", providerOptions: { thinking: { type: "adaptive" } } })
+LLM.request({ model, prompt: "Hello", providerOptions: { anthropic: { thinking: { type: "adaptive" } } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Anthropic thinking modes are a fixed union.
-  providerOptions: { thinking: { type: "automatic" } },
+  providerOptions: { anthropic: { thinking: { type: "automatic" } } },
 })
@@ -3,11 +3,11 @@ import { Azure } from "../../src/providers.js"

 const model = Azure.configure({ resourceName: "example" }).responses("deployment")

-LLM.request({ model, prompt: "Hello", providerOptions: { store: false } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { store: false } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Azure OpenAI store must be boolean.
-  providerOptions: { store: "false" },
+  providerOptions: { openai: { store: "false" } },
 })
@@ -3,11 +3,11 @@ import { GoogleVertexChat } from "../../src/providers.js"

 const model = GoogleVertexChat.configure({ accessToken: "test", project: "project" }).model("gemini")

-LLM.request({ model, prompt: "Hello", providerOptions: { serviceTier: "priority" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { serviceTier: "priority" } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Vertex OpenAI-compatible service tiers use the OpenAI union.
-  providerOptions: { serviceTier: "premium" },
+  providerOptions: { openai: { serviceTier: "premium" } },
 })
@@ -3,11 +3,11 @@ import { GoogleVertexMessages } from "../../src/providers.js"

 const model = GoogleVertexMessages.configure({ accessToken: "test", project: "project" }).model("claude")

-LLM.request({ model, prompt: "Hello", providerOptions: { effort: "medium" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { anthropic: { effort: "medium" } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Vertex Anthropic effort must be a string.
-  providerOptions: { effort: false },
+  providerOptions: { anthropic: { effort: false } },
 })
@@ -3,12 +3,11 @@ import { GoogleVertexResponses } from "../../src/providers.js"

 const model = GoogleVertexResponses.configure({ accessToken: "test", project: "project" }).model("gemini")

-LLM.request({ model, prompt: "Hello", providerOptions: { textVerbosity: "high" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { textVerbosity: "verbose" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openresponses: { textVerbosity: "high" } } })

 LLM.request({
  model,
  prompt: "Hello",
-  // @ts-expect-error Vertex Responses verbosity must be a string.
-  providerOptions: { textVerbosity: 1 },
+  // @ts-expect-error Vertex Responses verbosity uses the Open Responses union.
+  providerOptions: { openresponses: { textVerbosity: "verbose" } },
 })
@@ -6,12 +6,12 @@ const model = GoogleVertex.provider.configure({ apiKey: "test" }).model("gemini-
 LLM.request({
  model,
  prompt: "Hello",
-  providerOptions: { thinkingConfig: { includeThoughts: true } },
+  providerOptions: { gemini: { thinkingConfig: { includeThoughts: true } } },
 })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Vertex Gemini includeThoughts must be boolean.
-  providerOptions: { thinkingConfig: { includeThoughts: "yes" } },
+  providerOptions: { gemini: { thinkingConfig: { includeThoughts: "yes" } } },
 })
@@ -6,15 +6,17 @@ const model = Google.provider.model("gemini-2.5-pro")
 LLM.request({
  model,
  prompt: "Hello",
-  providerOptions: { thinkingConfig: { thinkingBudget: 1024 } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1024 } } },
 })

 LLM.request({
  model,
  prompt: "Hello",
  providerOptions: {
-    // @ts-expect-error Gemini safety settings require a threshold for every category.
-    safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH" }],
+    gemini: {
+      // @ts-expect-error Gemini safety settings require a threshold for every category.
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH" }],
+    },
  },
 })

@@ -22,10 +24,12 @@ LLM.request({
  model,
  prompt: "Hello",
  providerOptions: {
-    cachedContent: "cachedContents/example",
-    safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
-    serviceTier: "future-tier",
-    thinkingConfig: { thinkingLevel: "high", includeThoughts: true },
+    gemini: {
+      cachedContent: "cachedContents/example",
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+      serviceTier: "future-tier",
+      thinkingConfig: { thinkingLevel: "high", includeThoughts: true },
+    },
  },
 })

@@ -33,11 +37,11 @@ LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Gemini thinking budgets must be numeric.
-  providerOptions: { thinkingConfig: { thinkingBudget: "large" } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "large" } } },
 })

 LLM.request({
  model,
  prompt: "Hello",
-  providerOptions: { thinkingConfig: { thinkingLevel: "maximum" } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "maximum" } } },
 })
@@ -3,15 +3,11 @@ import { OpenAICompatibleResponses } from "../../src/providers.js"

 const model = OpenAICompatibleResponses.configure({ baseURL: "https://example.com" }).model("model")

-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningSummary: "detailed" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "high" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { textVerbosity: "low" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { textVerbosity: "verbose" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openresponses: { reasoningSummary: "detailed" } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error Open Responses reasoning summaries use a fixed union.
-  providerOptions: { reasoningSummary: "full" },
+  providerOptions: { openresponses: { reasoningSummary: "full" } },
 })
@@ -3,11 +3,11 @@ import { OpenAICompatible } from "../../src/providers.js"

 const model = OpenAICompatible.deepseek.model("deepseek-chat")

-LLM.request({ model, prompt: "Hello", providerOptions: { store: false } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { store: false } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error OpenAI-compatible store must be boolean.
-  providerOptions: { store: "false" },
+  providerOptions: { openai: { store: "false" } },
 })
@@ -2,20 +2,14 @@ import { LLM } from "../../src/index.js"
 import { OpenAI } from "../../src/providers.js"

 const selected = OpenAI.responses("gpt-5")
-const chat = OpenAI.chat("gpt-4o-mini")

-LLM.request({ model: selected, prompt: "Hello", providerOptions: { reasoningEffort: "high" } })
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { textVerbosity: "low" } })
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { textVerbosity: "verbose" } })
-LLM.request({ model: chat, prompt: "Hello", providerOptions: { reasoningEffort: "max" } })
-LLM.request({ model: chat, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
+LLM.request({ model: selected, prompt: "Hello", providerOptions: { openai: { reasoningEffort: "high" } } })

 LLM.request({
  model: selected,
  prompt: "Hello",
  // @ts-expect-error OpenAI reasoning effort must be a string.
-  providerOptions: { reasoningEffort: 1 },
+  providerOptions: { openai: { reasoningEffort: 1 } },
 })

 OpenAI.configure({
@@ -3,25 +3,27 @@ import { OpenRouter } from "../../src/providers.js"

 const model = OpenRouter.provider.model("anthropic/claude-sonnet-4.5")

-LLM.request({ model, prompt: "Hello", providerOptions: { usage: true } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openrouter: { usage: true } } })

 LLM.request({
  model,
  prompt: "Hello",
  providerOptions: {
-    models: ["google/gemini-3.1-pro"],
-    provider: {
-      order: ["anthropic"],
-      require_parameters: true,
-      data_collection: "future-policy",
-      sort: "future-sort",
-      max_price: { prompt: "0.50" },
+    openrouter: {
+      models: ["google/gemini-3.1-pro"],
+      provider: {
+        order: ["anthropic"],
+        require_parameters: true,
+        data_collection: "future-policy",
+        sort: "future-sort",
+        max_price: { prompt: "0.50" },
+      },
+      reasoning: { effort: "future-effort", exclude: false },
+      plugins: [{ id: "future-plugin", enabled: true }],
+      web_search_options: { engine: "future-engine" },
+      debug: { echo_upstream_body: true },
+      user: "user_123",
    },
-    reasoning: { effort: "future-effort", exclude: false },
-    plugins: [{ id: "future-plugin", enabled: true }],
-    web_search_options: { engine: "future-engine" },
-    debug: { echo_upstream_body: true },
-    user: "user_123",
  },
 })

@@ -29,5 +31,5 @@ LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error OpenRouter usage must be boolean or an option record.
-  providerOptions: { usage: "yes" },
+  providerOptions: { openrouter: { usage: "yes" } },
 })
@@ -3,12 +3,11 @@ import { XAI } from "../../src/providers.js"

 const model = XAI.provider.model("grok-4")

-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "high" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { xai: { reasoningEffort: "high" } } })

 LLM.request({
  model,
  prompt: "Hello",
  // @ts-expect-error xAI's OpenAI-compatible reasoning effort must be a string.
-  providerOptions: { reasoningEffort: true },
+  providerOptions: { xai: { reasoningEffort: true } },
 })
@@ -47,11 +47,11 @@ describe("provider package entrypoints", () => {
    }
    const openrouter = OpenRouter.model("anthropic/claude-sonnet-4", {
      ...settings,
-      providerOptions: { usage: true },
+      providerOptions: { openrouter: { usage: true } },
    })
    const xai = XAI.model("grok-4", {
      ...settings,
-      providerOptions: { reasoningEffort: "high" },
+      providerOptions: { xai: { reasoningEffort: "high" } },
    })

    for (const selected of [openrouter, xai]) {
@@ -60,8 +60,8 @@ describe("provider package entrypoints", () => {
      expect(selected.route.defaults.http?.body).toEqual(settings.body)
      expect(selected.route.defaults.limits).toEqual(settings.limits)
    }
-    expect(openrouter.route.defaults.providerOptions).toEqual({ usage: true })
-    expect(xai.route.defaults.providerOptions).toMatchObject({ reasoningEffort: "high", store: false })
+    expect(openrouter.route.defaults.providerOptions).toEqual({ openrouter: { usage: true } })
+    expect(xai.route.defaults.providerOptions).toMatchObject({ xai: { reasoningEffort: "high", store: false } })
  })

  test("maps package settings onto the executable model", () => {
@@ -89,7 +89,7 @@ describe("provider package entrypoints", () => {
      headers: { "x-application": "opencode" },
      body: { service_tier: "priority" },
      limits: { context: 200_000, output: 64_000 },
-      providerOptions: { reasoningEffort: "low", store: true },
+      providerOptions: { openresponses: { reasoningEffort: "low", store: true } },
    })

    expect(String(selected.provider)).toBe("example")
@@ -101,7 +101,9 @@ describe("provider package entrypoints", () => {
    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
    expect(selected.route.defaults.http?.body).toEqual({ service_tier: "priority" })
    expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
-    expect(selected.route.defaults.providerOptions).toEqual({ reasoningEffort: "low", store: true })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      openresponses: { reasoningEffort: "low", store: true },
+    })
  })

  test("maps Anthropic-compatible settings onto the executable model", async () => {
@@ -113,7 +115,7 @@ describe("provider package entrypoints", () => {
      headers: { "x-application": "opencode" },
      body: { metadata: { user_id: "user_1" } },
      limits: { context: 200_000, output: 64_000 },
-      providerOptions: { effort: "low" },
+      providerOptions: { anthropic: { effort: "low" } },
    })

    expect(String(selected.provider)).toBe("example")
@@ -125,17 +127,19 @@ describe("provider package entrypoints", () => {
    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
    expect(selected.route.defaults.http?.body).toEqual({ metadata: { user_id: "user_1" } })
    expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
-    expect(selected.route.defaults.providerOptions).toEqual({ effort: "low" })
+    expect(selected.route.defaults.providerOptions).toEqual({ anthropic: { effort: "low" } })
  })

  test("maps Anthropic provider options onto the executable model", async () => {
    const Anthropic = await import("@opencode-ai/ai/providers/anthropic")
    const selected = Anthropic.model("claude-sonnet-4-6", {
      apiKey: "fixture",
-      providerOptions: { thinking: { type: "adaptive" } },
+      providerOptions: { anthropic: { thinking: { type: "adaptive" } } },
    })

-    expect(selected.route.defaults.providerOptions).toEqual({ thinking: { type: "adaptive" } })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      anthropic: { thinking: { type: "adaptive" } },
+    })
  })

  test("requires an Anthropic-compatible base URL at runtime", async () => {
@@ -229,7 +233,7 @@ describe("provider package entrypoints", () => {
      headers: { "x-application": "opencode" },
      body: { safetySettings: [] },
      limits: { context: 1_000_000, output: 65_536 },
-      providerOptions: { thinkingConfig: { thinkingBudget: 1_024 } },
+      providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1_024 } } },
    })

    expect(selected.route.id).toBe("gemini")
@@ -237,7 +241,9 @@ describe("provider package entrypoints", () => {
    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
    expect(selected.route.defaults.http?.body).toEqual({ safetySettings: [] })
    expect(selected.route.defaults.limits).toEqual({ context: 1_000_000, output: 65_536 })
-    expect(selected.route.defaults.providerOptions).toEqual({ thinkingConfig: { thinkingBudget: 1_024 } })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      gemini: { thinkingConfig: { thinkingBudget: 1_024 } },
+    })
  })

  test("selects Vertex entrypoints with the same model contract", async () => {
@@ -299,7 +305,7 @@ describe("provider package entrypoints", () => {
      baseURL: "https://aiplatform.googleapis.com/v1/projects/vertex-project/locations/global/endpoints/openapi",
      path: "/responses",
    })
-    expect(responses.route.defaults.providerOptions).toEqual({ store: false })
+    expect(responses.route.defaults.providerOptions).toEqual({ openresponses: { store: false } })
  })

  test("rejects conflicting Vertex auth settings at runtime", async () => {
@@ -63,8 +63,7 @@ describe("Anthropic Messages route", () => {
      const prepared = yield* compileRequest(
        LLMRequest.update(request, {
          providerOptions: {
-            thinking: { type: "adaptive", display: "summarized" },
-            effort: "low",
+            anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "low" },
          },
        }),
      )
@@ -80,17 +79,17 @@ describe("Anthropic Messages route", () => {
    Effect.gen(function* () {
      const enabled = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "enabled", budgetTokens: 1_024 } },
+          providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: 1_024 } } },
        }),
      )
      const legacy = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "enabled", budget_tokens: 2_048 } },
+          providerOptions: { anthropic: { thinking: { type: "enabled", budget_tokens: 2_048 } } },
        }),
      )
      const disabled = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "disabled" } },
+          providerOptions: { anthropic: { thinking: { type: "disabled" } } },
        }),
      )

@@ -104,7 +103,7 @@ describe("Anthropic Messages route", () => {
    Effect.gen(function* () {
      const error = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "enabled" } },
+          providerOptions: { anthropic: { thinking: { type: "enabled" } } },
        }),
      ).pipe(Effect.flip)

@@ -1063,7 +1062,9 @@ describe("Anthropic Messages route", () => {
        ),
      )

-      expect(response.toolCalls).toMatchObject([{ id: "call_1", name: "lookup", input: { query: "weather" } }])
+      expect(response.toolCalls).toMatchObject([
+        { id: "call_1", name: "lookup", input: { query: "weather" } },
+      ])
      expect(response.finishReason).toEqual({ normalized: "tool-calls", raw: "tool_use" })
    }),
  )
@@ -48,26 +48,28 @@ describe("Gemini route", () => {
      const prepared = yield* compileRequest(
        LLMRequest.update(request, {
          providerOptions: {
-            cachedContent: "cachedContents/example",
-            safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
-            serviceTier: "priority",
-            thinkingConfig: { thinkingBudget: 0, includeThoughts: false, thinkingLevel: "high" },
+            gemini: {
+              cachedContent: "cachedContents/example",
+              safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+              serviceTier: "priority",
+              thinkingConfig: { thinkingBudget: 0, includeThoughts: false, thinkingLevel: "high" },
+            },
          },
        }),
      )
      const filtered = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { thinkingConfig: { thinkingBudget: "invalid", includeThoughts: false } },
+          providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "invalid", includeThoughts: false } } },
        }),
      )
      const defaulted = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { thinkingConfig: { thinkingLevel: "high" } },
+          providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "high" } } },
        }),
      )
      const emptySafetySettings = yield* compileRequest(
        LLMRequest.update(request, {
-          providerOptions: { safetySettings: [] },
+          providerOptions: { gemini: { safetySettings: [] } },
        }),
      )

@@ -62,7 +62,7 @@ describe("Google Vertex providers", () => {
            accessToken: "vertex-token",
            project: "vertex-project",
            providerOptions: {
-              labels: { component: "opencode", environment: "test" },
+              gemini: { labels: { component: "opencode", environment: "test" } },
            },
          }).model("gemini-3.5-flash"),
          prompt: "Say hello.",
@@ -15,7 +15,7 @@ const cases = [
    model: LanguageModel.update(
      OpenRouter.configure({
        apiKey: process.env.OPENROUTER_API_KEY ?? "fixture",
-        providerOptions: { reasoning: { max_tokens: 1024 } },
+        providerOptions: { openrouter: { reasoning: { max_tokens: 1024 } } },
      }).model("anthropic/claude-sonnet-4.6"),
      { compatibility: { reasoningField: "reasoning" } },
    ),
@@ -165,7 +165,7 @@ describe("OpenAI Chat route", () => {
        LLM.request({
          model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).chat("gpt-4o-mini"),
          prompt: "think",
-          providerOptions: { reasoningEffort: "max" },
+          providerOptions: { openai: { reasoningEffort: "max" } },
        }),
      )

@@ -221,7 +221,7 @@ describe("OpenAI Chat route", () => {
        LLM.request({
          model,
          prompt: "think",
-          providerOptions: { reasoningEffort: "experimental" },
+          providerOptions: { openai: { reasoningEffort: "experimental" } },
        }),
      )

@@ -255,7 +255,7 @@ describe("OpenAI Chat route", () => {
    LLMClient.generate(
      LLMRequest.update(request, {
        model: Azure.configure({
-          baseURL: "https://opencode-test.openai.azure.com/openai/",
+          baseURL: "https://opencode-test.openai.azure.com/openai/v1/",
          apiKey: "azure-key",
          headers: { authorization: "Bearer stale" },
        }).chat("gpt-4o-mini"),
@@ -118,18 +118,20 @@ describe("Open Responses-compatible route", () => {
    }),
  )

-  it.effect("reads standard Open Responses options", () =>
+  it.effect("reads standard options from the Open Responses namespace", () =>
    Effect.gen(function* () {
      const model = configure({
        apiKey: "test-key",
        baseURL: "https://responses.example.test/v1",
        providerOptions: {
-          reasoningEffort: "low",
-          store: true,
-          truncation: "auto",
-          allowedTools: { toolNames: ["lookup"] },
-          maxToolCalls: 2,
-          parallelToolCalls: false,
+          openresponses: {
+            reasoningEffort: "low",
+            store: true,
+            truncation: "auto",
+            allowedTools: { toolNames: ["lookup"] },
+            maxToolCalls: 2,
+            parallelToolCalls: false,
+          },
        },
      }).model("example-model")
      const prepared = yield* compileRequest(
@@ -159,8 +159,8 @@ describe("OpenAI Responses route", () => {

  it.effect("lowers semantic service tier options", () =>
    Effect.gen(function* () {
-      const input = LLMRequest.update(request, { providerOptions: { serviceTier: "priority" } })
-      expect(input.providerOptions).toEqual({ serviceTier: "priority" })
+      const input = LLMRequest.update(request, { providerOptions: { openai: { serviceTier: "priority" } } })
+      expect(input.providerOptions).toEqual({ openai: { serviceTier: "priority" } })
      const prepared = yield* compileRequest(input)

      expect(prepared.body).toMatchObject({ service_tier: "priority" })
@@ -171,27 +171,17 @@ describe("OpenAI Responses route", () => {
  it.effect("passes through custom OpenAI reasoning effort strings", () =>
    Effect.gen(function* () {
      const prepared = yield* compileRequest(
-        LLMRequest.update(request, { providerOptions: { reasoningEffort: "experimental" } }),
+        LLMRequest.update(request, { providerOptions: { openai: { reasoningEffort: "experimental" } } }),
      )

      expect(prepared.body.reasoning).toEqual({ effort: "experimental" })
    }),
  )

-  it.effect("passes through custom OpenAI text verbosity strings", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLMRequest.update(request, { providerOptions: { textVerbosity: "verbose" } }),
-      )
-
-      expect(prepared.body.text).toEqual({ verbosity: "verbose" })
-    }),
-  )
-
  it.effect("omits unsupported semantic service tiers", () =>
    Effect.gen(function* () {
      const prepared = yield* compileRequest(
-        LLMRequest.update(request, { providerOptions: { serviceTier: "unsupported" } }),
+        LLMRequest.update(request, { providerOptions: { openai: { serviceTier: "unsupported" } } }),
      )

      expect(prepared.body).not.toHaveProperty("service_tier")
@@ -1290,13 +1280,15 @@ describe("OpenAI Responses route", () => {
          ],
          toolChoice: "none",
          providerOptions: {
-            reasoningEffort: "high",
-            reasoningSummary: "auto",
-            include: ["reasoning.encrypted_content"],
-            truncation: "disabled",
-            allowedTools: { toolNames: ["read", "grep"], mode: "required" },
-            maxToolCalls: 4,
-            parallelToolCalls: false,
+            openai: {
+              reasoningEffort: "high",
+              reasoningSummary: "auto",
+              include: ["reasoning.encrypted_content"],
+              truncation: "disabled",
+              allowedTools: { toolNames: ["read", "grep"], mode: "required" },
+              maxToolCalls: 4,
+              parallelToolCalls: false,
+            },
          },
        }),
      )
@@ -1327,7 +1319,9 @@ describe("OpenAI Responses route", () => {
          model,
          prompt: "hi",
          providerOptions: {
-            include: ["reasoning.encrypted_content", "code_interpreter_call.outputs", "web_search_call.results"],
+            openai: {
+              include: ["reasoning.encrypted_content", "code_interpreter_call.outputs", "web_search_call.results"],
+            },
          },
        }),
      )
@@ -1346,7 +1340,7 @@ describe("OpenAI Responses route", () => {
        LLM.request({
          model,
          prompt: "hi",
-          providerOptions: { include: ["reasoning.encrypted_content", "bogus.thing"] },
+          providerOptions: { openai: { include: ["reasoning.encrypted_content", "bogus.thing"] } },
        }),
      )

@@ -1356,7 +1350,9 @@ describe("OpenAI Responses route", () => {

  it.effect("treats an explicit empty include as no include at all", () =>
    Effect.gen(function* () {
-      const prepared = yield* compileRequest(LLM.request({ model, prompt: "hi", providerOptions: { include: [] } }))
+      const prepared = yield* compileRequest(
+        LLM.request({ model, prompt: "hi", providerOptions: { openai: { include: [] } } }),
+      )

      expect(prepared.body.include).toBeUndefined()
    }),
@@ -1365,7 +1361,7 @@ describe("OpenAI Responses route", () => {
  it.effect("passes an unknown includable value through", () =>
    Effect.gen(function* () {
      const prepared = yield* compileRequest(
-        LLM.request({ model, prompt: "hi", providerOptions: { include: ["bogus.thing"] } }),
+        LLM.request({ model, prompt: "hi", providerOptions: { openai: { include: ["bogus.thing"] } } }),
      )

      expect(prepared.body.include).toEqual(["bogus.thing"])
@@ -1374,7 +1370,9 @@ describe("OpenAI Responses route", () => {

  it.effect("omits include when no include is set", () =>
    Effect.gen(function* () {
-      const prepared = yield* compileRequest(LLM.request({ model, prompt: "hi", providerOptions: { store: false } }))
+      const prepared = yield* compileRequest(
+        LLM.request({ model, prompt: "hi", providerOptions: { openai: { store: false } } }),
+      )

      expect(prepared.body.include).toBeUndefined()
    }),
@@ -1405,7 +1403,7 @@ describe("OpenAI Responses route", () => {
        LLM.request({
          model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).responses("gpt-5.2"),
          prompt: "hi",
-          providerOptions: { include: [] },
+          providerOptions: { openai: { include: [] } },
        }),
      )

@@ -1729,7 +1727,7 @@ describe("OpenAI Responses route", () => {
  it.effect("streams each reasoning summary part as a separate block", () =>
    Effect.gen(function* () {
      const response = yield* LLMClient.generate(
-        LLMRequest.update(request, { providerOptions: { store: false } }),
+        LLMRequest.update(request, { providerOptions: { openai: { store: false } } }),
      ).pipe(
        Effect.provide(
          fixedResponse(
@@ -1783,7 +1781,9 @@ describe("OpenAI Responses route", () => {

  it.effect("closes reasoning summary parts when storage is not disabled", () =>
    Effect.gen(function* () {
-      const response = yield* LLMClient.generate(LLMRequest.update(request, { providerOptions: { store: true } })).pipe(
+      const response = yield* LLMClient.generate(
+        LLMRequest.update(request, { providerOptions: { openai: { store: true } } }),
+      ).pipe(
        Effect.provide(
          fixedResponse(
            sseEvents(
@@ -1837,7 +1837,7 @@ describe("OpenAI Responses route", () => {
            ]),
            Message.user("Summarize it."),
          ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
        }),
      ).pipe(
        Effect.provide(
@@ -1896,7 +1896,7 @@ describe("OpenAI Responses route", () => {
              { type: "text", text: "After." },
            ]),
          ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
        }),
      )

@@ -1926,7 +1926,7 @@ describe("OpenAI Responses route", () => {
              },
            ]),
          ],
-          providerOptions: { store: true },
+          providerOptions: { openai: { store: true } },
        }),
      )

@@ -1959,7 +1959,7 @@ describe("OpenAI Responses route", () => {
            ]),
            Message.user("Continue."),
          ],
-          providerOptions: { store: true },
+          providerOptions: { openai: { store: true } },
        }),
      )

@@ -2032,7 +2032,7 @@ describe("OpenAI Responses route", () => {
              },
            ]),
          ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
        }),
      )

@@ -2072,7 +2072,7 @@ describe("OpenAI Responses route", () => {
            ]),
            Message.user("Summarize it."),
          ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
        }),
      )

@@ -141,7 +141,7 @@ describe("OpenRouter", () => {
        LLM.request({
          model: OpenRouter.configure({
            apiKey: "test-key",
-            providerOptions: { usage: false },
+            providerOptions: { openrouter: { usage: false } },
          }).model("openai/gpt-4o-mini"),
          cache: "none",
          prompt: "Hello",
@@ -159,15 +159,17 @@ describe("OpenRouter", () => {
          model: OpenRouter.configure({
            apiKey: "test-key",
            providerOptions: {
-              usage: true,
-              reasoning: { effort: "high" },
-              models: ["anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro"],
-              provider: { order: ["anthropic", "google"], require_parameters: true },
-              plugins: [{ id: "response-healing" }],
-              web_search_options: { engine: "native", max_results: 3 },
-              debug: { echo_upstream_body: true },
-              user: "user_123",
-              future_option: { enabled: true },
+              openrouter: {
+                usage: true,
+                reasoning: { effort: "high" },
+                models: ["anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro"],
+                provider: { order: ["anthropic", "google"], require_parameters: true },
+                plugins: [{ id: "response-healing" }],
+                web_search_options: { engine: "native", max_results: 3 },
+                debug: { echo_upstream_body: true },
+                user: "user_123",
+                future_option: { enabled: true },
+              },
            },
          }).model("anthropic/claude-3.7-sonnet:thinking"),
          prompt: "Think briefly.",
@@ -208,7 +210,7 @@ describe("OpenRouter", () => {
        LLM.request({
          model: OpenRouter.configure({
            apiKey: "test-key",
-            providerOptions: invalid,
+            providerOptions: { openrouter: invalid },
          }).model("openai/gpt-4o-mini"),
          prompt: "Hello",
        }),
@@ -181,10 +181,12 @@ const normalizeImageText = (value: string) =>
    .trim()

 const encryptedReasoningOptions = {
-  store: false,
-  include: ["reasoning.encrypted_content"],
-  reasoningEffort: "low",
-  reasoningSummary: "auto",
+  openai: {
+    store: false,
+    include: ["reasoning.encrypted_content"],
+    reasoningEffort: "low",
+    reasoningSummary: "auto",
+  },
 } as const

 type AssistantTextExpectation = string | RegExp
@@ -302,7 +304,8 @@ const runTextScenario = (context: GoldenScenarioContext) =>
    assistant.expectText(/^Hello!?$/, {
      system: "You are concise.",
      maxTokens: context.maxTokens ?? 40,
-      providerOptions: context.model.route.id === "gemini" ? { thinkingConfig: { thinkingBudget: 0 } } : undefined,
+      providerOptions:
+        context.model.route.id === "gemini" ? { gemini: { thinkingConfig: { thinkingBudget: 0 } } } : undefined,
    }),
  ])

@@ -385,7 +388,7 @@ const runReasoningScenario = (context: GoldenScenarioContext) =>
    user("Think briefly, then reply exactly with: Hello!"),
    assistant.expectText(/^Hello!?$/, {
      system: "Show concise reasoning when the provider supports visible reasoning summaries.",
-      providerOptions: { reasoningEffort: "low", reasoningSummary: "auto" },
+      providerOptions: { openai: { reasoningEffort: "low", reasoningSummary: "auto" } },
      maxTokens: context.maxTokens ?? 120,
      assert: (response) => expect(response.usage?.reasoningTokens ?? 0).toBeGreaterThan(0),
    }),
@@ -55,7 +55,7 @@ const schema_only_weather = Tool.make({
 })

 describe("LLMClient tools", () => {
-  it.effect("uses the selected model route when adding runtime tools", () =>
+  it.effect("uses the registered model route when adding runtime tools", () =>
    Effect.gen(function* () {
      const layer = scriptedResponses([
        sseEvents(deltaChunk({ role: "assistant", content: "Done." }), finishChunk("stop")),
@@ -636,7 +636,7 @@ describe("LLMClient tools", () => {
            .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
            .model({ id: "gpt-5.5" }),
          prompt: "Use the tool.",
-          providerOptions: { store: false, include: ["reasoning.encrypted_content"] },
+          providerOptions: { openai: { store: false, include: ["reasoning.encrypted_content"] } },
        }),
        tools: { get_weather },
      }).pipe(Stream.runCollect, Effect.provide(layer))
@@ -105,16 +105,4 @@ describe("extractPromptFromMessage", () => {

    expect(extractPromptFromMessage(message)[0]).toMatchObject({ type: "text", content: "model text" })
  })
-
-  test("restores command invocation text", () => {
-    const message = {
-      id: "msg_1",
-      type: "user",
-      text: "expanded command template",
-      command: { name: "command", arguments: "input" },
-      time: { created: 1 },
-    } satisfies SessionMessageUser
-
-    expect(extractPromptFromMessage(message)[0]).toMatchObject({ type: "text", content: "/command input" })
-  })
 })
@@ -44,9 +44,7 @@ export function extractPromptFromMessage(
  message: SessionMessageUser,
  opts?: { directory?: string; attachmentName?: string },
 ): Prompt {
-  const text = message.command
-    ? `/${message.command.name}${message.command.arguments ? ` ${message.command.arguments}` : ""}`
-    : (readPromptPresentation(message.metadata)?.displayText ?? message.text)
+  const text = readPromptPresentation(message.metadata)?.displayText ?? message.text
  const directory = opts?.directory
  const attachmentName = opts?.attachmentName ?? "attachment"
  const toRelative = (path: string) => {
@@ -50,18 +50,6 @@ describe("session message presentation", () => {
    })
  })

-  test("projects command invocation text", () => {
-    const message = {
-      id: "msg_user",
-      type: "user",
-      text: "expanded command template",
-      command: { name: "command", arguments: "input" },
-      time: { created: 1 },
-    } satisfies SessionMessageUser
-
-    expect(presentUserParts("ses_1", message)[0]).toMatchObject({ type: "text", text: "/command input" })
-  })
-
  test("projects current assistant content for existing DOM tools", () => {
    const message = {
      id: "msg_assistant",
@@ -57,9 +57,7 @@ export function presentUserMessage(

 export function presentUserParts(sessionID: string, message: SessionMessageUser): Part[] {
  const presentation = readPromptPresentation(message.metadata)
-  const text = message.command
-    ? `/${message.command.name}${message.command.arguments ? ` ${message.command.arguments}` : ""}`
-    : (presentation?.displayText ?? message.text)
+  const text = presentation?.displayText ?? message.text
  return [
    ...(text ? [textPart(sessionID, message.id, 0, text)] : []),
    ...(message.files ?? []).map(
@@ -30,7 +30,7 @@
    "generate": "bun run script/build.ts",
    "check:generated": "bun run generate && git diff --exit-code -- src/promise/generated src/effect/generated src/effect/api",
    "test": "bun test --timeout 5000",
-    "typecheck": "tsgo --noEmit"
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.test.json"
  },
  "dependencies": {
    "@opencode-ai/schema": "workspace:*",
@@ -12,10 +12,10 @@ import type { Brand } from "effect"
 import type { Model } from "@opencode-ai/schema/model"
 import type { SessionMessage } from "@opencode-ai/schema/session-message"
 import type { SessionInbox } from "@opencode-ai/schema/session-inbox"
+import type { Event } from "@opencode-ai/schema/event"
 import type { PromptInput } from "@opencode-ai/schema/prompt-input"
 import type { AgentAttachment } from "@opencode-ai/schema/prompt"
 import type { Skill } from "@opencode-ai/schema/skill"
-import type { Event } from "@opencode-ai/schema/event"
 import type { InstructionEntry } from "@opencode-ai/schema/instruction-entry"
 import type { Schema } from "effect"
 import type { EventLog } from "@opencode-ai/schema/event-log"
@@ -139,36 +139,46 @@ export type Endpoint5_5Input = { readonly sessionID: Session.ID }
 export type Endpoint5_5Output = Session.Info
 export type SessionGetOperation<E = never> = (input: Endpoint5_5Input) => Effect.Effect<Endpoint5_5Output, E>

-export type Endpoint5_6Input = { readonly sessionID: Session.ID }
-export type Endpoint5_6Output = void
-export type SessionRemoveOperation<E = never> = (input: Endpoint5_6Input) => Effect.Effect<Endpoint5_6Output, E>
+export type Endpoint5_6Input = { readonly sessionID: Session.ID; readonly recent?: number | undefined }
+export type Endpoint5_6Output = {
+  readonly session: Session.Info
+  readonly children: ReadonlyArray<Session.Info>
+  readonly inbox: ReadonlyArray<SessionInbox.Info>
+  readonly messages: ReadonlyArray<SessionMessage.Info>
+  readonly seq: Event.Seq
+}
+export type SessionSnapshotOperation<E = never> = (input: Endpoint5_6Input) => Effect.Effect<Endpoint5_6Output, E>

-export type Endpoint5_7Input = { readonly sessionID: Session.ID; readonly boundary: Session.ForkRequestBoundary }
-export type Endpoint5_7Output = Session.Info
-export type SessionForkOperation<E = never> = (input: Endpoint5_7Input) => Effect.Effect<Endpoint5_7Output, E>
+export type Endpoint5_7Input = { readonly sessionID: Session.ID }
+export type Endpoint5_7Output = void
+export type SessionRemoveOperation<E = never> = (input: Endpoint5_7Input) => Effect.Effect<Endpoint5_7Output, E>

-export type Endpoint5_8Input = { readonly sessionID: Session.ID; readonly agent: Agent.ID }
-export type Endpoint5_8Output = void
-export type SessionSwitchAgentOperation<E = never> = (input: Endpoint5_8Input) => Effect.Effect<Endpoint5_8Output, E>
+export type Endpoint5_8Input = { readonly sessionID: Session.ID; readonly boundary: Session.ForkRequestBoundary }
+export type Endpoint5_8Output = Session.Info
+export type SessionForkOperation<E = never> = (input: Endpoint5_8Input) => Effect.Effect<Endpoint5_8Output, E>

-export type Endpoint5_9Input = { readonly sessionID: Session.ID; readonly model: Model.Ref }
+export type Endpoint5_9Input = { readonly sessionID: Session.ID; readonly agent: Agent.ID }
 export type Endpoint5_9Output = void
-export type SessionSwitchModelOperation<E = never> = (input: Endpoint5_9Input) => Effect.Effect<Endpoint5_9Output, E>
+export type SessionSwitchAgentOperation<E = never> = (input: Endpoint5_9Input) => Effect.Effect<Endpoint5_9Output, E>

-export type Endpoint5_10Input = { readonly sessionID: Session.ID; readonly title: string }
+export type Endpoint5_10Input = { readonly sessionID: Session.ID; readonly model: Model.Ref }
 export type Endpoint5_10Output = void
-export type SessionRenameOperation<E = never> = (input: Endpoint5_10Input) => Effect.Effect<Endpoint5_10Output, E>
+export type SessionSwitchModelOperation<E = never> = (input: Endpoint5_10Input) => Effect.Effect<Endpoint5_10Output, E>

-export type Endpoint5_11Input = {
+export type Endpoint5_11Input = { readonly sessionID: Session.ID; readonly title: string }
+export type Endpoint5_11Output = void
+export type SessionRenameOperation<E = never> = (input: Endpoint5_11Input) => Effect.Effect<Endpoint5_11Output, E>
+
+export type Endpoint5_12Input = {
  readonly sessionID: Session.ID
  readonly directory: AbsolutePath
  readonly workspaceID?: Workspace.ID | undefined
  readonly delivery?: SessionInbox.Delivery | undefined
 }
-export type Endpoint5_11Output = void
-export type SessionMoveOperation<E = never> = (input: Endpoint5_11Input) => Effect.Effect<Endpoint5_11Output, E>
+export type Endpoint5_12Output = void
+export type SessionMoveOperation<E = never> = (input: Endpoint5_12Input) => Effect.Effect<Endpoint5_12Output, E>

-export type Endpoint5_12Input = {
+export type Endpoint5_13Input = {
  readonly sessionID: Session.ID
  readonly id?: SessionMessage.ID | undefined
  readonly text: string
@@ -179,10 +189,10 @@ export type Endpoint5_12Input = {
  readonly delivery?: SessionInbox.Delivery | undefined
  readonly resume?: boolean | undefined
 }
-export type Endpoint5_12Output = SessionInbox.User
-export type SessionPromptOperation<E = never> = (input: Endpoint5_12Input) => Effect.Effect<Endpoint5_12Output, E>
+export type Endpoint5_13Output = SessionInbox.User
+export type SessionPromptOperation<E = never> = (input: Endpoint5_13Input) => Effect.Effect<Endpoint5_13Output, E>

-export type Endpoint5_13Input = {
+export type Endpoint5_14Input = {
  readonly sessionID: Session.ID
  readonly id?: SessionMessage.ID | undefined
  readonly command: string
@@ -195,19 +205,19 @@ export type Endpoint5_13Input = {
  readonly delivery?: SessionInbox.Delivery | undefined
  readonly resume?: boolean | undefined
 }
-export type Endpoint5_13Output = SessionInbox.User
-export type SessionCommandOperation<E = never> = (input: Endpoint5_13Input) => Effect.Effect<Endpoint5_13Output, E>
+export type Endpoint5_14Output = SessionInbox.User
+export type SessionCommandOperation<E = never> = (input: Endpoint5_14Input) => Effect.Effect<Endpoint5_14Output, E>

-export type Endpoint5_14Input = {
+export type Endpoint5_15Input = {
  readonly sessionID: Session.ID
  readonly id?: SessionMessage.ID | undefined
  readonly skill: Skill.ID
  readonly resume?: boolean | undefined
 }
-export type Endpoint5_14Output = void
-export type SessionSkillOperation<E = never> = (input: Endpoint5_14Input) => Effect.Effect<Endpoint5_14Output, E>
+export type Endpoint5_15Output = void
+export type SessionSkillOperation<E = never> = (input: Endpoint5_15Input) => Effect.Effect<Endpoint5_15Output, E>

-export type Endpoint5_15Input = {
+export type Endpoint5_16Input = {
  readonly sessionID: Session.ID
  readonly id?: SessionMessage.ID | undefined
  readonly text: string
@@ -216,97 +226,98 @@ export type Endpoint5_15Input = {
  readonly delivery?: SessionInbox.Delivery | undefined
  readonly resume?: boolean | undefined
 }
-export type Endpoint5_15Output = SessionInbox.Synthetic
-export type SessionSyntheticOperation<E = never> = (input: Endpoint5_15Input) => Effect.Effect<Endpoint5_15Output, E>
+export type Endpoint5_16Output = SessionInbox.Synthetic
+export type SessionSyntheticOperation<E = never> = (input: Endpoint5_16Input) => Effect.Effect<Endpoint5_16Output, E>

-export type Endpoint5_16Input = {
+export type Endpoint5_17Input = {
  readonly sessionID: Session.ID
  readonly id?: Event.ID | undefined
  readonly command: string
 }
-export type Endpoint5_16Output = void
-export type SessionShellOperation<E = never> = (input: Endpoint5_16Input) => Effect.Effect<Endpoint5_16Output, E>
+export type Endpoint5_17Output = void
+export type SessionShellOperation<E = never> = (input: Endpoint5_17Input) => Effect.Effect<Endpoint5_17Output, E>

-export type Endpoint5_17Input = {
+export type Endpoint5_18Input = {
  readonly sessionID: Session.ID
  readonly id?: SessionMessage.ID | undefined
  readonly delivery?: SessionInbox.Delivery | undefined
 }
-export type Endpoint5_17Output = SessionInbox.Compaction
-export type SessionCompactOperation<E = never> = (input: Endpoint5_17Input) => Effect.Effect<Endpoint5_17Output, E>
+export type Endpoint5_18Output = SessionInbox.Compaction
+export type SessionCompactOperation<E = never> = (input: Endpoint5_18Input) => Effect.Effect<Endpoint5_18Output, E>

-export type Endpoint5_18Input = { readonly sessionID: Session.ID }
-export type Endpoint5_18Output = void
-export type SessionWaitOperation<E = never> = (input: Endpoint5_18Input) => Effect.Effect<Endpoint5_18Output, E>
+export type Endpoint5_19Input = { readonly sessionID: Session.ID }
+export type Endpoint5_19Output = void
+export type SessionWaitOperation<E = never> = (input: Endpoint5_19Input) => Effect.Effect<Endpoint5_19Output, E>

-export type Endpoint5_19Input = {
+export type Endpoint5_20Input = {
  readonly sessionID: Session.ID
  readonly messageID: SessionMessage.ID
  readonly files?: boolean | undefined
 }
-export type Endpoint5_19Output = Session.Revert
-export type SessionRevertStageOperation<E = never> = (input: Endpoint5_19Input) => Effect.Effect<Endpoint5_19Output, E>
-
-export type Endpoint5_20Input = { readonly sessionID: Session.ID }
-export type Endpoint5_20Output = void
-export type SessionRevertClearOperation<E = never> = (input: Endpoint5_20Input) => Effect.Effect<Endpoint5_20Output, E>
+export type Endpoint5_20Output = Session.Revert
+export type SessionRevertStageOperation<E = never> = (input: Endpoint5_20Input) => Effect.Effect<Endpoint5_20Output, E>

 export type Endpoint5_21Input = { readonly sessionID: Session.ID }
 export type Endpoint5_21Output = void
-export type SessionRevertCommitOperation<E = never> = (input: Endpoint5_21Input) => Effect.Effect<Endpoint5_21Output, E>
+export type SessionRevertClearOperation<E = never> = (input: Endpoint5_21Input) => Effect.Effect<Endpoint5_21Output, E>

 export type Endpoint5_22Input = { readonly sessionID: Session.ID }
-export type Endpoint5_22Output = ReadonlyArray<SessionMessage.Info>
-export type SessionContextOperation<E = never> = (input: Endpoint5_22Input) => Effect.Effect<Endpoint5_22Output, E>
+export type Endpoint5_22Output = void
+export type SessionRevertCommitOperation<E = never> = (input: Endpoint5_22Input) => Effect.Effect<Endpoint5_22Output, E>

 export type Endpoint5_23Input = { readonly sessionID: Session.ID }
-export type Endpoint5_23Output = ReadonlyArray<SessionInbox.Info>
-export type SessionInboxListOperation<E = never> = (input: Endpoint5_23Input) => Effect.Effect<Endpoint5_23Output, E>
+export type Endpoint5_23Output = ReadonlyArray<SessionMessage.Info>
+export type SessionContextOperation<E = never> = (input: Endpoint5_23Input) => Effect.Effect<Endpoint5_23Output, E>

-export type Endpoint5_24Input = { readonly sessionID: Session.ID; readonly inboxID: SessionMessage.ID }
-export type Endpoint5_24Output = void
-export type SessionInboxCancelOperation<E = never> = (input: Endpoint5_24Input) => Effect.Effect<Endpoint5_24Output, E>
+export type Endpoint5_24Input = { readonly sessionID: Session.ID }
+export type Endpoint5_24Output = ReadonlyArray<SessionInbox.Info>
+export type SessionInboxListOperation<E = never> = (input: Endpoint5_24Input) => Effect.Effect<Endpoint5_24Output, E>

 export type Endpoint5_25Input = { readonly sessionID: Session.ID; readonly inboxID: SessionMessage.ID }
 export type Endpoint5_25Output = void
-export type SessionInboxSteerOperation<E = never> = (input: Endpoint5_25Input) => Effect.Effect<Endpoint5_25Output, E>
+export type SessionInboxCancelOperation<E = never> = (input: Endpoint5_25Input) => Effect.Effect<Endpoint5_25Output, E>

 export type Endpoint5_26Input = { readonly sessionID: Session.ID; readonly inboxID: SessionMessage.ID }
 export type Endpoint5_26Output = void
-export type SessionInboxQueueOperation<E = never> = (input: Endpoint5_26Input) => Effect.Effect<Endpoint5_26Output, E>
+export type SessionInboxSteerOperation<E = never> = (input: Endpoint5_26Input) => Effect.Effect<Endpoint5_26Output, E>

-export type Endpoint5_27Input = { readonly sessionID: Session.ID }
-export type Endpoint5_27Output = ReadonlyArray<InstructionEntry.Info>
+export type Endpoint5_27Input = { readonly sessionID: Session.ID; readonly inboxID: SessionMessage.ID }
+export type Endpoint5_27Output = void
+export type SessionInboxQueueOperation<E = never> = (input: Endpoint5_27Input) => Effect.Effect<Endpoint5_27Output, E>
+
+export type Endpoint5_28Input = { readonly sessionID: Session.ID }
+export type Endpoint5_28Output = ReadonlyArray<InstructionEntry.Info>
 export type SessionInstructionsEntryListOperation<E = never> = (
-  input: Endpoint5_27Input,
-) => Effect.Effect<Endpoint5_27Output, E>
+  input: Endpoint5_28Input,
+) => Effect.Effect<Endpoint5_28Output, E>

-export type Endpoint5_28Input = {
+export type Endpoint5_29Input = {
  readonly sessionID: Session.ID
  readonly key: InstructionEntry.Key
  readonly value: Schema.Json
 }
-export type Endpoint5_28Output = void
-export type SessionInstructionsEntryPutOperation<E = never> = (
-  input: Endpoint5_28Input,
-) => Effect.Effect<Endpoint5_28Output, E>
-
-export type Endpoint5_29Input = { readonly sessionID: Session.ID; readonly key: InstructionEntry.Key }
 export type Endpoint5_29Output = void
-export type SessionInstructionsEntryRemoveOperation<E = never> = (
+export type SessionInstructionsEntryPutOperation<E = never> = (
  input: Endpoint5_29Input,
 ) => Effect.Effect<Endpoint5_29Output, E>

-export type Endpoint5_30Input = { readonly sessionID: Session.ID; readonly prompt: string }
-export type Endpoint5_30Output = { readonly text: string }
-export type SessionGenerateOperation<E = never> = (input: Endpoint5_30Input) => Effect.Effect<Endpoint5_30Output, E>
+export type Endpoint5_30Input = { readonly sessionID: Session.ID; readonly key: InstructionEntry.Key }
+export type Endpoint5_30Output = void
+export type SessionInstructionsEntryRemoveOperation<E = never> = (
+  input: Endpoint5_30Input,
+) => Effect.Effect<Endpoint5_30Output, E>

-export type Endpoint5_31Input = {
+export type Endpoint5_31Input = { readonly sessionID: Session.ID; readonly prompt: string }
+export type Endpoint5_31Output = { readonly text: string }
+export type SessionGenerateOperation<E = never> = (input: Endpoint5_31Input) => Effect.Effect<Endpoint5_31Output, E>
+
+export type Endpoint5_32Input = {
  readonly sessionID: Session.ID
  readonly after?: Event.Seq | undefined
  readonly follow?: boolean | undefined
+  readonly ephemeral?: boolean | undefined
 }
-export type Endpoint5_31Output =
+export type Endpoint5_32Output =
  | (
      | {
          readonly id: Event.ID
@@ -899,24 +910,101 @@ export type Endpoint5_31Output =
          }
        }
    )
+  | {
+      readonly id: Event.ID
+      readonly created: number
+      readonly metadata?: { readonly [x: string]: unknown } | undefined
+      readonly type: "session.usage.updated"
+      readonly location?: Location.Ref | undefined
+      readonly data: {
+        readonly sessionID: Session.ID
+        readonly cost: number & Brand.Brand<"Money.USD">
+        readonly tokens: {
+          readonly input: number
+          readonly output: number
+          readonly reasoning: number
+          readonly cache: { readonly read: number; readonly write: number }
+        }
+      }
+    }
+  | {
+      readonly id: Event.ID
+      readonly created: number
+      readonly metadata?: { readonly [x: string]: unknown } | undefined
+      readonly type: "session.text.delta"
+      readonly location?: Location.Ref | undefined
+      readonly data: {
+        readonly sessionID: Session.ID
+        readonly assistantMessageID: SessionMessage.ID
+        readonly ordinal: number
+        readonly delta: string
+      }
+    }
+  | {
+      readonly id: Event.ID
+      readonly created: number
+      readonly metadata?: { readonly [x: string]: unknown } | undefined
+      readonly type: "session.reasoning.delta"
+      readonly location?: Location.Ref | undefined
+      readonly data: {
+        readonly sessionID: Session.ID
+        readonly assistantMessageID: SessionMessage.ID
+        readonly ordinal: number
+        readonly delta: string
+      }
+    }
+  | {
+      readonly id: Event.ID
+      readonly created: number
+      readonly metadata?: { readonly [x: string]: unknown } | undefined
+      readonly type: "session.tool.input.delta"
+      readonly location?: Location.Ref | undefined
+      readonly data: {
+        readonly sessionID: Session.ID
+        readonly assistantMessageID: SessionMessage.ID
+        readonly id: string
+        readonly delta: string
+      }
+    }
+  | {
+      readonly id: Event.ID
+      readonly created: number
+      readonly metadata?: { readonly [x: string]: unknown } | undefined
+      readonly type: "session.tool.progress"
+      readonly location?: Location.Ref | undefined
+      readonly data: {
+        readonly sessionID: Session.ID
+        readonly assistantMessageID: SessionMessage.ID
+        readonly id: string
+        readonly metadata: { readonly [x: string]: Schema.Json }
+      }
+    }
+  | {
+      readonly id: Event.ID
+      readonly created: number
+      readonly metadata?: { readonly [x: string]: unknown } | undefined
+      readonly type: "session.compaction.delta"
+      readonly location?: Location.Ref | undefined
+      readonly data: { readonly sessionID: Session.ID; readonly text: string }
+    }
  | EventLog.Synced
-export type SessionLogOperation<E = never> = (input: Endpoint5_31Input) => Stream.Stream<Endpoint5_31Output, E>
+export type SessionLogOperation<E = never> = (input: Endpoint5_32Input) => Stream.Stream<Endpoint5_32Output, E>

-export type Endpoint5_32Input = { readonly sessionID: Session.ID; readonly continue?: boolean | undefined }
-export type Endpoint5_32Output = void
-export type SessionInterruptOperation<E = never> = (input: Endpoint5_32Input) => Effect.Effect<Endpoint5_32Output, E>
-
-export type Endpoint5_33Input = { readonly sessionID: Session.ID }
+export type Endpoint5_33Input = { readonly sessionID: Session.ID; readonly continue?: boolean | undefined }
 export type Endpoint5_33Output = void
-export type SessionBackgroundOperation<E = never> = (input: Endpoint5_33Input) => Effect.Effect<Endpoint5_33Output, E>
+export type SessionInterruptOperation<E = never> = (input: Endpoint5_33Input) => Effect.Effect<Endpoint5_33Output, E>

-export type Endpoint5_34Input = { readonly sessionID: Session.ID; readonly messageID: SessionMessage.ID }
-export type Endpoint5_34Output = SessionMessage.Info
-export type SessionMessageOperation<E = never> = (input: Endpoint5_34Input) => Effect.Effect<Endpoint5_34Output, E>
+export type Endpoint5_34Input = { readonly sessionID: Session.ID }
+export type Endpoint5_34Output = void
+export type SessionBackgroundOperation<E = never> = (input: Endpoint5_34Input) => Effect.Effect<Endpoint5_34Output, E>

-export type Endpoint5_35Input = { readonly sessionID: Session.ID; readonly variables: { readonly [x: string]: string } }
-export type Endpoint5_35Output = void
-export type SessionEnvironmentOperation<E = never> = (input: Endpoint5_35Input) => Effect.Effect<Endpoint5_35Output, E>
+export type Endpoint5_35Input = { readonly sessionID: Session.ID; readonly messageID: SessionMessage.ID }
+export type Endpoint5_35Output = SessionMessage.Info
+export type SessionMessageOperation<E = never> = (input: Endpoint5_35Input) => Effect.Effect<Endpoint5_35Output, E>
+
+export type Endpoint5_36Input = { readonly sessionID: Session.ID; readonly variables: { readonly [x: string]: string } }
+export type Endpoint5_36Output = void
+export type SessionEnvironmentOperation<E = never> = (input: Endpoint5_36Input) => Effect.Effect<Endpoint5_36Output, E>

 export interface SessionApi<E = never> {
  readonly list: SessionListOperation<E>
@@ -925,6 +1013,7 @@ export interface SessionApi<E = never> {
  readonly export: SessionExportOperation<E>
  readonly active: SessionActiveOperation<E>
  readonly get: SessionGetOperation<E>
+  readonly snapshot: SessionSnapshotOperation<E>
  readonly remove: SessionRemoveOperation<E>
  readonly fork: SessionForkOperation<E>
  readonly switchAgent: SessionSwitchAgentOperation<E>
@@ -86,6 +86,8 @@ import type {
  Endpoint5_34Output,
  Endpoint5_35Input,
  Endpoint5_35Output,
+  Endpoint5_36Input,
+  Endpoint5_36Output,
  Endpoint6_0Input,
  Endpoint6_0Output,
  Endpoint7_0Input,
@@ -350,48 +352,56 @@ const Endpoint5_5 = (raw: RawClient["server.session"]) => (input: Endpoint5_5Inp

 const Endpoint5_6 = (raw: RawClient["server.session"]) => (input: Endpoint5_6Input) =>
  preserveEffect<Endpoint5_6Output>()(
-    raw["session.remove"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
+    raw["session.snapshot"]({ params: { sessionID: input["sessionID"] }, query: { recent: input["recent"] } }).pipe(
+      Effect.mapError(mapClientError),
+      Effect.map((value) => value.data),
+    ),
  )

 const Endpoint5_7 = (raw: RawClient["server.session"]) => (input: Endpoint5_7Input) =>
  preserveEffect<Endpoint5_7Output>()(
+    raw["session.remove"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
+  )
+
+const Endpoint5_8 = (raw: RawClient["server.session"]) => (input: Endpoint5_8Input) =>
+  preserveEffect<Endpoint5_8Output>()(
    raw["session.fork"]({ params: { sessionID: input["sessionID"] }, payload: { boundary: input["boundary"] } }).pipe(
      Effect.mapError(mapClientError),
      Effect.map((value) => value.data),
    ),
  )

-const Endpoint5_8 = (raw: RawClient["server.session"]) => (input: Endpoint5_8Input) =>
-  preserveEffect<Endpoint5_8Output>()(
-    raw["session.switchAgent"]({ params: { sessionID: input["sessionID"] }, payload: { agent: input["agent"] } }).pipe(
-      Effect.mapError(mapClientError),
-    ),
-  )
-
 const Endpoint5_9 = (raw: RawClient["server.session"]) => (input: Endpoint5_9Input) =>
  preserveEffect<Endpoint5_9Output>()(
-    raw["session.switchModel"]({ params: { sessionID: input["sessionID"] }, payload: { model: input["model"] } }).pipe(
+    raw["session.switchAgent"]({ params: { sessionID: input["sessionID"] }, payload: { agent: input["agent"] } }).pipe(
      Effect.mapError(mapClientError),
    ),
  )

 const Endpoint5_10 = (raw: RawClient["server.session"]) => (input: Endpoint5_10Input) =>
  preserveEffect<Endpoint5_10Output>()(
-    raw["session.rename"]({ params: { sessionID: input["sessionID"] }, payload: { title: input["title"] } }).pipe(
+    raw["session.switchModel"]({ params: { sessionID: input["sessionID"] }, payload: { model: input["model"] } }).pipe(
      Effect.mapError(mapClientError),
    ),
  )

 const Endpoint5_11 = (raw: RawClient["server.session"]) => (input: Endpoint5_11Input) =>
  preserveEffect<Endpoint5_11Output>()(
+    raw["session.rename"]({ params: { sessionID: input["sessionID"] }, payload: { title: input["title"] } }).pipe(
+      Effect.mapError(mapClientError),
+    ),
+  )
+
+const Endpoint5_12 = (raw: RawClient["server.session"]) => (input: Endpoint5_12Input) =>
+  preserveEffect<Endpoint5_12Output>()(
    raw["session.move"]({
      params: { sessionID: input["sessionID"] },
      payload: { directory: input["directory"], workspaceID: input["workspaceID"], delivery: input["delivery"] },
    }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_12 = (raw: RawClient["server.session"]) => (input: Endpoint5_12Input) =>
-  preserveEffect<Endpoint5_12Output>()(
+const Endpoint5_13 = (raw: RawClient["server.session"]) => (input: Endpoint5_13Input) =>
+  preserveEffect<Endpoint5_13Output>()(
    raw["session.prompt"]({
      params: { sessionID: input["sessionID"] },
      payload: {
@@ -410,8 +420,8 @@ const Endpoint5_12 = (raw: RawClient["server.session"]) => (input: Endpoint5_12I
    ),
  )

-const Endpoint5_13 = (raw: RawClient["server.session"]) => (input: Endpoint5_13Input) =>
-  preserveEffect<Endpoint5_13Output>()(
+const Endpoint5_14 = (raw: RawClient["server.session"]) => (input: Endpoint5_14Input) =>
+  preserveEffect<Endpoint5_14Output>()(
    raw["session.command"]({
      params: { sessionID: input["sessionID"] },
      payload: {
@@ -432,16 +442,16 @@ const Endpoint5_13 = (raw: RawClient["server.session"]) => (input: Endpoint5_13I
    ),
  )

-const Endpoint5_14 = (raw: RawClient["server.session"]) => (input: Endpoint5_14Input) =>
-  preserveEffect<Endpoint5_14Output>()(
+const Endpoint5_15 = (raw: RawClient["server.session"]) => (input: Endpoint5_15Input) =>
+  preserveEffect<Endpoint5_15Output>()(
    raw["session.skill"]({
      params: { sessionID: input["sessionID"] },
      payload: { id: input["id"], skill: input["skill"], resume: input["resume"] },
    }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_15 = (raw: RawClient["server.session"]) => (input: Endpoint5_15Input) =>
-  preserveEffect<Endpoint5_15Output>()(
+const Endpoint5_16 = (raw: RawClient["server.session"]) => (input: Endpoint5_16Input) =>
+  preserveEffect<Endpoint5_16Output>()(
    raw["session.synthetic"]({
      params: { sessionID: input["sessionID"] },
      payload: {
@@ -458,16 +468,16 @@ const Endpoint5_15 = (raw: RawClient["server.session"]) => (input: Endpoint5_15I
    ),
  )

-const Endpoint5_16 = (raw: RawClient["server.session"]) => (input: Endpoint5_16Input) =>
-  preserveEffect<Endpoint5_16Output>()(
+const Endpoint5_17 = (raw: RawClient["server.session"]) => (input: Endpoint5_17Input) =>
+  preserveEffect<Endpoint5_17Output>()(
    raw["session.shell"]({
      params: { sessionID: input["sessionID"] },
      payload: { id: input["id"], command: input["command"] },
    }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_17 = (raw: RawClient["server.session"]) => (input: Endpoint5_17Input) =>
-  preserveEffect<Endpoint5_17Output>()(
+const Endpoint5_18 = (raw: RawClient["server.session"]) => (input: Endpoint5_18Input) =>
+  preserveEffect<Endpoint5_18Output>()(
    raw["session.compact"]({
      params: { sessionID: input["sessionID"] },
      payload: { id: input["id"], delivery: input["delivery"] },
@@ -477,13 +487,13 @@ const Endpoint5_17 = (raw: RawClient["server.session"]) => (input: Endpoint5_17I
    ),
  )

-const Endpoint5_18 = (raw: RawClient["server.session"]) => (input: Endpoint5_18Input) =>
-  preserveEffect<Endpoint5_18Output>()(
+const Endpoint5_19 = (raw: RawClient["server.session"]) => (input: Endpoint5_19Input) =>
+  preserveEffect<Endpoint5_19Output>()(
    raw["session.wait"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_19 = (raw: RawClient["server.session"]) => (input: Endpoint5_19Input) =>
-  preserveEffect<Endpoint5_19Output>()(
+const Endpoint5_20 = (raw: RawClient["server.session"]) => (input: Endpoint5_20Input) =>
+  preserveEffect<Endpoint5_20Output>()(
    raw["session.revert.stage"]({
      params: { sessionID: input["sessionID"] },
      payload: { messageID: input["messageID"], files: input["files"] },
@@ -493,27 +503,19 @@ const Endpoint5_19 = (raw: RawClient["server.session"]) => (input: Endpoint5_19I
    ),
  )

-const Endpoint5_20 = (raw: RawClient["server.session"]) => (input: Endpoint5_20Input) =>
-  preserveEffect<Endpoint5_20Output>()(
-    raw["session.revert.clear"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
-  )
-
 const Endpoint5_21 = (raw: RawClient["server.session"]) => (input: Endpoint5_21Input) =>
  preserveEffect<Endpoint5_21Output>()(
-    raw["session.revert.commit"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
+    raw["session.revert.clear"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
  )

 const Endpoint5_22 = (raw: RawClient["server.session"]) => (input: Endpoint5_22Input) =>
  preserveEffect<Endpoint5_22Output>()(
-    raw["session.context"]({ params: { sessionID: input["sessionID"] } }).pipe(
-      Effect.mapError(mapClientError),
-      Effect.map((value) => value.data),
-    ),
+    raw["session.revert.commit"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
  )

 const Endpoint5_23 = (raw: RawClient["server.session"]) => (input: Endpoint5_23Input) =>
  preserveEffect<Endpoint5_23Output>()(
-    raw["session.inbox.list"]({ params: { sessionID: input["sessionID"] } }).pipe(
+    raw["session.context"]({ params: { sessionID: input["sessionID"] } }).pipe(
      Effect.mapError(mapClientError),
      Effect.map((value) => value.data),
    ),
@@ -521,62 +523,70 @@ const Endpoint5_23 = (raw: RawClient["server.session"]) => (input: Endpoint5_23I

 const Endpoint5_24 = (raw: RawClient["server.session"]) => (input: Endpoint5_24Input) =>
  preserveEffect<Endpoint5_24Output>()(
-    raw["session.inbox.cancel"]({ params: { sessionID: input["sessionID"], inboxID: input["inboxID"] } }).pipe(
+    raw["session.inbox.list"]({ params: { sessionID: input["sessionID"] } }).pipe(
      Effect.mapError(mapClientError),
+      Effect.map((value) => value.data),
    ),
  )

 const Endpoint5_25 = (raw: RawClient["server.session"]) => (input: Endpoint5_25Input) =>
  preserveEffect<Endpoint5_25Output>()(
-    raw["session.inbox.steer"]({ params: { sessionID: input["sessionID"], inboxID: input["inboxID"] } }).pipe(
+    raw["session.inbox.cancel"]({ params: { sessionID: input["sessionID"], inboxID: input["inboxID"] } }).pipe(
      Effect.mapError(mapClientError),
    ),
  )

 const Endpoint5_26 = (raw: RawClient["server.session"]) => (input: Endpoint5_26Input) =>
  preserveEffect<Endpoint5_26Output>()(
-    raw["session.inbox.queue"]({ params: { sessionID: input["sessionID"], inboxID: input["inboxID"] } }).pipe(
+    raw["session.inbox.steer"]({ params: { sessionID: input["sessionID"], inboxID: input["inboxID"] } }).pipe(
      Effect.mapError(mapClientError),
    ),
  )

 const Endpoint5_27 = (raw: RawClient["server.session"]) => (input: Endpoint5_27Input) =>
  preserveEffect<Endpoint5_27Output>()(
+    raw["session.inbox.queue"]({ params: { sessionID: input["sessionID"], inboxID: input["inboxID"] } }).pipe(
+      Effect.mapError(mapClientError),
+    ),
+  )
+
+const Endpoint5_28 = (raw: RawClient["server.session"]) => (input: Endpoint5_28Input) =>
+  preserveEffect<Endpoint5_28Output>()(
    raw["session.instructions.entry.list"]({ params: { sessionID: input["sessionID"] } }).pipe(
      Effect.mapError(mapClientError),
      Effect.map((value) => value.data),
    ),
  )

-const Endpoint5_28 = (raw: RawClient["server.session"]) => (input: Endpoint5_28Input) =>
-  preserveEffect<Endpoint5_28Output>()(
+const Endpoint5_29 = (raw: RawClient["server.session"]) => (input: Endpoint5_29Input) =>
+  preserveEffect<Endpoint5_29Output>()(
    raw["session.instructions.entry.put"]({
      params: { sessionID: input["sessionID"], key: input["key"] },
      payload: { value: input["value"] },
    }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_29 = (raw: RawClient["server.session"]) => (input: Endpoint5_29Input) =>
-  preserveEffect<Endpoint5_29Output>()(
+const Endpoint5_30 = (raw: RawClient["server.session"]) => (input: Endpoint5_30Input) =>
+  preserveEffect<Endpoint5_30Output>()(
    raw["session.instructions.entry.remove"]({ params: { sessionID: input["sessionID"], key: input["key"] } }).pipe(
      Effect.mapError(mapClientError),
    ),
  )

-const Endpoint5_30 = (raw: RawClient["server.session"]) => (input: Endpoint5_30Input) =>
-  preserveEffect<Endpoint5_30Output>()(
+const Endpoint5_31 = (raw: RawClient["server.session"]) => (input: Endpoint5_31Input) =>
+  preserveEffect<Endpoint5_31Output>()(
    raw["session.generate"]({ params: { sessionID: input["sessionID"] }, payload: { prompt: input["prompt"] } }).pipe(
      Effect.mapError(mapClientError),
      Effect.map((value) => value.data),
    ),
  )

-const Endpoint5_31 = (raw: RawClient["server.session"]) => (input: Endpoint5_31Input) =>
-  preserveStream<Endpoint5_31Output>()(
+const Endpoint5_32 = (raw: RawClient["server.session"]) => (input: Endpoint5_32Input) =>
+  preserveStream<Endpoint5_32Output>()(
    Stream.unwrap(
      raw["session.log"]({
        params: { sessionID: input["sessionID"] },
-        query: { after: input["after"], follow: input["follow"] },
+        query: { after: input["after"], follow: input["follow"], ephemeral: input["ephemeral"] },
      }).pipe(
        Effect.mapError(mapClientError),
        Effect.map((stream) => stream.pipe(Stream.mapError(mapClientError))),
@@ -584,29 +594,29 @@ const Endpoint5_31 = (raw: RawClient["server.session"]) => (input: Endpoint5_31I
    ),
  )

-const Endpoint5_32 = (raw: RawClient["server.session"]) => (input: Endpoint5_32Input) =>
-  preserveEffect<Endpoint5_32Output>()(
+const Endpoint5_33 = (raw: RawClient["server.session"]) => (input: Endpoint5_33Input) =>
+  preserveEffect<Endpoint5_33Output>()(
    raw["session.interrupt"]({
      params: { sessionID: input["sessionID"] },
      query: { continue: input["continue"] },
    }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_33 = (raw: RawClient["server.session"]) => (input: Endpoint5_33Input) =>
-  preserveEffect<Endpoint5_33Output>()(
+const Endpoint5_34 = (raw: RawClient["server.session"]) => (input: Endpoint5_34Input) =>
+  preserveEffect<Endpoint5_34Output>()(
    raw["session.background"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError)),
  )

-const Endpoint5_34 = (raw: RawClient["server.session"]) => (input: Endpoint5_34Input) =>
-  preserveEffect<Endpoint5_34Output>()(
+const Endpoint5_35 = (raw: RawClient["server.session"]) => (input: Endpoint5_35Input) =>
+  preserveEffect<Endpoint5_35Output>()(
    raw["session.message"]({ params: { sessionID: input["sessionID"], messageID: input["messageID"] } }).pipe(
      Effect.mapError(mapClientError),
      Effect.map((value) => value.data),
    ),
  )

-const Endpoint5_35 = (raw: RawClient["server.session"]) => (input: Endpoint5_35Input) =>
-  preserveEffect<Endpoint5_35Output>()(
+const Endpoint5_36 = (raw: RawClient["server.session"]) => (input: Endpoint5_36Input) =>
+  preserveEffect<Endpoint5_36Output>()(
    raw["session.environment"]({
      params: { sessionID: input["sessionID"] },
      payload: { variables: input["variables"] },
@@ -620,29 +630,30 @@ const adaptGroup5 = (raw: RawClient["server.session"]) => ({
  export: Endpoint5_3(raw),
  active: Endpoint5_4(raw),
  get: Endpoint5_5(raw),
-  remove: Endpoint5_6(raw),
-  fork: Endpoint5_7(raw),
-  switchAgent: Endpoint5_8(raw),
-  switchModel: Endpoint5_9(raw),
-  rename: Endpoint5_10(raw),
-  move: Endpoint5_11(raw),
-  prompt: Endpoint5_12(raw),
-  command: Endpoint5_13(raw),
-  skill: Endpoint5_14(raw),
-  synthetic: Endpoint5_15(raw),
-  shell: Endpoint5_16(raw),
-  compact: Endpoint5_17(raw),
-  wait: Endpoint5_18(raw),
-  revert: { stage: Endpoint5_19(raw), clear: Endpoint5_20(raw), commit: Endpoint5_21(raw) },
-  context: Endpoint5_22(raw),
-  inbox: { list: Endpoint5_23(raw), cancel: Endpoint5_24(raw), steer: Endpoint5_25(raw), queue: Endpoint5_26(raw) },
-  instructions: { entry: { list: Endpoint5_27(raw), put: Endpoint5_28(raw), remove: Endpoint5_29(raw) } },
-  generate: Endpoint5_30(raw),
-  log: Endpoint5_31(raw),
-  interrupt: Endpoint5_32(raw),
-  background: Endpoint5_33(raw),
-  message: Endpoint5_34(raw),
-  environment: Endpoint5_35(raw),
+  snapshot: Endpoint5_6(raw),
+  remove: Endpoint5_7(raw),
+  fork: Endpoint5_8(raw),
+  switchAgent: Endpoint5_9(raw),
+  switchModel: Endpoint5_10(raw),
+  rename: Endpoint5_11(raw),
+  move: Endpoint5_12(raw),
+  prompt: Endpoint5_13(raw),
+  command: Endpoint5_14(raw),
+  skill: Endpoint5_15(raw),
+  synthetic: Endpoint5_16(raw),
+  shell: Endpoint5_17(raw),
+  compact: Endpoint5_18(raw),
+  wait: Endpoint5_19(raw),
+  revert: { stage: Endpoint5_20(raw), clear: Endpoint5_21(raw), commit: Endpoint5_22(raw) },
+  context: Endpoint5_23(raw),
+  inbox: { list: Endpoint5_24(raw), cancel: Endpoint5_25(raw), steer: Endpoint5_26(raw), queue: Endpoint5_27(raw) },
+  instructions: { entry: { list: Endpoint5_28(raw), put: Endpoint5_29(raw), remove: Endpoint5_30(raw) } },
+  generate: Endpoint5_31(raw),
+  log: Endpoint5_32(raw),
+  interrupt: Endpoint5_33(raw),
+  background: Endpoint5_34(raw),
+  message: Endpoint5_35(raw),
+  environment: Endpoint5_36(raw),
 })

 const Endpoint6_0 = (raw: RawClient["server.message"]) => (input: Endpoint6_0Input) =>
@@ -20,6 +20,8 @@ import type {
  SessionActiveOutput,
  SessionGetInput,
  SessionGetOutput,
+  SessionSnapshotInput,
+  SessionSnapshotOutput,
  SessionRemoveInput,
  SessionRemoveOutput,
  SessionForkInput,
@@ -514,6 +516,18 @@ export function make(options: ClientOptions) {
          },
          requestOptions,
        ).then((value) => value.data),
+      snapshot: (input: SessionSnapshotInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionSnapshotOutput }>(
+          {
+            method: "GET",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/snapshot`,
+            query: { recent: input["recent"] },
+            successStatus: 200,
+            declaredStatuses: [404, 500, 401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
      remove: (input: SessionRemoveInput, requestOptions?: RequestOptions) =>
        request<SessionRemoveOutput>(
          {
@@ -843,9 +857,9 @@ export function make(options: ClientOptions) {
          {
            method: "GET",
            path: `/api/experimental/session/${encodeURIComponent(input.sessionID)}/log`,
-            query: { after: input["after"], follow: input["follow"] },
+            query: { after: input["after"], follow: input["follow"], ephemeral: input["ephemeral"] },
            successStatus: 200,
-            declaredStatuses: [404, 401, 400],
+            declaredStatuses: [404, 409, 401, 400],
            empty: false,
          },
          requestOptions,
@@ -30,8 +30,6 @@ export type FileDiffInfo = {
  status: "added" | "deleted" | "modified"
 }

-export type PromptCommandInvocation = { name: string; arguments: string }
-
 export type PromptBase64 = string

 export type PromptFileSource = { type: "inline" } | { type: "uri"; uri: string }
@@ -514,51 +512,6 @@ export type SessionRevertCommitted = {
  data: { sessionID: string; to: string }
 }

-export type ModelsDevRefreshed = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "models-dev.refreshed"
-  location?: LocationRef
-  data: {}
-}
-
-export type IntegrationUpdated = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "integration.updated"
-  location?: LocationRef
-  data: {}
-}
-
-export type IntegrationConnectionUpdated = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "integration.connection.updated"
-  location?: LocationRef
-  data: { integrationID: string }
-}
-
-export type CatalogUpdated = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "catalog.updated"
-  location?: LocationRef
-  data: {}
-}
-
-export type AgentUpdated = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "agent.updated"
-  location?: LocationRef
-  data: {}
-}
-
 export type SessionTextDelta = {
  id: string
  created: number
@@ -604,6 +557,51 @@ export type SessionCompactionDelta = {
  data: { sessionID: string; text: string }
 }

+export type ModelsDevRefreshed = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "models-dev.refreshed"
+  location?: LocationRef
+  data: {}
+}
+
+export type IntegrationUpdated = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "integration.updated"
+  location?: LocationRef
+  data: {}
+}
+
+export type IntegrationConnectionUpdated = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "integration.connection.updated"
+  location?: LocationRef
+  data: { integrationID: string }
+}
+
+export type CatalogUpdated = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "catalog.updated"
+  location?: LocationRef
+  data: {}
+}
+
+export type AgentUpdated = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "agent.updated"
+  location?: LocationRef
+  data: {}
+}
+
 export type FilesystemChanged = {
  id: string
  created: number
@@ -1686,7 +1684,6 @@ export type SessionMessageUser = {
  metadata?: { [x: string]: JsonValue }
  time: { created: number }
  text: string
-  command?: PromptCommandInvocation
  files?: Array<PromptFileAttachment>
  agents?: Array<PromptAgentAttachment>
  skills?: Array<PromptSkillAttachment>
@@ -1695,7 +1692,6 @@ export type SessionMessageUser = {

 export type SessionInboxUserPayload = {
  text: string
-  command?: PromptCommandInvocation
  files?: Array<PromptFileAttachment>
  agents?: Array<PromptAgentAttachment>
  skills?: Array<PromptSkillAttachment>
@@ -1704,7 +1700,6 @@ export type SessionInboxUserPayload = {

 export type SessionInboxUserPayload1 = {
  text: string
-  command?: PromptCommandInvocation
  files?: Array<PromptFileAttachment>
  agents?: Array<PromptAgentAttachment>
  skills?: Array<PromptSkillAttachment>
@@ -2006,7 +2001,15 @@ export type FormCreated = {
  data: { form: FormInfo1 }
 }

-export type SessionLogItem = SessionEventDurable | EventLogSynced
+export type SessionLogItem =
+  | SessionEventDurable
+  | SessionUsageUpdated
+  | SessionTextDelta
+  | SessionReasoningDelta
+  | SessionToolInputDelta
+  | SessionToolProgress
+  | SessionCompactionDelta
+  | EventLogSynced

 export type IntegrationOAuthMethod = { id: string; type: "oauth"; label: string; form?: FormFields }

@@ -2016,6 +2019,16 @@ export type FormInfo = { id: string; sessionID: string; title: string; metadata?

 export type SessionTransferData = { info: SessionInfo; messages: Array<SessionMessageInfo> }

+export type SessionSnapshotResponse = {
+  data: {
+    session: SessionInfo
+    children: Array<SessionInfo>
+    inbox: Array<SessionInboxInfo>
+    messages: Array<SessionMessageInfo>
+    seq: number
+  }
+}
+
 export type SessionMessagesResponse = {
  data: Array<SessionMessageInfo>
  cursor: { previous?: string | null; next?: string | null }
@@ -2230,6 +2243,16 @@ export const isInstructionEntryValueTooLargeError = (value: unknown): value is I
  "_tag" in value &&
  value["_tag"] === "InstructionEntryValueTooLargeError"

+export type SeqUnavailableError = {
+  readonly _tag: "SeqUnavailableError"
+  readonly sessionID: string
+  readonly after: number
+  readonly head?: number | undefined
+  readonly message: string
+}
+export const isSeqUnavailableError = (value: unknown): value is SeqUnavailableError =>
+  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SeqUnavailableError"
+
 export type ProviderNotFoundError = {
  readonly _tag: "ProviderNotFoundError"
  readonly providerID: string
@@ -2557,7 +2580,6 @@ export type SessionImportInput = {
          readonly metadata?: { readonly [x: string]: JsonValue }
          readonly time: { readonly created: number }
          readonly text: string
-          readonly command?: { readonly name: string; readonly arguments: string }
          readonly files?: ReadonlyArray<{
            readonly data: string
            readonly mime: string
@@ -2827,7 +2849,6 @@ export type SessionImportInput = {
          readonly metadata?: { readonly [x: string]: JsonValue }
          readonly time: { readonly created: number }
          readonly text: string
-          readonly command?: { readonly name: string; readonly arguments: string }
          readonly files?: ReadonlyArray<{
            readonly data: string
            readonly mime: string
@@ -3097,7 +3118,6 @@ export type SessionImportInput = {
          readonly metadata?: { readonly [x: string]: JsonValue }
          readonly time: { readonly created: number }
          readonly text: string
-          readonly command?: { readonly name: string; readonly arguments: string }
          readonly files?: ReadonlyArray<{
            readonly data: string
            readonly mime: string
@@ -3311,6 +3331,13 @@ export type SessionGetInput = { readonly sessionID: { readonly sessionID: string

 export type SessionGetOutput = { data: SessionInfo }["data"]

+export type SessionSnapshotInput = {
+  readonly sessionID: { readonly sessionID: string }["sessionID"]
+  readonly recent?: { readonly recent?: number | undefined }["recent"]
+}
+
+export type SessionSnapshotOutput = SessionSnapshotResponse["data"]
+
 export type SessionRemoveInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }

 export type SessionRemoveOutput = void
@@ -3949,8 +3976,21 @@ export type SessionGenerateOutput = SessionGenerateResponse["data"]

 export type SessionLogInput = {
  readonly sessionID: { readonly sessionID: string }["sessionID"]
-  readonly after?: { readonly after?: number | undefined; readonly follow?: boolean | undefined }["after"]
-  readonly follow?: { readonly after?: number | undefined; readonly follow?: boolean | undefined }["follow"]
+  readonly after?: {
+    readonly after?: number | undefined
+    readonly follow?: boolean | undefined
+    readonly ephemeral?: boolean | undefined
+  }["after"]
+  readonly follow?: {
+    readonly after?: number | undefined
+    readonly follow?: boolean | undefined
+    readonly ephemeral?: boolean | undefined
+  }["follow"]
+  readonly ephemeral?: {
+    readonly after?: number | undefined
+    readonly follow?: boolean | undefined
+    readonly ephemeral?: boolean | undefined
+  }["ephemeral"]
 }

 export type SessionLogOutput = SessionLogItem
@@ -0,0 +1,248 @@
+import { batch, createSignal, onCleanup, untrack } from "solid-js"
+import type { Signal } from "solid-js"
+import type { OpenCodeClient, OpenCodeEvent, SessionPromptInput } from "../promise"
+import { isSeqUnavailableError } from "../promise"
+import { createData } from "./data"
+import type { CreateDataInput } from "./data"
+import { Engine } from "./engine/engine"
+
+type SessionApi = Pick<OpenCodeClient["session"], "snapshot" | "log" | "prompt">
+
+// The legacy layer reconciles handed-off values into its own store, mutating
+// them in place — so anything shared with it must be a copy, never engine
+// state. Engine data is plain JSON, so a recursive copy suffices.
+function clone<T>(value: T): T {
+  if (value === null || typeof value !== "object") return value
+  if (Array.isArray(value)) return value.map(clone) as T
+  const copy: Record<string, unknown> = {}
+  for (const key in value) copy[key] = clone(value[key as keyof T])
+  return copy as T
+}
+
+const ambientSessionEvents = new Set<OpenCodeEvent["type"]>([
+  "session.created",
+  "session.deleted",
+  "session.renamed",
+  "session.execution.started",
+  "session.execution.succeeded",
+  "session.execution.failed",
+  "session.execution.interrupted",
+])
+
+/** How many recent messages a session snapshot fetch requests. */
+export const SNAPSHOT_RECENT = 200
+
+export function createEngineTransport(api: () => SessionApi): Engine.SessionTransport {
+  return {
+    snapshot(sessionID) {
+      return api().snapshot({ sessionID, recent: SNAPSHOT_RECENT })
+    },
+    async *stream(sessionID, after, signal) {
+      try {
+        for await (const item of api().log(
+          { sessionID, after, follow: true, ephemeral: true },
+          signal ? { signal } : undefined,
+        )) {
+          if (item.type !== "session.forked") yield item
+        }
+      } catch (error) {
+        if (isSeqUnavailableError(error)) throw new Engine.SeqUnavailable()
+        throw error
+      }
+    },
+    async submit(input) {
+      try {
+        await api().prompt({ ...input.request, sessionID: input.sessionID, id: input.id })
+      } catch (error) {
+        if (isTypedError(error)) throw new Engine.SubmitRejected(error.message)
+        throw error
+      }
+    },
+  }
+}
+
+export function createEngineData(config: CreateDataInput) {
+  const legacy = createData({
+    ...config,
+    event: {
+      on: config.event.on,
+      listen(handler) {
+        return config.event.listen((event) => {
+          if (event.name.startsWith("session.") && !ambientSessionEvents.has(event.name)) return
+          handler(event)
+        })
+      },
+    },
+  })
+  const engines = new Map<string, Promise<Engine.SessionEngine>>()
+  const families = new Set<string>()
+  const invalidated = new Set<string>()
+  const failures = new Set<(failure: Engine.IntentFailure) => void>()
+  const cleanups = new Set<() => void>()
+  const transport = createEngineTransport(() => config.api().session)
+  let connected = false
+
+  // One signal per session holding the engine's immutable view. The fold is a
+  // persistent structure — unchanged subtrees keep their object identity
+  // across publishes — so keyed consumers get row stability from reference
+  // equality, and the engine's publish guard already drops identity-unchanged
+  // views. Reactivity is per session: any change to a session's view re-runs
+  // that session's readers.
+  const signals = new Map<string, Signal<Engine.SessionView | undefined>>()
+  const viewSignal = (sessionID: string) => {
+    const existing = signals.get(sessionID)
+    if (existing) return existing
+    const created = createSignal<Engine.SessionView | undefined>(undefined)
+    signals.set(sessionID, created)
+    return created
+  }
+  const view = (sessionID: string) => viewSignal(sessionID)[0]()
+
+  const update = (sessionID: string, next: Engine.SessionView) => {
+    const [read, write] = viewSignal(sessionID)
+    const previous = untrack(read)
+    batch(() => {
+      write(next)
+      if (next.session !== previous?.session) {
+        const current = legacy.session.get(sessionID)
+        if (!current || current.time.updated <= next.session.time.updated) {
+          legacy.session.remember(clone(next.session))
+        }
+      }
+      if (families.has(sessionID) && next.children !== previous?.children) {
+        next.children.forEach((child) => legacy.session.remember(clone(child)))
+      }
+    })
+  }
+
+  const ensure = (sessionID: string) => {
+    const existing = engines.get(sessionID)
+    if (existing) return existing
+    const created = Engine.createSessionEngine(sessionID, transport).then((engine) => {
+      update(sessionID, engine.view())
+      cleanups.add(engine.subscribe((view) => update(sessionID, view)))
+      cleanups.add(engine.subscribeFailures((failure) => failures.forEach((listener) => listener(failure))))
+      return engine
+    })
+    engines.set(sessionID, created)
+    void created.catch(() => engines.delete(sessionID))
+    return created
+  }
+
+  const sync = async (sessionID: string) => {
+    const engine = await ensure(sessionID)
+    if (invalidated.delete(sessionID)) await engine.refresh()
+    await engine.ready()
+  }
+
+  cleanups.add(
+    config.event.on("server.connected", () => {
+      if (!connected) {
+        connected = true
+        return
+      }
+      engines.forEach((engine) => void engine.then((handle) => handle.refresh()).catch(() => undefined))
+    }),
+  )
+
+  onCleanup(() => {
+    cleanups.forEach((cleanup) => cleanup())
+    engines.forEach((engine) => void engine.then((handle) => handle.stop()))
+  })
+
+  return {
+    ...legacy,
+    on: config.event.on,
+    listen: config.event.listen,
+    session: {
+      ...legacy.session,
+      async sync(sessionID: string, options?: { readonly children?: boolean }) {
+        if (options?.children) families.add(sessionID)
+        await sync(sessionID)
+        if (!options?.children) return
+        view(sessionID)?.children.forEach((child) => legacy.session.remember(clone(child)))
+      },
+      invalidate(sessionID: string) {
+        invalidated.add(sessionID)
+      },
+      status(sessionID: string) {
+        if (view(sessionID)?.active === "running") return "running"
+        return legacy.session.status(sessionID)
+      },
+      input: {
+        list(sessionID: string) {
+          return (
+            view(sessionID)
+              ?.pending.filter((item) => item.type !== "compaction")
+              .map((item) => item.id) ?? legacy.session.input.list(sessionID)
+          )
+        },
+        has(sessionID: string, inboxID: string) {
+          return (
+            view(sessionID)?.pending.some((item) => item.type !== "compaction" && item.id === inboxID) ??
+            legacy.session.input.has(sessionID, inboxID)
+          )
+        },
+      },
+      pending: {
+        list(sessionID: string) {
+          void ensure(sessionID)
+          return [...(view(sessionID)?.pending ?? [])]
+        },
+        sync(sessionID: string) {
+          return sync(sessionID)
+        },
+        invalidate(sessionID: string) {
+          invalidated.add(sessionID)
+        },
+      },
+      message: {
+        list(sessionID: string) {
+          void ensure(sessionID)
+          return [...(view(sessionID)?.messages ?? [])]
+        },
+        get(sessionID: string, messageID: string) {
+          void ensure(sessionID)
+          return view(sessionID)?.messages.find((message) => message.id === messageID)
+        },
+        sync(sessionID: string) {
+          return sync(sessionID)
+        },
+        invalidate(sessionID: string) {
+          invalidated.add(sessionID)
+        },
+      },
+      async prompt(input: SessionPromptInput) {
+        return (await ensure(input.sessionID)).submit({
+          id: input.id ?? undefined,
+          text: input.text,
+          files: input.files,
+          agents: input.agents,
+          skills: input.skills,
+          metadata: input.metadata,
+          delivery: input.delivery,
+          resume: input.resume,
+        })
+      },
+      failures: {
+        listen(listener: (failure: Engine.IntentFailure) => void) {
+          failures.add(listener)
+          return () => failures.delete(listener)
+        },
+      },
+    },
+  }
+}
+
+function isTypedError(error: unknown): error is { readonly _tag: string; readonly message: string } {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "_tag" in error &&
+    typeof error._tag === "string" &&
+    "message" in error &&
+    typeof error.message === "string"
+  )
+}
+
+export type EngineData = ReturnType<typeof createEngineData>
@@ -0,0 +1,498 @@
+import type {
+  EventLogSynced,
+  SessionCompactionDelta,
+  SessionInboxInfo,
+  SessionInboxItem,
+  SessionMessageInfo,
+  SessionPromptInput,
+  SessionReasoningDelta,
+  SessionTextDelta,
+  SessionToolInputDelta,
+  SessionToolProgress,
+  SessionUsageUpdated,
+} from "../../promise"
+import { SessionFold } from "./fold"
+import type { DurableSessionEvent, SessionFoldState, SessionSnapshot } from "./fold"
+
+export type EphemeralSessionEvent =
+  | SessionTextDelta
+  | SessionReasoningDelta
+  | SessionToolInputDelta
+  | SessionToolProgress
+  | SessionCompactionDelta
+  | SessionUsageUpdated
+
+export type SessionStreamItem = DurableSessionEvent | EphemeralSessionEvent | EventLogSynced
+
+export type Intent = {
+  readonly id: string
+  readonly item: Extract<SessionInboxItem, { readonly type: "user" | "synthetic" }>
+  readonly request: Omit<SessionPromptInput, "sessionID" | "id">
+  readonly created: number
+}
+
+export type SubmitInput = {
+  readonly id: string
+  readonly sessionID: string
+  readonly request: Intent["request"]
+}
+
+export type IntentFailure = {
+  readonly intent: Intent
+  readonly reason: string
+}
+
+export class SubmitRejected extends Error {
+  readonly _tag = "SubmitRejected"
+
+  constructor(readonly reason: string) {
+    super(reason)
+  }
+}
+
+export class SeqUnavailable extends Error {
+  readonly _tag = "SeqUnavailable"
+}
+
+export interface SessionTransport {
+  readonly snapshot: (sessionID: string) => Promise<SessionSnapshot>
+  readonly stream: (sessionID: string, after: number, signal?: AbortSignal) => AsyncIterable<SessionStreamItem>
+  readonly submit: (input: SubmitInput) => Promise<void>
+}
+
+export type SessionView = SessionFoldState & {
+  readonly pending: ReadonlyArray<SessionInboxInfo>
+}
+
+export interface SessionEngine {
+  readonly sessionID: string
+  readonly view: () => SessionView
+  readonly submit: (input: Intent["request"] & { readonly id?: string }) => Intent
+  readonly subscribe: (listener: (view: SessionView) => void) => () => void
+  readonly subscribeFailures: (listener: (failure: IntentFailure) => void) => () => void
+  readonly ready: () => Promise<void>
+  readonly refresh: () => Promise<void>
+  readonly settled: () => Promise<void>
+  readonly stop: () => void
+}
+
+export type SessionEngineOptions = {
+  readonly makeID?: () => string
+  readonly now?: () => number
+  readonly reconnect?: () => Promise<void>
+}
+
+type Overlay = ReadonlyMap<string, OverlayEntry>
+
+type OverlayEntry =
+  | { readonly type: "text"; readonly value: string }
+  | { readonly type: "reasoning"; readonly value: string }
+  | { readonly type: "tool-input"; readonly value: string }
+  | { readonly type: "tool-progress"; readonly metadata: SessionToolProgress["data"]["metadata"] }
+  | { readonly type: "compaction"; readonly value: string }
+  | { readonly type: "usage"; readonly value: SessionUsageUpdated["data"] }
+
+type EngineState = {
+  readonly folded: SessionFoldState
+  readonly outbox: ReadonlyArray<Intent>
+  readonly overlay: Overlay
+  readonly synced: boolean
+}
+
+export async function createSessionEngine(
+  sessionID: string,
+  transport: SessionTransport,
+  options: SessionEngineOptions = {},
+): Promise<SessionEngine> {
+  let counter = 0
+  const makeID = options.makeID ?? (() => `msg_${Date.now().toString(36)}_${++counter}`)
+  const now = options.now ?? Date.now
+  const reconnect = options.reconnect ?? (() => new Promise<void>((resolve) => setTimeout(resolve, 100)))
+  let state: EngineState = {
+    folded: SessionFold.fromSnapshot(await transport.snapshot(sessionID)),
+    outbox: [],
+    overlay: new Map(),
+    synced: false,
+  }
+  const listeners = new Set<(view: SessionView) => void>()
+  const failureListeners = new Set<(failure: IntentFailure) => void>()
+  const settled = new Set<() => void>()
+  const ready = Promise.withResolvers<void>()
+  let sent: string | undefined
+  let stopped = false
+  let sending = false
+  let refreshing: Promise<void> | undefined
+  const abort = new AbortController()
+
+  const publish = (next: EngineState) => {
+    const previous = state
+    state = next
+    // Views derive from folded/outbox/overlay only, so synced flips and stale
+    // replays (where the fold returns its input) need no render or notify.
+    if (next.folded !== previous.folded || next.outbox !== previous.outbox || next.overlay !== previous.overlay) {
+      const view = render(state)
+      listeners.forEach((listener) => listener(view))
+    }
+    if (state.outbox.length > 0) return
+    settled.forEach((resolve) => resolve())
+    settled.clear()
+  }
+
+  const applySnapshot = (snapshot: SessionSnapshot, synced = false) => {
+    const folded = SessionFold.fromSnapshot(snapshot)
+    const acknowledged = new Set([
+      ...folded.messages.map((message) => message.id),
+      ...folded.inbox.map((item) => item.id),
+    ])
+    publish({
+      folded,
+      outbox: state.outbox.filter((intent) => !acknowledged.has(intent.id)),
+      overlay: new Map(),
+      synced,
+    })
+  }
+
+  const applyDurable = (event: DurableSessionEvent) => {
+    if (event.type === "session.inbox.enqueued" && sent === event.data.inboxID) sent = undefined
+    publish({
+      folded: SessionFold.apply(state.folded, event),
+      outbox:
+        event.type === "session.inbox.enqueued"
+          ? state.outbox.filter((intent) => intent.id !== event.data.inboxID)
+          : state.outbox,
+      overlay: clearOverlay(state.overlay, event),
+      synced: state.synced,
+    })
+    send()
+  }
+
+  const reject = (intent: Intent, reason: string) => {
+    publish({ ...state, outbox: state.outbox.filter((item) => item.id !== intent.id) })
+    failureListeners.forEach((listener) => listener({ intent, reason }))
+  }
+
+  const send = () => {
+    if (!state.synced || sending || stopped) return
+    const intent = state.outbox[0]
+    if (!intent || sent === intent.id) return
+    sending = true
+    sent = intent.id
+    void (async () => {
+      try {
+        await transport.submit({ id: intent.id, sessionID, request: intent.request })
+      } catch (error) {
+        if (!(error instanceof SubmitRejected)) return
+        sent = undefined
+        reject(intent, error.reason)
+      }
+    })().finally(() => {
+      sending = false
+      send()
+    })
+  }
+
+  const sync = async () => {
+    while (!stopped) {
+      try {
+        for await (const item of transport.stream(sessionID, state.folded.seq, abort.signal)) {
+          if (stopped) return
+          if (item.type === "log.synced") {
+            // A marker past the fold means the server skipped events it could not
+            // replay for this cursor; recover through a fresh snapshot.
+            if (item.seq !== undefined && item.seq > state.folded.seq) throw new SeqUnavailable()
+            sent = undefined
+            publish({ ...state, synced: true })
+            ready.resolve()
+            send()
+            continue
+          }
+          if ("durable" in item) {
+            applyDurable(item)
+            continue
+          }
+          publish({ ...state, overlay: applyOverlay(state.overlay, item) })
+        }
+      } catch (error) {
+        if (error instanceof SeqUnavailable) {
+          try {
+            applySnapshot(await transport.snapshot(sessionID))
+          } catch {
+            await reconnect()
+          }
+          continue
+        }
+      }
+      if (stopped) return
+      publish({ ...state, synced: false })
+      await reconnect()
+    }
+  }
+
+  void sync()
+
+  return {
+    sessionID,
+    view: () => render(state),
+    submit(input) {
+      const intent: Intent = {
+        id: input.id ?? makeID(),
+        created: now(),
+        request: input,
+        item: {
+          type: "user",
+          delivery: input.delivery ?? "steer",
+          payload: {
+            text: input.text,
+            agents: input.agents?.map((agent) => ({ ...agent })),
+            metadata: input.metadata,
+          },
+        },
+      }
+      publish({ ...state, outbox: [...state.outbox, intent] })
+      send()
+      return intent
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    subscribeFailures(listener) {
+      failureListeners.add(listener)
+      return () => failureListeners.delete(listener)
+    },
+    ready: () => ready.promise,
+    refresh() {
+      if (refreshing) return refreshing
+      refreshing = transport
+        .snapshot(sessionID)
+        .then((snapshot) => {
+          if (snapshot.seq < state.folded.seq) return
+          applySnapshot(snapshot, state.synced)
+          send()
+        })
+        .finally(() => {
+          refreshing = undefined
+        })
+      return refreshing
+    },
+    settled() {
+      if (state.outbox.length === 0) return Promise.resolve()
+      return new Promise<void>((resolve) => settled.add(resolve))
+    },
+    stop() {
+      stopped = true
+      abort.abort()
+      publish({ ...state, synced: false })
+    },
+  }
+}
+
+// Render runs per ephemeral event, so everything an event did not touch must
+// keep its reference: the adapter diffs consecutive views by identity to
+// decide what to write into the reactive store. Both caches key on persistent
+// inputs (a fold, outbox, or usage entry keeps its identity until it actually
+// changes), so per-delta renders only reapply the overlay.
+export function render(state: Pick<EngineState, "folded" | "outbox" | "overlay">): SessionView {
+  const base = renderBase(state.folded, state.outbox)
+  return {
+    ...state.folded,
+    session: usageSession(state.folded, state.overlay.get("usage")),
+    messages: applyOverlayToMessages(base.messages, state.overlay),
+    pending: base.pending,
+  }
+}
+
+const bases = new WeakMap<SessionFoldState, ReturnType<typeof buildBase>>()
+
+function renderBase(folded: SessionFoldState, outbox: EngineState["outbox"]) {
+  const hit = bases.get(folded)
+  if (hit && hit.outbox === outbox) return hit
+  const base = buildBase(folded, outbox)
+  bases.set(folded, base)
+  return base
+}
+
+function buildBase(folded: SessionFoldState, outbox: EngineState["outbox"]) {
+  const pending =
+    outbox.length === 0
+      ? folded.inbox
+      : [
+          ...folded.inbox,
+          ...outbox.map(
+            (intent): SessionInboxInfo => ({
+              id: intent.id,
+              sessionID: folded.session.id,
+              timeCreated: intent.created,
+              ...intent.item,
+            }),
+          ),
+        ]
+  const appended = pendingMessages(folded, pending)
+  return {
+    outbox,
+    pending,
+    messages: appended.length === 0 ? folded.messages : [...folded.messages, ...appended],
+  }
+}
+
+function pendingMessages(folded: SessionFoldState, pending: ReadonlyArray<SessionInboxInfo>) {
+  if (pending.length === 0) return []
+  const messageIDs = new Set(folded.messages.map((message) => message.id))
+  return pending.flatMap((item): ReadonlyArray<SessionMessageInfo> => {
+    if (item.type !== "compaction" && item.delivery === "queue") return []
+    if (messageIDs.has(item.id)) return []
+    const message = SessionFold.messageFromInbox(item)
+    return message ? [message] : []
+  })
+}
+
+const usageSessions = new WeakMap<
+  Extract<OverlayEntry, { type: "usage" }>,
+  { base: SessionFoldState["session"]; session: SessionFoldState["session"] }
+>()
+
+function usageSession(folded: SessionFoldState, entry: OverlayEntry | undefined) {
+  if (entry?.type !== "usage") return folded.session
+  const hit = usageSessions.get(entry)
+  if (hit && hit.base === folded.session) return hit.session
+  const session = { ...folded.session, cost: entry.value.cost, tokens: entry.value.tokens }
+  usageSessions.set(entry, { base: folded.session, session })
+  return session
+}
+
+function applyOverlay(overlay: Overlay, event: EphemeralSessionEvent): Overlay {
+  const next = new Map(overlay)
+  switch (event.type) {
+    case "session.text.delta": {
+      const key = partKey("text", event.data.assistantMessageID, event.data.ordinal)
+      const current = next.get(key)
+      next.set(key, {
+        type: "text",
+        value: (current?.type === "text" ? current.value : "") + event.data.delta,
+      })
+      return next
+    }
+    case "session.reasoning.delta": {
+      const key = partKey("reasoning", event.data.assistantMessageID, event.data.ordinal)
+      const current = next.get(key)
+      next.set(key, {
+        type: "reasoning",
+        value: (current?.type === "reasoning" ? current.value : "") + event.data.delta,
+      })
+      return next
+    }
+    case "session.tool.input.delta": {
+      const key = toolKey("tool-input", event.data.assistantMessageID, event.data.id)
+      const current = next.get(key)
+      next.set(key, {
+        type: "tool-input",
+        value: (current?.type === "tool-input" ? current.value : "") + event.data.delta,
+      })
+      return next
+    }
+    case "session.tool.progress":
+      next.set(toolKey("tool-progress", event.data.assistantMessageID, event.data.id), {
+        type: "tool-progress",
+        metadata: event.data.metadata,
+      })
+      return next
+    case "session.compaction.delta": {
+      const current = next.get("compaction")
+      next.set("compaction", {
+        type: "compaction",
+        value: (current?.type === "compaction" ? current.value : "") + event.data.text,
+      })
+      return next
+    }
+    case "session.usage.updated":
+      next.set("usage", { type: "usage", value: event.data })
+      return next
+  }
+}
+
+function clearOverlay(overlay: Overlay, event: DurableSessionEvent): Overlay {
+  switch (event.type) {
+    case "session.text.ended":
+      return removeOverlay(overlay, partKey("text", event.data.assistantMessageID, event.data.ordinal))
+    case "session.reasoning.ended":
+      return removeOverlay(overlay, partKey("reasoning", event.data.assistantMessageID, event.data.ordinal))
+    case "session.tool.input.ended":
+    case "session.tool.called":
+      return removeOverlay(overlay, toolKey("tool-input", event.data.assistantMessageID, event.data.id))
+    case "session.tool.success":
+    case "session.tool.failed":
+      return removeOverlay(overlay, toolKey("tool-progress", event.data.assistantMessageID, event.data.id))
+    case "session.compaction.ended":
+    case "session.compaction.failed":
+      return removeOverlay(overlay, "compaction")
+    case "session.step.ended":
+    case "session.step.failed":
+    case "session.usage.recorded":
+      return removeOverlay(overlay, "usage")
+    default:
+      return overlay
+  }
+}
+
+function removeOverlay(overlay: Overlay, key: string): Overlay {
+  if (!overlay.has(key)) return overlay
+  const next = new Map(overlay)
+  next.delete(key)
+  return next
+}
+
+function applyOverlayToMessages(messages: ReadonlyArray<SessionMessageInfo>, overlay: Overlay) {
+  if (overlay.size === 0) return messages
+  // Remap only the messages the overlay actually touches so everything else
+  // keeps its identity.
+  const compacting = overlay.has("compaction")
+  const touched = new Set<string>()
+  overlay.forEach((_, key) => {
+    const id = keyMessageID(key)
+    if (id) touched.add(id)
+  })
+  if (touched.size === 0 && !compacting) return messages
+  return messages.map((message): SessionMessageInfo => {
+    if (message.type === "compaction" && message.status === "running") {
+      if (!compacting) return message
+      const entry = overlay.get("compaction")
+      return entry?.type === "compaction" ? { ...message, summary: message.summary + entry.value } : message
+    }
+    if (message.type !== "assistant" || !touched.has(message.id)) return message
+    const ordinals = { text: 0, reasoning: 0 }
+    const content = message.content.map((part) => {
+      if (part.type === "text") {
+        const entry = overlay.get(partKey("text", message.id, ordinals.text++))
+        return entry?.type === "text" ? { ...part, text: part.text + entry.value } : part
+      }
+      if (part.type === "reasoning") {
+        const entry = overlay.get(partKey("reasoning", message.id, ordinals.reasoning++))
+        return entry?.type === "reasoning" ? { ...part, text: part.text + entry.value } : part
+      }
+      const input = overlay.get(toolKey("tool-input", message.id, part.id))
+      if (input?.type === "tool-input" && part.state.status === "streaming")
+        return { ...part, state: { ...part.state, input: part.state.input + input.value } }
+      const progress = overlay.get(toolKey("tool-progress", message.id, part.id))
+      if (progress?.type === "tool-progress" && part.state.status === "running")
+        return { ...part, state: { ...part.state, metadata: progress.metadata } }
+      return part
+    })
+    return content.some((part, index) => part !== message.content[index]) ? { ...message, content } : message
+  })
+}
+
+function partKey(type: "text" | "reasoning", messageID: string, ordinal: number) {
+  return `${type}:${messageID}:${ordinal}`
+}
+
+function toolKey(type: "tool-input" | "tool-progress", messageID: string, toolID: string) {
+  return `${type}:${messageID}:${toolID}`
+}
+
+// Second segment of a part or tool key; undefined for the segmentless
+// "compaction" and "usage" keys.
+function keyMessageID(key: string) {
+  return key.split(":")[1]
+}
+
+export * as Engine from "./engine"
@@ -0,0 +1,583 @@
+import type {
+  SessionEventDurable,
+  SessionInboxInfo,
+  SessionInfo,
+  SessionMessageAssistant,
+  SessionMessageAssistantTool,
+  SessionMessageInfo,
+  TokenUsageInfo,
+} from "../../promise"
+
+export type SessionFoldState = {
+  readonly session: SessionInfo
+  readonly children: ReadonlyArray<SessionInfo>
+  readonly inbox: ReadonlyArray<SessionInboxInfo>
+  readonly messages: ReadonlyArray<SessionMessageInfo>
+  readonly active: "idle" | "running"
+  readonly deleted: boolean
+  readonly seq: number
+}
+
+export type SessionSnapshot = Omit<SessionFoldState, "active" | "deleted"> & {
+  readonly active?: SessionFoldState["active"]
+}
+
+export type DurableSessionEvent = Exclude<SessionEventDurable, { readonly type: "session.forked" }>
+
+export function fromSnapshot(snapshot: SessionSnapshot): SessionFoldState {
+  return { ...snapshot, active: snapshot.active ?? "idle", deleted: false }
+}
+
+export function apply(state: SessionFoldState, event: DurableSessionEvent): SessionFoldState {
+  if (event.durable.seq <= state.seq) return state
+  const current = { ...state, seq: event.durable.seq }
+  switch (event.type) {
+    case "session.created":
+      return current
+    case "session.deleted":
+      return { ...current, deleted: true }
+    case "session.usage.recorded":
+      return { ...current, session: addUsage(state.session, event.data.cost, event.data.tokens, event.created) }
+    case "session.agent.selected":
+      return append(
+        {
+          ...current,
+          session: {
+            ...state.session,
+            agent: event.data.agent,
+            time: { ...state.session.time, updated: event.created },
+          },
+        },
+        {
+          id: messageID(event.id),
+          type: "agent-switched",
+          agent: event.data.agent,
+          previous: event.data.previous ?? state.session.agent,
+          metadata: event.metadata,
+          time: { created: event.created },
+        },
+      )
+    case "session.model.selected":
+      return append(
+        {
+          ...current,
+          session: {
+            ...state.session,
+            model: event.data.model,
+            time: { ...state.session.time, updated: event.created },
+          },
+        },
+        {
+          id: messageID(event.id),
+          type: "model-switched",
+          model: event.data.model,
+          previous: event.data.previous ?? state.session.model,
+          metadata: event.metadata,
+          time: { created: event.created },
+        },
+      )
+    case "session.moved":
+      return append(
+        {
+          ...current,
+          session: {
+            ...state.session,
+            location: event.data.location,
+            projectID: event.data.projectID,
+            subpath: event.data.subpath,
+            time: { ...state.session.time, updated: event.created },
+          },
+        },
+        {
+          id: messageID(event.id),
+          type: "location-switched",
+          location: event.data.location,
+          projectID: event.data.projectID,
+          subpath: event.data.subpath,
+          previous: {
+            location: state.session.location,
+            projectID: state.session.projectID,
+            subpath: state.session.subpath,
+          },
+          metadata: event.metadata,
+          time: { created: event.created },
+        },
+      )
+    case "session.renamed":
+      return {
+        ...current,
+        session: { ...state.session, title: event.data.title, time: { ...state.session.time, updated: event.created } },
+      }
+    case "session.inbox.enqueued":
+      return {
+        ...current,
+        session: { ...state.session, time: { ...state.session.time, updated: event.created } },
+        inbox: state.inbox.some((item) => item.id === event.data.inboxID)
+          ? state.inbox
+          : [
+              ...state.inbox,
+              {
+                id: event.data.inboxID,
+                sessionID: event.data.sessionID,
+                timeCreated: event.created,
+                ...event.data.item,
+              },
+            ],
+      }
+    case "session.inbox.delivered": {
+      const item = state.inbox.find((item) => item.id === event.data.inboxID)
+      const next = { ...current, inbox: state.inbox.filter((item) => item.id !== event.data.inboxID) }
+      if (!item) return next
+      const delivered = messageFromInbox(item, event.created)
+      return delivered ? append(next, delivered) : next
+    }
+    case "session.inbox.cancelled":
+      return { ...current, inbox: state.inbox.filter((item) => item.id !== event.data.inboxID) }
+    case "session.inbox.delivery.changed":
+      return {
+        ...current,
+        inbox: state.inbox.map((item) =>
+          item.id === event.data.inboxID ? { ...item, delivery: event.data.delivery } : item,
+        ),
+      }
+    case "session.execution.started":
+      return { ...current, active: "running" }
+    case "session.execution.succeeded":
+    case "session.execution.failed":
+    case "session.execution.interrupted":
+      return { ...updateActiveAssistant(current, (message) => without(message, "retry")), active: "idle" }
+    case "session.instructions.updated":
+      if (event.data.text === undefined) return current
+      return append(current, {
+        id: messageID(event.id),
+        type: "system",
+        text: event.data.text,
+        description: `Instructions updated: ${Object.keys(event.data.delta).join(", ")}`,
+        metadata: event.metadata,
+        time: { created: event.created },
+      })
+    case "session.synthetic":
+      return append(current, {
+        id: messageID(event.id),
+        type: "synthetic",
+        text: event.data.text,
+        description: event.data.description,
+        metadata: event.data.metadata,
+        time: { created: event.created },
+      })
+    case "session.skill.activated":
+      return append(current, {
+        id: messageID(event.id),
+        type: "skill",
+        skill: event.data.id,
+        name: event.data.name,
+        text: event.data.text,
+        metadata: event.metadata,
+        time: { created: event.created },
+      })
+    case "session.shell.started":
+      return append(current, {
+        id: messageID(event.id),
+        type: "shell",
+        shellID: event.data.shell.id,
+        command: event.data.shell.command,
+        status: event.data.shell.status,
+        metadata: event.metadata,
+        time: { created: event.created },
+      })
+    case "session.shell.ended":
+      return updateMessage(
+        current,
+        (message) => message.type === "shell" && message.shellID === event.data.shell.id,
+        (message) => {
+          if (message.type !== "shell") return message
+          return {
+            ...message,
+            status: event.data.shell.status,
+            exit: event.data.shell.exit,
+            output: event.data.output,
+            time: { ...message.time, completed: event.created },
+          }
+        },
+        true,
+      )
+    case "session.step.started": {
+      const existing = state.messages.some((message) => message.id === event.data.assistantMessageID)
+      if (existing)
+        return updateAssistant(current, event.data.assistantMessageID, (message) => ({
+          ...without(message, "retry", "error", "finish"),
+          agent: event.data.agent,
+          model: event.data.model,
+          time: without(message.time, "completed"),
+          snapshot: event.data.snapshot ? { ...message.snapshot, start: event.data.snapshot } : message.snapshot,
+        }))
+      return append(
+        updateActiveAssistant(current, (message) => ({
+          ...without(message, "retry"),
+          time: { ...message.time, completed: event.created },
+        })),
+        {
+          id: event.data.assistantMessageID,
+          type: "assistant",
+          agent: event.data.agent,
+          model: event.data.model,
+          metadata: event.metadata,
+          content: [],
+          snapshot: event.data.snapshot ? { start: event.data.snapshot } : undefined,
+          time: { created: event.created },
+        },
+      )
+    }
+    case "session.step.ended":
+      return withUsage(
+        updateAssistant(current, event.data.assistantMessageID, (message) => ({
+          ...message,
+          finish: event.data.finish,
+          cost: event.data.cost,
+          tokens: event.data.tokens,
+          time: { ...message.time, completed: event.created },
+          snapshot:
+            event.data.snapshot || event.data.files
+              ? { ...message.snapshot, end: event.data.snapshot, files: event.data.files }
+              : message.snapshot,
+        })),
+        event.data.cost,
+        event.data.tokens,
+        event.created,
+      )
+    case "session.step.failed": {
+      const failed = updateAssistant(current, event.data.assistantMessageID, (message) => ({
+        ...without(message, "retry"),
+        finish: "error",
+        error: event.data.error,
+        cost: event.data.cost ?? message.cost,
+        tokens: event.data.tokens ?? message.tokens,
+        time: { ...message.time, completed: event.created },
+        snapshot:
+          event.data.snapshot || event.data.files
+            ? { ...message.snapshot, end: event.data.snapshot, files: event.data.files }
+            : message.snapshot,
+      }))
+      if (event.data.cost === undefined || event.data.tokens === undefined) return failed
+      return withUsage(failed, event.data.cost, event.data.tokens, event.created)
+    }
+    case "session.text.started":
+      return updateAssistant(current, event.data.assistantMessageID, (message) => ({
+        ...message,
+        content: insertOrdinal(message.content, "text", event.data.ordinal, { type: "text", text: "" }),
+      }))
+    case "session.text.ended":
+      return updateContent(current, event.data.assistantMessageID, "text", event.data.ordinal, (part) => {
+        const next = { ...part, text: event.data.text }
+        return event.data.state === undefined ? without(next, "state") : { ...next, state: event.data.state }
+      })
+    case "session.reasoning.started":
+      return updateAssistant(current, event.data.assistantMessageID, (message) => ({
+        ...message,
+        content: insertOrdinal(message.content, "reasoning", event.data.ordinal, {
+          type: "reasoning",
+          text: "",
+          state: event.data.state,
+          time: { created: event.created },
+        }),
+      }))
+    case "session.reasoning.ended":
+      return updateContent(current, event.data.assistantMessageID, "reasoning", event.data.ordinal, (part) => ({
+        ...part,
+        text: event.data.text,
+        state: event.data.state ?? part.state,
+        time: { created: part.time?.created ?? event.created, completed: event.created },
+      }))
+    case "session.tool.input.started":
+      return updateAssistant(current, event.data.assistantMessageID, (message) => ({
+        ...message,
+        content: [
+          ...message.content,
+          {
+            type: "tool",
+            id: event.data.id,
+            name: event.data.name,
+            state: { status: "streaming", input: "" },
+            time: { created: event.created },
+          },
+        ],
+      }))
+    case "session.tool.input.ended":
+      return updateTool(current, event.data.assistantMessageID, event.data.id, (part) =>
+        part.state.status === "streaming" ? { ...part, state: { ...part.state, input: event.data.text } } : part,
+      )
+    case "session.tool.called":
+      return updateTool(current, event.data.assistantMessageID, event.data.id, (part) => ({
+        ...part,
+        executed: event.data.executed,
+        providerState: event.data.state,
+        state: { status: "running", input: event.data.input, metadata: {} },
+        time: { ...part.time, ran: event.created },
+      }))
+    case "session.tool.success":
+      return updateTool(current, event.data.assistantMessageID, event.data.id, (part) => {
+        if (part.state.status !== "running") return part
+        return {
+          ...part,
+          executed: event.data.executed || part.executed === true,
+          providerResultState: event.data.resultState,
+          state: {
+            status: "completed",
+            input: part.state.input,
+            content: event.data.content,
+            metadata: event.data.metadata,
+          },
+          time: { ...part.time, completed: event.created },
+        }
+      })
+    case "session.tool.failed":
+      return updateTool(current, event.data.assistantMessageID, event.data.id, (part) => {
+        if (part.state.status !== "streaming" && part.state.status !== "running") return part
+        return {
+          ...part,
+          executed: event.data.executed || part.executed === true,
+          providerResultState: event.data.resultState,
+          state: {
+            status: "error",
+            error: event.data.error,
+            input: typeof part.state.input === "string" ? {} : part.state.input,
+            content: event.data.content,
+            metadata: event.data.metadata,
+          },
+          time: { ...part.time, completed: event.created },
+        }
+      })
+    case "session.retry.scheduled":
+      return updateAssistant(current, event.data.assistantMessageID, (message) => ({
+        ...message,
+        retry: { attempt: event.data.attempt, at: event.data.at, error: event.data.error },
+      }))
+    case "session.compaction.started":
+      return append(
+        {
+          ...current,
+          inbox: event.data.inputID ? state.inbox.filter((item) => item.id !== event.data.inputID) : state.inbox,
+        },
+        {
+          id: event.data.inputID ?? messageID(event.id),
+          type: "compaction",
+          status: "running",
+          reason: event.data.reason,
+          summary: "",
+          recent: event.data.recent,
+          metadata: event.metadata,
+          time: { created: event.created },
+        },
+      )
+    case "session.compaction.ended": {
+      const running = state.messages.findLast(
+        (message) => message.type === "compaction" && message.status === "running",
+      )
+      if (!running)
+        return append(current, {
+          id: messageID(event.id),
+          type: "compaction",
+          status: "completed",
+          reason: event.data.reason,
+          summary: event.data.text,
+          recent: event.data.recent,
+          metadata: event.metadata,
+          time: { created: event.created },
+        })
+      return updateMessage(
+        current,
+        (message) => message.id === running.id,
+        (message) => ({
+          ...message,
+          type: "compaction",
+          status: "completed",
+          reason: event.data.reason,
+          summary: event.data.text,
+          recent: event.data.recent,
+        }),
+      )
+    }
+    case "session.compaction.failed": {
+      const running = state.messages.findLast(
+        (message) => message.type === "compaction" && message.status === "running",
+      )
+      const failed = {
+        id: running?.id ?? event.data.inputID ?? messageID(event.id),
+        type: "compaction" as const,
+        status: "failed" as const,
+        reason: event.data.reason,
+        error: event.data.error,
+        metadata: running?.metadata ?? event.metadata,
+        time: running?.time ?? { created: event.created },
+      }
+      const next = {
+        ...current,
+        inbox: event.data.inputID ? state.inbox.filter((item) => item.id !== event.data.inputID) : state.inbox,
+      }
+      return running
+        ? updateMessage(
+            next,
+            (message) => message.id === running.id,
+            () => failed,
+          )
+        : append(next, failed)
+    }
+    case "session.revert.staged":
+      return {
+        ...current,
+        session: {
+          ...state.session,
+          revert: event.data.revert,
+          time: { ...state.session.time, updated: event.created },
+        },
+      }
+    case "session.revert.cleared":
+      return {
+        ...current,
+        session: without({ ...state.session, time: { ...state.session.time, updated: event.created } }, "revert"),
+      }
+    case "session.revert.committed":
+      return {
+        ...current,
+        session: without({ ...state.session, time: { ...state.session.time, updated: event.created } }, "revert"),
+        messages: state.messages.filter((message) => message.id < event.data.to),
+        inbox: state.inbox.filter((item) => item.id < event.data.to),
+      }
+  }
+}
+
+function messageID(eventID: string) {
+  return eventID.replace(/^evt_/, "msg_")
+}
+
+// Clearing a field must delete the key, not assign undefined: fold state
+// round-trips through JSON snapshots, which cannot represent undefined-valued
+// keys, so replay and fromSnapshot must agree on key presence.
+function without<T extends object, K extends keyof T>(value: T, ...keys: ReadonlyArray<K>): Omit<T, K> {
+  const next = { ...value }
+  for (const key of keys) delete next[key]
+  return next
+}
+
+export function messageFromInbox(item: SessionInboxInfo, created = item.timeCreated): SessionMessageInfo | undefined {
+  if (item.type === "user") return { id: item.id, type: "user", ...item.payload, time: { created } }
+  if (item.type === "synthetic") return { id: item.id, type: "synthetic", ...item.payload, time: { created } }
+}
+
+function append(state: SessionFoldState, item: SessionMessageInfo) {
+  if (state.messages.some((message) => message.id === item.id)) return state
+  return { ...state, messages: [...state.messages, item] }
+}
+
+function updateMessage(
+  state: SessionFoldState,
+  predicate: (message: SessionMessageInfo) => boolean,
+  update: (message: SessionMessageInfo) => SessionMessageInfo,
+  last = false,
+) {
+  const index = last ? state.messages.findLastIndex(predicate) : state.messages.findIndex(predicate)
+  if (index < 0) return state
+  return {
+    ...state,
+    messages: state.messages.map((message, position) => (position === index ? update(message) : message)),
+  }
+}
+
+function updateAssistant(
+  state: SessionFoldState,
+  messageID: string,
+  update: (message: SessionMessageAssistant) => SessionMessageAssistant,
+) {
+  return updateMessage(
+    state,
+    (message) => message.id === messageID && message.type === "assistant",
+    (message) => (message.type === "assistant" ? update(message) : message),
+  )
+}
+
+function updateActiveAssistant(
+  state: SessionFoldState,
+  update: (message: SessionMessageAssistant) => SessionMessageAssistant,
+) {
+  return updateMessage(
+    state,
+    (message) => message.type === "assistant" && message.time.completed === undefined,
+    (message) => (message.type === "assistant" ? update(message) : message),
+    true,
+  )
+}
+
+function updateContent<Type extends "text" | "reasoning">(
+  state: SessionFoldState,
+  messageID: string,
+  type: Type,
+  ordinal: number,
+  update: (
+    part: Extract<SessionMessageAssistant["content"][number], { readonly type: Type }>,
+  ) => Extract<SessionMessageAssistant["content"][number], { readonly type: Type }>,
+) {
+  return updateAssistant(state, messageID, (message) => {
+    const position = message.content.flatMap((part, index) => (part.type === type ? [index] : []))[ordinal]
+    const part = position === undefined ? undefined : message.content[position]
+    if (!part || part.type !== type) return message
+    return {
+      ...message,
+      content: message.content.map((item, index) =>
+        index === position
+          ? update(part as Extract<SessionMessageAssistant["content"][number], { readonly type: Type }>)
+          : item,
+      ),
+    }
+  })
+}
+
+function updateTool(
+  state: SessionFoldState,
+  messageID: string,
+  toolID: string,
+  update: (part: SessionMessageAssistantTool) => SessionMessageAssistantTool,
+) {
+  return updateAssistant(state, messageID, (message) => {
+    const index = message.content.findLastIndex((part) => part.type === "tool" && part.id === toolID)
+    if (index < 0) return message
+    return {
+      ...message,
+      content: message.content.map((part, position) =>
+        position === index && part.type === "tool" ? update(part) : part,
+      ),
+    }
+  })
+}
+
+function insertOrdinal<Type extends SessionMessageAssistant["content"][number]["type"]>(
+  content: SessionMessageAssistant["content"],
+  type: Type,
+  ordinal: number,
+  part: Extract<SessionMessageAssistant["content"][number], { readonly type: Type }>,
+) {
+  if (content.filter((item) => item.type === type)[ordinal]) return content
+  return [...content, part]
+}
+
+function addUsage(session: SessionInfo, cost: number, tokens: TokenUsageInfo, updated: number): SessionInfo {
+  return {
+    ...session,
+    cost: session.cost + cost,
+    tokens: {
+      input: session.tokens.input + tokens.input,
+      output: session.tokens.output + tokens.output,
+      reasoning: session.tokens.reasoning + tokens.reasoning,
+      cache: {
+        read: session.tokens.cache.read + tokens.cache.read,
+        write: session.tokens.cache.write + tokens.cache.write,
+      },
+    },
+    time: { ...session.time, updated },
+  }
+}
+
+function withUsage(state: SessionFoldState, cost: number, tokens: TokenUsageInfo, updated: number) {
+  return { ...state, session: addUsage(state.session, cost, tokens, updated) }
+}
+
+export * as SessionFold from "./fold"
@@ -1,2 +1,3 @@
 export * from "./data"
 export * from "./connection"
+export * from "./engine-data"
@@ -0,0 +1,145 @@
+// Proves the generated-client wiring the engine laws take for granted: the
+// adapter in src/solid/engine-data.ts must speak the real snapshot/log/prompt
+// API shapes and translate the generated typed errors into the engine's own
+// (the SeqUnavailable path is what laws 7-9 in test/sync-engine-laws.test.ts
+// rely on in production).
+import { describe, expect, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { Engine } from "../src/solid/engine/engine"
+import { SNAPSHOT_RECENT, createEngineData, createEngineTransport } from "../src/solid/engine-data"
+import { FakeSessionServer } from "./fixture/sync-engine"
+
+describe("engine data transport", () => {
+  test("uses snapshot and ephemeral follow log contracts", async () => {
+    const server = new FakeSessionServer("ses_transport")
+    const calls: Array<unknown> = []
+    const transport = createEngineTransport(() => ({
+      async snapshot(input) {
+        calls.push(input)
+        // The generated client returns mutable arrays; the fixture's snapshot
+        // is readonly, so mirror the wire shape here.
+        const value = server.snapshotValue()
+        return { ...value, children: [...value.children], inbox: [...value.inbox], messages: [...value.messages] }
+      },
+      async *log(input) {
+        calls.push(input)
+        yield { type: "log.synced" as const, aggregateID: input.sessionID, seq: 0 }
+      },
+      async prompt() {
+        throw new Error("unused")
+      },
+    }))
+
+    expect(await transport.snapshot(server.sessionID)).toEqual(server.snapshotValue())
+    const items: Array<Engine.SessionStreamItem> = []
+    for await (const item of transport.stream(server.sessionID, 0)) items.push(item)
+
+    expect(items).toEqual([{ type: "log.synced", aggregateID: server.sessionID, seq: 0 }])
+    expect(calls).toEqual([
+      { sessionID: server.sessionID, recent: SNAPSHOT_RECENT },
+      { sessionID: server.sessionID, after: 0, follow: true, ephemeral: true },
+    ])
+  })
+
+  test("preserves the prompt request and client-minted ID", async () => {
+    const requests: Array<unknown> = []
+    const transport = createEngineTransport(() => ({
+      async snapshot() {
+        throw new Error("unused")
+      },
+      async *log() {
+        throw new Error("unused")
+      },
+      async prompt(input) {
+        requests.push(input)
+        return {
+          id: input.id!,
+          sessionID: input.sessionID,
+          timeCreated: 1,
+          type: "user",
+          payload: { text: input.text },
+          delivery: input.delivery ?? "steer",
+        }
+      },
+    }))
+
+    await transport.submit({
+      id: "msg_client",
+      sessionID: "ses_submit",
+      request: {
+        text: "hello",
+        files: [{ uri: "file:///tmp/example.txt", name: "example.txt" }],
+        delivery: "queue",
+      },
+    })
+
+    expect(requests).toEqual([
+      {
+        id: "msg_client",
+        sessionID: "ses_submit",
+        text: "hello",
+        files: [{ uri: "file:///tmp/example.txt", name: "example.txt" }],
+        delivery: "queue",
+      },
+    ])
+  })
+
+  test("a failed initial attach does not poison the session cache", async () => {
+    const server = new FakeSessionServer("ses_attach_retry")
+    server.faults.loseSnapshots = 1
+    const api = {
+      session: {
+        snapshot: (input: { sessionID: string }) => server.snapshot(input.sessionID),
+        log: (input: { sessionID: string; after: number }) => server.stream(input.sessionID, input.after),
+        prompt: () => Promise.reject(new Error("unused")),
+      },
+    }
+    await createRoot(async (dispose) => {
+      const data = createEngineData({
+        api: () => api as never,
+        directory: "/workspace",
+        event: { on: () => () => {}, listen: () => () => {} },
+      })
+
+      // The server is down when the session first opens…
+      await expect(data.session.sync(server.sessionID)).rejects.toThrow("snapshot lost")
+      // …and the next sync attaches with a fresh engine instead of a cached rejection.
+      await data.session.sync(server.sessionID)
+
+      expect(data.session.get(server.sessionID)?.id).toBe(server.sessionID)
+      dispose()
+    })
+  })
+
+  test("translates generated typed failures", async () => {
+    // These literals mirror the generated client's error DTO shapes
+    // (SeqUnavailableError / InvalidRequestError in src/promise/generated);
+    // they must change if the generated error schema does.
+    const transport = createEngineTransport(() => ({
+      async snapshot() {
+        throw new Error("unused")
+      },
+      async *log() {
+        throw { _tag: "SeqUnavailableError", sessionID: "ses_errors", after: 2, head: 1, message: "gone" }
+      },
+      async prompt() {
+        throw { _tag: "InvalidRequestError", message: "invalid" }
+      },
+    }))
+
+    const streamError = await collectError(transport.stream("ses_errors", 2))
+    expect(streamError).toBeInstanceOf(Engine.SeqUnavailable)
+    await expect(
+      transport.submit({ id: "msg_client", sessionID: "ses_errors", request: { text: "invalid" } }),
+    ).rejects.toEqual(new Engine.SubmitRejected("invalid"))
+  })
+})
+
+async function collectError(iterable: AsyncIterable<unknown>) {
+  try {
+    for await (const item of iterable) void item
+  } catch (error) {
+    return error
+  }
+  throw new Error("stream did not fail")
+}
@@ -0,0 +1,231 @@
+// In-memory model of the server's session log, used by the engine laws
+// (sync-engine-laws.test.ts), the chaos simulation (sync-engine-sim.test.ts),
+// and the legacy bug catalog (legacy-divergence.test.ts). It folds with the
+// REAL SessionFold, so `truth()` is the same interpretation of events a
+// converged client must reach, and its admission dedupes by inbox ID exactly
+// like the server's inbox projector. Faults are injected per call through the
+// `faults` record; `cutConnections` and `prune` model disconnects and lost
+// retention.
+import type { SessionInfo, SessionMessageInfo } from "../../src/promise"
+import { Engine } from "../../src/solid/engine/engine"
+import type { DurableSessionEvent, SessionFoldState, SessionSnapshot } from "../../src/solid/engine/fold"
+import { SessionFold } from "../../src/solid/engine/fold"
+
+export class FakeSessionServer implements Engine.SessionTransport {
+  readonly events: Array<DurableSessionEvent> = []
+  readonly admitted: Array<string> = []
+  readonly faults = {
+    loseRequests: 0,
+    loseResponses: 0,
+    loseSnapshots: 0,
+    reject: 0,
+    latency: 0,
+  }
+
+  private folded: SessionFoldState
+  private readonly tails = new Set<AsyncQueue<Engine.SessionStreamItem>>()
+  private eventCounter = 0
+
+  constructor(
+    readonly sessionID: string,
+    readonly time = 1_717_171_717_000,
+  ) {
+    this.folded = SessionFold.fromSnapshot(emptySnapshot(sessionID, time))
+  }
+
+  async snapshot(sessionID: string) {
+    await this.pause()
+    this.assertSession(sessionID)
+    if (this.faults.loseSnapshots > 0) {
+      this.faults.loseSnapshots--
+      throw new Error("snapshot lost")
+    }
+    return this.snapshotValue()
+  }
+
+  async *stream(sessionID: string, after: number, signal?: AbortSignal): AsyncIterable<Engine.SessionStreamItem> {
+    await this.pause()
+    this.assertSession(sessionID)
+    if (after > this.folded.seq) throw new Engine.SeqUnavailable()
+    const replay = this.events.filter((event) => event.durable.seq > after)
+    // Honest replay contract: a cursor is only admitted when retained events fully cover (after, seq].
+    if (replay.length < this.folded.seq - after) throw new Engine.SeqUnavailable()
+    const queue = new AsyncQueue<Engine.SessionStreamItem>()
+    const abort = () => queue.fail(new Error("stream aborted"))
+    signal?.addEventListener("abort", abort, { once: true })
+    this.tails.add(queue)
+    try {
+      for (const event of replay) yield event
+      yield { type: "log.synced", aggregateID: sessionID, seq: this.folded.seq }
+      while (true) yield await queue.take()
+    } finally {
+      signal?.removeEventListener("abort", abort)
+      this.tails.delete(queue)
+    }
+  }
+
+  async submit(input: Engine.SubmitInput) {
+    await this.pause()
+    this.assertSession(input.sessionID)
+    const existing = this.events.find(
+      (event) => event.type === "session.inbox.enqueued" && event.data.inboxID === input.id,
+    )
+    if (existing) return
+    if (this.faults.loseRequests > 0) {
+      this.faults.loseRequests--
+      throw new Error("request lost")
+    }
+    if (this.faults.reject > 0) {
+      this.faults.reject--
+      throw new Engine.SubmitRejected("rejected")
+    }
+    this.admitted.push(input.id)
+    this.publish({
+      id: `evt_${String(++this.eventCounter).padStart(8, "0")}`,
+      created: this.time,
+      type: "session.inbox.enqueued",
+      durable: { aggregateID: this.sessionID, seq: this.folded.seq + 1, version: 1 },
+      data: {
+        sessionID: this.sessionID,
+        inboxID: input.id,
+        item: {
+          type: "user",
+          delivery: input.request.delivery ?? "steer",
+          payload: {
+            text: input.request.text,
+            agents: input.request.agents?.map((agent) => ({ ...agent })),
+            metadata: input.request.metadata,
+          },
+        },
+      },
+    })
+    if (this.faults.loseResponses > 0) {
+      this.faults.loseResponses--
+      throw new Error("response lost")
+    }
+  }
+
+  cutConnections() {
+    this.tails.forEach((tail) => tail.fail(new Error("connection cut")))
+  }
+
+  /** Drop retained event history, simulating `events.persist` off or pruned retention. */
+  prune() {
+    this.events.length = 0
+  }
+
+  /** Clear every injected fault. */
+  heal() {
+    for (const fault of Object.keys(this.faults) as Array<keyof FakeSessionServer["faults"]>) this.faults[fault] = 0
+  }
+
+  seq() {
+    return this.folded.seq
+  }
+
+  truth() {
+    return Engine.render({ folded: this.folded, outbox: [], overlay: new Map() })
+  }
+
+  snapshotValue(): SessionSnapshot {
+    return {
+      session: this.folded.session,
+      children: this.folded.children,
+      inbox: this.folded.inbox,
+      messages: this.folded.messages,
+      seq: this.folded.seq,
+      active: this.folded.active,
+    }
+  }
+
+  private publish(event: DurableSessionEvent) {
+    this.events.push(event)
+    this.folded = SessionFold.apply(this.folded, event)
+    this.tails.forEach((tail) => tail.offer(event))
+  }
+
+  private assertSession(sessionID: string) {
+    if (sessionID !== this.sessionID) throw new Error(`unknown session: ${sessionID}`)
+  }
+
+  private async pause() {
+    for (let step = 0; step < this.faults.latency; step++) await Promise.resolve()
+  }
+}
+
+/**
+ * Reconnect option that holds the engine's first reconnect until released,
+ * so a test can advance the server "while disconnected". Later reconnects
+ * pass through instantly.
+ */
+export function reconnectGate() {
+  let open = false
+  let release: (() => void) | undefined
+  return {
+    reconnect: () =>
+      new Promise<void>((resolve) => {
+        if (open) return resolve()
+        release = () => {
+          open = true
+          resolve()
+        }
+      }),
+    holding: () => release !== undefined,
+    release: () => release!(),
+  }
+}
+
+export async function until(check: () => boolean, message = "condition did not become true") {
+  for (let attempt = 0; attempt < 500; attempt++) {
+    if (check()) return
+    await Bun.sleep(1)
+  }
+  throw new Error(message)
+}
+
+export function userMessages(messages: ReadonlyArray<SessionMessageInfo>) {
+  return messages.filter(
+    (message): message is Extract<SessionMessageInfo, { readonly type: "user" }> => message.type === "user",
+  )
+}
+
+function emptySnapshot(sessionID: string, time: number): SessionSnapshot {
+  const session: SessionInfo = {
+    id: sessionID,
+    projectID: "project",
+    cost: 0,
+    tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+    time: { created: time, updated: time },
+    location: { directory: "/workspace" },
+  }
+  return { session, children: [], inbox: [], messages: [], seq: 0 }
+}
+
+class AsyncQueue<Value> {
+  private readonly values: Array<Value> = []
+  private readonly waiting: Array<{
+    readonly resolve: (value: Value) => void
+    readonly reject: (error: Error) => void
+  }> = []
+  private error?: Error
+
+  offer(value: Value) {
+    const waiter = this.waiting.shift()
+    if (waiter) {
+      waiter.resolve(value)
+      return
+    }
+    this.values.push(value)
+  }
+
+  fail(error: Error) {
+    this.error = error
+    this.waiting.splice(0).forEach((waiter) => waiter.reject(error))
+  }
+
+  take() {
+    if (this.values.length) return Promise.resolve(this.values.shift()!)
+    if (this.error) return Promise.reject(this.error)
+    return new Promise<Value>((resolve, reject) => this.waiting.push({ resolve, reject }))
+  }
+}
@@ -0,0 +1,258 @@
+// Divergence catalog: weird states the legacy data layer (createData) can get
+// into that the sync engine cannot. Each test drives the REAL legacy layer —
+// or, for the retry test, its raw ID-less prompt protocol — and PASSES by
+// demonstrating the bug, with a pointer to the engine law or mechanism that
+// rules the same state out. If a test here starts failing, the legacy layer
+// got fixed — celebrate and delete the test.
+//
+// Companion clean-behavior proofs: test/sync-engine-laws.test.ts.
+
+import { describe, expect, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { createData } from "../src/solid/data"
+import type { CreateDataInput } from "../src/solid/data"
+import type { OpenCodeEvent, SessionMessageInfo } from "../src/promise"
+import { FakeSessionServer } from "./fixture/sync-engine"
+
+const sessionID = "ses_legacy"
+const assistantID = "msg_assistant"
+
+describe("legacy data layer divergence catalog", () => {
+  test("a dropped durable event desyncs the transcript silently and forever", async () => {
+    // Server truth: the assistant message finished with text "FINAL".
+    // The client misses only the `session.text.ended` event (blip mid-stream).
+    const legacy = await hydrated()
+    legacy.dispatch(textStarted())
+    for (let index = 0; index < 5; index++) legacy.dispatch(textDelta("x"))
+    // ...the `ended` event with the durable final text never arrives.
+
+    // The transcript is stuck on accumulated deltas, disagreeing with the
+    // server, and nothing in the layer can ever notice: there is no sequence
+    // cursor, no gap check, no recovery path. Only a manual refetch heals it.
+    expect(legacy.text()).toBe("xxxxx")
+    legacy.dispose()
+    // Engine: durable events carry seqs; a gap surfaces as SeqUnavailable or a
+    // marker past the fold, forcing snapshot recovery (laws 7 and 8).
+  })
+
+  test("a late delta corrupts a completed message", async () => {
+    // Events delivered slightly out of order: the final text lands, then a
+    // straggling delta from the finished stream arrives.
+    const legacy = await hydrated()
+    legacy.dispatch(textStarted())
+    legacy.dispatch(textDelta("Hel"))
+    legacy.dispatch(textEnded("Hello"))
+    legacy.dispatch(textDelta("lo"))
+
+    // The handler appends onto whatever text part it finds — including a
+    // completed one. The final message is permanently corrupted.
+    expect(legacy.text()).toBe("Hellolo")
+    legacy.dispose()
+    // Engine: deltas are ephemeral overlay entries cleared by the durable
+    // lifecycle events, and the ordered log cannot deliver a delta after its
+    // own `ended` — there is no durable state for a straggler to corrupt.
+  })
+
+  test("a slow fetch rewinds the store past already-rendered live events", async () => {
+    // The initial message fetch is in flight when a live prompt admission
+    // arrives. The user's message renders... then the stale fetch resolves.
+    let resolveFetch: ((messages: SessionMessageInfo[]) => void) | undefined
+    const legacy = makeLegacy({
+      list: () => new Promise<SessionMessageInfo[]>((resolve) => (resolveFetch = resolve)),
+    })
+    const syncing = legacy.data.session.message.sync(sessionID)
+    legacy.dispatch(inboxEnqueued("msg_user"))
+    expect(legacy.data.session.message.get(sessionID, "msg_user")).toBeDefined()
+
+    resolveFetch!([]) // the fetch was served before the admission — stale
+    await syncing
+
+    // The message the user just watched appear is gone. It returns only if
+    // some later event or refetch happens to bring it back.
+    expect(legacy.data.session.message.get(sessionID, "msg_user")).toBeUndefined()
+    legacy.dispose()
+    // Engine: hydration is a seq-stamped snapshot, and a stale refresh cannot
+    // move the fold behind the live log (law 10, refresh monotonicity).
+  })
+
+  test("delivered-before-enqueued leaves a phantom pending row forever", async () => {
+    // Reordered delivery: the `delivered` event arrives before its `enqueued`.
+    const legacy = await hydrated()
+    legacy.dispatch(inboxDelivered("msg_user")) // no-op: nothing to deliver yet
+    legacy.dispatch(inboxEnqueued("msg_user")) // adds the pending row
+
+    // The delivered event was already consumed, so the row the server has
+    // long since promoted sits in "pending" until a manual refetch.
+    expect(legacy.data.session.pending.list(sessionID).map((item) => item.id)).toEqual(["msg_user"])
+    legacy.dispose()
+    // Engine: the transport is a single ordered log, so this ordering cannot
+    // be observed live; a reconnect replays from the seq cursor, and any gap
+    // fails the cursor check and recovers via snapshot (laws 7 and 8).
+  })
+
+  test("a retry after a lost response admits the prompt twice", async () => {
+    // Both protocols drive the same server admission logic (FakeSessionServer
+    // dedupes by inbox ID exactly like the real projector). The only
+    // difference is who mints the ID.
+
+    // Legacy protocol: the request carries no ID, so the server mints a fresh
+    // one per attempt and cannot recognize a retry. The response to the first
+    // send is lost, the user presses enter again — the transcript now has the
+    // prompt twice.
+    const legacyServer = new FakeSessionServer(sessionID)
+    legacyServer.faults.loseResponses = 1
+    let minted = 0
+    const legacySend = (text: string) =>
+      legacyServer.submit({ id: `msg_minted_${++minted}`, sessionID, request: { text } })
+    await legacySend("hello").catch(() => {})
+    await legacySend("hello")
+    expect(legacyServer.admitted).toHaveLength(2)
+
+    // Engine protocol: the retry reuses the client-minted ID and the same
+    // server admits exactly once. (Law 1 proves this end-to-end through the
+    // real engine retry loop; this is the raw protocol contrast.)
+    const engineServer = new FakeSessionServer(sessionID)
+    engineServer.faults.loseResponses = 1
+    const engineSend = () => engineServer.submit({ id: "msg_client", sessionID, request: { text: "hello" } })
+    await engineSend().catch(() => {})
+    await engineSend()
+    expect(engineServer.admitted).toEqual(["msg_client"])
+  })
+
+  test("a dropped execution event leaves an interrupted session spinning forever", async () => {
+    // The user hits interrupt; the server stops the run; the terminal
+    // `session.execution.interrupted` event is lost in a reconnect blip.
+    const legacy = await hydrated()
+    legacy.dispatch(executionStarted())
+
+    // Status only ever changes on the terminal event (lost) or a full
+    // reconnect's active-session refetch — until one of those happens the
+    // spinner spins over a session the server already stopped.
+    expect(legacy.data.session.status(sessionID)).toBe("running")
+    legacy.dispose()
+    // Engine: activity is folded durable state behind the seq cursor, so the
+    // gap itself is detected and snapshot recovery resyncs activity with the
+    // server (laws 7 and 8 pin the mechanism).
+  })
+})
+
+// Also part of the catalog, straight from the legacy source: the layer
+// documents its own event-vs-fetch race — see the session.created "band-aid"
+// comment in src/solid/data.ts (skipping racy initial reads so live events
+// are not overwritten by stale fetches).
+
+function makeLegacy(overrides: { list?: () => Promise<SessionMessageInfo[]> } = {}) {
+  let handler: ((event: { name: OpenCodeEvent["type"]; details: OpenCodeEvent }) => void) | undefined
+  const api = {
+    session: {
+      get: async () => ({
+        id: sessionID,
+        projectID: "project",
+        cost: 0,
+        tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+        time: { created: 1, updated: 2 },
+        location: { directory: "/workspace" },
+      }),
+    },
+    message: {
+      list: async () => ({
+        data: overrides.list ? await overrides.list() : transcript().toReversed(),
+        cursor: {},
+      }),
+    },
+  } as unknown as ReturnType<CreateDataInput["api"]>
+  return createRoot((dispose) => {
+    const data = createData({
+      api: () => api,
+      directory: "/workspace",
+      event: {
+        on: () => () => {},
+        listen(next) {
+          handler = next
+          return () => {}
+        },
+      },
+    })
+    return {
+      data,
+      dispose,
+      dispatch(event: { type: OpenCodeEvent["type"] } & Record<string, unknown>) {
+        handler?.({ name: event.type, details: event as unknown as OpenCodeEvent })
+      },
+      text() {
+        const message = data.session.message.get(sessionID, assistantID)
+        const part =
+          message?.type === "assistant" ? message.content.findLast((item) => item.type === "text") : undefined
+        return part?.type === "text" ? part.text : undefined
+      },
+    }
+  })
+}
+
+async function hydrated() {
+  const legacy = makeLegacy()
+  await legacy.data.session.sync(sessionID)
+  await legacy.data.session.message.sync(sessionID)
+  return legacy
+}
+
+function transcript(): SessionMessageInfo[] {
+  return [
+    { id: "msg_earlier", type: "user", text: "earlier", time: { created: 1 } },
+    {
+      id: assistantID,
+      type: "assistant",
+      time: { created: 2 },
+      agent: "build",
+      model: { id: "model", providerID: "provider" },
+      content: [],
+    },
+  ]
+}
+
+const textStarted = () => ({
+  id: "evt_start",
+  created: 3,
+  type: "session.text.started" as const,
+  data: { sessionID, assistantMessageID: assistantID, ordinal: 0 },
+})
+
+let deltaCount = 0
+const textDelta = (delta: string) => ({
+  id: `evt_delta_${++deltaCount}`,
+  created: 4,
+  type: "session.text.delta" as const,
+  data: { sessionID, assistantMessageID: assistantID, ordinal: 0, delta },
+})
+
+const textEnded = (text: string) => ({
+  id: "evt_end",
+  created: 5,
+  type: "session.text.ended" as const,
+  data: { sessionID, assistantMessageID: assistantID, ordinal: 0, text },
+})
+
+const inboxEnqueued = (inboxID: string) => ({
+  id: "evt_enqueued",
+  created: 6,
+  type: "session.inbox.enqueued" as const,
+  data: {
+    sessionID,
+    inboxID,
+    item: { type: "user", delivery: "steer", payload: { text: "hello" } },
+  },
+})
+
+const inboxDelivered = (inboxID: string) => ({
+  id: "evt_delivered",
+  created: 7,
+  type: "session.inbox.delivered" as const,
+  data: { sessionID, inboxID },
+})
+
+const executionStarted = () => ({
+  id: "evt_execution",
+  created: 8,
+  type: "session.execution.started" as const,
+  data: { sessionID },
+})
@@ -0,0 +1,201 @@
+// Laws of the session sync engine: each test pins one property the engine
+// must hold under transport faults. Cited by number from
+// test/legacy-divergence.test.ts (the legacy bug catalog these laws rule out)
+// and stress-tested together by test/sync-engine-sim.test.ts. The server
+// model lives in test/fixture/sync-engine.ts and folds with the real
+// SessionFold, so `server.truth()` is the state a converged client must show.
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { Engine } from "../src/solid/engine/engine"
+import { FakeSessionServer, reconnectGate, until, userMessages } from "./fixture/sync-engine"
+
+describe("session sync engine laws", () => {
+  test("1. idempotency: lost responses converge to one admitted message", async () => {
+    const server = new FakeSessionServer("ses_idempotency")
+    server.faults.loseResponses = 1
+    const engine = await Engine.createSessionEngine(server.sessionID, server, {
+      now: () => server.time,
+      reconnect: async () => {},
+    })
+
+    engine.submit({ id: "msg_1", text: "hello" })
+    await until(() => engine.view().seq === 1)
+    // The admit landed but the response was lost; the reconnect makes the
+    // engine resend the same client-minted ID — that resend is what
+    // idempotency must absorb.
+    server.cutConnections()
+    await engine.settled()
+
+    expect(server.admitted).toEqual(["msg_1"])
+    expect(userMessages(engine.view().messages)).toHaveLength(1)
+    engine.stop()
+  })
+
+  test("2. echo determinism: folding the echo does not change rendered messages", async () => {
+    const server = new FakeSessionServer("ses_echo")
+    const engine = await Engine.createSessionEngine(server.sessionID, server, { now: () => server.time })
+    await engine.ready()
+
+    // The "echo" is the server's inbox.enqueued event for our own submit:
+    // folding it over the optimistic render must be invisible — no flicker.
+    engine.submit({ id: "msg_1", text: "instant" })
+    const before = engine.view().messages
+    await engine.settled()
+
+    expect(engine.view().messages).toEqual(before)
+    engine.stop()
+  })
+
+  test("3. sync opacity: the fold cannot see intents or the engine", () => {
+    const source = readFileSync(new URL("../src/solid/engine/fold.ts", import.meta.url), "utf8")
+    const code = source.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "")
+
+    expect(code).not.toMatch(/\boutbox\b/)
+    expect(code).not.toContain("./engine")
+    expect(code).not.toMatch(/\bintents?\b/i)
+  })
+
+  test("4. ordering: a burst admits in submission order", async () => {
+    const server = new FakeSessionServer("ses_ordering")
+    const engine = await Engine.createSessionEngine(server.sessionID, server)
+
+    for (const value of [1, 2, 3, 4, 5]) engine.submit({ id: `msg_${value}`, text: `m${value}` })
+    await engine.settled()
+
+    expect(server.admitted).toEqual(["msg_1", "msg_2", "msg_3", "msg_4", "msg_5"])
+    engine.stop()
+  })
+
+  test("5. convergence: drained clients equal the server fold", async () => {
+    const server = new FakeSessionServer("ses_convergence")
+    const a = await Engine.createSessionEngine(server.sessionID, server, { makeID: () => "msg_a" })
+    const b = await Engine.createSessionEngine(server.sessionID, server, { makeID: () => "msg_b" })
+
+    a.submit({ text: "from a" })
+    b.submit({ text: "from b" })
+    await Promise.all([a.settled(), b.settled()])
+    await until(() => a.view().seq === server.seq() && b.view().seq === server.seq())
+
+    expect(a.view()).toEqual(server.truth())
+    expect(b.view()).toEqual(server.truth())
+    a.stop()
+    b.stop()
+  })
+
+  test("6. failure atomicity: typed rejection removes and surfaces the intent", async () => {
+    const server = new FakeSessionServer("ses_failure")
+    server.faults.reject = 1
+    const engine = await Engine.createSessionEngine(server.sessionID, server)
+    const failures: Array<Engine.IntentFailure> = []
+    engine.subscribeFailures((failure) => failures.push(failure))
+    const before = engine.view()
+
+    const intent = engine.submit({ id: "msg_1", text: "doomed" })
+    expect(userMessages(engine.view().messages)).toHaveLength(1)
+    await until(() => failures.length === 1)
+
+    expect(engine.view()).toEqual(before)
+    expect(failures).toEqual([{ intent, reason: "rejected" }])
+    engine.stop()
+  })
+
+  test("7. lossy history: reconnect without retained events recovers via snapshot", async () => {
+    const server = new FakeSessionServer("ses_lossy")
+    const gate = reconnectGate()
+    const engine = await Engine.createSessionEngine(server.sessionID, server, {
+      now: () => server.time,
+      reconnect: gate.reconnect,
+    })
+    engine.submit({ id: "msg_1", text: "first" })
+    await engine.settled()
+
+    server.cutConnections()
+    await until(gate.holding)
+    // While disconnected the session advances, then history is dropped: the
+    // reconnect cursor cannot be replayed and must recover via snapshot.
+    await server.submit({ id: "msg_2", sessionID: server.sessionID, request: { text: "second" } })
+    server.prune()
+    gate.release()
+
+    await until(() => engine.view().seq === 2)
+    expect(engine.view()).toEqual(server.truth())
+    engine.stop()
+  })
+
+  test("8. attach gaps: a synced marker past the fold forces snapshot recovery", async () => {
+    const server = new FakeSessionServer("ses_marker_gap")
+    await server.submit({ id: "msg_1", sessionID: server.sessionID, request: { text: "hello" } })
+    const stale = { ...server.snapshotValue(), messages: [], inbox: [], seq: 0 }
+    let attempts = 0
+    const engine = await Engine.createSessionEngine(
+      server.sessionID,
+      {
+        snapshot: (sessionID) => (attempts === 0 ? Promise.resolve(stale) : server.snapshot(sessionID)),
+        async *stream(sessionID, after, signal) {
+          attempts++
+          if (attempts === 1) {
+            // Dishonest attach: the marker admits the cursor but skips the replay range.
+            yield { type: "log.synced" as const, aggregateID: sessionID, seq: server.snapshotValue().seq }
+            return
+          }
+          yield* server.stream(sessionID, after, signal)
+        },
+        submit: (input) => server.submit(input),
+      },
+      { reconnect: async () => {} },
+    )
+    await engine.ready()
+
+    expect(attempts).toBe(2)
+    expect(engine.view()).toEqual(server.truth())
+    engine.stop()
+  })
+
+  test("9. outage recovery: failed recovery snapshots retry until the server returns", async () => {
+    const server = new FakeSessionServer("ses_outage")
+    const gate = reconnectGate()
+    const engine = await Engine.createSessionEngine(server.sessionID, server, {
+      now: () => server.time,
+      reconnect: gate.reconnect,
+    })
+    engine.submit({ id: "msg_1", text: "first" })
+    await engine.settled()
+
+    server.cutConnections()
+    await until(gate.holding)
+    // A server restart while disconnected: history is gone, and the server
+    // stays unreachable for the first snapshot attempts of the recovery.
+    await server.submit({ id: "msg_2", sessionID: server.sessionID, request: { text: "second" } })
+    server.prune()
+    server.faults.loseSnapshots = 3
+    gate.release()
+
+    await until(() => engine.view().seq === 2)
+    expect(server.faults.loseSnapshots).toBe(0)
+    expect(engine.view()).toEqual(server.truth())
+    engine.stop()
+  })
+
+  test("10. refresh monotonicity: a stale snapshot refresh cannot move the fold behind the live log", async () => {
+    const server = new FakeSessionServer("ses_refresh_race")
+    const stale = server.snapshotValue()
+    let refresh = false
+    const transport: Engine.SessionTransport = {
+      snapshot: (sessionID) => (refresh ? Promise.resolve(stale) : server.snapshot(sessionID)),
+      stream: (sessionID, after) => server.stream(sessionID, after),
+      submit: (input) => server.submit(input),
+    }
+    const engine = await Engine.createSessionEngine(server.sessionID, transport)
+    await engine.ready()
+
+    engine.submit({ id: "msg_1", text: "newer than snapshot" })
+    await until(() => engine.view().seq === 1)
+    refresh = true
+    await engine.refresh()
+
+    expect(engine.view().seq).toBe(1)
+    // ...and the un-echoed intent survives the rejected refresh.
+    expect(engine.view().pending.map((item) => item.id)).toEqual(["msg_1"])
+    engine.stop()
+  })
+})
@@ -0,0 +1,127 @@
+// Seeded chaos simulation: two engine clients share one FakeSessionServer
+// while every fault the fixture can inject is thrown at them at random, then
+// all faults heal and both clients must converge exactly to the server's
+// truth. This stress-tests the laws of test/sync-engine-laws.test.ts in
+// combination; failures reproduce deterministically from the seed.
+import { describe, expect, test } from "bun:test"
+import { Engine } from "../src/solid/engine/engine"
+import { FakeSessionServer, until, userMessages } from "./fixture/sync-engine"
+
+type Client = {
+  readonly name: string
+  readonly engine: Engine.SessionEngine
+  readonly submitted: Array<string>
+  readonly rejected: Set<string>
+  readonly views: Array<Engine.SessionView>
+}
+
+describe("session sync engine simulation", () => {
+  for (const seed of [1, 2, 3, 42, 1337, 90210]) {
+    test(`seed ${seed}: two clients converge through chaotic transport faults`, async () => {
+      const random = mulberry32(seed)
+      const server = new FakeSessionServer(`ses_sim_${seed}`)
+      const clients = await Promise.all([makeClient("a", server), makeClient("b", server)])
+
+      // Chaos phase. Per step: 45% submit from a random client, 10% cut all
+      // connections, 10% lose a response, 8% lose a burst of requests,
+      // 7% reject an admission, 7% lose a snapshot fetch, 13% shift latency.
+      for (let step = 0; step < 80; step++) {
+        const roll = random()
+        if (roll < 0.45) {
+          const client = pick(clients, random)
+          const intent = client.engine.submit({ text: `step-${step}` })
+          client.submitted.push(intent.id)
+        } else if (roll < 0.55) {
+          server.cutConnections()
+        } else if (roll < 0.65) {
+          server.faults.loseResponses++
+        } else if (roll < 0.73) {
+          server.faults.loseRequests += 1 + Math.floor(random() * 2)
+        } else if (roll < 0.8) {
+          server.faults.reject++
+        } else if (roll < 0.87) {
+          server.faults.loseSnapshots++
+        } else {
+          server.faults.latency = Math.floor(random() * 6)
+        }
+        await advance(2 + Math.floor(random() * 8))
+      }
+
+      // Drain phase: heal all faults, then repeatedly cut connections —
+      // reconnecting is what makes the engine resend intents whose responses
+      // were lost, so every submitted ID ends up admitted or rejected.
+      server.heal()
+      for (let attempt = 0; attempt < 100; attempt++) {
+        server.cutConnections()
+        await advance(4)
+        const accounted = clients.every(
+          (client) =>
+            client.submitted.filter((id) => server.admitted.includes(id) || client.rejected.has(id)).length ===
+            client.submitted.length,
+        )
+        if (accounted) break
+      }
+      await until(
+        () => clients.every((client) => client.engine.view().seq === server.seq()),
+        `seed ${seed} did not converge`,
+      )
+
+      expect(new Set(server.admitted).size).toBe(server.admitted.length)
+      for (const client of clients) {
+        const expected = client.submitted.filter((id) => !client.rejected.has(id))
+        const observed = server.admitted.filter((id) => client.submitted.includes(id))
+        expect(observed).toEqual(expected)
+        expect(client.engine.view()).toEqual(server.truth())
+        assertNoFlicker(client.views, server.admitted, `${seed}/${client.name}`)
+        client.engine.stop()
+      }
+    })
+  }
+})
+
+async function makeClient(name: string, server: FakeSessionServer): Promise<Client> {
+  let counter = 0
+  const engine = await Engine.createSessionEngine(server.sessionID, server, {
+    makeID: () => `msg_${name}${String(++counter).padStart(4, "0")}`,
+    now: () => server.time,
+    reconnect: async () => {},
+  })
+  const client: Client = { name, engine, submitted: [], rejected: new Set(), views: [engine.view()] }
+  engine.subscribe((view) => client.views.push(view))
+  engine.subscribeFailures((failure) => client.rejected.add(failure.intent.id))
+  return client
+}
+
+// Once an admitted message first renders, it appears exactly once in every
+// subsequent view — it never disappears or duplicates.
+function assertNoFlicker(views: ReadonlyArray<Engine.SessionView>, admitted: ReadonlyArray<string>, label: string) {
+  for (const id of admitted) {
+    const first = views.findIndex((view) => userMessages(view.messages).some((message) => message.id === id))
+    expect(first, `${label}: ${id} never rendered`).toBeGreaterThanOrEqual(0)
+    for (const view of views.slice(first)) {
+      const rows = userMessages(view.messages).filter((message) => message.id === id)
+      expect(rows, `${label}: ${id} disappeared or duplicated`).toHaveLength(1)
+    }
+  }
+}
+
+// One "step" is one microtask turn — each fixture `pause()` under
+// `faults.latency` consumes one — followed by a macrotask flush.
+async function advance(steps: number) {
+  for (let step = 0; step < steps; step++) await Promise.resolve()
+  await Bun.sleep(0)
+}
+
+function pick<Value>(values: ReadonlyArray<Value>, random: () => number) {
+  return values[Math.floor(random() * values.length)]!
+}
+
+function mulberry32(seed: number) {
+  return () => {
+    seed |= 0
+    seed = (seed + 0x6d2b79f5) | 0
+    const first = Math.imul(seed ^ (seed >>> 15), 1 | seed)
+    const second = (first + Math.imul(first ^ (first >>> 7), 61 | first)) ^ first
+    return ((second ^ (second >>> 14)) >>> 0) / 4294967296
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./tsconfig.json",
+  "include": [
+    "src",
+    "script",
+    "test/fixture",
+    "test/engine-data.test.ts",
+    "test/legacy-divergence.test.ts",
+    "test/sync-engine-laws.test.ts",
+    "test/sync-engine-sim.test.ts"
+  ]
+}
@@ -27,7 +27,7 @@ export function map(input: MapInput): Mapping | undefined {
          ...baseSettings,
          ...mapAPIKey(input.settings),
          ...(typeof input.settings.authToken === "string" ? { authToken: input.settings.authToken } : {}),
-          ...mapProviderOptions(input.settings, ["apiKey", "authToken", "baseURL"]),
+          ...mapAnthropicOptions(input.settings),
        },
      }
    case "@ai-sdk/amazon-bedrock":
@@ -89,8 +89,10 @@ export function map(input: MapInput): Mapping | undefined {
          ...(isRecord(input.settings.thinking) || typeof input.settings.effort === "string"
            ? {
                providerOptions: {
-                  ...(isRecord(input.settings.thinking) ? { thinking: input.settings.thinking } : {}),
-                  ...(typeof input.settings.effort === "string" ? { effort: input.settings.effort } : {}),
+                  anthropic: {
+                    ...(isRecord(input.settings.thinking) ? { thinking: input.settings.thinking } : {}),
+                    ...(typeof input.settings.effort === "string" ? { effort: input.settings.effort } : {}),
+                  },
                },
              }
            : {}),
@@ -106,7 +108,13 @@ export function map(input: MapInput): Mapping | undefined {
          ...(typeof input.settings.organization === "string" ? { organization: input.settings.organization } : {}),
          ...(typeof input.settings.project === "string" ? { project: input.settings.project } : {}),
          ...(isStringRecord(input.settings.queryParams) ? { queryParams: input.settings.queryParams } : {}),
-          ...mapProviderOptions(input.settings, ["apiKey", "baseURL", "organization", "project", "queryParams"]),
+          ...mapProviderOptions(input.settings, "openai", [
+            "apiKey",
+            "baseURL",
+            "organization",
+            "project",
+            "queryParams",
+          ]),
        },
      }
    case "@ai-sdk/openai-compatible":
@@ -117,7 +125,7 @@ export function map(input: MapInput): Mapping | undefined {
          ...baseSettings,
          ...mapAPIKey(input.settings),
          provider: input.providerID,
-          ...mapProviderOptions(input.settings, ["apiKey", "baseURL"]),
+          ...mapProviderOptions(input.settings, "openai", ["apiKey", "baseURL"]),
        },
      }
    case "@openrouter/ai-sdk-provider":
@@ -134,10 +142,18 @@ export function map(input: MapInput): Mapping | undefined {
  }
 }

-function mapProviderOptions(settings: Readonly<Record<string, unknown>>, excluded: ReadonlyArray<string>) {
+function mapAnthropicOptions(settings: Readonly<Record<string, unknown>>) {
+  return mapProviderOptions(settings, "anthropic", ["apiKey", "authToken", "baseURL"])
+}
+
+function mapProviderOptions(
+  settings: Readonly<Record<string, unknown>>,
+  key: string,
+  excluded: ReadonlyArray<string>,
+) {
  const options = Object.fromEntries(Object.entries(settings).filter(([name]) => !excluded.includes(name)))
  if (Object.keys(options).length === 0) return {}
-  return { providerOptions: options }
+  return { providerOptions: { [key]: options } }
 }

 function mapBedrockMantle(input: MapInput, baseSettings: Readonly<Record<string, unknown>>): Mapping | undefined {
@@ -270,7 +286,7 @@ function mapOpenAIOptions(settings: Readonly<Record<string, unknown>>) {
    ...(typeof settings.serviceTier === "string" ? { serviceTier: settings.serviceTier } : {}),
  }
  if (Object.keys(options).length === 0) return {}
-  return { providerOptions: options }
+  return { providerOptions: { openai: options } }
 }

 function mapBaseSettings(settings: Readonly<Record<string, unknown>>) {
@@ -301,7 +317,7 @@ function mapGoogleOptions(settings: Readonly<Record<string, unknown>>, extra: Re
    ...extra,
  }
  if (Object.keys(options).length === 0) return {}
-  return { providerOptions: options }
+  return { providerOptions: { gemini: options } }
 }

 function mapOpenRouter(
@@ -353,7 +369,7 @@ function mapOpenRouterOptions(settings: Readonly<Record<string, unknown>>) {
    ),
  )
  if (Object.keys(options).length === 0) return {}
-  return { providerOptions: options }
+  return { providerOptions: { openrouter: options } }
 }

 function isStringRecord(value: unknown): value is Readonly<Record<string, string>> {
@@ -366,5 +382,5 @@ function mapXAIOptions(settings: Readonly<Record<string, unknown>>) {
    ...(typeof settings.store === "boolean" ? { store: settings.store } : {}),
  }
  if (Object.keys(options).length === 0) return {}
-  return { providerOptions: options }
+  return { providerOptions: { xai: options } }
 }
@@ -307,6 +307,12 @@ function modelFromLanguage(info: Info, language: LanguageModelV3) {
  const packageName = Provider.packageName(info.package!)
  const projected = mapBodyToProviderOptions(info, packageName)
  const optionKey = providerOptionKey(packageName, info.providerID)
+  const providerOptions = (() => {
+    if (projected.settings === undefined) return
+    if (packageName === "@ai-sdk/gateway") return gatewayProviderOptions(info.modelID ?? info.id, projected.settings)
+    if (packageName === "@ai-sdk/azure") return { openai: projected.settings, azure: projected.settings }
+    return { [optionKey]: projected.settings }
+  })()
  const route: AnyRoute = {
    id: `ai-sdk:${packageName}`,
    provider: ProviderID.make(info.providerID),
@@ -329,11 +335,11 @@ function modelFromLanguage(info: Info, language: LanguageModelV3) {
              headers: info.headers,
            },
      limits: { context: info.limit.context, input: info.limit.input, output: info.limit.output },
-      providerOptions: projected.settings,
+      providerOptions,
    },
    body: {
      schema: Schema.Unknown,
-      from: (request) => Effect.succeed(callOptions(request, packageName, info.modelID ?? info.id, optionKey)),
+      from: (request) => Effect.succeed(callOptions(request)),
    },
    with: () => route,
    model: (input) =>
@@ -408,12 +414,7 @@ function mapBodyToProviderOptions(model: Info, packageName: string) {
  }
 }

-function callOptions(
-  request: LLMRequest,
-  packageName: string | undefined,
-  modelID: ID,
-  optionKey: string,
-): LanguageModelV3CallOptions {
+function callOptions(request: LLMRequest): LanguageModelV3CallOptions {
  return {
    prompt: prompt(request),
    maxOutputTokens: request.generation?.maxTokens,
@@ -427,7 +428,7 @@ function callOptions(
    tools: request.tools.map(tool),
    toolChoice: toolChoice(request.toolChoice),
    headers: request.http?.headers,
-    providerOptions: requestProviderOptions(request.providerOptions, packageName, modelID, optionKey),
+    providerOptions: providerOptions(request.providerOptions),
  }
 }

@@ -525,7 +526,7 @@ function assistantPart(part: ContentPart): AssistantContent {
    case "media":
      return [{ type: "file", mediaType: part.mediaType, data: part.data, filename: part.filename }]
    case "reasoning":
-      return [{ type: "reasoning", text: part.text, providerOptions: metadataProviderOptions(part.providerMetadata) }]
+      return [{ type: "reasoning", text: part.text, providerOptions: providerOptions(part.providerMetadata) }]
    case "tool-call":
      return [
        {
@@ -534,7 +535,7 @@ function assistantPart(part: ContentPart): AssistantContent {
          toolName: part.name,
          input: part.input,
          providerExecuted: part.providerExecuted,
-          providerOptions: metadataProviderOptions(part.providerMetadata),
+          providerOptions: providerOptions(part.providerMetadata),
        },
      ]
    case "tool-result":
@@ -550,7 +551,7 @@ function toolResultPart(part: ContentPart): ToolResultContent[] {
      toolCallId: part.id,
      toolName: part.name,
      output: toolOutput(part.result),
-      providerOptions: metadataProviderOptions(part.providerMetadata),
+      providerOptions: providerOptions(part.providerMetadata),
    },
  ]
 }
@@ -594,20 +595,7 @@ function toolChoice(input: LLMRequest["toolChoice"]): LanguageModelV3ToolChoice
  return { type: input.type }
 }

-function requestProviderOptions(
-  input: LLMRequest["providerOptions"],
-  packageName: string | undefined,
-  modelID: ID,
-  optionKey: string,
-): SharedV3ProviderOptions | undefined {
-  if (!input) return undefined
-  const options = jsonObject(input)
-  if (packageName === "@ai-sdk/gateway") return gatewayProviderOptions(modelID, options)
-  if (packageName === "@ai-sdk/azure") return { openai: options, azure: options }
-  return { [optionKey]: options }
-}
-
-function metadataProviderOptions(input: ProviderMetadata | undefined): SharedV3ProviderOptions | undefined {
+function providerOptions(input: LLMRequest["providerOptions"]): SharedV3ProviderOptions | undefined {
  if (!input) return undefined
  return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, jsonObject(value)]))
 }
@@ -44,6 +44,21 @@ export const reserveSequence = Effect.fn("Bus.reserveSequence")(function* (
    .pipe(Effect.orDie)
 })

+export const retainedCount = Effect.fn("Bus.retainedCount")(function* (
+  db: Database.Interface["db"],
+  aggregateID: string,
+  after: number,
+  through: number,
+) {
+  const row = yield* db
+    .select({ count: sql<number>`count(*)` })
+    .from(EventTable)
+    .where(and(eq(EventTable.aggregate_id, aggregateID), gt(EventTable.seq, after), lte(EventTable.seq, through)))
+    .get()
+    .pipe(Effect.orDie)
+  return row?.count ?? 0
+})
+
 export type SerializedEvent = {
  readonly id: Event.ID
  readonly type: string
@@ -150,6 +165,7 @@ export interface Interface {
    readonly aggregateID: string
    readonly after?: number
    readonly follow?: boolean
+    readonly includeLive?: (event: Event.Payload) => boolean
  }) => Stream.Stream<LogItem>
  /** @deprecated Use `subscribe()` and consume the returned stream. */
  readonly listen: (listener: Subscriber) => Effect.Effect<Unsubscribe>
@@ -768,6 +784,7 @@ export function configured(options?: Options) {
          readonly aggregateID: string
          readonly after?: number
          readonly follow?: boolean
+          readonly includeLive?: (event: Event.Payload) => boolean
        }): Stream.Stream<LogItem> =>
          Stream.unwrap(
            Effect.gen(function* () {
@@ -791,7 +808,8 @@ export function configured(options?: Options) {
                )
              // Subscribing before the historical read means events committed during
              // replay either appear in the read or arrive through a post-marker wake.
-              const wakes = input.follow ? yield* subscribeDurable(input.aggregateID) : undefined
+              const subscription = input.follow && input.includeLive ? yield* PubSub.subscribe(pubsub.live) : undefined
+              const wakes = input.follow && !subscription ? yield* subscribeDurable(input.aggregateID) : undefined
              const target = yield* latestSequence(db, input.aggregateID)
              const marker: EventLog.Synced = {
                type: "log.synced",
@@ -802,6 +820,14 @@ export function configured(options?: Options) {
                Stream.map((event): LogItem => event),
                Stream.concat(Stream.make(marker)),
              )
+              if (subscription && input.includeLive) {
+                const follow: Stream.Stream<LogItem> = Stream.fromSubscription(subscription).pipe(
+                  Stream.filter(input.includeLive),
+                  Stream.filter((event) => !event.durable || event.durable.seq > target),
+                  Stream.map((event): LogItem => event),
+                )
+                return Stream.concat(replay, follow)
+              }
              if (!wakes) return replay
              const live: Stream.Stream<LogItem> = Stream.fromSubscription(wakes).pipe(
                Stream.mapEffect(() => latestSequence(db, input.aggregateID)),
@@ -141,6 +141,11 @@ export class InboxConflictError extends Schema.TaggedError<InboxConflictError>()
  sessionID: SessionSchema.ID,
  inboxID: SessionMessage.ID,
 }) {}
+export class SeqUnavailableError extends Schema.TaggedError<SeqUnavailableError>()("Session.SeqUnavailableError", {
+  sessionID: SessionSchema.ID,
+  after: Event.Seq,
+  head: Schema.optional(Event.Seq),
+}) {}
 type InboxItemRef = { readonly sessionID: SessionSchema.ID; readonly inboxID: SessionMessage.ID }
 export class SkillNotFoundError extends Schema.TaggedError<SkillNotFoundError>()("Session.SkillNotFoundError", {
  skill: Skill.ID,
@@ -194,13 +199,33 @@ export interface Interface {
   * unhandled compaction barriers.
   */
  readonly inbox: (sessionID: SessionSchema.ID) => Effect.Effect<SessionInbox.Info[], NotFoundError>
+  readonly snapshot: (input: {
+    sessionID: SessionSchema.ID
+    recent?: number
+  }) => Effect.Effect<
+    {
+      readonly session: SessionSchema.Info
+      readonly children: SessionSchema.Info[]
+      readonly inbox: SessionInbox.Info[]
+      readonly messages: SessionMessage.Info[]
+      readonly seq: Event.Seq
+    },
+    NotFoundError | MessageDecodeError
+  >
  readonly cancelInbox: (input: InboxItemRef) => Effect.Effect<void, NotFoundError | InboxConflictError>
  readonly steerInbox: (input: InboxItemRef) => Effect.Effect<void, NotFoundError | InboxConflictError>
  readonly queueInbox: (input: InboxItemRef) => Effect.Effect<void, NotFoundError | InboxConflictError>
+  readonly openLog: (input: {
+    sessionID: SessionSchema.ID
+    after?: number
+    follow?: boolean
+    ephemeral?: boolean
+  }) => Effect.Effect<Stream.Stream<SessionEvent.Event | EventLog.Synced>, NotFoundError | SeqUnavailableError>
  /**
-   * Durable, ordered session log read. Replays durable session bus after
-   * the exclusive `after` cursor, emits a `Synced` marker at the captured
-   * replay watermark, then continues live when `follow` is set.
+   * Ordered session log read. Replays durable session events after the
+   * exclusive `after` cursor, emits a `Synced` marker at the captured replay
+   * watermark, then continues live when `follow` is set. Ephemeral events are
+   * included only in the live phase when explicitly requested.
   * The marker's seq may exceed the last emitted event because other durable
   * bus share the aggregate's sequence space.
   */
@@ -208,7 +233,8 @@ export interface Interface {
    sessionID: SessionSchema.ID
    after?: number
    follow?: boolean
-  }) => Stream.Stream<SessionEvent.DurableEvent | EventLog.Synced, NotFoundError>
+    ephemeral?: boolean
+  }) => Stream.Stream<SessionEvent.Event | EventLog.Synced, NotFoundError | SeqUnavailableError>
  readonly switchAgent: (input: { sessionID: SessionSchema.ID; agent: Agent.ID }) => Effect.Effect<void, NotFoundError>
  readonly switchModel: (input: { sessionID: SessionSchema.ID; model: Model.Ref }) => Effect.Effect<void, NotFoundError>
  readonly rename: (input: { sessionID: SessionSchema.ID; title: string }) => Effect.Effect<void, NotFoundError>
@@ -222,7 +248,6 @@ export interface Interface {
    id?: SessionMessage.ID
    sessionID: SessionSchema.ID
    text: string
-    command?: Prompt["command"]
    files?: PromptInput.Prompt["files"]
    agents?: PromptInput.Prompt["agents"]
    skills?: PromptInput.Prompt["skills"]
@@ -327,6 +352,7 @@ const layer = Layer.effect(
    })
    const decodeMessage = Schema.decodeUnknownEffect(SessionMessage.Info)
    const isDurableSessionEvent = Schema.is(SessionEvent.Durable)
+    const isSessionEvent = Schema.is(SessionEvent.All)
    const persistProject = (project: Project.Resolved) => upsertProject(db, project).pipe(Effect.orDie)
    const decode = (row: typeof SessionMessageTable.$inferSelect) =>
      decodeMessage({ ...row.data, id: row.id, type: row.type }).pipe(
@@ -558,20 +584,90 @@ const layer = Layer.effect(
        yield* result.get(sessionID)
        return yield* SessionInbox.list(db, sessionID)
      }),
+      snapshot: Effect.fn("Session.snapshot")(function* (input) {
+        return yield* db
+          .transaction(() =>
+            Effect.gen(function* () {
+              const row = yield* db
+                .select()
+                .from(SessionTable)
+                .where(eq(SessionTable.id, input.sessionID))
+                .get()
+                .pipe(Effect.orDie)
+              if (!row) return yield* new NotFoundError({ sessionID: input.sessionID })
+              const children = yield* db
+                .select()
+                .from(SessionTable)
+                .where(eq(SessionTable.parent_id, input.sessionID))
+                .orderBy(desc(SessionTable.time_updated), desc(SessionTable.id))
+                .all()
+                .pipe(Effect.orDie)
+              const inbox = yield* SessionInbox.list(db, input.sessionID)
+              const messages = yield* db
+                .select()
+                .from(SessionMessageTable)
+                .where(eq(SessionMessageTable.session_id, input.sessionID))
+                .orderBy(desc(SessionMessageTable.seq))
+                .limit(input.recent ?? 200)
+                .all()
+                .pipe(Effect.orDie)
+              const seq = yield* Bus.latestSequence(db, input.sessionID)
+              if (seq < 0) return yield* Effect.die(new Error(`Session ${input.sessionID} has no event sequence`))
+              return {
+                session: fromRow(row),
+                children: children.map(fromRow),
+                inbox,
+                messages: yield* Effect.forEach(messages.toReversed(), decode),
+                seq: Event.Seq.make(seq),
+              }
+            }),
+          )
+          .pipe(Effect.catchTag("SqlError", Effect.die))
+      }),
      cancelInbox: Effect.fn("Session.cancelInbox")((input) => mutatePending(input, SessionInbox.cancel)),
      steerInbox: Effect.fn("Session.steerInbox")((input) => mutatePending(input, SessionInbox.steer, true)),
      queueInbox: Effect.fn("Session.queueInbox")((input) => mutatePending(input, SessionInbox.queue)),
-      log: (input) =>
-        Stream.unwrap(
-          result
-            .get(input.sessionID)
-            .pipe(Effect.as(bus.log({ aggregateID: input.sessionID, after: input.after, follow: input.follow }))),
-        ).pipe(
-          Stream.filter(
-            (item): item is SessionEvent.DurableEvent | EventLog.Synced =>
-              Bus.isSynced(item) || isDurableSessionEvent(item),
-          ),
-        ),
+      openLog: Effect.fn("Session.openLog")(function* (input) {
+        yield* result.get(input.sessionID)
+        if (input.after !== undefined) {
+          const head = yield* Bus.latestSequence(db, input.sessionID)
+          if (input.after > head)
+            return yield* new SeqUnavailableError({
+              sessionID: input.sessionID,
+              after: Event.Seq.make(input.after),
+              head: head >= 0 ? Event.Seq.make(head) : undefined,
+            })
+          // A cursor claims the caller already holds everything through `after`, so
+          // replay of (after, head] must be provably complete. Without retained rows
+          // covering the range (events.persist off, or pruned history) replaying
+          // nothing would silently desync the caller; fail so it re-snapshots instead.
+          if (input.after < head) {
+            const retained = yield* Bus.retainedCount(db, input.sessionID, input.after, head)
+            if (retained < head - input.after)
+              return yield* new SeqUnavailableError({
+                sessionID: input.sessionID,
+                after: Event.Seq.make(input.after),
+                head: Event.Seq.make(head),
+              })
+          }
+        }
+        return bus
+          .log({
+            aggregateID: input.sessionID,
+            after: input.after,
+            follow: input.follow,
+            includeLive: input.ephemeral
+              ? (event) => isSessionEvent(event) && event.data.sessionID === input.sessionID
+              : undefined,
+          })
+          .pipe(
+            Stream.filter(
+              (item): item is SessionEvent.Event | EventLog.Synced =>
+                Bus.isSynced(item) || (input.ephemeral ? isSessionEvent(item) : isDurableSessionEvent(item)),
+            ),
+          )
+      }),
+      log: (input) => Stream.unwrap(result.openLog(input)),
      prompt: Effect.fn("Session.prompt")((input) =>
        Effect.uninterruptible(
          Effect.gen(function* () {
@@ -587,7 +683,11 @@ const layer = Layer.effect(
              return yield* Image.Service
            }).pipe(Effect.provide(locations.get(session.location)))
            const skills = Skill.Service.pipe(Effect.provide(locations.get(session.location)))
-            const prompt = yield* resolvePrompt(input, image, skills).pipe(Effect.provideService(FSUtil.Service, fs))
+            const prompt = yield* resolvePrompt(
+              { text: input.text, files: input.files, agents: input.agents, skills: input.skills },
+              image,
+              skills,
+            ).pipe(Effect.provideService(FSUtil.Service, fs))
            const messageID = input.id ?? SessionMessage.ID.create()
            const admittedInput = SessionInbox.Item.make({
              type: "user",
@@ -654,7 +754,6 @@ const layer = Layer.effect(
          id: input.id,
          sessionID: input.sessionID,
          text: evaluated.text,
-          command: { name: input.command, arguments: input.arguments ?? "" },
          files: input.files,
          agents: input.agents,
          skills: input.skills,
@@ -962,7 +1061,7 @@ function synthesizeTerminalShellInfo(started: ShellSchema.Info): ShellSchema.Inf
 }

 const resolvePrompt = Effect.fn("Session.resolvePrompt")(function* (
-  input: PromptInput.Prompt & Pick<Prompt, "command">,
+  input: PromptInput.Prompt,
  image: Effect.Effect<Image.Interface>,
  skills: Effect.Effect<Skill.Interface>,
 ) {
@@ -985,13 +1084,7 @@ const resolvePrompt = Effect.fn("Session.resolvePrompt")(function* (
      })
    })
  })
-  return Prompt.fromUserMessage({
-    text: input.text,
-    command: input.command,
-    agents: input.agents,
-    files,
-    skills: selected?.length ? selected : undefined,
-  })
+  return Prompt.make({ text: input.text, agents: input.agents, files, skills: selected?.length ? selected : undefined })
 })

 const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024
@@ -20,7 +20,6 @@ import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Money } from "@opencode-ai/schema/money"
 import { Worktree } from "@opencode-ai/schema/worktree"
 import { Project } from "@opencode-ai/schema/project"
-import { Prompt } from "@opencode-ai/schema/prompt"
 import { AbsolutePath, RelativePath } from "../schema.js"
 import type { SessionSchema } from "./schema.js"

@@ -527,14 +526,17 @@ const layer = Layer.effectDiscard(
        yield* insertMessage(
          db,
          event,
-              input.type === "user"
-                ? {
-                    ...Prompt.fromUserMessage(input.payload),
-                    id: input.id,
-                    type: "user",
-                    metadata: input.payload.metadata,
-                    time: { created: DateTime.makeUnsafe(event.created) },
-                  }
+          input.type === "user"
+            ? {
+                id: input.id,
+                type: "user",
+                metadata: input.payload.metadata,
+                text: input.payload.text,
+                files: input.payload.files,
+                agents: input.payload.agents,
+                skills: input.payload.skills,
+                time: { created: DateTime.makeUnsafe(event.created) },
+              }
            : {
                id: input.id,
                type: "synthetic",
@@ -22,14 +22,16 @@ describe("AISDKNative", () => {
      settings: {
        apiKey: "secret",
        baseURL: "https://api.meta.ai/v1",
-        providerOptions: {
-          reasoningEffort: "xhigh",
-          reasoningSummary: "auto",
-          include: ["reasoning.encrypted_content"],
-          instructions: "Follow the repository instructions.",
-          truncation: "auto",
-        },
        organization: "org",
+        providerOptions: {
+          openai: {
+            reasoningEffort: "xhigh",
+            reasoningSummary: "auto",
+            include: ["reasoning.encrypted_content"],
+            instructions: "Follow the repository instructions.",
+            truncation: "auto",
+          },
+        },
      },
    })
    expect(map("@ai-sdk/openai-compatible", { baseURL: "https://example.com/v1", reasoningEffort: "high" })).toEqual({
@@ -37,7 +39,7 @@ describe("AISDKNative", () => {
      settings: {
        baseURL: "https://example.com/v1",
        provider: "test-provider",
-        providerOptions: { reasoningEffort: "high" },
+        providerOptions: { openai: { reasoningEffort: "high" } },
      },
    })
  })
@@ -56,8 +58,10 @@ describe("AISDKNative", () => {
        authToken: "token",
        baseURL: "https://anthropic.example/v1",
        providerOptions: {
-          thinking: { type: "adaptive", display: "summarized" },
-          effort: "high",
+          anthropic: {
+            thinking: { type: "adaptive", display: "summarized" },
+            effort: "high",
+          },
        },
      },
    })
@@ -77,8 +81,7 @@ describe("AISDKNative", () => {
        project: "project",
        location: "us-central1",
        providerOptions: {
-          labels: { environment: "test" },
-          thinkingConfig: { thinkingLevel: "high" },
+          gemini: { labels: { environment: "test" }, thinkingConfig: { thinkingLevel: "high" } },
        },
      },
    })
@@ -112,7 +115,7 @@ describe("AISDKNative", () => {
        apiVersion: "2025-01-01-preview",
        queryParams: { feature: "enabled" },
        useDeploymentBasedUrls: true,
-        providerOptions: { reasoningEffort: "high" },
+        providerOptions: { openai: { reasoningEffort: "high" } },
      },
    })
    expect(map("@ai-sdk/azure", { ...settings, useCompletionUrls: true }, "custom-deployment")?.package).toBe(
@@ -190,9 +193,11 @@ describe("AISDKNative", () => {
        baseURL: "https://mantle.test/v1",
        region: "us-west-2",
        providerOptions: {
-          reasoningEffort: "high",
-          reasoningSummary: "auto",
-          include: ["reasoning.encrypted_content"],
+          openai: {
+            reasoningEffort: "high",
+            reasoningSummary: "auto",
+            include: ["reasoning.encrypted_content"],
+          },
        },
      },
      headers: { "x-test": "value" },
@@ -241,7 +246,7 @@ describe("AISDKNative", () => {
          region: "eu-west-1",
        },
        baseURL: "https://bedrock-mantle.eu-west-1.api.aws/v1",
-        providerOptions: { store: false },
+        providerOptions: { openai: { store: false } },
      },
    })
  })
@@ -273,10 +278,12 @@ describe("AISDKNative", () => {
      package: "@opencode-ai/ai/providers/openrouter",
      settings: {
        providerOptions: {
-          models: ["anthropic/claude-sonnet-4.6"],
-          provider: { only: ["anthropic"], require_parameters: true },
-          reasoning: { effort: "high" },
-          future_option: { enabled: true },
+          openrouter: {
+            models: ["anthropic/claude-sonnet-4.6"],
+            provider: { only: ["anthropic"], require_parameters: true },
+            reasoning: { effort: "high" },
+            future_option: { enabled: true },
+          },
        },
      },
      headers: {
@@ -305,13 +312,15 @@ describe("AISDKNative", () => {
      package: "@opencode-ai/ai/providers/google",
      settings: {
        providerOptions: {
-          cachedContent: "cachedContents/example",
-          safetySettings: [{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" }],
-          serviceTier: "flex",
-          thinkingConfig: {
-            thinkingBudget: 0,
-            includeThoughts: false,
-            thinkingLevel: "high",
+          gemini: {
+            cachedContent: "cachedContents/example",
+            safetySettings: [{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" }],
+            serviceTier: "flex",
+            thinkingConfig: {
+              thinkingBudget: 0,
+              includeThoughts: false,
+              thinkingLevel: "high",
+            },
          },
        },
      },
@@ -321,7 +330,7 @@ describe("AISDKNative", () => {
  test("maps Google thinking settings independently", () => {
    for (const thinkingConfig of [{ thinkingBudget: -1 }, { includeThoughts: true }, { thinkingLevel: "medium" }]) {
      expect(map("@ai-sdk/google", { thinkingConfig })).toMatchObject({
-        settings: { providerOptions: { thinkingConfig } },
+        settings: { providerOptions: { gemini: { thinkingConfig } } },
      })
    }
  })
@@ -336,9 +345,11 @@ describe("AISDKNative", () => {
    ).toMatchObject({
      settings: {
        providerOptions: {
-          cachedContent: "cachedContents/example",
-          safetySettings: [{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" }],
-          serviceTier: "future-tier",
+          gemini: {
+            cachedContent: "cachedContents/example",
+            safetySettings: [{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" }],
+            serviceTier: "future-tier",
+          },
        },
      },
    })
@@ -363,8 +374,10 @@ describe("AISDKNative", () => {
        location: "eu",
        project: "vertex-project",
        providerOptions: {
-          labels: { component: "opencode", environment: "test" },
-          thinkingConfig: { thinkingLevel: "high" },
+          gemini: {
+            labels: { component: "opencode", environment: "test" },
+            thinkingConfig: { thinkingLevel: "high" },
+          },
        },
      },
      headers: { "x-test": "value" },
@@ -390,8 +403,10 @@ describe("AISDKNative", () => {
        location: "eu",
        project: "vertex-project",
        providerOptions: {
-          thinking: { type: "adaptive", display: "summarized" },
-          effort: "high",
+          anthropic: {
+            thinking: { type: "adaptive", display: "summarized" },
+            effort: "high",
+          },
        },
      },
      headers: { "x-test": "value" },
@@ -412,8 +427,10 @@ describe("AISDKNative", () => {
        apiKey: "secret",
        baseURL: "https://xai.example/v1",
        providerOptions: {
-          reasoningEffort: "custom",
-          store: true,
+          xai: {
+            reasoningEffort: "custom",
+            store: true,
+          },
        },
      },
    })
@@ -94,19 +94,10 @@ it.effect("projects request settings, headers, and body overlays", () =>
      headers: { "x-test": "header" },
      body: { safety_setting: "strict" },
    })
-    const prepared = yield* compileRequest(
-      LLM.request({
-        model: resolved,
-        prompt: "Hello",
-        providerOptions: { safetySettings: [{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" }] },
-      }),
-    )
+    const prepared = yield* compileRequest(LLM.request({ model: resolved, prompt: "Hello" }))

    expect(prepared.body.providerOptions).toEqual({
-      google: {
-        thinkingConfig: { thinkingBudget: 1024 },
-        safetySettings: [{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" }],
-      },
+      google: { thinkingConfig: { thinkingBudget: 1024 } },
    })
    expect(prepared.body.headers).toEqual({ "x-test": "header" })
    expect(body).toEqual({ safety_setting: "strict" })
@@ -2,7 +2,7 @@ import { describe, expect } from "bun:test"
 import { LLM, LanguageModel } from "@opencode-ai/ai"
 import { OpenAIChat } from "@opencode-ai/ai/protocols"
 import { compileRequest } from "@opencode-ai/ai/route/client"
-import { ConfigProvider, Effect, Layer } from "effect"
+import { Effect, Layer } from "effect"
 import { Headers } from "effect/unstable/http"
 import { Credential } from "@opencode-ai/core/credential"
 import { Integration } from "@opencode-ai/core/integration"
@@ -66,10 +66,6 @@ function withEnv<A, E, R>(variables: Record<string, string | undefined>, effect:
  )
 }

-function withConfigEnv<A, E, R>(env: Record<string, string>, effect: () => Effect.Effect<A, E, R>) {
-  return effect().pipe(Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env }))))
-}
-
 describe("ModelResolver", () => {
  it.effect("constructs native Azure requests with deployment IDs and projected resource URLs", () =>
    Effect.gen(function* () {
@@ -261,7 +257,7 @@ describe("ModelResolver", () => {
  )

  it.effect("treats an empty configured API key as omitted", () =>
-    withConfigEnv({ OPENAI_API_KEY: "environment-key" }, () =>
+    withEnv({ OPENAI_API_KEY: "environment-key" }, () =>
      Effect.gen(function* () {
        const resolved = yield* ModelResolver.fromCatalogModel(
          model(Provider.aisdk("@ai-sdk/openai"), {
@@ -341,7 +337,7 @@ describe("ModelResolver", () => {
    })
    const layer = ModelResolver.layer.pipe(Layer.provide(Layer.mergeAll(catalog, integrations, npm, aisdk)))

-    return withConfigEnv({}, () =>
+    return withEnv({ GOOGLE_GENERATIVE_AI_API_KEY: undefined }, () =>
      Effect.gen(function* () {
        const resolver = yield* ModelResolver.Service
        const resolved = yield* resolver.resolveModel(selected)
@@ -362,7 +358,7 @@ describe("ModelResolver", () => {
  })

  it.effect("keeps native provider environment auth strict when no API key is configured", () =>
-    withConfigEnv({}, () =>
+    withEnv({ GOOGLE_GENERATIVE_AI_API_KEY: undefined }, () =>
      Effect.gen(function* () {
        const resolved = yield* ModelResolver.fromCatalogModel(
          model(Provider.aisdk("@ai-sdk/google"), {
@@ -481,11 +477,7 @@ describe("ModelResolver", () => {
          },
        ],
      })
-      const resolved = yield* ModelResolver.resolveModel(
-        catalog,
-        VariantID.make("xhigh"),
-        Credential.Key.make({ type: "key", key: "secret" }),
-      )
+      const resolved = yield* ModelResolver.resolveModel(catalog, VariantID.make("xhigh"))

      expect(resolved.route.defaults.headers).toMatchObject({ "x-test": "header", "x-variant": "high" })
      expect(resolved.route.defaults.http?.body).toEqual({
@@ -495,10 +487,12 @@ describe("ModelResolver", () => {
        temperature: 0.2,
      })
      expect(resolved.route.defaults.providerOptions).toEqual({
-        store: false,
-        reasoningEffort: "xhigh",
-        reasoningSummary: "auto",
-        include: ["reasoning.encrypted_content"],
+        openai: {
+          store: false,
+          reasoningEffort: "xhigh",
+          reasoningSummary: "auto",
+          include: ["reasoning.encrypted_content"],
+        },
      })
      const prepared = yield* compileRequest(LLM.request({ model: resolved, prompt: "Hello" }))
      expect(prepared.body).toMatchObject({
@@ -567,7 +561,7 @@ describe("ModelResolver", () => {
        custom_extension: { enabled: true },
      })
      expect(resolved.route.defaults.providerOptions).toEqual({
-        thinking: { type: "enabled", budgetTokens: 12000 },
+        anthropic: { thinking: { type: "enabled", budgetTokens: 12000 } },
      })
    }),
  )
@@ -849,46 +843,48 @@ describe("ModelResolver", () => {
            include: ["reasoning.encrypted_content"],
          },
          {
-            reasoningEffort: "xhigh",
-            reasoningSummary: "auto",
-            include: ["reasoning.encrypted_content"],
+            openai: {
+              reasoningEffort: "xhigh",
+              reasoningSummary: "auto",
+              include: ["reasoning.encrypted_content"],
+            },
          },
        ],
        [
          "@ai-sdk/anthropic",
          "@opencode-ai/ai/providers/anthropic",
          { thinking: { type: "adaptive", display: "summarized" }, effort: "high" },
-          { thinking: { type: "adaptive", display: "summarized" }, effort: "high" },
+          { anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "high" } },
        ],
        [
          "@ai-sdk/openai-compatible",
          "@opencode-ai/ai/providers/openai-compatible",
          { reasoningEffort: "high" },
-          { reasoningEffort: "high" },
+          { openai: { reasoningEffort: "high" } },
        ],
        [
          "@ai-sdk/google",
          "@opencode-ai/ai/providers/google",
          { thinkingConfig: { thinkingLevel: "high" } },
-          { thinkingConfig: { thinkingLevel: "high" } },
+          { gemini: { thinkingConfig: { thinkingLevel: "high" } } },
        ],
        [
          "@ai-sdk/google-vertex",
          "@opencode-ai/ai/providers/google-vertex",
          { thinkingConfig: { thinkingLevel: "high" } },
-          { thinkingConfig: { thinkingLevel: "high" } },
+          { gemini: { thinkingConfig: { thinkingLevel: "high" } } },
        ],
        [
          "@openrouter/ai-sdk-provider",
          "@opencode-ai/ai/providers/openrouter",
          { reasoning: { effort: "high" } },
-          { reasoning: { effort: "high" } },
+          { openrouter: { reasoning: { effort: "high" } } },
        ],
        [
          "@ai-sdk/xai",
          "@opencode-ai/ai/providers/xai",
          { reasoningEffort: "high" },
-          { reasoningEffort: "high" },
+          { xai: { reasoningEffort: "high" } },
        ],
      ] as const

@@ -1004,8 +1000,10 @@ describe("ModelResolver", () => {
                  location: "eu",
                  project: "vertex-project",
                  providerOptions: {
-                    thinking: { type: "adaptive", display: "summarized" },
-                    effort: "high",
+                    anthropic: {
+                      thinking: { type: "adaptive", display: "summarized" },
+                      effort: "high",
+                    },
                  },
                })
                return LanguageModel.make({ id: modelID, provider: "native-provider", route: native.route })
@@ -1078,11 +1076,15 @@ describe("ModelResolver", () => {
      )

      expect(google.route.id).toBe("gemini")
-      expect(google.route.defaults.providerOptions).toEqual({ thinkingConfig: { thinkingBudget: 1_024 } })
+      expect(google.route.defaults.providerOptions).toEqual({
+        gemini: { thinkingConfig: { thinkingBudget: 1_024 } },
+      })
      expect(openrouter.route.id).toBe("openrouter")
-      expect(openrouter.route.defaults.providerOptions).toEqual({ reasoning: { effort: "high" } })
+      expect(openrouter.route.defaults.providerOptions).toEqual({ openrouter: { reasoning: { effort: "high" } } })
      expect(xai.route.id).toBe("openai-responses")
-      expect(xai.route.defaults.providerOptions).toEqual({ reasoningEffort: "high", store: false })
+      expect(xai.route.defaults.providerOptions).toEqual({
+        xai: { reasoningEffort: "high", store: false },
+      })
      expect(bedrock.route.id).toBe("bedrock-converse")
      expect(bedrock.route.defaults.generation).toEqual({ topP: 0.8 })
      expect(bedrock.route.defaults.http?.body).toEqual({ serviceTier: { type: "priority" } })
@@ -4,8 +4,10 @@ import { Database } from "@opencode-ai/core/database/database"
 import { Agent } from "@opencode-ai/core/agent"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { and, eq } from "drizzle-orm"
 import { Bus } from "@opencode-ai/core/bus"
 import { Event } from "@opencode-ai/schema/event"
+import { EventTable } from "@opencode-ai/core/event/sql"
 import { Location } from "@opencode-ai/core/location"
 import { Project } from "@opencode-ai/core/project"
 import { ProjectTable } from "@opencode-ai/core/project/sql"
@@ -15,6 +17,8 @@ import { SessionProjector } from "@opencode-ai/core/session/projector"
 import { SessionExecution } from "@opencode-ai/core/session/execution"
 import { SessionStore } from "@opencode-ai/core/session/store"
 import { SessionTable } from "@opencode-ai/core/session/sql"
+import { SessionEvent } from "@opencode-ai/core/session/event"
+import { SessionMessage } from "@opencode-ai/core/session/message"
 import { testEffect } from "./lib/effect"
 import { globalProjectLayer } from "./lib/project"

@@ -28,6 +32,16 @@ const it = testEffect(
    ],
  ),
 )
+// Default bus: durable payloads are not retained (`events.persist` off).
+const itVolatile = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([Database.node, Bus.node, SessionProjector.node, SessionStore.node, Session.node]),
+    [
+      [Project.node, globalProjectLayer],
+      [SessionExecution.node, SessionExecution.noopLayer],
+    ],
+  ),
+)
 const location = Location.Ref.make({ directory: AbsolutePath.make("/project") })

 describe("Session.log", () => {
@@ -60,6 +74,43 @@ describe("Session.log", () => {
    }),
  )

+  it.effect("accepts a cursor exactly at the aggregate head", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const created = yield* session.create({ location })
+
+      const items = Array.from(
+        yield* Stream.runCollect(session.log({ sessionID: created.id, after: Event.Seq.make(0) })),
+      )
+
+      expect(items).toEqual([{ type: "log.synced", aggregateID: created.id, seq: Event.Seq.make(0) }])
+    }),
+  )
+
+  it.effect("fails with SeqUnavailable when the cursor is beyond the aggregate head", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const created = yield* session.create({ location })
+
+      const errors = yield* Effect.forEach([1, 10], (after) =>
+        Effect.flip(Stream.runCollect(session.log({ sessionID: created.id, after: Event.Seq.make(after) }))),
+      )
+
+      expect(errors.map((error) => error._tag)).toEqual([
+        "Session.SeqUnavailableError",
+        "Session.SeqUnavailableError",
+      ])
+      expect(errors.map((error) => (error._tag === "Session.SeqUnavailableError" ? error.after : undefined))).toEqual([
+        Event.Seq.make(1),
+        Event.Seq.make(10),
+      ])
+      expect(errors.map((error) => (error._tag === "Session.SeqUnavailableError" ? error.head : undefined))).toEqual([
+        Event.Seq.make(0),
+        Event.Seq.make(0),
+      ])
+    }),
+  )
+
  it.effect("fails with NotFound for an unknown session", () =>
    Effect.gen(function* () {
      const session = yield* Session.Service
@@ -68,6 +119,109 @@ describe("Session.log", () => {
    }),
  )

+  it.effect("orders live ephemeral deltas after their durable start", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const bus = yield* Bus.Service
+      const created = yield* session.create({ location })
+      const assistantMessageID = SessionMessage.ID.create()
+      const fiber = yield* session
+        .log({ sessionID: created.id, after: Event.Seq.make(0), follow: true, ephemeral: true })
+        .pipe(Stream.take(3), Stream.runCollect, Effect.forkScoped)
+      yield* Effect.yieldNow
+
+      yield* bus.publish(SessionEvent.Text.Started, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+      })
+      yield* bus.publish(SessionEvent.Text.Delta, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+        delta: "hello",
+      })
+
+      expect(Array.from(yield* Fiber.join(fiber)).map((item) => item.type)).toEqual([
+        "log.synced",
+        "session.text.started",
+        "session.text.delta",
+      ])
+    }),
+  )
+
+  it.effect("never includes ephemeral events in replay", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const bus = yield* Bus.Service
+      const created = yield* session.create({ location })
+      const assistantMessageID = SessionMessage.ID.create()
+      yield* bus.publish(SessionEvent.Text.Started, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+      })
+      yield* bus.publish(SessionEvent.Text.Delta, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+        delta: "not retained",
+      })
+      yield* bus.publish(SessionEvent.Text.Ended, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+        text: "complete",
+      })
+
+      const items = Array.from(yield* Stream.runCollect(session.log({ sessionID: created.id, ephemeral: true })))
+
+      expect(items.map((item) => item.type)).toEqual([
+        "session.created",
+        "session.text.started",
+        "session.text.ended",
+        "log.synced",
+      ])
+    }),
+  )
+
+  it.effect("keeps the default follow stream durable-only", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const bus = yield* Bus.Service
+      const created = yield* session.create({ location })
+      const assistantMessageID = SessionMessage.ID.create()
+      const fiber = yield* session
+        .log({ sessionID: created.id, after: Event.Seq.make(0), follow: true })
+        .pipe(Stream.take(3), Stream.runCollect, Effect.forkScoped)
+      yield* Effect.yieldNow
+
+      yield* bus.publish(SessionEvent.Text.Started, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+      })
+      yield* bus.publish(SessionEvent.Text.Delta, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+        delta: "filtered",
+      })
+      yield* bus.publish(SessionEvent.Text.Ended, {
+        sessionID: created.id,
+        assistantMessageID,
+        ordinal: 0,
+        text: "complete",
+      })
+
+      expect(Array.from(yield* Fiber.join(fiber)).map((item) => item.type)).toEqual([
+        "log.synced",
+        "session.text.started",
+        "session.text.ended",
+      ])
+    }),
+  )
+
  it.effect("reads across undecodable gaps in aggregate order and marks the true log position", () =>
    Effect.gen(function* () {
      const GapEvent = Bus.durable({
@@ -87,12 +241,33 @@ describe("Session.log", () => {
      const items = Array.from(yield* Stream.runCollect(session.log({ sessionID: created.id, after: 1 })))

      expect(
-        items.map((item): number | string | undefined => (Bus.isSynced(item) ? item.type : item.durable?.seq)),
+        items.map((item): number | string | undefined =>
+          Bus.isSynced(item) ? item.type : "durable" in item ? item.durable.seq : undefined,
+        ),
      ).toEqual([3, 4, "log.synced"])
      expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID: created.id, seq: Event.Seq.make(4) })
    }),
  )

+  it.effect("fails with SeqUnavailable when the replay range is only partially retained", () =>
+    Effect.gen(function* () {
+      const db = (yield* Database.Service).db
+      const session = yield* Session.Service
+      const created = yield* session.create({ location })
+      yield* session.rename({ sessionID: created.id, title: "pruned" })
+      yield* db
+        .delete(EventTable)
+        .where(and(eq(EventTable.aggregate_id, created.id), eq(EventTable.seq, 1)))
+        .run()
+
+      const error = yield* Effect.flip(
+        Stream.runCollect(session.log({ sessionID: created.id, after: Event.Seq.make(0) })),
+      )
+
+      expect(error._tag).toBe("Session.SeqUnavailableError")
+    }),
+  )
+
  it.effect("completes with a bare synced marker for a migrated Session with no event sequence", () =>
    Effect.gen(function* () {
      const db = (yield* Database.Service).db
@@ -121,3 +296,46 @@ describe("Session.log", () => {
    }),
  )
 })
+
+describe("Session.log without retained events", () => {
+  itVolatile.effect("accepts a cursor exactly at the head", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const created = yield* session.create({ location })
+      yield* session.rename({ sessionID: created.id, title: "at head" })
+
+      const items = Array.from(
+        yield* Stream.runCollect(session.log({ sessionID: created.id, after: Event.Seq.make(1) })),
+      )
+
+      expect(items).toEqual([{ type: "log.synced", aggregateID: created.id, seq: Event.Seq.make(1) }])
+    }),
+  )
+
+  itVolatile.effect("fails with SeqUnavailable for a cursor behind the head", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const created = yield* session.create({ location })
+      yield* session.rename({ sessionID: created.id, title: "behind head" })
+
+      const error = yield* Effect.flip(
+        Stream.runCollect(session.log({ sessionID: created.id, after: Event.Seq.make(0) })),
+      )
+
+      expect(error._tag).toBe("Session.SeqUnavailableError")
+      expect(error._tag === "Session.SeqUnavailableError" ? error.head : undefined).toEqual(Event.Seq.make(1))
+    }),
+  )
+
+  itVolatile.effect("replays nothing but stays live for a cursorless read", () =>
+    Effect.gen(function* () {
+      const session = yield* Session.Service
+      const created = yield* session.create({ location })
+      yield* session.rename({ sessionID: created.id, title: "cursorless" })
+
+      const items = Array.from(yield* Stream.runCollect(session.log({ sessionID: created.id })))
+
+      expect(items).toEqual([{ type: "log.synced", aggregateID: created.id, seq: Event.Seq.make(1) }])
+    }),
+  )
+})
@@ -323,11 +323,7 @@ describe("SessionProjector", () => {
      const admitted = yield* SessionInbox.admit(db, bus, {
        id,
        sessionID,
-        item: {
-          type: "user",
-          payload: { text: "expanded command template", command: { name: "command", arguments: "input" } },
-          delivery: "steer",
-        },
+        item: { type: "user", payload: { text: "promote me" }, delivery: "steer" },
      })
      if (!admitted) return yield* Effect.die("Prompt admission failed")

@@ -341,15 +337,7 @@ describe("SessionProjector", () => {
      ).toBeUndefined()
      expect(
        yield* db.select().from(SessionMessageTable).where(eq(SessionMessageTable.id, id)).get().pipe(Effect.orDie),
-      ).toMatchObject({
-        session_id: sessionID,
-        type: "user",
-        seq: event.durable?.seq,
-        data: {
-          text: "expanded command template",
-          command: { name: "command", arguments: "input" },
-        },
-      })
+      ).toMatchObject({ session_id: sessionID, type: "user", seq: event.durable?.seq })
    }),
  )

@@ -235,18 +235,16 @@ describe("Session.prompt", () => {
      const message = yield* session.prompt({
        sessionID,
        text: "Fix the failing tests",
-        command: { name: "fix", arguments: "tests" },
        resume: false,
      })

      expect(message.payload.text).toBe("Fix the failing tests")
-      expect(message.payload.command).toEqual({ name: "fix", arguments: "tests" })
      expect(yield* session.messages({ sessionID })).toEqual([])
      expect(yield* admitted(message.id)).toMatchObject({
        id: message.id,
        sessionID,
        type: "user",
-        payload: { text: "Fix the failing tests", command: { name: "fix", arguments: "tests" } },
+        payload: { text: "Fix the failing tests" },
        delivery: "steer",
      })
    }),
@@ -0,0 +1,87 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { Database } from "@opencode-ai/core/database/database"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { Bus } from "@opencode-ai/core/bus"
+import { Location } from "@opencode-ai/core/location"
+import { Project } from "@opencode-ai/core/project"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { Session } from "@opencode-ai/core/session"
+import { SessionProjector } from "@opencode-ai/core/session/projector"
+import { SessionExecution } from "@opencode-ai/core/session/execution"
+import { SessionStore } from "@opencode-ai/core/session/store"
+import { SessionEvent } from "@opencode-ai/core/session/event"
+import { Event } from "@opencode-ai/schema/event"
+import { testEffect } from "./lib/effect"
+import { globalProjectLayer } from "./lib/project"
+
+const it = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([Database.node, Bus.node, SessionProjector.node, SessionStore.node, Session.node]),
+    [
+      [Bus.node, Bus.configured({ persist: true })],
+      [Project.node, globalProjectLayer],
+      [SessionExecution.node, SessionExecution.noopLayer],
+    ],
+  ),
+)
+const location = Location.Ref.make({ directory: AbsolutePath.make("/project") })
+
+describe("Session.snapshot", () => {
+  it.effect("returns an empty projected session at its aggregate watermark", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const created = yield* sessions.create({ location })
+
+      expect(yield* sessions.snapshot({ sessionID: created.id })).toEqual({
+        session: created,
+        children: [],
+        inbox: [],
+        messages: [],
+        seq: Event.Seq.make(0),
+      })
+    }),
+  )
+
+  it.effect("returns the most recent messages in aggregate order", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const bus = yield* Bus.Service
+      const created = yield* sessions.create({ location })
+      yield* Effect.forEach(["first", "second", "third"], (text) =>
+        bus.publish(SessionEvent.Synthetic, { sessionID: created.id, text }),
+      )
+
+      const snapshot = yield* sessions.snapshot({ sessionID: created.id, recent: 2 })
+
+      expect(snapshot.messages.map((message) => (message.type === "synthetic" ? message.text : message.type))).toEqual([
+        "second",
+        "third",
+      ])
+      expect(snapshot.seq).toBe(Event.Seq.make(3))
+    }),
+  )
+
+  it.effect("keeps rows and watermark consistent during concurrent publication", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const bus = yield* Bus.Service
+      const created = yield* sessions.create({ location })
+      const publish = Effect.forEach(
+        Array.from({ length: 40 }, (_, index) => index + 1),
+        (index) => bus.publish(SessionEvent.Synthetic, { sessionID: created.id, text: String(index) }),
+      )
+      const read = Effect.forEach(Array.from({ length: 40 }), () => sessions.snapshot({ sessionID: created.id }))
+
+      const [, snapshots] = yield* Effect.all([publish, read], { concurrency: "unbounded" })
+
+      snapshots.forEach((snapshot) => {
+        expect(snapshot.messages).toHaveLength(snapshot.seq)
+        expect(
+          snapshot.messages.map((message) => (message.type === "synthetic" ? Number(message.text) : -1)),
+        ).toEqual(Array.from({ length: snapshot.seq }, (_, index) => index + 1))
+      })
+    }),
+  )
+})
@@ -17,6 +17,7 @@ import { Connection } from "@opencode-ai/schema/connection"
 import { Credential } from "@opencode-ai/schema/credential"
 import { FileSystem } from "@opencode-ai/schema/filesystem"
 import { Integration } from "@opencode-ai/schema/integration"
+import { AI } from "@opencode-ai/schema/ai"
 import { LLM } from "@opencode-ai/schema/llm"
 import { Permission } from "@opencode-ai/schema/permission"
 import { Pty } from "@opencode-ai/schema/pty"
@@ -95,6 +96,7 @@ test("Core reuses the canonical shared schemas", async () => {
    [coreIntegration.Method, Integration.Method],
    [coreIntegration.Ref, Integration.Ref],
    [coreLocation.Ref, Location.Ref],
+    [coreAI.ProviderMetadata, AI.ProviderMetadata],
    [coreAI.FinishReason, LLM.FinishReason],
    [coreModel.ID, Model.ID],
    [coreModel.VariantID, Model.VariantID],
@@ -1,5 +1,6 @@
 import { Schema } from "effect"
 import { Skill } from "@opencode-ai/schema/skill"
+import { Event } from "@opencode-ai/schema/event"

 export class InvalidRequestError extends Schema.TaggedError<InvalidRequestError>()(
  "InvalidRequestError",
@@ -35,6 +36,17 @@ export class SessionBusyError extends Schema.TaggedError<SessionBusyError>()(
  { httpApiStatus: 409 },
 ) {}

+export class SeqUnavailableError extends Schema.TaggedError<SeqUnavailableError>()(
+  "SeqUnavailableError",
+  {
+    sessionID: Schema.String,
+    after: Event.Seq,
+    head: Schema.optional(Event.Seq),
+    message: Schema.String,
+  },
+  { httpApiStatus: 409 },
+) {}
+
 export class ServiceUnavailableError extends Schema.TaggedError<ServiceUnavailableError>()(
  "ServiceUnavailableError",
  {
@@ -18,6 +18,7 @@ import {
  InvalidRequestError,
  MessageNotFoundError,
  ServiceUnavailableError,
+  SeqUnavailableError,
  SessionBusyError,
  SessionNotFoundError,
  SkillNotFoundError,
@@ -219,6 +220,30 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
        }),
      ),
    )
+    .add(
+      HttpApiEndpoint.get("session.snapshot", "/api/session/:sessionID/snapshot", {
+        params: { sessionID: Session.ID },
+        query: {
+          recent: Schema.NumberFromString.pipe(Schema.decodeTo(PositiveInt), Schema.optional),
+        },
+        success: Schema.Struct({
+          data: Schema.Struct({
+            session: Session.Info,
+            children: Schema.Array(Session.Info),
+            inbox: Schema.Array(SessionInbox.Info),
+            messages: Schema.Array(SessionMessage.Info),
+            seq: Event.Seq,
+          }),
+        }).annotate({ identifier: "SessionSnapshotResponse" }),
+        error: [SessionNotFoundError, UnknownError],
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.session.snapshot",
+          summary: "Snapshot session state",
+          description: "Retrieve projected session state and its aggregate sequence from one consistent read.",
+        }),
+      ),
+    )
    .add(
      HttpApiEndpoint.delete("session.remove", "/api/session/:sessionID", {
        params: { sessionID: Session.ID },
@@ -633,17 +658,18 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
        query: {
          after: Schema.NumberFromString.pipe(Schema.decodeTo(Event.Seq), Schema.optional),
          follow: BooleanFromString.pipe(Schema.optional),
+          ephemeral: BooleanFromString.pipe(Schema.optional),
        },
        success: HttpApiSchema.StreamSse({
-          data: Schema.Union([SessionEvent.Durable, EventLog.Synced]).annotate({ identifier: "SessionLogItem" }),
+          data: Schema.Union([SessionEvent.All, EventLog.Synced]).annotate({ identifier: "SessionLogItem" }),
        }),
-        error: SessionNotFoundError,
+        error: [SessionNotFoundError, SeqUnavailableError],
      }).annotateMerge(
        OpenApi.annotations({
          identifier: "v2.session.log",
          summary: "Read the session log",
          description:
-            "Experimental durable session event log. Reads events after an exclusive aggregate sequence and continues with live events when follow=true.",
+            "Experimental session event log. Replay is durable-only; follow mode can opt into live ephemeral events.",
        }),
      ),
    )
@@ -0,0 +1,8 @@
+export * as AI from "./ai.js"
+
+import { Schema } from "effect"
+
+export const ProviderMetadata = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown)).annotate({
+  identifier: "AI.ProviderMetadata",
+})
+export type ProviderMetadata = Schema.Schema.Type<typeof ProviderMetadata>
@@ -8,6 +8,7 @@ export { FileSystem } from "./filesystem.js"
 export { Form } from "./form.js"
 export { Integration } from "./integration.js"
 export { LLM } from "./llm.js"
+export { AI } from "./ai.js"
 export { Location } from "./location.js"
 export { Mcp } from "./mcp.js"
 export { Model } from "./model.js"
@@ -61,16 +61,9 @@ export const SkillAttachment = Schema.Struct({
  mention: PromptMention.pipe(optional),
 }).annotate({ identifier: "Prompt.SkillAttachment" })

-export interface CommandInvocation extends Schema.Schema.Type<typeof CommandInvocation> {}
-export const CommandInvocation = Schema.Struct({
-  name: Schema.String,
-  arguments: Schema.String,
-}).annotate({ identifier: "Prompt.CommandInvocation" })
-
 export interface Prompt extends Schema.Schema.Type<typeof Prompt> {}
 export const Prompt = Schema.Struct({
  text: Schema.String,
-  command: CommandInvocation.pipe(optional),
  files: Schema.Array(FileAttachment).pipe(optional),
  agents: Schema.Array(AgentAttachment).pipe(optional),
  skills: Schema.Array(SkillAttachment).pipe(optional),
@@ -79,10 +72,9 @@ export const Prompt = Schema.Struct({
  .pipe(
    statics((schema) => ({
      equivalence: Schema.toEquivalence(schema),
-      fromUserMessage: (input: Pick<Prompt, "text" | "command" | "files" | "agents" | "skills">) =>
+      fromUserMessage: (input: Pick<Prompt, "text" | "files" | "agents" | "skills">) =>
        schema.make({
          text: input.text,
-          ...(input.command === undefined ? {} : { command: input.command }),
          ...(input.files === undefined ? {} : { files: input.files }),
          ...(input.agents === undefined ? {} : { agents: input.agents }),
          ...(input.skills === undefined ? {} : { skills: input.skills }),
@@ -72,7 +72,10 @@ export const LocationSwitched = Schema.Struct({
 export interface User extends Schema.Schema.Type<typeof User> {}
 export const User = Schema.Struct({
  ...Base,
-  ...Prompt.fields,
+  text: Prompt.fields.text,
+  files: Prompt.fields.files,
+  agents: Prompt.fields.agents,
+  skills: Prompt.fields.skills,
  type: Schema.tag("user"),
 }).annotate({ identifier: "Session.Message.User" })

@@ -39,7 +39,7 @@ describe("SessionError", () => {
  })
 })

-test("FinishReason is the closed normalized provider set", () => {
+test("FinishReason is the closed browser-safe provider set", () => {
  const reasons = ["stop", "length", "tool-calls", "content-filter", "error", "unknown"] as const
  expect(reasons.map((reason) => Schema.decodeUnknownSync(LLM.FinishReason)(reason))).toEqual([...reasons])
  expect(() => Schema.decodeUnknownSync(LLM.FinishReason)("other")).toThrow()
@@ -1,7 +1,7 @@
 import { Session } from "@opencode-ai/core/session"
 import { SessionTransfer } from "@opencode-ai/core/session/transfer"
 import { InstructionEntry } from "@opencode-ai/core/session/instruction-entry"
-import { DateTime, Effect, Stream } from "effect"
+import { DateTime, Effect } from "effect"
 import { HttpApiBuilder, HttpApiSchema } from "effect/unstable/httpapi"
 import { Api } from "../api"
 import { SessionsCursor } from "@opencode-ai/protocol/groups/session"
@@ -13,6 +13,7 @@ import {
  InvalidCursorError,
  MessageNotFoundError,
  ServiceUnavailableError,
+  SeqUnavailableError,
  SessionBusyError,
  SessionNotFoundError,
  SkillNotFoundError,
@@ -26,16 +27,23 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
  Effect.gen(function* () {
    const session = yield* Session.Service
    const transfer = yield* SessionTransfer.Service
+    const sessionNotFound = (error: Session.NotFoundError) =>
+      new SessionNotFoundError({
+        sessionID: error.sessionID,
+        message: `Session not found: ${error.sessionID}`,
+      })
+    const messageDecodeFailed = (error: Session.MessageDecodeError) => {
+      const ref = `err_${crypto.randomUUID().slice(0, 8)}`
+      return Effect.logError("failed to decode session message").pipe(
+        Effect.annotateLogs({ ref, sessionID: error.sessionID, messageID: error.messageID }),
+        Effect.andThen(
+          Effect.fail(new UnknownError({ message: "Unexpected server error. Check server logs for details.", ref })),
+        ),
+      )
+    }
    const pendingMutation = (effect: ReturnType<typeof session.cancelInbox>, conflict: string) =>
      effect.pipe(
-        Effect.catchTag(
-          "Session.NotFoundError",
-          (error) =>
-            new SessionNotFoundError({
-              sessionID: error.sessionID,
-              message: `Session not found: ${error.sessionID}`,
-            }),
-        ),
+        Effect.catchTag("Session.NotFoundError", sessionNotFound),
        Effect.catchTag(
          "Session.InboxConflictError",
          (error) => new ConflictError({ resource: error.inboxID, message: `${conflict}: ${error.inboxID}` }),
@@ -131,25 +139,8 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
        Effect.fn(function* (ctx) {
          return {
            data: yield* transfer.export({ sessionID: ctx.params.sessionID, sanitize: ctx.query.sanitize }).pipe(
-              Effect.catchTag(
-                "Session.NotFoundError",
-                (error) =>
-                  new SessionNotFoundError({
-                    sessionID: error.sessionID,
-                    message: `Session not found: ${error.sessionID}`,
-                  }),
-              ),
-              Effect.catchTag("Session.MessageDecodeError", (error) => {
-                const ref = `err_${crypto.randomUUID().slice(0, 8)}`
-                return Effect.logError("failed to decode session message").pipe(
-                  Effect.annotateLogs({ ref, sessionID: error.sessionID, messageID: error.messageID }),
-                  Effect.andThen(
-                    Effect.fail(
-                      new UnknownError({ message: "Unexpected server error. Check server logs for details.", ref }),
-                    ),
-                  ),
-                )
-              }),
+              Effect.catchTag("Session.NotFoundError", sessionNotFound),
+              Effect.catchTag("Session.MessageDecodeError", messageDecodeFailed),
            ),
          }
        }),
@@ -180,6 +171,19 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
          }
        }),
      )
+      .handle(
+        "session.snapshot",
+        Effect.fn(function* (ctx) {
+          return {
+            data: yield* session
+              .snapshot({ sessionID: ctx.params.sessionID, recent: ctx.query.recent })
+              .pipe(
+                Effect.catchTag("Session.NotFoundError", sessionNotFound),
+                Effect.catchTag("Session.MessageDecodeError", messageDecodeFailed),
+              ),
+          }
+        }),
+      )
      .handle(
        "session.remove",
        Effect.fn(function* (ctx) {
@@ -664,25 +668,8 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
        Effect.fn(function* (ctx) {
          return {
            data: yield* session.context(ctx.params.sessionID).pipe(
-              Effect.catchTag("Session.NotFoundError", (error) =>
-                Effect.fail(
-                  new SessionNotFoundError({
-                    sessionID: error.sessionID,
-                    message: `Session not found: ${error.sessionID}`,
-                  }),
-                ),
-              ),
-              Effect.catchTag("Session.MessageDecodeError", (error) => {
-                const ref = `err_${crypto.randomUUID().slice(0, 8)}`
-                return Effect.logError("failed to decode session message").pipe(
-                  Effect.annotateLogs({ ref, sessionID: error.sessionID, messageID: error.messageID }),
-                  Effect.andThen(
-                    Effect.fail(
-                      new UnknownError({ message: "Unexpected server error. Check server logs for details.", ref }),
-                    ),
-                  ),
-                )
-              }),
+              Effect.catchTag("Session.NotFoundError", sessionNotFound),
+              Effect.catchTag("Session.MessageDecodeError", messageDecodeFailed),
            ),
          }
        }),
@@ -773,19 +760,25 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
      .handle(
        "session.log",
        Effect.fn(function* (ctx) {
-          yield* session.get(ctx.params.sessionID).pipe(
-            Effect.catchTag(
-              "Session.NotFoundError",
-              (error) =>
-                new SessionNotFoundError({
-                  sessionID: error.sessionID,
-                  message: `Session not found: ${error.sessionID}`,
-                }),
-            ),
-          )
-          return session
-            .log({ sessionID: ctx.params.sessionID, after: ctx.query.after, follow: ctx.query.follow })
-            .pipe(Stream.orDie)
+          return yield* session
+            .openLog({
+              sessionID: ctx.params.sessionID,
+              after: ctx.query.after,
+              follow: ctx.query.follow,
+              ephemeral: ctx.query.ephemeral,
+            })
+            .pipe(
+              Effect.mapError((error) =>
+                error._tag === "Session.NotFoundError"
+                  ? sessionNotFound(error)
+                  : new SeqUnavailableError({
+                      sessionID: error.sessionID,
+                      after: error.after,
+                      head: error.head,
+                      message: `Session log is unavailable after sequence ${error.after}`,
+                    }),
+              ),
+            )
        }),
      )
      .handle(
@@ -208,6 +208,11 @@ export function Prompt(props: PromptProps) {
  const config = useConfig().data
  const dialog = useDialog()
  const toast = useToast()
+  onCleanup(
+    data.session.failures.listen((failure) => {
+      toast.show({ title: "Prompt rejected", message: failure.reason, variant: "error" })
+    }),
+  )
  const status = createMemo(() => data.session.status(props.sessionID ?? ""))
  const history = usePromptHistory()
  const stash = usePromptStash()
@@ -1304,7 +1309,7 @@ export function Prompt(props: PromptProps) {
          return false
        }
      }
-      const error = await client.api.session
+      const error = await data.session
        .prompt({
          sessionID,
          text: inputText,
@@ -46,7 +46,6 @@ const ADD_TAB_WIDTH = 3
 const MARQUEE_DELAY = 600
 const MARQUEE_INTERVAL = 80
 const CONTEXT_MENU_WIDTH = 16
-const MIDDLE_MOUSE_BUTTON = 1
 const RIGHT_MOUSE_BUTTON = 2

 type TabContextMenuState = {
@@ -570,14 +569,6 @@ function VerticalSessionTabs(props: { controller?: SessionTabsController; animat
                  onMouseOver={() => marquee.enter(tab.sessionID, title(), hoveredTitleWidth())}
                  onMouseOut={() => marquee.leave(tab.sessionID)}
                  onMouseDown={(event) => {
-                    if (event.button === MIDDLE_MOUSE_BUTTON) {
-                      didDrag = false
-                      setDragging(undefined)
-                      tabs.close(tab.sessionID)
-                      event.preventDefault()
-                      event.stopPropagation()
-                      return
-                    }
                    if (event.button === RIGHT_MOUSE_BUTTON) {
                      didDrag = false
                      setDragging(undefined)
@@ -1117,14 +1108,6 @@ function HorizontalSessionTabs(props: { controller?: SessionTabsController; anim
              onMouseOver={() => marquee.enter(tab.sessionID, title(), hoveredTitleWidth())}
              onMouseOut={() => marquee.leave(tab.sessionID)}
              onMouseDown={(event) => {
-                if (event.button === MIDDLE_MOUSE_BUTTON) {
-                  didDrag = false
-                  setDragging(undefined)
-                  tabs.close(tab === NEW_SESSION_TAB ? undefined : tab.sessionID)
-                  event.preventDefault()
-                  event.stopPropagation()
-                  return
-                }
                if (event.button === RIGHT_MOUSE_BUTTON) {
                  didDrag = false
                  setDragging(undefined)
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Kit Langton	0f40b3f053	Merge remote-tracking branch 'origin/v2' into sync-engine-plan	2026-08-19 15:33:47 -04:00
Kit Langton	de7d389ed7	refactor(client): replace store adapter with signal of view The engine's immutable views are now held in one signal per session; the Data facade keeps its shape, backed by signal reads instead of store paths. Deletes the identity diff, per-path reconcile, deep clone into the store, the rendered shadow map, the mutable StoreSessionView type, and both hand-maintained invariants (new fields must be diffed; per-index writes cannot shrink). Views alias engine state directly, which is safe because views are immutable and consumers receive fresh arrays from the facade. Clones remain only where values cross into the legacy layer's store.	2026-08-19 14:40:31 -04:00
Kit Langton	96900eb67d	fix(client): clear fold fields by deleting keys Assigning undefined leaves an own key that JSON snapshots cannot represent, so replay and fromSnapshot disagreed on key presence (retry, error, finish, time.completed, revert, text state). The Solid store adapter masked this: reconcile treats undefined as delete. Clear semantics now delete the key so both hydration paths agree.	2026-08-19 14:40:31 -04:00
Kit Langton	d7562b3161	chore: move perf harness and design docs to follow-up Slims the review surface to runtime code and tests. The bench script, perf experiment log, and the two root-level design documents are preserved on the sync-engine-perf-docs branch and will return in a follow-up PR. Headline numbers stay in the PR description.	2026-08-19 14:06:09 -04:00
Kit Langton	726a11ba4a	test(client): review pass on sync-engine test suite Two parallel reviews (quality + tests-as-spec) over the engine tests, treating them as first-class code. Accuracy fixes to catalog claims, fixture honesty, and typecheck coverage: - typecheck now covers the sync-engine tests and scripts via tsconfig.test.json (old test files with pre-existing errors excluded); fixes the type errors this surfaced (fixture stream signal param, readonly snapshot arrays, invalid assistant literal) - FakeSessionServer: file header stating the real-fold modeling claim, honors the abort signal, heal() so the sim reset cannot drift from the faults record, seq() so tests stop leaning on events.length, threads the constructor time into the snapshot, fixes AsyncQueue falsy trap - laws: file header, law 10 numbering for the refresh-race test, vacuous law 2 wait replaced with engine.ready(), law 1/2 story comments, robust comment stripping in law 3 - sim: header, chaos distribution + drain-phase comments, heal(), ses_-prefixed session IDs everywhere - divergence catalog: corrected engine-side claims (live reordering is ruled out by the ordered log, not the cursor check; activity resync wording; law 10 citation), header notes the raw-protocol retry test, per-call delta event IDs - engine-data: header linking it to the laws, SNAPSHOT_RECENT named constant, error-DTO source-of-truth comment	2026-08-18 23:03:29 -04:00
Kit Langton	d31fbab722	test(client): catalog legacy data layer divergence states	2026-08-18 22:42:38 -04:00
Kit Langton	4fcffdd05e	docs: record future directions from architecture retrospective	2026-08-18 22:24:13 -04:00
Kit Langton	a060459985	docs: clarify engine vs legacy size comparison	2026-08-18 22:14:44 -04:00
Kit Langton	16a45957fd	test(client): cover server outages and restarts in sync engine suite	2026-08-18 22:11:51 -04:00
Kit Langton	90832ffe8d	refactor(client): simplify engine render and store diff	2026-08-18 21:58:35 -04:00
Kit Langton	6cbf607849	refactor(client): clone only changed subtrees on engine publish	2026-08-18 21:29:12 -04:00
Kit Langton	378d46c076	chore(client): add session sync streaming benchmark	2026-08-18 21:29:11 -04:00
Kit Langton	e0d4a0374c	chore(client): regenerate on rebased protocol	2026-08-18 20:56:08 -04:00
Kit Langton	f6f8606155	docs: record cursor honesty contract	2026-08-18 20:44:57 -04:00
Kit Langton	ef31823a6f	fix(client): recover from lossy log attach via snapshot	2026-08-18 20:44:57 -04:00
Kit Langton	4a42f4a724	fix(core): refuse log cursors without retained replay	2026-08-18 20:44:57 -04:00
Kit Langton	ce27f07f15	fix(client): preserve minted prompt IDs	2026-08-18 20:44:57 -04:00
Kit Langton	80587d936f	docs: wiring complete, regression dispositions	2026-08-18 20:44:57 -04:00
Kit Langton	09772d89d5	fix(tui): restore data-layer guarantees under engine wiring	2026-08-18 20:44:57 -04:00
Kit Langton	4f07025067	fix(client): restore engine refresh guarantees	2026-08-18 20:44:57 -04:00
Kit Langton	f253bdaeef	feat(tui): wire engine data layer	2026-08-18 20:44:57 -04:00
Kit Langton	93c24cafa7	feat(client): engine-backed data layer	2026-08-18 20:44:57 -04:00
Kit Langton	0963826120	docs: record lane status	2026-08-18 20:44:56 -04:00
Kit Langton	c5df2e5c28	refactor(core): simplify snapshot and log changes	2026-08-18 20:44:56 -04:00
Kit Langton	13f0cdd0ea	feat(core): session.log follow includes ephemeral events	2026-08-18 20:44:32 -04:00
Kit Langton	5887911c26	feat(core): typed seq-unavailable on session.log	2026-08-18 20:44:01 -04:00
Kit Langton	59bc653465	feat(protocol): session.snapshot endpoint	2026-08-18 20:44:01 -04:00
Kit Langton	8a4c14aed5	refactor(client): simplify sync engine	2026-08-18 20:43:47 -04:00
Kit Langton	15aef5f0f2	test(client): seeded chaos sim	2026-08-18 20:43:47 -04:00
Kit Langton	9b87120db6	test(client): six laws	2026-08-18 20:43:47 -04:00
Kit Langton	af6407a1b1	feat(client): engine core	2026-08-18 20:43:47 -04:00
Kit Langton	e4ff762483	feat(client): session fold	2026-08-18 20:43:47 -04:00
Kit Langton	a00822b06e	feat(core): Session.snapshot	2026-08-18 20:43:47 -04:00
Kit Langton	58c33f6870	docs: deletion inventory at adoption	2026-08-18 20:43:21 -04:00
Kit Langton	82d13c6715	docs: outbox ack contract, feature-grouped commits, opt-in ephemeral stream	2026-08-18 20:43:21 -04:00
Kit Langton	6c1d066a65	docs: drop adopt-strictness (S2), renumber lanes	2026-08-18 20:43:21 -04:00
Kit Langton	9b8801a3c6	docs: commit-by-commit implementation lanes, snapshot recent param	2026-08-18 20:43:21 -04:00
Kit Langton	8dad59cf99	docs: delivery is a parallel build for local comparison, not a staged migration	2026-08-18 20:43:21 -04:00
Kit Langton	a023ece71f	docs: snapshot-only entry contract, compaction/revert/fork, ambient bus filter (S4)	2026-08-18 20:43:21 -04:00
Kit Langton	2b5cc0090a	docs: single session stream, overlay semantics, mid-stream reconnect	2026-08-18 20:43:21 -04:00
Kit Langton	fc6b9e0dde	docs: fold prior-art findings into snapshot decision	2026-08-18 20:43:20 -04:00
Kit Langton	ab535c3875	docs: decide snapshot endpoint shape (tentative)	2026-08-18 20:43:20 -04:00
Kit Langton	4ca2f9dd83	docs: sync engine plan outline	2026-08-18 20:43:20 -04:00