feat(ai): add media foundation with ModelRef, Media assets, and Image rewrite

Co-authored-by: Hona <10430890+Hona@users.noreply.github.com>
Co-authored-by: Brendonovich <14191578+Brendonovich@users.noreply.github.com>

.github/workflows/check.yml

@@ -1,4 +1,4 @@
-name: typecheck
+name: check
 
 on:
   push:
@@ -8,7 +8,8 @@ on:
   workflow_dispatch:
 
 jobs:
-  typecheck:
+  check:
+    name: typecheck
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout repository
@@ -17,5 +18,5 @@ jobs:
       - name: Setup Bun
         uses: ./.github/actions/setup-bun
 
-      - name: Run typecheck
-        run: bun typecheck
+      - name: Run checks
+        run: bun run check

.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 }}

.gitignore

@@ -32,6 +32,7 @@ target
 # Local dev files
 opencode-dev
 UPCOMING_CHANGELOG.md
+RELEASE_REVIEW.md
 logs/
 *.bun-build
 tsconfig.tsbuildinfo

.husky/pre-push

@@ -17,4 +17,4 @@ if (process.versions.bun !== expectedBunVersion) {
   console.warn(`Warning: Bun version ${process.versions.bun} differs from expected ${expectedBunVersion}`);
 }
 '
-bun typecheck
+bun run check

.oxlintrc.json

@@ -1,45 +1,22 @@
 {
   "$schema": "https://raw.githubusercontent.com/nicolo-ribaudo/oxc-project.github.io/refs/heads/json-schema/src/public/.oxlintrc.schema.json",
-  "options": {
-    "typeAware": true
-  },
   "categories": {
-    "suspicious": "warn"
+    "correctness": "off",
+    "suspicious": "off",
+    "pedantic": "off",
+    "perf": "off",
+    "style": "off",
+    "restriction": "off",
+    "nursery": "off"
   },
   "rules": {
-    "typescript/no-base-to-string": "warn",
-    // Effect uses `function*` with Effect.gen/Effect.fnUntraced that don't always yield
-    "require-yield": "off",
-    // SolidJS uses `let ref: T | undefined` for JSX ref bindings assigned at runtime
-    "no-unassigned-vars": "off",
-    // SolidJS tracks reactive deps by reading properties inside createEffect
-    "no-unused-expressions": "off",
-    // Intentional control char matching (ANSI escapes, null byte sanitization)
-    "no-control-regex": "off",
-    // SST and plugin tools require triple-slash references
-    "triple-slash-reference": "off",
-
-    // Suspicious category: suppress noisy rules
-    // Effect's nested function* closures inherently shadow outer scope
-    "no-shadow": "off",
-    // Namespace-heavy codebase makes this too noisy
-    "unicorn/consistent-function-scoping": "off",
-    // Opinionated — .sort()/.reverse() mutation is fine in this codebase
-    "unicorn/no-array-sort": "off",
-    "unicorn/no-array-reverse": "off",
-    // Not relevant — this isn't a DOM event handler codebase
-    "unicorn/prefer-add-event-listener": "off",
-    // Bundler handles module resolution
-    "unicorn/require-module-specifiers": "off",
-    // postMessage target origin not relevant for this codebase
-    "unicorn/require-post-message-target-origin": "off",
-    // Side-effectful constructors are intentional in some places
-    "no-new": "off",
-
-    // Type-aware: catch unhandled promises
-    "typescript/no-floating-promises": "warn",
-    // Warn when spreading non-plain objects (Headers, class instances, etc.)
-    "typescript/no-misused-spread": "warn"
+    "no-restricted-globals": [
+      "error",
+      {
+        "name": "Reflect",
+        "message": "Use typed property access or direct invocation. Suppress this rule only for genuine reflection."
+      }
+    ]
   },
   "ignorePatterns": ["**/node_modules", "**/dist", "**/.build", "**/.sst", "**/*.d.ts", "**/sdk.gen.ts"]
 }

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
@@ -170,9 +170,10 @@ const table = sqliteTable("session", {
 - Test actual implementation, do not duplicate logic into tests
 - Tests cannot run from repo root (guard: `do-not-run-tests-from-root`); run from package directories such as `packages/core`.
 
-## Type Checking
+## Checks
 
-- Always run `bun typecheck` from package directories (for example, `packages/core`), never `tsc` directly.
+- Run `bun run check` from the repository root as the canonical full lint and type-check verification.
+- During focused iteration, run `bun typecheck` from the affected package directory (for example, `packages/core`). Never run `tsc` directly.
 
 ## V2 Session Core
 

V2_HTTP_API_AUDIT.md

@@ -0,0 +1,279 @@
+# V2 HTTP API audit checklist
+
+**Source:** `packages/protocol/openapi.json`  
+**Current endpoint count:** 139
+**Last regenerated:** 2026-09-13
+
+## How to use this checklist
+
+Review endpoints in document order. For each endpoint, select one disposition and capture rationale or follow-up work in Notes. Mark **Reviewed** only after the disposition is agreed.
+
+### Review criteria
+
+- Resource and operation naming
+- HTTP method and idempotency
+- Request parameters and location scope
+- Response shape and error taxonomy
+- Authentication and authorization
+- Current production consumers
+- Stability level: public, experimental, or internal
+- Whether the generated client API is intuitive
+
+### Disposition legend
+
+- **Keep:** ship unchanged as a supported V2 API
+- **Change:** retain after a defined contract change
+- **Remove:** exclude from the official V2 API
+- **Experimental-only:** retain outside the stable API commitment
+
+## Progress
+
+- [x] Group 1: Foundation and placement (4)
+- [ ] Group 2: Configuration and capability catalogs (16)
+- [ ] Group 3: Credentials, integrations, MCP, and web search (22)
+- [ ] Group 4: Session lifecycle (12)
+- [ ] Group 5: Session execution and inputs (11)
+- [ ] Group 6: Session history and recovery (13)
+- [ ] Group 7: Inbox, permissions, and forms (19)
+- [ ] Group 8: Filesystem, worktrees, and VCS (12)
+- [ ] Group 9: PTYs, persistent terminals, and shells (24)
+- [ ] Group 10: Events, RPC, and experimental operations (6)
+
+## Resolved during audit
+
+### [x] `POST /api/plugin/await-activation`
+
+- **Decision:** Remove
+- **Notes:** Activation timing is an internal server concern. Catalog reads remain non-blocking.
+
+### [x] Location response wrappers
+
+- **Decision:** Reduce generic endpoint response locations to `{ directory }`.
+- **Notes:** Full project metadata remains available from `GET /api/location`; no consumers used it from wrapped responses.
+
+### [x] `GET /api/health` and `GET /api/server`
+
+- **Decision:** Merge and rename
+- **Replacement:** `GET /api/status` with operation ID `server.status`.
+- **Notes:** Returns `version`, `pid`, and connection `urls`; readiness is conveyed by HTTP status.
+
+### [x] `GET /api/project/current`
+
+- **Decision:** Remove
+- **Replacement:** `GET /api/location`, using `project` from the response.
+- **Notes:** The endpoint duplicated `Location.Info.project`; production callers were migrated.
+
+### [x] `POST /api/workspace` and `DELETE /api/workspace/{workspaceID}`
+
+- **Decision:** Remove
+- **Notes:** Provider-backed workspaces are not part of the V2 HTTP contract and can be introduced later. Core and the embedded SDK retain internal workspace support.
+
+## Group 1: Foundation and placement
+
+**Endpoints:** 4
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 001–002 | `GET` | `/api/status` | `server.status` | Keep | Replaces the former health and server endpoints. |
+| [x] 003 | `GET` | `/api/location` | `location.get` | Keep | Workspace selectors and response fields removed until workspace support ships. |
+| [x] 004 | `GET` | `/api/project` | `project.list` | Keep | Removed unused `time.initialized`; the database column remains for migration data. |
+| [x] 005 | `PATCH` | `/api/project/{projectID}` | `project.update` | Keep | Request and response accepted as-is. |
+
+## Group 2: Configuration and capability catalogs
+
+**Endpoints:** 16
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 008 | `GET` | `/api/agent` | `agent.list` | Keep | Request and response accepted as-is. |
+| [x] 009 | `GET` | `/api/agent/{agentID}` | `agent.get` | Keep | Request, response, and not-found error accepted as-is. |
+| [x] 010 | `GET` | `/api/plugin` | `plugin.list` | Keep | Request and response accepted as-is. |
+| [x] 012 | `POST` | `/api/plugin/check` | `plugin.check` | Keep | Request and response accepted as-is. |
+| [x] 013 | `POST` | `/api/plugin/update` | `plugin.update` | Keep | Request and errors accepted as-is. |
+| [x] 014 | `GET` | `/api/model` | `model.list` | Keep | Request and response accepted as-is. |
+| [x] 015 | `GET` | `/api/model/default` | `model.default` | Keep | Request and nullable response accepted as-is. |
+| [x] 016 | `GET` | `/api/provider` | `provider.list` | Keep | Request and response accepted as-is. |
+| [x] 017 | `GET` | `/api/provider/{providerID}` | `provider.get` | Keep | Request, response, and not-found error accepted as-is. |
+| [x] 018 | `GET` | `/api/command` | `command.list` | Keep | Request and response accepted as-is. |
+| [x] 019 | `GET` | `/api/skill` | `skill.list` | Keep | Renamed `location` to `path`; removed the skill-specific `slash` flag and slash-command behavior. |
+| [x] 020 | `GET` | `/api/reference` | `reference.list` | Keep | Removed duplicate `description` and `hidden` fields from nested `source`. |
+| [x] 021 | `GET` | `/api/config` | `config.get` | Keep | Compatibility entries removed; response now contains only documents and OpenCode directories. |
+| [x] 022 | `GET` | `/api/config/preferences` | `config.preferences` | Remove | Redundant special projection of global config. |
+| [x] 023 | `PATCH` | `/api/config/preferences` | `config.updatePreferences` | Remove | Redundant field-specific config mutation API. |
+| [ ] 024 | `GET` | `/api/config/shell` | `config.shells` |  |  |
+| [x] 024a | `PATCH` | `/api/experimental/config` | `experimental.config.update` | Change | Experimental global config mutation; initially accepts only `shell`. |
+
+## Group 3: Credentials, integrations, MCP, and web search
+
+**Endpoints:** 22
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 025 | `GET` | `/api/integration` | `integration.list` | Keep | Full integration inventory is consumed by authentication and integration-selection clients. |
+| [x] 026 | `GET` | `/api/integration/{integrationID}` | `integration.get` | Change | Missing integration now returns typed `404` instead of optional data. |
+| [x] | `POST` | `/api/experimental/integration/wellknown` | `experimental.integration.wellknown.add` | Experimental-only | Retained outside the stable API commitment. |
+| [ ] 028 | `POST` | `/api/integration/{integrationID}/connect/key` | `integration.connect.key` |  |  |
+| [ ] 029 | `POST` | `/api/integration/{integrationID}/connect/oauth` | `integration.oauth.connect` |  |  |
+| [ ] 030 | `GET` | `/api/integration/{integrationID}/connect/oauth/{attemptID}` | `integration.oauth.status` |  |  |
+| [ ] 031 | `DELETE` | `/api/integration/{integrationID}/connect/oauth/{attemptID}` | `integration.oauth.cancel` |  |  |
+| [ ] 032 | `POST` | `/api/integration/{integrationID}/connect/oauth/{attemptID}/complete` | `integration.oauth.complete` |  |  |
+| [ ] 033 | `POST` | `/api/integration/{integrationID}/connect/command` | `integration.command.connect` |  |  |
+| [ ] 034 | `GET` | `/api/integration/{integrationID}/connect/command/{attemptID}` | `integration.command.status` |  |  |
+| [ ] 035 | `DELETE` | `/api/integration/{integrationID}/connect/command/{attemptID}` | `integration.command.cancel` |  |  |
+| [x] 036 | `GET` | `/api/mcp` | `mcp.list` | Keep | MCP inventory and connection status retained. |
+| [x] 037 | `PUT` | `/api/experimental/mcp/{server}` | `experimental.mcp.add` | Experimental-only | Runtime-only MCP override; does not persist configuration. |
+| [x] 038 | `DELETE` | `/api/experimental/mcp/{server}` | `experimental.mcp.remove` | Experimental-only | Runtime removal override; missing server returns `404`. |
+| [x] 039 | `POST` | `/api/experimental/mcp/{server}/connect` | `experimental.mcp.connect` | Experimental-only | Runtime connection override retained outside the stable API. |
+| [x] 040 | `POST` | `/api/experimental/mcp/{server}/disconnect` | `experimental.mcp.disconnect` | Experimental-only | Runtime disconnection override retained outside the stable API. |
+| [ ] 041 | `GET` | `/api/mcp/resource` | `mcp.resource.catalog` |  | Deferred for later review. |
+| [x] 042 | `PATCH` | `/api/credential/{credentialID}` | `credential.update` | Change | Removed redundant location query; credentials and events are global. |
+| [x] 043 | `DELETE` | `/api/credential/{credentialID}` | `credential.remove` | Change | Removed redundant location query; credentials and events are global. |
+| [x] 044 | `POST` | `/api/credential/{credentialID}/activate` | `credential.activate` | Change | Removed redundant location query; credentials and events are global. |
+| [x] 045 | `GET` | `/api/websearch/provider` | `websearch.providers` | Keep | Provider availability remains location-scoped; singular resource path retained. |
+| [x] 046 | `POST` | `/api/websearch` | `websearch.query` | Keep | Unknown provider remains an invalid request; published time documented as Unix epoch milliseconds. |
+
+## Group 4: Session lifecycle
+
+**Endpoints:** 12
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 047 | `GET` | `/api/session` | `session.list` | Keep | Existing filtering, ordering, and cursor contract retained for now. |
+| [x] 048 | `POST` | `/api/session` | `session.create` | Keep | Existing creation contract retained; model reference includes optional variant. |
+| [x] 049 | `GET` | `/api/experimental/session/stats` | `experimental.session.stats` | Experimental-only | Session analytics retained outside the stable API commitment. |
+| [x] 050 | `GET` | `/api/session/active` | `session.active` | Keep | Status record retained for future active-state expansion. |
+| [x] 051 | `GET` | `/api/session/{sessionID}` | `session.get` | Keep | Specific session read and typed `404` retained. |
+| [x] 052 | `DELETE` | `/api/session/{sessionID}` | `session.remove` | Keep | Session and child deletion with typed `404` retained. |
+| [x] 053 | `POST` | `/api/session/{sessionID}/fork` | `session.fork` | Change | Request now accepts optional branded `before` message ID; omission copies full history. |
+| [x] 054 | `POST` | `/api/session/{sessionID}/agent` | `session.switchAgent` | Keep | Subsequent-execution agent selection retained. |
+| [x] 055 | `POST` | `/api/session/{sessionID}/model` | `session.switchModel` | Keep | Subsequent-execution model and optional variant selection retained. |
+| [x] 056 | `PATCH` | `/api/session/{sessionID}` | `session.rename` | Change | Title-only rename now uses the session resource path. |
+| [x] 057 | `POST` | `/api/session/{sessionID}/move` | `session.move` | Change | Removed inaccurate local-change transfer claim; delivery behavior retained. |
+| [x] 058 | `POST` | `/api/session/{sessionID}/background` | `session.background` | Keep | Backgroundable foreground tools transition to background observation; idle requests remain no-ops. |
+
+## Group 5: Session execution and inputs
+
+**Endpoints:** 11
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 059 | `POST` | `/api/session/{sessionID}/prompt` | `session.prompt` | Keep | Durable admission, delivery mode, and admit-only resume control retained. |
+| [x] 060 | `POST` | `/api/session/{sessionID}/command` | `session.command` | Change | Renamed request field from `command` to `name`; `204` retained. |
+| [x] 061 | `POST` | `/api/experimental/session/{sessionID}/skill` | `experimental.session.skill` | Experimental-only | Skill ID is now the `id` field; standalone activation remains experimental. |
+| [x] 062 | `POST` | `/api/session/{sessionID}/synthetic` | `session.synthetic` | Keep | Durable synthetic admission and delivery controls retained. |
+| [x] 063 | `POST` | `/api/session/{sessionID}/shell` | `session.shell` | Change | Caller ID is now the optimistic shell message ID; server derives its event ID. |
+| [x] 064 | `POST` | `/api/session/{sessionID}/compact` | `session.compact` | Keep | Durable compaction admission and delivery controls retained. |
+| [x] 065 | `POST` | `/api/experimental/session/{sessionID}/wait` | `experimental.session.wait` | Experimental-only | Race-free idle barrier retained outside the stable API. |
+| [x] 066 | `POST` | `/api/session/{sessionID}/generate` | `session.generate` | Keep | Transient generation from session context retained. |
+| [x] 067 | `POST` | `/api/session/{sessionID}/interrupt` | `session.interrupt` | Change | Renamed `continue` to `resume` across public and internal interruption APIs. |
+| [x] 068 | `PUT` | `/api/experimental/session/{sessionID}/environment` | `experimental.session.environment` | Experimental-only | Process-local environment replacement retained outside the stable API. |
+| [x] 069 | `POST` | `/api/session/{sessionID}/view` | `session.view` | Change | Idle watermark now uses the standard epoch-millisecond timestamp schema. |
+
+## Group 6: Session history and recovery
+
+**Endpoints:** 13
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 070 | `POST` | `/api/experimental/session/import` | `experimental.session.import` | Experimental-only | Existing projected transcript import contract retained outside the stable API. |
+| [x] 071 | `GET` | `/api/experimental/session/{sessionID}/export` | `experimental.session.export` | Experimental-only | Existing projected transcript export contract retained outside the stable API. |
+| [x] 072 | `POST` | `/api/session/{sessionID}/revert/stage` | `session.revert.stage` | Keep | Existing staged history and optional file restoration behavior retained. |
+| [x] 073 | `DELETE` | `/api/session/{sessionID}/revert` | `session.revert.clear` | Change | Clearing staged revert now deletes the session revert resource. |
+| [x] 074 | `POST` | `/api/session/{sessionID}/revert/commit` | `session.revert.commit` | Keep | Explicit staged-revert commit action retained. |
+| [x] 075 | `GET` | `/api/session/{sessionID}/context` | `session.context` | Keep | Active model-context projection retained. |
+| [x] 076 | `GET` | `/api/session/{sessionID}/diff` | `session.diff` | Keep | Turn-range structured diff contract retained. |
+| [x] 077 | `GET` | `/api/experimental/session/{sessionID}/instructions/entries` | `experimental.session.instructions.entry.list` | Experimental-only | API-managed durable context entries retained outside the stable API. |
+| [x] 078 | `PUT` | `/api/experimental/session/{sessionID}/instructions/entries/{key}` | `experimental.session.instructions.entry.put` | Experimental-only | API-managed durable context entries retained outside the stable API. |
+| [x] 079 | `DELETE` | `/api/experimental/session/{sessionID}/instructions/entries/{key}` | `experimental.session.instructions.entry.remove` | Experimental-only | API-managed durable context entries retained outside the stable API. |
+| [x] | `GET` | `/api/experimental/session/{sessionID}/log` | `session.log` | Experimental-only | Retained outside the stable API commitment. |
+| [x] 081 | `GET` | `/api/session/{sessionID}/message/{messageID}` | `session.message.get` | Change | Normalized specific-message operation ID. |
+| [x] 082 | `GET` | `/api/session/{sessionID}/message` | `session.message.list` | Change | Normalized session-scoped message-list operation ID. |
+
+## Group 7: Inbox, permissions, and forms
+
+**Endpoints:** 19
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [x] 083 | `GET` | `/api/session/{sessionID}/inbox` | `session.inbox.list` | Change | Inbox timestamps now use the standard nested `time.created` shape. |
+| [ ] 084 | `DELETE` | `/api/session/{sessionID}/inbox/{inboxID}` | `session.inbox.cancel` |  |  |
+| [ ] 085 | `POST` | `/api/session/{sessionID}/inbox/{inboxID}/steer` | `session.inbox.steer` |  |  |
+| [ ] 086 | `POST` | `/api/session/{sessionID}/inbox/{inboxID}/queue` | `session.inbox.queue` |  |  |
+| [ ] 087 | `GET` | `/api/form/request` | `form.request.list` |  |  |
+| [ ] 088 | `GET` | `/api/session/{sessionID}/form` | `session.form.list` |  |  |
+| [ ] 089 | `POST` | `/api/session/{sessionID}/form` | `session.form.create` |  |  |
+| [ ] 090 | `GET` | `/api/session/{sessionID}/form/{formID}` | `session.form.get` |  |  |
+| [ ] 091 | `GET` | `/api/session/{sessionID}/form/{formID}/state` | `session.form.state` |  |  |
+| [ ] 092 | `POST` | `/api/session/{sessionID}/form/{formID}/reply` | `session.form.reply` |  |  |
+| [ ] 093 | `POST` | `/api/session/{sessionID}/form/{formID}/cancel` | `session.form.cancel` |  |  |
+| [ ] 094 | `GET` | `/api/permission/request` | `permission.request.list` |  |  |
+| [ ] 095 | `GET` | `/api/permission/saved` | `permission.saved.list` |  |  |
+| [ ] 096 | `DELETE` | `/api/permission/saved/{id}` | `permission.saved.remove` |  |  |
+| [ ] 097 | `POST` | `/api/session/{sessionID}/permission` | `session.permission.create` |  |  |
+| [ ] 098 | `GET` | `/api/session/{sessionID}/permission` | `session.permission.list` |  |  |
+| [ ] 099 | `GET` | `/api/session/{sessionID}/permission/{requestID}` | `session.permission.get` |  |  |
+| [ ] 100 | `POST` | `/api/session/{sessionID}/permission/{requestID}/reply` | `session.permission.reply` |  |  |
+| [ ] 101 | `PUT` | `/api/session/{sessionID}/permission/rules` | `session.permission.rules` |  |  |
+
+## Group 8: Filesystem, worktrees, and VCS
+
+**Endpoints:** 12
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [ ] 102 | `GET` | `/api/fs/read/*` | `fs.read` |  |  |
+| [ ] 103 | `GET` | `/api/fs/list` | `fs.list` |  |  |
+| [ ] 104 | `GET` | `/api/fs/find` | `fs.find` |  |  |
+| [ ] 105 | `GET` | `/api/worktree` | `worktree.list` |  |  |
+| [ ] 106 | `POST` | `/api/worktree` | `worktree.create` |  |  |
+| [ ] 107 | `DELETE` | `/api/worktree` | `worktree.remove` |  |  |
+| [ ] 108 | `POST` | `/api/worktree/refresh` | `worktree.refresh` |  |  |
+| [ ] 109 | `GET` | `/api/vcs` | `vcs.get` |  |  |
+| [ ] 110 | `GET` | `/api/vcs/base` | `vcs.base` |  |  |
+| [ ] 111 | `GET` | `/api/vcs/status` | `vcs.status` |  |  |
+| [ ] 112 | `GET` | `/api/vcs/branches` | `vcs.branches` |  |  |
+| [ ] 113 | `GET` | `/api/vcs/diff` | `vcs.diff` |  |  |
+
+## Group 9: PTYs, persistent terminals, and shells
+
+**Endpoints:** 24
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [ ] 114 | `GET` | `/api/pty` | `pty.list` |  |  |
+| [ ] 115 | `POST` | `/api/pty` | `pty.create` |  |  |
+| [ ] 116 | `GET` | `/api/pty/{ptyID}` | `pty.get` |  |  |
+| [ ] 117 | `PUT` | `/api/pty/{ptyID}` | `pty.update` |  |  |
+| [ ] 118 | `DELETE` | `/api/pty/{ptyID}` | `pty.remove` |  |  |
+| [ ] 119 | `POST` | `/api/pty/{ptyID}/connect-token` | `pty.connect.token` |  |  |
+| [ ] 120 | `GET` | `/api/pty/{ptyID}/connect` | `pty.connect` |  |  |
+| [x] | `GET` | `/api/experimental/session/{sessionID}/terminal/read` | `server.experimental.persistentPty.read` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `GET` | `/api/experimental/session/{sessionID}/terminal` | `server.experimental.persistentPty.list` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `POST` | `/api/experimental/session/{sessionID}/terminal` | `server.experimental.persistentPty.create` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `POST` | `/api/experimental/persistent-pty/shutdown` | `server.experimental.persistentPty.shutdown` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `POST` | `/api/experimental/persistent-pty/handoff` | `server.experimental.persistentPty.handoff` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `GET` | `/api/experimental/persistent-pty/{ptyID}` | `server.experimental.persistentPty.get` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `PUT` | `/api/experimental/persistent-pty/{ptyID}` | `server.experimental.persistentPty.update` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `DELETE` | `/api/experimental/persistent-pty/{ptyID}` | `server.experimental.persistentPty.remove` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `GET` | `/api/experimental/persistent-pty/{ptyID}/snapshot` | `server.experimental.persistentPty.snapshot` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `POST` | `/api/experimental/persistent-pty/{ptyID}/connect-token` | `server.experimental.persistentPty.connectToken` | Experimental-only | Retained outside the stable API commitment. |
+| [x] | `GET` | `/api/experimental/persistent-pty/{ptyID}/connect` | `persistentPty.connect` | Experimental-only | Retained outside the stable API commitment. |
+| [ ] 132 | `GET` | `/api/shell` | `shell.list` |  |  |
+| [ ] 133 | `POST` | `/api/shell` | `shell.create` |  |  |
+| [ ] 134 | `GET` | `/api/shell/{id}` | `shell.get` |  |  |
+| [ ] 135 | `DELETE` | `/api/shell/{id}` | `shell.remove` |  |  |
+| [ ] 136 | `PATCH` | `/api/shell/{id}/timeout` | `shell.timeout` |  |  |
+| [ ] 137 | `GET` | `/api/shell/{id}/output` | `shell.output` |  |  |
+
+## Group 10: Events, RPC, and experimental operations
+
+**Endpoints:** 6
+
+| Done | Method | Path | Operation ID | Decision | Notes |
+|---|---|---|---|---|---|
+| [ ] 138 | `POST` | `/api/generate` | `generate.text` |  |  |
+| [ ] 139 | `POST` | `/api/rpc/{rpcID}/{method}` | `rpc.call` |  |  |
+| [ ] 140 | `GET` | `/api/event` | `event.subscribe` |  |  |
+| [ ] 141 | `GET` | `/api/debug/location` | `debug.location.list` |  |  |
+| [ ] 142 | `DELETE` | `/api/debug/location` | `debug.location.evict` |  |  |
+| [x] | `GET` | `/api/experimental/migration/v1` | `experimental.migration.v1.status` | Experimental-only | Retained outside the stable API commitment. |

bun.lock

@@ -14,6 +14,7 @@
       "devDependencies": {
         "@actions/artifact": "5.0.1",
         "@ast-grep/cli": "0.44.0",
+        "@opencode/client": "workspace:*",
         "@tsconfig/bun": "catalog:",
         "@types/mime-types": "3.0.1",
         "@types/react": "19.2.17",
@@ -31,7 +32,7 @@
     },
     "packages/ai": {
       "name": "@opencode/ai",
-      "version": "1.17.20",
+      "version": "2.0.3",
       "dependencies": {
         "@aws-sdk/credential-providers": "3.1057.0",
         "@opencode/schema": "workspace:*",
@@ -53,7 +54,7 @@
     },
     "packages/app": {
       "name": "@opencode/app",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@corvu/drawer": "catalog:",
         "@dnd-kit/abstract": "0.5.0",
@@ -82,6 +83,7 @@
         "@solidjs/router": "catalog:",
         "@tanstack/solid-query": "5.91.4",
         "@tanstack/solid-virtual": "catalog:",
+        "core-js": "3.50.0",
         "effect": "catalog:",
         "fuzzysort": "catalog:",
         "ghostty-web": "github:anomalyco/ghostty-web#83c0a07b8628b748aed073b232cb4b52a6ca11c1",
@@ -111,7 +113,7 @@
     },
     "packages/cli": {
       "name": "@opencode/cli",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "bin": {
         "opencode2": "./bin/opencode2.cjs",
       },
@@ -175,7 +177,7 @@
     },
     "packages/client": {
       "name": "@opencode/client",
-      "version": "1.17.13",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/protocol": "workspace:*",
         "@opencode/schema": "workspace:*",
@@ -201,7 +203,7 @@
     },
     "packages/codemode": {
       "name": "@opencode/codemode",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "dependencies": {
         "acorn": "8.15.0",
         "effect": "catalog:",
@@ -215,7 +217,7 @@
     },
     "packages/console/app": {
       "name": "@opencode/console-app",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@cloudflare/vite-plugin": "1.15.2",
         "@ibm/plex": "6.4.1",
@@ -251,7 +253,7 @@
     },
     "packages/console/core": {
       "name": "@opencode/console-core",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@aws-sdk/client-sts": "3.782.0",
         "@jsx-email/render": "1.1.1",
@@ -278,7 +280,7 @@
     },
     "packages/console/function": {
       "name": "@opencode/console-function",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@openauthjs/openauth": "0.0.0-20250322224806",
         "@opencode/console-core": "workspace:*",
@@ -295,7 +297,7 @@
     },
     "packages/console/mail": {
       "name": "@opencode/console-mail",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@jsx-email/all": "2.2.3",
         "@jsx-email/cli": "1.4.3",
@@ -319,7 +321,7 @@
     },
     "packages/console/support": {
       "name": "@opencode/console-support",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@cloudflare/vite-plugin": "1.15.2",
         "@opencode/console-core": "workspace:*",
@@ -339,16 +341,10 @@
     },
     "packages/core": {
       "name": "@opencode/core",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "dependencies": {
-        "@ai-sdk/alibaba": "1.0.17",
-        "@ai-sdk/anthropic": "3.0.82",
-        "@ai-sdk/azure": "3.0.88",
         "@ai-sdk/cohere": "3.0.27",
         "@ai-sdk/gateway": "3.0.104",
-        "@ai-sdk/google-vertex": "4.0.128",
-        "@ai-sdk/mistral": "3.0.51",
-        "@ai-sdk/openai-compatible": "2.0.41",
         "@ai-sdk/perplexity": "3.0.26",
         "@ai-sdk/provider": "3.0.8",
         "@ai-sdk/provider-utils": "4.0.23",
@@ -356,7 +352,7 @@
         "@ff-labs/fff-bun": "0.10.5",
         "@ff-labs/fff-node": "0.10.5",
         "@lydell/node-pty": "catalog:",
-        "@modelcontextprotocol/sdk": "1.29.0",
+        "@modelcontextprotocol/client": "2.0.0",
         "@opencode-ai/pty": "0.1.13",
         "@opencode/ai": "workspace:*",
         "@opencode/codemode": "workspace:*",
@@ -367,7 +363,6 @@
         "@parcel/watcher": "2.5.1",
         "@silvia-odwyer/photon-node": "0.3.4",
         "@standard-schema/spec": "catalog:",
-        "ai-gateway-provider": "3.1.2",
         "bun-pty": "0.4.8",
         "diff": "catalog:",
         "drizzle-orm": "catalog:",
@@ -391,8 +386,10 @@
         "zod": "catalog:",
       },
       "devDependencies": {
+        "@ai-sdk/openai-compatible": "2.0.41",
         "@effect/platform-node": "catalog:",
         "@effect/sql-sqlite-bun": "catalog:",
+        "@modelcontextprotocol/server": "2.0.0",
         "@opencode/http-recorder": "workspace:*",
         "@parcel/watcher-darwin-arm64": "2.5.1",
         "@parcel/watcher-darwin-x64": "2.5.1",
@@ -411,7 +408,7 @@
     },
     "packages/desktop": {
       "name": "@opencode/desktop",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@zip.js/zip.js": "2.7.62",
         "electron-context-menu": "4.1.2",
@@ -463,7 +460,7 @@
     },
     "packages/enterprise": {
       "name": "@opencode/enterprise",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@hono/standard-validator": "catalog:",
         "@opencode-ai/sdk": "1.18.21",
@@ -500,7 +497,7 @@
     },
     "packages/function": {
       "name": "@opencode/function",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@octokit/auth-app": "8.0.1",
         "@octokit/rest": "catalog:",
@@ -516,7 +513,7 @@
     },
     "packages/http-recorder": {
       "name": "@opencode/http-recorder",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@effect/platform-node-shared": "4.0.0-rc.112",
       },
@@ -535,7 +532,7 @@
     },
     "packages/httpapi-codegen": {
       "name": "@opencode/httpapi-codegen",
-      "version": "0.0.0",
+      "version": "2.0.3",
       "dependencies": {
         "effect": "catalog:",
         "prettier": "3.6.2",
@@ -548,7 +545,7 @@
     },
     "packages/latex": {
       "name": "@opencode/latex",
-      "version": "0.0.0",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/plugin": "workspace:*",
         "@opentui/core": "catalog:",
@@ -562,7 +559,7 @@
     },
     "packages/merman": {
       "name": "@opencode/merman",
-      "version": "0.0.0",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/plugin": "workspace:*",
         "@opentui/core": "catalog:",
@@ -577,7 +574,7 @@
     },
     "packages/plugin": {
       "name": "@opencode/plugin",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@ai-sdk/provider": "3.0.8",
         "@opencode/ai": "workspace:*",
@@ -616,7 +613,7 @@
     },
     "packages/plugin-browser": {
       "name": "@opencode/plugin-browser",
-      "version": "0.0.0",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/plugin": "workspace:*",
         "@opencode/schema": "workspace:*",
@@ -646,7 +643,7 @@
     },
     "packages/protocol": {
       "name": "@opencode/protocol",
-      "version": "1.17.11",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/schema": "workspace:*",
         "effect": "catalog:",
@@ -661,7 +658,7 @@
     },
     "packages/schema": {
       "name": "@opencode/schema",
-      "version": "1.17.11",
+      "version": "2.0.3",
       "dependencies": {
         "@standard-schema/spec": "catalog:",
         "effect": "catalog:",
@@ -685,7 +682,7 @@
     },
     "packages/sdk": {
       "name": "@opencode/sdk",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/client": "workspace:*",
         "@opencode/core": "workspace:*",
@@ -706,7 +703,7 @@
     },
     "packages/server": {
       "name": "@opencode/server",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "dependencies": {
         "@effect/platform-node": "catalog:",
         "@effect/platform-node-shared": "catalog:",
@@ -728,7 +725,7 @@
     },
     "packages/session-ui": {
       "name": "@opencode/session-ui",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@kobalte/core": "catalog:",
         "@opencode/client": "workspace:*",
@@ -763,7 +760,7 @@
     },
     "packages/simulation": {
       "name": "@opencode/simulation",
-      "version": "1.17.13",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/ai": "workspace:*",
         "@opencode/core": "workspace:*",
@@ -783,7 +780,7 @@
     },
     "packages/stats/app": {
       "name": "@opencode/stats-app",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@ibm/plex": "6.4.1",
         "@kobalte/core": "catalog:",
@@ -817,7 +814,7 @@
     },
     "packages/stats/core": {
       "name": "@opencode/stats-core",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@aws-sdk/client-athena": "3.933.0",
         "@planetscale/database": "1.19.0",
@@ -836,7 +833,7 @@
     },
     "packages/stats/server": {
       "name": "@opencode/stats-server",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@aws-sdk/client-firehose": "3.933.0",
         "@effect/platform-node": "catalog:",
@@ -882,7 +879,7 @@
     },
     "packages/theme": {
       "name": "@opencode/theme",
-      "version": "0.0.0",
+      "version": "2.0.3",
       "dependencies": {
         "@opentui/core": "catalog:",
         "effect": "catalog:",
@@ -896,7 +893,7 @@
     },
     "packages/tui": {
       "name": "@opencode/tui",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "dependencies": {
         "@opencode/client": "workspace:*",
         "@opencode/core": "workspace:*",
@@ -931,7 +928,7 @@
     },
     "packages/ui": {
       "name": "@opencode/ui",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@kobalte/core": "catalog:",
         "@pierre/diffs": "catalog:",
@@ -966,7 +963,7 @@
     },
     "packages/util": {
       "name": "@opencode/util",
-      "version": "1.18.3",
+      "version": "2.0.3",
       "dependencies": {
         "@effect/opentelemetry": "catalog:",
         "@effect/platform-node": "catalog:",
@@ -999,7 +996,7 @@
     },
     "packages/web": {
       "name": "@opencode/web",
-      "version": "1.18.15",
+      "version": "2.0.3",
       "dependencies": {
         "@astrojs/cloudflare": "12.6.3",
         "@astrojs/markdown-remark": "6.3.1",
@@ -1040,7 +1037,7 @@
     },
     "services/update": {
       "name": "@opencode/update",
-      "version": "1.18.4",
+      "version": "2.0.3",
       "dependencies": {
         "jose": "6.0.11",
         "semver": "catalog:",
@@ -1080,16 +1077,14 @@
   "patchedDependencies": {
     "@pierre/trees@1.0.0-beta.4": "patches/@pierre%2Ftrees@1.0.0-beta.4.patch",
     "@tanstack/virtual-core@3.17.8": "patches/@tanstack%2Fvirtual-core@3.17.8.patch",
-    "@modelcontextprotocol/sdk@1.29.0": "patches/@modelcontextprotocol%2Fsdk@1.29.0.patch",
     "ghostty-web@github:anomalyco/ghostty-web#83c0a07": "patches/ghostty-web@0.3.0.patch",
+    "@modelcontextprotocol/client@2.0.0": "patches/@modelcontextprotocol%2Fclient@2.0.0.patch",
     "@standard-community/standard-openapi@0.2.9": "patches/@standard-community%2Fstandard-openapi@0.2.9.patch",
-    "@ai-sdk/mistral@3.0.51": "patches/@ai-sdk%2Fmistral@3.0.51.patch",
     "@npmcli/agent@4.0.2": "patches/@npmcli%2Fagent@4.0.2.patch",
     "@silvia-odwyer/photon-node@0.3.4": "patches/@silvia-odwyer%2Fphoton-node@0.3.4.patch",
     "solid-js@1.9.15": "patches/solid-js@1.9.15.patch",
     "vite@8.2.2": "patches/vite@8.2.2.patch",
     "@ff-labs/fff-bun@0.10.5": "patches/@ff-labs%2Ffff-bun@0.10.5.patch",
-    "@ai-sdk/google@3.0.73": "patches/@ai-sdk%2Fgoogle@3.0.73.patch",
     "@dnd-kit/dom@0.5.0": "patches/@dnd-kit%2Fdom@0.5.0.patch",
     "@ai-sdk/openai-compatible@2.0.41": "patches/@ai-sdk%2Fopenai-compatible@2.0.41.patch",
   },
@@ -1192,38 +1187,10 @@
 
     "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@1.2.1", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-jwYUdOQR7tc+Zfch53VL4JJyUNK/46q03uUTYb+PjECsmnNl94XFXOfYLJ8RBpMNidXd1rpOAVgb0vqD98xImA=="],
 
-    "@ai-sdk/alibaba": ["@ai-sdk/alibaba@1.0.17", "", { "dependencies": { "@ai-sdk/openai-compatible": "2.0.41", "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.23" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ZbE+U5bWz2JBc5DERLowx5+TKbjGBE93LqKZAWvuEn7HOSQMraxFMZuc0ST335QZJAyfBOzh7m1mPQ+y7EaaoA=="],
-
-    "@ai-sdk/amazon-bedrock": ["@ai-sdk/amazon-bedrock@4.0.112", "", { "dependencies": { "@ai-sdk/anthropic": "3.0.81", "@ai-sdk/openai": "3.0.67", "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27", "@smithy/eventstream-codec": "^4.0.1", "@smithy/util-utf8": "^4.0.0", "aws4fetch": "^1.0.20" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-PsSh7a6qW+3kQXPs1kD4wDwuZby0t1PIaB6j/1aMKmPFJ5LxcIcULLMF/bjITLt5o/8lc0t6TXIwG0zlhH7uZw=="],
-
-    "@ai-sdk/anthropic": ["@ai-sdk/anthropic@3.0.82", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-WKKou2wbhGGYV8PSALAPyV2YY4nfCqCPkyBzYtJtDA9yCcIFwsbtkTNgg7bqtLCVzeEsY7wwxRoCWy+EMfrw/A=="],
-
-    "@ai-sdk/azure": ["@ai-sdk/azure@3.0.88", "", { "dependencies": { "@ai-sdk/deepseek": "2.0.47", "@ai-sdk/openai": "3.0.84", "@ai-sdk/provider": "3.0.14", "@ai-sdk/provider-utils": "4.0.38" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-RRjZkB1lYplh8dpBarnvkl1j7sYLHsyXua7erL3oNcMK7fHcl4bPO5C7iQhD1O/DqD/zCceDifnege1s+8yEvw=="],
-
-    "@ai-sdk/cerebras": ["@ai-sdk/cerebras@2.0.41", "", { "dependencies": { "@ai-sdk/openai-compatible": "2.0.37", "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-kDMEpjaRdRXIUi1EH8WHwLRahyDTYv9SAJnP6VCCeq8X+tVqZbMLCqqxSG5dRknrI65ucjvzQt+FiDKTAa7AHg=="],
-
     "@ai-sdk/cohere": ["@ai-sdk/cohere@3.0.27", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-OqcCq2PiFY1dbK/0Ck45KuvE8jfdxRuuAE9Y5w46dAk6U+9vPOeg1CDcmR+ncqmrYrhRl3nmyDttyDahyjCzAw=="],
 
-    "@ai-sdk/deepgram": ["@ai-sdk/deepgram@2.0.52", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@ai-sdk/provider-utils": "4.0.46" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-8pcrQvEQCbvrrQKnD6hclBbI0hUgSrgyADykRbabxv/g9vPurfMC6n23J7dD+KZ3EcCoW+qz3IUIfySJ58gBOg=="],
-
-    "@ai-sdk/deepseek": ["@ai-sdk/deepseek@2.0.47", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@ai-sdk/provider-utils": "4.0.38" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MzcQ321JO8OY+TVLFI81A7cIIuoeLLxrLCDD+8C1E3Ro6UFyfMtRXo9bw9OhTMRSDMo6hgSDOo4Fekz8aJtQYQ=="],
-
-    "@ai-sdk/elevenlabs": ["@ai-sdk/elevenlabs@2.0.52", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@ai-sdk/provider-utils": "4.0.46" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ZgkausouWvO9U4ZtowNJ093bSNYOvH8zqls3uLC3+oxzWvbbTZO8SOdmFk0+gGafsXFJvq2yUX9+rEeJPwOJLw=="],
-
-    "@ai-sdk/fireworks": ["@ai-sdk/fireworks@2.0.77", "", { "dependencies": { "@ai-sdk/openai-compatible": "2.0.68", "@ai-sdk/provider": "3.0.15", "@ai-sdk/provider-utils": "4.0.46" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ce5IVMrW38P63MlkElmpzrFGh8rMm7no5vJ1dp+eDYV83OtDo5fAqQkcCXC7nQtQTfaTErOK9PEdNh13syUmQg=="],
-
     "@ai-sdk/gateway": ["@ai-sdk/gateway@3.0.104", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.23", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ZKX5n74io8VIRlhIMSLWVlvT3sXC8Z7cZ9GHuWBWZDVi96+62AIsWuLGvMfcBA1STYuSoDrp6rIziZmvrTq0TA=="],
 
-    "@ai-sdk/google": ["@ai-sdk/google@3.0.73", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-o2MuIeyvZrFIeIbnbA8Thrr63irdyUBh0uWBZ2lY6yFeXuE/tcwyXF74bDKS4KvTu84uFpQfpbS/LXHGKKXz+g=="],
-
-    "@ai-sdk/google-vertex": ["@ai-sdk/google-vertex@4.0.128", "", { "dependencies": { "@ai-sdk/anthropic": "3.0.77", "@ai-sdk/google": "3.0.73", "@ai-sdk/openai-compatible": "2.0.47", "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27", "google-auth-library": "^10.5.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-jK8fixb4km2yfgvb9DUFQRpV/jiDB0v9gyxHoHfPydaQvz+CpAz8DTt1quyaM+Wg9G2R8Zo68CYmHbIkUqW2AA=="],
-
-    "@ai-sdk/groq": ["@ai-sdk/groq@3.0.31", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-XbbugpnFmXGu2TlXiq8KUJskP6/VVbuFcnFIGDzDIB/Chg6XHsNnqrTF80Zxkh0Pd3+NvbM+2Uqrtsndk6bDAg=="],
-
-    "@ai-sdk/mistral": ["@ai-sdk/mistral@3.0.51", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@ai-sdk/provider-utils": "4.0.40" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-83eXY6p0lUFhSuMvNDmTKDuMciK5XDAWDlNh5c0L80tKjmtCFRItA1MZHp4IKe1r7eK8Rb5nN7qtxqMLUFRIRw=="],
-
-    "@ai-sdk/openai": ["@ai-sdk/openai@3.0.84", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@ai-sdk/provider-utils": "4.0.38" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-cmgbeJL0bbY0yTJH4/AdmP5E7MjWRL9G8UdhIi0JlV/So03o82ORJofW8OzwCZPTORVQblFbpZXYGDcUd9NdUQ=="],
-
     "@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.41", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.23" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-kNAGINk71AlOXx10Dq/PXw4t/9XjdK8uxfpVElRwtSFMdeSiLVt58p9TPx4/FJD+hxZuVhvxYj9r42osxWq79g=="],
 
     "@ai-sdk/perplexity": ["@ai-sdk/perplexity@3.0.26", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-dXzrVsLR5f6tr+U04jq4AXoRroGFBTvODnLgss0SWbzNjGGQg3XqtQ9j7rCLo6o8qbYGuAHvqUrIpUCuiscuFg=="],
@@ -1234,8 +1201,6 @@
 
     "@ai-sdk/vercel": ["@ai-sdk/vercel@2.0.39", "", { "dependencies": { "@ai-sdk/openai-compatible": "2.0.37", "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-8eu3ljJpkCTP4ppcyYB+NcBrkcBoSOFthCSgk5VnjaxnDaOJFaxnPwfddM7wx3RwMk2CiK1O61Px/LlqNc7QkQ=="],
 
-    "@ai-sdk/xai": ["@ai-sdk/xai@3.0.123", "", { "dependencies": { "@ai-sdk/openai-compatible": "2.0.69", "@ai-sdk/provider": "3.0.15", "@ai-sdk/provider-utils": "4.0.46" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-WNASvd1C516oh2qYIj9EvAVPdU+Abads8DQWU6p9lQtvFFeGh8QW+3LDOARZd1GCINUFfw5yadEK845SMQKLsA=="],
-
     "@alloc/quick-lru": ["@alloc/quick-lru@5.2.0", "", {}, "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw=="],
 
     "@ampproject/remapping": ["@ampproject/remapping@2.3.0", "", { "dependencies": { "@jridgewell/gen-mapping": "^0.3.5", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="],
@@ -1876,8 +1841,6 @@
 
     "@happy-dom/global-registrator": ["@happy-dom/global-registrator@20.0.11", "", { "dependencies": { "@types/node": "^20.0.0", "happy-dom": "^20.0.11" } }, "sha512-GqNqiShBT/lzkHTMC/slKBrvN0DsD4Di8ssBk4aDaVgEn+2WMzE6DXxq701ndSXj7/0cJ8mNT71pM7Bnrr6JRw=="],
 
-    "@hono/node-server": ["@hono/node-server@1.19.17", "", { "peerDependencies": { "hono": "^4" } }, "sha512-dSneS5qhiauZWGDCeK4o695Xd9nUNjviSZCMQrj10eetr8Uln1ucn6bbphOM6UynAMMtNIzZNSpL9vnASJwrPQ=="],
-
     "@hono/standard-validator": ["@hono/standard-validator@0.2.0", "", { "peerDependencies": { "@standard-schema/spec": "1.0.0", "hono": ">=3.9.0" } }, "sha512-pFq0UVAnjzXcDAgqFpDeVL3MOUPrlIh/kPqBDvbCYoThVhhS+Vf37VcdsakdOFFGiqoiYVxp3LifXFhGhp/rgQ=="],
 
     "@ibm/plex": ["@ibm/plex@6.4.1", "", { "dependencies": { "@ibm/telemetry-js": "^1.5.1" } }, "sha512-fnsipQywHt3zWvsnlyYKMikcVI7E2fEwpiPnIHFqlbByXVfQfANAAeJk1IV4mNnxhppUIDlhU0TzwYwL++Rn2g=="],
@@ -2036,7 +1999,11 @@
 
     "@mermaid-js/parser": ["@mermaid-js/parser@1.2.1", "", { "dependencies": { "@chevrotain/types": "~11.1.2" } }, "sha512-n12NohV3mrUyUL2o93IgG/ifeW9FTyeJn3zDxkhwa8MJ9Fxg3HQMlA3RiGmD/3UnJvheztkjjQAjA2T4LmUcpw=="],
 
-    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.29.0", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ=="],
+    "@modelcontextprotocol/client": ["@modelcontextprotocol/client@2.0.0", "", { "dependencies": { "@modelcontextprotocol/core": "2.0.0", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "jose": "^6.1.3", "pkce-challenge": "^5.0.0", "zod": "^4.2.0" } }, "sha512-8f1OghQ2rjzIOfqgUCP+8GiUWqRs89njoWLNqAe8kWmDePv3s1fZXseej+QXemssEuuOvLLmLO/kqM3IQHtISw=="],
+
+    "@modelcontextprotocol/core": ["@modelcontextprotocol/core@2.0.0", "", { "dependencies": { "zod": "^4.2.0" } }, "sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA=="],
+
+    "@modelcontextprotocol/server": ["@modelcontextprotocol/server@2.0.0", "", { "dependencies": { "@modelcontextprotocol/core": "2.0.0", "zod": "^4.2.0" } }, "sha512-YhHWdHfpFMQfd0prsEnxKeS3Qz3ytIGmsS0sth4KDjnacIT7hxk6hXHkJ9KysxlkvTM+WZAtQbbcUhdoP4Hvtw=="],
 
     "@motionone/animation": ["@motionone/animation@10.18.0", "", { "dependencies": { "@motionone/easing": "^10.18.0", "@motionone/types": "^10.17.1", "@motionone/utils": "^10.18.0", "tslib": "^2.3.1" } }, "sha512-9z2p5GFGCm0gBsZbi8rVMOAJCtw1WqBTIPw3ozk06gDvZInBPIsQcHgYogEJ4yuHJ+akuW8g1SEIOpTOvYs8hw=="],
 
@@ -2254,8 +2221,6 @@
 
     "@opencode/www": ["@opencode/www@workspace:services/www"],
 
-    "@openrouter/ai-sdk-provider": ["@openrouter/ai-sdk-provider@2.10.0", "", { "peerDependencies": { "ai": "^6.0.0", "zod": "^3.25.0 || ^4.0.0" } }, "sha512-FMsAEjLUt5pWuRE2LDC/LCvVrFjLlrEzUITH5+5SZtfq7KZ2wrOHjQVxzz92sju8S9ltpzW87CLW8/b0oBXVCw=="],
-
     "@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
 
     "@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.214.0", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-40lSJeqYO8Uz2Yj7u94/SJWE/wONa7rmMKjI1ZcIjgf3MHNHv1OZUCrCETGuaRF62d5pQD1wKIW+L4lmSMTzZA=="],
@@ -3362,8 +3327,6 @@
 
     "abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
 
-    "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
-
     "acorn": ["acorn@8.15.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg=="],
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
@@ -3376,8 +3339,6 @@
 
     "ai": ["ai@7.0.66", "", { "dependencies": { "@ai-sdk/gateway": "4.0.52", "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-wBUyoCYF3GVr+62nelBgR8YbpTSsMZrzFyOOjiwijylNSM2TFCW35C+Pml2vc59/WLMpyhS/LWZ55M+B9DAcSg=="],
 
-    "ai-gateway-provider": ["ai-gateway-provider@3.1.2", "", { "optionalDependencies": { "@ai-sdk/amazon-bedrock": "^4.0.62", "@ai-sdk/anthropic": "^3.0.46", "@ai-sdk/azure": "^3.0.31", "@ai-sdk/cerebras": "^2.0.34", "@ai-sdk/cohere": "^3.0.21", "@ai-sdk/deepgram": "^2.0.20", "@ai-sdk/deepseek": "^2.0.20", "@ai-sdk/elevenlabs": "^2.0.20", "@ai-sdk/fireworks": "^2.0.34", "@ai-sdk/google": "^3.0.30", "@ai-sdk/google-vertex": "^4.0.61", "@ai-sdk/groq": "^3.0.24", "@ai-sdk/mistral": "^3.0.20", "@ai-sdk/openai": "^3.0.30", "@ai-sdk/perplexity": "^3.0.19", "@ai-sdk/xai": "^3.0.57", "@openrouter/ai-sdk-provider": "^2.2.3" }, "peerDependencies": { "@ai-sdk/openai-compatible": "^2.0.0", "@ai-sdk/provider": "^3.0.0", "@ai-sdk/provider-utils": "^4.0.0", "ai": "^6.0.0" } }, "sha512-krGNnJSoO/gJ7Hbe5nQDlsBpDUGIBGtMQTRUaW7s1MylsfvLduba0TLWzQaGtOmNRkP0pGhtGlwsnS6FNQMlyw=="],
-
     "ajv": ["ajv@8.20.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
 
     "ajv-draft-04": ["ajv-draft-04@1.0.0", "", { "peerDependencies": { "ajv": "^8.5.0" }, "optionalPeers": ["ajv"] }, "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw=="],
@@ -3522,8 +3483,6 @@
 
     "bluebird": ["bluebird@3.7.2", "", {}, "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg=="],
 
-    "body-parser": ["body-parser@2.3.0", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^2.0.0", "debug": "^4.4.3", "http-errors": "^2.0.1", "iconv-lite": "^0.7.2", "on-finished": "^2.4.1", "qs": "^6.15.2", "raw-body": "^3.0.2", "type-is": "^2.1.0" } }, "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw=="],
-
     "boolbase": ["boolbase@1.0.0", "", {}, "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww=="],
 
     "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],
@@ -3566,8 +3525,6 @@
 
     "bundle-name": ["bundle-name@4.1.0", "", { "dependencies": { "run-applescript": "^7.0.0" } }, "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q=="],
 
-    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
-
     "bytestreamjs": ["bytestreamjs@2.0.1", "", {}, "sha512-U1Z/ob71V/bXfVABvNr/Kumf5VyeQRBEm6Txb0PQ6S7V5GpBM3w4Cbqz/xPDicR5tN0uvDifng8C+5qECeGwyQ=="],
 
     "cac": ["cac@7.0.0", "", {}, "sha512-tixWYgm5ZoOD+3g6UTea91eow5z6AAHaho3g0V9CNSNb45gM8SmflpAc+GRd1InC4AqN/07Unrgp56Y94N9hJQ=="],
@@ -3690,9 +3647,7 @@
 
     "consola": ["consola@3.4.2", "", {}, "sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA=="],
 
-    "content-disposition": ["content-disposition@1.1.0", "", {}, "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g=="],
-
-    "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
+    "content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
 
     "convert-source-map": ["convert-source-map@2.0.0", "", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],
 
@@ -3700,14 +3655,12 @@
 
     "cookie-es": ["cookie-es@2.0.1", "", {}, "sha512-aVf4A4hI2w70LnF7GG+7xDQUkliwiXWXFvTjkip4+b64ygDQ2sJPRSKFDHbxn8o0xu9QzPkMuuiWIXyFSE2slA=="],
 
-    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+    "core-js": ["core-js@3.50.0", "", {}, "sha512-BRWgOLKkFeCgRudR6zrs8p9XJZcE14grzKMMssoYrk6krtuEZ7MTKPIY5RzOnqsEKIR9kst7wNzphttraT+Yqw=="],
 
     "core-js-compat": ["core-js-compat@3.50.0", "", { "dependencies": { "browserslist": "^4.28.7" } }, "sha512-XGpFGbMLHwSt74YLTKho7Ib242qi6O8MSX+sRokV4oz7iKXvQWGYZthjIhjRGMxjzVkAubBO512dKGYcefmX3Q=="],
 
     "core-util-is": ["core-util-is@1.0.3", "", {}, "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ=="],
 
-    "cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="],
-
     "cose-base": ["cose-base@1.0.3", "", { "dependencies": { "layout-base": "^1.0.0" } }, "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg=="],
 
     "crc-32": ["crc-32@1.2.2", "", { "bin": { "crc32": "bin/crc32.njs" } }, "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ=="],
@@ -3860,8 +3813,6 @@
 
     "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
 
-    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
-
     "deprecation": ["deprecation@2.3.1", "", {}, "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="],
 
     "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
@@ -3936,8 +3887,6 @@
 
     "editorconfig": ["editorconfig@1.0.7", "", { "dependencies": { "@one-ini/wasm": "0.1.1", "commander": "^10.0.0", "minimatch": "^9.0.1", "semver": "^7.5.3" }, "bin": { "editorconfig": "bin/editorconfig" } }, "sha512-e0GOtq/aTQhVdNyDU9e02+wz9oDDM+SIOQxWME2QRjzRX5yyLAuHDE+0aE8vHb9XRC8XD37eO2u57+F09JqFhw=="],
 
-    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
-
     "effect": ["effect@4.0.0-rc.112", "", { "dependencies": { "fast-check": "^4.9.0", "msgpackr": "^2.0.5" } }, "sha512-wXxwuh1Ywnv4cPRM3Wfa0vDwuOHnZ1TsTgHJkG9XgzND6inhBH9n1vBxhg3iIXOia/OrpmvVmd3lrD4vq6bF3A=="],
 
     "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],
@@ -3976,8 +3925,6 @@
 
     "emoji-regex-xs": ["emoji-regex-xs@1.0.0", "", {}, "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg=="],
 
-    "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
-
     "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
 
     "engine.io-client": ["engine.io-client@6.6.6", "", { "dependencies": { "@socket.io/component-emitter": "~3.1.0", "debug": "~4.4.1", "engine.io-parser": "~5.2.1", "ws": "~8.21.0", "xmlhttprequest-ssl": "~2.1.1" } }, "sha512-iY6QdftLQ9pyiPoX082bpf/u1UewnOaJrtJIF9T0++QB34lZrj0uP+Q/bj8AlUsAxqhnkTV2BS8SBZSxOmoV5Q=="],
@@ -4030,8 +3977,6 @@
 
     "escape-goat": ["escape-goat@4.0.0", "", {}, "sha512-2Sd4ShcWxbx6OY1IHyla/CVNwvg7XwZVoXZHcSu9w9SReNP1EzzD5T8NWKIR38fIqEns9kDWKUQTXXAmlDrdPg=="],
 
-    "escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
-
     "escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
 
     "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
@@ -4054,8 +3999,6 @@
 
     "eta": ["eta@4.6.0", "", {}, "sha512-lW6is4T1NFOYnmqGZIfvixqj7A7sSvScF+DN8EK6K58xI5MZ5UvYe0GjopxOXQtZvUn4eDdVuZ8XSoYWTMEKwA=="],
 
-    "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
-
     "event-target-shim": ["event-target-shim@5.0.1", "", {}, "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ=="],
 
     "eventemitter3": ["eventemitter3@5.0.4", "", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
@@ -4074,10 +4017,6 @@
 
     "exponential-backoff": ["exponential-backoff@3.1.3", "", {}, "sha512-ZgEeZXj30q+I0EN+CbSSpIyPaJ5HVQD18Z1m+u1FXbAeT94mr1zw50q4q6jiiC447Nl/YTcIYSAftiGqetwXCA=="],
 
-    "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
-
-    "express-rate-limit": ["express-rate-limit@8.6.2", "", { "dependencies": { "debug": "^4.4.3", "ip-address": "^10.2.0" }, "peerDependencies": { "express": ">= 4.11" } }, "sha512-YH4ru+eOJxQABscKFfRCy9R7x9QFGdezclVMwwgFFndzS2Xnm0uo6B0ABZsLhcpeptGv2qvuJVWlQr9gQZoC3A=="],
-
     "expressive-code": ["expressive-code@0.41.7", "", { "dependencies": { "@expressive-code/core": "^0.41.7", "@expressive-code/plugin-frames": "^0.41.7", "@expressive-code/plugin-shiki": "^0.41.7", "@expressive-code/plugin-text-markers": "^0.41.7" } }, "sha512-2wZjC8OQ3TaVEMcBtYY4Va3lo6J+Ai9jf3d4dbhURMJcU4Pbqe6EcHe424MIZI0VHUA1bR6xdpoHYi3yxokWqA=="],
 
     "ext-list": ["ext-list@2.2.2", "", { "dependencies": { "mime-db": "^1.28.0" } }, "sha512-u+SQgsubraE6zItfVA0tBuCBhfU9ogSRnsvygI7wht9TS510oLkBRXBsqopeUG/GBOIQyKZO9wjTqIu/sf5zFA=="],
@@ -4124,8 +4063,6 @@
 
     "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
 
-    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
-
     "find-babel-config": ["find-babel-config@2.1.2", "", { "dependencies": { "json5": "^2.2.3" } }, "sha512-ZfZp1rQyp4gyuxqt1ZqjFGVeVBvmpURMqdIWXbPRfB97Bf6BzdK/xSIbylEINzQ0kB5tlDQfn9HkNXXWsqTqLg=="],
 
     "find-up": ["find-up@5.0.0", "", { "dependencies": { "locate-path": "^6.0.0", "path-exists": "^4.0.0" } }, "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng=="],
@@ -4150,14 +4087,10 @@
 
     "formdata-polyfill": ["formdata-polyfill@4.0.10", "", { "dependencies": { "fetch-blob": "^3.1.2" } }, "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g=="],
 
-    "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
-
     "fraction.js": ["fraction.js@5.3.4", "", {}, "sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ=="],
 
     "framer-motion": ["framer-motion@8.5.5", "", { "dependencies": { "@motionone/dom": "^10.15.3", "hey-listen": "^1.0.8", "tslib": "^2.4.0" }, "optionalDependencies": { "@emotion/is-prop-valid": "^0.8.2" }, "peerDependencies": { "react": "^18.0.0", "react-dom": "^18.0.0" } }, "sha512-5IDx5bxkjWHWUF3CVJoSyUVOtrbAxtzYBBowRE2uYI/6VYhkEBD+rbTHEGuUmbGHRj6YqqSfoG7Aa1cLyWCrBA=="],
 
-    "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
-
     "fs-extra": ["fs-extra@10.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ=="],
 
     "fs-minipass": ["fs-minipass@3.0.3", "", { "dependencies": { "minipass": "^7.0.3" } }, "sha512-XUBA9XClHbnJWSfBzjkm6RvPsyg3sryZt06BEQoXcF7EK/xpGaQYJgQKDJSUH5SGZ76Y7pFx1QBnXz09rU5Fbw=="],
@@ -4332,8 +4265,6 @@
 
     "http-cache-semantics": ["http-cache-semantics@4.2.0", "", {}, "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ=="],
 
-    "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
-
     "http-link-header": ["http-link-header@1.1.4", "", {}, "sha512-xT3GPW6/ZbGuw4UvwHqErSCEjNUlwbQJuZn9/q5U4WEKfp2kENVCAlousG1zLxHeaQ/ffOHUNpWamvkbBW0eNw=="],
 
     "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
@@ -4388,8 +4319,6 @@
 
     "ip-address": ["ip-address@10.5.0", "", {}, "sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g=="],
 
-    "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
-
     "iron-webcrypto": ["iron-webcrypto@1.2.1", "", {}, "sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg=="],
 
     "is-alphabetical": ["is-alphabetical@2.0.1", "", {}, "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ=="],
@@ -4454,8 +4383,6 @@
 
     "is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
 
-    "is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
-
     "is-property": ["is-property@1.0.2", "", {}, "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g=="],
 
     "is-regex": ["is-regex@1.2.1", "", { "dependencies": { "call-bound": "^1.0.2", "gopd": "^1.2.0", "has-tostringtag": "^1.0.2", "hasown": "^2.0.2" } }, "sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g=="],
@@ -4722,12 +4649,8 @@
 
     "mdn-data": ["mdn-data@2.27.1", "", {}, "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ=="],
 
-    "media-typer": ["media-typer@1.1.1", "", {}, "sha512-yz3xRaG20c6/BOzvYoDaGtPmGscs7YivItZEEqe6GbwNfHuxu9YNmvnEkMzKldAGY4/80pRcQRZSEnhquk9XuQ=="],
-
     "merge-anything": ["merge-anything@5.1.7", "", { "dependencies": { "is-what": "^4.1.8" } }, "sha512-eRtbOb1N5iyH0tkQDAoQ4Ipsp/5qSR79Dzrz8hEPxRX10RWWR/iQXdoKmBSRCThY1Fh5EhISDtpSc93fpxUniQ=="],
 
-    "merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
-
     "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="],
 
     "mermaid": ["mermaid@11.17.2", "", { "dependencies": { "@braintree/sanitize-url": "^7.1.2", "@iconify/utils": "^3.0.2", "@mermaid-js/parser": "^1.2.1", "@types/d3": "^7.4.3", "@upsetjs/venn.js": "^2.0.0", "cytoscape": "^3.34.0", "cytoscape-cose-bilkent": "^4.1.0", "cytoscape-fcose": "^2.2.0", "d3": "^7.9.0", "d3-sankey": "^0.12.3", "dagre-d3-es": "7.0.14", "dayjs": "^1.11.21", "dompurify": "^3.3.3", "es-toolkit": "^1.45.1", "fastdom": "1.0.12", "katex": "^0.16.47", "khroma": "^2.1.0", "marked": "^16.3.0", "roughjs": "^4.6.6", "stylis": "^4.3.6", "ts-dedent": "^2.2.0", "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0" } }, "sha512-V6K3C8EBdEsPFZXSKMJe6ppQOENxuHARr9GvHX4hh47lAbhMRD9qf4oEK7LoaRQxULMa80/qt5gHO73aCleBBg=="],
@@ -4952,8 +4875,6 @@
 
     "oidc-token-hash": ["oidc-token-hash@5.2.0", "", {}, "sha512-6gj2m8cJZ+iSW8bm0FXdGF0YhIQbKrfP4yWTNzxc31U6MOjfEmB1rHvlYvxI1B7t7BCi1F2vYTT6YhtQRG4hxw=="],
 
-    "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
-
     "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
 
     "oniguruma-parser": ["oniguruma-parser@0.12.2", "", {}, "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw=="],
@@ -5024,8 +4945,6 @@
 
     "parseley": ["parseley@0.12.1", "", { "dependencies": { "leac": "^0.6.0", "peberminta": "^0.9.0" } }, "sha512-e6qHKe3a9HWr0oMRVDTRhKce+bRO8VGQR3NyVwcjwrbhMmFCX9KszEV35+rn4AdilFAq9VPxP/Fe1wC9Qjd2lw=="],
 
-    "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
-
     "pascal-case": ["pascal-case@3.1.2", "", { "dependencies": { "no-case": "^3.0.4", "tslib": "^2.0.3" } }, "sha512-uWlGT3YSnK9x3BQJaOdcZwrnV6hPpd8jFH1/ucpiLRPh/2zCVJKS19E4GvYHvaCcACn3foXZ0cLB9Wrx1KGe5g=="],
 
     "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
@@ -5148,8 +5067,6 @@
 
     "protobufjs": ["protobufjs@7.6.5", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.5", "@protobufjs/eventemitter": "^1.1.1", "@protobufjs/fetch": "^1.1.1", "@protobufjs/float": "^1.0.2", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.1", "@types/node": ">=13.7.0", "long": "^5.3.2" } }, "sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw=="],
 
-    "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
-
     "proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
 
     "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
@@ -5176,10 +5093,6 @@
 
     "radix3": ["radix3@1.1.2", "", {}, "sha512-b484I/7b8rDEdSDKckSSBA8knMpcdsXudlE/LNL639wFoHKwLbEkQFZHWEYwDC0wa0FKUcCY+GAF73Z7wxNVFA=="],
 
-    "range-parser": ["range-parser@1.3.0", "", {}, "sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw=="],
-
-    "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
-
     "react": ["react@18.2.0", "", { "dependencies": { "loose-envify": "^1.1.0" } }, "sha512-/3IjMdb2L9QbBdWiW5e3P2/npwMBaU9mHCSCUzNln0ZCYbcfTsGbTJrU/kGemdH2IWmB2ioZ+zkxtmq6g09fGQ=="],
 
     "react-dom": ["react-dom@18.2.0", "", { "dependencies": { "loose-envify": "^1.1.0", "scheduler": "^0.23.0" }, "peerDependencies": { "react": "^18.2.0" } }, "sha512-6IMTriUmvsjHUjNtEDudZfuDQUoWXVxKHhlEGSk81n4YFS+r/Kl99wXiwlVXtPBtJenozv2P+hxDsw9eA7Xo6g=="],
@@ -5334,8 +5247,6 @@
 
     "roughjs": ["roughjs@4.6.6", "", { "dependencies": { "hachure-fill": "^0.5.2", "path-data-parser": "^0.1.0", "points-on-curve": "^0.2.0", "points-on-path": "^0.2.1" } }, "sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ=="],
 
-    "router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
-
     "run-applescript": ["run-applescript@7.1.0", "", {}, "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q=="],
 
     "run-parallel": ["run-parallel@1.2.0", "", { "dependencies": { "queue-microtask": "^1.2.2" } }, "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA=="],
@@ -5370,8 +5281,6 @@
 
     "semver-compare": ["semver-compare@1.0.0", "", {}, "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow=="],
 
-    "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
-
     "seq-queue": ["seq-queue@0.0.5", "", {}, "sha512-hr3Wtp/GZIc/6DAGPDcV4/9WoZhjrkXsi5B/07QgX8tsdc6ilr7BFM6PM6rbdAX1kFSDYeZGLipIZZKyQP0O5Q=="],
 
     "serialize-error": ["serialize-error@7.0.1", "", { "dependencies": { "type-fest": "^0.13.1" } }, "sha512-8I8TjW5KMOKsZQTvoxjuSIa7foAwPWGOts+6o7sgjz41/qMD9VQHEDxi6PBvK2l0MXUmqZyNpUK+T2tQaaElvw=="],
@@ -5382,16 +5291,12 @@
 
     "seroval-plugins": ["seroval-plugins@1.5.6", "", { "peerDependencies": { "seroval": "^1.0" } }, "sha512-HXuLAX2pu/UByPpaeo/TaMfvMIi+1QqIoPJYCcAtU8QkVNwgR6MPlGuCQTErV1JwraaMbYaWVIBX7mppzGLATQ=="],
 
-    "serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
-
     "set-function-length": ["set-function-length@1.2.2", "", { "dependencies": { "define-data-property": "^1.1.4", "es-errors": "^1.3.0", "function-bind": "^1.1.2", "get-intrinsic": "^1.2.4", "gopd": "^1.0.1", "has-property-descriptors": "^1.0.2" } }, "sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg=="],
 
     "set-function-name": ["set-function-name@2.0.2", "", { "dependencies": { "define-data-property": "^1.1.4", "es-errors": "^1.3.0", "functions-have-names": "^1.2.3", "has-property-descriptors": "^1.0.2" } }, "sha512-7PGFlmtwsEADb0WYyvCMa1t+yke6daIG4Wirafur5kcf+MhUnPms1UeR0CKQdTZD81yESwMHbtn+TR+dMviakQ=="],
 
     "set-proto": ["set-proto@1.0.0", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.0.0" } }, "sha512-RJRdvCo6IAnPdsvP/7m6bsQqNnn1FCBX5ZNtFL98MmFF/4xAIJTIg1YbHW5DC2W5SKZanrC6i4HsJqlajw/dZw=="],
 
-    "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
-
     "sharp": ["sharp@0.35.3", "", { "dependencies": { "@img/colour": "^1.1.0", "detect-libc": "^2.1.2", "semver": "^7.8.5" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "0.35.3", "@img/sharp-darwin-x64": "0.35.3", "@img/sharp-freebsd-wasm32": "0.35.3", "@img/sharp-libvips-darwin-arm64": "1.3.2", "@img/sharp-libvips-darwin-x64": "1.3.2", "@img/sharp-libvips-linux-arm": "1.3.2", "@img/sharp-libvips-linux-arm64": "1.3.2", "@img/sharp-libvips-linux-ppc64": "1.3.2", "@img/sharp-libvips-linux-riscv64": "1.3.2", "@img/sharp-libvips-linux-s390x": "1.3.2", "@img/sharp-libvips-linux-x64": "1.3.2", "@img/sharp-libvips-linuxmusl-arm64": "1.3.2", "@img/sharp-libvips-linuxmusl-x64": "1.3.2", "@img/sharp-linux-arm": "0.35.3", "@img/sharp-linux-arm64": "0.35.3", "@img/sharp-linux-ppc64": "0.35.3", "@img/sharp-linux-riscv64": "0.35.3", "@img/sharp-linux-s390x": "0.35.3", "@img/sharp-linux-x64": "0.35.3", "@img/sharp-linuxmusl-arm64": "0.35.3", "@img/sharp-linuxmusl-x64": "0.35.3", "@img/sharp-webcontainers-wasm32": "0.35.3", "@img/sharp-win32-arm64": "0.35.3", "@img/sharp-win32-ia32": "0.35.3", "@img/sharp-win32-x64": "0.35.3" }, "peerDependencies": { "@types/node": "*" }, "optionalPeers": ["@types/node"] }, "sha512-ej0zVHuZGHCiABXcNxeYhpRnPNPAcvbG8RMdBAhDAxLKkCRVSpK3Iyu7qbqw3JMzoj0REeM6f3tJLtVwl0023Q=="],
 
     "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
@@ -5516,8 +5421,6 @@
 
     "stat-mode": ["stat-mode@1.0.0", "", {}, "sha512-jH9EhtKIjuXZ2cWxmXS8ZP80XyC3iasQxMDV8jzhNJpfDb7VbQLVW4Wvsxz9QZvzV+G4YoSfBUVKDOyxLzi/sg=="],
 
-    "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
-
     "std-env": ["std-env@4.2.0", "", {}, "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw=="],
 
     "stop-iteration-iterator": ["stop-iteration-iterator@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "internal-slot": "^1.1.0" } }, "sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ=="],
@@ -5654,8 +5557,6 @@
 
     "toad-cache": ["toad-cache@3.7.4", "", {}, "sha512-m1TdR/rvT7kgGJZhspNtXdsdYk0fddFpJJFlG5s+UkPFo6lkLoZ3YLOaovPYjq1R75NP5JfeTlSHaOsE09peCg=="],
 
-    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
-
     "toolbeam-docs-theme": ["toolbeam-docs-theme@0.4.8", "", { "peerDependencies": { "@astrojs/starlight": "^0.34.3", "astro": "^5.7.13" } }, "sha512-b+5ynEFp4Woe5a22hzNQm42lD23t13ZMihVxHbzjA50zdcM9aOSJTIjdJ0PDSd4/50HbBXcpHiQsz6rM4N88ww=="],
 
     "topojson-client": ["topojson-client@3.1.0", "", { "dependencies": { "commander": "2" }, "bin": { "topo2geo": "bin/topo2geo", "topomerge": "bin/topomerge", "topoquantize": "bin/topoquantize" } }, "sha512-605uxS6bcYxGXw9qi62XyrV6Q3xwbndjachmNxu8HWTtVPxZfEJN9fd/SZS1Q54Sn2y0TMyMxFj/cJINqGHrKw=="],
@@ -5698,8 +5599,6 @@
 
     "type-fest": ["type-fest@4.41.0", "", {}, "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA=="],
 
-    "type-is": ["type-is@2.1.0", "", { "dependencies": { "content-type": "^2.0.0", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA=="],
-
     "typed-array-buffer": ["typed-array-buffer@1.0.3", "", { "dependencies": { "call-bound": "^1.0.3", "es-errors": "^1.3.0", "is-typed-array": "^1.1.14" } }, "sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw=="],
 
     "typed-array-byte-length": ["typed-array-byte-length@1.0.3", "", { "dependencies": { "call-bind": "^1.0.8", "for-each": "^0.3.3", "gopd": "^1.2.0", "has-proto": "^1.2.0", "is-typed-array": "^1.1.14" } }, "sha512-BaXgOuIxz8n8pIq3e7Atg/7s+DpiYrxn4vdot3w9KbnBhcRQq6o3xemQdIfynqSeXeDrF32x+WvfzmOjPiY9lg=="],
@@ -5778,8 +5677,6 @@
 
     "universalify": ["universalify@2.0.1", "", {}, "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw=="],
 
-    "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
-
     "unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
 
     "unstorage": ["unstorage@2.0.0-alpha.7", "", { "peerDependencies": { "@azure/app-configuration": "^1.11.0", "@azure/cosmos": "^4.9.1", "@azure/data-tables": "^13.3.2", "@azure/identity": "^4.13.0", "@azure/keyvault-secrets": "^4.10.0", "@azure/storage-blob": "^12.31.0", "@capacitor/preferences": "^6 || ^7 || ^8", "@deno/kv": ">=0.13.0", "@netlify/blobs": "^6.5.0 || ^7.0.0 || ^8.1.0 || ^9.0.0 || ^10.0.0", "@planetscale/database": "^1.19.0", "@upstash/redis": "^1.36.2", "@vercel/blob": ">=0.27.3", "@vercel/functions": "^2.2.12 || ^3.0.0", "@vercel/kv": "^1.0.1", "aws4fetch": "^1.0.20", "chokidar": "^4 || ^5", "db0": ">=0.3.4", "idb-keyval": "^6.2.2", "ioredis": "^5.9.3", "lru-cache": "^11.2.6", "mongodb": "^6 || ^7", "ofetch": "*", "uploadthing": "^7.7.4" }, "optionalPeers": ["@azure/app-configuration", "@azure/cosmos", "@azure/data-tables", "@azure/identity", "@azure/keyvault-secrets", "@azure/storage-blob", "@capacitor/preferences", "@deno/kv", "@netlify/blobs", "@planetscale/database", "@upstash/redis", "@vercel/blob", "@vercel/functions", "@vercel/kv", "aws4fetch", "chokidar", "db0", "idb-keyval", "ioredis", "lru-cache", "mongodb", "ofetch", "uploadthing"] }, "sha512-ELPztchk2zgFJnakyodVY3vJWGW9jy//keJ32IOJVGUMyaPydwcA1FtVvWqT0TNRch9H+cMNEGllfVFfScImog=="],
@@ -5810,8 +5707,6 @@
 
     "validate-npm-package-name": ["validate-npm-package-name@7.0.2", "", {}, "sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A=="],
 
-    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
-
     "venice-ai-sdk-provider": ["venice-ai-sdk-provider@2.1.1", "", { "dependencies": { "@ai-sdk/openai-compatible": "^2.0.51", "@ai-sdk/provider": "^3.0.10", "@ai-sdk/provider-utils": "^4.0.30" }, "peerDependencies": { "ai": "^6.0.90" } }, "sha512-w3OHkuzzKZ3r2TOxER6myBYzZJNoDqol+DUHu3NnfBN/GETnUVxecZJab0CHQQ8GZc0jjzpFymepjcLDPS4SQg=="],
 
     "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
@@ -6010,80 +5905,14 @@
 
     "@actions/http-client/undici": ["undici@6.28.0", "", {}, "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA=="],
 
-    "@ai-sdk/amazon-bedrock/@ai-sdk/anthropic": ["@ai-sdk/anthropic@3.0.81", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-B1JDd9Ugq9R5AgIaW3674lhGCMMYJcPUxnrZh8fzbGojgg4QvHFRv6eZahGQAUsmGHbcf74G9bdSBDLWQGY2GA=="],
-
-    "@ai-sdk/amazon-bedrock/@ai-sdk/openai": ["@ai-sdk/openai@3.0.67", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-oAiGC9eWG7IgtdsdS74bOCnAAHarAfTJhWN9x5INwnWPekL802AvF+0I5DvLzIF1MIRmNw4N8mPSL/GUVbX9Mw=="],
-
-    "@ai-sdk/amazon-bedrock/@ai-sdk/provider": ["@ai-sdk/provider@3.0.10", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-Q3BZ27qfpYqnCYGvE3vt+Qi6LGOF9R5Nmzn+9JoM1lCRsD9mYaIhfJLkSunN48nfGXJ6n+XNV0J/XVpqGQl7Dw=="],
-
-    "@ai-sdk/amazon-bedrock/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.27", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ubkAJ+xODouwtmN1tYlvTPphH1hPOBfZaEQe8U7skGvFAnIRs9PPpsq57bC2+Ky/MB4yzhd6YOsxTAx9sGpazw=="],
-
-    "@ai-sdk/anthropic/@ai-sdk/provider": ["@ai-sdk/provider@3.0.10", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-Q3BZ27qfpYqnCYGvE3vt+Qi6LGOF9R5Nmzn+9JoM1lCRsD9mYaIhfJLkSunN48nfGXJ6n+XNV0J/XVpqGQl7Dw=="],
-
-    "@ai-sdk/anthropic/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.27", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ubkAJ+xODouwtmN1tYlvTPphH1hPOBfZaEQe8U7skGvFAnIRs9PPpsq57bC2+Ky/MB4yzhd6YOsxTAx9sGpazw=="],
-
-    "@ai-sdk/azure/@ai-sdk/provider": ["@ai-sdk/provider@3.0.14", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-5X1k57JBJ4H7H1QjX7CnJYAB1I19r/trVZTMcSms7/kLNZ8RaU4Nt2agcwZzv82Hfx6Q7/TOLU7agAKeFfc8cA=="],
-
-    "@ai-sdk/azure/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.38", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-/HHGmtKllqjg1OLc023v9w9kK3laW7Z6TzfZukYQWCsGBbzB9p60zTvvpXFVcs44NZBVXL3viOa1HRKUbeee8g=="],
-
-    "@ai-sdk/cerebras/@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.37", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-+POSFVcgiu47BK64dhsI6OpcDC0/VAE2ZSaXdXGNNhpC/ava++uSRJYks0k2bpfY0wwCTgpAWZsXn/dG2Yppiw=="],
-
-    "@ai-sdk/cerebras/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
-
     "@ai-sdk/cohere/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
 
-    "@ai-sdk/deepgram/@ai-sdk/provider": ["@ai-sdk/provider@3.0.15", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-XeZW1CcDF2GMbH4wejW6xBRI2QCOgnkVYUnxoeDadB1mf85riL2bMUeDoh+6gJ/r4mjNfzUPW8OjLjvwTP0u1Q=="],
-
-    "@ai-sdk/deepgram/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8", "undici": "^6.28.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-tEtld97plCFiYevsJuOkGkeuhQndeMWFBVrJS4AjnbD5AqrNSXRCe0p+BZ3Cju/sxDeeZ9ym3q9YUV8fASA7aQ=="],
-
-    "@ai-sdk/deepseek/@ai-sdk/provider": ["@ai-sdk/provider@3.0.14", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-5X1k57JBJ4H7H1QjX7CnJYAB1I19r/trVZTMcSms7/kLNZ8RaU4Nt2agcwZzv82Hfx6Q7/TOLU7agAKeFfc8cA=="],
-
-    "@ai-sdk/deepseek/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.38", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-/HHGmtKllqjg1OLc023v9w9kK3laW7Z6TzfZukYQWCsGBbzB9p60zTvvpXFVcs44NZBVXL3viOa1HRKUbeee8g=="],
-
-    "@ai-sdk/elevenlabs/@ai-sdk/provider": ["@ai-sdk/provider@3.0.15", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-XeZW1CcDF2GMbH4wejW6xBRI2QCOgnkVYUnxoeDadB1mf85riL2bMUeDoh+6gJ/r4mjNfzUPW8OjLjvwTP0u1Q=="],
-
-    "@ai-sdk/elevenlabs/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8", "undici": "^6.28.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-tEtld97plCFiYevsJuOkGkeuhQndeMWFBVrJS4AjnbD5AqrNSXRCe0p+BZ3Cju/sxDeeZ9ym3q9YUV8fASA7aQ=="],
-
-    "@ai-sdk/fireworks/@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.68", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@ai-sdk/provider-utils": "4.0.46" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-JiWi/Av2R+SsiGo8rv3b0yWWr3uZH+ll4ky8AcQUUGWzKcMxotQvy3oOoSR4QY34OJ4aLtctHhhzxxEMWSkfIw=="],
-
-    "@ai-sdk/fireworks/@ai-sdk/provider": ["@ai-sdk/provider@3.0.15", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-XeZW1CcDF2GMbH4wejW6xBRI2QCOgnkVYUnxoeDadB1mf85riL2bMUeDoh+6gJ/r4mjNfzUPW8OjLjvwTP0u1Q=="],
-
-    "@ai-sdk/fireworks/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8", "undici": "^6.28.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-tEtld97plCFiYevsJuOkGkeuhQndeMWFBVrJS4AjnbD5AqrNSXRCe0p+BZ3Cju/sxDeeZ9ym3q9YUV8fASA7aQ=="],
-
-    "@ai-sdk/google/@ai-sdk/provider": ["@ai-sdk/provider@3.0.10", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-Q3BZ27qfpYqnCYGvE3vt+Qi6LGOF9R5Nmzn+9JoM1lCRsD9mYaIhfJLkSunN48nfGXJ6n+XNV0J/XVpqGQl7Dw=="],
-
-    "@ai-sdk/google/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.27", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ubkAJ+xODouwtmN1tYlvTPphH1hPOBfZaEQe8U7skGvFAnIRs9PPpsq57bC2+Ky/MB4yzhd6YOsxTAx9sGpazw=="],
-
-    "@ai-sdk/google-vertex/@ai-sdk/anthropic": ["@ai-sdk/anthropic@3.0.77", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ML8C2M1YvPA1ulEx4TiyF0k1xvC2ikEiPBIC1PPQ0a5xELUGrO2lAaEzsTEoJ+eCeDd8PSBuFJjs+r+9yIwQXA=="],
-
-    "@ai-sdk/google-vertex/@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.47", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.27" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-Enm5UlL0zUCrW3792opk5h7hRWxZOZzDe6eQYVFqX9LUOGGCe1h8MZWAGim765nwzgnjlpeYOsuzZmLtRsTPlg=="],
-
-    "@ai-sdk/google-vertex/@ai-sdk/provider": ["@ai-sdk/provider@3.0.10", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-Q3BZ27qfpYqnCYGvE3vt+Qi6LGOF9R5Nmzn+9JoM1lCRsD9mYaIhfJLkSunN48nfGXJ6n+XNV0J/XVpqGQl7Dw=="],
-
-    "@ai-sdk/google-vertex/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.27", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ubkAJ+xODouwtmN1tYlvTPphH1hPOBfZaEQe8U7skGvFAnIRs9PPpsq57bC2+Ky/MB4yzhd6YOsxTAx9sGpazw=="],
-
-    "@ai-sdk/groq/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
-
-    "@ai-sdk/mistral/@ai-sdk/provider": ["@ai-sdk/provider@3.0.14", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-5X1k57JBJ4H7H1QjX7CnJYAB1I19r/trVZTMcSms7/kLNZ8RaU4Nt2agcwZzv82Hfx6Q7/TOLU7agAKeFfc8cA=="],
-
-    "@ai-sdk/mistral/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.40", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-OL5IrpUm9Y8Dwy+w/vvFwPotS6m52O9W0op2oXgXdCROMJIBalBI0oro6OIBYkPxvm5Xg02GSkoQN25RlR0bnw=="],
-
-    "@ai-sdk/openai/@ai-sdk/provider": ["@ai-sdk/provider@3.0.14", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-5X1k57JBJ4H7H1QjX7CnJYAB1I19r/trVZTMcSms7/kLNZ8RaU4Nt2agcwZzv82Hfx6Q7/TOLU7agAKeFfc8cA=="],
-
-    "@ai-sdk/openai/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.38", "", { "dependencies": { "@ai-sdk/provider": "3.0.14", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-/HHGmtKllqjg1OLc023v9w9kK3laW7Z6TzfZukYQWCsGBbzB9p60zTvvpXFVcs44NZBVXL3viOa1HRKUbeee8g=="],
-
     "@ai-sdk/perplexity/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
 
     "@ai-sdk/vercel/@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.37", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-+POSFVcgiu47BK64dhsI6OpcDC0/VAE2ZSaXdXGNNhpC/ava++uSRJYks0k2bpfY0wwCTgpAWZsXn/dG2Yppiw=="],
 
     "@ai-sdk/vercel/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
 
-    "@ai-sdk/xai/@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.69", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@ai-sdk/provider-utils": "4.0.46" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-C99M0T0SpRkcCClmJxbQkpSqGmxLfh3NhTsNF3aNaUQZZ7oXN5sPWi9LGs49X5Q/r9FWxBYeZARXs15xxtGIig=="],
-
-    "@ai-sdk/xai/@ai-sdk/provider": ["@ai-sdk/provider@3.0.15", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-XeZW1CcDF2GMbH4wejW6xBRI2QCOgnkVYUnxoeDadB1mf85riL2bMUeDoh+6gJ/r4mjNfzUPW8OjLjvwTP0u1Q=="],
-
-    "@ai-sdk/xai/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "3.0.15", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8", "undici": "^6.28.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-tEtld97plCFiYevsJuOkGkeuhQndeMWFBVrJS4AjnbD5AqrNSXRCe0p+BZ3Cju/sxDeeZ9ym3q9YUV8fASA7aQ=="],
-
     "@astrojs/cloudflare/@cloudflare/vite-plugin": ["@cloudflare/vite-plugin@1.52.1", "", { "dependencies": { "@cloudflare/unenv-preset": "2.16.1", "miniflare": "5.20260811.1-alpha", "unenv": "2.0.0-rc.24", "workerd": "1.20260811.1", "wrangler": "4.123.0", "ws": "8.21.0" }, "peerDependencies": { "vite": "^6.1.0 || ^7.0.0 || ^8.0.0" }, "bin": { "cf-vite": "bin/cf-vite" } }, "sha512-O2IkD8E03qsUxNBdDRfDI9JPl25XIPt+76WJf8tgm206c34jYk8nn12ylBiOI/6NA8XUFhLjRTF1BGY+kVylXw=="],
 
     "@astrojs/cloudflare/wrangler": ["wrangler@4.123.0", "", { "dependencies": { "@cloudflare/kv-asset-handler": "0.5.0", "@cloudflare/unenv-preset": "2.16.1", "blake3-wasm": "2.1.5", "esbuild": "0.28.1", "miniflare": "5.20260811.1-alpha", "path-to-regexp": "6.3.0", "unenv": "2.0.0-rc.24", "workerd": "1.20260811.1" }, "optionalDependencies": { "fsevents": "2.3.3" }, "peerDependencies": { "@cloudflare/workers-types": "^5.20260811.1" }, "optionalPeers": ["@cloudflare/workers-types"], "bin": { "wrangler": "bin/wrangler.js", "wrangler2": "bin/wrangler.js", "cf-wrangler": "bin/cf-wrangler.js" } }, "sha512-VXo2I1oa0x9aGAKIFPRSQPqTh0RBY5Ktl44YOhNmsJQFUdJKDA2vVTU6Xj+FC2koll6orJqWZN8jbXVIk9O67Q=="],
@@ -6304,9 +6133,13 @@
 
     "@mdx-js/mdx/acorn": ["acorn@8.18.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ=="],
 
-    "@modelcontextprotocol/sdk/hono": ["hono@4.13.3", "", {}, "sha512-r8AO2mYHoLxSHkgafNeC/BXyb2vWRxD3jem4Ts+ptav8oTG5FIRifAjuJEmZI4bSvvc2ns0GxmIYiZnHqN3mMw=="],
+    "@modelcontextprotocol/client/jose": ["jose@6.2.9", "", {}, "sha512-XrchZOFZUl/T3vTwRe8XK+cJrGtMF4th1ARnDfwbBXFKThGhlsxEE4Zu03AD/bjJSt/9jT/mxrOCkJWOg77aPA=="],
 
-    "@modelcontextprotocol/sdk/jose": ["jose@6.2.9", "", {}, "sha512-XrchZOFZUl/T3vTwRe8XK+cJrGtMF4th1ARnDfwbBXFKThGhlsxEE4Zu03AD/bjJSt/9jT/mxrOCkJWOg77aPA=="],
+    "@modelcontextprotocol/client/zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
+
+    "@modelcontextprotocol/core/zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
+
+    "@modelcontextprotocol/server/zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
 
     "@npmcli/arborist/hosted-git-info": ["hosted-git-info@9.0.3", "", { "dependencies": { "lru-cache": "^11.1.0" } }, "sha512-Hc+ghLoSt6QaYZUv0WBiIvmMDZuZZ7oaDvdH8MbfOO4lOsxdXLEvuC6ePoGs9H1X9oCLyq6+NVN0MKqD+ydxyg=="],
 
@@ -6592,8 +6425,6 @@
 
     "babel-plugin-polyfill-corejs2/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
 
-    "body-parser/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "boxen/chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
 
     "builder-util/js-yaml": ["js-yaml@4.3.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ=="],
@@ -6672,8 +6503,6 @@
 
     "esbuild-plugin-copy/chokidar": ["chokidar@3.6.0", "", { "dependencies": { "anymatch": "~3.1.2", "braces": "~3.0.2", "glob-parent": "~5.1.2", "is-binary-path": "~2.1.0", "is-glob": "~4.0.1", "normalize-path": "~3.0.0", "readdirp": "~3.6.0" }, "optionalDependencies": { "fsevents": "~2.3.2" } }, "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw=="],
 
-    "express/cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
-
     "fetch-blob/web-streams-polyfill": ["web-streams-polyfill@3.3.3", "", {}, "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw=="],
 
     "ffi-rs/@yuuang/ffi-rs-darwin-arm64": ["@yuuang/ffi-rs-darwin-arm64@1.3.7", "", { "os": "darwin", "cpu": "arm64" }, "sha512-OueBlUFBT9IwD9pQnoYs0UszRBEySskfrEPXXfvKfGjL/DXnfn6kUheQ3oIP6sSmshVGNQUwrTCPo6feAa4QjA=="],
@@ -6808,8 +6637,6 @@
 
     "roarr/sprintf-js": ["sprintf-js@1.1.3", "", {}, "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA=="],
 
-    "router/path-to-regexp": ["path-to-regexp@8.4.2", "", {}, "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA=="],
-
     "safe-array-concat/isarray": ["isarray@2.0.5", "", {}, "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw=="],
 
     "safe-push-apply/isarray": ["isarray@2.0.5", "", {}, "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw=="],
@@ -6864,8 +6691,6 @@
 
     "tw-to-css/tailwindcss": ["tailwindcss@3.3.2", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "arg": "^5.0.2", "chokidar": "^3.5.3", "didyoumean": "^1.2.2", "dlv": "^1.1.3", "fast-glob": "^3.2.12", "glob-parent": "^6.0.2", "is-glob": "^4.0.3", "jiti": "^1.18.2", "lilconfig": "^2.1.0", "micromatch": "^4.0.5", "normalize-path": "^3.0.0", "object-hash": "^3.0.0", "picocolors": "^1.0.0", "postcss": "^8.4.23", "postcss-import": "^15.1.0", "postcss-js": "^4.0.1", "postcss-load-config": "^4.0.1", "postcss-nested": "^6.0.1", "postcss-selector-parser": "^6.0.11", "postcss-value-parser": "^4.2.0", "resolve": "^1.22.2", "sucrase": "^3.32.0" }, "bin": { "tailwind": "lib/cli.js", "tailwindcss": "lib/cli.js" } }, "sha512-9jPkMiIBXvPc2KywkraqsUfbfj+dHDb+JPWtSJa9MLFdrPyazI7q6WX2sUrm7R9eVR7qqv3Pas7EvQFzxKnI6w=="],
 
-    "type-is/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "unplugin/acorn": ["acorn@8.18.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ=="],
 
     "unused-filename/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
@@ -6936,14 +6761,6 @@
 
     "@actions/github/@octokit/plugin-rest-endpoint-methods/@octokit/types": ["@octokit/types@12.6.0", "", { "dependencies": { "@octokit/openapi-types": "^20.0.0" } }, "sha512-1rhSOfRa6H9w4YwK0yrf5faDaDTb+yLyBUKOCV4xtCDB5VmIPqd/v9yr9o6SAzOAlRxMiRiCic6JVM1/kunVkw=="],
 
-    "@ai-sdk/deepgram/@ai-sdk/provider-utils/undici": ["undici@6.28.0", "", {}, "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA=="],
-
-    "@ai-sdk/elevenlabs/@ai-sdk/provider-utils/undici": ["undici@6.28.0", "", {}, "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA=="],
-
-    "@ai-sdk/fireworks/@ai-sdk/provider-utils/undici": ["undici@6.28.0", "", {}, "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA=="],
-
-    "@ai-sdk/xai/@ai-sdk/provider-utils/undici": ["undici@6.28.0", "", {}, "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA=="],
-
     "@astrojs/cloudflare/@cloudflare/vite-plugin/@cloudflare/unenv-preset": ["@cloudflare/unenv-preset@2.16.1", "", { "peerDependencies": { "unenv": "2.0.0-rc.24", "workerd": ">1.20260305.0 <2.0.0-0" }, "optionalPeers": ["workerd"] }, "sha512-ECxObrMfyTl5bhQf/lZCXwo5G6xX9IAUo+nDMKK4SZ8m4Jvvxp52vilxyySSWh2YTZz8+HQ07qGH/2rEom1vDw=="],
 
     "@astrojs/cloudflare/@cloudflare/vite-plugin/miniflare": ["miniflare@5.20260811.1-alpha", "", { "dependencies": { "@cspotcode/source-map-support": "0.8.1", "sharp": "0.35.2", "undici": "7.29.0", "workerd": "1.20260811.1", "ws": "8.21.0", "youch": "4.1.0-beta.10" } }, "sha512-DtOG0BeanIxs2sH0smFvExZD89cBQwGckbHiFkRJrrNAUu3NGClZkUxqu+zy7HYfKBAgq935EMY49vIPm3JVdA=="],
@@ -7202,32 +7019,24 @@
 
     "@octokit/auth-app/@octokit/request/@octokit/types": ["@octokit/types@17.0.0", "", { "dependencies": { "@octokit/openapi-types": "^28.0.0" } }, "sha512-ByP1v7YL5SMveFPP7+sj0/ZuWCOOg/Chs4NafOMpq6WNIM/hdGY0S7C0TCGDBWu1aGmOxmUIhMx3cO+IdwYZ1Q=="],
 
-    "@octokit/auth-app/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/auth-app/@octokit/request-error/@octokit/types": ["@octokit/types@17.0.0", "", { "dependencies": { "@octokit/openapi-types": "^28.0.0" } }, "sha512-ByP1v7YL5SMveFPP7+sj0/ZuWCOOg/Chs4NafOMpq6WNIM/hdGY0S7C0TCGDBWu1aGmOxmUIhMx3cO+IdwYZ1Q=="],
 
     "@octokit/auth-oauth-app/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
     "@octokit/auth-oauth-app/@octokit/request/@octokit/request-error": ["@octokit/request-error@7.1.1", "", { "dependencies": { "@octokit/types": "^17.0.0" } }, "sha512-+eaY7G2VVpSf2pc5Gn1+mph837V/d/TYTJAgWL9Tb0ogGYcpN3IlAVFgjL+Vv93F/sevrxkvsYCedtpLdcFLzA=="],
 
-    "@octokit/auth-oauth-app/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/auth-oauth-app/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@octokit/auth-oauth-device/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
     "@octokit/auth-oauth-device/@octokit/request/@octokit/request-error": ["@octokit/request-error@7.1.1", "", { "dependencies": { "@octokit/types": "^17.0.0" } }, "sha512-+eaY7G2VVpSf2pc5Gn1+mph837V/d/TYTJAgWL9Tb0ogGYcpN3IlAVFgjL+Vv93F/sevrxkvsYCedtpLdcFLzA=="],
 
-    "@octokit/auth-oauth-device/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/auth-oauth-device/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@octokit/auth-oauth-user/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
     "@octokit/auth-oauth-user/@octokit/request/@octokit/request-error": ["@octokit/request-error@7.1.1", "", { "dependencies": { "@octokit/types": "^17.0.0" } }, "sha512-+eaY7G2VVpSf2pc5Gn1+mph837V/d/TYTJAgWL9Tb0ogGYcpN3IlAVFgjL+Vv93F/sevrxkvsYCedtpLdcFLzA=="],
 
-    "@octokit/auth-oauth-user/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/auth-oauth-user/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@octokit/core/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@24.2.0", "", {}, "sha512-9sIH3nSUttelJSXUrmGzl7QUBFul0/mB8HRYl3fOlgHbIWG+WnYDXU3v/2zMtAvuzZ/ed00Ei6on975FhBfzrg=="],
@@ -7238,8 +7047,6 @@
 
     "@octokit/oauth-methods/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
-    "@octokit/oauth-methods/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/oauth-methods/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@octokit/plugin-paginate-rest/@octokit/core/@octokit/auth-token": ["@octokit/auth-token@6.0.0", "", {}, "sha512-P4YJBPdPSpWTQ1NU4XYdvHvXJJDxM6YwpS0FZHRgP7YFkdVxsWcpWGy/NVqlAA7PcPCnMacXlRm1y2PFZRWL/w=="],
@@ -8054,20 +7861,14 @@
 
     "@octokit/plugin-paginate-rest/@octokit/core/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
-    "@octokit/plugin-paginate-rest/@octokit/core/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/plugin-paginate-rest/@octokit/core/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@octokit/plugin-rest-endpoint-methods/@octokit/core/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
-    "@octokit/plugin-rest-endpoint-methods/@octokit/core/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/plugin-rest-endpoint-methods/@octokit/core/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@octokit/rest/@octokit/core/@octokit/request/@octokit/endpoint": ["@octokit/endpoint@11.0.4", "", { "dependencies": { "@octokit/types": "^17.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-f1cOWoHPmxryJFknxbtDdjODWfV8A9tc8Aae6ermXPNgHFZ/x91AtHIz4gicEjL8hkJiip+u21QHJORfBv/qiA=="],
 
-    "@octokit/rest/@octokit/core/@octokit/request/content-type": ["content-type@2.1.0", "", {}, "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag=="],
-
     "@octokit/rest/@octokit/core/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="],
 
     "@opencode/enterprise/@tailwindcss/vite/@tailwindcss/node/lightningcss": ["lightningcss@1.30.1", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-darwin-arm64": "1.30.1", "lightningcss-darwin-x64": "1.30.1", "lightningcss-freebsd-x64": "1.30.1", "lightningcss-linux-arm-gnueabihf": "1.30.1", "lightningcss-linux-arm64-gnu": "1.30.1", "lightningcss-linux-arm64-musl": "1.30.1", "lightningcss-linux-x64-gnu": "1.30.1", "lightningcss-linux-x64-musl": "1.30.1", "lightningcss-win32-arm64-msvc": "1.30.1", "lightningcss-win32-x64-msvc": "1.30.1" } }, "sha512-xi6IyHML+c9+Q3W0S4fCQJOym42pyurFiJUHEcEyHS0CeKzia4yZDEsLlqOFykxOdHpNy0NmvVO31vcSqAxJCg=="],

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,46 @@ 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
+"%~dp0opencode.exe" %*
+exit /b %errorlevel%
+EOF
+        return
+    fi
+    cat > "$INSTALL_DIR/opencode2" <<'EOF'
+#!/bin/sh
+exec "$(dirname "$0")/opencode" "$@"
+EOF
+    chmod 755 "$INSTALL_DIR/opencode2"
 }
 
 if [ -n "$binary_path" ]; then
@@ -357,6 +384,7 @@ else
     check_version
     download_and_install
 fi
+install_legacy_shim
 
 
 add_to_path() {
@@ -453,7 +481,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 ""

nix/desktop.nix

@@ -90,7 +90,7 @@ stdenv.mkDerivation (finalAttrs: {
     export OPENCODE_CLI_DIST="$TMPDIR/desktop-cli"
     cli_package=$(bun -e 'import { getCurrentCli } from "./scripts/utils.ts"; console.log(getCurrentCli().package.replace("@opencode/", ""))')
     mkdir -p "$OPENCODE_CLI_DIST/$cli_package/bin"
-    cp ${lib.getExe opencode} "$OPENCODE_CLI_DIST/$cli_package/bin/opencode2"
+    cp ${lib.getExe opencode} "$OPENCODE_CLI_DIST/$cli_package/bin/opencode"
 
     bun run build
     npx electron-builder --dir \

nix/hashes.json

@@ -1,8 +1,8 @@
 {
   "nodeModules": {
-    "x86_64-linux": "sha256-yzCk746pospz8EVakHRcDhYJkhGYGSt9dHOPbzO4OYo=",
-    "aarch64-linux": "sha256-MFJVLos4v2r9jazmmr3ldVCJKLrO+Qp/BpGpyM/1lf8=",
-    "aarch64-darwin": "sha256-k8r/HVSgdRSTlJ1lI7EebqbxeA3AElnaw1sDYOPEdQw=",
-    "x86_64-darwin": "sha256-ACJdJfz12xLBQvWIkbuve86znSoGJ2PLDQbgh0cT6/g="
+    "x86_64-linux": "sha256-E5T4o3wNivOg8q4wRV7yE4CUNaUq4QNPxZsnvLaGUcg=",
+    "aarch64-linux": "sha256-xQQi7LgxInZQVCznASfa0Pm+cNGBo5j4Tfp0E/bKnNw=",
+    "aarch64-darwin": "sha256-qxb371dCf7WG09VvQE+HZ/x3EURpFIr11bdnQwGTHhw=",
+    "x86_64-darwin": "sha256-xi1qiYr41hzbgAQl+I3xdtnkiPx2SIcA/0OMpN78qXw="
   }
 }

nix/opencode.nix

@@ -8,6 +8,7 @@
   makeBinaryWrapper,
   models-dev,
   ripgrep,
+  wayland,
   installShellFiles,
   versionCheckHook,
   writableTmpDirAsHomeHook,
@@ -62,9 +63,10 @@ stdenvNoCC.mkDerivation (finalAttrs: {
   installPhase = ''
     runHook preInstall
 
-    install -Dm755 dist/cli-*/bin/opencode2 $out/bin/opencode2
+    install -Dm755 dist/cli-*/bin/opencode $out/bin/opencode
 
-    wrapProgram $out/bin/opencode2 \
+    # OpenTUI dlopens Wayland for clipboard images.
+    wrapProgram $out/bin/opencode \
       --prefix PATH : ${
         lib.makeBinPath (
           [
@@ -73,13 +75,21 @@ stdenvNoCC.mkDerivation (finalAttrs: {
           # bun runs sysctl to detect if running on rosetta2
           ++ lib.optional stdenvNoCC.hostPlatform.isDarwin sysctl
         )
-      }
+      } ${lib.optionalString stdenvNoCC.hostPlatform.isLinux ''
+        --prefix LD_LIBRARY_PATH : ${lib.makeLibraryPath [ wayland ]}
+      ''}
+
+    ln -s opencode $out/bin/opencode2
 
     runHook postInstall
   '';
 
   postInstall = lib.optionalString (stdenvNoCC.buildPlatform.canExecute stdenvNoCC.hostPlatform) ''
     # trick yargs into also generating zsh completions
+    installShellCompletion --cmd opencode \
+      --bash <($out/bin/opencode completion) \
+      --zsh <(SHELL=/bin/zsh $out/bin/opencode completion)
+
     installShellCompletion --cmd opencode2 \
       --bash <($out/bin/opencode2 completion) \
       --zsh <(SHELL=/bin/zsh $out/bin/opencode2 completion)
@@ -101,7 +111,7 @@ stdenvNoCC.mkDerivation (finalAttrs: {
     description = "The open source coding agent";
     homepage = "https://opencode.ai";
     license = lib.licenses.mit;
-    mainProgram = "opencode2";
+    mainProgram = "opencode";
     inherit (node_modules.meta) platforms;
   };
 })

package.json

@@ -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.3",
   "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",
@@ -24,6 +24,7 @@
     "test:lint-rules": "ast-grep test -c script/ast-grep/sgconfig.yml",
     "test:effect-simplification-rules": "ast-grep test -c script/ast-grep/effect-simplifications/sgconfig.yml",
     "typecheck": "bun turbo typecheck --concurrency=3",
+    "check": "bun run lint && bun run typecheck",
     "typecheck:profile": "bun script/profile-typecheck.ts",
     "typecheck:profile:packages": "bun script/profile-typecheck-packages.ts",
     "upgrade-opentui": "bun run script/upgrade-opentui.ts",
@@ -115,6 +116,7 @@
   "devDependencies": {
     "@actions/artifact": "5.0.1",
     "@ast-grep/cli": "0.44.0",
+    "@opencode/client": "workspace:*",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
     "@tsconfig/bun": "catalog:",
@@ -174,10 +176,10 @@
     "pacote@21.5.0": "patches/pacote@21.5.0.patch",
     "@ai-sdk/google@3.0.73": "patches/@ai-sdk%2Fgoogle@3.0.73.patch",
     "@pierre/trees@1.0.0-beta.4": "patches/@pierre%2Ftrees@1.0.0-beta.4.patch",
-    "@modelcontextprotocol/sdk@1.29.0": "patches/@modelcontextprotocol%2Fsdk@1.29.0.patch",
     "@tanstack/virtual-core@3.17.8": "patches/@tanstack%2Fvirtual-core@3.17.8.patch",
     "@ff-labs/fff-bun@0.10.5": "patches/@ff-labs%2Ffff-bun@0.10.5.patch",
     "ghostty-web@github:anomalyco/ghostty-web#83c0a07": "patches/ghostty-web@0.3.0.patch",
-    "vite@8.2.2": "patches/vite@8.2.2.patch"
+    "vite@8.2.2": "patches/vite@8.2.2.patch",
+    "@modelcontextprotocol/client@2.0.0": "patches/@modelcontextprotocol%2Fclient@2.0.0.patch"
   }
 }

packages/ai/AGENTS.md

@@ -10,7 +10,15 @@
 
 ## Conventions
 
-Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, and `LLM.generateObject`. Use `LLMRequest.update(...)` when deriving canonical request data; do not add a duplicate `LLM.updateRequest(...)` path. Two ways to construct the same thing is one too many.
+Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Message.media(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, and `LLM.generateObject`. Use `LLMRequest.update(...)` when deriving canonical request data; do not add a duplicate `LLM.updateRequest(...)` path. Two ways to construct the same thing is one too many.
+
+Modality namespaces mirror `LLM` exactly: `Image.request`, `Image.generate`, `Image.stream` (later `Video`, `Speech`, `Transcription`). Common request fields (`images`, `mask`, `n`, `size`, `aspectRatio`, `seed`, `format`) lower natively or fail with a typed `AIError`; provider-native controls always live under `providerOptions`, never under a modality-specific `options` key.
+
+Media payloads are always `Media.Asset` (`src/media.ts`). Construct them with `Media.bytes`, `Media.base64`, `Media.url`, `Media.ref`, `Media.fromDataUrl`, or `Media.file`; never introduce a parallel `data: string | Uint8Array` shape. `MediaPart.media`, `ImageRequest.images`/`mask`, `ImageResponse.images`, and the `media` `LLMEvent` all share it. Protocols branch on `asset.source.type` and `asset.kind` and use `ProviderShared.inlineMedia` / `requireInlineMedia` / `mediaUrl` / `MediaInput.refID` rather than re-deriving base64 or URL handling.
+
+`schema/messages.ts → media.ts → route/executor-service.ts` is an accepted runtime dependency from the schema layer on the executor service tag: `Media.Asset.bytes()` must be able to download `url` sources, and the tag lives in that leaf module precisely so the schema barrel never imports the executor implementation (which imports the schema barrel back). Do not move the tag into `route/executor.ts` or import `route/executor.ts` from `src/schema/*` or `src/media.ts`.
+
+Nothing in `src/*` except `src/promise.ts` may know about Promises. `@opencode/ai/promise` (`AI.make({ layer? })`, default `ai`) is the single Promise/`AsyncIterable` surface for LLM and media; it runs the Effect APIs in one `ManagedRuntime` and rethrows `AIError` unchanged.
 
 - Keep provider-defined string enums forward-compatible. Expose known values for autocomplete while accepting future values with `Known | (string & {})`; use `Schema.String` at runtime unless rejecting unknown values is required for correctness.
 - Order reasoning-effort values from lowest to highest: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Provider-specific subsets follow the same relative order in types, schemas, option lists, and tests.
@@ -86,6 +94,10 @@ The four-axis decomposition is the reason DeepSeek, TogetherAI, Cerebras, Basete
 
 When a provider supports multiple physical transports, selection remains execution policy below its semantic route. `OpenResponsesChannel.transport(...)` owns the provider-neutral Responses WebSocket concept: it prepares one final request, executes HTTP by default, strips WebSocket-disallowed fields, and passes a generic channel exchange to a per-call `WebSocketChannelExecutor` when supplied. Provider-specific Responses routes opt in with handshake and connection-age policy. `Route.streamPrepared` owns decoding and acknowledges channel completion only after successful full consumption.
 
+### Media Routes
+
+Media does not fit the SSE-frames-to-event-state-machine LLM route. `MediaRoute.make(...)` (`src/route/media.ts`) composes a `MediaProtocol` kind with `Endpoint` and `Auth` and owns the transport plumbing: `http` option merging, URL/query rendering, auth headers, JSON vs multipart encoding, and handing the response back to the protocol. `MediaProtocol.inline` (`src/route/media-protocol.ts`) is `body.from(request)` plus `response.decode(response, context)`; use `MediaProtocol.decodeJson` / `text` / `bytes` so decode failures retain the raw body and HTTP context. `MediaProtocol.JobProtocol` is the queued shape and `Job` (`src/job.ts`) is the provider-neutral handle over a `JobRoute` (`status`, `result`, `cancel`, `pollHint`); the first video route implements it. Image protocol files follow the same section order as LLM protocols and declare unsupported common fields once through `MediaInput.rejectUnsupported`.
+
 ### URL Construction
 
 `Endpoint` owns `{ baseURL, path, query }`. Each protocol route includes a canonical endpoint when the provider has one (e.g. `https://api.openai.com/v1`); provider helpers override endpoint fields by configuring the route before selecting a model. Generic OpenAI-compatible routes have no canonical URL and require configuration before execution.
@@ -94,10 +106,11 @@ For providers where the URL is derived from typed inputs (Azure resource name, B
 
 ### Provider Facades
 
-Provider-facing APIs are configured facades over route values. Endpoint/auth/resource/API-version setup happens before model selection, and model selectors accept only a model or deployment id:
+Provider-facing APIs are configured facades over route values. Endpoint/auth/resource/API-version setup happens before model selection, and model selectors accept only a model or deployment id. Every facade is wrapped in `ModelRef.facade(...)`, which makes it callable: `openai("gpt-4o-mini")` returns a `ModelRef` with lazy per-modality routes derived from the facade's own selectors (`model` → `llm`, `image` → `image`). `LLM.request` and `Image.request` resolve their route from the ref at request time, so one value names a model for every modality while named selectors stay the single source of truth:
 
 ```ts
 const openai = OpenAI.configure({ apiKey, baseURL })
+const ref = openai("gpt-4o-mini") // ModelRef: LLM.request → .responses, Image.request → .image
 const model = openai.responses("gpt-4o-mini")
 
 const azure = Azure.configure({ resourceName, apiKey, apiVersion: "v1" })
@@ -122,13 +135,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",
 })
 ```
 
@@ -165,6 +179,10 @@ Native chronological system messages are route/model-specific. Open Responses lo
 
 The wrapped-user fallback preserves ordering while visibly lowering authority. Never silently pass a raw chronological `role: "system"` through a route that might reject it. Do not insert raw retrieved documents, tool output, or web content into privileged chronological system updates; keep untrusted content in ordinary user/tool channels.
 
+### Effort Updates
+
+`Message.effort({ effort, previous })` is a chronological "reasoning effort changed here" marker (`undefined` means the model default). Changing a top-level effort invalidates the whole provider prompt cache, so protocols with a native per-message update (`Protocol.supportsEffortUpdates`) keep the top-level effort at the first marker's `previous` and lower each marker in place: Anthropic Messages emits an empty `role: "system"` message with `output_config.effort` plus the `mid-conversation-output-config-2026-07-01` beta, and OpenAI Responses emits `configuration_update` items. `applyEffortUpdates` runs in `prepareRequest` and strips the markers for every other route, so a protocol without support keeps today's plain top-level behaviour. When the last marker disagrees with the effort the request asks for (reverted or forked history), `resolveEffortUpdates` strips the markers and falls back to a plain top-level change.
+
 ### Tools
 
 Tool loops are represented in common messages and events:

packages/ai/README.md

@@ -8,10 +8,10 @@ import { LLM, LLMClient } from "@opencode/ai"
 import { RequestExecutor } from "@opencode/ai/route"
 import { OpenAI } from "@opencode/ai/providers"
 
-const model = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
 
 const request = LLM.request({
-  model,
+  model: openai("gpt-4o-mini"), // the request namespace picks the route; `.responses(...)` / `.chat(...)` stay explicit
   system: "You are concise.",
   prompt: "Say hello in one short sentence.",
   generation: { maxTokens: 40 },
@@ -29,6 +29,43 @@ await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
 
 Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
 
+The same configured facade names image models. `Image.request` resolves the provider's image route from the ref and
+returns `Media.Asset`s with lazily decoded bytes:
+
+```ts
+import { NodeFileSystem } from "@effect/platform-node"
+import { Image, ImageClient, Media } from "@opencode/ai"
+
+const image = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: openai("gpt-image-2"),
+    prompt: "A robot tending a rooftop garden",
+    size: "1024x1024",
+    providerOptions: { quality: "high" }, // typed per image model
+  })
+  yield* Media.write(response.image, "./garden.png")
+})
+
+// `asset.bytes()` / `Media.write` also need the executor, so merge it into the environment instead of hiding it.
+const imageLayer = ImageClient.layer.pipe(Layer.provideMerge(RequestExecutor.fetchLayer))
+
+await Effect.runPromise(image.pipe(Effect.provide(imageLayer), Effect.provide(NodeFileSystem.layer)))
+```
+
+Prefer promises? `@opencode/ai/promise` exposes the same LLM and image APIs over one managed runtime:
+
+```ts
+import { AI } from "@opencode/ai/promise"
+
+const ai = AI.make()
+const text = await ai.llm.generate({ model: openai("gpt-4o-mini"), prompt: "Say hello." })
+const generated = await ai.image.generate({ model: openai("gpt-image-2"), prompt: "A lighthouse" })
+for await (const event of ai.llm.stream({ model: openai("gpt-4o-mini"), prompt: "Stream hello." })) {
+  // LLMEvent
+}
+await ai.dispose()
+```
+
 ## Alibaba Cloud Model Studio
 
 `Alibaba` provides standard Model Studio inference. Configure a region explicitly, then select
@@ -314,23 +351,25 @@ citations or separate result blocks. Retain `response.message` for either API's
 Use `Image.generate` for one-off generation or editing:
 
 ```ts
-import { Image, ImageInput } from "@opencode/ai"
+import { Image, Media } from "@opencode/ai"
 
 const generation = Image.generate({
-  model: meta.image("muse-image-1.0"),
+  model: meta("muse-image-1.0"),
   prompt: "A flat black square on a white background.",
-  options: { n: 1, reasoningStrength: "low" },
+  n: 1,
+  providerOptions: { reasoningStrength: "low" },
 })
 
 const edit = Image.generate({
-  model: meta.image("muse-image-1.0"),
+  model: meta("muse-image-1.0"),
   prompt: "Make the square purple.",
-  images: [ImageInput.bytes(imageBytes, "image/webp")],
-  options: { outputFormat: "png", reasoningStrength: "low" },
+  images: [Media.bytes(imageBytes, "image/webp")],
+  format: "png",
+  providerOptions: { reasoningStrength: "low" },
 })
 ```
 
-The default image format is WEBP; `outputFormat` also accepts PNG/JPEG and `responseFormat: "url"`
+The default image format is WEBP; `format` also accepts PNG/JPEG and `responseFormat: "url"`
 returns a signed URL. `size` is an aspect-ratio hint. For conversational images, select
 `meta.responses("muse-image-1.0")` with `tools: [Meta.imageGeneration({ reasoningStrength: "low" })]`.
 Generated images are provider-executed tool results with file content. Retain `response.message` to
@@ -341,29 +380,40 @@ Meta Responses is explicitly HTTP/SSE-only and does not use WebSockets, even whe
 
 ## Image generation
 
-Use `Image.generate` with an image model for direct asset generation:
+Use `Image.generate` with an image model for direct asset generation. `Image.request` mirrors `LLM.request`: the
+model is a callable-facade ref (`openai("gpt-image-2")`) or an explicit `.image(...)` model, common fields
+(`images`, `mask`, `n`, `size`, `aspectRatio`, `seed`, `format`) lower natively or fail typed, and
+`providerOptions` is inferred from the selected model:
 
 ```ts
-import { Image, ImageInput } from "@opencode/ai"
+import { Image, Media } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"
 
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
+
 const program = Effect.gen(function* () {
   const response = yield* Image.generate({
-    model: OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).image("gpt-image-2"),
+    model: openai("gpt-image-2"),
     prompt: "A robot tending a rooftop garden",
-    options: {
-      n: 2,
-      size: "1024x1024",
+    n: 2,
+    size: "1024x1024",
+    format: "webp",
+    providerOptions: {
       quality: "high", // inferred from the OpenAI image model
-      outputFormat: "webp",
       future_option: true, // unknown native options pass through unchanged
     },
   })
 
-  return response.images // GeneratedImage[] with owned bytes or a provider URL
+  return response.images // Media.Asset[] with owned bytes or a provider URL
 })
 ```
 
+`Media.Asset` is the one asset type shared by image requests, image responses, LLM messages, and tool results.
+`asset.source` is the serializable `Media.Source` (`bytes`, `base64`, `url`, or `ref`); `asset.bytes()`,
+`asset.base64()`, and `asset.dataUrl()` decode or download lazily and cache; `asset.materialize()` pulls a `url`
+asset into owned bytes before the provider URL expires. Construct assets with `Media.bytes`, `Media.base64`,
+`Media.url`, `Media.ref(provider, id)`, `Media.fromDataUrl`, or `Media.file(path)`.
+
 Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:
 
 ```ts
@@ -373,49 +423,45 @@ const response =
     model,
     prompt: "Combine these product photos into one studio scene",
     images: [
-      ImageInput.bytes(firstBytes, "image/png"),
-      ImageInput.url("https://example.com/second.webp"),
-      ImageInput.file("file_123"),
+      Media.bytes(firstBytes, "image/png"),
+      Media.url("https://example.com/second.webp"),
+      Media.ref("openai", "file_123"),
     ],
-    options,
+    providerOptions,
     http,
   })
 ```
 
-`ImageInput.fileUri(uri, mediaType)` represents provider file URIs such as Gemini Files. Raw strings are not
-accepted as image inputs, avoiding ambiguity between base64, URLs, and provider IDs. Empty or omitted `images`
-uses text-to-image generation; a non-empty array selects the provider's edit behavior without enforcing provider
-image-count limits locally. `images` is the only common image-editing field. OpenAI uses multipart for byte/data-URL
-edits and its JSON reference body for URL or file-ID edits. Its provider-specific `options.mask` accepts an
-`ImageInput` for inpainting:
+`Media.ref(provider, id)` represents provider file handles such as OpenAI file IDs or Gemini Files URIs; routes
+only forward refs that belong to their own provider. Raw strings are not accepted as image inputs, avoiding
+ambiguity between base64, URLs, and provider IDs. Empty or omitted `images` uses text-to-image generation; a
+non-empty array selects the provider's edit behavior without enforcing provider image-count limits locally. OpenAI
+uses multipart for byte/data-URL edits and its JSON reference body for URL or file-ID edits. The common `mask`
+field selects inpainting; routes that cannot honor it fail with `UnsupportedOperation`:
 
 ```ts
 yield *
   Image.generate({
-    model: OpenAI.configure({ apiKey }).image("gpt-image-2"),
+    model: openai("gpt-image-2"),
     prompt,
-    images: [ImageInput.bytes(sourceBytes, "image/png")],
-    options: { mask: ImageInput.bytes(maskBytes, "image/png") },
+    images: [Media.bytes(sourceBytes, "image/png")],
+    mask: Media.bytes(maskBytes, "image/png"),
   })
 ```
 
-The OpenAI adapter extracts this helper value into the edit request's native `mask` field rather than passing the
-tagged `ImageInput` object through as an ordinary option. On multipart requests, `http.body` can override option
-fields but not structural `model`, `prompt`, `image[]`, or `mask` fields, and the transport owns the multipart
-`Content-Type` boundary. For JSON requests, `http.body` remains the final raw-native overlay. Gemini does not fetch
-public HTTP URLs, and hosted Z.ai image generation does not accept image inputs. These cases fail with
-`InvalidRequest` before network I/O.
+On multipart requests, `http.body` can override option fields but not structural `model`, `prompt`, `image[]`,
+or `mask` fields, and the transport owns the multipart `Content-Type` boundary. For JSON requests, `http.body`
+remains the final raw-native overlay. Gemini does not fetch public HTTP URLs, and hosted Z.ai image generation does
+not accept image inputs. These cases fail with a typed `AIError` before network I/O.
 
 Provider-native image options belong to each request. Raw `http.body` fields have final precedence over them:
 
 ```ts
-const model = OpenAI.configure({ apiKey }).image("gpt-image-2")
-
 yield *
   Image.generate({
-    model,
+    model: openai("gpt-image-2"),
     prompt,
-    options: { quality: "medium" },
+    providerOptions: { quality: "medium" },
     http,
   })
 ```
@@ -425,11 +471,11 @@ xAI image models use the same request API with xAI-native controls:
 ```ts
 yield *
   Image.generate({
-    model: XAI.configure({ apiKey }).image("any-model-id"),
+    model: XAI.configure({ apiKey })("any-model-id"),
     prompt,
-    options: {
-      n: 2,
-      aspectRatio: "16:9",
+    n: 2,
+    aspectRatio: "16:9",
+    providerOptions: {
       resolution: "1k",
       responseFormat: "b64_json",
       future_option: true,
@@ -445,12 +491,12 @@ import { Google } from "@opencode/ai/providers"
 
 const googleProgram = Effect.gen(function* () {
   const response = yield* Image.generate({
-    model: Google.configure({ apiKey }).image("any-model-id"),
+    model: Google.configure({ apiKey })("any-model-id"),
     prompt: "A robot tending a rooftop garden",
-    options: {
-      aspectRatio: "16:9",
+    aspectRatio: "16:9",
+    seed: 42,
+    providerOptions: {
       imageSize: "2K",
-      seed: 42,
       thinkingLevel: "HIGH",
       includeThoughts: true,
       futureOption: true,
@@ -472,9 +518,9 @@ Z.ai image models infer open Z.ai-native options from the selected model:
 ```ts
 yield *
   Image.generate({
-    model: ZAI.configure({ apiKey }).image("any-model-id"),
+    model: ZAI.configure({ apiKey })("any-model-id"),
     prompt,
-    options: {
+    providerOptions: {
       quality: "hd",
       userID: "user-123",
       future_option: true,
@@ -484,8 +530,8 @@ yield *
 ```
 
 Z.ai does not include trustworthy MIME metadata for output URLs, so generated images use
-`application/octet-stream`. Output URLs expire after 30 days; download and persist them promptly if they must
-remain available.
+`application/octet-stream` until materialized. Output URLs expire after 30 days; call `asset.materialize()` and
+persist the bytes promptly if they must remain available.
 
 Conversational image generation remains part of the LLM interaction. OpenAI Responses exposes it through its hosted image tool:
 
@@ -503,7 +549,7 @@ const program = Effect.gen(function* () {
 })
 ```
 
-The hosted result is represented as a provider-executed tool call and tool result. Its image is a `file` content item with a data URI, so retaining `response.message` preserves the generated image for continuation.
+The hosted result is represented as a provider-executed tool call and tool result, and the generated image is also emitted as a first-class `media` `LLMEvent` (`response.message` then carries a `media` part). Gemini image-capable models emit the same `media` event for inline image output. Retaining `response.message` preserves the generated image for continuation on both routes.
 
 ## Public API
 
@@ -512,8 +558,12 @@ The hosted result is represented as a provider-executed tool call and tool resul
 - **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
 - **`LanguageModel.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
 - **`LLMEvent.is.*`** — typed guards (`is.textDelta`, `is.toolCall`, `is.finish`, …) for filtering streams.
-- **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
+- **`Image.request` / `Image.generate` / `Image.stream`** — generate images through a provider-neutral image request and response model.
 - **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
+- **`Media`** — the shared asset type (`Media.Asset`, `Media.Source`) and constructors used by messages, tool results, and media requests.
+- **`ModelRef`** — the value returned by calling a configured facade (`openai("gpt-5")`); each request namespace resolves its own route from it.
+- **`Job`** — provider-neutral async job handle (`await`, `refresh`, `cancel`, `events`) used by queued media routes.
+- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm` and `image` as Promise / `AsyncIterable` APIs.
 
 ## Testing
 

packages/ai/docs/media-design.md

@@ -0,0 +1,342 @@
+# Media generation in `@opencode/ai` — public API direction
+
+Status: proposal. Branch `media-support`.
+
+## Goal
+
+`@opencode/ai` becomes the one package you reach for to generate anything: text, images, video, speech, transcripts, and later music and realtime. The LLM surface already exists and is shaped by three constraints: Effect-first, used by OpenCode Core, usable externally. Media has a different priority order: **external DX first**, Effect and Promise as peers, Core as one consumer among many.
+
+The design below is derived from a survey of the raw provider APIs (OpenAI, Gemini/Veo/Imagen, xAI, Stability, BFL, fal, Replicate, Runway, Luma, Kling, MiniMax, ElevenLabs, Deepgram, Cartesia, AssemblyAI, Lyria) and from the Vercel AI SDK v7 (`generateImage`, `generateSpeech`, `transcribe`, `experimental_generateVideo`, `ImageModelV4`/`SpeechModelV4`/`TranscriptionModelV4`/`Experimental_VideoModelV4`).
+
+## What the survey forces
+
+1. **Three execution shapes, everywhere.** Inline sync (OpenAI images, all TTS, Gemini), async job with polling or webhook (every video provider, BFL, fal, Replicate, AssemblyAI), and bidirectional streams (ElevenLabs/Cartesia/Deepgram WS, realtime). Video has no sync provider at all.
+2. **Output is never just bytes.** base64, signed URLs with TTLs from 10 minutes (BFL) to 2 days (Veo), URLs that need auth plus redirect (Veo), separate download endpoints (Sora `/content?variant=`), raw bodies (Stability, TTS). Multi-output is the norm.
+3. **Inputs have roles.** First/last frame, mask, style/subject reference, source video for edit/extend, reference audio, prior generation id, provider-side file handles (`file_id`, `gs://`, `runway://`, `mm_file://`).
+4. **Partial streaming is modality-specific.** Images: a few whole partial frames. Audio: ordered chunks plus timestamp events. Jobs: status/progress/logs. Video: none.
+5. **Usage is a union**: tokens, seconds, characters (often only in headers), credits, compute time.
+6. **Moderation can be partial success** (Veo strips audio but returns video). Deprecations are constant (Sora API shuts down 2026-09-24, Imagen on Gemini API 2026-08-17).
+
+## Where Vercel is weak and we should not be
+
+- No streaming TTS at all.
+- Video job handle is experimental and only `start`/`getStatus`; polling loop is inside `generateVideo` with an injectable `delay`.
+- Unsupported inputs become silent `warnings` arrays, so a request can succeed while dropping your mask.
+- `n` is fanned out into hidden parallel calls (`maxImagesPerCall`), which obscures cost and idempotency.
+- Each modality has its own bespoke result type; the file abstraction is a lazy base64/bytes pair with no URL, expiry, or provider ref.
+- Effect's own `unstable/ai` has no media generation. Nothing in the Effect ecosystem owns this.
+
+## Design principles
+
+- **Same shape as LLM.** `X.request(...)` → Schema class; `X.generate(request)` / `X.stream(request)`; `XClient.Service` + `layer`; typed `AIError`. If you know `LLM`, you know `Video`.
+- **Execution shape is route policy, not API shape.** `Image.generate` returns an image whether the provider is inline or queued. Job control is available uniformly when you want it.
+- **Errors, not warnings.** Unsupported common fields fail at the protocol boundary with a typed `AIError`, as the LLM routes do today. Provider-side partial results (filtered audio, moderated sample) surface as `notices` on the response, never as silent drops.
+- **One asset type in, one asset type out**, shared with LLM messages and tool results.
+- **Typed per-model options**, no hidden fan-out, no implicit retries that spend money.
+- **Promise API is one mechanism for the whole package**, not a media-only wrapper.
+- **The request namespace names the modality; the model does not repeat it.** `Image.request({ model: openai("gpt-image-2") })`, not `openai.image("gpt-image-2")`.
+
+## Public API
+
+### Model selection — `ModelRef`
+
+Today a model value is built as `OpenAI.configure({ apiKey }).responses("gpt-5")` or `.image("gpt-image-2")`: `configure` fixes credentials, endpoint, and defaults; the selector fixes which of the provider's APIs to hit and binds the typed `providerOptions` generic. The selector exists because OpenAI has two LLM APIs. For media that is the exception, and the request namespace already names the modality, so repeating it in the model is ceremony.
+
+A configured facade is callable and returns a `ModelRef`. Each request namespace resolves its own route from the ref.
+
+```ts
+import { OpenAI, Google } from "@opencode/ai/providers"
+
+const openai = OpenAI.configure({ apiKey })      // OpenAI(...) alone uses env auth (OPENAI_API_KEY)
+
+LLM.request({ model: openai("gpt-5"), prompt })                 // → routes.llm   (default: responses)
+Image.request({ model: openai("gpt-image-2"), prompt })         // → routes.image
+Video.request({ model: openai("sora-2"), prompt })              // → routes.video
+Speech.request({ model: openai("gpt-4o-mini-tts"), text })      // → routes.speech
+Transcription.request({ model: openai("gpt-4o-transcribe"), audio })
+
+// Explicit selectors remain only where a provider has two APIs for one modality.
+LLM.request({ model: openai.chat("gpt-4o"), prompt })
+Image.request({ model: google.imagen("imagen-4.0-generate-001"), prompt })   // default is Gemini-native image
+```
+
+Mechanics:
+
+- `ModelRef<Routes>` carries `{ id, provider, routes }` where `Routes = { llm?: Route<…>; image?: ImageRoute<Opts>; video?: VideoRoute<Opts>; speech?: …; transcription?: … }`. Routes are lazy; unused protocols are not constructed.
+- `X.request<M extends XModel | ModelRef<{ x: XRoute<any> }>>` infers `providerOptions` from `M["routes"]["x"]`. Passing a ref whose provider has no `x` route is a compile error. Model-id validity stays a runtime provider error, as today.
+- Explicit selectors (`openai.chat`, `google.imagen`) return the concrete `XModel` directly, exactly as `.responses(...)` does now. `.model(id)` stays as an alias of the callable for LLM compatibility.
+- Provider package entrypoints keep `model(modelID, settings)` and gain the same resolution: `@opencode/ai/providers/openai` `model(...)` returns a ref; `@opencode/ai/providers/openai/responses` returns the concrete LLM model.
+- One default per modality per provider is part of the facade definition (OpenAI image → Images API, Google image → Gemini-native since Imagen on the Gemini API shuts down 2026-08-17).
+
+This applies to LLM in the same pass so the package has one way to name a model.
+
+### `Media` — the asset type
+
+Replaces `MediaPart.data: string | Uint8Array`, `ImageInput`, `GeneratedImage`, and aligns `Tool.FileContent`.
+
+```ts
+import { Media } from "@opencode/ai"
+
+Media.Source =
+  | { type: "bytes";  data: Uint8Array; mediaType: string }
+  | { type: "base64"; data: string;     mediaType: string }
+  | { type: "url";    url: string; mediaType?: string; expiresAt?: number; headers?: Record<string, string> }
+  | { type: "ref";    provider: ProviderID; id: string; mediaType?: string }   // file_id, gs://, runway://, prior generation
+
+class Media.Asset {
+  readonly source: Media.Source
+  readonly mediaType: string                    // always resolved (sniffed when the provider omits it)
+  readonly kind: "image" | "video" | "audio" | "document" | "other"
+  readonly info?: { width?; height?; durationSeconds?; sampleRate?; channels?; encoding?; format? }
+  readonly expiresAt?: number
+  readonly providerMetadata?: ProviderMetadata
+
+  bytes(): Effect<Uint8Array, AIError, RequestExecutor.Service>   // downloads/decodes lazily, cached
+  base64(): Effect<string, AIError, RequestExecutor.Service>
+  dataUrl(): Effect<string, AIError, RequestExecutor.Service>
+  materialize(): Effect<Media.Asset, AIError, RequestExecutor.Service>  // url/ref → bytes, before the URL dies
+}
+
+Media.bytes(data, mediaType?)      Media.base64(data, mediaType?)
+Media.url(url, options?)           Media.ref(provider, id)
+Media.file(path)                   // Bun/Node: reads + sniffs; Effect FileSystem variant for layers
+Media.write(asset, path)           // convenience, uses FileSystem
+```
+
+Raw-PCM outputs (Gemini TTS, Cartesia raw, Deepgram WS) carry `info.encoding/sampleRate/channels` because there is no container header.
+
+### Modality namespaces
+
+Each namespace mirrors `LLM` exactly.
+
+```ts
+import { Image, Video, Speech, Transcription } from "@opencode/ai"
+import { OpenAI, Google, ElevenLabs, Fal } from "@opencode/ai/providers"
+```
+
+#### Image
+
+```ts
+const request = Image.request({
+  model: openai("gpt-image-2"),
+  prompt: "A robot tending a rooftop garden",
+  images: [Media.file("./ref.png")],           // references / edit sources
+  mask: Media.file("./mask.png"),
+  n: 2,
+  size: "1536x1024",                            // or aspectRatio: "3:2"
+  seed: 7,
+  format: "webp",
+  providerOptions: { quality: "high", background: "transparent" },   // typed per model
+})
+
+const response = yield* Image.generate(request)   // ImageResponse
+response.image                                    // Media.Asset (first)
+response.images                                   // Media.Asset[]
+response.usage                                    // Usage union (see below)
+response.notices                                  // moderation / partial-result notices
+
+yield* Image.stream(request)                      // Stream<ImageEvent>
+// ImageEvent: job-queued | job-progress | image-partial { index, image } | image { index, image } | finish { usage }
+```
+
+Editing is not a separate function; `images`/`mask` on the request select the edit path in the route (OpenAI `/images/edits`, Gemini multimodal parts, xAI `/images/edits`). Routes that cannot honor `mask` fail with `Unsupported`.
+
+#### Video
+
+```ts
+const request = Video.request({
+  model: google("veo-3.1-generate-preview"),
+  prompt: "Panning wide shot of a calico kitten sleeping in the sunshine",
+  frames: { first: Media.file("./start.png"), last: Media.file("./end.png") },
+  references: [Media.url("https://…/style.png")],
+  video: Media.ref("openai", "video_123"),      // edit / extend / remix source
+  durationSeconds: 8,
+  aspectRatio: "16:9",
+  resolution: "1080p",
+  audio: true,
+  n: 1,
+  providerOptions: { personGeneration: "dont_allow", negativePrompt: "text, watermark" },
+})
+
+// Simple: wait for it.
+const response = yield* Video.generate(request, { poll: { interval: "10 seconds", timeout: "10 minutes" } })
+response.video                                     // Media.Asset (url with expiresAt, or bytes when the route downloads)
+yield* response.video.materialize()                // pull bytes before the URL expires
+
+// Explicit job control.
+const job = yield* Video.start(request)            // Job<VideoResponse>
+job.id; job.status; job.progress; job.token        // token is serializable JSON
+yield* job.await({ poll })                         // VideoResponse
+yield* job.cancel()
+
+// Resume from another process.
+const resumed = yield* Video.resume(model, token)  // Job<VideoResponse>
+
+// Progress as a stream.
+yield* Video.stream(request)                       // Stream<VideoEvent>: job-queued { position } | job-progress { progress, logs } | video { index, video } | finish
+```
+
+Webhooks: `Video.complete(model, token, webhook)` finishes a job from a webhook payload without polling. Token shape is route-owned and opaque (Veo operation name, fal `response_url`, Runway task id).
+
+#### Speech (TTS)
+
+```ts
+const request = Speech.request({
+  model: elevenlabs("eleven_v3"),
+  text: "Hello from OpenCode.",
+  voice: "JBFqnCBsd6RMkjVDRZzb",                  // name, uuid, or { id } — provider-normalized
+  format: "mp3",                                   // mp3 | wav | pcm | opus | aac | flac | (string & {})
+  speed: 1.0,
+  language: "en",
+  instructions: "Warm, unhurried.",
+  providerOptions: { stability: 0.5 },
+})
+
+const response = yield* Speech.generate(request)   // SpeechResponse: audio: Media.Asset, timestamps?, usage
+yield* Speech.stream(request)                      // Stream<SpeechEvent>: audio-delta { chunk } | timestamps { words } | finish
+```
+
+Streaming TTS is first-class on day one: OpenAI `stream_format: sse`, ElevenLabs `/stream`, Cartesia SSE, Deepgram chunked. Input-streaming TTS (WS, text arrives incrementally) is a later `Speech.session(...)` scoped resource, not part of `generate`.
+
+#### Transcription (STT)
+
+```ts
+const request = Transcription.request({
+  model: openai("gpt-4o-transcribe"),
+  audio: Media.file("./call.wav"),
+  language: "en",
+  prompt: "Names: Shoubhit, OpenCode.",
+  timestamps: "word",                              // none | segment | word
+  diarize: true,
+  providerOptions: { chunkingStrategy: "auto" },
+})
+
+const response = yield* Transcription.generate(request)
+response.text; response.segments; response.words; response.language; response.durationSeconds
+yield* Transcription.stream(request)               // Stream<TranscriptionEvent>: text-delta | segment | finish
+```
+
+Realtime STT over WebSocket is the same future `session` shape as input-streaming TTS.
+
+### `Job` — shared async execution
+
+```ts
+class Job<Response> {
+  readonly id: string
+  readonly model: MediaModel
+  readonly token: unknown                          // route-owned serializable JSON
+  readonly status: "queued" | "running" | "completed" | "failed" | "cancelled" | "expired"
+  readonly progress?: number                       // 0..1, normalized
+  readonly position?: number
+  readonly expiresAt?: number
+  refresh(): Effect<Job<Response>, AIError>
+  await(options?: { poll?: Poll }): Effect<Response, AIError>
+  cancel(): Effect<void, AIError>
+  events(options?): Stream<JobEvent, AIError>
+}
+
+Poll = { interval?: Duration; timeout?: Duration; schedule?: Schedule }   // route may override from provider hints (`openai-poll-after-ms`)
+```
+
+`Job` is not video-specific. Image routes on BFL, fal, and Replicate are jobs; `Image.start` exists for them. A route declares itself `inline` or `job`; `generate` on a job route is `start` then `await`.
+
+### Usage
+
+```ts
+Usage =
+  | { type: "tokens"; input; output; total; details? }
+  | { type: "seconds"; seconds }
+  | { type: "characters"; characters }
+  | { type: "credits"; credits }
+  | { type: "compute"; seconds }
+```
+
+Header-only usage (ElevenLabs `character-cost`, Deepgram `dg-char-count`) is lifted into `usage` by the route.
+
+### Promise API — `@opencode/ai/promise`
+
+Mirrors the `packages/plugin/src/effect` and `packages/plugin/src/promise` split that already exists in this repo. One mechanism for LLM and media.
+
+```ts
+import { AI } from "@opencode/ai/promise"
+
+const ai = AI.make()                                // ManagedRuntime over RequestExecutor.fetchLayer + all clients
+// AI.make({ layer }) to inject a custom executor / recorder / middleware
+
+const image = await ai.image.generate({ model, prompt })
+await image.image.bytes()
+
+for await (const event of ai.speech.stream({ model, text, voice })) { … }
+
+const job = await ai.video.start({ model, prompt })
+const video = await job.await({ poll: { interval: 10_000 }, signal })
+const resumed = ai.video.resume(model, JSON.parse(saved))
+
+const text = await ai.llm.generate({ model, prompt })   // closes today's gap: LLM has no promise API either
+for await (const event of ai.llm.stream(request)) { … }
+
+await ai.dispose()
+```
+
+Streams become `AsyncIterable` via `Stream.toAsyncIterable`. `AIError` is thrown as-is. `AbortSignal` maps to interruption. Nothing in `src/*` except this entrypoint knows about promises.
+
+### Providers
+
+Existing facades gain media routes behind the callable `ModelRef`; the modality routes each facade provides:
+
+| Facade | llm | image | video | speech | transcription | other |
+|---|---|---|---|---|---|---|
+| `OpenAI` | responses (default), chat | Images API | Sora (deprecated 2026-09-24) | ✓ | ✓ | |
+| `Google` | Gemini | Gemini-native (default), `imagen` | Veo | Gemini TTS | Gemini transcribe | |
+| `XAI` | ✓ | ✓ | ✓ | | | |
+| `ElevenLabs` | | | | ✓ | Scribe | soundEffect, music |
+| `Fal` | | ✓ | ✓ | | | |
+| `Replicate`, `Runway`, `Luma`, `Kling`, `MiniMax`, `Deepgram`, `Cartesia`, `AssemblyAI`, `BlackForestLabs`, `Stability` | | per provider | | | | |
+
+New facades follow the existing one-file-per-provider rule. Package entrypoints: `@opencode/ai/providers/openai` `model(id, settings)` returns the ref; modality-specific entrypoints such as `@opencode/ai/providers/openai/images` return the concrete model.
+
+`ImageModel<Options>` already gives typed `providerOptions` per model; `VideoModel`, `SpeechModel`, `TranscriptionModel` follow the same generic and `ModelRef` infers through to them. A shared `MediaModel` union is what `Job` and the promise client key on.
+
+### Routes and protocols
+
+Media does not fit the LLM four-axis route (SSE frames → event state machine) except for streaming TTS/STT. Reuse `Endpoint`, `Auth`, `Framing`, `RequestExecutor`, and add media protocol kinds:
+
+- `MediaProtocol.inline` — `body.from(request)` (JSON, multipart, or query), `response.decode(response)` (JSON, or binary body → `Media.Asset`).
+- `MediaProtocol.job` — `start`, `status`, `result`, `cancel`, optional `download`, `pollHint`, `token` schema.
+- `MediaProtocol.stream` — framing + `step` state machine emitting modality events, same discipline as LLM protocols.
+
+`Route.make` for media composes one protocol kind with endpoint/auth. The existing `ImageRoute { generate(request, execute) }` is the ad-hoc version of `inline` and gets folded in.
+
+### LLM integration
+
+- `MediaPart` becomes `{ type: "media"; media: Media.Asset; … }` so protocols branch on `kind` and can pass `url`/`ref` sources through natively (OpenAI `image_url`, Gemini `fileData`).
+- New `LLMEvent`s: `media { media: Media.Asset }` so Gemini inline image output is first-class instead of dropped. OpenAI Responses `image_generation_call` keeps its single carrier — the provider-executed `tool-result` with `file` content — because Core consumes hosted tool-result content today and has no `media` event handling yet; it switches to the `media` carrier when Core adopts the event, so the image is never emitted twice.
+- `Message.assistant([...])` accepts media parts; Gemini multi-turn image editing replays them.
+- `Tool.FileContent` aligns with `Media.Source`.
+
+## Decisions
+
+All settled:
+
+1. **Callable facades + `ModelRef`** replace per-modality selectors as the primary way to name a model, for LLM and media alike. Explicit selectors stay only for providers with two APIs in one modality.
+2. **`providerOptions` everywhere** (rename current `Image.options`) for consistency with LLM.
+3. **No hidden `n` fan-out.** `n` lowers natively; routes that cannot do `n > 1` fail typed. Callers use `Effect.all` / `Promise.all` explicitly.
+4. **Errors over warnings** for unsupported common fields; `notices` for provider-side partial results only.
+5. **`Media.Asset` is a class** (lazy bytes, cached) with `Media.Source` as the serializable Schema for wire/persistence. `Asset.from(source)` / `asset.source` round-trip losslessly. Same pattern as `LanguageModel` today.
+6. **Promise entrypoint**: `@opencode/ai/promise` exporting `AI.make(options?: { layer? })` plus a module-level default `ai` for scripts, covering LLM too.
+7. **Modality set for v1**: `Image`, `Video`, `Speech`, `Transcription`. `Music`/`SoundEffect` and `session` (bidirectional WS, realtime) are designed-for but deferred.
+8. **Sora is skipped** (API shuts down 2026-09-24). Video launches with Veo, xAI, fal, Runway.
+
+## Build order
+
+Foundation + Image ship together as the reference implementation, serially. Video, Speech, and Transcription then proceed in parallel on separate branches. Image jobs and partial streaming come last, after Video has hardened `Job`.
+
+## Phasing
+
+1. **Foundation** — `ModelRef` + callable facades (LLM included, `.responses`/`.chat`/`.model` kept), `Media`, `Job`, `Poll`, `Usage` union, `MediaProtocol` kinds, `@opencode/ai/promise` with `llm` + `image`. Port the five existing image protocols onto it. Unify `MediaPart` and add the `media` LLM event (fixes Gemini image output being dropped).
+2. **Video** — Veo, xAI, fal, Runway first. Then Luma, Kling, MiniMax, Replicate.
+3. **Speech + Transcription** — OpenAI, ElevenLabs, Gemini TTS, Deepgram, Cartesia, AssemblyAI. Streaming TTS from the start.
+4. **Image jobs and partials** — BFL, fal, Replicate, Stability; OpenAI `partial_images` streaming.
+5. **Later** — ElevenLabs music/SFX, Lyria, `Speech.session` / `Transcription.session`, realtime.
+
+Core adoption (session attachments beyond png/jpeg/gif/webp/pdf, image-generation tool, TUI rendering) comes after phase 1 and is a Core concern.

packages/ai/example/tutorial.ts

@@ -1,5 +1,17 @@
 import { Config, Effect, Formatter, Layer, Schema, Stream } from "effect"
-import { LLM, LLMClient, LLMRequest, Message, ProviderID, Tool, ToolRuntime } from "@opencode/ai"
+import { NodeFileSystem } from "@effect/platform-node"
+import {
+  Image,
+  ImageClient,
+  LLM,
+  LLMClient,
+  LLMRequest,
+  Media,
+  Message,
+  ProviderID,
+  Tool,
+  ToolRuntime,
+} from "@opencode/ai"
 import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor } from "@opencode/ai/route"
 import { OpenAI } from "@opencode/ai/providers"
 
@@ -16,15 +28,20 @@ import { OpenAI } from "@opencode/ai/providers"
 
 const apiKey = Config.redacted("OPENAI_API_KEY")
 
-// 1. Pick a model. The provider helper records provider identity, protocol
-// choice, capabilities, deployment options, authentication, and defaults.
-const model = OpenAI.configure({
+// 1. Configure a provider. The configured facade records provider identity,
+// deployment options, authentication, and defaults. Calling it with a model id
+// returns a `ModelRef`: `LLM.request` resolves the default LLM route
+// (Responses for OpenAI) and `Image.request` resolves the image route, so one
+// value names a model for every modality. `.responses(...)` / `.chat(...)`
+// remain available when you need a specific API.
+const openai = OpenAI.configure({
   apiKey,
   generation: { maxTokens: 160 },
   providerOptions: {
     store: false,
   },
-}).model("gpt-4o-mini")
+})
+const model = openai("gpt-4o-mini")
 
 // 2. Build a provider-neutral request. This is useful when reusing one request
 // across generate and stream examples.
@@ -209,18 +226,39 @@ const FakeEcho = {
   }),
 }
 
+// 8. Image generation uses the same facade and the same request/generate shape.
+// `response.image` is a `Media.Asset`: bytes decode lazily and are cached, and
+// `Media.write` persists them through the Effect `FileSystem`.
+const generateImage = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: openai("gpt-image-1-mini"),
+    prompt: "A flat black circle centered on a plain white background.",
+    size: "1024x1024",
+    format: "jpeg",
+    providerOptions: { quality: "low" },
+  })
+
+  console.log("\n== image ==")
+  console.log("media type:", response.image.mediaType)
+  console.log("bytes:", (yield* response.image.bytes()).byteLength)
+  console.log("usage", Formatter.formatJson(response.usage, { space: 2 }))
+  yield* Media.write(response.image, "tutorial-image.jpg").pipe(Effect.provide(NodeFileSystem.layer))
+})
+
 // Provide the LLM runtime and the HTTP request executor once. Keep one path
 // enabled at a time so the tutorial can demonstrate generate, stream, or
 // tool-loop behavior without spending tokens on every example.
 const requestExecutorLayer = RequestExecutor.fetchLayer
 const llmClientLayer = LLMClient.layer.pipe(Layer.provide(requestExecutorLayer))
+const imageClientLayer = ImageClient.layer.pipe(Layer.provide(requestExecutorLayer))
 
 const program = Effect.gen(function* () {
   // yield* generateOnce
   // yield* streamText
   // yield* generateStructuredObject
   // yield* generateDynamicObject.pipe(Effect.andThen((response) => Effect.sync(() => console.log(response.object))))
+  // yield* generateImage
   yield* streamWithTools
-}).pipe(Effect.provide(Layer.mergeAll(requestExecutorLayer, llmClientLayer)))
+}).pipe(Effect.provide(Layer.mergeAll(requestExecutorLayer, llmClientLayer, imageClientLayer)))
 
 Effect.runPromise(program)

packages/ai/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.17.20",
+  "version": "2.0.3",
   "name": "@opencode/ai",
   "type": "module",
   "license": "MIT",
@@ -15,6 +15,7 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./promise": "./src/promise.ts",
     "./testing": "./src/testing.ts",
     "./*": "./src/*.ts"
   },

packages/ai/src/cache-policy.ts

@@ -12,6 +12,7 @@
 // count against the four-breakpoint budget; auto only fills remaining slots.
 import { CacheHint, type CachePolicy, type CachePolicyObject } from "./schema/options.js"
 import { LLMRequest, Message, ToolDefinition, type ContentPart, type ToolEntry } from "./schema/messages.js"
+import { effortUpdate } from "./effort-updates.js"
 
 const AUTO: CachePolicyObject = {
   tools: true,
@@ -121,9 +122,15 @@ const markMessages = (
     return markMessageAt(messages, lastIndexOfRole(messages, "user"), hint, budget)
   if (strategy === "latest-assistant")
     return markMessageAt(messages, lastIndexOfRole(messages, "assistant"), hint, budget)
-  const start = Math.max(0, messages.length - strategy.tail)
+  let start = messages.length
+  let remaining = strategy.tail
+  while (remaining > 0 && start > 0) {
+    start -= 1
+    if (effortUpdate(messages[start]!) === undefined) remaining -= 1
+  }
   let next = messages
-  for (let i = start; i < messages.length; i++) next = markMessageAt(next, i, hint, budget)
+  for (let i = start; i < messages.length; i++)
+    if (effortUpdate(messages[i]!) === undefined) next = markMessageAt(next, i, hint, budget)
   return next
 }
 

packages/ai/src/effort-updates.ts

@@ -0,0 +1,25 @@
+// Changing the top-level reasoning effort invalidates the provider prompt cache. Protocols with a native
+// per-message update keep it frozen and lower `Message.effort(...)` markers instead; other routes strip them.
+import { LLMRequest, type EffortPart, type Message } from "./schema/messages.js"
+
+export const effortUpdate = (message: Message): EffortPart | undefined => {
+  if (message.role !== "system" || message.content.length !== 1) return undefined
+  const part = message.content[0]
+  return part.type === "effort" ? part : undefined
+}
+
+export const stripEffortUpdates = (request: LLMRequest) => {
+  const messages = request.messages.filter((message) => effortUpdate(message) === undefined)
+  return messages.length === request.messages.length ? request : LLMRequest.update(request, { messages })
+}
+
+export const applyEffortUpdates = (request: LLMRequest): LLMRequest =>
+  request.model.route.supportsEffortUpdates?.(request) ? request : stripEffortUpdates(request)
+
+// Reverted or forked history can leave the last marker disagreeing with the requested effort.
+export const resolveEffortUpdates = (request: LLMRequest, current: string | undefined) => {
+  const updates = request.messages.flatMap((message) => effortUpdate(message) ?? [])
+  if (updates.length === 0) return { request, effort: current }
+  if (updates.at(-1)?.effort !== current) return { request: stripEffortUpdates(request), effort: current }
+  return { request, effort: updates[0]?.previous }
+}

packages/ai/src/image-client.ts

@@ -1,15 +1,21 @@
-import { Context, Effect, Layer } from "effect"
+import { Context, Effect, Layer, Stream } from "effect"
 import { RequestExecutor } from "./route/executor.js"
-import { mergeHttpOptions, type AIError } from "./schema/index.js"
-import { sanitizeSurrogates } from "./utils/sanitize.js"
-import type { ImageOptions, ImageRequest, ImageRequestFor, ImageResponse } from "./image.js"
-
-export type Execute = RequestExecutor.Interface["execute"]
+import type { AIError } from "./schema/index.js"
+import {
+  responseEvents,
+  type ImageEvent,
+  type ImageOptions,
+  type ImageRequestFor,
+  type ImageResponse,
+} from "./image.js"
 
 export interface Interface {
   readonly generate: <Options extends ImageOptions>(
     request: ImageRequestFor<Options>,
   ) => Effect.Effect<ImageResponse, AIError>
+  readonly stream: <Options extends ImageOptions>(
+    request: ImageRequestFor<Options>,
+  ) => Stream.Stream<ImageEvent, AIError>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/ImageClient") {}
@@ -22,23 +28,27 @@ export const generate = <Options extends ImageOptions>(
     return yield* client.generate(request)
   })
 
+export const stream = <Options extends ImageOptions>(
+  request: ImageRequestFor<Options>,
+): Stream.Stream<ImageEvent, AIError, Service> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const client = yield* Service
+      return client.stream(request)
+    }),
+  )
+
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
   Service,
   Effect.gen(function* () {
     const executor = yield* RequestExecutor.Service
+    const generate = <Options extends ImageOptions>(request: ImageRequestFor<Options>) =>
+      request.model.route.generate(request, executor.execute)
     return Service.of({
-      generate: (request) =>
-        request.model.route.generate(
-          {
-            ...sanitizeSurrogates({
-              ...request,
-              model: undefined,
-              http: mergeHttpOptions(request.model.http, request.http),
-            }),
-            model: request.model,
-          },
-          executor.execute,
-        ),
+      generate,
+      // Inline routes have no partial frames yet; the stream is the completed response expanded into events.
+      stream: (request) =>
+        Stream.unwrap(generate(request).pipe(Effect.map((response) => Stream.fromIterable(responseEvents(response))))),
     })
   }),
 )
@@ -47,4 +57,5 @@ export const ImageClient = {
   Service,
   layer,
   generate,
+  stream,
 } as const

packages/ai/src/image.ts

@@ -1,22 +1,32 @@
-import { Effect, Schema } from "effect"
+import { Effect, Schema, Stream } from "effect"
+import { Media } from "./media.js"
+import { ModelRef, type ResolveImageModel } from "./model-ref.js"
+import { Endpoint } from "./route/endpoint.js"
+import { MediaRoute } from "./route/media.js"
+import type { MediaProtocol } from "./route/media-protocol.js"
 import {
+  AIError,
   HttpOptions,
   InvalidRequestError,
-  AIError,
+  MediaUsage,
   ModelID,
   ProviderID,
   ProviderMetadata,
-  Usage,
+  UnsupportedOperationError,
 } from "./schema/index.js"
-import { ImageClient, Service, type Execute as ImageExecute } from "./image-client.js"
+import { ImageClient, Service } from "./image-client.js"
 
-export interface ImageRoute<Options extends ImageOptions = ImageOptions> {
-  readonly id: string
-  readonly generate: (request: ImageRequestFor<Options>, execute: ImageExecute) => Effect.Effect<ImageResponse, AIError>
-}
+// ---------------------------------------------------------------------------
+// Model
+// ---------------------------------------------------------------------------
 
 export type ImageOptions = Record<string, unknown>
 
+export type ImageRoute<Options extends ImageOptions = ImageOptions> = MediaRoute.Route<
+  ImageRequestFor<Options>,
+  ImageResponse
+>
+
 export class ImageModel<Options extends ImageOptions = ImageOptions> {
   declare protected readonly _Options: (options: Options) => Options
   readonly id: ModelID
@@ -39,6 +49,26 @@ export class ImageModel<Options extends ImageOptions = ImageOptions> {
       http: input.http,
     })
   }
+
+  /** Compose an inline image protocol with its canonical path into a model for one deployment. */
+  static fromRoute<Options extends ImageOptions = ImageOptions>(
+    route: ImageModel.RouteInput<Options>,
+    input: MediaRoute.ModelInput,
+  ) {
+    return ImageModel.make<Options>({
+      id: input.id,
+      provider: route.provider,
+      http: input.http,
+      route: MediaRoute.make({
+        id: route.id,
+        provider: route.provider,
+        protocol: route.protocol,
+        endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
+        auth: input.auth,
+        headers: input.headers,
+      }),
+    })
+  }
 }
 
 export namespace ImageModel {
@@ -54,81 +84,87 @@ export namespace ImageModel {
     readonly id: string | ModelID
     readonly provider: string | ProviderID
   }
+
+  export interface RouteInput<Options extends ImageOptions = ImageOptions> {
+    readonly id: string
+    readonly provider: string | ProviderID
+    readonly protocol: MediaProtocol.Inline<ImageRequestFor<Options>, ImageResponse>
+    readonly path: Endpoint.EndpointPart<MediaProtocol.Body, ImageRequestFor<Options>>
+    /** Canonical base URL; `ModelInput.baseURL` overrides it per deployment. */
+    readonly baseURL?: string
+  }
 }
 
 export const ImageModelSchema = Schema.declare((value): value is ImageModel => value instanceof ImageModel, {
   expected: "Image.Model",
 })
 
-const ImageBytesInput = Schema.Struct({
-  type: Schema.Literal("bytes"),
-  data: Schema.Uint8Array,
-  mediaType: Schema.String,
-})
-const ImageUrlInput = Schema.Struct({
-  type: Schema.Literal("url"),
-  url: Schema.String,
-})
-const ImageFileIDInput = Schema.Struct({
-  type: Schema.Literal("file-id"),
-  id: Schema.String,
-})
-const ImageFileURIInput = Schema.Struct({
-  type: Schema.Literal("file-uri"),
-  uri: Schema.String,
-  mediaType: Schema.String,
-})
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
 
-export const ImageInputSchema = Schema.Union([
-  ImageBytesInput,
-  ImageUrlInput,
-  ImageFileIDInput,
-  ImageFileURIInput,
-]).pipe(Schema.toTaggedUnion("type"))
-export type ImageInput = Schema.Schema.Type<typeof ImageInputSchema>
+export type ImageSize = `${number}x${number}`
+export const ImageSize = Schema.declare<ImageSize>(
+  (value): value is ImageSize => typeof value === "string" && /^\d+x\d+$/.test(value),
+  { title: "ImageSize" },
+)
 
-export const ImageInput = {
-  bytes: (data: Uint8Array, mediaType: string): ImageInput => ({ type: "bytes", data, mediaType }),
-  url: (url: string): ImageInput => ({ type: "url", url }),
-  file: (id: string): ImageInput => ({ type: "file-id", id }),
-  fileUri: (uri: string, mediaType: string): ImageInput => ({ type: "file-uri", uri, mediaType }),
-} as const
+export type ImageAspectRatio = `${number}:${number}`
+export const ImageAspectRatio = Schema.declare<ImageAspectRatio>(
+  (value): value is ImageAspectRatio => typeof value === "string" && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(value),
+  { title: "ImageAspectRatio" },
+)
+
+export type ImageFormat = "png" | "jpeg" | "webp" | (string & {})
 
 export class ImageRequest extends Schema.Class<ImageRequest>("Image.Request")({
   model: ImageModelSchema,
   prompt: Schema.String,
-  images: Schema.optional(Schema.Array(ImageInputSchema)),
-  options: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  /** Edit sources or style/subject references, in order. */
+  images: Schema.optional(Schema.Array(Media.AssetSchema)),
+  /** Inpainting mask; routes that cannot honor it fail with `UnsupportedOperation`. */
+  mask: Schema.optional(Media.AssetSchema),
+  n: Schema.optional(Schema.Int),
+  size: Schema.optional(ImageSize),
+  aspectRatio: Schema.optional(ImageAspectRatio),
+  seed: Schema.optional(Schema.Number),
+  format: Schema.optional(Schema.String),
+  providerOptions: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
   http: Schema.optional(HttpOptions),
 }) {
   declare protected readonly _ImageRequest: void
 }
 
-export type ImageRequestFor<Options extends ImageOptions = ImageOptions> = Omit<ImageRequest, "model" | "options"> & {
+export type ImageRequestFor<Options extends ImageOptions = ImageOptions> = Omit<
+  ImageRequest,
+  "model" | "providerOptions"
+> & {
   readonly model: ImageModel<Options>
-  readonly options?: Options
+  readonly providerOptions?: Options
 }
 
-export type ImageModelOptions<Model> = Model extends ImageModel<infer Options> ? Options : never
+export type ImageModelInput = ImageModel | ModelRef.WithImage
 
-export type ImageRequestInput<Model extends object = ImageModel> = Omit<
+export type ImageModelOptions<Model> = ResolveImageModel<Model> extends ImageModel<infer Options> ? Options : never
+
+export type ImageRequestInput<Model extends ImageModelInput = ImageModelInput> = Omit<
   ConstructorParameters<typeof ImageRequest>[0],
-  "model" | "options" | "http"
+  "model" | "providerOptions" | "http"
 > & {
   readonly model: Model
-  readonly options?: NoInfer<ImageModelOptions<Model>>
+  readonly format?: ImageFormat
+  readonly providerOptions?: NoInfer<ImageModelOptions<Model>>
   readonly http?: HttpOptions.Input
-} & (Model extends ImageModel<ImageModelOptions<Model>> ? unknown : never)
+}
 
-export class GeneratedImage extends Schema.Class<GeneratedImage>("Image.Generated")({
-  mediaType: Schema.String,
-  data: Schema.Union([Schema.String, Schema.Uint8Array]),
-  providerMetadata: Schema.optional(ProviderMetadata),
-}) {}
+// ---------------------------------------------------------------------------
+// Response and events
+// ---------------------------------------------------------------------------
 
 export class ImageResponse extends Schema.Class<ImageResponse>("Image.Response")({
-  images: Schema.Array(GeneratedImage),
-  usage: Schema.optional(Usage),
+  images: Schema.Array(Media.AssetSchema),
+  usage: Schema.optional(MediaUsage),
+  notices: Schema.optional(Schema.Array(Media.Notice)),
   providerMetadata: Schema.optional(ProviderMetadata),
 }) {
   get image() {
@@ -136,7 +172,57 @@ export class ImageResponse extends Schema.Class<ImageResponse>("Image.Response")
   }
 }
 
-export function request<const Model extends object>(
+export const ImageOutputEvent = Schema.Struct({
+  type: Schema.tag("image"),
+  index: Schema.Number,
+  image: Media.AssetSchema,
+}).annotate({ identifier: "Image.Event.Image" })
+
+export const ImageFinishEvent = Schema.Struct({
+  type: Schema.tag("finish"),
+  usage: Schema.optional(MediaUsage),
+  notices: Schema.optional(Schema.Array(Media.Notice)),
+  providerMetadata: Schema.optional(ProviderMetadata),
+}).annotate({ identifier: "Image.Event.Finish" })
+
+const imageEventTagged = Schema.Union([ImageOutputEvent, ImageFinishEvent]).pipe(Schema.toTaggedUnion("type"))
+export const ImageEvent = Object.assign(imageEventTagged, {
+  is: {
+    image: imageEventTagged.guards.image,
+    finish: imageEventTagged.guards.finish,
+  },
+})
+export type ImageEvent = Schema.Schema.Type<typeof imageEventTagged>
+
+/** Inline routes produce every image at once; expand the response into the streaming event shape. */
+export const responseEvents = (response: ImageResponse): ReadonlyArray<ImageEvent> => [
+  ...response.images.map((image, index) => ImageOutputEvent.make({ index, image })),
+  ImageFinishEvent.make({
+    usage: response.usage,
+    notices: response.notices,
+    providerMetadata: response.providerMetadata,
+  }),
+]
+
+// ---------------------------------------------------------------------------
+// Request-shaped call API
+// ---------------------------------------------------------------------------
+
+const resolveModel = (model: ImageModelInput): ImageModel => {
+  if (model instanceof ImageModel) return model
+  // Typed callers cannot reach the throw; it guards JS callers passing a ref without an image selector.
+  const selected = model.facade.image?.(model.id)
+  if (selected) return selected
+  throw new AIError({
+    reason: new UnsupportedOperationError({
+      operation: "image",
+      provider: model.provider,
+      message: `${model.provider} does not expose an image route for ${model.id}`,
+    }),
+  })
+}
+
+export function request<const Model extends ImageModelInput>(
   input: ImageRequestInput<Model>,
 ): ImageRequestFor<ImageModelOptions<Model>>
 export function request(input: ImageRequest): ImageRequest
@@ -144,29 +230,43 @@ export function request(input: ImageRequest | ImageRequestInput) {
   if (input instanceof ImageRequest) return input
   return new ImageRequest({
     ...input,
-    model: input.model as unknown as ImageModel,
+    model: resolveModel(input.model),
     http: input.http === undefined ? undefined : HttpOptions.make(input.http),
   })
 }
 
-export function generate<const Model extends object>(
+const requestEffect = (input: ImageRequest | ImageRequestInput) =>
+  Effect.try({
+    try: () => request(input),
+    catch: (error) =>
+      error instanceof AIError
+        ? error
+        : new AIError({
+            reason: new InvalidRequestError({
+              message: error instanceof Error ? error.message : String(error),
+              cause: error,
+            }),
+          }),
+  })
+
+export function generate<const Model extends ImageModelInput>(
   input: ImageRequestInput<Model>,
 ): Effect.Effect<ImageResponse, AIError, Service>
 export function generate(input: ImageRequest): Effect.Effect<ImageResponse, AIError, Service>
 export function generate(input: ImageRequest | ImageRequestInput) {
-  return Effect.try({
-    try: () => (input instanceof ImageRequest ? input : request(input)),
-    catch: (error) =>
-      new AIError({
-        reason: new InvalidRequestError({
-          message: error instanceof Error ? error.message : String(error),
-          cause: error,
-        }),
-      }),
-  }).pipe(Effect.flatMap((request) => ImageClient.generate(request as unknown as ImageRequestFor<ImageOptions>)))
+  return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.generate(request)))
+}
+
+export function stream<const Model extends ImageModelInput>(
+  input: ImageRequestInput<Model>,
+): Stream.Stream<ImageEvent, AIError, Service>
+export function stream(input: ImageRequest): Stream.Stream<ImageEvent, AIError, Service>
+export function stream(input: ImageRequest | ImageRequestInput) {
+  return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => ImageClient.stream(request))))
 }
 
 export const Image = {
   request,
   generate,
+  stream,
 } as const

packages/ai/src/index.ts

@@ -11,9 +11,30 @@ export type {
   Service as LLMClientService,
 } from "./route/client.js"
 export * from "./schema/index.js"
-export { GeneratedImage, ImageInput, ImageInputSchema, ImageModel, ImageRequest, ImageResponse } from "./image.js"
-export type { ImageModelOptions, ImageOptions, ImageRequestFor, ImageRequestInput, ImageRoute } from "./image.js"
+export {
+  ImageAspectRatio,
+  ImageEvent,
+  ImageModel,
+  ImageModelSchema,
+  ImageRequest,
+  ImageResponse,
+  ImageSize,
+} from "./image.js"
+export type {
+  ImageFormat,
+  ImageModelInput,
+  ImageModelOptions,
+  ImageOptions,
+  ImageRequestFor,
+  ImageRequestInput,
+  ImageRoute,
+} from "./image.js"
 export { Image } from "./image.js"
+export { Media } from "./media.js"
+export { ModelRef } from "./model-ref.js"
+export type { ResolveImageModel, ResolveLanguageModel } from "./model-ref.js"
+export { Job } from "./job.js"
+export type { Event as JobEvent, Poll, Route as JobRoute, Snapshot as JobSnapshot, Status as JobStatus } from "./job.js"
 export { Tool, ToolFailure, toDefinitions } from "./tool.js"
 export { ToolRuntime } from "./tool-runtime.js"
 export type { DispatchResult as ToolDispatchResult, ToolSettlement } from "./tool-runtime.js"

packages/ai/src/job.ts

@@ -0,0 +1,137 @@
+import { Duration, Effect, Schedule, Schema, Stream } from "effect"
+import { AIError, TimeoutError } from "./schema/errors.js"
+
+export const Status = Schema.Literals(["queued", "running", "completed", "failed", "cancelled", "expired"])
+export type Status = Schema.Schema.Type<typeof Status>
+
+/** Provider-neutral view of one job observation. */
+export interface Snapshot {
+  readonly id: string
+  readonly status: Status
+  /** Normalized 0..1 when the provider reports progress. */
+  readonly progress?: number
+  readonly position?: number
+  readonly expiresAt?: number
+}
+
+/**
+ * Route-owned job operations. `token` is the route's serializable handle (operation name, task id, response URL)
+ * so a job can be resumed from another process; its shape is opaque to `Job`.
+ */
+export interface Route<Response> {
+  readonly status: (token: unknown) => Effect.Effect<Snapshot, AIError>
+  readonly result: (token: unknown) => Effect.Effect<Response, AIError>
+  readonly cancel?: (token: unknown) => Effect.Effect<void, AIError>
+  /** Provider polling hint (e.g. `openai-poll-after-ms`) that overrides the default interval for the next poll. */
+  readonly pollHint?: (snapshot: Snapshot) => Duration.Duration | undefined
+}
+
+export interface Poll {
+  readonly interval?: Duration.Input
+  readonly timeout?: Duration.Input
+  /** Full override of the polling schedule; `interval` and `pollHint` are ignored when supplied. */
+  readonly schedule?: Schedule.Schedule<unknown, Snapshot>
+}
+
+export const DEFAULT_POLL_INTERVAL = Duration.seconds(5)
+export const DEFAULT_POLL_TIMEOUT = Duration.minutes(10)
+
+export type Event =
+  | { readonly type: "job-queued"; readonly id: string; readonly position?: number }
+  | { readonly type: "job-progress"; readonly id: string; readonly progress?: number }
+  | { readonly type: "job-finished"; readonly id: string; readonly status: Status }
+
+const TERMINAL: ReadonlySet<Status> = new Set(["completed", "failed", "cancelled", "expired"])
+
+export class Job<Response> {
+  readonly id: string
+  readonly status: Status
+  readonly progress?: number
+  readonly position?: number
+  readonly expiresAt?: number
+
+  constructor(
+    readonly route: Route<Response>,
+    readonly token: unknown,
+    snapshot: Snapshot,
+  ) {
+    this.id = snapshot.id
+    this.status = snapshot.status
+    this.progress = snapshot.progress
+    this.position = snapshot.position
+    this.expiresAt = snapshot.expiresAt
+  }
+
+  get snapshot(): Snapshot {
+    return {
+      id: this.id,
+      status: this.status,
+      progress: this.progress,
+      position: this.position,
+      expiresAt: this.expiresAt,
+    }
+  }
+
+  get terminal() {
+    return TERMINAL.has(this.status)
+  }
+
+  refresh(): Effect.Effect<Job<Response>, AIError> {
+    return this.route.status(this.token).pipe(Effect.map((snapshot) => new Job(this.route, this.token, snapshot)))
+  }
+
+  /** Poll until the job reaches a terminal status, then fetch the result. Fails with a `Timeout` reason on deadline. */
+  await(options?: { readonly poll?: Poll }): Effect.Effect<Response, AIError> {
+    const timeout = Duration.fromInputUnsafe(options?.poll?.timeout ?? DEFAULT_POLL_TIMEOUT)
+    const settled = this.terminal ? Effect.succeed(this) : this.poll(options?.poll)
+    return settled.pipe(
+      // Non-completed terminal states also go through `result` so the route can surface its provider failure body.
+      Effect.flatMap((job) => job.route.result(job.token)),
+      Effect.timeoutOrElse({
+        duration: timeout,
+        orElse: () =>
+          new AIError({
+            reason: new TimeoutError({
+              message: `Job ${this.id} did not finish within ${Duration.format(timeout)}`,
+              timeoutMs: Duration.toMillis(timeout),
+            }),
+          }),
+      }),
+    )
+  }
+
+  cancel(): Effect.Effect<void, AIError> {
+    return this.route.cancel?.(this.token) ?? Effect.void
+  }
+
+  /** Status observations as a stream, ending after the first terminal observation. */
+  events(options?: { readonly poll?: Poll }): Stream.Stream<Event, AIError> {
+    const observations = this.terminal
+      ? Stream.make(this)
+      : Stream.fromEffectSchedule(this.refresh(), this.schedule(options?.poll)).pipe(
+          Stream.takeUntil((job) => job.terminal),
+        )
+    return observations.pipe(
+      Stream.map((job): Event => {
+        if (job.terminal) return { type: "job-finished", id: job.id, status: job.status }
+        if (job.status === "queued") return { type: "job-queued", id: job.id, position: job.position }
+        return { type: "job-progress", id: job.id, progress: job.progress }
+      }),
+    )
+  }
+
+  private poll(poll: Poll | undefined) {
+    return this.refresh().pipe(Effect.repeat({ schedule: this.schedule(poll), until: (job) => job.terminal }))
+  }
+
+  private schedule(poll: Poll | undefined): Schedule.Schedule<unknown, Job<Response>> {
+    if (poll?.schedule) return poll.schedule.pipe(Schedule.setInputType<Job<Response>>())
+    const interval = poll?.interval ?? DEFAULT_POLL_INTERVAL
+    const pollHint = this.route.pollHint
+    const spaced = Schedule.spaced(interval).pipe(Schedule.setInputType<Job<Response>>())
+    if (!pollHint) return spaced
+    return spaced.pipe(
+      Schedule.modifyDelay((metadata) => Effect.succeed(pollHint(metadata.input.snapshot) ?? interval)),
+    )
+  }
+}

packages/ai/src/llm.ts

@@ -18,20 +18,24 @@ import {
   type ToolEntryInput,
 } from "./schema/index.js"
 import { make as makeTool, toDefinitions, type ToolSchema } from "./tool.js"
+import { ModelRef, type ResolveLanguageModel } from "./model-ref.js"
+
+/** A concrete language model or a callable-facade ref whose provider exposes an LLM route. */
+export type LanguageModelInput = LanguageModel | ModelRef
 
 /** Input accepted by `LLM.request`, normalized into the canonical `LLMRequest` class. */
-export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageModel> = Omit<
+export type RequestInput<SelectedModel extends LanguageModelInput = LanguageModelInput> = Omit<
   ConstructorParameters<typeof LLMRequest>[0],
   "model" | "system" | "messages" | "tools" | "toolChoice" | "generation" | "http" | "providerOptions"
 > & {
-  readonly model: SelectedLanguageModel
+  readonly model: SelectedModel
   readonly system?: string | SystemPart | ReadonlyArray<SystemPart>
   readonly prompt?: string | ContentPart | ReadonlyArray<ContentPart>
   readonly messages?: ReadonlyArray<Message | Message.Input>
   readonly tools?: ReadonlyArray<ToolEntryInput>
   readonly toolChoice?: ToolChoice.Input
   readonly generation?: GenerationOptions.Input
-  readonly providerOptions?: NoInfer<LanguageModelProviderOptions<SelectedLanguageModel>>
+  readonly providerOptions?: NoInfer<LanguageModelProviderOptions<ResolveLanguageModel<SelectedModel>>>
   readonly http?: HttpOptions.Input
 }
 
@@ -39,10 +43,14 @@ export const generate = LLMClient.generate
 
 export const stream = LLMClient.stream
 
-export const request = <const SelectedLanguageModel extends LanguageModel>(
-  input: RequestInput<SelectedLanguageModel>,
-) => {
+// The stored request keeps the concrete model; refs are resolved once here so nothing downstream knows about them.
+const resolveModel = (model: LanguageModelInput) => (model instanceof ModelRef ? model.facade.model(model.id) : model)
+
+export const request = <const SelectedModel extends LanguageModelInput>(
+  input: RequestInput<SelectedModel>,
+): LLMRequest<ResolveLanguageModel<SelectedModel>> => {
   const {
+    model,
     system: requestSystem,
     prompt,
     messages,
@@ -53,8 +61,9 @@ export const request = <const SelectedLanguageModel extends LanguageModel>(
     http: requestHttp,
     ...rest
   } = input
-  return new LLMRequest({
+  return new LLMRequest<ResolveLanguageModel<SelectedModel>>({
     ...rest,
+    model: resolveModel(model) as ResolveLanguageModel<SelectedModel>,
     system: SystemPart.content(requestSystem),
     messages: [...(messages?.map(Message.make) ?? []), ...(prompt === undefined ? [] : [Message.user(prompt)])],
     tools: tools?.map(ToolEntry.make) ?? [],
@@ -69,8 +78,8 @@ const GENERATE_OBJECT_TOOL_NAME = "generate_object"
 
 const GENERATE_OBJECT_TOOL_DESCRIPTION = "Return the structured result by calling this tool."
 
-type GenerateObjectBase<SelectedLanguageModel extends LanguageModel = LanguageModel> = Omit<
-  RequestInput<SelectedLanguageModel>,
+type GenerateObjectBase<SelectedModel extends LanguageModelInput = LanguageModelInput> = Omit<
+  RequestInput<SelectedModel>,
   "tools" | "toolChoice"
 >
 
@@ -91,13 +100,13 @@ export class GenerateObjectResponse<T> {
 
 export interface GenerateObjectOptions<
   S extends ToolSchema<any>,
-  SelectedLanguageModel extends LanguageModel = LanguageModel,
-> extends GenerateObjectBase<SelectedLanguageModel> {
+  SelectedModel extends LanguageModelInput = LanguageModelInput,
+> extends GenerateObjectBase<SelectedModel> {
   readonly schema: S
 }
 
-export interface GenerateObjectDynamicOptions<SelectedLanguageModel extends LanguageModel = LanguageModel>
-  extends GenerateObjectBase<SelectedLanguageModel> {
+export interface GenerateObjectDynamicOptions<SelectedModel extends LanguageModelInput = LanguageModelInput>
+  extends GenerateObjectBase<SelectedModel> {
   /** Raw JSON Schema object describing the expected output shape. */
   readonly jsonSchema: JsonSchema.JsonSchema
 }
@@ -147,11 +156,11 @@ const runGenerateObject = Effect.fn("LLM.generateObject")(function* (
  * 2. `jsonSchema: JsonSchema.JsonSchema` — `.object` is `unknown`. Use when
  *    the schema is only available at runtime (MCP, plugin manifests). Caller validates.
  */
-export function generateObject<const SelectedLanguageModel extends LanguageModel, S extends ToolSchema<any>>(
-  options: GenerateObjectOptions<S, SelectedLanguageModel>,
+export function generateObject<const SelectedModel extends LanguageModelInput, S extends ToolSchema<any>>(
+  options: GenerateObjectOptions<S, SelectedModel>,
 ): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, AIError, Service>
-export function generateObject<const SelectedLanguageModel extends LanguageModel>(
-  options: GenerateObjectDynamicOptions<SelectedLanguageModel>,
+export function generateObject<const SelectedModel extends LanguageModelInput>(
+  options: GenerateObjectDynamicOptions<SelectedModel>,
 ): Effect.Effect<GenerateObjectResponse<unknown>, AIError, Service>
 export function generateObject(options: GenerateObjectOptions<ToolSchema<any>> | GenerateObjectDynamicOptions) {
   if ("schema" in options) {

packages/ai/src/media.ts

@@ -0,0 +1,307 @@
+export * as Media from "./media.js"
+
+import { Effect, Encoding, FileSystem, Schema, SchemaGetter } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { ProviderID } from "./schema/ids.js"
+import { AIError, HttpContext, InvalidProviderOutputError, InvalidRequestError } from "./schema/errors.js"
+import { ProviderMetadata } from "./schema/options.js"
+import { Service } from "./route/executor-service.js"
+import { detectMediaType, extensionMediaType } from "./utils/media-type.js"
+
+export { detectMediaType } from "./utils/media-type.js"
+
+const OCTET_STREAM = "application/octet-stream"
+
+// ---------------------------------------------------------------------------
+// Source — the serializable wire/persistence form of a media asset
+// ---------------------------------------------------------------------------
+
+const BytesSource = Schema.Struct({
+  type: Schema.Literal("bytes"),
+  data: Schema.Uint8Array,
+  mediaType: Schema.String,
+})
+
+const Base64Source = Schema.Struct({
+  type: Schema.Literal("base64"),
+  data: Schema.String,
+  mediaType: Schema.String,
+})
+
+const UrlSource = Schema.Struct({
+  type: Schema.Literal("url"),
+  url: Schema.String,
+  mediaType: Schema.optional(Schema.String),
+  /** Epoch milliseconds after which the provider no longer serves the URL. */
+  expiresAt: Schema.optional(Schema.Number),
+  /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
+  headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+})
+
+/** A provider-side handle: OpenAI `file_id`, Gemini file URI, `gs://`, `runway://`, or a prior generation id. */
+const RefSource = Schema.Struct({
+  type: Schema.Literal("ref"),
+  provider: ProviderID,
+  id: Schema.String,
+  mediaType: Schema.optional(Schema.String),
+})
+
+export const Source = Schema.Union([BytesSource, Base64Source, UrlSource, RefSource])
+  .pipe(Schema.toTaggedUnion("type"))
+  .annotate({ identifier: "Media.Source" })
+export type Source = Schema.Schema.Type<typeof Source>
+
+// ---------------------------------------------------------------------------
+// Kind, Info, Notice
+// ---------------------------------------------------------------------------
+
+export const Kind = Schema.Literals(["image", "video", "audio", "document", "other"])
+export type Kind = Schema.Schema.Type<typeof Kind>
+
+export const kindOf = (mediaType: string): Kind => {
+  const lower = mediaType.toLowerCase()
+  if (lower.startsWith("image/")) return "image"
+  if (lower.startsWith("video/")) return "video"
+  if (lower.startsWith("audio/")) return "audio"
+  if (lower === "application/pdf" || lower.startsWith("text/")) return "document"
+  return "other"
+}
+
+/** Container-independent facts about the payload; raw PCM audio relies on these because it has no header. */
+export const Info = Schema.Struct({
+  width: Schema.optional(Schema.Number),
+  height: Schema.optional(Schema.Number),
+  durationSeconds: Schema.optional(Schema.Number),
+  sampleRate: Schema.optional(Schema.Number),
+  channels: Schema.optional(Schema.Number),
+  encoding: Schema.optional(Schema.String),
+  format: Schema.optional(Schema.String),
+}).annotate({ identifier: "Media.Info" })
+export type Info = Schema.Schema.Type<typeof Info>
+
+/** A provider-side partial result such as stripped audio or a moderated sample; never a silent drop. */
+export const Notice = Schema.Struct({
+  type: Schema.Literals(["moderated", "filtered", "other"]),
+  message: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
+}).annotate({ identifier: "Media.Notice" })
+export type Notice = Schema.Schema.Type<typeof Notice>
+
+// ---------------------------------------------------------------------------
+// Asset
+// ---------------------------------------------------------------------------
+
+const invalid = (message: string, cause?: unknown) =>
+  new AIError({ reason: new InvalidRequestError({ message, cause }) })
+
+/** Synchronous view of an inline payload; `undefined` for `url` and `ref` sources, which carry no local bytes. */
+export interface Inline {
+  readonly mime: string
+  readonly base64: string
+  readonly dataUrl: string
+}
+
+export class Asset {
+  readonly source: Source
+  /** Derived from the source: declared type, sniffed magic bytes, then `application/octet-stream`. */
+  readonly mediaType: string
+  readonly kind: Kind
+  readonly info?: Info
+  /** Epoch milliseconds after which a `url` source stops resolving. */
+  readonly expiresAt?: number
+  readonly providerMetadata?: ProviderMetadata
+
+  // Derived payload forms are cached on the instance because every protocol lowering re-reads the same payload. The
+  // cache is check-then-set (concurrent first reads of a `url` source may both download) and is never observable
+  // through `source`, so round-tripping through `Media.from(asset.source)` stays lossless.
+  #bytes: Uint8Array | undefined
+  #base64: string | undefined
+
+  constructor(input: Asset.Input) {
+    this.source = input.source
+    this.mediaType =
+      input.source.mediaType ??
+      (input.source.type === "bytes" ? detectMediaType(input.source.data) : undefined) ??
+      OCTET_STREAM
+    this.kind = kindOf(this.mediaType)
+    this.info = input.info
+    this.expiresAt = input.source.type === "url" ? input.source.expiresAt : undefined
+    this.providerMetadata = input.providerMetadata
+  }
+
+  /** Inline payload without effects, for protocols that embed base64 or data URLs directly. */
+  inline(): Inline | undefined {
+    const source = this.source
+    if (source.type !== "bytes" && source.type !== "base64") return undefined
+    const base64 = source.type === "base64" ? source.data : (this.#base64 ??= Encoding.encodeBase64(source.data))
+    const mime = this.mediaType.toLowerCase()
+    return { mime, base64, dataUrl: `data:${mime};base64,${base64}` }
+  }
+
+  /** Decoded payload; downloads `url` sources through the request executor and caches the result. */
+  bytes(): Effect.Effect<Uint8Array, AIError, Service> {
+    return Effect.suspend(() => {
+      const source = this.source
+      if (source.type === "bytes") return Effect.succeed(source.data)
+      if (this.#bytes !== undefined) return Effect.succeed(this.#bytes)
+      if (source.type === "ref")
+        return Effect.fail(invalid(`Cannot materialize provider ref ${source.provider}:${source.id}`))
+      const decoded =
+        source.type === "base64"
+          ? Effect.fromResult(Encoding.decodeBase64(source.data)).pipe(
+              Effect.mapError((cause) => invalid(`Media asset contains invalid base64 data`, cause)),
+            )
+          : download(source)
+      return decoded.pipe(Effect.tap((data) => Effect.sync(() => (this.#bytes = data))))
+    })
+  }
+
+  base64(): Effect.Effect<string, AIError, Service> {
+    return Effect.suspend(() => {
+      const source = this.source
+      if (source.type === "base64") return Effect.succeed(source.data)
+      if (this.#base64 !== undefined) return Effect.succeed(this.#base64)
+      return this.bytes().pipe(Effect.map((data) => (this.#base64 = Encoding.encodeBase64(data))))
+    })
+  }
+
+  dataUrl(): Effect.Effect<string, AIError, Service> {
+    return this.base64().pipe(Effect.map((data) => `data:${this.mediaType};base64,${data}`))
+  }
+
+  /**
+   * The `AssetEncoded` JSON form with `bytes` sources as base64, matching `Schema.toCodecJson(AssetSchema)`, so a
+   * plain `JSON.stringify` of messages or events stays lossless and decodes back through the JSON codec.
+   */
+  toJSON() {
+    const source = this.source
+    return {
+      source: source.type === "bytes" ? { ...source, data: Encoding.encodeBase64(source.data) } : source,
+      info: this.info,
+      providerMetadata: this.providerMetadata,
+    }
+  }
+
+  /** Pull `url` sources into owned bytes before the URL expires. Inline sources return themselves. */
+  materialize(): Effect.Effect<Asset, AIError, Service> {
+    if (this.source.type === "bytes" || this.source.type === "base64") return Effect.succeed(this)
+    return this.bytes().pipe(
+      Effect.map((data) =>
+        bytes(data, this.source.mediaType, { info: this.info, providerMetadata: this.providerMetadata }),
+      ),
+    )
+  }
+}
+
+export namespace Asset {
+  export interface Input {
+    readonly source: Source
+    readonly info?: Info
+    readonly providerMetadata?: ProviderMetadata
+  }
+}
+
+/** JSON form of an asset: the serializable `Source` plus caller-supplied metadata. `bytes` sources encode as base64. */
+export const AssetEncoded = Schema.Struct({
+  source: Source,
+  info: Schema.optional(Info),
+  providerMetadata: Schema.optional(ProviderMetadata),
+}).annotate({ identifier: "Media.AssetEncoded" })
+
+const encodeAsset = (asset: Asset): typeof AssetEncoded.Type => ({
+  source: asset.source,
+  info: asset.info,
+  providerMetadata: asset.providerMetadata,
+})
+
+const AssetInstance = Schema.declare((value): value is Asset => value instanceof Asset, {
+  expected: "Media.Asset",
+})
+
+/** `Asset` in the type domain and `AssetEncoded` on the wire, so messages and events holding assets serialize. */
+export const AssetSchema = AssetEncoded.pipe(
+  Schema.decodeTo(AssetInstance, {
+    decode: SchemaGetter.transform((encoded) => new Asset(encoded)),
+    encode: SchemaGetter.transform(encodeAsset),
+  }),
+)
+
+const download = Effect.fn("Media.download")(function* (source: Extract<Source, { readonly type: "url" }>) {
+  const executor = yield* Service
+  const response = yield* executor.execute(
+    HttpClientRequest.get(source.url).pipe(HttpClientRequest.setHeaders(source.headers ?? {})),
+  )
+  const buffer = yield* response.arrayBuffer.pipe(
+    Effect.mapError(
+      (cause) =>
+        new AIError({
+          reason: new InvalidProviderOutputError({
+            message: `Failed to read media from ${source.url}`,
+            http: new HttpContext({ url: response.request.url, status: response.status, headers: response.headers }),
+            cause,
+          }),
+        }),
+    ),
+  )
+  return new Uint8Array(buffer)
+})
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export type AssetOptions = Omit<Asset.Input, "source">
+
+export const from = (source: Source, options?: AssetOptions) => new Asset({ ...options, source })
+
+export const bytes = (data: Uint8Array, mediaType?: string, options?: AssetOptions) =>
+  from({ type: "bytes", data, mediaType: mediaType ?? detectMediaType(data) ?? OCTET_STREAM }, options)
+
+export const base64 = (data: string, mediaType: string, options?: AssetOptions) =>
+  from({ type: "base64", data, mediaType }, options)
+
+export const url = (
+  value: string,
+  options?: AssetOptions & Omit<Extract<Source, { readonly type: "url" }>, "type" | "url">,
+) => {
+  const { mediaType, expiresAt, headers, ...rest } = options ?? {}
+  return from({ type: "url", url: value, mediaType, expiresAt, headers }, rest)
+}
+
+export const ref = (provider: string | ProviderID, id: string, mediaType?: string, options?: AssetOptions) =>
+  from({ type: "ref", provider: ProviderID.make(provider), id, mediaType }, options)
+
+const DATA_URL = /^data:([^;,]+)(?:;[^,]*)*;base64,(.*)$/s
+
+/** Parse a `data:<mime>;base64,<data>` URL, or `undefined` when the value is not a base64 data URL. */
+export const parseDataUrl = (value: string, options?: AssetOptions) => {
+  const match = DATA_URL.exec(value)
+  return match === null ? undefined : base64(match[2], match[1], options)
+}
+
+/** Parse a `data:<mime>;base64,<data>` URL. Malformed input throws a typed `AIError` because constructors are sync. */
+export const fromDataUrl = (dataUrl: string, options?: AssetOptions) => {
+  const asset = parseDataUrl(dataUrl, options)
+  if (asset === undefined) throw invalid("Media data URLs must contain a MIME type and base64 data")
+  return asset
+}
+
+/** Read a file through `FileSystem` and sniff its media type from magic bytes, then the extension. */
+export const file = (path: string, options?: AssetOptions): Effect.Effect<Asset, AIError, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const data = yield* fs
+      .readFile(path)
+      .pipe(Effect.mapError((cause) => invalid(`Failed to read media file ${path}`, cause)))
+    return bytes(data, detectMediaType(data) ?? extensionMediaType(path), options)
+  })
+
+/** Materialize an asset and write its bytes through `FileSystem`. */
+export const write = (asset: Asset, path: string): Effect.Effect<void, AIError, FileSystem.FileSystem | Service> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const data = yield* asset.bytes()
+    yield* fs
+      .writeFile(path, data)
+      .pipe(Effect.mapError((cause) => invalid(`Failed to write media file ${path}`, cause)))
+  })

packages/ai/src/model-ref.ts

@@ -0,0 +1,54 @@
+import { ModelID, type ProviderID } from "./schema/ids.js"
+import type { LanguageModel } from "./schema/options.js"
+import type { ImageModel } from "./image.js"
+
+/**
+ * A provider-scoped model name bound to its configured facade. Callable facades return one of these so
+ * `LLM.request({ model: openai("gpt-5") })` and `Image.request({ model: openai("gpt-image-2") })` name a model once
+ * and let the request namespace pick the selector (`facade.model`, `facade.image`, …) on demand.
+ */
+export class ModelRef<S extends ModelRef.Selectors = ModelRef.Selectors> {
+  constructor(
+    readonly id: ModelID,
+    readonly facade: S,
+  ) {}
+
+  get provider() {
+    return this.facade.id
+  }
+}
+
+export namespace ModelRef {
+  /** The named selectors a configured provider facade exposes; `model` is the default LLM route. */
+  export interface Selectors {
+    readonly id: ProviderID
+    // oxlint-disable-next-line typescript-eslint/no-explicit-any
+    readonly model: (id: ModelID) => LanguageModel<any, any>
+    // oxlint-disable-next-line typescript-eslint/no-explicit-any
+    readonly image?: (id: ModelID) => ImageModel<any>
+  }
+
+  /** A ref whose provider exposes an image route. */
+  // oxlint-disable-next-line typescript-eslint/no-explicit-any
+  export type WithImage = ModelRef<Selectors & { readonly image: (id: ModelID) => ImageModel<any> }>
+
+  /** Make a configured facade callable: `openai("gpt-5")` returns a `ModelRef` over the facade's own selectors. */
+  export const facade = <const S extends Selectors>(selectors: S) =>
+    Object.assign((id: string | ModelID) => new ModelRef(ModelID.make(id), selectors), selectors)
+}
+
+/** The concrete `LanguageModel` a request will run against: either the model itself or the ref's `model` selector. */
+// oxlint-disable-next-line typescript-eslint/no-explicit-any
+export type ResolveLanguageModel<Model> =
+  Model extends LanguageModel<any, any> ? Model : Model extends ModelRef<infer S> ? ReturnType<S["model"]> : never
+
+/** The concrete `ImageModel` a request will run against: either the model itself or the ref's `image` selector. */
+// oxlint-disable-next-line typescript-eslint/no-explicit-any
+export type ResolveImageModel<Model> =
+  Model extends ImageModel<any>
+    ? Model
+    : Model extends ModelRef<infer S>
+      ? S extends { readonly image: (id: ModelID) => infer Selected }
+        ? Selected
+        : never
+      : never

packages/ai/src/promise.ts

@@ -0,0 +1,100 @@
+import { Effect, Layer, ManagedRuntime, Stream } from "effect"
+import { Image, ImageRequest, type ImageModelInput, type ImageRequestInput } from "./image.js"
+import { ImageClient } from "./image-client.js"
+import { LLM } from "./index.js"
+import { LLMClient } from "./route/client.js"
+import { RequestExecutor } from "./route/executor.js"
+import { LLMRequest } from "./schema/index.js"
+import type { LanguageModelInput, RequestInput } from "./llm.js"
+
+/**
+ * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM and image clients
+ * over a request executor; every method runs the corresponding Effect API and rethrows `AIError` unchanged.
+ */
+export interface Options {
+  /** Executor layer; defaults to `RequestExecutor.fetchLayer`. Inject a recorder or middleware here. */
+  readonly layer?: Layer.Layer<RequestExecutor.Service>
+}
+
+export interface RunOptions {
+  readonly signal?: AbortSignal
+}
+
+export type Services =
+  | Layer.Success<typeof LLMClient.layer>
+  | Layer.Success<typeof ImageClient.layer>
+  | RequestExecutor.Service
+
+const abortEffect = (signal: AbortSignal | undefined) =>
+  signal === undefined
+    ? Effect.never
+    : Effect.callback<void>((resume) => {
+        if (signal.aborted) {
+          resume(Effect.void)
+          return
+        }
+        const onAbort = () => resume(Effect.void)
+        signal.addEventListener("abort", onAbort, { once: true })
+        return Effect.sync(() => signal.removeEventListener("abort", onAbort))
+      })
+
+export const make = (options: Options = {}) => {
+  const runtime = ManagedRuntime.make(
+    Layer.mergeAll(LLMClient.layer, ImageClient.layer).pipe(
+      Layer.provideMerge(options.layer ?? RequestExecutor.fetchLayer),
+    ),
+  )
+
+  /** Run any package Effect (for example `asset.bytes()`) inside this runtime. */
+  const run = <A, E>(effect: Effect.Effect<A, E, Services>, options?: RunOptions) =>
+    runtime.runPromise(effect, { signal: options?.signal })
+
+  const iterate = <A, E>(stream: Stream.Stream<A, E, Services>, options?: RunOptions): AsyncIterable<A> =>
+    Stream.toAsyncIterable(
+      Stream.unwrap(
+        runtime.contextEffect.pipe(
+          Effect.map(
+            (context): Stream.Stream<A, E> =>
+              stream.pipe(Stream.interruptWhen(abortEffect(options?.signal)), Stream.provideContext(context)),
+          ),
+        ),
+      ),
+    )
+
+  // The typed `generate`/`stream` overloads take a concrete input or a request, not the union; normalize once here.
+  const llmRequest = (input: RequestInput | LLMRequest) => (input instanceof LLMRequest ? input : LLM.request(input))
+  const imageRequest = (input: ImageRequestInput | ImageRequest) =>
+    input instanceof ImageRequest ? input : Image.request(input)
+
+  return {
+    run,
+    llm: {
+      request: LLM.request,
+      generate: <const Model extends LanguageModelInput>(
+        input: RequestInput<Model> | LLMRequest,
+        options?: RunOptions,
+      ) => run(LLM.generate(llmRequest(input)), options),
+      stream: <const Model extends LanguageModelInput>(input: RequestInput<Model> | LLMRequest, options?: RunOptions) =>
+        iterate(LLM.stream(llmRequest(input)), options),
+    },
+    image: {
+      request: Image.request,
+      generate: <const Model extends ImageModelInput>(
+        input: ImageRequestInput<Model> | ImageRequest,
+        options?: RunOptions,
+      ) => run(Image.generate(imageRequest(input)), options),
+      stream: <const Model extends ImageModelInput>(
+        input: ImageRequestInput<Model> | ImageRequest,
+        options?: RunOptions,
+      ) => iterate(Image.stream(imageRequest(input)), options),
+    },
+    dispose: () => runtime.dispose(),
+  }
+}
+
+export type Client = ReturnType<typeof make>
+
+/** Default client over `RequestExecutor.fetchLayer` for scripts; the runtime builds its layer on first use. */
+export const ai = make()
+
+export * as AI from "./promise.js"

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

@@ -27,6 +27,7 @@ import {
 } from "../schema/index.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { classifyProviderFailure } from "../provider-error.js"
+import { effortUpdate, resolveEffortUpdates } from "../effort-updates.js"
 import * as Cache from "./utils/cache.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
@@ -36,6 +37,7 @@ const ADAPTER = "anthropic-messages"
 export const DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
 export const PATH = "/messages"
 export const DEFAULT_MAX_TOKENS = 32_000
+const DEFAULT_EFFORT = "high"
 
 const SSE_EVENTS = new Set([
   "message",
@@ -286,7 +288,11 @@ type AnthropicToolResultBlock = Schema.Schema.Type<typeof AnthropicToolResultBlo
 const AnthropicMessage = Schema.Union([
   Schema.Struct({ role: Schema.Literal("user"), content: Schema.Array(AnthropicUserBlock) }),
   Schema.Struct({ role: Schema.Literal("assistant"), content: Schema.Array(AnthropicAssistantBlock) }),
-  Schema.Struct({ role: Schema.Literal("system"), content: Schema.Array(AnthropicTextBlock) }),
+  Schema.Struct({
+    role: Schema.Literal("system"),
+    content: Schema.Array(AnthropicTextBlock),
+    output_config: Schema.optional(Schema.Struct({ effort: Schema.String })),
+  }),
 ]).pipe(Schema.toTaggedUnion("role"))
 type AnthropicMessage = Schema.Schema.Type<typeof AnthropicMessage>
 
@@ -654,7 +660,7 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (
   part: MediaPart,
   breakpoints?: Cache.Breakpoints,
 ) {
-  const mime = part.mediaType.toLowerCase()
+  const mime = part.media.mediaType.toLowerCase()
   const cacheControlValue = breakpoints ? cacheControl(breakpoints, part.cache) : undefined
   const fileId = fileIdFromMetadata(part.metadata)
 
@@ -683,9 +689,9 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (
     } satisfies AnthropicDocumentBlock
   }
 
-  const rawString = typeof part.data === "string" ? part.data.trim() : undefined
+  const rawString = ProviderShared.mediaUrl(part.media)?.trim()
   // SDK URL sources: URLImageSource:3817 / URLPDFSource:3823 {type:"url", url}
-  if (rawString && isHttpUrl(rawString) && !rawString.startsWith("data:")) {
+  if (rawString && isHttpUrl(rawString)) {
     if (mime.startsWith("image/"))
       return {
         type: "image" as const,
@@ -710,20 +716,11 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (
       } satisfies AnthropicDocumentBlock
   }
 
+  const media = yield* ProviderShared.requireInlineMedia("Anthropic Messages", part.media)
+
   // SDK PlainTextSource:2716 {type:"text", media_type:"text/plain", data}
   if (mime === "text/plain") {
-    const textData =
-      typeof part.data !== "string"
-        ? Buffer.from(part.data).toString("utf8")
-        : part.data.startsWith("data:")
-          ? (() => {
-              const comma = part.data.indexOf(",")
-              const payload = comma >= 0 ? part.data.slice(comma + 1) : part.data
-              return part.data.includes(";base64")
-                ? Buffer.from(payload, "base64").toString("utf8")
-                : decodeURIComponent(payload)
-            })()
-          : part.data
+    const textData = Buffer.from(media.base64, "base64").toString("utf8")
     return {
       type: "document" as const,
       source: { type: "text" as const, media_type: "text/plain" as const, data: textData },
@@ -738,7 +735,6 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (
     } satisfies AnthropicDocumentBlock
   }
 
-  const media = ProviderShared.normalizeMedia(part)
   if (media.mime === "application/pdf")
     return {
       type: "document" as const,
@@ -757,7 +753,7 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (
         : { citations: citationsFromMetadata(part.metadata)! }),
     } satisfies AnthropicDocumentBlock
   if (!media.mime.startsWith("image/"))
-    return yield* invalid(`Anthropic Messages does not support media type ${part.mediaType}`)
+    return yield* invalid(`Anthropic Messages does not support media type ${part.media.mediaType}`)
   return {
     type: "image" as const,
     source: {
@@ -776,7 +772,7 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (
 // content instead of JSON-stringifying base64 into a prompt string.
 const lowerToolResultContentItem = Effect.fnUntraced(function* (item: Tool.Content) {
   if (item.type === "text") return { type: "text" as const, text: item.text } satisfies AnthropicTextBlock
-  return yield* lowerMedia({ type: "media", mediaType: item.mime, data: item.uri, filename: item.name })
+  return yield* lowerMedia(ProviderShared.toolFileMedia(item))
 })
 
 const lowerToolResultContent = Effect.fnUntraced(function* (part: ToolResultPart) {
@@ -877,6 +873,12 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
 
   for (const [index, message] of request.messages.entries()) {
     if (message.role === "system") {
+      const update = effortUpdate(message)
+      if (update) {
+        // Accepted at any position, so the text-update placement rules do not apply.
+        messages.push({ role: "system", content: [], output_config: { effort: update.effort ?? DEFAULT_EFFORT } })
+        continue
+      }
       if (splitsLocalToolResults(request.messages, index))
         return yield* invalid("Anthropic Messages system updates cannot split a local tool call from its tool result")
       if (supportsNativeSystemUpdates(request) && canUseNativeSystemUpdate(request, index)) {
@@ -1034,18 +1036,11 @@ const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (
     ProviderShared.isRecord(rawOutputConfig) && ProviderShared.isRecord(rawOutputConfig.format)
       ? (rawOutputConfig.format as { type: "json_schema"; schema: Record<string, unknown> })
       : undefined
-  const output_config =
-    outputConfigEffort === undefined && outputConfigFormat === undefined
-      ? undefined
-      : {
-          ...(outputConfigEffort === undefined ? {} : { effort: outputConfigEffort }),
-          ...(outputConfigFormat === undefined ? {} : { format: outputConfigFormat }),
-        }
   const thinking = yield* resolveThinking(input?.thinking)
   return {
     thinking: applyThinkingBindingDefault(request.model, thinking),
     effort: outputConfigEffort,
-    output_config,
+    format: outputConfigFormat,
     service_tier,
     metadata,
     container,
@@ -1054,15 +1049,30 @@ const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (
   }
 })
 
+// Accept gateway namespaces and Vertex suffixes without treating a snapshot date as a minor version.
+const claudeVersion = (id: string) => {
+  const match = /(?:^|[./])claude-(?<family>[a-z]+)-(?<major>\d+)(?:[.-](?<minor>\d{1,2}))?(?:$|[-:@])/.exec(
+    id.toLowerCase(),
+  )?.groups
+  if (!match) return undefined
+  return { family: match.family, major: Number(match.major), minor: Number(match.minor ?? 0) }
+}
+
 const supportsThinkingBlockBinding = (model: LLMRequest["model"]) => {
   const override = model.compatibility?.supportsThinkingBlockBinding
   if (override !== undefined) return override
-  // Accept gateway namespaces and Vertex suffixes without treating a snapshot date as a minor version.
-  const version = /(?:^|[./])claude-[a-z]+-(?<major>\d+)(?:[.-](?<minor>\d{1,2}))?(?:$|[-:@])/i.exec(model.id)?.groups
-  if (!version) return false
-  const major = Number(version.major)
-  const minor = Number(version.minor ?? 0)
-  return major > 5 || (major === 5 && minor >= 1)
+  const version = claudeVersion(model.id)
+  return version !== undefined && (version.major > 5 || (version.major === 5 && version.minor >= 1))
+}
+
+const supportsEffortUpdates = (model: LLMRequest["model"]) => {
+  const override = model.compatibility?.supportsEffortUpdates
+  if (override !== undefined) return override
+  const version = claudeVersion(model.id)
+  if (version === undefined) return false
+  if (version.family === "opus") return version.major >= 5
+  if (version.family !== "fable" && version.family !== "mythos") return false
+  return version.major > 5 || (version.major === 5 && version.minor >= 1)
 }
 
 const applyThinkingBindingDefault = (model: LLMRequest["model"], thinking: AnthropicThinking | undefined) => {
@@ -1104,13 +1114,15 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
   const management = yield* ProviderShared.validateWith(
     Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
   )(request.providerOptions?.contextManagement)
+  const options = yield* resolveOptions(request)
+  const updates = resolveEffortUpdates(request, options.effort)
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   // Allocate the 4-breakpoint budget in invalidation order: tools → system →
   // messages. Tools live highest in the cache hierarchy, so when callers
   // over-mark we keep their tool hints and shed the message-tail ones first.
   const breakpoints = Cache.newBreakpoints(ANTHROPIC_BREAKPOINT_CAP)
-  const flattened = ProviderShared.flattenToolRequest(request)
+  const flattened = ProviderShared.flattenToolRequest(updates.request)
   const tools =
     flattened.tools.length === 0
       ? undefined
@@ -1138,7 +1150,13 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
       `Anthropic Messages: dropped ${breakpoints.dropped} cache breakpoint(s); the API allows at most ${ANTHROPIC_BREAKPOINT_CAP} per request.`,
     )
   }
-  const options = yield* resolveOptions(request)
+  const output_config =
+    updates.effort === undefined && options.format === undefined
+      ? undefined
+      : {
+          ...(updates.effort === undefined ? {} : { effort: updates.effort }),
+          ...(options.format === undefined ? {} : { format: options.format }),
+        }
   const body = {
     model: request.model.id,
     system,
@@ -1152,7 +1170,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     top_k: generation?.topK,
     stop_sequences: generation?.stop,
     thinking: options.thinking,
-    output_config: options.output_config,
+    output_config,
     // top-level passthrough per SDK MessageCreateParamsBase:4638,4643,4649,4654,4670
     cache_control: options.cache_control,
     container: options.container,
@@ -1677,6 +1695,7 @@ export const protocol = Protocol.make({
     }),
     step,
   },
+  supportsEffortUpdates: (request) => supportsEffortUpdates(request.model),
 })
 
 export const transport = <
@@ -1708,13 +1727,19 @@ 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"),
   )
   if (requestsCompaction || replaysCompaction) betas.push("compact-2026-01-12")
 
+  if (body.messages.some((message) => message.role === "system" && message.output_config !== undefined))
+    betas.push("mid-conversation-output-config-2026-07-01")
+
   const thinking = body.thinking
   if (thinking && thinking.type !== "disabled" && thinking.block_binding)
     betas.push("thinking-binding-controls-2026-08-01")

packages/ai/src/protocols/bedrock-converse.ts

@@ -25,6 +25,7 @@ import { BedrockAuth } from "./utils/bedrock-auth.js"
 import { BedrockCache } from "./utils/bedrock-cache.js"
 import { BedrockMedia } from "./utils/bedrock-media.js"
 import { Lifecycle } from "./utils/lifecycle.js"
+import { MistralToolID } from "./utils/mistral-tool-id.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
@@ -106,7 +107,7 @@ type BedrockSystemBlock = Schema.Schema.Type<typeof BedrockSystemBlock>
 const BedrockToolSpec = Schema.Struct({
   toolSpec: Schema.Struct({
     name: Schema.String,
-    description: Schema.String,
+    description: Schema.optional(Schema.String),
     inputSchema: Schema.Struct({
       json: JsonObject,
     }),
@@ -222,7 +223,7 @@ type BedrockEvent = Schema.Schema.Type<typeof BedrockEvent>
 const lowerToolSpec = (tool: ToolDefinition, inputSchema: JsonSchema): BedrockToolSpec => ({
   toolSpec: {
     name: tool.name,
-    description: tool.description,
+    ...(tool.description.trim().length > 0 ? { description: tool.description } : {}),
     inputSchema: { json: inputSchema },
   },
 })
@@ -279,15 +280,19 @@ const removeEmptyToolInputKeys = (input: unknown): unknown => {
   )
 }
 
-const lowerToolCall = (part: ToolCallPart): BedrockToolUseBlock => ({
+const lowerToolCall = (part: ToolCallPart, normalizeID: (id: string) => string): BedrockToolUseBlock => ({
   toolUse: {
-    toolUseId: part.id,
-    name: part.name,
+    toolUseId: normalizeID(part.id),
+    // Models can emit names that Converse rejects when replayed in history.
+    name: part.name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "_",
     input: removeEmptyToolInputKeys(part.input),
   },
 })
 
-const lowerToolResultContent = Effect.fn("BedrockConverse.lowerToolResultContent")(function* (part: ToolResultPart) {
+const lowerToolResultContent = Effect.fn("BedrockConverse.lowerToolResultContent")(function* (
+  part: ToolResultPart,
+  documentNames: Set<string>,
+) {
   if (part.result.type === "text" || part.result.type === "error")
     return [{ text: ProviderShared.toolResultText(part) }]
   if (part.result.type === "json") return [{ json: part.result.value }]
@@ -298,22 +303,21 @@ const lowerToolResultContent = Effect.fn("BedrockConverse.lowerToolResultContent
       content.push({ text: item.text })
       continue
     }
-    const media = yield* BedrockMedia.lower({
-      type: "media",
-      mediaType: item.mime,
-      data: item.uri,
-      filename: item.name,
-    })
-    content.push(media)
+    const media = yield* BedrockMedia.lower(ProviderShared.toolFileMedia(item), documentNames)
+    content.push(...media)
   }
   return content
 })
 
-const lowerToolResult = Effect.fn("BedrockConverse.lowerToolResult")(function* (part: ToolResultPart) {
+const lowerToolResult = Effect.fn("BedrockConverse.lowerToolResult")(function* (
+  part: ToolResultPart,
+  documentNames: Set<string>,
+  normalizeID: (id: string) => string,
+) {
   return {
     toolResult: {
-      toolUseId: part.id,
-      content: yield* lowerToolResultContent(part),
+      toolUseId: normalizeID(part.id),
+      content: yield* lowerToolResultContent(part, documentNames),
       status: part.result.type === "error" ? "error" : "success",
     },
   } satisfies BedrockToolResultBlock
@@ -324,6 +328,9 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
   breakpoints: BedrockCache.Breakpoints,
 ) {
   const messages: BedrockMessage[] = []
+  const documentNames = new Set<string>()
+  // Mistral can reject replay IDs even when they satisfy Converse's broader ID syntax.
+  const normalizeID = request.model.id.includes("mistral.") ? MistralToolID.normalizer(request) : (id: string) => id
   const providerMetadataKey = request.model.route.providerMetadataKey ?? String(request.model.provider)
 
   for (const message of request.messages) {
@@ -347,7 +354,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
           continue
         }
         if (part.type === "media") {
-          content.push(yield* BedrockMedia.lower(part))
+          content.push(...(yield* BedrockMedia.lower(part, documentNames)))
           continue
         }
       }
@@ -388,7 +395,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
           continue
         }
         if (part.type === "tool-call") {
-          content.push(lowerToolCall(part))
+          content.push(lowerToolCall(part, normalizeID))
           continue
         }
       }
@@ -400,7 +407,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
     for (const part of message.content) {
       if (!ProviderShared.supportsContent(part, ["tool-result"]))
         return yield* ProviderShared.unsupportedContent("Bedrock Converse", "tool", ["tool-result"])
-      content.push(yield* lowerToolResult(part))
+      content.push(yield* lowerToolResult(part, documentNames, normalizeID))
       const cachePoint = BedrockCache.block(breakpoints, part.cache)
       if (cachePoint) content.push(cachePoint)
     }

packages/ai/src/protocols/gemini.ts

@@ -19,6 +19,7 @@ import {
   type ToolDefinition,
 } from "../schema/index.js"
 import { classifyProviderFailure } from "../provider-error.js"
+import { Media } from "../media.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { GeminiToolSchema } from "./utils/gemini-tool-schema.js"
 import { Lifecycle } from "./utils/lifecycle.js"
@@ -100,9 +101,18 @@ const GeminiInlineDataPart = Schema.Struct({
     mimeType: Schema.String,
     data: Schema.String,
   }),
+  thoughtSignature: optionalNull(Schema.String),
 })
 type GeminiInlineDataPart = Schema.Schema.Type<typeof GeminiInlineDataPart>
 
+/** Gemini Files API reference; the only remote input Gemini accepts. */
+const GeminiFileDataPart = Schema.Struct({
+  fileData: Schema.Struct({
+    mimeType: Schema.String,
+    fileUri: Schema.String,
+  }),
+})
+
 const GeminiFunctionCallPart = Schema.Struct({
   functionCall: Schema.Struct({
     id: optionalNull(Schema.String),
@@ -124,6 +134,7 @@ const GeminiFunctionResponsePart = Schema.Struct({
 const GeminiContentPart = Schema.Union([
   GeminiTextPart,
   GeminiInlineDataPart,
+  GeminiFileDataPart,
   GeminiFunctionCallPart,
   GeminiFunctionResponsePart,
 ])
@@ -287,9 +298,13 @@ const lowerToolConfig = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
     tool: (name) => ({ functionCallingConfig: { mode: "ANY" as const, allowedFunctionNames: [name] } }),
   })
 
-const lowerUserPart = Effect.fn("Gemini.lowerUserPart")(function* (part: TextPart | MediaPart) {
+// Gemini does not fetch public URLs; inline payloads and Gemini Files references are the accepted inputs.
+const lowerContentPart = Effect.fn("Gemini.lowerContentPart")(function* (part: TextPart | MediaPart) {
   if (part.type === "text") return { text: part.text }
-  const media = ProviderShared.normalizeMedia(part)
+  const source = part.media.source
+  if (source.type === "ref" && source.provider === "google")
+    return { fileData: { mimeType: part.media.mediaType, fileUri: source.id } }
+  const media = yield* ProviderShared.requireInlineMedia("Gemini", part.media)
   return { inlineData: { mimeType: media.mime, data: media.base64 } }
 })
 
@@ -337,7 +352,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       for (const part of message.content) {
         if (!ProviderShared.supportsContent(part, ["text", "media"]))
           return yield* ProviderShared.unsupportedContent("Gemini", "user", ["text", "media"])
-        parts.push(yield* lowerUserPart(part))
+        parts.push(yield* lowerContentPart(part))
       }
       contents.push({ role: "user", parts })
       continue
@@ -348,12 +363,23 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       // Parallel Gemini 3 calls may carry one signature on the first call; unsigned sibling calls are valid.
       let hasSignedToolCall = false
       for (const part of message.content) {
-        if (!ProviderShared.supportsContent(part, ["text", "reasoning", "tool-call"]))
-          return yield* ProviderShared.unsupportedContent("Gemini", "assistant", ["text", "reasoning", "tool-call"])
+        if (!ProviderShared.supportsContent(part, ["text", "reasoning", "tool-call", "media"]))
+          return yield* ProviderShared.unsupportedContent("Gemini", "assistant", [
+            "text",
+            "reasoning",
+            "tool-call",
+            "media",
+          ])
         if (part.type === "text") {
           parts.push({ text: part.text, thoughtSignature: thoughtSignature(part.providerMetadata, metadataKey) })
           continue
         }
+        // Generated images replay as model-role inline data so multi-turn image editing keeps the prior output.
+        if (part.type === "media") {
+          const lowered = yield* lowerContentPart(part)
+          parts.push({ ...lowered, thoughtSignature: thoughtSignature(part.providerMetadata, metadataKey) })
+          continue
+        }
         if (part.type === "reasoning") {
           parts.push({
             text: part.text,
@@ -403,7 +429,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       const media: GeminiInlineDataPart[] = []
       for (const item of content) {
         if (item.type === "text") continue
-        const value = ProviderShared.normalizeToolFile(item)
+        const value = yield* ProviderShared.requireInlineMedia("Gemini", ProviderShared.toolFileMedia(item).media)
         media.push({ inlineData: { mimeType: value.mime, data: value.base64 } })
       }
       if (legacyToolMedia && media.length > 0) (pendingMedia ??= []).push(...media)
@@ -685,6 +711,19 @@ const step = (state: ParserState, event: GeminiEvent) => {
     // each block kind must retain the signature attached to its own parts.
     if (signature !== undefined && "thought" in part && part.thought) reasoningSignature = signature
     else if (signature !== undefined && "text" in part) textSignature = signature
+    // Image-capable Gemini models return generated images as inline data parts; surface them as first-class output.
+    if ("inlineData" in part) {
+      lifecycle = Lifecycle.stepStart(lifecycle, events)
+      events.push(
+        LLMEvent.media({
+          media: Media.base64(part.inlineData.data, part.inlineData.mimeType),
+          providerMetadata: signature
+            ? providerMetadata(state.providerMetadataKey, { thoughtSignature: signature })
+            : undefined,
+        }),
+      )
+      continue
+    }
     if ("text" in part && part.text.length > 0) {
       if (part.thought) {
         if (textId !== undefined) {

packages/ai/src/protocols/google-images.ts

@@ -1,40 +1,36 @@
-import { Effect, Encoding, Schema } from "effect"
-import { Headers, HttpClientRequest } from "effect/unstable/http"
-import {
-  GeneratedImage,
-  ImageModel,
-  ImageResponse,
-  type ImageInput,
-  type ImageRequestFor,
-  type ImageRoute,
-} from "../image.js"
-import { Auth, type Definition as AuthDefinition } from "../route/auth.js"
-import { AIError, Usage, mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema/index.js"
+import { Effect, Schema } from "effect"
+import type { HttpClientResponse } from "effect/unstable/http"
+import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
+import { Media } from "../media.js"
+import { MediaProtocol } from "../route/media-protocol.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, mergeJsonRecords, type AIError } from "../schema/index.js"
 import { ProviderShared } from "./shared.js"
-import { ImageInputs } from "./utils/image-input.js"
+import { MediaInput } from "./utils/media-input.js"
 
 const ADAPTER = "google-images"
+const NAME = "Google Images"
+const PROVIDER = ProviderID.make("google")
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 
+// ---------------------------------------------------------------------------
+// 1. Public model input
+// ---------------------------------------------------------------------------
+
 export type GoogleImageString<Known extends string> = Known | (string & {})
 
+/** Provider-native options. Common fields (`aspectRatio`, `seed`, `images`) live on the request. */
 export type GoogleImageOptions = {
-  readonly aspectRatio?: GoogleImageString<
-    "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9"
-  >
   readonly imageSize?: GoogleImageString<"1K" | "2K" | "4K">
-  readonly seed?: number
   readonly thinkingLevel?: GoogleImageString<"MINIMAL" | "LOW" | "MEDIUM" | "HIGH">
   readonly includeThoughts?: boolean
 } & Record<string, unknown>
 
-export type GoogleImageBody = Record<string, unknown> & {
-  readonly contents: ReadonlyArray<{
-    readonly role: "user"
-    readonly parts: ReadonlyArray<Record<string, unknown>>
-  }>
-  readonly generationConfig: Record<string, unknown>
-}
+export type Request = ImageRequestFor<GoogleImageOptions>
+
+// ---------------------------------------------------------------------------
+// 2. Response schema
+// ---------------------------------------------------------------------------
 
 const GoogleUsage = Schema.StructWithRest(
   Schema.Struct({
@@ -85,30 +81,20 @@ const GoogleImageResponse = Schema.Struct({
   promptFeedback: Schema.optional(Schema.Unknown),
 })
 
-export interface ModelInput {
-  readonly id: string
-  readonly auth: AuthDefinition
-  readonly baseURL?: string
-  readonly headers?: Record<string, string>
-  readonly http?: HttpOptions
-}
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
 
-const nativeOptions = (options: GoogleImageOptions | undefined) => {
-  const { aspectRatio, imageSize, seed, thinkingLevel, includeThoughts, ...native } = options ?? {}
-  const image = {
-    aspectRatio,
-    imageSize,
-  }
-  const thinkingConfig = {
-    thinkingLevel,
-    includeThoughts,
-  }
+const generationConfig = (request: Request) => {
+  const { imageSize, thinkingLevel, includeThoughts, ...native } = request.providerOptions ?? {}
+  const imageConfig = { aspectRatio: request.aspectRatio, imageSize }
+  const thinkingConfig = { thinkingLevel, includeThoughts }
   return (
     mergeJsonRecords(
       {
         responseModalities: ["IMAGE"],
-        imageConfig: Object.values(image).some((value) => value !== undefined) ? image : undefined,
-        seed,
+        imageConfig: Object.values(imageConfig).some((value) => value !== undefined) ? imageConfig : undefined,
+        seed: request.seed,
         thinkingConfig: Object.values(thinkingConfig).some((value) => value !== undefined) ? thinkingConfig : undefined,
       },
       native,
@@ -116,176 +102,208 @@ const nativeOptions = (options: GoogleImageOptions | undefined) => {
   )
 }
 
-const applyQuery = (url: string, query: Record<string, string> | undefined) => {
-  if (!query) return url
-  const next = new URL(url)
-  Object.entries(query).forEach(([key, value]) => next.searchParams.set(key, value))
-  return next.toString()
-}
-
-export const model = (input: ModelInput) => {
-  const route: ImageRoute<GoogleImageOptions> = {
-    id: ADAPTER,
-    generate: Effect.fn("GoogleImages.generate")(function* (request: ImageRequestFor<GoogleImageOptions>, execute) {
-      const imageParts = yield* Effect.forEach(request.images ?? [], googleImagePart)
-      const http = mergeHttpOptions(request.model.http, request.http)
-      const requestBody = mergeJsonRecords(
-        {
-          contents: [{ role: "user", parts: [{ text: request.prompt }, ...imageParts] }],
-          generationConfig: nativeOptions(request.options),
-        },
-        http?.body,
-      ) as GoogleImageBody
-      const text = ProviderShared.encodeJson(requestBody)
-      const url = applyQuery(
-        `${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}/models/${request.model.id}:generateContent`,
-        http?.query,
-      )
-      const headers = yield* Auth.toEffect(input.auth)({
-        request,
-        method: "POST",
-        url,
-        body: text,
-        headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
-      })
-      const response = yield* execute(
-        HttpClientRequest.post(url).pipe(
-          HttpClientRequest.setHeaders(headers),
-          HttpClientRequest.bodyText(text, "application/json"),
-        ),
-      )
-      const output = yield* ProviderShared.imageResponse(ADAPTER, "Google Images", response)
-      const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(GoogleImageResponse))(output.body).pipe(
-        Effect.mapError((cause) => output.invalid("Google Images returned an invalid response", cause)),
-      )
-      const candidates = decoded.candidates ?? []
-      const candidateMetadata = candidates.map((candidate, candidateIndex) => ({
-        index: candidate.index ?? candidateIndex,
-        finishReason: candidate.finishReason,
-        finishMessage: candidate.finishMessage,
-        safetyRatings: candidate.safetyRatings,
-        citationMetadata: candidate.citationMetadata,
-        groundingMetadata: candidate.groundingMetadata,
-        parts: (candidate.content?.parts ?? []).map((part) =>
-          part.inlineData === undefined
-            ? {
-                type: "text",
-                text: part.text,
-                thought: part.thought,
-                thoughtSignature: part.thoughtSignature,
-              }
-            : {
-                type: "inlineData",
-                mediaType: part.inlineData.mimeType,
-                thought: part.thought,
-                thoughtSignature: part.thoughtSignature,
-              },
-        ),
-      }))
-      const encoded = candidates.flatMap((candidate, candidateIndex) =>
-        (candidate.content?.parts ?? []).flatMap((part, partIndex) =>
-          part.inlineData === undefined || part.thought === true
-            ? []
-            : [{ candidate, candidateIndex, partIndex, inlineData: part.inlineData }],
-        ),
-      )
-      const images = yield* Effect.forEach(encoded, (item) =>
-        Effect.fromResult(Encoding.decodeBase64(item.inlineData.data)).pipe(
-          Effect.mapError((cause) =>
-            output.invalid(
-              `Google Images candidate ${item.candidateIndex} part ${item.partIndex} contains invalid base64 data`,
-              cause,
-            ),
-          ),
-          Effect.map(
-            (data) =>
-              new GeneratedImage({
-                mediaType: item.inlineData.mimeType,
-                data,
-                providerMetadata: {
-                  google: {
-                    candidateIndex: item.candidate.index ?? item.candidateIndex,
-                    partIndex: item.partIndex,
-                    finishReason: item.candidate.finishReason,
-                    safetyRatings: item.candidate.safetyRatings,
-                    citationMetadata: item.candidate.citationMetadata,
-                    groundingMetadata: item.candidate.groundingMetadata,
-                    thoughtSignature: item.candidate.content?.parts[item.partIndex]?.thoughtSignature,
-                  },
-                },
-              }),
-          ),
-        ),
-      )
-      if (images.length === 0) {
-        const finishReasons = candidates.flatMap((candidate) =>
-          candidate.finishReason === undefined ? [] : [candidate.finishReason],
-        )
-        return yield* output.invalid(
-          `Google Images returned no final images${
-            finishReasons.length === 0 ? "" : ` (finish reasons: ${finishReasons.join(", ")})`
-          }; inspect body for prompt feedback and candidate details`,
-        )
-      }
-      const usage = decoded.usageMetadata
-      const outputTokens =
-        usage?.candidatesTokenCount === undefined
-          ? undefined
-          : usage.candidatesTokenCount + (usage.thoughtsTokenCount ?? 0)
-      return new ImageResponse({
-        images,
-        usage:
-          usage === undefined
-            ? undefined
-            : new Usage({
-                inputTokens: usage.promptTokenCount,
-                outputTokens,
-                nonCachedInputTokens: ProviderShared.subtractTokens(
-                  usage.promptTokenCount,
-                  usage.cachedContentTokenCount,
-                ),
-                cacheReadInputTokens: usage.cachedContentTokenCount,
-                reasoningTokens: usage.thoughtsTokenCount,
-                totalTokens: ProviderShared.totalTokens(usage.promptTokenCount, outputTokens, usage.totalTokenCount),
-                providerMetadata: { google: usage },
-              }),
-        providerMetadata: {
-          google: {
-            modelVersion: decoded.modelVersion,
-            responseId: decoded.responseId,
-            promptFeedback: decoded.promptFeedback,
-            candidates: candidateMetadata,
-          },
-        },
-      })
-    }),
-  }
-  return ImageModel.make<GoogleImageOptions>({ id: input.id, provider: "google", route, http: input.http })
-}
-
-const googleImagePart = (image: ImageInput): Effect.Effect<Record<string, unknown>, AIError> => {
-  if (image.type === "bytes")
-    return Effect.succeed({ inlineData: { mimeType: image.mediaType, data: Encoding.encodeBase64(image.data) } })
-  if (image.type === "file-uri") return Effect.succeed({ fileData: { mimeType: image.mediaType, fileUri: image.uri } })
-  if (image.type === "url")
-    return ImageInputs.decodeDataUrl(image.url).pipe(
-      Effect.flatMap((decoded) => {
-        if (decoded === undefined)
-          return Effect.fail(
-            ImageInputs.invalid(
-              "Google generateContent does not fetch public image URLs; use bytes, a data URL, or a Gemini file URI",
-            ),
-          )
-        return Effect.succeed({
-          inlineData: { mimeType: decoded.mediaType, data: Encoding.encodeBase64(decoded.data) },
-        })
-      }),
+// Gemini does not fetch public URLs; inline payloads or Gemini Files references are the only accepted inputs.
+const imagePart = (asset: Media.Asset): Effect.Effect<Record<string, unknown>, AIError> => {
+  const inline = asset.inline()
+  if (inline) return Effect.succeed({ inlineData: { mimeType: inline.mime, data: inline.base64 } })
+  const id = MediaInput.refID(asset, PROVIDER)
+  if (id) return Effect.succeed({ fileData: { mimeType: asset.mediaType, fileUri: id } })
+  if (asset.source.type === "ref")
+    return Effect.fail(
+      ProviderShared.invalidRequest(
+        "Google generateContent requires Gemini file references rather than other providers' file IDs",
+      ),
     )
   return Effect.fail(
-    ImageInputs.invalid("Google generateContent requires Gemini file URIs rather than provider file IDs"),
+    ProviderShared.invalidRequest(
+      "Google generateContent does not fetch public image URLs; use bytes, a data URL, or a Gemini file reference",
+    ),
   )
 }
 
+const fromRequest = Effect.fn("GoogleImages.fromRequest")(function* (request: Request) {
+  if (request.n !== undefined && request.n > 1)
+    return yield* ProviderShared.unsupportedOperation({
+      operation: "image.n",
+      provider: PROVIDER,
+      route: ADAPTER,
+      message: `${NAME} generates one image per request; call it once per image instead of n=${request.n}`,
+    })
+  const parts = yield* Effect.forEach(request.images ?? [], imagePart)
+  return MediaProtocol.json(
+    mergeJsonRecords(
+      {
+        contents: [{ role: "user", parts: [{ text: request.prompt }, ...parts] }],
+        generationConfig: generationConfig(request),
+      },
+      request.http?.body,
+    ) ?? {},
+  )
+})
+
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+
+const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
+  response: HttpClientResponse.HttpClientResponse,
+) {
+  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, GoogleImageResponse)(response)
+  const decoded = output.value
+  const candidates = decoded.candidates ?? []
+  const candidateMetadata = candidates.map((candidate, candidateIndex) => ({
+    index: candidate.index ?? candidateIndex,
+    finishReason: candidate.finishReason,
+    finishMessage: candidate.finishMessage,
+    safetyRatings: candidate.safetyRatings,
+    citationMetadata: candidate.citationMetadata,
+    groundingMetadata: candidate.groundingMetadata,
+    parts: (candidate.content?.parts ?? []).map((part) =>
+      part.inlineData === undefined
+        ? { type: "text", text: part.text, thought: part.thought, thoughtSignature: part.thoughtSignature }
+        : {
+            type: "inlineData",
+            mediaType: part.inlineData.mimeType,
+            thought: part.thought,
+            thoughtSignature: part.thoughtSignature,
+          },
+    ),
+  }))
+  // Thought parts are drafts; only non-thought inline data is a final image.
+  const encoded = candidates.flatMap((candidate, candidateIndex) =>
+    (candidate.content?.parts ?? []).flatMap((part, partIndex) =>
+      part.inlineData === undefined || part.thought === true
+        ? []
+        : [
+            {
+              candidate,
+              candidateIndex,
+              partIndex,
+              inlineData: part.inlineData,
+              thoughtSignature: part.thoughtSignature,
+            },
+          ],
+    ),
+  )
+  const images = yield* Effect.forEach(encoded, (item) =>
+    MediaInput.decodedAsset(
+      output.invalid,
+      `${NAME} candidate ${item.candidateIndex} part ${item.partIndex}`,
+      item.inlineData.data,
+      item.inlineData.mimeType,
+      {
+        providerMetadata: {
+          google: {
+            candidateIndex: item.candidate.index ?? item.candidateIndex,
+            partIndex: item.partIndex,
+            finishReason: item.candidate.finishReason,
+            safetyRatings: item.candidate.safetyRatings,
+            citationMetadata: item.candidate.citationMetadata,
+            groundingMetadata: item.candidate.groundingMetadata,
+            thoughtSignature: item.thoughtSignature,
+          },
+        },
+      },
+    ),
+  )
+  if (images.length === 0) {
+    const finishReasons = candidates.flatMap((candidate) =>
+      candidate.finishReason === undefined ? [] : [candidate.finishReason],
+    )
+    return yield* output.invalid(
+      `${NAME} returned no final images${
+        finishReasons.length === 0 ? "" : ` (finish reasons: ${finishReasons.join(", ")})`
+      }; inspect body for prompt feedback and candidate details`,
+    )
+  }
+  // Candidates that stopped for a safety or policy reason are partial results, not a silent drop.
+  const notices = [
+    ...(decoded.promptFeedback === undefined
+      ? []
+      : [
+          {
+            type: "filtered" as const,
+            message: `${NAME} reported prompt feedback`,
+            providerMetadata: { google: { promptFeedback: decoded.promptFeedback } },
+          },
+        ]),
+    ...candidates.flatMap((candidate, index) =>
+      candidate.finishReason === undefined || candidate.finishReason === "STOP"
+        ? []
+        : [
+            {
+              type: "filtered" as const,
+              message: `${NAME} candidate ${candidate.index ?? index} finished with ${candidate.finishReason}${
+                candidate.finishMessage === undefined ? "" : `: ${candidate.finishMessage}`
+              }`,
+              providerMetadata: {
+                google: {
+                  candidateIndex: candidate.index ?? index,
+                  finishReason: candidate.finishReason,
+                  finishMessage: candidate.finishMessage,
+                  safetyRatings: candidate.safetyRatings,
+                },
+              },
+            },
+          ],
+    ),
+  ]
+  const usage = decoded.usageMetadata
+  const outputTokens =
+    usage?.candidatesTokenCount === undefined ? undefined : usage.candidatesTokenCount + (usage.thoughtsTokenCount ?? 0)
+  return new ImageResponse({
+    images,
+    notices: notices.length === 0 ? undefined : notices,
+    usage:
+      usage === undefined
+        ? undefined
+        : {
+            type: "tokens",
+            input: usage.promptTokenCount,
+            output: outputTokens,
+            total: ProviderShared.totalTokens(usage.promptTokenCount, outputTokens, usage.totalTokenCount),
+            details: {
+              reasoningTokens: usage.thoughtsTokenCount,
+              cacheReadInputTokens: usage.cachedContentTokenCount,
+              google: usage,
+            },
+          },
+    providerMetadata: {
+      google: {
+        modelVersion: decoded.modelVersion,
+        responseId: decoded.responseId,
+        promptFeedback: decoded.promptFeedback,
+        candidates: candidateMetadata,
+      },
+    },
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+
+export const protocol = MediaProtocol.inline<Request, ImageResponse>({
+  id: ADAPTER,
+  name: NAME,
+  unsupported: ["mask", "size", "format"],
+  body: { from: fromRequest },
+  response: { decode: decodeResponse },
+})
+
+export const model = (input: MediaRoute.ModelInput) =>
+  ImageModel.fromRoute<GoogleImageOptions>(
+    {
+      id: ADAPTER,
+      provider: PROVIDER,
+      protocol,
+      baseURL: DEFAULT_BASE_URL,
+      path: ({ request }) => `/models/${request.model.id}:generateContent`,
+    },
+    input,
+  )
+
 export const GoogleImages = {
+  protocol,
   model,
 } as const

packages/ai/src/protocols/meta-images.ts

@@ -1,17 +1,25 @@
-import { Effect, Encoding, Schema } from "effect"
-import { Headers, HttpClientRequest } from "effect/unstable/http"
-import { GeneratedImage, ImageModel, ImageResponse, type ImageRequestFor, type ImageRoute } from "../image.js"
-import { Auth } from "../route/auth.js"
-import { Usage, mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema/index.js"
+import { Effect, Schema } from "effect"
+import type { HttpClientResponse } from "effect/unstable/http"
+import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
+import { Media } from "../media.js"
+import { MediaProtocol } from "../route/media-protocol.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, mergeJsonRecords, type AIError } from "../schema/index.js"
 import { JsonObject, ProviderShared, optionalNull } from "./shared.js"
-import { ImageInputs } from "./utils/image-input.js"
+import { MediaInput } from "./utils/media-input.js"
+
+const ADAPTER = "meta-images"
+const NAME = "Meta Images"
+const PROVIDER = ProviderID.make("meta")
+
+// ---------------------------------------------------------------------------
+// 1. Public model input
+// ---------------------------------------------------------------------------
 
 type OpenString<Known extends string> = Known | (string & {})
+
+/** Provider-native options. Common fields (`n`, `size`, `format`, `images`) live on the request. */
 export type ImageOptions = {
-  readonly n?: number
-  /** Aspect ratio hint, not an exact output resolution. */
-  readonly size?: string
-  readonly outputFormat?: OpenString<"webp" | "png" | "jpeg">
   readonly responseFormat?: OpenString<"b64_json" | "url">
   readonly reasoningStrength?: OpenString<"low" | "high">
   readonly toolEnablement?: {
@@ -22,12 +30,19 @@ export type ImageOptions = {
   readonly [key: string]: unknown
 }
 
+export type Request = ImageRequestFor<ImageOptions>
+
+// ---------------------------------------------------------------------------
+// 2. Request body and response schemas
+// ---------------------------------------------------------------------------
+
 const Body = Schema.StructWithRest(
   Schema.Struct({
     model: Schema.String,
     prompt: Schema.String,
     images: Schema.optional(Schema.Array(JsonObject)),
     n: Schema.optional(Schema.Number),
+    /** Aspect ratio hint, not an exact output resolution. */
     size: Schema.optional(Schema.String),
     output_format: Schema.optional(Schema.String),
     response_format: Schema.optional(Schema.String),
@@ -49,85 +64,102 @@ const Response = Schema.Struct({
   ),
 })
 
-export const model = (input: {
-  readonly id: string
-  readonly auth: Auth.Definition
-  readonly baseURL: string
-  readonly headers?: Record<string, string>
-  readonly http?: HttpOptions
-}) => {
-  const route: ImageRoute<ImageOptions> = {
-    id: "meta-images",
-    generate: Effect.fn("MetaImages.generate")(function* (request: ImageRequestFor<ImageOptions>, execute) {
-      const http = mergeHttpOptions(request.model.http, request.http)
-      const images = yield* Effect.forEach(request.images ?? [], (image) => {
-        if (image.type === "bytes") return Effect.succeed({ image_url: ImageInputs.dataUrl(image) })
-        if (image.type === "url") return Effect.succeed({ image_url: image.url })
-        return ImageInputs.invalid("Meta Images accepts image bytes and URLs")
-      })
-      const { outputFormat, responseFormat, reasoningStrength, toolEnablement, ...native } = request.options ?? {}
-      const payload = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Body))(
-        mergeJsonRecords(
-          {
-            model: request.model.id,
-            prompt: request.prompt,
-            images: images.length === 0 ? undefined : images,
-            output_format: outputFormat,
-            response_format: responseFormat,
-            reasoning_strength: reasoningStrength,
-            tool_enablement: toolEnablement,
-          },
-          native,
-          http?.body,
-        ),
-      )
-      const body = ProviderShared.encodeJson(payload)
-      const url = new URL(`${input.baseURL.replace(/\/$/, "")}/images/${images.length === 0 ? "generations" : "edits"}`)
-      Object.entries(http?.query ?? {}).forEach(([key, value]) => url.searchParams.set(key, value))
-      const headers = yield* Auth.toEffect(input.auth)({
-        request,
-        method: "POST",
-        url: url.toString(),
-        body,
-        headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
-      })
-      const response = yield* execute(
-        HttpClientRequest.post(url.toString()).pipe(
-          HttpClientRequest.setHeaders(headers),
-          HttpClientRequest.bodyText(body, "application/json"),
-        ),
-      )
-      const output = yield* ProviderShared.imageResponse("meta-images", "Meta Images", response)
-      const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Response))(output.body).pipe(
-        Effect.mapError((cause) => output.invalid("Meta Images returned an invalid response", cause)),
-      )
-      const format = decoded.output_format ?? payload.output_format ?? "webp"
-      const generated = yield* Effect.forEach(decoded.data, (item, index) => {
-        if (item.b64_json)
-          return Effect.fromResult(Encoding.decodeBase64(item.b64_json)).pipe(
-            Effect.mapError((cause) => output.invalid(`Meta Images result ${index} contains invalid base64`, cause)),
-            Effect.map((data) => new GeneratedImage({ mediaType: `image/${format}`, data })),
-          )
-        if (item.url) return Effect.succeed(new GeneratedImage({ mediaType: `image/${format}`, data: item.url }))
-        return output.invalid(`Meta Images result ${index} has neither image data nor a URL`)
-      })
-      if (generated.length === 0) return yield* output.invalid("Meta Images returned no images")
-      return new ImageResponse({
-        images: generated,
-        usage:
-          decoded.usage === undefined
-            ? undefined
-            : new Usage({
-                inputTokens: decoded.usage.input_tokens,
-                outputTokens: decoded.usage.output_tokens,
-                totalTokens: decoded.usage.total_tokens,
-                providerMetadata: { meta: decoded.usage },
-              }),
-        providerMetadata: { meta: { outputFormat: format } },
-      })
-    }),
-  }
-  return ImageModel.make<ImageOptions>({ id: input.id, provider: "meta", route, http: input.http })
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
+
+const isEdit = (request: Request) => (request.images?.length ?? 0) > 0
+
+const reference = (asset: Media.Asset): Effect.Effect<Record<string, unknown>, AIError> => {
+  const inline = asset.inline()
+  if (inline) return Effect.succeed({ image_url: inline.dataUrl })
+  const url = ProviderShared.mediaUrl(asset)
+  if (url) return Effect.succeed({ image_url: url })
+  return Effect.fail(ProviderShared.invalidRequest(`${NAME} accepts image bytes and URLs`))
 }
 
+const fromRequest = Effect.fn("MetaImages.fromRequest")(function* (request: Request) {
+  const images = yield* Effect.forEach(request.images ?? [], reference)
+  const { responseFormat, reasoningStrength, toolEnablement, ...native } = request.providerOptions ?? {}
+  const payload = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Body))(
+    mergeJsonRecords(
+      {
+        model: request.model.id,
+        prompt: request.prompt,
+        images: images.length === 0 ? undefined : images,
+        n: request.n,
+        size: request.size,
+        output_format: request.format,
+        response_format: responseFormat,
+        reasoning_strength: reasoningStrength,
+        tool_enablement: toolEnablement,
+      },
+      native,
+      request.http?.body,
+    ),
+  )
+  return MediaProtocol.json(payload)
+})
+
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+
+const decodeResponse = Effect.fn("MetaImages.decodeResponse")(function* (
+  response: HttpClientResponse.HttpClientResponse,
+  context: MediaProtocol.DecodeContext<Request>,
+) {
+  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, Response)(response)
+  const decoded = output.value
+  const requested = context.body.type === "json" ? context.body.value.output_format : undefined
+  const format = decoded.output_format ?? (typeof requested === "string" ? requested : "webp")
+  const mediaType = `image/${format}`
+  const images = yield* Effect.forEach(decoded.data, (item, index) => {
+    if (item.b64_json)
+      return MediaInput.decodedAsset(output.invalid, `${NAME} result ${index}`, item.b64_json, mediaType, {
+        info: { format },
+      })
+    if (item.url) return Effect.succeed(Media.url(item.url, { mediaType, info: { format } }))
+    return Effect.fail(output.invalid(`${NAME} result ${index} has neither image data nor a URL`))
+  })
+  if (images.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  return new ImageResponse({
+    images,
+    usage:
+      decoded.usage === undefined
+        ? undefined
+        : {
+            type: "tokens",
+            input: decoded.usage.input_tokens,
+            output: decoded.usage.output_tokens,
+            total: decoded.usage.total_tokens,
+            details: { meta: decoded.usage },
+          },
+    providerMetadata: { meta: { outputFormat: format } },
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+
+export const protocol = MediaProtocol.inline<Request, ImageResponse>({
+  id: ADAPTER,
+  name: NAME,
+  unsupported: ["mask", "aspectRatio", "seed"],
+  body: { from: fromRequest },
+  response: { decode: decodeResponse },
+})
+
+export const model = (input: MediaRoute.ModelInput & { readonly baseURL: string }) =>
+  ImageModel.fromRoute<ImageOptions>(
+    {
+      id: ADAPTER,
+      provider: PROVIDER,
+      protocol,
+      path: ({ request }) => `/images/${isEdit(request) ? "edits" : "generations"}`,
+    },
+    input,
+  )
+
 export * as MetaImages from "./meta-images.js"

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

@@ -21,11 +21,11 @@ import {
 import { classifyProviderFailure } from "../provider-error.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { Lifecycle } from "./utils/lifecycle.js"
+import { MistralToolID } from "./utils/mistral-tool-id.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "mistral-chat"
 const DONE = "[DONE]" as const
-const TOOL_ID = /^[A-Za-z0-9]{9}$/
 export const DEFAULT_BASE_URL = "https://api.mistral.ai/v1"
 export const PATH = "/chat/completions"
 
@@ -223,40 +223,14 @@ const MistralEvent = Schema.StructWithRest(
 type MistralEvent = Schema.Schema.Type<typeof MistralEvent>
 const MistralStreamEvent = Schema.Union([Schema.Literal(DONE), Protocol.jsonEvent(MistralEvent)])
 
-const hashID = (value: string) => {
-  const hash = (seed: number) => {
-    let result = seed
-    for (const char of value) result = Math.imul(result ^ char.charCodeAt(0), 16777619)
-    return (result >>> 0).toString(36)
-  }
-  return `${hash(2166136261).padStart(7, "0")}${hash(2246822519).padStart(7, "0")}`.slice(-9)
-}
-
-const toolIDNormalizer = (request: LLMRequest) => {
-  const ids = request.messages.flatMap((message) =>
-    message.content.flatMap((part) => (part.type === "tool-call" || part.type === "tool-result" ? [part.id] : [])),
-  )
-  const used = new Set(ids.filter((id) => TOOL_ID.test(id)))
-  const normalized = new Map<string, string>()
-  return (id: string) => {
-    if (TOOL_ID.test(id)) return id
-    const previous = normalized.get(id)
-    if (previous) return previous
-    let attempt = 0
-    let candidate = hashID(id)
-    while (used.has(candidate)) candidate = hashID(`${id}:${++attempt}`)
-    used.add(candidate)
-    normalized.set(id, candidate)
-    return candidate
-  }
-}
-
 const lowerMedia = Effect.fn("MistralChat.lowerMedia")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
-  const url = typeof part.data === "string" && /^(?:https?:|data:)/.test(part.data) ? part.data : media.dataUrl
-  if (media.mime.startsWith("image/")) return { type: "image_url" as const, image_url: url }
-  if (media.mime === "application/pdf") return { type: "document_url" as const, document_url: url }
-  return yield* ProviderShared.invalidRequest(`Mistral Chat does not support media type ${part.mediaType}`)
+  const mime = part.media.mediaType.toLowerCase()
+  const url =
+    ProviderShared.mediaUrl(part.media) ??
+    (yield* ProviderShared.requireInlineMedia("Mistral Chat", part.media)).dataUrl
+  if (mime.startsWith("image/")) return { type: "image_url" as const, image_url: url }
+  if (mime === "application/pdf") return { type: "document_url" as const, document_url: url }
+  return yield* ProviderShared.invalidRequest(`Mistral Chat does not support media type ${part.media.mediaType}`)
 })
 
 const lowerUser = Effect.fn("MistralChat.lowerUser")(function* (message: LLMRequest["messages"][number]) {
@@ -344,7 +318,7 @@ const lowerToolResults = Effect.fn("MistralChat.lowerToolResults")(function* (
         content.push({ type: "text", text: item.text })
         continue
       }
-      content.push(yield* lowerMedia({ type: "media", mediaType: item.mime, data: item.uri, filename: item.name }))
+      content.push(yield* lowerMedia(ProviderShared.toolFileMedia(item)))
     }
     output.push({
       role: "tool",
@@ -359,7 +333,7 @@ const lowerToolResults = Effect.fn("MistralChat.lowerToolResults")(function* (
 })
 
 const lowerMessages = Effect.fn("MistralChat.lowerMessages")(function* (request: LLMRequest) {
-  const normalizeID = toolIDNormalizer(request)
+  const normalizeID = MistralToolID.normalizer(request)
   const messages: MistralMessage[] =
     request.system.length === 0 ? [] : [{ role: "system", content: ProviderShared.joinText(request.system) }]
   for (const message of request.messages) {
@@ -582,13 +556,13 @@ const appendContent = (
 }
 
 const normalizeStreamToolID = (state: ParserState, source: string) => {
-  if (TOOL_ID.test(source))
+  if (MistralToolID.valid.test(source))
     return { id: source, state: { ...state, usedToolIDs: new Set([...state.usedToolIDs, source]) } }
   const previous = state.toolIDs.get(source)
   if (previous) return { id: previous, state }
   let attempt = 0
-  let id = hashID(source)
-  while (state.usedToolIDs.has(id)) id = hashID(`${source}:${++attempt}`)
+  let id = MistralToolID.hash(source)
+  while (state.usedToolIDs.has(id)) id = MistralToolID.hash(`${source}:${++attempt}`)
   return {
     id,
     state: {

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,10 +163,15 @@ export const transport = <Body>(options: Options): Transport<Body, Prepared, str
                     request: create.request,
                     message: create.message,
                     base,
+                    continuation: options.continuation,
                   }),
                 }
               })
             : undefined
+        if (input.webSocket && !channel)
+          yield* Effect.logWarning(`${options.name} does not offer WebSocket for this endpoint; using HTTP`, {
+            url: parts.url,
+          })
         return {
           http: {
             request: ProviderShared.jsonPost({ url: parts.url, body: parts.bodyText, headers: parts.headers }),

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),
           ),
@@ -181,7 +191,7 @@ export const driver = (input: DriverInput): WebSocketChannelDriver => {
               responseID,
               request,
               // Completion can re-encrypt reasoning. Callers replay the item already emitted by output_item.done.
-              output: event.response?.output
+              output: event.response?.output?.length
                 ? event.response.output.map((item) =>
                     item.type === "reasoning" && item.id !== undefined
                       ? (output.find((done) => done.type === item.type && done.id === item.id) ?? item)
@@ -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"
@@ -18,8 +18,10 @@ import {
   type ToolDefinition,
   type ToolResultPart,
 } from "../schema/index.js"
+import type { Media } from "../media.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { classifyProviderFailure } from "../provider-error.js"
+import { effortUpdate } from "../effort-updates.js"
 import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
@@ -66,7 +68,6 @@ type MessagePhase = Schema.Schema.Type<typeof MessagePhase>
 
 export const MessageMetadata = Schema.Struct({
   itemId: Schema.optional(Schema.String),
-  type: Schema.optional(Schema.Literal("message")),
   status: Schema.optional(Schema.String),
   phase: Schema.optional(MessagePhase),
 })
@@ -164,14 +165,21 @@ export const CompactionItem = Schema.Struct({
   encrypted_content: Schema.String,
 })
 
+// Kept out of the baseline `InputItem` union: only the OpenAI extension accepts it.
+export const ConfigurationUpdate = Schema.Struct({
+  type: Schema.Literal("configuration_update"),
+  reasoning: Schema.Struct({ effort: OpenResponsesOptions.ReasoningEffort }),
+})
+type ConfigurationUpdate = Schema.Schema.Type<typeof ConfigurationUpdate>
+
 export const InputItem = Schema.Union([
   CompactionItem,
-  Schema.Struct({ role: Schema.tag("system"), content: Schema.String }),
-  Schema.Struct({ role: Schema.tag("developer"), content: Schema.String }),
+  Schema.Struct({ type: Schema.tag("message"), role: Schema.tag("system"), content: Schema.String }),
+  Schema.Struct({ type: Schema.tag("message"), role: Schema.tag("developer"), content: Schema.String }),
   Schema.Struct({
+    type: Schema.tag("message"),
     role: Schema.tag("user"),
     content: Schema.Array(OpenResponsesInputContent),
-    type: Schema.optional(Schema.Literal("message")),
     id: Schema.optional(Schema.String),
     status: Schema.optional(Schema.String),
   }),
@@ -208,6 +216,7 @@ export type HostedToolReplayItem = {
 type LoweredInputItem =
   | OpenResponsesInputItem
   | HostedToolReplayItem
+  | ConfigurationUpdate
   | {
       readonly type: "message"
       readonly id?: string
@@ -325,9 +334,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 +409,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
@@ -413,7 +450,7 @@ export interface ProviderAdapter {
   ) => Effect.Effect<{ readonly type: string }, AIError>
   readonly lowerMedia?: (input: {
     readonly part: MediaPart
-    readonly media: ProviderShared.NormalizedMedia
+    readonly media: Media.Inline | undefined
     readonly request: LLMRequest
   }) => MediaInput | undefined
   readonly restoreHostedToolItem?: (item: unknown) => HostedToolReplayItem | undefined
@@ -494,7 +531,7 @@ const lowerToolCall = (part: ToolCallPart, providerMetadataKey: string): OpenRes
     call_id: part.id,
     name: part.name,
     namespace: part.namespace,
-    arguments: ProviderShared.encodeJson(part.input),
+    arguments: ProviderShared.encodeJson(part.input === undefined ? {} : part.input),
   }
 }
 
@@ -520,29 +557,28 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   adapter: ProviderAdapter,
   target: "message" | "tool-result",
 ) {
-  const media = ProviderShared.normalizeMedia(part)
+  const media = part.media.inline()
   const providerMedia = adapter.lowerMedia?.({ part, media, request })
   if (providerMedia) return providerMedia
   const detail = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenResponsesInputImage.fields.detail))(
     part.providerMetadata?.[metadataKey(request.model)]?.detail,
   )
-  const url =
-    typeof part.data === "string" && (part.data.startsWith("https://") || part.data.startsWith("http://"))
-      ? part.data
-      : undefined
-  if (!media.mime.startsWith("image/")) {
-    if (target === "tool-result" && media.mime.startsWith("video/"))
-      return { type: "input_video" as const, video_url: url ?? media.dataUrl }
+  const mime = part.media.mediaType.toLowerCase()
+  const url = ProviderShared.mediaUrl(part.media)
+  const location = url ?? (yield* ProviderShared.requireInlineMedia(adapter.name, part.media)).dataUrl
+  if (part.media.kind !== "image") {
+    if (target === "tool-result" && part.media.kind === "video")
+      return { type: "input_video" as const, video_url: location }
     return {
       type: "input_file" as const,
-      filename: part.filename ?? (media.mime === "application/pdf" ? "document.pdf" : "file"),
+      filename: part.filename ?? (mime === "application/pdf" ? "document.pdf" : "file"),
       detail,
-      ...(url ? { file_url: url } : { file_data: media.dataUrl }),
+      ...(url ? { file_url: url } : { file_data: location }),
     }
   }
   return {
     type: "input_image" as const,
-    image_url: url ?? media.dataUrl,
+    image_url: location,
     detail,
   }
 })
@@ -572,12 +608,7 @@ const lowerToolResultContentItem = Effect.fnUntraced(function* (
   adapter: ProviderAdapter,
 ) {
   if (item.type === "text") return { type: "input_text" as const, text: item.text }
-  return yield* lowerMedia(
-    { type: "media", mediaType: item.mime, data: item.uri, filename: item.name },
-    request,
-    adapter,
-    "tool-result",
-  )
+  return yield* lowerMedia(ProviderShared.toolFileMedia(item), request, adapter, "tool-result")
 })
 
 const lowerHostedToolResultContentItem = Effect.fnUntraced(function* (
@@ -586,11 +617,7 @@ const lowerHostedToolResultContentItem = Effect.fnUntraced(function* (
   adapter: ProviderAdapter,
 ) {
   if (item.type === "text") return { type: "input_text" as const, text: item.text }
-  return yield* lowerMessageMedia(
-    { type: "media", mediaType: item.mime, data: item.uri, filename: item.name },
-    request,
-    adapter,
-  )
+  return yield* lowerMessageMedia(ProviderShared.toolFileMedia(item), request, adapter)
 })
 
 const lowerToolResultOutput = Effect.fnUntraced(function* (
@@ -606,6 +633,8 @@ const lowerToolResultOutput = Effect.fnUntraced(function* (
   return yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, adapter))
 })
 
+const DEFAULT_EFFORT = "medium"
+
 const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
   request: LLMRequest,
   adapter: ProviderAdapter,
@@ -618,7 +647,16 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
       Schema.decodeUnknownEffect(Schema.UndefinedOr(MessageMetadata)),
     )(message.providerMetadata?.[providerMetadataKey])
     if (message.role === "system") {
+      const update = effortUpdate(message)
+      if (update) {
+        // Consecutive updates are rejected, so a newer one replaces its predecessor.
+        const last = input.at(-1)
+        if (last !== undefined && "type" in last && last.type === "configuration_update") input.pop()
+        input.push({ type: "configuration_update", reasoning: { effort: update.effort ?? DEFAULT_EFFORT } })
+        continue
+      }
       input.push({
+        type: "message",
         role: "developer",
         content: ProviderShared.joinText(yield* ProviderShared.systemUpdateText(adapter.name, message)),
       })
@@ -628,7 +666,7 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
     if (message.role === "user") {
       const content = yield* Effect.forEach(message.content, (part) => lowerUserContent(part, request, adapter))
       if (content.length > 0)
-        input.push({ role: "user", content, type: metadata?.type, id: metadata?.itemId, status: metadata?.status })
+        input.push({ type: "message", role: "user", content, id: metadata?.itemId, status: metadata?.status })
       continue
     }
 
@@ -719,16 +757,28 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
               ? part.result.value
               : [{ type: "text", text: ProviderShared.toolResultText(part) }]
           input.push({
+            type: "message",
             role: "user",
             content: yield* Effect.forEach(content, (item) => lowerHostedToolResultContentItem(item, request, adapter)),
           })
           continue
         }
+        if (part.type === "media") {
+          flushText()
+          // Responses has no assistant-authored image item; replay generated media (e.g. from Gemini) as user input.
+          input.push({
+            type: "message",
+            role: "user",
+            content: [yield* lowerMessageMedia(part, request, adapter)],
+          })
+          continue
+        }
         return yield* ProviderShared.unsupportedContent(adapter.name, "assistant", [
           "text",
           "reasoning",
           "tool-call",
           "tool-result",
+          "media",
         ])
       }
       flushText()
@@ -761,8 +811,7 @@ export const lowerConversation = Effect.fn("OpenResponses.lowerConversation")(fu
   }
 })
 
-export const lowerGeneration = (request: LLMRequest) => {
-  const options = OpenResponsesOptions.resolve(request)
+export const lowerGeneration = (request: LLMRequest, options = OpenResponsesOptions.resolve(request)) => {
   const generation = request.generation
   const cacheKey = ProviderShared.promptCacheKey(request)
   const parallelToolCalls = resolveParallelToolCalls(request)

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

@@ -315,15 +315,16 @@ const lowerToolCall = (part: ToolCallPart, options: LoweringOptions): OpenAIChat
   type: "function",
   function: {
     name: part.name,
-    arguments: ProviderShared.encodeJson(part.input),
+    arguments: ProviderShared.encodeJson(part.input === undefined ? {} : part.input),
   },
 })
 
 const lowerMedia = Effect.fn("OpenAIChat.lowerMedia")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
-  if (!media.mime.startsWith("image/"))
-    return yield* ProviderShared.invalidRequest(`OpenAI Chat does not support media type ${part.mediaType}`)
-  return { type: "image_url" as const, image_url: { url: media.dataUrl } }
+  if (part.media.kind !== "image")
+    return yield* ProviderShared.invalidRequest(`OpenAI Chat does not support media type ${part.media.mediaType}`)
+  const url =
+    ProviderShared.mediaUrl(part.media) ?? (yield* ProviderShared.requireInlineMedia("OpenAI Chat", part.media)).dataUrl
+  return { type: "image_url" as const, image_url: { url } }
 })
 
 const openAICompatibleReasoningContent = (native: unknown) =>
@@ -456,11 +457,7 @@ const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (
       cache_control: options.cacheControl?.(part.cache),
     })
     const files = content.filter((item) => item.type === "file")
-    images.push(
-      ...(yield* Effect.forEach(files, (item) =>
-        lowerMedia({ type: "media", mediaType: item.mime, data: item.uri, filename: item.name }),
-      )),
-    )
+    images.push(...(yield* Effect.forEach(files, (item) => lowerMedia(ProviderShared.toolFileMedia(item)))))
   }
   return { messages, images }
 })
@@ -711,7 +708,11 @@ const detectZaiToolStream = (provider: string, baseURL: string | undefined, mode
 
 const lowerOptions = (request: LLMRequest, supportsStore: boolean) => {
   const options = OpenAIOptions.resolve(request)
-  const cacheKey = ProviderShared.promptCacheKey(request)
+  // Default off: strict providers 400 on unknown body fields, so only send
+  // the key where compatibility explicitly allows it. Header-based affinity
+  // (x-session-affinity, x-grok-conv-id, ...) is unaffected.
+  const cacheKey =
+    (request.model.compatibility?.supportsPromptCacheKey ?? false) ? ProviderShared.promptCacheKey(request) : undefined
   return {
     ...(supportsStore && options.store !== undefined ? { store: options.store } : {}),
     // For providers that support `store`, ensure stateless `store:false` is sent
@@ -766,7 +767,7 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
               supportsStrictMode,
             ),
           ),
-    tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
+    tool_choice: hasActiveTools && request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
     stream: true as const,
     ...(supportsUsageInStreaming ? { stream_options: { include_usage: true } } : {}),
     ...(zaiToolStream && hasActiveTools ? { tool_stream: true } : {}),

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

@@ -1,43 +1,39 @@
-import { Effect, Encoding, Schema } from "effect"
-import { Headers, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
-import {
-  ImageModel,
-  GeneratedImage,
-  ImageResponse,
-  type ImageInput,
-  type ImageRequestFor,
-  type ImageRoute,
-} from "../image.js"
-import { Auth, type Definition as AuthDefinition } from "../route/auth.js"
-import { Usage, mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema/index.js"
+import { Effect, Schema } from "effect"
+import type { HttpClientResponse } from "effect/unstable/http"
+import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
+import { Media } from "../media.js"
+import { MediaProtocol } from "../route/media-protocol.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, mergeJsonRecords, type AIError } from "../schema/index.js"
 import { ProviderShared } from "./shared.js"
-import { ImageInputs } from "./utils/image-input.js"
-import { OpenAIImage } from "./utils/openai-image.js"
+import { MediaInput } from "./utils/media-input.js"
 
 const ADAPTER = "openai-images"
+const NAME = "OpenAI Images"
+const PROVIDER = ProviderID.make("openai")
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/images/generations"
 export const EDIT_PATH = "/images/edits"
 
+// ---------------------------------------------------------------------------
+// 1. Public model input
+// ---------------------------------------------------------------------------
+
 export type OpenAIImageString<Known extends string> = Known | (string & {})
 
+/** Provider-native options. Common fields (`n`, `size`, `format`, `images`, `mask`) live on the request. */
 export type OpenAIImageOptions = {
-  readonly mask?: ImageInput
-  readonly n?: number
-  readonly size?: OpenAIImageString<
-    "auto" | "256x256" | "512x512" | "1024x1024" | "1536x1024" | "1024x1536" | "1792x1024" | "1024x1792"
-  >
   readonly quality?: OpenAIImageString<"auto" | "low" | "medium" | "high" | "standard" | "hd">
   readonly background?: OpenAIImageString<"auto" | "opaque" | "transparent">
   readonly moderation?: OpenAIImageString<"auto" | "low">
-  readonly outputFormat?: OpenAIImageString<"png" | "jpeg" | "webp">
   readonly outputCompression?: number
 } & Record<string, unknown>
 
-export type OpenAIImageBody = Record<string, unknown> & {
-  readonly model: string
-  readonly prompt: string
-}
+export type Request = ImageRequestFor<OpenAIImageOptions>
+
+// ---------------------------------------------------------------------------
+// 2. Response schema
+// ---------------------------------------------------------------------------
 
 const OpenAIImageResponse = Schema.Struct({
   data: Schema.Array(
@@ -59,196 +55,153 @@ const OpenAIImageResponse = Schema.Struct({
   ),
 })
 
-export interface ModelInput {
-  readonly id: string
-  readonly auth: AuthDefinition
-  readonly baseURL?: string
-  readonly headers?: Record<string, string>
-  readonly http?: HttpOptions
-}
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
+
+/** Multipart field names the route owns; `http.body` overlays cannot smuggle replacements for them. */
+const RESERVED_FORM_FIELDS = new Set(["model", "prompt", "image", "image[]", "images", "mask"])
 
 const nativeOptions = (options: OpenAIImageOptions | undefined) => {
   if (!options) return undefined
-  const { mask: _, outputFormat, outputCompression, ...native } = options
-  return {
-    output_format: outputFormat,
-    output_compression: outputCompression,
-    ...native,
-  }
+  const { outputCompression, ...native } = options
+  return { output_compression: outputCompression, ...native }
 }
 
-const applyQuery = (url: string, query: Record<string, string> | undefined) => {
-  if (!query) return url
-  const next = new URL(url)
-  Object.entries(query).forEach(([key, value]) => next.searchParams.set(key, value))
-  return next.toString()
-}
+const isEdit = (request: Request) => (request.images?.length ?? 0) > 0
 
-export const model = (input: ModelInput) => {
-  const route: ImageRoute<OpenAIImageOptions> = {
-    id: ADAPTER,
-    generate: Effect.fn("OpenAIImages.generate")(function* (request: ImageRequestFor<OpenAIImageOptions>, execute) {
-      const mask = request.options?.mask
-      if (mask !== undefined && (request.images?.length ?? 0) === 0)
-        return yield* ImageInputs.invalid("An OpenAI image mask requires at least one input image")
-      const http = mergeHttpOptions(request.model.http, request.http)
-      const sourceImages = request.images ?? []
-      const multipartImages = yield* Effect.forEach(sourceImages, (image) => {
-        if (image.type === "bytes") return Effect.succeed({ data: image.data, mediaType: image.mediaType })
-        if (image.type === "url") return ImageInputs.decodeDataUrl(image.url)
-        return Effect.undefined
-      })
-      const multipartMask =
-        mask === undefined
-          ? undefined
-          : mask.type === "bytes"
-            ? { data: mask.data, mediaType: mask.mediaType }
-            : mask.type === "url"
-              ? yield* ImageInputs.decodeDataUrl(mask.url)
-              : undefined
-      const useMultipart =
-        sourceImages.length > 0 &&
-        multipartImages.every((image) => image !== undefined) &&
-        (mask === undefined || multipartMask !== undefined)
-      const path = sourceImages.length === 0 ? PATH : EDIT_PATH
-      const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${path}`, http?.query)
+const isInline = (asset: Media.Asset) => asset.inline() !== undefined
 
-      if (useMultipart) {
-        const form = new FormData()
-        form.append("model", request.model.id)
-        form.append("prompt", request.prompt)
-        Object.entries(mergeJsonRecords(nativeOptions(request.options), http?.body) ?? {}).forEach(([key, value]) => {
-          if (["model", "prompt", "image", "image[]", "images", "mask"].includes(key)) return
-          form.append(key, typeof value === "string" ? value : ProviderShared.encodeJson(value))
-        })
-        multipartImages.forEach((image, index) => {
-          if (image === undefined) return
-          form.append("image[]", imageBlob(image.data, image.mediaType), `image-${index}`)
-        })
-        if (multipartMask !== undefined)
-          form.append("mask", imageBlob(multipartMask.data, multipartMask.mediaType), "mask")
-        const headers = yield* Auth.toEffect(input.auth)({
-          request,
-          method: "POST",
-          url,
-          body: "[multipart/form-data]",
-          headers: Headers.remove(Headers.fromInput({ ...input.headers, ...http?.headers }), "content-type"),
-        })
-        const response = yield* execute(
-          HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.bodyFormData(form)),
-        )
-        return yield* parseResponse(response, request.options, http?.body)
-      }
-
-      const references = sourceImages.map((image) => {
-        if (image.type === "bytes") return { image_url: ImageInputs.dataUrl(image) }
-        if (image.type === "url") return { image_url: image.url }
-        if (image.type === "file-id") return { file_id: image.id }
-        return undefined
-      })
-      if (references.some((image) => image === undefined))
-        return yield* ImageInputs.invalid("OpenAI Images accepts image URLs, data URLs, bytes, and file IDs")
-      const maskReference =
-        mask === undefined
-          ? undefined
-          : mask.type === "bytes"
-            ? { image_url: ImageInputs.dataUrl(mask) }
-            : mask.type === "url"
-              ? { image_url: mask.url }
-              : mask.type === "file-id"
-                ? { file_id: mask.id }
-                : undefined
-      if (mask !== undefined && maskReference === undefined)
-        return yield* ImageInputs.invalid("OpenAI Images accepts masks as URLs, data URLs, bytes, or file IDs")
-      const requestBody = mergeJsonRecords(
-        {
-          model: request.model.id,
-          prompt: request.prompt,
-          images: references.length === 0 ? undefined : references,
-          mask: maskReference,
-        },
-        nativeOptions(request.options),
-        http?.body,
-      ) as OpenAIImageBody
-      const text = ProviderShared.encodeJson(requestBody)
-      const headers = yield* Auth.toEffect(input.auth)({
-        request,
-        method: "POST",
-        url,
-        body: text,
-        headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
-      })
-      const response = yield* execute(
-        HttpClientRequest.post(url).pipe(
-          HttpClientRequest.setHeaders(headers),
-          HttpClientRequest.bodyText(text, "application/json"),
-        ),
-      )
-      return yield* parseResponse(response, request.options, http?.body)
-    }),
-  }
-  return ImageModel.make<OpenAIImageOptions>({ id: input.id, provider: "openai", route, http: input.http })
-}
-
-const parseResponse = Effect.fn("OpenAIImages.parseResponse")(function* (
-  response: HttpClientResponse.HttpClientResponse,
-  options: OpenAIImageOptions | undefined,
-  overlay: Record<string, unknown> | undefined,
-) {
-  const output = yield* ProviderShared.imageResponse(ADAPTER, "OpenAI Images", response)
-  const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(OpenAIImageResponse))(output.body).pipe(
-    Effect.mapError((cause) => output.invalid("OpenAI Images returned an invalid response", cause)),
-  )
-  const requestBody = mergeJsonRecords(nativeOptions(options), overlay)
-  const format =
-    decoded.output_format ?? (typeof requestBody?.output_format === "string" ? requestBody.output_format : "png")
-  const images = yield* Effect.forEach(decoded.data, (item, index) => {
-    if (item.b64_json)
-      return Effect.fromResult(Encoding.decodeBase64(item.b64_json)).pipe(
-        Effect.mapError((cause) => output.invalid(`OpenAI Images result ${index} contains invalid base64 data`, cause)),
-        Effect.map(
-          (data) =>
-            new GeneratedImage({
-              mediaType: `image/${format}`,
-              data,
-              providerMetadata:
-                item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
-            }),
-        ),
-      )
-    if (item.url)
-      return Effect.succeed(
-        new GeneratedImage({
-          mediaType: `image/${format}`,
-          data: item.url,
-          providerMetadata:
-            item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
-        }),
-      )
-    return Effect.fail(output.invalid(`OpenAI Images result ${index} has neither image data nor a URL`))
-  })
-  if (images.length === 0) return yield* output.invalid("OpenAI Images returned no images")
-  return new ImageResponse({
-    images,
-    usage:
-      decoded.usage === undefined
-        ? undefined
-        : new Usage({
-            inputTokens: decoded.usage.input_tokens,
-            outputTokens: decoded.usage.output_tokens,
-            totalTokens: decoded.usage.total_tokens,
-            providerMetadata: { openai: decoded.usage },
-          }),
-    providerMetadata: { openai: { outputFormat: format } },
-  })
-})
-
-const imageBlob = (data: Uint8Array, mediaType: string) => {
+const blob = (data: Uint8Array, mediaType: string) => {
   const buffer = new ArrayBuffer(data.byteLength)
   new Uint8Array(buffer).set(data)
   return new Blob([buffer], { type: mediaType })
 }
 
+const reference = (asset: Media.Asset): Effect.Effect<Record<string, unknown>, AIError> => {
+  const inline = asset.inline()
+  if (inline) return Effect.succeed({ image_url: inline.dataUrl })
+  const url = ProviderShared.mediaUrl(asset)
+  if (url) return Effect.succeed({ image_url: url })
+  const id = MediaInput.refID(asset, PROVIDER)
+  if (id) return Effect.succeed({ file_id: id })
+  return Effect.fail(
+    ProviderShared.invalidRequest("OpenAI Images accepts image URLs, data URLs, bytes, and OpenAI file IDs"),
+  )
+}
+
+const fromRequest = Effect.fn("OpenAIImages.fromRequest")(function* (request: Request) {
+  const images = request.images ?? []
+  const mask = request.mask
+  if (mask !== undefined && images.length === 0)
+    return yield* ProviderShared.invalidRequest("An OpenAI image mask requires at least one input image")
+  const fields = mergeJsonRecords(
+    { n: request.n, size: request.size, output_format: request.format },
+    nativeOptions(request.providerOptions),
+    request.http?.body,
+  )
+
+  // Owned bytes go through multipart edits; remote URLs and file IDs use the JSON edits body instead.
+  if (images.length > 0 && images.every(isInline) && (mask === undefined || isInline(mask))) {
+    const form = new FormData()
+    form.append("model", request.model.id)
+    form.append("prompt", request.prompt)
+    Object.entries(fields ?? {}).forEach(([key, value]) => {
+      if (RESERVED_FORM_FIELDS.has(key)) return
+      form.append(key, typeof value === "string" ? value : ProviderShared.encodeJson(value))
+    })
+    const uploads = yield* Effect.forEach(images, (image) => MediaInput.inlineBytes(ADAPTER, image))
+    uploads.forEach((data, index) => form.append("image[]", blob(data, images[index].mediaType), `image-${index}`))
+    if (mask !== undefined)
+      form.append("mask", blob(yield* MediaInput.inlineBytes(ADAPTER, mask), mask.mediaType), "mask")
+    return MediaProtocol.multipart(form)
+  }
+
+  const references = yield* Effect.forEach(images, reference)
+  const maskReference = mask === undefined ? undefined : yield* reference(mask)
+  return MediaProtocol.json(
+    mergeJsonRecords(
+      {
+        model: request.model.id,
+        prompt: request.prompt,
+        images: references.length === 0 ? undefined : references,
+        mask: maskReference,
+      },
+      fields,
+    ) ?? {},
+  )
+})
+
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+
+const requestedFormat = (body: MediaProtocol.Body) => {
+  const value = body.type === "json" ? body.value.output_format : body.value.get("output_format")
+  return typeof value === "string" ? value : undefined
+}
+
+const decodeResponse = Effect.fn("OpenAIImages.decodeResponse")(function* (
+  response: HttpClientResponse.HttpClientResponse,
+  context: MediaProtocol.DecodeContext<Request>,
+) {
+  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, OpenAIImageResponse)(response)
+  const decoded = output.value
+  const format = decoded.output_format ?? requestedFormat(context.body) ?? "png"
+  const mediaType = `image/${format}`
+  const images = yield* Effect.forEach(decoded.data, (item, index) => {
+    const providerMetadata =
+      item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } }
+    if (item.b64_json)
+      return MediaInput.decodedAsset(output.invalid, `${NAME} result ${index}`, item.b64_json, mediaType, {
+        info: { format },
+        providerMetadata,
+      })
+    if (item.url) return Effect.succeed(Media.url(item.url, { mediaType, info: { format }, providerMetadata }))
+    return Effect.fail(output.invalid(`${NAME} result ${index} has neither image data nor a URL`))
+  })
+  if (images.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  return new ImageResponse({
+    images,
+    usage:
+      decoded.usage === undefined
+        ? undefined
+        : {
+            type: "tokens",
+            input: decoded.usage.input_tokens,
+            output: decoded.usage.output_tokens,
+            total: decoded.usage.total_tokens,
+            details: { openai: decoded.usage },
+          },
+    providerMetadata: { openai: { outputFormat: format } },
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+
+export const protocol = MediaProtocol.inline<Request, ImageResponse>({
+  id: ADAPTER,
+  name: NAME,
+  unsupported: ["aspectRatio", "seed"],
+  body: { from: fromRequest },
+  response: { decode: decodeResponse },
+})
+
+export const model = (input: MediaRoute.ModelInput) =>
+  ImageModel.fromRoute<OpenAIImageOptions>(
+    {
+      id: ADAPTER,
+      provider: PROVIDER,
+      protocol,
+      baseURL: DEFAULT_BASE_URL,
+      path: ({ request }) => (isEdit(request) ? EDIT_PATH : PATH),
+    },
+    input,
+  )
+
 export const OpenAIImages = {
+  protocol,
   model,
 } as const

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

@@ -6,7 +6,9 @@ import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
 import { LLMRequest, mergeJsonRecords, type JsonSchema, type ToolDefinition, type ToolEntry } from "../schema/index.js"
+import { resolveEffortUpdates } from "../effort-updates.js"
 import { OpenResponses } from "./open-responses.js"
+import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { OpenAIImage } from "./utils/openai-image.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
@@ -94,9 +96,15 @@ const OpenAIResponsesToolChoice = Schema.Union([
   Schema.Struct({ type: Schema.tag("image_generation") }),
 ])
 
+const OpenAIResponsesInputItem = Schema.Union([
+  OpenResponses.InputItem,
+  OpenAIResponsesHostedToolItem,
+  OpenResponses.ConfigurationUpdate,
+])
+
 const OpenAIResponsesCoreFields = {
   ...OpenResponses.coreFields,
-  input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem])),
+  input: Schema.Array(OpenAIResponsesInputItem),
   tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
   context_management: Schema.optional(
@@ -119,7 +127,7 @@ export type OpenAIResponsesBody = Schema.Schema.Type<typeof OpenAIResponsesBody>
 export const CompactionTrigger = Schema.Struct({ type: Schema.Literal("compaction_trigger") })
 const CheckpointBody = Schema.Struct({
   ...OpenAIResponsesBody.fields,
-  input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem, CompactionTrigger])),
+  input: Schema.Array(Schema.Union([OpenAIResponsesInputItem, CompactionTrigger])),
   store: Schema.Literal(false),
   prompt_cache_retention: optionalNull(Schema.String),
   prompt_cache_options: optionalNull(
@@ -133,6 +141,14 @@ const adapter = {
   restoreHostedToolItem: (item: unknown) => (Schema.is(OpenAIResponsesHostedToolItem)(item) ? item : undefined),
 } satisfies OpenResponses.ProviderAdapter
 
+// Only GPT-6 Astra accepts `configuration_update`, and never alongside automatic `context_management` compaction.
+const supportsEffortUpdates = (request: LLMRequest) => {
+  if (request.providerOptions?.contextManagement !== undefined) return false
+  const override = request.model.compatibility?.supportsEffortUpdates
+  if (override !== undefined) return override
+  return /(?:^|\/)gpt-6-astra$/i.test(request.model.id)
+}
+
 const nativeImageToolInput = (tool: ToolDefinition) => {
   const native = tool.native?.openai
   return ProviderShared.isRecord(native) && native.type === "image_generation" ? native : undefined
@@ -189,18 +205,22 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
   const management = yield* ProviderShared.validateWith(
     Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
   )(request.providerOptions?.contextManagement)
+  const options = OpenResponsesOptions.resolve(request)
+  const updates = resolveEffortUpdates(request, options.reasoningEffort)
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   return yield* decodeBody({
-    ...(yield* OpenResponses.lowerConversation(request, adapter)),
-    ...OpenResponses.lowerGeneration(request),
+    ...(yield* OpenResponses.lowerConversation(updates.request, adapter)),
+    ...OpenResponses.lowerGeneration(request, { ...options, reasoningEffort: updates.effort }),
     context_management: management?.map((edit) => ({ type: edit.type, compact_threshold: edit.compactThreshold })),
     tools:
       request.tools.length === 0
         ? undefined
         : yield* Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, toolSchemaCompatibility)),
     tool_choice:
-      OpenResponses.allowedToolChoice(request) ??
-      (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
+      request.tools.length === 0
+        ? undefined
+        : (OpenResponses.allowedToolChoice(request) ??
+          (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined)),
   })
 })
 
@@ -295,6 +315,7 @@ export const protocol = Protocol.make({
     step,
     terminal: OpenResponses.terminal,
   },
+  supportsEffortUpdates,
 })
 
 const endpoint = Endpoint.path<OpenAIResponsesBody>(PATH, { baseURL: DEFAULT_BASE_URL })

packages/ai/src/protocols/shared.ts

@@ -1,14 +1,13 @@
-import { Buffer } from "node:buffer"
 import { Tool } from "@opencode/schema/tool"
 import { Effect, Schema, Stream } from "effect"
 import * as Sse from "effect/unstable/encoding/Sse"
-import { Headers, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { Headers, HttpClientRequest } from "effect/unstable/http"
+import { Media } from "../media.js"
 import {
   InvalidProviderOutputError,
   InvalidRequestError,
   UnsupportedOperationError,
   AIError,
-  HttpContext,
   LLMRequest,
   Message,
   ToolDefinition,
@@ -169,24 +168,33 @@ export const wrappedSystemUpdate = Effect.fn("ProviderShared.wrappedSystemUpdate
 export const parseToolInput = (route: string, name: string, raw: string) =>
   parseJson(route, raw || "{}", `Invalid JSON input for ${route} tool call ${name}`)
 
-export interface NormalizedMedia {
-  readonly mime: string
-  readonly base64: string
-  readonly dataUrl: string
+/** Inline view or a typed `InvalidRequest` for routes that cannot fetch URLs or dereference provider refs. */
+export const requireInlineMedia = (route: string, asset: Media.Asset): Effect.Effect<Media.Inline, AIError> => {
+  const inline = asset.inline()
+  return inline ? Effect.succeed(inline) : Effect.fail(inlineRequired(route, asset))
 }
 
-export const normalizeMedia = (part: MediaPart): NormalizedMedia => {
-  const mime = part.mediaType.toLowerCase()
-  if (typeof part.data !== "string") {
-    const base64 = Buffer.from(part.data).toString("base64")
-    return { mime, base64, dataUrl: `data:${mime};base64,${base64}` }
-  }
-  if (!part.data.startsWith("data:")) return { mime, base64: part.data, dataUrl: `data:${mime};base64,${part.data}` }
-  return { mime, base64: part.data.slice(part.data.indexOf(",") + 1), dataUrl: part.data }
-}
+export const inlineRequired = (route: string, asset: Media.Asset) =>
+  invalidRequest(
+    `${route} requires inline media (bytes or base64); ${asset.source.type} sources must be materialized first`,
+  )
 
-export const normalizeToolFile = (part: Tool.FileContent) =>
-  normalizeMedia({ type: "media", mediaType: part.mime, data: part.uri, filename: part.name })
+/** The remote URL of a `url` asset, for protocols that accept `http(s)` references natively. */
+export const mediaUrl = (asset: Media.Asset) => (asset.source.type === "url" ? asset.source.url : undefined)
+
+/**
+ * Lift a tool-result file into a `MediaPart`. Tool files carry either a data URL, an `http(s)` URL, or raw base64 in
+ * `uri`; the declared `mime` wins over any data-URL prefix so tool authors control the type the model sees.
+ */
+export const toolFileMedia = (item: Tool.FileContent): MediaPart => {
+  const parsed = Media.parseDataUrl(item.uri)
+  const asset = parsed
+    ? Media.from({ ...parsed.source, mediaType: item.mime })
+    : /^https?:\/\//.test(item.uri)
+      ? Media.url(item.uri, { mediaType: item.mime })
+      : Media.base64(item.uri, item.mime)
+  return Message.media(asset, { filename: item.name })
+}
 
 export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
 
@@ -315,34 +323,6 @@ export const flattenToolRequest = (request: LLMRequest) => {
   }
 }
 
-export const imageResponse = Effect.fn("ProviderShared.imageResponse")(function* (
-  route: string,
-  name: string,
-  response: HttpClientResponse.HttpClientResponse,
-) {
-  const http = new HttpContext({ url: response.request.url, status: response.status, headers: response.headers })
-  const body = yield* response.text.pipe(
-    Effect.mapError(
-      (cause) =>
-        new AIError({
-          reason: new InvalidProviderOutputError({
-            route,
-            message: `Failed to read the ${name} response`,
-            http,
-            cause,
-          }),
-        }),
-    ),
-  )
-  return {
-    body,
-    invalid: (message: string, cause?: unknown) =>
-      new AIError({
-        reason: new InvalidProviderOutputError({ route, message, body, http, cause }),
-      }),
-  }
-})
-
 export const matchToolChoice = <Auto, None, Required, Tool>(
   route: string,
   toolChoice: NonNullable<LLMRequest["toolChoice"]>,

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

@@ -57,8 +57,27 @@ const documentBlock = (name: string, format: DocumentFormat, bytes: string): Doc
   },
 })
 
+function documentName(filename: string | undefined, names: Set<string>) {
+  const base =
+    (filename ?? "")
+      .replace(/\.[^.]*$/, "")
+      .replace(/[^a-zA-Z0-9 ()[\]-]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 200)
+      .trim() || "document"
+  let name = base
+  // Converse requires labels to be unique across the entire request, including tool results.
+  for (let index = 2; names.has(name); index++) {
+    const suffix = ` ${index}`
+    name = `${base.slice(0, 200 - suffix.length).trimEnd()}${suffix}`
+  }
+  names.add(name)
+  return name
+}
+
 const mediaBase64 = Effect.fn("BedrockMedia.mediaBase64")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.requireInlineMedia("Bedrock Converse", part.media)
   const bytes = yield* Effect.fromResult(Encoding.decodeBase64(media.base64)).pipe(
     Effect.mapError((cause) =>
       ProviderShared.invalidRequest("Bedrock Converse media data must be valid base64", cause),
@@ -72,21 +91,30 @@ const mediaBase64 = Effect.fn("BedrockMedia.mediaBase64")(function* (part: Media
 // document block. Image MIME types not in `IMAGE_FORMATS` (e.g. `image/svg+xml`)
 // get an image-specific error so the caller knows it's a format-support issue,
 // not a kind-detection issue.
-export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart) {
-  const mime = part.mediaType.toLowerCase()
+export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart, documentNames: Set<string>) {
+  const mime = part.media.mediaType.toLowerCase()
   const imageFormat = IMAGE_FORMATS[mime as keyof typeof IMAGE_FORMATS]
   if (imageFormat) {
-    return { image: { format: imageFormat, source: { bytes: yield* mediaBase64(part) } } } satisfies ImageBlock
+    return [{ image: { format: imageFormat, source: { bytes: yield* mediaBase64(part) } } } satisfies ImageBlock]
   }
   if (mime.startsWith("image/"))
-    return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support image media type ${part.mediaType}`)
+    return yield* ProviderShared.invalidRequest(
+      `Bedrock Converse does not support image media type ${part.media.mediaType}`,
+    )
   const documentFormat = DOCUMENT_FORMATS[mime as keyof typeof DOCUMENT_FORMATS]
   if (documentFormat) {
-    if (!part.filename)
-      return yield* ProviderShared.invalidRequest("Bedrock Converse document media requires a filename")
-    return documentBlock(part.filename, documentFormat, yield* mediaBase64(part))
+    const name = documentName(part.filename, documentNames)
+    const block = documentBlock(name, documentFormat, yield* mediaBase64(part))
+    return part.filename !== undefined && part.filename !== name
+      ? [
+          {
+            text: `Attached file ${ProviderShared.encodeJson(part.filename)} has document label ${ProviderShared.encodeJson(name)}.`,
+          },
+          block,
+        ]
+      : [block]
   }
-  return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support media type ${part.mediaType}`)
+  return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support media type ${part.media.mediaType}`)
 })
 
 export * as BedrockMedia from "./bedrock-media.js"

packages/ai/src/protocols/utils/image-input.ts

@@ -1,31 +0,0 @@
-import { Effect, Encoding } from "effect"
-import type { ImageInput } from "../../image.js"
-import { InvalidRequestError, AIError } from "../../schema/index.js"
-
-const invalid = (message: string, cause?: unknown) =>
-  new AIError({
-    reason: new InvalidRequestError({ message, cause }),
-  })
-
-export const dataUrl = (input: Extract<ImageInput, { readonly type: "bytes" }>) =>
-  `data:${input.mediaType};base64,${Encoding.encodeBase64(input.data)}`
-
-export const decodeDataUrl = (
-  url: string,
-): Effect.Effect<{ readonly mediaType: string; readonly data: Uint8Array } | undefined, AIError> => {
-  if (!url.startsWith("data:")) return Effect.undefined
-  const match = /^data:([^;,]+);base64,(.*)$/s.exec(url)
-  if (!match) return Effect.fail(invalid("Image data URLs must contain a MIME type and base64 data"))
-  return Effect.fromResult(Encoding.decodeBase64(match[2])).pipe(
-    Effect.mapError((cause) => invalid("Image data URL contains invalid base64 data", cause)),
-    Effect.map((data) => ({ mediaType: match[1], data })),
-  )
-}
-
-export const invalidImageInput = invalid
-
-export const ImageInputs = {
-  dataUrl,
-  decodeDataUrl,
-  invalid: invalidImageInput,
-} as const

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

@@ -0,0 +1,33 @@
+import { Effect, Encoding } from "effect"
+import { Media } from "../../media.js"
+import type { AIError, ProviderID } from "../../schema/index.js"
+import { ProviderShared } from "../shared.js"
+
+/** Owned bytes for multipart uploads; decodes `base64` sources and rejects remote sources. */
+export const inlineBytes = (route: string, asset: Media.Asset): Effect.Effect<Uint8Array, AIError> => {
+  if (asset.source.type === "bytes") return Effect.succeed(asset.source.data)
+  const inline = asset.inline()
+  if (!inline) return Effect.fail(ProviderShared.inlineRequired(route, asset))
+  return Effect.fromResult(Encoding.decodeBase64(inline.base64)).pipe(
+    Effect.mapError((cause) => ProviderShared.invalidRequest(`${route} media contains invalid base64 data`, cause)),
+  )
+}
+
+/** Provider file handle when the ref belongs to this provider; refs from other providers are never forwarded. */
+export const refID = (asset: Media.Asset, provider: ProviderID) =>
+  asset.source.type === "ref" && asset.source.provider === provider ? asset.source.id : undefined
+
+/** Decode a provider's base64 output once into an owned `bytes` asset, sniffing the type when it is not declared. */
+export const decodedAsset = (
+  invalid: (message: string, cause?: unknown) => AIError,
+  label: string,
+  data: string,
+  mediaType: string | undefined,
+  options?: Media.AssetOptions,
+) =>
+  Effect.fromResult(Encoding.decodeBase64(data)).pipe(
+    Effect.mapError((cause) => invalid(`${label} contains invalid base64 data`, cause)),
+    Effect.map((bytes) => Media.bytes(bytes, mediaType, options)),
+  )
+
+export * as MediaInput from "./media-input.js"

packages/ai/src/protocols/utils/mistral-tool-id.ts

@@ -0,0 +1,34 @@
+import type { LLMRequest } from "../../schema/index.js"
+
+export const valid = /^[A-Za-z0-9]{9}$/
+
+export const hash = (value: string) => {
+  const hash = (seed: number) => {
+    let result = seed
+    for (const char of value) result = Math.imul(result ^ char.charCodeAt(0), 16777619)
+    return (result >>> 0).toString(36)
+  }
+  return `${hash(2166136261).padStart(7, "0")}${hash(2246822519).padStart(7, "0")}`.slice(-9)
+}
+
+export const normalizer = (request: LLMRequest) => {
+  const ids = request.messages.flatMap((message) =>
+    message.content.flatMap((part) => (part.type === "tool-call" || part.type === "tool-result" ? [part.id] : [])),
+  )
+  // Reserve valid IDs before projecting any history, including IDs encountered later.
+  const used = new Set(ids.filter((id) => valid.test(id)))
+  const normalized = new Map<string, string>()
+  return (id: string) => {
+    if (valid.test(id)) return id
+    const previous = normalized.get(id)
+    if (previous) return previous
+    let attempt = 0
+    let candidate = hash(id)
+    while (used.has(candidate)) candidate = hash(`${id}:${++attempt}`)
+    used.add(candidate)
+    normalized.set(id, candidate)
+    return candidate
+  }
+}
+
+export * as MistralToolID from "./mistral-tool-id.js"

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

@@ -1,12 +1,7 @@
 import { Option, Schema } from "effect"
-import type { LLMRequest } from "../../schema/index.js"
+import { ReasoningEffort, ReasoningEfforts, type LLMRequest } from "../../schema/index.js"
 
-export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
-export type ReasoningEffort = (typeof ReasoningEfforts)[number] | (string & {})
-export const ReasoningEffort = Schema.declare<ReasoningEffort>(
-  (value): value is ReasoningEffort => typeof value === "string",
-  { title: "ReasoningEffort" },
-)
+export { ReasoningEffort, ReasoningEfforts }
 
 export const TextVerbosities = ["low", "medium", "high"] as const
 export type TextVerbosity = (typeof TextVerbosities)[number] | (string & {})

packages/ai/src/protocols/utils/responses-compaction.ts

@@ -11,11 +11,13 @@ import {
   mergeJsonRecords,
 } from "../../schema/index.js"
 import type { CompactOperation } from "../../route/client.js"
+import { stripEffortUpdates } from "../../effort-updates.js"
 import { Endpoint } from "../../route/endpoint.js"
 import { RequestExecutor } from "../../route/executor.js"
 import { HttpTransport } from "../../route/transport/index.js"
 import { OpenResponses } from "../open-responses.js"
 import { JsonObject, optionalNull, ProviderShared } from "../shared.js"
+import { Media } from "../../media.js"
 
 const Body = Schema.Struct({
   model: Schema.String,
@@ -75,7 +77,8 @@ const Response = Schema.Struct({
 export const make = (adapter: OpenResponses.ProviderAdapter): CompactOperation =>
   Effect.fn("ResponsesCompaction.execute")(function* (request, executor, options) {
     const route = request.model.route
-    const native = yield* OpenResponses.lowerConversation(request, adapter)
+    // The standalone compaction endpoint rejects histories containing configuration updates.
+    const native = yield* OpenResponses.lowerConversation(stripEffortUpdates(request), adapter)
     const body = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Body))(
       mergeJsonRecords(
         {
@@ -155,20 +158,22 @@ function toMessage(item: (typeof Response.Type.output)[number], model: LLMReques
       if (part.type === "input_image")
         return {
           type: "media",
-          data: part.image_url,
-          mediaType: /^data:([^;,]+)/.exec(part.image_url)?.[1] ?? "image/*",
+          media: replayMedia(part.image_url, "image/*"),
           providerMetadata: part.detail === undefined ? undefined : { [key]: { detail: part.detail } },
         }
-      const data = part.file_url === undefined ? part.file_data : part.file_url
       return {
         type: "media",
-        data,
+        media: replayMedia(part.file_url === undefined ? part.file_data : part.file_url, "application/octet-stream"),
         filename: part.filename,
-        mediaType: /^data:([^;,]+)/.exec(data)?.[1] ?? "application/octet-stream",
         providerMetadata: part.detail === undefined ? undefined : { [key]: { detail: part.detail } },
       }
     }),
   })
 }
 
+/** Replayed compaction items carry either a data URL or a remote URL; the data URL's own type wins when present. */
+const replayMedia = (value: string, fallbackType: string) =>
+  Media.parseDataUrl(value) ??
+  (/^https?:\/\//.test(value) ? Media.url(value, { mediaType: fallbackType }) : Media.base64(value, fallbackType))
+
 export * as ResponsesCompaction from "./responses-compaction.js"

packages/ai/src/protocols/xai-images.ts

@@ -1,61 +1,38 @@
-import { Effect, Encoding, Schema } from "effect"
-import { Headers, HttpClientRequest } from "effect/unstable/http"
-import { GeneratedImage, ImageModel, ImageResponse, type ImageRequestFor, type ImageRoute } from "../image.js"
-import { Auth, type Definition as AuthDefinition } from "../route/auth.js"
-import { Usage, mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema/index.js"
+import { Effect, Schema } from "effect"
+import type { HttpClientResponse } from "effect/unstable/http"
+import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
+import { Media } from "../media.js"
+import { MediaProtocol } from "../route/media-protocol.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, mergeJsonRecords, type AIError } from "../schema/index.js"
 import { ProviderShared, optionalNull } from "./shared.js"
-import { ImageInputs } from "./utils/image-input.js"
+import { MediaInput } from "./utils/media-input.js"
 
 const ADAPTER = "xai-images"
+const NAME = "xAI Images"
+const PROVIDER = ProviderID.make("xai")
 export const DEFAULT_BASE_URL = "https://api.x.ai/v1"
 export const PATH = "/images/generations"
 export const EDIT_PATH = "/images/edits"
 
+// ---------------------------------------------------------------------------
+// 1. Public model input
+// ---------------------------------------------------------------------------
+
 export type XAIImageString<Known extends string> = Known | (string & {})
 
+/** Provider-native options. Common fields (`n`, `aspectRatio`, `images`) live on the request. */
 export type XAIImageOptions = {
-  readonly n?: number
-  readonly aspectRatio?: XAIImageString<
-    | "1:1"
-    | "3:4"
-    | "4:3"
-    | "9:16"
-    | "16:9"
-    | "2:3"
-    | "3:2"
-    | "9:19.5"
-    | "19.5:9"
-    | "9:20"
-    | "20:9"
-    | "1:2"
-    | "2:1"
-    | "auto"
-  >
-  readonly aspect_ratio?: XAIImageString<
-    | "1:1"
-    | "3:4"
-    | "4:3"
-    | "9:16"
-    | "16:9"
-    | "2:3"
-    | "3:2"
-    | "9:19.5"
-    | "19.5:9"
-    | "9:20"
-    | "20:9"
-    | "1:2"
-    | "2:1"
-    | "auto"
-  >
   readonly resolution?: XAIImageString<"1k" | "2k">
   readonly responseFormat?: XAIImageString<"url" | "b64_json">
   readonly response_format?: XAIImageString<"url" | "b64_json">
 } & Record<string, unknown>
 
-type XAIImageBody = Record<string, unknown> & {
-  readonly model: string
-  readonly prompt: string
-}
+export type Request = ImageRequestFor<XAIImageOptions>
+
+// ---------------------------------------------------------------------------
+// 2. Response schema
+// ---------------------------------------------------------------------------
 
 const XAIImageResponse = Schema.Struct({
   data: Schema.Array(
@@ -69,120 +46,109 @@ const XAIImageResponse = Schema.Struct({
   usage: Schema.optional(Schema.Unknown),
 })
 
-export interface ModelInput {
-  readonly id: string
-  readonly auth: AuthDefinition
-  readonly baseURL?: string
-  readonly headers?: Record<string, string>
-  readonly http?: HttpOptions
-}
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
 
 const nativeOptions = (options: XAIImageOptions | undefined) => {
   if (!options) return undefined
-  const { aspectRatio, responseFormat, ...native } = options
-  return {
-    aspect_ratio: aspectRatio,
-    response_format: responseFormat,
-    ...native,
-  }
+  const { responseFormat, ...native } = options
+  return { response_format: responseFormat, ...native }
 }
 
-const applyQuery = (url: string, query: Record<string, string> | undefined) => {
-  if (!query) return url
-  const next = new URL(url)
-  Object.entries(query).forEach(([key, value]) => next.searchParams.set(key, value))
-  return next.toString()
+const isEdit = (request: Request) => (request.images?.length ?? 0) > 0
+
+const reference = (asset: Media.Asset): Effect.Effect<Record<string, unknown>, AIError> => {
+  const inline = asset.inline()
+  if (inline) return Effect.succeed({ url: inline.dataUrl, type: "image_url" as const })
+  const url = ProviderShared.mediaUrl(asset)
+  if (url) return Effect.succeed({ url, type: "image_url" as const })
+  const id = MediaInput.refID(asset, PROVIDER)
+  if (id) return Effect.succeed({ file_id: id })
+  return Effect.fail(ProviderShared.invalidRequest(`${NAME} accepts image URLs, data URLs, bytes, and xAI file IDs`))
 }
 
-export const model = (input: ModelInput) => {
-  const route: ImageRoute<XAIImageOptions> = {
-    id: ADAPTER,
-    generate: Effect.fn("XAIImages.generate")(function* (request: ImageRequestFor<XAIImageOptions>, execute) {
-      const http = mergeHttpOptions(request.model.http, request.http)
-      const imageReferences = (request.images ?? []).map((image) => {
-        if (image.type === "bytes") return { url: ImageInputs.dataUrl(image), type: "image_url" as const }
-        if (image.type === "url") return { url: image.url, type: "image_url" as const }
-        if (image.type === "file-id") return { file_id: image.id }
-        return undefined
-      })
-      if (imageReferences.some((image) => image === undefined))
-        return yield* ImageInputs.invalid("xAI Images accepts image URLs, data URLs, bytes, and file IDs")
-      const requestBody = mergeJsonRecords(
+const fromRequest = Effect.fn("XAIImages.fromRequest")(function* (request: Request) {
+  const references = yield* Effect.forEach(request.images ?? [], reference)
+  return MediaProtocol.json(
+    mergeJsonRecords(
+      {
+        model: request.model.id,
+        prompt: request.prompt,
+        // xAI takes one edit source as `image` and several as `images`.
+        image: references.length === 1 ? references[0] : undefined,
+        images: references.length > 1 ? references : undefined,
+        n: request.n,
+        aspect_ratio: request.aspectRatio,
+      },
+      nativeOptions(request.providerOptions),
+      request.http?.body,
+    ) ?? {},
+  )
+})
+
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+
+const decodeResponse = Effect.fn("XAIImages.decodeResponse")(function* (
+  response: HttpClientResponse.HttpClientResponse,
+) {
+  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, XAIImageResponse)(response)
+  const decoded = output.value
+  const images = yield* Effect.forEach(decoded.data, (item, index) => {
+    const providerMetadata =
+      item.revised_prompt === undefined || item.revised_prompt === null
+        ? undefined
+        : { xai: { revisedPrompt: item.revised_prompt } }
+    if (item.b64_json)
+      return MediaInput.decodedAsset(
+        output.invalid,
+        `${NAME} result ${index}`,
+        item.b64_json,
+        item.mime_type ?? undefined,
         {
-          model: request.model.id,
-          prompt: request.prompt,
-          image: imageReferences.length === 1 ? imageReferences[0] : undefined,
-          images: imageReferences.length > 1 ? imageReferences : undefined,
+          providerMetadata,
         },
-        nativeOptions(request.options),
-        http?.body,
-      ) as XAIImageBody
-      const text = ProviderShared.encodeJson(requestBody)
-      const url = applyQuery(
-        `${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${imageReferences.length === 0 ? PATH : EDIT_PATH}`,
-        http?.query,
       )
-      const headers = yield* Auth.toEffect(input.auth)({
-        request,
-        method: "POST",
-        url,
-        body: text,
-        headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
-      })
-      const response = yield* execute(
-        HttpClientRequest.post(url).pipe(
-          HttpClientRequest.setHeaders(headers),
-          HttpClientRequest.bodyText(text, "application/json"),
-        ),
-      )
-      const output = yield* ProviderShared.imageResponse(ADAPTER, "xAI Images", response)
-      const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(XAIImageResponse))(output.body).pipe(
-        Effect.mapError((cause) => output.invalid("xAI Images returned an invalid response", cause)),
-      )
-      const images = yield* Effect.forEach(decoded.data, (item, index) => {
-        const mediaType = item.mime_type ?? "application/octet-stream"
-        if (item.b64_json)
-          return Effect.fromResult(Encoding.decodeBase64(item.b64_json)).pipe(
-            Effect.mapError((cause) =>
-              output.invalid(`xAI Images result ${index} contains invalid base64 data`, cause),
-            ),
-            Effect.map(
-              (data) =>
-                new GeneratedImage({
-                  mediaType,
-                  data,
-                  providerMetadata:
-                    item.revised_prompt === undefined || item.revised_prompt === null
-                      ? undefined
-                      : { xai: { revisedPrompt: item.revised_prompt } },
-                }),
-            ),
-          )
-        if (item.url)
-          return Effect.succeed(
-            new GeneratedImage({
-              mediaType,
-              data: item.url,
-              providerMetadata:
-                item.revised_prompt === undefined || item.revised_prompt === null
-                  ? undefined
-                  : { xai: { revisedPrompt: item.revised_prompt } },
-            }),
-          )
-        return Effect.fail(output.invalid(`xAI Images result ${index} has neither image data nor a URL`))
-      })
-      if (images.length === 0) return yield* output.invalid("xAI Images returned no images")
-      const usage = ProviderShared.isRecord(decoded.usage) ? decoded.usage : undefined
-      return new ImageResponse({
-        images,
-        usage: usage === undefined ? undefined : new Usage({ providerMetadata: { xai: usage } }),
-        providerMetadata: usage === undefined ? undefined : { xai: { usage } },
-      })
-    }),
-  }
-  return ImageModel.make<XAIImageOptions>({ id: input.id, provider: "xai", route, http: input.http })
-}
+    if (item.url)
+      return Effect.succeed(Media.url(item.url, { mediaType: item.mime_type ?? undefined, providerMetadata }))
+    return Effect.fail(output.invalid(`${NAME} result ${index} has neither image data nor a URL`))
+  })
+  if (images.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  const usage = ProviderShared.isRecord(decoded.usage) ? decoded.usage : undefined
+  // xAI reports image counts rather than tokens, seconds, or credits; the raw record stays in provider metadata.
+  return new ImageResponse({
+    images,
+    providerMetadata: usage === undefined ? undefined : { xai: { usage } },
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+
+export const protocol = MediaProtocol.inline<Request, ImageResponse>({
+  id: ADAPTER,
+  name: NAME,
+  unsupported: ["mask", "size", "seed", "format"],
+  body: { from: fromRequest },
+  response: { decode: decodeResponse },
+})
+
+export const model = (input: MediaRoute.ModelInput) =>
+  ImageModel.fromRoute<XAIImageOptions>(
+    {
+      id: ADAPTER,
+      provider: PROVIDER,
+      protocol,
+      baseURL: DEFAULT_BASE_URL,
+      path: ({ request }) => (isEdit(request) ? EDIT_PATH : PATH),
+    },
+    input,
+  )
 
 export const XAIImages = {
+  protocol,
   model,
 } as const

packages/ai/src/protocols/zai-images.ts

@@ -1,29 +1,34 @@
 import { Effect, Schema } from "effect"
-import { Headers, HttpClientRequest } from "effect/unstable/http"
-import { GeneratedImage, ImageModel, ImageResponse, type ImageRequestFor, type ImageRoute } from "../image.js"
-import { Auth, type Definition as AuthDefinition } from "../route/auth.js"
-import { mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema/index.js"
-import { ProviderShared } from "./shared.js"
-import { ImageInputs } from "./utils/image-input.js"
+import type { HttpClientResponse } from "effect/unstable/http"
+import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
+import { Media } from "../media.js"
+import { MediaProtocol } from "../route/media-protocol.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, mergeJsonRecords } from "../schema/index.js"
 
 const ADAPTER = "zai-images"
+const NAME = "Z.ai Images"
+const PROVIDER = ProviderID.make("zai")
 export const DEFAULT_BASE_URL = "https://api.z.ai/api/paas/v4"
 export const PATH = "/images/generations"
 
+// ---------------------------------------------------------------------------
+// 1. Public model input
+// ---------------------------------------------------------------------------
+
 export type ZAIImageString<Known extends string> = Known | (string & {})
 
+/** Provider-native options. The common `size` field lives on the request. */
 export type ZAIImageOptions = {
-  readonly size?: ZAIImageString<
-    "1024x1024" | "768x1344" | "864x1152" | "1344x768" | "1152x864" | "1440x720" | "720x1440"
-  >
   readonly quality?: ZAIImageString<"hd" | "standard">
   readonly userID?: string
 } & Record<string, unknown>
 
-type ZAIImageBody = Record<string, unknown> & {
-  readonly model: string
-  readonly prompt: string
-}
+export type Request = ImageRequestFor<ZAIImageOptions>
+
+// ---------------------------------------------------------------------------
+// 2. Response schema
+// ---------------------------------------------------------------------------
 
 const ZAIImageResponse = Schema.Struct({
   created: Schema.optional(Schema.Int),
@@ -40,84 +45,81 @@ const ZAIImageResponse = Schema.Struct({
   ),
 })
 
-export interface ModelInput {
-  readonly id: string
-  readonly auth: AuthDefinition
-  readonly baseURL?: string
-  readonly headers?: Record<string, string>
-  readonly http?: HttpOptions
-}
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
 
 const nativeOptions = (options: ZAIImageOptions | undefined) => {
   if (!options) return undefined
   const { userID, ...native } = options
-  return {
-    user_id: userID,
-    ...native,
-  }
+  return { user_id: userID, ...native }
 }
 
-const applyQuery = (url: string, query: Record<string, string> | undefined) => {
-  if (!query) return url
-  const next = new URL(url)
-  Object.entries(query).forEach(([key, value]) => next.searchParams.set(key, value))
-  return next.toString()
-}
+const fromRequest = Effect.fn("ZAIImages.fromRequest")(function* (request: Request) {
+  return MediaProtocol.json(
+    mergeJsonRecords(
+      { model: request.model.id, prompt: request.prompt, size: request.size },
+      nativeOptions(request.providerOptions),
+      request.http?.body,
+    ) ?? {},
+  )
+})
 
-export const model = (input: ModelInput) => {
-  const route: ImageRoute<ZAIImageOptions> = {
-    id: ADAPTER,
-    generate: Effect.fn("ZAIImages.generate")(function* (request: ImageRequestFor<ZAIImageOptions>, execute) {
-      if ((request.images?.length ?? 0) > 0)
-        return yield* ImageInputs.invalid("Z.ai hosted image generation does not support image inputs")
-      const http = mergeHttpOptions(request.model.http, request.http)
-      const requestBody = mergeJsonRecords(
-        { model: request.model.id, prompt: request.prompt },
-        nativeOptions(request.options),
-        http?.body,
-      ) as ZAIImageBody
-      const text = ProviderShared.encodeJson(requestBody)
-      const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${PATH}`, http?.query)
-      const headers = yield* Auth.toEffect(input.auth)({
-        request,
-        method: "POST",
-        url,
-        body: text,
-        headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
-      })
-      const response = yield* execute(
-        HttpClientRequest.post(url).pipe(
-          HttpClientRequest.setHeaders(headers),
-          HttpClientRequest.bodyText(text, "application/json"),
-        ),
-      )
-      const output = yield* ProviderShared.imageResponse(ADAPTER, "Z.ai Images", response)
-      const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ZAIImageResponse))(output.body).pipe(
-        Effect.mapError((cause) => output.invalid("Z.ai Images returned an invalid response", cause)),
-      )
-      if (decoded.data.length === 0) return yield* output.invalid("Z.ai Images returned no images")
-      return new ImageResponse({
-        images: decoded.data.map(
-          (item) =>
-            new GeneratedImage({
-              mediaType: "application/octet-stream",
-              data: item.url,
-            }),
-        ),
-        providerMetadata: {
-          zai: {
-            created: decoded.created,
-            id: decoded.id,
-            requestID: decoded.request_id,
-            contentFilter: decoded.content_filter,
-          },
-        },
-      })
-    }),
-  }
-  return ImageModel.make<ZAIImageOptions>({ id: input.id, provider: "zai", route, http: input.http })
-}
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+
+const decodeResponse = Effect.fn("ZAIImages.decodeResponse")(function* (
+  response: HttpClientResponse.HttpClientResponse,
+) {
+  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, ZAIImageResponse)(response)
+  const decoded = output.value
+  if (decoded.data.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  const filters = decoded.content_filter ?? []
+  return new ImageResponse({
+    // Z.ai returns only URLs and no content type; the media type resolves when the asset is materialized.
+    images: decoded.data.map((item) => Media.url(item.url)),
+    // Z.ai reports applied content filters alongside a successful result; surface them instead of dropping them.
+    notices:
+      filters.length === 0
+        ? undefined
+        : filters.map((filter) => ({
+            type: "moderated" as const,
+            message: `${NAME} applied a content filter${filter.role === undefined ? "" : ` for ${filter.role}`}${
+              filter.level === undefined ? "" : ` at level ${filter.level}`
+            }`,
+            providerMetadata: { zai: filter },
+          })),
+    providerMetadata: {
+      zai: {
+        created: decoded.created,
+        id: decoded.id,
+        requestID: decoded.request_id,
+        contentFilter: decoded.content_filter,
+      },
+    },
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+
+export const protocol = MediaProtocol.inline<Request, ImageResponse>({
+  id: ADAPTER,
+  name: NAME,
+  unsupported: ["images", "mask", "n", "aspectRatio", "seed", "format"],
+  body: { from: fromRequest },
+  response: { decode: decodeResponse },
+})
+
+export const model = (input: MediaRoute.ModelInput) =>
+  ImageModel.fromRoute<ZAIImageOptions>(
+    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
+    input,
+  )
 
 export const ZAIImages = {
+  protocol,
   model,
 } as const

packages/ai/src/provider-error.ts

@@ -73,9 +73,27 @@ const SERVER_CODES = new Set([
   "serviceunavailableexception",
 ])
 const INVALID_REQUEST_CODES = new Set(["invalid_prompt", "invalid_request_error", "validationexception"])
+// Azure OpenAI reports `content_filter` with `innererror.code` ResponsibleAIPolicyViolation.
+// OpenRouter tags provider failures with a typed `error_type`; its Responses skin also
+// emits `image_content_policy_violation` as the native code.
+const CONTENT_POLICY_CODES = new Set([
+  "content_filter",
+  "responsibleaipolicyviolation",
+  "content_policy_violation",
+  "image_content_policy_violation",
+  "refusal",
+])
+// OpenCode Zen replaces upstream codes outside its allow-list but keeps the original
+// as a `[code]` label at the start of the rewritten message.
+const GATEWAY_CODE_LABEL = /^[^:\n]+: \[([A-Za-z0-9_.-]+)\]/
 const RATE_LIMIT_TEXT = /rate increased too quickly|rate[-_\s]?limit|too[_\s]?many[_\s]?requests/i
 const QUOTA_TEXT = /insufficient[-_\s]?quota|quota[-_\s]?exceeded/i
-const CONTENT_POLICY_TEXT = /content[-_\s]?policy|content_filter|safety/i
+// Policy rejections without a dedicated code, matched against the provider's own
+// explanation only. OpenAI reuses `invalid_prompt` for usage-policy rejections while
+// Bedrock Mantle reuses it for schema validation; Anthropic reports blocked output
+// under `invalid_request_error`.
+const CONTENT_POLICY_TEXT =
+  /violating our usage policy|blocked by content filtering policy|content[-_\s]?policy|rejected as a result of our safety system/i
 const SERVER_ERROR_TEXT =
   /\b(?:try again|(?:please |you can )?retry (?:the |this |your )?request|try (?:the |this |your )?request again|(?:currently |temporarily )?at capacity|overloaded|temporarily unavailable|service[-_\s]?unavailable|(?:server|internal)[-_\s]?error|server (?:is )?busy|provider returned (?:an )?error|resource[-_\s]?exhausted|upstream (?:connect|connection|request)|request buffer limit while retrying upstream)\b/i
 
@@ -102,9 +120,12 @@ export interface ProviderFailure {
 export function classifyProviderFailure(input: ProviderFailure): AIError["reason"] {
   const details = { message: input.message, body: input.rawBody, http: input.http, cause: input.cause }
   const body = input.rawBody ?? ""
-  const codes = [...providerCodes(input.data), ...providerCodes(body), ...providerCodes(input.message)].map((code) =>
-    code.toLowerCase(),
-  )
+  const codes = [
+    ...providerCodes(input.data),
+    ...providerCodes(body),
+    ...providerCodes(input.message),
+    ...(GATEWAY_CODE_LABEL.exec(input.message)?.slice(1) ?? []),
+  ].map((code) => code.toLowerCase())
   // Scan the raw payload too so signals missing from the summary message
   // (e.g. overflow phrases nested in a JSON error body) still classify.
   const text = [input.message, body].filter((value) => value.length > 0).join("\n")
@@ -120,7 +141,8 @@ export function classifyProviderFailure(input: ProviderFailure): AIError["reason
     return new InvalidRequestError({ ...details, classification: "context-overflow" })
   if (input.status === 413 || isPayloadTooLarge(text))
     return new InvalidRequestError({ ...details, classification: "payload-too-large" })
-  if (CONTENT_POLICY_TEXT.test(text)) return new ContentPolicyError(details)
+  if (codes.some((code) => CONTENT_POLICY_CODES.has(code)) || (clientScoped && CONTENT_POLICY_TEXT.test(input.message)))
+    return new ContentPolicyError(details)
   if (codes.some((code) => QUOTA_CODES.has(code)) || (input.status === 429 && QUOTA_TEXT.test(text)))
     return new QuotaExceededError(details)
   if (input.status === 401 || input.status === 403 || codes.some((code) => AUTH_CODES.has(code)))
@@ -160,12 +182,24 @@ function providerCodes(value: unknown) {
   const decoded = typeof value === "string" ? Option.getOrUndefined(decodeJson(value)) : value
   if (!isRecord(decoded)) return []
   const error = isRecord(decoded.error) ? decoded.error : undefined
+  const inner = error && isRecord(error.innererror) ? error.innererror : undefined
+  const metadata = error && isRecord(error.metadata) ? error.metadata : undefined
   const response = isRecord(decoded.response) ? decoded.response : undefined
   const responseError = response && isRecord(response.error) ? response.error : undefined
   const exception = isRecord(decoded.exception) ? decoded.exception : undefined
-  return [decoded.code, error?.code, error?.type, error?.status, responseError?.code, exception?.type].filter(
-    (value): value is string => typeof value === "string",
-  )
+  return [
+    decoded.code,
+    decoded.error_type,
+    error?.code,
+    error?.type,
+    error?.status,
+    error?.error_type,
+    inner?.code,
+    metadata?.error_type,
+    responseError?.code,
+    response?.error_type,
+    exception?.type,
+  ].filter((value): value is string => typeof value === "string")
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

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,8 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("alibaba")
 
@@ -34,9 +36,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 +84,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` } }
@@ -97,7 +104,7 @@ export const configure = (input: Config) => {
       })
       .model<MessagesOptionsInput>({ id, compatibility: { requireSignature: false } })
   const responses = (id: string | ModelID) => responsesRoute.with(common).model<ResponsesOptionsInput>({ id })
-  return { id, model: chat, chat, messages, responses, configure }
+  return ModelRef.facade({ id, model: chat, chat, messages, responses, configure })
 }
 
 export const provider = { id, configure }
@@ -115,7 +122,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

@@ -1,10 +1,12 @@
 import { Route, type RouteDefaultsInput } from "../route/client.js"
+import { Endpoint } from "../route/endpoint.js"
 import type { ProviderPackage } from "../provider-package.js"
 import { OpenAIChat } from "../protocols/openai-chat.js"
-import { OpenAIResponses } from "../protocols/openai-responses.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"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("amazon-bedrock")
 
@@ -22,26 +24,25 @@ 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",
   provider: id,
   providerMetadataKey: "mantle",
-  protocol: OpenAIResponses.protocol,
-  endpoint: OpenAIResponses.route.endpoint,
-  auth: OpenAIResponses.route.auth,
-  transport: OpenAIResponses.httpTransport,
-  defaults: OpenAIResponses.route.defaults,
+  protocol: OpenResponses.protocol,
+  endpoint: Endpoint.path(OpenResponses.PATH),
+  transport: OpenResponses.httpTransport,
+  defaults: { providerOptions: { store: false, include: ["reasoning.encrypted_content"] } },
 })
 
 const chatRoute = OpenAIChat.route.with({
@@ -79,9 +80,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)
@@ -94,29 +98,40 @@ export const configure = (input: Config = {}) => {
       .with(withOpenAIOptions(modelID, modelDefaults))
       .model<OpenAIProviderOptionsInput>({ id: modelID })
 
-  return {
+  return ModelRef.facade({
     id,
     model: responses,
     chat,
     responses,
     configure,
-  }
+  })
 }
 
 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,9 +1,10 @@
 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"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("amazon-bedrock")
 
@@ -39,8 +40,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,
@@ -53,11 +55,11 @@ const configuredRoute = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => route.model({ id: modelID }),
     configure,
-  }
+  })
 }
 
 export const provider = configure()

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

@@ -3,7 +3,8 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export type AnthropicOptionsInput = AnthropicMessages.OptionsInput
 export type AnthropicProviderOptionsInput = AnthropicMessages.ProviderOptionsInput
@@ -19,13 +20,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 +37,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,
@@ -45,11 +50,11 @@ export const configure = (input: Config) => {
     endpoint: { baseURL },
     auth: auth(input),
   })
-  return {
+  return ModelRef.facade({
     id: ProviderID.make(provider),
     model: (modelID: string | ModelID) => route.model<AnthropicMessages.ProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -59,17 +64,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,9 +2,10 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export type AnthropicOptionsInput = AnthropicMessages.OptionsInput
 export type AnthropicProviderOptionsInput = AnthropicMessages.ProviderOptionsInput
@@ -21,12 +22,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">) => {
@@ -44,25 +45,28 @@ export const configure = (input: Config = {}) => {
     baseURL: baseURL ?? AnthropicMessages.DEFAULT_BASE_URL,
     provider: id,
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => compatible.model(modelID),
     configure,
-  }
+  })
 }
 
 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

@@ -1,13 +1,13 @@
-import { Headers } from "effect/unstable/http"
 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"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("azure")
 const routeAuth = Auth.remove("authorization")
@@ -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`
@@ -61,11 +61,6 @@ const responsesRoute = OpenAIResponses.route.with({
       url.searchParams.delete("api-version")
       return url.toString()
     },
-    headers: (headers) => {
-      const apiKey = headers["api-key"]
-      if (!apiKey) return headers
-      return Headers.remove(Headers.set(headers, "authorization", `Bearer ${apiKey}`), "api-key")
-    },
   }),
 })
 
@@ -135,15 +130,15 @@ export const configure = (input: Config) => {
   const chat = (modelID: string | ModelID) =>
     configuredRoute(chatRoute, input, modelID)
       .with(withOpenAIOptions(modelID, modelDefaults))
-      .model<OpenAIProviderOptionsInput>({ id: modelID })
+      .model<OpenAIProviderOptionsInput>({ id: modelID, compatibility: { supportsPromptCacheKey: true } })
 
-  return {
+  return ModelRef.facade({
     id,
     model: responses,
     responses,
     chat,
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -151,19 +146,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

@@ -5,6 +5,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("baseten")
 const baseURL = "https://inference.baseten.co/v1"
@@ -15,11 +16,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",
@@ -39,22 +40,25 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: endpoint ?? baseURL },
     auth: AuthOptions.bearer(input, "BASETEN_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => configured.model<OpenAIProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 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

@@ -5,6 +5,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("cerebras")
 const baseURL = "https://api.cerebras.ai/v1"
@@ -15,11 +16,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",
@@ -39,24 +40,32 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: endpoint ?? baseURL },
     auth: AuthOptions.bearer(input, "CEREBRAS_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) =>
       configured.model<OpenAIProviderOptionsInput>({
         id: modelID,
-        compatibility: { maxTokensField: "max_tokens", reasoningField: "reasoning", supportsStore: false },
+        compatibility: {
+          maxTokensField: "max_tokens",
+          reasoningField: "reasoning",
+          supportsStore: false,
+          supportsPromptCacheKey: true,
+        },
       }),
     configure,
-  }
+  })
 }
 
 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

@@ -1,12 +1,12 @@
-import type { Config, Redacted } from "effect"
+import { Schema, type Config, type Redacted } from "effect"
 import type { ProviderPackage } from "../provider-package.js"
-import { OpenAIChat } from "../protocols/openai-chat.js"
+import { AnthropicMessages, OpenAIChat, OpenAIResponses } from "../protocols/index.js"
 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 type { RouteDefaultsInput } from "../route/client.js"
+import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("cloudflare-ai-gateway")
 export const authEnvVars = ["CLOUDFLARE_API_TOKEN", "CF_AIG_TOKEN"] as const
@@ -14,85 +14,148 @@ export const authEnvVars = ["CLOUDFLARE_API_TOKEN", "CF_AIG_TOKEN"] as const
 type GatewayURL = AtLeastOne<{
   readonly accountId: string
   readonly baseURL: string
-}> & {
+}>
+
+type GatewayOptions = {
   readonly gatewayId?: string
+  readonly metadata?: unknown
+  readonly cacheTtl?: number
+  readonly cacheKey?: string
+  readonly skipCache?: boolean
+  readonly collectLog?: boolean
 }
 
 export type LanguageModelOptions = GatewayURL &
+  GatewayOptions &
   Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
-    /** Cloudflare AI Gateway authentication token. Sent as `cf-aig-authorization`. */
     readonly gatewayApiKey?: string | Redacted.Redacted | Config.Config<string | Redacted.Redacted>
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 export type Settings = ProviderPackage.Settings &
-  GatewayURL & {
+  OpenAIProviderOptionsInput &
+  GatewayURL &
+  GatewayOptions & {
     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")
-  return `https://gateway.ai.cloudflare.com/v1/${encodeURIComponent(input.accountId)}/${encodeURIComponent(input.gatewayId?.trim() || "default")}/compat`
+  if (!input.accountId)
+    throw new ProviderConfigurationError({
+      provider: id,
+      message: "CloudflareAIGateway.configure requires accountId unless baseURL is supplied",
+    })
+  return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(input.accountId)}/ai/v1`
 }
 
+export const responsesRoute = OpenAIResponses.route.with({
+  id: "cloudflare-ai-gateway-responses",
+  provider: id,
+  endpoint: { baseURL: undefined },
+})
+
+export const messagesRoute = AnthropicMessages.route.with({
+  id: "cloudflare-ai-gateway-messages",
+  provider: id,
+  endpoint: { baseURL: undefined },
+})
+
+export const route = OpenAIChat.route.with({
+  id: "cloudflare-ai-gateway-chat",
+  provider: id,
+  endpoint: { baseURL: undefined },
+})
+
+export const routes = [responsesRoute, messagesRoute, route]
+
 const auth = (input: LanguageModelOptions) => {
   if ("auth" in input && input.auth) return input.auth
-  const gateway = Auth.optional(input.gatewayApiKey, "gatewayApiKey")
+  return Auth.optional(input.gatewayApiKey ?? ("apiKey" in input ? input.apiKey : undefined), "apiKey")
     .orElse(Auth.config(authEnvVars[0]))
     .orElse(Auth.config(authEnvVars[1]))
-    .pipe(Auth.bearerHeader("cf-aig-authorization"))
-  if (!("apiKey" in input) || input.apiKey === undefined) return gateway
-  if (input.gatewayApiKey === undefined) return Auth.bearer(input.apiKey)
-  return Auth.bearerHeader("cf-aig-authorization", input.gatewayApiKey).andThen(Auth.bearer(input.apiKey))
+    .bearer()
 }
 
-export const route = Route.make({
-  id: "cloudflare-ai-gateway",
-  provider: id,
-  providerMetadataKey: "cloudflare-ai-gateway",
-  protocol: OpenAIChat.protocol,
-  endpoint: Endpoint.path("/chat/completions"),
-  framing: OpenAIChat.framing,
+const headers = (input: LanguageModelOptions) => ({
+  ...(input.gatewayId === undefined ? {} : { "cf-aig-gateway-id": input.gatewayId.trim() || "default" }),
+  ...(input.metadata === undefined
+    ? {}
+    : { "cf-aig-metadata": Schema.encodeSync(Schema.fromJsonString(Schema.Unknown))(input.metadata) }),
+  ...(input.cacheTtl === undefined ? {} : { "cf-aig-cache-ttl": String(input.cacheTtl) }),
+  ...(input.cacheKey === undefined ? {} : { "cf-aig-cache-key": input.cacheKey }),
+  ...(input.skipCache === undefined ? {} : { "cf-aig-skip-cache": String(input.skipCache) }),
+  ...(input.collectLog === undefined ? {} : { "cf-aig-collect-log": String(input.collectLog) }),
+  ...input.headers,
 })
 
-export const routes = [route]
+const modelID = (input: string | ModelID) => {
+  const value = String(input)
+  if (value.startsWith("workers-ai/")) return value.slice("workers-ai/".length)
+  if (value.startsWith("anthropic/")) return `anthropic/${value.slice("anthropic/".length).replaceAll(".", "-")}`
+  return value
+}
 
 export const configure = (input: LanguageModelOptions) => {
-  const {
-    accountId: _accountId,
-    gatewayId: _gatewayId,
-    apiKey: _apiKey,
-    gatewayApiKey: _gatewayApiKey,
-    baseURL: _baseURL,
-    auth: _auth,
-    ...defaults
-  } = input
-  const configured = route.with({
-    ...defaults,
+  const defaults = {
     endpoint: { baseURL: baseURL(input) },
     auth: auth(input),
-  })
-  return {
-    id,
-    model: (modelID: string | ModelID) => configured.model<OpenAIProviderOptionsInput>({ id: modelID }),
-    configure,
+    headers: headers(input),
+    http: input.http,
+    providerOptions: input.providerOptions,
   }
+  const responses = responsesRoute.with(defaults)
+  const messages = messagesRoute.with(defaults)
+  const chat = route.with(defaults)
+  return ModelRef.facade({
+    id,
+    model: (input: string | ModelID) => {
+      const wire = modelID(input)
+      if (String(input).startsWith("openai/")) return responses.model<OpenAIProviderOptionsInput>({ id: wire })
+      if (String(input).startsWith("anthropic/")) return messages.model<OpenAIProviderOptionsInput>({ id: wire })
+      return chat.model<OpenAIProviderOptionsInput>({ id: wire })
+    },
+    configure,
+  })
 }
 
 export const provider = { id, configure }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
-  configure({
-    apiKey: settings.apiKey,
-    gatewayApiKey: settings.gatewayApiKey,
-    baseURL: baseURL(settings),
-    headers: settings.headers === undefined ? undefined : { ...settings.headers },
-    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
-    providerOptions: settings.providerOptions,
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  {
+    accountId,
+    apiKey,
+    baseURL: configuredBaseURL,
+    body,
+    cacheKey,
+    cacheTtl,
+    collectLog,
+    gatewayApiKey,
+    gatewayId,
+    headers,
+    metadata,
+    skipCache,
+    ...providerOptions
+  },
+) => {
+  const connection = configuredBaseURL === undefined ? { accountId: accountId ?? "" } : { baseURL: configuredBaseURL }
+  return configure({
+    ...connection,
+    apiKey,
+    cacheKey,
+    cacheTtl,
+    collectLog,
+    gatewayApiKey,
+    gatewayId,
+    headers: headers === undefined ? undefined : { ...headers },
+    http: body === undefined ? undefined : { body: { ...body } },
+    metadata,
+    providerOptions,
+    skipCache,
   }).model(modelID)
+}
 
 export * as CloudflareAIGateway from "./cloudflare-ai-gateway.js"

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

@@ -3,11 +3,12 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("cloudflare-workers-ai")
-export const authEnvVars = ["CLOUDFLARE_API_KEY", "CLOUDFLARE_WORKERS_AI_TOKEN"] as const
+export const authEnvVars = ["CLOUDFLARE_API_KEY", "CLOUDFLARE_WORKERS_AI_TOKEN", "CLOUDFLARE_API_TOKEN"] as const
 
 type WorkersAIURL = AtLeastOne<{
   readonly accountId: string
@@ -21,14 +22,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`
 }
 
@@ -50,22 +55,24 @@ export const configure = (input: LanguageModelOptions) => {
     endpoint: { baseURL: baseURL(input) },
     auth: AuthOptions.bearer(input, authEnvVars),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => configured.model<OpenAIProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 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

@@ -5,6 +5,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("deepinfra")
 const baseURL = "https://api.deepinfra.com/v1/openai"
@@ -15,11 +16,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",
@@ -42,24 +43,32 @@ export const configure = (input: LanguageModelOptions = {}) => {
     },
     auth: AuthOptions.bearer(input, "DEEPINFRA_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) =>
       configured.model<OpenAIProviderOptionsInput>({
         id: modelID,
-        compatibility: { maxTokensField: "max_tokens", reasoningField: "reasoning_content", supportsStore: false },
+        compatibility: {
+          maxTokensField: "max_tokens",
+          reasoningField: "reasoning_content",
+          supportsStore: false,
+          supportsPromptCacheKey: true,
+        },
       }),
     configure,
-  }
+  })
 }
 
 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

@@ -5,6 +5,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("deepseek")
 const baseURL = "https://api.deepseek.com/v1"
@@ -15,11 +16,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",
@@ -39,7 +40,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: endpoint ?? baseURL },
     auth: AuthOptions.bearer(input, "DEEPSEEK_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) =>
       configured.model<OpenAIProviderOptionsInput>({
@@ -47,18 +48,21 @@ export const configure = (input: LanguageModelOptions = {}) => {
         compatibility: { maxTokensField: "max_tokens", supportsStore: false },
       }),
     configure,
-  }
+  })
 }
 
 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

@@ -5,6 +5,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("fireworks")
 const baseURL = "https://api.fireworks.ai/inference/v1"
@@ -15,11 +16,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",
@@ -39,22 +40,26 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: endpoint ?? baseURL },
     auth: AuthOptions.bearer(input, "FIREWORKS_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
-    model: (modelID: string | ModelID) => configured.model<OpenAIProviderOptionsInput>({ id: modelID }),
+    model: (modelID: string | ModelID) =>
+      configured.model<OpenAIProviderOptionsInput>({ id: modelID, compatibility: { supportsPromptCacheKey: true } }),
     configure,
-  }
+  })
 }
 
 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,9 +2,10 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("google-vertex")
 
@@ -16,14 +17,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 +38,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,
@@ -61,11 +63,11 @@ const configuredRoute = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => route.model<OpenAIProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -73,15 +75,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,8 +5,9 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export type AnthropicOptionsInput = AnthropicMessages.OptionsInput
 export type AnthropicProviderOptionsInput = AnthropicMessages.ProviderOptionsInput
@@ -25,14 +26,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 +68,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,
@@ -91,11 +92,11 @@ const configuredRoute = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => route.model<AnthropicMessages.ProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -105,16 +106,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,9 +2,10 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("google-vertex")
 
@@ -16,14 +17,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 +40,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,
@@ -63,11 +64,11 @@ const configuredRoute = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => route.model<OpenResponsesProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -77,16 +78,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,8 +6,9 @@ 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"
+import { ModelRef } from "../model-ref.js"
 
 export interface GeminiOptionsInput extends Gemini.OptionsInput {
   readonly labels?: Readonly<Record<string, string>>
@@ -26,6 +27,7 @@ export type Config = RouteDefaultsInput &
   }
 
 export type Settings = ProviderPackage.Settings &
+  GeminiProviderOptionsInput &
   (
     | { readonly accessToken?: string; readonly apiKey?: never }
     | { readonly accessToken?: never; readonly apiKey?: string }
@@ -33,11 +35,10 @@ 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) {
-  const body = yield* Gemini.protocol.body.from(request)
+  const { serviceTier: _, ...body } = yield* Gemini.protocol.body.from(request)
   // Vertex's native REST schema rejects `id` on FunctionCall/FunctionResponse parts with HTTP 400,
   // unlike AI Studio, so history minted there cannot be lowered verbatim.
   const contents = body.contents.map((content) => ({
@@ -75,6 +76,10 @@ const route = Route.make({
     return `/${model.startsWith("endpoints/") ? model : `models/${model}`}:streamGenerateContent?alt=sse`
   }),
   auth: Auth.none,
+  headers: ({ request }): Record<string, string> => {
+    const serviceTier = request.providerOptions?.serviceTier
+    return typeof serviceTier === "string" ? { "x-vertex-ai-llm-shared-request-type": serviceTier } : {}
+  },
   framing: Framing.sse,
 })
 
@@ -93,7 +98,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 =
@@ -109,28 +117,34 @@ const configuredRoute = (input: Config, modelID: string | ModelID) => {
 }
 
 export const configure = (input: Config = {}) => {
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) =>
       configuredRoute(input, modelID).model<GeminiProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 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

@@ -5,6 +5,7 @@ import type { ProviderPackage } from "../provider-package.js"
 import { HttpOptions, ProviderID, mergeHttpOptions, type ModelID } from "../schema/index.js"
 import { Gemini } from "../protocols/gemini.js"
 import { GoogleImages } from "../protocols/google-images.js"
+import { ModelRef } from "../model-ref.js"
 
 export type { GoogleImageOptions } from "../protocols/google-images.js"
 export type GeminiOptionsInput = Gemini.OptionsInput
@@ -20,11 +21,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
@@ -48,22 +49,25 @@ export const configure = (input: Config = {}) => {
       headers: input.headers,
       http: mergeHttpOptions(input.http === undefined ? undefined : HttpOptions.make(input.http)),
     })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => route.model<Gemini.ProviderOptionsInput>({ id: modelID }),
     image,
     configure,
-  }
+  })
 }
 
 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

@@ -8,6 +8,7 @@ import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { ProviderID, type ModelID, type LLMRequest } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("groq")
 const baseURL = "https://api.groq.com/openai/v1"
@@ -26,11 +27,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),
@@ -84,7 +85,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: endpoint ?? baseURL },
     auth: AuthOptions.bearer(input, "GROQ_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) =>
       configured.model<ProviderOptions>({
@@ -98,18 +99,21 @@ export const configure = (input: LanguageModelOptions = {}) => {
         },
       }),
     configure,
-  }
+  })
 }
 
 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

@@ -9,6 +9,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { HttpOptions, ProviderID, ToolDefinition, type ModelID } from "../schema/index.js"
 import type { OpenResponsesProviderOptionsInput } from "./open-responses-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("meta")
 const baseURL = "https://api.meta.ai/v1"
@@ -79,11 +80,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",
@@ -132,7 +133,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
   const chat = (modelID: string | ModelID) =>
     configuredChat.model<OpenResponsesProviderOptionsInput>({
       id: modelID,
-      compatibility: { maxTokensField: "max_completion_tokens", supportsStore: false },
+      compatibility: { maxTokensField: "max_completion_tokens", supportsStore: false, supportsPromptCacheKey: true },
     })
   const messages = (modelID: string | ModelID) =>
     configuredMessages.model<MessagesOptionsInput>({
@@ -147,7 +148,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
       headers: input.headers,
       http: input.http === undefined ? undefined : HttpOptions.make(input.http),
     })
-  return { id, model: responses, responses, chat, messages, image, configure }
+  return ModelRef.facade({ id, model: responses, responses, chat, messages, image, configure })
 }
 
 export const provider = configure()
@@ -169,13 +170,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

@@ -10,6 +10,7 @@ import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
 import { Protocol } from "../route/protocol.js"
 import { ProviderID, type LLMRequest, type ModelID } from "../schema/index.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("minimax")
 
@@ -40,11 +41,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 })),
@@ -120,21 +121,21 @@ export const configure = (input: Config = {}) => {
     })
   const responses = (modelID: string | ModelID) =>
     responsesRoute.with(defaults).model<ResponsesOptionsInput>({ id: modelID })
-  return { id, model: messages, messages, chat, responses, configure }
+  return ModelRef.facade({ id, model: messages, messages, chat, responses, configure })
 }
 
 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

@@ -3,6 +3,7 @@ import { MistralChat } from "../protocols/mistral-chat.js"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import type { RouteDefaultsInput } from "../route/client.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("mistral")
 
@@ -14,11 +15,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]
@@ -30,22 +31,25 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: baseURL ?? MistralChat.DEFAULT_BASE_URL },
     auth: AuthOptions.bearer(input, "MISTRAL_API_KEY"),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) => configured.model<ProviderOptions>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 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

@@ -10,6 +10,7 @@ import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
 import { Protocol } from "../route/protocol.js"
 import { ProviderID, type LLMRequest, type ModelID } from "../schema/index.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("moonshotai")
 
@@ -42,11 +43,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),
@@ -112,6 +113,7 @@ export const configure = (input: Config = {}) => {
         maxTokensField: "max_tokens",
         supportsStore: false,
         supportsStrictMode: false,
+        supportsPromptCacheKey: true,
         toolSchema: "moonshot",
         reasoningField: "reasoning_content",
       },
@@ -125,7 +127,7 @@ export const configure = (input: Config = {}) => {
     responsesRoute
       .with(defaults)
       .model<ResponsesOptionsInput>({ id: modelID, compatibility: { toolSchema: "moonshot" } })
-  return { id, model: chat, chat, messages, responses, configure }
+  return ModelRef.facade({ id, model: chat, chat, messages, responses, configure })
 }
 
 export const provider = configure()
@@ -133,13 +135,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

@@ -4,6 +4,7 @@ import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import type { RouteDefaultsInput } from "../route/client.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenResponsesProviderOptionsInput } from "./open-responses-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export type { OpenResponsesOptionsInput, OpenResponsesProviderOptionsInput } from "./open-responses-options.js"
 
@@ -16,12 +17,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]
 
@@ -34,11 +35,11 @@ export const configure = (input: Config) => {
     endpoint: { baseURL },
     auth: AuthOptions.bearer(input, []),
   })
-  return {
+  return ModelRef.facade({
     id: ProviderID.make(provider),
     model: (modelID: string | ModelID) => route.model<OpenResponsesProviderOptionsInput>({ id: modelID }),
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -48,13 +49,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

@@ -4,6 +4,7 @@ import type { RouteDefaultsInput } from "../route/client.js"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import type { ProviderPackage } from "../provider-package.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("openai-compatible")
 
@@ -14,12 +15,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]
 
@@ -32,12 +33,12 @@ export const configure = (input: GenericModelOptions) => {
     endpoint: { baseURL },
     auth: AuthOptions.bearer(input, []),
   })
-  return {
+  return ModelRef.facade({
     id: ProviderID.make(provider),
     model: (modelID: string | ModelID) =>
       route.model<OpenAIProviderOptionsInput>({ id: modelID, provider: ProviderID.make(provider) }),
     configure,
-  }
+  })
 }
 
 export const provider = {
@@ -45,14 +46,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

@@ -6,6 +6,7 @@ import * as OpenAIChat from "../protocols/openai-chat.js"
 import * as OpenAIResponses from "../protocols/openai-responses.js"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options.js"
 import { OpenAIImages, type OpenAIImageString } from "../protocols/openai-images.js"
+import { ModelRef } from "../model-ref.js"
 
 export type { OpenAIOptionsInput, OpenAIResponseIncludable } from "./openai-options.js"
 export type { OpenAIImageOptions } from "../protocols/openai-images.js"
@@ -57,14 +58,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")
 
@@ -91,7 +92,10 @@ export const configure = (input: Config = {}) => {
       .with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true }))
       .model<OpenAIProviderOptionsInput>({ id })
   const chat = (id: string | ModelID) =>
-    chatRoute.with(withOpenAIOptions(id, modelDefaults)).model<OpenAIProviderOptionsInput>({ id })
+    chatRoute.with(withOpenAIOptions(id, modelDefaults)).model<OpenAIProviderOptionsInput>({
+      id,
+      compatibility: { supportsPromptCacheKey: true },
+    })
   const image = (modelID: string | ModelID) =>
     OpenAIImages.model({
       id: modelID,
@@ -104,31 +108,40 @@ export const configure = (input: Config = {}) => {
       ),
     })
 
-  return {
+  return ModelRef.facade({
     id,
     model: responses,
     responses,
     chat,
     image,
     configure,
-  }
+  })
 }
 
 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

@@ -8,6 +8,7 @@ import type { ProviderPackage } from "../provider-package.js"
 import { OpenAIChat } from "../protocols/openai-chat.js"
 import { newBreakpoints, ttlBucket } from "../protocols/utils/cache.js"
 import { isRecord } from "../protocols/shared.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("openrouter")
 const baseURL = "https://openrouter.ai/api/v1"
@@ -77,11 +78,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),
@@ -181,22 +182,23 @@ const configuredRoute = (input: LanguageModelOptions) => {
 
 export const configure = (input: LanguageModelOptions = {}) => {
   const route = configuredRoute(input)
-  return {
+  return ModelRef.facade({
     id,
-    model: (modelID: string | ModelID) => route.model<OpenRouterProviderOptionsInput>({ id: modelID }),
+    model: (modelID: string | ModelID) =>
+      route.model<OpenRouterProviderOptionsInput>({ id: modelID, compatibility: { supportsPromptCacheKey: true } }),
     configure,
-  }
+  })
 }
 
 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

@@ -5,6 +5,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import type { OpenAIProviderOptionsInput } from "./openai-options.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("togetherai")
 const baseURL = "https://api.together.xyz/v1"
@@ -15,11 +16,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",
@@ -39,7 +40,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
     endpoint: { baseURL: endpoint ?? baseURL },
     auth: AuthOptions.bearer(input, ["TOGETHER_API_KEY", "TOGETHER_AI_API_KEY"]),
   })
-  return {
+  return ModelRef.facade({
     id,
     model: (modelID: string | ModelID) =>
       configured.model<OpenAIProviderOptionsInput>({
@@ -47,16 +48,19 @@ export const configure = (input: LanguageModelOptions = {}) => {
         compatibility: { maxTokensField: "max_tokens", supportsStore: false, supportsStrictMode: false },
       }),
     configure,
-  }
+  })
 }
 
 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

@@ -8,6 +8,7 @@ import { XAIResponses } from "../protocols/xai-responses.js"
 import { XAIImages } from "../protocols/xai-images.js"
 import type { OpenAIOptionsInput } from "./openai-options.js"
 import type { ProviderPackage } from "../provider-package.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("xai")
 const baseURL = "https://api.x.ai/v1"
@@ -20,11 +21,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 +42,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"] } },
 })
@@ -91,14 +96,14 @@ export const configure = (input: LanguageModelOptions = {}) => {
       headers: input.headers,
       http: input.http === undefined ? undefined : HttpOptions.make(input.http),
     })
-  return {
+  return ModelRef.facade({
     id,
     model: responses,
     responses,
     chat,
     image,
     configure,
-  }
+  })
 }
 
 export const provider = configure()
@@ -106,13 +111,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

@@ -9,6 +9,7 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("zai-coding-plan")
 
@@ -23,11 +24,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",
@@ -72,7 +73,7 @@ export const configure = (input: Config = {}) => {
       .model<MessagesOptionsInput>({ id: modelID, compatibility: { requireSignature: false } })
   const responses = (modelID: string | ModelID) =>
     responsesRoute.with(defaults).model<ResponsesOptionsInput>({ id: modelID })
-  return { id, model: chat, chat, messages, responses, configure }
+  return ModelRef.facade({ id, model: chat, chat, messages, responses, configure })
 }
 
 export const provider = configure()
@@ -80,13 +81,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

@@ -6,6 +6,7 @@ import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { ModelRef } from "../model-ref.js"
 
 export const id = ProviderID.make("zai")
 
@@ -17,11 +18,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"
 
@@ -57,26 +58,29 @@ export const configure = (input: Config = {}) => {
       http: input.http === undefined ? undefined : HttpOptions.make(input.http),
     })
 
-  return {
+  return ModelRef.facade({
     id,
     model: chat,
     chat,
     image,
     configure,
-  }
+  })
 }
 
 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

@@ -7,6 +7,7 @@ import { HttpTransport } from "./transport/index.js"
 import type { HttpMiddleware, Transport, TransportRuntime, WebSocketChannelExecutor } from "./transport/index.js"
 import type { Protocol } from "./protocol.js"
 import { applyCachePolicy } from "../cache-policy.js"
+import { applyEffortUpdates } from "../effort-updates.js"
 import { normalizeToolHistory } from "../tool-history.js"
 import { sanitizeSurrogates } from "../utils/sanitize.js"
 import * as ProviderShared from "../protocols/shared.js"
@@ -23,6 +24,7 @@ import {
   LanguageModel,
   LLMEvent,
   InvalidProviderOutputError,
+  ProviderConfigurationError,
   ProviderID,
   mergeGenerationOptions,
   mergeHttpOptions,
@@ -54,6 +56,7 @@ export interface Route<
   readonly transport: Transport<Body, Prepared, unknown>
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
+  readonly supportsEffortUpdates?: (request: LLMRequest) => boolean
   readonly with: {
     <Next extends CompactionOperations | undefined>(
       patch: RoutePatch<Body, Prepared> & { readonly compact: Next },
@@ -128,7 +131,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,
@@ -384,6 +390,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
       transport: routeInput.transport,
       defaults: routeInput.defaults ?? {},
       body: protocol.body,
+      supportsEffortUpdates: protocol.supportsEffortUpdates,
       with: (patch: RoutePatch<Body, Prepared>) => {
         const { compact, id, provider, providerMetadataKey, auth, transport, endpoint, ...defaults } = patch
         return build({
@@ -554,7 +561,9 @@ const prepareRequest = (request: LLMRequest) => {
     [...new Map(tools.map((tool) => [`${tool.type}:${tool.name}`, tool])).values()].map((tool) =>
       tool.type === "tool" ? tool : { ...tool, tools: dedupe(tool.tools) },
     )
-  const resolved = applyCachePolicy(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) }))
+  const resolved = applyCachePolicy(
+    applyEffortUpdates(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) })),
+  )
   const headers = resolved.model.route.headers?.({ request: resolved })
   return headers === undefined
     ? resolved

packages/ai/src/route/endpoint.ts

@@ -1,12 +1,12 @@
 import type { LLMRequest } from "../schema/index.js"
 import * as ProviderShared from "../protocols/shared.js"
 
-export interface EndpointInput<Body> {
-  readonly request: LLMRequest
+export interface EndpointInput<Body, Request = LLMRequest> {
+  readonly request: Request
   readonly body: Body
 }
 
-export type EndpointPart<Body> = string | ((input: EndpointInput<Body>) => string)
+export type EndpointPart<Body, Request = LLMRequest> = string | ((input: EndpointInput<Body, Request>) => string)
 
 /**
  * Declarative URL construction for one route.
@@ -17,26 +17,29 @@ export type EndpointPart<Body> = string | ((input: EndpointInput<Body>) => strin
  *
  * `path` may be a string or a function of `EndpointInput`, for routes whose
  * URL embeds the model id, region, or another body field (e.g. Bedrock,
- * Gemini).
+ * Gemini). Media routes reuse the same shape with their own request type.
  */
-export interface Definition<Body> {
+export interface Definition<Body, Request = LLMRequest> {
   readonly baseURL?: string
-  readonly path: EndpointPart<Body>
+  readonly path: EndpointPart<Body, Request>
   readonly query?: Record<string, string>
 }
 
-export type EndpointPatch<Body> = Partial<Definition<Body>>
+export type EndpointPatch<Body, Request = LLMRequest> = Partial<Definition<Body, Request>>
 
 /** Construct an `Endpoint` from a path string or path function. */
-export const path = <Body>(
-  value: EndpointPart<Body>,
-  options: Omit<Definition<Body>, "path"> = {},
-): Definition<Body> => ({
+export const path = <Body, Request = LLMRequest>(
+  value: EndpointPart<Body, Request>,
+  options: Omit<Definition<Body, Request>, "path"> = {},
+): Definition<Body, Request> => ({
   ...options,
   path: value,
 })
 
-export const merge = <Body>(base: Definition<Body>, patch: EndpointPatch<Body>): Definition<Body> => ({
+export const merge = <Body, Request = LLMRequest>(
+  base: Definition<Body, Request>,
+  patch: EndpointPatch<Body, Request>,
+): Definition<Body, Request> => ({
   ...base,
   ...patch,
   baseURL: patch.baseURL ?? base.baseURL,
@@ -44,10 +47,13 @@ export const merge = <Body>(base: Definition<Body>, patch: EndpointPatch<Body>):
   query: patch.query === undefined ? base.query : { ...base.query, ...patch.query },
 })
 
-const renderPart = <Body>(part: EndpointPart<Body>, input: EndpointInput<Body>) =>
+const renderPart = <Body, Request>(part: EndpointPart<Body, Request>, input: EndpointInput<Body, Request>) =>
   typeof part === "function" ? part(input) : part
 
-export const render = <Body>(endpoint: Definition<Body>, input: EndpointInput<Body>) => {
+export const render = <Body, Request = LLMRequest>(
+  endpoint: Definition<Body, Request>,
+  input: EndpointInput<Body, Request>,
+) => {
   const url = new URL(`${ProviderShared.trimBaseUrl(endpoint.baseURL ?? "")}${renderPart(endpoint.path, input)}`)
   for (const [key, value] of Object.entries(endpoint.query ?? {})) url.searchParams.set(key, value)
   return url

packages/ai/src/route/executor-service.ts

@@ -0,0 +1,22 @@
+import { Context, type Effect } from "effect"
+import type { HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import type { AIError } from "../schema/errors.js"
+
+// The service tag lives in its own leaf module so `Media.Asset` (imported by the schema layer) can require the
+// executor without pulling the full executor implementation, and therefore the schema barrel, into a cycle.
+export interface Interface {
+  readonly execute: (
+    request: HttpClientRequest.HttpClientRequest,
+    middleware?: HttpMiddleware,
+  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, AIError>
+}
+
+export type HttpHandler = (
+  request: HttpClientRequest.HttpClientRequest,
+) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>
+export type HttpMiddleware = (
+  request: HttpClientRequest.HttpClientRequest,
+  handler: HttpHandler,
+) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/AI/RequestExecutor") {}

packages/ai/src/route/executor.ts

@@ -1,4 +1,4 @@
-import { Cause, Context, Effect, Layer, Option, Schema, Stream } from "effect"
+import { Cause, Effect, Layer, Option, Schema, Stream } from "effect"
 import {
   FetchHttpClient,
   Headers,
@@ -9,23 +9,10 @@ import {
 } from "effect/unstable/http"
 import { HttpContext, HttpRateLimitDetails, AIError, TransportError } from "../schema/index.js"
 import { classifyProviderFailure } from "../provider-error.js"
+import { Service, type HttpMiddleware, type Interface } from "./executor-service.js"
 
-export interface Interface {
-  readonly execute: (
-    request: HttpClientRequest.HttpClientRequest,
-    middleware?: HttpMiddleware,
-  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, AIError>
-}
-
-export type HttpHandler = (
-  request: HttpClientRequest.HttpClientRequest,
-) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>
-export type HttpMiddleware = (
-  request: HttpClientRequest.HttpClientRequest,
-  handler: HttpHandler,
-) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>
-
-export class Service extends Context.Service<Service, Interface>()("@opencode/AI/RequestExecutor") {}
+export { Service } from "./executor-service.js"
+export type { HttpHandler, HttpMiddleware, Interface } from "./executor-service.js"
 
 const headerDetails = (headers: Headers.Headers) =>
   Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, String(value)]))

packages/ai/src/route/index.ts

@@ -20,6 +20,8 @@ export * from "./executor.js"
 export { Auth } from "./auth.js"
 export { AuthOptions } from "./auth-options.js"
 export { Endpoint } from "./endpoint.js"
+export { MediaRoute } from "./media.js"
+export { MediaProtocol } from "./media-protocol.js"
 export { Framing } from "./framing.js"
 export { Protocol } from "./protocol.js"
 export { HttpTransport, WebSocketTransport } from "./transport/index.js"

packages/ai/src/route/media-protocol.ts

@@ -0,0 +1,95 @@
+import { Effect, Schema } from "effect"
+import { HttpClientResponse } from "effect/unstable/http"
+import { AIError, HttpContext, InvalidProviderOutputError } from "../schema/index.js"
+
+// ---------------------------------------------------------------------------
+// Bodies
+// ---------------------------------------------------------------------------
+
+export type Body =
+  | { readonly type: "json"; readonly value: Record<string, unknown> }
+  | { readonly type: "multipart"; readonly value: FormData }
+
+export const json = (value: Record<string, unknown>): Body => ({ type: "json", value })
+export const multipart = (value: FormData): Body => ({ type: "multipart", value })
+
+// ---------------------------------------------------------------------------
+// Protocol kinds
+// ---------------------------------------------------------------------------
+
+export interface DecodeContext<Request> {
+  readonly request: Request
+  readonly body: Body
+}
+
+/** One request, one response. JSON or multipart in; JSON or raw bytes out. */
+export interface Inline<Request, Response> {
+  readonly kind: "inline"
+  readonly id: string
+  readonly name: string
+  /** Common request fields this protocol cannot lower; the route rejects them before `body.from` runs. */
+  readonly unsupported?: ReadonlyArray<keyof Request & string>
+  readonly body: { readonly from: (request: Request) => Effect.Effect<Body, AIError> }
+  readonly response: {
+    readonly decode: (
+      response: HttpClientResponse.HttpClientResponse,
+      context: DecodeContext<Request>,
+    ) => Effect.Effect<Response, AIError>
+  }
+}
+
+export const inline = <Request, Response>(
+  input: Omit<Inline<Request, Response>, "kind">,
+): Inline<Request, Response> => ({
+  kind: "inline",
+  ...input,
+})
+
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+
+const context = (response: HttpClientResponse.HttpClientResponse) =>
+  new HttpContext({ url: response.request.url, status: response.status, headers: response.headers })
+
+/** Read a text body while retaining the original payload and HTTP context on every downstream error. */
+export const text = Effect.fn("MediaProtocol.text")(function* (
+  route: string,
+  name: string,
+  response: HttpClientResponse.HttpClientResponse,
+) {
+  const http = context(response)
+  const body = yield* response.text.pipe(
+    Effect.mapError(
+      (cause) =>
+        new AIError({
+          reason: new InvalidProviderOutputError({
+            route,
+            message: `Failed to read the ${name} response`,
+            http,
+            cause,
+          }),
+        }),
+    ),
+  )
+  return {
+    body,
+    http,
+    invalid: (message: string, cause?: unknown) =>
+      new AIError({ reason: new InvalidProviderOutputError({ route, message, body, http, cause }) }),
+  }
+})
+
+/** Read and Schema-decode a JSON body. Decode failures keep the raw body as `reason.body`. */
+export const decodeJson = <A>(route: string, name: string, schema: Schema.Codec<A, unknown>) => {
+  const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema))
+  return Effect.fn("MediaProtocol.decodeJson")(function* (response: HttpClientResponse.HttpClientResponse) {
+    const output = yield* text(route, name, response)
+    const value = yield* decode(output.body).pipe(
+      Effect.mapError((cause) => output.invalid(`${name} returned an invalid response`, cause)),
+    )
+    return { ...output, value }
+  })
+}
+
+export * as MediaProtocol from "./media-protocol.js"

packages/ai/src/route/media.ts

@@ -0,0 +1,116 @@
+import { Effect } from "effect"
+import { Headers, HttpClientRequest } from "effect/unstable/http"
+import { Auth } from "./auth.js"
+import { Endpoint } from "./endpoint.js"
+import type { Interface } from "./executor-service.js"
+import { MediaProtocol } from "./media-protocol.js"
+import { ProviderShared } from "../protocols/shared.js"
+import { AIError, HttpOptions, ProviderID, mergeHttpOptions } from "../schema/index.js"
+import { sanitizeSurrogates } from "../utils/sanitize.js"
+
+export type Execute = Interface["execute"]
+
+/** The minimum a media request must carry for the route to build a transport request. */
+export interface MediaRequest {
+  readonly model: { readonly id: string; readonly provider: ProviderID; readonly http?: HttpOptions }
+  readonly http?: HttpOptions
+}
+
+/** Deployment inputs every media model factory accepts; provider facades fill these from `configure(...)`. */
+export interface ModelInput {
+  readonly id: string
+  readonly auth: Auth.Definition
+  readonly baseURL?: string
+  readonly headers?: Record<string, string>
+  readonly http?: HttpOptions
+}
+
+// ---------------------------------------------------------------------------
+// Route
+// ---------------------------------------------------------------------------
+
+export interface Route<Request extends MediaRequest, Response> {
+  readonly id: string
+  readonly provider: ProviderID
+  readonly protocol: string
+  readonly generate: (request: Request, execute: Execute) => Effect.Effect<Response, AIError>
+}
+
+export interface MakeInput<Request extends MediaRequest, Response> {
+  readonly id: string
+  readonly provider: string | ProviderID
+  readonly protocol: MediaProtocol.Inline<Request, Response>
+  readonly endpoint: Endpoint.Definition<MediaProtocol.Body, Request>
+  readonly auth: Auth.Definition
+  /** Deployment headers applied before transport authentication. */
+  readonly headers?: Record<string, string>
+}
+
+/**
+ * Compose an inline media protocol with an endpoint and auth into a runnable route. The route owns the transport
+ * plumbing every media protocol would otherwise duplicate: option merging, surrogate sanitizing, unsupported-field rejection, URL and query
+ * rendering, auth headers, JSON vs multipart encoding, and handing the response back to the protocol for decoding.
+ */
+export const make = <Request extends MediaRequest, Response>(
+  input: MakeInput<Request, Response>,
+): Route<Request, Response> => {
+  const provider = ProviderID.make(input.provider)
+  const routeHttp = input.headers === undefined ? undefined : new HttpOptions({ headers: input.headers })
+  const authorize = Auth.toEffect(input.auth)
+  return {
+    id: input.id,
+    provider,
+    protocol: input.protocol.id,
+    generate: Effect.fn(`MediaRoute.generate`)(function* (request: Request, execute: Execute) {
+      yield* rejectUnsupported(input.id, provider, request, input.protocol.unsupported)
+      const http = mergeHttpOptions(routeHttp, request.model.http, request.http)
+      // Sanitize after merging so model-level overlays are covered; the model value is restored, not sanitized.
+      const resolved: Request = { ...sanitizeSurrogates({ ...request, http }), model: request.model }
+      const body = yield* input.protocol.body.from(resolved)
+      const url = Endpoint.render(input.endpoint, { request: resolved, body })
+      for (const [key, value] of Object.entries(http?.query ?? {})) url.searchParams.set(key, value)
+      const encoded = body.type === "json" ? ProviderShared.encodeJson(body.value) : "[multipart/form-data]"
+      const baseHeaders = Headers.fromInput(http?.headers)
+      const headers = yield* authorize({
+        request: resolved,
+        method: "POST",
+        url: url.toString(),
+        body: encoded,
+        // The HTTP client sets the multipart boundary; a caller-supplied content-type would corrupt it.
+        headers: body.type === "multipart" ? Headers.remove(baseHeaders, "content-type") : baseHeaders,
+      })
+      const transport = HttpClientRequest.post(url.toString()).pipe(
+        HttpClientRequest.setHeaders(headers),
+        body.type === "json"
+          ? HttpClientRequest.bodyText(encoded, "application/json")
+          : HttpClientRequest.bodyFormData(body.value),
+      )
+      const response = yield* execute(transport)
+      return yield* input.protocol.response.decode(response, { request: resolved, body })
+    }),
+  }
+}
+
+/** Common fields are never silently dropped: a present field the protocol declared unsupported fails typed. */
+const rejectUnsupported = <Request extends object>(
+  route: string,
+  provider: ProviderID,
+  request: Request,
+  unsupported: ReadonlyArray<keyof Request & string> | undefined,
+): Effect.Effect<void, AIError> => {
+  const present = (unsupported ?? []).filter((field) => {
+    const value = request[field]
+    return Array.isArray(value) ? value.length > 0 : value !== undefined
+  })
+  if (present.length === 0) return Effect.void
+  return Effect.fail(
+    ProviderShared.unsupportedOperation({
+      operation: `media.${present[0]}`,
+      provider,
+      route,
+      message: `${provider}/${route} does not support ${present.join(", ")}`,
+    }),
+  )
+}
+
+export * as MediaRoute from "./media.js"

packages/ai/src/route/protocol.ts

@@ -41,6 +41,8 @@ export interface Protocol<Body, Frame, Event, State> {
   readonly body: ProtocolBody<Body>
   /** Response side: streaming state machine. */
   readonly stream: ProtocolStream<Frame, Event, State>
+  /** Whether `body.from` lowers `Message.effort(...)` markers; wrappers around another `body.from` must forward it. */
+  readonly supportsEffortUpdates?: (request: LLMRequest) => boolean
 }
 
 export interface ProtocolBody<Body> {