refactor(tui): remove unavailable sharing commands

Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>

.opencode/plugins/tui/discovery-smoke.ts

@@ -2,15 +2,12 @@ import type { Context } from "../../../packages/plugin/src/tui/context"
 
 export default {
   id: "test.tui-discovery-smoke",
-  setup(context: Context) {
+  setup(_context: Context) {
-    const timer = setTimeout(() => {
+    // context.ui.toast.show({
-      context.ui.toast.show({
+    //   title: "TUI plugin discovery works",
-        title: "TUI plugin discovery works",
+    //   message: "Loaded .opencode/plugins/tui/discovery-smoke.ts",
-        message: "Loaded .opencode/plugins/tui/discovery-smoke.ts",
+    //   variant: "success",
-        variant: "success",
+    //   duration: 30_000,
-        duration: 30_000,
+    // })
-      })
-    }, 1_000)
-    return () => clearTimeout(timer)
   },
 }

bun.lock

@@ -67,6 +67,7 @@
         "@opencode-ai/sdk": "file:vendor/opencode-ai-sdk-1.18.8-dev.tgz",
         "@opencode-ai/session-ui": "workspace:*",
         "@opencode-ai/ui": "workspace:*",
+        "@opencode-ai/util": "workspace:*",
         "@pierre/trees": "1.0.0-beta.4",
         "@sentry/solid": "catalog:",
         "@shikijs/transformers": "3.9.2",
@@ -143,7 +144,10 @@
         "open": "10.1.2",
         "semver": "catalog:",
         "solid-js": "catalog:",
+        "tree-sitter-bash": "0.25.0",
+        "tree-sitter-powershell": "0.25.10",
         "uqr": "0.1.3",
+        "web-tree-sitter": "0.25.10",
         "ws": "8.21.0",
       },
       "devDependencies": {
@@ -402,8 +406,11 @@
         "immer": "11.1.4",
         "jsonc-parser": "3.3.1",
         "semver": "^7.6.3",
+        "tree-sitter-bash": "0.25.0",
+        "tree-sitter-powershell": "0.25.10",
         "turndown": "7.2.0",
         "venice-ai-sdk-provider": "2.1.1",
+        "web-tree-sitter": "0.25.10",
         "which": "6.0.1",
         "zod": "catalog:",
       },
@@ -514,6 +521,7 @@
         "@opencode-ai/core": "workspace:*",
         "@opencode-ai/session-ui": "workspace:*",
         "@opencode-ai/ui": "workspace:*",
+        "@opencode-ai/util": "workspace:*",
         "@pierre/diffs": "catalog:",
         "@solidjs/meta": "catalog:",
         "@solidjs/router": "catalog:",
@@ -600,6 +608,7 @@
         "zod": "catalog:",
       },
       "devDependencies": {
+        "@opencode-ai/theme": "workspace:*",
         "@opentui/core": "catalog:",
         "@opentui/keymap": "catalog:",
         "@opentui/solid": "catalog:",
@@ -611,12 +620,14 @@
         "typescript": "catalog:",
       },
       "peerDependencies": {
+        "@opencode-ai/theme": "workspace:*",
         "@opentui/core": ">=0.4.5",
         "@opentui/keymap": ">=0.4.5",
         "@opentui/solid": ">=0.4.5",
         "solid-js": ">=1.9.0",
       },
       "optionalPeers": [
+        "@opencode-ai/theme",
         "@opentui/core",
         "@opentui/keymap",
         "@opentui/solid",
@@ -1070,9 +1081,11 @@
   },
   "trustedDependencies": [
     "esbuild",
+    "tree-sitter-powershell",
     "protobufjs",
     "electron",
     "web-tree-sitter",
+    "tree-sitter-bash",
   ],
   "patchedDependencies": {
     "@pierre/trees@1.0.0-beta.4": "patches/@pierre%2Ftrees@1.0.0-beta.4.patch",
@@ -4069,10 +4082,10 @@
 
     "fetch-blob": ["fetch-blob@3.2.0", "", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="],
 
-    "file-uri-to-path": ["file-uri-to-path@1.0.0", "", {}, "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw=="],
-
     "ffi-rs": ["ffi-rs@1.3.2", "", { "optionalDependencies": { "@yuuang/ffi-rs-android-arm64": "1.3.2", "@yuuang/ffi-rs-darwin-arm64": "1.3.2", "@yuuang/ffi-rs-darwin-x64": "1.3.2", "@yuuang/ffi-rs-linux-arm-gnueabihf": "1.3.2", "@yuuang/ffi-rs-linux-arm64-gnu": "1.3.2", "@yuuang/ffi-rs-linux-arm64-musl": "1.3.2", "@yuuang/ffi-rs-linux-x64-gnu": "1.3.2", "@yuuang/ffi-rs-linux-x64-musl": "1.3.2", "@yuuang/ffi-rs-win32-arm64-msvc": "1.3.2", "@yuuang/ffi-rs-win32-ia32-msvc": "1.3.2", "@yuuang/ffi-rs-win32-x64-msvc": "1.3.2" } }, "sha512-4s8dX9VbBw/jd5NOuE3EJRqXaIVdjMyiumeeDzrOhtjQRwp6Bz2za7iksWXTnvTQKV/tTdm1s1w7mObe92zPjQ=="],
 
+    "file-uri-to-path": ["file-uri-to-path@1.0.0", "", {}, "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw=="],
+
     "filelist": ["filelist@1.0.6", "", { "dependencies": { "minimatch": "^5.0.1" } }, "sha512-5giy2PkLYY1cP39p17Ech+2xlpTRL9HLspOfEgm0L6CwBXBTgsK5ou0JtzYuepxkaQ/tvhCFIJ5uXo0OrM2DxA=="],
 
     "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
@@ -5631,6 +5644,10 @@
 
     "traverse": ["traverse@0.3.9", "", {}, "sha512-iawgk0hLP3SxGKDfnDJf8wTz4p2qImnyihM5Hh/sGvQ3K37dPi/w8sRhdNIxYA1TwFwc5mDhIJq+O0RsvXBKdQ=="],
 
+    "tree-sitter-bash": ["tree-sitter-bash@0.25.0", "", { "dependencies": { "node-addon-api": "^8.2.1", "node-gyp-build": "^4.8.2" }, "peerDependencies": { "tree-sitter": "^0.25.0" }, "optionalPeers": ["tree-sitter"] }, "sha512-gZtlj9+qFS81qKxpLfD6H0UssQ3QBc/F0nKkPsiFDyfQF2YBqYvglFJUzchrPpVhZe9kLZTrJ9n2J6lmka69Vg=="],
+
+    "tree-sitter-powershell": ["tree-sitter-powershell@0.25.10", "", { "dependencies": { "node-addon-api": "^7.1.0", "node-gyp-build": "^4.8.0" }, "peerDependencies": { "tree-sitter": "^0.25.0" }, "optionalPeers": ["tree-sitter"] }, "sha512-bEt8QoySpGFnU3aa8WedQyNMaN6aTwy/WUbvIVt0JSKF+BbJoSHNHu+wCbhj7xLMsfB0AuffmiJm+B8gzva8Lg=="],
+
     "treeverse": ["treeverse@3.0.0", "", {}, "sha512-gcANaAnd2QDZFmHFEOF4k7uc1J/6a6z3DJMd/QwEyxLoKGiptJRwid582r7QIsFlFMIZ3SnxfS52S4hm2DHkuQ=="],
 
     "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
@@ -6853,6 +6870,8 @@
 
     "topojson-client/commander": ["commander@2.20.3", "", {}, "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ=="],
 
+    "tree-sitter-bash/node-addon-api": ["node-addon-api@8.9.0", "", {}, "sha512-ekZMeaaIzSQTSpr7X2X3iJM7lTzgnx8ahAG9pJfT/7+14mlEM8ZYQ9cgCDvSSRbReFK0oHli3WrZdCiRsgAT9Q=="],
+
     "tw-to-css/postcss": ["postcss@8.4.31", "", { "dependencies": { "nanoid": "^3.3.6", "picocolors": "^1.0.0", "source-map-js": "^1.0.2" } }, "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ=="],
 
     "tw-to-css/tailwindcss": ["tailwindcss@3.3.2", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "arg": "^5.0.2", "chokidar": "^3.5.3", "didyoumean": "^1.2.2", "dlv": "^1.1.3", "fast-glob": "^3.2.12", "glob-parent": "^6.0.2", "is-glob": "^4.0.3", "jiti": "^1.18.2", "lilconfig": "^2.1.0", "micromatch": "^4.0.5", "normalize-path": "^3.0.0", "object-hash": "^3.0.0", "picocolors": "^1.0.0", "postcss": "^8.4.23", "postcss-import": "^15.1.0", "postcss-js": "^4.0.1", "postcss-load-config": "^4.0.1", "postcss-nested": "^6.0.1", "postcss-selector-parser": "^6.0.11", "postcss-value-parser": "^4.2.0", "resolve": "^1.22.2", "sucrase": "^3.32.0" }, "bin": { "tailwind": "lib/cli.js", "tailwindcss": "lib/cli.js" } }, "sha512-9jPkMiIBXvPc2KywkraqsUfbfj+dHDb+JPWtSJa9MLFdrPyazI7q6WX2sUrm7R9eVR7qqv3Pas7EvQFzxKnI6w=="],

docs/design/v1-v2-database-migration.md

@@ -0,0 +1,118 @@
+# V1 to V2 Database Migration
+
+## Approach
+
+- Use the `dev` branch database schema and migration registry as the V1 baseline.
+- Remove migrations that exist only on the V2 branch.
+- Generate one canonical migration from the `dev` schema to the final V2 schema.
+- Add explicit data operations to that migration where generated DDL is insufficient.
+- Test the migration against a populated database at the exact `dev` schema.
+
+## Preserve
+
+The canonical V1 data remains in its existing tables. In particular, preserve `session`, `message`, and `part` rows.
+
+Preserve `workspace` rows and existing `session.workspace_id` values unchanged. The migration must not clear or rebuild
+workspace relationships.
+
+Keep the `todo` table and its data unchanged. V2 does not currently migrate todos into another representation, and the
+generated migration must not drop the table.
+
+## Truncate
+
+Truncate these pre-launch V2 tables before applying schema changes:
+
+- `event`
+- `event_sequence`
+- `session_message`
+
+These rows are not canonical V1 data. Truncating `event` before adding the required `event.created` column means the
+column needs neither a backfill nor a default. After truncation, rebuild `session_message` from canonical V1 `message`
+and `part` rows rather than retaining its pre-launch V2 contents.
+
+## Message Backfill
+
+Backfill canonical V1 history from `message` and `part` into `session_message`. This is the main data transformation in
+the migration. Preserving the V1 tables alone keeps the data safe but does not make existing history visible through the
+V2 session APIs, which read `session_message`.
+
+Reuse each V1 `message.id` as the corresponding `session_message.id`. Stable IDs keep the migration deterministic and
+avoid rewriting other persisted state that may refer to a message.
+
+Within each session, order V1 messages by `time_created` and then `id`, matching the existing V1 message index. Assign
+contiguous `session_message.seq` values starting at `0`.
+
+Map ordinary V1 messages one-to-one by role. Each ordinary V1 user message becomes one V2 `user` row, and each ordinary
+V1 assistant message becomes one V2 `assistant` row. Fold the source message's ordered V1 parts into that row's V2
+payload.
+
+Handle semantic marker parts before applying the ordinary mapping. In particular, a V1 user message containing a
+`compaction` part and its paired assistant summary represent one compaction operation, not two ordinary messages. Special
+part mappings must be decided explicitly before implementing the backfill.
+
+V1 synthetic content is represented by user text parts with `synthetic: true`, not by a separate message role. A V1 user
+message whose visible text parts are all synthetic should become a V2 `synthetic` message. If a V1 user message mixes
+ordinary and synthetic content, preserve the ordinary content in the V2 `user` row and emit the synthetic content as an
+adjacent V2 `synthetic` row. Ignore text parts marked `ignored`, matching V1 model-history behavior.
+
+Use the V1 compaction user message ID as the ID of the collapsed V2 compaction message. This matches V2's use of the
+admitted compaction input ID and preserves references to the initiating message.
+
+For a completed compaction, create one V2 `compaction` row with `status: "completed"`. Set `reason` from the V1
+compaction part's `auto` flag, join the paired summary assistant's nonempty text parts with blank lines for `summary`, and
+serialize the retained V1 tail beginning at `tail_start_id` for `recent`. Use an empty `recent` value when no tail was
+retained, and use the compaction user message creation time. Do not emit the paired summary assistant as a separate V2
+assistant row.
+
+After rebuilding `session_message`, seed `event_sequence` with one row per migrated session. Set its watermark to that
+session's maximum backfilled `session_message.seq`. This prevents new V2 events from reusing sequence numbers or sorting
+before migrated history. The `event` table remains empty.
+
+## Drop
+
+Drop these pre-launch V2 tables without preserving or transforming their rows:
+
+- `session_input`
+- `session_context_epoch`
+
+Do not transfer `session_input` rows into `session_pending`.
+
+## Create Empty
+
+Let the generated migration create these tables empty:
+
+- `instruction_blob`
+- `instruction_entry`
+- `instruction_state`
+- `session_pending`
+- `kv`
+
+V1 has no canonical data to backfill into these tables. V2 initializes their state as it runs.
+
+## Fork Storage
+
+V1 has no fork-boundary state to backfill. New V2 forks use a required message boundary and persist it in
+`session.fork_boundary`. The durable fork event contains no parent sequence. Its resolved boundary is one of:
+
+- `before`: copy messages before the identified message.
+- `through`: copy messages through the identified message.
+
+Forking an empty session is not supported. `session.fork_seq` and `session.fork_message_id` are not part of the final V2
+schema.
+
+New nullable session columns, including `fork_session_id`, `fork_boundary`, and `time_suspended`, require no explicit
+backfill. Existing rows naturally receive `NULL` when the generated migration adds the columns.
+
+## Verification
+
+The canonical migration test should seed representative V1 sessions, messages, parts, todos, projects, accounts,
+credentials, permissions, shares, and workspaces. After migration, it should verify:
+
+- Preserved rows and encoded values remain unchanged.
+- Todo rows remain available in the unchanged `todo` table.
+- `event` is empty, and stale pre-launch rows are absent from the rebuilt projections.
+- Backfilled `session_message` rows represent the canonical V1 `message` and `part` history.
+- Each migrated session's `event_sequence` watermark matches its maximum backfilled message sequence.
+- Dropped tables no longer exist.
+- New tables exist and are empty.
+- The final schema has no ungenerated changes.

packages/ai/AGENTS.md

@@ -12,6 +12,8 @@
 
 Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Model.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, `LLM.updateRequest`, and `LLM.generateObject`. Two ways to construct the same thing is one too many.
 
+- Keep provider-defined string enums forward-compatible. Expose known values for autocomplete while accepting future values with `Known | (string & {})`; use `Schema.String` at runtime unless rejecting unknown values is required for correctness.
+
 ## Tests
 
 - Use `testEffect(...)` from `test/lib/effect.ts` for tests requiring Effect layers.
@@ -46,7 +48,7 @@ const response = yield * LLMClient.generate(request)
 
 `LLM.request(...)` builds an `LLMRequest`. `LLMClient.generate(...)` reads the executable route carried by `request.model.route`, builds the provider-native body, asks the route's transport for a real `HttpClientRequest.HttpClientRequest`, sends it through `RequestExecutor.Service`, parses the provider stream into common `LLMEvent`s, and finally returns an `LLMResponse`.
 
-Use `LLMClient.stream(request)` when callers want incremental `LLMEvent`s. Use `LLMClient.generate(request)` when callers want those same events collected into an `LLMResponse`. Use `LLMClient.prepare<Body>(request)` to compile a request through the route pipeline without sending it — the optional `Body` type argument narrows `.body` to the route's native shape (e.g. `prepare<OpenAIChatBody>(...)` returns a `PreparedRequestOf<OpenAIChatBody>`). The runtime body is identical; the generic is a type-level assertion.
+Use `LLMClient.stream(request)` when callers want incremental `LLMEvent`s. Use `LLMClient.generate(request)` when callers want those same events collected into an `LLMResponse`.
 
 Filter or narrow `LLMEvent` streams with `LLMEvent.is.*` (camelCase guards, e.g. `events.filter(LLMEvent.is.toolCall)`). The kebab-case `LLMEvent.guards["tool-call"]` form also works but prefer `is.*` in new code.
 
@@ -138,13 +140,13 @@ packages/ai/src/
     ids.ts                  branded IDs, literal types, ProviderMetadata
     options.ts              Generation/Provider/Http options, Limits, Model, cache policy
     messages.ts             content parts, Message, ToolDefinition, LLMRequest
-    events.ts               Usage, individual events, LLMEvent, PreparedRequest, LLMResponse
+    events.ts               Usage, individual events, LLMEvent, LLMResponse
     errors.ts               error reasons, LLMError, 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.prepare/stream/generate
+    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

packages/ai/README.md

@@ -196,7 +196,6 @@ The hosted result is represented as a provider-executed tool call and tool resul
 - **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
 - **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
 - **`Model.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
-- **`LLMClient.prepare(request)`** — compile a request through protocol body construction, validation, and HTTP preparation without sending. Useful for inspection and testing.
 - **`LLMEvent.is.*`** — typed guards (`is.textDelta`, `is.toolCall`, `is.finish`, …) for filtering streams.
 - **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
 - **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.

packages/ai/example/call-sites.md

@@ -568,7 +568,7 @@ App boundary = explicit durable-config -> typed-provider call
       calling `.model(...)`.
 - [x] Remove request-shaping defaults from `Model`; selected models now carry only
       id, provider, and configured route while defaults live on routes or requests.
-- [x] Rework `LLMClient.prepare` / `stream` / `generate` to read
+- [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.

packages/ai/example/tutorial.ts

@@ -50,18 +50,6 @@ const request = LLM.request({
   },
 })
 
-// `http` is intentionally not needed for normal calls. This shows the shape for
-// newly released provider fields before they deserve a typed provider option.
-const rawOverlayExample = LLM.request({
-  model,
-  prompt: "Show the final HTTP overlay shape.",
-  http: {
-    body: { metadata: { example: "tutorial" } },
-    headers: { "x-opencode-tutorial": "1" },
-    query: { debug: "1" },
-  },
-})
-
 // 3. `generate` sends the request and collects the event stream into one
 // response object. `response.text` is the collected text output.
 const generateOnce = Effect.gen(function* () {
@@ -222,33 +210,15 @@ const FakeEcho = {
   }),
 }
 
-// `LLMClient.prepare` is the lower-level inspection hook: it compiles through
-// body conversion, validation, endpoint, auth, and HTTP construction without
-// sending anything over the network.
-const inspectFakeProvider = Effect.gen(function* () {
-  const prepared = yield* LLMClient.prepare(
-    LLM.request({
-      model: FakeEcho.configure().model("tiny-echo"),
-      prompt: "Show me the provider pipeline.",
-    }),
-  )
-
-  console.log("\n== fake provider prepare ==")
-  console.log("route:", prepared.route)
-  console.log("body:", Formatter.formatJson(prepared.body, { space: 2 }))
-})
-
 // Provide the LLM runtime and the HTTP request executor once. Keep one path
-// enabled at a time so the tutorial can demonstrate generate, prepare, stream,
+// enabled at a time so the tutorial can demonstrate generate, stream, or
-// or tool-loop behavior without spending tokens on every example.
+// tool-loop behavior without spending tokens on every example.
 const requestExecutorLayer = RequestExecutor.fetchLayer
 const llmDeps = Layer.mergeAll(requestExecutorLayer, WebSocketExecutor.layer)
 const llmClientLayer = LLMClient.layer.pipe(Layer.provide(llmDeps))
 
 const program = Effect.gen(function* () {
   // yield* generateOnce
-  // yield* inspectFakeProvider
-  // yield* LLMClient.prepare(rawOverlayExample).pipe(Effect.andThen((prepared) => Effect.sync(() => console.log(prepared.body))))
   // yield* streamText
   // yield* generateStructuredObject
   // yield* generateDynamicObject.pipe(Effect.andThen((response) => Effect.sync(() => console.log(response.object))))

packages/ai/src/cache-policy.ts

@@ -38,7 +38,7 @@ const resolve = (policy: CachePolicy | undefined): CachePolicyObject => {
 // Protocols whose wire format ignores inline cache markers (OpenAI's implicit
 // prefix caching, Gemini's implicit + out-of-band CachedContent). Skip the
 // whole policy pass for these — emitting hints would be harmless but pointless.
-const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse"])
+const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse", "openrouter"])
 
 const makeHint = (ttlSeconds: number | undefined): CacheHint =>
   ttlSeconds !== undefined ? new CacheHint({ type: "ephemeral", ttlSeconds }) : new CacheHint({ type: "ephemeral" })
@@ -133,6 +133,7 @@ const countHints = (request: LLMRequest) =>
 
 export const applyCachePolicy = (request: LLMRequest): LLMRequest => {
   if (!RESPECTS_INLINE_HINTS.has(request.model.route.id)) return request
+  if (request.model.route.id === "openrouter" && (request.cache === undefined || request.cache === "auto")) return request
   const policy = resolve(request.cache)
   if (!policy.tools && !policy.system && !policy.messages) return request
 

packages/ai/src/llm.ts

@@ -9,25 +9,28 @@ import {
   LLMRequest,
   LLMResponse,
   Message,
+  Model,
   SystemPart,
   ToolChoice,
   ToolDefinition,
   type ContentPart,
+  type ModelProviderOptions,
 } from "./schema"
 import { make as makeTool, toDefinitions, type ToolSchema } from "./tool"
 
 /** Input accepted by `LLM.request`, normalized into the canonical `LLMRequest` class. */
-export type RequestInput = Omit<
+export type RequestInput<SelectedModel extends Model = Model> = Omit<
   ConstructorParameters<typeof LLMRequest>[0],
-  "system" | "messages" | "tools" | "toolChoice" | "generation" | "http" | "providerOptions"
+  "model" | "system" | "messages" | "tools" | "toolChoice" | "generation" | "http" | "providerOptions"
 > & {
+  readonly model: SelectedModel
   readonly system?: string | SystemPart | ReadonlyArray<SystemPart>
   readonly prompt?: string | ContentPart | ReadonlyArray<ContentPart>
   readonly messages?: ReadonlyArray<Message | Message.Input>
   readonly tools?: ReadonlyArray<ToolDefinition.Input>
   readonly toolChoice?: ToolChoice.Input
   readonly generation?: GenerationOptions.Input
-  readonly providerOptions?: ConstructorParameters<typeof LLMRequest>[0]["providerOptions"]
+  readonly providerOptions?: NoInfer<ModelProviderOptions<SelectedModel>>
   readonly http?: HttpOptions.Input
 }
 
@@ -35,7 +38,7 @@ export const generate = LLMClient.generate
 
 export const stream = LLMClient.stream
 
-export const request = (input: RequestInput) => {
+export const request = <const SelectedModel extends Model>(input: RequestInput<SelectedModel>) => {
   const {
     system: requestSystem,
     prompt,
@@ -63,7 +66,7 @@ const GENERATE_OBJECT_TOOL_NAME = "generate_object"
 
 const GENERATE_OBJECT_TOOL_DESCRIPTION = "Return the structured result by calling this tool."
 
-type GenerateObjectBase = Omit<RequestInput, "tools" | "toolChoice">
+type GenerateObjectBase<SelectedModel extends Model = Model> = Omit<RequestInput<SelectedModel>, "tools" | "toolChoice">
 
 export class GenerateObjectResponse<T> {
   constructor(
@@ -80,11 +83,13 @@ export class GenerateObjectResponse<T> {
   }
 }
 
-export interface GenerateObjectOptions<S extends ToolSchema<any>> extends GenerateObjectBase {
+export interface GenerateObjectOptions<S extends ToolSchema<any>, SelectedModel extends Model = Model>
+  extends GenerateObjectBase<SelectedModel> {
   readonly schema: S
 }
 
-export interface GenerateObjectDynamicOptions extends GenerateObjectBase {
+export interface GenerateObjectDynamicOptions<SelectedModel extends Model = Model>
+  extends GenerateObjectBase<SelectedModel> {
   /** Raw JSON Schema object describing the expected output shape. */
   readonly jsonSchema: JsonSchema.JsonSchema
 }
@@ -137,11 +142,11 @@ const runGenerateObject = Effect.fn("LLM.generateObject")(function* (
  * 2. `jsonSchema: JsonSchema.JsonSchema` — `.object` is `unknown`. Use when
  *    the schema is only available at runtime (MCP, plugin manifests). Caller validates.
  */
-export function generateObject<S extends ToolSchema<any>>(
+export function generateObject<const SelectedModel extends Model, S extends ToolSchema<any>>(
-  options: GenerateObjectOptions<S>,
+  options: GenerateObjectOptions<S, SelectedModel>,
 ): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, LLMError>
-export function generateObject(
+export function generateObject<const SelectedModel extends Model>(
-  options: GenerateObjectDynamicOptions,
+  options: GenerateObjectDynamicOptions<SelectedModel>,
 ): Effect.Effect<GenerateObjectResponse<unknown>, LLMError>
 export function generateObject(options: GenerateObjectOptions<ToolSchema<any>> | GenerateObjectDynamicOptions) {
   if ("schema" in options) {

packages/ai/src/protocols/gemini.ts

@@ -29,9 +29,30 @@ export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1bet
 
 export interface OptionsInput {
   readonly [key: string]: unknown
+  readonly cachedContent?: string
+  readonly safetySettings?: ReadonlyArray<{
+    readonly category:
+      | "HARM_CATEGORY_UNSPECIFIED"
+      | "HARM_CATEGORY_HATE_SPEECH"
+      | "HARM_CATEGORY_DANGEROUS_CONTENT"
+      | "HARM_CATEGORY_HARASSMENT"
+      | "HARM_CATEGORY_SEXUALLY_EXPLICIT"
+      | "HARM_CATEGORY_CIVIC_INTEGRITY"
+      | (string & {})
+    readonly threshold:
+      | "HARM_BLOCK_THRESHOLD_UNSPECIFIED"
+      | "BLOCK_LOW_AND_ABOVE"
+      | "BLOCK_MEDIUM_AND_ABOVE"
+      | "BLOCK_ONLY_HIGH"
+      | "BLOCK_NONE"
+      | "OFF"
+      | (string & {})
+  }>
+  readonly serviceTier?: "standard" | "flex" | "priority" | (string & {})
   readonly thinkingConfig?: {
     readonly thinkingBudget?: number
     readonly includeThoughts?: boolean
+    readonly thinkingLevel?: "minimal" | "low" | "medium" | "high" | (string & {})
   }
 }
 
@@ -111,6 +132,12 @@ const GeminiToolConfig = Schema.Struct({
 const GeminiThinkingConfig = Schema.Struct({
   thinkingBudget: Schema.optional(Schema.Number),
   includeThoughts: Schema.optional(Schema.Boolean),
+  thinkingLevel: Schema.optional(Schema.String),
+})
+
+const GeminiSafetySetting = Schema.Struct({
+  category: Schema.String,
+  threshold: Schema.String,
 })
 
 const GeminiGenerationConfig = Schema.Struct({
@@ -123,7 +150,10 @@ const GeminiGenerationConfig = Schema.Struct({
 })
 
 const GeminiBodyFields = {
+  cachedContent: Schema.optional(Schema.String),
   contents: Schema.Array(GeminiContent),
+  safetySettings: optionalArray(GeminiSafetySetting),
+  serviceTier: Schema.optional(Schema.String),
   systemInstruction: Schema.optional(GeminiSystemInstruction),
   tools: optionalArray(GeminiTool),
   toolConfig: Schema.optional(GeminiToolConfig),
@@ -316,17 +346,38 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
 })
 
 const resolveOptions = (request: LLMRequest) => {
-  const value = request.providerOptions?.gemini?.thinkingConfig
+  const input = request.providerOptions?.gemini
-  if (!ProviderShared.isRecord(value)) return {}
+  const value = input?.thinkingConfig
   const thinkingConfig = {
-    thinkingBudget: typeof value.thinkingBudget === "number" ? value.thinkingBudget : undefined,
+    thinkingBudget:
-    includeThoughts: typeof value.includeThoughts === "boolean" ? value.includeThoughts : undefined,
+      ProviderShared.isRecord(value) && typeof value.thinkingBudget === "number" ? value.thinkingBudget : undefined,
+    includeThoughts:
+      ProviderShared.isRecord(value) && typeof value.includeThoughts === "boolean"
+        ? value.includeThoughts
+        : ProviderShared.isRecord(value)
+          ? true
+          : undefined,
+    thinkingLevel:
+      ProviderShared.isRecord(value) && typeof value.thinkingLevel === "string" ? value.thinkingLevel : undefined,
   }
   return {
+    cachedContent: typeof input?.cachedContent === "string" ? input.cachedContent : undefined,
+    safetySettings: mapSafetySettings(input?.safetySettings),
+    serviceTier: typeof input?.serviceTier === "string" ? input.serviceTier : undefined,
     thinkingConfig: Object.values(thinkingConfig).some((item) => item !== undefined) ? thinkingConfig : undefined,
   }
 }
 
+function mapSafetySettings(value: unknown) {
+  if (!Array.isArray(value)) return undefined
+  const settings = value.flatMap((item) =>
+    ProviderShared.isRecord(item) && typeof item.category === "string" && typeof item.threshold === "string"
+      ? [{ category: item.category, threshold: item.threshold }]
+      : [],
+  )
+  return settings
+}
+
 const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMRequest) {
   const hasTools = request.tools.length > 0
   const generation = request.generation
@@ -342,7 +393,10 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
   }
 
   return {
+    cachedContent: options.cachedContent,
     contents: yield* lowerMessages(request),
+    safetySettings: options.safetySettings,
+    serviceTier: options.serviceTier,
     systemInstruction:
       request.system.length === 0 ? undefined : { parts: [{ text: ProviderShared.joinText(request.system) }] },
     tools: hasTools

packages/ai/src/protocols/openai-chat.ts

@@ -11,6 +11,7 @@ import {
   Usage,
   type FinishReason,
   type FinishReasonDetails,
+  type CacheHint,
   type JsonSchema,
   type LLMRequest,
   type MediaPart,
@@ -38,6 +39,11 @@ export const PATH = "/chat/completions"
 // The body schema is the provider-native JSON body. `fromRequest` below builds
 // this shape from the common `LLMRequest`, then `Route.make` validates and
 // JSON-encodes it before transport.
+const OpenAIChatCacheControl = Schema.Struct({
+  type: Schema.Literal("ephemeral"),
+  ttl: Schema.optional(Schema.String),
+})
+
 const OpenAIChatFunction = Schema.Struct({
   name: Schema.String,
   description: Schema.String,
@@ -47,6 +53,7 @@ const OpenAIChatFunction = Schema.Struct({
 const OpenAIChatTool = Schema.Struct({
   type: Schema.tag("function"),
   function: OpenAIChatFunction,
+  cache_control: Schema.optional(OpenAIChatCacheControl),
 })
 type OpenAIChatTool = Schema.Schema.Type<typeof OpenAIChatTool>
 
@@ -61,7 +68,11 @@ const OpenAIChatAssistantToolCall = Schema.Struct({
 type OpenAIChatAssistantToolCall = Schema.Schema.Type<typeof OpenAIChatAssistantToolCall>
 
 const OpenAIChatUserContent = Schema.Union([
-  Schema.Struct({ type: Schema.Literal("text"), text: Schema.String }),
+  Schema.Struct({
+    type: Schema.Literal("text"),
+    text: Schema.String,
+    cache_control: Schema.optional(OpenAIChatCacheControl),
+  }),
   Schema.Struct({
     type: Schema.Literal("image_url"),
     image_url: Schema.Struct({ url: Schema.String }),
@@ -69,7 +80,10 @@ const OpenAIChatUserContent = Schema.Union([
 ])
 
 const OpenAIChatMessage = Schema.Union([
-  Schema.Struct({ role: Schema.Literal("system"), content: Schema.String }),
+  Schema.Struct({
+    role: Schema.Literal("system"),
+    content: Schema.Union([Schema.String, Schema.Array(OpenAIChatUserContent)]),
+  }),
   Schema.Struct({
     role: Schema.Literal("user"),
     content: Schema.Union([Schema.String, Schema.Array(OpenAIChatUserContent)]),
@@ -83,10 +97,16 @@ const OpenAIChatMessage = Schema.Union([
       reasoning: Schema.optional(Schema.String),
       reasoning_text: Schema.optional(Schema.String),
       reasoning_details: Schema.optional(Schema.Unknown),
+      cache_control: Schema.optional(OpenAIChatCacheControl),
     }),
     [Schema.Record(Schema.String, Schema.Unknown)],
   ),
-  Schema.Struct({ role: Schema.Literal("tool"), tool_call_id: Schema.String, content: Schema.String }),
+  Schema.Struct({
+    role: Schema.Literal("tool"),
+    tool_call_id: Schema.String,
+    content: Schema.String,
+    cache_control: Schema.optional(OpenAIChatCacheControl),
+  }),
 ]).pipe(Schema.toTaggedUnion("role"))
 type OpenAIChatMessage = Schema.Schema.Type<typeof OpenAIChatMessage>
 
@@ -107,6 +127,7 @@ export const bodyFields = {
   stream_options: Schema.optional(Schema.Struct({ include_usage: Schema.Boolean })),
   store: Schema.optional(Schema.Boolean),
   reasoning_effort: Schema.optional(OpenAIOptions.OpenAIReasoningEffort),
+  max_completion_tokens: Schema.optional(Schema.Number),
   max_tokens: Schema.optional(Schema.Number),
   temperature: Schema.optional(Schema.Number),
   top_p: Schema.optional(Schema.Number),
@@ -209,13 +230,20 @@ export interface ParserState {
 // Lowering is the only place that knows how common LLM messages map onto the
 // OpenAI Chat wire format. Keep provider quirks here instead of leaking native
 // fields into `LLMRequest`.
-const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema): OpenAIChatTool => ({
+interface LoweringOptions {
+  readonly cacheControl?: (
+    cache: CacheHint | undefined,
+  ) => Schema.Schema.Type<typeof OpenAIChatCacheControl> | undefined
+}
+
+const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema, options: LoweringOptions): OpenAIChatTool => ({
   type: "function",
   function: {
     name: tool.name,
     description: tool.description,
     parameters: ToolSchemaProjection.openAI(inputSchema),
   },
+  cache_control: options.cacheControl?.(tool.cache),
 })
 
 const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
@@ -257,11 +285,14 @@ const reasoningDetails = (parts: ReadonlyArray<ReasoningPart>, native: unknown)
   if (isRecord(native) && Array.isArray(native.reasoning_details)) return native.reasoning_details
 }
 
-const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (message: OpenAIChatRequestMessage) {
+const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (
+  message: OpenAIChatRequestMessage,
+  options: LoweringOptions,
+) {
   const content: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   for (const part of message.content) {
     if (part.type === "text") {
-      content.push({ type: "text", text: part.text })
+      content.push({ type: "text", text: part.text, cache_control: options.cacheControl?.(part.cache) })
       continue
     }
     if (part.type === "media") {
@@ -270,14 +301,18 @@ const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (mes
     }
     return yield* ProviderShared.unsupportedContent("OpenAI Chat", "user", ["text", "media"])
   }
-  if (content.every((part) => part.type === "text"))
+  if (content.every((part) => part.type === "text" && part.cache_control === undefined))
-    return { role: "user" as const, content: content.map((part) => part.text).join("") }
+    return {
+      role: "user" as const,
+      content: content.map((part) => (part.type === "text" ? part.text : "")).join(""),
+    }
   return { role: "user" as const, content }
 })
 
 const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(function* (
   message: OpenAIChatRequestMessage,
   configuredField?: string,
+  options: LoweringOptions = {},
 ) {
   const content: TextPart[] = []
   const reasoning: ReasoningPart[] = []
@@ -315,29 +350,44 @@ const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(func
     if (reasoning.length === 0) return nativeReasoning
     return text
   })()
+  const cached = message.content.findLast((part) => "cache" in part && part.cache !== undefined)
   const result = {
     role: "assistant" as const,
     content: content.length === 0 ? null : ProviderShared.joinText(content),
     tool_calls: toolCalls.length === 0 ? undefined : toolCalls,
     reasoning_details: details,
+    cache_control: options.cacheControl?.(cached && "cache" in cached ? cached.cache : undefined),
   }
   if (field === undefined || reasoningText === undefined) return result
   return { ...result, [field]: reasoningText }
 })
 
-const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (message: OpenAIChatRequestMessage) {
+const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (
+  message: OpenAIChatRequestMessage,
+  options: LoweringOptions,
+) {
   const messages: OpenAIChatMessage[] = []
   const images: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   for (const part of message.content) {
     if (!ProviderShared.supportsContent(part, ["tool-result"]))
       return yield* ProviderShared.unsupportedContent("OpenAI Chat", "tool", ["tool-result"])
     if (part.result.type !== "content") {
-      messages.push({ role: "tool", tool_call_id: part.id, content: ProviderShared.toolResultText(part) })
+      messages.push({
+        role: "tool",
+        tool_call_id: part.id,
+        content: ProviderShared.toolResultText(part),
+        cache_control: options.cacheControl?.(part.cache),
+      })
       continue
     }
     const content: ReadonlyArray<Tool.Content> = part.result.value
     const text = content.filter((item) => item.type === "text").map((item) => item.text)
-    messages.push({ role: "tool", tool_call_id: part.id, content: text.join("\n") })
+    messages.push({
+      role: "tool",
+      tool_call_id: part.id,
+      content: text.join("\n"),
+      cache_control: options.cacheControl?.(part.cache),
+    })
     const files = content.filter((item) => item.type === "file")
     images.push(
       ...(yield* Effect.forEach(files, (item) =>
@@ -351,15 +401,29 @@ const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (m
 const lowerMessage = Effect.fn("OpenAIChat.lowerMessage")(function* (
   message: OpenAIChatRequestMessage,
   reasoningField?: string,
+  options: LoweringOptions = {},
 ) {
-  if (message.role === "user") return [yield* lowerUserMessage(message)]
+  if (message.role === "user") return [yield* lowerUserMessage(message, options)]
-  if (message.role === "assistant") return [yield* lowerAssistantMessage(message, reasoningField)]
+  if (message.role === "assistant") return [yield* lowerAssistantMessage(message, reasoningField, options)]
-  return (yield* lowerToolMessages(message)).messages
+  return (yield* lowerToolMessages(message, options)).messages
 })
 
-const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request: LLMRequest) {
+const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request: LLMRequest, options: LoweringOptions) {
   const system: OpenAIChatMessage[] =
-    request.system.length === 0 ? [] : [{ role: "system", content: ProviderShared.joinText(request.system) }]
+    request.system.length === 0
+      ? []
+      : request.system.some((part) => part.cache !== undefined) && options.cacheControl !== undefined
+        ? [
+            {
+              role: "system",
+              content: request.system.map((part) => ({
+                type: "text",
+                text: part.text,
+                cache_control: options.cacheControl?.(part.cache),
+              })),
+            },
+          ]
+        : [{ role: "system", content: ProviderShared.joinText(request.system) }]
   const messages = [...system]
   const pendingImages: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   const flushImages = () => {
@@ -370,28 +434,53 @@ const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request:
     if (message.role === "system") {
       const part = yield* ProviderShared.wrappedSystemUpdate("OpenAI Chat", message)
       if (pendingImages.length > 0) {
-        messages.push({ role: "user", content: [...pendingImages.splice(0), { type: "text", text: part.text }] })
+        messages.push({
+          role: "user",
+          content: [
+            ...pendingImages.splice(0),
+            { type: "text", text: part.text, cache_control: options.cacheControl?.(part.cache) },
+          ],
+        })
         continue
       }
       const previous = messages.at(-1)
       if (previous?.role === "user" && typeof previous.content === "string")
-        messages[messages.length - 1] = { role: "user", content: `${previous.content}\n${part.text}` }
+        messages[messages.length - 1] = options.cacheControl?.(part.cache)
+          ? {
+              role: "user",
+              content: [
+                { type: "text", text: previous.content },
+                { type: "text", text: part.text, cache_control: options.cacheControl(part.cache) },
+              ],
+            }
+          : { role: "user", content: `${previous.content}\n${part.text}` }
       else if (previous?.role === "user" && Array.isArray(previous.content))
         messages[messages.length - 1] = {
           role: "user",
-          content: [...previous.content, { type: "text", text: part.text }],
+          content: [
+            ...previous.content,
+            { type: "text", text: part.text, cache_control: options.cacheControl?.(part.cache) },
+          ],
         }
-      else messages.push({ role: "user", content: part.text })
+      else
+        messages.push(
+          options.cacheControl?.(part.cache)
+            ? {
+                role: "user",
+                content: [{ type: "text", text: part.text, cache_control: options.cacheControl(part.cache) }],
+              }
+            : { role: "user", content: part.text },
+        )
       continue
     }
     if (message.role === "tool") {
-      const lowered = yield* lowerToolMessages(message)
+      const lowered = yield* lowerToolMessages(message, options)
       messages.push(...lowered.messages)
       pendingImages.push(...lowered.images)
       continue
     }
     flushImages()
-    messages.push(...(yield* lowerMessage(message, request.model.compatibility?.reasoningField)))
+    messages.push(...(yield* lowerMessage(message, request.model.compatibility?.reasoningField, options)))
   }
   flushImages()
   return messages
@@ -405,7 +494,10 @@ const lowerOptions = (request: LLMRequest) => {
   }
 }
 
-const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (request: LLMRequest) {
+export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
+  request: LLMRequest,
+  options: LoweringOptions = {},
+) {
   // `fromRequest` returns the provider body only. Endpoint, auth, framing,
   // validation, and HTTP execution are composed by `Route.make`.
   const reasoningField = request.model.compatibility?.reasoningField
@@ -415,19 +507,26 @@ const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (request: LLMR
     )
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
+  const maxTokensField = request.model.compatibility?.maxTokensField ?? "max_tokens"
   return {
     model: request.model.id,
-    messages: yield* lowerMessages(request),
+    messages: yield* lowerMessages(request, options),
     tools:
       request.tools.length === 0
         ? undefined
         : request.tools.map((tool) =>
-            lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
+            lowerTool(
+              tool,
+              ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
+              options,
+            ),
           ),
     tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
     stream: true as const,
     stream_options: { include_usage: true },
-    max_tokens: generation?.maxTokens,
+    ...(maxTokensField === "max_completion_tokens"
+      ? { max_completion_tokens: generation?.maxTokens }
+      : { max_tokens: generation?.maxTokens }),
     temperature: generation?.temperature,
     top_p: generation?.topP,
     frequency_penalty: generation?.frequencyPenalty,

packages/ai/src/provider-package.ts

@@ -1,16 +1,21 @@
-import type { Model } from "./schema"
+import type { Model, ProviderOptions } from "./schema"
 
 export interface Settings extends Readonly<Record<string, unknown>> {
+  readonly baseURL?: string
   readonly headers?: Readonly<Record<string, string>>
   readonly body?: Readonly<Record<string, unknown>>
   readonly limits?: {
     readonly context: number
+    readonly input?: number
     readonly output: number
   }
 }
 
-export interface Definition<ProviderSettings extends Settings = Settings> {
+export interface Definition<
-  readonly model: (modelID: string, settings: ProviderSettings) => Model
+  ProviderSettings extends Settings = Settings,
+  Options extends ProviderOptions = ProviderOptions,
+> {
+  readonly model: (modelID: string, settings: ProviderSettings) => Model<Options>
 }
 
 export * as ProviderPackage from "./provider-package"

packages/ai/src/providers/anthropic-compatible.ts

@@ -47,7 +47,7 @@ export const configure = (input: Config) => {
   })
   return {
     id: ProviderID.make(provider),
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<AnthropicMessages.ProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -57,7 +57,10 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, AnthropicMessages.ProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => {
   if (settings.apiKey !== undefined && settings.authToken !== undefined)
     throw new Error("Anthropic-compatible apiKey cannot be combined with authToken")
   return configure({

packages/ai/src/providers/anthropic.ts

@@ -52,7 +52,10 @@ export const configure = (input: Config = {}) => {
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, AnthropicMessages.ProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => {
   if (settings.apiKey !== undefined && settings.authToken !== undefined)
     throw new Error("Anthropic apiKey cannot be combined with authToken")
   return configure({

packages/ai/src/providers/azure.ts

@@ -99,10 +99,14 @@ export const configure = (input: Config) => {
   const modelDefaults = defaults(input)
 
   const responses = (modelID: string | ModelID) =>
-    configuredResponsesRoute.with(withOpenAIOptions(modelID, modelDefaults)).model({ id: modelID })
+    configuredResponsesRoute
+      .with(withOpenAIOptions(modelID, modelDefaults))
+      .model<OpenAIProviderOptionsInput>({ id: modelID })
 
   const chat = (modelID: string | ModelID) =>
-    configuredChatRoute.with(withOpenAIOptions(modelID, modelDefaults)).model({ id: modelID })
+    configuredChatRoute
+      .with(withOpenAIOptions(modelID, modelDefaults))
+      .model<OpenAIProviderOptionsInput>({ id: modelID })
 
   return {
     id,
@@ -133,8 +137,12 @@ const config = (settings: Settings): Config => {
   throw new Error("Azure requires resourceName or baseURL")
 }
 
-export const responsesModel: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+export const responsesModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
-  configure(config(settings)).responses(modelID)
+  modelID,
-export const chatModel: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+  settings,
-  configure(config(settings)).chat(modelID)
+) => configure(config(settings)).responses(modelID)
+export const chatModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => configure(config(settings)).chat(modelID)
 export const model = responsesModel

packages/ai/src/providers/cloudflare.ts

@@ -4,6 +4,7 @@ import { Auth } from "../route/auth"
 import { AuthOptions, type AtLeastOne, type ProviderAuthOption } from "../route/auth-options"
 import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
+import type { OpenAIProviderOptionsInput } from "./openai-options"
 
 export const aiGatewayID = ProviderID.make("cloudflare-ai-gateway")
 export const workersAIID = ProviderID.make("cloudflare-workers-ai")
@@ -20,10 +21,11 @@ type GatewayURL = AtLeastOne<{
 }
 
 export type AIGatewayOptions = GatewayURL &
-  RouteDefaultsInput &
+  Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
     /** Cloudflare AI Gateway authentication token. Sent as `cf-aig-authorization`. */
     readonly gatewayApiKey?: CloudflareSecret
+    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 type WorkersAIURL = AtLeastOne<{
@@ -31,7 +33,11 @@ type WorkersAIURL = AtLeastOne<{
   readonly baseURL: string
 }>
 
-export type WorkersAIOptions = WorkersAIURL & RouteDefaultsInput & ProviderAuthOption<"optional">
+export type WorkersAIOptions = WorkersAIURL &
+  Omit<RouteDefaultsInput, "providerOptions"> &
+  ProviderAuthOption<"optional"> & {
+    readonly providerOptions?: OpenAIProviderOptionsInput
+  }
 
 export const aiGatewayBaseURL = (input: GatewayURL) => {
   if (input.baseURL) return input.baseURL
@@ -98,7 +104,7 @@ const configureAIGateway = (options: AIGatewayOptions) => {
   })
   return {
     id: aiGatewayID,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<OpenAIProviderOptionsInput>({ id: modelID }),
     configure: configureAIGateway,
   }
 }
@@ -111,7 +117,7 @@ const configureWorkersAI = (options: WorkersAIOptions) => {
   })
   return {
     id: workersAIID,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<OpenAIProviderOptionsInput>({ id: modelID }),
     configure: configureWorkersAI,
   }
 }

packages/ai/src/providers/github-copilot.ts

@@ -50,9 +50,11 @@ export const configure = (options: ModelOptions) => {
   const responsesRoute = configuredResponsesRoute(options)
   const chatRoute = configuredChatRoute(options)
   const responses = (modelID: string | ModelID) =>
-    responsesRoute.with(withOpenAIOptions(modelID, defaults(options))).model({ id: modelID })
+    responsesRoute
+      .with(withOpenAIOptions(modelID, defaults(options)))
+      .model<OpenAIProviderOptionsInput>({ id: modelID })
   const chat = (modelID: string | ModelID) =>
-    chatRoute.with(withOpenAIOptions(modelID, defaults(options))).model({ id: modelID })
+    chatRoute.with(withOpenAIOptions(modelID, defaults(options))).model<OpenAIProviderOptionsInput>({ id: modelID })
   return {
     id,
     model: (modelID: string | ModelID) =>

packages/ai/src/providers/google-vertex-chat.ts

@@ -1,8 +1,9 @@
 import type { ProviderPackage } from "../provider-package"
 import { OpenAICompatibleChat } from "../protocols/openai-compatible-chat"
 import type { RouteDefaultsInput } from "../route/client"
-import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { ProviderID, type ModelID } from "../schema"
 import { GoogleVertexShared } from "./google-vertex-shared"
+import type { OpenAIProviderOptionsInput } from "./openai-options"
 
 export const id = ProviderID.make("google-vertex")
 
@@ -11,6 +12,7 @@ export type Config = RouteDefaultsInput &
     readonly baseURL?: string
     readonly location?: string
     readonly project?: string
+    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 export interface Settings extends ProviderPackage.Settings {
@@ -19,7 +21,7 @@ export interface Settings extends ProviderPackage.Settings {
   readonly baseURL?: string
   readonly location?: string
   readonly project?: string
-  readonly providerOptions?: ProviderOptions
+  readonly providerOptions?: OpenAIProviderOptionsInput
 }
 
 const route = OpenAICompatibleChat.route.with({
@@ -56,7 +58,7 @@ export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
   return {
     id,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<OpenAIProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -66,7 +68,7 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
   if (settings.apiKey !== undefined) throw new Error("Google Vertex Chat does not support API keys")
   return configure({
     accessToken: settings.accessToken,

packages/ai/src/providers/google-vertex-messages.ts

@@ -91,7 +91,7 @@ export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
   return {
     id,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<AnthropicMessages.ProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -101,7 +101,10 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, AnthropicMessages.ProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => {
   if (settings.apiKey !== undefined) throw new Error("Google Vertex Messages does not support API keys")
   return configure({
     accessToken: settings.accessToken,

packages/ai/src/providers/google-vertex-responses.ts

@@ -1,8 +1,9 @@
 import type { ProviderPackage } from "../provider-package"
 import { OpenAICompatibleResponses } from "../protocols/openai-compatible-responses"
 import type { RouteDefaultsInput } from "../route/client"
-import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { ProviderID, type ModelID } from "../schema"
 import { GoogleVertexShared } from "./google-vertex-shared"
+import type { OpenResponsesProviderOptionsInput } from "./open-responses-options"
 
 export const id = ProviderID.make("google-vertex")
 
@@ -11,6 +12,7 @@ export type Config = RouteDefaultsInput &
     readonly baseURL?: string
     readonly location?: string
     readonly project?: string
+    readonly providerOptions?: OpenResponsesProviderOptionsInput
   }
 
 export interface Settings extends ProviderPackage.Settings {
@@ -19,7 +21,7 @@ export interface Settings extends ProviderPackage.Settings {
   readonly baseURL?: string
   readonly location?: string
   readonly project?: string
-  readonly providerOptions?: ProviderOptions
+  readonly providerOptions?: OpenResponsesProviderOptionsInput
 }
 
 const route = OpenAICompatibleResponses.route.with({
@@ -58,7 +60,7 @@ export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
   return {
     id,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<OpenResponsesProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -68,7 +70,10 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, OpenResponsesProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => {
   if (settings.apiKey !== undefined) throw new Error("Google Vertex Responses does not support API keys")
   return configure({
     accessToken: settings.accessToken,

packages/ai/src/providers/google-vertex.ts

@@ -77,7 +77,8 @@ const configuredRoute = (input: Config, modelID: string | ModelID) => {
 export const configure = (input: Config = {}) => {
   return {
     id,
-    model: (modelID: string | ModelID) => configuredRoute(input, modelID).model({ id: modelID }),
+    model: (modelID: string | ModelID) =>
+      configuredRoute(input, modelID).model<Gemini.ProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -86,7 +87,10 @@ export const provider = {
   id,
   configure,
 }
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, Gemini.ProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => {
   if (settings.apiKey !== undefined && settings.accessToken !== undefined)
     throw new Error("Google Vertex apiKey cannot be combined with accessToken or auth")
   return configure({

packages/ai/src/providers/google.ts

@@ -50,14 +50,14 @@ export const configure = (input: Config = {}) => {
     })
   return {
     id,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<Gemini.ProviderOptionsInput>({ id: modelID }),
     image,
     configure,
   }
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, Gemini.ProviderOptionsInput>["model"] = (modelID, settings) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/providers/openai-compatible-responses.ts

@@ -36,7 +36,7 @@ export const configure = (input: Config) => {
   })
   return {
     id: ProviderID.make(provider),
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<OpenResponsesProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -46,7 +46,10 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenResponsesProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/providers/openai-compatible.ts

@@ -4,13 +4,15 @@ import type { RouteDefaultsInput } from "../route/client"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import type { ProviderPackage } from "../provider-package"
 import { profiles, type OpenAICompatibleProfile } from "./openai-compatible-profile"
+import type { OpenAIProviderOptionsInput } from "./openai-options"
 
 export const id = ProviderID.make("openai-compatible")
 
-type GenericModelOptions = RouteDefaultsInput &
+type GenericModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
     readonly provider?: string
     readonly baseURL: string
+    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 export interface Settings extends ProviderPackage.Settings {
@@ -19,9 +21,10 @@ export interface Settings extends ProviderPackage.Settings {
   readonly provider?: string
 }
 
-export type FamilyModelOptions = RouteDefaultsInput &
+export type FamilyModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
+    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 export const routes = [OpenAICompatibleChat.route]
@@ -37,7 +40,8 @@ export const configure = (input: GenericModelOptions) => {
   })
   return {
     id: ProviderID.make(provider),
-    model: (modelID: string | ModelID) => route.model({ id: modelID, provider: ProviderID.make(provider) }),
+    model: (modelID: string | ModelID) =>
+      route.model<OpenAIProviderOptionsInput>({ id: modelID, provider: ProviderID.make(provider) }),
     configure,
   }
 }
@@ -63,7 +67,7 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/providers/openai.ts

@@ -86,10 +86,15 @@ export const configure = (input: Config = {}) => {
   const chatRoute = configuredRoute(OpenAIChat.route, input)
   const modelDefaults = defaults(input)
   const responses = (id: string | ModelID) =>
-    responsesRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
+    responsesRoute
+      .with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true }))
+      .model<OpenAIProviderOptionsInput>({ id })
   const responsesWebSocket = (id: string | ModelID) =>
-    responsesWebSocketRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
+    responsesWebSocketRoute
-  const chat = (id: string | ModelID) => chatRoute.with(withOpenAIOptions(id, modelDefaults)).model({ id })
+      .with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true }))
+      .model<OpenAIProviderOptionsInput>({ id })
+  const chat = (id: string | ModelID) =>
+    chatRoute.with(withOpenAIOptions(id, modelDefaults)).model<OpenAIProviderOptionsInput>({ id })
   const image = (modelID: string | ModelID) =>
     OpenAIImages.model({
       id: modelID,
@@ -132,15 +137,17 @@ const config = (settings: Settings): Config => {
   }
 }
 
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
   const configured = configure(config(settings))
   if (settings.transport === undefined || settings.transport === "http") return configured.responses(modelID)
   if (settings.transport === "websocket") return configured.responsesWebSocket(modelID)
   throw new Error(`Unsupported OpenAI Responses transport: ${String(settings.transport)}`)
 }
 
-export const chatModel: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+export const chatModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
-  configure(config(settings)).chat(modelID)
+  modelID,
+  settings,
+) => configure(config(settings)).chat(modelID)
 export const responses = provider.responses
 export const responsesWebSocket = provider.responsesWebSocket
 export const chat = provider.chat

packages/ai/src/providers/openrouter.ts

@@ -4,20 +4,72 @@ import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
 import { Protocol } from "../route/protocol"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { ProviderID, type CacheHint, type ModelID, type ProviderOptions } from "../schema"
+import type { ProviderPackage } from "../provider-package"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAIChat from "../protocols/openai-chat"
+import { newBreakpoints, ttlBucket } from "../protocols/utils/cache"
 import { isRecord } from "../protocols/shared"
 
 export const profile = OpenAICompatibleProfiles.profiles.openrouter
 export const id = ProviderID.make(profile.provider)
 const ADAPTER = "openrouter"
 
+type OpenRouterString<Known extends string> = Known | (string & {})
+
+export interface OpenRouterProviderRouting {
+  readonly [key: string]: unknown
+  readonly order?: ReadonlyArray<string>
+  readonly allow_fallbacks?: boolean
+  readonly require_parameters?: boolean
+  readonly data_collection?: OpenRouterString<"allow" | "deny">
+  readonly only?: ReadonlyArray<string>
+  readonly ignore?: ReadonlyArray<string>
+  readonly quantizations?: ReadonlyArray<string>
+  readonly sort?: OpenRouterString<"price" | "throughput" | "latency">
+  readonly max_price?: Readonly<{
+    prompt?: number | string
+    completion?: number | string
+    image?: number | string
+    audio?: number | string
+    request?: number | string
+  }>
+  readonly zdr?: boolean
+}
+
+export type OpenRouterPlugin =
+  | Readonly<{
+      id: "web"
+      max_results?: number
+      search_prompt?: string
+      engine?: OpenRouterString<"native" | "exa">
+    }>
+  | Readonly<{ id: "file-parser"; max_files?: number; pdf?: { engine?: string } }>
+  | Readonly<{ id: "moderation" }>
+  | Readonly<{ id: "response-healing" }>
+  | Readonly<{ id: "auto-router"; allowed_models?: ReadonlyArray<string> }>
+  | Readonly<{ id: string & {}; [key: string]: unknown }>
+
 export interface OpenRouterOptions {
   readonly [key: string]: unknown
-  readonly usage?: boolean | Record<string, unknown>
+  readonly debug?: Readonly<{ echo_upstream_body?: boolean }>
-  readonly reasoning?: Record<string, unknown>
+  readonly models?: ReadonlyArray<string>
+  readonly plugins?: ReadonlyArray<OpenRouterPlugin>
   readonly promptCacheKey?: string
+  readonly provider?: OpenRouterProviderRouting
+  readonly reasoning?: Readonly<{
+    enabled?: boolean
+    exclude?: boolean
+    effort?: OpenRouterString<"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">
+    max_tokens?: number
+  }>
+  readonly usage?: boolean | Readonly<{ include: boolean }>
+  readonly user?: string
+  readonly web_search_options?: Readonly<{
+    max_results?: number
+    search_prompt?: string
+    engine?: OpenRouterString<"native" | "exa">
+  }>
 }
 
 export type OpenRouterProviderOptionsInput = ProviderOptions & {
@@ -30,6 +82,12 @@ export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenRouterProviderOptionsInput
   }
 
+export interface Settings extends ProviderPackage.Settings {
+  readonly apiKey?: string
+  readonly baseURL?: string
+  readonly providerOptions?: OpenRouterProviderOptionsInput
+}
+
 const OpenRouterBody = Schema.StructWithRest(Schema.Struct(OpenAIChat.bodyFields), [
   Schema.Record(Schema.String, Schema.Any),
 ])
@@ -40,7 +98,7 @@ export const protocol = Protocol.make({
   body: {
     schema: OpenRouterBody,
     from: (request) =>
-      OpenAIChat.protocol.body.from(request).pipe(
+      OpenAIChat.fromRequest(request, { cacheControl: cacheControl() }).pipe(
         Effect.map((body) => {
           const sourceAssistants = request.messages.filter((message) => message.role === "assistant")
           let assistantIndex = 0
@@ -71,16 +129,39 @@ export const protocol = Protocol.make({
   stream: OpenAIChat.protocol.stream,
 })
 
+const cacheControl = () => {
+  const breakpoints = newBreakpoints(4)
+  return (cache: CacheHint | undefined) => {
+    if (cache === undefined || breakpoints.remaining === 0) return undefined
+    breakpoints.remaining -= 1
+    return {
+      type: "ephemeral" as const,
+      ...(ttlBucket(cache.ttlSeconds) === "1h" ? { ttl: "1h" } : {}),
+    }
+  }
+}
+
 const bodyOptions = (input: unknown) => {
   const openrouter = isRecord(input) ? input : {}
+  const { usage, models, provider, plugins, web_search_options, debug, user, reasoning, promptCacheKey, ...options } =
+    openrouter
   return {
-    ...(openrouter.usage === true
+    ...options,
+    ...(usage === undefined || usage === true
       ? { usage: { include: true } }
-      : isRecord(openrouter.usage)
+      : usage === false
-        ? { usage: openrouter.usage }
+        ? { usage: { include: false } }
-        : {}),
+        : isRecord(usage)
-    ...(isRecord(openrouter.reasoning) ? { reasoning: openrouter.reasoning } : {}),
+          ? { usage }
-    ...(typeof openrouter.promptCacheKey === "string" ? { prompt_cache_key: openrouter.promptCacheKey } : {}),
+          : {}),
+    ...(Array.isArray(models) ? { models } : {}),
+    ...(isRecord(provider) ? { provider } : {}),
+    ...(Array.isArray(plugins) ? { plugins } : {}),
+    ...(isRecord(web_search_options) ? { web_search_options } : {}),
+    ...(isRecord(debug) ? { debug } : {}),
+    ...(typeof user === "string" ? { user } : {}),
+    ...(isRecord(reasoning) ? { reasoning } : {}),
+    ...(typeof promptCacheKey === "string" ? { prompt_cache_key: promptCacheKey } : {}),
   }
 }
 
@@ -107,10 +188,21 @@ export const configure = (input: ModelOptions = {}) => {
   const route = configuredRoute(input)
   return {
     id,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => route.model<OpenRouterProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
 
 export const provider = configure()
-export const model = provider.model
+export const model: ProviderPackage.Definition<Settings, OpenRouterProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) =>
+  configure({
+    apiKey: settings.apiKey,
+    baseURL: settings.baseURL,
+    headers: settings.headers,
+    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
+    limits: settings.limits,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)

packages/ai/src/providers/xai.ts

@@ -1,29 +1,62 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import type { RouteDefaultsInput } from "../route/client"
+import { Route, type RouteDefaultsInput } from "../route/client"
-import { HttpOptions, ProviderID, type ModelID } from "../schema"
+import { Endpoint } from "../route/endpoint"
+import { HttpOptions, ProviderID, type ModelID, type ProviderOptions } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
+import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
 import { XAIImages } from "../protocols/xai-images"
+import type { OpenAIOptionsInput } from "./openai-options"
+import type { ProviderPackage } from "../provider-package"
 
 export const id = ProviderID.make("xai")
 
-export type ModelOptions = RouteDefaultsInput &
+export type XAIProviderOptionsInput = ProviderOptions & {
+  readonly xai?: OpenAIOptionsInput
+}
+
+export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
+    readonly providerOptions?: XAIProviderOptionsInput
   }
 
+export interface Settings extends ProviderPackage.Settings {
+  readonly apiKey?: string
+  readonly baseURL?: string
+  readonly providerOptions?: XAIProviderOptionsInput
+}
+
 export type { XAIImageOptions } from "../protocols/xai-images"
 
-export const routes = [OpenAIResponses.route, OpenAICompatibleChat.route]
+const responsesRoute = Route.make({
+  id: "openai-responses",
+  provider: id,
+  providerMetadataKey: "xai",
+  protocol: OpenAIResponses.protocol,
+  endpoint: Endpoint.path("/responses", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
+  transport: OpenAIResponses.httpTransport,
+  defaults: { providerOptions: { xai: { store: false } } },
+})
+
+const chatRoute = Route.make({
+  id: "openai-compatible-chat",
+  provider: id,
+  providerMetadataKey: "xai",
+  protocol: OpenAIChat.protocol,
+  endpoint: Endpoint.path("/chat/completions", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
+  transport: OpenAICompatibleChat.route.transport,
+})
+
+export const routes = [responsesRoute, chatRoute]
 
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "XAI_API_KEY")
 
 const configuredResponsesRoute = (input: ModelOptions) => {
   const { apiKey: _, auth: _auth, baseURL, ...rest } = input
-  return OpenAIResponses.route.with({
+  return responsesRoute.with({
     ...rest,
-    provider: id,
     endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
     auth: auth(input),
   })
@@ -31,9 +64,8 @@ const configuredResponsesRoute = (input: ModelOptions) => {
 
 const configuredChatRoute = (input: ModelOptions) => {
   const { apiKey: _, auth: _auth, baseURL, ...rest } = input
-  return OpenAICompatibleChat.route.with({
+  return chatRoute.with({
     ...rest,
-    provider: id,
     endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
     auth: auth(input),
   })
@@ -42,8 +74,8 @@ const configuredChatRoute = (input: ModelOptions) => {
 export const configure = (input: ModelOptions = {}) => {
   const responsesRoute = configuredResponsesRoute(input)
   const chatRoute = configuredChatRoute(input)
-  const responses = (modelID: string | ModelID) => responsesRoute.model({ id: modelID })
+  const responses = (modelID: string | ModelID) => responsesRoute.model<XAIProviderOptionsInput>({ id: modelID })
-  const chat = (modelID: string | ModelID) => chatRoute.model({ id: modelID })
+  const chat = (modelID: string | ModelID) => chatRoute.model<XAIProviderOptionsInput>({ id: modelID })
   const image = (modelID: string | ModelID) =>
     XAIImages.model({
       id: modelID,
@@ -63,7 +95,15 @@ export const configure = (input: ModelOptions = {}) => {
 }
 
 export const provider = configure()
-export const model = provider.model
+export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput>["model"] = (modelID, settings) =>
+  configure({
+    apiKey: settings.apiKey,
+    baseURL: settings.baseURL,
+    headers: settings.headers,
+    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
+    limits: settings.limits,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)
 export const responses = provider.responses
 export const chat = provider.chat
 export const image = provider.image

packages/ai/src/route/client.ts

@@ -5,12 +5,12 @@ import { Endpoint, type EndpointPatch } from "./endpoint"
 import { RequestExecutor } from "./executor"
 import { Framing } from "./framing"
 import { HttpTransport } from "./transport"
-import type { Transport, TransportRuntime } from "./transport"
+import type { HttpRequestTransform, Transport, TransportRuntime } from "./transport"
 import { WebSocketExecutor } from "./transport"
 import type { Protocol } from "./protocol"
 import { applyCachePolicy } from "../cache-policy"
 import * as ProviderShared from "../protocols/shared"
-import type { LLMError, PreparedRequestOf, ProtocolID, ProviderOptions } from "../schema"
+import type { LLMError, ProtocolID, ProviderOptions } from "../schema"
 import {
   GenerationOptions,
   HttpOptions,
@@ -20,7 +20,6 @@ import {
   ModelLimits,
   LLMError as LLMErrorClass,
   LLMEvent,
-  PreparedRequest,
   ProviderID,
   mergeGenerationOptions,
   mergeHttpOptions,
@@ -46,8 +45,12 @@ export interface Route<Body, Prepared = unknown> {
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
   readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared>
-  readonly model: (input: RouteMappedModelInput) => Model
+  readonly model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedModelInput) => Model<Options>
-  readonly prepareTransport: (body: Body, request: LLMRequest) => Effect.Effect<Prepared, LLMError>
+  readonly prepareTransport: (
+    body: Body,
+    request: LLMRequest,
+    options?: StreamOptions,
+  ) => Effect.Effect<Prepared, LLMError>
   readonly streamPrepared: (
     prepared: Prepared,
     request: LLMRequest,
@@ -93,12 +96,12 @@ export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
 
 type RouteMappedModelInput = RouteModelInput | RouteRoutedModelInput
 
-const makeRouteModel = (route: AnyRoute, mapped: RouteMappedModelInput) => {
+const makeRouteModel = <Options extends ProviderOptions = ProviderOptions>(route: AnyRoute, mapped: RouteMappedModelInput) => {
   const provider = route.provider ?? ("provider" in mapped ? mapped.provider : undefined)
   if (!provider) throw new Error(`Route.model(${route.id}) requires a provider`)
   if (!endpointBaseURL(route.endpoint))
     throw new Error(`Route.model(${route.id}) requires an endpoint baseURL — configure it on the route first`)
-  return Model.make({
+  return Model.make<Options>({
     ...mapped,
     provider,
     route,
@@ -142,27 +145,20 @@ export const httpOptions = (input: HttpOptionsInput | undefined) => {
 }
 
 export interface Interface {
-  /**
-   * Compile a request through protocol body construction, validation, and HTTP
-   * preparation without sending it. Returns the prepared request including the
-   * provider-native body.
-   *
-   * Pass a `Body` type argument to statically expose the route's body
-   * shape (e.g. `prepare<OpenAIChatBody>(...)`) — the runtime body is
-   * identical, so this is a type-level assertion the caller makes about which
-   * route the request will resolve to.
-   */
-  readonly prepare: <Body = unknown>(request: LLMRequest) => Effect.Effect<PreparedRequestOf<Body>, LLMError>
   readonly stream: StreamMethod
   readonly generate: GenerateMethod
 }
 
+export interface StreamOptions {
+  readonly transform?: HttpRequestTransform
+}
+
 export interface StreamMethod {
-  (request: LLMRequest): Stream.Stream<LLMEvent, LLMError>
+  (request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, LLMError>
 }
 
 export interface GenerateMethod {
-  (request: LLMRequest): Effect.Effect<LLMResponse, LLMError>
+  (request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, LLMError>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/LLMClient") {}
@@ -296,8 +292,9 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
           defaults: mergeRouteDefaults(route.defaults, defaults),
         })
       },
-      model: (input) => makeRouteModel(route, input),
+      model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedModelInput) =>
-      prepareTransport: (body, request) =>
+        makeRouteModel<Options>(route, input),
+      prepareTransport: (body, request, options) =>
         routeInput.transport.prepare({
           body,
           request,
@@ -305,6 +302,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
           auth: routeInput.auth ?? Auth.none,
           encodeBody,
           headers: routeInput.headers,
+          transform: options?.transform,
         }),
       streamPrepared: (prepared: Prepared, request: LLMRequest, runtime: TransportRuntime) => {
         const route = `${request.model.provider}/${request.model.route.id}`
@@ -370,17 +368,14 @@ export function make<Body, Prepared, Frame, Event, State>(
   })
 }
 
-// `compile` is the important boundary: it turns a common `LLMRequest` into a
+const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest, options?: StreamOptions) {
-// validated provider body plus transport-private prepared data, but does not
-// execute transport.
-const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest) {
   const resolved = applyCachePolicy(resolveRequestOptions(request))
   const route = resolved.model.route
 
   const body = yield* route.body
     .from(resolved)
     .pipe(Effect.flatMap(ProviderShared.validateWith(Schema.decodeUnknownEffect(route.body.schema))))
-  const prepared = yield* route.prepareTransport(body, resolved)
+  const prepared = yield* route.prepareTransport(body, resolved, options)
 
   return {
     request: resolved,
@@ -390,30 +385,30 @@ const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest) {
   }
 })
 
-const prepareWith = Effect.fn("LLMClient.prepare")(function* (request: LLMRequest) {
+/** @internal Test-only projection of the execution compiler; not exported from package barrels. */
+export const compileRequest = Effect.fn("LLM.compileRequest")(function* (request: LLMRequest) {
   const compiled = yield* compile(request)
-
+  return {
-  return new PreparedRequest({
     id: compiled.request.id ?? "request",
     route: compiled.route.id,
     protocol: compiled.route.protocol,
     model: compiled.request.model,
     body: compiled.body,
     metadata: { transport: compiled.route.transport.id },
-  })
+  }
 })
 
-const streamRequestWith = (runtime: TransportRuntime) => (request: LLMRequest) =>
+const streamRequestWith = (runtime: TransportRuntime) => (request: LLMRequest, options?: StreamOptions) =>
   Stream.unwrap(
     Effect.gen(function* () {
-      const compiled = yield* compile(request)
+      const compiled = yield* compile(request, options)
       return compiled.route.streamPrepared(compiled.prepared, compiled.request, runtime)
     }),
   )
 
 const generateWith = (stream: Interface["stream"]) =>
-  Effect.fn("LLM.generate")(function* (request: LLMRequest) {
+  Effect.fn("LLM.generate")(function* (request: LLMRequest, options?: StreamOptions) {
-    const state = yield* stream(request).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce))
+    const state = yield* stream(request, options).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce))
     const response = LLMResponse.complete(state)
     if (response) return response
     return yield* ProviderShared.eventError(
@@ -422,27 +417,24 @@ const generateWith = (stream: Interface["stream"]) =>
     )
   })
 
-export const prepare = <Body = unknown>(request: LLMRequest) =>
+export function stream(request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, LLMError> {
-  prepareWith(request) as Effect.Effect<PreparedRequestOf<Body>, LLMError>
-
-export function stream(request: LLMRequest): Stream.Stream<LLMEvent, LLMError> {
   return Stream.unwrap(
     Effect.gen(function* () {
-      return (yield* Service).stream(request)
+      return (yield* Service).stream(request, options)
     }),
   ) as Stream.Stream<LLMEvent, LLMError>
 }
 
-export function generate(request: LLMRequest): Effect.Effect<LLMResponse, LLMError> {
+export function generate(request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, LLMError> {
   return Effect.gen(function* () {
-    return yield* (yield* Service).generate(request)
+    return yield* (yield* Service).generate(request, options)
   }) as Effect.Effect<LLMResponse, LLMError>
 }
 
-export const streamRequest = (request: LLMRequest) =>
+export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>
   Stream.unwrap(
     Effect.gen(function* () {
-      return (yield* Service).stream(request)
+      return (yield* Service).stream(request, options)
     }),
   )
 
@@ -453,7 +445,7 @@ export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer
       http: yield* RequestExecutor.Service,
       webSocket: Option.getOrUndefined(yield* Effect.serviceOption(WebSocketExecutor.Service)),
     })
-    return Service.of({ prepare: prepareWith as Interface["prepare"], stream, generate: generateWith(stream) })
+    return Service.of({ stream, generate: generateWith(stream) })
   }),
 )
 
@@ -462,7 +454,6 @@ export const Route = { make } as const
 export const LLMClient = {
   Service,
   layer,
-  prepare,
   stream,
   generate,
 } as const

packages/ai/src/route/index.ts

@@ -8,6 +8,7 @@ export type {
   AnyRoute,
   Interface as LLMClientShape,
   Service as LLMClientService,
+  StreamOptions,
 } from "./client"
 export * from "./executor"
 export { Auth } from "./auth"
@@ -22,4 +23,4 @@ export type { ApiKeyMode, AuthOverride, ProviderAuthOption } from "./auth-option
 export type { Definition as EndpointFn, EndpointInput } from "./endpoint"
 export type { Definition as FramingDef } from "./framing"
 export type { Protocol as ProtocolDef } from "./protocol"
-export type { Transport as TransportDef, TransportRuntime } from "./transport"
+export type { HttpRequest, HttpRequestTransform, Transport as TransportDef, TransportRuntime } from "./transport"

packages/ai/src/route/transport/http.ts

@@ -28,57 +28,9 @@ const applyQuery = (url: string, query: Record<string, string> | undefined) => {
   return next.toString()
 }
 
-const PROTOCOL_BODY_OVERLAY_DENYLIST = new Set([
-  "anthropic_version",
-  "content",
-  "contents",
-  "frequencyPenalty",
-  "frequency_penalty",
-  "generationConfig",
-  "inferenceConfig",
-  "input",
-  "maxTokens",
-  "max_tokens",
-  "messages",
-  "model",
-  "presencePenalty",
-  "presence_penalty",
-  "responseFormat",
-  "response_format",
-  "seed",
-  "stop",
-  "stopSequences",
-  "stop_sequences",
-  "stream",
-  "streamOptions",
-  "stream_options",
-  "system",
-  "systemInstruction",
-  "system_instruction",
-  "temperature",
-  "thinking",
-  "toolChoice",
-  "toolConfig",
-  "tool_choice",
-  "tool_config",
-  "tools",
-  "topK",
-  "topP",
-  "top_k",
-  "top_p",
-])
-
-const forbiddenBodyOverlayKeys = (body: Record<string, unknown>) =>
-  Object.keys(body).filter((key) => PROTOCOL_BODY_OVERLAY_DENYLIST.has(key))
-
 const bodyWithOverlay = <Body>(body: Body, request: LLMRequest, encodeBody: (body: Body) => string) =>
   Effect.gen(function* () {
     if (request.http?.body === undefined) return { jsonBody: body, bodyText: encodeBody(body) }
-    const forbiddenKeys = forbiddenBodyOverlayKeys(request.http.body)
-    if (forbiddenKeys.length > 0)
-      return yield* ProviderShared.invalidRequest(
-        `http.body cannot overlay protocol-owned field(s): ${forbiddenKeys.join(", ")}`,
-      )
     if (ProviderShared.isRecord(body)) {
       const overlaid = mergeJsonRecords(body, request.http.body) ?? {}
       return { jsonBody: overlaid, bodyText: ProviderShared.encodeJson(overlaid) }
@@ -120,14 +72,19 @@ export const httpJson = <Body, Frame>(input: HttpJsonInput<Body, Frame>): HttpJs
   id: "http-json",
   with: (patch) => httpJson({ ...input, ...patch }),
   prepare: (prepareInput) =>
-    jsonRequestParts({
+    Effect.gen(function* () {
-      ...prepareInput,
+      const parts = yield* jsonRequestParts({ ...prepareInput })
-    }).pipe(
+      const request = { url: parts.url, method: "POST", headers: { ...parts.headers }, body: parts.bodyText }
-      Effect.map((parts) => ({
+      yield* (prepareInput.transform?.(request) ?? Effect.void)
-        request: ProviderShared.jsonPost({ url: parts.url, body: parts.bodyText, headers: parts.headers }),
+      return {
+        request: ProviderShared.jsonPost({
+          url: request.url,
+          body: request.body ?? "",
+          headers: Headers.fromInput(request.headers),
+        }),
         framing: input.framing,
-      })),
+      }
-    ),
+    }),
   frames: (prepared, request, runtime) =>
     Stream.unwrap(
       runtime.http

packages/ai/src/route/transport/index.ts

@@ -10,6 +10,15 @@ export interface TransportRuntime {
   readonly webSocket?: WebSocketExecutorInterface
 }
 
+export interface HttpRequest {
+  url: string
+  readonly method: string
+  headers: Record<string, string>
+  body: string | undefined
+}
+
+export type HttpRequestTransform = (request: HttpRequest) => Effect.Effect<void>
+
 export interface Transport<Body, Prepared, Frame> {
   readonly id: string
   readonly prepare: (input: TransportPrepareInput<Body>) => Effect.Effect<Prepared, LLMError>
@@ -27,6 +36,7 @@ export interface TransportPrepareInput<Body> {
   readonly auth: Auth.Definition
   readonly encodeBody: (body: Body) => string
   readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
+  readonly transform?: HttpRequestTransform
 }
 
 export * as HttpTransport from "./http"

packages/ai/src/schema/events.ts

@@ -1,6 +1,5 @@
 import { Schema } from "effect"
-import { ContentBlockID, FinishReason, ProtocolID, ProviderMetadata, RouteID, ToolCallID } from "./ids"
+import { ContentBlockID, FinishReason, ProviderMetadata, ToolCallID } from "./ids"
-import { ModelSchema } from "./options"
 import { Message, ToolCallPart, ToolOutput, ToolResultPart, ToolResultValue, type ContentPart } from "./messages"
 import { ProviderFailureClassification } from "./errors"
 
@@ -314,29 +313,6 @@ export const LLMEvent = Object.assign(llmEventTagged, {
 })
 export type LLMEvent = Schema.Schema.Type<typeof llmEventTagged>
 
-export class PreparedRequest extends Schema.Class<PreparedRequest>("LLM.PreparedRequest")({
-  id: Schema.String,
-  route: RouteID,
-  protocol: ProtocolID,
-  model: ModelSchema,
-  body: Schema.Unknown,
-  metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-}) {}
-
-/**
- * A `PreparedRequest` whose `body` is typed as `Body`. Use with the generic
- * on `LLMClient.prepare<Body>(...)` when the caller knows which route their
- * request will resolve to and wants its native shape statically exposed
- * (debug UIs, request previews, plan rendering).
- *
- * The runtime body is identical — the route still emits `body: unknown` — so
- * this is a type-level assertion the caller makes about what they expect to
- * find. The prepare runtime does not validate the assertion.
- */
-export type PreparedRequestOf<Body> = Omit<PreparedRequest, "body"> & {
-  readonly body: Body
-}
-
 const responseText = (events: ReadonlyArray<LLMEvent>) =>
   events
     .filter(LLMEvent.is.textDelta)

packages/ai/src/schema/messages.ts

@@ -124,6 +124,7 @@ export const ToolCallPart = Object.assign(
     name: Schema.String,
     input: Schema.Unknown,
     providerExecuted: Schema.optional(Schema.Boolean),
+    cache: Schema.optional(CacheHint),
     metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
     providerMetadata: Schema.optional(ProviderMetadata),
   }).annotate({ identifier: "LLM.Content.ToolCall" }),
@@ -168,6 +169,7 @@ export const ReasoningPart = Schema.Struct({
   type: Schema.Literal("reasoning"),
   text: Schema.String,
   encrypted: Schema.optional(Schema.String),
+  cache: Schema.optional(CacheHint),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Content.Reasoning" })

packages/ai/src/schema/options.ts

@@ -123,6 +123,7 @@ export const mergeGenerationOptions = (...items: ReadonlyArray<GenerationOptions
 
 export class ModelLimits extends Schema.Class<ModelLimits>("LLM.ModelLimits")({
   context: Schema.optional(Schema.Number),
+  input: Schema.optional(Schema.Number),
   output: Schema.optional(Schema.Number),
 }) {}
 
@@ -166,9 +167,13 @@ export namespace ModelDefaults {
 export const ModelToolSchemaCompatibility = Schema.Literals(["gemini", "moonshot"])
 export type ModelToolSchemaCompatibility = Schema.Schema.Type<typeof ModelToolSchemaCompatibility>
 
+export const ModelMaxTokensFieldCompatibility = Schema.Literals(["max_completion_tokens", "max_tokens"])
+export type ModelMaxTokensFieldCompatibility = Schema.Schema.Type<typeof ModelMaxTokensFieldCompatibility>
+
 export class ModelCompatibility extends Schema.Class<ModelCompatibility>("LLM.ModelCompatibility")({
   toolSchema: Schema.optional(ModelToolSchemaCompatibility),
   reasoningField: Schema.optional(Schema.String),
+  maxTokensField: Schema.optional(ModelMaxTokensFieldCompatibility),
 }) {}
 
 export namespace ModelCompatibility {
@@ -178,7 +183,8 @@ export namespace ModelCompatibility {
   export const make = (input: Input) => (input instanceof ModelCompatibility ? input : new ModelCompatibility(input))
 }
 
-export class Model {
+export class Model<Options extends ProviderOptions = ProviderOptions> {
+  declare protected readonly _ProviderOptions: Options
   readonly id: ModelID
   readonly provider: ProviderID
   readonly route: AnyRoute
@@ -193,8 +199,8 @@ export class Model {
     this.compatibility = input.compatibility
   }
 
-  static make(input: Model.Input) {
+  static make<Options extends ProviderOptions = ProviderOptions>(input: Model.Input) {
-    return new Model({
+    return new Model<Options>({
       id: ModelID.make(input.id),
       provider: ProviderID.make(input.provider),
       route: input.route,
@@ -203,7 +209,7 @@ export class Model {
     })
   }
 
-  static input(model: Model): Model.ConstructorInput {
+  static input<Options extends ProviderOptions>(model: Model<Options>): Model.ConstructorInput {
     return {
       id: model.id,
       provider: model.provider,
@@ -213,9 +219,9 @@ export class Model {
     }
   }
 
-  static update(model: Model, patch: Partial<Model.Input>) {
+  static update<Options extends ProviderOptions>(model: Model<Options>, patch: Partial<Model.Input>) {
     if (Object.keys(patch).length === 0) return model
-    return Model.make({
+    return Model.make<Options>({
       ...Model.input(model),
       ...patch,
     })
@@ -241,6 +247,8 @@ export namespace Model {
 
 export type ModelInput = Model.Input
 
+export type ModelProviderOptions<SelectedModel> = SelectedModel extends Model<infer Options> ? Options : never
+
 export const ModelSchema = Schema.declare((value): value is Model => value instanceof Model, { expected: "LLM.Model" })
 
 export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({

packages/ai/src/testing.ts

@@ -99,7 +99,6 @@ export const layer = (options: LayerOptions = {}) =>
         )
       }) as LLMClientShape["stream"]
       const client = LLMClient.Service.of({
-        prepare: () => Effect.die("TestLLM does not prepare provider-native requests"),
         stream,
         generate: (request) =>
           stream(request).pipe(

packages/ai/test/adapter.test.ts

@@ -2,6 +2,7 @@ import { describe, expect } from "bun:test"
 import { Effect, Schema, Stream } from "effect"
 import { LLM, LLMRequest, LLMResponse } from "../src"
 import { Route, Endpoint, LLMClient, Protocol, type FramingDef } from "../src/route"
+import { compileRequest } from "../src/route/client"
 import { Model } from "../src/schema"
 import { testEffect } from "./lib/effect"
 import { dynamicResponse } from "./lib/http"
@@ -139,8 +140,7 @@ describe("llm route", () => {
 
   it.effect("selects routes by model route value", () =>
     Effect.gen(function* () {
-      const llm = yield* LLMClient.Service
+      const prepared = yield* compileRequest(
-      const prepared = yield* llm.prepare(
         LLMRequest.update(request, { model: updateModel(request.model, { route: configuredGemini }) }),
       )
 
@@ -173,7 +173,7 @@ describe("llm route", () => {
         framing: fakeFraming,
       })
 
-      const prepared = yield* (yield* LLMClient.Service).prepare(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, { model: updateModel(request.model, { route: duplicate }) }),
       )
 

packages/ai/test/cache-policy.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { CacheHint, LLM, Message } from "../src"
-import { Auth, LLMClient } from "../src/route"
+import { Auth } from "../src/route"
+import { compileRequest } from "../src/route/client"
 import { AmazonBedrock } from "../src/providers"
 import * as AnthropicMessages from "../src/protocols/anthropic-messages"
 import * as Gemini from "../src/protocols/gemini"
@@ -31,7 +32,7 @@ const geminiModel = Gemini.route
 describe("applyCachePolicy", () => {
   it.effect("undefined cache resolves to 'auto' (the recommended default)", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           system: "You are concise.",
@@ -50,7 +51,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("'auto' marks the last tool, first and last system parts, and final message boundary on Anthropic", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           system: [
@@ -87,7 +88,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("'auto' is a no-op on OpenAI (implicit caching protocol)", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: openaiModel,
           system: "Sys",
@@ -106,7 +107,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("'auto' is a no-op on Gemini (out-of-band caching protocol)", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: geminiModel,
           system: "Sys",
@@ -123,7 +124,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("'auto' on Bedrock emits cachePoint markers in the right places", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: bedrockModel,
           system: [
@@ -157,7 +158,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("'none' disables auto placement even when manual hints exist", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           system: "Sys",
@@ -176,7 +177,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("granular object form: tools-only marks just tools", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           system: "Sys",
@@ -195,7 +196,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("auto policy preserves manual CacheHints on other parts", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           system: [
@@ -241,7 +242,7 @@ describe("applyCachePolicy", () => {
       expect("cache" in tail ? tail.cache : undefined).toBeUndefined()
       expect(applyCachePolicy(applied)).toBe(applied)
 
-      const prepared = yield* LLMClient.prepare(request)
+      const prepared = yield* compileRequest(request)
 
       const body = prepared.body as {
         tools: Array<{ cache_control?: unknown }>
@@ -261,7 +262,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("ttlSeconds in the policy flows through to wire markers", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           system: "Sys",
@@ -278,7 +279,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("messages: { tail: 2 } marks the last 2 message boundaries", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           messages: [Message.user("u1"), Message.assistant("a1"), Message.user("u2"), Message.assistant("a2")],
@@ -296,7 +297,7 @@ describe("applyCachePolicy", () => {
 
   it.effect("'latest-assistant' marks the last assistant message", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: anthropicModel,
           messages: [Message.user("u1"), Message.assistant("a1"), Message.user("u2")],

packages/ai/test/compile.test.ts

@@ -4,6 +4,7 @@ import { HttpClientRequest } from "effect/unstable/http"
 import { LLM, mergeProviderOptions } from "../src"
 import { AnthropicMessages, OpenAIChat } from "../src/protocols"
 import { Auth, LLMClient } from "../src/route"
+import { compileRequest } from "../src/route/client"
 import { it } from "./lib/effect"
 import { dynamicResponse } from "./lib/http"
 import { deltaChunk } from "./lib/openai-chunks"
@@ -44,7 +45,7 @@ describe("request option precedence", () => {
     })
   })
 
-  it.effect("prepares bodies with route defaults, model defaults, and call options in order", () =>
+  it.effect("compiles bodies with route defaults, model defaults, and call options in order", () =>
     Effect.gen(function* () {
       const route = OpenAIChat.route.with({
         endpoint: { baseURL: "https://api.openai.test/v1/" },
@@ -59,7 +60,7 @@ describe("request option precedence", () => {
           providerOptions: { openai: { reasoningEffort: "medium" } },
         },
       })
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "Say hello.",
@@ -136,24 +137,61 @@ describe("request option precedence", () => {
     ),
   )
 
-  it.effect("rejects raw body overlays for protocol-owned roots", () =>
+  it.effect("transforms the final HTTP request after serialization and authentication", () =>
-    Effect.gen(function* () {
+    LLMClient.generate(
-      const model = OpenAIChat.route
+      LLM.request({
-        .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+        model: OpenAIChat.route
-        .model({ id: "gpt-4o-mini" })
+          .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("fresh-key") })
-      const error = yield* LLMClient.prepare(
+          .model({ id: "gpt-4o-mini" }),
-        LLM.request({
+        prompt: "Say hello.",
-          model,
+      }),
-          prompt: "Say hello.",
+      {
-          http: { body: { model: "gpt-5", messages: [], tools: [] } },
+        transform: (request) =>
-        }),
+          Effect.sync(() => {
-      ).pipe(Effect.flip)
+            expect(request.headers.authorization).toBe("Bearer fresh-key")
+            request.url = "https://proxy.test/v1/chat/completions"
+            request.headers["x-plugin"] = "transformed"
+            request.body = JSON.stringify({ transformed: true })
+          }),
+      },
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.url).toBe("https://proxy.test/v1/chat/completions")
+            expect(web.headers.get("x-plugin")).toBe("transformed")
+            expect(decodeJson(input.text)).toEqual({ transformed: true })
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
 
-      expect(error.reason).toMatchObject({
+  it.effect("applies raw body overlays after protocol lowering", () =>
-        _tag: "InvalidRequest",
+    LLMClient.generate(
-        message: "http.body cannot overlay protocol-owned field(s): model, messages, tools",
+      LLM.request({
-      })
+        model: OpenAIChat.route
-    }),
+          .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+          .model({ id: "gpt-4o-mini" }),
+        prompt: "Say hello.",
+        http: { body: { model: "gpt-5", messages: [], tools: [] } },
+      }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            expect(decodeJson(input.text)).toMatchObject({ model: "gpt-5", messages: [], tools: [] })
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
   )
 
   it.effect("uses model output limits after route limits and before call maxTokens", () =>
@@ -164,10 +202,8 @@ describe("request option precedence", () => {
         limits: { output: 128 },
       })
       const model = route.model({ id: "claude-sonnet-4-5", defaults: { limits: { output: 64 } } })
-      const withoutMaxTokens = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const withoutMaxTokens = yield* compileRequest(LLM.request({ model, prompt: "Say hello.", cache: "none" }))
-        LLM.request({ model, prompt: "Say hello.", cache: "none" }),
+      const withMaxTokens = yield* compileRequest(
-      )
-      const withMaxTokens = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
         LLM.request({ model, prompt: "Say hello.", cache: "none", generation: { maxTokens: 32 } }),
       )
 

packages/ai/test/exports.test.ts

@@ -53,9 +53,7 @@ describe("public exports", () => {
     expect(CloudflareWorkersAI.configure).toBeFunction()
     expect(CloudflareWorkersAI.configure({ accountId: "fixture", apiKey: "fixture" }).model).toBeFunction()
     expect(OpenRouter.model).toBeFunction()
-    expect(OpenRouter.provider.model).toBe(OpenRouter.model)
     expect(XAI.model).toBeFunction()
-    expect(XAI.provider.model).toBe(XAI.model)
     expect(XAI.provider.responses).toBe(XAI.responses)
     expect(XAI.provider.chat).toBe(XAI.chat)
     expect(XAI.configure({ apiKey: "fixture" }).responses("grok-4.3").route.id).toBe("openai-responses")

packages/ai/test/llm-option-types.types.ts

@@ -0,0 +1,47 @@
+import { Schema } from "effect"
+import { LLM, type Model, type ModelProviderOptions, type ProviderOptions } from "../src"
+import { OpenAIChat } from "../src/protocols"
+
+interface ExampleOptions {
+  readonly [key: string]: unknown
+  readonly mode?: "fast" | "thorough"
+}
+
+type ExampleProviderOptions = ProviderOptions & {
+  readonly example?: ExampleOptions
+}
+
+const model = OpenAIChat.route
+  .with({ endpoint: { baseURL: "https://example.com/v1" } })
+  .model<ExampleProviderOptions>({ id: "example" })
+
+LLM.request({ model, prompt: "Hello", providerOptions: { example: { mode: "fast" } } })
+LLM.request({ model, prompt: "Hello", providerOptions: { future: { option: true } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Known provider options preserve their value types.
+  providerOptions: { example: { mode: "slow" } },
+})
+
+LLM.generateObject({
+  model,
+  prompt: "Hello",
+  schema: Schema.Struct({ answer: Schema.String }),
+  providerOptions: { example: { mode: "thorough" } },
+})
+
+LLM.generateObject({
+  model,
+  prompt: "Hello",
+  jsonSchema: { type: "object" },
+  // @ts-expect-error Dynamic object generation uses the selected model's provider options.
+  providerOptions: { example: { mode: false } },
+})
+
+declare const generic: Model
+LLM.request({ model: generic, prompt: "Hello", providerOptions: { arbitrary: { option: true } } })
+
+const options: ModelProviderOptions<typeof model> = { example: { mode: "fast" } }
+void options

packages/ai/test/provider-options/anthropic-compatible.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { AnthropicCompatible } from "../../src/providers"
+
+const model = AnthropicCompatible.configure({ baseURL: "https://example.com" }).model("claude")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { anthropic: { effort: "high" } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Anthropic effort must be a string.
+  providerOptions: { anthropic: { effort: 1 } },
+})

packages/ai/test/provider-options/anthropic.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { Anthropic } from "../../src/providers"
+
+const model = Anthropic.provider.model("claude-sonnet-4-5")
+
+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: { anthropic: { thinking: { type: "automatic" } } },
+})

packages/ai/test/provider-options/azure.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { Azure } from "../../src/providers"
+
+const model = Azure.configure({ resourceName: "example" }).responses("deployment")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { store: false } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Azure OpenAI store must be boolean.
+  providerOptions: { openai: { store: "false" } },
+})

packages/ai/test/provider-options/cloudflare.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { CloudflareWorkersAI } from "../../src/providers"
+
+const model = CloudflareWorkersAI.configure({ accountId: "account", apiKey: "test" }).model("model")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { promptCacheKey: "cache" } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Cloudflare's OpenAI-compatible prompt cache key must be a string.
+  providerOptions: { openai: { promptCacheKey: 1 } },
+})

packages/ai/test/provider-options/github-copilot.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { GitHubCopilot } from "../../src/providers"
+
+const model = GitHubCopilot.configure({ baseURL: "https://example.com" }).model("gpt-5")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { reasoningSummary: "auto" } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Copilot reasoning summaries use the OpenAI union.
+  providerOptions: { openai: { reasoningSummary: "full" } },
+})

packages/ai/test/provider-options/google-vertex-chat.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { GoogleVertexChat } from "../../src/providers"
+
+const model = GoogleVertexChat.configure({ accessToken: "test", project: "project" }).model("gemini")
+
+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: { openai: { serviceTier: "premium" } },
+})

packages/ai/test/provider-options/google-vertex-messages.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { GoogleVertexMessages } from "../../src/providers"
+
+const model = GoogleVertexMessages.configure({ accessToken: "test", project: "project" }).model("claude")
+
+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: { anthropic: { effort: false } },
+})

packages/ai/test/provider-options/google-vertex-responses.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { GoogleVertexResponses } from "../../src/providers"
+
+const model = GoogleVertexResponses.configure({ accessToken: "test", project: "project" }).model("gemini")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openresponses: { textVerbosity: "high" } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Vertex Responses verbosity uses the Open Responses union.
+  providerOptions: { openresponses: { textVerbosity: "verbose" } },
+})

packages/ai/test/provider-options/google-vertex.types.ts

@@ -0,0 +1,17 @@
+import { LLM } from "../../src"
+import { GoogleVertex } from "../../src/providers"
+
+const model = GoogleVertex.provider.configure({ apiKey: "test" }).model("gemini-2.5-pro")
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: { gemini: { thinkingConfig: { includeThoughts: true } } },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Vertex Gemini includeThoughts must be boolean.
+  providerOptions: { gemini: { thinkingConfig: { includeThoughts: "yes" } } },
+})

packages/ai/test/provider-options/google.types.ts

@@ -0,0 +1,47 @@
+import { LLM } from "../../src"
+import { Google } from "../../src/providers"
+
+const model = Google.provider.model("gemini-2.5-pro")
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1024 } } },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: {
+    gemini: {
+      // @ts-expect-error Gemini safety settings require a threshold for every category.
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH" }],
+    },
+  },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: {
+    gemini: {
+      cachedContent: "cachedContents/example",
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+      serviceTier: "future-tier",
+      thinkingConfig: { thinkingLevel: "high", includeThoughts: true },
+    },
+  },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error Gemini thinking budgets must be numeric.
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "large" } } },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "maximum" } } },
+})

packages/ai/test/provider-options/openai-compatible-responses.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { OpenAICompatibleResponses } from "../../src/providers"
+
+const model = OpenAICompatibleResponses.configure({ baseURL: "https://example.com" }).model("model")
+
+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: { openresponses: { reasoningSummary: "full" } },
+})

packages/ai/test/provider-options/openai-compatible.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { OpenAICompatible } from "../../src/providers"
+
+const model = OpenAICompatible.deepseek.model("deepseek-chat")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { store: false } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error OpenAI-compatible store must be boolean.
+  providerOptions: { openai: { store: "false" } },
+})

packages/ai/test/provider-options/openai.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { OpenAI } from "../../src/providers"
+
+const model = OpenAI.responses("gpt-5")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { reasoningEffort: "high" } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error OpenAI reasoning effort must be a string.
+  providerOptions: { openai: { reasoningEffort: 1 } },
+})

packages/ai/test/provider-options/openrouter.types.ts

@@ -0,0 +1,35 @@
+import { LLM } from "../../src"
+import { OpenRouter } from "../../src/providers"
+
+const model = OpenRouter.provider.model("anthropic/claude-sonnet-4.5")
+
+LLM.request({ model, prompt: "Hello", providerOptions: { openrouter: { usage: true } } })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: {
+    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",
+    },
+  },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  // @ts-expect-error OpenRouter usage must be boolean or an option record.
+  providerOptions: { openrouter: { usage: "yes" } },
+})

packages/ai/test/provider-options/xai.types.ts

@@ -0,0 +1,13 @@
+import { LLM } from "../../src"
+import { XAI } from "../../src/providers"
+
+const model = XAI.provider.model("grok-4")
+
+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: { xai: { reasoningEffort: true } },
+})

packages/ai/test/provider-package.test.ts

@@ -21,6 +21,8 @@ describe("provider package entrypoints", () => {
       import("@opencode-ai/ai/providers/google-vertex/chat"),
       import("@opencode-ai/ai/providers/google-vertex/responses"),
       import("@opencode-ai/ai/providers/google-vertex/messages"),
+      import("@opencode-ai/ai/providers/openrouter"),
+      import("@opencode-ai/ai/providers/xai"),
     ])
 
     for (const module of modules) expect(module.model).toBeFunction()
@@ -29,6 +31,35 @@ describe("provider package entrypoints", () => {
     expect(modules[12].model).toBe(modules[13].model)
   })
 
+  test("maps OpenRouter and xAI package settings onto executable models", async () => {
+    const OpenRouter = await import("@opencode-ai/ai/providers/openrouter")
+    const XAI = await import("@opencode-ai/ai/providers/xai")
+    const settings = {
+      apiKey: "fixture",
+      baseURL: "https://provider.example.test/v1",
+      headers: { "x-application": "opencode" },
+      body: { service_tier: "priority" },
+      limits: { context: 200_000, output: 64_000 },
+    }
+    const openrouter = OpenRouter.model("anthropic/claude-sonnet-4", {
+      ...settings,
+      providerOptions: { openrouter: { usage: true } },
+    })
+    const xai = XAI.model("grok-4", {
+      ...settings,
+      providerOptions: { xai: { reasoningEffort: "high" } },
+    })
+
+    for (const selected of [openrouter, xai]) {
+      expect(selected.route.endpoint.baseURL).toBe(settings.baseURL)
+      expect(selected.route.defaults.headers).toEqual(settings.headers)
+      expect(selected.route.defaults.http?.body).toEqual(settings.body)
+      expect(selected.route.defaults.limits).toEqual(settings.limits)
+    }
+    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", () => {
     const selected = model("gpt-5", {
       apiKey: "fixture",

packages/ai/test/provider/anthropic-messages.test.ts

@@ -3,6 +3,7 @@ import { Effect } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
 import { CacheHint, LLM, LLMError, LLMRequest, Message, ToolCallPart, ToolDefinition, Usage } from "../../src"
 import { Auth, LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
 import { continuationRequest, nativeAnthropicMessagesContinuation } from "../continuation-scenarios"
 import { it } from "../lib/effect"
@@ -44,7 +45,7 @@ const expectToolResult = (body: AnthropicMessages.AnthropicMessagesBody): Anthro
 describe("Anthropic Messages route", () => {
   it.effect("prepares Anthropic Messages target", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(request)
+      const prepared = yield* compileRequest(request)
 
       expect(prepared.body).toEqual({
         model: "claude-sonnet-4-5",
@@ -59,7 +60,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("lowers adaptive thinking settings with effort", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: {
             anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "low" },
@@ -76,17 +77,17 @@ describe("Anthropic Messages route", () => {
 
   it.effect("normalizes enabled and disabled thinking settings", () =>
     Effect.gen(function* () {
-      const enabled = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const enabled = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: 1_024 } } },
         }),
       )
-      const legacy = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const legacy = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: { anthropic: { thinking: { type: "enabled", budget_tokens: 2_048 } } },
         }),
       )
-      const disabled = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const disabled = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: { anthropic: { thinking: { type: "disabled" } } },
         }),
@@ -100,7 +101,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("rejects enabled thinking without a budget", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: { anthropic: { thinking: { type: "enabled" } } },
         }),
@@ -112,7 +113,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("lowers chronological system updates natively for Claude Opus 4.8 with cache hints", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: opus48,
           messages: [
@@ -137,7 +138,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("lowers chronological system updates to wrapped user text for unsupported Anthropic models", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -164,7 +165,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("rejects non-text chronological system update content before send", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model: opus48,
           messages: [
@@ -181,7 +182,7 @@ describe("Anthropic Messages route", () => {
   it.effect("falls back for unsupported native chronological system update placement", () =>
     Effect.gen(function* () {
       expect(
-        (yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        (yield* compileRequest(
           LLM.request({
             model: opus48,
             messages: [Message.assistant("Plain."), Message.system("After plain assistant.")],
@@ -196,12 +197,11 @@ describe("Anthropic Messages route", () => {
         },
       ])
       expect(
-        (yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        (yield* compileRequest(LLM.request({ model: opus48, messages: [Message.system("First.")], cache: "none" })))
-          LLM.request({ model: opus48, messages: [Message.system("First.")], cache: "none" }),
+          .body.messages,
-        )).body.messages,
       ).toEqual([{ role: "user", content: [{ type: "text", text: "<system-update>\nFirst.\n</system-update>" }] }])
       expect(
-        (yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        (yield* compileRequest(
           LLM.request({
             model: opus48,
             messages: [Message.user("Before."), Message.system("One."), Message.system("Two.")],
@@ -223,7 +223,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("rejects a system update between a local tool call and its result", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model: opus48,
           messages: [
@@ -242,7 +242,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("prepares tool call and tool result messages", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result",
           model,
@@ -273,7 +273,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("keeps tools and sends tool_choice none", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_choice_none",
           model,
@@ -303,7 +303,7 @@ describe("Anthropic Messages route", () => {
   // not JSON-stringified into `tool_result.content`.
   it.effect("lowers media tool-result content as structured blocks", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_image",
           model,
@@ -335,7 +335,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("lowers single-image tool-result content as a structured image block", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_image_only",
           model,
@@ -360,7 +360,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("rejects unsupported media in tool-result content with a clear error", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_unsupported_media",
           model,
@@ -384,7 +384,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("prepares the composed native continuation request", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         continuationRequest({
           id: "req_native_continuation_anthropic",
           model,
@@ -428,7 +428,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("lowers preserved Anthropic reasoning signature metadata", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -447,7 +447,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("round-trips redacted thinking as redacted_thinking blocks", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -628,9 +628,7 @@ describe("Anthropic Messages route", () => {
         { type: "reasoning", text: "", providerMetadata: { anthropic: { signature: "sig_1" } } },
       ])
 
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(LLM.request({ model, messages: [response.message], cache: "none" }))
-        LLM.request({ model, messages: [response.message], cache: "none" }),
-      )
       expect(prepared.body.messages).toEqual([
         { role: "assistant", content: [{ type: "thinking", thinking: "", signature: "sig_1" }] },
       ])
@@ -773,7 +771,7 @@ describe("Anthropic Messages route", () => {
           ),
         ),
       )
-      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -1133,7 +1131,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("round-trips provider-executed assistant content into server tool blocks", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_round_trip",
           model,
@@ -1184,7 +1182,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("rejects round-trip for unknown server tool names", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_unknown_server_tool",
           model,
@@ -1261,7 +1259,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("maps ttlSeconds >= 3600 to cache_control ttl: '1h'", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           system: { type: "text", text: "system", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3600 }) },
@@ -1277,7 +1275,7 @@ describe("Anthropic Messages route", () => {
 
   it.effect("emits cache_control on tool definitions and tool-result blocks", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           tools: [
@@ -1318,7 +1316,7 @@ describe("Anthropic Messages route", () => {
   it.effect("drops cache_control breakpoints past the 4-per-request cap", () =>
     Effect.gen(function* () {
       const hint = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           system: [
@@ -1344,7 +1342,7 @@ describe("Anthropic Messages route", () => {
   it.effect("spends breakpoint budget on tools before system before messages", () =>
     Effect.gen(function* () {
       const hint = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           tools: [

packages/ai/test/provider/bedrock-converse.test.ts

@@ -13,6 +13,7 @@ import {
   ToolDefinition,
 } from "../../src"
 import { LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import { AmazonBedrock } from "../../src/providers"
 import * as BedrockConverse from "../../src/protocols/bedrock-converse"
 import { it } from "../lib/effect"
@@ -101,7 +102,7 @@ const baseRequest = LLM.request({
 describe("Bedrock Converse route", () => {
   it.effect("prepares Converse target with system, inference config, and messages", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(baseRequest)
+      const prepared = yield* compileRequest(baseRequest)
 
       expect(prepared.body).toEqual({
         modelId: "anthropic.claude-3-5-sonnet-20240620-v1:0",
@@ -114,7 +115,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("passes topK through additionalModelRequestFields as top_k", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(
         LLMRequest.update(baseRequest, {
           generation: GenerationOptions.make({ maxTokens: 64, temperature: 0, topK: 40 }),
         }),
@@ -129,14 +130,14 @@ describe("Bedrock Converse route", () => {
 
   it.effect("omits additionalModelRequestFields when topK is unset", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(baseRequest)
+      const prepared = yield* compileRequest(baseRequest)
       expect(prepared.body.additionalModelRequestFields).toBeUndefined()
     }),
   )
 
   it.effect("lowers chronological system updates to wrapped user text in order", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [Message.user("Before."), Message.system("Update."), Message.assistant("After.")],
@@ -153,7 +154,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("prepares tool config with toolSpec and toolChoice", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLMRequest.update(baseRequest, {
           tools: [
             ToolDefinition.make({
@@ -187,7 +188,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("keeps tools and omits the unsupported choice when tool choice is none", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLMRequest.update(baseRequest, {
           tools: [
             ToolDefinition.make({
@@ -217,7 +218,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("lowers assistant tool-call + tool-result message history", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_history",
           model,
@@ -256,7 +257,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("lowers image content in tool-result messages", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_image",
           model,
@@ -491,7 +492,7 @@ describe("Bedrock Converse route", () => {
         providerMetadata: { bedrock: { signature: "sig_1" } },
       })
 
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -546,9 +547,7 @@ describe("Bedrock Converse route", () => {
         },
       ])
 
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(LLM.request({ model, messages: [response.message], cache: "none" }))
-        LLM.request({ model, messages: [response.message], cache: "none" }),
-      )
       expect(prepared.body.messages).toEqual([
         {
           role: "assistant",
@@ -639,7 +638,7 @@ describe("Bedrock Converse route", () => {
         text: "",
         providerMetadata: { bedrock: { redactedData } },
       })
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -754,7 +753,7 @@ describe("Bedrock Converse route", () => {
           secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
         },
       }).model("anthropic.claude-3-5-sonnet-20240620-v1:0")
-      const prepared = yield* LLMClient.prepare(LLMRequest.update(baseRequest, { model: signed }))
+      const prepared = yield* compileRequest(LLMRequest.update(baseRequest, { model: signed }))
 
       expect(prepared.route).toBe("bedrock-converse")
       expect(prepared.model).toBe(signed)
@@ -764,7 +763,7 @@ describe("Bedrock Converse route", () => {
   it.effect("emits cachePoint markers after system, user-text, and assistant-text with cache hints", () =>
     Effect.gen(function* () {
       const cache = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_cache",
           model,
@@ -796,7 +795,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("does not emit cachePoint when no cache hint is set", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(baseRequest)
+      const prepared = yield* compileRequest(baseRequest)
       expect(prepared.body).toMatchObject({
         system: [{ text: "You are concise." }],
         messages: [{ role: "user", content: [{ text: "Say hello." }] }],
@@ -806,7 +805,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("lowers image media into Bedrock image blocks", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_image",
           model,
@@ -843,7 +842,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("base64-encodes Uint8Array image bytes", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_image_bytes",
           model,
@@ -865,7 +864,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("lowers document media into Bedrock document blocks with format and name", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_doc",
           model,
@@ -897,7 +896,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("requires names for document media", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model,
           messages: [Message.user({ type: "media", mediaType: "application/pdf", data: "UERGREFUQQ==" })],
@@ -910,7 +909,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("passes named document-only messages through for provider validation", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           cache: "none",
@@ -936,7 +935,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("lowers document media in tool results", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           cache: "none",
@@ -988,7 +987,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("rejects unsupported image media types", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_bad_image",
           model,
@@ -1002,7 +1001,7 @@ describe("Bedrock Converse route", () => {
 
   it.effect("rejects unsupported document media types", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_bad_doc",
           model,
@@ -1017,7 +1016,7 @@ describe("Bedrock Converse route", () => {
   it.effect("maps ttlSeconds >= 3600 to cachePoint ttl: '1h'", () =>
     Effect.gen(function* () {
       const cache = new CacheHint({ type: "ephemeral", ttlSeconds: 3600 })
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           system: [{ type: "text", text: "system", cache }],
@@ -1034,7 +1033,7 @@ describe("Bedrock Converse route", () => {
   it.effect("appends cachePoint after marked tool definitions and tool-result blocks", () =>
     Effect.gen(function* () {
       const cache = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           tools: [{ name: "lookup", description: "lookup", inputSchema: { type: "object", properties: {} }, cache }],
@@ -1066,7 +1065,7 @@ describe("Bedrock Converse route", () => {
   it.effect("drops cachePoint markers past the 4-per-request cap", () =>
     Effect.gen(function* () {
       const cache = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           system: [

packages/ai/test/provider/cloudflare.test.ts

@@ -3,7 +3,7 @@ import { ConfigProvider, Effect, Schema } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
 import { LLM, LLMEvent } from "../../src"
 import { CloudflareAIGateway, CloudflareWorkersAI } from "../../src/providers/cloudflare"
-import { LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import { it } from "../lib/effect"
 import { dynamicResponse } from "../lib/http"
 import { sseEvents } from "../lib/sse"
@@ -34,7 +34,7 @@ describe("Cloudflare", () => {
       })
       expect(model.route.endpoint.baseURL).toBe("https://gateway.ai.cloudflare.com/v1/test-account/test-gateway/compat")
 
-      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Say hello." }))
+      const prepared = yield* compileRequest(LLM.request({ model, prompt: "Say hello." }))
 
       expect(prepared.route).toBe("cloudflare-ai-gateway")
       expect(prepared.body).toMatchObject({
@@ -129,7 +129,7 @@ describe("Cloudflare", () => {
         openai: { reasoningField: "reasoning", reasoningDetails: merged },
       })
 
-      const replay = yield* LLMClient.prepare(LLM.request({ model, messages: [response.message] }))
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
       expect(replay.body.messages).toEqual([
         { role: "assistant", content: "Hello", reasoning: "Thinking", reasoning_details: merged },
       ])
@@ -180,7 +180,7 @@ describe("Cloudflare", () => {
 
   it.effect("allows a fully configured baseURL override", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: CloudflareAIGateway.configure({
             baseURL: "https://gateway.proxy.test/v1/custom/compat",
@@ -208,7 +208,7 @@ describe("Cloudflare", () => {
       })
       expect(model.route.endpoint.baseURL).toBe("https://api.cloudflare.com/client/v4/accounts/test-account/ai/v1")
 
-      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Say hello." }))
+      const prepared = yield* compileRequest(LLM.request({ model, prompt: "Say hello." }))
 
       expect(prepared.route).toBe("cloudflare-workers-ai")
       expect(prepared.body).toMatchObject({

packages/ai/test/provider/gemini.test.ts

@@ -2,6 +2,7 @@ import { describe, expect } from "bun:test"
 import { Effect } from "effect"
 import { LLM, LLMError, LLMRequest, Message, ToolCallPart, ToolDefinition, Usage } from "../../src"
 import { Auth, LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import * as Gemini from "../../src/protocols/gemini"
 import { ProviderShared } from "../../src/protocols/shared"
 import { it } from "../lib/effect"
@@ -26,7 +27,7 @@ const request = LLM.request({
 describe("Gemini route", () => {
   it.effect("prepares Gemini target", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(request)
+      const prepared = yield* compileRequest(request)
 
       expect(prepared.body).toEqual({
         contents: [{ role: "user", parts: [{ text: "Say hello." }] }],
@@ -38,28 +39,56 @@ describe("Gemini route", () => {
 
   it.effect("normalizes Gemini thinking options", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 0, includeThoughts: false } } },
+          providerOptions: {
+            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* LLMClient.prepare<Gemini.GeminiBody>(
+      const filtered = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "invalid", includeThoughts: false } } },
         }),
       )
+      const defaulted = yield* compileRequest(
+        LLMRequest.update(request, {
+          providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "high" } } },
+        }),
+      )
+      const emptySafetySettings = yield* compileRequest(
+        LLMRequest.update(request, {
+          providerOptions: { gemini: { safetySettings: [] } },
+        }),
+      )
 
       expect(prepared.body.generationConfig?.thinkingConfig).toEqual({
         thinkingBudget: 0,
         includeThoughts: false,
+        thinkingLevel: "high",
       })
+      expect(prepared.body.cachedContent).toBe("cachedContents/example")
+      expect(prepared.body.safetySettings).toEqual([
+        { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" },
+      ])
+      expect(prepared.body.serviceTier).toBe("priority")
       expect(filtered.body.generationConfig?.thinkingConfig).toEqual({ includeThoughts: false })
+      expect(defaulted.body.generationConfig?.thinkingConfig).toEqual({
+        includeThoughts: true,
+        thinkingLevel: "high",
+      })
+      expect(emptySafetySettings.body.safetySettings).toEqual([])
     }),
   )
 
   it.effect("lowers chronological system updates to wrapped user text in order", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [Message.user("Before."), Message.system("Update."), Message.assistant("After.")],
@@ -75,7 +104,7 @@ describe("Gemini route", () => {
 
   it.effect("prepares multimodal user input and tool history", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result",
           model,
@@ -143,7 +172,7 @@ describe("Gemini route", () => {
 
   it.effect("continues media tool results as inline model input without base64 text", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -188,7 +217,7 @@ describe("Gemini route", () => {
 
   it.effect("strips matching data URLs to raw base64 inlineData", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -229,7 +258,7 @@ describe("Gemini route", () => {
   ] as const)
     it.effect(`rejects ${name}`, () =>
       Effect.gen(function* () {
-        const error = yield* LLMClient.prepare(
+        const error = yield* compileRequest(
           LLM.request({ model, messages: [Message.user({ type: "media", ...media })] }),
         ).pipe(Effect.flip)
         expect(error.message).toMatch(/does not support|does not match|valid base64/)
@@ -238,7 +267,7 @@ describe("Gemini route", () => {
 
   it.effect("rejects oversized image input", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -256,7 +285,7 @@ describe("Gemini route", () => {
 
   it.effect("keeps tools and sends function calling mode NONE", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_choice_none",
           model,
@@ -276,7 +305,7 @@ describe("Gemini route", () => {
 
   it.effect("sanitizes integer enums, dangling required, untyped arrays, and scalar object keys", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_schema_patch",
           model,
@@ -457,7 +486,7 @@ describe("Gemini route", () => {
         response.events.findIndex((event) => event.type === "tool-call"),
       )
 
-      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -691,7 +720,7 @@ describe("Gemini route", () => {
 
   it.effect("rejects unsupported assistant media content", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_media",
           model,

packages/ai/test/provider/google-vertex.test.ts

@@ -4,6 +4,7 @@ import { HttpClientRequest } from "effect/unstable/http"
 import { LLM } from "../../src"
 import { GoogleVertex, GoogleVertexChat, GoogleVertexMessages, GoogleVertexResponses } from "../../src/providers"
 import { LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import { it } from "../lib/effect"
 import { dynamicResponse } from "../lib/http"
 import { deltaChunk, finishChunk } from "../lib/openai-chunks"
@@ -180,23 +181,6 @@ describe("Google Vertex providers", () => {
     }),
   )
 
-  it.effect("protects the Vertex Messages API version from body overlays", () =>
-    Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
-        LLM.request({
-          model: GoogleVertexMessages.configure({
-            accessToken: "vertex-token",
-            http: { body: { anthropic_version: "wrong" } },
-            project: "vertex-project",
-          }).model("claude-sonnet-4-6"),
-          prompt: "Say hello.",
-        }),
-      ).pipe(Effect.flip)
-
-      expect(error.message).toContain("http.body cannot overlay protocol-owned field(s): anthropic_version")
-    }),
-  )
-
   it.effect("routes tuned Gemini models through their deployed endpoint", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(

packages/ai/test/provider/openai-chat-reasoning.recorded.test.ts

@@ -5,6 +5,7 @@ import { OpenAIChat } from "../../src/protocols/openai-chat"
 import * as OpenAICompatible from "../../src/providers/openai-compatible"
 import * as OpenRouter from "../../src/providers/openrouter"
 import { LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import { recordedTests } from "../recorded-test"
 import { expectWeatherToolLoop, goldenWeatherToolLoopRequest, runWeatherToolLoop } from "../recorded-scenarios"
 
@@ -84,9 +85,7 @@ for (const item of cases) {
             ),
           ).toBe(true)
 
-          const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+          const replay = yield* compileRequest(LLM.request({ model: item.model, messages: [response.message] }))
-            LLM.request({ model: item.model, messages: [response.message] }),
-          )
           expect(replay.body.messages).toMatchObject([
             { role: "assistant", content: response.text, reasoning: response.reasoning },
           ])

packages/ai/test/provider/openai-chat.test.ts

@@ -18,6 +18,7 @@ import * as OpenAI from "../../src/providers/openai"
 import * as OpenAIChat from "../../src/protocols/openai-chat"
 import { ProviderShared } from "../../src/protocols/shared"
 import { Auth, LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import { it } from "../lib/effect"
 import { dynamicResponse, fixedResponse, truncatedStream } from "../lib/http"
 import { deltaChunk, usageChunk } from "../lib/openai-chunks"
@@ -42,11 +43,7 @@ const request = LLM.request({
 describe("OpenAI Chat route", () => {
   it.effect("prepares OpenAI Chat payload", () =>
     Effect.gen(function* () {
-      // Pass the OpenAIChat payload type so `prepared.body` is statically
+      const prepared = yield* compileRequest(request)
-      // typed to the route's native shape — the assertions below read field
-      // names without `unknown` casts.
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(request)
-      const _typed: { readonly model: string; readonly stream: true } = prepared.body
 
       expect(prepared.body).toEqual({
         model: "gpt-4o-mini",
@@ -64,7 +61,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("lowers chronological system updates to escaped user wrappers in order", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -87,7 +84,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("replays canonical reasoning as OpenAI-compatible reasoning_content", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -105,7 +102,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("writes reasoning to a configured custom field on every assistant message", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: Model.update(model, { compatibility: { reasoningField: "vendor_reasoning" } }),
           messages: [
@@ -131,7 +128,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("rejects reasoning fields that conflict with assistant message fields", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model: Model.update(model, { compatibility: { reasoningField: "content" } }),
           messages: [Message.assistant([{ type: "reasoning", text: "thinking" }])],
@@ -144,7 +141,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("maps OpenAI provider options to Chat options", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).chat("gpt-4o-mini"),
           prompt: "think",
@@ -159,7 +156,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("passes through custom OpenAI-compatible reasoning effort strings", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "think",
@@ -253,7 +250,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("prepares assistant tool-call and tool-result messages", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result",
           model,
@@ -291,7 +288,7 @@ describe("OpenAI Chat route", () => {
   it.effect("preserves structured tool errors for the model", () =>
     Effect.gen(function* () {
       const error = { error: { type: "unknown", message: "Tool execution interrupted" } }
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -311,7 +308,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("continues image tool results as vision input without base64 text", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -355,7 +352,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("orders parallel tool responses before one aggregated vision message", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -405,7 +402,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("aggregates consecutive tool images with a following system update", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -446,7 +443,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("appends system updates without replacing multipart user content", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -474,7 +471,7 @@ describe("OpenAI Chat route", () => {
   ] as const)
     it.effect(`rejects ${name}`, () =>
       Effect.gen(function* () {
-        const error = yield* LLMClient.prepare(
+        const error = yield* compileRequest(
           LLM.request({ model, messages: [Message.user({ type: "media", ...media })] }),
         ).pipe(Effect.flip)
         expect(error.message).toMatch(/does not support|does not match|valid base64/)
@@ -483,7 +480,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("rejects oversized image input", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -501,7 +498,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("prepares raw and data URL image media as vision input", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_media",
           model,
@@ -528,7 +525,7 @@ describe("OpenAI Chat route", () => {
 
   it.effect("lowers reasoning-only assistant history", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_reasoning",
           model,
@@ -619,9 +616,7 @@ describe("OpenAI Chat route", () => {
           openai: { reasoningField: field },
         })
 
-        const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-          LLM.request({ model, messages: [response.message] }),
-        )
         expect(replay.body.messages).toEqual([{ role: "assistant", content: "Hello", [field]: "thinking" }])
       }
     }),
@@ -647,9 +642,7 @@ describe("OpenAI Chat route", () => {
         openai: { reasoningField: "vendor_reasoning" },
       })
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model: custom, messages: [response.message] }))
-        LLM.request({ model: custom, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([{ role: "assistant", content: "Hello", vendor_reasoning: "thinking" }])
     }),
   )
@@ -692,9 +685,7 @@ describe("OpenAI Chat route", () => {
         openai: { reasoningField: "reasoning", reasoningDetails: details },
       })
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([
         {
           role: "assistant",
@@ -737,9 +728,7 @@ describe("OpenAI Chat route", () => {
         openai: { reasoningDetails: details },
       })
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([{ role: "assistant", content: "Hello", reasoning_details: details }])
     }),
   )
@@ -764,9 +753,7 @@ describe("OpenAI Chat route", () => {
         openai: { reasoningField: "reasoning", reasoningDetails: details },
       })
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([
         { role: "assistant", content: "Hello", reasoning: "thinking", reasoning_details: details },
       ])
@@ -839,9 +826,7 @@ describe("OpenAI Chat route", () => {
         openai: { reasoningDetails: [] },
       })
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([{ role: "assistant", content: "Hello", reasoning_details: [] }])
     }),
   )
@@ -889,9 +874,7 @@ describe("OpenAI Chat route", () => {
         response.events.findIndex(LLMEvent.is.textStart),
       )
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([
         { role: "assistant", content: "Hello", reasoning: "thinking", reasoning_details: merged },
       ])
@@ -918,9 +901,7 @@ describe("OpenAI Chat route", () => {
       expect(response.events.filter(LLMEvent.is.reasoningStart)).toHaveLength(1)
       expect(response.events.filter(LLMEvent.is.reasoningEnd)).toHaveLength(1)
 
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(replay.body.messages).toEqual([{ role: "assistant", content: null, reasoning_details: details }])
     }),
   )
@@ -950,7 +931,7 @@ describe("OpenAI Chat route", () => {
     Effect.gen(function* () {
       const first = { type: "reasoning.text", text: "first", signature: "signed-0", index: 0 }
       const second = { type: "reasoning.text", text: "second", signature: "signed-1", index: 1 }
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -979,7 +960,7 @@ describe("OpenAI Chat route", () => {
   it.effect("retains scalar replay for mixed structured reasoning parts", () =>
     Effect.gen(function* () {
       const detail = { type: "reasoning.encrypted", data: "opaque", index: 0 }
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -1004,7 +985,7 @@ describe("OpenAI Chat route", () => {
   it.effect("replays native scalar reasoning alongside native details", () =>
     Effect.gen(function* () {
       const details = [{ type: "reasoning.encrypted", data: "opaque", index: 0 }]
-      const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const replay = yield* compileRequest(
         LLM.request({
           model,
           messages: [

packages/ai/test/provider/openai-compatible-chat.test.ts

@@ -3,6 +3,7 @@ import { Effect, Schema } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
 import { LLM, LLMRequest, Message, ToolCallPart, ToolChoice, ToolDefinition } from "../../src"
 import { Auth, LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import * as OpenAICompatible from "../../src/providers/openai-compatible"
 import * as OpenAICompatibleChat from "../../src/protocols/openai-compatible-chat"
 import { it } from "../lib/effect"
@@ -52,7 +53,7 @@ const providerFamilies = [
 describe("OpenAI-compatible Chat route", () => {
   it.effect("prepares generic Chat target", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, {
           tools: [ToolDefinition.make({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })],
           toolChoice: ToolChoice.make({ type: "required" }),
@@ -127,7 +128,7 @@ describe("OpenAI-compatible Chat route", () => {
 
   it.effect("matches AI SDK compatible basic request body fixture", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(request)
+      const prepared = yield* compileRequest(request)
 
       expect(prepared.body).toEqual({
         model: "deepseek-chat",
@@ -143,9 +144,23 @@ describe("OpenAI-compatible Chat route", () => {
     }),
   )
 
+  it.effect("configures the max tokens request field", () =>
+    Effect.gen(function* () {
+      const compatible = OpenAICompatibleChat.route
+        .with({ provider: "custom", endpoint: { baseURL: "https://api.custom.test/v1" } })
+        .model({ id: "custom-model", compatibility: { maxTokensField: "max_completion_tokens" } })
+      const prepared = yield* compileRequest(
+        LLM.request({ model: compatible, prompt: "Say hello.", generation: { maxTokens: 20 } }),
+      )
+
+      expect(prepared.body).toMatchObject({ max_completion_tokens: 20 })
+      expect(prepared.body).not.toHaveProperty("max_tokens")
+    }),
+  )
+
   it.effect("matches AI SDK compatible tool request body fixture", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_parity",
           model,

packages/ai/test/provider/openai-compatible-responses.test.ts

@@ -7,6 +7,7 @@ import { OpenResponses } from "../../src/protocols/open-responses"
 import { OpenAICompatibleResponses } from "../../src/protocols/openai-compatible-responses"
 import { OpenAIResponses } from "../../src/protocols/openai-responses"
 import { LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import { it } from "../lib/effect"
 import { fixedResponse } from "../lib/http"
 import { sseEvents } from "../lib/sse"
@@ -23,7 +24,7 @@ describe("Open Responses-compatible route", () => {
         baseURL: "https://responses.example.test/v1",
         provider: "example",
       }).model("example-model")
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           system: "You are concise.",
@@ -61,7 +62,7 @@ describe("Open Responses-compatible route", () => {
         apiKey: "test-key",
         baseURL: "https://responses.example.test/v1",
       }).model("example-model")
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({ model, prompt: "Draw.", tools: [OpenAI.imageGeneration()] }),
       ).pipe(Effect.flip)
 
@@ -76,7 +77,7 @@ describe("Open Responses-compatible route", () => {
         apiKey: "test-key",
         baseURL: "https://responses.example.test/v1",
       }).model("example-model")
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -102,7 +103,7 @@ describe("Open Responses-compatible route", () => {
         baseURL: "https://responses.example.test/v1",
         providerOptions: { openresponses: { reasoningEffort: "low", store: true } },
       }).model("example-model")
-      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Think." }))
+      const prepared = yield* compileRequest(LLM.request({ model, prompt: "Think." }))
 
       expect(prepared.body).toMatchObject({
         reasoning: { effort: "low" },

packages/ai/test/provider/openai-responses.test.ts

@@ -14,6 +14,7 @@ import {
   Usage,
 } from "../../src"
 import { Auth, LLMClient, RequestExecutor, WebSocketExecutor } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import * as Azure from "../../src/providers/azure"
 import * as OpenAI from "../../src/providers/openai"
 import * as XAI from "../../src/providers/xai"
@@ -56,7 +57,7 @@ const expectToolOutput = (body: OpenAIResponses.OpenAIResponsesBody): OpenAITool
 describe("OpenAI Responses route", () => {
   it.effect("prepares OpenAI Responses target", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(request)
+      const prepared = yield* compileRequest(request)
 
       expect(prepared.body).toEqual({
         model: "gpt-4.1-mini",
@@ -74,7 +75,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lowers the hosted OpenAI image generation tool", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "Show me a rooftop garden.",
@@ -92,7 +93,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("rejects invalid hosted image generation options locally", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           model,
           prompt: "Show me a rooftop garden.",
@@ -109,7 +110,7 @@ describe("OpenAI Responses route", () => {
     Effect.gen(function* () {
       const input = LLMRequest.update(request, { providerOptions: { openai: { serviceTier: "priority" } } })
       expect(input.providerOptions).toEqual({ openai: { serviceTier: "priority" } })
-      const prepared = yield* LLMClient.prepare(input)
+      const prepared = yield* compileRequest(input)
 
       expect(prepared.body).toMatchObject({ service_tier: "priority" })
       expect(prepared.body).not.toHaveProperty("serviceTier")
@@ -118,7 +119,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("passes through custom OpenAI reasoning effort strings", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, { providerOptions: { openai: { reasoningEffort: "experimental" } } }),
       )
 
@@ -128,7 +129,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("omits unsupported semantic service tiers", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, { providerOptions: { openai: { serviceTier: "unsupported" } } }),
       )
 
@@ -138,7 +139,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("flattens top-level object unions in function schemas", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, {
           tools: [
             ToolDefinition.make({
@@ -191,7 +192,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lowers chronological system updates to escaped user wrappers in order", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -217,7 +218,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("prepares OpenAI Responses WebSocket target", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLMRequest.update(request, {
           model: OpenAIResponses.webSocketRoute
             .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
@@ -395,7 +396,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("prepares function call and function output input items", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result",
           model,
@@ -432,7 +433,7 @@ describe("OpenAI Responses route", () => {
         content: [],
         structured: {},
       }
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -453,7 +454,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("keeps primitive tool errors as plain text", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -469,7 +470,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("keeps non-JSON tool errors as plain text", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -487,7 +488,7 @@ describe("OpenAI Responses route", () => {
   // image data is not JSON-stringified into `function_call_output.output`.
   it.effect("lowers image tool-result content as structured input_image items", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_image",
           model,
@@ -516,7 +517,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lowers single-image tool-result content as structured input_image array", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_image_only",
           model,
@@ -540,7 +541,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lowers PDF tool-result content as structured input_file array", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_pdf",
           model,
@@ -575,7 +576,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("uses xAI inline file encoding for PDF tool results", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: xaiModel,
           messages: [
@@ -610,7 +611,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("rejects unsupported media in tool-result content with a clear error", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_unsupported_media",
           model,
@@ -633,7 +634,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("prepares the composed native continuation request", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         continuationRequest({
           id: "req_native_continuation_openai",
           model,
@@ -675,7 +676,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("maps OpenAI provider options to Responses options", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).model("gpt-5.2"),
           prompt: "think",
@@ -700,7 +701,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("accepts the full ResponseIncludable union", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "hi",
@@ -722,7 +723,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("filters unknown includable values out of the include array", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "hi",
@@ -739,7 +740,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("treats an explicit empty include as no include at all", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({ model, prompt: "hi", providerOptions: { openai: { include: [] } } }),
       )
 
@@ -749,7 +750,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("treats an all-invalid include as no include at all", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({ model, prompt: "hi", providerOptions: { openai: { include: ["bogus.thing"] } } }),
       )
 
@@ -759,7 +760,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("omits include when no include is set", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({ model, prompt: "hi", providerOptions: { openai: { store: false } } }),
       )
 
@@ -773,7 +774,7 @@ describe("OpenAI Responses route", () => {
       // reasoningSummary: "auto" by default. Without `include`, a follow-up
       // turn cannot replay reasoning state, so the facade also opts into
       // `reasoning.encrypted_content` automatically.
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).responses("gpt-5.2"),
           prompt: "hi",
@@ -788,7 +789,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lets callers opt out of the GPT-5 default include", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).responses("gpt-5.2"),
           prompt: "hi",
@@ -802,7 +803,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("request OpenAI provider options override route defaults", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenAI.configure({
             baseURL: "https://api.openai.test/v1/",
@@ -934,9 +935,7 @@ describe("OpenAI Responses route", () => {
         },
       ])
 
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(LLM.request({ model, messages: [response.message] }))
-        LLM.request({ model, messages: [response.message] }),
-      )
       expect(prepared.body.input).toEqual([
         {
           role: "assistant",
@@ -1270,7 +1269,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("preserves assistant content order around reasoning items", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_reasoning_order",
           model,
@@ -1308,7 +1307,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("references stored reasoning items by id", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -1330,7 +1329,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("references stored provider-executed hosted tool results by id", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -1367,7 +1366,7 @@ describe("OpenAI Responses route", () => {
   it.effect("continues stateless hosted image generation with the generated image", () =>
     Effect.gen(function* () {
       const imageTool = OpenAI.imageGeneration({ action: "edit" })
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           messages: [
@@ -1408,7 +1407,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("joins streamed summary blocks into one continuation reasoning item", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_multi_summary_continuation",
           model,
@@ -1445,7 +1444,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("skips non-persisted reasoning ids without encrypted state", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_reasoning_without_encrypted_state",
           model,
@@ -1762,7 +1761,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lowers user image and PDF content", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           id: "req_media",
           model,
@@ -1793,7 +1792,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("uses xAI inline file encoding for user PDFs", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: xaiModel,
           messages: [
@@ -1825,7 +1824,7 @@ describe("OpenAI Responses route", () => {
 
   it.effect("rejects unsupported user media content", () =>
     Effect.gen(function* () {
-      const error = yield* LLMClient.prepare(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_media",
           model,

packages/ai/test/provider/openrouter.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, Message } from "../../src"
+import { CacheHint, LLM, Message } from "../../src"
 import { LLMClient } from "../../src/route"
+import { compileRequest } from "../../src/route/client"
 import * as OpenRouter from "../../src/providers/openrouter"
 import { it } from "../lib/effect"
 import { fixedResponse } from "../lib/http"
@@ -19,20 +20,141 @@ describe("OpenRouter", () => {
       })
       expect(model.route.endpoint.baseURL).toBe("https://openrouter.ai/api/v1")
 
-      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Say hello." }))
+      const prepared = yield* compileRequest(LLM.request({ model, prompt: "Say hello." }))
 
       expect(prepared.route).toBe("openrouter")
       expect(prepared.body).toMatchObject({
         model: "openai/gpt-4o-mini",
         messages: [{ role: "user", content: "Say hello." }],
         stream: true,
+        usage: { include: true },
       })
     }),
   )
 
+  it.effect("lowers the native cache policy to OpenRouter cache controls", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          system: [
+            { type: "text", text: "Base agent", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3_600 }) },
+            { type: "text", text: "Project instructions" },
+          ],
+          tools: [{ name: "lookup", description: "Lookup", inputSchema: { type: "object", properties: {} } }],
+          prompt: "Hello",
+          cache: { tools: true, system: true, messages: { tail: 1 } },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [{ cache_control: { type: "ephemeral" } }],
+        messages: [
+          {
+            role: "system",
+            content: [
+              { text: "Base agent", cache_control: { type: "ephemeral", ttl: "1h" } },
+              { text: "Project instructions", cache_control: { type: "ephemeral" } },
+            ],
+          },
+          {
+            role: "user",
+            content: [{ text: "Hello", cache_control: { type: "ephemeral" } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("lowers manual assistant and tool-result cache hints", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
+          messages: [
+            Message.user("Call the tool"),
+            Message.assistant([
+              { type: "text", text: "Calling", cache: new CacheHint({ type: "ephemeral" }) },
+              { type: "tool-call", id: "call_1", name: "lookup", input: {} },
+            ]),
+            Message.tool({
+              id: "call_1",
+              name: "lookup",
+              result: "Done",
+              cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3_600 }),
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toMatchObject([
+        { role: "user", content: "Call the tool" },
+        { role: "assistant", content: "Calling", cache_control: { type: "ephemeral" } },
+        { role: "tool", content: '"Done"', cache_control: { type: "ephemeral", ttl: "1h" } },
+      ])
+    }),
+  )
+
+  it.effect("caps manual cache controls at four breakpoints", () =>
+    Effect.gen(function* () {
+      const cache = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
+          system: [1, 2, 3, 4, 5].map((index) => ({ type: "text" as const, text: `System ${index}`, cache })),
+          prompt: "Hello",
+        }),
+      )
+
+      const system = prepared.body.messages[0]
+      expect(system?.role).toBe("system")
+      expect(
+        system && Array.isArray(system.content)
+          ? system.content.filter((part) => "cache_control" in part && part.cache_control !== undefined)
+          : [],
+      ).toHaveLength(4)
+    }),
+  )
+
+  it.effect("preserves cache policy hints on reasoning-only assistant messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: { messages: "latest-assistant" },
+          messages: [Message.user("Think"), Message.assistant([{ type: "reasoning", text: "Reasoning" }])],
+        }),
+      )
+
+      expect(prepared.body.messages).toMatchObject([
+        { role: "user", content: "Think" },
+        { role: "assistant", cache_control: { type: "ephemeral" } },
+      ])
+    }),
+  )
+
+  it.effect("allows usage accounting to be disabled explicitly", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({
+            apiKey: "test-key",
+            providerOptions: { openrouter: { usage: false } },
+          }).model("openai/gpt-4o-mini"),
+          cache: "none",
+          prompt: "Hello",
+        }),
+      )
+
+      expect(prepared.body.usage).toEqual({ include: false })
+    }),
+  )
+
   it.effect("applies OpenRouter payload options from the model helper", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({
             apiKey: "test-key",
@@ -41,6 +163,13 @@ describe("OpenRouter", () => {
                 usage: true,
                 reasoning: { effort: "high" },
                 promptCacheKey: "session_123",
+                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"),
@@ -52,10 +181,54 @@ describe("OpenRouter", () => {
         usage: { include: true },
         reasoning: { effort: "high" },
         prompt_cache_key: "session_123",
+        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 },
       })
     }),
   )
 
+  it.effect("filters invalid known OpenRouter options while preserving extensions", () =>
+    Effect.gen(function* () {
+      const invalid: Record<string, unknown> = {
+        usage: "yes",
+        models: "anthropic/claude-sonnet-4.6",
+        provider: [],
+        plugins: {},
+        web_search_options: [],
+        debug: [],
+        user: 123,
+        reasoning: [],
+        promptCacheKey: 123,
+        future_option: { enabled: true },
+      }
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({
+            apiKey: "test-key",
+            providerOptions: { openrouter: invalid },
+          }).model("openai/gpt-4o-mini"),
+          prompt: "Hello",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({ future_option: { enabled: true } })
+      expect(prepared.body).not.toHaveProperty("usage")
+      expect(prepared.body).not.toHaveProperty("models")
+      expect(prepared.body).not.toHaveProperty("provider")
+      expect(prepared.body).not.toHaveProperty("plugins")
+      expect(prepared.body).not.toHaveProperty("web_search_options")
+      expect(prepared.body).not.toHaveProperty("debug")
+      expect(prepared.body).not.toHaveProperty("user")
+      expect(prepared.body).not.toHaveProperty("reasoning")
+      expect(prepared.body).not.toHaveProperty("prompt_cache_key")
+    }),
+  )
+
   it.effect("preserves the upstream provider finish reason", () =>
     Effect.gen(function* () {
       const model = OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6")
@@ -100,9 +273,10 @@ describe("OpenRouter", () => {
         { type: "reasoning.text", signature: "signed", format: "anthropic-claude-v1", index: 0 },
         { type: "reasoning.encrypted", data: "opaque", format: "openai-responses-v1", index: 1 },
       ]
-      const prepared = yield* LLMClient.prepare<OpenRouter.OpenRouterBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [
             Message.assistant([
               {
@@ -133,9 +307,10 @@ describe("OpenRouter", () => {
         { type: "reasoning.encrypted", id: "state", data: "opaque" },
         { type: "reasoning.encrypted", id: "state", data: "opaque" },
       ]
-      const prepared = yield* LLMClient.prepare<OpenRouter.OpenRouterBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [
             Message.assistant({
               type: "reasoning",
@@ -158,9 +333,10 @@ describe("OpenRouter", () => {
         { type: "reasoning.text", id: "first", index: 0, text: "A", opaque: "first" },
         { type: "reasoning.text", id: "second", index: 1, text: "B", opaque: "second" },
       ]
-      const prepared = yield* LLMClient.prepare<OpenRouter.OpenRouterBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [
             Message.assistant({
               type: "reasoning",
@@ -179,9 +355,10 @@ describe("OpenRouter", () => {
 
   it.effect("omits scalar reasoning without continuation details", () =>
     Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare<OpenRouter.OpenRouterBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [Message.assistant({ type: "reasoning", text: "Thinking" })],
         }),
       )

packages/ai/test/tool-schema-projection.test.ts

@@ -3,7 +3,8 @@ import { Effect } from "effect"
 import { LLM } from "../src"
 import { OpenAIChat } from "../src/protocols"
 import { ToolSchemaProjection } from "../src/protocols/utils/tool-schema"
-import { Auth, LLMClient } from "../src/route"
+import { Auth } from "../src/route"
+import { compileRequest } from "../src/route/client"
 import { it } from "./lib/effect"
 
 describe("tool schema projections", () => {
@@ -79,7 +80,7 @@ describe("tool schema projections", () => {
       const model = OpenAIChat.route
         .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
         .model({ id: "kimi-k2", compatibility: { toolSchema: "moonshot" } })
-      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+      const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "Use the tool.",

packages/app/package.json

@@ -59,6 +59,7 @@
     "@opencode-ai/sdk": "file:vendor/opencode-ai-sdk-1.18.8-dev.tgz",
     "@opencode-ai/session-ui": "workspace:*",
     "@opencode-ai/ui": "workspace:*",
+    "@opencode-ai/util": "workspace:*",
     "@pierre/trees": "1.0.0-beta.4",
     "@sentry/solid": "catalog:",
     "@shikijs/transformers": "3.9.2",

packages/app/src/components/dialog-fork.tsx

@@ -69,7 +69,7 @@ export const DialogFork: Component = () => {
     const dir = base64Encode(sdk().directory)
 
     sdk()
-      .api.session.fork({ sessionID, messageID: item.id })
+      .api.session.fork({ sessionID, boundary: { type: "before", messageID: item.id } })
       .then((forked) => {
         dialog.close()
         prompt.set(restored, undefined, { dir, id: forked.id })

packages/app/src/components/titlebar-tab-nav.tsx

@@ -4,6 +4,7 @@ import { createResizeObserver } from "@solid-primitives/resize-observer"
 import { createMutation } from "@tanstack/solid-query"
 import { IconButtonV2 } from "@opencode-ai/ui/v2/icon-button-v2"
 import { Icon as IconV2 } from "@opencode-ai/ui/v2/icon"
+import { displayLabel } from "@opencode-ai/util/session-title-fallback"
 import { useGlobal } from "@/context/global"
 import { ServerConnection, serverName } from "@/context/server"
 import { displayName, projectForSession } from "@/pages/layout/helpers"
@@ -54,7 +55,10 @@ export function TabNavItem(props: {
     if (!session) return
     return projectForSession(session, serverCtx()?.projects.list() ?? [])
   })
-  const title = createMemo(() => props.session()?.title ?? props.fallbackTitle)
+  const title = createMemo(() => {
+    const session = props.session()
+    return session ? displayLabel(session) : props.fallbackTitle
+  })
 
   const projectName = createMemo(() => {
     const session = props.session()
@@ -143,7 +147,7 @@ export function TabNavItem(props: {
     if (!canOpenTabRename(props.dragging, editing(), rename.isPending)) return
     const session = props.session()
     if (!session) return
-    titleEl.textContent = session.title
+    titleEl.textContent = session.title ?? ""
     setEditing(true)
 
     requestAnimationFrame(() => {
@@ -302,7 +306,7 @@ export function TabNavItem(props: {
       }}
       data={{
         projectName: projectName(),
-        title: props.session()?.title,
+        title: title(),
         path: previewPath(),
         serverName: serverLabel(),
       }}

packages/app/src/context/global-sync/bootstrap.ts

@@ -129,8 +129,8 @@ export const loadProjectsQuery = (scope: ServerScope, api: ProjectApi) =>
         api.list().then((projects) => {
           return projects
             .filter((p) => !!p?.id)
-            .filter((p) => !!p.worktree && !p.worktree.includes("opencode-test"))
             .map(normalizeProjectInfo)
+            .filter((p) => !!p.worktree && !p.worktree.includes("opencode-test"))
             .slice()
             .sort((a, b) => cmp(a.id, b.id))
         }),

packages/app/src/context/global-sync/utils.ts

@@ -168,6 +168,7 @@ export function sanitizeProject(project: Project) {
 export function normalizeProjectInfo(project: Project | CurrentProject): Project {
   return {
     ...project,
+    worktree: "canonical" in project ? project.canonical : project.worktree,
     vcs: project.vcs === "git" ? "git" : undefined,
   }
 }

packages/app/src/pages/home/home-session-search-controller.ts

@@ -3,6 +3,7 @@ import { useLanguage } from "@/context/language"
 import { serverName } from "@/context/server"
 import { displayName } from "@/pages/layout/helpers"
 import { makeEventListener } from "@solid-primitives/event-listener"
+import { displayLabel } from "@opencode-ai/util/session-title-fallback"
 import { createMemo, onCleanup } from "solid-js"
 import { createStore } from "solid-js/store"
 import type { HomeController } from "./home-controller"
@@ -23,7 +24,7 @@ export function createHomeSessionSearchController(home: HomeController, sessions
     if (!value) return []
     return sessions.data
       .searchRecords()
-      .filter((record) => `${record.session.title} ${record.projectName}`.toLowerCase().includes(value))
+      .filter((record) => `${displayLabel(record.session)} ${record.projectName}`.toLowerCase().includes(value))
   })
   const active = createMemo(() => {
     const records = results()

packages/app/src/pages/home/home-sessions-view.tsx

@@ -6,10 +6,10 @@ import { ButtonV2 } from "@opencode-ai/ui/v2/button-v2"
 import { Icon as IconV2 } from "@opencode-ai/ui/v2/icon"
 import { IconButtonV2 } from "@opencode-ai/ui/v2/icon-button-v2"
 import { TooltipV2 } from "@opencode-ai/ui/v2/tooltip-v2"
+import { displayLabel } from "@opencode-ai/util/session-title-fallback"
 import { useLanguage } from "@/context/language"
 import { ServerConnection } from "@/context/server"
 import { SessionTabAvatarView } from "@/pages/layout/session-tab-avatar"
-import { sessionTitle } from "@/utils/session-title"
 import { shouldOpenSessionInBackground } from "../home-session-open"
 import {
   HomeSessionStatusController,
@@ -344,7 +344,7 @@ function HomeSessionSearchResultRow(
     selected: boolean
   },
 ) {
-  const title = createMemo(() => sessionTitle(props.record.session.title) || props.record.session.id)
+  const title = createMemo(() => displayLabel(props.record.session))
   const showProjectName = () => props.showProjectName() && props.record.projectName
   const key = () => homeSessionSearchKey(props.record)
 
@@ -415,7 +415,7 @@ function HomeSessionGroupHeader(props: {
 }
 
 function HomeSessionRow(props: HomeSessionsViewProps & { record: HomeSessionRecord }) {
-  const title = createMemo(() => sessionTitle(props.record.session.title) || props.record.session.id)
+  const title = createMemo(() => displayLabel(props.record.session))
   const showProjectName = () => props.showProjectName() && props.record.projectName
 
   return (

packages/app/src/pages/layout/sidebar-items.tsx

@@ -5,6 +5,7 @@ import { Icon as IconV2 } from "@opencode-ai/ui/v2/icon"
 import { IconButton } from "@opencode-ai/ui/icon-button"
 import { Spinner } from "@opencode-ai/ui/spinner"
 import { Tooltip } from "@opencode-ai/ui/tooltip"
+import { displayLabel } from "@opencode-ai/util/session-title-fallback"
 import { getFilename } from "@opencode-ai/core/util/path"
 import { A, useParams } from "@solidjs/router"
 import { type Accessor, createMemo, For, type JSX, Match, Show, Switch } from "solid-js"
@@ -14,7 +15,6 @@ import { getAvatarColors, type LocalProject, useLayout } from "@/context/layout"
 import { useNotification } from "@/context/notification"
 import { usePermission } from "@/context/permission"
 import { messageAgentColor } from "@/utils/agent"
-import { sessionTitle } from "@/utils/session-title"
 import { sessionPermissionRequest } from "../session/composer/session-request-tree"
 import { childSessionOnPath, getProjectAvatarSource, hasProjectPermissions } from "./helpers"
 
@@ -104,7 +104,7 @@ const SessionRow = (props: {
   warmPress: () => void
   warmFocus: () => void
 }): JSX.Element => {
-  const title = () => sessionTitle(props.session.title)
+  const title = () => displayLabel(props.session)
 
   return (
     <A
@@ -229,7 +229,7 @@ export const SessionItem = (props: SessionItemProps): JSX.Element => {
               fallback={
                 <Tooltip
                   placement={props.mobile ? "bottom" : "right"}
-                  value={sessionTitle(props.session.title)}
+                  value={displayLabel(props.session)}
                   gutter={10}
                   class="min-w-0 w-full"
                 >

packages/app/src/pages/session/timeline/message-timeline.tsx

@@ -70,7 +70,7 @@ import { legacySessionHref, requireServerKey, sessionHref } from "@/utils/sessio
 import { useSDK } from "@/context/sdk"
 import { useSync } from "@/context/sync"
 import { notifySessionTabsRemoved } from "@/components/titlebar-session-events"
-import { sessionTitle } from "@/utils/session-title"
+import { displayLabel } from "@opencode-ai/util/session-title-fallback"
 import { scheduleConnectedMeasure } from "./measure"
 import { observeElementOffsetReconnectAware } from "./observe-element-offset"
 import { createTimelineProjection } from "./projection"
@@ -296,8 +296,11 @@ export function MessageTimeline(props: {
     if (!id) return
     return sync().session.get(id)
   })
-  const titleValue = createMemo(() => info()?.title)
+  const titleLabel = createMemo(() => {
-  const titleLabel = createMemo(() => sessionTitle(titleValue()))
+    const session = info()
+    if (!session) return
+    return displayLabel(session)
+  })
   const shareUrl = createMemo(() => info()?.share?.url)
   const shareEnabled = createMemo(() => sync().data.config.share !== "disabled")
   const parentID = createMemo(() => info()?.parentID)
@@ -311,7 +314,10 @@ export function MessageTimeline(props: {
     if (!id) return emptyMessages
     return sync().data.message[id] ?? emptyMessages
   })
-  const parentTitle = createMemo(() => sessionTitle(parent()?.title) ?? language.t("command.session.new"))
+  const parentTitle = createMemo(() => {
+    const session = parent()
+    return session ? displayLabel(session) : language.t("command.session.new")
+  })
   const getMsgParts = (msgId: string) => sync().data.part[msgId] ?? emptyParts
   const getMsgPart = (messageID: string, partID: string) => getMsgParts(messageID).find((part) => part.id === partID)
   const childTaskDescription = createMemo(() => {
@@ -329,7 +335,7 @@ export function MessageTimeline(props: {
     if (value) return value
     return language.t("command.session.new")
   })
-  const showHeader = createMemo(() => !!(titleValue() || parentID()))
+  const showHeader = createMemo(() => !!(titleLabel() || parentID()))
   const projection = createTimelineProjection({
     messages: sessionMessages,
     userMessages: () => props.userMessages,
@@ -912,9 +918,10 @@ export function MessageTimeline(props: {
   }
 
   function DialogDeleteSession(props: { sessionID: string }) {
-    const name = createMemo(
+    const name = createMemo(() => {
-      () => sessionTitle(sync().session.get(props.sessionID)?.title) ?? language.t("command.session.new"),
+      const session = sync().session.get(props.sessionID)
-    )
+      return session ? displayLabel(session) : language.t("command.session.new")
+    })
     const handleDelete = async () => {
       await deleteSession(props.sessionID)
       dialog.close()

packages/app/src/pages/session/timeline/observe-element-offset.test.ts

@@ -38,17 +38,19 @@ test("reports a divergent native offset once and ignores equal offsets and unrel
     instance.scrollOffset = offset
   })
 
-  document.body.append(unrelated)
-  unrelated.remove()
-  await frames(2)
-  expect(calls).toEqual([])
-
   route.remove()
   document.body.append(route)
   await new Promise((resolve) => setTimeout(resolve, 0))
   await frames(3)
   expect(calls).toEqual([[0, false]])
 
+  instance.scrollOffset = 79_400
+  document.body.append(unrelated)
+  unrelated.remove()
+  await frames(2)
+  expect(calls).toEqual([[0, false]])
+
+  instance.scrollOffset = 0
   route.remove()
   document.body.append(route)
   await new Promise((resolve) => setTimeout(resolve, 0))

packages/app/src/utils/server-compat.test.ts

@@ -26,7 +26,6 @@ function setup(
         return new Response(undefined, { status: 204 })
       if (request.method === "POST" && request.url.endsWith("/prompt")) {
         return Response.json({
-          admittedSeq: 1,
           id: "msg_1",
           sessionID: "ses_1",
           timeCreated: 1,

packages/app/src/utils/server-compat.ts

@@ -128,7 +128,7 @@ function createV1Api(input: CompatibleInput): CompatibleApi {
   const located = <T>(data: T, value?: { directory?: string }) => ({
     location: {
       directory: directory(value) ?? "",
-      project: { id: "", directory: directory(value) ?? "" },
+      project: { id: "", directory: directory(value) ?? "", canonical: directory(value) ?? "" },
     },
     data,
   })
@@ -229,7 +229,6 @@ function createV1Api(input: CompatibleInput): CompatibleApi {
           ],
         })
         return {
-          admittedSeq: 0,
           id: value.id ?? "",
           sessionID: value.sessionID,
           timeCreated: Date.now(),
@@ -255,7 +254,6 @@ function createV1Api(input: CompatibleInput): CompatibleApi {
           })),
         })
         return {
-          admittedSeq: 0,
           id: value.id ?? "",
           sessionID: value.sessionID,
           timeCreated: Date.now(),
@@ -280,7 +278,6 @@ function createV1Api(input: CompatibleInput): CompatibleApi {
           modelID: value.model.modelID,
         })
         return {
-          admittedSeq: 0,
           id: value.id ?? "",
           sessionID: value.sessionID,
           timeCreated: Date.now(),
@@ -301,12 +298,19 @@ function createV1Api(input: CompatibleInput): CompatibleApi {
     project: {
       ...input.current.project,
       async list() {
-        return ((await legacy().project.list()).data ?? []) as Project[]
+        return ((await legacy().project.list()).data ?? []).map((project) => ({
+          ...project,
+          canonical: project.worktree,
+        }))
       },
       async current(value?: Parameters<ServerApi["project"]["current"]>[0]) {
         const result = await legacy(value?.location).project.current()
         if (!result.data) throw new Error("Project not found")
-        return { id: result.data.id, directory: result.data.worktree } satisfies ProjectCurrent
+        return {
+          id: result.data.id,
+          directory: result.data.worktree,
+          canonical: result.data.worktree,
+        } satisfies ProjectCurrent
       },
       // async update(value: Parameters<ServerApi["project"]["update"]>[0]) {
       //   const project = (await legacy().project.list()).data?.find((item) => item.id === value.projectID)

packages/app/src/utils/session-title.ts

@@ -1,7 +0,0 @@
-const pattern = /^(New session|Child session) - \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
-
-export function sessionTitle(title?: string) {
-  if (!title) return title
-  const match = title.match(pattern)
-  return match?.[1] ?? title
-}

packages/app/src/utils/session.ts

@@ -1,5 +1,6 @@
 import type { SessionApi, SessionInfo, SessionListInput } from "@opencode-ai/client/promise"
 import type { Session } from "@opencode-ai/sdk/v2/client"
+import { withTimestampedFallback } from "@opencode-ai/util/session-title-fallback"
 
 export function normalizeSessionInfo(input: SessionInfo | Session): Session {
   if (!("location" in input)) return input
@@ -13,7 +14,7 @@ export function normalizeSessionInfo(input: SessionInfo | Session): Session {
     parentID: input.parentID,
     cost: input.cost,
     tokens: input.tokens,
-    title: input.title,
+    title: withTimestampedFallback(input),
     agent: input.agent,
     model: input.model,
     version: "",

packages/cli/package.json

@@ -40,6 +40,9 @@
     "open": "10.1.2",
     "semver": "catalog:",
     "solid-js": "catalog:",
+    "tree-sitter-bash": "0.25.0",
+    "tree-sitter-powershell": "0.25.10",
+    "web-tree-sitter": "0.25.10",
     "uqr": "0.1.3",
     "ws": "8.21.0"
   },

packages/cli/script/build-node.ts

@@ -62,8 +62,8 @@ for (const target of targets) {
   await rm("dist-node", { recursive: true, force: true })
   const assetHash = await hashNodeAssets(assets)
   const input = { version: Script.version, channel: Script.channel, models: modelsData, assetHash, target }
-  await build(mainConfig(input))
   await copyNodeAssets(assets)
+  await build(mainConfig(input))
 
   const host = target.platform === process.platform && target.arch === process.arch
   if (host) {

packages/cli/script/node-assets.ts

@@ -3,7 +3,7 @@ import { copyFile, mkdir, readdir, readFile, stat } from "node:fs/promises"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { getNodeAssets } from "@opentui/core/node-assets"
-import { attentionSoundAssets, type NodeTarget, photonWasmAsset } from "../src/node/target"
+import { attentionSoundAssets, type NodeTarget, photonWasmAsset, shellParserWasmAssets } from "../src/node/target"
 
 const dir = path.resolve(import.meta.dirname, "..")
 
@@ -43,6 +43,10 @@ export async function collectNodeAssets(target: NodeTarget) {
       key: photonWasmAsset,
       source: fileURLToPath(import.meta.resolve(photonWasmAsset)),
     },
+    ...Object.values(shellParserWasmAssets).map((key) => ({
+      key,
+      source: fileURLToPath(import.meta.resolve(key)),
+    })),
     ...attentionSoundAssets.map((key) => ({
       key,
       source: path.resolve(dir, "../ui/src/assets/audio", path.basename(key)),
@@ -54,8 +58,9 @@ export async function collectNodeAssets(target: NodeTarget) {
         source: path.join(ptyRoot, relative),
       })),
   ]
-  await Promise.all(assets.map((asset) => stat(asset.source)))
+  const unique = [...new Map(assets.map((asset) => [asset.key, asset])).values()]
-  return assets
+  await Promise.all(unique.map((asset) => stat(asset.source)))
+  return unique
 }
 
 export async function hashNodeAssets(assets: readonly NodeAsset[]) {

packages/cli/src/acp/service.ts

@@ -8,6 +8,7 @@ import {
   type SessionMessageInfo,
   type SkillInfo,
 } from "@opencode-ai/client/promise"
+import { withTimestampedFallback } from "@opencode-ai/util/session-title-fallback"
 import type {
   AgentSideConnection,
   AuthenticateRequest,
@@ -213,7 +214,7 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
         sessions: page.data.map((session) => ({
           sessionId: session.id,
           cwd: session.location.directory,
-          title: session.title,
+          title: withTimestampedFallback(session),
           updatedAt: new Date(session.time.updated).toISOString(),
         })),
         ...(page.cursor.next ? { nextCursor: page.cursor.next } : {}),
@@ -244,7 +245,10 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
       return {}
     },
     forkSession: async (params) => {
-      const forked = await input.client.session.fork({ sessionID: params.sessionId })
+      const forked = await input.client.session.fork({
+        sessionID: params.sessionId,
+        boundary: { type: "through" },
+      })
       const state = await attach(forked, forked.location.directory, params.mcpServers ?? [])
       await replay(state)
       return { sessionId: state.id, configOptions: configOptions(state) }

packages/cli/src/node/target.ts

@@ -29,6 +29,11 @@ export function nodeTarget(platform: string, arch: string) {
 }
 
 export const photonWasmAsset = "@silvia-odwyer/photon-node/photon_rs_bg.wasm"
+export const shellParserWasmAssets = {
+  runtime: "web-tree-sitter/tree-sitter.wasm",
+  bash: "tree-sitter-bash/tree-sitter-bash.wasm",
+  powershell: "tree-sitter-powershell/tree-sitter-powershell.wasm",
+} as const
 export const nodeExecArgv = ["--experimental-ffi", "--use-system-ca", "--disable-warning=ExperimentalWarning"] as const
 
 export const attentionSoundAssets = [

packages/cli/src/session-target.ts

@@ -105,7 +105,7 @@ async function selectSession(input: {
     return {
       session: input.fork
         ? await input.client.session
-            .fork({ sessionID: explicit.id }, ...requestOptions(input.signal))
+            .fork({ sessionID: explicit.id, boundary: { type: "through" } }, ...requestOptions(input.signal))
             .catch((error) => {
               throw new SessionTargetMutationError(error)
             })
@@ -118,9 +118,11 @@ async function selectSession(input: {
   if (!selected) return { session: undefined, location }
   return {
     session: input.fork
-      ? await input.client.session.fork({ sessionID: selected.id }, ...requestOptions(input.signal)).catch((error) => {
+      ? await input.client.session
-          throw new SessionTargetMutationError(error)
+          .fork({ sessionID: selected.id, boundary: { type: "through" } }, ...requestOptions(input.signal))
-        })
+          .catch((error) => {
+            throw new SessionTargetMutationError(error)
+          })
       : selected,
   }
 }

packages/cli/test/acp/service-lifecycle.test.ts

@@ -136,7 +136,7 @@ describe("acp service lifecycle", () => {
       method: "POST",
       path: "/api/session/ses_loaded/fork",
       query: {},
-      body: {},
+      body: { boundary: { type: "through" } },
     })
   })
 

packages/cli/test/node-assets.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "bun:test"
+import { fileURLToPath } from "node:url"
+import { collectNodeAssets } from "../script/node-assets"
+import { nodeTarget, shellParserWasmAssets } from "../src/node/target"
+
+test("collects each SEA asset key once", async () => {
+  const assets = await collectNodeAssets(nodeTarget(process.platform, process.arch))
+  const keys = assets.map((asset) => asset.key)
+
+  expect(new Set(keys).size).toBe(keys.length)
+  expect(assets.filter((asset) => asset.key === shellParserWasmAssets.runtime)).toEqual([
+    {
+      key: shellParserWasmAssets.runtime,
+      source: fileURLToPath(import.meta.resolve(shellParserWasmAssets.runtime)),
+    },
+  ])
+})

packages/cli/test/run/noninteractive.test.ts

@@ -267,7 +267,7 @@ async function run(input: {
     values.push(...input.turn(messageID))
     wake?.()
     wake = undefined
-    return ok({ admittedSeq: 1, id: messageID, sessionID: "ses_1", timeCreated: 1 }) as never
+    return ok({ id: messageID, sessionID: "ses_1", timeCreated: 1 }) as never
   })
   await runNonInteractivePrompt({
     client: sdk,

packages/cli/test/session-target.test.ts

@@ -3,7 +3,7 @@ import { OpenCode, type LocationGetOutput, type ModelRef, type SessionInfo } fro
 import { resolveSessionTarget, SessionTargetMutationError } from "../src/session-target"
 
 function location(directory: string, workspaceID?: string): LocationGetOutput {
-  return { directory, workspaceID, project: { id: "project", directory } }
+  return { directory, workspaceID, project: { id: "project", directory, canonical: directory } }
 }
 
 function session(id: string, directory: string, workspaceID?: string, model?: ModelRef): SessionInfo {

packages/cli/vite.node.config.ts

@@ -3,7 +3,13 @@ import { readFile } from "node:fs/promises"
 import { createRequire } from "node:module"
 import { defineConfig, type Plugin, type UserConfig } from "vite"
 import solid from "vite-plugin-solid"
-import { nodeExecArgv, nodeTarget, type NodeTarget, photonWasmAsset } from "./src/node/target"
+import {
+  nodeExecArgv,
+  nodeTarget,
+  type NodeTarget,
+  photonWasmAsset,
+  shellParserWasmAssets,
+} from "./src/node/target"
 
 const dir = import.meta.dirname
 
@@ -194,6 +200,9 @@ process.env.OTUI_ASSET_ROOT = __ocAssetRoot
 process.env.OPENCODE_NODE_PTY_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.nodePtyEntryAsset)})
 process.env.OPENCODE_PARCEL_WATCHER_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.parcelWatcherAsset)})
 process.env.OPENCODE_PHOTON_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(photonWasmAsset)})
+process.env.OPENCODE_TREE_SITTER_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(shellParserWasmAssets.runtime)})
+process.env.OPENCODE_TREE_SITTER_BASH_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(shellParserWasmAssets.bash)})
+process.env.OPENCODE_TREE_SITTER_POWERSHELL_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(shellParserWasmAssets.powershell)})
 process.env.FFF_BINARY_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.fffAsset)})
 process.env.OPENCODE_FFF_FFI_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.fffFfiAsset)})
 try {

packages/client/src/effect/api/api.ts

@@ -118,6 +118,7 @@ export type SessionListOperation<E = never> = (input?: Endpoint5_0Input) => Effe
 
 export type Endpoint5_1Input = {
   readonly id?: Session.ID | undefined
+  readonly title?: string | undefined
   readonly agent?: Agent.ID | undefined
   readonly model?: Model.Ref | undefined
   readonly location?: Location.Ref | undefined
@@ -136,7 +137,7 @@ export type Endpoint5_4Input = { readonly sessionID: Session.ID }
 export type Endpoint5_4Output = void
 export type SessionRemoveOperation<E = never> = (input: Endpoint5_4Input) => Effect.Effect<Endpoint5_4Output, E>
 
-export type Endpoint5_5Input = { readonly sessionID: Session.ID; readonly messageID?: SessionMessage.ID | undefined }
+export type Endpoint5_5Input = { readonly sessionID: Session.ID; readonly boundary: Session.ForkRequestBoundary }
 export type Endpoint5_5Output = Session.Info
 export type SessionForkOperation<E = never> = (input: Endpoint5_5Input) => Effect.Effect<Endpoint5_5Output, E>
 
@@ -342,8 +343,10 @@ export type Endpoint5_26Output =
           readonly data: {
             readonly sessionID: Session.ID
             readonly parentID: Session.ID
-            readonly parentSeq: number
+            readonly boundary: Session.ForkBoundary
-            readonly from?: SessionMessage.ID | undefined
+            readonly instructions?:
+              | { readonly [x: string & Brand.Brand<"Instruction.Key">]: string & Brand.Brand<"Instruction.Hash"> }
+              | undefined
           }
         }
       | {

packages/client/src/effect/generated/client.ts

@@ -299,7 +299,13 @@ const Endpoint5_0 = (raw: RawClient["server.session"]) => (input?: Endpoint5_0In
 const Endpoint5_1 = (raw: RawClient["server.session"]) => (input?: Endpoint5_1Input) =>
   preserveEffect<Endpoint5_1Output>()(
     raw["session.create"]({
-      payload: { id: input?.["id"], agent: input?.["agent"], model: input?.["model"], location: input?.["location"] },
+      payload: {
+        id: input?.["id"],
+        title: input?.["title"],
+        agent: input?.["agent"],
+        model: input?.["model"],
+        location: input?.["location"],
+      },
     }).pipe(
       Effect.mapError(mapClientError),
       Effect.map((value) => value.data),
@@ -329,7 +335,7 @@ const Endpoint5_4 = (raw: RawClient["server.session"]) => (input: Endpoint5_4Inp
 
 const Endpoint5_5 = (raw: RawClient["server.session"]) => (input: Endpoint5_5Input) =>
   preserveEffect<Endpoint5_5Output>()(
-    raw["session.fork"]({ params: { sessionID: input["sessionID"] }, payload: { messageID: input["messageID"] } }).pipe(
+    raw["session.fork"]({ params: { sessionID: input["sessionID"] }, payload: { boundary: input["boundary"] } }).pipe(
       Effect.mapError(mapClientError),
       Effect.map((value) => value.data),
     ),

packages/client/src/promise/generated/client.ts

@@ -462,6 +462,7 @@ export function make(options: ClientOptions) {
             path: `/api/session`,
             body: {
               id: input?.["id"],
+              title: input?.["title"],
               agent: input?.["agent"],
               model: input?.["model"],
               location: input?.["location"],
@@ -510,7 +511,7 @@ export function make(options: ClientOptions) {
           {
             method: "POST",
             path: `/api/session/${encodeURIComponent(input.sessionID)}/fork`,
-            body: { messageID: input["messageID"] },
+            body: { boundary: input["boundary"] },
             successStatus: 200,
             declaredStatuses: [404, 400, 401],
             empty: false,

packages/client/src/promise/generated/types.ts

@@ -14,6 +14,8 @@ export type PermissionEffect = "allow" | "deny" | "ask"
 
 export type PluginInfo = { id: string }
 
+export type SessionForkBoundary = { type: "before"; messageID: string } | { type: "through"; messageID: string }
+
 export type MoneyUSD = number
 
 export type TokenUsageInfo = {
@@ -43,13 +45,7 @@ export type PromptMention = { start: number; end: number; text: string }
 
 export type SessionPendingSyntheticData = { text: string; description?: string; metadata?: { [x: string]: JsonValue } }
 
-export type SessionPendingCompaction = {
+export type SessionPendingCompaction = { id: string; sessionID: string; timeCreated: number; type: "compaction" }
-  admittedSeq: number
-  id: string
-  sessionID: string
-  timeCreated: number
-  type: "compaction"
-}
 
 export type SessionMessageAgentSelected = {
   id: string
@@ -283,7 +279,7 @@ export type ProjectCommands = { start?: string }
 
 export type ProjectTime = { created: number; updated: number; initialized?: number }
 
-export type ProjectCurrent = { id: string; directory: string }
+export type ProjectCurrent = { id: string; directory: string; canonical: string }
 
 export type ProjectDirectory = { directory: string; strategy?: string }
 
@@ -628,7 +624,7 @@ export type SessionForked = {
   type: "session.forked"
   durable: { aggregateID: string; seq: number; version: 2 }
   location?: LocationRef
-  data: { sessionID: string; parentID: string; parentSeq: number; from?: string }
+  data: { sessionID: string; parentID: string; boundary: SessionForkBoundary; instructions?: { [x: string]: string } }
 }
 
 export type SessionInputPromoted = {
@@ -1210,7 +1206,6 @@ export type PromptFileAttachment = {
 export type PromptAgentAttachment = { name: string; mention?: PromptMention }
 
 export type SessionPendingSynthetic = {
-  admittedSeq: number
   id: string
   sessionID: string
   timeCreated: number
@@ -1435,7 +1430,7 @@ export type McpResourceCatalog = { resources: Array<McpResource>; templates: Arr
 
 export type Project = {
   id: string
-  worktree: string
+  canonical: string
   vcs?: ProjectVcs
   name?: string
   icon?: ProjectIcon
@@ -1755,14 +1750,14 @@ export type PermissionRuleset = Array<PermissionRule>
 export type SessionInfo = {
   id: string
   parentID?: string
-  fork?: { sessionID: string; messageID?: string }
+  fork?: { sessionID: string; boundary: SessionForkBoundary }
   projectID: string
   agent?: string
   model?: ModelRef
   cost: MoneyUSD
   tokens: TokenUsageInfo
   time: { created: number; updated: number; archived?: number }
-  title: string
+  title?: string
   location: LocationRef
   subpath?: string
   revert?: SessionRevert
@@ -1966,7 +1961,6 @@ export type AgentInfo = {
 export type SessionsResponse = { data: Array<SessionInfo>; cursor: { previous?: string | null; next?: string | null } }
 
 export type SessionPendingUser = {
-  admittedSeq: number
   id: string
   sessionID: string
   timeCreated: number
@@ -2012,7 +2006,7 @@ export type SessionV1Info = {
   cost?: number
   tokens?: { input: number; output: number; reasoning: number; cache: { read: number; write: number } }
   share?: { url: string }
-  title: string
+  title?: string
   agent?: string
   model?: { id: string; providerID: string; variant?: string }
   version: string
@@ -2521,7 +2515,11 @@ export type LocationGetInput = {
   }["location"]
 }
 
-export type LocationGetOutput = { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+export type LocationGetOutput = {
+  directory: string
+  workspaceID?: string
+  project: { id: string; directory: string; canonical: string }
+}
 
 export type AgentListInput = {
   readonly location?: {
@@ -2530,7 +2528,7 @@ export type AgentListInput = {
 }
 
 export type AgentListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<AgentInfo>
 }
 
@@ -2542,7 +2540,7 @@ export type AgentGetInput = {
 }
 
 export type AgentGetOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: AgentInfo
 }
 
@@ -2553,7 +2551,7 @@ export type PluginListInput = {
 }
 
 export type PluginListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<PluginInfo>
 }
 
@@ -2664,24 +2662,35 @@ export type SessionListOutput = SessionsResponse
 export type SessionCreateInput = {
   readonly id?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
   }["id"]
+  readonly title?: {
+    readonly id?: string | null
+    readonly title?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
+    readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
+  }["title"]
   readonly agent?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
   }["agent"]
   readonly model?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
   }["model"]
   readonly location?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
@@ -2702,7 +2711,9 @@ export type SessionRemoveOutput = void
 
 export type SessionForkInput = {
   readonly sessionID: { readonly sessionID: string }["sessionID"]
-  readonly messageID?: { readonly messageID?: string | undefined }["messageID"]
+  readonly boundary: {
+    readonly boundary: { readonly type: "before"; readonly messageID: string } | { readonly type: "through" }
+  }["boundary"]
 }
 
 export type SessionForkOutput = { data: SessionInfo }["data"]
@@ -3235,7 +3246,7 @@ export type ModelListInput = {
 }
 
 export type ModelListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<ModelInfo>
 }
 
@@ -3246,7 +3257,7 @@ export type ModelDefaultInput = {
 }
 
 export type ModelDefaultOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: ModelInfo | null
 }
 
@@ -3273,7 +3284,7 @@ export type ProviderListInput = {
 }
 
 export type ProviderListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<ProviderInfo>
 }
 
@@ -3285,7 +3296,7 @@ export type ProviderGetInput = {
 }
 
 export type ProviderGetOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: ProviderInfo
 }
 
@@ -3296,7 +3307,7 @@ export type IntegrationListInput = {
 }
 
 export type IntegrationListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<IntegrationInfo>
 }
 
@@ -3308,7 +3319,7 @@ export type IntegrationGetInput = {
 }
 
 export type IntegrationGetOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: IntegrationInfo | null
 }
 
@@ -3355,7 +3366,7 @@ export type IntegrationOauthConnectInput = {
 }
 
 export type IntegrationOauthConnectOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: {
     attemptID: string
     url: string
@@ -3374,7 +3385,7 @@ export type IntegrationOauthStatusInput = {
 }
 
 export type IntegrationOauthStatusOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: IntegrationAttemptStatus
 }
 
@@ -3409,7 +3420,7 @@ export type IntegrationCommandConnectInput = {
 }
 
 export type IntegrationCommandConnectOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: IntegrationCommandAttempt
 }
 
@@ -3422,7 +3433,7 @@ export type IntegrationCommandStatusInput = {
 }
 
 export type IntegrationCommandStatusOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: IntegrationCommandAttemptStatus
 }
 
@@ -3443,7 +3454,7 @@ export type McpListInput = {
 }
 
 export type McpListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<McpServer>
 }
 
@@ -3532,7 +3543,7 @@ export type McpResourceCatalogInput = {
 }
 
 export type McpResourceCatalogOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: McpResourceCatalog
 }
 
@@ -3581,7 +3592,7 @@ export type FormRequestListInput = {
 }
 
 export type FormRequestListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<FormInfo>
 }
 
@@ -4437,7 +4448,7 @@ export type PermissionRequestListInput = {
 }
 
 export type PermissionRequestListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<PermissionRequest>
 }
 
@@ -4559,7 +4570,7 @@ export type FileListInput = {
 }
 
 export type FileListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<FileSystemEntry>
 }
 
@@ -4591,7 +4602,7 @@ export type FileFindInput = {
 }
 
 export type FileFindOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<FileSystemEntry>
 }
 
@@ -4602,7 +4613,7 @@ export type CommandListInput = {
 }
 
 export type CommandListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<CommandInfo>
 }
 
@@ -4613,7 +4624,7 @@ export type SkillListInput = {
 }
 
 export type SkillListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<SkillInfo>
 }
 
@@ -4626,7 +4637,7 @@ export type PtyListInput = {
 }
 
 export type PtyListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<Pty>
 }
 
@@ -4672,7 +4683,7 @@ export type PtyCreateInput = {
 }
 
 export type PtyCreateOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Pty
 }
 
@@ -4684,7 +4695,7 @@ export type PtyGetInput = {
 }
 
 export type PtyGetOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Pty
 }
 
@@ -4701,7 +4712,7 @@ export type PtyUpdateInput = {
 }
 
 export type PtyUpdateOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Pty
 }
 
@@ -4721,7 +4732,7 @@ export type ShellListInput = {
 }
 
 export type ShellListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<ShellInfo1>
 }
 
@@ -4756,7 +4767,7 @@ export type ShellCreateInput = {
 }
 
 export type ShellCreateOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: ShellInfo1
 }
 
@@ -4768,7 +4779,7 @@ export type ShellGetInput = {
 }
 
 export type ShellGetOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: ShellInfo1
 }
 
@@ -4781,7 +4792,7 @@ export type ShellTimeoutInput = {
 }
 
 export type ShellTimeoutOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: ShellInfo1
 }
 
@@ -4805,7 +4816,7 @@ export type ShellOutputInput = {
 }
 
 export type ShellOutputOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: { output: string; cursor: number; size: number; truncated: boolean }
 }
 
@@ -4825,7 +4836,7 @@ export type QuestionRequestListInput = {
 }
 
 export type QuestionRequestListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<QuestionRequest>
 }
 
@@ -4855,7 +4866,7 @@ export type ReferenceListInput = {
 }
 
 export type ReferenceListOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<ReferenceInfo>
 }
 
@@ -4898,7 +4909,7 @@ export type VcsStatusInput = {
 }
 
 export type VcsStatusOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<VcsFileStatus>
 }
 
@@ -4921,7 +4932,7 @@ export type VcsDiffInput = {
 }
 
 export type VcsDiffOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<FileDiffInfo>
 }
 
@@ -4942,7 +4953,7 @@ export type WebsearchProvidersInput = {
 }
 
 export type WebsearchProvidersOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: Array<WebSearchProvider>
 }
 
@@ -4955,6 +4966,6 @@ export type WebsearchQueryInput = {
 }
 
 export type WebsearchQueryOutput = {
-  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
   data: { providerID: string; results: Array<WebSearchResult> }
 }

packages/client/test/effect.test.ts

@@ -268,7 +268,6 @@ const session = {
 
 const admission = {
   data: {
-    admittedSeq: 0,
     id: "msg_test",
     sessionID: "ses_test",
     type: "user",
@@ -281,7 +280,6 @@ const admission = {
 const compactionAdmission = {
   data: {
     type: "compaction",
-    admittedSeq: 1,
     id: "msg_compaction",
     sessionID: "ses_test",
     timeCreated: 1_717_171_717_000,

packages/client/test/promise.test.ts

@@ -304,7 +304,6 @@ test("session.pending.list uses the public HTTP contract", async () => {
   const requests: Array<{ method: string; url: string }> = []
   const pending = [
     {
-      admittedSeq: 3,
       id: "msg_pending",
       sessionID: "ses_test",
       timeCreated: 1_717_171_717_000,
@@ -547,7 +546,6 @@ const session = {
 
 const admission = {
   data: {
-    admittedSeq: 0,
     id: "msg_test",
     sessionID: "ses_test",
     type: "user",
@@ -559,7 +557,6 @@ const admission = {
 
 const syntheticAdmission = {
   data: {
-    admittedSeq: 1,
     id: "msg_synthetic",
     sessionID: "ses_test",
     type: "synthetic",
@@ -572,7 +569,6 @@ const syntheticAdmission = {
 const compactionAdmission = {
   data: {
     type: "compaction",
-    admittedSeq: 1,
     id: "msg_compaction",
     sessionID: "ses_test",
     timeCreated: 1_717_171_717_000,

packages/core/package.json

@@ -41,6 +41,11 @@
       "node": "./src/image/photon-wasm.node.ts",
       "default": "./src/image/photon-wasm.bun.ts"
     },
+    "#shell-parser-wasm": {
+      "bun": "./src/shell/parser-wasm.bun.ts",
+      "node": "./src/shell/parser-wasm.node.ts",
+      "default": "./src/shell/parser-wasm.bun.ts"
+    },
     "#process-lock-ffi": {
       "bun": "./src/util/process-lock-ffi.bun.ts",
       "node": "./src/util/process-lock-ffi.node.ts",
@@ -119,7 +124,10 @@
     "jsonc-parser": "3.3.1",
     "semver": "^7.6.3",
     "turndown": "7.2.0",
+    "tree-sitter-bash": "0.25.0",
+    "tree-sitter-powershell": "0.25.10",
     "venice-ai-sdk-provider": "2.1.1",
+    "web-tree-sitter": "0.25.10",
     "which": "6.0.1",
     "zod": "catalog:"
   },