feat(core): route subagent models by role

.changeset/websocket-request-hooks.md

@@ -1,6 +0,0 @@
----
-"@opencode-ai/plugin": patch
-"@opencode-ai/core": patch
----
-
-Add transport-neutral Session model request hooks and provider-scoped hook registration so eligible OpenAI Responses requests can prefer WebSocket without bypassing HTTP-only middleware.

.github/actions/setup-bun/action.yml

@@ -1,10 +1,6 @@
 name: "Setup Bun"
 description: "Setup Bun with caching and install dependencies"
 inputs:
-  bun-version:
-    description: "Bun version to install instead of the root packageManager version"
-    required: false
-    default: ""
   install-flags:
     description: "Additional flags to pass to 'bun install'"
     required: false
@@ -24,22 +20,19 @@ runs:
       shell: bash
       run: |
         if [ "$RUNNER_ARCH" = "X64" ]; then
-          V="${{ inputs.bun-version }}"
-          if [ -z "$V" ]; then V=$(node -p "require('./package.json').packageManager.split('@')[1]"); fi
-          TAG=$([ "$V" = "canary" ] && echo "canary" || echo "bun-v${V}")
+          V=$(node -p "require('./package.json').packageManager.split('@')[1]")
           case "$RUNNER_OS" in
             macOS)   OS=darwin ;;
             Linux)   OS=linux ;;
             Windows) OS=windows ;;
           esac
-          echo "url=https://github.com/oven-sh/bun/releases/download/${TAG}/bun-${OS}-x64-baseline.zip" >> "$GITHUB_OUTPUT"
+          echo "url=https://github.com/oven-sh/bun/releases/download/bun-v${V}/bun-${OS}-x64-baseline.zip" >> "$GITHUB_OUTPUT"
         fi
 
     - name: Setup Bun
       uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
       with:
-        bun-version: ${{ !steps.bun-url.outputs.url && inputs.bun-version || '' }}
-        bun-version-file: ${{ !steps.bun-url.outputs.url && !inputs.bun-version && 'package.json' || '' }}
+        bun-version-file: ${{ !steps.bun-url.outputs.url && 'package.json' || '' }}
         bun-download-url: ${{ steps.bun-url.outputs.url }}
 
     - name: Get cache directory

.github/workflows/beta.yml

@@ -0,0 +1,37 @@
+name: beta
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 * * * *"
+
+jobs:
+  sync:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: ./.github/actions/setup-bun
+
+      - name: Setup Git Committer
+        id: setup-git-committer
+        uses: ./.github/actions/setup-git-committer
+        with:
+          opencode-app-id: ${{ vars.OPENCODE_APP_ID }}
+          opencode-app-secret: ${{ secrets.OPENCODE_APP_SECRET }}
+
+      - name: Install OpenCode
+        run: bun i -g opencode-ai
+
+      - name: Sync beta branch
+        env:
+          GH_TOKEN: ${{ steps.setup-git-committer.outputs.token }}
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        run: bun script/beta.ts

.github/workflows/generate.yml

@@ -0,0 +1,52 @@
+name: generate
+
+on:
+  push:
+    branches:
+      - dev
+      - v2
+
+jobs:
+  generate:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Setup Bun
+        uses: ./.github/actions/setup-bun
+
+      - name: Setup git committer
+        id: committer
+        uses: ./.github/actions/setup-git-committer
+        with:
+          opencode-app-id: ${{ vars.OPENCODE_APP_ID }}
+          opencode-app-secret: ${{ secrets.OPENCODE_APP_SECRET }}
+
+      - name: Generate
+        run: ./script/generate.ts
+
+      - name: Commit and push
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "No changes to commit"
+            exit 0
+          fi
+          git add -A
+          git commit -m "chore: generate" --allow-empty
+          git push origin HEAD:${{ github.ref_name }} --no-verify
+          # if ! git push origin HEAD:${{ github.event.pull_request.head.ref || github.ref_name }} --no-verify; then
+          #   echo ""
+          #   echo "============================================"
+          #   echo "Failed to push generated code."
+          #   echo "Please run locally and push:"
+          #   echo ""
+          #   echo "  ./script/generate.ts"
+          #   echo "  git add -A && git commit -m \"chore: generate\" && git push"
+          #   echo ""
+          #   echo "============================================"
+          #   exit 1
+          # fi

.github/workflows/nix-hashes.yml

@@ -6,7 +6,7 @@ permissions:
 on:
   workflow_dispatch:
   push:
-    branches: [dev, beta, v2]
+    branches: [dev, beta]
     paths:
       - "bun.lock"
       - "package.json"

.github/workflows/publish.yml

@@ -7,7 +7,6 @@ on:
       - ci
       - dev
       - beta
-      - v2
       - fix/npm-native-binary-install
       - snapshot-*
   workflow_dispatch:
@@ -33,7 +32,7 @@ permissions:
   packages: write
 
 env:
-  OPENCODE_CHANNEL: ${{ (github.ref_name == 'v2' && 'dev') || '' }}
+  OPENCODE_CHANNEL: ${{ (github.ref_name == 'v2' && 'next') || '' }}
 
 jobs:
   version:
@@ -46,13 +45,6 @@ jobs:
 
       - uses: ./.github/actions/setup-bun
 
-      - name: Deploy update service
-        if: github.ref_name == 'v2' || github.ref_name == 'beta'
-        working-directory: packages/updates
-        run: bun run deploy
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-
       - name: Setup git committer
         id: committer
         uses: ./.github/actions/setup-git-committer
@@ -82,16 +74,13 @@ jobs:
   build-cli:
     needs: version
     runs-on: blacksmith-4vcpu-ubuntu-2404
-    timeout-minutes: 30
-    if: github.repository == 'anomalyco/opencode'
+    if: github.repository == 'anomalyco/opencode' && github.ref_name != 'beta'
     steps:
       - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
         with:
           fetch-tags: true
 
       - uses: ./.github/actions/setup-bun
-        with:
-          bun-version: canary # Bun 1.4 until its stable release is published
 
       - name: Setup git committer
         id: committer
@@ -113,7 +102,6 @@ jobs:
         id: build
         run: ./packages/cli/script/build.ts ${{ (github.ref_name == 'beta' && '--sourcemaps') || '' }}
         env:
-          BUN_COMPILE_RELEASE: canary
           OPENCODE_VERSION: ${{ needs.version.outputs.version }}
           OPENCODE_RELEASE: ${{ needs.version.outputs.release }}
           GH_REPO: ${{ needs.version.outputs.repo }}
@@ -197,7 +185,7 @@ jobs:
 
   build-node-cli:
     needs: version
-    if: github.repository == 'anomalyco/opencode' && false # Temporarily disabled
+    if: github.repository == 'anomalyco/opencode' && github.ref_name != 'beta'
     strategy:
       fail-fast: false
       matrix:
@@ -347,7 +335,6 @@ jobs:
   build-electron:
     needs:
       - version
-      - sign-cli-macos
     if: github.repository == 'anomalyco/opencode' && github.ref_name != 'v2'
     continue-on-error: false
     env:
@@ -386,12 +373,6 @@ jobs:
     steps:
       - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
 
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        if: github.ref_name == 'beta'
-        with:
-          name: opencode-preview-cli
-          path: packages/cli/dist
-
       - uses: apple-actions/import-codesign-certs@8f3fb608891dd2244cdab3d69cd68c0d37a7fe93 # v2.0.0
         if: runner.os == 'macOS'
         with:
@@ -450,7 +431,6 @@ jobs:
           OPENCODE_VERSION: ${{ needs.version.outputs.version }}
           OPENCODE_CHANNEL: ${{ (github.ref_name == 'beta' && 'beta') || 'prod' }}
           OPENCODE_CLI_TARGET: ${{ matrix.settings.target }}
-          OPENCODE_CLI_DIST: ${{ (github.ref_name == 'beta' && format('{0}/packages/cli/dist', github.workspace)) || '' }}
 
       - name: Build
         run: bun run build
@@ -467,7 +447,6 @@ jobs:
           VITE_SENTRY_ENVIRONMENT: ${{ (github.ref_name == 'beta' && 'beta') || 'production' }}
           VITE_SENTRY_RELEASE: desktop@${{ needs.version.outputs.version }}
           OPENCODE_CLI_TARGET: ${{ matrix.settings.target }}
-          OPENCODE_CLI_DIST: ${{ github.workspace }}/packages/cli/dist
 
       - name: Package
         if: needs.version.outputs.release
@@ -590,12 +569,13 @@ jobs:
           path: packages/opencode/dist
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        if: github.ref_name != 'beta'
         with:
           name: opencode-preview-cli
           path: packages/cli/dist
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        if: needs.build-node-cli.result == 'success'
+        if: github.ref_name != 'beta'
         with:
           pattern: opencode-node-cli-*
           path: packages/cli/dist/node

.github/workflows/test.yml

@@ -80,8 +80,6 @@ jobs:
         if: always()
         timeout-minutes: 10
         working-directory: packages/cli
-        env:
-          NODE_OPTIONS: ${{ runner.os == 'Windows' && '--max-old-space-size=4096' || '' }}
         run: |
           bun run script/build.ts --single --skip-install
           bun run script/service-smoke.ts
@@ -96,8 +94,6 @@ jobs:
         if: always()
         timeout-minutes: 15
         working-directory: packages/cli
-        env:
-          NODE_OPTIONS: ${{ runner.os == 'Windows' && '--max-old-space-size=4096' || '' }}
         run: |
           bun run script/build-node.ts --single --skip-install --outdir=dist/node
           bun run script/service-smoke.ts --node

.opencode/skills/opencode-dev/SKILL.md

@@ -1,231 +0,0 @@
----
-name: opencode-dev
-description: Use when interactively running, debugging, or verifying opencode's own V2 CLI/TUI or server during development in this repo — starting the dev TUI, driving it with termctrl, comparing V2 against the legacy TUI, hitting the V2 server/API directly, reading log files, or attaching Bun's inspector.
----
-
-# Debugging opencode itself
-
-Workflow for interactively exercising the V2 CLI/TUI and server while developing in this repo. All commands below run from `packages/cli` unless noted otherwise.
-
-## Server/client model
-
-opencode V2 is a client/server system, not a single monolithic process:
-
-- **Server process** runs the Effect HTTP API (`packages/server`) and owns all domain state: sessions, database, plugins, permissions, Location services. It's started by the `serve` command (`packages/cli/src/commands/handlers/serve.ts`).
-- **TUI process** is a separate process that runs no application logic itself — it's an HTTP/SSE client of the server via the generated SDK (`createOpencodeClient` / `sdk.client.v2`).
-- **Discovery**: CLI processes find the shared server through a JSON registration file at `~/.local/state/opencode/service.json` (or `service-local.json` for the local/dev channel) containing `{id, version, url, pid}`. A separate password file under `~/.config/opencode/service.json` provides HTTP Basic auth. Before reusing a registration, the client calls `GET /health` to confirm the server is alive, authenticated, and version-compatible.
-- **Sharing**: because of this registration/health-check dance, many concurrent `opencode`/TUI invocations converge on one shared background daemon rather than each spawning their own. If no compatible healthy daemon is found, a new one is spawned detached (`serve --service`) and registers itself.
-- **`bun dev service start|status|stop|restart`** manages this shared background daemon's lifecycle directly — useful when you need to force a fresh server, confirm one is running, or kill a stuck one.
-- **Standalone mode** (`--standalone`) opts a single invocation out of the shared daemon: it spawns a private one-off `serve --stdio --port 0` child tied to that invocation's lifetime, with its own random password. Use this to isolate a debugging session from your other running opencode sessions.
-- Every log line is tagged `role=server` or `role=cli` and a per-process `run=<id>`, so you can distinguish server-side and client-side activity in one shared log file (see "Logs" below) even when both roles are interleaved from concurrent processes.
-
-## Starting the dev TUI
-
-- This package is the V2 CLI adapter. Run its `dev` script when testing the TUI; do not use the repository-root `bun dev`, which launches the legacy `packages/opencode` CLI.
-- Run commands from `packages/cli`. Use `bun dev` for most debugging so the TUI starts with a private V2 server.
-
-## Interactive debugging with termctrl
-
-- Use `termctrl` for interactive checks instead of starting the TUI as a blocking foreground process. It provides a real PTY, handles OpenTUI's host handshake, and can save reviewable screenshots.
-- Use a dedicated session name and do not reuse or kill an unrelated session.
-
-```bash
-termctrl start opencode-v2-dev --host opentui --cols 112 --rows 34 -- bun dev
-termctrl wait opencode-v2-dev "Ask anything" --timeout 20000
-termctrl show opencode-v2-dev
-```
-
-- Wait for visible text before interacting instead of relying on fixed sleeps. Use the text expected from the screen under test, such as `Ask anything` or `Connect a provider`.
-- Drive the running TUI with `termctrl send`. Prefix typed input with `text:` and send control keys separately so the interaction matches real terminal input.
-
-```bash
-termctrl send opencode-v2-dev 'text:example prompt' enter
-termctrl send opencode-v2-dev ctrl-c
-```
-
-- Use `termctrl show` after each meaningful interaction and inspect the full visible screen for rendering errors, stale state, error toasts, and unexpected exits.
-- Save PNG evidence for every user-visible bug and fix. Do not save text captures; inspect the rendered PNG. Write temporary captures outside the repository unless the artifact is intended to be committed.
-
-```bash
-termctrl save opencode-v2-dev --format png --out /tmp/opencode/v2-tui.png
-```
-
-- For resize-sensitive changes, resize the viewport, wait for the expected content, and capture the screen again:
-
-```bash
-termctrl resize opencode-v2-dev --cols 100 --rows 30
-termctrl show opencode-v2-dev
-```
-
-- Source changes may require restarting the process. Use `termctrl restart opencode-v2-dev` rather than assuming the running TUI reloaded the change.
-- To exercise background-service behavior, use `bun dev service start`, `bun dev service status`, and `bun dev service stop`.
-- Always clean up the Terminal Control session when the check is complete:
-
-```bash
-termctrl stop opencode-v2-dev
-```
-
-## Comparing V2 against the legacy TUI
-
-Run both versions in separate Terminal Control sessions and save PNG-only captures at equivalent states:
-
-```bash
-# From packages/cli: local V2 TUI
-termctrl start opencode-v2-dev --host opentui --cols 112 --rows 34 -- bun dev
-
-# Released legacy TUI behavior reference
-termctrl start opencode-legacy --host opentui --cols 112 --rows 34 -- bunx opencode-ai@latest
-
-termctrl save opencode-v2-dev --format png --out /tmp/opencode/v2.png
-termctrl save opencode-legacy --format png --out /tmp/opencode/legacy.png
-```
-
-- Use the same viewport and send equivalent inputs to both sessions before comparing screenshots. The released CLI is a behavioral reference, not a source of V2 API design; keep the local implementation on V2 endpoints.
-- Stop both sessions after comparison: `termctrl stop opencode-v2-dev` and `termctrl stop opencode-legacy`.
-
-## Server/API debugging
-
-- Use `bun dev api --help` from `packages/cli` to inspect the API debugging command. It sends one request to the V2 server using the same daemon discovery/auth path as the CLI.
-- Use `bun dev api` to introspect the server-side data backing the TUI. This is useful when debugging UI bugs: compare what the screen renders with the raw session, message, event, agent, or health data returned by the API to determine whether the bug is in the server state, the client data layer, or the TUI rendering.
-- `bun dev api` accepts either an OpenAPI operation ID or a raw HTTP method plus path:
-
-```bash
-bun dev api get /health
-bun dev api get /openapi.json
-bun dev api <operationId> --param key=value
-```
-
-- Pass JSON request bodies with `--data`/`-d`; the command sets `content-type: application/json` automatically unless you provide a header. Add extra headers with `--header`/`-H name:value`.
-- If no compatible background server is registered, `bun dev api` starts one through the daemon service. Use `bun dev service status`, `bun dev service restart`, and `bun dev service stop` when you need explicit lifecycle control.
-- Prefer raw method/path calls for quick server debugging and operation IDs when exercising documented OpenAPI routes with path or query parameters.
-
-## Auditing installed `opencode2` sessions
-
-Installed next-channel sessions normally use `~/.local/share/opencode/opencode-next.db` and `~/.local/share/opencode/log/opencode.log`; `OPENCODE_DB` can override the database. Before calling `opencode2 api`, inspect `~/.local/state/opencode/service.json` because the command may start a daemon when none is healthy.
-
-For a supplied `ses_...` ID, compare three sources:
-
-- `opencode2 api get /api/session/active` and the Session/message endpoints for live server state.
-- The database's ordered `event` rows for durable history.
-- `packages/tui/src/context/data.tsx` and the relevant route for client projection and rendering.
-
-Locate an uncertain database without modifying it:
-
-```bash
-SESSION=ses_...
-for db in ~/.local/share/opencode/*.db; do
-  sqlite3 "file:$db?mode=ro" "select 1 from session where id='$SESSION' limit 1" 2>/dev/null | grep -q 1 && printf '%s\n' "$db"
-done
-```
-
-## Logs
-
-- Log files live under `~/.local/share/opencode/log/`. In a local/dev checkout the active file is `opencode-local.log`; `opencode.log` is used for non-local (released) channel installs. Both are append-only, shared across every CLI and server process on the machine.
-- Each line is structured `key=value` text: `timestamp`, `level`, `run=<id>` (per-process run ID), `message`, and a `role=cli` or `role=server` tag. Use `run=` to isolate one process's activity and `role=` to separate client-side from server-side log lines, since a shared daemon interleaves many processes' output in one file.
-- Tail the live file while reproducing an issue instead of guessing from stale output:
-
-```bash
-tail -f ~/.local/share/opencode/log/opencode-local.log
-```
-
-- Filter to one run or role when the file is noisy:
-
-```bash
-grep 'run=8fc3b1d5' ~/.local/share/opencode/log/opencode-local.log
-grep 'role=server' ~/.local/share/opencode/log/opencode-local.log
-```
-
-- `OPENCODE_LOG_LEVEL` controls verbosity (default `INFO`); set it before starting `bun dev` or `serve` to get `DEBUG` output for a specific repro.
-- `OPENCODE_PRINT_LOGS=1` additionally tees log output to stderr of the process that emitted it, which is useful when a process fails before you'd think to check the shared log file.
-- `termctrl logs <session>` surfaces stdout/stderr for a Terminal Control session specifically (e.g. inspector output or startup failures before the TUI renderer starts) — use the log file above for anything emitted by a separate server/daemon process instead.
-
-## Heap snapshots
-
-The CLI installs a `SIGUSR1` listener on non-Windows processes in `packages/cli/src/heap.ts`. Use it to capture the installed `opencode2` server without restarting it or attaching an inspector.
-
-1. Find the processes and inspect their roles and memory:
-
-```bash
-pgrep -a -f 'opencode2\.exe|opencode2'
-ps -o pid,ppid,rss,vsz,lstart,etime,cmd -p <pid>,<pid>
-```
-
-2. Signal the process whose heap needs investigation. For shared-service memory, target the `opencode2.exe serve --service` child, not the short wrapper/TUI process:
-
-```bash
-kill -USR1 <server-pid>
-```
-
-3. Wait for `heap snapshot written` in the channel's log before opening the file. Snapshots are written to the same log directory as `heap-<pid>-<timestamp>.heapsnapshot`; writing a large heap can take several seconds and the file is incomplete until the completion message appears:
-
-```bash
-grep 'heap snapshot' ~/.local/share/opencode/log/opencode.log | tail
-find ~/.local/share/opencode/log -maxdepth 1 -name 'heap-<server-pid>-*.heapsnapshot' -printf '%T@ %s %p\n' | sort -nr | head
-```
-
-Use `opencode-local.log` instead for a local/dev channel process. The log's `path=` field is authoritative.
-
-4. Analyze the snapshot with Chrome DevTools, a V8 heap snapshot parser, or a temporary tool installed outside the repository. Start with the largest retained objects, dominators, object counts grouped by constructor/name, and retainer paths back to GC roots. Relate suspicious names and paths back to the source tree rather than treating large shallow allocations as leaks.
-
-For command-line analysis, install tooling under `/tmp/opencode`, not in the repository. For example, MemLab can rank dominators and trace a reported heap object ID back to a GC root:
-
-```bash
-npm install --prefix /tmp/opencode/heap-analysis @memlab/cli
-/tmp/opencode/heap-analysis/node_modules/.bin/memlab analyze object-size --snapshot <snapshot>
-/tmp/opencode/heap-analysis/node_modules/.bin/memlab analyze shape --snapshot <snapshot>
-/tmp/opencode/heap-analysis/node_modules/.bin/memlab trace --snapshot <snapshot> --node-id=<id>
-```
-
-A single snapshot explains what retains memory at one point in time, but does not by itself prove a leak. For leak confirmation, capture a baseline, perform a controlled repeated workload, allow idle cleanup/GC when possible, capture another snapshot, and compare growth and retainer paths. Also compare snapshot heap size with process RSS: a large difference can indicate native allocations, database mappings, allocator fragmentation, or other memory outside the JavaScript heap.
-
-```bash
-cat /proc/<pid>/smaps_rollup
-pmap -x <pid> | sort -k3 -nr | head -25
-```
-
-Heap serialization itself can temporarily increase RSS and allocator high-water marks, so record `ps`/`smaps_rollup` both before and after capture. Large anonymous mappings with a comparatively small live heap require native-allocation or allocator investigation; they cannot be explained from JavaScript retainer paths alone.
-
-## CPU profiles
-
-The CLI installs a `SIGPROF` listener on non-Windows processes in `packages/cli/src/cpu-profile.ts`. One signal starts a ten-second CPU profile and stops it automatically; additional signals are ignored while a profile is active. There is no CPU profile CLI flag or environment variable.
-
-1. Get the PID from the health endpoint. For shared-service performance, target the server PID returned here rather than the short wrapper or TUI process:
-
-```bash
-opencode2 api get /api/health
-```
-
-Use `bun dev api get /api/health` instead when targeting the local/dev channel.
-
-2. Start the capture:
-
-```bash
-kill -PROF <server-pid>
-```
-
-3. Wait for `CPU profile written` in the channel's log before opening the file. Profiles are written to the same log directory as `cpu-<pid>-<timestamp>.cpuprofile`; the log's `path=` field is authoritative:
-
-```bash
-grep 'CPU profile' ~/.local/share/opencode/log/opencode.log | tail
-find ~/.local/share/opencode/log -maxdepth 1 -name 'cpu-<server-pid>-*.cpuprofile' -printf '%T@ %s %p\n' | sort -nr | head
-```
-
-Use `opencode-local.log` for a local/dev process. Load the completed `.cpuprofile` in Chrome DevTools or another V8 CPU profile viewer and inspect the hottest functions, call stacks, and self time during the controlled workload.
-
-## Debugger
-
-- To debug the V2 CLI or TUI with Bun's inspector, launch the CLI entrypoint through Terminal Control with an inspector URL, then attach a debugger to that URL:
-
-```bash
-termctrl start opencode-v2-debug --host opentui --cols 112 --rows 34 -- \
-  bun run --inspect=ws://localhost:6499/ src/index.ts
-```
-
-- Use `--inspect-wait` or `--inspect-brk` when execution must pause until a debugger attaches.
-- Use `termctrl logs opencode-v2-debug` for inspector output or startup failures emitted before the TUI renderer starts. Use `termctrl show` for the visible full-screen TUI.
-
-## Verification
-
-- Run `bun typecheck` from `packages/cli` after CLI adapter changes.
-- Run `bun typecheck` and `bun test` from `packages/tui` after shared TUI changes. Do not run tests from the repository root.
-- Treat automated checks and Terminal Control smoke tests as complementary. For user-visible changes, verify initial render, the changed interaction, Ctrl-C exit behavior, and save a screenshot of the corrected state.

AGENTS.md

@@ -9,7 +9,7 @@
 
 - Run `bun run dev:live` from a development worktree to test its TUI against the currently elected `opencode2` background server and live sessions.
 - Pass a directory after the script when needed, for example `bun run dev:live /path/to/project`.
-- The script discovers the server with `opencode2 service status`, injects its private local credential from `opencode2 service get password`, and uses the `dev` TUI storage channel so tabs and other client-local state match the installed client.
+- The script discovers the server with `opencode2 service status`, injects its private local credential from `opencode2 service get password`, and uses the `next` TUI storage channel so tabs and other client-local state match the installed client.
 - Prefer `dev:live` over plain `bun run dev` for this workflow. An implicit managed-service connection may replace the live server when the worktree client version differs; explicit `--server` warns and continues without replacing it.
 
 ## V2 TUI Stories

bunfig.toml

@@ -2,7 +2,7 @@
 exact = true
 # Only install newly resolved package versions published at least 3 days ago.
 minimumReleaseAge = 259200
-minimumReleaseAgeExcludes = ["@ai-sdk/amazon-bedrock", "@ai-sdk/anthropic", "@opencode-ai/sdk", "@opentui/core", "@opentui/core-darwin-arm64", "@opentui/core-darwin-x64", "@opentui/core-linux-arm64", "@opentui/core-linux-arm64-musl", "@opentui/core-linux-x64", "@opentui/core-linux-x64-musl", "@opentui/core-win32-arm64", "@opentui/core-win32-x64", "@opentui/keymap", "@opentui/solid", "opentui-spinner", "gitlab-ai-provider", "opencode-gitlab-auth", "@ff-labs/fff-node", "@ff-labs/fff-bun", "@ff-labs/fff-bin-darwin-arm64", "@ff-labs/fff-bin-darwin-x64", "@ff-labs/fff-bin-linux-arm64-gnu", "@ff-labs/fff-bin-linux-arm64-musl", "@ff-labs/fff-bin-linux-x64-gnu", "@ff-labs/fff-bin-linux-x64-musl", "@ff-labs/fff-bin-win32-arm64", "@ff-labs/fff-bin-win32-x64", "@pierre/diffs", "@pierre/theming", "app-builder-lib", "dmg-builder", "electron-builder", "electron-publish", "blume"]
+minimumReleaseAgeExcludes = ["@ai-sdk/amazon-bedrock", "@ai-sdk/anthropic", "@opencode-ai/sdk", "@opentui/core", "@opentui/core-darwin-arm64", "@opentui/core-darwin-x64", "@opentui/core-linux-arm64", "@opentui/core-linux-arm64-musl", "@opentui/core-linux-x64", "@opentui/core-linux-x64-musl", "@opentui/core-win32-arm64", "@opentui/core-win32-x64", "@opentui/keymap", "@opentui/solid", "opentui-spinner", "gitlab-ai-provider", "opencode-gitlab-auth", "@ff-labs/fff-node", "@ff-labs/fff-bun", "@ff-labs/fff-bin-darwin-arm64", "@ff-labs/fff-bin-darwin-x64", "@ff-labs/fff-bin-linux-arm64-gnu", "@ff-labs/fff-bin-linux-arm64-musl", "@ff-labs/fff-bin-linux-x64-gnu", "@ff-labs/fff-bin-linux-x64-musl", "@ff-labs/fff-bin-win32-arm64", "@ff-labs/fff-bin-win32-x64", "@pierre/diffs", "@pierre/theming", "app-builder-lib", "dmg-builder", "electron-builder", "electron-publish"]
 
 [test]
 root = "./do-not-run-tests-from-root"

install

@@ -15,13 +15,13 @@ Usage: install.sh [options]
 
 Options:
     -h, --help              Display this help message
-    -v, --version <version> Install a specific version (e.g., 0.0.0-beta-17236)
+    -v, --version <version> Install a specific version (e.g., 0.0.0-next-17236)
     -b, --binary <path>     Install from a local binary instead of downloading
         --no-modify-path    Don't modify shell config files (.zshrc, .bashrc, etc.)
 
 Examples:
-    curl -fsSL https://opencode.ai/v2/install | bash
-    curl -fsSL https://opencode.ai/v2/install | bash -s -- --version 0.0.0-beta-17236
+    curl -fsSL https://raw.githubusercontent.com/anomalyco/opencode/v2/install | bash
+    curl -fsSL https://raw.githubusercontent.com/anomalyco/opencode/v2/install | bash -s -- --version 0.0.0-next-17236
     ./install --binary /path/to/opencode2
 EOF
 }
@@ -166,7 +166,7 @@ else
     fi
 
     if [ -z "$requested_version" ]; then
-        metadata=$(curl -fsSL https://registry.npmjs.org/@opencode-ai%2fcli/beta || true)
+        metadata=$(curl -fsSL https://registry.npmjs.org/@opencode-ai%2fcli/next || true)
         specific_version=$(echo "$metadata" | sed -n 's/.*"version":"\([^"]*\)".*/\1/p')
 
         if [ -z "$specific_version" ]; then

nix/hashes.json

@@ -1,8 +1,8 @@
 {
   "nodeModules": {
-    "x86_64-linux": "sha256-IxkSw0gK/qkMHZGVHqjwgM9BKhzbQX6hyF9SWUNtpzg=",
-    "aarch64-linux": "sha256-YVjpbil0QswVwi6NtVYFq3xCqpsfveG1chlNVCVI0MU=",
-    "aarch64-darwin": "sha256-CdL2mI84pawH2H5i9qu8A6IWbkmKOYHlJS+DI/Mafdw=",
-    "x86_64-darwin": "sha256-NtswwfU5WYv99bEmI4XeLwjhBGcS9ZMYLRo4MQRNtLo="
+    "x86_64-linux": "sha256-uduwrM143NDSc+tXsi4lVVfoMll2a3BDHRUjuO7GB68=",
+    "aarch64-linux": "sha256-6DUda78XdXY6DP86lIUkweSjys3iG4Y4mo1PiaNuXbg=",
+    "aarch64-darwin": "sha256-AkJwfLULLZVwwz+XU1QcFUZoIS7oVPCn+n/MXEaxrqE=",
+    "x86_64-darwin": "sha256-hAxKGdiITTxQ2uujQt6prNjo3NxGAMMeo+9HlMWK6GU="
   }
 }

nix/node_modules.nix

@@ -10,7 +10,7 @@
     ]).nodeModules.${stdenvNoCC.hostPlatform.system},
 }:
 let
-  packageJson = lib.pipe ../packages/cli/package.json [
+  packageJson = lib.pipe ../packages/opencode/package.json [
     builtins.readFile
     builtins.fromJSON
   ];
@@ -52,7 +52,7 @@ stdenvNoCC.mkDerivation {
       --cpu="${bunCpu}" \
       --os="${bunOs}" \
       --filter '!./' \
-      --filter './packages/cli' \
+      --filter './packages/opencode' \
       --filter './packages/desktop' \
       --filter './packages/app' \
       --frozen-lockfile \

nix/opencode.nix

@@ -48,13 +48,13 @@ stdenvNoCC.mkDerivation (finalAttrs: {
   env.OPENCODE_DISABLE_MODELS_FETCH = true;
   env.OPENCODE_VERSION = finalAttrs.version;
   env.OPENCODE_CHANNEL = "prod";
-  env.NODE_OPTIONS = "--max-old-space-size=4096";
 
   buildPhase = ''
     runHook preBuild
 
-    cd ./packages/cli
+    cd ./packages/opencode
     bun --bun ./script/build.ts --single --skip-install
+    bun --bun ./script/schema.ts schema.json
 
     runHook postBuild
   '';
@@ -62,9 +62,10 @@ stdenvNoCC.mkDerivation (finalAttrs: {
   installPhase = ''
     runHook preInstall
 
-    install -Dm755 dist/cli-*/bin/opencode2 $out/bin/opencode2
+    install -Dm755 dist/opencode-*/bin/opencode $out/bin/opencode
+    install -Dm644 schema.json $out/share/opencode/schema.json
 
-    wrapProgram $out/bin/opencode2 \
+    wrapProgram $out/bin/opencode \
       --prefix PATH : ${
         lib.makeBinPath (
           [
@@ -80,9 +81,9 @@ stdenvNoCC.mkDerivation (finalAttrs: {
 
   postInstall = lib.optionalString (stdenvNoCC.buildPlatform.canExecute stdenvNoCC.hostPlatform) ''
     # trick yargs into also generating zsh completions
-    installShellCompletion --cmd opencode2 \
-      --bash <($out/bin/opencode2 completion) \
-      --zsh <(SHELL=/bin/zsh $out/bin/opencode2 completion)
+    installShellCompletion --cmd opencode \
+      --bash <($out/bin/opencode completion) \
+      --zsh <(SHELL=/bin/zsh $out/bin/opencode completion)
   '';
 
   nativeInstallCheckInputs = [
@@ -94,6 +95,7 @@ stdenvNoCC.mkDerivation (finalAttrs: {
   versionCheckProgramArg = "--version";
 
   passthru = {
+    jsonschema = "${placeholder "out"}/share/opencode/schema.json";
     env = finalAttrs.env;
   };
 
@@ -101,7 +103,7 @@ stdenvNoCC.mkDerivation (finalAttrs: {
     description = "The open source coding agent";
     homepage = "https://opencode.ai";
     license = lib.licenses.mit;
-    mainProgram = "opencode2";
+    mainProgram = "opencode";
     inherit (node_modules.meta) platforms;
   };
 })

package.json

@@ -8,7 +8,7 @@
   "packageManager": "bun@1.3.14",
   "scripts": {
     "dev": "bun run --cwd packages/cli --conditions=browser src/index.ts",
-    "dev:live": "OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode2 service get password)\" bun run dev --server \"$(opencode2 service status)\"",
+    "dev:live": "OPENCODE_TUI_CHANNEL=next OPENCODE_PASSWORD=\"$(opencode2 service get password)\" bun run dev --server \"$(opencode2 service status)\"",
     "dev:desktop": "bun --cwd packages/desktop dev",
     "dev:web": "bun --cwd packages/app dev",
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",
@@ -37,19 +37,18 @@
       "packages/slack"
     ],
     "catalog": {
-      "@effect/opentelemetry": "4.0.0-beta.107",
-      "@effect/platform-node": "4.0.0-beta.107",
-      "@effect/platform-node-shared": "4.0.0-beta.107",
-      "@effect/sql-sqlite-bun": "4.0.0-beta.107",
+      "@effect/opentelemetry": "4.0.0-beta.101",
+      "@effect/platform-node": "4.0.0-beta.101",
+      "@effect/sql-sqlite-bun": "4.0.0-beta.101",
       "@npmcli/arborist": "9.4.0",
       "@types/bun": "1.3.13",
       "@types/cross-spawn": "6.0.6",
       "@octokit/rest": "22.0.0",
       "@hono/standard-validator": "0.2.0",
       "@hono/zod-validator": "0.4.2",
-      "@opentui/core": "0.5.4",
-      "@opentui/keymap": "0.5.4",
-      "@opentui/solid": "0.5.4",
+      "@opentui/core": "0.5.3",
+      "@opentui/keymap": "0.5.3",
+      "@opentui/solid": "0.5.3",
       "@tanstack/solid-virtual": "3.13.32",
       "@shikijs/stream": "4.2.0",
       "@standard-schema/spec": "1.1.0",
@@ -71,7 +70,7 @@
       "dompurify": "3.3.1",
       "drizzle-kit": "1.0.0-rc.2",
       "drizzle-orm": "1.0.0-rc.2",
-      "effect": "4.0.0-beta.107",
+      "effect": "4.0.0-beta.101",
       "ai": "6.0.168",
       "cross-spawn": "7.0.6",
       "hono": "4.10.7",
@@ -121,7 +120,8 @@
     "prettier": "3.6.2",
     "semver": "^7.6.0",
     "sst": "catalog:",
-    "turbo": "2.10.2"
+    "turbo": "2.10.2",
+    "vitest": "4.1.10"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "3.933.0",
@@ -154,7 +154,6 @@
     "@opentui/core": "catalog:",
     "@opentui/keymap": "catalog:",
     "@opentui/solid": "catalog:",
-    "@effect/platform-node-shared": "catalog:",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
     "effect": "catalog:"
@@ -165,7 +164,6 @@
     "@npmcli/agent@4.0.2": "patches/@npmcli%2Fagent@4.0.2.patch",
     "@silvia-odwyer/photon-node@0.3.4": "patches/@silvia-odwyer%2Fphoton-node@0.3.4.patch",
     "@standard-community/standard-openapi@0.2.9": "patches/@standard-community%2Fstandard-openapi@0.2.9.patch",
-    "drizzle-orm@1.0.0-rc.2": "patches/drizzle-orm@1.0.0-rc.2.patch",
     "solid-js@1.9.10": "patches/solid-js@1.9.10.patch",
     "@ai-sdk/mistral@3.0.51": "patches/@ai-sdk%2Fmistral@3.0.51.patch",
     "gcp-metadata@8.1.2": "patches/gcp-metadata@8.1.2.patch",
@@ -173,6 +171,7 @@
     "@ai-sdk/google@3.0.73": "patches/@ai-sdk%2Fgoogle@3.0.73.patch",
     "@pierre/trees@1.0.0-beta.4": "patches/@pierre%2Ftrees@1.0.0-beta.4.patch",
     "@modelcontextprotocol/sdk@1.29.0": "patches/@modelcontextprotocol%2Fsdk@1.29.0.patch",
+    "effect@4.0.0-beta.101": "patches/effect@4.0.0-beta.101.patch",
     "@tanstack/virtual-core@3.17.3": "patches/@tanstack%2Fvirtual-core@3.17.3.patch",
     "@ff-labs/fff-bun@0.10.1": "patches/@ff-labs%2Ffff-bun@0.10.1.patch"
   }

packages/ai/AGENTS.md

@@ -49,7 +49,7 @@ Filter or narrow `LLMEvent` streams with `LLMEvent.is.*` (camelCase guards, e.g.
 
 ### Routes
 
-A route is the runnable composition of four orthogonal pieces:
+A route is the registered, runnable composition of four orthogonal pieces:
 
 - **`Protocol`** (`src/route/protocol.ts`) — semantic API contract. Owns request body construction (`body.from`), the body schema (`body.schema`), the streaming-event schema (`stream.event`), and the event-to-`LLMEvent` state machine (`stream.step`). `Route.make(...)` validates and JSON-encodes the body from `body.schema` and decodes frames with `stream.event`. Examples: `OpenAIChat.protocol`, `OpenResponses.protocol`, `OpenAIResponses.protocol`, `AnthropicMessages.protocol`, `Gemini.protocol`, `BedrockConverse.protocol`.
 - **`Endpoint`** (`src/route/endpoint.ts`) — URL construction. The host, path, and route query live on the endpoint. `Endpoint.path("/chat/completions", { baseURL })` is the common case; pass a function for paths that embed the model id or a body field (e.g. `Endpoint.path(({ body }) => `/model/${body.modelId}/converse-stream`)`).
@@ -66,7 +66,7 @@ export const route = Route.make({
   endpoint: Endpoint.path("/chat/completions", {
     baseURL: "https://api.openai.com/v1",
   }),
-  auth: Auth.bearer(Auth.config("OPENAI_API_KEY")),
+  auth: Auth.bearer(),
   framing: Framing.sse,
 })
 ```
@@ -79,7 +79,7 @@ When a provider supports multiple physical transports, selection remains executi
 
 ### URL Construction
 
-`Endpoint` owns `{ baseURL, path, query }`. Each protocol route includes a canonical endpoint when the provider has one (e.g. `https://api.openai.com/v1`); provider helpers override endpoint fields by configuring the route before selecting a model. Generic OpenAI-compatible routes have no canonical URL and require configuration before execution.
+`Endpoint` owns `{ baseURL, path, query }`. Each protocol route includes a canonical endpoint when the provider has one (e.g. `https://api.openai.com/v1`); provider helpers override endpoint fields by configuring the route before selecting a model. Routes that have no canonical URL (OpenAI-compatible Chat, GitHub Copilot) require configuration before execution.
 
 For providers where the URL is derived from typed inputs (Azure resource name, Bedrock region), the provider helper configures the route endpoint before calling `.model(...)`. Use `AtLeastOne<T>` from `route/auth-options.ts` for inputs that accept either of two derivation paths (Azure: `resourceName` or `baseURL`).
 
@@ -126,6 +126,54 @@ Keep semantic APIs as separate entrypoints, such as OpenAI `chat` and `responses
 
 Do not expose `Route` in provider package settings. Route composition stays an implementation detail behind `model(...)`.
 
+### Folder layout
+
+```
+packages/ai/src/
+  schema/                   canonical Schema model, split by concern
+    ids.ts                  branded IDs, literal types, ProviderMetadata
+    options.ts              Generation/Provider/Http options, Limits, LanguageModel, cache policy
+    messages.ts             content parts, Message, ToolDefinition, LLMRequest
+    events.ts               Usage, individual events, LLMEvent, LLMResponse
+    errors.ts               error reasons, AIError, ToolFailure
+    index.ts                barrel
+  llm.ts                    request constructors and convenience helpers
+  route/
+    index.ts                @opencode-ai/ai/route advanced barrel
+    client.ts               Route.make + LLMClient.stream/generate
+    executor.ts             RequestExecutor service + transport error mapping
+    protocol.ts             Protocol type + Protocol.make
+    endpoint.ts             Endpoint type + Endpoint.path
+    auth.ts                 Auth type + Auth.bearer / Auth.apiKeyHeader / Auth.passthrough
+    auth-options.ts         ProviderAuthOption shape, AuthOptions.bearer, AtLeastOne helper
+    framing.ts              Framing type + Framing.sse
+    transport/              transport implementations
+      index.ts              Transport execution types + HttpTransport / WebSocketTransport namespaces
+      websocket-channel.ts  generic sequential channel executor/driver contract
+      http.ts               HttpTransport.httpJson — POST + framing
+      websocket.ts          direct one-request channel executor + raw socket adapter
+  protocols/
+    shared.ts               ProviderShared toolkit used inside protocol impls
+    openai-chat.ts          protocol + route (compose OpenAIChat.protocol)
+    open-responses.ts         provider-neutral Responses protocol baseline
+    open-responses-channel.ts provider-neutral Responses WebSocket transport factory
+    openai-responses.ts       OpenAI tools/events and channel policy composed over OpenResponses
+    anthropic-messages.ts
+    gemini.ts
+    bedrock-converse.ts
+    bedrock-event-stream.ts framing for AWS event-stream binary frames
+    openai-compatible-chat.ts route that reuses OpenAIChat.protocol, no canonical URL
+    openai-compatible-responses.ts deployment adapter that reuses OpenResponses.protocol, no canonical URL
+    utils/                  per-protocol helpers (auth, cache, media, tool-stream, ...)
+  providers/
+    openai-compatible.ts    generic Chat helper + family model helpers
+    openai-compatible-responses.ts generic Responses helper
+    openai-compatible-profile.ts family defaults (deepseek, togetherai, ...)
+    azure.ts / amazon-bedrock.ts / cloudflare.ts / github-copilot.ts / google.ts / xai.ts / openai.ts / anthropic.ts / openrouter.ts
+  tool.ts                   typed tool() helper
+  tool-runtime.ts           narrow one-call typed tool dispatcher
+```
+
 The dependency arrow points down: `providers/*.ts` files import protocol routes and auth-option utilities; protocol modules import `endpoint`, `auth`, `framing`, and transport pieces. Protocols do not import provider facades. Lower-level modules know nothing about provider catalog metadata. `OpenAIResponses` composes the provider-neutral `OpenResponses` protocol; the baseline never imports the OpenAI extension.
 
 ### Shared protocol helpers
@@ -145,7 +193,7 @@ If you find yourself copying a 3-to-5-line snippet between two protocols, lift i
 
 `LLMRequest.system` is the initial privileged prompt that applies ahead of the conversation. `Message.system(...)` is a separate, provider-neutral chronological operator update inside `LLMRequest.messages`; it applies only from its position in history onward and accepts text content only.
 
-Native chronological system messages are route/model-specific. Open Responses lowers them to standard `developer` messages, while Anthropic Messages lowers them to native system messages for Claude Opus 4.8 (`claude-opus-4-8`). Other routes and models intentionally lower the update in place into ordinary user-compatible text using this stable escaped representation:
+Native chronological system messages are route/model-specific. Anthropic Messages lowers them natively for Claude Opus 4.8 (`claude-opus-4-8`). Other routes and models intentionally lower the update in place into ordinary user-compatible text using this stable escaped representation:
 
 ```text
 <system-update>
@@ -173,17 +221,19 @@ Routes lower these into provider-native assistant tool-call messages and tool-re
 
 ### Tool dispatch
 
-`LLM.stream(request)` and `LLM.generate(request)` each run exactly one model call. Add tool schemas to `request.tools` with `Tool.toDefinitions(tools)`. When a caller wants the package's typed one-call execution behavior, pass each canonical local `tool-call` event to `ToolRuntime.dispatch(tools, call)`.
+`LLM.stream(request)` and `LLM.generate(request)` each run exactly one provider turn. Add tool schemas to `request.tools` with `Tool.toDefinitions(tools)`. When a caller wants the package's typed one-call execution behavior, pass each canonical local `tool-call` event to `ToolRuntime.dispatch(tools, call)`.
 
 ```ts
-const get_weather = Tool.make({
+const get_weather = tool({
   description: "Get current weather for a city",
   parameters: Schema.Struct({ city: Schema.String }),
   success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
-  execute: (input) =>
+  execute: ({ city }) =>
     Effect.gen(function* () {
-      const data = yield* WeatherApi.fetch(input.city)
+      // city: string  — typed from parameters Schema
+      const data = yield* WeatherApi.fetch(city)
       return { temperature: data.temp, condition: data.cond }
+      // return type checked against success Schema
     }),
 })
 

packages/ai/README.md

@@ -237,11 +237,11 @@ Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "aut
 
 ### Auto placement
 
-`"auto"` places up to four breakpoints — the last tool definition, the first system part, the last system part when distinct, and the final message boundary. These expose successively larger reusable prefixes for tools, the base agent, project instructions, and the active conversation. The rolling final-message boundary advances on every request so recent conversation prefixes remain reusable during tool loops.
+`"auto"` places up to four breakpoints — the last tool definition, the first system part, the last system part when distinct, and the final message boundary. These expose successively larger reusable prefixes for tools, the base agent, project instructions, and the active conversation. The rolling final-message boundary is the load-bearing detail in tool loops: it advances on every request so the previous cache entry stays within Anthropic's 20-block lookback.
 
 Tools precede every system and conversation block in the provider prefix, so tool definitions must remain byte-stable and deterministically ordered for downstream breakpoints to remain reusable.
 
-Requests below a provider's minimum cacheable size simply do not produce a reusable cache entry.
+The math justifies the default: Anthropic's 5-minute cache write is 1.25× base, read is 0.1×, so a single reuse within 5 minutes already wins. One-shot completions below the per-model minimum-cacheable-token threshold silently no-op on the wire, so the worst case is harmless.
 
 ### Opting out
 
@@ -285,7 +285,6 @@ LLM.request({
 | ----------------------- | ------------------------------------------------------------------------- |
 | Anthropic Messages      | emits up to 4 `cache_control` markers (4-breakpoint cap enforced)         |
 | Bedrock Converse        | emits up to 4 `cachePoint` blocks (4-breakpoint cap enforced)             |
-| OpenRouter              | emits up to 4 `cache_control` markers                                     |
 | OpenAI Chat / Responses | no-op (implicit caching above 1024 tokens)                                |
 | Gemini                  | no-op (implicit caching on 2.5+; explicit `CachedContent` is out-of-band) |
 
@@ -372,23 +371,11 @@ Request options in order of stability:
 
 1. **`generation`** — portable knobs (`maxTokens`, `temperature`, `topP`, `topK`, penalties, seed, stop).
 2. **`promptCacheKey`** — stable cache affinity lowered by every protocol that supports it.
-3. **`providerOptions: { ... }`** — flat options inferred from the selected model (OpenAI `store`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
+3. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `store`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
 4. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.
 
 Route/provider defaults are overridden by request-level values for each axis.
 
-The selected model supplies the provider-specific option type, so per-request overrides stay flat while the canonical runtime request remains provider-neutral:
-
-```ts
-LLM.request({
-  model,
-  prompt,
-  providerOptions: {
-    reasoningEffort: "low",
-  },
-})
-```
-
 ## Routes
 
 Adding a new model or deployment is usually 5-15 lines using `Route.make({ protocol, endpoint, auth, framing, ... })`. The route owns endpoint/auth/framing and the protocol owns body construction plus stream parsing. Transports are reusable IO templates that receive route endpoint/auth at compile time. Capability/catalog metadata lives outside this low-level package; unsupported request shapes fail during protocol lowering. See `AGENTS.md` for the architectural detail.
@@ -400,5 +387,6 @@ This package is built on Effect. Public methods return `Effect` or `Stream`; pro
 ## See also
 
 - `AGENTS.md` — architecture, route construction, contributor guide
+- `STATUS.md` — native provider parity status and AI SDK migration gaps
 - `example/tutorial.ts` — runnable end-to-end walkthrough
 - `test/provider/*.test.ts` — fixture-first protocol tests; `*.recorded.test.ts` files cover live cassettes

packages/ai/STATUS.md

@@ -0,0 +1,107 @@
+# LLM Provider Parity Status
+
+Last reviewed: 2026-08-07
+
+This file tracks the gap between the native `@opencode-ai/ai` package and the AI SDK provider packages that opencode still depends on for many catalog/runtime paths.
+
+## Existing Status Sources
+
+| File                                | What it tracks                                                          | Limitation                                              |
+| ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
+| `packages/ai/DESIGN.md`             | Future clean-break API proposal for `@opencode-ai/ai`.                  | Not a provider parity tracker.                          |
+| `packages/ai/example/call-sites.md` | Route/value/provider-facade migration checklist and call-site sketches. | Architecture migration only; not AI SDK package parity. |
+
+## Current Implementation Snapshot
+
+| Native slice                       | Source                                                                                                                            | Current state                                                                                                                                                            | Main gaps                                                                                                                                                                                                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI Chat                        | `src/protocols/openai-chat.ts`, `src/providers/openai.ts`                                                                         | Usable. Streams text, reasoning deltas, tool calls, usage, images, and common generation controls.                                                                       | No typed structured-output / `response_format` path. Limited typed OpenAI option surface compared with SDK escape hatches.                                                                                                                                |
+| OpenAI Responses                   | `src/protocols/open-responses.ts`, `src/protocols/openai-responses.ts`, `src/providers/openai.ts`                                 | Usable over HTTP by default, with optional per-call WebSocket channel execution on the same model and route identity.                                                    | No incremental `previous_response_id` path or persistent Session channel manager yet. Typed options cover only a subset of Responses fields. Structured output is still mostly synthetic-tool based.                                                      |
+| OpenAI-compatible Chat             | `src/protocols/openai-compatible-chat.ts`, `src/providers/openai-compatible.ts`                                                   | Usable for generic Chat and several profiles: Baseten, Cerebras, DeepInfra, DeepSeek, Fireworks, Groq, TogetherAI.                                                       | Family quirks are mostly endpoint defaults, not full typed behavior.                                                                                                                                                                                      |
+| Open Responses-compatible          | `src/protocols/open-responses.ts`, `src/protocols/openai-compatible-responses.ts`, `src/providers/openai-compatible-responses.ts` | Usable for deployments that implement the provider-neutral Open Responses protocol. The deployment adapter does not inherit OpenAI tools, events, metadata, or defaults. | No named family profiles or recorded deployment coverage yet.                                                                                                                                                                                             |
+| Anthropic-compatible Messages      | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic-compatible.ts`                                                    | Usable for deployments that implement the Anthropic Messages wire protocol. Named Anthropic composes this base; MiniMax M3 has recorded text and tool-loop coverage.     | No named compatible family profiles yet.                                                                                                                                                                                                                  |
+| Anthropic Messages                 | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic.ts`                                                               | Usable. Supports tools, thinking, cache control, images, server-hosted tool events, and usage.                                                                           | Provider option surface is small. Beta/header handling, metadata, and newer Messages fields need a typed parity pass.                                                                                                                                     |
+| Gemini Developer API               | `src/protocols/gemini.ts`, `src/providers/google.ts`                                                                              | Usable for Google API key flow. Supports text, images, tools, thinking signatures, and cache usage.                                                                      | This is not Vertex. Typed provider options are narrow; many Gemini request fields currently require raw `http.body` overlays.                                                                                                                             |
+| Vertex Gemini                      | `src/protocols/gemini.ts`, `src/providers/google-vertex.ts`                                                                       | Usable through API-key express mode, explicit OAuth tokens, or ADC with project/location endpoint derivation, including tuned `endpoints/...` deployments.               | Core runner/catalog mapping and recorded provider coverage are missing.                                                                                                                                                                                   |
+| Vertex Chat                        | `src/protocols/openai-chat.ts`, `src/providers/google-vertex-chat.ts`                                                             | Usable for MaaS models through OpenAI-compatible Chat Completions with explicit OAuth tokens or ADC and project/location endpoint derivation.                            | Core runner/catalog mapping and recorded provider coverage are missing; MaaS family-specific request parity needs review.                                                                                                                                 |
+| Vertex Responses                   | `src/protocols/open-responses.ts`, `src/providers/google-vertex-responses.ts`                                                     | Usable for Grok models through Open Responses with explicit OAuth tokens or ADC, project/location endpoint derivation, and an explicit `store: false` Vertex default.    | Core runner/catalog mapping and recorded provider coverage are missing; stateful continuation is not supported by Vertex.                                                                                                                                 |
+| Vertex Messages                    | `src/protocols/anthropic-messages.ts`, `src/providers/google-vertex-messages.ts`                                                  | Usable through explicit OAuth tokens or ADC, including global, regional, and `eu`/`us` multi-region endpoints.                                                           | Core runner/catalog mapping and recorded provider coverage are missing; Vertex-specific hosted-tool parity needs review.                                                                                                                                  |
+| Bedrock Converse                   | `src/protocols/bedrock-converse.ts`, `src/providers/amazon-bedrock.ts`                                                            | Partial but real. Supports AWS event-stream framing, SigV4 with supplied credentials, bearer auth, tools, reasoning signatures, media, cache points, and recorded tests. | Native facade does not mirror the AI SDK plugin's default AWS credential chain/profile behavior. Runner/catalog mapping is missing. Guardrails, inference profiles, region-specific model ID fixes, and model-specific request fields need a parity pass. |
+| Azure OpenAI                       | `src/providers/azure.ts` using OpenAI Chat/Responses protocols                                                                    | Partial. Supports resource/base URL setup, API key auth, API version query, Chat, and Responses selectors.                                                               | Core runner does not map `@ai-sdk/azure` to this native facade. AAD/token auth and Azure-specific endpoint variants need review.                                                                                                                          |
+| Cloudflare AI Gateway / Workers AI | `src/providers/cloudflare.ts`                                                                                                     | Present via OpenAI-compatible Chat routes.                                                                                                                               | Useful but not part of the critical AI SDK replacement set yet. Needs per-product recorded coverage before relying on it broadly.                                                                                                                         |
+| OpenRouter                         | `src/providers/openrouter.ts`                                                                                                     | Present with OpenRouter-specific usage/reasoning/prompt-cache options over Chat.                                                                                         | Responses-style OpenRouter support is absent.                                                                                                                                                                                                             |
+| xAI                                | `src/providers/xai.ts`                                                                                                            | Present with Responses and Chat selectors.                                                                                                                               | Needs package-parity review against the AI SDK xAI provider.                                                                                                                                                                                              |
+| GitHub Copilot                     | `src/providers/github-copilot.ts`                                                                                                 | Present as explicit-base-URL OpenAI Chat/Responses facade.                                                                                                               | Runtime/catalog integration remains specialized and should stay separate from public OpenAI-compatible defaults.                                                                                                                                          |
+
+## V2 Runner Status
+
+`packages/core/src/session/runner/model.ts` currently resolves only this native subset from catalog `aisdk` metadata:
+
+| Catalog API                                         | Native route used today      |
+| --------------------------------------------------- | ---------------------------- |
+| `aisdk:@ai-sdk/openai`                              | `OpenAIResponses.route`      |
+| `aisdk:@ai-sdk/anthropic`                           | `AnthropicMessages.route`    |
+| `aisdk:@ai-sdk/openai-compatible` with explicit URL | `OpenAICompatibleChat.route` |
+
+Other `aisdk:` packages, including Google Vertex, Azure, and Bedrock, currently fall back through the AI SDK loader in the production runner. The dependency-free resolver seam rejects them with `SessionRunnerModel.UnsupportedPackageError`; they are not native route mappings yet.
+
+## AI SDK Package Parity Matrix
+
+| AI SDK package                    | Intended native target                                    | Status           | Biggest gaps                                                                                                                                                                                                        |
+| --------------------------------- | --------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@ai-sdk/openai`                  | `OpenAI.chat`, `OpenAI.responses`                         | Partial / usable | Add complete typed option coverage, structured output strategy, explicit Responses continuation support, and runner execution policy for optional WebSocket channels.                                               |
+| `@ai-sdk/openai-compatible`       | Generic OpenAI-compatible Chat and Responses              | Partial / usable | Decide per-family namespace/profile behavior and runner API selection for providers that support Responses versus Chat only.                                                                                        |
+| `@ai-sdk/anthropic`               | `AnthropicMessages`                                       | Partial / usable | Finish Messages API parity for headers/betas/metadata/newer fields and document hosted-tool continuation expectations.                                                                                              |
+| `@ai-sdk/google`                  | Gemini Developer API                                      | Partial / usable | Add typed options for safety, response schema/modalities, cached content, grounding/search/code execution, and non-text output modes where supported.                                                               |
+| `@ai-sdk/google-vertex`           | Vertex Gemini namespace/facade                            | Partial / usable | Add runner/catalog mapping, recorded coverage, and broader provider-option parity.                                                                                                                                  |
+| `@ai-sdk/google-vertex/anthropic` | Anthropic Messages over Vertex namespace/facade           | Partial / usable | Add runner/catalog mapping, recorded coverage, and Vertex-specific hosted-tool parity.                                                                                                                              |
+| `@ai-sdk/google-vertex/maas`      | Vertex Chat                                               | Partial / usable | Add runner/catalog mapping, recorded coverage, and MaaS family-specific request parity.                                                                                                                             |
+| `@ai-sdk/google-vertex/xai`       | Vertex Chat / Responses                                   | Partial / usable | Decide Chat/Responses selection for catalog models, add runner mapping and recorded coverage, and review xAI-specific request options.                                                                              |
+| `@ai-sdk/azure`                   | Azure OpenAI Chat/Responses facade                        | Partial          | Map runner/catalog metadata to native Azure, handle resourceName/baseURL/apiVersion variants, add AAD/token auth story, and verify Chat vs Responses deployment selection.                                          |
+| `@ai-sdk/amazon-bedrock`          | Bedrock Converse                                          | Partial          | Add default AWS credential chain/profile support, region/inference-profile model ID handling, provider option parity via `additionalModelRequestFields`, guardrails/performance config, and runner/catalog mapping. |
+| `@ai-sdk/amazon-bedrock/mantle`   | Bedrock Mantle OpenAI-compatible Chat/Responses namespace | Partial / usable | Add default AWS credential chain/profile support; native catalog mapping currently requires bearer auth or explicit static credentials.                                                                             |
+
+## Highest-Risk Gaps
+
+1. Runner support is narrower than the LLM package. The package has native provider facades for Google, Azure, and Bedrock, but the V2 Session runner only maps OpenAI, Anthropic, and explicit OpenAI-compatible Chat from `aisdk` catalog metadata.
+2. The Open Responses adapter is available through a separate package entrypoint, but the V2 runner still maps `@ai-sdk/openai-compatible` to Chat only. Catalog selection must become API-aware before Responses deployments can use it.
+3. Bedrock native auth is not AI SDK parity. The AI SDK plugin uses the default AWS provider chain, profile, container credentials, and Bedrock bearer token env behavior. Native Bedrock currently expects explicit credentials or bearer auth on the facade.
+4. Vertex Gemini, Vertex Chat, Vertex Responses, and Vertex Messages now have native package entrypoints, but the core runner does not map catalog metadata to them yet and recorded provider coverage is still missing.
+5. Azure is only a provider facade, not a full runtime replacement. Native Azure exists, but the catalog runner does not select it, and token auth/resource variants need review.
+6. Provider option typing is uneven. OpenAI, Anthropic, Gemini, Bedrock, and OpenRouter each expose a small typed subset plus raw HTTP overlays; this is useful but not equivalent to AI SDK provider option coverage.
+7. Structured output is not provider-native yet. `LLM.generateObject` still uses a synthetic tool strategy, while the future design expects native structured output where reliable and tool fallback where needed.
+8. Package/namespace boundaries for the current native loading set are explicit in docs and exports. Other exported provider facades are not catalog package entrypoints until they implement the contract. Vertex xAI still needs catalog API selection.
+9. Recorded coverage is uneven. OpenAI, Anthropic, Gemini, Bedrock Converse, Bedrock Mantle, Cloudflare, OpenRouter, and several OpenAI-compatible Chat providers have cassettes. Azure and Vertex still need first-class recorded scenarios before switching defaults.
+
+## Native Namespace Shape
+
+These are implementation/API slices, not separate npm packages.
+
+| API slice                     | Package-like entrypoint                                     | Purpose                                                                                    |
+| ----------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| OpenAI Chat                   | `@opencode-ai/ai/providers/openai/chat`                     | OpenAI `/chat/completions` semantics.                                                      |
+| OpenAI Responses              | `@opencode-ai/ai/providers/openai/responses`                | OpenAI `/responses` semantics with HTTP default and optional per-call WebSocket execution. |
+| OpenAI-compatible Chat        | `@opencode-ai/ai/providers/openai-compatible`               | Generic OpenAI-compatible `/chat/completions`.                                             |
+| Open Responses-compatible     | `@opencode-ai/ai/providers/openai-compatible/responses`     | Generic provider-neutral `/responses`.                                                     |
+| Anthropic-compatible Messages | `@opencode-ai/ai/providers/anthropic-compatible`            | Generic Anthropic-compatible `/messages`.                                                  |
+| Anthropic Messages            | `@opencode-ai/ai/providers/anthropic`                       | Anthropic Messages API.                                                                    |
+| Gemini Developer API          | `@opencode-ai/ai/providers/google`                          | Google AI Studio Gemini API.                                                               |
+| Vertex Gemini                 | `@opencode-ai/ai/providers/google-vertex/gemini`            | Vertex Gemini API; `providers/google-vertex` is the default alias.                         |
+| Vertex Chat                   | `@opencode-ai/ai/providers/google-vertex/chat`              | Vertex OpenAI-compatible Chat Completions for MaaS models.                                 |
+| Vertex Responses              | `@opencode-ai/ai/providers/google-vertex/responses`         | Vertex Open Responses for Grok models.                                                     |
+| Vertex Messages               | `@opencode-ai/ai/providers/google-vertex/messages`          | Vertex-hosted Anthropic Messages API.                                                      |
+| Bedrock Converse              | `@opencode-ai/ai/providers/amazon-bedrock`                  | AWS Bedrock Converse API.                                                                  |
+| Bedrock Mantle Chat           | `@opencode-ai/ai/providers/amazon-bedrock/mantle/chat`      | AWS Bedrock Mantle OpenAI-compatible Chat API.                                             |
+| Bedrock Mantle Responses      | `@opencode-ai/ai/providers/amazon-bedrock/mantle/responses` | AWS Bedrock Mantle OpenAI-compatible Responses API.                                        |
+| Azure OpenAI Chat             | `@opencode-ai/ai/providers/azure/chat`                      | Azure specialization of OpenAI Chat.                                                       |
+| Azure OpenAI Responses        | `@opencode-ai/ai/providers/azure/responses`                 | Azure specialization of OpenAI Responses.                                                  |
+
+## Suggested Next Work Slices
+
+1. Add native runner/catalog mappings for `@ai-sdk/azure`, `@ai-sdk/google`, and `@ai-sdk/amazon-bedrock` where the existing native facades are already close.
+2. Add API-aware runner/catalog selection between OpenAI-compatible Chat and Responses.
+3. Bring Bedrock native auth/config to AI SDK parity: region, profile, default AWS credential chain, bearer token env, endpoint override, and cross-region inference profile handling.
+4. Add runner/catalog mappings and recorded scenarios for the native Vertex Gemini, Chat, Responses, and Messages entrypoints.
+5. Decide Chat/Responses selection for `@ai-sdk/google-vertex/xai` catalog models.
+6. Expand typed provider options from the existing V1 lowerer knowledge in `packages/core/src/v1/config/provider-options.ts` before adding more raw overlay examples.
+7. Add recorded provider tests for Azure, Vertex Gemini, Vertex Chat, Vertex Responses, Vertex Messages, and Bedrock credential-chain behavior before making native runtime the default for those packages.

packages/ai/example/call-sites.md

@@ -0,0 +1,606 @@
+# LLM Call Site Sketches
+
+Scratchpad for examples first, abstractions second. Current direction: routes
+execute, provider facades organize configured route sets, and models carry route
+values directly.
+
+## Conversation Summary
+
+Kit and Aidan want provider-specific LLM behavior to move out of opencode's AI
+SDK transform path and into `packages/ai` where possible. The goal is not a big
+generic transform layer; the goal is small composable route definitions backed by
+recorded golden tests.
+
+Things to keep testing against:
+
+- Cache placement: `cache: "auto"`, manual cache breakpoints, provider cache usage.
+- Images: golden image tests for providers/protocols that claim image support.
+- Reasoning: canonical reasoning parts/events versus provider-native knobs.
+- Auth: bearer, custom headers, multiple credentials, query auth, SigV4, OAuth, no auth.
+- OpenAI-compatible providers: DeepSeek, Together, Groq, Alibaba/DashScope, custom routers.
+- Provider switching: stale signatures, encrypted reasoning, provider metadata, incompatible parts.
+- Error quality: typed errors instead of generic SDK/server failures.
+
+## Final Guide: Routes Execute, Providers Organize
+
+Do not introduce a first-class `Deployment` abstraction unless it gains real
+semantics. Provider facades are ergonomic configured route groups, not execution
+registries. The executable/composable thing is still a route. Do not make route
+construction publish to a global registry; models should carry their route value
+directly.
+
+Keep durable identity separate from runtime capability:
+
+- Durable identity is small serializable data like `{ providerID, modelID }` for
+  config, sessions, logs, and catalogs.
+- Runtime capability is a `LanguageModel` with a route value, protocol, transport, auth,
+  and defaults. It is allowed to contain functions and schemas.
+- If persisted identity needs to become executable, resolve it through an app
+  boundary first. Do not make `LLMRequest` recover behavior from a global route
+  side table.
+
+Keep unconfigured behavior values as values, not factories. A transport like
+`HttpTransport.sseJson` should be a reusable immutable value. Use a function only
+when the caller supplies options or when construction needs fresh state.
+
+Use constants to remove repetition before inventing abstractions. Provider ids
+are branded once per provider facade and reused across routes; a plain exported
+object is enough for the provider-facing API unless a helper earns its keep by
+removing repeated route projection.
+
+Expose default configured provider instances, and put provider-specific setup on
+`.configure(...)`. Model selectors stay pure: `model(id)`, `responses(id)`,
+`chat(id)`, etc. Endpoint/auth/resource/api-version configuration happens before
+model selection, not as a second argument to model selection.
+
+Use provider/product facades consistently:
+
+- One coherent provider/product config surface gets one top-level facade.
+- APIs/model kinds that share that config are methods on the facade.
+- Different products with different required config get separate top-level
+  facades, not a shared namespace with unrelated children.
+- Default facades are exposed only when concrete defaults or lazy env/credential
+  defaults make the facade valid.
+
+Examples:
+
+```ts
+OpenAI.responses("gpt-4o")
+OpenAI.chat("gpt-4o")
+
+Azure.configure({ resourceName, apiKey }).responses("my-deployment")
+AmazonBedrock.configure({ region, credentials }).model("anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+CloudflareAIGateway.configure({ accountId, gatewayId, gatewayApiKey, apiKey }).model("openai/gpt-4o")
+CloudflareWorkersAI.configure({ accountId, apiKey }).model("@cf/meta/llama-3.1-8b-instruct")
+
+OpenAICompatible.configure({
+  provider: "custom",
+  baseURL: "https://custom.example/v1",
+  auth: Auth.bearer(apiKey),
+}).model("custom-model")
+```
+
+Standardize the provider facade contract before abstracting construction. A
+plain object is enough at first; add a helper only if repeated route projection
+starts hiding the real provider-specific config.
+
+`Route.with(...)` patch semantics should be boring and explicit:
+
+- Omitted fields inherit from the original route.
+- `endpoint` patches merge with the existing endpoint, so overriding `baseURL`
+  keeps the existing `path`.
+- `endpoint.query` merges by default; later values win.
+- `auth` replaces.
+- `headers` merge by default; undefined values are omitted.
+- `id` is optional in patches. Route ids are diagnostic/provider API labels, not
+  global runtime registry keys.
+
+1. **Route**
+   - route id
+   - provider id
+   - protocol
+   - body schema
+   - body builder
+   - stream event schema
+   - parser/state machine
+   - transport
+     - method / IO shape
+     - framing
+     - request preparation
+     - constants when unconfigured; functions only when configured
+   - endpoint
+     - base URL
+     - static path
+     - body/model-derived path
+     - query params
+   - auth
+     - bearer
+     - custom header
+     - multiple credentials
+     - SigV4
+     - none
+   - defaults
+     - headers
+     - generation defaults
+     - provider options
+     - limits
+2. **Provider Facade**
+   - default configured provider instance
+   - provider-specific `.configure(...)`
+   - plain object/function facade over one or more routes
+   - top-level export only when it represents one coherent config surface
+   - no passive `Provider.make(...)` wrapper unless it gains runtime behavior
+3. **Model Selector**
+   - route/provider-owned selector
+   - accepts model id only
+   - returns executable models
+   - does not accept endpoint/auth/deployment overrides
+4. **Language Model**
+   - model id
+   - route value
+   - provider id
+   - configured route value at selection time
+5. **LLM Request**
+   - model
+   - messages/tools
+   - generation/cache/reasoning/response-format options
+   - request-level HTTP overlays for per-request headers/query/body additions,
+     not provider endpoint/auth reconfiguration
+6. **Compile**
+   - read route from model
+   - merge route defaults and request overrides
+   - build final URL from route endpoint
+   - apply auth from the configured route
+   - build body with protocol
+   - execute with transport and parse with protocol
+
+## Provider Facade Shape
+
+The provider abstraction is a facade over configured routes, not the runtime
+execution mechanism:
+
+```ts
+type ProviderFacade<APIs, Config> = {
+  readonly id: ProviderID
+  readonly model: (id: string) => LanguageModel
+  readonly configure: (input?: Config) => ProviderFacade<APIs, Config>
+} & APIs
+```
+
+Manual construction is fine and should be the default until duplication earns a
+helper:
+
+```ts
+export const OpenAI = {
+  id: openAIProvider,
+  model: openAIResponses.model,
+  responses: openAIResponses.model,
+  chat: openAIChat.model,
+  configure: configureOpenAI,
+} satisfies ProviderFacade<
+  {
+    responses: (id: string) => LanguageModel
+    chat: (id: string) => LanguageModel
+  },
+  OpenAIConfig
+>
+```
+
+If several providers repeat the same projection from route values to model
+methods, the helper can stay deliberately tiny:
+
+```ts
+const configureOpenAI = (input: OpenAIConfig = {}) =>
+  Provider.define({
+    id: openAIProvider,
+    routes: {
+      responses: openAIResponses.with(openAIConfig(input)),
+      chat: openAIChat.with(openAIConfig(input)),
+    },
+    default: "responses",
+    configure: configureOpenAI,
+  })
+
+export const OpenAI = configureOpenAI()
+```
+
+`Provider.define(...)` would only project route methods and preserve types:
+
+```ts
+OpenAI.model("gpt-4o")
+OpenAI.responses("gpt-4o")
+OpenAI.chat("gpt-4o")
+OpenAI.configure({ apiKey }).responses("gpt-4o")
+```
+
+It must not register routes, select routes dynamically, or participate in
+execution. Execution still reads the route value carried by the model.
+
+## Ideal Call Sites
+
+Define concrete routes for a native provider, then project them through a
+provider facade:
+
+```ts
+const openAIProvider = ProviderID.make("openai")
+
+const openAIResponses = Route.make({
+  id: "openai-responses",
+  provider: openAIProvider,
+  protocol: OpenAIResponses.protocol,
+  transport: HttpTransport.sseJson,
+  endpoint: {
+    baseURL: "https://api.openai.com/v1",
+    path: "/responses",
+  },
+  auth: Auth.envBearer("OPENAI_API_KEY"),
+})
+
+const openAIChat = Route.make({
+  id: "openai-chat",
+  provider: openAIProvider,
+  protocol: OpenAIChat.protocol,
+  transport: HttpTransport.sseJson,
+  endpoint: {
+    baseURL: "https://api.openai.com/v1",
+    path: "/chat/completions",
+  },
+  auth: Auth.envBearer("OPENAI_API_KEY"),
+})
+
+const openAIConfig = (input: OpenAIConfig) => ({
+  endpoint: input.endpoint,
+  auth: input.auth ?? (input.apiKey ? Auth.bearer(input.apiKey) : undefined),
+  headers: {
+    "OpenAI-Organization": input.organization,
+    "OpenAI-Project": input.project,
+  },
+})
+
+const configureOpenAI = (input: OpenAIConfig = {}) => {
+  const responses = openAIResponses.with(openAIConfig(input))
+  const chat = openAIChat.with(openAIConfig(input))
+
+  return {
+    id: openAIProvider,
+    responses: responses.model,
+    chat: chat.model,
+    model: responses.model,
+    configure: configureOpenAI,
+  }
+}
+
+export const OpenAI = configureOpenAI()
+```
+
+Specialize it functionally for concrete providers:
+
+```ts
+const deepSeekProvider = ProviderID.make("deepseek")
+
+const deepseekChat = openAIChat.with({
+  id: "deepseek-chat",
+  provider: deepSeekProvider,
+  endpoint: {
+    baseURL: "https://api.deepseek.com/v1",
+  },
+  auth: Auth.envBearer("DEEPSEEK_API_KEY"),
+})
+
+const configureDeepSeek = (input: OpenAICompatibleConfig = {}) => {
+  const route = deepseekChat.with({
+    endpoint: input.endpoint,
+    auth: input.auth ?? (input.apiKey ? Auth.bearer(input.apiKey) : undefined),
+  })
+
+  return {
+    id: deepSeekProvider,
+    model: route.model,
+    configure: configureDeepSeek,
+  }
+}
+
+export const DeepSeek = {
+  id: deepSeekProvider,
+  model: deepseekChat.model,
+  configure: configureDeepSeek,
+}
+```
+
+Provider-specific configuration happens before model selection:
+
+```ts
+const deepseek = DeepSeek.configure({
+  endpoint: {
+    baseURL: "https://proxy.example.com/v1",
+  },
+  auth: Auth.bearer(apiKey),
+})
+
+const model = deepseek.model("deepseek-chat")
+```
+
+Final request call site stays boring:
+
+```ts
+const response =
+  yield *
+  LLM.generate(
+    LLM.request({
+      model: DeepSeek.model("deepseek-chat"),
+      prompt: "Hello.",
+    }),
+  )
+```
+
+For direct provider-facade calls, Responses has one semantic model and route:
+
+```ts
+OpenAI.responses("gpt-4o")
+```
+
+The package-like OpenAI Responses entrypoint has the same transport-neutral
+`model(...)` contract:
+
+```ts
+import { model } from "@opencode-ai/ai/providers/openai/responses"
+
+model("gpt-4o", { apiKey })
+```
+
+Vertex keeps Gemini, Chat, Responses, and Messages as separate package-like entrypoints,
+while sharing project/location resolution and ADC authentication internally:
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/gemini"
+
+model("gemini-3.5-flash", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/chat"
+
+model("deepseek-ai/deepseek-v3.2-maas", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/responses"
+
+model("xai/grok-4.20-reasoning", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/messages"
+
+model("claude-sonnet-4-6", { project, location: "global" })
+```
+
+The client does not require a different public layer for WebSocket execution.
+Responses routes use HTTP by default, and callers may pass a channel executor per
+call. Routes without channel support simply ignore that execution capability.
+
+Azure is a route specialization with auth/path/default changes plus input
+mapping. The public API configures the Azure resource once, then selects
+deployment ids with pure model selectors:
+
+```ts
+const azureProvider = ProviderID.make("azure")
+
+const azureResponses = openAIResponses.with({
+  id: "azure-openai-responses",
+  provider: azureProvider,
+  auth: Auth.envHeader("api-key", "AZURE_OPENAI_API_KEY"),
+})
+
+const configureAzure = (input: AzureConfig = {}) => {
+  const route = azureResponses.with({
+    endpoint: {
+      baseURL:
+        input.baseURL ??
+        Endpoint.envBaseURL(
+          "AZURE_RESOURCE_NAME",
+          (resourceName) => `https://${resourceName}.openai.azure.com/openai/v1`,
+        ),
+      query: { "api-version": input.apiVersion ?? "v1" },
+    },
+    auth: input.apiKey ? Auth.header("api-key", input.apiKey) : Auth.envHeader("api-key", "AZURE_OPENAI_API_KEY"),
+  })
+
+  return {
+    id: azureProvider,
+    model: route.model,
+    responses: route.model,
+    configure: configureAzure,
+  }
+}
+
+export const Azure = configureAzure()
+
+const azure = Azure.configure({
+  resourceName: "my-resource",
+  apiVersion: "v1",
+})
+
+const model = azure.responses("my-deployment")
+```
+
+Default provider facades are only valid when required configuration has a lazy
+default source. `Azure.responses("my-deployment")` can be valid if endpoint
+resolution reads `AZURE_RESOURCE_NAME` lazily and fails with a typed
+configuration error when missing. If a provider has no sensible lazy default,
+do not expose a default model selector; expose only a configured entrypoint.
+
+Cloudflare AI Gateway and Workers AI are separate product facades because their
+configuration surfaces differ. Do not make a root `Cloudflare.configure(...)`
+pretend there is one coherent Cloudflare provider configuration:
+
+```ts
+const cloudflareProvider = ProviderID.make("cloudflare-ai-gateway")
+
+const cloudflareOpenAIChat = openAIChat.with({
+  id: "cloudflare-ai-gateway-openai-chat",
+  provider: cloudflareProvider,
+  auth: Auth.bearerHeader("cf-aig-authorization").andThen(Auth.bearer()),
+})
+
+const configureCloudflareAIGateway = (input: CloudflareAIGatewayConfig) => {
+  const route = cloudflareOpenAIChat.with({
+    endpoint: {
+      baseURL: `https://gateway.ai.cloudflare.com/v1/${input.accountId}/${input.gatewayId}/openai`,
+    },
+    auth: Auth.bearerHeader("cf-aig-authorization", input.gatewayApiKey).andThen(Auth.bearer(input.apiKey)),
+  })
+
+  return {
+    id: cloudflareProvider,
+    model: (modelID: string) => route.model({ id: modelID }),
+    configure: configureCloudflareAIGateway,
+  }
+}
+
+export const CloudflareAIGateway = {
+  id: cloudflareProvider,
+  configure: configureCloudflareAIGateway,
+}
+
+const gateway = CloudflareAIGateway.configure({
+  accountId: "account",
+  gatewayId: "gateway",
+  gatewayApiKey,
+  apiKey,
+})
+
+const model = gateway.model("openai/gpt-4o")
+```
+
+If a Cloudflare product gains a full lazy env default, it can expose a direct
+selector too. Until then, omitting `CloudflareAIGateway.model(...)` makes missing
+account/gateway configuration unrepresentable.
+
+opencode's dynamic runtime should construct executable models at its app
+boundary instead of exposing a giant unstructured public model constructor or a
+generic dynamic resolver:
+
+```ts
+const model =
+  providerID === "azure" ? Azure.configure(resolvedAzureConfig).responses(apiModelID) : OpenAI.responses(apiModelID)
+```
+
+That boundary can branch on durable config/catalog metadata and call typed
+provider APIs directly. Transport selection remains execution policy: a Session
+or other caller may pass a WebSocket channel executor per call without changing
+the model constructed by this boundary.
+
+## Competitive Shape
+
+This follows the strongest parts of adjacent libraries:
+
+- AI SDK: configured provider instances expose provider-specific model methods.
+- Effect AI: executable models carry provider requirements and can be resolved by
+  an app boundary.
+- LiteLLM/opencode config: dynamic `providerID/modelID` branching belongs at the
+  app boundary, not in the typed public provider API or a global runtime
+  resolver.
+- LangChain/LlamaIndex: constructor-style config plus model id is convenient,
+  but we avoid making model selection also configure endpoint/auth.
+
+The chosen split is:
+
+```txt
+Route = execution mechanics
+Provider facade = configured route group
+LanguageModel = selected executable model carrying route value
+App boundary = explicit durable-config -> typed-provider call
+```
+
+## What This Removes
+
+- No `Provider.make(...)` as a core abstraction.
+- No `Provider.make(...)` wrapper just to bind an id to model functions. Use a
+  branded provider id constant and a plain exported provider facade.
+- No `Deployment.define(...)` unless future examples force it.
+- No global route registry as the normal execution path.
+- No import side effects required before a model can execute.
+- No duplicate `provider.id` object when selected models already carry provider
+  id.
+- No `model(id, overrides)` escape hatch. Model selection takes the model id;
+  endpoint/auth/deployment customization happens by configuring the route first.
+- No transport setting on a provider or executable model. OpenAI Responses uses
+  HTTP by default and accepts an optional per-call channel executor as execution policy.
+- No separate public `LLMClient.layerWithWebSocket`. The runtime should expose one
+  client layer with the available transport capabilities.
+- No executable `ModelRef`. The executable handle is `LanguageModel`; durable model
+  identity stays separate and cannot execute on its own.
+
+## Implementation Todo
+
+- [x] Replace the current executable `ModelRef` with `LanguageModel`.
+- [x] Change `LanguageModel.route` to carry a route value, not a `RouteID` string.
+- [ ] Keep a separate durable model identity type for persisted/session/catalog
+      data, likely `{ providerID, modelID }`, and make it clear that it cannot
+      execute without resolver context.
+- [x] Change route model selectors so `route.model(id)` returns an executable
+      model with the route value attached, not a globally registered route id.
+- [x] Remove the standalone `Route.model(route, defaults, mapInput)` helper;
+      configured route instances own model selection.
+- [x] Remove endpoint/auth escape hatches from route model selection; callers must
+      configure endpoint/auth through `route.with(...)` or provider facades before
+      calling `.model(...)`.
+- [x] Remove request-shaping defaults from `LanguageModel`; selected models now carry only
+      id, provider, and configured route while defaults live on routes or requests.
+- [x] Rework `LLMClient.stream` / `generate` to read
+      `request.model.route` directly instead of calling `registeredRoute(...)`.
+- [x] Remove `Route.make(...)` global registration from the normal execution
+      path; keep route ids only as diagnostics/provider API labels.
+- [x] Model endpoint as `{ baseURL, path, query }` on routes, then remove the
+      current split where host/query live on the model and path lives in route
+      transport setup.
+- [x] Define `Route.with(...)` with explicit patch semantics for endpoint merge,
+      query merge, header merge, auth replacement, and optional diagnostic id.
+- [x] Make unconfigured transports reusable constants such as
+      `HttpTransport.sseJson`; keep transport functions only for configured/fresh
+      state construction.
+- [x] Collapse the public WebSocket runtime split so one `LLMClient.layer` accepts
+      optional per-call channel execution without changing route identity.
+- [x] Convert OpenAI provider APIs to provider-facade shape:
+      `OpenAI.configure(config).responses(id)` and `.chat(id)`.
+- [x] Convert Azure to a configured facade where resource/base URL/api version
+      setup happens before selecting deployment ids.
+- [x] Split Cloudflare products into separate facades such as
+      `CloudflareAIGateway` and `CloudflareWorkersAI`; do not expose a shared root
+      config surface unless one product actually exists.
+- [x] Migrate remaining built-in provider facades one at a time so configuration
+      happens before model selection and selectors accept only ids:
+      xAI, GitHub Copilot, OpenRouter, OpenAI-compatible families, Anthropic,
+      Google/Gemini, and Amazon Bedrock now use configured facades such as
+      `Provider.configure(options).model(id)` with named selectors where needed.
+- [ ] Decide whether a tiny `Provider.define(...)` helper is warranted after two
+      or three provider conversions; start with plain objects if duplication is not
+      yet painful.
+- [x] Keep executable model construction transport-neutral at the Session boundary;
+      Session-scoped execution policy supplies channel capability separately.
+- [ ] Update tests so direct route/provider tests assert route values are carried
+      by executable models, and opencode/native tests assert boundary-based route
+      selection.
+- [ ] Remove compatibility exports or stale docs only after internal call sites
+      are migrated; do not keep duplicate constructor paths without an external
+      compatibility need.
+
+## Open Questions
+
+- Default facades with required setup: should providers like Azure and Bedrock
+  expose default model selectors only when all required setup has lazy env or
+  credential-chain defaults? If not, omit the default selector so missing config
+  is impossible at the type/API level.
+- Lazy endpoint/auth values: should `Endpoint.envBaseURL(...)` and env-backed
+  auth produce typed configuration/authentication errors at compile/prepare time
+  or only when executing the transport?
+- `Route.with(...)` clearing semantics: endpoint/query/header patches merge by
+  default, but what is the explicit way to remove an inherited value?
+- Provider facade helper: keep plain objects until duplication hurts, or add a
+  tiny `Provider.define(...)` immediately to enforce shape and method projection?
+- Auth shape: should auth stay as today's composable `Auth`, or split into an
+  auth placement/strategy and credential sources?
+- Naming: is `baseURL` still the right endpoint field name, or should it be
+  `origin` / `urlPrefix` to clarify that route `path` is appended?

packages/ai/example/tutorial.ts

@@ -22,7 +22,7 @@ const model = OpenAI.configure({
   apiKey,
   generation: { maxTokens: 160 },
   providerOptions: {
-    store: false,
+    openai: { store: false },
   },
 }).model("gpt-4o-mini")
 
@@ -34,7 +34,7 @@ const model = OpenAI.configure({
 //   - `generation`: common controls such as max tokens, temperature, topP/topK,
 //     penalties, seed, and stop sequences.
 //   - `promptCacheKey`: stable cache affinity for protocols that support it.
-//   - `providerOptions`: model-typed provider-native behavior. For example,
+//   - `providerOptions`: namespaced provider-native behavior. For example,
 //     OpenAI store behavior, Anthropic thinking, Gemini thinking config, or
 //     OpenRouter routing/reasoning.
 //   - `http`: last-resort serializable overlays for final request body, headers,
@@ -188,7 +188,7 @@ const FakeProtocol = Protocol.make<FakeBody, string, string, void>({
   },
 })
 
-// A route is the runnable binding for that protocol. It adds the deployment
+// An route is the runnable binding for that protocol. It adds the deployment
 // axes that the protocol deliberately does not know: URL, auth, and framing.
 const FakeAdapter = Route.make({
   id: "fake-echo",

packages/ai/src/cache-policy.ts

@@ -5,8 +5,8 @@
 // The default `"auto"` shape places breakpoints at the last tool definition,
 // the first and last distinct system parts, and the conversation tail. This
 // exposes reusable tool, base-agent, project, and session prefixes while
-// advancing the tail after each tool result keeps recent conversation prefixes
-// reusable during long agent runs.
+// advancing the tail after each tool result keeps the previous cache entry
+// within Anthropic's 20-block lookback during long agent turns.
 //
 // Manual `cache: CacheHint` placements on individual parts are preserved and
 // count against the four-breakpoint budget; auto only fills remaining slots.
@@ -23,7 +23,9 @@ const NONE: CachePolicyObject = {}
 const BREAKPOINT_CAP = 4
 
 // Resolution rules:
-//   - undefined   → "auto" — caching is on by default.
+//   - undefined   → "auto" — caching is on by default. The math favors it:
+//                   Anthropic 5m-cache write is 1.25x base, read is 0.1x,
+//                   so a single reuse within 5 minutes already wins.
 //   - "auto"      → tools + first/last system + final message boundary.
 //   - "none"      → no auto placement; manual `CacheHint`s still flow.
 //   - object form → exactly what the caller asked for.

packages/ai/src/protocols/anthropic-messages.ts

@@ -16,6 +16,7 @@ import {
   type JsonSchema,
   type LLMRequest,
   type MediaPart,
+  type ProviderOptions,
   type ProviderMetadata,
   type ToolCallPart,
   type ToolDefinition,
@@ -29,6 +30,7 @@ import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "anthropic-messages"
+const MEDIA_MIMES = new Set<string>([...ProviderShared.IMAGE_MIMES, ...ProviderShared.PDF_MIMES])
 export const DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
 export const PATH = "/messages"
 
@@ -51,7 +53,9 @@ export interface OptionsInput {
   readonly effort?: string
 }
 
-export type ProviderOptionsInput = OptionsInput
+export type ProviderOptionsInput = ProviderOptions & {
+  readonly anthropic?: OptionsInput
+}
 
 // =============================================================================
 // Request Body Schema
@@ -396,7 +400,7 @@ const lowerServerToolResult = Effect.fn("AnthropicMessages.lowerServerToolResult
 })
 
 const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.validateMedia("Anthropic Messages", part, MEDIA_MIMES)
   if (media.mime === "application/pdf")
     return {
       type: "document" as const,
@@ -406,8 +410,6 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (part: Me
         data: media.base64,
       },
     } satisfies AnthropicDocumentBlock
-  if (!media.mime.startsWith("image/"))
-    return yield* invalid(`Anthropic Messages does not support media type ${part.mediaType}`)
   return {
     type: "image" as const,
     source: {
@@ -434,19 +436,10 @@ const lowerToolResultContent = Effect.fnUntraced(function* (part: ToolResultPart
   return yield* Effect.forEach(content, lowerToolResultContentItem)
 })
 
-// Mid-conversation system messages became available with Opus 4.8 and version
-// 5 of the other supported Claude families. Treat later family versions as
-// compatible without assuming that every Anthropic Messages model is Claude.
-const supportsNativeSystemUpdates = (request: LLMRequest) => {
-  const match = /(?:^|[./])claude-(fable|haiku|mythos|opus|sonnet)-(\d+)(?:[.-](\d+))?/.exec(
-    String(request.model.id).toLowerCase(),
-  )
-  if (!match) return false
-  const major = Number(match[2])
-  if (match[1] !== "opus") return major >= 5
-  if (major !== 4) return major >= 5
-  return match[3] !== undefined && match[3].length <= 2 && Number(match[3]) >= 8
-}
+// Mid-conversation system messages are a native Claude API feature only for
+// Opus 4.8. Other Anthropic models intentionally use the same visible wrapped-
+// user fallback as non-Anthropic routes rather than sending a role they reject.
+const supportsNativeSystemUpdates = (request: LLMRequest) => String(request.model.id) === "claude-opus-4-8"
 
 const endsInServerToolUse = (message: LLMRequest["messages"][number]) => {
   const last = message.content.at(-1)
@@ -590,7 +583,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
 })
 
 const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (request: LLMRequest) {
-  const input = request.providerOptions
+  const input = request.providerOptions?.anthropic
   return {
     thinking: yield* resolveThinking(input?.thinking),
     effort: typeof input?.effort === "string" ? input.effort : undefined,
@@ -902,7 +895,6 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
 
   if (delta?.type === "input_json_delta" && event.index !== undefined) {
     if (!delta.partial_json) return [state, NO_EVENTS] satisfies StepResult
-    if (!state.tools[event.index]) return [state, NO_EVENTS] satisfies StepResult
     const result = ToolStream.appendExisting(
       ADAPTER,
       state.tools,
@@ -964,12 +956,9 @@ const onMessageDelta = (state: ParserState, event: AnthropicEvent): StepResult =
   ]
 }
 
-const onMessageStop = Effect.fn("AnthropicMessages.onMessageStop")(function* (state: ParserState) {
-  const result = yield* ToolStream.finishAll(ADAPTER, state.tools)
+const onMessageStop = (state: ParserState): StepResult => {
   const events: LLMEvent[] = []
-  const lifecycle = result.events.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
-  events.push(...result.events)
-  const finished = Lifecycle.finish(lifecycle, events, {
+  const lifecycle = Lifecycle.finish(state.lifecycle, events, {
     reason: state.pendingFinish?.reason ?? {
       normalized: "unknown",
       raw: undefined,
@@ -977,8 +966,8 @@ const onMessageStop = Effect.fn("AnthropicMessages.onMessageStop")(function* (st
     usage: state.usage,
     providerMetadata: state.pendingFinish?.providerMetadata,
   })
-  return [{ ...state, lifecycle: finished, tools: result.tools }, events] satisfies StepResult
-})
+  return [{ ...state, lifecycle }, events]
+}
 
 // Prefix `error.type` so overloads, rate limits, and quota errors are visible
 // even when the provider message is generic or empty.
@@ -1002,7 +991,7 @@ const step = (state: ParserState, event: AnthropicEvent) => {
   if (event.type === "content_block_delta") return onContentBlockDelta(state, event)
   if (event.type === "content_block_stop") return onContentBlockStop(state, event)
   if (event.type === "message_delta") return Effect.succeed(onMessageDelta(state, event))
-  if (event.type === "message_stop") return onMessageStop(state)
+  if (event.type === "message_stop") return Effect.succeed(onMessageStop(state))
   if (event.type === "error") return onError(event)
   return Effect.succeed<StepResult>([state, NO_EVENTS])
 }
@@ -1012,8 +1001,8 @@ const step = (state: ParserState, event: AnthropicEvent) => {
 // =============================================================================
 /**
  * The Anthropic Messages protocol — request body construction, body schema,
- * and the streaming-event state machine shared by Anthropic-compatible and
- * Vertex-hosted Messages routes.
+ * and the streaming-event state machine. Used by native Anthropic Cloud and
+ * (once registered) Vertex Anthropic / Bedrock-hosted Anthropic passthrough.
  */
 export const protocol = Protocol.make({
   id: ADAPTER,

packages/ai/src/protocols/gemini.ts

@@ -12,6 +12,7 @@ import {
   type JsonSchema,
   type LLMRequest,
   type MediaPart,
+  type ProviderOptions,
   type ProviderMetadata,
   type TextPart,
   type ToolCallPart,
@@ -23,6 +24,7 @@ import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
 
 const ADAPTER = "gemini"
+const MEDIA_MIMES = new Set<string>(ProviderShared.MEDIA_MIMES)
 // Google documents this sentinel for replaying Gemini 3 function calls after their original signature was lost.
 const SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
@@ -66,7 +68,9 @@ export interface OptionsInput {
   }
 }
 
-export type ProviderOptionsInput = OptionsInput
+export type ProviderOptionsInput = ProviderOptions & {
+  readonly gemini?: OptionsInput
+}
 
 // =============================================================================
 // Request Body Schema
@@ -89,7 +93,7 @@ const GeminiFunctionCallPart = Schema.Struct({
   functionCall: Schema.Struct({
     id: Schema.optional(Schema.String),
     name: Schema.String,
-    args: Schema.optional(Schema.Unknown),
+    args: Schema.Unknown,
   }),
   thoughtSignature: Schema.optional(Schema.String),
 })
@@ -163,7 +167,6 @@ const GeminiGenerationConfig = Schema.Struct({
 const GeminiBodyFields = {
   cachedContent: Schema.optional(Schema.String),
   contents: Schema.Array(GeminiContent),
-  labels: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   safetySettings: optionalArray(GeminiSafetySetting),
   serviceTier: Schema.optional(Schema.String),
   systemInstruction: Schema.optional(GeminiSystemInstruction),
@@ -188,19 +191,8 @@ const GeminiCandidate = Schema.Struct({
   finishReason: Schema.optional(Schema.String),
 })
 
-const GeminiPromptFeedback = Schema.StructWithRest(
-  Schema.Struct({
-    blockReason: Schema.optional(Schema.String),
-    blockReasonMessage: Schema.optional(Schema.String),
-    safetyRatings: Schema.optional(Schema.Unknown),
-  }),
-  [Schema.Record(Schema.String, Schema.Unknown)],
-)
-type GeminiPromptFeedback = Schema.Schema.Type<typeof GeminiPromptFeedback>
-
 const GeminiEvent = Schema.Struct({
   candidates: optionalArray(GeminiCandidate),
-  promptFeedback: Schema.optional(GeminiPromptFeedback),
   usageMetadata: Schema.optional(GeminiUsage),
 })
 type GeminiEvent = Schema.Schema.Type<typeof GeminiEvent>
@@ -209,7 +201,6 @@ interface ParserState {
   readonly finishReason?: string
   readonly hasToolCalls: boolean
   readonly nextToolCallId: number
-  readonly promptFeedback?: GeminiPromptFeedback
   readonly usage?: Usage
   readonly lifecycle: Lifecycle.State
   readonly reasoningSignature?: string
@@ -257,7 +248,7 @@ const lowerToolConfig = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
 
 const lowerUserPart = Effect.fn("Gemini.lowerUserPart")(function* (part: TextPart | MediaPart) {
   if (part.type === "text") return { text: part.text }
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.validateMedia("Gemini", part, MEDIA_MIMES)
   return { inlineData: { mimeType: media.mime, data: media.base64 } }
 })
 
@@ -362,7 +353,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       const media: GeminiInlineDataPart[] = []
       for (const item of content) {
         if (item.type === "text") continue
-        const value = ProviderShared.normalizeToolFile(item)
+        const value = yield* ProviderShared.validateToolFile("Gemini", item, MEDIA_MIMES)
         media.push({ inlineData: { mimeType: value.mime, data: value.base64 } })
       }
       parts.push({
@@ -384,7 +375,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
 })
 
 const resolveOptions = (request: LLMRequest) => {
-  const input = request.providerOptions
+  const input = request.providerOptions?.gemini
   const value = input?.thinkingConfig
   const thinkingConfig = {
     thinkingBudget:
@@ -513,37 +504,32 @@ const mapFinishReason = (finishReason: string | undefined, hasToolCalls: boolean
   return "unknown"
 }
 
-const finish = (state: ParserState): ReadonlyArray<LLMEvent> => {
-  const promptBlockReason = state.finishReason === undefined ? state.promptFeedback?.blockReason : undefined
-  const finishReason = state.finishReason ?? promptBlockReason
-  if (finishReason === undefined && state.usage === undefined) return []
-
-  const events: LLMEvent[] = []
-  const lifecycle = state.reasoningSignature
-    ? Lifecycle.reasoningEnd(
-        state.lifecycle,
-        events,
-        "reasoning-0",
-        googleMetadata({ thoughtSignature: state.reasoningSignature }),
-      )
-    : state.lifecycle
-  Lifecycle.finish(lifecycle, events, {
-    reason: {
-      normalized:
-        promptBlockReason === undefined ? mapFinishReason(finishReason, state.hasToolCalls) : "content-filter",
-      raw: finishReason,
-    },
-    usage: state.usage,
-    providerMetadata:
-      state.promptFeedback === undefined ? undefined : googleMetadata({ promptFeedback: state.promptFeedback }),
-  })
-  return events
-}
+const finish = (state: ParserState): ReadonlyArray<LLMEvent> =>
+  state.finishReason || state.usage
+    ? (() => {
+        const events: LLMEvent[] = []
+        const lifecycle = state.reasoningSignature
+          ? Lifecycle.reasoningEnd(
+              state.lifecycle,
+              events,
+              "reasoning-0",
+              googleMetadata({ thoughtSignature: state.reasoningSignature }),
+            )
+          : state.lifecycle
+        Lifecycle.finish(lifecycle, events, {
+          reason: {
+            normalized: mapFinishReason(state.finishReason, state.hasToolCalls),
+            raw: state.finishReason,
+          },
+          usage: state.usage,
+        })
+        return events
+      })()
+    : []
 
 const step = (state: ParserState, event: GeminiEvent) => {
   const nextState = {
     ...state,
-    promptFeedback: event.promptFeedback ?? state.promptFeedback,
     usage: event.usageMetadata ? (mapUsage(event.usageMetadata) ?? state.usage) : state.usage,
   }
   const candidate = event.candidates?.[0]
@@ -584,7 +570,7 @@ const step = (state: ParserState, event: GeminiEvent) => {
     }
 
     if ("functionCall" in part) {
-      const input = part.functionCall.args === undefined ? {} : part.functionCall.args
+      const input = part.functionCall.args
       const id = `tool_${nextToolCallId++}`
       const metadata = {
         ...(part.functionCall.id === undefined ? {} : { functionCallId: part.functionCall.id }),
@@ -627,7 +613,8 @@ const step = (state: ParserState, event: GeminiEvent) => {
 // =============================================================================
 /**
  * The Gemini protocol — request body construction, body schema, and the
- * streaming-event state machine shared by Google AI Studio and Vertex Gemini.
+ * streaming-event state machine. Used by Google AI Studio Gemini and (once
+ * registered) Vertex Gemini.
  */
 export const protocol = Protocol.make({
   id: ADAPTER,

packages/ai/src/protocols/open-responses.ts

@@ -26,6 +26,7 @@ import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "open-responses"
 const NAME = "Open Responses"
+const MEDIA_MIMES = new Set<string>([...ProviderShared.IMAGE_MIMES, ...ProviderShared.PDF_MIMES])
 export const PATH = "/responses"
 
 // =============================================================================
@@ -90,7 +91,6 @@ const OpenResponsesFunctionCallOutput = Schema.Union([
 
 export const InputItem = Schema.Union([
   Schema.Struct({ role: Schema.tag("system"), content: Schema.String }),
-  Schema.Struct({ role: Schema.tag("developer"), content: Schema.String }),
   Schema.Struct({ role: Schema.tag("user"), content: Schema.Array(OpenResponsesInputContent) }),
   Schema.Struct({
     role: Schema.tag("assistant"),
@@ -141,11 +141,6 @@ export const Tool = Schema.Struct({
 export const ToolChoice = Schema.Union([
   Schema.Literals(["auto", "none", "required"]),
   Schema.Struct({ type: Schema.tag("function"), name: Schema.String }),
-  Schema.Struct({
-    type: Schema.tag("allowed_tools"),
-    mode: Schema.Literals(["auto", "none", "required"]),
-    tools: Schema.Array(Schema.Struct({ type: Schema.tag("function"), name: Schema.String })),
-  }),
 ])
 
 // Fields shared between the HTTP body and the WebSocket `response.create`
@@ -159,7 +154,6 @@ export const coreFields = {
   tools: optionalArray(Tool),
   tool_choice: Schema.optional(ToolChoice),
   store: Schema.optional(Schema.Boolean),
-  truncation: Schema.optional(OpenResponsesOptions.TruncationSchema),
   service_tier: Schema.optional(OpenResponsesOptions.ServiceTierSchema),
   prompt_cache_key: Schema.optional(Schema.String),
   include: optionalArray(OpenResponsesOptions.ResponseIncludableSchema),
@@ -175,8 +169,6 @@ export const coreFields = {
     }),
   ),
   max_output_tokens: Schema.optional(Schema.Number),
-  max_tool_calls: Schema.optional(Schema.Int),
-  parallel_tool_calls: Schema.optional(Schema.Boolean),
   temperature: Schema.optional(Schema.Number),
   top_p: Schema.optional(Schema.Number),
 }
@@ -293,7 +285,7 @@ export interface Extension {
   readonly name: string
   readonly lowerMedia?: (input: {
     readonly part: MediaPart
-    readonly media: ProviderShared.NormalizedMedia
+    readonly media: ProviderShared.ValidatedMedia
     readonly request: LLMRequest
   }) => MediaInput | undefined
   readonly messagePhase?: (value: unknown) => MessagePhase | null | undefined
@@ -340,7 +332,7 @@ export const lowerTool = Effect.fn("OpenResponses.lowerTool")(function* (
     name: tool.name,
     description: tool.description,
     parameters: ToolSchemaProjection.responses(inputSchema),
-    // The common tool definition does not currently express Responses strict-schema policy.
+    // TODO: Read this from Responses tool options so direct LLM callers can opt into strict schemas.
     strict: false,
   }
 })
@@ -388,13 +380,13 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   request: LLMRequest,
   extension: Extension,
 ) {
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.validateMedia(extension.name, part, MEDIA_MIMES)
   const extended = extension.lowerMedia?.({ part, media, request })
   if (extended) return extended
-  if (!media.mime.startsWith("image/")) {
+  if (media.mime === "application/pdf") {
     return {
       type: "input_file" as const,
-      filename: part.filename ?? (media.mime === "application/pdf" ? "document.pdf" : "file"),
+      filename: part.filename ?? "document.pdf",
       file_data: media.dataUrl,
     }
   }
@@ -448,10 +440,14 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
 
   for (const message of request.messages) {
     if (message.role === "system") {
-      input.push({
-        role: "developer",
-        content: ProviderShared.joinText(yield* ProviderShared.systemUpdateText(extension.name, message)),
-      })
+      const part = yield* ProviderShared.wrappedSystemUpdate(extension.name, message)
+      const previous = input.at(-1)
+      if (previous && "role" in previous && previous.role === "user")
+        input[input.length - 1] = {
+          role: "user",
+          content: [...previous.content, { type: "input_text", text: part.text }],
+        }
+      else input.push({ role: "user", content: [{ type: "input_text", text: part.text }] })
       continue
     }
 
@@ -585,19 +581,6 @@ const lowerOptions = (request: LLMRequest) => {
       : {}),
     ...(options.textVerbosity ? { text: { verbosity: options.textVerbosity } } : {}),
     ...(options.serviceTier ? { service_tier: options.serviceTier } : {}),
-    ...(options.maxToolCalls !== undefined ? { max_tool_calls: options.maxToolCalls } : {}),
-    ...(options.parallelToolCalls !== undefined ? { parallel_tool_calls: options.parallelToolCalls } : {}),
-    ...(options.truncation ? { truncation: options.truncation } : {}),
-  }
-}
-
-const allowedToolChoice = (request: LLMRequest) => {
-  const allowed = OpenResponsesOptions.resolve(request).allowedTools
-  if (!allowed) return undefined
-  return {
-    type: "allowed_tools" as const,
-    mode: allowed.mode,
-    tools: allowed.toolNames.map((name) => ({ type: "function" as const, name })),
   }
 }
 
@@ -620,9 +603,7 @@ export const fromRequestWithExtension = Effect.fn("OpenResponses.fromRequestWith
               ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
             ),
           ),
-    tool_choice:
-      allowedToolChoice(request) ??
-      (request.toolChoice ? yield* lowerToolChoice(extension.name, request.toolChoice) : undefined),
+    tool_choice: request.toolChoice ? yield* lowerToolChoice(extension.name, request.toolChoice) : undefined,
     stream: true as const,
     max_output_tokens: generation?.maxTokens,
     temperature: generation?.temperature,

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

@@ -28,6 +28,7 @@ import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "openai-chat"
+const IMAGE_MIMES = new Set<string>(ProviderShared.IMAGE_MIMES)
 const RESERVED_REASONING_FIELDS = new Set(["role", "content", "tool_calls"])
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/chat/completions"
@@ -283,9 +284,7 @@ const lowerToolCall = (part: ToolCallPart): OpenAIChatAssistantToolCall => ({
 })
 
 const lowerMedia = Effect.fn("OpenAIChat.lowerMedia")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
-  if (!media.mime.startsWith("image/"))
-    return yield* ProviderShared.invalidRequest(`OpenAI Chat does not support media type ${part.mediaType}`)
+  const media = yield* ProviderShared.validateMedia("OpenAI Chat", part, IMAGE_MIMES)
   return { type: "image_url" as const, image_url: { url: media.dataUrl } }
 })
 

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

@@ -121,8 +121,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
         : yield* Effect.forEach(request.tools, (tool) =>
             lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
           ),
-    tool_choice:
-      body.tool_choice ?? (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
+    tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined,
   } satisfies OpenAIResponsesBody
 })
 
@@ -261,7 +260,7 @@ export const route = Route.make({
   endpoint,
   auth,
   transport,
-  defaults: { providerOptions: { store: false } },
+  defaults: { providerOptions: { openai: { store: false } } },
 })
 
 export * as OpenAIResponses from "./openai-responses.js"

packages/ai/src/protocols/shared.ts

@@ -41,10 +41,12 @@ export interface ToolAccumulator {
  * when at least one is defined. Returns `undefined` when neither input nor
  * output is known so routes don't publish a misleading `0`.
  *
- * Under the inclusive `AI.Usage` contract, `inputTokens` includes cached input
- * and `outputTokens` includes reasoning. Protocol mappers normalize those
- * inclusive values before calling this helper. The provider-supplied total is
- * the source of truth when present; otherwise their sum is the canonical total.
+ * Under the additive `AI.Usage` contract, `inputTokens` and `outputTokens`
+ * are the non-cached input and visible output only. The provider-supplied
+ * `total` is the source of truth when present; the computed fallback
+ * under-counts cache and reasoning by design and exists mainly so
+ * Anthropic-style providers (which don't surface a total) still get a
+ * sensible aggregate on the input + output axes.
  */
 export const totalTokens = (
   inputTokens: number | undefined,
@@ -65,7 +67,7 @@ export const totalTokens = (
  *
  * If `total` is `undefined`, returns `undefined` (we don't fabricate
  * counts). If `subtrahend` is `undefined`, returns `total` unchanged. The
- * provider-native breakdown stays available on `Usage.providerMetadata` for debugging.
+ * provider-native breakdown stays available on `Usage.native` for debugging.
  */
 export const subtractTokens = (total: number | undefined, subtrahend: number | undefined): number | undefined => {
   if (total === undefined) return undefined
@@ -153,24 +155,59 @@ export const wrappedSystemUpdate = Effect.fn("ProviderShared.wrappedSystemUpdate
 export const parseToolInput = (route: string, name: string, raw: string) =>
   parseJson(route, raw || "{}", `Invalid JSON input for ${route} tool call ${name}`)
 
-export interface NormalizedMedia {
+export const IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "image/webp"] as const
+export const VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"] as const
+export const AUDIO_MIMES = ["audio/wav", "audio/mp3", "audio/aiff", "audio/aac", "audio/ogg", "audio/flac"] as const
+export const PDF_MIMES = ["application/pdf"] as const
+export const MEDIA_MIMES = [...IMAGE_MIMES, ...VIDEO_MIMES, ...AUDIO_MIMES, ...PDF_MIMES] as const
+export const MAX_MEDIA_ENCODED_BYTES = 28 * 1024 * 1024
+export const MAX_MEDIA_DECODED_BYTES = 20 * 1024 * 1024
+
+const base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+export interface ValidatedMedia {
   readonly mime: string
   readonly base64: string
   readonly dataUrl: string
+  readonly bytes: Uint8Array
 }
 
-export const normalizeMedia = (part: MediaPart): NormalizedMedia => {
+export const validateMedia = Effect.fn("ProviderShared.validateMedia")(function* (
+  route: string,
+  part: MediaPart,
+  supportedMimes: ReadonlySet<string>,
+) {
   const mime = part.mediaType.toLowerCase()
-  if (typeof part.data !== "string") {
-    const base64 = Buffer.from(part.data).toString("base64")
-    return { mime, base64, dataUrl: `data:${mime};base64,${base64}` }
-  }
-  if (!part.data.startsWith("data:")) return { mime, base64: part.data, dataUrl: `data:${mime};base64,${part.data}` }
-  return { mime, base64: part.data.slice(part.data.indexOf(",") + 1), dataUrl: part.data }
-}
+  if (!supportedMimes.has(mime)) return yield* invalidRequest(`${route} does not support media type ${part.mediaType}`)
 
-export const normalizeToolFile = (part: Tool.FileContent) =>
-  normalizeMedia({ type: "media", mediaType: part.mime, data: part.uri, filename: part.name })
+  let base64: string
+  if (typeof part.data !== "string") {
+    if (part.data.byteLength > MAX_MEDIA_DECODED_BYTES)
+      return yield* invalidRequest(`${route} media exceeds the ${MAX_MEDIA_DECODED_BYTES} byte decoded limit`)
+    base64 = Buffer.from(part.data).toString("base64")
+  } else if (part.data.startsWith("data:")) {
+    const match = /^data:([^;,]+);base64,([A-Za-z0-9+/]*={0,2})$/s.exec(part.data)
+    if (!match) return yield* invalidRequest(`${route} media data URL must contain valid base64`)
+    if (match[1]!.toLowerCase() !== mime)
+      return yield* invalidRequest(`${route} media type ${part.mediaType} does not match data URL type ${match[1]}`)
+    base64 = match[2]!
+  } else {
+    base64 = part.data
+  }
+
+  if (Buffer.byteLength(base64, "utf8") > MAX_MEDIA_ENCODED_BYTES)
+    return yield* invalidRequest(`${route} media exceeds the ${MAX_MEDIA_ENCODED_BYTES} byte encoded limit`)
+  if (!base64 || base64.length % 4 !== 0 || !base64Pattern.test(base64))
+    return yield* invalidRequest(`${route} media must contain valid base64`)
+  const bytes = Buffer.from(base64, "base64")
+  if (bytes.byteLength > MAX_MEDIA_DECODED_BYTES)
+    return yield* invalidRequest(`${route} media exceeds the ${MAX_MEDIA_DECODED_BYTES} byte decoded limit`)
+  if (bytes.toString("base64") !== base64) return yield* invalidRequest(`${route} media must contain canonical base64`)
+  return { mime, base64, dataUrl: `data:${mime};base64,${base64}`, bytes } satisfies ValidatedMedia
+})
+
+export const validateToolFile = (route: string, part: Tool.FileContent, supportedMimes: ReadonlySet<string>) =>
+  validateMedia(route, { type: "media", mediaType: part.mime, data: part.uri, filename: part.name }, supportedMimes)
 
 export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
 
@@ -197,24 +234,27 @@ export const errorText = (error: unknown) => {
 
 /**
  * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
- * decoder, and drops empty / `[DONE]` keep-alive events so the protocol event
- * schema sees one JSON string per element. The SSE channel emits a
+ * decoder, and drops empty / `[DONE]` keep-alive events so the downstream
+ * `decodeChunk` sees one JSON string per element. The SSE channel emits a
  * `Retry` control event on its error channel; we drop it here (we don't
- * implement client-driven retries). Decoder failures become provider output
- * errors so the public error channel stays `AIError`.
+ * implement client-driven retries) so the public error channel stays
+ * `AIError`.
  */
 export const sseFraming = (bytes: Stream.Stream<Uint8Array, AIError>): Stream.Stream<string, AIError> =>
   bytes.pipe(
     Stream.decodeText(),
     Stream.pipeThroughChannel(Sse.decode()),
     Stream.catchTag("Retry", () => Stream.empty),
-    Stream.catchTag("SseError", (error) => Stream.fail(eventError("sse", error.message))),
     Stream.filter((event) => event.data.length > 0 && event.data !== "[DONE]"),
     Stream.map((event) => event.data),
   )
 
 /**
- * Canonical invalid-request constructor shared by protocol lowering.
+ * Canonical invalid-request constructor. Lift one-line `const invalid =
+ * (message) => invalidRequest(message)` aliases out of every
+ * route so the error constructor lives in one place. If we ever extend
+ * `InvalidRequestReason` with route context or trace metadata, the change
+ * lands here.
  */
 export const invalidRequest = (message: string) =>
   new AIError({

packages/ai/src/protocols/utils/bedrock-cache.ts

@@ -4,7 +4,7 @@ import { newBreakpoints, ttlBucket, type Breakpoints } from "./cache.js"
 
 // Bedrock cache markers are positional: emit a `cachePoint` block immediately
 // after the content the caller wants treated as a cacheable prefix. Bedrock
-// accepts optional `ttl: "5m" | "1h"` on cachePoint.
+// accepts optional `ttl: "5m" | "1h"` on cachePoint, mirroring Anthropic.
 export const CachePointBlock = Schema.Struct({
   cachePoint: Schema.Struct({
     type: Schema.tag("default"),
@@ -13,8 +13,9 @@ export const CachePointBlock = Schema.Struct({
 })
 export type CachePointBlock = Schema.Schema.Type<typeof CachePointBlock>
 
-// Callers pass a shared counter through every `block()` call site so the
-// four-breakpoint budget is respected across `system`, `messages`, and `tools`.
+// Bedrock-Claude enforces the same 4-breakpoint cap as the Anthropic Messages
+// API. Callers pass a shared counter through every `block()` call site so the
+// budget is respected across `system`, `messages`, and `tools`.
 export const BEDROCK_BREAKPOINT_CAP = 4
 
 export type { Breakpoints } from "./cache.js"

packages/ai/src/protocols/utils/bedrock-media.ts

@@ -66,7 +66,11 @@ export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart)
   const mime = part.mediaType.toLowerCase()
   const imageFormat = IMAGE_FORMATS[mime as keyof typeof IMAGE_FORMATS]
   if (imageFormat) {
-    const media = ProviderShared.normalizeMedia(part)
+    const media = yield* ProviderShared.validateMedia(
+      "Bedrock Converse",
+      part,
+      new Set<string>(Object.keys(IMAGE_FORMATS)),
+    )
     return { image: { format: imageFormat, source: { bytes: media.base64 } } } satisfies ImageBlock
   }
   if (mime.startsWith("image/"))
@@ -75,7 +79,11 @@ export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart)
   if (documentFormat) {
     if (!part.filename)
       return yield* ProviderShared.invalidRequest("Bedrock Converse document media requires a filename")
-    const media = ProviderShared.normalizeMedia(part)
+    const media = yield* ProviderShared.validateMedia(
+      "Bedrock Converse",
+      part,
+      new Set<string>(Object.keys(DOCUMENT_FORMATS)),
+    )
     return documentBlock(part.filename, documentFormat, media.base64)
   }
   return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support media type ${part.mediaType}`)

packages/ai/src/protocols/utils/cache.ts

@@ -1,4 +1,6 @@
-// Shared counter and TTL mapping for provider cache-marker lowering.
+// Shared helpers for provider cache-marker lowering. Anthropic and Bedrock
+// both enforce a 4-breakpoint cap per request and accept the same `5m`/`1h`
+// TTL buckets, so the counter and TTL mapping live here.
 
 export interface Breakpoints {
   remaining: number
@@ -7,7 +9,8 @@ export interface Breakpoints {
 
 export const newBreakpoints = (cap: number): Breakpoints => ({ remaining: cap, dropped: 0 })
 
-// Requests of at least one hour use the explicit `"1h"` bucket; shorter
-// requests omit the wire TTL and use the provider default.
+// Returns `"1h"` for any `ttlSeconds >= 3600`, otherwise `undefined` (the
+// provider default 5m). Anthropic & Bedrock both treat anything shorter than
+// an hour as 5m.
 export const ttlBucket = (ttlSeconds: number | undefined): "1h" | undefined =>
   ttlSeconds !== undefined && ttlSeconds >= 3600 ? "1h" : undefined

packages/ai/src/protocols/utils/open-responses-options.ts

@@ -1,19 +1,5 @@
-import { Option, Schema } from "effect"
-import type { LLMRequest } from "../../schema/index.js"
-
-export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
-export type ReasoningEffort = (typeof ReasoningEfforts)[number] | (string & {})
-export const ReasoningEffort = Schema.declare<ReasoningEffort>(
-  (value): value is ReasoningEffort => typeof value === "string",
-  { title: "ReasoningEffort" },
-)
-
-export const TextVerbosities = ["low", "medium", "high"] as const
-export type TextVerbosity = (typeof TextVerbosities)[number] | (string & {})
-export const TextVerbosity = Schema.declare<TextVerbosity>(
-  (value): value is TextVerbosity => typeof value === "string",
-  { title: "TextVerbosity" },
-)
+import { Schema } from "effect"
+import { TextVerbosity, type LLMRequest } from "../../schema/index.js"
 
 export const ResponseIncludables = [
   "file_search_call.results",
@@ -25,59 +11,52 @@ export const ResponseIncludables = [
   "reasoning.encrypted_content",
   "message.output_text.logprobs",
 ] as const
-export type ResponseIncludable = (typeof ResponseIncludables)[number] | (string & {})
+export type ResponseIncludable = (typeof ResponseIncludables)[number]
 
 export const ServiceTiers = ["auto", "default", "flex", "priority"] as const
 export type ServiceTier = (typeof ServiceTiers)[number]
 
-export const Truncations = ["auto", "disabled"] as const
-export type Truncation = (typeof Truncations)[number]
+const TEXT_VERBOSITY = new Set<string>(["low", "medium", "high"])
+const INCLUDABLES = new Set<string>(ResponseIncludables)
+const SERVICE_TIERS = new Set<string>(ServiceTiers)
 
+const isTextVerbosity = (value: unknown): value is Schema.Schema.Type<typeof TextVerbosity> =>
+  typeof value === "string" && TEXT_VERBOSITY.has(value)
+
+const isServiceTier = (value: unknown): value is ServiceTier => typeof value === "string" && SERVICE_TIERS.has(value)
+
+export const ReasoningEffort = Schema.String
 export const TextVerbositySchema = TextVerbosity
-export const ResponseIncludableSchema = Schema.declare<ResponseIncludable>(
-  (value): value is ResponseIncludable => typeof value === "string",
-  { title: "ResponseIncludable" },
-)
+export const ResponseIncludableSchema = Schema.Literals(ResponseIncludables)
 export const ServiceTierSchema = Schema.Literals(ServiceTiers)
-export const TruncationSchema = Schema.Literals(Truncations)
 
-export const AllowedTools = Schema.Struct({
-  toolNames: Schema.Array(Schema.String),
-  mode: Schema.optional(Schema.Literals(["auto", "none", "required"])),
-})
-export type AllowedTools = typeof AllowedTools.Type
-
-export const Options = Schema.Struct({
-  instructions: Schema.optional(Schema.String),
-  store: Schema.optional(Schema.Boolean),
-  reasoningEffort: Schema.optional(ReasoningEffort),
-  reasoningSummary: Schema.optional(Schema.Literals(["auto", "concise", "detailed"])),
-  include: Schema.optional(Schema.Array(ResponseIncludableSchema)),
-  textVerbosity: Schema.optional(TextVerbositySchema),
-  serviceTier: Schema.optional(ServiceTierSchema),
-  truncation: Schema.optional(TruncationSchema),
-  allowedTools: Schema.optional(AllowedTools),
-  maxToolCalls: Schema.optional(Schema.Int),
-  parallelToolCalls: Schema.optional(Schema.Boolean),
-})
-export type Options = typeof Options.Type
-
-export type Resolved = Omit<Options, "allowedTools"> & {
-  readonly allowedTools?: AllowedTools & { readonly mode: NonNullable<AllowedTools["mode"]> }
+export interface Resolved {
+  readonly instructions?: string
+  readonly store?: boolean
+  readonly reasoningEffort?: string
+  readonly reasoningSummary?: "auto" | "concise" | "detailed"
+  readonly include?: ReadonlyArray<ResponseIncludable>
+  readonly textVerbosity?: Schema.Schema.Type<typeof TextVerbosity>
+  readonly serviceTier?: ServiceTier
 }
 
-const decodeOptions = Schema.decodeUnknownOption(Options)
-
 export const resolve = (request: LLMRequest): Resolved => {
-  const input = Option.getOrUndefined(decodeOptions(request.providerOptions))
-  if (!input) return {}
+  const input = request.providerOptions?.[request.model.route.providerMetadataKey ?? "openresponses"]
+  const include = Array.isArray(input?.include)
+    ? input.include.filter((entry): entry is ResponseIncludable => INCLUDABLES.has(entry))
+    : []
+  const reasoningSummary = input?.reasoningSummary
   return {
-    ...input,
-    include: input.include?.length ? input.include : undefined,
-    allowedTools:
-      input.allowedTools && input.allowedTools.toolNames.length > 0
-        ? { ...input.allowedTools, mode: input.allowedTools.mode ?? "auto" }
+    instructions: typeof input?.instructions === "string" ? input.instructions : undefined,
+    store: typeof input?.store === "boolean" ? input.store : undefined,
+    reasoningEffort: typeof input?.reasoningEffort === "string" ? input.reasoningEffort : undefined,
+    reasoningSummary:
+      reasoningSummary === "auto" || reasoningSummary === "concise" || reasoningSummary === "detailed"
+        ? reasoningSummary
         : undefined,
+    include: include.length > 0 ? include : undefined,
+    textVerbosity: isTextVerbosity(input?.textVerbosity) ? input.textVerbosity : undefined,
+    serviceTier: isServiceTier(input?.serviceTier) ? input.serviceTier : undefined,
   }
 }
 

packages/ai/src/protocols/utils/openai-options.ts

@@ -1,9 +1,8 @@
+import { ReasoningEfforts } from "../../schema/index.js"
 import { OpenResponsesOptions } from "./open-responses-options.js"
 
-export const OpenAIReasoningEfforts = OpenResponsesOptions.ReasoningEfforts
-export type OpenAIReasoningEffort = OpenResponsesOptions.ReasoningEffort
-export const OpenAITextVerbosities = OpenResponsesOptions.TextVerbosities
-export type OpenAITextVerbosity = OpenResponsesOptions.TextVerbosity
+export const OpenAIReasoningEfforts = ReasoningEfforts
+export type OpenAIReasoningEffort = string
 
 // Mirrors OpenAI's `ResponseIncludable` union from the official SDK. Keep this
 // in lockstep with `openai-node/src/resources/responses/responses.ts`.
@@ -13,7 +12,7 @@ export const OpenAIServiceTiers = OpenResponsesOptions.ServiceTiers
 export type OpenAIServiceTier = OpenResponsesOptions.ServiceTier
 
 export const OpenAIReasoningEffort = OpenResponsesOptions.ReasoningEffort
-export const OpenAITextVerbosity = OpenResponsesOptions.TextVerbosity
+export const OpenAITextVerbosity = OpenResponsesOptions.TextVerbositySchema
 export const OpenAIResponseIncludable = OpenResponsesOptions.ResponseIncludableSchema
 export const OpenAIServiceTier = OpenResponsesOptions.ServiceTierSchema
 

packages/ai/src/provider-error.ts

@@ -57,7 +57,7 @@ export const isContextOverflowFailure = (failure: unknown) =>
     ? failure.reason._tag === "InvalidRequest" && failure.reason.classification === "context-overflow"
     : Schema.is(ProviderErrorEvent)(failure) && failure.classification === "context-overflow"
 
-const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown))
+const decodeJson = Schema.decodeUnknownOption(Schema.UnknownFromJsonString)
 const QUOTA_CODES = new Set(["insufficient_quota", "usage_not_included", "billing_error"])
 const SERVER_CODES = new Set([
   "api_error",

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

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

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

@@ -1,19 +1,14 @@
-import { Effect } from "effect"
 import type { ProviderPackage } from "../provider-package.js"
 import { Gemini } from "../protocols/gemini.js"
-import { ProviderShared } from "../protocols/shared.js"
 import { Auth } from "../route/auth.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
-import { ProviderID, type LLMRequest, type ModelID } from "../schema/index.js"
+import { ProviderID, type ModelID } from "../schema/index.js"
 import { GoogleVertexShared } from "./google-vertex-shared.js"
 
-export interface GeminiOptionsInput extends Gemini.OptionsInput {
-  readonly labels?: Readonly<Record<string, string>>
-}
-
-export type GeminiProviderOptionsInput = GeminiOptionsInput
+export type GeminiOptionsInput = Gemini.OptionsInput
+export type GeminiProviderOptionsInput = Gemini.ProviderOptionsInput
 
 export const id = ProviderID.make("google-vertex")
 
@@ -22,7 +17,7 @@ export type Config = RouteDefaultsInput &
     readonly baseURL?: string
     readonly location?: string
     readonly project?: string
-    readonly providerOptions?: GeminiProviderOptionsInput
+    readonly providerOptions?: Gemini.ProviderOptionsInput
   }
 
 export type Settings = ProviderPackage.Settings &
@@ -33,33 +28,14 @@ export type Settings = ProviderPackage.Settings &
     readonly baseURL?: string
     readonly location?: string
     readonly project?: string
-    readonly providerOptions?: GeminiProviderOptionsInput
+    readonly providerOptions?: Gemini.ProviderOptionsInput
   }
 
-const fromRequest = Effect.fn("GoogleVertex.fromRequest")(function* (request: LLMRequest) {
-  const body = yield* Gemini.protocol.body.from(request)
-  const value = request.providerOptions?.labels
-  const labels = ProviderShared.isRecord(value)
-    ? Object.fromEntries(
-        Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
-      )
-    : undefined
-  return { ...body, labels }
-})
-
-const protocol = {
-  ...Gemini.protocol,
-  body: {
-    ...Gemini.protocol.body,
-    from: fromRequest,
-  },
-}
-
 const route = Route.make({
   id: "google-vertex-gemini",
   provider: id,
   providerMetadataKey: "google",
-  protocol,
+  protocol: Gemini.protocol,
   endpoint: Endpoint.path(({ request }) => {
     const model = String(request.model.id)
     return `/${model.startsWith("endpoints/") ? model : `models/${model}`}:streamGenerateContent?alt=sse`
@@ -102,7 +78,7 @@ export const configure = (input: Config = {}) => {
   return {
     id,
     model: (modelID: string | ModelID) =>
-      configuredRoute(input, modelID).model<GeminiProviderOptionsInput>({ id: modelID }),
+      configuredRoute(input, modelID).model<Gemini.ProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
@@ -111,7 +87,10 @@ export const provider = {
   id,
   configure,
 }
-export const model: ProviderPackage.Definition<Settings, GeminiProviderOptionsInput>["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/open-responses-options.ts

@@ -1,6 +1,19 @@
-import type { Options } from "../protocols/utils/open-responses-options.js"
+import type { ResponseIncludable, ServiceTier } from "../protocols/utils/open-responses-options.js"
+import type { ProviderOptions, ReasoningEffort, TextVerbosity } from "../schema/index.js"
 
-export type OpenResponsesOptionsInput = Options & { readonly [key: string]: unknown }
-export type OpenResponsesProviderOptionsInput = OpenResponsesOptionsInput
+export interface OpenResponsesOptionsInput {
+  readonly [key: string]: unknown
+  readonly instructions?: string
+  readonly store?: boolean
+  readonly reasoningEffort?: ReasoningEffort
+  readonly reasoningSummary?: "auto" | "concise" | "detailed"
+  readonly include?: ReadonlyArray<ResponseIncludable>
+  readonly textVerbosity?: TextVerbosity
+  readonly serviceTier?: ServiceTier
+}
+
+export type OpenResponsesProviderOptionsInput = ProviderOptions & {
+  readonly openresponses?: OpenResponsesOptionsInput
+}
 
 export * as OpenResponsesProviderOptions from "./open-responses-options.js"

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

@@ -19,7 +19,6 @@ export interface Settings extends ProviderPackage.Settings {
   readonly apiKey?: string
   readonly baseURL: string
   readonly provider?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
 }
 
 export type FamilyModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
@@ -76,7 +75,6 @@ export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsIn
     http: settings.body === undefined ? undefined : { body: { ...settings.body } },
     limits: settings.limits,
     provider: settings.provider,
-    providerOptions: settings.providerOptions,
   }).model(modelID)
 
 export const baseten = define(profiles.baseten)

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

@@ -1,17 +1,20 @@
-import { mergeProviderOptions, type ProviderOptions } from "../schema/index.js"
+import type { ProviderOptions } from "../schema/index.js"
+import { mergeProviderOptions } from "../schema/index.js"
 import type { OpenResponsesOptionsInput } from "./open-responses-options.js"
 
 export type { OpenAIResponseIncludable, OpenAIServiceTier } from "../protocols/utils/openai-options.js"
 
 export type OpenAIOptionsInput = OpenResponsesOptionsInput
 
-export type OpenAIProviderOptionsInput = OpenAIOptionsInput
+export type OpenAIProviderOptionsInput = ProviderOptions & {
+  readonly openai?: OpenAIOptionsInput
+}
 
 const definedEntries = (input: Record<string, unknown>) =>
   Object.entries(input).filter((entry) => entry[1] !== undefined)
 
 const openAIProviderOptions = (options: OpenAIOptionsInput | undefined): ProviderOptions | undefined => {
-  const result = Object.fromEntries(
+  const openai = Object.fromEntries(
     definedEntries({
       store: options?.store,
       reasoningEffort: options?.reasoningEffort,
@@ -21,8 +24,8 @@ const openAIProviderOptions = (options: OpenAIOptionsInput | undefined): Provide
       serviceTier: options?.serviceTier,
     }),
   )
-  if (Object.keys(result).length === 0) return undefined
-  return result
+  if (Object.keys(openai).length === 0) return undefined
+  return { openai }
 }
 
 export const gpt5DefaultOptions = (

packages/ai/src/providers/openrouter.ts

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

packages/ai/src/providers/xai.ts

@@ -1,7 +1,7 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { HttpOptions, ProviderID, type ModelID, type ProviderOptions } from "../schema/index.js"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile.js"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
@@ -12,7 +12,9 @@ import type { ProviderPackage } from "../provider-package.js"
 
 export const id = ProviderID.make("xai")
 
-export type XAIProviderOptionsInput = OpenAIOptionsInput
+export type XAIProviderOptionsInput = ProviderOptions & {
+  readonly xai?: OpenAIOptionsInput
+}
 
 export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
@@ -35,7 +37,7 @@ const responsesRoute = Route.make({
   protocol: OpenAIResponses.protocol,
   endpoint: Endpoint.path("/responses", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
   transport: OpenAIResponses.httpTransport,
-  defaults: { providerOptions: { store: false } },
+  defaults: { providerOptions: { xai: { store: false } } },
 })
 
 const chatRoute = Route.make({

packages/ai/src/route/framing.ts

@@ -13,8 +13,8 @@ import type { AIError } from "../schema/index.js"
  * - AWS event stream — length-prefixed binary frames with CRC checksums.
  *   Each emitted frame is one parsed binary event record.
  *
- * The frame type is opaque to this layer; the protocol's event schema decodes
- * each frame before its state machine handles it.
+ * The frame type is opaque to this layer; the protocol's `decode` step turns
+ * a frame into a typed chunk.
  */
 export interface Definition<Frame> {
   readonly id: string

packages/ai/src/route/protocol.ts

@@ -73,7 +73,8 @@ export interface ProtocolStream<Frame, Event, State> {
  *
  * Provider implementations should usually call `Protocol.make({ ... })`
  * without explicit type arguments; the schemas and parser functions are the
- * source of truth.
+ * source of truth. The constructor remains as the public seam for future
+ * cross-cutting concerns such as tracing or instrumentation.
  */
 export const make = <Body, Frame, Event, State>(
   input: Protocol<Body, Frame, Event, State>,

packages/ai/src/schema/errors.ts

@@ -1,7 +1,6 @@
 import { Schema } from "effect"
 import { Tool } from "@opencode-ai/schema/tool"
-import { ModelID, ProviderID, RouteID } from "./ids.js"
-import { ProviderMetadata } from "./messages.js"
+import { ModelID, ProviderID, ProviderMetadata, RouteID } from "./ids.js"
 
 export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"])
 export type ProviderFailureClassification = typeof ProviderFailureClassification.Type
@@ -149,7 +148,7 @@ export const AIErrorReason = Schema.Union([
 ]).pipe(Schema.toTaggedUnion("_tag"))
 export type AIErrorReason = Schema.Schema.Type<typeof AIErrorReason>
 
-export class AIError extends Schema.TaggedError<AIError>()("AI.Error", {
+export class AIError extends Schema.TaggedErrorClass<AIError>()("AI.Error", {
   module: Schema.String,
   method: Schema.String,
   reason: AIErrorReason,

packages/ai/src/schema/events.ts

@@ -1,21 +1,8 @@
 import { Schema } from "effect"
-import { LLM } from "@opencode-ai/schema/llm"
-import { ContentBlockID, ToolCallID } from "./ids.js"
-import {
-  Message,
-  ProviderMetadata,
-  ToolCallPart,
-  ToolOutput,
-  ToolResultPart,
-  ToolResultValue,
-  type ContentPart,
-} from "./messages.js"
+import { ContentBlockID, FinishReason, ProviderMetadata, ToolCallID } from "./ids.js"
+import { Message, ToolCallPart, ToolOutput, ToolResultPart, ToolResultValue, type ContentPart } from "./messages.js"
 import { ProviderFailureClassification } from "./errors.js"
 
-export const FinishReason = LLM.FinishReason
-export type FinishReason = Schema.Schema.Type<typeof FinishReason>
-export { ProviderMetadata } from "./messages.js"
-
 /**
  * Token usage reported by an LLM provider.
  *

packages/ai/src/schema/ids.ts

@@ -1,4 +1,8 @@
 import { Schema } from "effect"
+import { ProviderMetadata } from "@opencode-ai/schema/ai"
+import { LLM } from "@opencode-ai/schema/llm"
+
+export { ProviderMetadata }
 
 /** Stable string identifier for a protocol implementation. */
 export const ProtocolID = Schema.String
@@ -22,3 +26,19 @@ export type ContentBlockID = Schema.Schema.Type<typeof ContentBlockID>
 
 export const ToolCallID = Schema.String
 export type ToolCallID = Schema.Schema.Type<typeof ToolCallID>
+
+export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
+export const ReasoningEffort = Schema.String
+export type ReasoningEffort = Schema.Schema.Type<typeof ReasoningEffort>
+
+export const TextVerbosity = Schema.Literals(["low", "medium", "high"])
+export type TextVerbosity = Schema.Schema.Type<typeof TextVerbosity>
+
+export const MessageRole = Schema.Literals(["system", "user", "assistant", "tool"])
+export type MessageRole = Schema.Schema.Type<typeof MessageRole>
+
+export const FinishReason = LLM.FinishReason
+export type FinishReason = Schema.Schema.Type<typeof FinishReason>
+
+export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
+export type JsonSchema = Schema.Schema.Type<typeof JsonSchema>

packages/ai/src/schema/messages.ts

@@ -1,24 +1,16 @@
 import { Schema } from "effect"
 import { Tool } from "@opencode-ai/schema/tool"
+import { JsonSchema, MessageRole, ProviderMetadata } from "./ids.js"
 import {
   CacheHint,
   CachePolicy,
   GenerationOptions,
   HttpOptions,
-  JsonSchema,
   LanguageModelSchema,
   ProviderOptions,
 } from "./options.js"
 import { isRecord } from "../utils/record.js"
 
-export const MessageRole = Schema.Literals(["system", "user", "assistant", "tool"])
-export type MessageRole = Schema.Schema.Type<typeof MessageRole>
-
-export const ProviderMetadata = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown)).annotate({
-  identifier: "LLM.ProviderMetadata",
-})
-export type ProviderMetadata = Schema.Schema.Type<typeof ProviderMetadata>
-
 const systemPartSchema = Schema.Struct({
   type: Schema.Literal("text"),
   text: Schema.String,

packages/ai/src/schema/options.ts

@@ -1,11 +1,8 @@
 import { Schema } from "effect"
-import { ModelID, ProviderID } from "./ids.js"
+import { JsonSchema, ModelID, ProviderID } from "./ids.js"
 import type { AnyRoute } from "../route/client.js"
 import { isRecord } from "../utils/record.js"
 
-export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
-export type JsonSchema = Schema.Schema.Type<typeof JsonSchema>
-
 export const mergeJsonRecords = (
   ...items: ReadonlyArray<Record<string, unknown> | undefined>
 ): Record<string, unknown> | undefined => {
@@ -36,12 +33,22 @@ const mergeStringRecords = (
   return Object.keys(result).length === 0 ? undefined : result
 }
 
-export const ProviderOptions = Schema.Record(Schema.String, Schema.Unknown)
+export const ProviderOptions = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown))
 export type ProviderOptions = Schema.Schema.Type<typeof ProviderOptions>
 
 export const mergeProviderOptions = (
   ...items: ReadonlyArray<ProviderOptions | undefined>
-): ProviderOptions | undefined => mergeJsonRecords(...items)
+): ProviderOptions | undefined => {
+  const result: Record<string, Record<string, unknown>> = {}
+  for (const item of items) {
+    if (!item) continue
+    for (const [provider, options] of Object.entries(item)) {
+      const merged = mergeJsonRecords(result[provider], options)
+      if (merged) result[provider] = merged
+    }
+  }
+  return Object.keys(result).length === 0 ? undefined : result
+}
 
 export class HttpOptions extends Schema.Class<HttpOptions>("AI.HttpOptions")({
   body: Schema.optional(JsonSchema),
@@ -262,9 +269,10 @@ export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({
 // Auto-placement policy for prompt caching. The protocol-neutral lowering step
 // reads this and injects `CacheHint`s at the configured boundaries; the
 // per-protocol body builders then translate those hints into wire markers as
-// usual. `"auto"` is the default for agent loops — it places
+// usual. `"auto"` is the recommended default for agent loops — it places
 // breakpoints at the last tool definition, the first and last distinct system
-// parts, and the conversation tail so recent prefixes remain reusable during
+// parts, and the conversation tail. The rolling message breakpoint keeps a
+// prior cache entry within Anthropic/Bedrock's 20-block lookback during long
 // tool loops.
 //
 // Pass `"none"` to opt out entirely (the legacy behavior). Pass the granular

packages/ai/src/testing.ts

@@ -7,7 +7,6 @@ import {
   type FinishReasonDetails,
   type AIError,
   type LLMRequest,
-  type ProviderMetadata,
   type UsageInput,
 } from "./schema/index.js"
 import { Context, Deferred, Effect, Latch, Layer, Queue, Scope, Stream } from "effect"
@@ -34,22 +33,13 @@ export interface LayerOptions {
 export class Service extends Context.Service<Service, Interface>()("@opencode/ai/TestLLM") {}
 
 export const complete = (
-  options: {
-    readonly reason: FinishReasonDetails
-    readonly usage?: UsageInput
-    readonly providerMetadata?: ProviderMetadata
-  },
+  options: { readonly reason: FinishReasonDetails; readonly usage?: UsageInput },
   ...events: readonly LLMEvent[]
 ) => [
   LLMEvent.stepStart({ index: 0 }),
   ...events,
-  LLMEvent.stepFinish({
-    index: 0,
-    reason: options.reason,
-    usage: options.usage,
-    providerMetadata: options.providerMetadata,
-  }),
-  LLMEvent.finish({ reason: options.reason, providerMetadata: options.providerMetadata }),
+  LLMEvent.stepFinish({ index: 0, reason: options.reason, usage: options.usage }),
+  LLMEvent.finish({ reason: options.reason }),
 ]
 
 export const stop = (...events: readonly LLMEvent[]) => complete({ reason: { normalized: "stop" } }, ...events)

packages/ai/test/auth-options.types.ts

@@ -81,7 +81,7 @@ OpenAI.configure({
 }).responses("gpt-4.1-mini")
 OpenAI.configure({
   generation: { maxTokens: 100 },
-  providerOptions: { store: false },
+  providerOptions: { openai: { store: false } },
 }).responses("gpt-4.1-mini")
 
 // @ts-expect-error OpenAI model selectors only accept model ids.
@@ -97,7 +97,7 @@ OpenAI.configure({ bogus: true })
 OpenAI.configure({ generation: { maxTokens: "many" } })
 
 // @ts-expect-error provider-native options remain typed.
-OpenAI.configure({ providerOptions: { store: "false" } })
+OpenAI.configure({ providerOptions: { openai: { store: "false" } } })
 
 // @ts-expect-error auth is an override, so OpenAI rejects apiKey with auth.
 OpenAI.configure({ apiKey: "sk-test", auth: Auth.bearer("oauth-token") })
@@ -139,8 +139,7 @@ Anthropic.configure({ apiKey: "anthropic-key" }).model("claude-haiku")
 Anthropic.configure({
   apiKey: "anthropic-key",
   providerOptions: {
-    thinking: { type: "enabled", budgetTokens: 1_024 },
-    effort: "high",
+    anthropic: { thinking: { type: "enabled", budgetTokens: 1_024 }, effort: "high" },
   },
 }).model("claude-haiku")
 // @ts-expect-error Anthropic model selectors only accept model ids.
@@ -148,15 +147,15 @@ Anthropic.configure({ apiKey: "anthropic-key" }).model("claude-haiku", {})
 // @ts-expect-error Anthropic package settings accept only one auth source.
 Anthropic.model("claude-sonnet-4-6", { apiKey: "anthropic-key", authToken: "anthropic-token" })
 // @ts-expect-error Enabled Anthropic thinking requires a token budget.
-Anthropic.configure({ providerOptions: { thinking: { type: "enabled" } } })
+Anthropic.configure({ providerOptions: { anthropic: { thinking: { type: "enabled" } } } })
 // @ts-expect-error Anthropic thinking budgets must be numbers.
-Anthropic.configure({ providerOptions: { thinking: { type: "enabled", budgetTokens: "large" } } })
+Anthropic.configure({ providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: "large" } } } })
 
 AnthropicCompatible.configure({
   apiKey: "messages-key",
   baseURL: "https://messages.example.com/v1",
   provider: "example",
-  providerOptions: { thinking: { type: "disabled" } },
+  providerOptions: { anthropic: { thinking: { type: "disabled" } } },
 }).model("compatible-model")
 // @ts-expect-error Anthropic-compatible providers require a base URL.
 AnthropicCompatible.configure({ apiKey: "messages-key" })
@@ -172,16 +171,16 @@ AnthropicCompatible.model("compatible-model", {
 Google.configure({ apiKey: "google-key" }).model("gemini-2.5-flash")
 Google.configure({
   apiKey: "google-key",
-  providerOptions: { thinkingConfig: { thinkingBudget: 0, includeThoughts: false } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 0, includeThoughts: false } } },
 }).model("gemini-2.5-flash")
 // @ts-expect-error Google model selectors only accept model ids.
 Google.configure({ apiKey: "google-key" }).model("gemini-2.5-flash", {})
 // @ts-expect-error Gemini thinking budgets must be numbers.
-Google.configure({ providerOptions: { thinkingConfig: { thinkingBudget: "large" } } })
+Google.configure({ providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "large" } } } })
 
 GoogleVertex.configure({
   apiKey: "vertex-key",
-  providerOptions: { thinkingConfig: { thinkingBudget: 1_024 } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1_024 } } },
 }).model("gemini-3.5-flash")
 GoogleVertex.configure({ accessToken: "vertex-token", project: "project" }).model("gemini-3.5-flash")
 GoogleVertex.configure({ auth: Auth.bearer("vertex-token"), project: "project" }).model("gemini-3.5-flash")
@@ -231,7 +230,7 @@ GoogleVertexResponses.configure({
 GoogleVertexMessages.configure({
   accessToken: "vertex-token",
   project: "project",
-  providerOptions: { thinking: { type: "adaptive", display: "omitted" }, effort: "low" },
+  providerOptions: { anthropic: { thinking: { type: "adaptive", display: "omitted" }, effort: "low" } },
 }).model("claude-sonnet-4-6")
 // @ts-expect-error Vertex Messages package settings do not accept API keys.
 GoogleVertexMessages.model("claude-sonnet-4-6", { apiKey: "vertex-key", project: "project" })

packages/ai/test/compile.test.ts

@@ -17,25 +17,31 @@ describe("request option precedence", () => {
   test("deep-merges provider option records and replaces arrays, primitives, and null", () => {
     const merged = mergeProviderOptions(
       {
-        include: ["route"],
-        metadata: { route: true, shared: "route" },
-        nullable: "route",
-        primitive: "route",
+        openai: {
+          include: ["route"],
+          metadata: { route: true, shared: "route" },
+          nullable: "route",
+          primitive: "route",
+        },
       },
       {
-        include: ["model"],
-        metadata: { model: true, shared: "model" },
-        nullable: null,
-        primitive: "model",
+        openai: {
+          include: ["model"],
+          metadata: { model: true, shared: "model" },
+          nullable: null,
+          primitive: "model",
+        },
       },
-      { metadata: { request: true }, primitive: false },
+      { openai: { metadata: { request: true }, primitive: false } },
     )
 
     expect(merged).toEqual({
-      include: ["model"],
-      metadata: { route: true, model: true, request: true, shared: "model" },
-      nullable: null,
-      primitive: false,
+      openai: {
+        include: ["model"],
+        metadata: { route: true, model: true, request: true, shared: "model" },
+        nullable: null,
+        primitive: false,
+      },
     })
   })
 
@@ -45,13 +51,13 @@ describe("request option precedence", () => {
         endpoint: { baseURL: "https://api.openai.test/v1/" },
         auth: Auth.bearer("test"),
         generation: { maxTokens: 10, temperature: 1, stop: ["route"] },
-        providerOptions: { store: false, reasoningEffort: "low" },
+        providerOptions: { openai: { store: false, reasoningEffort: "low" } },
       })
       const model = route.model({
         id: "gpt-4o-mini",
         defaults: {
           generation: { maxTokens: 20, temperature: 0.5, frequencyPenalty: 0.25, stop: ["model"] },
-          providerOptions: { reasoningEffort: "medium" },
+          providerOptions: { openai: { reasoningEffort: "medium" } },
         },
       })
       const prepared = yield* compileRequest(
@@ -59,7 +65,7 @@ describe("request option precedence", () => {
           model,
           prompt: "Say hello.",
           generation: { maxTokens: 30, topP: 0.9, stop: ["request"] },
-          providerOptions: { store: true },
+          providerOptions: { openai: { store: true } },
         }),
       )
 

packages/ai/test/continuation-scenarios.ts

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

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

@@ -13,7 +13,9 @@ interface ExampleOptions {
   readonly mode?: "fast" | "thorough"
 }
 
-type ExampleProviderOptions = ProviderOptions & ExampleOptions
+type ExampleProviderOptions = ProviderOptions & {
+  readonly example?: ExampleOptions
+}
 
 const model = OpenAIChat.route
   .with({ endpoint: { baseURL: "https://example.com/v1" } })
@@ -24,7 +26,7 @@ type StreamRequirements<T> = T extends Stream.Stream<infer _A, infer _E, infer R
 type Equal<A, B> = [A, B] extends [B, A] ? true : false
 type Assert<T extends true> = T
 
-LLM.request({ model, prompt: "Hello", providerOptions: { mode: "fast" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { example: { mode: "fast" } } })
 LLM.request({ model, prompt: "Hello", providerOptions: { future: { option: true } } })
 
 const generated = LLM.generate(LLM.request({ model, prompt: "Hello" }))
@@ -36,14 +38,14 @@ LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Known provider options preserve their value types.
-  providerOptions: { mode: "slow" },
+  providerOptions: { example: { mode: "slow" } },
 })
 
 const generatedObject = LLM.generateObject({
   model,
   prompt: "Hello",
   schema: Schema.Struct({ answer: Schema.String }),
-  providerOptions: { mode: "thorough" },
+  providerOptions: { example: { mode: "thorough" } },
 })
 type GenerateObjectRequirements = Assert<Equal<Requirements<typeof generatedObject>, LLMClientService>>
 
@@ -59,13 +61,13 @@ LLM.generateObject({
   prompt: "Hello",
   jsonSchema: { type: "object" },
   // @ts-expect-error Dynamic object generation uses the selected model's provider options.
-  providerOptions: { mode: false },
+  providerOptions: { example: { mode: false } },
 })
 
 declare const generic: LanguageModel
 LLM.request({ model: generic, prompt: "Hello", providerOptions: { arbitrary: { option: true } } })
 
-const options: LanguageModelProviderOptions<typeof model> = { mode: "fast" }
+const options: LanguageModelProviderOptions<typeof model> = { example: { mode: "fast" } }
 void (options satisfies LanguageModelProviderOptions<typeof model>)
 void (true satisfies GenerateRequirements)
 void (true satisfies StreamClientRequirements)

packages/ai/test/llm.test.ts

@@ -59,18 +59,18 @@ describe("llm constructors", () => {
         provider: "fake",
         route: chatRoute.with({
           generation: { maxTokens: 100, temperature: 1 },
-          providerOptions: { store: false, metadata: { model: true } },
+          providerOptions: { openai: { store: false, metadata: { model: true } } },
           http: { body: { metadata: { model: true } }, headers: { "x-shared": "model" }, query: { model: "1" } },
         }),
       }),
       prompt: "Say hello.",
       generation: { temperature: 0 },
-      providerOptions: { store: true, metadata: { request: true } },
+      providerOptions: { openai: { store: true, metadata: { request: true } } },
       http: { body: { metadata: { request: true } }, headers: { "x-shared": "request" }, query: { request: "1" } },
     })
 
     expect(request.generation).toEqual({ temperature: 0 })
-    expect(request.providerOptions).toEqual({ store: true, metadata: { request: true } })
+    expect(request.providerOptions).toEqual({ openai: { store: true, metadata: { request: true } } })
     expect(request.http).toEqual({
       body: { metadata: { request: true } },
       headers: { "x-shared": "request" },
@@ -123,7 +123,7 @@ describe("llm constructors", () => {
       defaults: {
         limits: { context: 128_000, output: 8_192 },
         generation: { maxTokens: 1_024, stop: ["END"] },
-        providerOptions: { parallelToolCalls: false },
+        providerOptions: { openai: { parallelToolCalls: false } },
         http: { body: { extra_body: true } },
       },
       compatibility: { toolSchema: "moonshot" },
@@ -132,7 +132,7 @@ describe("llm constructors", () => {
 
     expect(request.model.defaults?.limits).toEqual({ context: 128_000, output: 8_192 })
     expect(request.model.defaults?.generation).toEqual({ maxTokens: 1_024, stop: ["END"] })
-    expect(request.model.defaults?.providerOptions).toEqual({ parallelToolCalls: false })
+    expect(request.model.defaults?.providerOptions).toEqual({ openai: { parallelToolCalls: false } })
     expect(request.model.defaults?.http).toEqual({ body: { extra_body: true } })
     expect(request.model.compatibility).toEqual({ toolSchema: "moonshot" })
     expect(request.generation).toBeUndefined()

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

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

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

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

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

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

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

@@ -3,11 +3,11 @@ import { GoogleVertexChat } from "../../src/providers.js"
 
 const model = GoogleVertexChat.configure({ accessToken: "test", project: "project" }).model("gemini")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { serviceTier: "priority" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openai: { serviceTier: "priority" } } })
 
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Vertex OpenAI-compatible service tiers use the OpenAI union.
-  providerOptions: { serviceTier: "premium" },
+  providerOptions: { openai: { serviceTier: "premium" } },
 })

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

@@ -3,11 +3,11 @@ import { GoogleVertexMessages } from "../../src/providers.js"
 
 const model = GoogleVertexMessages.configure({ accessToken: "test", project: "project" }).model("claude")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { effort: "medium" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { anthropic: { effort: "medium" } } })
 
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Vertex Anthropic effort must be a string.
-  providerOptions: { effort: false },
+  providerOptions: { anthropic: { effort: false } },
 })

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

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

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

@@ -6,12 +6,12 @@ const model = GoogleVertex.provider.configure({ apiKey: "test" }).model("gemini-
 LLM.request({
   model,
   prompt: "Hello",
-  providerOptions: { thinkingConfig: { includeThoughts: true } },
+  providerOptions: { gemini: { thinkingConfig: { includeThoughts: true } } },
 })
 
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Vertex Gemini includeThoughts must be boolean.
-  providerOptions: { thinkingConfig: { includeThoughts: "yes" } },
+  providerOptions: { gemini: { thinkingConfig: { includeThoughts: "yes" } } },
 })

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

@@ -6,15 +6,17 @@ const model = Google.provider.model("gemini-2.5-pro")
 LLM.request({
   model,
   prompt: "Hello",
-  providerOptions: { thinkingConfig: { thinkingBudget: 1024 } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1024 } } },
 })
 
 LLM.request({
   model,
   prompt: "Hello",
   providerOptions: {
-    // @ts-expect-error Gemini safety settings require a threshold for every category.
-    safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH" }],
+    gemini: {
+      // @ts-expect-error Gemini safety settings require a threshold for every category.
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH" }],
+    },
   },
 })
 
@@ -22,10 +24,12 @@ LLM.request({
   model,
   prompt: "Hello",
   providerOptions: {
-    cachedContent: "cachedContents/example",
-    safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
-    serviceTier: "future-tier",
-    thinkingConfig: { thinkingLevel: "high", includeThoughts: true },
+    gemini: {
+      cachedContent: "cachedContents/example",
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+      serviceTier: "future-tier",
+      thinkingConfig: { thinkingLevel: "high", includeThoughts: true },
+    },
   },
 })
 
@@ -33,11 +37,11 @@ LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Gemini thinking budgets must be numeric.
-  providerOptions: { thinkingConfig: { thinkingBudget: "large" } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "large" } } },
 })
 
 LLM.request({
   model,
   prompt: "Hello",
-  providerOptions: { thinkingConfig: { thinkingLevel: "maximum" } },
+  providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "maximum" } } },
 })

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

@@ -3,15 +3,11 @@ import { OpenAICompatibleResponses } from "../../src/providers.js"
 
 const model = OpenAICompatibleResponses.configure({ baseURL: "https://example.com" }).model("model")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningSummary: "detailed" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "high" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { textVerbosity: "low" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { textVerbosity: "verbose" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openresponses: { reasoningSummary: "detailed" } } })
 
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Open Responses reasoning summaries use a fixed union.
-  providerOptions: { reasoningSummary: "full" },
+  providerOptions: { openresponses: { reasoningSummary: "full" } },
 })

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

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

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

@@ -2,20 +2,14 @@ import { LLM } from "../../src/index.js"
 import { OpenAI } from "../../src/providers.js"
 
 const selected = OpenAI.responses("gpt-5")
-const chat = OpenAI.chat("gpt-4o-mini")
 
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { reasoningEffort: "high" } })
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { textVerbosity: "low" } })
-LLM.request({ model: selected, prompt: "Hello", providerOptions: { textVerbosity: "verbose" } })
-LLM.request({ model: chat, prompt: "Hello", providerOptions: { reasoningEffort: "max" } })
-LLM.request({ model: chat, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
+LLM.request({ model: selected, prompt: "Hello", providerOptions: { openai: { reasoningEffort: "high" } } })
 
 LLM.request({
   model: selected,
   prompt: "Hello",
   // @ts-expect-error OpenAI reasoning effort must be a string.
-  providerOptions: { reasoningEffort: 1 },
+  providerOptions: { openai: { reasoningEffort: 1 } },
 })
 
 OpenAI.configure({

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

@@ -3,25 +3,27 @@ import { OpenRouter } from "../../src/providers.js"
 
 const model = OpenRouter.provider.model("anthropic/claude-sonnet-4.5")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { usage: true } })
+LLM.request({ model, prompt: "Hello", providerOptions: { openrouter: { usage: true } } })
 
 LLM.request({
   model,
   prompt: "Hello",
   providerOptions: {
-    models: ["google/gemini-3.1-pro"],
-    provider: {
-      order: ["anthropic"],
-      require_parameters: true,
-      data_collection: "future-policy",
-      sort: "future-sort",
-      max_price: { prompt: "0.50" },
+    openrouter: {
+      models: ["google/gemini-3.1-pro"],
+      provider: {
+        order: ["anthropic"],
+        require_parameters: true,
+        data_collection: "future-policy",
+        sort: "future-sort",
+        max_price: { prompt: "0.50" },
+      },
+      reasoning: { effort: "future-effort", exclude: false },
+      plugins: [{ id: "future-plugin", enabled: true }],
+      web_search_options: { engine: "future-engine" },
+      debug: { echo_upstream_body: true },
+      user: "user_123",
     },
-    reasoning: { effort: "future-effort", exclude: false },
-    plugins: [{ id: "future-plugin", enabled: true }],
-    web_search_options: { engine: "future-engine" },
-    debug: { echo_upstream_body: true },
-    user: "user_123",
   },
 })
 
@@ -29,5 +31,5 @@ LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error OpenRouter usage must be boolean or an option record.
-  providerOptions: { usage: "yes" },
+  providerOptions: { openrouter: { usage: "yes" } },
 })

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

@@ -3,12 +3,11 @@ import { XAI } from "../../src/providers.js"
 
 const model = XAI.provider.model("grok-4")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "high" } })
-LLM.request({ model, prompt: "Hello", providerOptions: { reasoningEffort: "experimental" } })
+LLM.request({ model, prompt: "Hello", providerOptions: { xai: { reasoningEffort: "high" } } })
 
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error xAI's OpenAI-compatible reasoning effort must be a string.
-  providerOptions: { reasoningEffort: true },
+  providerOptions: { xai: { reasoningEffort: true } },
 })

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

@@ -47,11 +47,11 @@ describe("provider package entrypoints", () => {
     }
     const openrouter = OpenRouter.model("anthropic/claude-sonnet-4", {
       ...settings,
-      providerOptions: { usage: true },
+      providerOptions: { openrouter: { usage: true } },
     })
     const xai = XAI.model("grok-4", {
       ...settings,
-      providerOptions: { reasoningEffort: "high" },
+      providerOptions: { xai: { reasoningEffort: "high" } },
     })
 
     for (const selected of [openrouter, xai]) {
@@ -60,8 +60,8 @@ describe("provider package entrypoints", () => {
       expect(selected.route.defaults.http?.body).toEqual(settings.body)
       expect(selected.route.defaults.limits).toEqual(settings.limits)
     }
-    expect(openrouter.route.defaults.providerOptions).toEqual({ usage: true })
-    expect(xai.route.defaults.providerOptions).toMatchObject({ reasoningEffort: "high", store: false })
+    expect(openrouter.route.defaults.providerOptions).toEqual({ openrouter: { usage: true } })
+    expect(xai.route.defaults.providerOptions).toMatchObject({ xai: { reasoningEffort: "high", store: false } })
   })
 
   test("maps package settings onto the executable model", () => {
@@ -89,7 +89,7 @@ describe("provider package entrypoints", () => {
       headers: { "x-application": "opencode" },
       body: { service_tier: "priority" },
       limits: { context: 200_000, output: 64_000 },
-      providerOptions: { reasoningEffort: "low", store: true },
+      providerOptions: { openresponses: { reasoningEffort: "low", store: true } },
     })
 
     expect(String(selected.provider)).toBe("example")
@@ -101,7 +101,9 @@ describe("provider package entrypoints", () => {
     expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
     expect(selected.route.defaults.http?.body).toEqual({ service_tier: "priority" })
     expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
-    expect(selected.route.defaults.providerOptions).toEqual({ reasoningEffort: "low", store: true })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      openresponses: { reasoningEffort: "low", store: true },
+    })
   })
 
   test("maps Anthropic-compatible settings onto the executable model", async () => {
@@ -113,7 +115,7 @@ describe("provider package entrypoints", () => {
       headers: { "x-application": "opencode" },
       body: { metadata: { user_id: "user_1" } },
       limits: { context: 200_000, output: 64_000 },
-      providerOptions: { effort: "low" },
+      providerOptions: { anthropic: { effort: "low" } },
     })
 
     expect(String(selected.provider)).toBe("example")
@@ -125,17 +127,19 @@ describe("provider package entrypoints", () => {
     expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
     expect(selected.route.defaults.http?.body).toEqual({ metadata: { user_id: "user_1" } })
     expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
-    expect(selected.route.defaults.providerOptions).toEqual({ effort: "low" })
+    expect(selected.route.defaults.providerOptions).toEqual({ anthropic: { effort: "low" } })
   })
 
   test("maps Anthropic provider options onto the executable model", async () => {
     const Anthropic = await import("@opencode-ai/ai/providers/anthropic")
     const selected = Anthropic.model("claude-sonnet-4-6", {
       apiKey: "fixture",
-      providerOptions: { thinking: { type: "adaptive" } },
+      providerOptions: { anthropic: { thinking: { type: "adaptive" } } },
     })
 
-    expect(selected.route.defaults.providerOptions).toEqual({ thinking: { type: "adaptive" } })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      anthropic: { thinking: { type: "adaptive" } },
+    })
   })
 
   test("requires an Anthropic-compatible base URL at runtime", async () => {
@@ -229,7 +233,7 @@ describe("provider package entrypoints", () => {
       headers: { "x-application": "opencode" },
       body: { safetySettings: [] },
       limits: { context: 1_000_000, output: 65_536 },
-      providerOptions: { thinkingConfig: { thinkingBudget: 1_024 } },
+      providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1_024 } } },
     })
 
     expect(selected.route.id).toBe("gemini")
@@ -237,7 +241,9 @@ describe("provider package entrypoints", () => {
     expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
     expect(selected.route.defaults.http?.body).toEqual({ safetySettings: [] })
     expect(selected.route.defaults.limits).toEqual({ context: 1_000_000, output: 65_536 })
-    expect(selected.route.defaults.providerOptions).toEqual({ thinkingConfig: { thinkingBudget: 1_024 } })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      gemini: { thinkingConfig: { thinkingBudget: 1_024 } },
+    })
   })
 
   test("selects Vertex entrypoints with the same model contract", async () => {
@@ -299,7 +305,7 @@ describe("provider package entrypoints", () => {
       baseURL: "https://aiplatform.googleapis.com/v1/projects/vertex-project/locations/global/endpoints/openapi",
       path: "/responses",
     })
-    expect(responses.route.defaults.providerOptions).toEqual({ store: false })
+    expect(responses.route.defaults.providerOptions).toEqual({ openresponses: { store: false } })
   })
 
   test("rejects conflicting Vertex auth settings at runtime", async () => {

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

@@ -63,8 +63,7 @@ describe("Anthropic Messages route", () => {
       const prepared = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: {
-            thinking: { type: "adaptive", display: "summarized" },
-            effort: "low",
+            anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "low" },
           },
         }),
       )
@@ -80,17 +79,17 @@ describe("Anthropic Messages route", () => {
     Effect.gen(function* () {
       const enabled = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "enabled", budgetTokens: 1_024 } },
+          providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: 1_024 } } },
         }),
       )
       const legacy = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "enabled", budget_tokens: 2_048 } },
+          providerOptions: { anthropic: { thinking: { type: "enabled", budget_tokens: 2_048 } } },
         }),
       )
       const disabled = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "disabled" } },
+          providerOptions: { anthropic: { thinking: { type: "disabled" } } },
         }),
       )
 
@@ -104,7 +103,7 @@ describe("Anthropic Messages route", () => {
     Effect.gen(function* () {
       const error = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { thinking: { type: "enabled" } },
+          providerOptions: { anthropic: { thinking: { type: "enabled" } } },
         }),
       ).pipe(Effect.flip)
 
@@ -137,33 +136,6 @@ describe("Anthropic Messages route", () => {
     }),
   )
 
-  it.effect("supports native chronological system updates on documented and later Claude family versions", () =>
-    Effect.gen(function* () {
-      const ids = [
-        "claude-opus-4-8",
-        "claude-opus-5-1",
-        "claude-sonnet-5",
-        "claude-haiku-5-1",
-        "claude-fable-6",
-        "anthropic/claude-mythos-7.2",
-      ]
-
-      const prepared = yield* Effect.forEach(ids, (id) =>
-        compileRequest(
-          LLM.request({
-            model: AnthropicMessages.route
-              .with({ endpoint: { baseURL: "https://api.anthropic.test/v1/" }, auth: Auth.header("x-api-key", "test") })
-              .model({ id }),
-            messages: [Message.user("Before."), Message.system("Update."), Message.assistant("After.")],
-            cache: "none",
-          }),
-        ),
-      )
-
-      expect(prepared.map((item) => item.body.messages[1]?.role)).toEqual(ids.map(() => "system"))
-    }),
-  )
-
   it.effect("lowers chronological system updates to wrapped user text for unsupported Anthropic models", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
@@ -191,34 +163,6 @@ describe("Anthropic Messages route", () => {
     }),
   )
 
-  it.effect("does not infer native system update support for older or undocumented Claude families", () =>
-    Effect.gen(function* () {
-      const ids = [
-        "claude-opus-4-7",
-        "claude-opus-4-20250514",
-        "claude-sonnet-4-9",
-        "claude-haiku-4-9",
-        "custom-model-7",
-      ]
-
-      const prepared = yield* Effect.forEach(ids, (id) =>
-        compileRequest(
-          LLM.request({
-            model: AnthropicMessages.route
-              .with({ endpoint: { baseURL: "https://api.anthropic.test/v1/" }, auth: Auth.header("x-api-key", "test") })
-              .model({ id }),
-            messages: [Message.user("Before."), Message.system("Update."), Message.assistant("After.")],
-            cache: "none",
-          }),
-        ),
-      )
-
-      expect(prepared.map((item) => item.body.messages.some((message) => message.role === "system"))).toEqual(
-        ids.map(() => false),
-      )
-    }),
-  )
-
   it.effect("rejects non-text chronological system update content before send", () =>
     Effect.gen(function* () {
       const error = yield* compileRequest(
@@ -455,7 +399,7 @@ describe("Anthropic Messages route", () => {
     }),
   )
 
-  it.effect("rejects tool-result media that cannot be lowered", () =>
+  it.effect("rejects unsupported media in tool-result content with a clear error", () =>
     Effect.gen(function* () {
       const error = yield* compileRequest(
         LLM.request({
@@ -474,7 +418,8 @@ describe("Anthropic Messages route", () => {
         }),
       ).pipe(Effect.flip)
 
-      expect(error.message).toContain("Anthropic Messages does not support media type audio/mpeg")
+      expect(error.message).toContain("Anthropic Messages")
+      expect(error.message).toContain("audio/mpeg")
     }),
   )
 
@@ -1011,63 +956,6 @@ describe("Anthropic Messages route", () => {
     }),
   )
 
-  it.effect("ignores tool input deltas without a matching tool start", () =>
-    Effect.gen(function* () {
-      const response = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              { type: "message_start", message: { usage: { input_tokens: 5 } } },
-              { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
-              { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Hello" } },
-              {
-                type: "content_block_delta",
-                index: 1,
-                delta: { type: "input_json_delta", partial_json: '{"query":"orphaned"}' },
-              },
-              { type: "content_block_stop", index: 0 },
-              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
-              { type: "message_stop" },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.text).toBe("Hello")
-      expect(response.toolCalls).toEqual([])
-      expect(response.finishReason).toEqual({ normalized: "stop", raw: "end_turn" })
-    }),
-  )
-
-  it.effect("settles pending tool calls at message_stop", () =>
-    Effect.gen(function* () {
-      const response = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              { type: "message_start", message: { usage: { input_tokens: 5 } } },
-              {
-                type: "content_block_start",
-                index: 0,
-                content_block: { type: "tool_use", id: "call_1", name: "lookup" },
-              },
-              {
-                type: "content_block_delta",
-                index: 0,
-                delta: { type: "input_json_delta", partial_json: '{"query":"weather"}' },
-              },
-              { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 1 } },
-              { type: "message_stop" },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.toolCalls).toMatchObject([{ id: "call_1", name: "lookup", input: { query: "weather" } }])
-      expect(response.finishReason).toEqual({ normalized: "tool-calls", raw: "tool_use" })
-    }),
-  )
-
   it.effect("assembles and persists multiple tool calls from one Anthropic response", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(request).pipe(

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

@@ -75,6 +75,7 @@ describe("Amazon Bedrock Mantle provider", () => {
             }),
           ),
         ),
+        Effect.flip,
       )
 
       expect(seen).toEqual([{ url: "https://mantle.test/v1/chat/completions", authorization: "Bearer test-key" }])

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

@@ -4,6 +4,7 @@ import { LLM, AIError, LLMRequest, Message, ToolCallPart, ToolDefinition, Usage
 import { Auth, LLMClient } from "../../src/route.js"
 import { compileRequest } from "../../src/route/client.js"
 import * as Gemini from "../../src/protocols/gemini.js"
+import { ProviderShared } from "../../src/protocols/shared.js"
 import { it } from "../lib/effect.js"
 import { fixedResponse } from "../lib/http.js"
 import { sseEvents, sseRaw } from "../lib/sse.js"
@@ -48,26 +49,28 @@ describe("Gemini route", () => {
       const prepared = yield* compileRequest(
         LLMRequest.update(request, {
           providerOptions: {
-            cachedContent: "cachedContents/example",
-            safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
-            serviceTier: "priority",
-            thinkingConfig: { thinkingBudget: 0, includeThoughts: false, thinkingLevel: "high" },
+            gemini: {
+              cachedContent: "cachedContents/example",
+              safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+              serviceTier: "priority",
+              thinkingConfig: { thinkingBudget: 0, includeThoughts: false, thinkingLevel: "high" },
+            },
           },
         }),
       )
       const filtered = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { thinkingConfig: { thinkingBudget: "invalid", includeThoughts: false } },
+          providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "invalid", includeThoughts: false } } },
         }),
       )
       const defaulted = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { thinkingConfig: { thinkingLevel: "high" } },
+          providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "high" } } },
         }),
       )
       const emptySafetySettings = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { safetySettings: [] },
+          providerOptions: { gemini: { safetySettings: [] } },
         }),
       )
 
@@ -288,30 +291,35 @@ describe("Gemini route", () => {
     }),
   )
 
-  it.effect("passes encoded media through without local validation", () =>
+  for (const [name, media] of [
+    ["mismatched data URL MIME", { mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" }],
+    ["malformed base64", { mediaType: "image/png", data: "%%%=" }],
+    ["unsupported SVG", { mediaType: "image/svg+xml", data: "PHN2Zz4=" }],
+  ] as const)
+    it.effect(`rejects ${name}`, () =>
+      Effect.gen(function* () {
+        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/)
+      }),
+    )
+
+  it.effect("rejects oversized image input", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(
+      const error = yield* compileRequest(
         LLM.request({
           model,
           messages: [
-            Message.user([
-              { type: "media", mediaType: "image/png", data: "%%%=" },
-              { type: "media", mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" },
-              { type: "media", mediaType: "image/svg+xml", data: "PHN2Zz4=" },
-            ]),
+            Message.user({
+              type: "media",
+              mediaType: "image/png",
+              data: "A".repeat(ProviderShared.MAX_MEDIA_ENCODED_BYTES + 4),
+            }),
           ],
         }),
-      )
-      expect(prepared.body.contents).toEqual([
-        {
-          role: "user",
-          parts: [
-            { inlineData: { mimeType: "image/png", data: "%%%=" } },
-            { inlineData: { mimeType: "image/png", data: "/9j/" } },
-            { inlineData: { mimeType: "image/svg+xml", data: "PHN2Zz4=" } },
-          ],
-        },
-      ])
+      ).pipe(Effect.flip)
+      expect(error.message).toContain("encoded limit")
     }),
   )
 
@@ -700,80 +708,6 @@ describe("Gemini route", () => {
     }),
   )
 
-  it.effect("leaves unsigned parallel calls unchanged after a signed Gemini 3 call", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model: gemini3,
-          messages: [
-            Message.assistant([
-              ToolCallPart.make({
-                id: "tool_0",
-                name: "lookup",
-                input: { query: "weather" },
-                providerMetadata: { google: { thoughtSignature: "parallel_signature" } },
-              }),
-              ToolCallPart.make({ id: "tool_1", name: "lookup", input: { query: "news" } }),
-              ToolCallPart.make({ id: "tool_2", name: "lookup", input: { query: "sports" } }),
-            ]),
-          ],
-        }),
-      )
-
-      expect(prepared.body.contents).toEqual([
-        {
-          role: "model",
-          parts: [
-            {
-              functionCall: { id: undefined, name: "lookup", args: { query: "weather" } },
-              thoughtSignature: "parallel_signature",
-            },
-            {
-              functionCall: { id: undefined, name: "lookup", args: { query: "news" } },
-              thoughtSignature: undefined,
-            },
-            {
-              functionCall: { id: undefined, name: "lookup", args: { query: "sports" } },
-              thoughtSignature: undefined,
-            },
-          ],
-        },
-      ])
-    }),
-  )
-
-  it.effect("adds the validator bypass sentinel to every call in an unsigned Gemini 3 batch", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model: gemini3,
-          messages: [
-            Message.assistant([
-              ToolCallPart.make({ id: "tool_0", name: "lookup", input: { query: "weather" } }),
-              ToolCallPart.make({ id: "tool_1", name: "lookup", input: { query: "news" } }),
-            ]),
-          ],
-        }),
-      )
-
-      expect(prepared.body.contents).toEqual([
-        {
-          role: "model",
-          parts: [
-            {
-              functionCall: { id: undefined, name: "lookup", args: { query: "weather" } },
-              thoughtSignature: "skip_thought_signature_validator",
-            },
-            {
-              functionCall: { id: undefined, name: "lookup", args: { query: "news" } },
-              thoughtSignature: "skip_thought_signature_validator",
-            },
-          ],
-        },
-      ])
-    }),
-  )
-
   it.effect("emits streamed tool calls and maps finish reason", () =>
     Effect.gen(function* () {
       const body = sseEvents({
@@ -839,31 +773,6 @@ describe("Gemini route", () => {
     }),
   )
 
-  it.effect("defaults omitted function call args to an empty object", () =>
-    Effect.gen(function* () {
-      const response = yield* LLMClient.generate(
-        LLMRequest.update(request, {
-          tools: [ToolDefinition.make({ name: "ping", description: "Ping", inputSchema: { type: "object" } })],
-        }),
-      ).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents({
-              candidates: [
-                {
-                  content: { role: "model", parts: [{ functionCall: { name: "ping" } }] },
-                  finishReason: "STOP",
-                },
-              ],
-            }),
-          ),
-        ),
-      )
-
-      expect(response.toolCalls).toEqual([{ type: "tool-call", id: "tool_0", name: "ping", input: {} }])
-    }),
-  )
-
   it.effect("maps tool calls without a finish reason", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(
@@ -959,51 +868,6 @@ describe("Gemini route", () => {
     }),
   )
 
-  it.effect("preserves candidate-less prompt safety blocks as content-filter outcomes", () =>
-    Effect.gen(function* () {
-      const blocked = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents({
-              promptFeedback: {
-                blockReason: "FUTURE_SAFETY_REASON",
-                blockReasonMessage: "Prompt blocked",
-                safetyRatings: [{ category: "HARM_CATEGORY_HARASSMENT", blocked: true }],
-              },
-            }),
-          ),
-        ),
-      )
-      const blockedWithUsage = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              { promptFeedback: { blockReason: "SAFETY" } },
-              { usageMetadata: { promptTokenCount: 7, totalTokenCount: 7 } },
-            ),
-          ),
-        ),
-      )
-
-      expect(blocked.events.map((event) => event.type)).toEqual(["step-start", "step-finish", "finish"])
-      expect(blocked.events.at(-1)).toMatchObject({
-        type: "finish",
-        reason: { normalized: "content-filter", raw: "FUTURE_SAFETY_REASON" },
-        providerMetadata: {
-          google: {
-            promptFeedback: {
-              blockReason: "FUTURE_SAFETY_REASON",
-              blockReasonMessage: "Prompt blocked",
-              safetyRatings: [{ category: "HARM_CATEGORY_HARASSMENT", blocked: true }],
-            },
-          },
-        },
-      })
-      expect(blockedWithUsage.finishReason).toEqual({ normalized: "content-filter", raw: "SAFETY" })
-      expect(blockedWithUsage.usage).toMatchObject({ inputTokens: 7, totalTokens: 7 })
-    }),
-  )
-
   it.effect("maps current blocking and invalid-output finish reasons", () =>
     Effect.gen(function* () {
       const reasons = [

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

@@ -54,27 +54,6 @@ describe("Google Vertex providers", () => {
     }),
   )
 
-  it.effect("adds billing labels to Vertex Gemini requests", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model: GoogleVertex.configure({
-            accessToken: "vertex-token",
-            project: "vertex-project",
-            providerOptions: {
-              labels: { component: "opencode", environment: "test" },
-            },
-          }).model("gemini-3.5-flash"),
-          prompt: "Say hello.",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        labels: { component: "opencode", environment: "test" },
-      })
-    }),
-  )
-
   it.effect("projects Anthropic Messages onto the Vertex raw-predict API", () =>
     Effect.gen(function* () {
       const model = GoogleVertexMessages.configure({

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

@@ -15,7 +15,7 @@ const cases = [
     model: LanguageModel.update(
       OpenRouter.configure({
         apiKey: process.env.OPENROUTER_API_KEY ?? "fixture",
-        providerOptions: { reasoning: { max_tokens: 1024 } },
+        providerOptions: { openrouter: { reasoning: { max_tokens: 1024 } } },
       }).model("anthropic/claude-sonnet-4.6"),
       { compatibility: { reasoningField: "reasoning" } },
     ),

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

@@ -165,7 +165,7 @@ describe("OpenAI Chat route", () => {
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).chat("gpt-4o-mini"),
           prompt: "think",
-          providerOptions: { reasoningEffort: "max" },
+          providerOptions: { openai: { reasoningEffort: "max" } },
         }),
       )
 
@@ -221,7 +221,7 @@ describe("OpenAI Chat route", () => {
         LLM.request({
           model,
           prompt: "think",
-          providerOptions: { reasoningEffort: "experimental" },
+          providerOptions: { openai: { reasoningEffort: "experimental" } },
         }),
       )
 
@@ -255,7 +255,7 @@ describe("OpenAI Chat route", () => {
     LLMClient.generate(
       LLMRequest.update(request, {
         model: Azure.configure({
-          baseURL: "https://opencode-test.openai.azure.com/openai/",
+          baseURL: "https://opencode-test.openai.azure.com/openai/v1/",
           apiKey: "azure-key",
           headers: { authorization: "Bearer stale" },
         }).chat("gpt-4o-mini"),
@@ -527,42 +527,35 @@ describe("OpenAI Chat route", () => {
     }),
   )
 
-  it.effect("passes encoded image media through without local validation", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [
-            Message.user([
-              { type: "media", mediaType: "image/png", data: "not-base64" },
-              { type: "media", mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" },
-              { type: "media", mediaType: "image/svg+xml", data: "PHN2Zz4=" },
-            ]),
-          ],
-        }),
-      )
-      expect(prepared.body.messages).toEqual([
-        {
-          role: "user",
-          content: [
-            { type: "image_url", image_url: { url: "data:image/png;base64,not-base64" } },
-            { type: "image_url", image_url: { url: "data:image/jpeg;base64,/9j/" } },
-            { type: "image_url", image_url: { url: "data:image/svg+xml;base64,PHN2Zz4=" } },
-          ],
-        },
-      ])
-    }),
-  )
+  for (const [name, media] of [
+    ["mismatched data URL MIME", { mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" }],
+    ["malformed base64", { mediaType: "image/png", data: "not-base64" }],
+    ["unsupported SVG", { mediaType: "image/svg+xml", data: "PHN2Zz4=" }],
+  ] as const)
+    it.effect(`rejects ${name}`, () =>
+      Effect.gen(function* () {
+        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/)
+      }),
+    )
 
-  it.effect("rejects non-image media that cannot be lowered", () =>
+  it.effect("rejects oversized image input", () =>
     Effect.gen(function* () {
       const error = yield* compileRequest(
         LLM.request({
           model,
-          messages: [Message.user({ type: "media", mediaType: "audio/mpeg", data: "AAECAw==" })],
+          messages: [
+            Message.user({
+              type: "media",
+              mediaType: "image/png",
+              data: "A".repeat(ProviderShared.MAX_MEDIA_ENCODED_BYTES + 4),
+            }),
+          ],
         }),
       ).pipe(Effect.flip)
-      expect(error.message).toContain("OpenAI Chat does not support media type audio/mpeg")
+      expect(error.message).toContain("encoded limit")
     }),
   )
 

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

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMEvent, Message, ToolDefinition } from "../../src/index.js"
+import { LLM, LLMEvent, Message } from "../../src/index.js"
 import { configure } from "../../src/providers/openai-compatible-responses.js"
 import { OpenAI } from "../../src/providers.js"
 import { OpenResponses } from "../../src/protocols/open-responses.js"
@@ -56,28 +56,6 @@ describe("Open Responses-compatible route", () => {
     }),
   )
 
-  it.effect("lowers chronological system updates as standard developer messages", () =>
-    Effect.gen(function* () {
-      const model = configure({
-        apiKey: "test-key",
-        baseURL: "https://responses.example.test/v1",
-        provider: "example",
-      }).model("example-model")
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [Message.user("Before."), Message.system("Operator update."), Message.assistant("After.")],
-        }),
-      )
-
-      expect(prepared.body.input).toEqual([
-        { role: "user", content: [{ type: "input_text", text: "Before." }] },
-        { role: "developer", content: "Operator update." },
-        { role: "assistant", content: [{ type: "output_text", text: "After." }] },
-      ])
-    }),
-  )
-
   it.effect("rejects OpenAI-native tools", () =>
     Effect.gen(function* () {
       const model = configure({
@@ -118,39 +96,18 @@ describe("Open Responses-compatible route", () => {
     }),
   )
 
-  it.effect("reads standard Open Responses options", () =>
+  it.effect("reads standard options from the Open Responses namespace", () =>
     Effect.gen(function* () {
       const model = configure({
         apiKey: "test-key",
         baseURL: "https://responses.example.test/v1",
-        providerOptions: {
-          reasoningEffort: "low",
-          store: true,
-          truncation: "auto",
-          allowedTools: { toolNames: ["lookup"] },
-          maxToolCalls: 2,
-          parallelToolCalls: false,
-        },
+        providerOptions: { openresponses: { reasoningEffort: "low", store: true } },
       }).model("example-model")
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          prompt: "Think.",
-          tools: [ToolDefinition.make({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })],
-        }),
-      )
+      const prepared = yield* compileRequest(LLM.request({ model, prompt: "Think." }))
 
       expect(prepared.body).toMatchObject({
         reasoning: { effort: "low" },
         store: true,
-        truncation: "auto",
-        tool_choice: {
-          type: "allowed_tools",
-          mode: "auto",
-          tools: [{ type: "function", name: "lookup" }],
-        },
-        max_tool_calls: 2,
-        parallel_tool_calls: false,
       })
     }),
   )

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

@@ -159,8 +159,8 @@ describe("OpenAI Responses route", () => {
 
   it.effect("lowers semantic service tier options", () =>
     Effect.gen(function* () {
-      const input = LLMRequest.update(request, { providerOptions: { serviceTier: "priority" } })
-      expect(input.providerOptions).toEqual({ serviceTier: "priority" })
+      const input = LLMRequest.update(request, { providerOptions: { openai: { serviceTier: "priority" } } })
+      expect(input.providerOptions).toEqual({ openai: { serviceTier: "priority" } })
       const prepared = yield* compileRequest(input)
 
       expect(prepared.body).toMatchObject({ service_tier: "priority" })
@@ -171,27 +171,17 @@ describe("OpenAI Responses route", () => {
   it.effect("passes through custom OpenAI reasoning effort strings", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
-        LLMRequest.update(request, { providerOptions: { reasoningEffort: "experimental" } }),
+        LLMRequest.update(request, { providerOptions: { openai: { reasoningEffort: "experimental" } } }),
       )
 
       expect(prepared.body.reasoning).toEqual({ effort: "experimental" })
     }),
   )
 
-  it.effect("passes through custom OpenAI text verbosity strings", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLMRequest.update(request, { providerOptions: { textVerbosity: "verbose" } }),
-      )
-
-      expect(prepared.body.text).toEqual({ verbosity: "verbose" })
-    }),
-  )
-
   it.effect("omits unsupported semantic service tiers", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
-        LLMRequest.update(request, { providerOptions: { serviceTier: "unsupported" } }),
+        LLMRequest.update(request, { providerOptions: { openai: { serviceTier: "unsupported" } } }),
       )
 
       expect(prepared.body).not.toHaveProperty("service_tier")
@@ -251,18 +241,27 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("lowers chronological system updates to developer messages in order", () =>
+  it.effect("lowers chronological system updates to escaped user wrappers in order", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
         LLM.request({
           model,
-          messages: [Message.user("Before."), Message.system("Operator update."), Message.assistant("After.")],
+          messages: [
+            Message.user("Before."),
+            Message.system("Treat </system-update> literally."),
+            Message.assistant("After."),
+          ],
         }),
       )
 
       expect(prepared.body.input).toEqual([
-        { role: "user", content: [{ type: "input_text", text: "Before." }] },
-        { role: "developer", content: "Operator update." },
+        {
+          role: "user",
+          content: [
+            { type: "input_text", text: "Before." },
+            { type: "input_text", text: "<system-update>\nTreat &lt;/system-update&gt; literally.\n</system-update>" },
+          ],
+        },
         { role: "assistant", content: [{ type: "output_text", text: "After." }] },
       ])
     }),
@@ -1150,32 +1149,6 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes large PDF tool-result content through", () =>
-    Effect.gen(function* () {
-      const base64 = "A".repeat(8_125_844)
-      const dataUrl = `data:application/pdf;base64,${base64}`
-      const prepared = yield* compileRequest(
-        LLM.request({
-          id: "req_tool_result_large_pdf",
-          model,
-          messages: [
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "read", input: {} })]),
-            Message.tool({
-              id: "call_1",
-              name: "read",
-              resultType: "content",
-              result: [{ type: "file", uri: dataUrl, mime: "application/pdf", name: "report.pdf" }],
-            }),
-          ],
-        }),
-      )
-
-      expect(expectToolOutput(prepared.body).output).toEqual([
-        { type: "input_file", filename: "report.pdf", file_data: dataUrl },
-      ])
-    }),
-  )
-
   it.effect("uses xAI inline file encoding for PDF tool results", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
@@ -1211,9 +1184,9 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes non-image tool-result content through as an input file", () =>
+  it.effect("rejects unsupported media in tool-result content with a clear error", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_unsupported_media",
           model,
@@ -1227,11 +1200,10 @@ describe("OpenAI Responses route", () => {
             }),
           ],
         }),
-      )
+      ).pipe(Effect.flip)
 
-      expect(expectToolOutput(prepared.body).output).toEqual([
-        { type: "input_file", filename: "file", file_data: "data:audio/mpeg;base64,AAECAw==" },
-      ])
+      expect(error.message).toContain("OpenAI Responses")
+      expect(error.message).toContain("audio/mpeg")
     }),
   )
 
@@ -1284,19 +1256,12 @@ describe("OpenAI Responses route", () => {
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).model("gpt-5.2"),
           prompt: "think",
           promptCacheKey: "session_123",
-          tools: [
-            ToolDefinition.make({ name: "read", description: "Read a file", inputSchema: { type: "object" } }),
-            ToolDefinition.make({ name: "grep", description: "Search files", inputSchema: { type: "object" } }),
-          ],
-          toolChoice: "none",
           providerOptions: {
-            reasoningEffort: "high",
-            reasoningSummary: "auto",
-            include: ["reasoning.encrypted_content"],
-            truncation: "disabled",
-            allowedTools: { toolNames: ["read", "grep"], mode: "required" },
-            maxToolCalls: 4,
-            parallelToolCalls: false,
+            openai: {
+              reasoningEffort: "high",
+              reasoningSummary: "auto",
+              include: ["reasoning.encrypted_content"],
+            },
           },
         }),
       )
@@ -1306,17 +1271,6 @@ describe("OpenAI Responses route", () => {
       expect(prepared.body.include).toEqual(["reasoning.encrypted_content"])
       expect(prepared.body.reasoning).toEqual({ effort: "high", summary: "auto" })
       expect(prepared.body.text).toEqual({ verbosity: "low" })
-      expect(prepared.body.truncation).toBe("disabled")
-      expect(prepared.body.tool_choice).toEqual({
-        type: "allowed_tools",
-        mode: "required",
-        tools: [
-          { type: "function", name: "read" },
-          { type: "function", name: "grep" },
-        ],
-      })
-      expect(prepared.body.max_tool_calls).toBe(4)
-      expect(prepared.body.parallel_tool_calls).toBe(false)
     }),
   )
 
@@ -1327,7 +1281,9 @@ describe("OpenAI Responses route", () => {
           model,
           prompt: "hi",
           providerOptions: {
-            include: ["reasoning.encrypted_content", "code_interpreter_call.outputs", "web_search_call.results"],
+            openai: {
+              include: ["reasoning.encrypted_content", "code_interpreter_call.outputs", "web_search_call.results"],
+            },
           },
         }),
       )
@@ -1340,41 +1296,48 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes forward-compatible includable values through", () =>
+  it.effect("filters unknown includable values out of the include array", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
         LLM.request({
           model,
           prompt: "hi",
-          providerOptions: { include: ["reasoning.encrypted_content", "bogus.thing"] },
+          // The user passed one invalid entry alongside a valid one. Keep the
+          // valid one so the request still succeeds rather than failing on a
+          // typo from upstream config.
+          providerOptions: { openai: { include: ["reasoning.encrypted_content", "bogus.thing"] } },
         }),
       )
 
-      expect(prepared.body.include).toEqual(["reasoning.encrypted_content", "bogus.thing"])
+      expect(prepared.body.include).toEqual(["reasoning.encrypted_content"])
     }),
   )
 
   it.effect("treats an explicit empty include as no include at all", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(LLM.request({ model, prompt: "hi", providerOptions: { include: [] } }))
+      const prepared = yield* compileRequest(
+        LLM.request({ model, prompt: "hi", providerOptions: { openai: { include: [] } } }),
+      )
 
       expect(prepared.body.include).toBeUndefined()
     }),
   )
 
-  it.effect("passes an unknown includable value through", () =>
+  it.effect("treats an all-invalid include as no include at all", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
-        LLM.request({ model, prompt: "hi", providerOptions: { include: ["bogus.thing"] } }),
+        LLM.request({ model, prompt: "hi", providerOptions: { openai: { include: ["bogus.thing"] } } }),
       )
 
-      expect(prepared.body.include).toEqual(["bogus.thing"])
+      expect(prepared.body.include).toBeUndefined()
     }),
   )
 
   it.effect("omits include when no include is set", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(LLM.request({ model, prompt: "hi", providerOptions: { store: false } }))
+      const prepared = yield* compileRequest(
+        LLM.request({ model, prompt: "hi", providerOptions: { openai: { store: false } } }),
+      )
 
       expect(prepared.body.include).toBeUndefined()
     }),
@@ -1405,7 +1368,7 @@ describe("OpenAI Responses route", () => {
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).responses("gpt-5.2"),
           prompt: "hi",
-          providerOptions: { include: [] },
+          providerOptions: { openai: { include: [] } },
         }),
       )
 
@@ -1729,7 +1692,7 @@ describe("OpenAI Responses route", () => {
   it.effect("streams each reasoning summary part as a separate block", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(
-        LLMRequest.update(request, { providerOptions: { store: false } }),
+        LLMRequest.update(request, { providerOptions: { openai: { store: false } } }),
       ).pipe(
         Effect.provide(
           fixedResponse(
@@ -1783,7 +1746,9 @@ describe("OpenAI Responses route", () => {
 
   it.effect("closes reasoning summary parts when storage is not disabled", () =>
     Effect.gen(function* () {
-      const response = yield* LLMClient.generate(LLMRequest.update(request, { providerOptions: { store: true } })).pipe(
+      const response = yield* LLMClient.generate(
+        LLMRequest.update(request, { providerOptions: { openai: { store: true } } }),
+      ).pipe(
         Effect.provide(
           fixedResponse(
             sseEvents(
@@ -1837,7 +1802,7 @@ describe("OpenAI Responses route", () => {
             ]),
             Message.user("Summarize it."),
           ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
         }),
       ).pipe(
         Effect.provide(
@@ -1896,7 +1861,7 @@ describe("OpenAI Responses route", () => {
               { type: "text", text: "After." },
             ]),
           ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
         }),
       )
 
@@ -1926,7 +1891,7 @@ describe("OpenAI Responses route", () => {
               },
             ]),
           ],
-          providerOptions: { store: true },
+          providerOptions: { openai: { store: true } },
         }),
       )
 
@@ -1959,7 +1924,7 @@ describe("OpenAI Responses route", () => {
             ]),
             Message.user("Continue."),
           ],
-          providerOptions: { store: true },
+          providerOptions: { openai: { store: true } },
         }),
       )
 
@@ -2032,7 +1997,7 @@ describe("OpenAI Responses route", () => {
               },
             ]),
           ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
         }),
       )
 
@@ -2072,7 +2037,7 @@ describe("OpenAI Responses route", () => {
             ]),
             Message.user("Summarize it."),
           ],
-          providerOptions: { store: false },
+          providerOptions: { openai: { store: false } },
         }),
       )
 
@@ -2429,28 +2394,17 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes non-image user media through as an input file", () =>
+  it.effect("rejects unsupported user media content", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_media",
           model,
           messages: [Message.user({ type: "media", mediaType: "application/x-tar", data: "AAECAw==" })],
         }),
-      )
+      ).pipe(Effect.flip)
 
-      expect(prepared.body.input).toEqual([
-        {
-          role: "user",
-          content: [
-            {
-              type: "input_file",
-              filename: "file",
-              file_data: "data:application/x-tar;base64,AAECAw==",
-            },
-          ],
-        },
-      ])
+      expect(error.message).toContain("OpenAI Responses does not support media type application/x-tar")
     }),
   )
 

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

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

packages/ai/test/recorded-scenarios.ts

@@ -181,10 +181,12 @@ const normalizeImageText = (value: string) =>
     .trim()
 
 const encryptedReasoningOptions = {
-  store: false,
-  include: ["reasoning.encrypted_content"],
-  reasoningEffort: "low",
-  reasoningSummary: "auto",
+  openai: {
+    store: false,
+    include: ["reasoning.encrypted_content"],
+    reasoningEffort: "low",
+    reasoningSummary: "auto",
+  },
 } as const
 
 type AssistantTextExpectation = string | RegExp
@@ -302,7 +304,8 @@ const runTextScenario = (context: GoldenScenarioContext) =>
     assistant.expectText(/^Hello!?$/, {
       system: "You are concise.",
       maxTokens: context.maxTokens ?? 40,
-      providerOptions: context.model.route.id === "gemini" ? { thinkingConfig: { thinkingBudget: 0 } } : undefined,
+      providerOptions:
+        context.model.route.id === "gemini" ? { gemini: { thinkingConfig: { thinkingBudget: 0 } } } : undefined,
     }),
   ])
 
@@ -385,7 +388,7 @@ const runReasoningScenario = (context: GoldenScenarioContext) =>
     user("Think briefly, then reply exactly with: Hello!"),
     assistant.expectText(/^Hello!?$/, {
       system: "Show concise reasoning when the provider supports visible reasoning summaries.",
-      providerOptions: { reasoningEffort: "low", reasoningSummary: "auto" },
+      providerOptions: { openai: { reasoningEffort: "low", reasoningSummary: "auto" } },
       maxTokens: context.maxTokens ?? 120,
       assert: (response) => expect(response.usage?.reasoningTokens ?? 0).toBeGreaterThan(0),
     }),

packages/ai/test/schema.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import { Effect, Schema, Stream } from "effect"
+import { Effect, Schema } from "effect"
 import * as OpenAIChat from "../src/protocols/openai-chat.js"
 import * as OpenAIResponses from "../src/protocols/openai-responses.js"
 import {
@@ -90,18 +90,6 @@ describe("AI.Usage", () => {
     expect(ProviderShared.sumTokens()).toBeUndefined()
   })
 
-  test("sseFraming maps decoder failures to AI errors", async () => {
-    const error = await Effect.runPromise(
-      ProviderShared.sseFraming(Stream.make(new TextEncoder().encode(`data: ${"x".repeat(10 * 1024 * 1024)}`))).pipe(
-        Stream.runCollect,
-        Effect.flip,
-      ),
-    )
-
-    expect(error).toBeInstanceOf(AIError)
-    expect(error.reason._tag).toBe("InvalidProviderOutput")
-  })
-
   test("visibleOutputTokens clamps reasoning > output to zero", () => {
     expect(new Usage({ outputTokens: 10, reasoningTokens: 4 }).visibleOutputTokens).toBe(6)
     expect(new Usage({ outputTokens: 10 }).visibleOutputTokens).toBe(10)

packages/ai/test/tool-runtime.test.ts

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

packages/app/e2e/performance/timeline-stability/adverse.spec.ts

@@ -9,7 +9,6 @@ import {
 import {
   assistantMessage,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   shell,
   textPart,
@@ -98,15 +97,13 @@ test.describe("timeline adverse visual stability", () => {
       element.scrollTop = 0
     })
     await page.waitForTimeout(300)
-    const trigger = page.locator(
-      `[data-timeline-part-id="${renderedPartID(targetID)}"] [data-slot="collapsible-trigger"]`,
-    )
+    const trigger = page.locator(`[data-timeline-part-id="${targetID}"] [data-slot="collapsible-trigger"]`)
     await expect(trigger).toBeVisible()
     await trigger.click()
     await expect(trigger).toHaveAttribute("aria-expanded", "true")
 
     await scroller.evaluate((element) => (element.scrollTop = element.scrollHeight))
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(targetID)}"]`)).toHaveCount(0)
+    await expect(page.locator(`[data-timeline-part-id="${targetID}"]`)).toHaveCount(0)
     await scroller.evaluate((element) => (element.scrollTop = 0))
     await expect(trigger).toBeVisible()
     await expect(trigger).toHaveAttribute("aria-expanded", "true")
@@ -130,16 +127,13 @@ test.describe("timeline adverse visual stability", () => {
       cpuRate: 4,
     })
     await waitForVisualSettle(page, [
-      `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+      `[data-timeline-part-id="${shellID}"]`,
+      `[data-timeline-part-id="${followingID}"]`,
     ])
     const regions = defineVisualRegions({
-      shell: {
-        selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
+      shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })
@@ -190,13 +184,10 @@ test.describe("timeline adverse visual stability", () => {
     })
     const group = `[data-timeline-part-ids="${contextIDs.join(",")}"]`
     const regions = defineVisualRegions({
-      shell: {
-        selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
+      shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
       context: { selector: group, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })

packages/app/e2e/performance/timeline-stability/context-matrix.spec.ts

@@ -0,0 +1,192 @@
+import { expect, test } from "@playwright/test"
+import {
+  defineVisualRegions,
+  reportVisualStability,
+  startVisualProbe,
+  stopVisualProbe,
+  visualPlan,
+} from "../../utils/visual-stability"
+import {
+  assistantID,
+  assistantMessage,
+  event,
+  partUpdated,
+  setupTimeline,
+  textPart,
+  toolPart,
+  userMessage,
+  waitForVisualSettle,
+} from "./fixture"
+
+const inputs = {
+  read: { filePath: "src/a.ts", offset: 0, limit: 120 },
+  glob: { path: ".", pattern: "**/*.ts" },
+  grep: { path: ".", pattern: "stable", include: "*.ts" },
+  list: { path: "src" },
+}
+
+test("appends context operations while the group is expanded", async ({ page }, testInfo) => {
+  const firstID = "prt_append_01_read"
+  const followingID = "prt_append_99_following"
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(),
+      assistantMessage([toolPart(firstID, "read", "running", inputs.read), textPart(followingID, "Following append")], {
+        completed: false,
+      }),
+    ],
+    cpuRate: 4,
+  })
+  const initialGroup = `[data-timeline-part-ids="${firstID}"]`
+  await page.locator(`${initialGroup} [data-slot="collapsible-trigger"]`).click()
+  await waitForVisualSettle(page, [initialGroup, `[data-timeline-part-id="${followingID}"]`])
+  const regions = defineVisualRegions({
+    context: {
+      selector: '[data-timeline-part-ids^="prt_append_01_read"]',
+      closest: '[data-timeline-row="AssistantPart"]',
+    },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+  })
+  await startVisualProbe(page, regions)
+  await timeline.send(partUpdated(toolPart("prt_append_02_glob", "glob", "running", inputs.glob)), 180)
+  await timeline.send(partUpdated(toolPart("prt_append_03_grep", "grep", "completed", inputs.grep)), 240)
+  await timeline.send(partUpdated(toolPart("prt_append_04_list", "list", "completed", inputs.list)), 500)
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(
+    testInfo,
+    "context-append",
+    trace,
+    visualPlan(
+      regions,
+      [
+        { type: "required", regions: ["context", "following"] },
+        { type: "unique", regions: ["context", "following"] },
+        { type: "stable", regions: ["context", "following"] },
+        { type: "opacity", regions: "all" },
+        { type: "continuity", regions: "all" },
+        { type: "motion", regions: ["following"], maxPositionReversals: 0 },
+        { type: "label-stability", regions: "all" },
+        { type: "preserve-bottom-anchor" },
+        { type: "flow", regions: ["context", "following"] },
+      ],
+      { perMarker: true },
+    ),
+  )
+  await expect(
+    page.locator(
+      '[data-timeline-part-ids="prt_append_01_read,prt_append_02_glob,prt_append_03_grep,prt_append_04_list"]',
+    ),
+  ).toBeVisible()
+  await expect(
+    page.locator('[data-timeline-part-ids^="prt_append_01_read"] [data-slot="collapsible-trigger"]'),
+  ).toHaveAttribute("aria-expanded", "true")
+})
+
+test("splits and merges context groups when a middle text part changes", async ({ page }, testInfo) => {
+  const textID = "prt_split_02_text"
+  const followingID = "prt_split_99_following"
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(),
+      assistantMessage([
+        toolPart("prt_split_01_read", "read", "completed", inputs.read),
+        textPart(textID, "Boundary"),
+        toolPart("prt_split_03_glob", "glob", "completed", inputs.glob),
+        textPart(followingID, "Following split groups"),
+      ]),
+    ],
+    cpuRate: 4,
+  })
+  const regions = defineVisualRegions({
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+  })
+  await startVisualProbe(page, regions)
+  await timeline.send(
+    event("message.part.removed", { sessionID: "ses_timeline_stability", messageID: assistantID, partID: textID }),
+    500,
+  )
+  await expect(page.locator('[data-timeline-part-ids="prt_split_01_read,prt_split_03_glob"]')).toBeVisible()
+  await timeline.send(partUpdated(textPart(textID, "Boundary restored")), 500)
+  await expect(page.locator('[data-timeline-part-ids="prt_split_01_read"]')).toBeVisible()
+  await expect(page.locator('[data-timeline-part-ids="prt_split_03_glob"]')).toBeVisible()
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(
+    testInfo,
+    "context-split-merge",
+    trace,
+    visualPlan(
+      regions,
+      [
+        { type: "required", regions: ["following"] },
+        { type: "unique", regions: ["following"] },
+        { type: "stable", regions: ["following"] },
+        { type: "opacity", regions: "all" },
+        { type: "continuity", regions: "all" },
+        { type: "motion", regions: "all", maxPositionReversals: 1 },
+        { type: "label-stability", regions: "all" },
+      ],
+      { perMarker: true },
+    ),
+  )
+})
+
+test("removing the first context member replaces the group once without overlapping following content", async ({
+  page,
+}, testInfo) => {
+  const ids = ["prt_key_01_read", "prt_key_02_glob", "prt_key_03_grep"]
+  const followingID = "prt_key_99_following"
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(),
+      assistantMessage([
+        toolPart(ids[0]!, "read", "completed", inputs.read),
+        toolPart(ids[1]!, "glob", "completed", inputs.glob),
+        toolPart(ids[2]!, "grep", "completed", inputs.grep),
+        textPart(followingID, "Following replaced group"),
+      ]),
+    ],
+    cpuRate: 4,
+  })
+  const original = page.locator(`[data-timeline-part-ids="${ids.join(",")}"]`)
+  const originalRowKey = await original.evaluate((element) =>
+    element.closest("[data-timeline-key]")?.getAttribute("data-timeline-key"),
+  )
+  await original.locator('[data-slot="collapsible-trigger"]').click()
+  await expect(original.locator('[data-slot="collapsible-trigger"]')).toHaveAttribute("aria-expanded", "true")
+  const regions = defineVisualRegions({
+    context: {
+      selector: '[data-timeline-part-ids*="prt_key_02_glob"]',
+      closest: '[data-timeline-row="AssistantPart"]',
+    },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+  })
+  await startVisualProbe(page, regions)
+  await timeline.send(
+    event("message.part.removed", { sessionID: "ses_timeline_stability", messageID: assistantID, partID: ids[0] }),
+    500,
+  )
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(
+    testInfo,
+    "context-first-remove",
+    trace,
+    visualPlan(regions, [
+      { type: "required", regions: ["context", "following"] },
+      { type: "unique", regions: ["context", "following"] },
+      { type: "opacity", regions: "all" },
+      { type: "continuity", regions: "all" },
+      { type: "motion", regions: "all", maxPositionReversals: 0 },
+      { type: "label-stability", regions: "all" },
+      { type: "flow", regions: ["context", "following"] },
+    ]),
+  )
+  await expect(page.locator(`[data-timeline-part-ids="${ids.slice(1).join(",")}"]`)).toBeVisible()
+  expect(
+    await page
+      .locator(`[data-timeline-part-ids="${ids.slice(1).join(",")}"]`)
+      .evaluate((element) => element.closest("[data-timeline-key]")?.getAttribute("data-timeline-key")),
+  ).toBe(originalRowKey)
+  await expect(
+    page.locator(`[data-timeline-part-ids="${ids.slice(1).join(",")}"] [data-slot="collapsible-trigger"]`),
+  ).toHaveAttribute("aria-expanded", "true")
+})

packages/app/e2e/performance/timeline-stability/environment-matrix.spec.ts

@@ -9,7 +9,6 @@ import {
 import {
   assistantMessage,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   shell,
   textPart,
@@ -35,16 +34,13 @@ for (const deviceScaleFactor of [1, 1.25]) {
       seedHistory: true,
     })
     await waitForVisualSettle(page, [
-      `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+      `[data-timeline-part-id="${shellID}"]`,
+      `[data-timeline-part-id="${followingID}"]`,
     ])
     const regions = defineVisualRegions({
-      shell: {
-        selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
+      shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })
@@ -75,16 +71,13 @@ for (const reducedMotion of [true]) {
       seedHistory: true,
     })
     await waitForVisualSettle(page, [
-      `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+      `[data-timeline-part-id="${shellID}"]`,
+      `[data-timeline-part-id="${followingID}"]`,
     ])
     const regions = defineVisualRegions({
-      shell: {
-        selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
+      shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })

packages/app/e2e/performance/timeline-stability/file-matrix.spec.ts

@@ -9,7 +9,6 @@ import {
 import {
   assistantMessage,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   textPart,
   toolPart,
@@ -44,17 +43,11 @@ for (const profile of profiles) {
       settings: { editToolPartsExpanded: true },
       cpuRate: 4,
     })
-    await waitForVisualSettle(page, [
-      `[data-timeline-part-id="${renderedPartID(partID)}"]`,
-      `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-    ])
+    await waitForVisualSettle(page, [`[data-timeline-part-id="${partID}"]`, `[data-timeline-part-id="${followingID}"]`])
     const regions = defineVisualRegions({
-      tool: {
-        selector: `[data-timeline-part-id="${renderedPartID(partID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
+      tool: { selector: `[data-timeline-part-id="${partID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })

packages/app/e2e/performance/timeline-stability/file-mutation.spec.ts

@@ -9,7 +9,6 @@ import {
 import {
   assistantMessage,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   textPart,
   toolPart,
@@ -36,23 +35,12 @@ test("adds patch files incrementally without resetting outer expansion", async (
     cpuRate: 4,
     seedHistory: true,
   })
-  const trigger = page
-    .locator(`[data-timeline-part-id="${renderedPartID(patchID)}"] [data-slot="collapsible-trigger"]`)
-    .first()
+  const trigger = page.locator(`[data-timeline-part-id="${patchID}"] [data-slot="collapsible-trigger"]`).first()
   await expect(trigger).toHaveAttribute("aria-expanded", "true")
-  await waitForVisualSettle(page, [
-    `[data-timeline-part-id="${renderedPartID(patchID)}"]`,
-    `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-  ])
+  await waitForVisualSettle(page, [`[data-timeline-part-id="${patchID}"]`, `[data-timeline-part-id="${followingID}"]`])
   const regions = defineVisualRegions({
-    patch: {
-      selector: `[data-timeline-part-id="${renderedPartID(patchID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    patch: { selector: `[data-timeline-part-id="${patchID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   const second = patchFile("src/b.ts", "add")

packages/app/e2e/performance/timeline-stability/fixture.test.ts

@@ -17,28 +17,19 @@ describe("timeline fixture validation", () => {
   test("rejects malformed SDK values at runtime", () => {
     expect(() =>
       assistantMessage([], {
-        error: { type: "APIError", message: 1 } as never,
+        error: { name: "APIError", data: { message: "failed" } } as never,
       }),
     ).toThrow()
     expect(() =>
       validateTimelineEvent({
-        id: "evt_invalid_status",
-        created: 1,
-        type: "session.status",
-        data: { sessionID: "ses_timeline_stability", status: { type: "retry", attempt: 1 } },
+        directory: "C:/OpenCode/TimelineStability",
+        payload: {
+          id: "evt_invalid_status",
+          type: "session.status",
+          properties: { sessionID: "ses_timeline_stability", status: { type: "retry", attempt: 1 } },
+        },
       }),
     ).toThrow()
-    expect(() => validateTimelineMessages([{ ...userMessage(), id: "invalid" } as never])).toThrow()
-    expect(() => validateTimelineMessages([{ ...userMessage(), time: { created: "invalid" } } as never])).toThrow()
-    expect(() =>
-      validateTimelineMessages([
-        userMessage(),
-        {
-          ...assistantMessage(),
-          content: [{ type: "tool", id: "call_invalid", name: "bash", state: { status: "completed" } }],
-        } as never,
-      ]),
-    ).toThrow()
   })
 
   test("rejects duplicate IDs and orphan assistants", () => {
@@ -51,8 +42,8 @@ describe("timeline fixture validation", () => {
   test("assigns deterministic event IDs", () => {
     const first = event("session.status", { sessionID: "ses_timeline_stability", status: { type: "busy" } })
     const second = event("session.status", { sessionID: "ses_timeline_stability", status: { type: "idle" } })
-    expect(first.id).toMatch(/^evt_timeline_\d{4}$/)
-    expect(Number(second.id.slice(-4))).toBe(Number(first.id.slice(-4)) + 1)
+    expect(first.payload.id).toMatch(/^evt_timeline_\d{4}$/)
+    expect(Number(second.payload.id.slice(-4))).toBe(Number(first.payload.id.slice(-4)) + 1)
   })
 })
 

packages/app/e2e/performance/timeline-stability/fixture.ts

@@ -1,16 +1,9 @@
-import { base64Encode } from "@opencode-ai/util/encode"
-import type {
-  JsonValue,
-  OpenCodeEvent,
-  SessionInfo,
-  SessionMessageAssistant,
-  SessionMessageInfo,
-  SessionMessageUser,
-  SessionStatus,
-  SessionStructuredError,
-} from "@opencode-ai/client/promise"
-import { EventManifest } from "@opencode-ai/schema/event-manifest"
-import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { base64Encode } from "@opencode-ai/core/util/encode"
+import { Event } from "@opencode-ai/schema/event"
+import { SessionStatusEvent } from "@opencode-ai/schema/session-status-event"
+import { SessionV1 } from "@opencode-ai/schema/session-v1"
+import type { SessionInfo, SessionMessageInfo, SessionStatus } from "@opencode-ai/client/promise"
+import type { AssistantMessage, Message, Part, ToolPart, ToolState, UserMessage } from "../../../src/types"
 import { expect, type Page } from "@playwright/test"
 import { Schema } from "effect"
 import { mockOpenCodeServer } from "../../utils/mock-server"
@@ -25,80 +18,50 @@ export const assistantID = "msg_1001_timeline_assistant"
 export const title = "Timeline visual stability"
 export const model = { providerID: "opencode", modelID: "claude-opus-4-6", variant: "max" }
 
-const server = `http://${process.env.PLAYWRIGHT_SERVER_HOST ?? "127.0.0.1"}:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
-const tokens = { input: 100, output: 200, reasoning: 0, cache: { read: 0, write: 0 } }
-
 type Session = SessionInfo
-type TextSeed = {
-  id: string
-  type: "text"
-  text: string
-  messageID?: string
-}
-type FileSeed = {
-  id: string
-  type: "file"
-  mime: string
-  filename?: string
-  url: string
-  source?: { type: string; path?: string; text?: { value: string; start: number; end: number } }
-}
-type AgentSeed = {
-  id: string
-  type: "agent"
-  name: string
-  source?: { value: string; start: number; end: number }
-}
-type ReasoningSeed = {
-  id: string
-  type: "reasoning"
-  text: string
-  time?: { start: number; end?: number }
-  metadata?: Record<string, unknown>
-  messageID?: string
-}
-type ToolSeed = {
-  id: string
-  type: "tool"
-  callID: string
-  tool: string
-  messageID?: string
-  executed?: boolean
-  providerState?: Record<string, unknown>
-  providerResultState?: Record<string, unknown>
-  state:
-    | { status: "pending"; input: Record<string, unknown>; raw: string }
-    | {
-        status: "running"
-        input: Record<string, unknown>
-        title?: string
-        metadata: Record<string, unknown>
-        time: { start: number }
-      }
-    | {
-        status: "completed"
-        input: Record<string, unknown>
-        output: string
-        title: string
-        metadata: Record<string, unknown>
-        time: { start: number; end: number }
-      }
-    | {
-        status: "error"
-        input: Record<string, unknown>
-        error: string
-        metadata: Record<string, unknown>
-        time: { start: number; end: number }
-      }
+type GlobalEvent = {
+  directory: string
+  project?: string
+  workspace?: string
+  payload: {
+    id: string
+    type: string
+    properties: Record<string, unknown>
+  }
 }
 
-export type TimelineMessage = SessionMessageUser | SessionMessageAssistant
-export type TimelineEvent = OpenCodeEvent | readonly OpenCodeEvent[]
-export type EventPayload = OpenCodeEvent
-export type ToolStatus = ToolSeed["state"]["status"]
-export type PartSeed<Owner extends "user" | "assistant"> = Owner extends "user"
-  ? TextSeed | FileSeed | AgentSeed
-  : TextSeed | ReasoningSeed | ToolSeed
+type TimelineProperties = {
+  "message.updated": { sessionID: string; info: Message }
+  "message.removed": { sessionID: string; messageID: string }
+  "message.part.updated": { sessionID: string; part: Part; time: number }
+  "message.part.removed": { sessionID: string; messageID: string; partID: string }
+  "message.part.delta": { sessionID: string; messageID: string; partID: string; field: string; delta: string }
+  "session.status": { sessionID: string; status: SessionStatus }
+}
+type TimelinePayload = {
+  [Type in keyof TimelineProperties]: { id: string; type: Type; properties: TimelineProperties[Type] }
+}[keyof TimelineProperties]
+
+type DeepReadonly<Value> = Value extends readonly unknown[]
+  ? { readonly [Key in keyof Value]: DeepReadonly<Value[Key]> }
+  : Value extends object
+    ? { readonly [Key in keyof Value]: DeepReadonly<Value[Key]> }
+    : Value
+
+export type TimelineEvent = DeepReadonly<Omit<GlobalEvent, "payload"> & { payload: TimelinePayload }>
+export type EventPayload = TimelineEvent
+export type ToolStatus = ToolState["status"]
+export type TimelineMessage = { info: UserMessage; parts: Part[] } | { info: AssistantMessage; parts: Part[] }
+
+type UserPart = Extract<Part, { type: "text" | "file" | "agent" | "subtask" }>
+type AssistantPart = Exclude<Part, { type: "agent" | "subtask" }>
+type OwnedPart<Owner extends Message["role"]> = Owner extends "user" ? UserPart : AssistantPart
+export type PartSeed<Owner extends Message["role"]> =
+  OwnedPart<Owner> extends infer Candidate
+    ? Candidate extends Part
+      ? Omit<Candidate, "sessionID" | "messageID">
+      : never
+    : never
 
 type ToolOptions<State extends ToolStatus> = State extends "pending"
   ? { output?: never; title?: never; metadata?: never; error?: never }
@@ -108,19 +71,26 @@ type ToolOptions<State extends ToolStatus> = State extends "pending"
       ? { error?: string; metadata?: Record<string, unknown>; output?: never; title?: never }
       : { output?: string; title?: string; metadata?: Record<string, unknown>; error?: never }
 
-type PartRef = { messageID: string; type: "text" | "reasoning" | "tool"; ordinal?: number }
-const partRefs = new Map<string, PartRef>()
-const nextOrdinals = new Map<string, { text: number; reasoning: number }>()
-const startedParts = new Set<string>()
-const toolStates = new Map<string, ToolStatus>()
+const decodeOptions = { errors: "all", onExcessProperty: "error" } as const
+const decodeMessage = Schema.decodeUnknownSync(SessionV1.WithParts)
+const decodePart = Schema.decodeUnknownSync(SessionV1.Part)
+const decodeStatus = Schema.decodeUnknownSync(SessionStatusEvent.Info)
+const timelineEventSchema = Schema.Union([
+  eventSchema("message.updated", SessionV1.Event.MessageUpdated.data),
+  eventSchema("message.removed", SessionV1.Event.MessageRemoved.data),
+  eventSchema("message.part.updated", SessionV1.Event.PartUpdated.data),
+  eventSchema("message.part.removed", SessionV1.Event.PartRemoved.data),
+  eventSchema("message.part.delta", SessionV1.Event.PartDelta.data),
+  eventSchema("session.status", SessionStatusEvent.Status.data),
+])
+const decodeEvent = Schema.decodeUnknownSync(timelineEventSchema)
 let eventSequence = 0
-let durableSequence = -1
 
 export async function setupTimeline(
   page: Page,
   input: {
     messages?: TimelineMessage[]
-    sessionMessages?: SessionMessageInfo[]
+    currentMessages?: SessionMessageInfo[]
     sessionStatus?: Record<string, SessionStatus>
     settings?: Record<string, boolean>
     sessions?: Session[]
@@ -133,26 +103,40 @@ export async function setupTimeline(
     seedHistory?: boolean
   } = {},
 ) {
-  eventSequence = 0
-  durableSequence = -1
   const sessions = input.sessions ?? [session()]
   const messages =
-    input.sessionMessages ??
+    input.currentMessages ??
     validateTimelineMessages([
       ...(input.seedHistory ? historyMessages(18) : []),
       ...(input.messages ?? [userMessage(), assistantMessage()]),
     ])
-  const active = messages.findLast((message) => message.type === "assistant")
-  const initialStatus: SessionStatus =
-    active?.type === "assistant" && active.time.completed === undefined ? { type: "busy" } : { type: "idle" }
-  const transport = await installSseTransport(page, { server, retry: input.eventRetry ?? 20 })
+  const active = messages.findLast((message) =>
+    "info" in message ? message.info.role === "assistant" : message.type === "assistant",
+  )
+  const initialStatus = decodeStatus(
+    active &&
+      ("info" in active
+        ? active.info.role === "assistant" && active.info.time.completed === undefined
+        : active.type === "assistant" && active.time.completed === undefined)
+      ? { type: "busy" }
+      : { type: "idle" },
+    decodeOptions,
+  )
+  const server = `http://${process.env.PLAYWRIGHT_SERVER_HOST ?? "127.0.0.1"}:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
+  const transport = await installSseTransport<EventPayload>(page, {
+    server,
+    retry: input.eventRetry ?? 20,
+  })
   await mockOpenCodeServer(page, {
+    protocol: "v2",
     directory,
     project: project(),
     provider: provider(),
     sessions,
     sessionStatus: input.sessionStatus ?? { [sessionID]: initialStatus },
-    pageMessages: () => ({ items: messages }),
+    pageMessages: () => ({
+      items: messages,
+    }),
   })
   await page.addInitScript((settings) => {
     localStorage.setItem(
@@ -167,6 +151,9 @@ export async function setupTimeline(
         },
       }),
     )
+    if (settings.newLayoutDesigns === false) {
+      localStorage.setItem("app-version.v1", JSON.stringify({ version: "1.17.20" }))
+    }
   }, input.settings ?? {})
   if (input.locale) {
     await page.addInitScript((locale) => {
@@ -185,7 +172,7 @@ export async function setupTimeline(
       mobile: false,
     })
   }
-  await page.goto(`/server/${base64Encode(server)}/session/${sessionID}`)
+  await page.goto(`/${base64Encode(directory)}/session/${sessionID}`)
   await expectSessionReady(page, { server, sessionID, title })
   await transport.waitForConnection()
   if (input.cpuRate && input.cpuRate > 1) {
@@ -195,25 +182,15 @@ export async function setupTimeline(
 
   return {
     transport,
-    async send(input: TimelineEvent, delay = 0) {
-      const events = timelineEvents(input)
-      if (events.length === 1) await transport.send(events[0]!, { marker: describeEvent(events[0]!) })
-      if (events.length > 1)
-        await transport.burst(
-          events,
-          events.map((item) => ({ marker: describeEvent(item) })),
-        )
+    async send(event: TimelineEvent, delay = 0) {
+      const valid = validateTimelineEvent(event)
+      await transport.send(valid, { marker: describeEvent(valid) })
       if (delay) await page.waitForTimeout(delay)
     },
     async sendAll(sequence: { event: TimelineEvent; delay: number }[]) {
       for (const item of sequence) {
-        const events = timelineEvents(item.event)
-        if (events.length === 1) await transport.send(events[0]!, { marker: describeEvent(events[0]!) })
-        if (events.length > 1)
-          await transport.burst(
-            events,
-            events.map((event) => ({ marker: describeEvent(event) })),
-          )
+        const valid = validateTimelineEvent(item.event)
+        await transport.send(valid, { marker: describeEvent(valid) })
         await page.waitForTimeout(item.delay)
       }
     },
@@ -233,63 +210,72 @@ export async function setupTimeline(
       )
     },
     async waitForPart(partID: string) {
-      const part = page.locator(`[data-timeline-part-id="${renderedPartID(partID)}"]`)
+      const part = page.locator(`[data-timeline-part-id="${partID}"]`)
       await expect(part).toHaveCount(1)
       await expect(part).toBeVisible()
     },
   }
 }
 
-function timelineEvents(input: TimelineEvent) {
-  return (Array.isArray(input) ? input : [input]).map(validateTimelineEvent)
-}
-
-function describeEvent(event: OpenCodeEvent) {
-  if (event.type.startsWith("session.tool.")) {
-    const data = event.data as { id?: string }
-    return [event.type, data.id].filter(Boolean).join(":")
+function describeEvent(event: EventPayload) {
+  if (event.payload.type === "message.part.updated") {
+    const part = event.payload.properties.part
+    return [
+      event.payload.type,
+      part.id,
+      part.type === "tool" ? part.tool : part.type,
+      part.type === "tool" ? part.state.status : undefined,
+    ]
+      .filter(Boolean)
+      .join(":")
   }
-  return event.type
+  if (event.payload.type === "session.status") {
+    const status = event.payload.properties.status
+    return [event.payload.type, status.type, status.type === "retry" ? status.attempt : undefined]
+      .filter((value) => value !== undefined)
+      .join(":")
+  }
+  return event.payload.type
 }
 
-export function event(
-  type: "session.status",
-  data: Extract<OpenCodeEvent, { type: "session.status" }>["data"],
-): OpenCodeEvent {
-  return makeEvent(type, data)
+export function event<const Type extends TimelinePayload["type"]>(
+  type: Type,
+  properties: Extract<TimelinePayload, { type: Type }>["properties"],
+): TimelineEvent
+export function event(type: TimelinePayload["type"], properties: TimelinePayload["properties"]): TimelineEvent {
+  return validateTimelineEvent({
+    directory,
+    payload: { id: `evt_timeline_${String(++eventSequence).padStart(4, "0")}`, type, properties },
+  })
 }
 
-export function validateTimelineEvent(input: unknown): OpenCodeEvent {
-  if (!input || typeof input !== "object") throw new Error("Timeline event must be an object")
-  if (!("type" in input) || typeof input.type !== "string") throw new Error("Timeline event requires a type")
-  const definition = EventManifest.ServerDefinitions.find((definition) => definition.type === input.type)
-  if (!definition) throw new Error(`Unknown timeline event: ${input.type}`)
-  return Schema.decodeUnknownSync(definition)(input) as OpenCodeEvent
+export function validateTimelineEvent(input: unknown): TimelineEvent {
+  return decodeEvent(input, decodeOptions) as TimelineEvent
 }
 
 export function validateTimelineMessages(input: readonly TimelineMessage[]): TimelineMessage[] {
-  const messages = input.map((message): TimelineMessage => {
-    const decoded = Schema.decodeUnknownSync(SessionMessage.Info)(message)
-    if (decoded.type !== "user" && decoded.type !== "assistant")
-      throw new Error(`Unsupported timeline message type: ${decoded.type}`)
-    return message
-  })
+  input.forEach((message) => decodeMessage(message, decodeOptions))
+  const messages = [...input]
   const messageIDs = new Set<string>()
-  let parentID: string | undefined
+  const partIDs = new Set<string>()
+  const users = new Set(messages.filter((message) => message.info.role === "user").map((message) => message.info.id))
+
   messages.forEach((message) => {
-    if (messageIDs.has(message.id)) throw new Error(`Timeline fixture has duplicate message ID: ${message.id}`)
-    messageIDs.add(message.id)
-    if (message.type === "user") parentID = message.id
-    if (message.type === "assistant") {
-      const expected = typeof message.metadata?.parentID === "string" ? message.metadata.parentID : parentID
-      if (!expected || expected !== parentID)
-        throw new Error(`Timeline assistant ${message.id} must reference a parent user in the fixture`)
-      message.content.forEach((part) => {
-        if (part.type !== "tool") return
-        if (partRefs.has(part.id) && partRefs.get(part.id)?.messageID !== message.id)
-          throw new Error(`Timeline fixture has duplicate part ID: ${part.id}`)
-      })
-    }
+    if (messageIDs.has(message.info.id))
+      throw new Error(`Timeline fixture has duplicate message ID: ${message.info.id}`)
+    messageIDs.add(message.info.id)
+    if (message.info.role === "assistant" && !users.has(message.info.parentID))
+      throw new Error(`Timeline assistant ${message.info.id} must reference a parent user in the fixture`)
+    message.parts.forEach((part) => {
+      if (part.sessionID !== message.info.sessionID || part.messageID !== message.info.id)
+        throw new Error(`Timeline part ${part.id} ownership does not match message ${message.info.id}`)
+      if (message.info.role === "user" && !["text", "file", "agent", "subtask"].includes(part.type))
+        throw new Error(`Timeline user message ${message.info.id} cannot own ${part.type} part ${part.id}`)
+      if (message.info.role === "assistant" && ["agent", "subtask"].includes(part.type))
+        throw new Error(`Timeline assistant message ${message.info.id} cannot own ${part.type} part ${part.id}`)
+      if (partIDs.has(part.id)) throw new Error(`Timeline fixture has duplicate part ID: ${part.id}`)
+      partIDs.add(part.id)
+    })
   })
   return messages
 }
@@ -351,146 +337,55 @@ export function historyMessages(count: number): TimelineMessage[] {
   }).flat()
 }
 
-export function partUpdated(part: PartSeed<"assistant">): readonly OpenCodeEvent[] {
-  const messageID = part.messageID ?? assistantID
-  const started = startedParts.has(part.id)
-  const ref = partRef(part.id, messageID, part.type)
-  if (part.type === "text") {
-    startedParts.add(part.id)
-    return [
-      ...(started
-        ? []
-        : [makeEvent("session.text.started", { sessionID, assistantMessageID: messageID, ordinal: ref.ordinal! })]),
-      makeEvent("session.text.ended", {
-        sessionID,
-        assistantMessageID: messageID,
-        ordinal: ref.ordinal!,
-        text: part.text,
-      }),
-    ]
-  }
-  if (part.type === "reasoning") {
-    startedParts.add(part.id)
-    return [
-      ...(started
-        ? []
-        : [
-            makeEvent("session.reasoning.started", {
-              sessionID,
-              assistantMessageID: messageID,
-              ordinal: ref.ordinal!,
-              state: jsonRecord(part.metadata),
-            }),
-          ]),
-      makeEvent("session.reasoning.ended", {
-        sessionID,
-        assistantMessageID: messageID,
-        ordinal: ref.ordinal!,
-        text: part.text,
-        state: jsonRecord(part.metadata),
-      }),
-    ]
-  }
-  return toolEvents(part, messageID)
-}
-
-export function renderedPartID(partID: string) {
-  const ref = partRefs.get(partID)
-  if (!ref || ref.type === "tool") return partID
-  return `${ref.messageID}:${ref.type}:${ref.ordinal}`
+export function partUpdated(part: Part | PartSeed<"assistant">) {
+  const owned = "messageID" in part ? part : { ...part, sessionID, messageID: assistantID }
+  decodePart(owned, decodeOptions)
+  return event("message.part.updated", {
+    sessionID,
+    part: owned,
+    time: 1700000002000,
+  })
 }
 
 export function partDelta(partID: string, delta: string, messageID = assistantID) {
-  const ref = partRefs.get(partID)
-  if (!ref || ref.type !== "text" || ref.ordinal === undefined) throw new Error(`Unknown text part: ${partID}`)
-  return makeEvent("session.text.delta", {
-    sessionID,
-    assistantMessageID: messageID,
-    ordinal: ref.ordinal,
-    delta,
-  })
+  return event("message.part.delta", { sessionID, messageID, partID, field: "text", delta })
 }
 
-export function messageUpdated(info: SessionMessageAssistant) {
-  if (info.error)
-    return makeEvent("session.step.failed", {
-      sessionID,
-      assistantMessageID: info.id,
-      error: info.error,
-      cost: info.cost,
-      tokens: info.tokens,
-    })
-  return makeEvent("session.step.ended", {
-    sessionID,
-    assistantMessageID: info.id,
-    finish: info.finish ?? "stop",
-    cost: info.cost ?? 0,
-    tokens: info.tokens ?? tokens,
-  })
+export function messageUpdated(info: Message) {
+  return event("message.updated", { sessionID, info })
 }
 
 export function status(type: SessionStatus["type"], attempt = 1) {
-  if (type === "busy") return makeEvent("session.execution.started", { sessionID })
-  if (type === "idle") return makeEvent("session.execution.succeeded", { sessionID })
-  return makeEvent("session.retry.scheduled", {
+  return event("session.status", {
     sessionID,
-    assistantMessageID: assistantID,
-    attempt,
-    at: 1700000010000,
-    error: { type: "provider.error", message: "Rate limited" },
-  })
-}
-
-export function stepStarted(message: SessionMessageAssistant) {
-  return makeEvent("session.step.started", {
-    sessionID,
-    assistantMessageID: message.id,
-    agent: message.agent,
-    model: message.model,
+    status: type === "retry" ? { type, attempt, message: "Rate limited", next: 1700000010000 } : { type },
   })
 }
 
 export function userMessage(
   parts?: PartSeed<"user">[],
-  input: { id?: string; summary?: unknown; created?: number } = {},
-): SessionMessageUser {
+  input: { id?: string; summary?: UserMessage["summary"]; created?: number } = {},
+): Extract<TimelineMessage, { info: { role: "user" } }> {
   const id = input.id ?? userID
   const seeds = parts ?? [userText("Build the timeline stability matrix.", { id: `prt_${id}_text` })]
-  return {
-    id,
-    type: "user",
-    time: { created: input.created ?? 1700000000000 },
-    text: seeds.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n"),
-    files: seeds.flatMap((part) => {
-      if (part.type !== "file") return []
-      const mention = part.source?.text
-        ? { text: part.source.text.value, start: part.source.text.start, end: part.source.text.end }
-        : undefined
-      return [
-        {
-          data: part.url.match(/^data:[^,]*;base64,(.*)$/)?.[1] ?? "",
-          mime: part.mime,
-          source: part.url.startsWith("data:")
-            ? ({ type: "inline" } as const)
-            : ({ type: "uri", uri: part.source?.path ?? part.url } as const),
-          ...(part.filename ? { name: part.filename } : {}),
-          ...(mention ? { mention } : {}),
-        },
-      ]
-    }),
-    agents: seeds.flatMap((part) => {
-      if (part.type !== "agent") return []
-      return [
-        {
-          name: part.name,
-          ...(part.source
-            ? { mention: { text: part.source.value, start: part.source.start, end: part.source.end } }
-            : {}),
-        },
-      ]
-    }),
-    ...(input.summary === undefined ? {} : { metadata: { summary: input.summary as JsonValue } }),
-  }
+  const message = {
+    info: {
+      id,
+      sessionID,
+      role: "user",
+      time: { created: input.created ?? 1700000000000 },
+      summary: input.summary ?? { diffs: [] },
+      agent: "build",
+      model,
+    },
+    parts: seeds.map((part) => ({
+      ...part,
+      sessionID,
+      messageID: id,
+    })),
+  } satisfies Extract<TimelineMessage, { info: { role: "user" } }>
+  decodeMessage(message, decodeOptions)
+  return message
 }
 
 export function assistantMessage(
@@ -499,43 +394,49 @@ export function assistantMessage(
     id?: string
     parentID?: string
     completed?: boolean
-    error?: SessionStructuredError
+    error?: AssistantMessage["error"]
     created?: number
   } = {},
-): SessionMessageAssistant {
-  if (input.error && (typeof input.error.type !== "string" || typeof input.error.message !== "string"))
-    throw new Error("Invalid assistant error")
+): Extract<TimelineMessage, { info: { role: "assistant" } }> {
   const id = input.id ?? assistantID
-  const created = input.created ?? 1700000001000
-  const ordinals = { text: 0, reasoning: 0 }
-  const content = parts.map((part) => messageContent(part, id, ordinals))
-  nextOrdinals.set(id, ordinals)
-  return {
-    id,
-    type: "assistant",
-    metadata: { parentID: input.parentID ?? userID },
-    time: { created, ...(input.completed === false ? {} : { completed: created + 1_000 }) },
-    model: { id: model.modelID, providerID: model.providerID, variant: model.variant },
-    agent: "build",
-    content,
-    cost: 0.01,
-    tokens,
-    ...(input.completed === false ? {} : { finish: "stop" as const }),
-    ...(input.error ? { error: input.error } : {}),
-  }
+  const message = {
+    info: {
+      id,
+      sessionID,
+      role: "assistant",
+      time: {
+        created: input.created ?? 1700000001000,
+        ...(input.completed === false ? {} : { completed: (input.created ?? 1700000001000) + 1_000 }),
+      },
+      parentID: input.parentID ?? userID,
+      modelID: model.modelID,
+      providerID: model.providerID,
+      mode: "build",
+      agent: "build",
+      path: { cwd: directory, root: directory },
+      cost: 0.01,
+      tokens: { input: 100, output: 200, reasoning: 0, cache: { read: 0, write: 0 } },
+      variant: "max",
+      ...(input.error ? { error: input.error } : {}),
+    },
+    parts: parts.map((part) => ({ ...part, sessionID, messageID: id })),
+  } satisfies Extract<TimelineMessage, { info: { role: "assistant" } }>
+  decodeMessage(message, decodeOptions)
+  return message
 }
 
-export function userText(text: string, input: Partial<Omit<TextSeed, "type" | "text">> = {}): TextSeed {
+export function userText(
+  text: string,
+  input: Partial<Omit<Extract<PartSeed<"user">, { type: "text" }>, "type" | "text">> = {},
+): Extract<PartSeed<"user">, { type: "text" }> {
   return { id: "prt_user_text", type: "text", text, ...input }
 }
 
-export function textPart(id: string, text: string): TextSeed {
-  partRef(id, assistantID, "text")
+export function textPart(id: string, text: string): Extract<PartSeed<"assistant">, { type: "text" }> {
   return { id, type: "text", text }
 }
 
-export function reasoningPart(id: string, text: string): ReasoningSeed {
-  partRef(id, assistantID, "reasoning")
+export function reasoningPart(id: string, text: string): Extract<PartSeed<"assistant">, { type: "reasoning" }> {
   return { id, type: "reasoning", text, time: { start: 1700000001000 } }
 }
 
@@ -545,35 +446,35 @@ export function toolPart(
   state: "pending",
   input: Record<string, unknown>,
   options?: ToolOptions<"pending">,
-): ToolSeed
+): Omit<ToolPart, "sessionID" | "messageID">
 export function toolPart(
   id: string,
   tool: string,
   state: "running",
   input: Record<string, unknown>,
   options?: ToolOptions<"running">,
-): ToolSeed
+): Omit<ToolPart, "sessionID" | "messageID">
 export function toolPart(
   id: string,
   tool: string,
   state: "completed",
   input: Record<string, unknown>,
   options?: ToolOptions<"completed">,
-): ToolSeed
+): Omit<ToolPart, "sessionID" | "messageID">
 export function toolPart(
   id: string,
   tool: string,
   state: "error",
   input: Record<string, unknown>,
   options?: ToolOptions<"error">,
-): ToolSeed
+): Omit<ToolPart, "sessionID" | "messageID">
 export function toolPart(
   id: string,
   tool: string,
   state: ToolStatus,
   input: Record<string, unknown>,
   options: ToolOptions<ToolStatus> = {},
-): ToolSeed {
+): Omit<ToolPart, "sessionID" | "messageID"> {
   const base = { id, type: "tool" as const, callID: id, tool }
   if (state === "pending") return { ...base, state: { status: state, input, raw: "" } }
   if (state === "running")
@@ -611,7 +512,12 @@ export function toolPart(
   }
 }
 
-export function shell(id: string, state: ToolStatus, output = "", command = `echo ${id}`): ToolSeed {
+export function shell(
+  id: string,
+  state: ToolStatus,
+  output = "",
+  command = `echo ${id}`,
+): Omit<ToolPart, "sessionID" | "messageID"> {
   if (state === "pending") return toolPart(id, "bash", state, { command })
   if (state === "running")
     return toolPart(id, "bash", state, { command }, { title: command, metadata: { command, output } })
@@ -620,7 +526,7 @@ export function shell(id: string, state: ToolStatus, output = "", command = `ech
   return toolPart(id, "bash", state, { command }, { title: command, output, metadata: { command, output } })
 }
 
-export function completedAssistantInfo(info: SessionMessageAssistant): SessionMessageAssistant {
+export function completedAssistantInfo(info: AssistantMessage): AssistantMessage {
   return { ...info, time: { ...info.time, completed: 1700000003000 } }
 }
 
@@ -648,200 +554,16 @@ export function session(input: Partial<Session> = {}): Session {
   }
 }
 
-function messageContent(
-  part: PartSeed<"assistant">,
-  messageID: string,
-  ordinals: { text: number; reasoning: number },
-): SessionMessageAssistant["content"][number] {
-  if (part.type === "tool") {
-    partRefs.set(part.id, { messageID, type: part.type })
-    toolStates.set(part.callID, part.state.status)
-  } else {
-    partRefs.set(part.id, { messageID, type: part.type, ordinal: ordinals[part.type]++ })
-    startedParts.add(part.id)
-  }
-  if (part.type === "text") return { type: "text", text: part.text }
-  if (part.type === "reasoning")
-    return {
-      type: "reasoning",
-      text: part.text,
-      state: jsonRecord(part.metadata),
-      time: part.time
-        ? { created: part.time.start, ...(part.time.end === undefined ? {} : { completed: part.time.end }) }
-        : undefined,
-    }
-  const state = part.state
-  const time = "time" in state ? state.time : undefined
-  const completed = state.status === "completed" || state.status === "error" ? state.time.end : undefined
-  const base = {
-    type: "tool" as const,
-    id: part.callID,
-    name: part.tool,
-    time: {
-      created: time?.start ?? 1700000001000,
-      ...(time?.start === undefined ? {} : { ran: time.start }),
-      ...(completed === undefined ? {} : { completed }),
-    },
-    ...(part.executed === undefined ? {} : { executed: part.executed }),
-    ...(part.providerState ? { providerState: jsonRecord(part.providerState) } : {}),
-    ...(part.providerResultState ? { providerResultState: jsonRecord(part.providerResultState) } : {}),
-  }
-  if (state.status === "pending") return { ...base, state: { status: "streaming", input: state.raw } }
-  if (state.status === "running")
-    return {
-      ...base,
-      state: { status: "running", input: jsonRecord(state.input), metadata: jsonRecord(state.metadata) },
-    }
-  if (state.status === "error")
-    return {
-      ...base,
-      state: {
-        status: "error",
-        input: jsonRecord(state.input),
-        error: { type: "ToolError", message: state.error },
-        metadata: jsonRecord(state.metadata),
-      },
-    }
-  return {
-    ...base,
-    state: {
-      status: "completed",
-      input: jsonRecord(state.input),
-      content: [{ type: "text", text: state.output }],
-      metadata: jsonRecord(state.metadata),
-    },
-  }
-}
-
-function toolEvents(part: ToolSeed, messageID: string): readonly OpenCodeEvent[] {
-  const previous = toolStates.get(part.callID)
-  if (previous === "completed" || previous === "error") return []
-
-  const events: OpenCodeEvent[] = []
-  if (!previous) {
-    events.push(
-      makeEvent("session.tool.input.started", {
-        sessionID,
-        assistantMessageID: messageID,
-        id: part.callID,
-        name: part.tool,
-      }),
-    )
-  }
-  if (part.state.status === "pending") {
-    toolStates.set(part.callID, part.state.status)
-    return events
-  }
-  if (!previous || previous === "pending") {
-    events.push(
-      makeEvent("session.tool.input.ended", {
-        sessionID,
-        assistantMessageID: messageID,
-        id: part.callID,
-        text: JSON.stringify(part.state.input),
-      }),
-      makeEvent("session.tool.called", {
-        sessionID,
-        assistantMessageID: messageID,
-        id: part.callID,
-        input: part.state.input,
-        executed: part.executed ?? true,
-        state: jsonRecord(part.providerState),
-      }),
-    )
-  }
-  if (part.state.status === "running") {
-    if (previous === "running" || Object.keys(part.state.metadata).length)
-      events.push(
-        makeEvent("session.tool.progress", {
-          sessionID,
-          assistantMessageID: messageID,
-          id: part.callID,
-          metadata: jsonRecord(part.state.metadata),
-        }),
-      )
-    toolStates.set(part.callID, part.state.status)
-    return events
-  }
-  if (part.state.status === "error") {
-    events.push(
-      makeEvent("session.tool.failed", {
-        sessionID,
-        assistantMessageID: messageID,
-        id: part.callID,
-        error: { type: "ToolError", message: part.state.error },
-        metadata: jsonRecord(part.state.metadata),
-        executed: part.executed ?? true,
-        resultState: jsonRecord(part.providerResultState),
-      }),
-    )
-    toolStates.set(part.callID, part.state.status)
-    return events
-  }
-  events.push(
-    makeEvent("session.tool.success", {
-      sessionID,
-      assistantMessageID: messageID,
-      id: part.callID,
-      content: [{ type: "text", text: part.state.output }],
-      metadata: jsonRecord(part.state.metadata),
-      executed: part.executed ?? true,
-      resultState: jsonRecord(part.providerResultState),
-    }),
-  )
-  toolStates.set(part.callID, part.state.status)
-  return events
-}
-
-function partRef(id: string, messageID: string, type: PartRef["type"]): PartRef {
-  const current = partRefs.get(id)
-  if (current) return current
-  if (type === "tool") {
-    const ref = { messageID, type } satisfies PartRef
-    partRefs.set(id, ref)
-    return ref
-  }
-  const next = nextOrdinals.get(messageID) ?? { text: 0, reasoning: 0 }
-  const ref = { messageID, type, ordinal: next[type]++ } satisfies PartRef
-  nextOrdinals.set(messageID, next)
-  partRefs.set(id, ref)
-  return ref
-}
-
-function makeEvent<Type extends OpenCodeEvent["type"]>(
-  type: Type,
-  data: Extract<OpenCodeEvent, { type: Type }>["data"],
-): OpenCodeEvent {
-  const id = `evt_timeline_${String(++eventSequence).padStart(4, "0")}`
-  const base = { id, created: 1700000002000 + eventSequence, type, data, location: { directory } }
-  const definition = EventManifest.ServerDefinitions.find((definition) => definition.type === type)
-  if (!definition) throw new Error(`Unknown timeline event: ${type}`)
-  const input =
-    definition.durability === "durable"
-      ? {
-          ...base,
-          durable: { aggregateID: sessionID, seq: ++durableSequence, version: definition.durable.version },
-        }
-      : base
-  return Schema.decodeUnknownSync(definition)(input) as unknown as OpenCodeEvent
-}
-
-function jsonRecord(value: Record<string, unknown> | undefined): Record<string, JsonValue> {
-  if (!value) return {}
-  return Object.fromEntries(
-    Object.entries(value).flatMap(([key, item]) => {
-      const next = jsonValue(item)
-      return next === undefined ? [] : [[key, next]]
-    }),
-  )
-}
-
-function jsonValue(value: unknown): JsonValue | undefined {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return value
-  if (typeof value === "number") return Number.isFinite(value) ? value : null
-  if (Array.isArray(value)) return value.map((item) => jsonValue(item) ?? null)
-  if (!value || typeof value !== "object") return
-  return jsonRecord(value as Record<string, unknown>)
+function eventSchema<
+  const Type extends TimelinePayload["type"],
+  const Properties extends Schema.Codec<unknown, unknown>,
+>(type: Type, properties: Properties) {
+  return Schema.Struct({
+    directory: Schema.String,
+    project: Schema.optional(Schema.String),
+    workspace: Schema.optional(Schema.String),
+    payload: Schema.Struct({ id: Event.ID, type: Schema.Literal(type), properties }),
+  })
 }
 
 function provider() {

packages/app/e2e/performance/timeline-stability/interaction.spec.ts

@@ -6,16 +6,7 @@ import {
   stopVisualProbe,
   visualPlan,
 } from "../../utils/visual-stability"
-import {
-  assistantMessage,
-  renderedPartID,
-  setupTimeline,
-  shell,
-  textPart,
-  toolPart,
-  userMessage,
-  waitForVisualSettle,
-} from "./fixture"
+import { assistantMessage, setupTimeline, shell, textPart, toolPart, userMessage, waitForVisualSettle } from "./fixture"
 
 test("expands and collapses a long completed shell without overlap", async ({ page }, testInfo) => {
   const shellID = "prt_interaction_01_shell"
@@ -29,20 +20,11 @@ test("expands and collapses a long completed shell without overlap", async ({ pa
     cpuRate: 4,
     seedHistory: true,
   })
-  const trigger = page.locator(`[data-timeline-part-id="${renderedPartID(shellID)}"] [data-slot="collapsible-trigger"]`)
-  await waitForVisualSettle(page, [
-    `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-    `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-  ])
+  const trigger = page.locator(`[data-timeline-part-id="${shellID}"] [data-slot="collapsible-trigger"]`)
+  await waitForVisualSettle(page, [`[data-timeline-part-id="${shellID}"]`, `[data-timeline-part-id="${followingID}"]`])
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   const plan = visualPlan(regions, [
     { type: "required", regions: ["shell", "following"] },
@@ -94,7 +76,7 @@ test("expands and collapses a completed context group without overlap", async ({
     seedHistory: true,
   })
   const trigger = page.locator(`${group} [data-slot="collapsible-trigger"]`)
-  await waitForVisualSettle(page, [group, `[data-timeline-part-id="${renderedPartID(followingID)}"]`])
+  await waitForVisualSettle(page, [group, `[data-timeline-part-id="${followingID}"]`])
   for (const [name, expanded] of [
     ["context-expand", true],
     ["context-collapse", false],
@@ -103,7 +85,7 @@ test("expands and collapses a completed context group without overlap", async ({
     const regions = defineVisualRegions({
       context: { selector: group, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })
@@ -162,22 +144,11 @@ test("expands and collapses an edit diff without moving twice", async ({ page },
     cpuRate: 4,
     seedHistory: true,
   })
-  const trigger = page
-    .locator(`[data-timeline-part-id="${renderedPartID(editID)}"] [data-slot="collapsible-trigger"]`)
-    .first()
-  await waitForVisualSettle(page, [
-    `[data-timeline-part-id="${renderedPartID(editID)}"]`,
-    `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-  ])
+  const trigger = page.locator(`[data-timeline-part-id="${editID}"] [data-slot="collapsible-trigger"]`).first()
+  await waitForVisualSettle(page, [`[data-timeline-part-id="${editID}"]`, `[data-timeline-part-id="${followingID}"]`])
   const regions = defineVisualRegions({
-    edit: {
-      selector: `[data-timeline-part-id="${renderedPartID(editID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    edit: { selector: `[data-timeline-part-id="${editID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await trigger.click()
@@ -202,6 +173,64 @@ test("expands and collapses an edit diff without moving twice", async ({ page },
   )
 })
 
+test("shows all and expands historical diff summary without overlap", async ({ page }, testInfo) => {
+  const firstUser = userMessage(undefined, {
+    summary: {
+      diffs: Array.from({ length: 12 }, (_, index) => ({
+        file: `src/diff-${index}.ts`,
+        status: "modified",
+        additions: 1,
+        deletions: 1,
+        patch: `@@ -1 +1 @@\n-export const value = ${index}\n+export const value = ${index + 1}`,
+      })),
+    },
+  })
+  const nextUserID = "msg_2000_diff_interaction_user"
+  await setupTimeline(page, {
+    messages: [
+      firstUser,
+      assistantMessage(),
+      userMessage(undefined, { id: nextUserID, created: 1700000010000 }),
+      assistantMessage([], {
+        id: "msg_2001_diff_interaction_assistant",
+        parentID: nextUserID,
+        created: 1700000011000,
+      }),
+    ],
+    cpuRate: 4,
+  })
+  const scroller = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
+  await scroller.evaluate((element) => (element.scrollTop = 0))
+  const diff = page.locator('[data-timeline-row="DiffSummary"]')
+  const following = page.locator(`[data-message-id="${nextUserID}"]`).first()
+  await expect(diff).toBeVisible()
+  const regions = defineVisualRegions({
+    diff: { selector: '[data-timeline-row="DiffSummary"]' },
+    following: { selector: `[data-message-id="${nextUserID}"]` },
+  })
+  await startVisualProbe(page, regions)
+  await page.getByText(/show all/i).click()
+  await page.waitForTimeout(500)
+  await diff.locator('[data-slot="session-turn-diff-trigger"]').first().click()
+  await page.waitForTimeout(900)
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(
+    testInfo,
+    "diff-summary-expand",
+    trace,
+    visualPlan(regions, [
+      { type: "required", regions: ["diff", "following"] },
+      { type: "unique", regions: ["diff", "following"] },
+      { type: "stable", regions: ["diff", "following"] },
+      { type: "opacity", regions: "all" },
+      { type: "continuity", regions: "all" },
+      { type: "motion", regions: "all", maxPositionReversals: 1, maxReversals: 2 },
+      { type: "label-stability", regions: "all" },
+      { type: "flow", regions: ["diff", "following"] },
+    ]),
+  )
+})
+
 function lines(count: number) {
   return Array.from({ length: count }, (_, index) => `line ${index + 1}`).join("\n")
 }

packages/app/e2e/performance/timeline-stability/lifecycle.spec.ts

@@ -14,7 +14,6 @@ import {
   partDelta,
   partUpdated,
   reasoningPart,
-  renderedPartID,
   setupTimeline,
   shell,
   status,
@@ -51,7 +50,7 @@ test.describe("timeline visual lifecycle stability", () => {
       prt_shell_long: shellRegion(ids[2]),
       following: shellRegion(followingID),
     })
-    await waitForVisualSettle(page, [`[data-timeline-part-id="${renderedPartID(followingID)}"]`])
+    await waitForVisualSettle(page, [`[data-timeline-part-id="${followingID}"]`])
     await startVisualProbe(page, regions)
     await timeline.sendAll([
       { event: partUpdated(shell(ids[0]!, "completed", "")), delay: 180 },
@@ -61,7 +60,7 @@ test.describe("timeline visual lifecycle stability", () => {
       { event: partUpdated(shell(ids[1]!, "completed", lines(2))), delay: 260 },
       { event: partUpdated(shell(ids[2]!, "running", lines(50))), delay: 100 },
       { event: partUpdated(shell(ids[2]!, "completed", lines(50))), delay: 450 },
-      { event: messageUpdated(completedAssistantInfo(assistant)), delay: 100 },
+      { event: messageUpdated(completedAssistantInfo(assistant.info)), delay: 100 },
       { event: status("idle"), delay: 700 },
     ])
     const trace = await stopVisualProbe<keyof typeof regions>(page)
@@ -85,11 +84,9 @@ test.describe("timeline visual lifecycle stability", () => {
         { perMarker: true },
       ),
     )
-    await expect(
-      page.locator(`[data-timeline-part-id="${renderedPartID(ids[2])}"] [data-slot="bash-pre"]`),
-    ).toContainText("line 50")
+    await expect(page.locator(`[data-timeline-part-id="${ids[2]}"] [data-slot="bash-pre"]`)).toContainText("line 50")
 
-    const short = page.locator(`[data-timeline-part-id="${renderedPartID(ids[1])}"]`)
+    const short = page.locator(`[data-timeline-part-id="${ids[1]}"]`)
     await short.locator('[data-slot="collapsible-trigger"]').click()
     await expect(short.locator('[data-slot="collapsible-trigger"]')).toHaveAttribute("aria-expanded", "false")
     await timeline.send(partUpdated(textPart("prt_late_sibling", "A later sibling rerender.")), 250)
@@ -109,31 +106,26 @@ test.describe("timeline visual lifecycle stability", () => {
     })
     await timeline.send(status("busy"), 120)
     await expect(page.locator('[data-timeline-row="Thinking"]')).toBeVisible()
-    const initialReasoning = reasoningPart(reasoningID, "")
-    const initialText = textPart(textID, "Starting")
 
     const regions = defineVisualRegions({
       thinking: { selector: '[data-timeline-row="Thinking"]' },
       reasoning: {
-        selector: `[data-timeline-part-id="${renderedPartID(reasoningID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
-      text: {
-        selector: `[data-timeline-part-id="${renderedPartID(textID)}"]`,
+        selector: `[data-timeline-part-id="${reasoningID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
+      text: { selector: `[data-timeline-part-id="${textID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
     })
     await startVisualProbe(page, regions)
-    await timeline.send(partUpdated(initialReasoning), 100)
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(reasoningID)}"]`)).toHaveCount(0)
+    await timeline.send(partUpdated(reasoningPart(reasoningID, "")), 100)
+    await expect(page.locator(`[data-timeline-part-id="${reasoningID}"]`)).toHaveCount(0)
     await timeline.send(partUpdated(reasoningPart(reasoningID, "## Planning\n\nChecking the visible timeline.")), 160)
     await timeline.waitForPart(reasoningID)
     await expect(page.locator('[data-timeline-row="Thinking"]')).toHaveCount(0)
-    await timeline.send(partUpdated(initialText), 100)
+    await timeline.send(partUpdated(textPart(textID, "Starting")), 100)
     await timeline.send(partDelta(textID, " **stable"), 90)
     await timeline.send(partDelta(textID, " output** with `code` and [a link"), 130)
     await timeline.send(partDelta(textID, "](https://example.com)."), 220)
-    await timeline.send(messageUpdated(completedAssistantInfo(assistant)), 120)
+    await timeline.send(messageUpdated(completedAssistantInfo(assistant.info)), 120)
     await timeline.send(status("idle"), 500)
     const trace = await stopVisualProbe<keyof typeof regions>(page)
     await reportVisualStability(
@@ -152,7 +144,7 @@ test.describe("timeline visual lifecycle stability", () => {
         { type: "flow", regions: ["reasoning", "text"] },
       ]),
     )
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(textID)}"]`)).toContainText("stable output")
+    await expect(page.locator(`[data-timeline-part-id="${textID}"]`)).toContainText("stable output")
   })
 })
 
@@ -161,5 +153,5 @@ function lines(count: number) {
 }
 
 function shellRegion(id: string) {
-  return { selector: `[data-timeline-part-id="${renderedPartID(id)}"]`, closest: '[data-timeline-row="AssistantPart"]' }
+  return { selector: `[data-timeline-part-id="${id}"]`, closest: '[data-timeline-row="AssistantPart"]' }
 }

packages/app/e2e/performance/timeline-stability/oracle-browser.spec.ts

@@ -6,14 +6,14 @@ import {
   stopVisualProbe,
   visualPlan,
 } from "../../utils/visual-stability"
-import { assistantMessage, renderedPartID, setupTimeline, textPart, userMessage } from "./fixture"
+import { assistantMessage, setupTimeline, textPart, userMessage } from "./fixture"
 
 test("detects blanking caused by ancestor opacity", async ({ page }) => {
   const partID = "prt_oracle_ancestor_opacity"
   await setupTimeline(page, { messages: [userMessage(), assistantMessage([textPart(partID, "Visible content")])] })
-  const row = page.locator(`[data-timeline-part-id="${renderedPartID(partID)}"]`).first()
+  const row = page.locator(`[data-timeline-part-id="${partID}"]`).first()
   const regions = defineVisualRegions({
-    content: { selector: `[data-timeline-part-id="${renderedPartID(partID)}"]` },
+    content: { selector: `[data-timeline-part-id="${partID}"]` },
   })
   await startVisualProbe(page, regions)
   await row.evaluate((element) => {
@@ -41,13 +41,13 @@ test("detects blanking caused by ancestor opacity", async ({ page }) => {
 test("detects root opacity when probing descendant opacity", async ({ page }) => {
   const partID = "prt_oracle_descendant_opacity"
   await setupTimeline(page, { messages: [userMessage(), assistantMessage([textPart(partID, "Visible content")])] })
-  const row = page.locator(`[data-timeline-part-id="${renderedPartID(partID)}"]`).first()
+  const row = page.locator(`[data-timeline-part-id="${partID}"]`).first()
   await row.evaluate((element) => {
     element.innerHTML = '<span data-probe-opacity="true">Visible content</span>'
   })
   const regions = defineVisualRegions({
     content: {
-      selector: `[data-timeline-part-id="${renderedPartID(partID)}"]`,
+      selector: `[data-timeline-part-id="${partID}"]`,
       opacitySelectors: ['[data-probe-opacity="true"]'],
     },
   })

packages/app/e2e/performance/timeline-stability/scroll-interaction.spec.ts

@@ -9,7 +9,6 @@ import {
 import {
   assistantMessage,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   shell,
   textPart,
@@ -35,14 +34,8 @@ test("does not reverse visible rows when the user wheels during shell remeasurem
   })
   const scroller = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await timeline.send(partUpdated(shell(shellID, "running", lines(30))), 80)
@@ -150,8 +143,8 @@ test("tracks keyboard scrolling from a focused timeline descendant", async ({ pa
     reducedMotion: true,
   })
   const scroller = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
-  const row = page.locator(`[data-timeline-part-id="${renderedPartID(shellID)}"]`).first()
-  const trigger = page.locator(`[data-timeline-part-id="${renderedPartID(shellID)}"] [data-slot="collapsible-trigger"]`)
+  const row = page.locator(`[data-timeline-part-id="${shellID}"]`).first()
+  const trigger = page.locator(`[data-timeline-part-id="${shellID}"] [data-slot="collapsible-trigger"]`)
   await row.evaluate((element) => element.setAttribute("tabindex", "0"))
   await row.focus()
   for (let index = 0; index < 3; index++) {
@@ -189,7 +182,7 @@ test("does not claim keyboard scrolling owned by a nested scrollable", async ({
     seedHistory: true,
   })
   const scroller = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
-  const nested = page.locator(`[data-timeline-part-id="${renderedPartID(shellID)}"] [data-scrollable]`)
+  const nested = page.locator(`[data-timeline-part-id="${shellID}"] [data-scrollable]`)
   await nested.evaluate((element) => (element.scrollTop = element.scrollHeight))
   await nested.focus()
   await page.waitForFunction(() => {
@@ -216,7 +209,7 @@ test("does not claim keyboard scrolling owned by a nested scrollable", async ({
   await nested.press("PageUp")
   await expect.poll(() => scroller.evaluate((element) => element.scrollTop)).toBeLessThan(boundaryBefore)
 
-  const nonOverflowing = page.locator(`[data-timeline-part-id="${renderedPartID(shellID)}"]`).first()
+  const nonOverflowing = page.locator(`[data-timeline-part-id="${shellID}"]`).first()
   await nonOverflowing.evaluate((element) => {
     element.setAttribute("data-scrollable", "")
     element.setAttribute("tabindex", "0")
@@ -245,18 +238,12 @@ test("jump to latest lands on stable final rows after offscreen growth", async (
   )
   await timeline.send(partUpdated(shell(shellID, "running", lines(50))), 300)
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await page.getByRole("button", { name: /Jump to latest/i }).click()
-  await expect(page.locator(`[data-timeline-part-id="${renderedPartID(followingID)}"]`)).toBeVisible()
+  await expect(page.locator(`[data-timeline-part-id="${followingID}"]`)).toBeVisible()
   await page.waitForTimeout(600)
   const trace = await stopVisualProbe<keyof typeof regions>(page)
   await reportVisualStability(
@@ -290,14 +277,8 @@ test("handles a single row taller than the viewport", async ({ page }, testInfo)
     seedHistory: true,
   })
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await timeline.send(partUpdated(shell(shellID, "completed", lines(100))), 700)

packages/app/e2e/performance/timeline-stability/shell-matrix.spec.ts

@@ -9,7 +9,6 @@ import {
 import {
   assistantMessage,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   shell,
   textPart,
@@ -69,16 +68,13 @@ for (const profile of profiles) {
     const scroller = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
     await scroller.evaluate((element) => (element.scrollTop = element.scrollHeight))
     await waitForVisualSettle(page, [
-      `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+      `[data-timeline-part-id="${shellID}"]`,
+      `[data-timeline-part-id="${followingID}"]`,
     ])
     const regions = defineVisualRegions({
-      shell: {
-        selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-        closest: '[data-timeline-row="AssistantPart"]',
-      },
+      shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+        selector: `[data-timeline-part-id="${followingID}"]`,
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })
@@ -124,19 +120,10 @@ test("keeps following row stable when a collapsed shell receives 50 lines", asyn
     cpuRate: 4,
     seedHistory: true,
   })
-  await waitForVisualSettle(page, [
-    `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-    `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-  ])
+  await waitForVisualSettle(page, [`[data-timeline-part-id="${shellID}"]`, `[data-timeline-part-id="${followingID}"]`])
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await timeline.send(partUpdated(shell(shellID, "running", lines(50))), 240)
@@ -177,19 +164,10 @@ test("keeps rows stable when a running shell becomes an error", async ({ page },
     cpuRate: 4,
     seedHistory: true,
   })
-  await waitForVisualSettle(page, [
-    `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-    `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-  ])
+  await waitForVisualSettle(page, [`[data-timeline-part-id="${shellID}"]`, `[data-timeline-part-id="${followingID}"]`])
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await timeline.send(
@@ -237,20 +215,16 @@ test("keeps rows stable when later text arrives before shell output", async ({ p
     cpuRate: 4,
     seedHistory: true,
   })
-  const following = textPart(followingID, "Later assistant content arrived before shell output.")
-  await waitForVisualSettle(page, [`[data-timeline-part-id="${renderedPartID(shellID)}"]`])
+  await waitForVisualSettle(page, [`[data-timeline-part-id="${shellID}"]`])
   const regions = defineVisualRegions({
-    shell: {
-      selector: `[data-timeline-part-id="${renderedPartID(shellID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    shell: { selector: `[data-timeline-part-id="${shellID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
     following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
+      selector: `[data-timeline-part-id="${followingID}"]`,
       closest: '[data-timeline-row="AssistantPart"]',
     },
   })
   await startVisualProbe(page, regions)
-  await timeline.send(partUpdated(following), 240)
+  await timeline.send(partUpdated(textPart(followingID, "Later assistant content arrived before shell output.")), 240)
   await timeline.send(partUpdated(shell(shellID, "running", lines(20))), 300)
   await timeline.send(partUpdated(shell(shellID, "completed", lines(20))), 600)
   const trace = await stopVisualProbe<keyof typeof regions>(page)

packages/app/e2e/performance/timeline-stability/tool-mutation.spec.ts

@@ -11,8 +11,8 @@ import {
   partUpdated,
   session,
   sessionID,
-  renderedPartID,
   setupTimeline,
+  textPart,
   toolPart,
   userMessage,
 } from "./fixture"
@@ -27,7 +27,7 @@ test("adds a task child-session link without replacing the task row", async ({ p
     cpuRate: 4,
   })
   const regions = defineVisualRegions({
-    task: { selector: `[data-timeline-part-id="${renderedPartID(taskID)}"] [data-slot="collapsible-trigger"]` },
+    task: { selector: `[data-timeline-part-id="${taskID}"] [data-slot="collapsible-trigger"]` },
   })
   await startVisualProbe(page, regions)
   await timeline.send(
@@ -53,3 +53,54 @@ test("adds a task child-session link without replacing the task row", async ({ p
     page.locator(`a[href$="/session/${childID}"]`, { has: page.locator('[data-component="task-tool-card"]') }),
   ).toBeVisible()
 })
+
+test("changes generic tool arguments without replacing the row", async ({ page }, testInfo) => {
+  const toolID = "prt_generic_mutation"
+  const followingID = "prt_generic_mutation_following"
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(),
+      assistantMessage(
+        [
+          toolPart(toolID, "mcp_probe", "running", { target: "one", count: 1 }),
+          textPart(followingID, "Following generic tool"),
+        ],
+        { completed: false },
+      ),
+    ],
+    cpuRate: 4,
+  })
+  const regions = defineVisualRegions({
+    tool: { selector: `[data-timeline-part-id="${toolID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+  })
+  await startVisualProbe(page, regions)
+  await timeline.send(
+    partUpdated(toolPart(toolID, "mcp_probe", "running", { target: "two", count: 2, mode: "deep" })),
+    200,
+  )
+  await timeline.send(
+    partUpdated(toolPart(toolID, "mcp_probe", "completed", { target: "two", count: 2, mode: "deep" })),
+    400,
+  )
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(
+    testInfo,
+    "generic-mutation",
+    trace,
+    visualPlan(
+      regions,
+      [
+        { type: "required", regions: ["tool", "following"] },
+        { type: "unique", regions: ["tool", "following"] },
+        { type: "stable", regions: ["tool", "following"] },
+        { type: "opacity", regions: "all" },
+        { type: "continuity", regions: "all" },
+        { type: "motion", regions: "all", maxPositionReversals: 0 },
+        { type: "label-stability", regions: "all" },
+        { type: "flow", regions: ["tool", "following"] },
+      ],
+      { perMarker: true },
+    ),
+  )
+})

packages/app/e2e/performance/timeline-stability/tools.spec.ts

@@ -12,7 +12,6 @@ import {
   partUpdated,
   session,
   sessionID,
-  renderedPartID,
   setupTimeline,
   status,
   textPart,
@@ -49,8 +48,8 @@ test.describe("timeline tool state stability", () => {
     })
     await timeline.send(status("busy"), 120)
     for (const id of ids) await timeline.waitForPart(`prt_state_${id}`)
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(questionID)}"]`)).toHaveCount(0)
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(todoID)}"]`)).toHaveCount(0)
+    await expect(page.locator(`[data-timeline-part-id="${questionID}"]`)).toHaveCount(0)
+    await expect(page.locator(`[data-timeline-part-id="${todoID}"]`)).toHaveCount(0)
 
     const regionIDs = [
       "prt_state_webfetch",
@@ -105,10 +104,8 @@ test.describe("timeline tool state stability", () => {
         { type: "label-stability", regions: "all" },
       ]),
     )
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(questionID)}"]`)).toContainText(
-      "Keep it stable",
-    )
-    await expect(page.locator(`[data-timeline-part-id="${renderedPartID(todoID)}"]`)).toHaveCount(0)
+    await expect(page.locator(`[data-timeline-part-id="${questionID}"]`)).toContainText("Keep it stable")
+    await expect(page.locator(`[data-timeline-part-id="${todoID}"]`)).toHaveCount(0)
     await expect(
       page.locator(`a[href$="/session/${childID}"]`, { has: page.locator('[data-component="task-tool-card"]') }),
     ).toBeVisible()
@@ -148,7 +145,7 @@ test.describe("timeline tool state stability", () => {
       },
       context: { selector: groupSelector, closest: '[data-timeline-row="AssistantPart"]' },
       following: {
-        selector: `[data-timeline-part-id="${renderedPartID("prt_ctx_following")}"]`,
+        selector: '[data-timeline-part-id="prt_ctx_following"]',
         closest: '[data-timeline-row="AssistantPart"]',
       },
     })
@@ -197,5 +194,5 @@ function questionInput() {
 }
 
 function toolRegion(id: string) {
-  return { selector: `[data-timeline-part-id="${renderedPartID(id)}"]`, closest: '[data-timeline-row="AssistantPart"]' }
+  return { selector: `[data-timeline-part-id="${id}"]`, closest: '[data-timeline-row="AssistantPart"]' }
 }

packages/app/e2e/performance/timeline-stability/transition-matrix.spec.ts

@@ -7,13 +7,13 @@ import {
   visualPlan,
 } from "../../utils/visual-stability"
 import {
+  assistantID,
   assistantMessage,
   completedAssistantInfo,
   event,
   messageUpdated,
   partDelta,
   partUpdated,
-  renderedPartID,
   setupTimeline,
   shell,
   status,
@@ -22,6 +22,35 @@ import {
   userMessage,
 } from "./fixture"
 
+test("keeps unchanged siblings stable while a middle part is inserted and removed", async ({ page }, testInfo) => {
+  const firstID = "prt_mutation_01_first"
+  const middleID = "prt_mutation_02_middle"
+  const lastID = "prt_mutation_03_last"
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(),
+      assistantMessage([textPart(firstID, "First stable row"), textPart(lastID, "Last stable row")], {
+        completed: false,
+      }),
+    ],
+    cpuRate: 4,
+  })
+  const regions = defineVisualRegions({
+    first: { selector: `[data-timeline-part-id="${firstID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    last: { selector: `[data-timeline-part-id="${lastID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+  })
+  await startVisualProbe(page, regions)
+  await timeline.send(partUpdated(textPart(middleID, "Inserted middle row. ".repeat(12))), 350)
+  await expect(page.locator(`[data-timeline-part-id="${middleID}"]`)).toBeVisible()
+  await timeline.send(
+    event("message.part.removed", { sessionID: "ses_timeline_stability", messageID: assistantID, partID: middleID }),
+    500,
+  )
+  await expect(page.locator(`[data-timeline-part-id="${middleID}"]`)).toHaveCount(0)
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(testInfo, "middle-insert-remove", trace, stablePairPlan(regions, 1))
+})
+
 test("streams text through growth, canonical replacement, and completion", async ({ page }, testInfo) => {
   const textID = "prt_text_reconcile"
   const followingID = "prt_text_reconcile_following"
@@ -30,20 +59,14 @@ test("streams text through growth, canonical replacement, and completion", async
   })
   const timeline = await setupTimeline(page, { messages: [userMessage(), assistant], cpuRate: 4 })
   const regions = defineVisualRegions({
-    text: {
-      selector: `[data-timeline-part-id="${renderedPartID(textID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    following: {
-      selector: `[data-timeline-part-id="${renderedPartID(followingID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    text: { selector: `[data-timeline-part-id="${textID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    following: { selector: `[data-timeline-part-id="${followingID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await timeline.send(partDelta(textID, " streamed content"), 100)
   await timeline.send(partDelta(textID, "\n\n- item one\n- item two\n- item three"), 180)
   await timeline.send(partUpdated(textPart(textID, "Canonical replacement with a shorter final paragraph.")), 200)
-  await timeline.send(messageUpdated(completedAssistantInfo(assistant)), 500)
+  await timeline.send(messageUpdated(completedAssistantInfo(assistant.info)), 500)
   const trace = await stopVisualProbe<keyof typeof regions>(page)
   await reportVisualStability(
     testInfo,
@@ -82,23 +105,17 @@ test("inserts a completed question between stable rows", async ({ page }, testIn
     ],
     cpuRate: 4,
   })
-  await expect(page.locator(`[data-timeline-part-id="${renderedPartID(questionID)}"]`)).toHaveCount(0)
+  await expect(page.locator(`[data-timeline-part-id="${questionID}"]`)).toHaveCount(0)
   const regions = defineVisualRegions({
-    first: {
-      selector: `[data-timeline-part-id="${renderedPartID(firstID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
-    last: {
-      selector: `[data-timeline-part-id="${renderedPartID(lastID)}"]`,
-      closest: '[data-timeline-row="AssistantPart"]',
-    },
+    first: { selector: `[data-timeline-part-id="${firstID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
+    last: { selector: `[data-timeline-part-id="${lastID}"]`, closest: '[data-timeline-row="AssistantPart"]' },
   })
   await startVisualProbe(page, regions)
   await timeline.send(
     partUpdated(toolPart(questionID, "question", "completed", input, { metadata: { answers: [["Yes"]] } })),
     600,
   )
-  await expect(page.locator(`[data-timeline-part-id="${renderedPartID(questionID)}"]`)).toBeVisible()
+  await expect(page.locator(`[data-timeline-part-id="${questionID}"]`)).toBeVisible()
   const trace = await stopVisualProbe<keyof typeof regions>(page)
   await reportVisualStability(testInfo, "question-insert", trace, stablePairPlan(regions, 0))
 })
@@ -115,8 +132,8 @@ test("replaces thinking with an assistant error without a blank turn", async ({
   await startVisualProbe(page, regions)
   await timeline.send(
     messageUpdated({
-      ...assistant,
-      error: { type: "APIError", message: "Provider failed visibly" },
+      ...assistant.info,
+      error: { name: "APIError", data: { message: "Provider failed visibly", isRetryable: false } },
     }),
     500,
   )
@@ -186,6 +203,59 @@ test("updates retry attempts and long provider messages without remounting the r
   )
 })
 
+test("reducer-hardening: removes a historical turn one message at a time without moving a visible lower anchor twice", async ({
+  page,
+}, testInfo) => {
+  const removeUserID = "msg_0500_remove_user"
+  const removeAssistantID = "msg_0501_remove_assistant"
+  const anchorUserID = "msg_2000_anchor_user"
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(undefined, { id: removeUserID, created: 1690000000000 }),
+      assistantMessage([textPart("prt_remove_text", "Removed historical content. ".repeat(15))], {
+        id: removeAssistantID,
+        parentID: removeUserID,
+        created: 1690000001000,
+      }),
+      userMessage(undefined, { id: anchorUserID, created: 1700000000000 }),
+      assistantMessage([textPart("prt_anchor_text", "Visible anchor response")], {
+        id: "msg_2001_anchor_assistant",
+        parentID: anchorUserID,
+        created: 1700000001000,
+      }),
+    ],
+    cpuRate: 4,
+  })
+  const regions = defineVisualRegions({
+    anchor: { selector: `[data-timeline-row="UserMessage"][data-message-id="${anchorUserID}"]` },
+  })
+  await startVisualProbe(page, regions)
+  await timeline.send(
+    event("message.removed", { sessionID: "ses_timeline_stability", messageID: removeAssistantID }),
+    200,
+  )
+  await timeline.send(event("message.removed", { sessionID: "ses_timeline_stability", messageID: removeUserID }), 500)
+  const trace = await stopVisualProbe<keyof typeof regions>(page)
+  await reportVisualStability(
+    testInfo,
+    "historical-turn-remove",
+    trace,
+    visualPlan(
+      regions,
+      [
+        { type: "required", regions: ["anchor"] },
+        { type: "unique", regions: ["anchor"] },
+        { type: "stable", regions: ["anchor"] },
+        { type: "opacity", regions: "all" },
+        { type: "continuity", regions: "all" },
+        { type: "motion", regions: "all", maxPositionReversals: 0 },
+        { type: "label-stability", regions: "all" },
+      ],
+      { perMarker: true },
+    ),
+  )
+})
+
 function stablePairPlan(
   regions: Record<"first" | "last", { selector: string; closest?: string }>,
   maxPositionReversals: number,

packages/app/e2e/performance/timeline/review-pane-scaling-benchmark.spec.ts

@@ -48,6 +48,7 @@ benchmark.describe("performance: review pane scaling", () => {
         await setupTimelineBenchmark(page, {
           historyTurns: 0,
           eventBatch: 1,
+          newLayoutDesigns: true,
         })
         await page.route("**/vcs/diff**", (route) =>
           route.fulfill({

packages/app/e2e/performance/timeline/session-parent-hydration-benchmark.spec.ts

@@ -1,4 +1,3 @@
-import type { SessionMessageAssistant, SessionMessageInfo, SessionMessageUser } from "@opencode-ai/client/promise"
 import type { Page } from "@playwright/test"
 import { expectSessionTitle } from "../../utils/waits"
 import { mockOpenCodeServer } from "../../utils/mock-server"
@@ -12,35 +11,42 @@ type ParentHydrationBenchmarkMode = "natural" | "candidate"
 const mode = process.env.SESSION_PARENT_HYDRATION_BENCHMARK_MODE ?? "natural"
 if (mode !== "natural" && mode !== "candidate") throw new Error(`Unknown parent hydration benchmark mode: ${mode}`)
 const userID = "msg_parent_hydration_user"
-const userSeed = fixture.messages[fixture.targetID][0] as SessionMessageUser
 const user = {
-  ...userSeed,
-  id: userID,
-  time: { created: 1700001000000 },
-} satisfies SessionMessageInfo
-const assistantSeed = fixture.messages[fixture.targetID][3] as SessionMessageAssistant
+  ...fixture.messages[fixture.targetID][0]!,
+  info: { ...fixture.messages[fixture.targetID][0]!.info, id: userID, time: { created: 1700001000000 } },
+  parts: fixture.messages[fixture.targetID][0]!.parts.map((part, index) => ({
+    ...part,
+    id: `prt_parent_hydration_user_${index}`,
+    messageID: userID,
+  })),
+}
+const assistantSeed = fixture.messages[fixture.targetID][3]!
 const assistants = Array.from({ length: 14 }, (_, index) => {
   const messageID = `msg_parent_hydration_${String(index).padStart(2, "0")}`
   return {
     ...assistantSeed,
-    id: messageID,
-    time: { created: 1700001001000 + index * 1_000, completed: 1700001001500 + index * 1_000 },
-    content: assistantSeed.content.map((part, partIndex) =>
-      part.type === "tool"
-        ? { ...part, id: `call_parent_hydration_${String(index).padStart(2, "0")}_${partIndex}` }
-        : part,
-    ),
-  } satisfies SessionMessageInfo
+    info: {
+      ...assistantSeed.info,
+      id: messageID,
+      parentID: userID,
+      time: { created: 1700001001000 + index * 1_000, completed: 1700001001500 + index * 1_000 },
+    },
+    parts: assistantSeed.parts.map((part, partIndex) => ({
+      ...part,
+      id: `prt_parent_hydration_${String(index).padStart(2, "0")}_${partIndex}`,
+      messageID,
+    })),
+  }
 })
 const messages = [user, ...assistants]
 const target = fixture.sessions.find((session) => session.id === fixture.targetID)!
 const lastID = userID
 const lastAssistant = assistants.at(-1)!
-const lastPart = lastAssistant.content.at(-1)!
+const lastPart = lastAssistant.parts.at(-1)!
 const lastPartID =
   lastPart.type === "tool"
     ? lastPart.id
-    : `${lastAssistant.id}:${lastPart.type}:${lastAssistant.content.filter((part) => part.type === lastPart.type).length - 1}`
+    : `${lastAssistant.info.id}:${lastPart.type}:${lastAssistant.parts.filter((part) => part.type === lastPart.type).length - 1}`
 
 benchmark("hydrates an orphaned latest turn after a cold session click", async ({ browser, report }, testInfo) => {
   benchmark.setTimeout(180_000)
@@ -101,25 +107,30 @@ async function trial(page: Page, mode: ParentHydrationBenchmarkMode) {
     },
     pageMessages: (sessionID, limit, before) => {
       const items = sessionID === fixture.targetID ? messages : fixture.messages[fixture.sourceID]
-      const end = before ? items.findIndex((message) => message.id === before) : items.length
+      const end = before ? items.findIndex((message) => message.info.id === before) : items.length
       const start = Math.max(0, end - limit)
-      return { items: items.slice(start, end), cursor: start > 0 ? items[start]!.id : undefined }
+      return { items: items.slice(start, end), cursor: start > 0 ? items[start]!.info.id : undefined }
     },
   })
-  await page.route(`**/api/session/${fixture.targetID}`, (route) =>
-    route.fulfill({
+  await page.route(`**/session/${fixture.targetID}`, (route) => {
+    const current = new URL(route.request().url()).pathname.startsWith("/api/")
+    return route.fulfill({
       status: 200,
       contentType: "application/json",
-      body: JSON.stringify({
-        data: {
-          ...target,
-          cost: 0,
-          tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
-          location: { directory: target.directory },
-        },
-      }),
-    }),
-  )
+      body: JSON.stringify(
+        current
+          ? {
+              data: {
+                ...target,
+                cost: 0,
+                tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+                location: { directory: target.directory },
+              },
+            }
+          : target,
+      ),
+    })
+  })
   await installStressSessionTabs(page, { sessionIDs: [fixture.sourceID] })
   await page.goto(stressSessionHref(fixture.sourceID))
   await expectSessionTitle(page, fixture.expected.sourceTitle)
@@ -137,8 +148,8 @@ async function trial(page: Page, mode: ParentHydrationBenchmarkMode) {
     { href, title: target.title },
   )
   const metrics = await measureSessionSwitch(page, {
-    destinationIDs: messages.map((message) => message.id),
-    sourceIDs: fixture.messages[fixture.sourceID].map((message) => message.id),
+    destinationIDs: messages.map((message) => message.info.id),
+    sourceIDs: fixture.messages[fixture.sourceID].map((message) => message.info.id),
     lastID,
     requiredPartID: lastPartID,
     requireBottomAnchor: false,

packages/app/e2e/performance/timeline/session-tab-flash.spec.ts

@@ -32,8 +32,8 @@ benchmark("samples cached session repaint after the click", async ({ page, repor
 
   await installCachedRepaintProbe(page, {
     targetHref: stressSessionHref(fixture.targetID),
-    destination: fixture.messages[fixture.targetID].map((message) => message.id),
-    source: fixture.messages[fixture.sourceID].map((message) => message.id),
+    destination: fixture.messages[fixture.targetID].map((message) => message.info.id),
+    source: fixture.messages[fixture.sourceID].map((message) => message.info.id),
     last: fixture.expected.targetMessageIDs.at(-1)!,
     windowMs: 1_000,
   })

packages/app/e2e/performance/timeline/session-tab-switch-benchmark.spec.ts

@@ -13,8 +13,21 @@ import { measureSessionSwitch, waitForStableTimeline } from "./session-tab-switc
 
 type Result = Awaited<ReturnType<typeof measureSessionSwitch>>
 
+benchmark("benchmarks cold and hot session tab switching", async ({ browser, report }, testInfo) => {
+  benchmark.setTimeout(180_000)
+  const results = { cold: [] as Result[], hot: [] as Result[] }
+  for (const mode of ["cold", "hot"] as const) {
+    for (let run = 0; run < 5; run++) {
+      results[mode].push(
+        await withBenchmarkPage(browser, `session-tab-switch-${mode}-${run}`, (page) => trial(page, mode), testInfo),
+      )
+    }
+  }
+  report({ results, summary: summarize(results) })
+})
+
 benchmark(
-  "benchmarks session tab switching with and without the review pane",
+  "benchmarks v2 session tab switching with and without the review pane",
   async ({ browser, report }, testInfo) => {
     benchmark.setTimeout(360_000)
     const runs = Number(process.env.SESSION_TAB_SWITCH_RUNS ?? 5)
@@ -28,8 +41,8 @@ benchmark(
           results[reviewPane][mode].push(
             await withBenchmarkPage(
               browser,
-              `session-tab-switch-${reviewPane}-${mode}-${run}`,
-              (page) => trial(page, mode, reviewPane),
+              `session-tab-switch-v2-${reviewPane}-${mode}-${run}`,
+              (page) => trial(page, mode, { newLayoutDesigns: true, reviewPane }),
               testInfo,
             ),
           )
@@ -40,10 +53,14 @@ benchmark(
   },
 )
 
-async function trial(page: Page, mode: "cold" | "hot", reviewPane: "closed" | "open") {
-  const reviewDiffs = createReviewDiffs()
+async function trial(
+  page: Page,
+  mode: "cold" | "hot",
+  options?: { newLayoutDesigns?: boolean; reviewPane?: "closed" | "open" },
+) {
+  const reviewDiffs = options?.newLayoutDesigns ? createReviewDiffs() : undefined
   await mockStressTimeline(page, { vcsDiff: reviewDiffs })
-  await installTimelineSettings(page)
+  if (options?.newLayoutDesigns) await installTimelineSettings(page)
   await installStressSessionTabs(page)
   if (mode === "hot") {
     await page.goto(stressSessionHref(fixture.targetID))
@@ -55,13 +72,13 @@ async function trial(page: Page, mode: "cold" | "hot", reviewPane: "closed" | "o
     await expectSessionTitle(page, fixture.expected.sourceTitle)
   }
   await waitForStableTimeline(page, fixture.expected.sourceMessageIDs.at(-1)!)
-  if (reviewPane === "open") {
+  if (options?.reviewPane === "open") {
     await openReviewPane(page)
     await waitForStableTimeline(page, fixture.expected.sourceMessageIDs.at(-1)!)
   }
 
-  const destinationIDs = fixture.messages[fixture.targetID].map((message) => message.id)
-  const sourceIDs = fixture.messages[fixture.sourceID].map((message) => message.id)
+  const destinationIDs = fixture.messages[fixture.targetID].map((message) => message.info.id)
+  const sourceIDs = fixture.messages[fixture.sourceID].map((message) => message.info.id)
   const lastID = fixture.expected.targetMessageIDs.at(-1)!
   const href = stressSessionHref(fixture.targetID)
   const result = await measureSessionSwitch(page, {
@@ -117,6 +134,8 @@ async function openReviewPane(page: Page) {
   await page.getByRole("button", { name: "Toggle review" }).click()
   const panel = page.locator("#review-panel")
   await expect(panel).toBeVisible()
+  // Text-based readiness works across review implementations; the legacy list mounts
+  // diff viewers lazily while V2 mounts the active preview eagerly.
   await page.waitForFunction(() => {
     const panel = document.querySelector<HTMLElement>("#review-panel")
     const text = panel?.textContent ?? ""