fix(release): use V2 Docker artifact paths (#48571)

Co-authored-by: nexxeln <95541290+nexxeln@users.noreply.github.com>

.github/workflows/publish.yml

@@ -25,7 +25,7 @@ on:
         required: false
         type: string
 
-concurrency: ${{ github.workflow }}-${{ github.ref }}-${{ inputs.version || inputs.bump }}
+concurrency: ${{ github.workflow }}-${{ github.ref }}-${{ (github.ref_name == 'v2' && (inputs.version || inputs.bump) && 'release') || inputs.version || inputs.bump }}
 
 permissions:
   id-token: write
@@ -33,7 +33,7 @@ permissions:
   packages: write
 
 env:
-  OPENCODE_CHANNEL: ${{ (github.ref_name == 'v2' && 'dev') || '' }}
+  OPENCODE_CHANNEL: ${{ (github.ref_name == 'v2' && !inputs.bump && !inputs.version && 'dev') || '' }}
 
 jobs:
   version:
@@ -168,7 +168,7 @@ jobs:
           fi
 
           found=0
-          for file in packages/cli/dist/cli-darwin-*/bin/opencode2; do
+          for file in packages/cli/dist/cli-darwin-*/bin/opencode; do
             if [ ! -f "$file" ]; then
               continue
             fi
@@ -191,7 +191,7 @@ jobs:
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
-          name: opencode-preview-cli
+          name: opencode-preview-cli-macos
           path: packages/cli/dist/cli-*
           if-no-files-found: error
 
@@ -199,7 +199,7 @@ jobs:
     needs: version
     runs-on: blacksmith-4vcpu-ubuntu-2404
     timeout-minutes: 30
-    if: github.repository == 'anomalyco/opencode'
+    if: github.repository == 'anomalyco/opencode' && !(github.ref_name == 'v2' && (inputs.bump || inputs.version))
     steps:
       - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
 
@@ -221,7 +221,7 @@ jobs:
     needs:
       - version
       - build-node-app-archive
-    if: github.repository == 'anomalyco/opencode'
+    if: github.repository == 'anomalyco/opencode' && !(github.ref_name == 'v2' && (inputs.bump || inputs.version))
     strategy:
       fail-fast: false
       matrix:
@@ -276,10 +276,9 @@ jobs:
 
   sign-cli-windows:
     needs:
-      - build-cli
-      - version
+      - sign-cli-macos
     runs-on: blacksmith-4vcpu-windows-2025
-    if: github.repository == 'anomalyco/opencode' && github.ref_name != 'v2' && github.ref_name != 'beta'
+    if: github.repository == 'anomalyco/opencode' && (github.ref_name == 'v2' || github.ref_name == 'beta')
     env:
       AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
       AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
@@ -292,15 +291,8 @@ jobs:
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
-          name: opencode-cli-windows
-          path: packages/opencode/dist
-
-      - 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: opencode-preview-cli-macos
+          path: packages/cli/dist
 
       - name: Azure login
         uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2.3.0
@@ -315,9 +307,9 @@ jobs:
           signing-account-name: ${{ env.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
           certificate-profile-name: ${{ env.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE }}
           files: |
-            ${{ github.workspace }}\packages\opencode\dist\opencode-windows-arm64\bin\opencode.exe
-            ${{ github.workspace }}\packages\opencode\dist\opencode-windows-x64\bin\opencode.exe
-            ${{ github.workspace }}\packages\opencode\dist\opencode-windows-x64-baseline\bin\opencode.exe
+            ${{ github.workspace }}\packages\cli\dist\cli-windows-arm64\bin\opencode.exe
+            ${{ github.workspace }}\packages\cli\dist\cli-windows-x64\bin\opencode.exe
+            ${{ github.workspace }}\packages\cli\dist\cli-windows-x64-baseline\bin\opencode.exe
           exclude-environment-credential: true
           exclude-workload-identity-credential: true
           exclude-managed-identity-credential: true
@@ -333,9 +325,9 @@ jobs:
         shell: pwsh
         run: |
           $files = @(
-            "${{ github.workspace }}\packages\opencode\dist\opencode-windows-arm64\bin\opencode.exe",
-            "${{ github.workspace }}\packages\opencode\dist\opencode-windows-x64\bin\opencode.exe",
-            "${{ github.workspace }}\packages\opencode\dist\opencode-windows-x64-baseline\bin\opencode.exe"
+            "${{ github.workspace }}\packages\cli\dist\cli-windows-arm64\bin\opencode.exe",
+            "${{ github.workspace }}\packages\cli\dist\cli-windows-x64\bin\opencode.exe",
+            "${{ github.workspace }}\packages\cli\dist\cli-windows-x64-baseline\bin\opencode.exe"
           )
 
           foreach ($file in $files) {
@@ -345,40 +337,17 @@ jobs:
             }
           }
 
-      - name: Repack Windows CLI archives
-        working-directory: packages/opencode/dist
-        shell: pwsh
-        run: |
-          Compress-Archive -Path "opencode-windows-arm64\bin\*" -DestinationPath "opencode-windows-arm64.zip" -Force
-          Compress-Archive -Path "opencode-windows-x64\bin\*" -DestinationPath "opencode-windows-x64.zip" -Force
-          Compress-Archive -Path "opencode-windows-x64-baseline\bin\*" -DestinationPath "opencode-windows-x64-baseline.zip" -Force
-
-      - name: Upload signed Windows CLI release assets
-        if: needs.version.outputs.release != ''
-        shell: pwsh
-        env:
-          GH_TOKEN: ${{ steps.committer.outputs.token }}
-        run: |
-          gh release upload "v${{ needs.version.outputs.version }}" `
-            "${{ github.workspace }}\packages\opencode\dist\opencode-windows-arm64.zip" `
-            "${{ github.workspace }}\packages\opencode\dist\opencode-windows-x64.zip" `
-            "${{ github.workspace }}\packages\opencode\dist\opencode-windows-x64-baseline.zip" `
-            --clobber `
-            --repo "${{ needs.version.outputs.repo }}"
-
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
-          name: opencode-cli-signed-windows
-          path: |
-            packages/opencode/dist/opencode-windows-arm64
-            packages/opencode/dist/opencode-windows-x64
-            packages/opencode/dist/opencode-windows-x64-baseline
+          name: opencode-preview-cli
+          path: packages/cli/dist/cli-*
+          if-no-files-found: error
 
   build-electron:
     needs:
       - version
-      - sign-cli-macos
-    if: github.repository == 'anomalyco/opencode' && github.ref_name != 'v2'
+      - sign-cli-windows
+    if: github.repository == 'anomalyco/opencode' && (github.ref_name != 'v2' || needs.version.outputs.release != '')
     continue-on-error: false
     env:
       AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}

AGENTS.md

@@ -8,9 +8,9 @@
 
 ## Live V2 TUI Testing
 
-- Run `bun run dev:live` from a development worktree to test its TUI against the currently elected `opencode2` background server and live sessions.
+- Run `bun run dev:live` from a development worktree to test its TUI against the currently elected `opencode` 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 `opencode service status`, injects its private local credential from `opencode service get password`, and uses the `dev` 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

bun.lock

@@ -31,7 +31,7 @@
     },
     "packages/ai": {
       "name": "@opencode/ai",
-      "version": "1.17.20",
+      "version": "2.0.0",
       "dependencies": {
         "@aws-sdk/credential-providers": "3.1057.0",
         "@opencode/schema": "workspace:*",
@@ -53,7 +53,7 @@
     },
     "packages/app": {
       "name": "@opencode/app",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@corvu/drawer": "catalog:",
         "@dnd-kit/abstract": "0.5.0",
@@ -111,7 +111,7 @@
     },
     "packages/cli": {
       "name": "@opencode/cli",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "bin": {
         "opencode2": "./bin/opencode2.cjs",
       },
@@ -175,7 +175,7 @@
     },
     "packages/client": {
       "name": "@opencode/client",
-      "version": "1.17.13",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/protocol": "workspace:*",
         "@opencode/schema": "workspace:*",
@@ -201,7 +201,7 @@
     },
     "packages/codemode": {
       "name": "@opencode/codemode",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "dependencies": {
         "acorn": "8.15.0",
         "effect": "catalog:",
@@ -215,7 +215,7 @@
     },
     "packages/console/app": {
       "name": "@opencode/console-app",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@cloudflare/vite-plugin": "1.15.2",
         "@ibm/plex": "6.4.1",
@@ -251,7 +251,7 @@
     },
     "packages/console/core": {
       "name": "@opencode/console-core",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@aws-sdk/client-sts": "3.782.0",
         "@jsx-email/render": "1.1.1",
@@ -278,7 +278,7 @@
     },
     "packages/console/function": {
       "name": "@opencode/console-function",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@openauthjs/openauth": "0.0.0-20250322224806",
         "@opencode/console-core": "workspace:*",
@@ -295,7 +295,7 @@
     },
     "packages/console/mail": {
       "name": "@opencode/console-mail",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@jsx-email/all": "2.2.3",
         "@jsx-email/cli": "1.4.3",
@@ -319,7 +319,7 @@
     },
     "packages/console/support": {
       "name": "@opencode/console-support",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@cloudflare/vite-plugin": "1.15.2",
         "@opencode/console-core": "workspace:*",
@@ -339,7 +339,7 @@
     },
     "packages/core": {
       "name": "@opencode/core",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "dependencies": {
         "@ai-sdk/alibaba": "1.0.17",
         "@ai-sdk/anthropic": "3.0.82",
@@ -411,7 +411,7 @@
     },
     "packages/desktop": {
       "name": "@opencode/desktop",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@zip.js/zip.js": "2.7.62",
         "electron-context-menu": "4.1.2",
@@ -463,7 +463,7 @@
     },
     "packages/enterprise": {
       "name": "@opencode/enterprise",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@hono/standard-validator": "catalog:",
         "@opencode-ai/sdk": "1.18.21",
@@ -500,7 +500,7 @@
     },
     "packages/function": {
       "name": "@opencode/function",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@octokit/auth-app": "8.0.1",
         "@octokit/rest": "catalog:",
@@ -516,7 +516,7 @@
     },
     "packages/http-recorder": {
       "name": "@opencode/http-recorder",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@effect/platform-node-shared": "4.0.0-rc.112",
       },
@@ -535,7 +535,7 @@
     },
     "packages/httpapi-codegen": {
       "name": "@opencode/httpapi-codegen",
-      "version": "0.0.0",
+      "version": "2.0.0",
       "dependencies": {
         "effect": "catalog:",
         "prettier": "3.6.2",
@@ -548,7 +548,7 @@
     },
     "packages/latex": {
       "name": "@opencode/latex",
-      "version": "0.0.0",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/plugin": "workspace:*",
         "@opentui/core": "catalog:",
@@ -562,7 +562,7 @@
     },
     "packages/merman": {
       "name": "@opencode/merman",
-      "version": "0.0.0",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/plugin": "workspace:*",
         "@opentui/core": "catalog:",
@@ -577,7 +577,7 @@
     },
     "packages/plugin": {
       "name": "@opencode/plugin",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@ai-sdk/provider": "3.0.8",
         "@opencode/ai": "workspace:*",
@@ -616,7 +616,7 @@
     },
     "packages/plugin-browser": {
       "name": "@opencode/plugin-browser",
-      "version": "0.0.0",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/plugin": "workspace:*",
         "@opencode/schema": "workspace:*",
@@ -646,7 +646,7 @@
     },
     "packages/protocol": {
       "name": "@opencode/protocol",
-      "version": "1.17.11",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/schema": "workspace:*",
         "effect": "catalog:",
@@ -661,7 +661,7 @@
     },
     "packages/schema": {
       "name": "@opencode/schema",
-      "version": "1.17.11",
+      "version": "2.0.0",
       "dependencies": {
         "@standard-schema/spec": "catalog:",
         "effect": "catalog:",
@@ -685,7 +685,7 @@
     },
     "packages/sdk": {
       "name": "@opencode/sdk",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/client": "workspace:*",
         "@opencode/core": "workspace:*",
@@ -706,7 +706,7 @@
     },
     "packages/server": {
       "name": "@opencode/server",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "dependencies": {
         "@effect/platform-node": "catalog:",
         "@effect/platform-node-shared": "catalog:",
@@ -728,7 +728,7 @@
     },
     "packages/session-ui": {
       "name": "@opencode/session-ui",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@kobalte/core": "catalog:",
         "@opencode/client": "workspace:*",
@@ -763,7 +763,7 @@
     },
     "packages/simulation": {
       "name": "@opencode/simulation",
-      "version": "1.17.13",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/ai": "workspace:*",
         "@opencode/core": "workspace:*",
@@ -783,7 +783,7 @@
     },
     "packages/stats/app": {
       "name": "@opencode/stats-app",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@ibm/plex": "6.4.1",
         "@kobalte/core": "catalog:",
@@ -817,7 +817,7 @@
     },
     "packages/stats/core": {
       "name": "@opencode/stats-core",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@aws-sdk/client-athena": "3.933.0",
         "@planetscale/database": "1.19.0",
@@ -836,7 +836,7 @@
     },
     "packages/stats/server": {
       "name": "@opencode/stats-server",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@aws-sdk/client-firehose": "3.933.0",
         "@effect/platform-node": "catalog:",
@@ -882,7 +882,7 @@
     },
     "packages/theme": {
       "name": "@opencode/theme",
-      "version": "0.0.0",
+      "version": "2.0.0",
       "dependencies": {
         "@opentui/core": "catalog:",
         "effect": "catalog:",
@@ -896,7 +896,7 @@
     },
     "packages/tui": {
       "name": "@opencode/tui",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "dependencies": {
         "@opencode/client": "workspace:*",
         "@opencode/core": "workspace:*",
@@ -931,7 +931,7 @@
     },
     "packages/ui": {
       "name": "@opencode/ui",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@kobalte/core": "catalog:",
         "@pierre/diffs": "catalog:",
@@ -966,7 +966,7 @@
     },
     "packages/util": {
       "name": "@opencode/util",
-      "version": "1.18.3",
+      "version": "2.0.0",
       "dependencies": {
         "@effect/opentelemetry": "catalog:",
         "@effect/platform-node": "catalog:",
@@ -999,7 +999,7 @@
     },
     "packages/web": {
       "name": "@opencode/web",
-      "version": "1.18.15",
+      "version": "2.0.0",
       "dependencies": {
         "@astrojs/cloudflare": "12.6.3",
         "@astrojs/markdown-remark": "6.3.1",
@@ -1040,7 +1040,7 @@
     },
     "services/update": {
       "name": "@opencode/update",
-      "version": "1.18.4",
+      "version": "2.0.0",
       "dependencies": {
         "jose": "6.0.11",
         "semver": "catalog:",

install

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
-APP=opencode2
+APP=opencode
+SOURCE_APP=opencode
 
 MUTED='\033[0;2m'
 RED='\033[0;31m'
@@ -22,7 +23,7 @@ Options:
 Examples:
     curl -fsSL https://opencode.ai/v2/install | bash
     curl -fsSL https://opencode.ai/v2/install | bash -s -- --version 0.0.0-beta-17236
-    ./install --binary /path/to/opencode2
+    ./install --binary /path/to/opencode
 EOF
 }
 
@@ -201,9 +202,9 @@ else
 
     filename="cli-$target-$specific_version.tgz"
     url="https://registry.npmjs.org/$package_name/-/$filename"
-    binary_name="$APP"
+    binary_name="$SOURCE_APP"
     if [ "$os" = "windows" ]; then
-        binary_name="$APP.exe"
+        binary_name="$SOURCE_APP.exe"
     fi
 fi
 
@@ -230,12 +231,7 @@ check_version() {
         installed_version="${installed_version##* }"
         installed_version="${installed_version#v}"
 
-        if [[ "$installed_version" != "$specific_version" ]]; then
-            print_message info "${MUTED}Installed version: ${NC}$installed_version."
-        else
-            print_message info "${MUTED}Version ${NC}$specific_version${MUTED} already installed"
-            exit 0
-        fi
+        print_message info "${MUTED}Installed version: ${NC}$installed_version."
     fi
 }
 
@@ -340,15 +336,47 @@ download_and_install() {
     fi
 
     tar -xzf "$tmp_dir/$filename" -C "$tmp_dir"
-    mv "$tmp_dir/package/bin/$binary_name" "$INSTALL_DIR"
-    chmod 755 "${INSTALL_DIR}/$binary_name"
+    local installed_binary="$APP"
+    if [ "$os" = "windows" ]; then
+        installed_binary="$APP.exe"
+    fi
+    mv "$tmp_dir/package/bin/$binary_name" "$INSTALL_DIR/$installed_binary"
+    chmod 755 "$INSTALL_DIR/$installed_binary"
     rm -rf "$tmp_dir"
 }
 
 install_from_binary() {
     print_message info "\n${MUTED}Installing ${NC}$APP ${MUTED}from: ${NC}$binary_path"
-    cp "$binary_path" "${INSTALL_DIR}/$APP"
-    chmod 755 "${INSTALL_DIR}/$APP"
+    local installed_binary="$APP"
+    case "$(uname -s)" in
+        MINGW*|MSYS*|CYGWIN*) installed_binary="$APP.exe" ;;
+    esac
+    cp "$binary_path" "$INSTALL_DIR/$installed_binary"
+    chmod 755 "$INSTALL_DIR/$installed_binary"
+}
+
+install_legacy_shim() {
+    local shim_os="${os:-}"
+    if [[ -z "$shim_os" ]]; then
+        case "$(uname -s)" in
+            MINGW*|MSYS*|CYGWIN*) shim_os="windows" ;;
+        esac
+    fi
+    rm -f "$INSTALL_DIR/opencode2" "$INSTALL_DIR/opencode2.exe" "$INSTALL_DIR/opencode2.cmd"
+    if [[ "$shim_os" == "windows" ]]; then
+        cat > "$INSTALL_DIR/opencode2.cmd" <<'EOF'
+@echo off
+echo opencode2 is now just opencode. run opencode
+exit /b 1
+EOF
+        return
+    fi
+    cat > "$INSTALL_DIR/opencode2" <<'EOF'
+#!/bin/sh
+echo 'opencode2 is now just opencode. run opencode'
+exit 1
+EOF
+    chmod 755 "$INSTALL_DIR/opencode2"
 }
 
 if [ -n "$binary_path" ]; then
@@ -357,6 +385,7 @@ else
     check_version
     download_and_install
 fi
+install_legacy_shim
 
 
 add_to_path() {
@@ -453,7 +482,7 @@ echo -e ""
 echo -e "${MUTED}OpenCode includes free models, to start:${NC}"
 echo -e ""
 echo -e "cd <project>  ${MUTED}# Open directory${NC}"
-echo -e "opencode2     ${MUTED}# Run command${NC}"
+echo -e "opencode      ${MUTED}# Run command${NC}"
 echo -e ""
 echo -e "${MUTED}For more information visit ${NC}https://opencode.ai/v2/docs"
 echo -e ""

package.json

@@ -2,15 +2,15 @@
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode",
   "description": "AI-powered development tool",
-  "version": "0.0.0",
+  "version": "2.0.0",
   "private": true,
   "type": "module",
   "packageManager": "bun@1.4.2",
   "scripts": {
     "dev": "bun run --cwd packages/cli src/index.ts",
-    "dev:live": "sh -c 'OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode2 service get password)\" exec bun run dev \"$@\" --server \"$(opencode2 service status)\"' --",
+    "dev:live": "sh -c 'OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode service get password)\" exec bun run dev \"$@\" --server \"$(opencode service status)\"' --",
     "dev:vite": "bun run --cwd packages/cli --conditions=browser dev/vite.ts",
-    "dev:vite:live": "sh -c 'OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode2 service get password)\" exec bun run dev:vite \"$@\" --server \"$(opencode2 service status)\"' --",
+    "dev:vite:live": "sh -c 'OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode service get password)\" exec bun run dev:vite \"$@\" --server \"$(opencode 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",

packages/ai/AGENTS.md

@@ -122,13 +122,14 @@ Keep provider facades small and explicit:
 
 ### Provider Package Entrypoints
 
-Catalog-selected native providers use package-like export paths from `@opencode/ai`. They are internal entrypoints in one npm package, not separately published provider packages. Every entrypoint implements `ProviderPackage.Definition` and exposes `model(modelID, settings)`, where settings are serializable provider configuration plus common `headers`, `body`, and `limits` overlays.
+Catalog-selected native providers use package-like export paths from `@opencode/ai`. They are internal entrypoints in one npm package, not separately published provider packages. Every entrypoint implements `ProviderPackage.Definition` and exposes `model(modelID, settings)`, where settings are one flat serializable object: the connection keys the entrypoint declares (`apiKey`, `baseURL`, `region`, …), the common `headers` and `body` overlays, and the protocol's request options (`reasoningEffort`, `thinking`, …) side by side. Each entrypoint destructures its own connection keys and passes the rest to the route as `providerOptions`; there is no nested `providerOptions` at the entrypoint.
 
 ```ts
 import { model } from "@opencode/ai/providers/openai/responses"
 
 const selected = model("gpt-5", {
   apiKey,
+  reasoningEffort: "high",
 })
 ```
 

packages/ai/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.17.20",
+  "version": "2.0.0",
   "name": "@opencode/ai",
   "type": "module",
   "license": "MIT",

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

@@ -1708,7 +1708,10 @@ export const transport = <
 }
 
 function requiredBetaHeaders(body: Pick<AnthropicMessagesBody, "messages" | "context_management" | "thinking">) {
-  const betas: string[] = []
+  // Always request interleaved thinking. The API accepts the header on any
+  // model and ignores it where unsupported, while manual-thinking models need
+  // it for thinking between tool calls.
+  const betas: string[] = ["interleaved-thinking-2025-05-14"]
   const requestsCompaction = (body.context_management?.edits.length ?? 0) > 0
   const replaysCompaction = body.messages.some((message) =>
     message.content.some((block) => block.type === "compaction"),

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

@@ -18,7 +18,6 @@ const WebSocketResponseCreate = Schema.StructWithRest(Schema.Struct({ type: Sche
 ])
 const decodeMessage = ProviderShared.validateWith(Schema.decodeUnknownEffect(WebSocketResponseCreate))
 const encodeMessage = Schema.encodeSync(Schema.fromJsonString(WebSocketResponseCreate))
-const decodeEvent = Schema.decodeUnknownEffect(OpenResponses.protocol.stream.event)
 
 export interface Options {
   readonly id: string
@@ -27,6 +26,7 @@ export interface Options {
   readonly enabled?: (url: string) => boolean
   readonly url?: (url: string) => string
   readonly headers?: (headers: Headers.Headers) => Headers.Headers
+  readonly continuation?: OpenResponsesContinuation.Shape
 }
 
 export interface Prepared {
@@ -60,7 +60,7 @@ const driver = (options: Options, body: string): WebSocketChannelDriver => {
       }),
     observe: (_create, frame) =>
       Effect.gen(function* () {
-        const event = yield* decodeEvent(frame).pipe(
+        const event = yield* OpenResponses.decodeChannelEvent(frame).pipe(
           Effect.mapError((cause) =>
             ProviderShared.eventError(options.id, `Invalid ${options.name} WebSocket event`, frame, cause),
           ),
@@ -163,6 +163,7 @@ export const transport = <Body>(options: Options): Transport<Body, Prepared, str
                     request: create.request,
                     message: create.message,
                     base,
+                    continuation: options.continuation,
                   }),
                 }
               })

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

@@ -6,7 +6,6 @@ import { OpenResponses } from "./open-responses.js"
 
 const PROTOCOL = "open-responses.websocket.v1"
 const VERSION = 1
-const decodeEvent = Schema.decodeUnknownEffect(OpenResponses.protocol.stream.event)
 
 interface CheckpointValue {
   readonly version: typeof VERSION
@@ -15,12 +14,19 @@ interface CheckpointValue {
   readonly output: ReadonlyArray<unknown>
 }
 
+/**
+ * Fields to send next to `previous_response_id` on an incremental step, or undefined to send the step in full.
+ * Whether omitted fields carry over from the continued response is provider behavior the route must know.
+ */
+export type Shape = (request: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>> | undefined
+
 export interface DriverInput {
   readonly id: string
   readonly name: string
   readonly request: Readonly<Record<string, unknown>>
   readonly message: string
   readonly base: WebSocketChannelDriver
+  readonly continuation?: Shape
 }
 
 const checkpointValue = (checkpoint: ChannelCheckpoint | undefined): CheckpointValue | undefined => {
@@ -127,22 +133,26 @@ const rejected = (
 
 export const driver = (input: DriverInput): WebSocketChannelDriver => {
   const { previous_response_id: _previousResponseID, ...request } = input.request
+  const shape = input.continuation ?? ((fields: Readonly<Record<string, unknown>>) => fields)
   let output: OpenResponses.StreamItem[] = []
   return {
     create: (checkpoint) =>
       Effect.sync(() => {
         output = []
         const previous = checkpointValue(checkpoint)
-        const delta = previous ? incremental(request, previous) : undefined
-        if (!previous || !delta) return { message: ProviderShared.encodeJson(request), mode: "full" as const }
+        // Ask the route first: diffing the whole history is wasted when it declines the continuation.
+        const fields = previous ? shape(request) : undefined
+        const delta = previous && fields ? incremental(request, previous) : undefined
+        if (!previous || !fields || !delta)
+          return { message: ProviderShared.encodeJson(request), mode: "full" as const }
         return {
-          message: ProviderShared.encodeJson({ ...request, input: delta, previous_response_id: previous.responseID }),
+          message: ProviderShared.encodeJson({ ...fields, input: delta, previous_response_id: previous.responseID }),
           mode: "incremental" as const,
         }
       }),
     observe: (create, frame) =>
       Effect.gen(function* () {
-        const event = yield* decodeEvent(frame).pipe(
+        const event = yield* OpenResponses.decodeChannelEvent(frame).pipe(
           Effect.mapError((cause) =>
             ProviderShared.eventError(input.id, `Invalid ${input.name} WebSocket event`, frame, cause),
           ),
@@ -195,4 +205,4 @@ export const driver = (input: DriverInput): WebSocketChannelDriver => {
   }
 }
 
-export const OpenResponsesContinuation = { driver } as const
+export * as OpenResponsesContinuation from "./open-responses-continuation.js"

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

@@ -1,4 +1,4 @@
-import { Effect, Option, Schema } from "effect"
+import { Effect, Option, Schema, SchemaGetter } from "effect"
 import type { Content } from "@opencode/schema/tool"
 import { HttpTransport } from "../route/transport/index.js"
 import { Protocol } from "../route/protocol.js"
@@ -325,9 +325,8 @@ export const StreamItem = Schema.StructWithRest(
 export type StreamItem = Schema.Schema.Type<typeof StreamItem>
 export type OutputItem = StreamItem & { readonly id: string }
 
-// The Responses schema puts streaming error details at the top level and
-// response failures under `response.error`. WebSocket failures use an
-// event-level `error` envelope, so accept all three shapes here.
+// Responses-compatible providers put streaming error details at the top level or
+// under `error`, and response failures under `response.error`. Accept all three shapes.
 // https://www.openresponses.org/specification
 const OpenResponsesErrorPayload = Schema.Struct({
   type: optionalNull(Schema.String),
@@ -401,10 +400,39 @@ export const Event = Schema.StructWithRest(
     headers: Schema.optional(Schema.Unknown),
   }),
   [Schema.Record(Schema.String, Schema.Unknown)],
+).pipe(
+  Schema.decode({
+    decode: SchemaGetter.transform((event) => {
+      if (event.type !== "error" || event.error != null) return event
+      const { code, message, param, ...rest } = event
+      if (code === undefined && message === undefined && param === undefined) return event
+      // Flat errors (for example, Meta's) can also arrive through generic Responses endpoints.
+      return { ...rest, error: { code, message, param } }
+    }),
+    encode: SchemaGetter.passthrough(),
+  }),
 )
 export type Event = Schema.Schema.Type<typeof Event>
 export type NormalizedEvent = Event & { readonly item?: OutputItem | null }
 
+const decodeEventValue = Schema.decodeUnknownEffect(Event)
+const decodeFrame = Schema.decodeUnknownEffect(ProviderShared.Json)
+
+/**
+ * Decodes one WebSocket frame. xAI answers a rejected `response.create` with `{ "error": { "message", "type" } }` and no
+ * event type; that envelope reads as an error event so the failure classifies instead of failing decoding.
+ */
+export const decodeChannelEvent = (frame: string) =>
+  decodeFrame(frame).pipe(
+    Effect.flatMap((value) =>
+      decodeEventValue(
+        ProviderShared.isRecord(value) && value.type === undefined && ProviderShared.isRecord(value.error)
+          ? { ...value, type: "error" }
+          : value,
+      ),
+    ),
+  )
+
 export interface ProviderAdapter {
   readonly id: string
   readonly name: string

packages/ai/src/provider-package.ts

@@ -1,6 +1,10 @@
 import type { LanguageModel, ProviderOptions } from "./schema/index.js"
 import type { CompactionOperations } from "./route/client.js"
 
+/**
+ * Flat, serializable settings for `model(modelID, settings)`. Each entrypoint declares the connection keys it
+ * reads; every other key is a request option for the route's protocol.
+ */
 export interface Settings extends Readonly<Record<string, unknown>> {
   readonly baseURL?: string
   readonly headers?: Readonly<Record<string, string>>

packages/ai/src/providers/alibaba.ts

@@ -1,3 +1,4 @@
+import { Struct } from "effect"
 import type { ProviderPackage } from "../provider-package.js"
 import { AlibabaChat } from "../protocols/alibaba-chat.js"
 import { AlibabaMessages } from "../protocols/alibaba-messages.js"
@@ -6,7 +7,7 @@ import { AuthOptions, type AtLeastOne, type ProviderAuthOption } from "../route/
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
-import { ProviderID, ToolDefinition, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, ToolDefinition, type ModelID } from "../schema/index.js"
 
 export const id = ProviderID.make("alibaba")
 
@@ -34,9 +35,9 @@ export type Config = Location &
     readonly providerOptions?: ChatOptionsInput | MessagesOptionsInput | ResponsesOptionsInput
   }
 export type Settings<Options = ChatOptionsInput> = Location &
-  ProviderPackage.Settings & {
+  ProviderPackage.Settings &
+  Options & {
     readonly apiKey?: string
-    readonly providerOptions?: Options
   }
 
 const hosts = new Map<string, string>([
@@ -82,8 +83,13 @@ export const configure = (input: Config) => {
         ? hosts.get(region)
         : `${workspaceID}.${region}.maas.aliyuncs.com`
   if (baseURL === undefined) {
-    if (region === undefined) throw new Error("Alibaba requires region or baseURL")
-    if (host === undefined) throw new Error(`Alibaba region ${region} requires workspaceID or baseURL`)
+    if (region === undefined)
+      throw new ProviderConfigurationError({ provider: id, message: "Alibaba requires region or baseURL" })
+    if (host === undefined)
+      throw new ProviderConfigurationError({
+        provider: id,
+        message: `Alibaba region ${region} requires workspaceID or baseURL`,
+      })
   }
   const opts = { ...rest, auth: AuthOptions.bearer(input, ["DASHSCOPE_API_KEY", "ALIBABA_API_KEY"]) }
   const common = { ...opts, endpoint: { baseURL: baseURL ?? `https://${host}/compatible-mode/v1` } }
@@ -115,7 +121,11 @@ export const responsesModel: ProviderPackage.Definition<
 
 function fromSettings(input: Settings<Config["providerOptions"]>) {
   const { body, ...rest } = input
-  return configure({ ...rest, http: body === undefined ? undefined : { body } })
+  return configure({
+    ...rest,
+    http: body === undefined ? undefined : { body },
+    providerOptions: Struct.omit(rest, ["apiKey", "baseURL", "headers", "region", "workspaceID"]),
+  })
 }
 
 export const webSearch = () => hostedTool("web_search", "Search the web with Alibaba's hosted search tool.")

packages/ai/src/providers/amazon-bedrock-mantle.ts

@@ -4,7 +4,7 @@ import type { ProviderPackage } from "../provider-package.js"
 import { OpenAIChat } from "../protocols/openai-chat.js"
 import { OpenResponses } from "../protocols/open-responses.js"
 import { BedrockAuth, type Credentials } from "../protocols/utils/bedrock-auth.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options.js"
 
 export const id = ProviderID.make("amazon-bedrock")
@@ -23,16 +23,16 @@ export type Config = RouteDefaultsInput & {
   readonly providerOptions?: OpenAIProviderOptionsInput
 }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly auth?: "bearer" | "sigv4"
-  readonly baseURL?: string
-  readonly credentials?: Credentials
-  readonly profile?: string
-  readonly region?: string
-  readonly topP?: number
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly auth?: "bearer" | "sigv4"
+    readonly baseURL?: string
+    readonly credentials?: Credentials
+    readonly profile?: string
+    readonly region?: string
+    readonly topP?: number
+  }
 
 const responsesRoute = Route.make({
   id: "bedrock-mantle-responses",
@@ -79,9 +79,12 @@ const defaults = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   if (input.auth === "bearer" && input.apiKey === undefined && process.env.AWS_BEARER_TOKEN_BEDROCK === undefined)
-    throw new Error("Amazon Bedrock Mantle bearer auth requires apiKey")
+    throw new ProviderConfigurationError({ provider: id, message: "Amazon Bedrock Mantle bearer auth requires apiKey" })
   if (input.auth === "sigv4" && input.apiKey !== undefined)
-    throw new Error("Amazon Bedrock Mantle SigV4 auth does not accept apiKey")
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "Amazon Bedrock Mantle SigV4 auth does not accept apiKey",
+    })
   const configuredResponsesRoute = configuredRoute(responsesRoute, input)
   const configuredChatRoute = configuredRoute(chatRoute, input)
   const modelDefaults = defaults(input)
@@ -105,18 +108,29 @@ export const configure = (input: Config = {}) => {
 
 export const provider = configure()
 
-const fromSettings = (settings: Settings) =>
+const fromSettings = ({
+  apiKey,
+  auth,
+  baseURL,
+  body,
+  credentials,
+  headers,
+  profile,
+  region,
+  topP,
+  ...providerOptions
+}: Settings) =>
   configure({
-    apiKey: settings.apiKey,
-    auth: settings.auth,
-    baseURL: settings.baseURL,
-    credentials: settings.credentials,
-    generation: settings.topP === undefined ? undefined : { topP: settings.topP },
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    profile: settings.profile,
-    providerOptions: settings.providerOptions,
-    region: settings.region,
+    apiKey,
+    auth,
+    baseURL,
+    credentials,
+    generation: topP === undefined ? undefined : { topP },
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    profile,
+    providerOptions,
+    region,
   })
 
 export const chatModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (

packages/ai/src/providers/amazon-bedrock.ts

@@ -1,6 +1,6 @@
 import type { RouteDefaultsInput } from "../route/client.js"
 import type { ProviderPackage } from "../provider-package.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import * as BedrockConverse from "../protocols/bedrock-converse.js"
 import type { BedrockCredentials } from "../protocols/bedrock-converse.js"
 import { BedrockAuth } from "../protocols/utils/bedrock-auth.js"
@@ -39,8 +39,9 @@ const bedrockBaseURL = (region: string) => `https://bedrock-runtime.${region}.am
 const configuredRoute = (input: Config) => {
   const { apiKey, auth, credentials, profile, region, baseURL, ...rest } = input
   if (auth === "bearer" && apiKey === undefined && process.env.AWS_BEARER_TOKEN_BEDROCK === undefined)
-    throw new Error("Amazon Bedrock bearer auth requires apiKey")
-  if (auth === "sigv4" && apiKey !== undefined) throw new Error("Amazon Bedrock SigV4 auth does not accept apiKey")
+    throw new ProviderConfigurationError({ provider: id, message: "Amazon Bedrock bearer auth requires apiKey" })
+  if (auth === "sigv4" && apiKey !== undefined)
+    throw new ProviderConfigurationError({ provider: id, message: "Amazon Bedrock SigV4 auth does not accept apiKey" })
   const resolvedRegion = BedrockAuth.resolveRegion(input)
   return BedrockConverse.route.with({
     ...rest,

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

@@ -3,7 +3,7 @@ import { AnthropicMessages } from "../protocols/anthropic-messages.js"
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
 import type { RouteDefaultsInput } from "../route/client.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 
 export type AnthropicOptionsInput = AnthropicMessages.OptionsInput
 export type AnthropicProviderOptionsInput = AnthropicMessages.ProviderOptionsInput
@@ -19,13 +19,13 @@ export type Config = RouteDefaultsInput &
   }
 
 export type Settings = ProviderPackage.Settings &
+  AnthropicMessages.ProviderOptionsInput &
   (
     | { readonly apiKey?: string; readonly authToken?: never }
     | { readonly apiKey?: never; readonly authToken?: string }
   ) & {
     readonly baseURL: string
     readonly provider?: string
-    readonly providerOptions?: AnthropicMessages.ProviderOptionsInput
   }
 
 export const routes = [AnthropicMessages.route]
@@ -36,8 +36,12 @@ const auth = (input: ProviderAuthOption<"optional">) => {
 }
 
 export const configure = (input: Config) => {
-  if (!input.baseURL) throw new Error("Anthropic-compatible providers require a baseURL")
   const provider = input.provider ?? "anthropic-compatible"
+  if (!input.baseURL)
+    throw new ProviderConfigurationError({
+      provider: ProviderID.make(provider),
+      message: "Anthropic-compatible providers require a baseURL",
+    })
   const { provider: _, baseURL, apiKey: _apiKey, auth: _auth, ...rest } = input
   const route = AnthropicMessages.route.with({
     ...rest,
@@ -59,17 +63,20 @@ export const provider = {
 
 export const model: ProviderPackage.Definition<Settings, AnthropicMessages.ProviderOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, authToken, baseURL, body, headers, provider, ...providerOptions },
 ) => {
-  if (settings.apiKey !== undefined && settings.authToken !== undefined)
-    throw new Error("Anthropic-compatible apiKey cannot be combined with authToken")
+  if (apiKey !== undefined && authToken !== undefined)
+    throw new ProviderConfigurationError({
+      provider: ProviderID.make(provider ?? id),
+      message: "Anthropic-compatible apiKey cannot be combined with authToken",
+    })
   return configure({
-    ...(settings.authToken === undefined ? { apiKey: settings.apiKey } : { auth: Auth.bearer(settings.authToken) }),
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    provider: settings.provider,
-    providerOptions: settings.providerOptions,
+    ...(authToken === undefined ? { apiKey: apiKey } : { auth: Auth.bearer(authToken) }),
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    provider,
+    providerOptions,
   }).model(modelID)
 }
 

packages/ai/src/providers/anthropic.ts

@@ -2,7 +2,7 @@ import type { RouteDefaultsInput } from "../route/client.js"
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
 import type { ProviderPackage } from "../provider-package.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import { AnthropicMessages } from "../protocols/anthropic-messages.js"
 import { AnthropicCompatible } from "./anthropic-compatible.js"
 
@@ -21,12 +21,12 @@ export type Config = RouteDefaultsInput &
   }
 
 export type Settings = ProviderPackage.Settings &
+  AnthropicMessages.ProviderOptionsInput &
   (
     | { readonly apiKey?: string; readonly authToken?: never }
     | { readonly apiKey?: never; readonly authToken?: string }
   ) & {
     readonly baseURL?: string
-    readonly providerOptions?: AnthropicMessages.ProviderOptionsInput
   }
 
 const auth = (options: ProviderAuthOption<"optional">) => {
@@ -54,15 +54,18 @@ export const configure = (input: Config = {}) => {
 export const provider = configure()
 export const model: ProviderPackage.Definition<Settings, AnthropicMessages.ProviderOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, authToken, baseURL, body, headers, ...providerOptions },
 ) => {
-  if (settings.apiKey !== undefined && settings.authToken !== undefined)
-    throw new Error("Anthropic apiKey cannot be combined with authToken")
+  if (apiKey !== undefined && authToken !== undefined)
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "Anthropic apiKey cannot be combined with authToken",
+    })
   return configure({
-    ...(settings.authToken === undefined ? { apiKey: settings.apiKey } : { auth: Auth.bearer(settings.authToken) }),
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    ...(authToken === undefined ? { apiKey: apiKey } : { auth: Auth.bearer(authToken) }),
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 }

packages/ai/src/providers/azure.ts

@@ -3,7 +3,7 @@ import { Auth } from "../route/auth.js"
 import { type AtLeastOne, type ProviderAuthOption } from "../route/auth-options.js"
 import type { Route, RouteDefaultsInput, CompactionOperations } from "../route/client.js"
 import type { ProviderPackage } from "../provider-package.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
 import * as OpenAIResponses from "../protocols/openai-responses.js"
 import { ProviderShared } from "../protocols/shared.js"
@@ -28,12 +28,12 @@ export type LanguageModelOptions = AzureURL &
 export type Config = LanguageModelOptions
 
 export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput &
   AzureURL & {
     readonly apiKey?: string
     readonly apiVersion?: string
     readonly queryParams?: Readonly<Record<string, string>>
     readonly useDeploymentBasedUrls?: boolean
-    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 const resourceBaseURL = (resourceName: string) => `https://${resourceName.trim()}.openai.azure.com/openai`
@@ -151,19 +151,29 @@ export const provider = {
   configure,
 }
 
-const config = (settings: Settings): Config => {
+const config = ({
+  apiKey,
+  apiVersion,
+  baseURL,
+  body,
+  headers,
+  queryParams,
+  resourceName,
+  useDeploymentBasedUrls,
+  ...providerOptions
+}: Settings): Config => {
   const common = {
-    apiKey: settings.apiKey,
-    apiVersion: settings.apiVersion,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
-    queryParams: settings.queryParams === undefined ? undefined : { ...settings.queryParams },
-    useDeploymentBasedUrls: settings.useDeploymentBasedUrls,
+    apiKey,
+    apiVersion,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
+    queryParams: queryParams === undefined ? undefined : { ...queryParams },
+    useDeploymentBasedUrls,
   }
-  if (settings.baseURL !== undefined) return { ...common, baseURL: settings.baseURL }
-  if (settings.resourceName !== undefined) return { ...common, resourceName: settings.resourceName }
-  throw new Error("Azure requires resourceName or baseURL")
+  if (baseURL !== undefined) return { ...common, baseURL }
+  if (resourceName !== undefined) return { ...common, resourceName }
+  throw new ProviderConfigurationError({ provider: id, message: "Azure requires resourceName or baseURL" })
 }
 
 export const responsesModel: ProviderPackage.Definition<

packages/ai/src/providers/baseten.ts

@@ -15,11 +15,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = Route.make({
   id: "baseten-chat",
@@ -48,13 +48,16 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as Baseten from "./baseten.js"

packages/ai/src/providers/cerebras.ts

@@ -15,11 +15,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = Route.make({
   id: "cerebras-chat",
@@ -52,11 +52,14 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)

packages/ai/src/providers/cloudflare-ai-gateway.ts

@@ -5,7 +5,7 @@ import { Auth } from "../route/auth.js"
 import type { AtLeastOne, ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
 
 export const id = ProviderID.make("cloudflare-ai-gateway")
@@ -27,15 +27,19 @@ export type LanguageModelOptions = GatewayURL &
   }
 
 export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput &
   GatewayURL & {
     readonly apiKey?: string
     readonly gatewayApiKey?: string
-    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 export const baseURL = (input: GatewayURL) => {
   if (input.baseURL) return input.baseURL
-  if (!input.accountId) throw new Error("CloudflareAIGateway.configure requires accountId unless baseURL is supplied")
+  if (!input.accountId)
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "CloudflareAIGateway.configure requires accountId unless baseURL is supplied",
+    })
   return `https://gateway.ai.cloudflare.com/v1/${encodeURIComponent(input.accountId)}/${encodeURIComponent(input.gatewayId?.trim() || "default")}/compat`
 }
 
@@ -85,14 +89,25 @@ export const configure = (input: LanguageModelOptions) => {
 
 export const provider = { id, configure }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
-  configure({
-    apiKey: settings.apiKey,
-    gatewayApiKey: settings.gatewayApiKey,
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
+  const {
+    accountId: _,
+    apiKey,
+    baseURL: _url,
+    body,
+    gatewayApiKey,
+    gatewayId: _id,
+    headers,
+    ...providerOptions
+  } = settings
+  return configure({
+    apiKey,
+    gatewayApiKey,
     baseURL: baseURL(settings),
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
+}
 
 export * as CloudflareAIGateway from "./cloudflare-ai-gateway.js"

packages/ai/src/providers/cloudflare-workers-ai.ts

@@ -3,7 +3,7 @@ import { OpenAIChat } from "../protocols/openai-chat.js"
 import { AuthOptions, type AtLeastOne, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
 
 export const id = ProviderID.make("cloudflare-workers-ai")
@@ -21,14 +21,18 @@ export type LanguageModelOptions = WorkersAIURL &
   }
 
 export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput &
   WorkersAIURL & {
     readonly apiKey?: string
-    readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 export const baseURL = (input: WorkersAIURL) => {
   if (input.baseURL) return input.baseURL
-  if (!input.accountId) throw new Error("CloudflareWorkersAI.configure requires accountId unless baseURL is supplied")
+  if (!input.accountId)
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "CloudflareWorkersAI.configure requires accountId unless baseURL is supplied",
+    })
   return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(input.accountId)}/ai/v1`
 }
 
@@ -59,13 +63,15 @@ export const configure = (input: LanguageModelOptions) => {
 
 export const provider = { id, configure }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
-  configure({
-    apiKey: settings.apiKey,
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
+  const { accountId: _, apiKey, baseURL: _url, body, headers, ...providerOptions } = settings
+  return configure({
+    apiKey,
     baseURL: baseURL(settings),
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
+}
 
 export * as CloudflareWorkersAI from "./cloudflare-workers-ai.js"

packages/ai/src/providers/deepinfra.ts

@@ -15,11 +15,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = Route.make({
   id: "deepinfra-chat",
@@ -55,11 +55,14 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)

packages/ai/src/providers/deepseek.ts

@@ -15,11 +15,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = Route.make({
   id: "deepseek-chat",
@@ -52,13 +52,16 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as DeepSeek from "./deepseek.js"

packages/ai/src/providers/fireworks.ts

@@ -15,11 +15,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = Route.make({
   id: "fireworks-chat",
@@ -48,13 +48,16 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as Fireworks from "./fireworks.js"

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

@@ -2,7 +2,7 @@ import type { ProviderPackage } from "../provider-package.js"
 import { OpenAIChat } from "../protocols/openai-chat.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import { GoogleVertexShared } from "./google-vertex-shared.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
 
@@ -16,14 +16,14 @@ export type Config = RouteDefaultsInput &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly accessToken?: string
-  readonly apiKey?: never
-  readonly baseURL?: string
-  readonly location?: string
-  readonly project?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly accessToken?: string
+    readonly apiKey?: never
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
 
 const route = Route.make({
   id: "google-vertex-chat",
@@ -37,7 +37,8 @@ const route = Route.make({
 export const routes = [route]
 
 const configuredRoute = (input: Config) => {
-  if ("apiKey" in input && input.apiKey !== undefined) throw new Error("Google Vertex Chat does not support API keys")
+  if ("apiKey" in input && input.apiKey !== undefined)
+    throw new ProviderConfigurationError({ provider: id, message: "Google Vertex Chat does not support API keys" })
   const {
     accessToken: _accessToken,
     auth: _auth,
@@ -73,15 +74,19 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
-  if (settings.apiKey !== undefined) throw new Error("Google Vertex Chat does not support API keys")
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { accessToken, apiKey, baseURL, body, headers, location, project, ...providerOptions },
+) => {
+  if (apiKey !== undefined)
+    throw new ProviderConfigurationError({ provider: id, message: "Google Vertex Chat does not support API keys" })
   return configure({
-    accessToken: settings.accessToken,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    location: settings.location,
-    project: settings.project,
-    providerOptions: settings.providerOptions,
+    accessToken,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    location,
+    project,
+    providerOptions,
   }).model(modelID)
 }

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

@@ -5,7 +5,7 @@ import { Auth } from "../route/auth.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import { GoogleVertexShared } from "./google-vertex-shared.js"
 
 export type AnthropicOptionsInput = AnthropicMessages.OptionsInput
@@ -25,14 +25,14 @@ export type Config = RouteDefaultsInput &
     readonly providerOptions?: AnthropicMessages.ProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly accessToken?: string
-  readonly apiKey?: never
-  readonly baseURL?: string
-  readonly location?: string
-  readonly project?: string
-  readonly providerOptions?: AnthropicMessages.ProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  AnthropicMessages.ProviderOptionsInput & {
+    readonly accessToken?: string
+    readonly apiKey?: never
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
 
 const route = Route.make({
   id: "google-vertex-messages",
@@ -67,7 +67,7 @@ export const routes = [route]
 
 const configuredRoute = (input: Config) => {
   if ("apiKey" in input && input.apiKey !== undefined)
-    throw new Error("Google Vertex Messages does not support API keys")
+    throw new ProviderConfigurationError({ provider: id, message: "Google Vertex Messages does not support API keys" })
   const {
     accessToken: _accessToken,
     auth: _auth,
@@ -105,16 +105,17 @@ export const provider = {
 
 export const model: ProviderPackage.Definition<Settings, AnthropicMessages.ProviderOptionsInput>["model"] = (
   modelID,
-  settings,
+  { accessToken, apiKey, baseURL, body, headers, location, project, ...providerOptions },
 ) => {
-  if (settings.apiKey !== undefined) throw new Error("Google Vertex Messages does not support API keys")
+  if (apiKey !== undefined)
+    throw new ProviderConfigurationError({ provider: id, message: "Google Vertex Messages does not support API keys" })
   return configure({
-    accessToken: settings.accessToken,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    location: settings.location,
-    project: settings.project,
-    providerOptions: settings.providerOptions,
+    accessToken,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    location,
+    project,
+    providerOptions,
   }).model(modelID)
 }

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

@@ -2,7 +2,7 @@ import type { ProviderPackage } from "../provider-package.js"
 import { OpenResponses } from "../protocols/open-responses.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { ProviderID, type ModelID } from "../schema/index.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import { GoogleVertexShared } from "./google-vertex-shared.js"
 import type { OpenResponsesProviderOptionsInput } from "./open-responses-options.js"
 
@@ -16,14 +16,14 @@ export type Config = RouteDefaultsInput &
     readonly providerOptions?: OpenResponsesProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly accessToken?: string
-  readonly apiKey?: never
-  readonly baseURL?: string
-  readonly location?: string
-  readonly project?: string
-  readonly providerOptions?: OpenResponsesProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenResponsesProviderOptionsInput & {
+    readonly accessToken?: string
+    readonly apiKey?: never
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
 
 const route = Route.make({
   id: "google-vertex-responses",
@@ -39,7 +39,7 @@ export const routes = [route]
 
 const configuredRoute = (input: Config) => {
   if ("apiKey" in input && input.apiKey !== undefined)
-    throw new Error("Google Vertex Responses does not support API keys")
+    throw new ProviderConfigurationError({ provider: id, message: "Google Vertex Responses does not support API keys" })
   const {
     accessToken: _accessToken,
     auth: _auth,
@@ -77,16 +77,17 @@ export const provider = {
 
 export const model: ProviderPackage.Definition<Settings, OpenResponsesProviderOptionsInput>["model"] = (
   modelID,
-  settings,
+  { accessToken, apiKey, baseURL, body, headers, location, project, ...providerOptions },
 ) => {
-  if (settings.apiKey !== undefined) throw new Error("Google Vertex Responses does not support API keys")
+  if (apiKey !== undefined)
+    throw new ProviderConfigurationError({ provider: id, message: "Google Vertex Responses does not support API keys" })
   return configure({
-    accessToken: settings.accessToken,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    location: settings.location,
-    project: settings.project,
-    providerOptions: settings.providerOptions,
+    accessToken,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    location,
+    project,
+    providerOptions,
   }).model(modelID)
 }

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

@@ -1,8 +1,10 @@
 import type { AnyAuthClient } from "google-auth-library"
 import { Effect, Redacted } from "effect"
 import { Auth, MissingCredentialError } from "../route/auth.js"
+import { ProviderConfigurationError, ProviderID } from "../schema/index.js"
 
 const SCOPE = "https://www.googleapis.com/auth/cloud-platform"
+const id = ProviderID.make("google-vertex")
 
 export type OAuthOptions =
   | { readonly accessToken?: string; readonly auth?: never }
@@ -35,12 +37,18 @@ export const host = (location: string) => {
 
 export const requireProject = (value: string | undefined) => {
   if (value) return value
-  throw new Error("Google Vertex requires a project when baseURL is not configured")
+  throw new ProviderConfigurationError({
+    provider: id,
+    message: "Google Vertex requires a project when baseURL is not configured",
+  })
 }
 
 export const apiKey = (input: ApiKeyOptions) => {
   if (input.apiKey !== undefined && (input.accessToken !== undefined || input.auth !== undefined))
-    throw new Error("Google Vertex apiKey cannot be combined with accessToken or auth")
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "Google Vertex apiKey cannot be combined with accessToken or auth",
+    })
   if (input.accessToken !== undefined || input.auth !== undefined) return undefined
   return input.apiKey ?? process.env.GOOGLE_VERTEX_API_KEY
 }
@@ -68,7 +76,10 @@ const adc = (project?: string) => {
 
 export const oauth = (input: OAuthOptions, project?: string) => {
   if (input.accessToken !== undefined && input.auth !== undefined)
-    throw new Error("Google Vertex accessToken cannot be combined with auth")
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "Google Vertex accessToken cannot be combined with auth",
+    })
   if (input.auth) return input.auth
   if (input.accessToken !== undefined) return Auth.bearer(input.accessToken)
   return adc(project)

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

@@ -6,7 +6,7 @@ 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 { ProviderConfigurationError, ProviderID, type LLMRequest, type ModelID } from "../schema/index.js"
 import { GoogleVertexShared } from "./google-vertex-shared.js"
 
 export interface GeminiOptionsInput extends Gemini.OptionsInput {
@@ -26,6 +26,7 @@ export type Config = RouteDefaultsInput &
   }
 
 export type Settings = ProviderPackage.Settings &
+  GeminiProviderOptionsInput &
   (
     | { readonly accessToken?: string; readonly apiKey?: never }
     | { readonly accessToken?: never; readonly apiKey?: string }
@@ -33,7 +34,6 @@ export type Settings = ProviderPackage.Settings &
     readonly baseURL?: string
     readonly location?: string
     readonly project?: string
-    readonly providerOptions?: GeminiProviderOptionsInput
   }
 
 const fromRequest = Effect.fn("GoogleVertex.fromRequest")(function* (request: LLMRequest) {
@@ -93,7 +93,10 @@ const configuredRoute = (input: Config, modelID: string | ModelID) => {
   const apiKey = GoogleVertexShared.apiKey(input)
   const endpointModel = String(modelID).startsWith("endpoints/")
   if (apiKey !== undefined && endpointModel)
-    throw new Error("Google Vertex tuned models do not support Express Mode API keys")
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "Google Vertex tuned models do not support Express Mode API keys",
+    })
   const location = GoogleVertexShared.location(inputLocation, "us-central1")
   const project = GoogleVertexShared.project(inputProject)
   const endpoint =
@@ -121,16 +124,22 @@ export const provider = {
   id,
   configure,
 }
-export const model: ProviderPackage.Definition<Settings, GeminiProviderOptionsInput>["model"] = (modelID, settings) => {
-  if (settings.apiKey !== undefined && settings.accessToken !== undefined)
-    throw new Error("Google Vertex apiKey cannot be combined with accessToken or auth")
+export const model: ProviderPackage.Definition<Settings, GeminiProviderOptionsInput>["model"] = (
+  modelID,
+  { accessToken, apiKey, baseURL, body, headers, location, project, ...providerOptions },
+) => {
+  if (apiKey !== undefined && accessToken !== undefined)
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "Google Vertex apiKey cannot be combined with accessToken or auth",
+    })
   return configure({
-    ...(settings.apiKey === undefined ? { accessToken: settings.accessToken } : { apiKey: settings.apiKey }),
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    location: settings.location,
-    project: settings.project,
-    providerOptions: settings.providerOptions,
+    ...(apiKey === undefined ? { accessToken: accessToken } : { apiKey: apiKey }),
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    location,
+    project,
+    providerOptions,
   }).model(modelID)
 }

packages/ai/src/providers/google.ts

@@ -20,11 +20,11 @@ export type Config = RouteDefaultsInput &
     readonly providerOptions?: Gemini.ProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: Gemini.ProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  Gemini.ProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const auth = (options: ProviderAuthOption<"optional">) => {
   if ("auth" in options && options.auth) return options.auth
@@ -57,13 +57,16 @@ export const configure = (input: Config = {}) => {
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings, Gemini.ProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, Gemini.ProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export const image = provider.image

packages/ai/src/providers/groq.ts

@@ -26,11 +26,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ProviderOptions
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: ProviderOptions
-}
+export type Settings = ProviderPackage.Settings &
+  ProviderOptions & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const Options = Schema.Struct({
   includeReasoning: Schema.optional(Schema.Boolean),
@@ -103,13 +103,16 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, ProviderOptions>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, ProviderOptions>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as Groq from "./groq.js"

packages/ai/src/providers/meta.ts

@@ -79,11 +79,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: ProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  ProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const responsesRoute = Route.make({
   id: "meta-responses",
@@ -169,13 +169,13 @@ export const chatModel: ProviderPackage.Definition<Settings, OpenResponsesProvid
 export const messagesModel: ProviderPackage.Definition<Settings, MessagesOptionsInput>["model"] = (modelID, settings) =>
   fromSettings(settings).messages(modelID)
 
-function fromSettings(settings: Settings) {
+function fromSettings({ apiKey, baseURL, body, headers, ...providerOptions }: Settings) {
   return configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   })
 }
 

packages/ai/src/providers/minimax.ts

@@ -40,11 +40,11 @@ export type Config = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ProviderOptionsInput
   }
 
-export interface Settings<Options = MessagesOptionsInput> extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: Options
-}
+export type Settings<Options = MessagesOptionsInput> = ProviderPackage.Settings &
+  Options & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const ChatOptions = Schema.Struct({
   thinking: Schema.optional(Schema.Struct({ type: Schema.String })),
@@ -127,14 +127,14 @@ export const provider = configure()
 
 export const model: ProviderPackage.Definition<Settings<MessagesOptionsInput>, MessagesOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export const messages = provider.messages

packages/ai/src/providers/minimax/chat.ts

@@ -3,11 +3,14 @@ import { MiniMax } from "../minimax.js"
 
 export type Settings = MiniMax.Settings<MiniMax.ChatOptionsInput>
 
-export const model: ProviderPackage.Definition<Settings, MiniMax.ChatOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, MiniMax.ChatOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   MiniMax.configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).chat(modelID)

packages/ai/src/providers/minimax/responses.ts

@@ -5,12 +5,12 @@ export type Settings = MiniMax.Settings<MiniMax.ResponsesOptionsInput>
 
 export const model: ProviderPackage.Definition<Settings, MiniMax.ResponsesOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   MiniMax.configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).responses(modelID)

packages/ai/src/providers/mistral.ts

@@ -14,11 +14,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ProviderOptions
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: ProviderOptions
-}
+export type Settings = ProviderPackage.Settings &
+  ProviderOptions & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = MistralChat.route
 export const routes = [route]
@@ -39,13 +39,16 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, ProviderOptions>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, ProviderOptions>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as Mistral from "./mistral.js"

packages/ai/src/providers/moonshot.ts

@@ -42,11 +42,11 @@ export type Config = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ChatOptionsInput | MessagesOptionsInput | ResponsesOptionsInput
   }
 
-export interface Settings<Options = ChatOptionsInput> extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: Options
-}
+export type Settings<Options = ChatOptionsInput> = ProviderPackage.Settings &
+  Options & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const ChatOptions = Schema.Struct({
   reasoningEffort: Schema.optional(Schema.String),
@@ -133,13 +133,16 @@ export const chat = provider.chat
 export const messages = provider.messages
 export const responses = provider.responses
 
-export const model: ProviderPackage.Definition<Settings, ChatOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, ChatOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as Moonshot from "./moonshot.js"

packages/ai/src/providers/moonshot/messages.ts

@@ -5,12 +5,12 @@ export type Settings = Moonshot.Settings<Moonshot.MessagesOptionsInput>
 
 export const model: ProviderPackage.Definition<Settings, Moonshot.MessagesOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   Moonshot.configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).messages(modelID)

packages/ai/src/providers/moonshot/responses.ts

@@ -5,12 +5,12 @@ export type Settings = Moonshot.Settings<Moonshot.ResponsesOptionsInput>
 
 export const model: ProviderPackage.Definition<Settings, Moonshot.ResponsesOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   Moonshot.configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).responses(modelID)

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

@@ -16,12 +16,12 @@ export type Config = RouteDefaultsInput &
     readonly providerOptions?: OpenResponsesProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL: string
-  readonly provider?: string
-  readonly providerOptions?: OpenResponsesProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenResponsesProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL: string
+    readonly provider?: string
+  }
 
 export const routes = [OpenAICompatibleResponses.route]
 
@@ -48,13 +48,13 @@ export const provider = {
 
 export const model: ProviderPackage.Definition<Settings, OpenResponsesProviderOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, provider, ...providerOptions },
 ) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    provider: settings.provider,
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    provider,
+    providerOptions,
   }).model(modelID)

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

@@ -14,12 +14,12 @@ type GenericModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL: string
-  readonly provider?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL: string
+    readonly provider?: string
+  }
 
 export const routes = [OpenAICompatibleChat.route]
 
@@ -45,14 +45,17 @@ export const provider = {
   configure,
 }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, provider, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    provider: settings.provider,
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    provider,
+    providerOptions,
   }).model(modelID)
 
 export * as OpenAICompatible from "./openai-compatible.js"

packages/ai/src/providers/openai.ts

@@ -57,14 +57,14 @@ export const imageGeneration = (options: ImageGenerationOptions = {}) =>
     },
   })
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly organization?: string
-  readonly project?: string
-  readonly queryParams?: Readonly<Record<string, string>>
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+    readonly organization?: string
+    readonly project?: string
+    readonly queryParams?: Readonly<Record<string, string>>
+  }
 
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "OPENAI_API_KEY")
 
@@ -116,19 +116,28 @@ export const configure = (input: Config = {}) => {
 
 export const provider = configure()
 
-const config = (settings: Settings): Config => {
+const config = ({
+  apiKey,
+  baseURL,
+  body,
+  headers: given,
+  organization,
+  project,
+  queryParams,
+  ...providerOptions
+}: Settings): Config => {
   const headers = {
-    ...(settings.organization === undefined ? {} : { "OpenAI-Organization": settings.organization }),
-    ...(settings.project === undefined ? {} : { "OpenAI-Project": settings.project }),
-    ...settings.headers,
+    ...(organization === undefined ? {} : { "OpenAI-Organization": organization }),
+    ...(project === undefined ? {} : { "OpenAI-Project": project }),
+    ...given,
   }
   return {
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
+    apiKey,
+    baseURL,
     headers: Object.keys(headers).length === 0 ? undefined : headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
-    queryParams: settings.queryParams === undefined ? undefined : { ...settings.queryParams },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
+    queryParams: queryParams === undefined ? undefined : { ...queryParams },
   }
 }
 

packages/ai/src/providers/openrouter.ts

@@ -77,11 +77,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenRouterProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenRouterProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenRouterProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const OpenRouterBody = Schema.StructWithRest(Schema.Struct(OpenAIChat.bodyFields), [
   Schema.Record(Schema.String, Schema.Any),
@@ -191,12 +191,12 @@ export const configure = (input: LanguageModelOptions = {}) => {
 export const provider = configure()
 export const model: ProviderPackage.Definition<Settings, OpenRouterProviderOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)

packages/ai/src/providers/togetherai.ts

@@ -15,11 +15,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  OpenAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export const route = Route.make({
   id: "togetherai-chat",
@@ -52,11 +52,14 @@ export const configure = (input: LanguageModelOptions = {}) => {
 
 export const provider = configure()
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)

packages/ai/src/providers/xai.ts

@@ -20,11 +20,11 @@ export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: XAIProviderOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: XAIProviderOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  XAIProviderOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export type { XAIImageOptions } from "../protocols/xai-images.js"
 
@@ -41,6 +41,10 @@ const responsesRoute = Route.make({
     id: "openai-responses",
     name: "xAI Responses",
     rotateAfterMs: RESPONSES_WEBSOCKET_ROTATE_AFTER_MS,
+    // xAI continues a chain only from stored responses: with `store: false` (the route default) `previous_response_id`
+    // fails with "Response with id=… not found", so those steps are sent in full over the reused connection. It also
+    // rejects `instructions` next to `previous_response_id` and keeps the instructions of the response it continues.
+    continuation: ({ instructions: _instructions, ...request }) => (request.store === false ? undefined : request),
   }),
   defaults: { providerOptions: { store: false, include: ["reasoning.encrypted_content"] } },
 })
@@ -106,13 +110,13 @@ export const model: ProviderPackage.Definition<
   Settings,
   XAIProviderOptionsInput,
   typeof responsesRoute.compact
->["model"] = (modelID, settings) =>
+>["model"] = (modelID, { apiKey, baseURL, body, headers, ...providerOptions }) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 export const responses = provider.responses
 export const chat = provider.chat

packages/ai/src/providers/zai-coding-plan.ts

@@ -23,11 +23,11 @@ export type Config = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ChatOptionsInput | MessagesOptionsInput | ResponsesOptionsInput
   }
 
-export interface Settings<Options = ChatOptionsInput> extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: Options
-}
+export type Settings<Options = ChatOptionsInput> = ProviderPackage.Settings &
+  Options & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 const chatRoute = Route.make({
   id: "zai-coding-chat",
@@ -80,13 +80,16 @@ export const chat = provider.chat
 export const messages = provider.messages
 export const responses = provider.responses
 
-export const model: ProviderPackage.Definition<Settings, ChatOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, ChatOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as ZAICodingPlan from "./zai-coding-plan.js"

packages/ai/src/providers/zai-coding-plan/messages.ts

@@ -5,12 +5,12 @@ export type Settings = ZAICodingPlan.Settings<ZAICodingPlan.MessagesOptionsInput
 
 export const model: ProviderPackage.Definition<Settings, ZAICodingPlan.MessagesOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   ZAICodingPlan.configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).messages(modelID)

packages/ai/src/providers/zai-coding-plan/responses.ts

@@ -5,12 +5,12 @@ export type Settings = ZAICodingPlan.Settings<ZAICodingPlan.ResponsesOptionsInpu
 
 export const model: ProviderPackage.Definition<Settings, ZAICodingPlan.ResponsesOptionsInput>["model"] = (
   modelID,
-  settings,
+  { apiKey, baseURL, body, headers, ...providerOptions },
 ) =>
   ZAICodingPlan.configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).responses(modelID)

packages/ai/src/providers/zai.ts

@@ -17,11 +17,11 @@ export type Config = Omit<RouteDefaultsInput, "providerOptions"> &
     readonly providerOptions?: ChatOptionsInput
   }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly baseURL?: string
-  readonly providerOptions?: ChatOptionsInput
-}
+export type Settings = ProviderPackage.Settings &
+  ChatOptionsInput & {
+    readonly apiKey?: string
+    readonly baseURL?: string
+  }
 
 export type { ZAIImageOptions } from "../protocols/zai-images.js"
 
@@ -70,13 +70,16 @@ export const provider = configure()
 export const image = provider.image
 export const chat = provider.chat
 
-export const model: ProviderPackage.Definition<Settings, ChatOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, ChatOptionsInput>["model"] = (
+  modelID,
+  { apiKey, baseURL, body, headers, ...providerOptions },
+) =>
   configure({
-    apiKey: settings.apiKey,
-    baseURL: settings.baseURL,
-    headers: settings.headers,
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+    apiKey,
+    baseURL,
+    headers,
+    http: body === undefined ? undefined : { body: { ...body } },
+    providerOptions,
   }).model(modelID)
 
 export * as ZAI from "./zai.js"

packages/ai/src/route/client.ts

@@ -23,6 +23,7 @@ import {
   LanguageModel,
   LLMEvent,
   InvalidProviderOutputError,
+  ProviderConfigurationError,
   ProviderID,
   mergeGenerationOptions,
   mergeHttpOptions,
@@ -128,7 +129,10 @@ const makeRouteLanguageModel = <Options extends ProviderOptions, Compact extends
   const provider = route.provider ?? ("provider" in mapped ? mapped.provider : undefined)
   if (!provider) throw new Error(`Route.model(${route.id}) requires a provider`)
   if (!endpointBaseURL(route.endpoint))
-    throw new Error(`Route.model(${route.id}) requires an endpoint baseURL — configure it on the route first`)
+    throw new ProviderConfigurationError({
+      provider: ProviderID.make(provider),
+      message: `Route.model(${route.id}) requires an endpoint baseURL — configure it on the route first`,
+    })
   return LanguageModel.make<Options, Compact>({
     ...mapped,
     provider,

packages/ai/src/schema/errors.ts

@@ -50,6 +50,19 @@ export class UnsupportedOperationError extends Schema.TaggedError<UnsupportedOpe
   route: Schema.optional(RouteID),
 }) {}
 
+/**
+ * Provider settings that are missing, conflicting, or unsupported, such as
+ * Azure without `resourceName` or `baseURL`. Thrown synchronously while a
+ * provider facade or package entrypoint configures a model, before any
+ * request exists, so it is not an `AIError` reason.
+ */
+export class ProviderConfigurationError extends Schema.TaggedError<ProviderConfigurationError>(
+  "AI.Error.ProviderConfiguration",
+)("ProviderConfiguration", {
+  provider: ProviderID,
+  message: Schema.String,
+}) {}
+
 export class NoRouteError extends Schema.TaggedError<NoRouteError>("AI.Error.NoRoute")("NoRoute", {
   ...ReasonFields,
   route: RouteID,

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

@@ -3,6 +3,9 @@ import { model } from "@opencode/ai/providers/openai"
 import { LLM } from "../src/index.js"
 import { Endpoint } from "../src/route/endpoint.js"
 
+const configuration = (provider: string, message: string) =>
+  expect.objectContaining({ _tag: "ProviderConfiguration", provider, message })
+
 describe("provider package entrypoints", () => {
   test("semantic API aliases expose the same contract", async () => {
     const modules = await Promise.all([
@@ -185,13 +188,13 @@ describe("provider package entrypoints", () => {
       baseURL: "https://provider.example.test/v1/",
       headers: { "x-application": "opencode" },
       body: { service_tier: "priority" },
-      providerOptions: { reasoningEffort: "high" as const },
+      reasoningEffort: "high" as const,
     }
     const deepinfra = DeepInfra.model("google/gemma-3-27b-it", settings)
 
     expect(deepinfra.route.id).toBe("deepinfra-chat")
     expect(deepinfra.route.endpoint.baseURL).toBe("https://provider.example.test/v1/openai")
-    expect(deepinfra.route.defaults.providerOptions).toEqual(settings.providerOptions)
+    expect(deepinfra.route.defaults.providerOptions).toEqual({ reasoningEffort: "high" })
     expect(deepinfra.route.defaults.headers).toEqual(settings.headers)
     expect(deepinfra.route.defaults.http?.body).toEqual(settings.body)
   })
@@ -207,7 +210,7 @@ describe("provider package entrypoints", () => {
         apiKey: "fixture",
         headers: { "x-application": "opencode" },
         body: { custom: true },
-        providerOptions: { reasoningEffort: "high" },
+        reasoningEffort: "high",
       })
       expect(selected.provider).toBe(provider.id)
       expect(selected.route.endpoint.baseURL).toBe(provider.baseURL({ accountId: "account" }))
@@ -228,11 +231,11 @@ describe("provider package entrypoints", () => {
     }
     const openrouter = OpenRouter.model("anthropic/claude-sonnet-4", {
       ...settings,
-      providerOptions: { usage: true },
+      usage: true,
     })
     const xai = XAI.model("grok-4", {
       ...settings,
-      providerOptions: { reasoningEffort: "high" },
+      reasoningEffort: "high",
     })
 
     for (const selected of [openrouter, xai]) {
@@ -266,7 +269,8 @@ describe("provider package entrypoints", () => {
       provider: "example",
       headers: { "x-application": "opencode" },
       body: { service_tier: "priority" },
-      providerOptions: { reasoningEffort: "low", store: true },
+      reasoningEffort: "low",
+      store: true,
     })
 
     expect(String(selected.provider)).toBe("example")
@@ -292,7 +296,7 @@ describe("provider package entrypoints", () => {
       provider: "example",
       headers: { "x-application": "opencode" },
       body: { metadata: { user_id: "user_1" } },
-      providerOptions: { effort: "low" },
+      effort: "low",
     })
 
     expect(String(selected.provider)).toBe("example")
@@ -312,7 +316,7 @@ describe("provider package entrypoints", () => {
     const Anthropic = await import("@opencode/ai/providers/anthropic")
     const selected = Anthropic.model("claude-sonnet-4-6", {
       apiKey: "fixture",
-      providerOptions: { thinking: { type: "adaptive" } },
+      thinking: { type: "adaptive" },
     })
 
     expect(selected.route.defaults.providerOptions).toEqual({ thinking: { type: "adaptive" } })
@@ -322,7 +326,7 @@ describe("provider package entrypoints", () => {
     const AnthropicCompatible = await import("@opencode/ai/providers/anthropic-compatible")
     expect(() =>
       Reflect.apply(AnthropicCompatible.model, undefined, ["compatible-model", { apiKey: "fixture" }]),
-    ).toThrow("Anthropic-compatible providers require a baseURL")
+    ).toThrow(configuration("anthropic-compatible", "Anthropic-compatible providers require a baseURL"))
   })
 
   test("rejects conflicting Anthropic-compatible auth settings at runtime", async () => {
@@ -337,10 +341,10 @@ describe("provider package entrypoints", () => {
           baseURL: "https://messages.example.test/v1",
         },
       ]),
-    ).toThrow("Anthropic-compatible apiKey cannot be combined with authToken")
+    ).toThrow(configuration("anthropic-compatible", "Anthropic-compatible apiKey cannot be combined with authToken"))
     expect(() =>
       Reflect.apply(Anthropic.model, undefined, ["claude-sonnet-4-6", { apiKey: "fixture", authToken: "token" }]),
-    ).toThrow("Anthropic apiKey cannot be combined with authToken")
+    ).toThrow(configuration("anthropic", "Anthropic apiKey cannot be combined with authToken"))
   })
 
   test("maps legacy OpenAI organization and project settings to headers", () => {
@@ -406,7 +410,7 @@ describe("provider package entrypoints", () => {
       baseURL: "https://generativelanguage.test/v1beta",
       headers: { "x-application": "opencode" },
       body: { safetySettings: [] },
-      providerOptions: { thinkingConfig: { thinkingBudget: 1_024 } },
+      thinkingConfig: { thinkingBudget: 1_024 },
     })
 
     expect(selected.route.id).toBe("gemini")
@@ -490,43 +494,45 @@ describe("provider package entrypoints", () => {
         "gemini-3.5-flash",
         { accessToken: "token", apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex apiKey cannot be combined with accessToken or auth")
+    ).toThrow(configuration("google-vertex", "Google Vertex apiKey cannot be combined with accessToken or auth"))
     const configured = Reflect.apply(GoogleVertex.configure, undefined, [
       { accessToken: "token", auth: {}, project: "vertex-project" },
     ])
-    expect(() => configured.model("gemini-3.5-flash")).toThrow("Google Vertex accessToken cannot be combined with auth")
+    expect(() => configured.model("gemini-3.5-flash")).toThrow(
+      configuration("google-vertex", "Google Vertex accessToken cannot be combined with auth"),
+    )
     expect(() =>
       Reflect.apply(GoogleVertexMessages.model, undefined, [
         "claude-sonnet-4-6",
         { apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex Messages does not support API keys")
+    ).toThrow(configuration("google-vertex", "Google Vertex Messages does not support API keys"))
     expect(() =>
       Reflect.apply(Providers.GoogleVertexMessages.configure, undefined, [
         { apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex Messages does not support API keys")
+    ).toThrow(configuration("google-vertex", "Google Vertex Messages does not support API keys"))
     expect(() =>
       Reflect.apply(GoogleVertexChat.model, undefined, [
         "deepseek-ai/deepseek-v3.2-maas",
         { apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex Chat does not support API keys")
+    ).toThrow(configuration("google-vertex", "Google Vertex Chat does not support API keys"))
     expect(() =>
       Reflect.apply(Providers.GoogleVertexChat.configure, undefined, [
         { apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex Chat does not support API keys")
+    ).toThrow(configuration("google-vertex", "Google Vertex Chat does not support API keys"))
     expect(() =>
       Reflect.apply(GoogleVertexResponses.model, undefined, [
         "xai/grok-4.20-reasoning",
         { apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex Responses does not support API keys")
+    ).toThrow(configuration("google-vertex", "Google Vertex Responses does not support API keys"))
     expect(() =>
       Reflect.apply(Providers.GoogleVertexResponses.configure, undefined, [
         { apiKey: "fixture", project: "vertex-project" },
       ]),
-    ).toThrow("Google Vertex Responses does not support API keys")
+    ).toThrow(configuration("google-vertex", "Google Vertex Responses does not support API keys"))
   })
 })

packages/ai/test/provider/alibaba.test.ts

@@ -76,7 +76,13 @@ it.effect("Alibaba owns regional shared and workspace-specific endpoints", () =>
 
 test("Alibaba requires explicit placement and supports complete base URL overrides", () => {
   for (const region of ["eu-central-1", "ap-northeast-1", "future-region"])
-    expect(() => Alibaba.configure({ region })).toThrow("requires workspaceID or baseURL")
+    expect(() => Alibaba.configure({ region })).toThrow(
+      expect.objectContaining({
+        _tag: "ProviderConfiguration",
+        provider: "alibaba",
+        message: `Alibaba region ${region} requires workspaceID or baseURL`,
+      }),
+    )
   for (const config of [
     { baseURL: "https://gateway.example/prefix" },
     { region: "future-region", workspaceID: "ignored", baseURL: "https://gateway.example/prefix" },

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

@@ -69,7 +69,9 @@ for (const model of [
       dynamicResponse(({ request, text, respond }) =>
         Effect.sync(() => {
           const body = JSON.parse(text)
-          expect(request.headers["anthropic-beta"]).toBe("existing-beta,compact-2026-01-12")
+          expect(request.headers["anthropic-beta"]).toBe(
+            "existing-beta,interleaved-thinking-2025-05-14,compact-2026-01-12",
+          )
           if (body.messages.length === 1) {
             expect(body.context_management.edits).toEqual([
               {

packages/ai/test/provider/anthropic-thinking-binding.test.ts

@@ -32,7 +32,9 @@ for (const [id, enabled] of [
         enabled ? { type: "adaptive", block_binding: { prefix_mismatch_behavior: "drop_block" } } : undefined,
       )
       expect(prepared.request.headers["anthropic-beta"]).toBe(
-        enabled ? "existing-beta,thinking-binding-controls-2026-08-01" : "existing-beta",
+        enabled
+          ? "existing-beta,interleaved-thinking-2025-05-14,thinking-binding-controls-2026-08-01"
+          : "existing-beta,interleaved-thinking-2025-05-14",
       )
     }),
   )
@@ -53,7 +55,9 @@ it.effect("preserves explicit thinking settings and combines required beta heade
       const prepared = yield* AnthropicMessages.route.prepareTransport(compiled.body, request)
       expect(compiled.body.thinking).toEqual(thinking)
       expect(prepared.request.headers["anthropic-beta"]).toBe(
-        thinking.type === "disabled" ? "compact-2026-01-12" : "compact-2026-01-12,thinking-binding-controls-2026-08-01",
+        thinking.type === "disabled"
+          ? "interleaved-thinking-2025-05-14,compact-2026-01-12"
+          : "interleaved-thinking-2025-05-14,compact-2026-01-12,thinking-binding-controls-2026-08-01",
       )
     }
   }),

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

@@ -1458,7 +1458,13 @@ describe("Bedrock Converse route", () => {
         expect(headers.get("authorization")).toContain("Credential=AKIACHAINEXAMPLE/")
         expect(headers.get("authorization")).toContain("/ap-southeast-2/bedrock/aws4_request")
       }
-      expect(() => AmazonBedrock.configure({ auth: "sigv4", apiKey: "k" })).toThrow("does not accept apiKey")
+      expect(() => AmazonBedrock.configure({ auth: "sigv4", apiKey: "k" })).toThrow(
+        expect.objectContaining({
+          _tag: "ProviderConfiguration",
+          provider: "amazon-bedrock",
+          message: "Amazon Bedrock SigV4 auth does not accept apiKey",
+        }),
+      )
     }).pipe(
       withProcessEnv({
         ...noAmbientAWS,

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

@@ -378,7 +378,11 @@ describe("Google Vertex providers", () => {
 
   test("rejects tuned Gemini models in express mode", () => {
     expect(() => GoogleVertex.configure({ apiKey: "fixture" }).model("endpoints/1234567890")).toThrow(
-      "Google Vertex tuned models do not support Express Mode API keys",
+      expect.objectContaining({
+        _tag: "ProviderConfiguration",
+        provider: "google-vertex",
+        message: "Google Vertex tuned models do not support Express Mode API keys",
+      }),
     )
   })
 })

packages/ai/test/provider/groq.test.ts

@@ -34,12 +34,10 @@ it.effect("Groq lowers its own options for custom catalog identities and endpoin
         baseURL: "https://gateway.example/v1",
         headers: { "x-client": "test" },
         body: { custom: "value" },
-        providerOptions: {
-          reasoningEffort: "default",
-          parallelToolCalls: true,
-          serviceTier: "flex",
-          user: "test-user",
-        },
+        reasoningEffort: "default",
+        parallelToolCalls: true,
+        serviceTier: "flex",
+        user: "test-user",
       }),
       { provider: "custom-groq" },
     )

packages/ai/test/provider/meta.test.ts

@@ -87,7 +87,7 @@ it.effect("Meta package selectors preserve overrides and Chat token policy on cu
         baseURL: "https://gateway.example/v1",
         headers: { "x-client": "test" },
         body: { custom: "value" },
-        providerOptions: { reasoningEffort: "future-effort" },
+        reasoningEffort: "future-effort",
       })
       expect(model.route.endpoint.baseURL).toBe("https://gateway.example/v1")
       expect(model.route.defaults.headers).toEqual({ "x-client": "test" })

packages/ai/test/provider/native-providers.test.ts

@@ -99,7 +99,7 @@ describe("native OpenAI-compatible providers", () => {
         const settings = {
           apiKey: "fixture",
           baseURL: "https://gateway.example/v1",
-          providerOptions: { reasoningEffort: "high" },
+          reasoningEffort: "high",
         }
         const selected = provider.configure(settings).model("test-model")
         expect(selected.provider).toBe(provider.id)
@@ -143,7 +143,7 @@ describe("native OpenAI-compatible providers", () => {
           tools: [
             ToolDefinition.make({ name: "lookup", description: "Look up data", inputSchema: { type: "object" } }),
           ],
-          providerOptions: { store: true },
+          store: true,
         }),
       )
 
@@ -168,7 +168,7 @@ describe("native OpenAI-compatible providers", () => {
             ]),
             Message.user("Continue."),
           ],
-          providerOptions: { store: true },
+          store: true,
         }),
       )
 
@@ -206,7 +206,7 @@ describe("native OpenAI-compatible providers", () => {
         baseURL: "https://gateway.example/v1",
         headers: { "x-application": "opencode" },
         body: { service_tier: "priority" },
-        providerOptions: { reasoningEffort: "high" },
+        reasoningEffort: "high",
       })
 
       expect(selected.route.endpoint.baseURL).toBe("https://gateway.example/v1")

packages/ai/test/provider/open-responses-errors.test.ts

@@ -0,0 +1,78 @@
+import { expect } from "bun:test"
+import { Effect, Schema } from "effect"
+import { LLM, LLMClient } from "../../src/index.js"
+import { OpenResponses } from "../../src/protocols/open-responses.js"
+import { Meta } from "../../src/providers/index.js"
+import { configure } from "../../src/providers/openai-compatible-responses.js"
+import { it } from "../lib/effect.js"
+import { fixedResponse } from "../lib/http.js"
+import { sseEvents } from "../lib/sse.js"
+
+const decodeEvent = Schema.decodeUnknownEffect(OpenResponses.protocol.stream.event)
+
+it.effect("normalizes flat errors in shared SSE and WebSocket decoding", () =>
+  Effect.gen(function* () {
+    const frame = {
+      type: "error",
+      sequence_number: 4,
+      code: "server_shutting_down",
+      message: "Server is shutting down. Please retry your request.",
+      param: null,
+    }
+    for (const decode of [decodeEvent, OpenResponses.decodeChannelEvent]) {
+      const event = yield* decode(JSON.stringify(frame))
+      expect(event).toEqual({
+        type: "error",
+        sequence_number: 4,
+        error: { code: frame.code, message: frame.message, param: null },
+      })
+
+      for (const unchanged of [
+        event,
+        { type: "error" },
+        {
+          type: "response.failed",
+          response: { id: "resp_failed", error: { code: "server_error", message: "Internal server error" } },
+        },
+        { type: "response.output_text.delta", item_id: "msg_text", delta: "Hello" },
+      ]) {
+        expect(yield* decode(JSON.stringify(unchanged))).toEqual(unchanged)
+      }
+    }
+  }),
+)
+
+it.effect("continues to normalize untyped xAI WebSocket errors", () =>
+  Effect.gen(function* () {
+    const frame = { error: { type: "api_error", message: "gRPC error: Response with id=resp_missing not found" } }
+    expect(yield* OpenResponses.decodeChannelEvent(JSON.stringify(frame))).toEqual({ ...frame, type: "error" })
+  }),
+)
+
+it.effect("retains classification and original error bodies through Meta and generic Responses routes", () =>
+  Effect.gen(function* () {
+    const raw = `{
+  "type": "error",
+  "sequence_number": 4,
+  "code": "server_shutting_down",
+  "message": "Server is shutting down. Please retry your request.",
+  "param": null,
+  "diagnostic": "retain-original-frame"
+}`
+    for (const model of [
+      Meta.configure({ apiKey: "fixture" }).responses("muse-spark-1.3"),
+      configure({ apiKey: "fixture", provider: "gateway", baseURL: "https://responses.example.test/v1" }).model(
+        "example-model",
+      ),
+    ]) {
+      const error = yield* LLMClient.generate(LLM.request({ model, prompt: "Hello" })).pipe(
+        Effect.provide(fixedResponse(sseEvents(raw.replaceAll("\n", "\ndata: ")))),
+        Effect.flip,
+      )
+      expect(error.reason._tag).toBe("ProviderInternal")
+      expect(error.message).toBe("server_shutting_down: Server is shutting down. Please retry your request.")
+      expect(error.reason.body).toBe(raw)
+      expect(error.reason.http?.status).toBe(200)
+    }
+  }),
+)

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

@@ -90,7 +90,11 @@ const classifyingChannelDriver = (message: string): WebSocketChannelDriver => {
   }
 }
 
-const continuationDriver = (request: Readonly<Record<string, unknown>>, base = baseChannelDriver) => {
+const continuationDriver = (
+  request: Readonly<Record<string, unknown>>,
+  base = baseChannelDriver,
+  continuation?: OpenResponsesContinuation.Shape,
+) => {
   const message = ProviderShared.encodeJson(request)
   return OpenResponsesContinuation.driver({
     id: "openai-responses",
@@ -98,6 +102,7 @@ const continuationDriver = (request: Readonly<Record<string, unknown>>, base = b
     request,
     message,
     base: base(message),
+    continuation,
   })
 }
 
@@ -921,6 +926,58 @@ describe("OpenAI Responses route", () => {
         type: "provider-failure",
         error: { reason: { _tag: "InvalidRequest", classification: "context-overflow" } },
       })
+
+      // A retryable failure stays one: the runner retries it, and the transport has already dropped the
+      // checkpoint, so that retry is a full send. xAI reports every rejection this way.
+      const internal = ProviderShared.encodeJson({
+        type: "error",
+        error: { type: "api_error", message: "gRPC error: Response with id=resp_1 not found" },
+      })
+      expect(yield* second.observe(yield* second.create(saved), internal)).toMatchObject({
+        type: "provider-failure",
+        error: { reason: { _tag: "ProviderInternal" } },
+      })
+    }),
+  )
+
+  it.effect("shapes the incremental send with the route continuation", () =>
+    Effect.gen(function* () {
+      const firstRequest = {
+        type: "response.create",
+        model: "grok-4.6",
+        store: true,
+        instructions: "You are terse.",
+        input: [{ role: "user", content: [{ type: "input_text", text: "First" }] }],
+      }
+      const secondRequest = {
+        ...firstRequest,
+        input: [...firstRequest.input, { role: "user", content: [{ type: "input_text", text: "Second" }] }],
+      }
+      const saved = checkpoint(
+        yield* continuationDriver(firstRequest).observe(
+          yield* continuationDriver(firstRequest).create(undefined),
+          ProviderShared.encodeJson({ type: "response.completed", response: { id: "resp_1" } }),
+        ),
+      )
+
+      const trimmed = yield* continuationDriver(
+        secondRequest,
+        baseChannelDriver,
+        ({ instructions: _, ...rest }) => rest,
+      ).create(saved)
+      expect(trimmed.mode).toBe("incremental")
+      expect(JSON.parse(trimmed.message)).toEqual({
+        type: "response.create",
+        model: "grok-4.6",
+        store: true,
+        previous_response_id: "resp_1",
+        input: [{ role: "user", content: [{ type: "input_text", text: "Second" }] }],
+      })
+
+      // Declining the continuation sends the step in full and never sends a previous_response_id.
+      const declined = yield* continuationDriver(secondRequest, baseChannelDriver, () => undefined).create(saved)
+      expect(declined.mode).toBe("full")
+      expect(JSON.parse(declined.message)).toEqual(secondRequest)
     }),
   )
 

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

@@ -1,11 +1,18 @@
 import { describe, expect } from "bun:test"
-import { Effect } from "effect"
+import { Effect, Layer, Stream } from "effect"
 import { LLM, LLMEvent, Message } from "../../src/index.js"
 import { XAI } from "../../src/providers.js"
 import { OpenResponses } from "../../src/protocols/open-responses.js"
 import { OpenAIResponses } from "../../src/protocols/openai-responses.js"
+import * as ProviderShared from "../../src/protocols/shared.js"
 import { XAIResponses } from "../../src/protocols/xai-responses.js"
-import { LLMClient } from "../../src/route.js"
+import {
+  LLMClient,
+  RequestExecutor,
+  WebSocketTransport,
+  type ChannelCheckpoint,
+  type WebSocketChannelDriver,
+} from "../../src/route.js"
 import { compileRequest } from "../../src/route/client.js"
 import { it } from "../lib/effect.js"
 import { fixedResponse } from "../lib/http.js"
@@ -13,6 +20,35 @@ import { sseEvents } from "../lib/sse.js"
 
 const model = XAI.configure({ apiKey: "test", baseURL: "https://api.x.ai/v1" }).responses("grok-4.6")
 
+/** Runs a request through the WebSocket transport and hands back its channel driver; the HTTP fallback answers. */
+const channelDriver = (request: ReturnType<typeof LLM.request>) =>
+  Effect.gen(function* () {
+    let driver: WebSocketChannelDriver | undefined
+    yield* LLMClient.generate(request, {
+      webSocket: {
+        execute: (exchange) =>
+          Effect.sync(() => {
+            driver = exchange.driver
+            return { frames: exchange.fallback(), complete: Effect.void }
+          }),
+      },
+    }).pipe(Effect.provide(fixedResponse(sseEvents({ type: "response.completed", response: { id: "http" } }))))
+    if (!driver) throw new Error("Expected a WebSocket channel driver")
+    return driver
+  })
+
+const completed = (driver: WebSocketChannelDriver, id: string) =>
+  Effect.gen(function* () {
+    const create = yield* driver.create(undefined)
+    yield* driver.observe(create, ProviderShared.encodeJson({ type: "response.created", response: { id } }))
+    const observation = yield* driver.observe(
+      create,
+      ProviderShared.encodeJson({ type: "response.completed", response: { id } }),
+    )
+    if (observation.type !== "completed" || !observation.checkpoint) throw new Error("Expected a checkpoint")
+    return observation.checkpoint
+  })
+
 describe("xAI Responses route", () => {
   it.effect("composes the Open Responses baseline with xAI extensions", () =>
     Effect.gen(function* () {
@@ -162,6 +198,78 @@ describe("xAI Responses route", () => {
     }),
   )
 
+  it.effect("classifies xAI's untyped WebSocket error envelope", () =>
+    Effect.gen(function* () {
+      // xAI answers a rejected response.create with an error envelope that carries no event type.
+      const envelope = ProviderShared.encodeJson({
+        error: {
+          message:
+            'Request validation error: {"code":"400","error":"Argument not supported: instructions and previous_response_id together"}',
+          type: "api_error",
+        },
+      })
+      const webSocket = WebSocketTransport.makeDirect({
+        open: () =>
+          Effect.succeed({ sendText: () => Effect.void, messages: Stream.make(envelope), close: Effect.void }),
+      })
+      const error = yield* LLMClient.generate(LLM.request({ model, prompt: "Hello" }), { webSocket }).pipe(
+        Effect.provide(
+          LLMClient.layer.pipe(
+            Layer.provide(
+              Layer.succeed(
+                RequestExecutor.Service,
+                RequestExecutor.Service.of({ execute: () => Effect.die("unexpected HTTP request") }),
+              ),
+            ),
+          ),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason._tag).toBe("ProviderInternal")
+      expect(error.message).toContain("Argument not supported: instructions and previous_response_id together")
+      expect(error.reason.body).toBe(envelope)
+    }),
+  )
+
+  it.effect("continues stored responses without instructions and sends unstored steps in full", () =>
+    Effect.gen(function* () {
+      const step = (store: boolean, ...prompts: string[]) =>
+        LLM.request({
+          model,
+          system: "You are terse.",
+          messages: prompts.map((prompt) => Message.user(prompt)),
+          providerOptions: { store },
+        })
+      const send = (store: boolean, checkpoint: ChannelCheckpoint) =>
+        channelDriver(step(store, "First", "Second")).pipe(Effect.flatMap((driver) => driver.create(checkpoint)))
+
+      const stored = yield* send(true, yield* completed(yield* channelDriver(step(true, "First")), "resp_1"))
+      expect(stored.mode).toBe("incremental")
+      expect(JSON.parse(stored.message)).toEqual({
+        type: "response.create",
+        model: "grok-4.6",
+        store: true,
+        include: ["reasoning.encrypted_content"],
+        previous_response_id: "resp_1",
+        input: [{ role: "user", content: [{ type: "input_text", text: "Second" }] }],
+      })
+
+      // The connection cache only serves stored responses, so the default store: false never chains.
+      const unstored = yield* send(false, yield* completed(yield* channelDriver(step(false, "First")), "resp_1"))
+      expect(unstored.mode).toBe("full")
+      expect(JSON.parse(unstored.message)).toMatchObject({
+        instructions: "You are terse.",
+        store: false,
+        input: [
+          { role: "user", content: [{ type: "input_text", text: "First" }] },
+          { role: "user", content: [{ type: "input_text", text: "Second" }] },
+        ],
+      })
+      expect(JSON.parse(unstored.message).previous_response_id).toBeUndefined()
+    }),
+  )
+
   it.effect("parses xAI hosted tool items", () =>
     Effect.gen(function* () {
       const item = { type: "x_search_call", id: "x_search_1", status: "completed", action: { query: "news" } }

packages/app/component-tests/ssh-reconnect.spec.ts

@@ -19,11 +19,13 @@ story("cancelling a version mismatch permits reconnecting again", async ({ mount
   const component = await mount("app-dialog-ssh--incompatible-session")
   await component.getByRole("button", { name: "Reconnect", exact: true }).click()
   const dialog = page.getByRole("dialog")
-  await expect(dialog.getByRole("alert")).toBeVisible()
+  await expect(dialog.getByRole("status")).toContainText("Server update required")
+  await expect(dialog.getByRole("textbox")).toHaveCount(0)
   await dialog.getByRole("button", { name: "Cancel", exact: true }).click()
   await expect(dialog).toHaveCount(0)
   await component.getByRole("button", { name: "Reconnect", exact: true }).click()
-  await expect(dialog.getByRole("alert")).toBeVisible()
+  await expect(dialog.getByRole("status")).toContainText("Server update required")
+  await expect(dialog.getByRole("textbox")).toHaveCount(0)
   await dialog.getByRole("button", { name: "Cancel", exact: true }).click()
   await expect(dialog).toHaveCount(0)
 })
@@ -43,6 +45,17 @@ story("adding a server keeps all SSH challenges in the original connection dialo
   await expect(dialog).toHaveCount(0)
 })
 
+story("adding an incompatible server advances to a dedicated update step", async ({ mount, page }) => {
+  await mount("app-dialog-ssh--incompatible-host")
+  const dialog = page.getByRole("dialog")
+  await dialog.getByRole("textbox", { name: "Host or SSH command" }).fill("ssh devbox")
+  await dialog.getByRole("button", { name: "Add server", exact: true }).click()
+  await expect(dialog.getByRole("status")).toContainText("Server update required")
+  await expect(dialog.getByRole("textbox")).toHaveCount(0)
+  await expect(dialog.getByRole("alert")).toHaveCount(0)
+  await expect(dialog.getByRole("button", { name: "Update and reconnect", exact: true })).toBeVisible()
+})
+
 story("updating an incompatible connection continues authentication in the same dialog", async ({ mount, page }) => {
   const component = await mount("app-dialog-ssh--incompatible-session")
   await component.getByRole("button", { name: "Reconnect", exact: true }).click()

packages/app/e2e/regression/session-timeline-reducer-projection.spec.ts

@@ -115,7 +115,7 @@ test("combines follow-up patches into one three-file stack inside Used", async (
   })
   const group = page.locator('[data-component="collapsed-tool-group"]')
   await group.getByRole("button", { name: "Used 2 Shell, Patch", exact: true }).click()
-  await expect(group.getByText("2 files", { exact: true })).toBeVisible()
+  await expect(group.locator('[data-slot="apply-patch-filename"]')).toHaveText(["a.ts", "b.ts"])
   await timeline.send(
     partUpdated(
       toolPart(
@@ -134,7 +134,6 @@ test("combines follow-up patches into one three-file stack inside Used", async (
     "true",
   )
   await expect(group.locator('[data-component="apply-patch-tool"]')).toHaveCount(1)
-  await expect(group.getByText("3 files", { exact: true })).toBeVisible()
   await expect(group.locator('[data-slot="apply-patch-filename"]')).toHaveText(["a.ts", "b.ts", "c.ts"])
 })
 

packages/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode/app",
-  "version": "1.18.15",
+  "version": "2.0.0",
   "description": "",
   "type": "module",
   "exports": {

packages/app/src/composer/submit.ts

@@ -126,15 +126,9 @@ export function createComposerSubmit(input: ComposerSubmitInput) {
 
       if (command) {
         clearSubmission(input, submission)
-        // Commands always steer: the server applies a command's configured
-        // agent and model immediately at admission, so queueing one would
-        // reconfigure the turn it is supposed to wait behind.
-        void sendCommand(
-          session,
-          { ...value, delivery: "steer" },
-          command,
-          input.adapter.controls().model.selection.trackSessionCommit,
-        ).catch((error) => failSubmission(input, session, "command", error, restore, value.id))
+        void sendCommand(session, value, command, input.adapter.controls().model.selection.trackSessionCommit).catch(
+          (error) => failSubmission(input, session, "command", error, restore, value.id),
+        )
         return
       }
     } finally {
@@ -326,7 +320,8 @@ async function sendCommand(
   track?: ModelSelection["trackSessionCommit"],
 ) {
   const request = await buildSubmissionRequest(session, value)
-  await applySelection(session, value.selection, track)
+  // Like queued prompts, queued commands must not apply the composer's selection to active work.
+  if (value.delivery === "steer") await applySelection(session, value.selection, track)
   await session.api.command({
     sessionID: session.id,
     command: command.command,

packages/app/src/runtime/i18n/desktop-native.ts

@@ -285,7 +285,7 @@ export const DESKTOP_NATIVE_ENGLISH = {
   "desktop.updater.dialog.later": "Later",
 
   "desktop.cli.installed.title": "CLI Installed",
-  "desktop.cli.installed.message": "CLI installed to {{path}}\n\nRestart your terminal to use the 'opencode2' command.",
+  "desktop.cli.installed.message": "CLI installed to {{path}}\n\nRestart your terminal to use the 'opencode' command.",
   "desktop.cli.failed.title": "Installation Failed",
   "desktop.cli.failed.message": "Failed to install CLI: {{error}}",
 

packages/app/src/runtime/platform/web.ts

@@ -54,8 +54,12 @@ export function createWebPlatform(version: string) {
 
 function getCurrentServerUrl() {
   if (import.meta.env.VITE_OPENCODE_SERVER_MODE === "none") return undefined
-  if (import.meta.env.DEV)
-    return `http://${import.meta.env.VITE_OPENCODE_SERVER_HOST ?? "localhost"}:${import.meta.env.VITE_OPENCODE_SERVER_PORT ?? "4096"}`
+  if (import.meta.env.DEV) {
+    const loopback =
+      location.hostname === "localhost" || location.hostname === "[::1]" || location.hostname.startsWith("127.")
+    const host = import.meta.env.VITE_OPENCODE_SERVER_HOST ?? (loopback ? location.hostname : "localhost")
+    return `http://${host}:${import.meta.env.VITE_OPENCODE_SERVER_PORT ?? "4096"}`
+  }
   return location.origin
 }
 

packages/app/src/runtime/server/runtime.tsx

@@ -10,6 +10,7 @@ import { createData } from "@opencode/client/solid"
 import type { ServerScope } from "@/runtime/server/scope"
 import { createPermissionAutoApprover } from "@/session/requests/auto-approve"
 import { createServerNotificationState } from "@/shell/notifications/notification"
+import { createNotificationCoordinator } from "@/shell/notifications/coordinator"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import { createDesktopData } from "./data"
 import { ModelState } from "./persistence"
@@ -33,6 +34,7 @@ export const { use: useGlobal, provider: GlobalProvider } = createSimpleContext(
       },
     })
     const models = createGlobalModels()
+    const notificationCoordinator = createNotificationCoordinator()
 
     const settingsServer = createMemo(() => {
       const list = server.list
@@ -57,7 +59,7 @@ export const { use: useGlobal, provider: GlobalProvider } = createSimpleContext(
       if (existing) return existing
       const serverCtx = createRoot((dispose) => {
         serverCtxDisposers.set(key, dispose)
-        return createServerController(conn, server.scope(key), server.projects.forServer(key))
+        return createServerController(conn, server.scope(key), server.projects.forServer(key), notificationCoordinator)
       }, owner)
       serverCtxs.set(key, serverCtx)
       return serverCtx
@@ -131,6 +133,7 @@ function createServerController(
   conn: ServerConnection.Any,
   scope: ServerScope,
   projects: ReturnType<typeof createServerProjects>,
+  notificationCoordinator: ReturnType<typeof createNotificationCoordinator>,
 ) {
   const language = useLanguage()
   const settings = useSettings()
@@ -159,7 +162,7 @@ function createServerController(
   })
   const sync = createServerSyncContext(sdk, data)
   createPermissionAutoApprover({ sdk, data })
-  const notification = createServerNotificationState({ sdk, data, key: connKey })
+  const notification = createServerNotificationState({ sdk, data, key: connKey, coordinator: notificationCoordinator })
 
   function enrich(project: { worktree: string; expanded: boolean }) {
     const [childStore] = sync.child(project.worktree, { bootstrap: false })

packages/app/src/servers/ssh/dialog.stories.tsx

@@ -278,6 +278,7 @@ function Open(props: { initial?: string }) {
 export default { title: "App/Dialogs/SSH", id: "app-dialog-ssh" }
 export const AuthenticationRequired = { render: () => <Fixture initial="required" /> }
 export const SettingsReconnect = { render: () => <Fixture initial="required" settings connectionDelay={200} /> }
+export const IncompatibleHost = { render: () => <Fixture incompatible /> }
 export const IncompatibleSession = { render: () => <Fixture initial="required" session incompatible /> }
 export const InactiveSession = { render: () => <Fixture initial="required" session connectionDelay={3000} /> }
 export const KeyReconnect = { render: () => <Fixture initial="required" session keyOnly connectionDelay={3000} /> }

packages/app/src/servers/ssh/dialog.tsx

@@ -120,7 +120,13 @@ export function DialogSsh(props: {
       <Divider />
       <DialogBody class="flex w-full min-w-0 flex-1 flex-col px-4 pt-4 pb-2">
         <div class="flex w-full min-w-0 flex-col gap-6">
-          <Show when={!props.promptOnly && (!state.prompted || (!!error() && !prompt()))}>
+          <Show
+            when={
+              !props.promptOnly &&
+              item()?.stage !== "incompatible" &&
+              (!state.prompted || (!!error() && !prompt()))
+            }
+          >
             <div class="flex w-full min-w-0 flex-col gap-2">
               <label class="settings-server-dialog-label" for="ssh-target">
                 {language.t("ssh.target")}
@@ -160,6 +166,12 @@ export function DialogSsh(props: {
               />
             </div>
           </Show>
+          <Show when={item()?.stage === "incompatible"}>
+            <div class="flex w-full min-w-0 flex-col gap-2" role="status" aria-live="polite">
+              <span class="text-14-medium text-v2-text-text-base">{language.t("ssh.stage.incompatible")}</span>
+              <span class="text-13-regular text-v2-text-text-muted">{language.t("ssh.error.version")}</span>
+            </div>
+          </Show>
           <Show when={prompt()} keyed>
             {(prompt) => (
               <div class="flex w-full min-w-0 flex-col gap-2">
@@ -195,7 +207,7 @@ export function DialogSsh(props: {
               </div>
             )}
           </Show>
-          <Show when={error()}>
+          <Show when={item()?.stage !== "incompatible" && error()}>
             {(error) => (
               <span class="settings-server-dialog-error !leading-[var(--line-height-compact)]" role="alert">
                 {error()}

packages/app/src/session/files/session-file-browser-tab.tsx

@@ -1,6 +1,6 @@
 import { createMemo, createUniqueId, Show } from "solid-js"
 import { createStore } from "solid-js/store"
-import { createQuery } from "@tanstack/solid-query"
+import { createQuery, keepPreviousData } from "@tanstack/solid-query"
 import { Icon } from "@opencode/ui/icon"
 import { SessionFilePanelV2, SessionFilePanelV2Empty } from "@opencode/session-ui/v2/session-file-panel-v2"
 import { SessionReviewV2Sidebar } from "@opencode/session-ui/v2/session-review-v2"
@@ -56,6 +56,7 @@ export function SessionFileBrowserTab(props: {
       queryKey: [serverSDK.scope, "session-open-file", workspaceKey(), value] as const,
       enabled: serverSDK.connection.status() === "connected" && value.length > 0,
       queryFn: ({ signal }) => file.searchFiles(value, { limit: 200, signal }),
+      placeholderData: keepPreviousData,
     }
   })
   const files = createMemo(() => {

packages/app/src/shell/notifications/coordinator.ts

@@ -0,0 +1,93 @@
+import { onCleanup } from "solid-js"
+
+const FOCUS_LOCK = "opencode:notification-focus"
+const MAX_CLAIMED = 500
+
+export function createNotificationCoordinator() {
+  const locks = typeof navigator === "undefined" ? undefined : navigator.locks
+  const claimed = new Set<string>()
+  const focus = { pending: false, release: undefined as (() => void) | undefined }
+
+  const updateFocus = () => {
+    if (typeof document === "undefined" || !document.hasFocus()) {
+      focus.release?.()
+      return
+    }
+    if (!locks || focus.pending || focus.release) return
+
+    focus.pending = true
+    void locks
+      .request(FOCUS_LOCK, { mode: "shared" }, async () => {
+        focus.pending = false
+        if (!document.hasFocus()) return
+        await new Promise<void>((resolve) => {
+          focus.release = resolve
+        })
+        focus.release = undefined
+      })
+      .catch(() => {
+        focus.pending = false
+      })
+  }
+
+  if (typeof window !== "undefined") {
+    window.addEventListener("focus", updateFocus)
+    window.addEventListener("blur", updateFocus)
+    document.addEventListener("visibilitychange", updateFocus)
+    updateFocus()
+    onCleanup(() => {
+      window.removeEventListener("focus", updateFocus)
+      window.removeEventListener("blur", updateFocus)
+      document.removeEventListener("visibilitychange", updateFocus)
+      focus.release?.()
+    })
+  }
+
+  const once = async (kind: "sound" | "system", eventID: string, run: () => Promise<unknown> | void) => {
+    const key = `${kind}:${eventID}`
+    const execute = async () => {
+      if (!claim(kind, key, claimed)) return
+      await run()
+    }
+    if (!locks) return execute()
+    await locks.request(`opencode:notification:${key}`, execute)
+  }
+
+  return {
+    sound(eventID: string, run: () => Promise<unknown> | void) {
+      return once("sound", eventID, run)
+    },
+    system(eventID: string, run: () => Promise<unknown> | void) {
+      return once("system", eventID, async () => {
+        if (typeof document !== "undefined" && document.hasFocus()) return
+        if (!locks) return run()
+        await locks.request(FOCUS_LOCK, { mode: "exclusive", ifAvailable: true }, async (lock) => {
+          if (!lock) return
+          await run()
+        })
+      })
+    },
+  }
+}
+
+function claim(kind: "sound" | "system", eventID: string, claimed: Set<string>) {
+  if (claimed.has(eventID)) return false
+
+  if (typeof localStorage !== "undefined") {
+    try {
+      const storageKey = `opencode:notification-${kind}`
+      const value: unknown = JSON.parse(localStorage.getItem(storageKey) ?? "[]")
+      const events = Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : []
+      if (events.includes(eventID)) {
+        claimed.add(eventID)
+        return false
+      }
+      localStorage.setItem(storageKey, JSON.stringify([...events, eventID].slice(-MAX_CLAIMED)))
+    } catch {
+      // The in-memory claim still prevents duplicates in this renderer when storage is unavailable.
+    }
+  }
+
+  claimed.add(eventID)
+  return true
+}

packages/app/src/shell/notifications/notification.tsx

@@ -11,7 +11,8 @@ import { useSettings } from "@/settings/model"
 import { decode64 } from "@/runtime/persistence/base64"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import { Persistence } from "@/runtime/persistence/schema"
-import { playSoundByIdOnce } from "@/shell/notifications/sound"
+import { playSoundById } from "@/shell/notifications/sound"
+import type { createNotificationCoordinator } from "@/shell/notifications/coordinator"
 import { useGlobal } from "@/runtime/server/runtime"
 import { ServerConnection, useServers } from "@/runtime/server/registry"
 import { sessionIDHasOpenTab, useTabs } from "@/shell/tabs/tabs"
@@ -114,7 +115,12 @@ function buildNotificationIndex(list: Notification[]) {
   return index
 }
 
-export function createServerNotificationState(input: { sdk: ServerSDK; data: Data; key: ServerConnection.Key }) {
+export function createServerNotificationState(input: {
+  sdk: ServerSDK
+  data: Data
+  key: ServerConnection.Key
+  coordinator: ReturnType<typeof createNotificationCoordinator>
+}) {
   const platform = usePlatform()
   const settings = useSettings()
   const language = useLanguage()
@@ -223,7 +229,7 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat
       if (session.parentID) return
 
       if (sessionIDHasOpenTab(tabs.store, input.key, sessionID) && settings.sounds.agentEnabled()) {
-        void playSoundByIdOnce(settings.sounds.agent(), `${input.key}\0${eventID}`)
+        void input.coordinator.sound(`${input.key}\0${eventID}`, () => playSoundById(settings.sounds.agent()))
       }
 
       append({
@@ -235,8 +241,10 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat
       })
 
       if (settings.notifications.agent()) {
-        void platform.notify(language.t("notification.session.responseReady.title"), session.title ?? sessionID, () =>
-          openNotificationSession(tabs, input.key, sessionID),
+        void input.coordinator.system(`${input.key}\0${eventID}`, () =>
+          platform.notify(language.t("notification.session.responseReady.title"), session.title ?? sessionID, () =>
+            openNotificationSession(tabs, input.key, sessionID),
+          ),
         )
       }
     })
@@ -248,7 +256,7 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat
       if (session?.parentID) return
 
       if (sessionIDHasOpenTab(tabs.store, input.key, sessionID) && settings.sounds.errorsEnabled()) {
-        void playSoundByIdOnce(settings.sounds.errors(), `${input.key}\0${eventID}`)
+        void input.coordinator.sound(`${input.key}\0${eventID}`, () => playSoundById(settings.sounds.errors()))
       }
 
       append({
@@ -263,8 +271,10 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat
         session?.title ??
         (typeof error === "string" ? error : language.t("notification.session.error.fallbackDescription"))
       if (settings.notifications.errors()) {
-        void platform.notify(language.t("notification.session.error.title"), description, () =>
-          openNotificationSession(tabs, input.key, sessionID),
+        void input.coordinator.system(`${input.key}\0${eventID}`, () =>
+          platform.notify(language.t("notification.session.error.title"), description, () =>
+            openNotificationSession(tabs, input.key, sessionID),
+          ),
         )
       }
     })

packages/app/src/shell/notifications/sound.ts

@@ -74,9 +74,6 @@ function getLoads() {
 }
 
 const cache = new Map<SoundID, Promise<string | undefined>>()
-const claimed = new Set<string>()
-const CLAIMED_STORAGE_KEY = "opencode:notification-sounds"
-const MAX_CLAIMED = 500
 
 export function soundSrc(id: string | undefined) {
   const loads = getLoads()
@@ -103,34 +100,3 @@ export function playSound(src: string | undefined) {
 export function playSoundById(id: string | undefined) {
   return soundSrc(id).then((src) => playSound(src))
 }
-
-export async function playSoundByIdOnce(id: string | undefined, eventID: string) {
-  const play = async () => {
-    if (!claim(eventID)) return
-    await playSoundById(id)
-  }
-
-  if (typeof navigator === "undefined" || !navigator.locks) return play()
-  await navigator.locks.request(`${CLAIMED_STORAGE_KEY}:${eventID}`, play)
-}
-
-function claim(eventID: string) {
-  if (claimed.has(eventID)) return false
-
-  if (typeof localStorage !== "undefined") {
-    try {
-      const value: unknown = JSON.parse(localStorage.getItem(CLAIMED_STORAGE_KEY) ?? "[]")
-      const events = Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : []
-      if (events.includes(eventID)) {
-        claimed.add(eventID)
-        return false
-      }
-      localStorage.setItem(CLAIMED_STORAGE_KEY, JSON.stringify([...events, eventID].slice(-MAX_CLAIMED)))
-    } catch {
-      // The in-memory claim still prevents duplicates in this renderer when storage is unavailable.
-    }
-  }
-
-  claimed.add(eventID)
-  return true
-}

packages/cli/Dockerfile

@@ -0,0 +1,16 @@
+FROM alpine AS base
+
+ARG BUN_RUNTIME_TRANSPILER_CACHE_PATH=0
+ENV BUN_RUNTIME_TRANSPILER_CACHE_PATH=${BUN_RUNTIME_TRANSPILER_CACHE_PATH}
+RUN apk add --no-cache libgcc libstdc++ ripgrep
+
+FROM base AS build-amd64
+COPY dist/cli-linux-x64-baseline-musl/bin/opencode /usr/local/bin/opencode
+
+FROM base AS build-arm64
+COPY dist/cli-linux-arm64-musl/bin/opencode /usr/local/bin/opencode
+
+ARG TARGETARCH
+FROM build-${TARGETARCH}
+RUN opencode --version
+ENTRYPOINT ["opencode"]

packages/cli/bin/opencode.cjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+const forwardedSignals =
+  process.platform === "win32" ? ["SIGINT", "SIGTERM", "SIGHUP"] : ["SIGINT", "SIGTERM", "SIGHUP", "SIGUSR1"]
+
+function run(target) {
+  const child = childProcess.spawn(target, process.argv.slice(2), { stdio: "inherit" })
+  child.on("error", (error) => {
+    console.error(error.message)
+    process.exit(1)
+  })
+  const forwarders = {}
+  for (const signal of forwardedSignals) {
+    forwarders[signal] = () => {
+      try {
+        child.kill(signal)
+      } catch {}
+    }
+    process.on(signal, forwarders[signal])
+  }
+  child.on("exit", (code, signal) => {
+    for (const forwardedSignal of forwardedSignals) process.removeListener(forwardedSignal, forwarders[forwardedSignal])
+    if (signal) return process.kill(process.pid, signal)
+    process.exit(typeof code === "number" ? code : 0)
+  })
+}
+
+const envPath = process.env.OPENCODE_BIN_PATH
+const scriptDir = path.dirname(fs.realpathSync(__filename))
+const command = path.basename(__filename).replace(/\.cjs$/, "")
+const nodeBuild = command === "opencode-node"
+const sourceCommand = nodeBuild ? "opencode2-node" : "opencode"
+const cached = path.join(scriptDir, `.${command}`)
+const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[os.platform()] || os.platform()
+const arch = { x64: "x64", arm64: "arm64", arm: "arm" }[os.arch()] || os.arch()
+const base = `@opencode/cli${nodeBuild ? "-node" : ""}-` + platform + "-" + arch
+const binary = platform === "windows" ? `${sourceCommand}.exe` : sourceCommand
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], { encoding: "utf8", timeout: 1500 })
+      return result.status === 0 && (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+  if (platform === "windows") {
+    const command =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+    for (const executable of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(executable, ["-NoProfile", "-NonInteractive", "-Command", command], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const output = (result.stdout || "").trim().toLowerCase()
+        if (output === "true" || output === "1") return true
+        if (output === "false" || output === "0") return false
+      } catch {
+        continue
+      }
+    }
+  }
+  return false
+}
+
+const names = (() => {
+  if (nodeBuild) return [base]
+  const baseline = arch === "x64" && !supportsAvx2()
+  if (platform === "linux") {
+    const musl = (() => {
+      try {
+        if (fs.existsSync("/etc/alpine-release")) return true
+        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+        return ((result.stdout || "") + (result.stderr || "")).toLowerCase().includes("musl")
+      } catch {
+        return false
+      }
+    })()
+    if (musl)
+      return arch === "x64"
+        ? baseline
+          ? [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+          : [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+        : [`${base}-musl`, base]
+    return arch === "x64"
+      ? baseline
+        ? [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+        : [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+      : [base, `${base}-musl`]
+  }
+  return arch === "x64" ? (baseline ? [`${base}-baseline`, base] : [base, `${base}-baseline`]) : [base]
+})()
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules))
+      for (const name of names) {
+        const candidate = path.join(modules, name, "bin", binary)
+        if (fs.existsSync(candidate)) return candidate
+      }
+    const parent = path.dirname(current)
+    if (parent === current) return
+    current = parent
+  }
+}
+
+const resolved = envPath || (fs.existsSync(cached) ? cached : findBinary(scriptDir))
+if (!resolved) {
+  console.error(
+    `It seems that your package manager failed to install the right ${command} CLI package. Try manually installing ` +
+      names.map((name) => `"${name}"`).join(" or ") +
+      " package",
+  )
+  process.exit(1)
+}
+run(resolved)

packages/cli/bin/opencode2.cjs

@@ -1,134 +1,4 @@
 #!/usr/bin/env node
 
-const childProcess = require("child_process")
-const fs = require("fs")
-const path = require("path")
-const os = require("os")
-
-const forwardedSignals =
-  process.platform === "win32" ? ["SIGINT", "SIGTERM", "SIGHUP"] : ["SIGINT", "SIGTERM", "SIGHUP", "SIGUSR1"]
-
-function run(target) {
-  const child = childProcess.spawn(target, process.argv.slice(2), { stdio: "inherit" })
-  child.on("error", (error) => {
-    console.error(error.message)
-    process.exit(1)
-  })
-  const forwarders = {}
-  for (const signal of forwardedSignals) {
-    forwarders[signal] = () => {
-      try {
-        child.kill(signal)
-      } catch {}
-    }
-    process.on(signal, forwarders[signal])
-  }
-  child.on("exit", (code, signal) => {
-    for (const forwardedSignal of forwardedSignals) process.removeListener(forwardedSignal, forwarders[forwardedSignal])
-    if (signal) return process.kill(process.pid, signal)
-    process.exit(typeof code === "number" ? code : 0)
-  })
-}
-
-const envPath = process.env.OPENCODE_BIN_PATH
-const scriptDir = path.dirname(fs.realpathSync(__filename))
-const command = path.basename(__filename).replace(/\.cjs$/, "")
-const nodeBuild = command === "opencode2-node"
-const cached = path.join(scriptDir, `.${command}`)
-const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[os.platform()] || os.platform()
-const arch = { x64: "x64", arm64: "arm64", arm: "arm" }[os.arch()] || os.arch()
-const base = `@opencode/cli${nodeBuild ? "-node" : ""}-` + platform + "-" + arch
-const binary = platform === "windows" ? `${command}.exe` : command
-
-function supportsAvx2() {
-  if (arch !== "x64") return false
-  if (platform === "linux") {
-    try {
-      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
-    } catch {
-      return false
-    }
-  }
-  if (platform === "darwin") {
-    try {
-      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], { encoding: "utf8", timeout: 1500 })
-      return result.status === 0 && (result.stdout || "").trim() === "1"
-    } catch {
-      return false
-    }
-  }
-  if (platform === "windows") {
-    const command =
-      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
-    for (const executable of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
-      try {
-        const result = childProcess.spawnSync(executable, ["-NoProfile", "-NonInteractive", "-Command", command], {
-          encoding: "utf8",
-          timeout: 3000,
-          windowsHide: true,
-        })
-        if (result.status !== 0) continue
-        const output = (result.stdout || "").trim().toLowerCase()
-        if (output === "true" || output === "1") return true
-        if (output === "false" || output === "0") return false
-      } catch {
-        continue
-      }
-    }
-  }
-  return false
-}
-
-const names = (() => {
-  if (nodeBuild) return [base]
-  const baseline = arch === "x64" && !supportsAvx2()
-  if (platform === "linux") {
-    const musl = (() => {
-      try {
-        if (fs.existsSync("/etc/alpine-release")) return true
-        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
-        return ((result.stdout || "") + (result.stderr || "")).toLowerCase().includes("musl")
-      } catch {
-        return false
-      }
-    })()
-    if (musl)
-      return arch === "x64"
-        ? baseline
-          ? [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
-          : [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
-        : [`${base}-musl`, base]
-    return arch === "x64"
-      ? baseline
-        ? [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
-        : [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
-      : [base, `${base}-musl`]
-  }
-  return arch === "x64" ? (baseline ? [`${base}-baseline`, base] : [base, `${base}-baseline`]) : [base]
-})()
-
-function findBinary(startDir) {
-  let current = startDir
-  for (;;) {
-    const modules = path.join(current, "node_modules")
-    if (fs.existsSync(modules))
-      for (const name of names) {
-        const candidate = path.join(modules, name, "bin", binary)
-        if (fs.existsSync(candidate)) return candidate
-      }
-    const parent = path.dirname(current)
-    if (parent === current) return
-    current = parent
-  }
-}
-
-const resolved = envPath || (fs.existsSync(cached) ? cached : findBinary(scriptDir))
-if (!resolved) {
-  console.error(
-    `It seems that your package manager failed to install the right ${command} CLI package. Try manually installing ` +
-      names.map((name) => `"${name}"`).join(" or ") +
-      " package",
-  )
-  process.exit(1)
-}
-run(resolved)
+console.log("opencode2 is now just opencode. run opencode")
+process.exit(1)

packages/cli/package.json

@@ -1,10 +1,11 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode/cli",
-  "version": "1.18.4",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "bin": {
+    "opencode": "./bin/opencode.cjs",
     "opencode2": "./bin/opencode2.cjs"
   },
   "files": [

packages/cli/script/build.ts

@@ -12,7 +12,7 @@ import { verifyArtifact, verifySimulationGraph } from "./verify-artifact"
 import { resolveOpencodePty } from "./opencode-pty"
 
 const dir = path.resolve(import.meta.dirname, "..")
-const binary = "opencode2"
+const binary = "opencode"
 const outdir = path.resolve(
   dir,
   process.argv.find((arg) => arg.startsWith("--outdir="))?.slice("--outdir=".length) ?? "dist",
@@ -149,7 +149,7 @@ export default { path: file, version: ${JSON.stringify(opencodePty.version)}, sh
     },
     define: {
       OPENCODE_VERSION: `'${Script.version}'`,
-      OPENCODE_CLI_NAME: `'${binary}'`,
+      OPENCODE_CLI_NAME: "'opencode'",
       OPENCODE_CHANNEL: `'${Script.channel}'`,
       OPENCODE_ARTIFACT: `'cli'`,
       OPENCODE_LIBC: item.os === "linux" ? `'${item.abi ?? "glibc"}'` : "undefined",

packages/cli/script/postinstall.mjs

@@ -12,10 +12,11 @@ const require = createRequire(import.meta.url)
 const packageJson = JSON.parse(fs.readFileSync(path.join(directory, "package.json"), "utf8"))
 const command = Object.keys(packageJson.bin ?? {})[0]
 if (!command) throw new Error("OpenCode package does not declare a binary")
+const sourceCommand = packageJson.opencodeSourceBinary ?? command
 
 const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[os.platform()] ?? os.platform()
 const arch = { x64: "x64", arm64: "arm64", arm: "arm" }[os.arch()] ?? os.arch()
-const sourceBinary = platform === "windows" ? `${command}.exe` : command
+const sourceBinary = platform === "windows" ? `${sourceCommand}.exe` : sourceCommand
 const targetBinary = path.resolve(directory, packageJson.bin[command])
 const dependencies = packageJson.optionalDependencies ?? {}
 const base = Object.keys(dependencies).find((name) => name.endsWith(`-${platform}-${arch}`))

packages/cli/script/publish-aur.ts

@@ -6,15 +6,10 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { UpdateArtifact } from "../../../script/update-artifact"
 
-if (Script.channel !== "beta" && Script.channel !== "latest") {
-  throw new Error("AUR publishing requires the beta or latest channel")
-}
-const beta = Script.channel === "beta"
-const name = beta ? "opencode-beta" : "opencode-bin"
-const command = beta ? "opencode2" : "opencode"
-if (!(beta ? /^\d+\.\d+\.\d+-beta[.-]\d+(?:\.\d+)?$/ : /^\d+\.\d+\.\d+$/).test(Script.version)) {
-  throw new Error(`Expected a ${Script.channel} release version`)
-}
+if (Script.channel !== "beta") throw new Error("AUR publishing requires the beta channel")
+const name = "opencode-beta"
+const command = "opencode"
+if (!/^\d+\.\d+\.\d+-beta[.-]\d+(?:\.\d+)?$/.test(Script.version)) throw new Error("Expected a beta release version")
 
 const dir = fileURLToPath(new URL("..", import.meta.url))
 const root = path.resolve(process.env.OPENCODE_CLI_DIST ?? path.join(dir, "dist"))
@@ -22,6 +17,7 @@ const outdir = path.join(root, `aur-${name}`)
 const dryRun = process.argv.includes("--dry-run")
 const pkgver = Script.version.replaceAll("-", ".")
 const license = Bun.file(path.join(dir, "..", "..", "LICENSE"))
+const shim = "#!/bin/sh\necho 'opencode2 is now just opencode. run opencode'\nexit 1\n"
 
 await rm(outdir, { recursive: true, force: true })
 await mkdir(path.dirname(outdir), { recursive: true })
@@ -48,6 +44,7 @@ const sources = await Promise.all(
 )
 
 await Bun.write(path.join(outdir, "LICENSE"), license)
+await Bun.write(path.join(outdir, "opencode2"), shim)
 await Bun.write(
   path.join(outdir, "PKGBUILD"),
   [
@@ -55,21 +52,22 @@ await Bun.write(
     `pkgname=${name}`,
     `pkgver=${pkgver}`,
     "pkgrel=1",
-    `pkgdesc='OpenCode${beta ? " V2 beta" : ""} - the AI coding agent for the terminal'`,
+    "pkgdesc='OpenCode beta - the AI coding agent for the terminal'",
     "url='https://github.com/anomalyco/opencode'",
     "arch=('x86_64' 'aarch64')",
     "license=('MIT')",
     "depends=('glibc' 'gcc-libs' 'ripgrep')",
-    `provides=('${command}')`,
-    `conflicts=('${command}')`,
+    `provides=('${command}' 'opencode2')`,
+    `conflicts=('${command}' 'opencode2')`,
     // Stripping a compiled Bun executable can damage its embedded application.
     "options=('!strip' '!debug')",
-    "source=('LICENSE')",
-    `sha256sums=('${new Bun.CryptoHasher("sha256").update(await license.arrayBuffer()).digest("hex")}')`,
+    "source=('LICENSE' 'opencode2')",
+    `sha256sums=('${new Bun.CryptoHasher("sha256").update(await license.arrayBuffer()).digest("hex")}' '${new Bun.CryptoHasher("sha256").update(shim).digest("hex")}')`,
     ...sources,
     "",
     "package() {",
-    `  install -Dm755 "$srcdir/package/bin/opencode2" "$pkgdir/usr/bin/${command}"`,
+    `  install -Dm755 "$srcdir/package/bin/opencode" "$pkgdir/usr/bin/${command}"`,
+    '  install -Dm755 "$srcdir/opencode2" "$pkgdir/usr/bin/opencode2"',
     '  install -Dm644 "$srcdir/LICENSE" "$pkgdir/usr/share/licenses/$pkgname/LICENSE"',
     "}",
     "",
@@ -79,7 +77,7 @@ await Bun.write(path.join(outdir, ".SRCINFO"), await $`makepkg --printsrcinfo`.c
 console.log(`Prepared ${name} ${pkgver} in ${outdir}`)
 if (dryRun) process.exit(0)
 
-await $`git add PKGBUILD .SRCINFO LICENSE`.cwd(outdir)
+await $`git add PKGBUILD .SRCINFO LICENSE opencode2`.cwd(outdir)
 if ((await $`git diff --cached --quiet`.cwd(outdir).nothrow()).exitCode !== 0) {
   await $`git commit -m ${`chore: update ${name} to ${pkgver}`}`.cwd(outdir)
   await $`git push origin master`.cwd(outdir)

packages/cli/script/publish.ts

@@ -29,6 +29,8 @@ async function publish(dir: string, name: string, version: string) {
 async function publishDistribution(input: {
   root: string
   name: string
+  command: string
+  legacyCommand?: string
   binary: string
   packagePrefix: string
   artifact: string
@@ -48,7 +50,7 @@ async function publishDistribution(input: {
 
   await $`mkdir -p ${input.root}/${input.name}/bin`
   await $`cp ./script/postinstall.mjs ${input.root}/${input.name}/postinstall.mjs`
-  await Bun.file(`${input.root}/${input.name}/bin/${input.binary}.exe`).write(
+  await Bun.file(`${input.root}/${input.name}/bin/${input.command}.exe`).write(
     [
       `echo "Error: ${input.name}'s postinstall script was not run." >&2`,
       'echo "" >&2',
@@ -58,11 +60,19 @@ async function publishDistribution(input: {
       "",
     ].join("\n"),
   )
+  if (input.legacyCommand)
+    await Bun.file(`${input.root}/${input.name}/bin/${input.legacyCommand}.cjs`).write(
+      `#!/usr/bin/env node\n\nconsole.log(${JSON.stringify(`opencode2 is now just opencode. run ${input.command}`)})\nprocess.exit(1)\n`,
+    )
   await Bun.file(`${input.root}/${input.name}/package.json`).write(
     JSON.stringify(
       {
         name: input.name,
-        bin: { [input.binary]: `./bin/${input.binary}.exe` },
+        bin: {
+          [input.command]: `./bin/${input.command}.exe`,
+          ...(input.legacyCommand ? { [input.legacyCommand]: `./bin/${input.legacyCommand}.cjs` } : {}),
+        },
+        ...(input.command !== input.binary ? { opencodeSourceBinary: input.binary } : {}),
         scripts: { postinstall: "node ./postinstall.mjs" },
         version,
         license: pkg.license,
@@ -120,21 +130,28 @@ async function publishDistribution(input: {
 await publishDistribution({
   root,
   name: pkg.name,
-  binary: "opencode2",
+  command: "opencode",
+  legacyCommand: "opencode2",
+  binary: "opencode",
   packagePrefix: "@opencode/cli-",
   artifact: "cli",
 })
-if (existsSync(path.join(root, "node"))) {
+if (Script.channel !== "latest" && existsSync(path.join(root, "node"))) {
   await publishDistribution({
     root: path.join(root, "node"),
     name: "@opencode/cli-node",
+    command: "opencode2-node",
     binary: "opencode2-node",
     packagePrefix: "@opencode/cli-node-",
     artifact: "cli-node",
   })
 }
 
-if ((Script.channel === "beta" || Script.channel === "latest") && Script.release) {
+if (Script.channel === "latest" && Script.release && !dryRun) {
+  await $`docker buildx build --platform linux/amd64,linux/arm64 --tag ghcr.io/anomalyco/opencode:${Script.version} --push .`
+}
+
+if (Script.channel === "beta" && Script.release) {
   await $`bun ./script/publish-aur.ts ${dryRun ? ["--dry-run"] : []}`.env({ ...process.env, OPENCODE_CLI_DIST: root })
 }
 

packages/cli/script/service-smoke.ts

@@ -11,7 +11,10 @@ import path from "node:path"
 const nodeBuild = process.argv.includes("--node")
 const target = `cli${nodeBuild ? "-node" : ""}-${process.platform === "win32" ? "windows" : process.platform}-${process.arch}`
 const directory = path.join(import.meta.dir, "..", "dist", ...(nodeBuild ? ["node"] : []), target, "bin")
-const binary = path.join(directory, `opencode2${nodeBuild ? "-node" : ""}${process.platform === "win32" ? ".exe" : ""}`)
+const binary = path.join(
+  directory,
+  `${nodeBuild ? "opencode2-node" : "opencode"}${process.platform === "win32" ? ".exe" : ""}`,
+)
 if (!(await Bun.file(binary).exists())) throw new Error(`Missing compiled CLI in ${directory}`)
 
 const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-smoke-")))

packages/cli/src/acp/config-option.ts

@@ -76,7 +76,10 @@ export function buildEffortSelectOption(input: {
     category: "thought_level",
     type: "select",
     currentValue: selectVariant(input.currentVariant, input.variants),
-    options: input.variants.map((variant) => ({ value: variant, name: formatVariantName(variant) })),
+    options: [...new Set([...input.variants, DEFAULT_VARIANT_VALUE])].map((variant) => ({
+      value: variant,
+      name: formatVariantName(variant),
+    })),
   }
 }
 
@@ -125,6 +128,7 @@ export function formatVariantName(variant: string) {
 }
 
 function selectVariant(variant: string | undefined, variants: readonly string[]) {
+  if (!variant || variant === DEFAULT_VARIANT_VALUE) return DEFAULT_VARIANT_VALUE
   if (variant && variants.includes(variant)) return variant
   if (variants.includes(DEFAULT_VARIANT_VALUE)) return DEFAULT_VARIANT_VALUE
   return variants[0] ?? DEFAULT_VARIANT_VALUE

packages/cli/src/acp/event.ts

@@ -201,7 +201,7 @@ export async function streamTurn(input: {
         if (!child) assistantMessageID = event.data.assistantMessageID
         await send({
           sessionUpdate: "agent_thought_chunk",
-          messageId: event.data.assistantMessageID,
+          messageId: `${event.data.assistantMessageID}:reasoning:${event.data.ordinal}`,
           content: { type: "text", text: event.data.delta },
         })
         continue
@@ -455,6 +455,8 @@ async function replayMessage(
     return
   }
   if (message.type !== "assistant") return
+  // Live reasoning ordinals count only reasoning parts, not the mixed content array.
+  let reasoningOrdinal = 0
   for (const part of message.content) {
     if (part.type === "text") {
       await connection.sessionUpdate({
@@ -472,7 +474,7 @@ async function replayMessage(
         sessionId: sessionID,
         update: {
           sessionUpdate: "agent_thought_chunk",
-          messageId: message.id,
+          messageId: `${message.id}:reasoning:${reasoningOrdinal++}`,
           content: { type: "text", text: part.text },
         },
       })

packages/cli/src/acp/service.ts

@@ -41,7 +41,12 @@ import type {
 } from "@agentclientprotocol/sdk"
 import { OPENCODE_VERSION } from "../version"
 import { SessionMessage } from "@opencode/schema/session-message"
-import { buildConfigOptions, parseModelSelection, type ConfigOptionProvider } from "./config-option"
+import {
+  buildConfigOptions,
+  DEFAULT_VARIANT_VALUE,
+  parseModelSelection,
+  type ConfigOptionProvider,
+} from "./config-option"
 import { promptContentToParts } from "./content"
 import {
   ChildSessionUpdateMethod,
@@ -275,7 +280,7 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
       if (typeof params.value !== "string") throw new ACPError.InvalidConfigOptionError({ configId: params.configId })
       switch (params.configId) {
         case "model": {
-          const selected = requireModel(state.catalog, params.value)
+          const selected = requireModel(state.catalog, params.value, state.model)
           state.model = selected
           await input.client.session.switchModel({ sessionID: state.id, model: selected })
           break
@@ -284,7 +289,10 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
           const model = state.catalog.models.find(
             (item) => item.providerID === state.model.providerID && item.id === state.model.id,
           )
-          if (!model?.variants.some((variant) => variant.id === params.value))
+          if (
+            !model ||
+            (params.value !== DEFAULT_VARIANT_VALUE && !model.variants.some((variant) => variant.id === params.value))
+          )
             throw new ACPError.InvalidEffortError({ effort: params.value })
           state.model = { ...state.model, variant: params.value }
           await input.client.session.switchModel({ sessionID: state.id, model: state.model })
@@ -453,7 +461,7 @@ function providers(models: readonly ModelInfo[]): ConfigOptionProvider[] {
     }))
 }
 
-function requireModel(catalog: Catalog, modelID: string): ModelRef {
+function requireModel(catalog: Catalog, modelID: string, current: ModelRef): ModelRef {
   const selected = parseModelSelection(modelID, catalog.providers)
   const model = catalog.models.find(
     (item) => item.providerID === selected.model.providerID && item.id === selected.model.modelID,
@@ -461,7 +469,14 @@ function requireModel(catalog: Catalog, modelID: string): ModelRef {
   if (!model) throw new ACPError.InvalidModelError({ providerId: selected.model.providerID, modelId: modelID })
   if (selected.variant && !model.variants.some((variant) => variant.id === selected.variant))
     throw new ACPError.InvalidEffortError({ effort: selected.variant })
-  return { providerID: model.providerID, id: model.id, variant: selected.variant }
+  const variant =
+    selected.variant ??
+    (current.providerID === model.providerID &&
+    current.id === model.id &&
+    (current.variant === DEFAULT_VARIANT_VALUE || model.variants.some((variant) => variant.id === current.variant))
+      ? current.variant
+      : undefined)
+  return { providerID: model.providerID, id: model.id, variant }
 }
 
 async function selectMode(client: OpenCodeClient, state: Attached, modeID: string) {

packages/cli/src/commands/commands.ts

@@ -36,7 +36,7 @@ const PermissionParams = {
 }
 
 const Root = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCODE_CLI_NAME : "opencode", {
-  description: "OpenCode 2.0 preview command line interface",
+  description: "OpenCode command line interface",
   params: {
     ...ServerParams,
     ...PermissionParams,

packages/cli/src/commands/handlers/session/list.ts

@@ -47,7 +47,7 @@ const handler = Effect.fn("cli.session.list")(function* (
           null,
           2,
         )
-      : formatTable(page.data)) + EOL
+      : formatList(page.data)) + EOL
   const write = Effect.tryPromise(
     () =>
       new Promise<void>((resolve, reject) => {
@@ -96,18 +96,14 @@ export default Runtime.handler(Commands.commands.session.commands.list, (input)
   ),
 )
 
-function formatTable(sessions: ReadonlyArray<SessionInfo>) {
-  const rows = sessions.map((session) => ({
-    id: session.id,
-    title: (session.title ?? "Untitled session").replace(/[\r\n\t]/g, " "),
-    updated: new Date(session.time.updated).toLocaleString(),
-  }))
-  const idWidth = Math.max(20, ...rows.map((row) => row.id.length))
-  const titleWidth = Math.max(25, ...rows.map((row) => row.title.length))
-  const header = `${"Session ID".padEnd(idWidth)}  ${"Title".padEnd(titleWidth)}  Updated`
-  return [
-    header,
-    "─".repeat(header.length),
-    ...rows.map((row) => `${row.id.padEnd(idWidth)}  ${row.title.padEnd(titleWidth)}  ${row.updated}`),
-  ].join(EOL)
+function formatList(sessions: ReadonlyArray<SessionInfo>) {
+  return sessions
+    .map((session) =>
+      [
+        session.id,
+        (session.title ?? "Untitled session").replace(/[\r\n\t]/g, " "),
+        new Date(session.time.updated).toLocaleString(),
+      ].join("\t"),
+    )
+    .join(EOL)
 }

packages/cli/src/services/updater.ts

@@ -105,7 +105,7 @@ const make = Effect.gen(function* () {
       global.home,
       ".opencode",
       "bin",
-      process.platform === "win32" ? "opencode2.exe" : "opencode2",
+      process.platform === "win32" ? "opencode.exe" : "opencode",
     )
     if (path.resolve(process.execPath) === path.resolve(binary)) return "curl"
     if (!installedPackage) return
@@ -186,7 +186,10 @@ const make = Effect.gen(function* () {
         "npm",
         "install",
         "--global",
-        ...(installedPackage && packageName !== installedPackage ? ["--force"] : []),
+        ...((OPENCODE_ARTIFACT === "cli" && !installedPackage?.endsWith("/cli-node")) ||
+        (installedPackage && packageName !== installedPackage)
+          ? ["--force"]
+          : []),
         target,
       ],
       pnpm: ["pnpm", "add", "--global", `--allow-build=${packageName}`, target],

packages/cli/test/acp/config-options.subprocess.test.ts

@@ -50,11 +50,11 @@ describe("acp config option subprocess", () => {
     const effort = requireSelectOption((await newSession(acp, fixture.home)).configOptions, "effort")
 
     expect(effort.category).toBe("thought_level")
-    expect(effort.currentValue).toBe("low")
-    expect(flattenSelectOptions(effort).map((option) => option.value)).toEqual(["low", "high"])
+    expect(effort.currentValue).toBe("default")
+    expect(flattenSelectOptions(effort).map((option) => option.value)).toEqual(["low", "high", "default"])
   }, 60_000)
 
-  test("effort switch updates currentValue", async () => {
+  test("effort survives model synchronization and can be reset to default", async () => {
     await using fixture = await createAcpFixture()
     const acp = fixture.spawn()
     await initialize(acp)
@@ -70,5 +70,23 @@ describe("acp config option subprocess", () => {
     )
 
     expect(selectConfigOption(updated.configOptions, "effort")?.currentValue).toBe(nextEffort)
+
+    const synchronized = expectOk(
+      await acp.request<SetSessionConfigOptionResponse>("session/set_config_option", {
+        sessionId: session.sessionId,
+        configId: "model",
+        value: requireSelectOption(session.configOptions, "model").currentValue,
+      }),
+    )
+    expect(selectConfigOption(synchronized.configOptions, "effort")?.currentValue).toBe(nextEffort)
+
+    const reset = expectOk(
+      await acp.request<SetSessionConfigOptionResponse>("session/set_config_option", {
+        sessionId: session.sessionId,
+        configId: "effort",
+        value: "default",
+      }),
+    )
+    expect(selectConfigOption(reset.configOptions, "effort")?.currentValue).toBe("default")
   }, 60_000)
 })

packages/cli/test/acp/event-behavior.test.ts

@@ -91,7 +91,7 @@ describe("acp event behavior", () => {
     }
   })
 
-  test("preserves text and reasoning order before returning the terminal response", async () => {
+  test("preserves reasoning boundaries and update order during streaming and replay", async () => {
     const firstUpdate = Promise.withResolvers<void>()
     const releaseUpdate = Promise.withResolvers<void>()
     const allUpdates = Promise.withResolvers<void>()
@@ -108,6 +108,14 @@ describe("acp event behavior", () => {
             delta: "think-1",
           }),
         )
+        send(
+          ephemeralEvent("session.reasoning.delta", {
+            sessionID: "ses_order",
+            assistantMessageID: "msg_order",
+            ordinal: 0,
+            delta: " continued",
+          }),
+        )
         send(
           ephemeralEvent("session.text.delta", {
             sessionID: "ses_order",
@@ -120,7 +128,7 @@ describe("acp event behavior", () => {
           ephemeralEvent("session.reasoning.delta", {
             sessionID: "ses_order",
             assistantMessageID: "msg_order",
-            ordinal: 2,
+            ordinal: 1,
             delta: "think-2",
           }),
         )
@@ -144,7 +152,7 @@ describe("acp event behavior", () => {
           firstUpdate.resolve()
           await releaseUpdate.promise
         }
-        if (updates.length === 3) allUpdates.resolve()
+        if (updates.length === 4) allUpdates.resolve()
       },
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
     } satisfies Connection
@@ -171,18 +179,48 @@ describe("acp event behavior", () => {
           ) {
             return [
               item.update.sessionUpdate,
+              item.update.messageId,
               item.update.content.type === "text" ? item.update.content.text : undefined,
             ]
           }
           return [item.update.sessionUpdate, undefined]
         }),
       ).toEqual([
-        ["agent_thought_chunk", "think-1"],
-        ["agent_message_chunk", "answer"],
-        ["agent_thought_chunk", "think-2"],
+        ["agent_thought_chunk", "msg_order:reasoning:0", "think-1"],
+        ["agent_thought_chunk", "msg_order:reasoning:0", " continued"],
+        ["agent_message_chunk", "msg_order", "answer"],
+        ["agent_thought_chunk", "msg_order:reasoning:1", "think-2"],
       ])
       expect(fixture.requests.at(-1)?.path).toBe("/api/session/ses_order/message/msg_order")
       expect(response).toMatchObject({ stopReason: "end_turn", usage: { totalTokens: 2 } })
+
+      const replayed: SessionUpdateParams[] = []
+      await replayMessages(recordingConnection(replayed), "ses_order", "/workspace", [
+        {
+          id: "msg_order",
+          type: "assistant",
+          agent: "build",
+          model: { providerID: "test", id: "test-model" },
+          time: { created: 1 },
+          content: [
+            { type: "reasoning", text: "think-1 continued" },
+            { type: "text", text: "answer" },
+            { type: "reasoning", text: "think-2" },
+          ],
+        },
+      ])
+      expect(replayed).toEqual([
+        {
+          sessionId: "ses_order",
+          update: {
+            sessionUpdate: "agent_thought_chunk",
+            messageId: "msg_order:reasoning:0",
+            content: { type: "text", text: "think-1 continued" },
+          },
+        },
+        updates[2],
+        updates[3],
+      ])
     } finally {
       releaseUpdate.resolve()
       releaseSubmit.resolve()

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

@@ -222,7 +222,7 @@ describe("acp service directory behavior", () => {
     await fixture.service.setSessionMode({ sessionId: session.sessionId, modeId: "build" })
 
     expect(currentValue(selectedModel, "model")).toBe("test/second-model")
-    expect(currentValue(selectedModel, "effort")).toBe("low")
+    expect(currentValue(selectedModel, "effort")).toBe("default")
     expect(currentValue(selectedEffort, "effort")).toBe("medium")
     expect(currentValue(selectedMode, "mode")).toBe("plan")
     expect(

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

@@ -32,7 +32,7 @@ describe("acp service lifecycle", () => {
         model: { providerID: "test", id: "second-model" },
       },
     })
-    expect(currentValue(created, "effort")).toBe("none")
+    expect(currentValue(created, "effort")).toBe("default")
   })
 
   test("loads and forks with paginated replay while resume does not replay", async () => {

packages/cli/test/config.test.ts

@@ -423,24 +423,24 @@ test("updates effective duplicate canonical keybinds", async () => {
   const file = path.join(directory.path, "cli.json")
   await Bun.write(
     file,
-    `{"keybinds":{"session.delete":"first","session.delete":"last","permission.mode":"off","permission.mode":"on"}}`,
+    `{"keybinds":{"session.delete":"first","session.delete":"last","opencode.settings":"off","opencode.settings":"on"}}`,
   )
 
   const config = await run(
     directory.path,
     Effect.gen(function* () {
       const service = yield* Config.Service
-      expect((yield* service.get()).keybinds).toEqual({ "session.delete": "last", "permission.mode": "on" })
+      expect((yield* service.get()).keybinds).toEqual({ "session.delete": "last", "opencode.settings": "on" })
       return yield* service.update((draft) => {
-        draft.keybinds = { ...draft.keybinds, "session.delete": "changed", "permission.mode": "changed" }
+        draft.keybinds = { ...draft.keybinds, "session.delete": "changed", "opencode.settings": "changed" }
       })
     }),
   )
 
-  expect(config.keybinds).toEqual({ "session.delete": "changed", "permission.mode": "changed" })
+  expect(config.keybinds).toEqual({ "session.delete": "changed", "opencode.settings": "changed" })
   expect(parse(await Bun.file(file).text()).keybinds).toEqual({
     "session.delete": "changed",
-    "permission.mode": "changed",
+    "opencode.settings": "changed",
   })
 })
 

packages/cli/test/updater-install.test.ts

@@ -100,7 +100,7 @@ function fixture(
 }
 
 const installs = [
-  { method: "npm", command: ["npm", "install", "--global", "@opencode/cli@2.3.4-beta.1"] },
+  { method: "npm", command: ["npm", "install", "--global", "--force", "@opencode/cli@2.3.4-beta.1"] },
   {
     method: "pnpm",
     command: ["pnpm", "add", "--global", "--allow-build=@opencode/cli", "@opencode/cli@2.3.4-beta.1"],

packages/client/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode/client",
-  "version": "1.17.13",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "repository": {

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

@@ -11,13 +11,13 @@ import type { RelativePath } from "@opencode/schema/schema"
 import type { Brand } from "effect"
 import type { Model } from "@opencode/schema/model"
 import type { DateTime } from "effect"
+import type { Permission } from "@opencode/schema/permission"
 import type { SessionMessage } from "@opencode/schema/session-message"
 import type { SessionInbox } from "@opencode/schema/session-inbox"
 import type { PromptInput } from "@opencode/schema/prompt-input"
 import type { AgentAttachment } from "@opencode/schema/prompt"
 import type { Skill } from "@opencode/schema/skill"
 import type { Event } from "@opencode/schema/event"
-import type { FileDiff } from "@opencode/schema/file-diff"
 import type { InstructionEntry } from "@opencode/schema/instruction-entry"
 import type { Schema } from "effect"
 import type { EventLog } from "@opencode/schema/event-log"
@@ -27,7 +27,6 @@ import type { Integration } from "@opencode/schema/integration"
 import type { Form } from "@opencode/schema/form"
 import type { Mcp } from "@opencode/schema/mcp"
 import type { Credential } from "@opencode/schema/credential"
-import type { Permission } from "@opencode/schema/permission"
 import type { PermissionSaved } from "@opencode/schema/permission-saved"
 import type { FileSystem } from "@opencode/schema/filesystem"
 import type { Command } from "@opencode/schema/command"
@@ -37,6 +36,7 @@ import type { PtyTicket } from "@opencode/schema/pty-ticket"
 import type { Reference } from "@opencode/schema/reference"
 import type { Worktree } from "@opencode/schema/worktree"
 import type { Vcs } from "@opencode/schema/vcs"
+import type { FileDiff } from "@opencode/schema/file-diff"
 import type { WebSearch } from "@opencode/schema/websearch"
 import type { Config } from "@opencode/schema/config"
 
@@ -209,6 +209,7 @@ export type SessionCreateInput = {
   readonly model?: Model.Ref | undefined
   readonly location?: Location.Ref | undefined
   readonly metadata?: Session.Metadata | undefined
+  readonly permissions?: Permission.Ruleset | undefined
 }
 export type SessionCreateOutput = Session.Info
 export type SessionCreateOperation<E = never> = (input?: SessionCreateInput) => Effect.Effect<SessionCreateOutput, E>
@@ -360,15 +361,6 @@ export type SessionContextInput = { readonly sessionID: Session.ID }
 export type SessionContextOutput = ReadonlyArray<SessionMessage.Info>
 export type SessionContextOperation<E = never> = (input: SessionContextInput) => Effect.Effect<SessionContextOutput, E>
 
-export type SessionDiffInput = {
-  readonly sessionID: Session.ID
-  readonly messageID?: SessionMessage.ID | undefined
-  readonly to?: SessionMessage.ID | undefined
-  readonly context?: number | undefined
-}
-export type SessionDiffOutput = ReadonlyArray<FileDiff.Info>
-export type SessionDiffOperation<E = never> = (input: SessionDiffInput) => Effect.Effect<SessionDiffOutput, E>
-
 export type SessionInboxListInput = { readonly sessionID: Session.ID }
 export type SessionInboxListOutput = ReadonlyArray<SessionInbox.Info>
 export type SessionInboxListOperation<E = never> = (
@@ -446,6 +438,7 @@ export type SessionLogOutput =
             readonly agent?: Agent.ID | undefined
             readonly model?: Model.Ref | undefined
             readonly metadata?: Session.Metadata | undefined
+            readonly permissions?: Permission.Ruleset | undefined
             readonly version: string
           }
         }
@@ -498,6 +491,15 @@ export type SessionLogOutput =
           readonly location?: Location.Ref | undefined
           readonly data: { readonly sessionID: Session.ID; readonly title: string }
         }
+      | {
+          readonly id: Event.ID
+          readonly created: number
+          readonly metadata?: { readonly [x: string]: unknown } | undefined
+          readonly type: "session.permissions.updated"
+          readonly durable: { readonly aggregateID: string; readonly seq: Event.Seq; readonly version: Event.Version }
+          readonly location?: Location.Ref | undefined
+          readonly data: { readonly sessionID: Session.ID; readonly permissions: Permission.Ruleset }
+        }
       | {
           readonly id: Event.ID
           readonly created: number
@@ -1148,7 +1150,6 @@ export interface SessionApi<E = never> {
     readonly commit: SessionRevertCommitOperation<E>
   }
   readonly context: SessionContextOperation<E>
-  readonly diff: SessionDiffOperation<E>
   readonly inbox: {
     readonly list: SessionInboxListOperation<E>
     readonly cancel: SessionInboxCancelOperation<E>
@@ -1595,6 +1596,12 @@ export type PermissionReplyOperation<E = never> = (
   input: PermissionReplyInput,
 ) => Effect.Effect<PermissionReplyOutput, E>
 
+export type PermissionRulesInput = { readonly sessionID: Session.ID; readonly permissions: Permission.Ruleset }
+export type PermissionRulesOutput = void
+export type PermissionRulesOperation<E = never> = (
+  input: PermissionRulesInput,
+) => Effect.Effect<PermissionRulesOutput, E>
+
 export interface PermissionApi<E = never> {
   readonly request: { readonly list: PermissionRequestListOperation<E> }
   readonly saved: { readonly list: PermissionSavedListOperation<E>; readonly remove: PermissionSavedRemoveOperation<E> }
@@ -1602,6 +1609,7 @@ export interface PermissionApi<E = never> {
   readonly list: PermissionListOperation<E>
   readonly get: PermissionGetOperation<E>
   readonly reply: PermissionReplyOperation<E>
+  readonly rules: PermissionRulesOperation<E>
 }
 
 export type FileListInput = {