feat(ai): support PDF inputs (#38253)

Co-authored-by: Kit Langton <kit.langton@gmail.com>

.changeset/calm-services-start.md

@@ -0,0 +1,7 @@
+---
+"@opencode-ai/client": patch
+"@opencode-ai/protocol": patch
+"@opencode-ai/cli": patch
+---
+
+Expose background-service lifecycle status, preserve one process-held owner through startup and failure, reconnect TUIs without activating replacement, and stop exact service instances gracefully.

.changeset/calm-sessions-header.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/cli": patch
+---
+
+Expose a TUI plugin slot at the top of the session view.

.changeset/clean-sessions-generate.md

@@ -0,0 +1,7 @@
+---
+"@opencode-ai/client": patch
+"@opencode-ai/plugin": patch
+"@opencode-ai/protocol": patch
+---
+
+Expose transient, read-only session generation through the HTTP API, generated clients, and V2 plugin session context.

.changeset/fresh-composers-slot.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/cli": patch
+---
+
+Expose a TUI plugin slot above the session composer.

.gitattributes

@@ -1,2 +1,3 @@
 packages/core/migration/**/snapshot.json linguist-generated
 packages/core/src/database/migration.gen.ts linguist-generated
+packages/core/src/**/*.txt text eol=lf

.github/TEAM_MEMBERS

@@ -18,4 +18,4 @@ simonklee
 Slickstef11
 usrnk1
 vimtor
-starptech
+StarpTech

.github/workflows/publish.yml

@@ -90,11 +90,18 @@ jobs:
           opencode-app-id: ${{ vars.OPENCODE_APP_ID }}
           opencode-app-secret: ${{ secrets.OPENCODE_APP_SECRET }}
 
-      - name: Build
+      - name: Build legacy CLI
+        if: github.ref_name != 'v2'
+        run: ./packages/opencode/script/build.ts ${{ (github.ref_name == 'beta' && '--sourcemaps') || '' }}
+        env:
+          OPENCODE_VERSION: ${{ needs.version.outputs.version }}
+          OPENCODE_RELEASE: ${{ needs.version.outputs.release }}
+          GH_REPO: ${{ needs.version.outputs.repo }}
+          GH_TOKEN: ${{ steps.committer.outputs.token }}
+
+      - name: Build preview CLI
         id: build
-        run: |
-          ./packages/opencode/script/build.ts ${{ (github.ref_name == 'beta' && '--sourcemaps') || '' }}
-          ./packages/cli/script/build.ts ${{ (github.ref_name == 'beta' && '--sourcemaps') || '' }}
+        run: ./packages/cli/script/build.ts ${{ (github.ref_name == 'beta' && '--sourcemaps') || '' }}
         env:
           OPENCODE_VERSION: ${{ needs.version.outputs.version }}
           OPENCODE_RELEASE: ${{ needs.version.outputs.release }}
@@ -102,6 +109,7 @@ jobs:
           GH_TOKEN: ${{ steps.committer.outputs.token }}
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: github.ref_name != 'v2'
         with:
           name: opencode-cli
           path: |
@@ -109,6 +117,7 @@ jobs:
             packages/opencode/dist/opencode-linux*
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: github.ref_name != 'v2'
         with:
           name: opencode-cli-windows
           path: packages/opencode/dist/opencode-windows*
@@ -121,6 +130,55 @@ jobs:
     outputs:
       version: ${{ needs.version.outputs.version }}
 
+  build-node-cli:
+    needs: version
+    if: github.repository == 'anomalyco/opencode'
+    strategy:
+      fail-fast: false
+      matrix:
+        settings:
+          - target: linux-arm64
+            host: blacksmith-4vcpu-ubuntu-2404-arm
+          - target: linux-x64
+            host: blacksmith-4vcpu-ubuntu-2404
+          - target: darwin-arm64
+            host: macos-26
+          - target: windows-arm64
+            host: blacksmith-4vcpu-windows-2025
+          - target: windows-x64
+            host: blacksmith-4vcpu-windows-2025
+    runs-on: ${{ matrix.settings.host }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+
+      - uses: ./.github/actions/setup-bun
+        with:
+          install-flags: --os=* --cpu=*
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "26.4.0"
+
+      - name: Build
+        run: bun packages/cli/script/build-node.ts --target=${{ matrix.settings.target }} --skip-install --outdir=dist/node
+        env:
+          OPENCODE_VERSION: ${{ needs.version.outputs.version }}
+          OPENCODE_RELEASE: ${{ needs.version.outputs.release }}
+
+      - name: Verify service lifecycle
+        if: matrix.settings.target != 'windows-arm64'
+        working-directory: packages/cli
+        run: bun run script/service-smoke.ts --node
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: opencode-node-cli-${{ matrix.settings.target }}
+          path: packages/cli/dist/node/cli-node-*
+          if-no-files-found: error
+
   sign-cli-windows:
     needs:
       - build-cli
@@ -413,6 +471,7 @@ jobs:
     needs:
       - version
       - build-cli
+      - build-node-cli
       - sign-cli-windows
       - build-electron
     if: always() && !failure() && !cancelled()
@@ -441,11 +500,13 @@ jobs:
           registry-url: "https://registry.npmjs.org"
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        if: github.ref_name != 'v2'
         with:
           name: opencode-cli
           path: packages/opencode/dist
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        if: github.ref_name != 'v2'
         with:
           name: opencode-cli-windows
           path: packages/opencode/dist
@@ -461,6 +522,12 @@ jobs:
           name: opencode-preview-cli
           path: packages/cli/dist
 
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          pattern: opencode-node-cli-*
+          path: packages/cli/dist/node
+          merge-multiple: true
+
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         if: needs.version.outputs.release
         with:

.github/workflows/test.yml

@@ -70,6 +70,28 @@ jobs:
         env:
           OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER: ${{ runner.os == 'Windows' && 'true' || 'false' }}
 
+      - name: Verify compiled service lifecycle
+        if: always()
+        timeout-minutes: 10
+        working-directory: packages/cli
+        run: |
+          bun run script/build.ts --single --skip-install
+          bun run script/service-smoke.ts
+
+      - name: Setup Node build runtime
+        if: always()
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "26.4.0"
+
+      - name: Verify Node build
+        if: always()
+        timeout-minutes: 15
+        working-directory: packages/cli
+        run: |
+          bun run script/build-node.ts --single --skip-install --outdir=dist/node
+          bun run script/service-smoke.ts --node
+
       - name: Check generated client
         if: runner.os == 'Linux'
         working-directory: packages/client

.gitignore

@@ -11,6 +11,7 @@ node_modules
 playground
 tmp
 dist
+dist-node
 ts-dist
 .turbo
 .typecheck-profiles
@@ -25,6 +26,7 @@ Session.vim
 a.out
 target
 .scripts
+.cache
 .direnv/
 
 # Local dev files

.opencode/command/translate.md

@@ -1,6 +1,6 @@
 ---
 description: translate English to other languages
-model: opencode/claude-opus-4-8
+model: opencode/gpt-5.6-sol
 ---
 
 run git diff and translate changed english doc and UI copy files to other international languages. Translate all languages in parallel to save time.

.opencode/tool/github-triage.ts

@@ -4,7 +4,7 @@ import { tool } from "@opencode-ai/plugin"
 const TEAM = {
   tui: ["kommander", "simonklee"],
   desktop_web: ["Hona", "Brendonovich"],
-  core: ["jlongster", "rekram1-node", "nexxeln", "kitlangton", "starptech"],
+  core: ["jlongster", "rekram1-node", "nexxeln", "kitlangton"],
   inference: ["fwang", "MrMushrooooom", "starptech"],
   windows: ["Hona"],
 } as const

AGENTS.md

@@ -19,8 +19,6 @@ Valid types are `feat`, `fix`, `docs`, `chore`, `refactor`, and `test`. Scopes a
 
 Examples: `fix(tui): simplify thinking toggle styling`, `docs: update contributing guide`, `chore(sdk): regenerate types`.
 
-Never bypass Git hooks. Do not use `--no-verify` or otherwise disable, skip, or circumvent commit or push hooks. If a hook fails, fix the failure or stop and report it to the user.
-
 ## Style Guide
 
 ### General Principles

CONTEXT.md

@@ -1,245 +0,0 @@
-# OpenCode Session Runtime
-
-OpenCode sessions preserve durable conversational history while assembling the runtime context an agent needs to act correctly in its current environment.
-
-## Language
-
-**Model Context**:
-The complete model-visible input assembled for one **Step**, including system instructions, **Session History**, tool definitions, and step-local additions. **Instructions** are one component of Model Context, not a synonym for it.
-_Avoid_: System Context
-
-**Instructions**:
-The opaque algebra of independently refreshable typed instruction sources that render the durable instruction baseline and chronological updates shown to the model.
-_Avoid_: Model Context, System Context
-
-**Session History**:
-The projected chronological conversation selected for a **Step** after applying the active compaction boundary and interleaving derived **Instruction Updates** from the current **Instruction Epoch**.
-_Avoid_: Session Context
-
-**Instruction Source**:
-One independently read typed value within **Instructions**, represented by a stable namespaced key, canonical JSON codec, pure first/changed renderers, and an optional removal renderer.
-_Avoid_: Prompt fragment
-
-**InstructionEntry**:
-One API-managed, durable, per-Session instruction value. Its slash-free client key maps to the `api/<key>` **Instruction Source** key. Entries deliberately render to the model as mechanism-neutral `<context>` blocks: the model sees session context, not how it was attached.
-
-**InstructionDiscovery**:
-The Location-scoped service that observes ambient global and upward-project `AGENTS.md` files as one ordered aggregate **Instruction Source**.
-
-**Instruction State**:
-The Session-owned projection cache of one instruction log fold: epoch start, values at that start, current values, and the last folded sequence. It is rebuilt from durable events and never authors model-visible facts.
-
-**Instruction Update**:
-A durable `session.instructions.updated` value delta admitted at a **Safe Step Boundary**. Its model-visible System text is rendered from stored values at request assembly and is never persisted verbatim.
-_Avoid_: Correction, stored prose, raw text diff
-
-**Initial Instructions**:
-The deterministic instruction text rendered from values at the current **Instruction Epoch** start and sent as provider-cache prefix state until completed compaction moves the epoch or Session movement or committed revert resets it.
-_Avoid_: Live system prompt
-
-**Instruction Epoch**:
-The span between completed compactions. Its start is the last `session.compaction.ended` sequence, or the initial complete instruction delta when no prior epoch exists.
-
-**Instruction Values**:
-The key-to-hash map produced by folding instruction deltas in durable sequence order. Hash bodies live once in the content-addressed instruction blob store.
-
-**Unavailable Instruction Source**:
-An expected temporary inability to read an **Instruction Source** value; the runtime retains its prior effective value and emits no update, while an unavailable source blocks the initial complete delta.
-
-**Safe Step Boundary**:
-The point during Step preparation, after prior tool settlement and before durable input promotion, where instruction changes may be admitted chronologically.
-
-**Admitted Prompt**:
-A durable user input accepted into the Session inbox but not yet included in **Session History**.
-
-**Prompt Promotion**:
-The durable transition that removes an **Admitted Prompt** from pending input and appends its user message to **Session History**.
-
-**Step**:
-One logical LLM call spanning pre-flight instruction synchronization, input promotion, request build, and compaction check; the provider stream; and tool settlement.
-_Avoid_: provider turn, turn (unqualified)
-
-**Physical Attempt**:
-One actual provider request on the wire in service of a **Step**; most Steps have one Physical Attempt, while overflow-triggered compaction recovery may give one Step two.
-
-**Assistant Turn**:
-A reserved name for the not-yet-modeled unit containing all **Steps** from prompt promotion until the assistant yields the floor; do not reify it until something durable needs it.
-
-**Settlement**:
-The terminal transition for a unit of work: Step and tool settlement are durable, while drain and execution settlement are coordinator-observed.
-
-**Execution**:
-One session-scoped coordinator busy period from first wake until idle. An Execution is process-local coordination rather than a durable domain entity.
-
-**Session Drain**:
-One process-local execution span that promotes eligible input and runs required **Steps** until no immediate continuation remains. A Session Drain has no durable identity or transcript boundary.
-
-**Model Tool Output**:
-The bounded projection of a Core-executed tool result persisted in Session history and replayed to the model. A tool may shape this projection semantically, but the Tool Registry enforces the final size limit.
-
-**Managed Tool Output File**:
-A temporary file created under OpenCode's shared tool-output directory to retain complete output that was too large for Session history.
-
-**Model Request Options**:
-Provider-semantic model settings selected from the Catalog and active Session variant before the LLM protocol adapter encodes them for a provider request.
-_Avoid_: Request body, wire options
-
-**Generation Controls**:
-Provider-neutral sampling and output controls, partitioned from provider semantics and compatibility wire fields when model metadata enters the Catalog.
-
-**Native Continuation Metadata**:
-Opaque protocol-shaped data attached to assistant content and required to continue that content natively with a compatible model, such as a reasoning signature or provider-hosted item identifier.
-
-**PTY Environment**:
-The host-supplied environment overlay applied by the server when creating a PTY, observed for the request Location and resolved PTY working directory.
-
-**OpenCode Client**:
-The generated Promise and Effect APIs derived from the public `HttpApi`; **Embedded OpenCode** shares the Effect API through an in-memory `HttpClient` against the same router and handlers.
-_Avoid_: Remote client
-
-**SDK Contract IR**:
-The runtime-neutral compiled representation of the authoritative `HttpApi`, preserving encoded and decoded type projections plus transport metadata so independent SDK emitters can choose their public value model and runtime interpreter.
-
-**Embedded OpenCode**:
-A scoped in-process host that structurally extends the **OpenCode Client**, supplies an in-memory HTTP transport, and exposes additional same-process capabilities directly.
-_Avoid_: Local implementation
-
-**Page**:
-A bounded ordered result containing `items` and opaque `previous` and `next` cursor links for navigating the same query in either direction.
-_Avoid_: Response envelope
-
-## Relationships
-
-- **Instructions** is an opaque carrier composed from zero or more **Instruction Sources**.
-- **Model Context** is broader than **Instructions**. For each **Step**, the runner assembles the selected agent or provider system text, **Initial Instructions**, **Session History**, available tools, and step-local additions into one model request.
-- **Session History** persists conversational messages. The runner derives model-facing **Instruction Update** messages from value deltas and interleaves them by durable sequence; **Initial Instructions** remain separate provider-request state.
-- The runner explicitly loads and combines instruction built-ins, **InstructionDiscovery**, selected-agent skill guidance, reference guidance, MCP guidance, and **InstructionEntry** values. There is no instruction registry.
-- `Instructions.combine(...)` preserves caller order and rejects duplicate stable namespaced source keys. The runner loads its producers concurrently, then combines them in its fixed declared order.
-- Each **Instruction Source** read returns one coherent typed value, explicit removal, or temporary unavailability. `Instructions.make(...)` hides the value type so differently typed sources compose uniformly; its canonical codec defines storage and hash equivalence, while pure renderers produce first, changed, and optional removal text.
-- `Instructions.read(...)` reads every composed source concurrently and exactly once at the boundary. `Instructions.diff(...)` compares encoded-value hashes with current **Instruction Values** and returns one delta plus new blob bodies.
-- `Instructions.renderInitial(...)` renders values at the **Instruction Epoch** start. `Instructions.renderUpdate(...)` renders one hydrated delta against the values immediately before it.
-- A changed **Instruction Source** contributes its hash to one **Instruction Update**; explicit removal contributes the `"removed"` sentinel.
-- An **Instruction Update** persists only its value delta. Rendered text is derived during request assembly and excluded from compaction summaries.
-- The instruction blob insert, durable delta, and **Instruction State** advance commit atomically.
-- Changes from multiple **Instruction Sources** admitted at one safe boundary combine into one **Instruction Update**.
-- Instruction changes are sampled and admitted lazily at a **Safe Step Boundary**, never pushed asynchronously when their source changes.
-- At a **Safe Step Boundary**, prior tool results are already settled; instruction preparation completes before newly admitted user input promotes.
-- An **Admitted Prompt** is replayable pending input, not yet model-visible **Session History**.
-- **Prompt Promotion** atomically consumes the pending inbox entry and appends its model-visible user message.
-- Steering prompts promote at the next **Safe Step Boundary** while the current **Session Drain** still requires continuation. Promoting any newly admitted user input resets the selected agent's step allowance; multiple prompts promoted at one boundary reset it once.
-- A queued prompt does not promote while the current **Session Drain** requires continuation. The runner promotes one queued prompt when the Session would otherwise become idle, then reevaluates continuation before promoting another.
-- A **Session Drain** is process-local coordination rather than a durable domain entity. Durable recovery must reason from prompts, projected history, physical attempts, and tool state rather than inventing an enclosing execution identity.
-- An **Execution** contains one or more **Session Drains**; a **Session Drain** contains one reserved assistant-turn span at a time; that span contains **Steps**; and each **Step** contains one or more **Physical Attempts** plus any tool calls it requires.
-- A **Step** record covers only the model-visible span from first assistant output through tool settlement; pre-flight leaves no record, and one Step settles at most one record.
-- The first **Step** admits one complete delta and renders **Initial Instructions** without narrating that delta in history; an unavailable initial source blocks the Step instead of persisting incomplete values.
-- Instruction preparation precedes durable input promotion on every Step so an unavailable first baseline leaves pending input untouched and later updates enter history before newly promoted input.
-- Completed compaction moves the **Instruction Epoch** to the exact `session.compaction.ended` sequence and copies current hashes to the epoch's initial values. Earlier updates leave active model history while durable deltas remain.
-- A newly composed **Instruction Source** absent from current **Instruction Values** emits its first rendering once at the next **Safe Step Boundary**.
-- **Unavailable Instruction Source** uses stale-while-revalidate semantics and is distinct from a successfully loaded absence, which may emit removal text.
-- **InstructionDiscovery** observes ambient instructions as one ordered aggregate **Instruction Source**.
-- Ambient discovery reads global and upward-project `AGENTS.md` files and honors `OPENCODE_DISABLE_PROJECT_CONFIG` for project files.
-- After a successful internal file or directory read, nearby `AGENTS.md` files toward the Location root are injected once per Session as durable synthetic instruction messages.
-- **InstructionEntry** stores API-managed per-Session JSON values. Each entry contributes one `api/<key>` **Instruction Source**, so adding, replacing, or removing an entry is reconciled at the next **Safe Step Boundary**.
-- Location-scoped instruction producers naturally re-resolve when a moved Session next runs in its destination Location.
-- Moving a Session clears its **Instruction State**, so the destination must admit a complete delta before another prompt can promote. Committed revert does the same; replay derives both resets from their durable events.
-- Selected-agent available-skill guidance is an **Instruction Source** composed explicitly by the runner. It lists only names and descriptions permitted for that agent; skill bodies and locations are exposed only through the permission-checked `skill` tool.
-- The selected agent and model are sampled when a **Step** starts. Changes admitted after that boundary apply to the next Step and do not restart the current Step.
-- An agent switch that changes selected-agent guidance produces an **Instruction Update** while preserving the current baseline.
-- Local tool authorization and pending permission requests retain the effective agent of the **Step** that issued the call; a later agent switch cannot change that call's policy.
-- Instruction source changes never wake idle Sessions; the next naturally scheduled **Safe Step Boundary** loads and compares current values lazily.
-- Once admitted, an **Instruction Update** remains durable even if the following **Physical Attempt** fails and is replayed unchanged on retry.
-- **Instruction Updates** remain durable value history but are not `session_message` rows. Clients display changed keys rather than model-facing prose.
-- The date **Instruction Source** initially preserves host-local calendar-date behavior; a configured user timezone may replace that default later.
-- **Initial Instructions** are recomputed deterministically from durable values for every request; rendered bytes are not stored.
-- A model/provider switch preserves current **Instruction Values**, the **Instruction Epoch**, and chronological conversation history; the new selection applies to the next **Step**.
-- **Native Continuation Metadata** remains in durable history. Step projection includes it only for a successful exact originating provider/model match; failed Steps and incompatible models omit opaque metadata, while non-empty visible reasoning lowers to ordinary assistant text after a model switch. This conservative relation may widen only when recorded provider tests establish compatibility.
-- **Model Request Options** remain provider-semantic through Catalog resolution. The Session runner maps them into the LLM package's provider-option namespace; the selected protocol adapter alone owns provider wire encoding.
-- **Generation Controls**, protocol-semantic **Model Request Options**, and compatibility request body fields are separate Catalog domains. A shared ingestion adapter partitions legacy and models.dev AI-SDK-shaped options before routing.
-- The **PTY Environment** is a server concern rather than a Core PTY concern. PTY creation merges caller values, then the host overlay, then Core-forced terminal invariants such as `TERM` and `OPENCODE_TERMINAL`.
-- Networked and **Embedded OpenCode** use the same **OpenCode Client** and preserve the full HTTP encoding, routing, middleware, and decoding boundary; only the `HttpClient` transport differs.
-- The Effect-native network constructor obtains `HttpClient.HttpClient` from its environment so callers own transport selection, recording, tracing, retries, and tests. Convenience runtimes may provide a fetch transport separately.
-- Creating **Embedded OpenCode** is scoped. Closing its owning Scope releases the in-process server resources, database resources, registrations, and fibers.
-- **Embedded OpenCode** exposes shared client capabilities and embedded-only capabilities on one object; consumers do not navigate through a nested `.client` property.
-- The beta **OpenCode Client** currently uses plural consumer-facing capability groups such as `sessions`; whether the stable Session namespace should instead be singular `session` must be settled before stabilization. Internal server identifiers do not implicitly define public client names.
-- Server's concrete `HttpApi` is authoritative for shared **OpenCode Client** capabilities. Codegen compiles its Session group directly; the Effect runtime uses an equivalent Protocol-only projection so generated artifacts remain independent of Core and Server.
-- SDK generation reflects the public `HttpApi` once into an **SDK Contract IR**. Promise and Effect emitters share endpoint structure and transport metadata without being required to expose identical public values: an emitter may select encoded wire types, decoded domain types, compile-time brands, runtime validation, and its own execution abstraction independently.
-- The first Effect emitter is the rich projection: it exposes decoded Effect-native values, preserves brands and schema transformations, performs runtime schema decoding, and delegates transport interpretation to `HttpApiClient`. Lighter wire-shaped Effect output remains possible through another emitter policy rather than constraining the shared IR.
-- The rich Effect emitter regenerates private executable schemas when the **SDK Contract IR** proves that their transport semantics can be reproduced exactly. Contracts with authoritative custom transformations use the import-based Effect emitter against a Protocol-only client projection whose generated transport output is tested against Server's concrete API; the Promise emitter still derives zero-Effect structural wire types from the same IR.
-- `@opencode-ai/protocol` owns Session endpoint construction and middleware placement. Server supplies concrete middleware keys to produce the authoritative build-time API; the client projection supplies transport-only keys without importing Core or Server at runtime.
-- The first Promise emitter targets the same clean domain-oriented method organization rather than Hey API source compatibility. It returns unwrapped values directly, rejects declared and infrastructure failures, and begins with minimal client-level transport configuration; result wrappers, interceptors, and legacy generated signatures are outside the initial surface.
-- The first Promise emitter parses response syntax and trusts its generated structural types; it does not perform runtime structural validation. Malformed payload syntax fails, while a syntactically valid shape mismatch is not detected at the SDK boundary. Standalone validator generation remains an optional future emitter policy.
-- Declared Promise-client failures retain their tagged structural wire values and have generated type guards. Consumers do not depend on generated `Error` subclass identity, preserving discrimination across package copies and realms while remaining structurally aligned with Effect domain errors.
-- Promise-client infrastructure failures use one generated `ClientError` class with a structured reason such as transport failure, unexpected status, unsupported content type, or malformed response. Promise methods reject with either a tagged declared domain failure or `ClientError`, matching the Effect client's conceptual domain/infrastructure error division.
-- Promise methods accept a separate optional per-call transport-options argument containing `AbortSignal` and header overrides. Cancellation and transport metadata do not enter the domain input object; broader interceptor and response-mode APIs remain deferred.
-- Promise streaming methods return a lazy `AsyncIterable` directly rather than a Promise-wrapped stream object. Iteration opens the connection, `AbortSignal` cancels it, and ending iteration closes the underlying request; the Effect emitter analogously returns `Stream` directly.
-- Promise SSE connection establishment, declared HTTP failures, and infrastructure failures occur during `AsyncIterable` iteration, beginning with its first `next()` call, rather than during synchronous method construction.
-- Neither generated streaming runtime automatically reconnects after disconnection. Promise `AsyncIterable` and Effect `Stream` fail explicitly; live consumers refresh and resubscribe, while durable sequence-based resume remains explicit composition above the generated client.
-- Promise client construction is synchronous and network-free. It requires `baseUrl`, defaults to `globalThis.fetch`, accepts client-level headers, and merges them with per-call header overrides.
-- Effect client construction accepts an explicit `baseUrl` and obtains `HttpClient.HttpClient` from the Effect environment. It does not install fetch or duplicate per-call transport policy; callers transform/provide the client for headers, tracing, retries, recording, and tests, while fiber interruption owns cancellation.
-- Promise and Effect emitters each own their generated public type modules. The **SDK Contract IR**, not a physically shared generated type package, is the common source; this permits zero-Effect wire types and rich decoded Effect types to evolve independently.
-- Promise and Effect network clients ship from `@opencode-ai/client` behind isolated root and `/effect` exports. The root has no runtime path to Effect; `/effect` imports only Effect, Schema, and Protocol.
-- The Effect-native scoped host belongs to `@opencode-ai/sdk-next`, which will assume the existing `@opencode-ai/sdk` name after legacy consumers migrate. Client remains network-only and SDK depends one-way on Client.
-- SDK executes Server's assembled `HttpRouter` in memory. It opens no listener and performs no network I/O, while preserving Server routing, middleware, codecs, handlers, and errors.
-- The Effect Client and SDK re-export their decoded datatype facade from Schema so callers do not depend on internal package locations or Core's versioned names.
-- A capability intended for both networked and **Embedded OpenCode** belongs in the authoritative public `HttpApi`; embedded-only same-process capabilities extend **Embedded OpenCode** separately.
-- `sessions.log({ sessionID, after, follow })` is the public durable Session event stream. It verifies the Session, replays durable events after the optional aggregate sequence, optionally continues with newly committed durable events, excludes live-only fragments, and is transported as SSE in both networked and embedded modes.
-- `events.subscribe()` is a distinct public instance-wide live stream for Session and non-Session activity. It has no replay guarantee and includes connection, heartbeat, and instance-disposal lifecycle events; consumers recover from disconnection by refreshing authoritative state.
-- A Session ID is not an optional filter on `events.subscribe()`: instance-wide live events and durable Session events have different schemas, replay guarantees, cursors, lifecycle events, and failure behavior.
-- The initial common OpenCode Client does not expose server-global event aggregation. `events.subscribe()` is bounded to the connected OpenCode instance or workspace; any future cross-instance administrative stream requires a separately designed API.
-- `events.subscribe()` does not automatically reconnect after transport loss. The live-only stream fails with `ClientError`; consumers refresh authoritative state before explicitly opening a new subscription because events missed during disconnection cannot be replayed.
-- `sessions.log({ sessionID, after, follow })` returns the generated HTTP client's cold durable event stream and does not build reconnection policy into the endpoint or client constructor. Transport loss fails the stream with `ClientError`. Callers may compose an explicit resuming stream above it by retaining the last observed durable sequence and opening a new subscription with `after`; any reusable resume helper remains a separate API design question.
-- The stable `sessions.list(...)` design returns a **Page** in both networked and **Embedded OpenCode**; embedded execution does not define a separate unbounded array-returning list operation. The beta client currently preserves the existing HTTP `{ data, cursor }` envelope until emitter-level Page projection is implemented.
-- Session list cursors are opaque branded values carrying continuation query and ordering state. Consumers pass them back unchanged and do not inspect storage anchors or encoded filter fields.
-- A Session list continuation accepts only its opaque cursor. Scope, filters, ordering, and page size are fixed by the initial query and carried by that cursor.
-- `sessions.messages(...)` returns a **Page** and uses the same cursor discipline as `sessions.list(...)`: the initial request supplies `sessionID`, ordering, and page size; continuation supplies `sessionID` plus only an opaque branded message cursor carrying ordering, page size, direction, and message anchor. Using a cursor with another Session is invalid.
-- `sessions.message({ sessionID, messageID })` is a required resource lookup. An unknown Session fails with `SessionNotFoundError`; a known Session with an absent or differently owned message fails with `MessageNotFoundError` without disclosing cross-Session ownership. Absence is not represented as `undefined` across the public HTTP boundary.
-- `sessions.interrupt({ sessionID })` first verifies that the durable Session exists, failing with `SessionNotFoundError` otherwise. For a known Session, interruption is idempotent: idle, already-settled, or locally unowned execution is a no-op.
-- `sessions.active()` snapshots the current process's foreground Session drain registry as a record of Session IDs to `{ type: "running" }`. Missing IDs are inactive; background subagents and tasks do not make their parent Session active, and process restart clears the registry.
-- `sessions.context({ sessionID })` preserves the existing message-only operation. It returns projected **Session History**; it does not include or represent the complete **Model Context**, whose agent system text, **Initial Instructions**, tools, and step-local additions remain separate.
-- **Open question**: Should a future, separately named operation expose complete **Model Context**, including the instruction baseline, applied instruction metadata, tools, and step-local additions?
-- `sessions.prompt(...)` exposes `resume?: boolean`. Omitting it preserves durable admission followed by an advisory execution wake; `resume: false` requests durable admit-only behavior.
-- The public operation remains `sessions.prompt(...)`; `SessionPending.admit` is the internal primitive, while the public `Admission` result and `resume` option express its durable admission semantics.
-- `sessions.create(...)` accepts an optional `location`. Omission resolves through the connected OpenCode instance's default or current location; an explicit value selects a known location. Networked and embedded transports use the same handler semantics.
-- `sessions.switchAgent({ sessionID, agent })` is part of the common client alongside `sessions.switchModel(...)`. It affects subsequent Session activity and fails with `SessionNotFoundError` for an unknown Session.
-- The **Embedded OpenCode** Layer delegates to the same scoped creation path; it does not define a second implementation.
-- A **PTY Environment** adapter observes plugins in the request Location while passing the resolved PTY working directory to the hook; standalone servers use an empty adapter.
-- An **Instruction Update** lowers to the provider's native chronological instruction role when supported and to a wrapped chronological fallback otherwise.
-- When the aggregate discovered instruction set changes, its **Instruction Update** includes the complete current ordered set and supersedes the prior aggregate value; when no discovered instructions remain, the message states that previously loaded instructions no longer apply.
-- Ambient project instruction discovery honors `OPENCODE_DISABLE_PROJECT_CONFIG`; global instructions remain eligible.
-- Oversized textual **Model Tool Output** retains a bounded preview in Session history while its complete text moves to managed tool-output storage. Arbitrary structured-result size is a separate concern.
-- One tool settlement receives one aggregate textual limit, using the configured maximum lines or UTF-8 bytes, whichever is reached first. The limit is provider-independent; token pressure belongs to context assembly and compaction.
-- Generic truncation preserves the beginning and end of textual output. Tools may apply a more meaningful strategy before the Tool Registry enforces the final limit.
-- A truncated **Model Tool Output** identifies its complete text in the bounded model-visible preview. The Tool Registry also supplies managed paths as internal metadata to tool hooks; Session events do not expose a typed `outputPaths` field.
-- A **Managed Tool Output File** is temporary and may expire after its retention period. The bounded **Model Tool Output**, not the file, is the durable replayable record.
-- Failure to retain a **Managed Tool Output File** fails settlement operationally. The Session never publishes a successful result whose complete output was lost during generic bounding.
-- Once a tool operation succeeds, bounding its **Model Tool Output** and publishing its one durable settlement form an interruption-safe completion region. Raw oversized success is never published before a later correction.
-- When a structured-only result would exceed the **Model Tool Output** limit, its validated structured value remains unchanged for Session consumers while model replay uses a bounded textual JSON preview and optional managed output path.
-- Existing tool-managed output paths survive generic bounding. A fallback file retains exactly the complete projected text received by the Tool Registry and never claims to reconstruct output already discarded by tool-specific shaping.
-- **Managed Tool Output Files** use globally unique names in one shared flat directory. They receive no special filesystem authority; each tool applies its ordinary external-path policy.
-- Provider-executed tool results remain provider-native transcript facts outside generic Tool Registry bounding. Their context control requires provider-aware pruning or compaction because some providers require exact structured round-trip payloads.
-
-## Client contract architecture
-
-Semantic values that mean the same thing internally and publicly live in the lightweight Schema leaf. Core consumes Schema for domain behavior; Protocol composes Schema values into paths, payloads, envelopes, errors, cursors, and streams; Server imports both, hosts Protocol's exact groups, and owns protocol/domain adaptation. The root Promise client remains zero-Effect, `/effect` depends on Effect plus Schema and Protocol, and `@opencode-ai/sdk-next` composes the scoped in-process host above Client, Core, and Server.
-
-Shared public records are plain objects declared with `Schema.Struct`. A same-name inferred interface gives object records readable TypeScript signatures without constructors, prototypes, or nominal identity; unions retain explicit type aliases.
-
-Before stabilizing the client API:
-
-- Keep additional public schemas in Schema and additional network groups in Protocol; neither package may transitively load databases, Drizzle, Session execution, providers, watchers, native modules, or WASM.
-- Keep concrete Location middleware keys in Server while Protocol owns their placement. Client projections may supply transport-only keys, but must prove generated equivalence with Server's concrete API.
-- Project the existing list response envelope to the stable client **Page** shape and enforce separate initial-query and cursor-continuation inputs without changing the hosted V2 wire contract.
-- Settle the stable consumer namespace (`session` versus the current beta `sessions`) and use an explicit codegen annotation if the consumer name should differ from the server group identifier.
-- Preserve V2 route paths, operation IDs, codecs, errors, middleware behavior, and OpenAPI output while making this change.
-- Preserve browser-safe `@opencode-ai/client` and `@opencode-ai/client/effect` bundles through import-boundary tests.
-- Define embedded-host placement before supporting multiple hosts over one database. Hosts that share durable Session storage must also share process-local Session execution coordination, or each host must receive isolated storage explicitly.
-- Keep an embedded request scope alive until any streamed response body finishes. The initial non-streaming Session surface does not exercise this lifetime boundary; Session and instance event streams must do so before joining the embedded client.
-
-## Example dialogue
-
-> **Dev:** "The date changed while the session was active. Should the **Instruction Update** say what the old date was?"
-> **Domain expert:** "No. Emit the newly effective date so the agent can act on the current instructions."
-
-## Flagged ambiguities
-
-- Legacy `experimental.chat.system.transform` can mutate assembled system text arbitrarily, but V2 plugins do not yet expose an equivalent hook. Decide separately whether to port it, model dynamic uses as explicit **Instruction Sources**, or narrow its semantics.

docs/design/service-lifecycle.md

@@ -0,0 +1,685 @@
+# Service Lifecycle: Election, Restart, and Reconnect
+
+Status: in progress
+
+Incident: [#36688](https://github.com/anomalyco/opencode/issues/36688)
+
+## Summary
+
+The managed V2 service keeps its current update policy: the background updater
+may install a new package, but only a freshly launched TUI activates that update
+after finding an older running service. Existing TUIs never replace a service;
+they only reconnect.
+
+The restart path changes in three places:
+
+1. A process-held OS lock, not the HTTP port or registration file, elects
+   exactly one server owner for its lifetime.
+2. The elected process binds and registers a minimal lifecycle surface before
+   it initializes the application, so clients can distinguish a slow winner
+   from an absent server.
+3. TUIs rediscover and reconnect indefinitely. Transport loss is never a
+   terminal error by itself.
+
+Several clients may spawn small contenders during a restart. This is safe and
+intentional: one contender acquires the lock and initializes, while every loser
+exits before expensive server boot. The design does not require clients to
+agree on a single initiator.
+
+This proposal does not introduce a supervisor process, warm candidate server,
+protocol negotiation, idle background restart, or general execution-recovery
+framework.
+
+## Architecture at a Glance
+
+```text
+                       ╭───────────────────╮
+                       │ CLI ServiceConfig │
+                       ╰─────────┬─────────╯
+                                 │
+                                 ▼
+                     ╭──────────────────────╮
+                     │ CLI ServerConnection │
+                     ╰───────────┬──────────╯
+              ╭──────────────────╰───────────────────╮
+              ▼                                      ▼
+╭──────────────────────────╮            ╭─────────────────────────╮
+│ Client Service lifecycle │            │ CLI runPromiseWith seam │
+╰─────────────┬────────────╯            ╰─────────────┬───────────╯
+              ╰─────╮                                 │
+                    ▼                                 ▼
+     ╭────────────────────────────╮            ╭─────────────╮
+     │ Background service process │            │ TUI / Solid │
+     ╰──────────────┬─────────────╯            ╰──────┬──────╯
+                    │                                 │
+                    ╰────────────◀────────────────────╯
+                     ╭───────────────────────╮
+                     │ Server HTTP transport │
+                     ╰───────────┬───────────╯
+                                 │
+                                 ▼
+                       ╭──────────────────╮
+                       │ Core application │
+                       ╰──────────────────╯
+```
+
+| Owner                                            | Responsibility                                                                                      |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `packages/client/src/effect/service.ts`          | Effect-native discovery, start, and stop lifecycle operations                                       |
+| `packages/cli/src/services/service-config.ts`    | CLI registration path, installed version, and daemon command                                        |
+| `packages/cli/src/services/server-connection.ts` | Resolve an endpoint and, only for the shared service, grouped reconnect and restart Effects         |
+| `packages/cli/src/server-process.ts`             | Daemon election, registration, and server process boot                                              |
+| `packages/server/src/process.ts`                 | HTTP lifecycle shell and application transport                                                      |
+| `packages/core`                                  | Application behavior behind the transport                                                           |
+| CLI default handler                              | Convert lifecycle Effects with the outer `FileSystem` context and pass grouped Promise capabilities |
+| `packages/tui` Solid client context              | Own event-stream reconnect, endpoint replacement, status, and user-triggered restart UI             |
+
+## Implementation Status
+
+| Area                      | State                                                                 |
+| ------------------------- | --------------------------------------------------------------------- |
+| Lifetime ownership        | Implemented on this branch with a scoped OS lock                      |
+| Contender behavior        | Implemented; losers exit before the server module is imported         |
+| Registration repair       | Implemented; the owner reasserts deleted or corrupt discovery         |
+| Channel isolation         | Implemented with no-clobber migration for legacy preview discovery    |
+| Client startup waiting    | Implemented; slow winners are not killed and waiting is indefinite    |
+| Lifecycle shell           | Implemented; the owner binds and registers before application boot    |
+| Failed-state latching     | Implemented; deterministic boot failure stays bound and actionable    |
+| Recovery diagnostics      | Implemented; the TUI shows status instead of transport internals      |
+| Cross-platform validation | macOS runtime verified; Linux and Windows run in the unit-test matrix |
+
+## Context
+
+The V2 CLI runs a shared managed service that owns Sessions, location graphs,
+plugins, permissions, and tool execution. The service updater can replace the
+installed package while the current process continues running the old image.
+A later TUI launch then detects the version mismatch and replaces the service.
+
+Incident #36688 showed four failures in that replacement path:
+
+- Multiple TUIs spawned heavyweight server contenders.
+- A winner remained unobservable while it cold-booted, so another wave treated
+  it as absent and displaced it.
+- A fresh TUI exhausted its reconnect budget and crashed with an unhandled
+  transport defect.
+- A losing contender remained alive and consumed about 1 GB of RSS.
+
+The `origin/v2` baseline serializes service startup with `EffectFlock`. A
+contender acquires a three-second heartbeat lease, checks whether another
+service became discoverable, and only the winner crosses the application-boot
+boundary. This already prevents simultaneous heavy boots and makes startup
+losers exit.
+
+The lease is released immediately after registration, however, so it is not
+lifetime ownership. Registration then reverts to last-writer-wins authority: a
+deleted or corrupt registration can admit a second boot, a displaced server
+terminates itself through its 10-second registration self-check, and a stalled
+lease holder can be displaced after the three-second service staleness timeout.
+
+`Flock` and `EffectFlock` live in `packages/core/src/util` and are also used for
+config writes, MCP auth, npm installs, and repository caching. Despite the
+name, the primitive is an atomic-mkdir lease with heartbeat and staleness
+takeover, not an OS-held lock. It remains appropriate for bounded critical
+sections, including today's startup fence, but is not lifetime service
+ownership.
+
+The current implementation also mixes three different concepts:
+
+- **Ownership:** which process is allowed to be the managed server.
+- **Discovery:** where clients can reach that process.
+- **Lifecycle:** whether that process is starting, ready, stopping, or failed.
+
+This design gives each concept one authority.
+
+```definitions
+[
+  {
+    "term": "Owner",
+    "definition": "The one process holding the process-held OS service lock."
+  },
+  {
+    "term": "Contender",
+    "definition": "A small serve process attempting to acquire the service lock. It must not initialize the application before winning."
+  },
+  {
+    "term": "Registration",
+    "definition": "An atomic discovery record containing the elected owner's identity and endpoint. Registration never grants ownership."
+  },
+  {
+    "term": "Lifecycle shell",
+    "definition": "The minimal HTTP surface bound by the elected process before application initialization. It serves health and retryable startup responses."
+  },
+  {
+    "term": "Application",
+    "definition": "The full server routes and global or location-scoped modules used for normal OpenCode work."
+  }
+]
+```
+
+## Goals
+
+- At most one process initializes and serves the managed application.
+- Losing contenders exit before database, route, plugin, MCP, or location boot.
+- A slow winner becomes observable before expensive initialization.
+- Existing and freshly launched TUIs survive retryable service unavailability.
+- Reconnect follows service state instead of displaying retry counts or raw
+  transport failures.
+- Version-mismatch replacement remains triggered by a fresh TUI launch.
+- A stale or malformed registration cannot create a second owner.
+- An unresponsive owner is never killed automatically by an arbitrary TUI.
+- Every spawned contender has a bounded path to ownership or exit.
+
+## Non-goals
+
+- Restarting automatically when a background update finds an idle window.
+- Running old and candidate application servers concurrently.
+- Adding a permanent steward, proxy, or supervisor process.
+- Zero-downtime worker handoff or automatic rollback.
+- Application protocol negotiation or automatic TUI self-restart.
+- General hard-crash recovery for active Sessions.
+- Defining recovery semantics for provider attempts, tools, shells, sub-agents,
+  permissions, questions, or background jobs.
+- Automatically killing a frozen owner.
+- Bounding concurrent location cold boots after clients reconnect.
+- Multi-machine or clustered service placement.
+
+## Invariants
+
+1. **The service lock is ownership.** Exactly one process may hold the OS lock
+   for one installation channel and service profile.
+2. **Ownership precedes boot.** A contender performs no expensive application
+   initialization before it acquires the lock.
+3. **Ownership lasts for the process lifetime.** The owner holds an open lock
+   handle until the managed server exits. The OS releases it on process death
+   without a cleanup callback.
+4. **The port is transport, not election.** The owner may select a dynamic port
+   after acquiring the lock.
+5. **Registration is discovery, not election.** Deleting, corrupting, or
+   replacing registration does not invalidate a live owner's lock.
+6. **Only a fresh launch enforces package version.** Existing TUIs reconnect to
+   the current owner without initiating version replacement.
+7. **Transport loss is retryable.** It never terminates a TUI without a separate
+   diagnosed, non-retryable cause.
+8. **Clients do not kill an unresponsive owner automatically.** Destructive
+   recovery requires the explicit `service restart` command.
+9. **Lifecycle does not promise execution semantics.** Graceful replacement
+   invokes Session suspension and resumption hooks, but tool-level continuity
+   belongs to a separate design.
+
+## System Model
+
+```text
+╭───────────────────────╮                              ╭──────────────────────────────╮
+│ Fresh or existing TUI │                              │ Process-held OS service lock │
+╰───────────┬───────────╯                              ╰───────────────┬──────────────╯
+            ╰─────┬ normal requests  observe ───────────────────────╮  │
+                  │ discover               │                        ├──╯ authorizes one owner
+                  ▼                        │                        ▼
+        ╭───────────────────╮              │               ╭─────────────────╮
+        │ Registration file │              │               │ Lifecycle shell │
+        ╰───────────────────╯              │               ╰────────┬────────╯
+                                           │                        │
+                                           ├────────────────────────╯
+                                           ▼
+                               ╭──────────────────────╮
+                               │ OpenCode application │
+                               ╰──────────────────────╯
+```
+
+The lifecycle shell and application run in the same process. The distinction is
+initialization order and responsibility, not process topology.
+
+## Service Status
+
+The server reports one small status value:
+
+```typescript
+type ServiceStatus =
+  | {
+      type: "starting"
+    }
+  | {
+      type: "ready"
+    }
+  | {
+      type: "stopping"
+      targetVersion?: string
+    }
+  | {
+      type: "failed"
+      message: string
+      action: string
+    }
+```
+
+The client adds only the discovery states needed by callers:
+
+```typescript
+type Status = { type: "missing" } | { type: "unreachable" } | { type: "unresponsive" } | ServiceStatus
+```
+
+The health response retains the existing fields for old clients and adds the
+status discriminant:
+
+```typescript
+type ServiceHealth = {
+  healthy: true
+  version: string
+  pid: number
+  instanceID: string
+  status: ServiceStatus
+}
+```
+
+`healthy: true` means the registered lifecycle shell is responding and its
+identity matches registration. New clients use `status.type === "ready"` as
+the application-readiness signal.
+
+During `starting` or `stopping`, application requests are not held in memory.
+They receive an immediate retryable response:
+
+```http
+HTTP/1.1 503 Service Unavailable
+Retry-After: 1
+Content-Type: application/json
+
+{"code":"service_starting"}
+```
+
+`stopping` uses `service_stopping`. A failed application boot uses
+`service_failed` and includes a safe diagnostic message.
+
+A failed owner remains bound and keeps holding the service lock. Exiting on
+failure would let every waiting client's `ensureRunning` loop elect a new
+contender that repeats the same heavy failing boot, so staying bound turns a
+deterministic boot failure into one observable `failed` state instead of a
+client-driven respawn loop. Recovery still works: a fresh launch observes the
+failed instance through the stop path, and explicit `service restart` replaces
+it.
+
+## Registration Contract
+
+Registration contains only discovery identity:
+
+```typescript
+type ServiceRegistration = {
+  schema: 1
+  instanceID: string
+  version: string
+  url: string
+  pid: number
+}
+```
+
+Authentication continues to use the existing private service credential
+storage. The registration schema does not change that policy.
+
+The owner writes registration only after the lifecycle shell has bound:
+
+1. Bind the lifecycle shell.
+2. Write a temporary registration file with mode `0600`.
+3. Atomically rename it over the old registration.
+4. Serve lifecycle health as `starting`.
+
+On shutdown, the owner removes registration only if the current file still has
+its `instanceID`. An old finalizer can never remove a successor's registration.
+
+While running, the owner periodically asserts its registration. Because the
+lock guarantees exactly one live owner, any registration that does not name the
+owner is stale or corrupt, and the owner rewrites it. A deleted or clobbered
+registration therefore heals within one assertion interval instead of leaving
+clients waiting on absent discovery. This inverts today's self-check loop,
+which terminates the displaced process instead of repairing discovery.
+
+Legacy registration shapes are decoded by a compatibility adapter. The new
+domain type does not make fields optional to represent old formats.
+
+## Election
+
+This design promotes today's startup fence into lifetime ownership.
+Last-writer-wins registration is replaced by a process-held OS lock that is
+acquired before any expensive boot work and held for the entire service
+lifetime.
+
+A heartbeat-and-staleness lease, including the existing `Flock` utility, is not
+sufficient for service ownership: the service configures a three-second stale
+timeout, after which its lock can be broken and recreated. An event-loop stall,
+a suspended machine, or a debugger pause can therefore make a live owner appear
+stale and allow a contender to displace it. Service ownership requires a
+process-held OS lock: `flock` on Unix and an exclusively bound named pipe on
+Windows. It cannot be broken because a heartbeat exceeded a timeout. Process
+death releases the lock through the OS.
+
+Neither Bun nor Node exposes `flock` directly, the existing `Flock` utility is
+an mkdir-plus-heartbeat lease rather than an OS-held lock, and the common
+lockfile packages are staleness-based leases as well. The platform layer uses
+`bun:ffi` to call `flock` on POSIX and Node's named-pipe server support on
+Windows, where Bun FFI is not available on every shipped architecture. It lives
+alongside the existing utility in `packages/core/src/util`. This primitive is
+the foundation of the design, so the delivery sequence spikes it first.
+
+```text
+Contender           Lock            Lifecycle              Application
+    │                 │                 │                       │
+    ├─ try acquire ───▶                 │                       │
+    │                 │                 │                       │
+ ╭─ alt: lock held ────────────────────────────────────────────────╮
+ │  │                 │                 │                       │  │
+ │  ◀─ busy ──────────┤                 │                       │  │
+ │  │                 │                 │                       │  │
+ │  ├─────────╮       │                 │                       │  │
+ │  │ exit    │       │                 │                       │  │
+ │  ◀─────────╯       │                 │                       │  │
+ │  │                 │                 │                       │  │
+ ├─ else: lock acquired ───────────────────────────────────────────┤
+ │  │                 │                 │                       │  │
+ │  ◀─ owner ─────────┤                 │                       │  │
+ │  │                 │                 │                       │  │
+ │  ├─ bind, register, starting ────────▶                       │  │
+ │  │                 │                 │                       │  │
+ │  ├─ initialize ──────────────────────────────────────────────▶  │
+ │  │                 │                 │                       │  │
+ │╭─ alt: boot succeeds ──────────────────────────────────────────╮│
+ ││ │                 │                 │                       │ ││
+ ││ │                 │                 ◀─ ready ───────────────┤ ││
+ ││ │                 │                 │                       │ ││
+ │├─ else: boot fails ────────────────────────────────────────────┤│
+ ││ │                 │                 │                       │ ││
+ ││ │                 │                 ◀─ failed, stay bound ──┤ ││
+ ││ │                 │                 │                       │ ││
+ │╰───────────────────────────────────────────────────────────────╯│
+ │  │                 │                 │                       │  │
+ ╰─────────────────────────────────────────────────────────────────╯
+    │                 │                 │                       │
+```
+
+Lock acquisition by a contender is nonblocking or tightly bounded. A loser
+must exit before constructing application routes or importing startup-heavy
+modules.
+
+Several clients may spawn contenders concurrently. The design guarantees one
+heavy winner, not one process spawn. If the winner crashes during startup, the
+OS releases the lock and a later client retry starts another election.
+
+The lock is scoped by installation channel and service profile. Local, preview,
+and stable installations cannot displace one another.
+
+## Update Activation
+
+Background update behavior remains unchanged:
+
+1. The running service checks for an update.
+2. The updater installs the package in the background.
+3. The running process continues using its existing process image.
+4. No idle check or automatic restart occurs.
+
+A fresh TUI launch activates the installed update:
+
+1. Read registration and authenticate the responding service.
+2. If its package version matches the fresh client, attach normally.
+3. If the version differs, request graceful stop of that exact registered
+   instance using the existing authenticated stop path.
+4. Re-check instance identity before every signal or escalation in that path.
+5. Wait for the old process to exit and release the service lock.
+6. Call `ensureRunning` until a compatible service becomes ready.
+
+Concurrent fresh launchers may all observe the same old instance. Stopping that
+exact instance must be idempotent. Once registration names a different instance,
+a stale launcher stops signaling and returns to discovery.
+
+No durable restart-transition record is introduced. The initiating fresh TUI
+already knows the source and target versions and can display its update
+preflight. Existing TUIs may display `Updating...` if they observed `stopping`;
+otherwise `Waiting for background service...` is the honest fallback.
+
+## Fresh Launch Versus Reconnect
+
+Fresh launch and reconnect deliberately have different version policies:
+
+```typescript
+type ManagedConnection =
+  | {
+      type: "launch"
+      requiredVersion: string
+    }
+  | {
+      type: "reconnect"
+    }
+```
+
+- `launch` requires the installed package version and may activate replacement.
+- `reconnect` accepts the current owner and never activates replacement.
+
+This preserves today's permissive reconnect behavior. Explicit application
+protocol negotiation and automatic TUI re-exec remain follow-ups.
+
+## Client Reconnect
+
+Fresh and existing TUIs use the same status loop after startup:
+
+1. Read registration on every attempt. Do not retry a stale URL indefinitely.
+2. If registration is absent, call `ensureRunning` and continue waiting.
+3. If registration is unreachable, call `ensureRunning`. A live owner prevents
+   contenders from acquiring the lock; a dead owner does not.
+4. If status is `starting` or `stopping`, wait.
+5. If status is `failed`, show its actionable message.
+6. If status is `ready`, rebuild HTTP and event-stream clients for the new
+   endpoint and perform authoritative state reconciliation.
+
+Retry cadence is internal policy. Retry counts are telemetry, not user-facing
+state. The TUI waits until the service is ready or the user exits.
+
+Transport failures are handled at the TUI run boundary. A raw client transport
+error or Effect defect must not escape to the terminal. Hard exit is reserved
+for diagnosed causes such as invalid local configuration, failed authentication,
+or a foreign process occupying an explicitly configured port.
+
+The UI derives text from status:
+
+| Status                   | User-facing state                   |
+| ------------------------ | ----------------------------------- |
+| No registration          | `Starting background service...`    |
+| Registration unreachable | `Waiting for background service...` |
+| `starting`               | `Starting OpenCode vX...`           |
+| `stopping`               | `Updating to vX...`                 |
+| `failed`                 | Actionable failure message          |
+| `ready`                  | Normal TUI                          |
+
+## Graceful Session Continuity
+
+Version-mismatch replacement uses the existing graceful Session suspension and
+resumption hooks:
+
+1. The old server snapshots active Session IDs during graceful teardown.
+2. The successor schedules those Sessions for continuation.
+3. The runner reloads durable Session history before continuing.
+
+This lifecycle design does not define what an interrupted physical provider
+attempt or tool invocation means. It does not promise that external side effects
+did not occur, replay the exact interrupted tool, preserve an in-memory form, or
+recover process-local background work.
+
+Those concerns require a separate execution-continuity design covering tools,
+shells, sub-agents, permissions, questions, provider attempts, and hard-crash
+recovery.
+
+## Unresponsive Owner
+
+An unreachable registration does not prove that the owner is dead. A contender
+attempts the service lock:
+
+- If the lock is free, the contender starts a replacement.
+- If the lock is held, the contender exits and the client keeps waiting.
+
+After a bounded diagnostic threshold, the client may show:
+
+```text
+The background service owns the service lock but is not responding.
+Run `opencode service restart` to recover it.
+```
+
+Only explicit `service restart` may perform destructive recovery. It verifies
+the complete registration and process instance before signaling, waits for
+graceful exit, re-checks identity before escalation, and refuses to kill a
+process it cannot positively identify.
+
+Automatic frozen-owner recovery is deferred.
+
+## Failure Walkthroughs
+
+### Update with open TUIs
+
+1. The old service installs vNext but keeps running.
+2. A fresh vNext TUI finds the healthy vOld service and requests graceful stop.
+3. The old service reports `stopping`, suspends active Sessions, and exits.
+4. Open TUIs enter their indefinite status loops.
+5. One or more clients spawn contenders.
+6. One contender acquires the service lock. Losers exit before heavy boot.
+7. The winner binds and registers the lifecycle shell as `starting`.
+8. Clients stop spawning and wait on the observable winner.
+9. The winner initializes the application and reports `ready`.
+10. TUIs rebuild clients, reconcile state, and resume.
+
+### Server crashes while ready
+
+1. The endpoint becomes unreachable and registration may remain stale.
+2. Clients call `ensureRunning`.
+3. Process death has released the service lock.
+4. One contender wins, replaces registration, and starts normally.
+5. Detailed active-execution recovery is outside this design.
+
+### Winner crashes during startup
+
+1. Clients observed `starting` and remain alive.
+2. Process death releases the service lock.
+3. A later reconnect attempt starts another election.
+4. One new contender wins; all other contenders exit.
+
+### Registration is deleted while the owner is healthy
+
+1. Clients may call `ensureRunning` because discovery is absent.
+2. Every contender fails to acquire the owner's lock and exits.
+3. No second application initializes.
+4. The owner's next registration assertion republishes discovery.
+
+### Owner is alive but unresponsive
+
+1. Health fails, but the process still holds the service lock.
+2. Contenders fail lock acquisition and exit.
+3. Clients wait and eventually show explicit recovery guidance.
+4. No TUI kills the owner automatically.
+
+## TDD Verification
+
+Implementation should proceed test-first with real subprocesses and real locks.
+Mocks cannot establish process death, lock release, loser cleanup, or port
+behavior.
+
+### Election tests
+
+| Scenario                                              | Required result                                         |
+| ----------------------------------------------------- | ------------------------------------------------------- |
+| Ten contenders start simultaneously                   | Exactly one crosses the application-boot boundary       |
+| Winner pauses after lock acquisition                  | No loser initializes or remains alive                   |
+| Winner event loop pauses beyond the old stale timeout | Ownership is not displaced                              |
+| Winner crashes before bind                            | Lock releases; a later attempt wins                     |
+| Winner crashes after bind but before registration     | Lock releases; a later attempt replaces stale discovery |
+| Registration is deleted while owner runs              | No second owner initializes                             |
+| Registration is malformed                             | Lock still prevents a second owner                      |
+| Registration names a dead PID                         | New contender can acquire the released lock             |
+| Two installation channels start                       | Each elects an independent owner                        |
+| Explicit configured port is foreign-owned             | Fail diagnostically; do not kill the foreign process    |
+
+The fixture records a marker immediately before application initialization. The
+tests assert that only one process writes that marker and that every loser exits
+within a bounded interval. The harness should also assert that a loser's peak
+RSS stays an order of magnitude below an application boot, since import weight
+was the observed incident cost.
+
+### Lifecycle tests
+
+| Scenario                                        | Required result                                                  |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| Winner owns lock but application boot is paused | Health reports `starting`                                        |
+| Application request arrives during startup      | Immediate retryable `503`                                        |
+| Application becomes ready                       | Status changes once from `starting` to `ready`                   |
+| Graceful replacement begins                     | Status reports `stopping` before disconnect                      |
+| Application initialization fails                | Actionable `failed` status; owner stays bound and holds the lock |
+| Registration is deleted while owner runs        | Owner republishes it within one assertion interval               |
+| Owner exits                                     | Registration is removed only if it still names that owner        |
+
+### Update tests
+
+| Scenario                               | Required result                                          |
+| -------------------------------------- | -------------------------------------------------------- |
+| Background update installs vNext       | Running vOld service does not restart                    |
+| Fresh vNext launch finds vOld          | Exact old instance stops; vNext eventually becomes ready |
+| Two fresh vNext launches race          | One heavy successor; both clients attach                 |
+| Existing vOld TUI reconnects to vNext  | It never requests replacement                            |
+| Stale launcher observes a new instance | It does not signal the new instance                      |
+
+### Reconnect tests
+
+| Scenario                                            | Required result                                    |
+| --------------------------------------------------- | -------------------------------------------------- |
+| Endpoint disappears and changes port                | TUI rediscovers and rebuilds clients               |
+| Service remains unavailable beyond old retry budget | TUI remains alive                                  |
+| Event stream reconnects                             | Client performs authoritative state reconciliation |
+| Transport returns an unexpected defect              | TUI formats it; no raw stack escapes               |
+| Owner remains unresponsive                          | TUI waits and shows explicit restart guidance      |
+
+## Delivery Sequence
+
+1. **Spike the lock primitive.** Prove a nonblocking, process-held OS lock
+   under Bun on macOS, Linux, and Windows (`bun:ffi` to `flock` on POSIX and a
+   named pipe on Windows), including release on hard kill and behavior across
+   containers and network filesystems used in CI.
+2. **Expand the subprocess test harness.** Begin from the baseline
+   two-contender test and cover ten contenders, lock release on crash, a paused
+   winner, deleted or corrupt registration, and bounded loser exit before
+   changing ownership.
+3. **Contain client failure.** Make transport loss nonterminal, rediscover on
+   every cycle, and format unexpected failures at the TUI boundary.
+4. **Promote the startup fence to process-held ownership.** Preserve the
+   existing pre-boot acquisition seam, replace its lease with the OS lock, hold
+   it until process exit, and invert the registration self-check from
+   self-termination to reassertion.
+5. **Bind the lifecycle shell first.** Publish registration and `starting`,
+   return retryable `503` for application requests, then initialize the app.
+   The health contract change is public API: regenerate clients from
+   `packages/client` with `bun run generate`.
+6. **Codify launch versus reconnect.** Fresh launch enforces installed version;
+   reconnect never activates replacement.
+7. **Integrate graceful replacement.** Preserve current background-install and
+   fresh-launch activation behavior while invoking Session continuity hooks.
+8. **Harden explicit recovery.** Verify exact process identity during explicit
+   `service restart`; never automatically kill an unresponsive owner.
+9. **Run the full multi-process suite.** Include repeated restart cycles and
+   assert that no contender or child process remains afterward.
+
+## Acceptance Criteria
+
+- Ten concurrent restart observers produce one application initialization.
+- No losing contender survives or builds a location graph.
+- A 30-second application boot remains continuously observable as `starting`.
+- A TUI remains alive through a service outage longer than the previous retry
+  budget.
+- A service endpoint change does not require restarting an existing TUI.
+- Background installation alone does not restart the service.
+- A fresh mismatched TUI eventually attaches to the installed service version.
+- Existing reconnecting TUIs never replace the current owner.
+- Registration corruption cannot produce two owners.
+- A deleted registration heals without restarting the owner or any client.
+- An unresponsive owner is not killed without an explicit recovery command.
+- Raw transport defects never escape to the terminal.
+
+## Follow-ups
+
+- Idle background update activation with an admission fence.
+- Application protocol compatibility and automatic local TUI re-exec.
+- Durable execution recovery for provider attempts and tools.
+- Shell, sub-agent, permission, question, and background-job continuity.
+- Automatic recovery for a positively identified frozen owner.
+- Cold-boot concurrency limits and interaction-prioritized location loading.
+- A steward or socket-handoff architecture if zero-downtime replacement becomes
+  a real requirement.

infra/stage.ts

@@ -8,6 +8,25 @@ export const zoneID = "430ba34c138cfb5360826c4909f99be8"
 export const awsStage = $app.stage === "production" ? "production" : "dev"
 export const deployAws = $app.stage === awsStage
 
+if ($app.stage === "production") {
+  new cloudflare.DnsRecord("TrustCenter", {
+    zoneId: zoneID,
+    name: "trust.opencode.ai",
+    type: "CNAME",
+    content: "3a69a5bb27875189.vercel-dns-016.com",
+    proxied: false,
+    ttl: 60,
+  })
+
+  new cloudflare.DnsRecord("TrustCenterVerification", {
+    zoneId: zoneID,
+    name: "opencode.ai",
+    type: "TXT",
+    content: "compai-domain-verification=org_6993a99c6200a2d642bb115d",
+    ttl: 60,
+  })
+}
+
 new cloudflare.RegionalHostname("RegionalHostname", {
   hostname: domain,
   regionKey: "us",

nix/desktop.nix

@@ -8,6 +8,8 @@
   makeWrapper,
   writableTmpDirAsHomeHook,
   autoPatchelfHook,
+  copyDesktopItems,
+  makeDesktopItem,
   opencode,
 }:
 let
@@ -27,9 +29,12 @@ stdenv.mkDerivation (finalAttrs: {
     nodejs
     makeWrapper
     writableTmpDirAsHomeHook
-  ] ++ lib.optionals stdenv.hostPlatform.isLinux [
+  ]
+  ++ lib.optionals stdenv.hostPlatform.isLinux [
     autoPatchelfHook
-  ] ++ lib.optionals stdenv.hostPlatform.isDarwin [
+    copyDesktopItems
+  ]
+  ++ lib.optionals stdenv.hostPlatform.isDarwin [
     # Ad-hoc sign the .app: --config.mac.identity=null below skips signing.
     darwin.autoSignDarwinBinariesHook
   ];
@@ -38,20 +43,37 @@ stdenv.mkDerivation (finalAttrs: {
     (lib.getLib stdenv.cc.cc)
   ];
 
+  desktopItems = lib.optional stdenv.hostPlatform.isLinux (makeDesktopItem {
+    name = "ai.opencode.desktop";
+    desktopName = "OpenCode";
+    exec = "opencode-desktop %U";
+    icon = "ai.opencode.desktop";
+    # Electron 41 derives X11 WM_CLASS from app.name.
+    startupWMClass = "OpenCode";
+    categories = [ "Development" ];
+  });
+
   env = opencode.env // {
     ELECTRON_SKIP_BINARY_DOWNLOAD = "1";
   };
 
-  # https://github.com/electron/electron/issues/31121
-  # mac builds use a .app bundle which doesnt have this issue
-  postPatch = lib.optionalString stdenv.isLinux ''
-    BASE_PATH=packages/desktop
-    FILES=(src/main/windows.ts)
-    for file in "''${FILES[@]}"; do
-      substituteInPlace $BASE_PATH/$file \
-        --replace-fail "process.resourcesPath" "'$out/opt/opencode-desktop/resources'"
-    done
-  '';
+  postPatch =
+    # NOTE: Relax Bun version check to be a warning instead of an error
+    ''
+      substituteInPlace packages/script/src/index.ts \
+        --replace-fail 'throw new Error(`This script requires bun@''${expectedBunVersionRange}' \
+                       'console.warn(`Warning: This script requires bun@''${expectedBunVersionRange}'
+    ''
+    # https://github.com/electron/electron/issues/31121
+    # mac builds use a .app bundle which doesnt have this issue
+    + lib.optionalString stdenv.isLinux ''
+      BASE_PATH=packages/desktop
+      FILES=(src/main/windows.ts)
+      for file in "''${FILES[@]}"; do
+        substituteInPlace $BASE_PATH/$file \
+          --replace-fail "process.resourcesPath" "'$out/opt/opencode-desktop/resources'"
+      done
+    '';
 
   preBuild = ''
     cp -r "${electron.dist}" $HOME/.electron-dist
@@ -76,27 +98,38 @@ stdenv.mkDerivation (finalAttrs: {
     runHook postBuild
   '';
 
-  installPhase =
-    ''
-      runHook preInstall
-    ''
-    + lib.optionalString stdenv.hostPlatform.isDarwin ''
-      mkdir -p $out/Applications
-      mv dist/mac*/*.app $out/Applications
-      makeWrapper "$out/Applications/OpenCode.app/Contents/MacOS/OpenCode" $out/bin/opencode-desktop
-    ''
-    + lib.optionalString stdenv.hostPlatform.isLinux ''
-      mkdir -p $out/opt/opencode-desktop
-      cp -r dist/linux*-unpacked/{resources,LICENSE*} $out/opt/opencode-desktop
-      makeWrapper ${lib.getExe electron} $out/bin/opencode-desktop \
-        --inherit-argv0 \
-        --set ELECTRON_FORCE_IS_PACKAGED 1 \
-        --add-flags $out/opt/opencode-desktop/resources/app.asar \
-        --add-flags "\''${NIXOS_OZONE_WL:+\''${WAYLAND_DISPLAY:+--ozone-platform-hint=auto --enable-features=WaylandWindowDecorations --enable-wayland-ime=true}}"
-    ''
-    + ''
-      runHook postInstall
-    '';
+  installPhase = ''
+    runHook preInstall
+  ''
+  + lib.optionalString stdenv.hostPlatform.isDarwin ''
+    mkdir -p $out/Applications
+    mv dist/mac*/*.app $out/Applications
+    makeWrapper "$out/Applications/OpenCode.app/Contents/MacOS/OpenCode" $out/bin/opencode-desktop
+  ''
+  + lib.optionalString stdenv.hostPlatform.isLinux ''
+    mkdir -p $out/opt/opencode-desktop
+    cp -r dist/linux*-unpacked/{resources,LICENSE*} $out/opt/opencode-desktop
+    install -Dm644 resources/icons/32x32.png \
+      "$out/share/icons/hicolor/32x32/apps/ai.opencode.desktop.png"
+    install -Dm644 resources/icons/64x64.png \
+      "$out/share/icons/hicolor/64x64/apps/ai.opencode.desktop.png"
+    install -Dm644 resources/icons/128x128.png \
+      "$out/share/icons/hicolor/128x128/apps/ai.opencode.desktop.png"
+    install -Dm644 resources/icons/128x128@2x.png \
+      "$out/share/icons/hicolor/256x256/apps/ai.opencode.desktop.png"
+    install -Dm644 resources/icons/icon.png \
+      "$out/share/icons/hicolor/512x512/apps/ai.opencode.desktop.png"
+    install -Dm644 resources/ai.opencode.desktop.metainfo.xml \
+      "$out/share/metainfo/ai.opencode.desktop.metainfo.xml"
+    makeWrapper ${lib.getExe electron} $out/bin/opencode-desktop \
+     --inherit-argv0 \
+     --set ELECTRON_FORCE_IS_PACKAGED 1 \
+     --add-flags $out/opt/opencode-desktop/resources/app.asar \
+     --add-flags "\''${NIXOS_OZONE_WL:+\''${WAYLAND_DISPLAY:+--ozone-platform-hint=auto --enable-features=WaylandWindowDecorations --enable-wayland-ime=true}}"
+  ''
+  + ''
+    runHook postInstall
+  '';
 
   autoPatchelfIgnoreMissingDeps = [
     "libc.musl-x86_64.so.1"

nix/hashes.json

@@ -1,8 +1,8 @@
 {
   "nodeModules": {
-    "x86_64-linux": "sha256-JTtn+wXTXg+yklvIMDLcGFaYhTU6ZrCgKT9JTNEQ3gA=",
-    "aarch64-linux": "sha256-gXU6zyhvAZrZirkL/PlHdkHtEof/7PVSPCaE34Jnd4U=",
-    "aarch64-darwin": "sha256-Q0oTG3uzOlD/X2kJingLle529lKFoTpyCW2rHXOZ6iE=",
-    "x86_64-darwin": "sha256-LINvKHxPibTlJeNzfACQx0x+Yj5oROT6Du3I5AtqqXk="
+    "x86_64-linux": "sha256-qt11SKmOjq0KU542QFbs+u7YyJicn4drCcwCdg325yk=",
+    "aarch64-linux": "sha256-z68doReXTrWS7HeiAjc0btIjAsvzeZZ7hXAlHr0c77Q=",
+    "aarch64-darwin": "sha256-PILYH1Pi8XBvSkuZ+1sNnUTao5kba+m5Z8iJKx6YXPo=",
+    "x86_64-darwin": "sha256-KpcJzP4m0SUavu/WaSffgzOxrHq8ljdy0GOzs9p16lo="
   }
 }

package.json

@@ -12,9 +12,10 @@
     "dev:web": "bun --cwd packages/app dev",
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",
     "dev:stats": "bun sst shell --stage=production -- bun run --cwd packages/stats/app dev",
+    "dev:www": "bun run --cwd packages/www dev",
     "dev:storybook": "bun --cwd packages/storybook storybook",
     "lint": "oxlint",
-    "lint:effect-patterns": "ast-grep scan -c script/ast-grep/sgconfig.yml packages/core/src packages/server/src packages/protocol/src packages/cli/src",
+    "lint:effect-patterns": "ast-grep scan -c script/ast-grep/sgconfig.yml packages/util/src packages/core/src packages/server/src packages/protocol/src packages/cli/src",
     "test:lint-rules": "ast-grep test -c script/ast-grep/sgconfig.yml",
     "typecheck": "bun turbo typecheck --concurrency=3",
     "typecheck:profile": "bun script/profile-typecheck.ts",
@@ -36,19 +37,19 @@
       "packages/slack"
     ],
     "catalog": {
-      "@effect/opentelemetry": "4.0.0-beta.83",
-      "@effect/platform-node": "4.0.0-beta.83",
-      "@effect/sql-sqlite-bun": "4.0.0-beta.83",
+      "@effect/opentelemetry": "4.0.0-beta.98",
+      "@effect/platform-node": "4.0.0-beta.98",
+      "@effect/sql-sqlite-bun": "4.0.0-beta.98",
       "@npmcli/arborist": "9.4.0",
       "@types/bun": "1.3.13",
       "@types/cross-spawn": "6.0.6",
       "@octokit/rest": "22.0.0",
       "@hono/standard-validator": "0.2.0",
       "@hono/zod-validator": "0.4.2",
-      "@opentui/core": "0.4.3",
-      "@opentui/keymap": "0.4.3",
-      "@opentui/solid": "0.4.3",
-      "@tanstack/solid-virtual": "3.13.28",
+      "@opentui/core": "0.4.5",
+      "@opentui/keymap": "0.4.5",
+      "@opentui/solid": "0.4.5",
+      "@tanstack/solid-virtual": "3.13.32",
       "@shikijs/stream": "4.2.0",
       "ulid": "3.0.1",
       "@kobalte/core": "0.13.11",
@@ -68,14 +69,15 @@
       "dompurify": "3.3.1",
       "drizzle-kit": "1.0.0-rc.2",
       "drizzle-orm": "1.0.0-rc.2",
-      "effect": "4.0.0-beta.83",
+      "effect": "4.0.0-beta.98",
       "ai": "6.0.168",
       "cross-spawn": "7.0.6",
       "hono": "4.10.7",
       "hono-openapi": "1.1.2",
       "fuzzysort": "3.1.0",
+      "get-east-asian-width": "1.6.0",
       "luxon": "3.6.1",
-      "marked": "17.0.1",
+      "marked": "17.0.6",
       "marked-shiki": "1.2.1",
       "remend": "1.3.0",
       "@playwright/test": "1.59.1",
@@ -84,9 +86,11 @@
       "@typescript/native-preview": "7.0.0-dev.20251207.1",
       "zod": "4.1.8",
       "remeda": "2.26.0",
+      "resolve.exports": "2.0.3",
       "sst": "4.13.1",
       "shiki": "4.2.0",
       "solid-list": "0.3.0",
+      "string-width": "7.2.0",
       "tailwindcss": "4.1.11",
       "vite": "7.1.4",
       "@solidjs/meta": "0.29.4",
@@ -102,6 +106,8 @@
   "devDependencies": {
     "@actions/artifact": "5.0.1",
     "@ast-grep/cli": "0.44.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
     "@tsconfig/bun": "catalog:",
     "@types/mime-types": "3.0.1",
     "@typescript/native-preview": "catalog:",
@@ -158,10 +164,9 @@
     "gcp-metadata@8.1.2": "patches/gcp-metadata@8.1.2.patch",
     "pacote@21.5.0": "patches/pacote@21.5.0.patch",
     "@ai-sdk/google@3.0.73": "patches/@ai-sdk%2Fgoogle@3.0.73.patch",
-    "@tanstack/solid-virtual@3.13.28": "patches/@tanstack%2Fsolid-virtual@3.13.28.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.0": "patches/@tanstack%2Fvirtual-core@3.17.0.patch",
-    "effect@4.0.0-beta.83": "patches/effect@4.0.0-beta.83.patch"
+    "effect@4.0.0-beta.98": "patches/effect@4.0.0-beta.98.patch",
+    "@tanstack/virtual-core@3.17.3": "patches/@tanstack%2Fvirtual-core@3.17.3.patch"
   }
 }

packages/ai/AGENTS.md

@@ -1,4 +1,4 @@
-# LLM Package Guide
+# AI Package Guide
 
 ## Effect
 
@@ -115,10 +115,10 @@ Keep provider facades small and explicit:
 
 ### Provider Package Entrypoints
 
-Catalog-selected native providers use package-like export paths from `@opencode-ai/llm`. 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/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.
 
 ```ts
-import { model } from "@opencode-ai/llm/providers/openai/responses"
+import { model } from "@opencode-ai/ai/providers/openai/responses"
 
 const selected = model("gpt-5", {
   apiKey,
@@ -133,7 +133,7 @@ Do not expose `Route` in provider package settings. Route composition stays an i
 ### Folder layout
 
 ```
-packages/llm/src/
+packages/ai/src/
   schema/                   canonical Schema model, split by concern
     ids.ts                  branded IDs, literal types, ProviderMetadata
     options.ts              Generation/Provider/Http options, Limits, Model, cache policy
@@ -143,7 +143,7 @@ packages/llm/src/
     index.ts                barrel
   llm.ts                    request constructors and convenience helpers
   route/
-    index.ts                @opencode-ai/llm/route advanced barrel
+    index.ts                @opencode-ai/ai/route advanced barrel
     client.ts               Route.make + LLMClient.prepare/stream/generate
     executor.ts             RequestExecutor service + transport error mapping
     protocol.ts             Protocol type + Protocol.make
@@ -164,9 +164,11 @@ packages/llm/src/
     bedrock-converse.ts
     bedrock-event-stream.ts framing for AWS event-stream binary frames
     openai-compatible-chat.ts route that reuses OpenAIChat.protocol, no canonical URL
+    openai-compatible-responses.ts route that reuses OpenAIResponses.protocol, no canonical URL
     utils/                  per-protocol helpers (auth, cache, media, tool-stream, ...)
   providers/
-    openai-compatible.ts    generic compatible helper + family model helpers
+    openai-compatible.ts    generic Chat helper + family model helpers
+    openai-compatible-responses.ts generic Responses helper
     openai-compatible-profile.ts family defaults (deepseek, togetherai, ...)
     azure.ts / amazon-bedrock.ts / cloudflare.ts / github-copilot.ts / google.ts / xai.ts / openai.ts / anthropic.ts / openrouter.ts
   tool.ts                   typed tool() helper

packages/ai/DESIGN.md

@@ -1,7 +1,7 @@
 # AI Library Design
 
-> Discussion draft. This document describes the intended replacement for the
-> current private `@opencode-ai/llm` API. Names and exact TypeScript signatures
+> Discussion draft. This document describes an intended clean-break redesign of
+> the current private `@opencode-ai/ai` API. Names and exact TypeScript signatures
 > are illustrative until implementation, but the domain boundaries and defaults
 > are deliberate.
 
@@ -1074,7 +1074,6 @@ The redesign intentionally removes or changes these current concepts:
 
 | Current                                 | Proposed                                                    |
 | --------------------------------------- | ----------------------------------------------------------- |
-| `@opencode-ai/llm`                      | `@opencode-ai/ai`                                           |
 | Mandatory `LLM.request({ model, ... })` | Inline calls or model-free portable requests                |
 | `LLM.generate` means one turn           | `LLM.generate` means complete run                           |
 | `LLMClient.generate/stream`             | `LLM.generateTurn/streamTurn` for one turn                  |

packages/ai/README.md

@@ -0,0 +1,360 @@
+# @opencode-ai/ai
+
+Schema-first AI primitives for opencode. Provider quirks live in adapters, not in calling code.
+
+```ts
+import { Effect } from "effect"
+import { LLM, LLMClient } from "@opencode-ai/ai"
+import { OpenAI } from "@opencode-ai/ai/providers"
+
+const model = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
+
+const request = LLM.request({
+  model,
+  system: "You are concise.",
+  prompt: "Say hello in one short sentence.",
+  generation: { maxTokens: 40 },
+})
+
+const program = Effect.gen(function* () {
+  const response = yield* LLMClient.generate(request)
+  console.log(response.text)
+})
+```
+
+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.
+
+## Image generation
+
+Use `Image.generate` with an image model for direct asset generation:
+
+```ts
+import { Image, ImageInput } from "@opencode-ai/ai"
+import { OpenAI } from "@opencode-ai/ai/providers"
+
+const program = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).image("gpt-image-2"),
+    prompt: "A robot tending a rooftop garden",
+    options: {
+      n: 2,
+      size: "1024x1024",
+      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
+})
+```
+
+Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:
+
+```ts
+const response =
+  yield *
+  Image.generate({
+    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"),
+    ],
+    options,
+    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:
+
+```ts
+yield *
+  Image.generate({
+    model: OpenAI.configure({ apiKey }).image("gpt-image-2"),
+    prompt,
+    images: [ImageInput.bytes(sourceBytes, "image/png")],
+    options: { mask: ImageInput.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.
+
+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,
+    prompt,
+    options: { quality: "medium" },
+    http,
+  })
+```
+
+xAI image models use the same request API with xAI-native controls:
+
+```ts
+yield *
+  Image.generate({
+    model: XAI.configure({ apiKey }).image("any-model-id"),
+    prompt,
+    options: {
+      n: 2,
+      aspectRatio: "16:9",
+      resolution: "1k",
+      responseFormat: "b64_json",
+      future_option: true,
+    },
+    http,
+  })
+```
+
+Google's current Gemini image models use the same direct API:
+
+```ts
+import { Google } from "@opencode-ai/ai/providers"
+
+const googleProgram = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: Google.configure({ apiKey }).image("any-model-id"),
+    prompt: "A robot tending a rooftop garden",
+    options: {
+      aspectRatio: "16:9",
+      imageSize: "2K",
+      seed: 42,
+      thinkingLevel: "HIGH",
+      includeThoughts: true,
+      futureOption: true,
+    },
+    http,
+  })
+
+  return response.images
+})
+```
+
+Google image options are request-scoped and inferred from the selected model. Known fields autocomplete while
+future string values and arbitrary native Gemini `generationConfig` fields remain available. Native fields override
+their mapped aliases, and `http.body` is the final deep overlay. The selected model ID is sent to Gemini
+`generateContent` without a local allowlist.
+
+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"),
+    prompt,
+    options: {
+      quality: "hd",
+      userID: "user-123",
+      future_option: true,
+    },
+    http,
+  })
+```
+
+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.
+
+Conversational image generation remains part of the LLM interaction. OpenAI Responses exposes it through its hosted image tool:
+
+```ts
+const program = Effect.gen(function* () {
+  const response = yield* LLM.generate(
+    LLM.request({
+      model: OpenAI.configure({ apiKey }).responses("gpt-5"),
+      prompt: "Design a solarpunk rooftop garden, then show me.",
+      tools: [OpenAI.imageGeneration({ quality: "high" })],
+    }),
+  )
+
+  return response.message
+})
+```
+
+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.
+
+## Public API
+
+- **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
+- **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
+- **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
+- **`Model.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
+- **`LLMClient.prepare(request)`** — compile a request through protocol body construction, validation, and HTTP preparation without sending. Useful for inspection and testing.
+- **`LLMEvent.is.*`** — typed guards (`is.textDelta`, `is.toolCall`, `is.finish`, …) for filtering streams.
+- **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
+- **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
+
+## Caching
+
+Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "auto"` unless the caller opts out with `cache: "none"`. Each protocol translates `CacheHint`s to its wire format (`cache_control` on Anthropic, `cachePoint` on Bedrock; OpenAI and Gemini do implicit caching server-side and don't need inline markers — auto is a no-op there).
+
+### Auto placement
+
+`"auto"` places three breakpoints — last tool definition, last system part, latest user message. The last-user-message boundary is the load-bearing detail: in a tool-use loop, a single user turn expands into many assistant/tool round-trips, all sharing that prefix. Caching at that boundary lets every intra-turn API call hit.
+
+The math justifies the default: Anthropic's 5-minute cache write is 1.25× base, read is 0.1×, so a single reuse within 5 minutes already wins. One-shot completions below the per-model minimum-cacheable-token threshold silently no-op on the wire, so the worst case is harmless.
+
+### Opting out
+
+```ts
+LLM.request({
+  model,
+  system,
+  prompt: "one-off question",
+  cache: "none",
+})
+```
+
+### Granular policy
+
+```ts
+cache: {
+  tools?: boolean,
+  system?: boolean,
+  messages?: "latest-user-message" | "latest-assistant" | { tail: number },
+  ttlSeconds?: number,         // ≥ 3600 → 1h on Anthropic/Bedrock; else 5m
+}
+```
+
+### Manual hints
+
+Inline `CacheHint` on any text / system / tool / tool-result part overrides automatic placement. The auto policy preserves manual hints; it only fills gaps.
+
+```ts
+LLM.request({
+  model,
+  system: [
+    { type: "text", text: "stable system prompt", cache: { type: "ephemeral" } },
+  ],
+  ...
+})
+```
+
+### Provider behavior table
+
+| Protocol                | `cache: "auto"`                                                           |
+| ----------------------- | ------------------------------------------------------------------------- |
+| Anthropic Messages      | emits up to 3 `cache_control` markers (4-breakpoint cap enforced)         |
+| Bedrock Converse        | emits up to 3 `cachePoint` blocks (4-breakpoint cap enforced)             |
+| OpenAI Chat / Responses | no-op (implicit caching above 1024 tokens)                                |
+| Gemini                  | no-op (implicit caching on 2.5+; explicit `CachedContent` is out-of-band) |
+
+Normalized cache usage is read back into `response.usage.cacheReadInputTokens` and `cacheWriteInputTokens` across every provider.
+
+## Providers
+
+Provider facades configure endpoint/auth/deployment details first, then expose model selectors that take only a model or deployment id. The selected model carries the executable route value used at runtime.
+
+```ts
+import { OpenAI, CloudflareAIGateway } from "@opencode-ai/ai/providers"
+
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
+const gateway = CloudflareAIGateway.configure({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+  gatewayApiKey: process.env.CLOUDFLARE_API_TOKEN,
+}).model("workers-ai/@cf/meta/llama-3.1-8b-instruct")
+```
+
+Included providers: OpenAI, Anthropic, Google (Gemini), Google Vertex Gemini and Anthropic, Amazon Bedrock, Azure OpenAI, Cloudflare AI Gateway, Cloudflare Workers AI, GitHub Copilot, OpenRouter, xAI, Z.ai, plus generic OpenAI-compatible Chat and Responses entrypoints and an Anthropic Messages-compatible entrypoint.
+
+### Package-like entrypoints
+
+Native catalog integrations load provider behavior through package-like entrypoints. These are export paths from the same `@opencode-ai/ai` npm package, not independently published packages. Each entrypoint exports the same `model(modelID, settings)` contract, and `settings` contains serializable provider configuration plus common `headers`, `body`, and `limits` overlays.
+
+```ts
+import { model } from "@opencode-ai/ai/providers/openai/responses"
+
+const selected = model("gpt-5", {
+  apiKey: process.env.OPENAI_API_KEY,
+  transport: "websocket",
+  headers: { "x-application": "opencode" },
+  limits: { context: 200_000, output: 64_000 },
+})
+```
+
+OpenAI Chat and OpenAI Responses are separate semantic entrypoints:
+
+- `@opencode-ai/ai/providers/openai/chat`
+- `@opencode-ai/ai/providers/openai/responses`
+- `@opencode-ai/ai/providers/openai-compatible/responses`
+- `@opencode-ai/ai/providers/anthropic-compatible`
+- `@opencode-ai/ai/providers/google-vertex/gemini`
+- `@opencode-ai/ai/providers/google-vertex/chat`
+- `@opencode-ai/ai/providers/google-vertex/responses`
+- `@opencode-ai/ai/providers/google-vertex/messages`
+
+Responses HTTP versus WebSocket is a scoped `transport` setting on the OpenAI Responses entrypoint, not another entrypoint. Azure follows the same Chat/Responses split at `providers/azure/chat` and `providers/azure/responses`. Generic OpenAI-compatible Chat remains at `providers/openai-compatible`; compatible Responses is separate at `providers/openai-compatible/responses`. Generic Anthropic Messages-compatible providers use `providers/anthropic-compatible`, which the named Anthropic provider composes. Google Gemini and Amazon Bedrock expose their single native API through their existing provider paths.
+
+Vertex Gemini, Vertex Chat, Vertex Responses, and Vertex Messages are separate API entrypoints. All accept `project`, `location`, and an optional `accessToken`; when no explicit token or auth override is supplied they lazily use Google Application Default Credentials. Vertex Gemini instead selects express mode when `apiKey` or `GOOGLE_VERTEX_API_KEY` is present. Vertex Chat targets MaaS models through the OpenAI-compatible Chat Completions endpoint, while Vertex Responses targets Grok models and defaults `store` to `false` as required by Vertex. `providers/google-vertex` remains the default alias for `providers/google-vertex/gemini`.
+
+Tuned Vertex Gemini deployments use model ids shaped like `endpoints/1234567890` and require OAuth or ADC; Vertex express-mode API keys support publisher models only.
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/gemini"
+
+model("gemini-3.5-flash", { project: "my-project", location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/chat"
+
+model("deepseek-ai/deepseek-v3.2-maas", { project: "my-project", location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/responses"
+
+model("xai/grok-4.20-reasoning", { project: "my-project", location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/messages"
+
+model("claude-sonnet-4-6", { project: "my-project", location: "global" })
+```
+
+Provider facades such as `OpenAI.configure(...).responses(...)` remain the direct application API. Package-like entrypoints are the self-similar loading contract used when a catalog selects behavior by export path.
+
+Other provider exports listed above remain direct facades until they explicitly implement the package-like contract. Exporting a provider facade does not implicitly make it a catalog-loadable provider package.
+
+## Provider options & HTTP overlays
+
+Three escape hatches in order of stability:
+
+1. **`generation`** — portable knobs (`maxTokens`, `temperature`, `topP`, `topK`, penalties, seed, stop).
+2. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `promptCacheKey`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
+3. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.
+
+Route/provider defaults are overridden by request-level values for each axis.
+
+## Routes
+
+Adding a new model or deployment is usually 5-15 lines using `Route.make({ protocol, endpoint, auth, framing, ... })`. The route owns endpoint/auth/framing and the protocol owns body construction plus stream parsing. Transports are reusable IO templates that receive route endpoint/auth at compile time. Capability/catalog metadata lives outside this low-level package; unsupported request shapes fail during protocol lowering. See `AGENTS.md` for the architectural detail.
+
+## Effect
+
+This package is built on Effect. Public methods return `Effect` or `Stream`; provide `LLMClient.layer` for LLM dispatch and `ImageClient.layer` for image dispatch, then import the provider/protocol modules for the routes you use. The example at `example/tutorial.ts` is a runnable walkthrough.
+
+## See also
+
+- `AGENTS.md` — architecture, route construction, contributor guide
+- `STATUS.md` — native provider parity status and AI SDK migration gaps
+- `example/tutorial.ts` — runnable end-to-end walkthrough
+- `test/provider/*.test.ts` — fixture-first protocol tests; `*.recorded.test.ts` files cover live cassettes

packages/ai/STATUS.md

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

packages/ai/example/call-sites.md

@@ -7,7 +7,7 @@ values directly.
 ## Conversation Summary
 
 Kit and Aidan want provider-specific LLM behavior to move out of opencode's AI
-SDK transform path and into `packages/llm` where possible. The goal is not a big
+SDK transform path and into `packages/ai` where possible. The goal is not a big
 generic transform layer; the goal is small composable route definitions backed by
 recorded golden tests.
 
@@ -355,11 +355,38 @@ The package-like OpenAI Responses entrypoint instead keeps transport scoped to
 Responses settings while preserving the same `model(...)` contract:
 
 ```ts
-import { model } from "@opencode-ai/llm/providers/openai/responses"
+import { model } from "@opencode-ai/ai/providers/openai/responses"
 
 model("gpt-4o", { apiKey, transport: "websocket" })
 ```
 
+Vertex keeps Gemini, Chat, Responses, and Messages as separate package-like entrypoints,
+while sharing project/location resolution and ADC authentication internally:
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/gemini"
+
+model("gemini-3.5-flash", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/chat"
+
+model("deepseek-ai/deepseek-v3.2-maas", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/responses"
+
+model("xai/grok-4.20-reasoning", { project, location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/messages"
+
+model("claude-sonnet-4-6", { project, location: "global" })
+```
+
 The client should not require a different public layer just because a selected
 route uses WebSocket. Use one `LLMClient.layer` with HTTP and WebSocket runtime
 capabilities available; routes that do not need WebSocket simply never touch it.

packages/ai/example/tutorial.ts

@@ -1,12 +1,12 @@
 import { Config, Effect, Formatter, Layer, Schema, Stream } from "effect"
-import { LLM, LLMClient, Message, ProviderID, Tool, ToolRuntime } from "@opencode-ai/llm"
-import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor, WebSocketExecutor } from "@opencode-ai/llm/route"
-import { OpenAI } from "@opencode-ai/llm/providers"
+import { LLM, LLMClient, Message, ProviderID, Tool, ToolRuntime } from "@opencode-ai/ai"
+import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor, WebSocketExecutor } from "@opencode-ai/ai/route"
+import { OpenAI } from "@opencode-ai/ai/providers"
 
 /**
  * A runnable walkthrough of the LLM package use-site API.
  *
- * Run from `packages/llm` with an OpenAI key in the environment:
+ * Run from `packages/ai` with an OpenAI key in the environment:
  *
  *   OPENAI_API_KEY=... bun example/tutorial.ts
  *

packages/ai/package.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "version": "1.17.20",
+  "name": "@opencode-ai/ai",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "setup:recording-env": "bun run script/setup-recording-env.ts",
+    "test": "bun test --timeout 30000 --only-failures",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.types.json",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "devDependencies": {
+    "@clack/prompts": "1.0.0-alpha.1",
+    "@effect/platform-node": "catalog:",
+    "@opencode-ai/http-recorder": "workspace:*",
+    "@tsconfig/bun": "catalog:",
+    "@types/bun": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:"
+  },
+  "dependencies": {
+    "@smithy/eventstream-codec": "4.2.14",
+    "@smithy/util-utf8": "4.2.2",
+    "@opencode-ai/schema": "workspace:*",
+    "aws4fetch": "1.0.20",
+    "effect": "catalog:",
+    "google-auth-library": "10.5.0"
+  }
+}

packages/ai/script/publish.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+import { Script } from "@opencode-ai/script"
+import { $ } from "bun"
+import { fileURLToPath } from "url"
+
+const dir = fileURLToPath(new URL("..", import.meta.url))
+process.chdir(dir)
+
+async function published(name: string, version: string) {
+  return (await $`npm view ${name}@${version} version`.nothrow()).exitCode === 0
+}
+
+await $`bun run build`
+const originalText = await Bun.file("package.json").text()
+const pkg = JSON.parse(originalText) as {
+  name: string
+  version: string
+  exports: Record<string, string>
+}
+if (await published(pkg.name, pkg.version)) {
+  console.log(`already published ${pkg.name}@${pkg.version}`)
+} else {
+  for (const [key, value] of Object.entries(pkg.exports)) {
+    const file = value.replace("./src/", "./dist/").replace(".ts", "")
+    // @ts-ignore
+    pkg.exports[key] = {
+      import: file + ".js",
+      types: file + ".d.ts",
+    }
+  }
+  await Bun.write("package.json", JSON.stringify(pkg, null, 2))
+  try {
+    await $`bun pm pack`
+    await $`npm publish *.tgz --tag ${Script.channel} --access public`
+  } finally {
+    await Bun.write("package.json", originalText)
+  }
+}

packages/ai/script/setup-recording-env.ts

@@ -161,6 +161,18 @@ const PROVIDERS: ReadonlyArray<Provider> = [
     vars: [{ name: "TOGETHER_AI_API_KEY" }],
     validate: (env) => validateBearer("https://api.together.xyz/v1/models", Redacted.make(env.TOGETHER_AI_API_KEY)),
   },
+  {
+    id: "minimax",
+    label: "MiniMax",
+    tier: "compatible",
+    note: "Anthropic-compatible Messages text/tool recorded tests",
+    vars: [{ name: "MINIMAX_API_KEY" }],
+    validate: (env) =>
+      HttpClientRequest.get("https://api.minimax.io/anthropic/v1/models").pipe(
+        HttpClientRequest.setHeader("x-api-key", Redacted.value(Redacted.make(env.MINIMAX_API_KEY))),
+        executeRequest,
+      ),
+  },
   {
     id: "mistral",
     label: "Mistral",

packages/ai/src/image-client.ts

@@ -0,0 +1,38 @@
+import { Context, Effect, Layer } from "effect"
+import { RequestExecutor } from "./route/executor"
+import type { ImageOptions, ImageRequest, ImageRequestFor, ImageResponse } from "./image"
+import type { LLMError } from "./schema"
+
+export type Execute = RequestExecutor.Interface["execute"]
+
+export interface Interface {
+  readonly generate: <Options extends ImageOptions>(
+    request: ImageRequestFor<Options>,
+  ) => Effect.Effect<ImageResponse, LLMError>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/ImageClient") {}
+
+export const generate = <Options extends ImageOptions>(
+  request: ImageRequestFor<Options>,
+): Effect.Effect<ImageResponse, LLMError> =>
+  Effect.gen(function* () {
+    const client = yield* Service
+    return yield* client.generate(request)
+  }) as Effect.Effect<ImageResponse, LLMError>
+
+export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const executor = yield* RequestExecutor.Service
+    return Service.of({
+      generate: (request) => request.model.route.generate(request, executor.execute),
+    })
+  }),
+)
+
+export const ImageClient = {
+  Service,
+  layer,
+  generate,
+} as const

packages/ai/src/image.ts

@@ -0,0 +1,166 @@
+import { Effect, Schema } from "effect"
+import { HttpOptions, InvalidRequestReason, LLMError, ModelID, ProviderID, ProviderMetadata, Usage } from "./schema"
+import { ImageClient, Service, type Execute as ImageExecute } from "./image-client"
+
+export interface ImageRoute<Options extends ImageOptions = ImageOptions> {
+  readonly id: string
+  readonly generate: (
+    request: ImageRequestFor<Options>,
+    execute: ImageExecute,
+  ) => Effect.Effect<ImageResponse, LLMError>
+}
+
+export type ImageOptions = Record<string, unknown>
+
+export class ImageModel<Options extends ImageOptions = ImageOptions> {
+  declare protected readonly _Options: (options: Options) => Options
+  readonly id: ModelID
+  readonly provider: ProviderID
+  readonly route: ImageRoute<Options>
+  readonly http?: HttpOptions
+
+  constructor(input: ImageModel.Input<Options>) {
+    this.id = input.id
+    this.provider = input.provider
+    this.route = input.route
+    this.http = input.http
+  }
+
+  static make<Options extends ImageOptions = ImageOptions>(input: ImageModel.MakeInput<Options>) {
+    return new ImageModel<Options>({
+      id: ModelID.make(input.id),
+      provider: ProviderID.make(input.provider),
+      route: input.route,
+      http: input.http,
+    })
+  }
+}
+
+export namespace ImageModel {
+  export interface Input<Options extends ImageOptions = ImageOptions> {
+    readonly id: ModelID
+    readonly provider: ProviderID
+    readonly route: ImageRoute<Options>
+    readonly http?: HttpOptions
+  }
+
+  export interface MakeInput<Options extends ImageOptions = ImageOptions>
+    extends Omit<Input<Options>, "id" | "provider"> {
+    readonly id: string | ModelID
+    readonly provider: string | ProviderID
+  }
+}
+
+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,
+})
+
+export const ImageInputSchema = Schema.Union([
+  ImageBytesInput,
+  ImageUrlInput,
+  ImageFileIDInput,
+  ImageFileURIInput,
+]).pipe(Schema.toTaggedUnion("type"))
+export type ImageInput = Schema.Schema.Type<typeof ImageInputSchema>
+
+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 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)),
+  http: Schema.optional(HttpOptions),
+}) {
+  declare protected readonly _ImageRequest: void
+}
+
+export type ImageRequestFor<Options extends ImageOptions = ImageOptions> = Omit<ImageRequest, "model" | "options"> & {
+  readonly model: ImageModel<Options>
+  readonly options?: Options
+}
+
+export type ImageModelOptions<Model> = Model extends ImageModel<infer Options> ? Options : never
+
+export type ImageRequestInput<Model extends object = ImageModel> = Omit<
+  ConstructorParameters<typeof ImageRequest>[0],
+  "model" | "options" | "http"
+> & {
+  readonly model: Model
+  readonly options?: 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),
+}) {}
+
+export class ImageResponse extends Schema.Class<ImageResponse>("Image.Response")({
+  images: Schema.Array(GeneratedImage),
+  usage: Schema.optional(Usage),
+  providerMetadata: Schema.optional(ProviderMetadata),
+}) {
+  get image() {
+    return this.images[0]
+  }
+}
+
+export function request<const Model extends object>(
+  input: ImageRequestInput<Model>,
+): ImageRequestFor<ImageModelOptions<Model>>
+export function request(input: ImageRequest): ImageRequest
+export function request(input: ImageRequest | ImageRequestInput) {
+  if (input instanceof ImageRequest) return input
+  return new ImageRequest({
+    ...input,
+    model: input.model as unknown as ImageModel,
+    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+  })
+}
+
+export function generate<const Model extends object>(
+  input: ImageRequestInput<Model>,
+): Effect.Effect<ImageResponse, LLMError, Service>
+export function generate(input: ImageRequest): Effect.Effect<ImageResponse, LLMError, Service>
+export function generate(input: ImageRequest | ImageRequestInput) {
+  return Effect.try({
+    try: () => (input instanceof ImageRequest ? input : request(input)),
+    catch: (error) =>
+      new LLMError({
+        module: "Image",
+        method: "generate",
+        reason: new InvalidRequestReason({ message: error instanceof Error ? error.message : String(error) }),
+      }),
+  }).pipe(Effect.flatMap((request) => ImageClient.generate(request as unknown as ImageRequestFor<ImageOptions>)))
+}
+
+export const Image = {
+  request,
+  generate,
+} as const

packages/ai/src/index.ts

@@ -1,4 +1,5 @@
 export { LLMClient } from "./route/client"
+export { ImageClient } from "./image-client"
 export { Auth } from "./route/auth"
 export { Provider } from "./provider"
 export { ProviderPackage } from "./provider-package"
@@ -10,6 +11,9 @@ export type {
   Service as LLMClientService,
 } from "./route/client"
 export * from "./schema"
+export { GeneratedImage, ImageInput, ImageInputSchema, ImageModel, ImageRequest, ImageResponse } from "./image"
+export type { ImageModelOptions, ImageOptions, ImageRequestFor, ImageRequestInput, ImageRoute } from "./image"
+export { Image } from "./image"
 export { Tool, ToolFailure, toDefinitions } from "./tool"
 export { ToolRuntime } from "./tool-runtime"
 export type { DispatchResult as ToolDispatchResult, ToolSettlement } from "./tool-runtime"
@@ -18,7 +22,7 @@ export type {
   AnyTool,
   ExecutableTool,
   ExecutableTools,
-  Tool as ToolShape,
+  Definition as ToolShape,
   ToolExecute,
   ToolExecuteContext,
   ToolModelOutputInput,

packages/ai/src/protocols.ts

@@ -0,0 +1 @@
+export * from "./protocols/index"

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

@@ -5,6 +5,7 @@ import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
 import { Protocol } from "../route/protocol"
 import {
+  LLMError,
   LLMEvent,
   Usage,
   type CacheHint,
@@ -19,13 +20,14 @@ import {
   type ToolResultPart,
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
-import { isContextOverflow } from "../provider-error"
+import { classifyProviderFailure } from "../provider-error"
 import * as Cache from "./utils/cache"
 import { Lifecycle } from "./utils/lifecycle"
 import { ToolSchemaProjection } from "./utils/tool-schema"
 import { ToolStream } from "./utils/tool-stream"
 
 const ADAPTER = "anthropic-messages"
+const MEDIA_MIMES = new Set<string>([...ProviderShared.IMAGE_MIMES, ...ProviderShared.PDF_MIMES])
 export const DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
 export const PATH = "/messages"
 
@@ -55,6 +57,17 @@ const AnthropicImageBlock = Schema.Struct({
 })
 type AnthropicImageBlock = Schema.Schema.Type<typeof AnthropicImageBlock>
 
+const AnthropicDocumentBlock = Schema.Struct({
+  type: Schema.tag("document"),
+  source: Schema.Struct({
+    type: Schema.tag("base64"),
+    media_type: Schema.Literal("application/pdf"),
+    data: Schema.String,
+  }),
+  cache_control: Schema.optional(AnthropicCacheControl),
+})
+type AnthropicDocumentBlock = Schema.Schema.Type<typeof AnthropicDocumentBlock>
+
 const AnthropicThinkingBlock = Schema.Struct({
   type: Schema.tag("thinking"),
   thinking: Schema.String,
@@ -100,13 +113,10 @@ const AnthropicServerToolResultBlock = Schema.Struct({
 })
 type AnthropicServerToolResultBlock = Schema.Schema.Type<typeof AnthropicServerToolResultBlock>
 
-// Anthropic accepts either a plain string or an ordered array of text/image
-// blocks inside `tool_result.content`. The array form is required when a tool
-// returns image bytes (screenshot, image search, etc.) so they can be passed
-// to the model as proper image inputs instead of being JSON-stringified into
-// the prompt — which silently inflates context by megabytes and can push the
-// conversation over the model's token limit.
-const AnthropicToolResultContent = Schema.Union([AnthropicTextBlock, AnthropicImageBlock])
+// Anthropic accepts either a plain string or an ordered array of text, image, and
+// document blocks inside `tool_result.content`. The array form keeps media as native
+// model input instead of JSON-stringifying base64 into prompt text.
+const AnthropicToolResultContent = Schema.Union([AnthropicTextBlock, AnthropicImageBlock, AnthropicDocumentBlock])
 
 const AnthropicToolResultBlock = Schema.Struct({
   type: Schema.tag("tool_result"),
@@ -116,7 +126,12 @@ const AnthropicToolResultBlock = Schema.Struct({
   cache_control: Schema.optional(AnthropicCacheControl),
 })
 
-const AnthropicUserBlock = Schema.Union([AnthropicTextBlock, AnthropicImageBlock, AnthropicToolResultBlock])
+const AnthropicUserBlock = Schema.Union([
+  AnthropicTextBlock,
+  AnthropicImageBlock,
+  AnthropicDocumentBlock,
+  AnthropicToolResultBlock,
+])
 type AnthropicUserBlock = Schema.Schema.Type<typeof AnthropicUserBlock>
 const AnthropicAssistantBlock = Schema.Union([
   AnthropicTextBlock,
@@ -181,7 +196,7 @@ const AnthropicBodyFields = {
   thinking: Schema.optional(AnthropicThinking),
   output_config: Schema.optional(AnthropicOutputConfig),
 }
-const AnthropicMessagesBody = Schema.Struct(AnthropicBodyFields)
+export const AnthropicMessagesBody = Schema.Struct(AnthropicBodyFields)
 export type AnthropicMessagesBody = Schema.Schema.Type<typeof AnthropicMessagesBody>
 
 const AnthropicUsage = Schema.Struct({
@@ -318,12 +333,17 @@ const lowerServerToolResult = Effect.fn("AnthropicMessages.lowerServerToolResult
   return { type: wireType, tool_use_id: part.id, content: part.result.value } satisfies AnthropicServerToolResultBlock
 })
 
-const lowerImage = Effect.fn("AnthropicMessages.lowerImage")(function* (part: MediaPart) {
-  const media = yield* ProviderShared.validateMedia(
-    "Anthropic Messages",
-    part,
-    new Set<string>(ProviderShared.IMAGE_MIMES),
-  )
+const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (part: MediaPart) {
+  const media = yield* ProviderShared.validateMedia("Anthropic Messages", part, MEDIA_MIMES)
+  if (media.mime === "application/pdf")
+    return {
+      type: "document" as const,
+      source: {
+        type: "base64" as const,
+        media_type: "application/pdf" as const,
+        data: media.base64,
+      },
+    } satisfies AnthropicDocumentBlock
   return {
     type: "image" as const,
     source: {
@@ -334,25 +354,13 @@ const lowerImage = Effect.fn("AnthropicMessages.lowerImage")(function* (part: Me
   } satisfies AnthropicImageBlock
 })
 
-// Tool results may carry structured text/images. Keep media as provider-native
+// Tool results may carry structured text, images, and documents. Keep media as provider-native
 // content instead of JSON-stringifying base64 into a prompt string.
 const lowerToolResultContentItem = Effect.fn("AnthropicMessages.lowerToolResultContentItem")(function* (
   item: ToolContent,
 ) {
   if (item.type === "text") return { type: "text" as const, text: item.text } satisfies AnthropicTextBlock
-  const media = yield* ProviderShared.validateToolFile(
-    "Anthropic Messages",
-    item,
-    new Set<string>(ProviderShared.IMAGE_MIMES),
-  )
-  return {
-    type: "image" as const,
-    source: {
-      type: "base64" as const,
-      media_type: media.mime,
-      data: media.base64,
-    },
-  } satisfies AnthropicImageBlock
+  return yield* lowerMedia({ type: "media", mediaType: item.mime, data: item.uri, filename: item.name })
 })
 
 const lowerToolResultContent = Effect.fn("AnthropicMessages.lowerToolResultContent")(function* (part: ToolResultPart) {
@@ -444,7 +452,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
           continue
         }
         if (part.type === "media") {
-          content.push(yield* lowerImage(part))
+          content.push(yield* lowerMedia(part))
           continue
         }
         return yield* ProviderShared.unsupportedContent("Anthropic Messages", "user", ["text", "media"])
@@ -702,7 +710,14 @@ const onContentBlockStart = (state: ParserState, event: AnthropicEvent): StepRes
           providerExecuted: block.type === "server_tool_use",
         }),
       },
-      [...events, LLMEvent.toolInputStart({ id: block.id ?? String(event.index), name: block.name ?? "" })],
+      [
+        ...events,
+        LLMEvent.toolInputStart({
+          id: block.id ?? String(event.index),
+          name: block.name ?? "",
+          providerExecuted: block.type === "server_tool_use" ? true : undefined,
+        }),
+      ],
     ]
   }
 
@@ -832,15 +847,12 @@ const providerErrorMessage = (event: AnthropicEvent): string => {
   return message || type || "Anthropic Messages stream error"
 }
 
-const onError = (state: ParserState, event: AnthropicEvent): StepResult => [
-  state,
-  [
-    LLMEvent.providerError({
-      message: providerErrorMessage(event),
-      classification: isContextOverflow(event.error?.message ?? "") ? "context-overflow" : undefined,
-    }),
-  ],
-]
+const onError = (event: AnthropicEvent) =>
+  new LLMError({
+    module: ADAPTER,
+    method: "stream",
+    reason: classifyProviderFailure({ message: providerErrorMessage(event), code: event.error?.type }),
+  })
 
 const step = (state: ParserState, event: AnthropicEvent) => {
   if (event.type === "message_start") return Effect.succeed(onMessageStart(state, event))
@@ -848,7 +860,7 @@ const step = (state: ParserState, event: AnthropicEvent) => {
   if (event.type === "content_block_delta") return onContentBlockDelta(state, event)
   if (event.type === "content_block_stop") return onContentBlockStop(state, event)
   if (event.type === "message_delta") return Effect.succeed(onMessageDelta(state, event))
-  if (event.type === "error") return Effect.succeed(onError(state, event))
+  if (event.type === "error") return onError(event)
   return Effect.succeed<StepResult>([state, NO_EVENTS])
 }
 

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

@@ -3,6 +3,7 @@ import { Route } from "../route/client"
 import { Endpoint } from "../route/endpoint"
 import { Protocol } from "../route/protocol"
 import {
+  LLMError,
   LLMEvent,
   Usage,
   type CacheHint,
@@ -17,7 +18,7 @@ import {
   type ToolResultPart,
 } from "../schema"
 import { BedrockEventStream } from "./bedrock-event-stream"
-import { isContextOverflow } from "../provider-error"
+import { classifyProviderFailure } from "../provider-error"
 import { JsonObject, optionalArray, ProviderShared } from "./shared"
 import { BedrockAuth } from "./utils/bedrock-auth"
 import { BedrockCache } from "./utils/bedrock-cache"
@@ -51,6 +52,7 @@ const BedrockToolResultContentItem = Schema.Union([
   Schema.Struct({ text: Schema.String }),
   Schema.Struct({ json: Schema.Unknown }),
   BedrockMedia.ImageBlock,
+  BedrockMedia.DocumentBlock,
 ])
 
 const BedrockToolResultBlock = Schema.Struct({
@@ -282,8 +284,6 @@ const lowerToolResultContent = Effect.fn("BedrockConverse.lowerToolResultContent
       data: item.uri,
       filename: item.name,
     })
-    if (!("image" in media))
-      return yield* ProviderShared.invalidRequest("Bedrock Converse only supports image media in tool results")
     content.push(media)
   }
   return content
@@ -560,7 +560,9 @@ const step = (state: ParserState, event: BedrockEvent) =>
       return [
         {
           ...state,
-          hasToolCalls: resultEvents.some(LLMEvent.is.toolCall) ? true : state.hasToolCalls,
+          hasToolCalls:
+            resultEvents.some((event) => LLMEvent.is.toolCall(event) || LLMEvent.is.toolInputError(event)) ||
+            state.hasToolCalls,
           lifecycle,
           tools: result.tools,
           reasoningSignatures: Object.fromEntries(
@@ -586,27 +588,24 @@ const step = (state: ParserState, event: BedrockEvent) =>
       return [{ ...state, pendingFinish: { reason: state.pendingFinish?.reason ?? "stop", usage } }, []] as const
     }
 
-    if (event.internalServerException || event.modelStreamErrorException || event.serviceUnavailableException) {
-      const message =
-        event.internalServerException?.message ??
-        event.modelStreamErrorException?.message ??
-        event.serviceUnavailableException?.message ??
-        "Bedrock Converse stream error"
-      return [state, [LLMEvent.providerError({ message })]] as const
-    }
-
-    if (event.validationException || event.throttlingException) {
-      const message =
-        event.validationException?.message ?? event.throttlingException?.message ?? "Bedrock Converse error"
-      return [
-        state,
-        [
-          LLMEvent.providerError({
-            message,
-            classification: event.validationException && isContextOverflow(message) ? "context-overflow" : undefined,
-          }),
-        ],
+    const exception = (
+      [
+        ["internalServerException", event.internalServerException],
+        ["modelStreamErrorException", event.modelStreamErrorException],
+        ["serviceUnavailableException", event.serviceUnavailableException],
+        ["throttlingException", event.throttlingException],
+        ["validationException", event.validationException],
       ] as const
+    ).find((entry) => entry[1] !== undefined)
+    if (exception) {
+      return yield* new LLMError({
+        module: ADAPTER,
+        method: "stream",
+        reason: classifyProviderFailure({
+          message: exception[1]?.message ?? "Bedrock Converse stream error",
+          code: exception[0],
+        }),
+      })
     }
 
     return [state, []] as const

packages/ai/src/protocols/bedrock-event-stream.ts

@@ -1,7 +1,7 @@
 import { EventStreamCodec } from "@smithy/eventstream-codec"
 import { fromUtf8, toUtf8 } from "@smithy/util-utf8"
 import { Effect, Stream } from "effect"
-import type { Framing } from "../route/framing"
+import { Framing } from "../route/framing"
 import { ProviderShared } from "./shared"
 
 // Bedrock streams responses using the AWS event stream binary protocol — each
@@ -79,7 +79,7 @@ const consumeFrames = (route: string) => (state: FrameBufferState, chunk: Uint8A
  * under its `:event-type` header so the chunk schema can match the JSON
  * payload directly.
  */
-export const framing = (route: string): Framing<object> => ({
+export const framing = (route: string): Framing.Definition<object> => ({
   id: "aws-event-stream",
   frame: (bytes) => bytes.pipe(Stream.mapAccumEffect(() => initialFrameBuffer, consumeFrames(route))),
 })

packages/ai/src/protocols/gemini.ts

@@ -41,9 +41,11 @@ const GeminiInlineDataPart = Schema.Struct({
     data: Schema.String,
   }),
 })
+type GeminiInlineDataPart = Schema.Schema.Type<typeof GeminiInlineDataPart>
 
 const GeminiFunctionCallPart = Schema.Struct({
   functionCall: Schema.Struct({
+    id: Schema.optional(Schema.String),
     name: Schema.String,
     args: Schema.Unknown,
   }),
@@ -52,8 +54,10 @@ const GeminiFunctionCallPart = Schema.Struct({
 
 const GeminiFunctionResponsePart = Schema.Struct({
   functionResponse: Schema.Struct({
+    id: Schema.optional(Schema.String),
     name: Schema.String,
     response: Schema.Unknown,
+    parts: Schema.optional(Schema.Array(GeminiInlineDataPart)),
   }),
 })
 
@@ -197,8 +201,13 @@ const thoughtSignature = (providerMetadata: ProviderMetadata | undefined) => {
     : undefined
 }
 
+const functionCallId = (providerMetadata: ProviderMetadata | undefined) => {
+  const google = providerMetadata?.google
+  return ProviderShared.isRecord(google) && typeof google.functionCallId === "string" ? google.functionCallId : undefined
+}
+
 const lowerToolCall = (part: ToolCallPart) => ({
-  functionCall: { name: part.name, args: part.input },
+  functionCall: { id: functionCallId(part.providerMetadata), name: part.name, args: part.input },
   thoughtSignature: thoughtSignature(part.providerMetadata),
 })
 
@@ -255,6 +264,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       if (part.result.type !== "content") {
         parts.push({
           functionResponse: {
+            id: functionCallId(part.providerMetadata),
             name: part.name,
             response: {
               name: part.name,
@@ -266,20 +276,23 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       }
       const content: ReadonlyArray<ToolContent> = part.result.value
       const text = content.filter((item) => item.type === "text").map((item) => item.text)
+      const media: GeminiInlineDataPart[] = []
+      for (const item of content) {
+        if (item.type === "text") continue
+        const value = yield* ProviderShared.validateToolFile("Gemini", item, MEDIA_MIMES)
+        media.push({ inlineData: { mimeType: value.mime, data: value.base64 } })
+      }
       parts.push({
         functionResponse: {
+          id: functionCallId(part.providerMetadata),
           name: part.name,
           response: {
             name: part.name,
             content: text.join("\n"),
           },
+          parts: media.length > 0 ? media : undefined,
         },
       })
-      for (const item of content) {
-        if (item.type === "text") continue
-        const media = yield* ProviderShared.validateToolFile("Gemini", item, MEDIA_MIMES)
-        parts.push({ inlineData: { mimeType: media.mime, data: media.base64 } })
-      }
     }
     contents.push({ role: "user", parts })
   }
@@ -441,6 +454,10 @@ const step = (state: ParserState, event: GeminiEvent) => {
     if ("functionCall" in part) {
       const input = part.functionCall.args
       const id = `tool_${nextToolCallId++}`
+      const metadata = {
+        ...(part.functionCall.id === undefined ? {} : { functionCallId: part.functionCall.id }),
+        ...(part.thoughtSignature === undefined ? {} : { thoughtSignature: part.thoughtSignature }),
+      }
       lifecycle = Lifecycle.reasoningEnd(
         lifecycle,
         events,
@@ -453,9 +470,7 @@ const step = (state: ParserState, event: GeminiEvent) => {
           id,
           name: part.functionCall.name,
           input,
-          providerMetadata: part.thoughtSignature
-            ? googleMetadata({ thoughtSignature: part.thoughtSignature })
-            : undefined,
+          providerMetadata: Object.keys(metadata).length > 0 ? googleMetadata(metadata) : undefined,
         }),
       )
       hasToolCalls = true

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

@@ -0,0 +1,314 @@
+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"
+import { Auth, type Definition as AuthDefinition } from "../route/auth"
+import {
+  InvalidProviderOutputReason,
+  LLMError,
+  Usage,
+  mergeHttpOptions,
+  mergeJsonRecords,
+  type HttpOptions,
+  type ProviderMetadata,
+} from "../schema"
+import { ProviderShared } from "./shared"
+import { ImageInputs } from "./utils/image-input"
+
+const ADAPTER = "google-images"
+export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+
+export type GoogleImageString<Known extends string> = Known | (string & {})
+
+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>
+}
+
+const GoogleUsage = Schema.StructWithRest(
+  Schema.Struct({
+    cachedContentTokenCount: Schema.optional(Schema.Number),
+    thoughtsTokenCount: Schema.optional(Schema.Number),
+    promptTokenCount: Schema.optional(Schema.Number),
+    candidatesTokenCount: Schema.optional(Schema.Number),
+    totalTokenCount: Schema.optional(Schema.Number),
+    promptTokensDetails: Schema.optional(Schema.Unknown),
+    candidatesTokensDetails: Schema.optional(Schema.Unknown),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+)
+
+const GoogleImageResponse = Schema.Struct({
+  candidates: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        index: Schema.optional(Schema.Number),
+        content: Schema.optional(
+          Schema.Struct({
+            parts: Schema.Array(
+              Schema.Struct({
+                text: Schema.optional(Schema.String),
+                thought: Schema.optional(Schema.Boolean),
+                thoughtSignature: Schema.optional(Schema.String),
+                inlineData: Schema.optional(
+                  Schema.Struct({
+                    mimeType: Schema.String,
+                    data: Schema.String,
+                  }),
+                ),
+              }),
+            ),
+          }),
+        ),
+        finishReason: Schema.optional(Schema.String),
+        finishMessage: Schema.optional(Schema.String),
+        safetyRatings: Schema.optional(Schema.Unknown),
+        citationMetadata: Schema.optional(Schema.Unknown),
+        groundingMetadata: Schema.optional(Schema.Unknown),
+      }),
+    ),
+  ),
+  usageMetadata: Schema.optional(GoogleUsage),
+  modelVersion: Schema.optional(Schema.String),
+  responseId: Schema.optional(Schema.String),
+  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
+}
+
+const nativeOptions = (options: GoogleImageOptions | undefined) => {
+  const { aspectRatio, imageSize, seed, thinkingLevel, includeThoughts, ...native } = options ?? {}
+  const image = {
+    aspectRatio,
+    imageSize,
+  }
+  const thinkingConfig = {
+    thinkingLevel,
+    includeThoughts,
+  }
+  return (
+    mergeJsonRecords(
+      {
+        responseModalities: ["IMAGE"],
+        imageConfig: Object.values(image).some((value) => value !== undefined) ? image : undefined,
+        seed,
+        thinkingConfig: Object.values(thinkingConfig).some((value) => value !== undefined) ? thinkingConfig : undefined,
+      },
+      native,
+    ) ?? { responseModalities: ["IMAGE"] }
+  )
+}
+
+const invalidOutput = (message: string, providerMetadata?: ProviderMetadata) =>
+  new LLMError({
+    module: ADAPTER,
+    method: "generate",
+    reason: new InvalidProviderOutputReason({ message, route: ADAPTER, providerMetadata }),
+  })
+
+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 payload = yield* response.json.pipe(
+        Effect.mapError(() => invalidOutput("Failed to read the Google Images response")),
+      )
+      const decoded = yield* Schema.decodeUnknownEffect(GoogleImageResponse)(payload).pipe(
+        Effect.mapError(() => invalidOutput("Google Images returned an invalid response")),
+      )
+      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(() =>
+            invalidOutput(
+              `Google Images candidate ${item.candidateIndex} part ${item.partIndex} contains invalid base64 data`,
+            ),
+          ),
+          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* invalidOutput(
+          `Google Images returned no final images${
+            finishReasons.length === 0 ? "" : ` (finish reasons: ${finishReasons.join(", ")})`
+          }; inspect reason.providerMetadata.google for prompt feedback and candidate details`,
+          {
+            google: {
+              promptFeedback: decoded.promptFeedback,
+              candidates: candidateMetadata,
+            },
+          },
+        )
+      }
+      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>, LLMError> => {
+  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, ADAPTER).pipe(
+      Effect.flatMap((decoded) => {
+        if (decoded === undefined)
+          return Effect.fail(
+            ImageInputs.invalid(
+              ADAPTER,
+              "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) },
+        })
+      }),
+    )
+  return Effect.fail(
+    ImageInputs.invalid(ADAPTER, "Google generateContent requires Gemini file URIs rather than provider file IDs"),
+  )
+}
+
+export const GoogleImages = {
+  model,
+} as const

packages/ai/src/protocols/index.ts

@@ -2,5 +2,7 @@ export * as AnthropicMessages from "./anthropic-messages"
 export * as BedrockConverse from "./bedrock-converse"
 export * as Gemini from "./gemini"
 export * as OpenAIChat from "./openai-chat"
+export * as OpenAIImages from "./openai-images"
 export * as OpenAICompatibleChat from "./openai-compatible-chat"
+export * as OpenAICompatibleResponses from "./openai-compatible-responses"
 export * as OpenAIResponses from "./openai-responses"

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

@@ -25,6 +25,7 @@ import { ToolStream } from "./utils/tool-stream"
 
 const ADAPTER = "openai-chat"
 const IMAGE_MIMES = new Set<string>(ProviderShared.IMAGE_MIMES)
+const RESERVED_REASONING_FIELDS = new Set(["role", "content", "tool_calls"])
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/chat/completions"
 
@@ -70,12 +71,18 @@ const OpenAIChatMessage = Schema.Union([
     role: Schema.Literal("user"),
     content: Schema.Union([Schema.String, Schema.Array(OpenAIChatUserContent)]),
   }),
-  Schema.Struct({
-    role: Schema.Literal("assistant"),
-    content: Schema.NullOr(Schema.String),
-    tool_calls: optionalArray(OpenAIChatAssistantToolCall),
-    reasoning_content: Schema.optional(Schema.String),
-  }),
+  Schema.StructWithRest(
+    Schema.Struct({
+      role: Schema.Literal("assistant"),
+      content: Schema.NullOr(Schema.String),
+      tool_calls: optionalArray(OpenAIChatAssistantToolCall),
+      reasoning_content: Schema.optional(Schema.String),
+      reasoning: Schema.optional(Schema.String),
+      reasoning_text: Schema.optional(Schema.String),
+      reasoning_details: Schema.optional(Schema.Unknown),
+    }),
+    [Schema.Record(Schema.String, Schema.Unknown)],
+  ),
   Schema.Struct({ role: Schema.Literal("tool"), tool_call_id: Schema.String, content: Schema.String }),
 ]).pipe(Schema.toTaggedUnion("role"))
 type OpenAIChatMessage = Schema.Schema.Type<typeof OpenAIChatMessage>
@@ -142,11 +149,17 @@ const OpenAIChatToolCallDelta = Schema.Struct({
 })
 type OpenAIChatToolCallDelta = Schema.Schema.Type<typeof OpenAIChatToolCallDelta>
 
-const OpenAIChatDelta = Schema.Struct({
-  content: optionalNull(Schema.String),
-  reasoning_content: optionalNull(Schema.String),
-  tool_calls: optionalNull(Schema.Array(OpenAIChatToolCallDelta)),
-})
+const OpenAIChatDelta = Schema.StructWithRest(
+  Schema.Struct({
+    content: optionalNull(Schema.String),
+    reasoning_content: optionalNull(Schema.String),
+    reasoning: optionalNull(Schema.String),
+    reasoning_text: optionalNull(Schema.String),
+    reasoning_details: optionalNull(Schema.Unknown),
+    tool_calls: optionalNull(Schema.Array(OpenAIChatToolCallDelta)),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+)
 
 const OpenAIChatChoice = Schema.Struct({
   delta: optionalNull(OpenAIChatDelta),
@@ -160,12 +173,23 @@ export const OpenAIChatEvent = Schema.Struct({
 export type OpenAIChatEvent = Schema.Schema.Type<typeof OpenAIChatEvent>
 type OpenAIChatRequestMessage = LLMRequest["messages"][number]
 
-interface ParserState {
+interface PendingToolDelta {
+  readonly id?: string
+  readonly name?: string
+  readonly input: string
+}
+
+export interface ParserState {
   readonly tools: ToolStream.State<number>
+  readonly pendingTools: Partial<Record<number, PendingToolDelta>>
   readonly toolCallEvents: ReadonlyArray<LLMEvent>
   readonly usage?: Usage
   readonly finishReason?: FinishReason
   readonly lifecycle: Lifecycle.State
+  readonly reasoningField?: string
+  readonly reasoningDetails: Array<unknown>
+  readonly reasoningDetailsObserved: boolean
+  readonly reasoningEmitted: boolean
 }
 
 // =============================================================================
@@ -208,6 +232,20 @@ const lowerMedia = Effect.fn("OpenAIChat.lowerMedia")(function* (part: MediaPart
 const openAICompatibleReasoningContent = (native: unknown) =>
   isRecord(native) && typeof native.reasoning_content === "string" ? native.reasoning_content : undefined
 
+const reasoningField = (part: ReasoningPart) => {
+  const field = part.providerMetadata?.openai?.reasoningField
+  return typeof field === "string" ? field : undefined
+}
+
+const reasoningDetails = (parts: ReadonlyArray<ReasoningPart>, native: unknown) => {
+  const observed = parts.flatMap((part) => {
+    const details = part.providerMetadata?.openai?.reasoningDetails
+    return Array.isArray(details) ? details : []
+  })
+  if (parts.some((part) => Array.isArray(part.providerMetadata?.openai?.reasoningDetails))) return observed
+  if (isRecord(native) && Array.isArray(native.reasoning_details)) return native.reasoning_details
+}
+
 const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (message: OpenAIChatRequestMessage) {
   const content: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   for (const part of message.content) {
@@ -228,6 +266,7 @@ const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (mes
 
 const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(function* (
   message: OpenAIChatRequestMessage,
+  configuredField?: string,
 ) {
   const content: TextPart[] = []
   const reasoning: ReasoningPart[] = []
@@ -248,15 +287,31 @@ const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(func
       continue
     }
   }
-  return {
+  const text = reasoning.map((part) => part.text).join("")
+  const details = reasoningDetails(reasoning, message.native?.openaiCompatible)
+  const observedField = reasoning.map(reasoningField).find((value) => value !== undefined)
+  const nativeReasoning = openAICompatibleReasoningContent(message.native?.openaiCompatible)
+  const fullyStructured = reasoning.every((part) => Array.isArray(part.providerMetadata?.openai?.reasoningDetails))
+  const field = (() => {
+    if (configuredField !== undefined) return configuredField
+    if (reasoning.length === 0) return undefined
+    if (observedField !== undefined) return observedField
+    if (nativeReasoning !== undefined) return "reasoning_content"
+    if (!fullyStructured) return "reasoning_content"
+  })()
+  const reasoningText = (() => {
+    if (configuredField !== undefined) return reasoning.length === 0 ? (nativeReasoning ?? "") : text
+    if (reasoning.length === 0) return nativeReasoning
+    return text
+  })()
+  const result = {
     role: "assistant" as const,
     content: content.length === 0 ? null : ProviderShared.joinText(content),
     tool_calls: toolCalls.length === 0 ? undefined : toolCalls,
-    reasoning_content:
-      reasoning.length > 0
-        ? reasoning.map((part) => part.text).join("")
-        : openAICompatibleReasoningContent(message.native?.openaiCompatible),
+    reasoning_details: details,
   }
+  if (field === undefined || reasoningText === undefined) return result
+  return { ...result, [field]: reasoningText }
 })
 
 const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (message: OpenAIChatRequestMessage) {
@@ -282,9 +337,12 @@ const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (m
   return { messages, images }
 })
 
-const lowerMessage = Effect.fn("OpenAIChat.lowerMessage")(function* (message: OpenAIChatRequestMessage) {
+const lowerMessage = Effect.fn("OpenAIChat.lowerMessage")(function* (
+  message: OpenAIChatRequestMessage,
+  reasoningField?: string,
+) {
   if (message.role === "user") return [yield* lowerUserMessage(message)]
-  if (message.role === "assistant") return [yield* lowerAssistantMessage(message)]
+  if (message.role === "assistant") return [yield* lowerAssistantMessage(message, reasoningField)]
   return (yield* lowerToolMessages(message)).messages
 })
 
@@ -322,7 +380,7 @@ const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request:
       continue
     }
     flushImages()
-    messages.push(...(yield* lowerMessage(message)))
+    messages.push(...(yield* lowerMessage(message, request.model.compatibility?.reasoningField)))
   }
   flushImages()
   return messages
@@ -340,6 +398,11 @@ const lowerOptions = Effect.fn("OpenAIChat.lowerOptions")(function* (request: LL
 const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (request: LLMRequest) {
   // `fromRequest` returns the provider body only. Endpoint, auth, framing,
   // validation, and HTTP execution are composed by `Route.make`.
+  const reasoningField = request.model.compatibility?.reasoningField
+  if (reasoningField && RESERVED_REASONING_FIELDS.has(reasoningField))
+    return yield* ProviderShared.invalidRequest(
+      `OpenAI Chat reasoning field conflicts with reserved field ${reasoningField}`,
+    )
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   return {
@@ -400,6 +463,73 @@ const mapUsage = (usage: OpenAIChatEvent["usage"]): Usage | undefined => {
   })
 }
 
+const reasoningDelta = (
+  delta: Schema.Schema.Type<typeof OpenAIChatDelta> | null | undefined,
+  configuredField?: string,
+) => {
+  if (!delta) return undefined
+  const fields = new Set([configuredField, "reasoning_content", "reasoning", "reasoning_text"])
+  for (const field of fields) {
+    if (field === undefined) continue
+    const text = delta[field]
+    if (typeof text === "string" && text.length > 0) return { field, text }
+  }
+  return undefined
+}
+
+const detailText = (details: ReadonlyArray<unknown>) => {
+  const text = details.flatMap((detail) => {
+    if (!isRecord(detail)) return []
+    if (detail.type === "reasoning.text" && typeof detail.text === "string" && detail.text) return [detail.text]
+    if (detail.type === "reasoning.summary" && typeof detail.summary === "string" && detail.summary)
+      return [detail.summary]
+    return []
+  })
+  if (text.length > 0) return text.join("")
+}
+
+const appendReasoningDetails = (result: Array<unknown>, details: ReadonlyArray<unknown>) => {
+  for (const detail of details) {
+    const previous = result.at(-1)
+    if (
+      !isRecord(previous) ||
+      previous.type !== "reasoning.text" ||
+      !isRecord(detail) ||
+      detail.type !== "reasoning.text" ||
+      conflictingReasoningTextDetails(previous, detail)
+    ) {
+      result.push(detail)
+      continue
+    }
+    result[result.length - 1] = {
+      ...previous,
+      ...Object.fromEntries(Object.entries(detail).filter((entry) => entry[1] !== undefined)),
+      text: `${typeof previous.text === "string" ? previous.text : ""}${typeof detail.text === "string" ? detail.text : ""}`,
+      signature: mergeDetailValue(previous.signature, detail.signature),
+      format: mergeDetailValue(previous.format, detail.format),
+    }
+  }
+}
+
+const mergeDetailValue = (previous: unknown, current: unknown) =>
+  previous || current || (previous !== undefined ? previous : current)
+
+const conflictingReasoningTextDetails = (previous: Record<string, unknown>, current: Record<string, unknown>) =>
+  conflictingDetailValue(previous.id, current.id) ||
+  conflictingDetailValue(previous.index, current.index) ||
+  conflictingDetailValue(previous.format, current.format) ||
+  (Boolean(previous.signature) && Boolean(current.signature) && previous.signature !== current.signature)
+
+const conflictingDetailValue = (previous: unknown, current: unknown) =>
+  previous !== undefined && previous !== null && current !== undefined && current !== null && previous !== current
+
+const reasoningMetadata = (field: ParserState["reasoningField"], details?: ReadonlyArray<unknown>) => ({
+  openai: {
+    ...(field ? { reasoningField: field } : {}),
+    ...(details ? { reasoningDetails: details } : {}),
+  },
+})
+
 const step = (state: ParserState, event: OpenAIChatEvent) =>
   Effect.gen(function* () {
     const events: LLMEvent[] = []
@@ -409,25 +539,56 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
     const delta = choice?.delta
     const toolDeltas = delta?.tool_calls ?? []
     let tools = state.tools
+    let pendingTools = state.pendingTools
 
     let lifecycle = state.lifecycle
 
-    if (delta?.reasoning_content)
-      lifecycle = Lifecycle.reasoningDelta(lifecycle, events, "reasoning-0", delta.reasoning_content)
+    const reasoning = reasoningDelta(delta, state.reasoningField)
+    const reasoningField = state.reasoningField ?? (!state.lifecycle.text.has("text-0") ? reasoning?.field : undefined)
+    const detailDelta = Array.isArray(delta?.reasoning_details) ? delta.reasoning_details : undefined
+    if (detailDelta !== undefined) appendReasoningDetails(state.reasoningDetails, detailDelta)
+    const reasoningDetailsObserved = state.reasoningDetailsObserved || detailDelta !== undefined
+    const deltaMetadata = reasoningMetadata(reasoningField)
+    const text = detailDelta?.length ? (detailText(detailDelta) ?? reasoning?.text) : reasoning?.text
+    if (!state.lifecycle.text.has("text-0") && text !== undefined)
+      lifecycle = Lifecycle.reasoningDelta(lifecycle, events, "reasoning-0", text, deltaMetadata)
+    else if (
+      reasoningDetailsObserved &&
+      !lifecycle.reasoning.has("reasoning-0") &&
+      (Boolean(delta?.content) || toolDeltas.length > 0)
+    )
+      lifecycle = Lifecycle.reasoningStart(lifecycle, events, "reasoning-0", deltaMetadata)
+    const reasoningEmitted = state.reasoningEmitted || lifecycle.reasoning.has("reasoning-0")
 
     if (delta?.content) {
-      lifecycle = Lifecycle.reasoningEnd(lifecycle, events, "reasoning-0")
+      lifecycle = Lifecycle.reasoningEnd(
+        lifecycle,
+        events,
+        "reasoning-0",
+        reasoningMetadata(reasoningField, reasoningDetailsObserved ? state.reasoningDetails : undefined),
+      )
       lifecycle = Lifecycle.textDelta(lifecycle, events, "text-0", delta.content)
     }
 
-    if (toolDeltas.length) lifecycle = Lifecycle.reasoningEnd(lifecycle, events, "reasoning-0")
-
     for (const tool of toolDeltas) {
+      const current = tools[tool.index]
+      const pending = pendingTools[tool.index]
+      const id = current?.id ?? pending?.id ?? (tool.id || undefined)
+      const name = current?.name ?? pending?.name ?? (tool.function?.name || undefined)
+      const text = `${pending?.input ?? ""}${tool.function?.arguments ?? ""}`
+      if (!current && (!id || !name)) {
+        pendingTools = { ...pendingTools, [tool.index]: { id: id || undefined, name: name || undefined, input: text } }
+        continue
+      }
+      if (pending) {
+        pendingTools = { ...pendingTools }
+        delete pendingTools[tool.index]
+      }
       const result = ToolStream.appendOrStart(
         ADAPTER,
         tools,
         tool.index,
-        { id: tool.id ?? undefined, name: tool.function?.name ?? undefined, text: tool.function?.arguments ?? "" },
+        { id: id || undefined, name: name || undefined, text },
         "OpenAI Chat tool call delta is missing id or name",
       )
       if (ToolStream.isError(result)) return yield* result
@@ -436,8 +597,11 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
       events.push(...result.events)
     }
 
+    if (finishReason !== undefined && state.finishReason === undefined && Object.keys(pendingTools).length > 0)
+      return yield* ProviderShared.eventError(ADAPTER, "OpenAI Chat tool call delta is missing id or name")
+
     // Finalize accumulated tool inputs eagerly when finish_reason arrives so
-    // JSON parse failures fail the stream at the boundary rather than at halt.
+    // valid calls and malformed local calls settle independently.
     const finished =
       finishReason !== undefined && state.finishReason === undefined && Object.keys(tools).length > 0
         ? yield* ToolStream.finishAll(ADAPTER, tools)
@@ -446,10 +610,15 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
     return [
       {
         tools: finished?.tools ?? tools,
+        pendingTools,
         toolCallEvents: finished?.events ?? state.toolCallEvents,
         usage,
         finishReason,
         lifecycle,
+        reasoningField,
+        reasoningDetails: state.reasoningDetails,
+        reasoningDetailsObserved,
+        reasoningEmitted,
       },
       events,
     ] as const
@@ -459,7 +628,16 @@ const finishEvents = (state: ParserState): ReadonlyArray<LLMEvent> => {
   const events: LLMEvent[] = []
   const hasToolCalls = state.toolCallEvents.length > 0
   const reason = state.finishReason === "stop" && hasToolCalls ? "tool-calls" : state.finishReason
-  const lifecycle = state.toolCallEvents.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
+  const metadata = reasoningMetadata(
+    state.reasoningField,
+    state.reasoningDetailsObserved ? state.reasoningDetails : undefined,
+  )
+  const started =
+    state.reasoningDetailsObserved && !state.reasoningEmitted
+      ? Lifecycle.reasoningStart(state.lifecycle, events, "reasoning-0", reasoningMetadata(state.reasoningField))
+      : state.lifecycle
+  const ended = Lifecycle.reasoningEnd(started, events, "reasoning-0", metadata)
+  const lifecycle = state.toolCallEvents.length ? Lifecycle.stepStart(ended, events) : ended
   events.push(...state.toolCallEvents)
   if (reason) Lifecycle.finish(lifecycle, events, { reason, usage: state.usage })
   return events
@@ -482,7 +660,16 @@ export const protocol = Protocol.make({
   },
   stream: {
     event: Protocol.jsonEvent(OpenAIChatEvent),
-    initial: () => ({ tools: ToolStream.empty<number>(), toolCallEvents: [], lifecycle: Lifecycle.initial() }),
+    initial: (request) => ({
+      tools: ToolStream.empty<number>(),
+      pendingTools: {},
+      toolCallEvents: [],
+      lifecycle: Lifecycle.initial(),
+      reasoningField: request.model.compatibility?.reasoningField,
+      reasoningDetails: [],
+      reasoningDetailsObserved: false,
+      reasoningEmitted: false,
+    }),
     step,
     onHalt: finishEvents,
   },

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

@@ -0,0 +1,23 @@
+import { Route, type RouteRoutedModelInput } from "../route/client"
+import { Endpoint } from "../route/endpoint"
+import { OpenAIResponses } from "./openai-responses"
+
+const ADAPTER = "openai-compatible-responses"
+
+export type OpenAICompatibleResponsesModelInput = RouteRoutedModelInput
+
+/**
+ * Route for providers that expose an OpenAI Responses-compatible `/responses`
+ * endpoint. Provider helpers configure identity, endpoint, and auth before
+ * model selection while this route reuses the OpenAI Responses protocol.
+ */
+export const route = Route.make({
+  id: ADAPTER,
+  providerMetadataKey: "openai",
+  protocol: OpenAIResponses.protocol,
+  endpoint: Endpoint.path(OpenAIResponses.PATH),
+  transport: OpenAIResponses.httpTransport,
+  defaults: { providerOptions: { openai: { store: false } } },
+})
+
+export * as OpenAICompatibleResponses from "./openai-compatible-responses"

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

@@ -0,0 +1,270 @@
+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"
+import { Auth, type Definition as AuthDefinition } from "../route/auth"
+import {
+  InvalidProviderOutputReason,
+  LLMError,
+  Usage,
+  mergeHttpOptions,
+  mergeJsonRecords,
+  type HttpOptions,
+} from "../schema"
+import { ProviderShared } from "./shared"
+import { ImageInputs } from "./utils/image-input"
+import { OpenAIImage } from "./utils/openai-image"
+
+const ADAPTER = "openai-images"
+export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
+export const PATH = "/images/generations"
+export const EDIT_PATH = "/images/edits"
+
+export type OpenAIImageString<Known extends string> = Known | (string & {})
+
+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
+}
+
+const OpenAIImageResponse = Schema.Struct({
+  data: Schema.Array(
+    Schema.Struct({
+      b64_json: Schema.optional(Schema.String),
+      url: Schema.optional(Schema.String),
+      revised_prompt: Schema.optional(Schema.String),
+    }),
+  ),
+  output_format: Schema.optional(Schema.String),
+  usage: Schema.optional(
+    Schema.Struct({
+      input_tokens: Schema.optional(Schema.Number),
+      output_tokens: Schema.optional(Schema.Number),
+      total_tokens: Schema.optional(Schema.Number),
+      input_tokens_details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+      output_tokens_details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+    }),
+  ),
+})
+
+export interface ModelInput {
+  readonly id: string
+  readonly auth: AuthDefinition
+  readonly baseURL?: string
+  readonly headers?: Record<string, string>
+  readonly http?: HttpOptions
+}
+
+const nativeOptions = (options: OpenAIImageOptions | undefined) => {
+  if (!options) return undefined
+  const { mask: _, outputFormat, outputCompression, ...native } = options
+  return {
+    output_format: outputFormat,
+    output_compression: outputCompression,
+    ...native,
+  }
+}
+
+const invalidOutput = (message: string) =>
+  new LLMError({
+    module: ADAPTER,
+    method: "generate",
+    reason: new InvalidProviderOutputReason({ message, route: ADAPTER }),
+  })
+
+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<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(ADAPTER, "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, ADAPTER)
+        return Effect.succeed(undefined)
+      })
+      const multipartMask =
+        mask === undefined
+          ? undefined
+          : mask.type === "bytes"
+            ? { data: mask.data, mediaType: mask.mediaType }
+            : mask.type === "url"
+              ? yield* ImageInputs.decodeDataUrl(mask.url, ADAPTER)
+              : 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)
+
+      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(ADAPTER, "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(ADAPTER, "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 payload = yield* response.json.pipe(
+    Effect.mapError(() => invalidOutput("Failed to read the OpenAI Images response")),
+  )
+  const decoded = yield* Schema.decodeUnknownEffect(OpenAIImageResponse)(payload).pipe(
+    Effect.mapError(() => invalidOutput("OpenAI Images returned an invalid response")),
+  )
+  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(() => invalidOutput(`OpenAI Images result ${index} contains invalid base64 data`)),
+        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(invalidOutput(`OpenAI Images result ${index} has neither image data nor a URL`))
+  })
+  if (images.length === 0) return yield* invalidOutput("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 buffer = new ArrayBuffer(data.byteLength)
+  new Uint8Array(buffer).set(data)
+  return new Blob([buffer], { type: mediaType })
+}
+
+export const OpenAIImages = {
+  model,
+} as const

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

@@ -1,15 +1,17 @@
-import { Effect, Schema } from "effect"
+import { Effect, Encoding, Schema } from "effect"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
 import { HttpTransport, WebSocketTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
+  LLMError,
   LLMEvent,
   Usage,
   type FinishReason,
   type JsonSchema,
   type LLMRequest,
+  type MediaPart,
   type ProviderMetadata,
   type ReasoningPart,
   type TextPart,
@@ -19,13 +21,15 @@ import {
   type ToolResultPart,
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
-import { isContextOverflow } from "../provider-error"
+import { classifyProviderFailure } from "../provider-error"
 import { OpenAIOptions } from "./utils/openai-options"
 import { Lifecycle } from "./utils/lifecycle"
 import { ToolSchemaProjection } from "./utils/tool-schema"
 import { ToolStream } from "./utils/tool-stream"
+import { OpenAIImage } from "./utils/openai-image"
 
 const ADAPTER = "openai-responses"
+const MEDIA_MIMES = new Set<string>([...ProviderShared.IMAGE_MIMES, ...ProviderShared.PDF_MIMES])
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/responses"
 
@@ -40,7 +44,17 @@ const OpenAIResponsesInputImage = Schema.Struct({
   type: Schema.tag("input_image"),
   image_url: Schema.String,
 })
-const OpenAIResponsesInputContent = Schema.Union([OpenAIResponsesInputText, OpenAIResponsesInputImage])
+const OpenAIResponsesInputFile = Schema.Struct({
+  type: Schema.tag("input_file"),
+  filename: Schema.String,
+  file_data: Schema.String,
+  mime_type: Schema.optional(Schema.String),
+})
+const OpenAIResponsesInputContent = Schema.Union([
+  OpenAIResponsesInputText,
+  OpenAIResponsesInputImage,
+  OpenAIResponsesInputFile,
+])
 type OpenAIResponsesInputContent = Schema.Schema.Type<typeof OpenAIResponsesInputContent>
 
 const OpenAIResponsesOutputText = Schema.Struct({
@@ -66,9 +80,13 @@ const OpenAIResponsesItemReference = Schema.Struct({
 })
 
 // `function_call_output.output` accepts either a plain string or an ordered
-// array of content items so tools can return images in addition to text.
+// array of content items so tools can return images and files in addition to text.
 // https://platform.openai.com/docs/api-reference/responses/object
-const OpenAIResponsesFunctionCallOutputContent = Schema.Union([OpenAIResponsesInputText, OpenAIResponsesInputImage])
+const OpenAIResponsesFunctionCallOutputContent = Schema.Union([
+  OpenAIResponsesInputText,
+  OpenAIResponsesInputImage,
+  OpenAIResponsesInputFile,
+])
 
 const OpenAIResponsesFunctionCallOutput = Schema.Union([
   Schema.String,
@@ -112,11 +130,24 @@ const OpenAIResponsesTool = Schema.Struct({
   parameters: JsonObject,
   strict: Schema.optional(Schema.Boolean),
 })
-type OpenAIResponsesTool = Schema.Schema.Type<typeof OpenAIResponsesTool>
+const OpenAIResponsesImageGenerationTool = Schema.Struct({
+  type: Schema.tag("image_generation"),
+  action: Schema.optional(Schema.Literals(["auto", "generate", "edit"])),
+  background: Schema.optional(Schema.Literals(["auto", "opaque", "transparent"])),
+  input_fidelity: Schema.optional(Schema.Literals(["low", "high"])),
+  output_compression: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 }))),
+  output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
+  partial_images: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+  quality: Schema.optional(Schema.Literals(["auto", "low", "medium", "high"])),
+  size: Schema.optional(OpenAIImage.Size),
+})
+const OpenAIResponsesTools = Schema.Union([OpenAIResponsesTool, OpenAIResponsesImageGenerationTool])
+type OpenAIResponsesTool = Schema.Schema.Type<typeof OpenAIResponsesTools>
 
 const OpenAIResponsesToolChoice = Schema.Union([
   Schema.Literals(["auto", "none", "required"]),
   Schema.Struct({ type: Schema.tag("function"), name: Schema.String }),
+  Schema.Struct({ type: Schema.tag("image_generation") }),
 ])
 
 // Fields shared between the HTTP body and the WebSocket `response.create`
@@ -127,7 +158,7 @@ const OpenAIResponsesCoreFields = {
   model: Schema.String,
   input: Schema.Array(OpenAIResponsesInputItem),
   instructions: Schema.optional(Schema.String),
-  tools: optionalArray(OpenAIResponsesTool),
+  tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
   store: Schema.optional(Schema.Boolean),
   service_tier: Schema.optional(OpenAIOptions.OpenAIServiceTier),
@@ -193,6 +224,8 @@ const OpenAIResponsesStreamItem = Schema.Struct({
   outputs: Schema.optional(Schema.Unknown),
   server_label: Schema.optional(Schema.String),
   output: Schema.optional(Schema.Unknown),
+  result: Schema.optional(Schema.String),
+  output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
   error: Schema.optional(Schema.Unknown),
   encrypted_content: optionalNull(Schema.String),
 })
@@ -257,21 +290,41 @@ const invalid = ProviderShared.invalidRequest
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema): OpenAIResponsesTool => ({
-  type: "function",
-  name: tool.name,
-  description: tool.description,
-  parameters: ToolSchemaProjection.openAI(inputSchema),
-  // TODO: Read this from OpenAI-specific tool options so direct LLM callers can opt into strict schemas.
-  strict: false,
+const nativeImageToolInput = (tool: ToolDefinition) => {
+  const native = tool.native?.openai
+  return ProviderShared.isRecord(native) && native.type === "image_generation" ? native : undefined
+}
+
+const nativeImageTool = (tool: ToolDefinition) => {
+  const native = nativeImageToolInput(tool)
+  return Schema.is(OpenAIResponsesImageGenerationTool)(native) ? native : undefined
+}
+
+const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool: ToolDefinition, inputSchema: JsonSchema) {
+  const native = nativeImageToolInput(tool)
+  if (native !== undefined) {
+    if (Schema.is(OpenAIResponsesImageGenerationTool)(native)) return native
+    return yield* invalid("OpenAI Responses image generation tool options are invalid")
+  }
+  return {
+    type: "function" as const,
+    name: tool.name,
+    description: tool.description,
+    parameters: ToolSchemaProjection.openAI(inputSchema),
+    // TODO: Read this from OpenAI-specific tool options so direct LLM callers can opt into strict schemas.
+    strict: false,
+  }
 })
 
-const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
+const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tools: ReadonlyArray<ToolDefinition>) =>
   ProviderShared.matchToolChoice("OpenAI Responses", toolChoice, {
     auto: () => "auto" as const,
     none: () => "none" as const,
     required: () => "required" as const,
-    tool: (name) => ({ type: "function" as const, name }),
+    tool: (name) =>
+      tools.some((tool) => tool.name === name && nativeImageTool(tool) !== undefined)
+        ? ({ type: "image_generation" } as const)
+        : { type: "function" as const, name },
   })
 
 const lowerToolCall = (part: ToolCallPart): OpenAIResponsesInputItem => ({
@@ -306,42 +359,58 @@ const hostedToolItemID = (part: ToolResultPart) => {
     : undefined
 }
 
-const lowerUserContent = Effect.fn("OpenAIResponses.lowerUserContent")(function* (
-  part: LLMRequest["messages"][number]["content"][number],
-) {
-  if (part.type === "text") return { type: "input_text" as const, text: part.text }
-  if (part.type === "media") {
-    const media = yield* ProviderShared.validateMedia(
-      "OpenAI Responses",
-      part,
-      new Set<string>(ProviderShared.IMAGE_MIMES),
-    )
-    return { type: "input_image" as const, image_url: media.dataUrl }
+const lowerMedia = Effect.fn("OpenAIResponses.lowerMedia")(function* (part: MediaPart, provider: string) {
+  const media = yield* ProviderShared.validateMedia("OpenAI Responses", part, MEDIA_MIMES)
+  if (media.mime === "application/pdf") {
+    // xAI models inline bytes and MIME separately; OpenAI uses a data URL in file_data.
+    if (provider === "xai")
+      return {
+        type: "input_file" as const,
+        filename: part.filename ?? "document.pdf",
+        file_data: media.base64,
+        mime_type: media.mime,
+      }
+    return {
+      type: "input_file" as const,
+      filename: part.filename ?? "document.pdf",
+      file_data: media.dataUrl,
+    }
   }
-  return yield* ProviderShared.unsupportedContent("OpenAI Responses", "user", ["text", "media"])
-})
-
-// Tool results may carry structured text/images. Keep media as provider-native
-// content instead of JSON-stringifying base64 into a prompt string.
-const lowerToolResultContentItem = Effect.fn("OpenAIResponses.lowerToolResultContentItem")(function* (
-  item: ToolContent,
-) {
-  if (item.type === "text") return { type: "input_text" as const, text: item.text }
-  const media = yield* ProviderShared.validateToolFile(
-    "OpenAI Responses",
-    item,
-    new Set<string>(ProviderShared.IMAGE_MIMES),
-  )
   return { type: "input_image" as const, image_url: media.dataUrl }
 })
 
-const lowerToolResultOutput = Effect.fn("OpenAIResponses.lowerToolResultOutput")(function* (part: ToolResultPart) {
+const lowerUserContent = Effect.fn("OpenAIResponses.lowerUserContent")(function* (
+  part: LLMRequest["messages"][number]["content"][number],
+  provider: string,
+) {
+  if (part.type === "text") return { type: "input_text" as const, text: part.text }
+  if (part.type === "media") return yield* lowerMedia(part, provider)
+  return yield* ProviderShared.unsupportedContent("OpenAI Responses", "user", ["text", "media"])
+})
+
+// Tool results may carry structured text, images, and files. Keep media as provider-native
+// content instead of JSON-stringifying base64 into a prompt string.
+const lowerToolResultContentItem = Effect.fn("OpenAIResponses.lowerToolResultContentItem")(function* (
+  item: ToolContent,
+  provider: string,
+) {
+  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 },
+    provider,
+  )
+})
+
+const lowerToolResultOutput = Effect.fn("OpenAIResponses.lowerToolResultOutput")(function* (
+  part: ToolResultPart,
+  provider: string,
+) {
   // Text/json/error results are encoded as a plain string for backward
   // compatibility with existing cassettes and provider expectations.
   if (part.result.type !== "content") return ProviderShared.toolResultText(part)
   // Preserve the narrowed array element type when compiled through a consumer package.
   const content: ReadonlyArray<ToolContent> = part.result.value
-  return yield* Effect.forEach(content, lowerToolResultContentItem)
+  return yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, provider))
 })
 
 const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (request: LLMRequest) {
@@ -364,7 +433,10 @@ const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (requ
     }
 
     if (message.role === "user") {
-      input.push({ role: "user", content: yield* Effect.forEach(message.content, lowerUserContent) })
+      input.push({
+        role: "user",
+        content: yield* Effect.forEach(message.content, (part) => lowerUserContent(part, request.model.provider)),
+      })
       continue
     }
 
@@ -419,6 +491,15 @@ const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (requ
           const itemID = hostedToolItemID(part)
           if (store !== false && itemID && !hostedToolReferences.has(itemID))
             input.push({ type: "item_reference", id: itemID })
+          if (store === false && part.name === "image_generation" && part.result.type === "content") {
+            const content: ReadonlyArray<ToolContent> = part.result.value
+            input.push({
+              role: "user",
+              content: yield* Effect.forEach(content, (item) =>
+                lowerToolResultContentItem(item, request.model.provider),
+              ),
+            })
+          }
           if (itemID) hostedToolReferences.add(itemID)
           continue
         }
@@ -439,7 +520,7 @@ const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (requ
       input.push({
         type: "function_call_output",
         call_id: part.id,
-        output: yield* lowerToolResultOutput(part),
+        output: yield* lowerToolResultOutput(part, request.model.provider),
       })
     }
   }
@@ -484,10 +565,10 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
     tools:
       request.tools.length === 0
         ? undefined
-        : request.tools.map((tool) =>
+        : yield* Effect.forEach(request.tools, (tool) =>
             lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
           ),
-    tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
+    tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined,
     stream: true as const,
     max_output_tokens: generation?.maxTokens,
     temperature: generation?.temperature,
@@ -573,14 +654,29 @@ const isReasoningItem = (
 
 // Round-trip the full item as the structured result so consumers can extract
 // outputs / sources / status without re-decoding.
-const hostedToolResult = (item: OpenAIResponsesStreamItem) => {
+const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function* (item: OpenAIResponsesStreamItem) {
   const isError = typeof item.error !== "undefined" && item.error !== null
+  if (item.type === "image_generation_call" && item.result) {
+    yield* Effect.fromResult(Encoding.decodeBase64(item.result)).pipe(
+      Effect.mapError(() => ProviderShared.eventError(ADAPTER, "OpenAI Responses returned invalid image base64")),
+    )
+    return {
+      type: "content" as const,
+      value: [
+        {
+          type: "file" as const,
+          uri: `data:image/${item.output_format ?? "png"};base64,${item.result}`,
+          mime: `image/${item.output_format ?? "png"}`,
+        },
+      ],
+    }
+  }
   return isError ? { type: "error" as const, value: item.error } : { type: "json" as const, value: item }
-}
+})
 
-const hostedToolEvents = (
+const hostedToolEvents = Effect.fn("OpenAIResponses.hostedToolEvents")(function* (
   item: OpenAIResponsesStreamItem & { type: HostedToolType; id: string },
-): ReadonlyArray<LLMEvent> => {
+) {
   const tool = HOSTED_TOOLS[item.type]
   const providerMetadata = openaiMetadata({ itemId: item.id })
   return [
@@ -594,21 +690,20 @@ const hostedToolEvents = (
     LLMEvent.toolResult({
       id: item.id,
       name: tool.name,
-      result: hostedToolResult(item),
+      result: yield* hostedToolResult(item),
       providerExecuted: true,
       providerMetadata,
     }),
   ]
-}
+})
 
 type StepResult = readonly [ParserState, ReadonlyArray<LLMEvent>]
 
 const NO_EVENTS: StepResult["1"] = []
 
 // `response.completed` / `response.incomplete` are clean finishes that emit a
-// `finish` event; `response.failed` is a hard failure that emits a
-// `provider-error`. All three end the stream — kept in one set so `step` and
-// the protocol's `terminal` predicate stay in sync.
+// `finish` event; `response.failed` is a hard failure. All three end the stream,
+// so keep this set aligned with `step` and the protocol's terminal predicate.
 const TERMINAL_TYPES = new Set(["response.completed", "response.incomplete", "response.failed"])
 
 const onOutputTextDelta = (state: ParserState, event: OpenAIResponsesEvent): StepResult => {
@@ -835,7 +930,9 @@ const onOutputItemDone = Effect.fn("OpenAIResponses.onOutputItemDone")(function*
       {
         ...state,
         lifecycle,
-        hasFunctionCall: resultEvents.some(LLMEvent.is.toolCall) ? true : state.hasFunctionCall,
+        hasFunctionCall:
+          resultEvents.some((event) => LLMEvent.is.toolCall(event) || LLMEvent.is.toolInputError(event)) ||
+          state.hasFunctionCall,
         tools: result.tools,
       },
       events,
@@ -845,7 +942,7 @@ const onOutputItemDone = Effect.fn("OpenAIResponses.onOutputItemDone")(function*
   if (isHostedToolItem(item)) {
     const events: LLMEvent[] = []
     const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
-    events.push(...hostedToolEvents(item))
+    events.push(...(yield* hostedToolEvents(item)))
     return [{ ...state, lifecycle }, events] satisfies StepResult
   }
 
@@ -910,22 +1007,13 @@ const providerErrorMessage = (event: OpenAIResponsesEvent, fallback: string): st
 const providerError = (event: OpenAIResponsesEvent, fallback: string) => {
   const code = event.code || event.error?.code || event.response?.error?.code || undefined
   const message = providerErrorMessage(event, fallback)
-  return LLMEvent.providerError({
-    message,
-    classification: code === "context_length_exceeded" || isContextOverflow(message) ? "context-overflow" : undefined,
+  return new LLMError({
+    module: ADAPTER,
+    method: "stream",
+    reason: classifyProviderFailure({ message, code }),
   })
 }
 
-const onResponseFailed = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
-  state,
-  [providerError(event, "OpenAI Responses response failed")],
-]
-
-const onError = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
-  state,
-  [providerError(event, "OpenAI Responses stream error")],
-]
-
 const step = (state: ParserState, event: OpenAIResponsesEvent) => {
   if (event.type === "response.output_text.delta") return Effect.succeed(onOutputTextDelta(state, event))
   if (event.type === "response.output_text.done") return Effect.succeed(onOutputTextDone(state, event))
@@ -950,8 +1038,8 @@ const step = (state: ParserState, event: OpenAIResponsesEvent) => {
   if (event.type === "response.output_item.done") return onOutputItemDone(state, event)
   if (event.type === "response.completed" || event.type === "response.incomplete")
     return Effect.succeed(onResponseFinish(state, event))
-  if (event.type === "response.failed") return Effect.succeed(onResponseFailed(state, event))
-  if (event.type === "error") return Effect.succeed(onError(state, event))
+  if (event.type === "response.failed") return providerError(event, "OpenAI Responses response failed")
+  if (event.type === "error") return providerError(event, "OpenAI Responses stream error")
   return Effect.succeed<StepResult>([state, NO_EVENTS])
 }
 

packages/ai/src/protocols/shared.ts

@@ -158,7 +158,8 @@ export const parseToolInput = (route: string, name: string, raw: string) =>
 export const IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "image/webp"] as const
 export const VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"] as const
 export const AUDIO_MIMES = ["audio/wav", "audio/mp3", "audio/aiff", "audio/aac", "audio/ogg", "audio/flac"] as const
-export const MEDIA_MIMES = [...IMAGE_MIMES, ...VIDEO_MIMES, ...AUDIO_MIMES] as const
+export const PDF_MIMES = ["application/pdf"] as const
+export const MEDIA_MIMES = [...IMAGE_MIMES, ...VIDEO_MIMES, ...AUDIO_MIMES, ...PDF_MIMES] as const
 export const MAX_MEDIA_ENCODED_BYTES = 28 * 1024 * 1024
 export const MAX_MEDIA_DECODED_BYTES = 20 * 1024 * 1024
 

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

@@ -49,10 +49,10 @@ const DOCUMENT_FORMATS = {
   "text/markdown": "md",
 } as const satisfies Record<string, DocumentFormat>
 
-const documentBlock = (part: MediaPart, format: DocumentFormat, bytes: string): DocumentBlock => ({
+const documentBlock = (name: string, format: DocumentFormat, bytes: string): DocumentBlock => ({
   document: {
     format,
-    name: part.filename ?? `document.${format}`,
+    name,
     source: { bytes },
   },
 })
@@ -77,12 +77,14 @@ export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart)
     return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support image media type ${part.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")
     const media = yield* ProviderShared.validateMedia(
       "Bedrock Converse",
       part,
       new Set<string>(Object.keys(DOCUMENT_FORMATS)),
     )
-    return documentBlock(part, documentFormat, media.base64)
+    return documentBlock(part.filename, documentFormat, media.base64)
   }
   return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support media type ${part.mediaType}`)
 })

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

@@ -0,0 +1,34 @@
+import { Effect, Encoding } from "effect"
+import type { ImageInput } from "../../image"
+import { InvalidRequestReason, LLMError } from "../../schema"
+
+const invalid = (module: string, message: string) =>
+  new LLMError({
+    module,
+    method: "generate",
+    reason: new InvalidRequestReason({ message }),
+  })
+
+export const dataUrl = (input: Extract<ImageInput, { readonly type: "bytes" }>) =>
+  `data:${input.mediaType};base64,${Encoding.encodeBase64(input.data)}`
+
+export const decodeDataUrl = (
+  url: string,
+  module: string,
+): Effect.Effect<{ readonly mediaType: string; readonly data: Uint8Array } | undefined, LLMError> => {
+  if (!url.startsWith("data:")) return Effect.succeed(undefined)
+  const match = /^data:([^;,]+);base64,(.*)$/s.exec(url)
+  if (!match) return Effect.fail(invalid(module, "Image data URLs must contain a MIME type and base64 data"))
+  return Effect.fromResult(Encoding.decodeBase64(match[2])).pipe(
+    Effect.mapError(() => invalid(module, "Image data URL contains invalid base64 data")),
+    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/lifecycle.ts

@@ -44,7 +44,7 @@ export const reasoningDelta = (
   providerMetadata?: ProviderMetadata,
 ): State => {
   const started = reasoningStart(state, events, id, providerMetadata)
-  events.push(LLMEvent.reasoningDelta({ id, text }))
+  events.push(LLMEvent.reasoningDelta({ id, text, providerMetadata }))
   return started
 }
 

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

@@ -0,0 +1,20 @@
+import { Schema } from "effect"
+
+const dimensions = (value: string) => {
+  const match = /^(\d+)x(\d+)$/.exec(value)
+  if (!match) return undefined
+  return { width: Number(match[1]), height: Number(match[2]) }
+}
+
+export const Size = Schema.String.check(
+  Schema.makeFilter((value) => {
+    if (value === "auto") return undefined
+    const parsed = dimensions(value)
+    if (!parsed) return "image size must be `auto` or `{width}x{height}`"
+    return parsed.width > 0 && parsed.height > 0 ? undefined : "image dimensions must be positive integers"
+  }),
+)
+
+export const OpenAIImage = {
+  Size,
+} as const

packages/ai/src/protocols/utils/tool-stream.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall } from "../../schema"
+import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall, type ToolInputError } from "../../schema"
 import { eventError, parseToolInput, type ToolAccumulator } from "../shared"
 
 type StreamKey = string | number
@@ -53,6 +53,7 @@ const inputStart = (tool: PendingTool) =>
   LLMEvent.toolInputStart({
     id: tool.id,
     name: tool.name,
+    providerExecuted: tool.providerExecuted ? true : undefined,
     providerMetadata: tool.providerMetadata,
   })
 
@@ -63,19 +64,36 @@ const inputDelta = (tool: PendingTool, text: string) =>
     text,
   })
 
-const toolCall = (route: string, tool: PendingTool, inputOverride?: string) =>
-  parseToolInput(route, tool.name, inputOverride ?? tool.input).pipe(
-    Effect.map(
-      (input): ToolCall =>
-        LLMEvent.toolCall({
-          id: tool.id,
-          name: tool.name,
-          input,
-          providerExecuted: tool.providerExecuted ? true : undefined,
-          providerMetadata: tool.providerMetadata,
-        }),
+const toolCall = (route: string, tool: PendingTool, inputOverride?: string) => {
+  const raw = inputOverride ?? tool.input
+  return parseToolInput(route, tool.name, raw).pipe(
+    Effect.map((input): ToolCall | ToolInputError =>
+      LLMEvent.toolCall({
+        id: tool.id,
+        name: tool.name,
+        input,
+        providerExecuted: tool.providerExecuted ? true : undefined,
+        providerMetadata: tool.providerMetadata,
+      }),
+    ),
+    Effect.catch((error) =>
+      tool.providerExecuted
+        ? Effect.fail(error)
+        : Effect.succeed(
+            LLMEvent.toolInputError({
+              id: tool.id,
+              name: tool.name,
+              raw,
+            }),
+          ),
     ),
   )
+}
+
+const finishEvents = (tool: PendingTool, event: ToolCall | ToolInputError): ReadonlyArray<LLMEvent> =>
+  event.type === "tool-input-error"
+    ? [event]
+    : [LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }), event]
 
 /** Store the updated tool and produce the optional public delta event. */
 const appendTool = <K extends StreamKey>(
@@ -122,8 +140,8 @@ export const appendOrStart = <K extends StreamKey>(
   missingToolMessage: string,
 ): AppendOutcome<K> | LLMError => {
   const current = tools[key]
-  const id = delta.id ?? current?.id
-  const name = delta.name ?? current?.name
+  const id = current?.id ?? delta.id
+  const name = current?.name ?? delta.name
   if (!id || !name) return eventError(route, missingToolMessage)
 
   const tool = {
@@ -158,8 +176,9 @@ export const appendExisting = <K extends StreamKey>(
 
 /**
  * Finalize one pending tool call: parse the accumulated raw JSON, remove it
- * from state, and return the optional public `tool-call` event. Missing keys are
- * a no-op because some providers emit stop events for non-tool content blocks.
+ * from state, and return either a call or a non-executable local input error.
+ * Missing keys are a no-op because some providers emit stop events for
+ * non-tool content blocks.
  */
 export const finish = <K extends StreamKey>(route: string, tools: State<K>, key: K) =>
   Effect.gen(function* () {
@@ -167,10 +186,7 @@ export const finish = <K extends StreamKey>(route: string, tools: State<K>, key:
     if (!tool) return { tools }
     return {
       tools: withoutTool(tools, key),
-      events: [
-        LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
-        yield* toolCall(route, tool),
-      ],
+      events: finishEvents(tool, yield* toolCall(route, tool)),
     }
   })
 
@@ -185,17 +201,14 @@ export const finishWithInput = <K extends StreamKey>(route: string, tools: State
     if (!tool) return { tools }
     return {
       tools: withoutTool(tools, key),
-      events: [
-        LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
-        yield* toolCall(route, tool, input),
-      ],
+      events: finishEvents(tool, yield* toolCall(route, tool, input)),
     }
   })
 
 /**
  * Finalize every pending tool call at once. OpenAI Chat has this shape: it does
- * not emit per-tool stop events, so all accumulated calls finish when the choice
- * receives a terminal `finish_reason`.
+ * not emit per-tool stop events, so all accumulated calls finish independently
+ * when the choice receives a terminal `finish_reason`.
  */
 export const finishAll = <K extends StreamKey>(route: string, tools: State<K>) =>
   Effect.gen(function* () {
@@ -205,12 +218,7 @@ export const finishAll = <K extends StreamKey>(route: string, tools: State<K>) =
     return {
       tools: empty<K>(),
       events: yield* Effect.forEach(pending, (tool) =>
-        toolCall(route, tool).pipe(
-          Effect.map((call) => [
-            LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
-            call,
-          ]),
-        ),
+        toolCall(route, tool).pipe(Effect.map((event) => finishEvents(tool, event))),
       ).pipe(Effect.map((events) => events.flat())),
     }
   })

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

@@ -0,0 +1,202 @@
+import { Effect, Encoding, Schema } from "effect"
+import { Headers, HttpClientRequest } from "effect/unstable/http"
+import { GeneratedImage, ImageModel, ImageResponse, type ImageRequestFor, type ImageRoute } from "../image"
+import { Auth, type Definition as AuthDefinition } from "../route/auth"
+import {
+  InvalidProviderOutputReason,
+  LLMError,
+  Usage,
+  mergeHttpOptions,
+  mergeJsonRecords,
+  type HttpOptions,
+} from "../schema"
+import { ProviderShared, optionalNull } from "./shared"
+import { ImageInputs } from "./utils/image-input"
+
+const ADAPTER = "xai-images"
+export const DEFAULT_BASE_URL = "https://api.x.ai/v1"
+export const PATH = "/images/generations"
+export const EDIT_PATH = "/images/edits"
+
+export type XAIImageString<Known extends string> = Known | (string & {})
+
+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
+}
+
+const XAIImageResponse = Schema.Struct({
+  data: Schema.Array(
+    Schema.Struct({
+      b64_json: optionalNull(Schema.String),
+      url: optionalNull(Schema.String),
+      revised_prompt: optionalNull(Schema.String),
+      mime_type: optionalNull(Schema.String),
+    }),
+  ),
+  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
+}
+
+const nativeOptions = (options: XAIImageOptions | undefined) => {
+  if (!options) return undefined
+  const { aspectRatio, responseFormat, ...native } = options
+  return {
+    aspect_ratio: aspectRatio,
+    response_format: responseFormat,
+    ...native,
+  }
+}
+
+const invalidOutput = (message: string) =>
+  new LLMError({
+    module: ADAPTER,
+    method: "generate",
+    reason: new InvalidProviderOutputReason({ message, route: ADAPTER }),
+  })
+
+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<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(ADAPTER, "xAI Images accepts image URLs, data URLs, bytes, and file IDs")
+      const requestBody = mergeJsonRecords(
+        {
+          model: request.model.id,
+          prompt: request.prompt,
+          image: imageReferences.length === 1 ? imageReferences[0] : undefined,
+          images: imageReferences.length > 1 ? imageReferences : undefined,
+        },
+        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 payload = yield* response.json.pipe(
+        Effect.mapError(() => invalidOutput("Failed to read the xAI Images response")),
+      )
+      const decoded = yield* Schema.decodeUnknownEffect(XAIImageResponse)(payload).pipe(
+        Effect.mapError(() => invalidOutput("xAI Images returned an invalid response")),
+      )
+      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(() => invalidOutput(`xAI Images result ${index} contains invalid base64 data`)),
+            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(invalidOutput(`xAI Images result ${index} has neither image data nor a URL`))
+      })
+      if (images.length === 0) return yield* invalidOutput("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 })
+}
+
+export const XAIImages = {
+  model,
+} as const

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

@@ -0,0 +1,132 @@
+import { Effect, Schema } from "effect"
+import { Headers, HttpClientRequest } from "effect/unstable/http"
+import { GeneratedImage, ImageModel, ImageResponse, type ImageRequestFor, type ImageRoute } from "../image"
+import { Auth, type Definition as AuthDefinition } from "../route/auth"
+import { InvalidProviderOutputReason, LLMError, mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema"
+import { ProviderShared } from "./shared"
+import { ImageInputs } from "./utils/image-input"
+
+const ADAPTER = "zai-images"
+export const DEFAULT_BASE_URL = "https://api.z.ai/api/paas/v4"
+export const PATH = "/images/generations"
+
+export type ZAIImageString<Known extends string> = Known | (string & {})
+
+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
+}
+
+const ZAIImageResponse = Schema.Struct({
+  created: Schema.optional(Schema.Int),
+  id: Schema.optional(Schema.String),
+  request_id: Schema.optional(Schema.String),
+  data: Schema.Array(Schema.Struct({ url: Schema.String })),
+  content_filter: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        role: Schema.optional(Schema.String),
+        level: Schema.optional(Schema.Number),
+      }),
+    ),
+  ),
+})
+
+export interface ModelInput {
+  readonly id: string
+  readonly auth: AuthDefinition
+  readonly baseURL?: string
+  readonly headers?: Record<string, string>
+  readonly http?: HttpOptions
+}
+
+const nativeOptions = (options: ZAIImageOptions | undefined) => {
+  if (!options) return undefined
+  const { userID, ...native } = options
+  return {
+    user_id: userID,
+    ...native,
+  }
+}
+
+const invalidOutput = (message: string) =>
+  new LLMError({
+    module: ADAPTER,
+    method: "generate",
+    reason: new InvalidProviderOutputReason({ message, route: ADAPTER }),
+  })
+
+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<ZAIImageOptions> = {
+    id: ADAPTER,
+    generate: Effect.fn("ZAIImages.generate")(function* (request: ImageRequestFor<ZAIImageOptions>, execute) {
+      if ((request.images?.length ?? 0) > 0)
+        return yield* ImageInputs.invalid(ADAPTER, "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 payload = yield* response.json.pipe(
+        Effect.mapError(() => invalidOutput("Failed to read the Z.ai Images response")),
+      )
+      const decoded = yield* Schema.decodeUnknownEffect(ZAIImageResponse)(payload).pipe(
+        Effect.mapError(() => invalidOutput("Z.ai Images returned an invalid response")),
+      )
+      if (decoded.data.length === 0) return yield* invalidOutput("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 })
+}
+
+export const ZAIImages = {
+  model,
+} as const

packages/ai/src/provider-error.ts

@@ -0,0 +1,165 @@
+import { Option, Schema } from "effect"
+import {
+  AuthenticationReason,
+  ContentPolicyReason,
+  InvalidRequestReason,
+  LLMError,
+  ProviderErrorEvent,
+  ProviderInternalReason,
+  QuotaExceededReason,
+  RateLimitReason,
+  UnknownProviderReason,
+  type HttpContext,
+  type HttpRateLimitDetails,
+  type ProviderMetadata,
+} from "./schema"
+
+const patterns = [
+  /prompt is too long/i,
+  /request_too_large/i,
+  /input is too long for requested model/i,
+  /exceeds the context window/i,
+  /exceeds (?:the )?(?:model'?s )?maximum context length(?: of [\d,]+ tokens?|\s*\([\d,]+\))/i,
+  /input token count.*exceeds the maximum/i,
+  /tokens in request more than max tokens allowed/i,
+  /maximum prompt length is \d+/i,
+  /reduce the length of the messages/i,
+  /maximum context length is \d+ tokens/i,
+  /exceeds (?:the )?maximum allowed input length of [\d,]+ tokens?/i,
+  /input \(\d+ tokens\) is longer than the model'?s context length \(\d+ tokens\)/i,
+  /exceeds the limit of \d+/i,
+  /exceeds the available context size/i,
+  /greater than the context length/i,
+  /context window exceeds limit/i,
+  /exceeded model token limit/i,
+  /context[_ ]length[_ ]exceeded/i,
+  /request entity too large/i,
+  /context length is only \d+ tokens/i,
+  /input length.*exceeds.*context length/i,
+  /prompt too long; exceeded (?:max )?context length/i,
+  /too large for model with \d+ maximum context length/i,
+  /prompt has [\d,]+ tokens?, but the configured context size is [\d,]+ tokens?/i,
+  /model_context_window_exceeded/i,
+  /too many tokens/i,
+  /token limit exceeded/i,
+]
+
+const exclusions = [/^(throttling error|service unavailable):/i, /rate limit/i, /too many requests/i]
+
+export const isContextOverflow = (message: string) =>
+  !exclusions.some((pattern) => pattern.test(message)) &&
+  (patterns.some((pattern) => pattern.test(message)) || /^4(00|13)\s*(status code)?\s*\(no body\)/i.test(message))
+
+export const isContextOverflowFailure = (failure: unknown) =>
+  failure instanceof LLMError
+    ? failure.reason._tag === "InvalidRequest" && failure.reason.classification === "context-overflow"
+    : Schema.is(ProviderErrorEvent)(failure) && failure.classification === "context-overflow"
+
+const decodeJson = Schema.decodeUnknownOption(Schema.UnknownFromJsonString)
+const QUOTA_CODES = new Set(["insufficient_quota", "usage_not_included", "billing_error"])
+const SERVER_CODES = new Set([
+  "api_error",
+  "internal_error",
+  "internalserverexception",
+  "modelstreamerrorexception",
+  "overloaded_error",
+  "server_error",
+  "server_is_overloaded",
+  "serviceunavailableexception",
+])
+const INVALID_REQUEST_CODES = new Set(["invalid_prompt", "invalid_request_error", "validationexception"])
+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
+
+export interface ProviderFailure {
+  readonly message: string
+  readonly status?: number | undefined
+  readonly code?: string | undefined
+  readonly retryAfterMs?: number | undefined
+  readonly rateLimit?: HttpRateLimitDetails | undefined
+  readonly http?: HttpContext | undefined
+  readonly providerMetadata?: ProviderMetadata | undefined
+}
+
+// Keep HTTP failures and provider-reported stream failures on one typed path so
+// session retry policy never needs provider-specific string matching.
+export function classifyProviderFailure(input: ProviderFailure): LLMError["reason"] {
+  const body = input.http?.body ?? ""
+  const codes = [input.code, ...providerCodes(body), ...providerCodes(input.message)]
+    .filter((code): code is string => code !== undefined)
+    .map((code) => code.toLowerCase())
+  const text = body || input.message
+  const common = { message: input.message, providerMetadata: input.providerMetadata, http: input.http }
+  const clientScoped = input.status === undefined || (input.status >= 400 && input.status < 500)
+
+  if (
+    clientScoped &&
+    (codes.includes("context_length_exceeded") ||
+      codes.includes("model_context_window_exceeded") ||
+      isContextOverflow(text))
+  )
+    return new InvalidRequestReason({ ...common, classification: "context-overflow" })
+  if (CONTENT_POLICY_TEXT.test(text)) return new ContentPolicyReason(common)
+  if (codes.some((code) => QUOTA_CODES.has(code)) || (input.status === 429 && QUOTA_TEXT.test(text)))
+    return new QuotaExceededReason(common)
+  if (input.status === 401) return new AuthenticationReason({ ...common, kind: "invalid" })
+  if (input.status === 403) return new AuthenticationReason({ ...common, kind: "insufficient-permissions" })
+  if (codes.includes("authentication_error")) return new AuthenticationReason({ ...common, kind: "invalid" })
+  if (codes.includes("permission_error"))
+    return new AuthenticationReason({ ...common, kind: "insufficient-permissions" })
+  if (
+    codes.some((code) => code.includes("rate_limit") || code === "too_many_requests" || code === "throttlingexception")
+  )
+    return new RateLimitReason({
+      ...common,
+      retryAfterMs: input.retryAfterMs,
+      rateLimit: input.rateLimit,
+    })
+  if (RATE_LIMIT_TEXT.test(text))
+    return new RateLimitReason({
+      ...common,
+      retryAfterMs: input.retryAfterMs,
+      rateLimit: input.rateLimit,
+    })
+  if (codes.some((code) => SERVER_CODES.has(code) || code.includes("exhausted") || code.includes("unavailable")))
+    return new ProviderInternalReason({
+      ...common,
+      status: input.status,
+      retryAfterMs: input.retryAfterMs,
+    })
+  if (input.status === 429) {
+    return new RateLimitReason({
+      ...common,
+      retryAfterMs: input.retryAfterMs,
+      rateLimit: input.rateLimit,
+    })
+  }
+  if (input.status !== undefined && input.status >= 500)
+    return new ProviderInternalReason({
+      ...common,
+      status: input.status,
+      retryAfterMs: input.retryAfterMs,
+    })
+  if (codes.some((code) => INVALID_REQUEST_CODES.has(code))) return new InvalidRequestReason(common)
+  if (
+    input.status === 400 ||
+    input.status === 404 ||
+    input.status === 409 ||
+    input.status === 413 ||
+    input.status === 422
+  )
+    return new InvalidRequestReason(common)
+  return new UnknownProviderReason({ ...common, status: input.status })
+}
+
+function providerCodes(value: string) {
+  const decoded = Option.getOrUndefined(decodeJson(value))
+  if (!isRecord(decoded)) return []
+  const error = isRecord(decoded.error) ? decoded.error : undefined
+  return [decoded.code, error?.code, error?.type].filter((value): value is string => typeof value === "string")
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}

packages/ai/src/providers.ts

@@ -0,0 +1 @@
+export * from "./providers/index"

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

@@ -0,0 +1,67 @@
+import type { ProviderPackage } from "../provider-package"
+import { AnthropicMessages } from "../protocols/anthropic-messages"
+import { Auth } from "../route/auth"
+import type { ProviderAuthOption } from "../route/auth-options"
+import type { RouteDefaultsInput } from "../route/client"
+import { ProviderID, type ModelID } from "../schema"
+
+export const id = ProviderID.make("anthropic-compatible")
+
+export type Config = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly provider?: string
+    readonly baseURL: string
+  }
+
+export type Settings = ProviderPackage.Settings &
+  (
+    | { readonly apiKey?: string; readonly authToken?: never }
+    | { readonly apiKey?: never; readonly authToken?: string }
+  ) & {
+    readonly baseURL: string
+    readonly provider?: string
+  }
+
+export const routes = [AnthropicMessages.route]
+
+const auth = (input: ProviderAuthOption<"optional">) => {
+  if ("auth" in input && input.auth) return input.auth
+  return Auth.optional("apiKey" in input ? input.apiKey : undefined, "apiKey").pipe(Auth.header("x-api-key"))
+}
+
+export const configure = (input: Config) => {
+  if (!input.baseURL) throw new Error("Anthropic-compatible providers require a baseURL")
+  const provider = input.provider ?? "anthropic-compatible"
+  const { provider: _, baseURL, apiKey: _apiKey, auth: _auth, ...rest } = input
+  const route = AnthropicMessages.route.with({
+    ...rest,
+    provider,
+    endpoint: { baseURL },
+    auth: auth(input),
+  })
+  return {
+    id: ProviderID.make(provider),
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}
+
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+  if (settings.apiKey !== undefined && settings.authToken !== undefined)
+    throw new Error("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 } },
+    limits: settings.limits,
+    provider: settings.provider,
+  }).model(modelID)
+}
+
+export * as AnthropicCompatible from "./anthropic-compatible"

packages/ai/src/providers/anthropic.ts

@@ -3,7 +3,8 @@ import { Auth } from "../route/auth"
 import type { ProviderAuthOption } from "../route/auth-options"
 import type { ProviderPackage } from "../provider-package"
 import { ProviderID, type ModelID } from "../schema"
-import * as AnthropicMessages from "../protocols/anthropic-messages"
+import { AnthropicMessages } from "../protocols/anthropic-messages"
+import { AnthropicCompatible } from "./anthropic-compatible"
 
 export const id = ProviderID.make("anthropic")
 
@@ -11,11 +12,13 @@ export const routes = [AnthropicMessages.route]
 
 export type Config = RouteDefaultsInput & ProviderAuthOption<"optional"> & { readonly baseURL?: string }
 
-export interface Settings extends ProviderPackage.Settings {
-  readonly apiKey?: string
-  readonly authToken?: string
-  readonly baseURL?: string
-}
+export type Settings = ProviderPackage.Settings &
+  (
+    | { readonly apiKey?: string; readonly authToken?: never }
+    | { readonly apiKey?: never; readonly authToken?: string }
+  ) & {
+    readonly baseURL?: string
+  }
 
 const auth = (options: ProviderAuthOption<"optional">) => {
   if ("auth" in options && options.auth) return options.auth
@@ -24,26 +27,30 @@ const auth = (options: ProviderAuthOption<"optional">) => {
     .pipe(Auth.header("x-api-key"))
 }
 
-const configuredRoute = (input: Config) => {
-  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
-  return AnthropicMessages.route.with({ ...rest, endpoint: { baseURL }, auth: auth(input) })
-}
-
 export const configure = (input: Config = {}) => {
-  const route = configuredRoute(input)
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  const compatible = AnthropicCompatible.configure({
+    ...rest,
+    auth: auth(input),
+    baseURL: baseURL ?? AnthropicMessages.DEFAULT_BASE_URL,
+    provider: id,
+  })
   return {
     id,
-    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    model: (modelID: string | ModelID) => compatible.model(modelID),
     configure,
   }
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
-  configure({
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+  if (settings.apiKey !== undefined && settings.authToken !== undefined)
+    throw new Error("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 } },
     limits: settings.limits,
   }).model(modelID)
+}

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

@@ -0,0 +1,81 @@
+import type { ProviderPackage } from "../provider-package"
+import { OpenAICompatibleChat } from "../protocols/openai-compatible-chat"
+import type { RouteDefaultsInput } from "../route/client"
+import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { GoogleVertexShared } from "./google-vertex-shared"
+
+export const id = ProviderID.make("google-vertex")
+
+export type Config = RouteDefaultsInput &
+  GoogleVertexShared.OAuthOptions & {
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
+
+export interface Settings extends ProviderPackage.Settings {
+  readonly accessToken?: string
+  readonly apiKey?: never
+  readonly baseURL?: string
+  readonly location?: string
+  readonly project?: string
+  readonly providerOptions?: ProviderOptions
+}
+
+const route = OpenAICompatibleChat.route.with({
+  id: "google-vertex-chat",
+  provider: id,
+})
+
+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")
+  const {
+    accessToken: _accessToken,
+    auth: _auth,
+    baseURL,
+    location: inputLocation,
+    project: inputProject,
+    ...rest
+  } = input
+  const location = GoogleVertexShared.location(inputLocation, "global")
+  const project = GoogleVertexShared.project(inputProject)
+  return route.with({
+    ...rest,
+    endpoint: {
+      baseURL:
+        baseURL ??
+        `https://aiplatform.googleapis.com/v1/projects/${GoogleVertexShared.requireProject(project)}/locations/${location}/endpoints/openapi`,
+    },
+    auth: GoogleVertexShared.oauth(input, project),
+  })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}
+
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+  if (settings.apiKey !== undefined) throw new Error("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 } },
+    limits: settings.limits,
+    location: settings.location,
+    project: settings.project,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)
+}

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

@@ -0,0 +1,111 @@
+import { Effect, Schema, Struct } from "effect"
+import type { ProviderPackage } from "../provider-package"
+import { AnthropicMessages } from "../protocols/anthropic-messages"
+import { Auth } from "../route/auth"
+import { Route, type RouteDefaultsInput } from "../route/client"
+import { Endpoint } from "../route/endpoint"
+import { Framing } from "../route/framing"
+import { Protocol } from "../route/protocol"
+import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { GoogleVertexShared } from "./google-vertex-shared"
+
+const VERSION = "vertex-2023-10-16" as const
+
+// models.dev uses this provider id even though the API contract is Anthropic Messages.
+export const id = ProviderID.make("google-vertex-anthropic")
+
+export type Config = RouteDefaultsInput &
+  GoogleVertexShared.OAuthOptions & {
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
+
+export interface Settings extends ProviderPackage.Settings {
+  readonly accessToken?: string
+  readonly apiKey?: never
+  readonly baseURL?: string
+  readonly location?: string
+  readonly project?: string
+  readonly providerOptions?: ProviderOptions
+}
+
+const route = Route.make({
+  id: "google-vertex-messages",
+  provider: id,
+  providerMetadataKey: "anthropic",
+  protocol: Protocol.make({
+    id: AnthropicMessages.protocol.id,
+    body: {
+      schema: Schema.Struct({
+        ...Struct.omit(AnthropicMessages.AnthropicMessagesBody.fields, ["model"]),
+        anthropic_version: Schema.Literal(VERSION),
+      }),
+      from: (request) =>
+        AnthropicMessages.protocol.body.from(request).pipe(
+          Effect.map((body) => ({
+            ...Struct.omit(body, ["model"]),
+            anthropic_version: VERSION,
+          })),
+        ),
+    },
+    stream: AnthropicMessages.protocol.stream,
+  }),
+  endpoint: Endpoint.path(({ request }) => `/${request.model.id}:streamRawPredict`),
+  auth: Auth.none,
+  framing: Framing.sse,
+})
+
+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")
+  const {
+    accessToken: _accessToken,
+    auth: _auth,
+    baseURL,
+    location: inputLocation,
+    project: inputProject,
+    ...rest
+  } = input
+  const location = GoogleVertexShared.location(inputLocation, "global")
+  const project = GoogleVertexShared.project(inputProject)
+  return route.with({
+    ...rest,
+    endpoint: {
+      baseURL:
+        baseURL ??
+        `https://${GoogleVertexShared.host(location)}/v1/projects/${GoogleVertexShared.requireProject(project)}/locations/${location}/publishers/anthropic/models`,
+    },
+    auth: GoogleVertexShared.oauth(input, project),
+  })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}
+
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+  if (settings.apiKey !== undefined) throw new Error("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 } },
+    limits: settings.limits,
+    location: settings.location,
+    project: settings.project,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)
+}

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

@@ -0,0 +1,82 @@
+import type { ProviderPackage } from "../provider-package"
+import { OpenAICompatibleResponses } from "../protocols/openai-compatible-responses"
+import type { RouteDefaultsInput } from "../route/client"
+import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { GoogleVertexShared } from "./google-vertex-shared"
+
+export const id = ProviderID.make("google-vertex")
+
+export type Config = RouteDefaultsInput &
+  GoogleVertexShared.OAuthOptions & {
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
+
+export interface Settings extends ProviderPackage.Settings {
+  readonly accessToken?: string
+  readonly apiKey?: never
+  readonly baseURL?: string
+  readonly location?: string
+  readonly project?: string
+  readonly providerOptions?: ProviderOptions
+}
+
+const route = OpenAICompatibleResponses.route.with({
+  id: "google-vertex-responses",
+  provider: id,
+})
+
+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")
+  const {
+    accessToken: _accessToken,
+    auth: _auth,
+    baseURL,
+    location: inputLocation,
+    project: inputProject,
+    ...rest
+  } = input
+  const location = GoogleVertexShared.location(inputLocation, "global")
+  const project = GoogleVertexShared.project(inputProject)
+  return route.with({
+    ...rest,
+    endpoint: {
+      baseURL:
+        baseURL ??
+        `https://aiplatform.googleapis.com/v1/projects/${GoogleVertexShared.requireProject(project)}/locations/${location}/endpoints/openapi`,
+    },
+    auth: GoogleVertexShared.oauth(input, project),
+  })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}
+
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+  if (settings.apiKey !== undefined) throw new Error("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 } },
+    limits: settings.limits,
+    location: settings.location,
+    project: settings.project,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)
+}

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

@@ -0,0 +1,77 @@
+import type { AnyAuthClient } from "google-auth-library"
+import { Effect, Redacted } from "effect"
+import { Auth, MissingCredentialError } from "../route/auth"
+
+const SCOPE = "https://www.googleapis.com/auth/cloud-platform"
+
+export type OAuthOptions =
+  | { readonly accessToken?: string; readonly auth?: never }
+  | { readonly accessToken?: never; readonly auth?: Auth.Definition }
+
+export type ApiKeyOptions =
+  | (OAuthOptions & { readonly apiKey?: never })
+  | { readonly accessToken?: never; readonly apiKey?: string; readonly auth?: never }
+
+export const project = (value?: string) =>
+  value ??
+  process.env.GOOGLE_VERTEX_PROJECT ??
+  process.env.GOOGLE_CLOUD_PROJECT ??
+  process.env.GCP_PROJECT ??
+  process.env.GCLOUD_PROJECT
+
+export const location = (value: string | undefined, fallback: string) =>
+  value ??
+  process.env.GOOGLE_VERTEX_LOCATION ??
+  process.env.GOOGLE_CLOUD_LOCATION ??
+  process.env.VERTEX_LOCATION ??
+  fallback
+
+export const host = (location: string) => {
+  if (location === "global") return "aiplatform.googleapis.com"
+  // Jurisdictional multi-regions use Regional Endpoint Platform domains.
+  if (location === "eu" || location === "us") return `aiplatform.${location}.rep.googleapis.com`
+  return `${location}-aiplatform.googleapis.com`
+}
+
+export const requireProject = (value: string | undefined) => {
+  if (value) return value
+  throw new Error("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")
+  if (input.accessToken !== undefined || input.auth !== undefined) return undefined
+  return input.apiKey ?? process.env.GOOGLE_VERTEX_API_KEY
+}
+
+const adc = (project?: string) => {
+  let client: Promise<AnyAuthClient> | undefined
+  const loadClient = () => {
+    if (client) return client
+    client = import("google-auth-library").then(({ GoogleAuth }) =>
+      new GoogleAuth({ projectId: project, scopes: [SCOPE] }).getClient(),
+    )
+    return client
+  }
+  return Auth.effect(
+    Effect.tryPromise({
+      try: async () => {
+        const token = await (await loadClient()).getAccessToken()
+        if (!token.token) throw new Error("Google ADC returned an empty access token")
+        return Redacted.make(token.token)
+      },
+      catch: () => new MissingCredentialError("Google Application Default Credentials"),
+    }),
+  ).bearer()
+}
+
+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")
+  if (input.auth) return input.auth
+  if (input.accessToken !== undefined) return Auth.bearer(input.accessToken)
+  return adc(project)
+}
+
+export * as GoogleVertexShared from "./google-vertex-shared"

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

@@ -0,0 +1,98 @@
+import type { ProviderPackage } from "../provider-package"
+import { Gemini } from "../protocols/gemini"
+import { Auth } from "../route/auth"
+import { Route, type RouteDefaultsInput } from "../route/client"
+import { Endpoint } from "../route/endpoint"
+import { Framing } from "../route/framing"
+import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { GoogleVertexShared } from "./google-vertex-shared"
+
+export const id = ProviderID.make("google-vertex")
+
+export type Config = RouteDefaultsInput &
+  GoogleVertexShared.ApiKeyOptions & {
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+  }
+
+export type Settings = ProviderPackage.Settings &
+  (
+    | { readonly accessToken?: string; readonly apiKey?: never }
+    | { readonly accessToken?: never; readonly apiKey?: string }
+  ) & {
+    readonly baseURL?: string
+    readonly location?: string
+    readonly project?: string
+    readonly providerOptions?: ProviderOptions
+  }
+
+const route = Route.make({
+  id: "google-vertex-gemini",
+  provider: id,
+  providerMetadataKey: "google",
+  protocol: Gemini.protocol,
+  endpoint: Endpoint.path(({ request }) => {
+    const model = String(request.model.id)
+    return `/${model.startsWith("endpoints/") ? model : `models/${model}`}:streamGenerateContent?alt=sse`
+  }),
+  auth: Auth.none,
+  framing: Framing.sse,
+})
+
+export const routes = [route]
+
+const configuredRoute = (input: Config, modelID: string | ModelID) => {
+  const {
+    accessToken: _accessToken,
+    apiKey: _apiKey,
+    auth: _auth,
+    baseURL,
+    location: inputLocation,
+    project: inputProject,
+    ...rest
+  } = input
+  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")
+  const location = GoogleVertexShared.location(inputLocation, "us-central1")
+  const project = GoogleVertexShared.project(inputProject)
+  const endpoint =
+    baseURL ??
+    (apiKey
+      ? "https://aiplatform.googleapis.com/v1/publishers/google"
+      : `https://${GoogleVertexShared.host(location)}/v1beta1/projects/${GoogleVertexShared.requireProject(project)}/locations/${location}${endpointModel ? "" : "/publishers/google"}`)
+  return route.with({
+    ...rest,
+    endpoint: { baseURL: endpoint },
+    auth: apiKey === undefined ? GoogleVertexShared.oauth(input, project) : Auth.header("x-goog-api-key", apiKey),
+  })
+}
+
+export const configure = (input: Config = {}) => {
+  return {
+    id,
+    model: (modelID: string | ModelID) => configuredRoute(input, modelID).model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
+  if (settings.apiKey !== undefined && settings.accessToken !== undefined)
+    throw new Error("Google Vertex apiKey cannot be combined with accessToken or auth")
+  return configure({
+    ...(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 } },
+    limits: settings.limits,
+    location: settings.location,
+    project: settings.project,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)
+}

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

@@ -0,0 +1,2 @@
+export { model } from "../google-vertex-chat"
+export type { Settings } from "../google-vertex-chat"

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

@@ -0,0 +1,2 @@
+export { model } from "../google-vertex"
+export type { Settings } from "../google-vertex"

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

@@ -0,0 +1,2 @@
+export { model } from "../google-vertex-messages"
+export type { Settings } from "../google-vertex-messages"

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

@@ -0,0 +1,2 @@
+export { model } from "../google-vertex-responses"
+export type { Settings } from "../google-vertex-responses"

packages/ai/src/providers/google.ts

@@ -2,14 +2,20 @@ import type { RouteDefaultsInput } from "../route/client"
 import { Auth } from "../route/auth"
 import type { ProviderAuthOption } from "../route/auth-options"
 import type { ProviderPackage } from "../provider-package"
-import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
-import * as Gemini from "../protocols/gemini"
+import { HttpOptions, ProviderID, mergeHttpOptions, type ModelID, type ProviderOptions } from "../schema"
+import { Gemini } from "../protocols/gemini"
+import { GoogleImages } from "../protocols/google-images"
+
+export type { GoogleImageOptions } from "../protocols/google-images"
 
 export const id = ProviderID.make("google")
 
 export const routes = [Gemini.route]
 
-export type Config = RouteDefaultsInput & ProviderAuthOption<"optional"> & { readonly baseURL?: string }
+export type Config = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL?: string
+  }
 
 export interface Settings extends ProviderPackage.Settings {
   readonly apiKey?: string
@@ -31,9 +37,18 @@ const configuredRoute = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
+  const image = (modelID: string | ModelID) =>
+    GoogleImages.model({
+      id: modelID,
+      auth: auth(input),
+      baseURL: input.baseURL,
+      headers: input.headers,
+      http: mergeHttpOptions(input.http === undefined ? undefined : HttpOptions.make(input.http)),
+    })
   return {
     id,
     model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    image,
     configure,
   }
 }
@@ -48,3 +63,5 @@ export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, se
     limits: settings.limits,
     providerOptions: settings.providerOptions,
   }).model(modelID)
+
+export const image = provider.image

packages/ai/src/providers/index.ts

@@ -1,11 +1,18 @@
 export * as Anthropic from "./anthropic"
+export * as AnthropicCompatible from "./anthropic-compatible"
 export * as AmazonBedrock from "./amazon-bedrock"
 export * as Azure from "./azure"
 export * as Cloudflare from "./cloudflare"
 export { CloudflareAIGateway, CloudflareWorkersAI } from "./cloudflare"
 export * as GitHubCopilot from "./github-copilot"
 export * as Google from "./google"
+export * as GoogleVertex from "./google-vertex"
+export * as GoogleVertexChat from "./google-vertex-chat"
+export * as GoogleVertexMessages from "./google-vertex-messages"
+export * as GoogleVertexResponses from "./google-vertex-responses"
 export * as OpenAI from "./openai"
 export * as OpenAICompatible from "./openai-compatible"
+export * as OpenAICompatibleResponses from "./openai-compatible-responses"
 export * as OpenRouter from "./openrouter"
 export * as XAI from "./xai"
+export * as ZAI from "./zai"

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

@@ -0,0 +1,55 @@
+import type { ProviderPackage } from "../provider-package"
+import { OpenAICompatibleResponses } from "../protocols/openai-compatible-responses"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
+import type { RouteDefaultsInput } from "../route/client"
+import { ProviderID, type ModelID } from "../schema"
+import type { OpenAIProviderOptionsInput } from "./openai-options"
+
+export const id = ProviderID.make("openai-compatible")
+
+export type Config = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly provider?: string
+    readonly baseURL: string
+  }
+
+export interface Settings extends ProviderPackage.Settings {
+  readonly apiKey?: string
+  readonly baseURL: string
+  readonly provider?: string
+  readonly providerOptions?: OpenAIProviderOptionsInput
+}
+
+export const routes = [OpenAICompatibleResponses.route]
+
+export const configure = (input: Config) => {
+  const provider = input.provider ?? "openai-compatible"
+  const { provider: _, baseURL, apiKey: _apiKey, auth: _auth, ...rest } = input
+  const route = OpenAICompatibleResponses.route.with({
+    ...rest,
+    provider,
+    endpoint: { baseURL },
+    auth: AuthOptions.bearer(input, []),
+  })
+  return {
+    id: ProviderID.make(provider),
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}
+
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+  configure({
+    apiKey: settings.apiKey,
+    baseURL: settings.baseURL,
+    headers: settings.headers === undefined ? undefined : { ...settings.headers },
+    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
+    limits: settings.limits,
+    provider: settings.provider,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)

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

@@ -0,0 +1 @@
+export * from "../openai-compatible-responses"

packages/ai/src/providers/openai.ts

@@ -1,12 +1,14 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import type { Route, RouteDefaultsInput } from "../route/client"
 import type { ProviderPackage } from "../provider-package"
-import { ProviderID, type ModelID } from "../schema"
+import { HttpOptions, ProviderID, ToolDefinition, mergeHttpOptions, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options"
+import { OpenAIImages, type OpenAIImageString } from "../protocols/openai-images"
 
 export type { OpenAIOptionsInput, OpenAIResponseIncludable } from "./openai-options"
+export type { OpenAIImageOptions } from "../protocols/openai-images"
 
 export const id = ProviderID.make("openai")
 
@@ -22,6 +24,39 @@ export type Config = RouteDefaultsInput &
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
+export interface ImageGenerationOptions {
+  readonly action?: OpenAIImageString<"auto" | "generate" | "edit">
+  readonly background?: OpenAIImageString<"auto" | "opaque" | "transparent">
+  readonly inputFidelity?: OpenAIImageString<"low" | "high">
+  readonly outputCompression?: number
+  readonly outputFormat?: OpenAIImageString<"png" | "jpeg" | "webp">
+  readonly partialImages?: number
+  readonly quality?: OpenAIImageString<"auto" | "low" | "medium" | "high" | "standard" | "hd">
+  readonly size?: OpenAIImageString<
+    "auto" | "256x256" | "512x512" | "1024x1024" | "1536x1024" | "1024x1536" | "1792x1024" | "1024x1792"
+  >
+}
+
+export const imageGeneration = (options: ImageGenerationOptions = {}) =>
+  ToolDefinition.make({
+    name: "image_generation",
+    description: "Generate or edit an image using OpenAI's hosted image generation tool.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    native: {
+      openai: {
+        type: "image_generation",
+        action: options.action,
+        background: options.background,
+        input_fidelity: options.inputFidelity,
+        output_compression: options.outputCompression,
+        output_format: options.outputFormat,
+        partial_images: options.partialImages,
+        quality: options.quality,
+        size: options.size,
+      },
+    },
+  })
+
 export interface Settings extends ProviderPackage.Settings {
   readonly apiKey?: string
   readonly baseURL?: string
@@ -55,6 +90,17 @@ export const configure = (input: Config = {}) => {
   const responsesWebSocket = (id: string | ModelID) =>
     responsesWebSocketRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
   const chat = (id: string | ModelID) => chatRoute.with(withOpenAIOptions(id, modelDefaults)).model({ id })
+  const image = (modelID: string | ModelID) =>
+    OpenAIImages.model({
+      id: modelID,
+      auth: auth(input),
+      baseURL: input.baseURL,
+      headers: input.headers,
+      http: mergeHttpOptions(
+        input.http === undefined ? undefined : HttpOptions.make(input.http),
+        input.queryParams === undefined ? undefined : new HttpOptions({ query: input.queryParams }),
+      ),
+    })
 
   return {
     id,
@@ -62,6 +108,7 @@ export const configure = (input: Config = {}) => {
     responses,
     responsesWebSocket,
     chat,
+    image,
     configure,
   }
 }
@@ -97,3 +144,4 @@ export const chatModel: ProviderPackage.Definition<Settings>["model"] = (modelID
 export const responses = provider.responses
 export const responsesWebSocket = provider.responsesWebSocket
 export const chat = provider.chat
+export const image = provider.image

packages/ai/src/providers/openrouter.ts

@@ -41,13 +41,31 @@ export const protocol = Protocol.make({
     schema: OpenRouterBody,
     from: (request) =>
       OpenAIChat.protocol.body.from(request).pipe(
-        Effect.map(
-          (body) =>
-            ({
-              ...body,
-              ...bodyOptions(request.providerOptions?.openrouter),
-            }) as OpenRouterBody,
-        ),
+        Effect.map((body) => {
+          const sourceAssistants = request.messages.filter((message) => message.role === "assistant")
+          let assistantIndex = 0
+          const messages = body.messages.map((message) => {
+            if (message.role !== "assistant") return message
+            const source = sourceAssistants[assistantIndex++]
+            const reasoning = source?.content
+              .filter((part) => part.type === "reasoning")
+              .map((part) => part.text)
+              .join("")
+            const reasoningDetails = Array.isArray(message.reasoning_details) ? message.reasoning_details : undefined
+            return {
+              ...message,
+              reasoning_content: undefined,
+              reasoning_text: undefined,
+              reasoning: reasoning && reasoningDetails && reasoningDetails.length > 0 ? reasoning : undefined,
+              reasoning_details: reasoningDetails,
+            }
+          })
+          return {
+            ...body,
+            messages,
+            ...bodyOptions(request.providerOptions?.openrouter),
+          } as OpenRouterBody
+        }),
       ),
   },
   stream: OpenAIChat.protocol.stream,

packages/ai/src/providers/xai.ts

@@ -1,9 +1,10 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import type { RouteDefaultsInput } from "../route/client"
-import { ProviderID, type ModelID } from "../schema"
+import { HttpOptions, ProviderID, type ModelID } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
+import { XAIImages } from "../protocols/xai-images"
 
 export const id = ProviderID.make("xai")
 
@@ -12,6 +13,8 @@ export type ModelOptions = RouteDefaultsInput &
     readonly baseURL?: string
   }
 
+export type { XAIImageOptions } from "../protocols/xai-images"
+
 export const routes = [OpenAIResponses.route, OpenAICompatibleChat.route]
 
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "XAI_API_KEY")
@@ -41,11 +44,20 @@ export const configure = (input: ModelOptions = {}) => {
   const chatRoute = configuredChatRoute(input)
   const responses = (modelID: string | ModelID) => responsesRoute.model({ id: modelID })
   const chat = (modelID: string | ModelID) => chatRoute.model({ id: modelID })
+  const image = (modelID: string | ModelID) =>
+    XAIImages.model({
+      id: modelID,
+      auth: auth(input),
+      baseURL: input.baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL,
+      headers: input.headers,
+      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    })
   return {
     id,
     model: responses,
     responses,
     chat,
+    image,
     configure,
   }
 }
@@ -54,3 +66,4 @@ export const provider = configure()
 export const model = provider.model
 export const responses = provider.responses
 export const chat = provider.chat
+export const image = provider.image

packages/ai/src/providers/zai.ts

@@ -0,0 +1,35 @@
+import { ZAIImages } from "../protocols/zai-images"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
+import { HttpOptions, ProviderID, type ModelID } from "../schema"
+
+export const id = ProviderID.make("zai")
+
+export type Config = ProviderAuthOption<"optional"> & {
+  readonly baseURL?: string
+  readonly headers?: Record<string, string>
+  readonly http?: HttpOptions.Input
+}
+
+export type { ZAIImageOptions } from "../protocols/zai-images"
+
+const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "ZAI_API_KEY")
+
+export const configure = (input: Config = {}) => {
+  const image = (modelID: string | ModelID) =>
+    ZAIImages.model({
+      id: modelID,
+      auth: auth(input),
+      baseURL: input.baseURL,
+      headers: input.headers,
+      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    })
+
+  return {
+    id,
+    image,
+    configure,
+  }
+}
+
+export const provider = configure()
+export const image = provider.image

packages/ai/src/route.ts

@@ -0,0 +1 @@
+export * from "./route/index"

packages/ai/src/route/auth-options.ts

@@ -4,7 +4,7 @@ import { Auth } from "./auth"
 export type ApiKeyMode = "optional" | "required"
 
 export type AuthOverride = {
-  readonly auth: Auth
+  readonly auth: Auth.Definition
   readonly apiKey?: never
 }
 
@@ -44,7 +44,10 @@ export type AtLeastOne<T> = {
  * override, otherwise resolve `apiKey` (option > config var) and apply it as
  * a bearer token.
  */
-export const bearer = (options: ProviderAuthOption<"optional">, envVar: string | ReadonlyArray<string>): Auth => {
+export const bearer = (
+  options: ProviderAuthOption<"optional">,
+  envVar: string | ReadonlyArray<string>,
+): Auth.Definition => {
   if ("auth" in options && options.auth) return options.auth
   return (Array.isArray(envVar) ? envVar : [envVar])
     .reduce(

packages/ai/src/route/auth.ts

@@ -1,6 +1,6 @@
 import { Config, Effect, Redacted } from "effect"
 import { Headers } from "effect/unstable/http"
-import { AuthenticationReason, InvalidRequestReason, LLMError, type LLMRequest } from "../schema"
+import { AuthenticationReason, InvalidRequestReason, LLMError, type HttpOptions } from "../schema"
 
 export class MissingCredentialError extends Error {
   readonly _tag = "MissingCredentialError"
@@ -15,7 +15,7 @@ export type AuthError = CredentialError | LLMError
 type Secret = string | Redacted.Redacted | Config.Config<string | Redacted.Redacted>
 
 export interface AuthInput {
-  readonly request: LLMRequest
+  readonly request: { readonly http?: HttpOptions }
   readonly method: "POST" | "GET"
   readonly url: string
   readonly body: string
@@ -25,19 +25,19 @@ export interface AuthInput {
 export interface Credential {
   readonly load: Effect.Effect<Redacted.Redacted, CredentialError>
   readonly orElse: (that: Credential) => Credential
-  readonly bearer: () => Auth
-  readonly header: (name: string) => Auth
+  readonly bearer: () => Definition
+  readonly header: (name: string) => Definition
   readonly pipe: <A>(f: (self: Credential) => A) => A
 }
 
-export interface Auth {
+export interface Definition {
   readonly apply: (input: AuthInput) => Effect.Effect<Headers.Headers, AuthError>
-  readonly andThen: (that: Auth) => Auth
-  readonly orElse: (that: Auth) => Auth
-  readonly pipe: <A>(f: (self: Auth) => A) => A
+  readonly andThen: (that: Definition) => Definition
+  readonly orElse: (that: Definition) => Definition
+  readonly pipe: <A>(f: (self: Definition) => A) => A
 }
 
-export const isAuth = (input: unknown): input is Auth =>
+export const isAuth = (input: unknown): input is Definition =>
   typeof input === "object" && input !== null && "apply" in input && typeof input.apply === "function"
 
 const credential = (load: Effect.Effect<Redacted.Redacted, CredentialError>): Credential => {
@@ -51,8 +51,8 @@ const credential = (load: Effect.Effect<Redacted.Redacted, CredentialError>): Cr
   return self
 }
 
-const auth = (apply: Auth["apply"]): Auth => {
-  const self: Auth = {
+const auth = (apply: Definition["apply"]): Definition => {
+  const self: Definition = {
     apply,
     andThen: (that) =>
       auth((input) => apply(input).pipe(Effect.flatMap((headers) => that.apply({ ...input, headers })))),
@@ -109,15 +109,15 @@ const credentialInput = (source: Secret | Credential) =>
     ? credentialFromSecret(source, "value")
     : source
 
-export function bearer(source: Secret | Credential): Auth
+export function bearer(source: Secret | Credential): Definition
 export function bearer(source: Secret | Credential) {
   return credentialInput(source).bearer()
 }
 
 export const apiKey = bearer
 
-export function header(name: string): (source: Secret | Credential) => Auth
-export function header(name: string, source: Secret | Credential): Auth
+export function header(name: string): (source: Secret | Credential) => Definition
+export function header(name: string, source: Secret | Credential): Definition
 export function header(name: string, source?: Secret | Credential) {
   if (source === undefined) {
     return (next: Secret | Credential) => credentialInput(next).header(name)
@@ -125,8 +125,8 @@ export function header(name: string, source?: Secret | Credential) {
   return credentialInput(source).header(name)
 }
 
-export function bearerHeader(name: string): (source: Secret | Credential) => Auth
-export function bearerHeader(name: string, source: Secret | Credential): Auth
+export function bearerHeader(name: string): (source: Secret | Credential) => Definition
+export function bearerHeader(name: string, source: Secret | Credential): Definition
 export function bearerHeader(name: string, source?: Secret | Credential) {
   const render = (input: Secret | Credential) =>
     fromCredential(credentialInput(input), (secret) => ({ [name]: `Bearer ${secret}` }))
@@ -149,7 +149,7 @@ const toLLMError = (error: AuthError): LLMError => {
 }
 
 export const toEffect =
-  (input: Auth) =>
+  (input: Definition) =>
   (authInput: AuthInput): Effect.Effect<Headers.Headers, LLMError> =>
     input.apply(authInput).pipe(Effect.mapError(toLLMError))
 

packages/ai/src/route/client.ts

@@ -1,16 +1,16 @@
 import { Cause, Context, Effect, Layer, Schema, Stream } from "effect"
 import * as Option from "effect/Option"
-import { Auth, type Auth as AuthDef } from "./auth"
+import { Auth } from "./auth"
 import { Endpoint, type EndpointPatch } from "./endpoint"
 import { RequestExecutor } from "./executor"
-import type { Framing } from "./framing"
+import { Framing } from "./framing"
 import { HttpTransport } from "./transport"
 import type { Transport, TransportRuntime } from "./transport"
 import { WebSocketExecutor } from "./transport"
 import type { Protocol } from "./protocol"
 import { applyCachePolicy } from "../cache-policy"
 import * as ProviderShared from "../protocols/shared"
-import type { LLMError, LLMEvent, PreparedRequestOf, ProtocolID, ProviderOptions } from "../schema"
+import type { LLMError, PreparedRequestOf, ProtocolID, ProviderOptions } from "../schema"
 import {
   GenerationOptions,
   HttpOptions,
@@ -19,6 +19,7 @@ import {
   Model,
   ModelLimits,
   LLMError as LLMErrorClass,
+  LLMEvent,
   PreparedRequest,
   ProviderID,
   mergeGenerationOptions,
@@ -39,8 +40,8 @@ export interface Route<Body, Prepared = unknown> {
   /** ProviderMetadata namespace emitted and consumed by this route. */
   readonly providerMetadataKey?: string
   readonly protocol: ProtocolID
-  readonly endpoint: Endpoint<Body>
-  readonly auth: AuthDef
+  readonly endpoint: Endpoint.Definition<Body>
+  readonly auth: Auth.Definition
   readonly transport: Transport<Body, Prepared, unknown>
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
@@ -85,7 +86,7 @@ export interface RouteDefaultsInput {
 export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
   readonly id?: string
   readonly provider?: string | ProviderID
-  readonly auth?: AuthDef
+  readonly auth?: Auth.Definition
   readonly transport?: Transport<Body, Prepared, unknown>
   readonly endpoint?: EndpointPatch<Body>
 }
@@ -121,7 +122,7 @@ const mergeRouteDefaults = (base: RouteDefaults | undefined, patch: RouteDefault
   }
 }
 
-const endpointBaseURL = <Body>(endpoint: Endpoint<Body>) =>
+const endpointBaseURL = <Body>(endpoint: Endpoint.Definition<Body>) =>
   typeof endpoint.baseURL === "string" ? endpoint.baseURL : undefined
 
 const mergeHeaders = (...items: ReadonlyArray<Record<string, string> | undefined>) => {
@@ -191,11 +192,11 @@ export interface MakeInput<Body, Frame, Event, State> {
   /** Semantic API contract — owns body construction, body schema, and parsing. */
   readonly protocol: Protocol<Body, Frame, Event, State>
   /** Where the request is sent. */
-  readonly endpoint: Endpoint<Body>
+  readonly endpoint: Endpoint.Definition<Body>
   /** Per-request transport auth. Provider facades override this via `route.with(...)`. */
-  readonly auth?: AuthDef
+  readonly auth?: Auth.Definition
   /** Stream framing — bytes -> frames before `protocol.stream.event` decoding. */
-  readonly framing: Framing<Frame>
+  readonly framing: Framing.Definition<Frame>
   /** Static / per-request headers added before `auth` runs. */
   readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
   /** Route/request defaults used when compiling requests for this route. */
@@ -212,9 +213,9 @@ export interface MakeTransportInput<Body, Prepared, Frame, Event, State> {
   /** Semantic API contract — owns body construction, body schema, and parsing. */
   readonly protocol: Protocol<Body, Frame, Event, State>
   /** Where the request is sent. */
-  readonly endpoint: Endpoint<Body>
+  readonly endpoint: Endpoint.Definition<Body>
   /** Per-request transport auth. Provider facades override this via `route.with(...)`. */
-  readonly auth?: AuthDef
+  readonly auth?: Auth.Definition
   /** Static / per-request headers added before `auth` runs. */
   readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
   /** Runnable transport route. */
@@ -229,6 +230,28 @@ const streamError = (route: string, message: string, cause: Cause.Cause<unknown>
   return ProviderShared.eventError(route, message, Cause.pretty(cause))
 }
 
+const requireTerminalEvent = (route: string) => (events: Stream.Stream<LLMEvent, LLMError>) =>
+  Stream.suspend(() => {
+    let terminal = false
+    return events.pipe(
+      Stream.mapEffect((event) => {
+        if (terminal)
+          return Effect.fail(
+            ProviderShared.eventError(route, `Provider emitted ${event.type} after the terminal event`),
+          )
+        if (LLMEvent.is.finish(event) || LLMEvent.is.providerError(event)) terminal = true
+        return Effect.succeed(event)
+      }),
+      Stream.onEnd(
+        Effect.suspend(() =>
+          terminal
+            ? Effect.void
+            : Effect.fail(ProviderShared.eventError(route, "Provider stream ended without a terminal finish event")),
+        ),
+      ),
+    )
+  })
+
 function makeFromTransport<Body, Prepared, Frame, Event, State>(
   input: MakeTransportInput<Body, Prepared, Frame, Event, State>,
 ): Route<Body, Prepared> {
@@ -298,6 +321,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
             protocol.stream.onHalt ? { onHalt: protocol.stream.onHalt } : undefined,
           ),
           Stream.catchCause((cause) => Stream.fail(streamError(route, `Failed to read ${route} stream`, cause))),
+          requireTerminalEvent(route),
         )
       },
     } satisfies Route<Body, Prepared>

packages/ai/src/route/endpoint.ts

@@ -19,21 +19,24 @@ export type EndpointPart<Body> = string | ((input: EndpointInput<Body>) => strin
  * URL embeds the model id, region, or another body field (e.g. Bedrock,
  * Gemini).
  */
-export interface Endpoint<Body> {
+export interface Definition<Body> {
   readonly baseURL?: string
   readonly path: EndpointPart<Body>
   readonly query?: Record<string, string>
 }
 
-export type EndpointPatch<Body> = Partial<Endpoint<Body>>
+export type EndpointPatch<Body> = Partial<Definition<Body>>
 
 /** Construct an `Endpoint` from a path string or path function. */
-export const path = <Body>(value: EndpointPart<Body>, options: Omit<Endpoint<Body>, "path"> = {}): Endpoint<Body> => ({
+export const path = <Body>(
+  value: EndpointPart<Body>,
+  options: Omit<Definition<Body>, "path"> = {},
+): Definition<Body> => ({
   ...options,
   path: value,
 })
 
-export const merge = <Body>(base: Endpoint<Body>, patch: EndpointPatch<Body>): Endpoint<Body> => ({
+export const merge = <Body>(base: Definition<Body>, patch: EndpointPatch<Body>): Definition<Body> => ({
   ...base,
   ...patch,
   baseURL: patch.baseURL ?? base.baseURL,
@@ -44,7 +47,7 @@ export const merge = <Body>(base: Endpoint<Body>, patch: EndpointPatch<Body>): E
 const renderPart = <Body>(part: EndpointPart<Body>, input: EndpointInput<Body>) =>
   typeof part === "function" ? part(input) : part
 
-export const render = <Body>(endpoint: Endpoint<Body>, input: EndpointInput<Body>) => {
+export const render = <Body>(endpoint: Definition<Body>, input: EndpointInput<Body>) => {
   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