feat(desktop): compose V2 sidecar

feat(client): add shared Chromium driver
feat(client): add browser host SDK
2026-08-03 16:56:33 -04:00 · 2026-07-28 16:55:54 +10:00 · 2026-07-28 16:55:53 +10:00 · 2026-07-28 16:55:53 +10:00 · 2026-07-28 16:55:52 +10:00 · 2026-07-28 16:55:50 +10:00
788 changed files with 64680 additions and 96402 deletions
@@ -1,7 +0,0 @@
---
-"@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.
@@ -1,5 +0,0 @@
---
-"@opencode-ai/cli": patch
---
-
-Expose a TUI plugin slot at the top of the session view.
@@ -1,8 +0,0 @@
---
-"@opencode-ai/plugin": minor
-"@opencode-ai/sdk": minor
-"@opencode-ai/client": minor
-"@opencode-ai/protocol": minor
---
-
-Replace the V2 tool result model with one canonical representation per fact. Tools lose `structured`, projection callbacks, the `Structured` generic, and the exported `Tool.settle` interpreter; tool responses carry schema-validated `output`, model-visible `content`, and optional compact JSON `metadata`. Code Mode receives the validated encoded output. Durable tool success stores non-empty model content plus optional metadata; failure stores one error plus the final bounded partial snapshot. Progress carries metadata only, while `execute.after` hooks receive the canonical terminal outcome and managed `outputPaths`. A one-time migration rewrites existing projected tool rows and moves provider-hosted result payloads into provider-owned result state.
@@ -1,7 +0,0 @@
---
-"@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.
@@ -1,5 +0,0 @@
---
-"@opencode-ai/cli": patch
---
-
-Expose a TUI plugin slot above the session composer.
@@ -0,0 +1,37 @@
+name: deploy-www
+
+on:
+  push:
+    branches:
+      - dev
+      - v2
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-www-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    if: github.repository == 'anomalyco/opencode' && (github.ref_name == 'dev' || github.ref_name == 'v2')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Build
+        working-directory: packages/www
+        run: bun run build
+        env:
+          BLUME_ENV: ${{ github.ref_name == 'v2' && 'production' || 'dev' }}
+          CLOUDFLARE_ENV: ${{ github.ref_name == 'v2' && 'production' || 'dev' }}
+
+      - name: Deploy
+        working-directory: packages/www
+        run: bun run deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
@@ -308,6 +308,7 @@ jobs:
          - host: "windows-2025"
            target: aarch64-pc-windows-msvc
            platform_flag: --win --arm64
+            bun_install_flags: --os=win32 --cpu=arm64
          - host: "blacksmith-4vcpu-windows-2025"
            target: x86_64-pc-windows-msvc
            platform_flag: --win
@@ -388,6 +389,7 @@ jobs:
        working-directory: packages/desktop
        env:
          NODE_OPTIONS: --max-old-space-size=4096
+          RUST_TARGET: ${{ matrix.settings.target }}
          OPENCODE_CHANNEL: ${{ (github.ref_name == 'beta' && 'beta') || 'prod' }}
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ vars.SENTRY_ORG }}
@@ -99,7 +99,7 @@ jobs:

      - name: Check generated documentation
        if: runner.os == 'Linux'
-        working-directory: packages/docs
+        working-directory: packages/www
        run: bun run check:generated

  e2e:
@@ -1,4 +1,3 @@
- To regenerate the legacy JavaScript SDK, run `./packages/sdk/js/script/build.ts`.
 - After changing the public Protocol or Server `HttpApi`, run `bun run generate` from `packages/client`. Do not edit `src/generated` or `src/generated-effect` directly.
 - Keep runtime dependencies directed from Schema to Core and Protocol, then from Core and Protocol to Server. Client runtime code may depend on Schema and Protocol but never Core or Server; `sdk-next` composes Client, Core, and Server.
 - Do not modify `packages/opencode` unless the user explicitly asks for V1 work. `packages/opencode` is the V1 implementation and is present for reference only. New implementation changes should land in the V2 package set: `packages/core`, `packages/cli`, `packages/server`, `packages/protocol`, `packages/schema`, and related generated client surfaces when required.
@@ -2,7 +2,7 @@
 exact = true
 # Only install newly resolved package versions published at least 3 days ago.
 minimumReleaseAge = 259200
-minimumReleaseAgeExcludes = ["@ai-sdk/amazon-bedrock", "@ai-sdk/anthropic", "@opentui/core", "@opentui/core-darwin-arm64", "@opentui/core-darwin-x64", "@opentui/core-linux-arm64", "@opentui/core-linux-arm64-musl", "@opentui/core-linux-x64", "@opentui/core-linux-x64-musl", "@opentui/core-win32-arm64", "@opentui/core-win32-x64", "@opentui/keymap", "@opentui/solid", "opentui-spinner", "gitlab-ai-provider", "opencode-gitlab-auth", "@ff-labs/fff-node", "@ff-labs/fff-bun", "@ff-labs/fff-bin-darwin-arm64", "@ff-labs/fff-bin-darwin-x64", "@ff-labs/fff-bin-linux-arm64-gnu", "@ff-labs/fff-bin-linux-arm64-musl", "@ff-labs/fff-bin-linux-x64-gnu", "@ff-labs/fff-bin-linux-x64-musl", "@ff-labs/fff-bin-win32-arm64", "@ff-labs/fff-bin-win32-x64", "@pierre/diffs", "@pierre/theming", "app-builder-lib", "dmg-builder", "electron-builder", "electron-publish"]
+minimumReleaseAgeExcludes = ["@ai-sdk/amazon-bedrock", "@ai-sdk/anthropic", "@opencode-ai/sdk", "@opentui/core", "@opentui/core-darwin-arm64", "@opentui/core-darwin-x64", "@opentui/core-linux-arm64", "@opentui/core-linux-arm64-musl", "@opentui/core-linux-x64", "@opentui/core-linux-x64-musl", "@opentui/core-win32-arm64", "@opentui/core-win32-x64", "@opentui/keymap", "@opentui/solid", "opentui-spinner", "gitlab-ai-provider", "opencode-gitlab-auth", "@ff-labs/fff-node", "@ff-labs/fff-bun", "@ff-labs/fff-bin-darwin-arm64", "@ff-labs/fff-bin-darwin-x64", "@ff-labs/fff-bin-linux-arm64-gnu", "@ff-labs/fff-bin-linux-arm64-musl", "@ff-labs/fff-bin-linux-x64-gnu", "@ff-labs/fff-bin-linux-x64-musl", "@ff-labs/fff-bin-win32-arm64", "@ff-labs/fff-bin-win32-x64", "@pierre/diffs", "@pierre/theming", "app-builder-lib", "dmg-builder", "electron-builder", "electron-publish"]

 [test]
 root = "./do-not-run-tests-from-root"
@@ -15,6 +15,6 @@
    "@actions/github": "6.0.1",
    "@octokit/graphql": "9.0.1",
    "@octokit/rest": "catalog:",
-    "@opencode-ai/sdk": "workspace:*"
+    "@opencode-ai/sdk": "1.18.5"
  }
 }
@@ -33,13 +33,12 @@
      "packages/*",
      "packages/console/*",
      "packages/stats/*",
-      "packages/sdk/js",
      "packages/slack"
    ],
    "catalog": {
-      "@effect/opentelemetry": "4.0.0-beta.98",
-      "@effect/platform-node": "4.0.0-beta.98",
-      "@effect/sql-sqlite-bun": "4.0.0-beta.98",
+      "@effect/opentelemetry": "4.0.0-beta.101",
+      "@effect/platform-node": "4.0.0-beta.101",
+      "@effect/sql-sqlite-bun": "4.0.0-beta.101",
      "@npmcli/arborist": "9.4.0",
      "@types/bun": "1.3.13",
      "@types/cross-spawn": "6.0.6",
@@ -51,6 +50,7 @@
      "@opentui/solid": "0.4.5",
      "@tanstack/solid-virtual": "3.13.32",
      "@shikijs/stream": "4.2.0",
+      "@standard-schema/spec": "1.1.0",
      "ulid": "3.0.1",
      "@kobalte/core": "0.13.11",
      "@corvu/drawer": "0.2.4",
@@ -69,7 +69,7 @@
      "dompurify": "3.3.1",
      "drizzle-kit": "1.0.0-rc.2",
      "drizzle-orm": "1.0.0-rc.2",
-      "effect": "4.0.0-beta.98",
+      "effect": "4.0.0-beta.101",
      "ai": "6.0.168",
      "cross-spawn": "7.0.6",
      "hono": "4.10.7",
@@ -124,7 +124,7 @@
    "@aws-sdk/client-s3": "3.933.0",
    "@opencode-ai/plugin": "workspace:*",
    "@opencode-ai/script": "workspace:*",
-    "@opencode-ai/sdk": "workspace:*",
+    "@opencode-ai/sdk": "1.18.5",
    "heap-snapshot-toolkit": "1.1.3",
    "typescript": "catalog:"
  },
@@ -152,7 +152,8 @@
    "@opentui/keymap": "catalog:",
    "@opentui/solid": "catalog:",
    "@types/bun": "catalog:",
-    "@types/node": "catalog:"
+    "@types/node": "catalog:",
+    "effect": "catalog:"
  },
  "patchedDependencies": {
    "@npmcli/agent@4.0.2": "patches/@npmcli%2Fagent@4.0.2.patch",
@@ -166,7 +167,7 @@
    "@ai-sdk/google@3.0.73": "patches/@ai-sdk%2Fgoogle@3.0.73.patch",
    "@pierre/trees@1.0.0-beta.4": "patches/@pierre%2Ftrees@1.0.0-beta.4.patch",
    "@modelcontextprotocol/sdk@1.29.0": "patches/@modelcontextprotocol%2Fsdk@1.29.0.patch",
-    "effect@4.0.0-beta.98": "patches/effect@4.0.0-beta.98.patch",
+    "effect@4.0.0-beta.101": "patches/effect@4.0.0-beta.101.patch",
    "@tanstack/virtual-core@3.17.3": "patches/@tanstack%2Fvirtual-core@3.17.3.patch"
  }
 }
@@ -207,7 +207,9 @@ Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "aut

 ### 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.
+`"auto"` places up to four breakpoints — the last tool definition, the first system part, the last system part when distinct, and the final message boundary. These expose successively larger reusable prefixes for tools, the base agent, project instructions, and the active conversation. The rolling final-message boundary is the load-bearing detail in tool loops: it advances on every request so the previous cache entry stays within Anthropic's 20-block lookback.
+
+Tools precede every system and conversation block in the provider prefix, so tool definitions must remain byte-stable and deterministically ordered for downstream breakpoints to remain reusable.

 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.

@@ -235,7 +237,7 @@ cache: {

 ### 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.
+Inline `CacheHint` on any text / system / tool / tool-result part overrides automatic placement. The auto policy preserves manual hints, counts them against Anthropic and Bedrock's four-breakpoint limit, and only fills the remaining slots.

 ```ts
 LLM.request({
@@ -251,8 +253,8 @@ LLM.request({

 | 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)             |
+| Anthropic Messages      | emits up to 4 `cache_control` markers (4-breakpoint cap enforced)         |
+| Bedrock Converse        | emits up to 4 `cachePoint` blocks (4-breakpoint cap enforced)             |
 | OpenAI Chat / Responses | no-op (implicit caching above 1024 tokens)                                |
 | Gemini                  | no-op (implicit caching on 2.5+; explicit `CachedContent` is out-of-band) |

@@ -2,32 +2,31 @@
 // the policy designates. Runs once at compile time, before the per-protocol
 // body builder, so the existing inline-hint lowering path handles the rest.
 //
-// The default `"auto"` shape places one breakpoint at the last tool definition,
-// one at the last system part, and one at the latest user message. This
-// matches what production agent harnesses (LangChain's caching middleware,
-// kern-ai's 10x cost-reduction playbook) converge on for tool-use loops: the
-// latest user message stays put while a single turn explodes into many
-// assistant/tool round-trips, so caching at that boundary lets every
-// intra-turn API call hit the prefix.
+// The default `"auto"` shape places breakpoints at the last tool definition,
+// the first and last distinct system parts, and the conversation tail. This
+// exposes reusable tool, base-agent, project, and session prefixes while
+// advancing the tail after each tool result keeps the previous cache entry
+// within Anthropic's 20-block lookback during long agent turns.
 //
-// Manual `cache: CacheHint` placements on individual parts are preserved —
-// this function only fills gaps the caller left empty.
+// Manual `cache: CacheHint` placements on individual parts are preserved and
+// count against the four-breakpoint budget; auto only fills remaining slots.
 import { CacheHint, type CachePolicy, type CachePolicyObject } from "./schema/options"
 import { LLMRequest, Message, ToolDefinition, type ContentPart } from "./schema/messages"

 const AUTO: CachePolicyObject = {
  tools: true,
  system: true,
-  messages: "latest-user-message",
+  messages: { tail: 1 },
 }

 const NONE: CachePolicyObject = {}
+const BREAKPOINT_CAP = 4

 // Resolution rules:
 //   - undefined   → "auto" — caching is on by default. The math favors it:
 //                   Anthropic 5m-cache write is 1.25x base, read is 0.1x,
 //                   so a single reuse within 5 minutes already wins.
-//   - "auto"      → tools + system + latest user msg.
+//   - "auto"      → tools + first/last system + final message boundary.
 //   - "none"      → no auto placement; manual `CacheHint`s still flow.
 //   - object form → exactly what the caller asked for.
 const resolve = (policy: CachePolicy | undefined): CachePolicyObject => {
@@ -44,18 +43,32 @@ const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse"]
 const makeHint = (ttlSeconds: number | undefined): CacheHint =>
  ttlSeconds !== undefined ? new CacheHint({ type: "ephemeral", ttlSeconds }) : new CacheHint({ type: "ephemeral" })

-const markLastTool = (tools: ReadonlyArray<ToolDefinition>, hint: CacheHint): ReadonlyArray<ToolDefinition> => {
+interface Budget {
+  remaining: number
+}
+
+const markLastTool = (
+  tools: ReadonlyArray<ToolDefinition>,
+  hint: CacheHint,
+  budget: Budget,
+): ReadonlyArray<ToolDefinition> => {
  if (tools.length === 0) return tools
  const last = tools.length - 1
-  if (tools[last]!.cache) return tools
+  if (tools[last]!.cache || budget.remaining === 0) return tools
+  budget.remaining -= 1
  return tools.map((tool, i) => (i === last ? new ToolDefinition({ ...tool, cache: hint }) : tool))
 }

-const markLastSystem = (system: LLMRequest["system"], hint: CacheHint): LLMRequest["system"] => {
+const markSystemBoundaries = (system: LLMRequest["system"], hint: CacheHint, budget: Budget): LLMRequest["system"] => {
  if (system.length === 0) return system
-  const last = system.length - 1
-  if (system[last]!.cache) return system
-  return system.map((part, i) => (i === last ? { ...part, cache: hint } : part))
+  let changed = false
+  const next = system.map((part, index) => {
+    if ((index !== 0 && index !== system.length - 1) || part.cache || budget.remaining === 0) return part
+    budget.remaining -= 1
+    changed = true
+    return { ...part, cache: hint }
+  })
+  return changed ? next : system
 }

 const lastIndexOfRole = (messages: ReadonlyArray<Message>, role: Message["role"]): number =>
@@ -64,14 +77,20 @@ const lastIndexOfRole = (messages: ReadonlyArray<Message>, role: Message["role"]
 // Mark the last text part of `messages[index]`. If no text part exists, mark
 // the last content part regardless of type — that's the breakpoint position
 // in tool-result-only messages too.
-const markMessageAt = (messages: ReadonlyArray<Message>, index: number, hint: CacheHint): ReadonlyArray<Message> => {
+const markMessageAt = (
+  messages: ReadonlyArray<Message>,
+  index: number,
+  hint: CacheHint,
+  budget: Budget,
+): ReadonlyArray<Message> => {
  if (index < 0 || index >= messages.length) return messages
  const target = messages[index]!
  if (target.content.length === 0) return messages
  const lastTextIndex = target.content.findLastIndex((part) => part.type === "text")
  const markAt = lastTextIndex >= 0 ? lastTextIndex : target.content.length - 1
  const existing = target.content[markAt]!
-  if ("cache" in existing && existing.cache) return messages
+  if (("cache" in existing && existing.cache) || budget.remaining === 0) return messages
+  budget.remaining -= 1
  const nextContent = target.content.map((part, i) => (i === markAt ? ({ ...part, cache: hint } as ContentPart) : part))
  const next = new Message({ ...target, content: nextContent })
  // Single pass over `messages`, substituting the one updated entry. Long
@@ -86,25 +105,42 @@ const markMessages = (
  messages: ReadonlyArray<Message>,
  strategy: NonNullable<CachePolicyObject["messages"]>,
  hint: CacheHint,
+  budget: Budget,
 ): ReadonlyArray<Message> => {
  if (messages.length === 0) return messages
-  if (strategy === "latest-user-message") return markMessageAt(messages, lastIndexOfRole(messages, "user"), hint)
-  if (strategy === "latest-assistant") return markMessageAt(messages, lastIndexOfRole(messages, "assistant"), hint)
+  if (strategy === "latest-user-message")
+    return markMessageAt(messages, lastIndexOfRole(messages, "user"), hint, budget)
+  if (strategy === "latest-assistant")
+    return markMessageAt(messages, lastIndexOfRole(messages, "assistant"), hint, budget)
  const start = Math.max(0, messages.length - strategy.tail)
  let next = messages
-  for (let i = start; i < messages.length; i++) next = markMessageAt(next, i, hint)
+  for (let i = start; i < messages.length; i++) next = markMessageAt(next, i, hint, budget)
  return next
 }

+const countHints = (request: LLMRequest) =>
+  request.tools.reduce((count, tool) => count + (tool.cache === undefined ? 0 : 1), 0) +
+  request.system.reduce((count, part) => count + (part.cache === undefined ? 0 : 1), 0) +
+  request.messages.reduce(
+    (count, message) =>
+      count +
+      message.content.reduce(
+        (contentCount, part) => contentCount + ("cache" in part && part.cache !== undefined ? 1 : 0),
+        0,
+      ),
+    0,
+  )
+
 export const applyCachePolicy = (request: LLMRequest): LLMRequest => {
  if (!RESPECTS_INLINE_HINTS.has(request.model.route.id)) return request
  const policy = resolve(request.cache)
  if (!policy.tools && !policy.system && !policy.messages) return request

  const hint = makeHint(policy.ttlSeconds)
-  const tools = policy.tools ? markLastTool(request.tools, hint) : request.tools
-  const system = policy.system ? markLastSystem(request.system, hint) : request.system
-  const messages = policy.messages ? markMessages(request.messages, policy.messages, hint) : request.messages
+  const budget = { remaining: Math.max(0, BREAKPOINT_CAP - countHints(request)) }
+  const tools = policy.tools ? markLastTool(request.tools, hint, budget) : request.tools
+  const system = policy.system ? markSystemBoundaries(request.system, hint, budget) : request.system
+  const messages = policy.messages ? markMessages(request.messages, policy.messages, hint, budget) : request.messages

  if (tools === request.tools && system === request.system && messages === request.messages) return request
  return LLMRequest.update(request, { tools, system, messages })
@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect"
+import { Tool } from "@opencode-ai/schema/tool"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
@@ -7,8 +8,10 @@ import { Protocol } from "../route/protocol"
 import {
  LLMError,
  LLMEvent,
+  mergeJsonRecords,
  Usage,
  type CacheHint,
+  type FinishReasonDetails,
  type FinishReason,
  type JsonSchema,
  type LLMRequest,
@@ -17,7 +20,6 @@ import {
  type ProviderMetadata,
  type ToolCallPart,
  type ToolDefinition,
-  type ToolContent,
  type ToolResultPart,
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
@@ -233,12 +235,27 @@ const AnthropicBodyFields = {
 export const AnthropicMessagesBody = Schema.Struct(AnthropicBodyFields)
 export type AnthropicMessagesBody = Schema.Schema.Type<typeof AnthropicMessagesBody>

-const AnthropicUsage = Schema.Struct({
-  input_tokens: Schema.optional(Schema.Number),
-  output_tokens: Schema.optional(Schema.Number),
-  cache_creation_input_tokens: optionalNull(Schema.Number),
-  cache_read_input_tokens: optionalNull(Schema.Number),
-})
+const AnthropicUsage = Schema.StructWithRest(
+  Schema.Struct({
+    input_tokens: Schema.optional(Schema.Number),
+    output_tokens: Schema.optional(Schema.Number),
+    cache_creation_input_tokens: optionalNull(Schema.Number),
+    cache_read_input_tokens: optionalNull(Schema.Number),
+    server_tool_use: optionalNull(
+      Schema.StructWithRest(
+        Schema.Struct({ web_search_requests: Schema.optional(Schema.Number) }),
+        [Schema.Record(Schema.String, Schema.Unknown)],
+      ),
+    ),
+    output_tokens_details: optionalNull(
+      Schema.StructWithRest(
+        Schema.Struct({ thinking_tokens: Schema.optional(Schema.Number) }),
+        [Schema.Record(Schema.String, Schema.Unknown)],
+      ),
+    ),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+)
 type AnthropicUsage = Schema.Schema.Type<typeof AnthropicUsage>

 const AnthropicStreamBlock = Schema.Struct({
@@ -288,7 +305,12 @@ type AnthropicEvent = Schema.Schema.Type<typeof AnthropicEvent>

 interface ParserState {
  readonly tools: ToolStream.State<number>
+  readonly reasoningSignatures: Readonly<Record<number, string>>
  readonly usage?: Usage
+  readonly pendingFinish?: {
+    readonly reason: FinishReasonDetails
+    readonly providerMetadata?: ProviderMetadata
+  }
  readonly lifecycle: Lifecycle.State
 }

@@ -403,7 +425,7 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (part: Me
 // 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,
+  item: Tool.Content,
 ) {
  if (item.type === "text") return { type: "text" as const, text: item.text } satisfies AnthropicTextBlock
  return yield* lowerMedia({ type: "media", mediaType: item.mime, data: item.uri, filename: item.name })
@@ -414,7 +436,7 @@ const lowerToolResultContent = Effect.fn("AnthropicMessages.lowerToolResultConte
  // 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
+  const content: ReadonlyArray<Tool.Content> = part.result.value
  return yield* Effect.forEach(content, lowerToolResultContentItem)
 })

@@ -660,9 +682,8 @@ const mapFinishReason = (reason: string | null | undefined): FinishReason => {
 // `input_tokens` is the *non-cached* count per the Messages API docs, with
 // cache reads and writes as separate fields. We sum them to derive the
 // inclusive `inputTokens` the rest of the contract expects. Extended
-// thinking tokens are *not* broken out by Anthropic — they're billed as
-// part of `output_tokens`, so `reasoningTokens` stays `undefined` and
-// `outputTokens` carries the combined total.
+// thinking tokens are included in `output_tokens`; newer responses also
+// expose that subset through `output_tokens_details.thinking_tokens`.
 const mapUsage = (usage: AnthropicUsage | undefined): Usage | undefined => {
  if (!usage) return undefined
  const nonCached = usage.input_tokens
@@ -675,6 +696,7 @@ const mapUsage = (usage: AnthropicUsage | undefined): Usage | undefined => {
    nonCachedInputTokens: nonCached,
    cacheReadInputTokens: cacheRead,
    cacheWriteInputTokens: cacheWrite,
+    reasoningTokens: usage.output_tokens_details?.thinking_tokens,
    totalTokens: ProviderShared.totalTokens(inputTokens, usage.output_tokens, undefined),
    providerMetadata: { anthropic: usage },
  })
@@ -693,18 +715,18 @@ const mergeUsage = (left: Usage | undefined, right: Usage | undefined) => {
  const cacheWriteInputTokens = right.cacheWriteInputTokens ?? left.cacheWriteInputTokens
  const inputTokens = ProviderShared.sumTokens(nonCachedInputTokens, cacheReadInputTokens, cacheWriteInputTokens)
  const outputTokens = right.outputTokens ?? left.outputTokens
+  const reasoningTokens = right.reasoningTokens ?? left.reasoningTokens
  return new Usage({
    inputTokens,
    outputTokens,
    nonCachedInputTokens,
    cacheReadInputTokens,
    cacheWriteInputTokens,
+    reasoningTokens,
    totalTokens: ProviderShared.totalTokens(inputTokens, outputTokens, undefined),
    providerMetadata: {
-      anthropic: {
-        ...left.providerMetadata?.["anthropic"],
-        ...right.providerMetadata?.["anthropic"],
-      },
+      anthropic:
+        mergeJsonRecords(left.providerMetadata?.["anthropic"], right.providerMetadata?.["anthropic"]) ?? {},
    },
  })
 }
@@ -763,6 +785,10 @@ const onContentBlockStart = (state: ParserState, event: AnthropicEvent): StepRes
        tools: ToolStream.start(state.tools, event.index, {
          id: block.id ?? String(event.index),
          name: block.name ?? "",
+          input:
+            block.input !== undefined && (!ProviderShared.isRecord(block.input) || Object.keys(block.input).length > 0)
+              ? ProviderShared.encodeJson(block.input)
+              : undefined,
          providerExecuted: block.type === "server_tool_use",
        }),
      },
@@ -777,20 +803,31 @@ const onContentBlockStart = (state: ParserState, event: AnthropicEvent): StepRes
    ]
  }

-  if (block.type === "text" && block.text) {
+  if (block.type === "text" && block.text !== undefined) {
    const events: LLMEvent[] = []
+    const id = `text-${event.index ?? 0}`
+    const lifecycle = Lifecycle.textStart(state.lifecycle, events, id)
    return [
-      { ...state, lifecycle: Lifecycle.textDelta(state.lifecycle, events, `text-${event.index ?? 0}`, block.text) },
+      { ...state, lifecycle: block.text ? Lifecycle.textDelta(lifecycle, events, id, block.text) : lifecycle },
      events,
    ]
  }

-  if (block.type === "thinking" && block.thinking) {
+  if (block.type === "thinking" && block.thinking !== undefined) {
    const events: LLMEvent[] = []
+    const id = `reasoning-${event.index ?? 0}`
+    const providerMetadata = block.signature === undefined ? undefined : anthropicMetadata({ signature: block.signature })
+    const lifecycle = Lifecycle.reasoningStart(state.lifecycle, events, id, providerMetadata)
    return [
      {
        ...state,
-        lifecycle: Lifecycle.reasoningDelta(state.lifecycle, events, `reasoning-${event.index ?? 0}`, block.thinking),
+        lifecycle: block.thinking
+          ? Lifecycle.reasoningDelta(lifecycle, events, id, block.thinking, providerMetadata)
+          : lifecycle,
+        reasoningSignatures:
+          event.index === undefined || block.signature === undefined
+            ? state.reasoningSignatures
+            : { ...state.reasoningSignatures, [event.index]: block.signature },
      },
      events,
    ]
@@ -799,7 +836,7 @@ const onContentBlockStart = (state: ParserState, event: AnthropicEvent): StepRes
  // Redacted thinking surfaces as an empty reasoning part carrying the opaque
  // payload as `redactedData` metadata (same model as Vercel's
  // @ai-sdk/anthropic). The existing content_block_stop closes the part.
-  if (block.type === "redacted_thinking" && block.data) {
+  if (block.type === "redacted_thinking" && block.data !== undefined) {
    const events: LLMEvent[] = []
    return [
      {
@@ -847,18 +884,13 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
  }

  if (delta?.type === "signature_delta" && delta.signature) {
-    const events: LLMEvent[] = []
+    const index = event.index ?? 0
    return [
      {
        ...state,
-        lifecycle: Lifecycle.reasoningEnd(
-          state.lifecycle,
-          events,
-          `reasoning-${event.index ?? 0}`,
-          anthropicMetadata({ signature: delta.signature }),
-        ),
+        reasoningSignatures: { ...state.reasoningSignatures, [index]: delta.signature },
      },
-      events,
+      NO_EVENTS,
    ] satisfies StepResult
  }

@@ -889,31 +921,53 @@ const onContentBlockStop = Effect.fn("AnthropicMessages.onContentBlockStop")(fun
  const result = yield* ToolStream.finish(ADAPTER, state.tools, event.index)
  const events: LLMEvent[] = []
  const resultEvents = result.events ?? []
+  const signature = state.reasoningSignatures[event.index]
  const lifecycle = resultEvents.length
    ? Lifecycle.stepStart(state.lifecycle, events)
    : Lifecycle.reasoningEnd(
        Lifecycle.textEnd(state.lifecycle, events, `text-${event.index}`),
        events,
        `reasoning-${event.index}`,
+        signature === undefined ? undefined : anthropicMetadata({ signature }),
      )
  events.push(...resultEvents)
-  return [{ ...state, lifecycle, tools: result.tools }, events] satisfies StepResult
+  const reasoningSignatures = { ...state.reasoningSignatures }
+  delete reasoningSignatures[event.index]
+  return [{ ...state, lifecycle, tools: result.tools, reasoningSignatures }, events] satisfies StepResult
 })

 const onMessageDelta = (state: ParserState, event: AnthropicEvent): StepResult => {
  const usage = mergeUsage(state.usage, mapUsage(event.usage))
+  return [
+    {
+      ...state,
+      usage,
+      pendingFinish: {
+        reason: {
+          normalized: mapFinishReason(event.delta?.stop_reason),
+          raw: event.delta?.stop_reason ?? undefined,
+        },
+        providerMetadata:
+          event.delta?.stop_sequence === null || event.delta?.stop_sequence === undefined
+            ? undefined
+            : anthropicMetadata({ stopSequence: event.delta.stop_sequence }),
+      },
+    },
+    NO_EVENTS,
+  ]
+}
+
+const onMessageStop = (state: ParserState): StepResult => {
  const events: LLMEvent[] = []
  const lifecycle = Lifecycle.finish(state.lifecycle, events, {
-    reason: {
-      normalized: mapFinishReason(event.delta?.stop_reason),
-      raw: event.delta?.stop_reason ?? undefined,
+    reason: state.pendingFinish?.reason ?? {
+      normalized: "unknown",
+      raw: undefined,
    },
-    usage,
-    providerMetadata: event.delta?.stop_sequence
-      ? anthropicMetadata({ stopSequence: event.delta.stop_sequence })
-      : undefined,
+    usage: state.usage,
+    providerMetadata: state.pendingFinish?.providerMetadata,
  })
-  return [{ ...state, lifecycle, usage }, events]
+  return [{ ...state, lifecycle }, events]
 }

 // Prefix `error.type` so overloads, rate limits, and quota errors are visible
@@ -938,6 +992,7 @@ const step = (state: ParserState, event: AnthropicEvent) => {
  if (event.type === "content_block_delta") return onContentBlockDelta(state, event)
  if (event.type === "content_block_stop") return onContentBlockStop(state, event)
  if (event.type === "message_delta") return Effect.succeed(onMessageDelta(state, event))
+  if (event.type === "message_stop") return Effect.succeed(onMessageStop(state))
  if (event.type === "error") return onError(event)
  return Effect.succeed<StepResult>([state, NO_EVENTS])
 }
@@ -958,7 +1013,11 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: Protocol.jsonEvent(AnthropicEvent),
-    initial: () => ({ tools: ToolStream.empty<number>(), lifecycle: Lifecycle.initial() }),
+    initial: () => ({
+      tools: ToolStream.empty<number>(),
+      reasoningSignatures: {},
+      lifecycle: Lifecycle.initial(),
+    }),
    step,
  },
 })
@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect"
+import { Tool } from "@opencode-ai/schema/tool"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
@@ -16,7 +17,6 @@ import {
  type TextPart,
  type ToolCallPart,
  type ToolDefinition,
-  type ToolContent,
 } from "../schema"
 import { JsonObject, optionalArray, ProviderShared } from "./shared"
 import { GeminiToolSchema } from "./utils/gemini-tool-schema"
@@ -289,7 +289,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
        })
        continue
      }
-      const content: ReadonlyArray<ToolContent> = part.result.value
+      const content: ReadonlyArray<Tool.Content> = part.result.value
      const text = content.filter((item) => item.type === "text").map((item) => item.text)
      const media: GeminiInlineDataPart[] = []
      for (const item of content) {
@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect"
+import type { Content } from "@opencode-ai/schema/tool"
 import { HttpTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
@@ -14,7 +15,6 @@ import {
  type TextPart,
  type ToolCallPart,
  type ToolDefinition,
-  type ToolContent,
  type ToolResultPart,
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
@@ -55,6 +55,9 @@ const OpenResponsesOutputText = Schema.Struct({
  text: Schema.String,
 })

+export const MessagePhase = Schema.Literals(["commentary", "final_answer"])
+type MessagePhase = Schema.Schema.Type<typeof MessagePhase>
+
 const OpenResponsesReasoningSummaryText = Schema.Struct({
  type: Schema.tag("summary_text"),
  text: Schema.String,
@@ -86,10 +89,14 @@ const OpenResponsesFunctionCallOutput = Schema.Union([
  Schema.Array(OpenResponsesFunctionCallOutputContent),
 ])

-const OpenResponsesInputItem = Schema.Union([
+export const InputItem = Schema.Union([
  Schema.Struct({ role: Schema.tag("system"), content: Schema.String }),
  Schema.Struct({ role: Schema.tag("user"), content: Schema.Array(OpenResponsesInputContent) }),
-  Schema.Struct({ role: Schema.tag("assistant"), content: Schema.Array(OpenResponsesOutputText) }),
+  Schema.Struct({
+    role: Schema.tag("assistant"),
+    content: Schema.Array(OpenResponsesOutputText),
+    phase: Schema.optionalKey(MessagePhase),
+  }),
  OpenResponsesReasoningItem,
  OpenResponsesItemReference,
  Schema.Struct({
@@ -104,7 +111,14 @@ const OpenResponsesInputItem = Schema.Union([
    output: OpenResponsesFunctionCallOutput,
  }),
 ])
-type OpenResponsesInputItem = Schema.Schema.Type<typeof OpenResponsesInputItem>
+type OpenResponsesInputItem = Schema.Schema.Type<typeof InputItem>
+type LoweredInputItem =
+  | OpenResponsesInputItem
+  | {
+      readonly role: "assistant"
+      readonly content: ReadonlyArray<{ readonly type: "output_text"; readonly text: string }>
+      readonly phase?: MessagePhase | null
+    }

 // Mutable counterpart of the schema reasoning item so `lowerMessages` can fold
 // multiple streamed summary parts into the same item before flushing.
@@ -135,7 +149,7 @@ export const ToolChoice = Schema.Union([
 // transports in sync without a destructure-and-strip dance.
 export const coreFields = {
  model: Schema.String,
-  input: Schema.Array(OpenResponsesInputItem),
+  input: Schema.Array(InputItem),
  instructions: Schema.optional(Schema.String),
  tools: optionalArray(Tool),
  tool_choice: Schema.optional(ToolChoice),
@@ -167,7 +181,12 @@ export type OpenResponsesBody = Schema.Schema.Type<typeof OpenResponsesBody>

 const OpenResponsesUsage = Schema.Struct({
  input_tokens: Schema.optional(Schema.Number),
-  input_tokens_details: optionalNull(Schema.Struct({ cached_tokens: Schema.optional(Schema.Number) })),
+  input_tokens_details: optionalNull(
+    Schema.Struct({
+      cached_tokens: Schema.optional(Schema.Number),
+      cache_write_tokens: Schema.optional(Schema.Number),
+    }),
+  ),
  output_tokens: Schema.optional(Schema.Number),
  output_tokens_details: optionalNull(Schema.Struct({ reasoning_tokens: Schema.optional(Schema.Number) })),
  total_tokens: Schema.optional(Schema.Number),
@@ -201,6 +220,7 @@ export const Event = Schema.StructWithRest(
  Schema.Struct({
    type: Schema.String,
    delta: Schema.optional(Schema.String),
+    text: Schema.optional(Schema.String),
    item_id: Schema.optional(Schema.String),
    summary_index: Schema.optional(Schema.Number),
    item: Schema.optional(StreamItem),
@@ -233,6 +253,7 @@ export interface Extension {
    readonly media: ProviderShared.ValidatedMedia
    readonly request: LLMRequest
  }) => MediaInput | undefined
+  readonly messagePhase?: (value: unknown) => MessagePhase | null | undefined
 }

 const BASE: Extension = { id: ADAPTER, name: NAME }
@@ -244,6 +265,9 @@ export interface ParserState {
  readonly tools: ToolStream.State<string>
  readonly hasFunctionCall: boolean
  readonly lifecycle: Lifecycle.State
+  readonly messageItems: ReadonlySet<string>
+  readonly messagePhase: (value: unknown) => MessagePhase | null | undefined
+  readonly messagePhases: Readonly<Record<string, MessagePhase | null>>
  readonly reasoningItems: Readonly<Record<string, ReasoningStreamItem>>
  readonly store: boolean | undefined
 }
@@ -347,7 +371,7 @@ const lowerUserContent = Effect.fn("OpenResponses.lowerUserContent")(function* (
 // 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("OpenResponses.lowerToolResultContentItem")(function* (
-  item: ToolContent,
+  item: Content,
  request: LLMRequest,
  extension: Extension,
 ) {
@@ -368,14 +392,14 @@ const lowerToolResultOutput = Effect.fn("OpenResponses.lowerToolResultOutput")(f
  // 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
+  const content: ReadonlyArray<Content> = part.result.value
  return yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, extension))
 })

 const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (request: LLMRequest, extension: Extension) {
-  const system: OpenResponsesInputItem[] =
+  const system: LoweredInputItem[] =
    request.system.length === 0 ? [] : [{ role: "system", content: ProviderShared.joinText(request.system) }]
-  const input: OpenResponsesInputItem[] = [...system]
+  const input: LoweredInputItem[] = [...system]
  const store = OpenResponsesOptions.resolve(request).store
  const providerMetadataKey = request.model.route.providerMetadataKey ?? "openresponses"

@@ -407,7 +431,27 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
      const hostedToolReferences = new Set<string>()
      const flushText = () => {
        if (content.length === 0) return
-        input.push({ role: "assistant", content: content.map((part) => ({ type: "output_text", text: part.text })) })
+        const groups = content.reduce<Array<{ phase: MessagePhase | null | undefined; parts: TextPart[] }>>(
+          (groups, part) => {
+            const metadata = part.providerMetadata?.[providerMetadataKey]
+            const phase =
+              ProviderShared.isRecord(metadata)
+                ? messagePhase(metadata.phase, extension)
+                : undefined
+            const group = groups.at(-1)
+            if (group && group.phase === phase) group.parts.push(part)
+            else groups.push({ phase, parts: [part] })
+            return groups
+          },
+          [],
+        )
+        input.push(
+          ...groups.map((group) => ({
+            role: "assistant" as const,
+            content: group.parts.map((part) => ({ type: "output_text" as const, text: part.text })),
+            ...(group.phase === undefined ? {} : { phase: group.phase }),
+          })),
+        )
        content.splice(0, content.length)
      }
      for (const part of message.content) {
@@ -452,7 +496,7 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
          if (store !== false && itemID && !hostedToolReferences.has(itemID))
            input.push({ type: "item_reference", id: itemID })
          if (store === false && part.result.type === "content") {
-            const content: ReadonlyArray<ToolContent> = part.result.value
+            const content: ReadonlyArray<Content> = part.result.value
            input.push({
              role: "user",
              content: yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, extension)),
@@ -508,9 +552,9 @@ const lowerOptions = (request: LLMRequest) => {
  }
 }

-export const fromRequest = Effect.fn("OpenResponses.fromRequest")(function* (
+export const fromRequestWithExtension = Effect.fn("OpenResponses.fromRequestWithExtension")(function* (
  request: LLMRequest,
-  extension: Extension = BASE,
+  extension: Extension,
 ) {
  const generation = request.generation
  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
@@ -536,23 +580,31 @@ export const fromRequest = Effect.fn("OpenResponses.fromRequest")(function* (
  }
 })

+const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenResponsesBody))
+
+export const fromRequest = Effect.fn("OpenResponses.fromRequest")(function* (request: LLMRequest) {
+  return yield* decodeBody(yield* fromRequestWithExtension(request, BASE))
+})
+
 // =============================================================================
 // Stream Parsing
 // =============================================================================
 // Responses APIs report `input_tokens` (inclusive total) with a
-// `cached_tokens` subset, and `output_tokens` (inclusive total) with a
-// `reasoning_tokens` subset. Pass the totals through and derive the
+// cached-read and cache-write subsets, and `output_tokens` (inclusive total)
+// with a `reasoning_tokens` subset. Pass the totals through and derive the
 // non-cached breakdown.
 const mapUsage = (usage: OpenResponsesUsage | null | undefined, providerMetadataKey: string) => {
  if (!usage) return undefined
  const cached = usage.input_tokens_details?.cached_tokens
+  const cacheWrite = usage.input_tokens_details?.cache_write_tokens
  const reasoning = usage.output_tokens_details?.reasoning_tokens
-  const nonCached = ProviderShared.subtractTokens(usage.input_tokens, cached)
+  const nonCached = ProviderShared.subtractTokens(usage.input_tokens, ProviderShared.sumTokens(cached, cacheWrite))
  return new Usage({
    inputTokens: usage.input_tokens,
    outputTokens: usage.output_tokens,
    nonCachedInputTokens: nonCached,
    cacheReadInputTokens: cached,
+    cacheWriteInputTokens: cacheWrite,
    reasoningTokens: reasoning,
    totalTokens: ProviderShared.totalTokens(usage.input_tokens, usage.output_tokens, usage.total_tokens),
    providerMetadata: { [providerMetadataKey]: usage },
@@ -588,24 +640,30 @@ const NO_EVENTS: StepResult["1"] = []
 const TERMINAL_TYPES = new Set(["response.completed", "response.incomplete", "response.failed"])
 export const terminal = (event: Event) => TERMINAL_TYPES.has(event.type)

-const onOutputTextDelta = (state: ParserState, event: Event): StepResult => {
+const onOutputTextDelta = (state: ParserState, event: Event, id: string): StepResult => {
  if (!event.delta) return [state, NO_EVENTS]
  const events: LLMEvent[] = []
+  const phase = state.messagePhases[id]
+  const metadata = phase === undefined ? undefined : providerMetadata(state, { phase })
+  const lifecycle = Lifecycle.textStart(state.lifecycle, events, id, metadata)
  return [
-    { ...state, lifecycle: Lifecycle.textDelta(state.lifecycle, events, event.item_id ?? "text-0", event.delta) },
+    { ...state, lifecycle: Lifecycle.textDelta(lifecycle, events, id, event.delta) },
    events,
  ]
 }

-const onOutputTextDone = (state: ParserState, event: Event): StepResult => {
+const onOutputTextDone = (state: ParserState, event: Event, id: string): StepResult => {
+  if (state.messageItems.has(id)) {
+    if (state.lifecycle.text.has(id) || event.text === undefined) return [state, NO_EVENTS]
+    return onOutputTextDelta(state, { ...event, delta: event.text }, id)
+  }
  const events: LLMEvent[] = []
-  return [{ ...state, lifecycle: Lifecycle.textEnd(state.lifecycle, events, event.item_id ?? "text-0") }, events]
+  return [{ ...state, lifecycle: Lifecycle.textEnd(state.lifecycle, events, id) }, events]
 }

-export const onReasoningDelta = (state: ParserState, event: Event): StepResult => {
+export const onReasoningDelta = (state: ParserState, event: Event, itemID: string): StepResult => {
  if (!event.delta) return [state, NO_EVENTS]
  const events: LLMEvent[] = []
-  const itemID = event.item_id ?? "reasoning-0"
  const id =
    event.summary_index !== undefined || state.reasoningItems[itemID] ? `${itemID}:${event.summary_index ?? 0}` : itemID
  return [
@@ -636,6 +694,18 @@ const reasoningMetadata = (state: ParserState, item: StreamItem & { id: string }
 // best-effort, not guaranteed.
 const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
  const item = event.item
+  if (item?.type === "message" && item.id)
+    return [
+      {
+        ...state,
+        messageItems: new Set([...state.messageItems, item.id]),
+        messagePhases: (() => {
+          const phase = state.messagePhase(item.phase)
+          return phase === undefined ? state.messagePhases : { ...state.messagePhases, [item.id]: phase }
+        })(),
+      },
+      NO_EVENTS,
+    ]
  if (item && isReasoningItem(item)) {
    const events: LLMEvent[] = []
    return [
@@ -792,7 +862,28 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
  const item = event.item
  if (!item) return [state, NO_EVENTS] satisfies StepResult

-  if (item.type === "message" && item.id) return onOutputTextDone(state, { ...event, item_id: item.id })
+  if (item.type === "message" && item.id) {
+    const itemPhase = state.messagePhase(item.phase)
+    const phase = itemPhase === undefined ? state.messagePhases[item.id] : itemPhase
+    const events: LLMEvent[] = []
+    const messageItems = new Set(state.messageItems)
+    messageItems.delete(item.id)
+    const { [item.id]: _phase, ...messagePhases } = state.messagePhases
+    return [
+      {
+        ...state,
+        lifecycle: Lifecycle.textEnd(
+          state.lifecycle,
+          events,
+          item.id,
+          phase === undefined ? undefined : providerMetadata(state, { phase }),
+        ),
+        messageItems,
+        messagePhases,
+      },
+      events,
+    ] satisfies StepResult
+  }

  if (item.type === "function_call") {
    if (!item.id || !item.call_id || !item.name) return [state, NO_EVENTS] satisfies StepResult
@@ -892,19 +983,41 @@ const providerError = (state: ParserState, event: Event, fallback: string) => {
 }

 export const step = (state: ParserState, event: Event) => {
-  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))
-  if (event.type === "response.reasoning.delta" || event.type === "response.reasoning_summary_text.delta")
-    return Effect.succeed(onReasoningDelta(state, event))
-  if (event.type === "response.reasoning.done" || event.type === "response.reasoning_summary_text.done")
+  if (event.type === "response.output_text.delta" || event.type === "response.output_text.done") {
+    if (!event.item_id) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
+    return Effect.succeed(
+      event.type === "response.output_text.delta"
+        ? onOutputTextDelta(state, event, event.item_id)
+        : onOutputTextDone(state, event, event.item_id),
+    )
+  }
+  if (event.type === "response.reasoning.delta" || event.type === "response.reasoning_summary_text.delta") {
+    if (!event.item_id) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
+    return Effect.succeed(onReasoningDelta(state, event, event.item_id))
+  }
+  if (event.type === "response.reasoning.done" || event.type === "response.reasoning_summary_text.done") {
+    if (!event.item_id) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
    return Effect.succeed(onReasoningDone(state, event))
+  }
  if (event.type === "response.reasoning_summary_part.added")
-    return Effect.succeed(onReasoningSummaryPartAdded(state, event))
+    return event.item_id
+      ? Effect.succeed(onReasoningSummaryPartAdded(state, event))
+      : ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
  if (event.type === "response.reasoning_summary_part.done")
-    return Effect.succeed(onReasoningSummaryPartDone(state, event))
-  if (event.type === "response.output_item.added") return Effect.succeed(onOutputItemAdded(state, event))
+    return event.item_id
+      ? Effect.succeed(onReasoningSummaryPartDone(state, event))
+      : ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
+  if (event.type === "response.output_item.added") {
+    if (event.item?.type === "message" && !event.item.id)
+      return ProviderShared.eventError(state.id, `${event.type} message is missing id`)
+    return Effect.succeed(onOutputItemAdded(state, event))
+  }
  if (event.type === "response.function_call_arguments.delta") return onFunctionCallArgumentsDelta(state, event)
-  if (event.type === "response.output_item.done") return onOutputItemDone(state, event)
+  if (event.type === "response.output_item.done") {
+    if (event.item?.type === "message" && !event.item.id)
+      return ProviderShared.eventError(state.id, `${event.type} message is missing id`)
+    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 providerError(state, event, `${state.name} response failed`)
@@ -926,10 +1039,18 @@ export const initial = (request: LLMRequest, extension: Extension = BASE): Parse
  hasFunctionCall: false,
  tools: ToolStream.empty<string>(),
  lifecycle: Lifecycle.initial(),
+  messageItems: new Set<string>(),
+  messagePhase: (value) => messagePhase(value, extension),
+  messagePhases: {},
  reasoningItems: {},
  store: OpenResponsesOptions.resolve(request).store,
 })

+const messagePhase = (value: unknown, extension: Extension): MessagePhase | null | undefined => {
+  if (value === "commentary" || value === "final_answer") return value
+  return extension.messagePhase?.(value)
+}
+
 export const protocol = Protocol.make({
  id: ADAPTER,
  body: {
@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect"
+import { Tool } from "@opencode-ai/schema/tool"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
@@ -17,7 +18,6 @@ import {
  type TextPart,
  type ToolCallPart,
  type ToolDefinition,
-  type ToolContent,
 } from "../schema"
 import { classifyProviderFailure } from "../provider-error"
 import { isRecord, JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
@@ -131,6 +131,7 @@ const OpenAIChatUsage = Schema.Struct({
  prompt_tokens_details: optionalNull(
    Schema.Struct({
      cached_tokens: Schema.optional(Schema.Number),
+      cache_write_tokens: Schema.optional(Schema.Number),
    }),
  ),
  completion_tokens_details: optionalNull(
@@ -334,7 +335,7 @@ const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (m
      messages.push({ role: "tool", tool_call_id: part.id, content: ProviderShared.toolResultText(part) })
      continue
    }
-    const content: ReadonlyArray<ToolContent> = part.result.value
+    const content: ReadonlyArray<Tool.Content> = part.result.value
    const text = content.filter((item) => item.type === "text").map((item) => item.text)
    messages.push({ role: "tool", tool_call_id: part.id, content: text.join("\n") })
    const files = content.filter((item) => item.type === "file")
@@ -453,20 +454,22 @@ const mapFinishReason = (reason: string | null | undefined): FinishReason => {
 }

 // OpenAI Chat reports `prompt_tokens` (inclusive total) with a
-// `cached_tokens` subset, and `completion_tokens` (inclusive total) with
-// a `reasoning_tokens` subset. We pass the inclusive totals through and
-// derive the non-cached breakdown so the `LLM.Usage` contract is
+// cached-read and cache-write subsets, and `completion_tokens` (inclusive
+// total) with a `reasoning_tokens` subset. We pass the inclusive totals
+// through and derive the non-cached breakdown so the `LLM.Usage` contract is
 // satisfied on both sides.
 const mapUsage = (usage: OpenAIChatEvent["usage"]): Usage | undefined => {
  if (!usage) return undefined
  const cached = usage.prompt_tokens_details?.cached_tokens
+  const cacheWrite = usage.prompt_tokens_details?.cache_write_tokens
  const reasoning = usage.completion_tokens_details?.reasoning_tokens
-  const nonCached = ProviderShared.subtractTokens(usage.prompt_tokens, cached)
+  const nonCached = ProviderShared.subtractTokens(usage.prompt_tokens, ProviderShared.sumTokens(cached, cacheWrite))
  return new Usage({
    inputTokens: usage.prompt_tokens,
    outputTokens: usage.completion_tokens,
    nonCachedInputTokens: nonCached,
    cacheReadInputTokens: cached,
+    cacheWriteInputTokens: cacheWrite,
    reasoningTokens: reasoning,
    totalTokens: ProviderShared.totalTokens(usage.prompt_tokens, usage.completion_tokens, usage.total_tokens),
    providerMetadata: { openai: usage },
@@ -35,8 +35,18 @@ const OpenAIResponsesToolChoice = Schema.Union([
  Schema.Struct({ type: Schema.tag("image_generation") }),
 ])

+const OpenAIResponsesInputItem = Schema.Union([
+  Schema.Struct({
+    role: Schema.tag("assistant"),
+    content: Schema.Array(Schema.Struct({ type: Schema.tag("output_text"), text: Schema.String })),
+    phase: Schema.optionalKey(Schema.NullOr(OpenResponses.MessagePhase)),
+  }),
+  OpenResponses.InputItem,
+])
+
 const OpenAIResponsesCoreFields = {
  ...OpenResponses.coreFields,
+  input: Schema.Array(OpenAIResponsesInputItem),
  tools: optionalArray(OpenAIResponsesTools),
  tool_choice: Schema.optional(OpenAIResponsesToolChoice),
 }
@@ -60,6 +70,7 @@ const encodeWebSocketMessage = Schema.encodeSync(Schema.fromJsonString(OpenAIRes
 const extension = {
  id: ADAPTER,
  name: NAME,
+  messagePhase: (value: unknown) => (value === null ? null : undefined),
  lowerMedia: ({ part, media, request }) => {
    if (request.model.provider !== "xai" || media.mime !== "application/pdf") return undefined
    return {
@@ -102,7 +113,7 @@ const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tool
  })

 const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: LLMRequest) {
-  const body = yield* OpenResponses.fromRequest(
+  const body = yield* OpenResponses.fromRequestWithExtension(
    LLMRequest.update(request, { tools: [], toolChoice: undefined }),
    extension,
  )
@@ -208,9 +219,13 @@ const onHostedToolDone = Effect.fn("OpenAIResponses.onHostedToolDone")(function*

 const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
  if (event.type === "response.reasoning_text.delta" || event.type === "response.reasoning_summary.delta")
-    return Effect.succeed(OpenResponses.onReasoningDelta(state, event))
+    return event.item_id
+      ? Effect.succeed(OpenResponses.onReasoningDelta(state, event, event.item_id))
+      : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
  if (event.type === "response.reasoning_text.done" || event.type === "response.reasoning_summary.done")
-    return Effect.succeed(OpenResponses.onReasoningDone(state, event))
+    return event.item_id
+      ? Effect.succeed(OpenResponses.onReasoningDone(state, event))
+      : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
  if (event.type === "response.output_item.done" && event.item && isHostedToolItem(event.item))
    return onHostedToolDone(state, event.item)
  return OpenResponses.step(state, event)
@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer"
+import { Tool } from "@opencode-ai/schema/tool"
 import { Effect, Schema, Stream } from "effect"
 import * as Sse from "effect/unstable/encoding/Sse"
 import { Headers, HttpClientRequest } from "effect/unstable/http"
@@ -9,7 +10,6 @@ import {
  type ContentPart,
  type LLMRequest,
  type MediaPart,
-  type ToolFileContent,
  type TextPart,
  type ToolResultPart,
 } from "../schema"
@@ -206,7 +206,7 @@ export const validateMedia = Effect.fn("ProviderShared.validateMedia")(function*
  return { mime, base64, dataUrl: `data:${mime};base64,${base64}`, bytes } satisfies ValidatedMedia
 })

-export const validateToolFile = (route: string, part: ToolFileContent, supportedMimes: ReadonlySet<string>) =>
+export const validateToolFile = (route: string, part: Tool.FileContent, supportedMimes: ReadonlySet<string>) =>
  validateMedia(route, { type: "media", mediaType: part.mime, data: part.uri, filename: part.name }, supportedMimes)

 export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
@@ -14,16 +14,19 @@ export const stepStart = (state: State, events: LLMEvent[]): State => {
  return { ...state, stepStarted: true }
 }

-export const textDelta = (state: State, events: LLMEvent[], id: string, text: string): State => {
+export const textStart = (state: State, events: LLMEvent[], id: string, providerMetadata?: ProviderMetadata): State => {
+  if (state.text.has(id)) return state
  const stepped = stepStart(state, events)
-  if (stepped.text.has(id)) {
-    events.push(LLMEvent.textDelta({ id, text }))
-    return stepped
-  }
-  events.push(LLMEvent.textStart({ id }), LLMEvent.textDelta({ id, text }))
+  events.push(LLMEvent.textStart({ id, providerMetadata }))
  return { ...stepped, text: new Set([...stepped.text, id]) }
 }

+export const textDelta = (state: State, events: LLMEvent[], id: string, text: string): State => {
+  const started = textStart(state, events, id)
+  events.push(LLMEvent.textDelta({ id, text }))
+  return started
+}
+
 export const reasoningStart = (
  state: State,
  events: LLMEvent[],
@@ -1,4 +1,5 @@
 import { Schema } from "effect"
+import { Tool } from "@opencode-ai/schema/tool"
 import { ModelID, ProviderID, ProviderMetadata, RouteID } from "./ids"

 export const ProviderFailureClassification = Schema.Literal("context-overflow")
@@ -152,8 +153,4 @@ export class LLMError extends Schema.TaggedErrorClass<LLMError>()("LLM.Error", {
 * Anything thrown or yielded by a handler that is not a `ToolFailure` is
 * treated as a defect and fails the stream.
 */
-export class ToolFailure extends Schema.TaggedErrorClass<ToolFailure>()("LLM.ToolFailure", {
-  message: Schema.String,
-  error: Schema.optional(Schema.Defect()),
-  metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-}) {}
+export class ToolFailure extends Tool.Error {}
@@ -40,9 +40,9 @@ import { ProviderFailureClassification } from "./errors"
 * - Anthropic and Bedrock report the input breakdown natively: Anthropic's
 *   `input_tokens` and Bedrock's `inputTokens` are non-cached only. Their
 *   mappers sum the breakdown to derive the inclusive `inputTokens`.
- *   Anthropic does *not* break extended-thinking out of `output_tokens`, so
- *   `reasoningTokens` is `undefined` and `outputTokens` carries the
- *   combined total — a documented limitation of the Anthropic API.
+ *   Anthropic's `outputTokens` includes extended thinking. Newer responses
+ *   expose that subset as `output_tokens_details.thinking_tokens`, which maps
+ *   to `reasoningTokens`; older responses leave it undefined.
 *
 * `providerMetadata` always carries the provider's raw usage payload —
 * keyed by provider name (`{ openai: ... }`, `{ anthropic: ... }`, etc.)
@@ -1,5 +1,5 @@
 import { Schema } from "effect"
-import { ToolContent, ToolFileContent, ToolTextContent } from "@opencode-ai/schema/llm"
+import { Tool } from "@opencode-ai/schema/tool"
 import { JsonSchema, MessageRole, ProviderMetadata } from "./ids"
 import { CacheHint, CachePolicy, GenerationOptions, HttpOptions, ModelSchema, ProviderOptions } from "./options"
 import { isRecord } from "../utils/record"
@@ -40,8 +40,6 @@ export const MediaPart = Schema.Struct({
 }).annotate({ identifier: "LLM.Content.Media" })
 export type MediaPart = Schema.Schema.Type<typeof MediaPart>

-export { ToolContent, ToolFileContent, ToolTextContent }
-
 const isToolResultValue = (value: unknown): value is ToolResultValue =>
  isRecord(value) &&
  (value.type === "text" || value.type === "json" || value.type === "error" || value.type === "content") &&
@@ -63,7 +61,7 @@ export const ToolResultValue = Object.assign(
    }),
    Schema.Struct({
      type: Schema.Literal("content"),
-      value: Schema.Array(ToolContent),
+      value: Schema.Array(Tool.Content),
    }),
  ]).annotate({ identifier: "LLM.ToolResult" }),
  {
@@ -79,16 +77,16 @@ export type ToolResultValue = Schema.Schema.Type<typeof ToolResultValue>

 export interface ToolOutput {
  readonly structured: unknown
-  readonly content: ReadonlyArray<ToolContent>
+  readonly content: ReadonlyArray<Tool.Content>
 }

 export const ToolOutput = Object.assign(
  Schema.Struct({
    structured: Schema.Unknown,
-    content: Schema.Array(ToolContent),
+    content: Schema.Array(Tool.Content),
  }).annotate({ identifier: "LLM.ToolOutput" }),
  {
-    make: (structured: unknown, content: ReadonlyArray<ToolContent> = []): ToolOutput => ({ structured, content }),
+    make: (structured: unknown, content: ReadonlyArray<Tool.Content> = []): ToolOutput => ({ structured, content }),
    fromResultValue: (result: ToolResultValue): ToolOutput | undefined => {
      switch (result.type) {
        case "json":
@@ -251,11 +251,11 @@ export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({
 // Auto-placement policy for prompt caching. The protocol-neutral lowering step
 // reads this and injects `CacheHint`s at the configured boundaries; the
 // per-protocol body builders then translate those hints into wire markers as
-// usual. `"auto"` is the recommended default for agent loops — it places one
-// breakpoint at the last tool definition, one at the last system part, and one
-// at the latest user message. The combination of provider invalidation
-// hierarchy (tools → system → messages) and Anthropic/Bedrock's 20-block
-// lookback means three trailing breakpoints reliably cover the static prefix.
+// usual. `"auto"` is the recommended default for agent loops — it places
+// breakpoints at the last tool definition, the first and last distinct system
+// parts, and the conversation tail. The rolling message breakpoint keeps a
+// prior cache entry within Anthropic/Bedrock's 20-block lookback during long
+// tool loops.
 //
 // Pass `"none"` to opt out entirely (the legacy behavior). Pass the granular
 // object form to override individual choices.
@@ -28,7 +28,7 @@ export const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<Dispat

  return decodeAndExecute(tool, call).pipe(
    Effect.map((value) => result(call, value)),
-    Effect.catchTag("LLM.ToolFailure", (failure) =>
+    Effect.catchTag("Tool.Error", (failure) =>
      Effect.succeed(result(call, { type: "error", value: failure.message }, failure.error)),
    ),
  )
@@ -1,7 +1,7 @@
 import { Effect, JsonSchema, Schema } from "effect"
+import { Tool } from "@opencode-ai/schema/tool"
 import type {
  ToolCallPart,
-  ToolContent,
  ToolDefinition as ToolDefinitionClass,
  ToolOutput as ToolOutputType,
 } from "./schema"
@@ -31,7 +31,7 @@ export interface ToolModelOutputInput<Parameters, Output> {

 export type ToolToModelOutput<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>> = (
  input: ToolModelOutputInput<Schema.Schema.Type<Parameters>, Success["Encoded"]>,
-) => ReadonlyArray<ToolContent>
+) => ReadonlyArray<Tool.Content>

 /**
 * A type-safe LLM tool. Each tool bundles its own description, parameter
@@ -95,7 +95,7 @@ type DynamicToolConfig = {
  readonly jsonSchema: JsonSchema.JsonSchema
  readonly outputSchema?: JsonSchema.JsonSchema
  readonly execute?: (params: unknown, context?: ToolExecuteContext) => Effect.Effect<unknown, ToolFailure>
-  readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<ToolContent>
+  readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>
  readonly toStructuredOutput?: (output: unknown) => unknown
 }

@@ -151,7 +151,7 @@ export function make(config: {
  readonly jsonSchema: JsonSchema.JsonSchema
  readonly outputSchema?: JsonSchema.JsonSchema
  readonly execute: (params: unknown, context?: ToolExecuteContext) => Effect.Effect<unknown, ToolFailure>
-  readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<ToolContent>
+  readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>
  readonly toStructuredOutput?: (output: unknown) => unknown
 }): AnyExecutableTool
 export function make(config: {
@@ -159,7 +159,7 @@ export function make(config: {
  readonly jsonSchema: JsonSchema.JsonSchema
  readonly outputSchema?: JsonSchema.JsonSchema
  readonly execute?: undefined
-  readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<ToolContent>
+  readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>
  readonly toStructuredOutput?: (output: unknown) => unknown
 }): AnyTool
 export function make(config: TypedToolConfig | DynamicToolConfig): AnyTool {
@@ -236,7 +236,7 @@ const toJsonSchema = (schema: Schema.Top): JsonSchema.JsonSchema => {
 }

 const project = (
-  toModelOutput: ((input: ToolModelOutputInput<any, any>) => ReadonlyArray<ToolContent>) | undefined,
+  toModelOutput: ((input: ToolModelOutputInput<any, any>) => ReadonlyArray<Tool.Content>) | undefined,
  toStructuredOutput: ((output: unknown) => unknown) | undefined,
  parameters: unknown,
  callID: ToolCallPart["id"],
@@ -39,8 +39,8 @@ describe("applyCachePolicy", () => {
        }),
      )

-      // No explicit cache field → auto policy fires → last system part + latest
-      // user message both get cache_control markers.
+      // A single system block is both the first and last boundary, so the auto
+      // policy deduplicates it and still marks the conversation tail.
      expect(prepared.body).toMatchObject({
        system: [{ type: "text", text: "You are concise.", cache_control: { type: "ephemeral" } }],
        messages: [{ role: "user", content: [{ type: "text", text: "hi", cache_control: { type: "ephemeral" } }] }],
@@ -48,12 +48,15 @@ describe("applyCachePolicy", () => {
    }),
  )

-  it.effect("'auto' marks the last tool, last system part, and latest user message on Anthropic", () =>
+  it.effect("'auto' marks the last tool, first and last system parts, and final message boundary on Anthropic", () =>
    Effect.gen(function* () {
      const prepared = yield* LLMClient.prepare(
        LLM.request({
          model: anthropicModel,
-          system: "Sys A",
+          system: [
+            { type: "text", text: "Base agent" },
+            { type: "text", text: "Project instructions" },
+          ],
          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
          messages: [
            Message.user("first user"),
@@ -66,7 +69,10 @@ describe("applyCachePolicy", () => {

      expect(prepared.body).toMatchObject({
        tools: [{ name: "t1", cache_control: { type: "ephemeral" } }],
-        system: [{ type: "text", text: "Sys A", cache_control: { type: "ephemeral" } }],
+        system: [
+          { type: "text", text: "Base agent", cache_control: { type: "ephemeral" } },
+          { type: "text", text: "Project instructions", cache_control: { type: "ephemeral" } },
+        ],
        messages: [
          { role: "user", content: [{ type: "text", text: "first user" }] },
          { role: "assistant", content: [{ type: "text", text: "assistant reply" }] },
@@ -120,7 +126,10 @@ describe("applyCachePolicy", () => {
      const prepared = yield* LLMClient.prepare(
        LLM.request({
          model: bedrockModel,
-          system: "Sys",
+          system: [
+            { type: "text", text: "Base agent" },
+            { type: "text", text: "Project instructions" },
+          ],
          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
          messages: [Message.user("first user"), Message.assistant("reply"), Message.user("latest user")],
          cache: "auto",
@@ -131,7 +140,12 @@ describe("applyCachePolicy", () => {
        toolConfig: {
          tools: [{ toolSpec: { name: "t1" } }, { cachePoint: { type: "default" } }],
        },
-        system: [{ text: "Sys" }, { cachePoint: { type: "default" } }],
+        system: [
+          { text: "Base agent" },
+          { cachePoint: { type: "default" } },
+          { text: "Project instructions" },
+          { cachePoint: { type: "default" } },
+        ],
        messages: [
          { role: "user", content: [{ text: "first user" }] },
          { role: "assistant", content: [{ text: "reply" }] },
@@ -193,9 +207,55 @@ describe("applyCachePolicy", () => {
        }),
      )

-      const body = prepared.body as { system: Array<{ text: string; cache_control?: unknown }> }
+      const body = prepared.body as {
+        system: Array<{ text: string; cache_control?: unknown }>
+        messages: Array<{ content: Array<{ cache_control?: unknown }> }>
+      }
      expect(body.system[0]?.cache_control).toEqual({ type: "ephemeral", ttl: "1h" })
      expect(body.system[1]?.cache_control).toEqual({ type: "ephemeral" })
+      expect(body.messages[0]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
+    }),
+  )
+
+  it.effect("auto policy stays within the four-breakpoint cap when preserving manual hints", () =>
+    Effect.gen(function* () {
+      const request = LLM.request({
+        model: anthropicModel,
+        system: [
+          { type: "text", text: "Base agent" },
+          {
+            type: "text",
+            text: "Manual context",
+            cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3600 }),
+          },
+          { type: "text", text: "Project instructions" },
+        ],
+        tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
+        prompt: "hi",
+        cache: "auto",
+      })
+      const applied = applyCachePolicy(request)
+      expect(applied.tools[0]?.cache).toBeDefined()
+      expect(applied.system.map((part) => part.cache !== undefined)).toEqual([true, true, true])
+      const tail = applied.messages[0]!.content[0]!
+      expect("cache" in tail ? tail.cache : undefined).toBeUndefined()
+      expect(applyCachePolicy(applied)).toBe(applied)
+
+      const prepared = yield* LLMClient.prepare(request)
+
+      const body = prepared.body as {
+        tools: Array<{ cache_control?: unknown }>
+        system: Array<{ cache_control?: unknown }>
+        messages: Array<{ content: Array<{ cache_control?: unknown }> }>
+      }
+      const marked = [
+        ...body.tools.map((tool) => tool.cache_control),
+        ...body.system.map((part) => part.cache_control),
+        ...body.messages.flatMap((message) => message.content.map((part) => part.cache_control)),
+      ].filter((cache) => cache !== undefined)
+      expect(marked).toHaveLength(4)
+      expect(body.system[1]?.cache_control).toEqual({ type: "ephemeral", ttl: "1h" })
+      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
    }),
  )

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { CacheHint, LLM } from "../../src"
+import { CacheHint, LLM, LLMRequest, Message, ToolCallPart, ToolDefinition } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as Anthropic from "../../src/providers/anthropic"
 import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
@@ -24,6 +24,39 @@ const cacheRequest = LLM.request({
  generation: { maxTokens: 16, temperature: 0 },
 })

+const lookup = ToolDefinition.make({
+  name: "lookup",
+  description: "Look up a fixture value.",
+  inputSchema: {
+    type: "object",
+    properties: { index: { type: "number" } },
+    required: ["index"],
+    additionalProperties: false,
+  },
+})
+const longToolTurn = [
+  Message.user("Run the fixture lookups."),
+  ...Array.from({ length: 11 }, (_, index) => {
+    const id = `lookup_${index}`
+    return [
+      Message.assistant(ToolCallPart.make({ id, name: lookup.name, input: { index } })),
+      Message.tool({
+        id,
+        name: lookup.name,
+        result: `Fixture result ${index}. `.repeat(80),
+      }),
+    ]
+  }).flat(),
+]
+const longToolTurnRequest = LLM.request({
+  id: "recorded_anthropic_cache_long_tool_turn",
+  model,
+  system: LARGE_CACHEABLE_SYSTEM,
+  messages: longToolTurn,
+  tools: [lookup],
+  generation: { maxTokens: 16, temperature: 0 },
+})
+
 const recorded = recordedTests({
  prefix: "anthropic-messages-cache",
  provider: "anthropic",
@@ -50,4 +83,28 @@ describe("Anthropic Messages cache recorded", () => {
      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
    }),
  )
+
+  recorded.effect.with("keeps a long tool turn inside the cache lookback", { tags: ["cache", "tool"] }, () =>
+    Effect.gen(function* () {
+      const first = yield* LLMClient.generate(longToolTurnRequest)
+      const firstRead = first.usage?.cacheReadInputTokens ?? 0
+      const firstWrite = first.usage?.cacheWriteInputTokens ?? 0
+      const firstCached = firstRead + firstWrite
+      // The prefix may already be warm when recording, so either a read or a
+      // write establishes that Anthropic recognized the cache boundary.
+      expect(firstCached).toBeGreaterThan(0)
+
+      const second = yield* LLMClient.generate(
+        LLMRequest.update(longToolTurnRequest, {
+          messages: [
+            ...longToolTurn,
+            Message.assistant("The fixture lookups are complete."),
+            Message.user("Reply exactly: OK"),
+          ],
+        }),
+      )
+      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(firstCached)
+      expect(second.usage?.cacheWriteInputTokens ?? 0).toBeLessThan(firstCached)
+    }),
+  )
 })
@@ -506,6 +506,7 @@ describe("Anthropic Messages route", () => {
      expect(response.events.find((event) => event.type === "reasoning-end")).toMatchObject({
        providerMetadata: { anthropic: { signature: "sig_1" } },
      })
+      expect(response.events.find((event) => event.type === "reasoning-delta" && event.text === "")).toBeUndefined()
      expect(response.message.content).toEqual([
        { type: "text", text: "Hello!" },
        { type: "reasoning", text: "thinking", providerMetadata: { anthropic: { signature: "sig_1" } } },
@@ -518,6 +519,199 @@ describe("Anthropic Messages route", () => {
    }),
  )

+  it.effect("requires message_stop before completing a streamed message", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "message_start", message: { usage: { input_tokens: 5 } } },
+              { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+              { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Hello" } },
+              { type: "content_block_stop", index: 0 },
+              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+            ),
+          ),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({
+        _tag: "InvalidProviderOutput",
+        message: "Provider stream ended without a terminal finish event",
+      })
+    }),
+  )
+
+  it.effect("maps thinking tokens and preserves unknown Anthropic usage fields", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              {
+                type: "message_start",
+                message: {
+                  usage: {
+                    input_tokens: 5,
+                    cache_read_input_tokens: 2,
+                    service_tier: "standard",
+                    cache_creation: { ephemeral_5m_input_tokens: 1 },
+                    server_tool_use: { web_search_requests: 1, start_counter: 2 },
+                    output_tokens_details: { thinking_tokens: 3, start_detail: "preserved" },
+                  },
+                },
+              },
+              {
+                type: "message_delta",
+                delta: { stop_reason: "end_turn" },
+                usage: {
+                  output_tokens: 8,
+                  server_tool_use: { web_search_requests: 2, terminal_counter: 3 },
+                  output_tokens_details: { terminal_detail: "preserved" },
+                  future_terminal: { requests: 4 },
+                },
+              },
+              { type: "message_stop" },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.usage).toMatchObject({
+        inputTokens: 7,
+        outputTokens: 8,
+        reasoningTokens: 3,
+        totalTokens: 15,
+        providerMetadata: {
+          anthropic: {
+            input_tokens: 5,
+            cache_read_input_tokens: 2,
+            service_tier: "standard",
+            cache_creation: { ephemeral_5m_input_tokens: 1 },
+            server_tool_use: { web_search_requests: 2, start_counter: 2, terminal_counter: 3 },
+            output_tokens: 8,
+            output_tokens_details: {
+              thinking_tokens: 3,
+              start_detail: "preserved",
+              terminal_detail: "preserved",
+            },
+            future_terminal: { requests: 4 },
+          },
+        },
+      })
+    }),
+  )
+
+  it.effect("round-trips omitted thinking carried only by a signature delta", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "message_start", message: { usage: { input_tokens: 5 } } },
+              {
+                type: "content_block_start",
+                index: 0,
+                content_block: { type: "thinking", thinking: "", signature: "" },
+              },
+              { type: "content_block_delta", index: 0, delta: { type: "signature_delta", signature: "sig_1" } },
+              { type: "content_block_stop", index: 0 },
+              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+              { type: "message_stop" },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.message.content).toEqual([
+        { type: "reasoning", text: "", providerMetadata: { anthropic: { signature: "sig_1" } } },
+      ])
+
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({ model, messages: [response.message], cache: "none" }),
+      )
+      expect(prepared.body.messages).toEqual([
+        { role: "assistant", content: [{ type: "thinking", thinking: "", signature: "sig_1" }] },
+      ])
+    }),
+  )
+
+  it.effect("retains a thinking signature supplied in content_block_start", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "message_start", message: { usage: { input_tokens: 5 } } },
+              {
+                type: "content_block_start",
+                index: 0,
+                content_block: { type: "thinking", thinking: "", signature: "sig_1" },
+              },
+              { type: "content_block_stop", index: 0 },
+              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+              { type: "message_stop" },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.message.content).toEqual([
+        { type: "reasoning", text: "", providerMetadata: { anthropic: { signature: "sig_1" } } },
+      ])
+      expect(response.events.find((event) => event.type === "reasoning-end")).toMatchObject({
+        providerMetadata: { anthropic: { signature: "sig_1" } },
+      })
+    }),
+  )
+
+  it.effect("retains complete tool input from content_block_start", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "message_start", message: { usage: { input_tokens: 5 } } },
+              {
+                type: "content_block_start",
+                index: 0,
+                content_block: { type: "tool_use", id: "call_1", name: "lookup", input: { query: "weather" } },
+              },
+              { type: "content_block_stop", index: 0 },
+              { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 1 } },
+              { type: "message_stop" },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.toolCalls).toMatchObject([
+        { id: "call_1", name: "lookup", input: { query: "weather" } },
+      ])
+    }),
+  )
+
+  it.effect("retains empty text blocks", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "message_start", message: { usage: { input_tokens: 5 } } },
+              { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+              { type: "content_block_stop", index: 0 },
+              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+              { type: "message_stop" },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.message.content).toEqual([{ type: "text", text: "" }])
+    }),
+  )
+
  it.effect("parses redacted thinking into empty reasoning with redactedData metadata", () =>
    Effect.gen(function* () {
      const body = sseEvents(
@@ -629,6 +823,7 @@ describe("Anthropic Messages route", () => {
                delta: { stop_reason: "model_context_window_exceeded" },
                usage: { output_tokens: 1 },
              },
+              { type: "message_stop" },
            ),
          ),
        ),
@@ -646,6 +841,7 @@ describe("Anthropic Messages route", () => {
            sseEvents(
              { type: "message_start", message: { usage: { input_tokens: 5 } } },
              { type: "message_delta", delta: { stop_reason: "pause_turn" }, usage: { output_tokens: 1 } },
+              { type: "message_stop" },
            ),
          ),
        ),
@@ -664,6 +860,7 @@ describe("Anthropic Messages route", () => {
        { type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: ':"weather"}' } },
        { type: "content_block_stop", index: 0 },
        { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 1 } },
+        { type: "message_stop" },
      )
      const response = yield* LLMClient.generate(
        LLMRequest.update(request, {
@@ -849,6 +1046,7 @@ describe("Anthropic Messages route", () => {
        { type: "content_block_delta", index: 2, delta: { type: "text_delta", text: "Found it." } },
        { type: "content_block_stop", index: 2 },
        { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 8 } },
+        { type: "message_stop" },
      )
      const response = yield* LLMClient.generate(
        LLMRequest.update(request, {
@@ -912,6 +1110,7 @@ describe("Anthropic Messages route", () => {
        },
        { type: "content_block_stop", index: 1 },
        { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+        { type: "message_stop" },
      )
      const response = yield* LLMClient.generate(
        LLMRequest.update(request, {
@@ -939,6 +939,7 @@ describe("Bedrock Converse route", () => {
      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
        LLM.request({
          model,
+          cache: "none",
          messages: [
            Message.assistant([ToolCallPart.make({ id: "call_1", name: "read", input: { path: "report.pdf" } })]),
            Message.tool({
@@ -550,7 +550,7 @@ describe("OpenAI Chat route", () => {
          prompt_tokens: 5,
          completion_tokens: 2,
          total_tokens: 7,
-          prompt_tokens_details: { cached_tokens: 1 },
+          prompt_tokens_details: { cached_tokens: 1, cache_write_tokens: 2 },
          completion_tokens_details: { reasoning_tokens: 0 },
        }),
      )
@@ -558,8 +558,9 @@ describe("OpenAI Chat route", () => {
      const usage = new Usage({
        inputTokens: 5,
        outputTokens: 2,
-        nonCachedInputTokens: 4,
+        nonCachedInputTokens: 2,
        cacheReadInputTokens: 1,
+        cacheWriteInputTokens: 2,
        reasoningTokens: 0,
        totalTokens: 7,
        providerMetadata: {
@@ -567,7 +568,7 @@ describe("OpenAI Chat route", () => {
            prompt_tokens: 5,
            completion_tokens: 2,
            total_tokens: 7,
-            prompt_tokens_details: { cached_tokens: 1 },
+            prompt_tokens_details: { cached_tokens: 1, cache_write_tokens: 2 },
            completion_tokens_details: { reasoning_tokens: 0 },
          },
        },
@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMEvent } from "../../src"
+import { LLM, LLMEvent, Message } from "../../src"
 import { configure } from "../../src/providers/openai-compatible-responses"
 import { OpenAI } from "../../src/providers"
 import { OpenResponses } from "../../src/protocols/open-responses"
@@ -70,6 +70,31 @@ describe("Open Responses-compatible route", () => {
    }),
  )

+  it.effect("omits OpenAI-only nullable phases from the Open Responses baseline", () =>
+    Effect.gen(function* () {
+      const model = configure({
+        apiKey: "test-key",
+        baseURL: "https://responses.example.test/v1",
+      }).model("example-model")
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant({
+              type: "text",
+              text: "Unclassified.",
+              providerMetadata: { openresponses: { phase: null } },
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        input: [{ role: "assistant", content: [{ type: "output_text", text: "Unclassified." }] }],
+      })
+    }),
+  )
+
  it.effect("reads standard options from the Open Responses namespace", () =>
    Effect.gen(function* () {
      const model = configure({
@@ -832,7 +832,7 @@ describe("OpenAI Responses route", () => {
              input_tokens: 5,
              output_tokens: 2,
              total_tokens: 7,
-              input_tokens_details: { cached_tokens: 1 },
+              input_tokens_details: { cached_tokens: 1, cache_write_tokens: 2 },
              output_tokens_details: { reasoning_tokens: 0 },
            },
          },
@@ -842,8 +842,9 @@ describe("OpenAI Responses route", () => {
      const usage = new Usage({
        inputTokens: 5,
        outputTokens: 2,
-        nonCachedInputTokens: 4,
+        nonCachedInputTokens: 2,
        cacheReadInputTokens: 1,
+        cacheWriteInputTokens: 2,
        reasoningTokens: 0,
        totalTokens: 7,
        providerMetadata: {
@@ -851,7 +852,7 @@ describe("OpenAI Responses route", () => {
            input_tokens: 5,
            output_tokens: 2,
            total_tokens: 7,
-            input_tokens_details: { cached_tokens: 1 },
+            input_tokens_details: { cached_tokens: 1, cache_write_tokens: 2 },
            output_tokens_details: { reasoning_tokens: 0 },
          },
        },
@@ -881,6 +882,121 @@ describe("OpenAI Responses route", () => {
    }),
  )

+  it.effect("preserves and replays assistant message phases", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              {
+                type: "response.output_item.added",
+                item: { type: "message", id: "msg_commentary" },
+              },
+              { type: "response.output_text.delta", item_id: "msg_commentary", delta: "Checking." },
+              { type: "response.output_text.done", item_id: "msg_commentary" },
+              {
+                type: "response.output_item.done",
+                item: { type: "message", id: "msg_commentary", phase: "commentary" },
+              },
+              {
+                type: "response.output_item.added",
+                item: { type: "message", id: "msg_final", phase: "final_answer" },
+              },
+              { type: "response.output_text.done", item_id: "msg_final", text: "Finished." },
+              {
+                type: "response.output_item.done",
+                item: { type: "message", id: "msg_final", phase: "final_answer" },
+              },
+              { type: "response.output_item.added", item: { type: "message", id: "msg_null", phase: null } },
+              { type: "response.output_text.delta", item_id: "msg_null", delta: "Unclassified." },
+              { type: "response.output_item.done", item: { type: "message", id: "msg_null", phase: null } },
+              { type: "response.completed", response: { id: "resp_1" } },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.message.content).toEqual([
+        {
+          type: "text",
+          text: "Checking.",
+          providerMetadata: { openai: { phase: "commentary" } },
+        },
+        {
+          type: "text",
+          text: "Finished.",
+          providerMetadata: { openai: { phase: "final_answer" } },
+        },
+        {
+          type: "text",
+          text: "Unclassified.",
+          providerMetadata: { openai: { phase: null } },
+        },
+      ])
+
+      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+        LLM.request({ model, messages: [response.message] }),
+      )
+      expect(prepared.body.input).toEqual([
+        {
+          role: "assistant",
+          content: [{ type: "output_text", text: "Checking." }],
+          phase: "commentary",
+        },
+        {
+          role: "assistant",
+          content: [{ type: "output_text", text: "Finished." }],
+          phase: "final_answer",
+        },
+        {
+          role: "assistant",
+          content: [{ type: "output_text", text: "Unclassified." }],
+          phase: null,
+        },
+      ])
+    }),
+  )
+
+  it.effect("rejects output text events without the spec-required item id", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "response.output_text.delta", delta: "orphaned" },
+              { type: "response.completed", response: { id: "resp_1" } },
+            ),
+          ),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason._tag).toBe("InvalidProviderOutput")
+      expect(error.message).toContain("response.output_text.delta is missing item_id")
+    }),
+  )
+
+  it.effect("rejects reasoning events without the spec-required item id", () =>
+    Effect.gen(function* () {
+      const events = [
+        { type: "response.reasoning_summary_part.added", summary_index: 0 },
+        { type: "response.reasoning_summary_part.done", summary_index: 0 },
+        { type: "response.reasoning_text.done" },
+      ]
+
+      for (const event of events) {
+        const error = yield* LLMClient.generate(request).pipe(
+          Effect.provide(
+            fixedResponse(sseEvents(event, { type: "response.completed", response: { id: "resp_1" } })),
+          ),
+          Effect.flip,
+        )
+        expect(error.reason._tag).toBe("InvalidProviderOutput")
+        expect(error.message).toContain(`${event.type} is missing item_id`)
+      }
+    }),
+  )
+
  it.effect("maps incomplete response reasons", () =>
    Effect.gen(function* () {
      const generate = (incompleteDetails: object) =>
@@ -1,4 +1,5 @@
 import { describe, expect } from "bun:test"
+import { Content } from "@opencode-ai/schema/tool"
 import { Effect, Schema, Stream } from "effect"
 import {
  GenerationOptions,
@@ -7,7 +8,6 @@ import {
  LLMRequest,
  LLMResponse,
  ToolChoice,
-  ToolContent,
  ToolOutput,
  toDefinitions,
 } from "../src"
@@ -279,7 +279,7 @@ describe("LLMClient tools", () => {

  it.effect("models canonical tool files with URIs", () =>
    Effect.sync(() => {
-      const decode = Schema.decodeUnknownSync(ToolContent)
+      const decode = Schema.decodeUnknownSync(Content)

      expect(decode({ type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png" })).toEqual({
        type: "file",
@@ -539,6 +539,7 @@ describe("LLMClient tools", () => {
                  },
                  { type: "content_block_stop", index: 1 },
                  { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 5 } },
+                  { type: "message_stop" },
                )
              : sseEvents(
                  { type: "message_start", message: { usage: { input_tokens: 5 } } },
@@ -546,6 +547,7 @@ describe("LLMClient tools", () => {
                  { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Done." } },
                  { type: "content_block_stop", index: 0 },
                  { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+                  { type: "message_stop" },
                ),
            { headers: { "content-type": "text/event-stream" } },
          )
@@ -801,6 +803,7 @@ describe("LLMClient tools", () => {
              { type: "content_block_delta", index: 2, delta: { type: "text_delta", text: "Done." } },
              { type: "content_block_stop", index: 2 },
              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 8 } },
+              { type: "message_stop" },
            ),
            { headers: { "content-type": "text/event-stream" } },
          )
@@ -56,7 +56,7 @@
    "@opencode-ai/client": "file:vendor/opencode-ai-client-1.17.13.tgz",
    "@opencode-ai/core": "workspace:*",
    "@opencode-ai/schema": "workspace:*",
-    "@opencode-ai/sdk": "workspace:*",
+    "@opencode-ai/sdk": "1.18.5",
    "@opencode-ai/session-ui": "workspace:*",
    "@opencode-ai/ui": "workspace:*",
    "@pierre/trees": "1.0.0-beta.4",
@@ -8,8 +8,8 @@ import type {
  QuestionRequest,
  Session,
  SessionStatus,
-  FileDiffInfo,
 } from "@opencode-ai/sdk/v2/client"
+import type { SessionDiff } from "@/utils/diffs"
 import type { State, VcsCache } from "./types"
 import { trimSessions } from "./session-trim"
 import { dropSessionCaches } from "./session-cache"
@@ -171,7 +171,7 @@ export function applyDirectoryEvent(input: {
      break
    }
    case "session.diff": {
-      const props = event.properties as { sessionID: string; diff: FileDiffInfo[] }
+      const props = event.properties as { sessionID: string; diff: SessionDiff[] }
      input.setStore("session_diff", props.sessionID, reconcile(list(props.diff), { key: "file" }))
      break
    }
@@ -5,8 +5,8 @@ import type {
  PermissionRequest,
  QuestionRequest,
  SessionStatus,
-  FileDiffInfo,
 } from "@opencode-ai/sdk/v2/client"
+import type { SessionDiff } from "@/utils/diffs"
 import { dropSessionCaches, pickSessionCacheEvictions } from "./session-cache"

 const msg = (id: string, sessionID: string) =>
@@ -32,7 +32,7 @@ describe("app session cache", () => {
  test("dropSessionCaches clears orphaned parts without message rows", () => {
    const store: {
      session_status: Record<string, SessionStatus | undefined>
-      session_diff: Record<string, FileDiffInfo[] | undefined>
+      session_diff: Record<string, SessionDiff[] | undefined>
      message: Record<string, Message[] | undefined>
      part: Record<string, Part[] | undefined>
      permission: Record<string, PermissionRequest[] | undefined>
@@ -63,7 +63,7 @@ describe("app session cache", () => {
    const m = msg("msg_1", "ses_1")
    const store: {
      session_status: Record<string, SessionStatus | undefined>
-      session_diff: Record<string, FileDiffInfo[] | undefined>
+      session_diff: Record<string, SessionDiff[] | undefined>
      message: Record<string, Message[] | undefined>
      part: Record<string, Part[] | undefined>
      permission: Record<string, PermissionRequest[] | undefined>
@@ -4,14 +4,14 @@ import type {
  PermissionRequest,
  QuestionRequest,
  SessionStatus,
-  FileDiffInfo,
 } from "@opencode-ai/sdk/v2/client"
+import type { SessionDiff } from "@/utils/diffs"

 export const SESSION_CACHE_LIMIT = 40

 type SessionCache = {
  session_status: Record<string, SessionStatus | undefined>
-  session_diff: Record<string, FileDiffInfo[] | undefined>
+  session_diff: Record<string, SessionDiff[] | undefined>
  message: Record<string, Message[] | undefined>
  part: Record<string, Part[] | undefined>
  permission: Record<string, PermissionRequest[] | undefined>
@@ -13,9 +13,9 @@ import type {
  ReferenceInfo,
  Session,
  SessionStatus,
-  FileDiffInfo,
  VcsInfo,
 } from "@opencode-ai/sdk/v2/client"
+import type { SessionDiff } from "@/utils/diffs"
 import { NormalizedProviderListResponse } from "@opencode-ai/session-ui/context"
 import type { Accessor } from "solid-js"
 import type { SetStoreFunction, Store } from "solid-js/store"
@@ -50,7 +50,7 @@ export type State = {
  }
  session_working(id: string): boolean
  session_diff: {
-    [sessionID: string]: FileDiffInfo[]
+    [sessionID: string]: SessionDiff[]
  }
  permission: {
    [sessionID: string]: PermissionRequest[]
@@ -25,7 +25,7 @@ describe("adaptServerEvent", () => {
    } as OpenCodeEvent

    expect(adaptServerEvent(current)).toMatchObject({
-      type: "permission.asked",
+      type: "permission.v2.asked",
      properties: { id: "perm_1", sessionID: "ses_1", permission: "read", patterns: ["src/**"] },
      current,
    })
@@ -1,5 +1,5 @@
 import type { OpenCodeEvent } from "@opencode-ai/client/promise"
-import type { Event } from "@opencode-ai/sdk/v2/client"
+import type { Event, PermissionRequest } from "@opencode-ai/sdk/v2/client"
 import { createSimpleContext } from "@opencode-ai/ui/context"
 import { createGlobalEmitter } from "@solid-primitives/event-bus"
 import { makeEventListener } from "@solid-primitives/event-listener"
@@ -18,7 +18,15 @@ const isAbortError = (error: unknown) =>
  error !== null && typeof error === "object" && "name" in error && error.name === "AbortError"

 const isStreamClosed = (error: unknown, signal?: AbortSignal) => isAbortError(error) || signal?.aborted === true
-export type ServerEvent = Event & { current?: OpenCodeEvent }
+type PermissionEvent = {
+  id: string
+  type: "permission.v2.asked"
+  properties: PermissionRequest
+  current?: OpenCodeEvent
+}
+export type ServerEvent = (Event | PermissionEvent) & {
+  current?: OpenCodeEvent
+}
 type QueuedServerEvent = { directory: string; payload: ServerEvent }
 type CurrentDelta = Extract<
  OpenCodeEvent,
@@ -29,7 +37,7 @@ export function adaptServerEvent(event: OpenCodeEvent): ServerEvent {
  if (event.type === "permission.v2.asked") {
    return {
      id: event.id,
-      type: "permission.asked",
+      type: "permission.v2.asked",
      properties: {
        id: event.data.id,
        sessionID: event.data.sessionID,
@@ -43,16 +51,16 @@ export function adaptServerEvent(event: OpenCodeEvent): ServerEvent {
            : undefined,
      },
      current: event,
-    } as ServerEvent
+    }
  }
  if (event.type === "permission.v2.replied")
-    return { id: event.id, type: "permission.replied", properties: event.data, current: event } as ServerEvent
+    return { id: event.id, type: "permission.v2.replied", properties: event.data, current: event } as ServerEvent
  if (event.type === "question.v2.asked")
-    return { id: event.id, type: "question.asked", properties: event.data, current: event } as ServerEvent
+    return { id: event.id, type: "question.v2.asked", properties: event.data, current: event } as ServerEvent
  if (event.type === "question.v2.replied")
-    return { id: event.id, type: "question.replied", properties: event.data, current: event } as ServerEvent
+    return { id: event.id, type: "question.v2.replied", properties: event.data, current: event } as ServerEvent
  if (event.type === "question.v2.rejected")
-    return { id: event.id, type: "question.rejected", properties: event.data, current: event } as ServerEvent
+    return { id: event.id, type: "question.v2.rejected", properties: event.data, current: event } as ServerEvent
  return { id: event.id, type: event.type, properties: event.data, current: event } as ServerEvent
 }

@@ -8,8 +8,8 @@ import type {
  QuestionRequest,
  Session,
  SessionStatus,
-  FileDiffInfo,
 } from "@opencode-ai/sdk/v2/client"
+import type { SessionDiff } from "@/utils/diffs"
 import { batch } from "solid-js"
 import { createStore, produce, reconcile } from "solid-js/store"
 import { diffs as cleanDiffs, message as cleanMessage } from "@/utils/diffs"
@@ -140,7 +140,7 @@ export function createServerSession(client: OpencodeClient, options?: { retry?:
  const [data, setData] = createStore({
    info: {} as Record<string, Session | undefined>,
    session_status: {} as Record<string, SessionStatus>,
-    session_diff: {} as Record<string, FileDiffInfo[]>,
+    session_diff: {} as Record<string, SessionDiff[]>,
    permission: {} as Record<string, PermissionRequest[]>,
    question: {} as Record<string, QuestionRequest[]>,
    message: {} as Record<string, Message[]>,
@@ -773,7 +773,7 @@ export function createServerSession(client: OpencodeClient, options?: { retry?:
        return
      }
      case "session.diff": {
-        const props = event.properties as { sessionID: string; diff: FileDiffInfo[] }
+        const props = event.properties as { sessionID: string; diff: SessionDiff[] }
        setData("session_diff", props.sessionID, reconcile(cleanDiffs(props.diff), { key: "file" }))
        return
      }
@@ -909,13 +909,8 @@ export default function Page() {
  )

  const stopVcs = sdk().event.listen((evt) => {
-    if (evt.details.type !== "filesystem.changed") return
-    const props =
-      typeof evt.details.properties === "object" && evt.details.properties
-        ? (evt.details.properties as Record<string, unknown>)
-        : undefined
-    const file = typeof props?.file === "string" ? props.file : undefined
-    if (!file || file.startsWith(".git/")) return
+    if (evt.details.type !== "file.watcher.updated") return
+    if (evt.details.properties.file.startsWith(".git/")) return
    refreshVcs()
  })
  onCleanup(stopVcs)
@@ -1,6 +1,7 @@
 import { createEffect, onCleanup, type JSX } from "solid-js"
 import { makeEventListener } from "@solid-primitives/event-listener"
-import type { FileDiffInfo, VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { SessionDiff } from "@/utils/diffs"
 import { SessionReview } from "@opencode-ai/session-ui/session-review"
 import type {
  SessionReviewCommentActions,
@@ -14,7 +15,7 @@ import type { LineComment } from "@/context/comments"

 export type DiffStyle = "unified" | "split"

-type ReviewDiff = FileDiffInfo | VcsFileDiff
+type ReviewDiff = SessionDiff | VcsFileDiff

 export interface SessionReviewTabProps {
  title?: JSX.Element
@@ -23,7 +23,8 @@ import { Mark } from "@opencode-ai/ui/logo"
 import { IconButtonV2 } from "@opencode-ai/ui/v2/icon-button-v2"
 import { KeybindV2 } from "@opencode-ai/ui/v2/keybind-v2"
 import { TooltipV2 } from "@opencode-ai/ui/v2/tooltip-v2"
-import type { FileDiffInfo, VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { SessionDiff } from "@/utils/diffs"
 import { ConstrainDragYAxis, getDraggableId } from "@/utils/solid-dnd"
 import { useDialog } from "@opencode-ai/ui/context/dialog"

@@ -59,7 +60,7 @@ import type { RenderDiff } from "@/pages/session/v2/review-diff-kinds"

 export function SessionSidePanel(props: {
  canReview: () => boolean
-  diffs: () => (FileDiffInfo | VcsFileDiff)[]
+  diffs: () => (SessionDiff | VcsFileDiff)[]
  diffsReady: () => boolean
  empty: () => string
  hasReview: () => boolean
@@ -1,8 +1,9 @@
-import type { FileDiffInfo, VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { SessionDiff } from "@/utils/diffs"
 import type { Kind } from "@/components/file-tree-v2"
 import { normalizeFileTreeV2Path } from "@/components/file-tree-v2-model"

-export type RenderDiff = FileDiffInfo | VcsFileDiff
+export type RenderDiff = SessionDiff | VcsFileDiff

 export function normalizePath(p: string) {
  return normalizeFileTreeV2Path(p)
@@ -1,5 +1,6 @@
 import { createMemo, createResource, createSignal, Show, type JSX } from "solid-js"
-import type { FileDiffInfo, VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { VcsFileDiff } from "@opencode-ai/sdk/v2"
+import type { SessionDiff } from "@/utils/diffs"
 import {
  SESSION_REVIEW_V2_SIDEBAR_WIDTH_MAX,
  SESSION_REVIEW_V2_SIDEBAR_WIDTH_MIN,
@@ -29,7 +30,7 @@ import {
 import type { ReviewPanelV2State } from "@/pages/session/v2/review-panel-v2-state"
 import { applyFileListKeyDown, SessionFileListV2 } from "@/pages/session/v2/session-file-list-v2"

-type ReviewDiff = FileDiffInfo | VcsFileDiff
+type ReviewDiff = SessionDiff | VcsFileDiff

 export type ReviewPanelV2Props = {
  title?: JSX.Element
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import type { FileDiffInfo } from "@opencode-ai/sdk/v2"
+import type { SnapshotFileDiff } from "@opencode-ai/sdk/v2"
 import type { Message } from "@opencode-ai/sdk/v2/client"
 import { diffs, message } from "./diffs"

@@ -9,7 +9,7 @@ const item = {
  additions: 1,
  deletions: 1,
  status: "modified",
-} satisfies FileDiffInfo
+} satisfies SnapshotFileDiff

 describe("diffs", () => {
  test("keeps valid arrays", () => {
@@ -1,9 +1,9 @@
-import type { FileDiffInfo } from "@opencode-ai/sdk/v2"
+import type { SnapshotFileDiff } from "@opencode-ai/sdk/v2"
 import type { Message } from "@opencode-ai/sdk/v2/client"

-type Diff = FileDiffInfo
+export type SessionDiff = SnapshotFileDiff & { file: string; patch: string }

-function diff(value: unknown): value is Diff {
+function diff(value: unknown): value is SessionDiff {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false
  if (!("file" in value) || typeof value.file !== "string") return false
  if (!("patch" in value) || typeof value.patch !== "string") return false
@@ -17,7 +17,7 @@ function object(value: unknown): value is Record<string, unknown> {
  return !!value && typeof value === "object" && !Array.isArray(value)
 }

-export function diffs(value: unknown): Diff[] {
+export function diffs(value: unknown): SessionDiff[] {
  if (Array.isArray(value) && value.every(diff)) return value
  if (Array.isArray(value)) return value.filter(diff)
  if (diff(value)) return [value]
@@ -71,7 +71,7 @@ export async function streamTurn(input: {
      const next = await stream.next()
      if (next.done) throw new Error("event stream disconnected during prompt execution")
      const event = next.value
-      if (event.type === "permission.v2.asked" && event.data.sessionID === input.sessionID) {
+      if (event.type === "permission.asked" && event.data.sessionID === input.sessionID) {
        const tool = event.data.source?.callID ? tools.get(event.data.source.callID) : undefined
        await replyPermission({
          client: input.client,
@@ -5,7 +5,7 @@ import { Result } from "effect"
 import { isAbsolute, resolve } from "node:path"
 import { pendingToolCall, stringValue, toLocations, toToolKind, type ToolInput } from "./tool"

-type PermissionEvent = Extract<EventSubscribeOutput, { type: "permission.v2.asked" }>
+type PermissionEvent = Extract<EventSubscribeOutput, { type: "permission.asked" }>
 type Connection = Pick<AgentSideConnection, "requestPermission"> & Partial<Pick<AgentSideConnection, "writeTextFile">>
 type Tool = { readonly name: string; readonly input: ToolInput }

@@ -5,7 +5,7 @@ import { readDisplayText } from "@opencode-ai/tui/mini/tool"
 export type ToolInput = Record<string, unknown>
 export type ToolContent = ReadonlyArray<
  | { readonly type: "text"; readonly text: string }
-  | { readonly type: "file"; readonly uri: string; readonly mime: string; readonly name?: string }
+  | { readonly type: "file"; readonly uri: string; readonly mime: string; readonly name?: string | null }
 >

 export function toToolKind(toolName: string): ToolKind {
@@ -44,6 +44,7 @@ export function toLocations(toolName: string, input: ToolInput, cwd?: string): T
      return workdir ? [{ path: workdir }] : []
    }
    case "read":
+      return locationFrom(input.path)
    case "edit":
    case "write":
    case "patch":
@@ -9,8 +9,8 @@ import {
  Provider,
  Reference,
  Skill,
-} from "@opencode-ai/plugin/v2/effect"
-import { Tool } from "@opencode-ai/plugin/v2/effect/tool"
+} from "@opencode-ai/plugin/effect"
+import { Tool } from "@opencode-ai/schema/tool"

 const key = Symbol.for("opencode.plugin.v2.effect")
 ;(globalThis as typeof globalThis & { [key]?: unknown })[key] = {
@@ -24,5 +24,5 @@ const key = Symbol.for("opencode.plugin.v2.effect")
  Provider,
  Reference,
  Skill,
-  Tool,
+  Tool: { Error: Tool.Error },
 }
@@ -9,8 +9,7 @@ import {
  Provider,
  Reference,
  Skill,
-} from "@opencode-ai/plugin/v2"
-import { Tool } from "@opencode-ai/plugin/v2/tool"
+} from "@opencode-ai/plugin"

 const key = Symbol.for("opencode.plugin.v2.promise")
 ;(globalThis as typeof globalThis & { [key]?: unknown })[key] = {
@@ -24,5 +23,4 @@ const key = Symbol.for("opencode.plugin.v2.promise")
  Provider,
  Reference,
  Skill,
-  Tool,
 }
@@ -1,11 +1,11 @@
 import type {
  EventSubscribeOutput,
  JsonValue,
-  LLMToolContent,
  LocationRef,
  OpenCodeClient,
  SessionMessageAssistantTool,
  SessionMessageInfo,
+  ToolContent,
 } from "@opencode-ai/client/promise"
 import { SessionMessage } from "@opencode-ai/schema/session-message"
 import { EOL } from "node:os"
@@ -56,7 +56,7 @@ type ToolState = StartedPart & {
  provider?: unknown
  providerState?: SessionMessageAssistantTool["providerState"]
  metadata: Record<string, JsonValue>
-  content: LLMToolContent[]
+  content: ToolContent[]
 }

 type V2Event = EventSubscribeOutput
@@ -177,7 +177,7 @@ export async function runNonInteractivePrompt(input: Input) {
      }
      const event = next.value

-      if (event.type === "permission.v2.asked" && submitted && event.data.sessionID === input.sessionID) {
+      if (event.type === "permission.asked" && submitted && event.data.sessionID === input.sessionID) {
        await replyPermission(event.data)
        continue
      }
@@ -13,11 +13,13 @@ type Options = {
  readonly command?: ReadonlyArray<string>
 }

+const startupDirectory = process.cwd()
+
 function command(password: string, options: Options) {
  const [executable, ...args] = options.command ?? [...selfCommand(), "serve"]
  if (!executable) throw new Error("Failed to resolve standalone server command")
  return ChildProcess.make(executable, [...args, "--stdio", "--port", "0"], {
-    cwd: process.cwd(),
+    cwd: startupDirectory,
    // Explicit entry wins over anything inherited, so a user-exported
    // OPENCODE_PASSWORD cannot shadow the child's lease credential.
    env: { OPENCODE_PASSWORD: password },
@@ -1,11 +1,13 @@
 import path from "node:path"

+const entrypoint = process.argv[1] ? path.resolve(process.argv[1]) : undefined
+
 export function selfCommand() {
  const runtime = path.basename(process.execPath, path.extname(process.execPath)).toLowerCase()
  if (runtime !== "bun" && runtime !== "node" && runtime !== "nodejs") return [process.execPath]
-  if (!process.argv[1]) throw new Error("Failed to resolve CLI entrypoint")
-  if (runtime === "node" || runtime === "nodejs") return [process.execPath, ...nodeFlags(), process.argv[1]]
-  return [process.execPath, process.argv[1]]
+  if (!entrypoint) throw new Error("Failed to resolve CLI entrypoint")
+  if (runtime === "node" || runtime === "nodejs") return [process.execPath, ...nodeFlags(), entrypoint]
+  return [process.execPath, entrypoint]
 }

 function nodeFlags() {
@@ -244,7 +244,7 @@ describe("acp event behavior", () => {
            sessionID: "ses_tools",
            assistantMessageID: "msg_tools",
            callID: "call_fail",
-            input: { filePath: "/workspace/missing.ts" },
+            input: { path: "/workspace/missing.ts" },
            executed: false,
          }),
        )
@@ -638,7 +638,7 @@ function replayFixtureMessages(): SessionMessageInfo[] {
          time: { created: 2, completed: 3 },
          state: {
            status: "error",
-            input: { filePath: "/workspace/missing.ts" },
+            input: { path: "/workspace/missing.ts" },
            metadata: { bytes: 0 },
            content: [{ type: "text", text: "partial" }],
            error: { type: "tool.error", message: "failed hard" },
@@ -49,7 +49,7 @@ describe("acp permission behavior", () => {
        send(
          permissionAsked("ses_allow", "perm_always", {
            action: "read",
-            metadata: { filePath: "/workspace/file.ts" },
+            metadata: { path: "/workspace/file.ts" },
            source: { type: "tool", messageID: "msg_allow", callID: "call_always" },
          }),
        )
@@ -96,7 +96,7 @@ describe("acp permission behavior", () => {
          title: "/workspace/file.ts",
          kind: "read",
          locations: [{ path: "/workspace/file.ts" }],
-          rawInput: { filePath: "/workspace/file.ts" },
+          rawInput: { path: "/workspace/file.ts" },
        },
      })
      expect(permissionReplies(fixture)).toEqual([
@@ -502,7 +502,7 @@ function permissionAsked(
    readonly source?: { readonly type: "tool"; readonly messageID: string; readonly callID: string }
  } = {},
 ) {
-  return ephemeralEvent("permission.v2.asked", {
+  return ephemeralEvent("permission.asked", {
    id,
    sessionID,
    action: input.action ?? "shell",
@@ -28,7 +28,7 @@ describe("acp tools", () => {
  })

  test("extracts file locations from tool input", () => {
-    expect(toLocations("read", { filePath: "/tmp/a.ts" })).toEqual([{ path: "/tmp/a.ts" }])
+    expect(toLocations("read", { path: "/tmp/a.ts" })).toEqual([{ path: "/tmp/a.ts" }])
    expect(toLocations("edit", { filePath: "/tmp/b.ts" })).toEqual([{ path: "/tmp/b.ts" }])
    expect(toLocations("write", { filePath: "/tmp/c.ts" })).toEqual([{ path: "/tmp/c.ts" }])
    expect(toLocations("grep", { path: "/repo/src" })).toEqual([{ path: "/repo/src" }])
@@ -43,7 +43,7 @@ describe("acp tools", () => {
    ])
    expect(toLocations("bash", { command: "pwd", workdir: "/abs/dir" }, "/workspace")).toEqual([{ path: "/abs/dir" }])
    expect(toLocations("bash", { command: "printf hello" })).toEqual([])
-    expect(toLocations("read", { path: "/tmp/missing-file-path.ts" })).toEqual([])
+    expect(toLocations("read", { path: "/tmp/missing-file-path.ts" })).toEqual([{ path: "/tmp/missing-file-path.ts" }])
  })

  test("builds completed content with text and image attachments", () => {
@@ -205,12 +205,13 @@ describe("acp tools", () => {
      runningToolUpdate({
        toolCallId: "call",
        toolName: "read",
-        state: { input: { filePath: "/tmp/a" } },
+        state: { input: { path: "/tmp/a" } },
        content: [{ type: "text", text: "done" }],
      }),
    ).toMatchObject({
      toolCallId: "call",
      status: "in_progress",
+      locations: [{ path: "/tmp/a" }],
      content: [{ type: "content", content: { type: "text", text: "done" } }],
    })
  })
@@ -273,7 +274,7 @@ describe("acp tools", () => {
      errorToolUpdate({
        toolCallId: "call",
        toolName: "read",
-        input: { filePath: "/tmp/a" },
+        input: { path: "/tmp/a" },
        content: [{ type: "text", text: "partial output" }],
        metadata: { path: "/tmp/a" },
        error: "failed",
@@ -284,7 +285,7 @@ describe("acp tools", () => {
      kind: "read",
      title: "read",
      locations: [{ path: "/tmp/a" }],
-      rawInput: { filePath: "/tmp/a" },
+      rawInput: { path: "/tmp/a" },
      content: [
        { type: "content", content: { type: "text", text: "partial output" } },
        { type: "content", content: { type: "text", text: "failed" } },
@@ -3,12 +3,14 @@ import { Service } from "@opencode-ai/client/effect/service"
 import path from "node:path"
 import { Standalone } from "../../src/services/standalone"

-process.argv[1] = path.join(import.meta.dir, "../../src/index.ts")
+process.chdir(path.join(import.meta.dir, "../../../.."))

 await Effect.runPromise(
  Effect.scoped(
    Effect.gen(function* () {
-      const endpoint = yield* Standalone.start()
+      const endpoint = yield* Standalone.start({
+        command: [process.execPath, path.join(import.meta.dir, "../../src/index.ts"), "serve"],
+      })
      const response = yield* Effect.promise(() =>
        fetch(new URL("/api/health", endpoint.url), { headers: Service.headers(endpoint) }),
      )
@@ -75,20 +75,11 @@ export const define = sdk.Plugin.define`
  const effectPluginModule = promisePluginModule
    .replace("opencode.plugin.v2.promise", "opencode.plugin.v2.effect")
    .replace("Promise plugin", "Effect plugin")
-  const promiseToolModule = `const sdk = globalThis[Symbol.for("opencode.plugin.v2.promise")]
-if (!sdk) throw new Error("OpenCode Promise plugin SDK is unavailable")
-export const Tool = sdk.Tool
-export const make = sdk.Tool.make`
+  const promiseToolModule = `export {}`
  const effectToolModule = `const sdk = globalThis[Symbol.for("opencode.plugin.v2.effect")]
 if (!sdk) throw new Error("OpenCode Effect plugin SDK is unavailable")
-export const Tool = sdk.Tool
-export const Failure = sdk.Tool.Failure
-export const RegistrationError = sdk.Tool.RegistrationError
-export const make = sdk.Tool.make
-export const validateName = sdk.Tool.validateName
-export const registrationEntries = sdk.Tool.registrationEntries
-export const validateNamespace = sdk.Tool.validateNamespace
-export const toLLMDefinition = sdk.Tool.toLLMDefinition`
+export const Error = sdk.Tool.Error
+`
  return `#!/usr/bin/env -S node ${nodeExecArgv.join(" ")}
 import __cjs_mod__ from "node:module"
 import { chmodSync as __ocChmod, existsSync as __ocExists, lstatSync as __ocLstat, mkdirSync as __ocMkdir, renameSync as __ocRename, rmSync as __ocRm, writeFileSync as __ocWrite } from "node:fs"
@@ -100,17 +91,17 @@ const __filename = import.meta.filename
 const __dirname = import.meta.dirname
 const require = __cjs_mod__.createRequire(import.meta.url)
 const __ocPluginModules = ${JSON.stringify({
-    "@opencode-ai/plugin/v2": "opencode:plugin-v2",
-    "@opencode-ai/plugin/v2/plugin": "opencode:plugin-v2-plugin",
-    "@opencode-ai/plugin/v2/tool": "opencode:plugin-v2-tool",
-    "@opencode-ai/plugin/v2/effect": "opencode:plugin-v2-effect",
-    "@opencode-ai/plugin/v2/effect/plugin": "opencode:plugin-v2-effect-plugin",
-    "@opencode-ai/plugin/v2/effect/tool": "opencode:plugin-v2-effect-tool",
+    "@opencode-ai/plugin": "opencode:plugin-v2",
+    "@opencode-ai/plugin/promise/plugin": "opencode:plugin-promise-plugin",
+    "@opencode-ai/plugin/promise/tool": "opencode:plugin-promise-tool",
+    "@opencode-ai/plugin/effect": "opencode:plugin-v2-effect",
+    "@opencode-ai/plugin/effect/plugin": "opencode:plugin-v2-effect-plugin",
+    "@opencode-ai/plugin/effect/tool": "opencode:plugin-v2-effect-tool",
  })}
 const __ocPluginSources = ${JSON.stringify({
    "opencode:plugin-v2": promiseModule,
-    "opencode:plugin-v2-plugin": promisePluginModule,
-    "opencode:plugin-v2-tool": promiseToolModule,
+    "opencode:plugin-promise-plugin": promisePluginModule,
+    "opencode:plugin-promise-tool": promiseToolModule,
    "opencode:plugin-v2-effect": effectModule,
    "opencode:plugin-v2-effect-plugin": effectPluginModule,
    "opencode:plugin-v2-effect-tool": effectToolModule,
@@ -1,17 +1,62 @@
 # @opencode-ai/client

-Private generation target for clients derived directly from OpenCode's authoritative Effect `HttpApi`.
+Promise and Effect clients derived from OpenCode's authoritative Effect `HttpApi`, plus handwritten Node transports.

 ## Entrypoints

 - `@opencode-ai/client`: zero-Effect Promise client using `fetch`.
+- `@opencode-ai/client/node`: Promise client plus Node-hosted browser attachments.
 - `@opencode-ai/client/effect`: rich Effect network client using an environment-provided `HttpClient`.

 The generated surface includes every standard HTTP group from Server's concrete API. The build compiler reads `@opencode-ai/server/api`; the generated Effect runtime imports a client-local projection built from Protocol, with a generation-equivalence test preventing transport drift. Custom transports such as the PTY WebSocket connection remain outside the generic HTTP client. Run `bun run generate` after changing the contract and `bun run check:generated` to detect committed-output drift.

 The Effect entrypoint uses canonical decoded values such as `Session.ID`, `Location.Ref`, and `Prompt`. These datatypes come from the lightweight `@opencode-ai/schema` package and are re-exported so callers depend only on the client surface. Protocol owns endpoint construction and middleware placement; Server supplies the concrete middleware keys used by the build-time API.

-The Promise root remains structural and has no Core or Effect runtime dependency. `/effect` depends only on Effect, Schema, and Protocol and is browser-bundle safe. Bundle-boundary tests enforce both import graphs.
+The Promise root remains structural and has no Core, Effect, Schema, Protocol, or WebSocket runtime dependency. `/node` adds Effect, Schema, Protocol, and `ws`, but never Core or Server. `/effect` depends only on Effect, Schema, and Protocol and is browser-bundle safe. Bundle-boundary tests enforce these import graphs.
+
+## Node browser attachments
+
+The Node entrypoint owns the control connection, Session lease, authenticated proxy, and network tunnels. Chromium hosts provide a small platform port once with `BrowserDriver.chromium`; the SDK owns command semantics, CDP input, snapshots, generations, cancellation, and limits.
+
+```ts
+import { BrowserDriver, OpenCode } from "@opencode-ai/client/node"
+
+const driver = BrowserDriver.chromium(async ({ proxy, signal }) => {
+  const view = await createChromiumView({ proxy, signal })
+  return {
+    resource: view,
+    state: () => view.state(),
+    subscribe: (listener) => view.subscribe((state, mainDocumentChanged) => listener({ state, mainDocumentChanged })),
+    navigate: (url) => view.navigate(url),
+    back: () => view.back(),
+    forward: () => view.forward(),
+    reload: () => view.reload(),
+    stop: () => view.stop(),
+    send: (method, params) => view.sendCDP(method, params),
+    viewport: () => view.viewport(),
+    screenshot: ({ maxDimension }) => view.capturePNG({ maxDimension }),
+    dispose: () => view.close(),
+  }
+})
+
+const client = OpenCode.make({
+  baseUrl: "https://opencode.example",
+  headers: { authorization: `Basic ${credentials}` },
+})
+const attachment = await client.browser.attach({ sessionID, driver })
+
+await attachment.resource.navigate("example.com")
+const view = attachment.resource.resource
+await attachment.close()
+```
+
+`attach` resolves only after the server acknowledges the exact Session lease. Each attachment has its own proxy and driver resource; `close()` and `Symbol.asyncDispose` are idempotent. A single Node client multiplexes up to 16 distinct Sessions over one lazily opened control WebSocket.
+
+Driver factories should return after configuring their resource rather than await a proxied navigation: tunnel dialing is deliberately held behind the first lease acknowledgement, which is published after the driver supplies its initial state.
+
+Port state events set `mainDocumentChanged` only when the main document changes; this advances the public generation and invalidates element refs. `send` must dispatch CDP calls in invocation order. `screenshot` returns PNG bytes and dimensions, proportionally scaled to `maxDimension` without upscaling. The returned controller serializes local navigation with remote commands; `stop` immediately interrupts active work, and controller disposal is idempotent. An aborted or timed-out operation that reached the platform disposes the port so late native completion cannot cross the queue fence.
+
+`BrowserDriver` descriptors are structural factory functions, so adapters remain compatible across duplicate client package instances. The Node entrypoint also re-exports canonical `Browser` contracts. `BrowserDriver.define` remains the advanced escape hatch for non-Chromium semantics; throw `BrowserDriverError` for typed command failures there. Structurally equivalent errors are accepted only when their `code` is a valid `Browser.ErrorCode`.

 Effect consumers construct canonical decoded inputs:

@@ -17,6 +17,7 @@
  ],
  "exports": {
    ".": "./src/promise/index.ts",
+    "./node": "./src/node/index.ts",
    "./promise": "./src/promise/index.ts",
    "./promise/api": "./src/promise/api.ts",
    "./service": "./src/promise/service.ts",
@@ -28,15 +29,17 @@
    "build": "bun run script/build-package.ts",
    "generate": "bun run script/build.ts",
    "check:generated": "bun run generate && git diff --exit-code -- src/promise/generated src/effect/generated src/effect/api",
-    "test": "bun test --timeout 5000",
-    "typecheck": "tsgo --noEmit"
+    "test": "bun test --timeout 5000 && bun run test:node-package",
+    "test:node-package": "bun test ./test/node/package-smoke.ts --timeout 60000",
+    "typecheck": "tsgo --noEmit && tsgo -p test/types/tsconfig.json --noEmit && tsgo -p test/types/tsconfig.nodenext.json --noEmit"
  },
  "dependencies": {
    "@opencode-ai/schema": "workspace:*",
-    "@opencode-ai/protocol": "workspace:*"
+    "@opencode-ai/protocol": "workspace:*",
+    "ws": "8.21.0"
  },
  "peerDependencies": {
-    "effect": "4.0.0-beta.98"
+    "effect": "4.0.0-beta.101"
  },
  "peerDependenciesMeta": {
    "effect": {
@@ -48,6 +51,7 @@
    "@opencode-ai/httpapi-codegen": "workspace:*",
    "@tsconfig/bun": "catalog:",
    "@types/bun": "catalog:",
+    "@types/ws": "8.18.1",
    "@typescript/native-preview": "catalog:",
    "effect": "catalog:"
  }
@@ -7,3 +7,4 @@ process.chdir(fileURLToPath(new URL("..", import.meta.url)))

 await $`rm -rf dist`
 await $`bun tsc -p tsconfig.build.json`
+await $`bun build src/node/index.ts --outfile dist/node/index.js --target=node --format=esm --packages=external`
@@ -6,11 +6,86 @@ import {
  groupNames,
  promiseOmitEndpoints,
 } from "@opencode-ai/protocol/client"
-import { Effect } from "effect"
+import { Agent } from "@opencode-ai/schema/agent"
+import { Command } from "@opencode-ai/schema/command"
+import { Credential } from "@opencode-ai/schema/credential"
+import { Event } from "@opencode-ai/schema/event"
+import { EventLog } from "@opencode-ai/schema/event-log"
+import { FileDiff } from "@opencode-ai/schema/file-diff"
+import { FileSystem } from "@opencode-ai/schema/filesystem"
+import { Form } from "@opencode-ai/schema/form"
+import { InstructionEntry } from "@opencode-ai/schema/instruction-entry"
+import { Integration } from "@opencode-ai/schema/integration"
+import { Location } from "@opencode-ai/schema/location"
+import { Mcp } from "@opencode-ai/schema/mcp"
+import { Model } from "@opencode-ai/schema/model"
+import { Permission } from "@opencode-ai/schema/permission"
+import { PermissionSaved } from "@opencode-ai/schema/permission-saved"
+import { Plugin } from "@opencode-ai/schema/plugin"
+import { Project } from "@opencode-ai/schema/project"
+import { ProjectCopy } from "@opencode-ai/schema/project-copy"
+import { AgentAttachment, FileAttachment, Prompt, PromptMention } from "@opencode-ai/schema/prompt"
+import { PromptInput } from "@opencode-ai/schema/prompt-input"
+import { Provider } from "@opencode-ai/schema/provider"
+import { Pty } from "@opencode-ai/schema/pty"
+import { PtyTicket } from "@opencode-ai/schema/pty-ticket"
+import { Question } from "@opencode-ai/schema/question"
+import { Reference } from "@opencode-ai/schema/reference"
+import { AbsolutePath, PositiveInt, RelativePath } from "@opencode-ai/schema/schema"
+import { Session } from "@opencode-ai/schema/session"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { SessionPending } from "@opencode-ai/schema/session-pending"
+import { Shell } from "@opencode-ai/schema/shell"
+import { Skill } from "@opencode-ai/schema/skill"
+import { Vcs } from "@opencode-ai/schema/vcs"
+import { WebSearch } from "@opencode-ai/schema/websearch"
+import { Workspace } from "@opencode-ai/schema/workspace"
+import { Effect, Schema } from "effect"
 import { fileURLToPath } from "url"

 const promiseContract = compile(ClientApi, { groupNames, omitEndpoints: promiseOmitEndpoints })
 const effectContract = compile(ClientApi, { groupNames, omitEndpoints: effectOmitEndpoints })
+const effectTypeReferences = [
+  ...namespaceTypes("Agent", "@opencode-ai/schema/agent", Agent),
+  ...namespaceTypes("Command", "@opencode-ai/schema/command", Command),
+  ...namespaceTypes("Credential", "@opencode-ai/schema/credential", Credential),
+  ...namespaceTypes("Event", "@opencode-ai/schema/event", Event),
+  ...namespaceTypes("EventLog", "@opencode-ai/schema/event-log", EventLog),
+  ...namespaceTypes("FileDiff", "@opencode-ai/schema/file-diff", FileDiff),
+  ...namespaceTypes("FileSystem", "@opencode-ai/schema/filesystem", FileSystem),
+  ...namespaceTypes("Form", "@opencode-ai/schema/form", Form),
+  ...namespaceTypes("InstructionEntry", "@opencode-ai/schema/instruction-entry", InstructionEntry),
+  ...namespaceTypes("Integration", "@opencode-ai/schema/integration", Integration),
+  ...namespaceTypes("Location", "@opencode-ai/schema/location", Location),
+  ...namespaceTypes("Mcp", "@opencode-ai/schema/mcp", Mcp),
+  ...namespaceTypes("Model", "@opencode-ai/schema/model", Model),
+  ...namespaceTypes("Permission", "@opencode-ai/schema/permission", Permission),
+  ...namespaceTypes("PermissionSaved", "@opencode-ai/schema/permission-saved", PermissionSaved),
+  ...namespaceTypes("Plugin", "@opencode-ai/schema/plugin", Plugin),
+  ...namespaceTypes("Project", "@opencode-ai/schema/project", Project),
+  ...namespaceTypes("ProjectCopy", "@opencode-ai/schema/project-copy", ProjectCopy),
+  ...namespaceTypes("PromptInput", "@opencode-ai/schema/prompt-input", PromptInput),
+  ...namespaceTypes("Provider", "@opencode-ai/schema/provider", Provider),
+  ...namespaceTypes("Pty", "@opencode-ai/schema/pty", Pty),
+  ...namespaceTypes("PtyTicket", "@opencode-ai/schema/pty-ticket", PtyTicket),
+  ...namespaceTypes("Question", "@opencode-ai/schema/question", Question),
+  ...namespaceTypes("Reference", "@opencode-ai/schema/reference", Reference),
+  ...namespaceTypes("Session", "@opencode-ai/schema/session", Session),
+  ...namespaceTypes("SessionMessage", "@opencode-ai/schema/session-message", SessionMessage),
+  ...namespaceTypes("SessionPending", "@opencode-ai/schema/session-pending", SessionPending),
+  ...namespaceTypes("Shell", "@opencode-ai/schema/shell", Shell),
+  ...namespaceTypes("Skill", "@opencode-ai/schema/skill", Skill),
+  ...namespaceTypes("Vcs", "@opencode-ai/schema/vcs", Vcs),
+  ...namespaceTypes("WebSearch", "@opencode-ai/schema/websearch", WebSearch),
+  ...namespaceTypes("Workspace", "@opencode-ai/schema/workspace", Workspace),
+  typeReference("Prompt", "@opencode-ai/schema/prompt", Prompt),
+  typeReference("PromptMention", "@opencode-ai/schema/prompt", PromptMention),
+  typeReference("FileAttachment", "@opencode-ai/schema/prompt", FileAttachment),
+  typeReference("AgentAttachment", "@opencode-ai/schema/prompt", AgentAttachment),
+  typeReference("AbsolutePath", "@opencode-ai/schema/schema", AbsolutePath),
+  typeReference("PositiveInt", "@opencode-ai/schema/schema", PositiveInt),
+  typeReference("RelativePath", "@opencode-ai/schema/schema", RelativePath),
+]

 await Effect.runPromise(
  Effect.all(
@@ -22,14 +97,40 @@ await Effect.runPromise(
        fileURLToPath(new URL("../src/promise/generated", import.meta.url)),
      ),
      write(
-        emitEffectImported(effectContract, { module: "../../contract", api: "ClientApi" }),
+        emitEffectImported(effectContract, {
+          module: "../../contract",
+          api: "ClientApi",
+          shapeModule: "../api/api.js",
+        }),
        fileURLToPath(new URL("../src/effect/generated", import.meta.url)),
      ),
      write(
-        emitEffectShape(effectContract, { module: "../../contract", api: "ClientApi" }),
+        emitEffectShape(effectContract, {
+          typeReferences: effectTypeReferences,
+          outputTypes: {
+            "event.subscribe": {
+              name: "OpenCodeEvent",
+              import: 'import type { OpenCodeEvent } from "@opencode-ai/protocol/groups/event"',
+            },
+          },
+        }),
        fileURLToPath(new URL("../src/effect/api", import.meta.url)),
      ),
    ],
    { concurrency: 3, discard: true },
  ).pipe(Effect.provide(NodeFileSystem.layer)),
 )
+
+function namespaceTypes(namespace: string, module: string, values: object) {
+  return Object.entries(values).flatMap(([name, schema]) =>
+    Schema.isSchema(schema) ? [typeReference(`${namespace}.${name}`, module, schema)] : [],
+  )
+}
+
+function typeReference(name: string, module: string, schema: Schema.Top) {
+  return {
+    schema,
+    name,
+    import: `import type { ${name.split(".")[0]} } from ${JSON.stringify(module)}`,
+  }
+}
@@ -1,7 +1,9 @@
-import type { ModelApi, ProviderApi } from "./api/api.js"
+import type { ModelApi, ProviderApi, WebsearchApi } from "./api/api.js"

 export type * from "./api/api.js"

+export type WebSearchApi<E = never> = WebsearchApi<E>
+
 export interface CatalogApi<E = never> {
  readonly provider: ProviderApi<E>
  readonly model: ModelApi<E>
@@ -1,2 +1,2 @@
-export { ClientError } from "./client-error"
-export * as OpenCode from "./client"
+export { ClientError } from "./client-error.js"
+export * as OpenCode from "./client.js"
@@ -14,6 +14,7 @@ export type {
  PluginApi,
  ProviderApi,
  ReferenceApi,
+  WebSearchApi,
  SessionApi,
  SkillApi,
 } from "./api.js"
@@ -35,6 +36,7 @@ export { Provider } from "@opencode-ai/schema/provider"
 export { Pty } from "@opencode-ai/schema/pty"
 export { Question } from "@opencode-ai/schema/question"
 export { Reference } from "@opencode-ai/schema/reference"
+export { WebSearch } from "@opencode-ai/schema/websearch"
 export { AbsolutePath, RelativePath } from "@opencode-ai/schema/schema"
 export { Session } from "@opencode-ai/schema/session"
 export { SessionPending } from "@opencode-ai/schema/session-pending"
@@ -0,0 +1,639 @@
+import { BrowserControlProtocol } from "@opencode-ai/protocol/browser-control"
+import { BROWSER_CONTROL_PROTOCOL } from "@opencode-ai/protocol/groups/browser"
+import { Browser } from "@opencode-ai/schema/browser"
+import { BrowserControl } from "@opencode-ai/schema/browser-control"
+import { Session } from "@opencode-ai/schema/session"
+import { Effect, Schema } from "effect"
+import WebSocket from "ws"
+import type { ClientOptions } from "../../promise/generated/client.js"
+import {
+  browserDriverFactory,
+  type BrowserDriver,
+  type BrowserDriverContext,
+  type BrowserDriverInstance,
+  type BrowserProxy,
+} from "./driver.js"
+import { createBrowserProxy } from "./proxy.js"
+import { openBrowserTunnel, type BrowserTunnelEndpoint } from "./tunnel.js"
+
+export interface BrowserAttachOptions<Resource> {
+  readonly sessionID: string
+  readonly driver: BrowserDriver<Resource>
+  readonly signal?: AbortSignal
+}
+
+export interface BrowserAttachment<Resource> extends AsyncDisposable {
+  readonly resource: Resource
+  readonly close: () => Promise<void>
+}
+
+export interface BrowserClient {
+  readonly attach: <Resource>(options: BrowserAttachOptions<Resource>) => Promise<BrowserAttachment<Resource>>
+}
+
+type ProxyServer = Awaited<ReturnType<typeof createBrowserProxy>>
+
+type AttachmentRecord = {
+  readonly sessionID: Session.ID
+  readonly leaseID: Browser.LeaseID
+  readonly abort: AbortController
+  readonly setup: Promise<void>
+  readonly finishSetup: () => void
+  readonly externalSignal?: AbortSignal
+  externalAbort?: () => void
+  active: boolean
+  closed: boolean
+  state?: Browser.State
+  execute?: BrowserDriverInstance<unknown>["execute"]
+  dispose?: BrowserDriverInstance<unknown>["dispose"]
+  unsubscribe?: () => void
+  proxy?: ProxyServer
+  closing?: Promise<void>
+}
+
+type ActiveAttachment = AttachmentRecord & {
+  readonly active: true
+  readonly state: Browser.State
+  readonly execute: BrowserDriverInstance<unknown>["execute"]
+}
+
+type Waiter = {
+  readonly key: string
+  readonly signal: AbortSignal
+  readonly resolve: () => void
+  readonly reject: (error: Error) => void
+  readonly abort: () => void
+}
+
+/** Creates the Node-only browser host attached to one immutable server endpoint. */
+export function createBrowserClient(options: ClientOptions): BrowserClient {
+  const control = new BrowserClientControl(endpoint(options))
+  return { attach: (input) => control.attach(input) }
+}
+
+class BrowserClientControl {
+  private readonly records = new Map<Session.ID, AttachmentRecord>()
+  private readonly requests = new Map<
+    BrowserControl.RequestID,
+    { readonly leaseID: Browser.LeaseID; readonly abort: AbortController }
+  >()
+  private readonly waiters = new Set<Waiter>()
+  private socket?: WebSocket
+  private retry?: ReturnType<typeof setTimeout>
+  private retryAttempt = 0
+  private revision = 0
+  private ready = false
+  private opening?: Promise<void>
+  private openingAbort?: AbortController
+  private synced?: string
+  private syncing?: { readonly revision: number; readonly snapshot: string; readonly leases: Set<string> }
+  private syncedLeases = new Set<string>()
+  private inbound = Promise.resolve()
+  private failing = false
+
+  constructor(private readonly server: BrowserTunnelEndpoint) {}
+
+  async attach<Resource>(input: BrowserAttachOptions<Resource>): Promise<BrowserAttachment<Resource>> {
+    if (!Schema.is(Session.ID)(input.sessionID)) throw new TypeError("Browser attachment requires a valid Session ID")
+    if (input.signal?.aborted) throw abortError(input.signal, "Browser attachment was aborted")
+    const sessionID = Session.ID.make(input.sessionID)
+    if (this.records.has(sessionID)) throw new Error(`Browser is already attached to Session ${sessionID}`)
+    if (this.records.size >= 16) throw new Error("A Node client cannot attach more than 16 browser Sessions")
+
+    let finishSetup!: () => void
+    const setup = new Promise<void>((resolve) => {
+      finishSetup = resolve
+    })
+    const record: AttachmentRecord = {
+      sessionID,
+      leaseID: Browser.LeaseID.create(),
+      abort: new AbortController(),
+      setup,
+      finishSetup,
+      externalSignal: input.signal,
+      active: false,
+      closed: false,
+    }
+    this.records.set(sessionID, record)
+    record.externalAbort = () => {
+      void this.close(record, abortError(input.signal, "Browser attachment was aborted")).catch(() => undefined)
+    }
+    input.signal?.addEventListener("abort", record.externalAbort, { once: true })
+
+    try {
+      record.proxy = await createBrowserProxy({
+        connect: async (target, signal) => {
+          await this.waitForAttachment(record, signal)
+          const tunnelSignal = AbortSignal.any([signal, record.abort.signal])
+          if (tunnelSignal.aborted) throw abortError(tunnelSignal, "Browser tunnel was aborted")
+          return openBrowserTunnel({
+            endpoint: this.server,
+            sessionID: record.sessionID,
+            leaseID: record.leaseID,
+            target,
+            signal: tunnelSignal,
+          })
+        },
+      })
+      this.requireOpen(record)
+
+      const instance = await createDriver(
+        input.driver,
+        { proxy: exposedProxy(record.proxy), signal: record.abort.signal },
+        record.abort.signal,
+      )
+      if (instance !== null && typeof instance === "object" && typeof instance.dispose === "function") {
+        record.dispose = () => instance.dispose()
+      }
+      if (
+        instance === null ||
+        typeof instance !== "object" ||
+        typeof instance.state !== "function" ||
+        typeof instance.subscribe !== "function" ||
+        typeof instance.execute !== "function" ||
+        typeof instance.dispose !== "function"
+      ) {
+        throw new TypeError("Browser driver factory returned an invalid driver instance")
+      }
+      record.execute = (command, options) => instance.execute(command, options)
+
+      let receivedState = false
+      record.unsubscribe = instance.subscribe((state) => {
+        if (record.closed) return
+        const next = contractState(state)
+        if (!next) {
+          void this.close(record, new TypeError("Browser driver published an invalid state")).catch(() => undefined)
+          return
+        }
+        receivedState = true
+        record.state = next
+        if (record.active) this.changed()
+      })
+      if (typeof record.unsubscribe !== "function") {
+        throw new TypeError("Browser driver subscribe must return an unsubscribe function")
+      }
+      const initial = contractState(instance.state())
+      if (!initial) throw new TypeError("Browser driver returned an invalid initial state")
+      if (!receivedState) record.state = initial
+      this.requireOpen(record)
+
+      record.active = true
+      this.changed()
+      record.finishSetup()
+      await this.waitForAttachment(record, record.abort.signal)
+      this.requireOpen(record)
+
+      const close = () => this.close(record)
+      return Object.freeze({
+        resource: instance.resource,
+        close,
+        [Symbol.asyncDispose]: close,
+      })
+    } catch (error) {
+      record.finishSetup()
+      await this.close(record).catch(() => undefined)
+      throw error
+    }
+  }
+
+  private close(record: AttachmentRecord, reason = new Error("Browser attachment was closed")) {
+    if (!record.closed) {
+      record.closed = true
+      record.active = false
+      if (this.records.get(record.sessionID) === record) this.records.delete(record.sessionID)
+      record.abort.abort(reason)
+      this.syncedLeases.delete(attachmentKey(record.sessionID, record.leaseID))
+      this.rejectAttachmentWaiters(record, reason)
+      this.abortRequests(record.leaseID)
+      this.changed()
+    }
+    if (record.closing) return record.closing
+    record.closing = record.setup.then(async () => {
+      if (record.externalAbort) record.externalSignal?.removeEventListener("abort", record.externalAbort)
+      const unsubscribe = await cleanup(() => record.unsubscribe?.())
+      const dispose = await cleanup(() => record.dispose?.())
+      const proxy = await cleanup(() => record.proxy?.close())
+      const failure = [unsubscribe, dispose, proxy].find(
+        (result): result is { readonly ok: false; readonly error: unknown } => !result.ok,
+      )
+      if (failure) throw failure.error
+    })
+    return record.closing
+  }
+
+  private requireOpen(record: AttachmentRecord) {
+    if (!record.closed && !record.abort.signal.aborted) return
+    throw abortError(record.abort.signal, "Browser attachment was closed")
+  }
+
+  private changed() {
+    if (this.failing) return
+    if (this.attachments().length === 0) {
+      this.stopControl()
+      return
+    }
+    this.connect()
+    this.publish()
+  }
+
+  private attachments() {
+    return [...this.records.values()].filter(
+      (record): record is ActiveAttachment =>
+        record.active && record.state !== undefined && record.execute !== undefined && !record.closed,
+    )
+  }
+
+  private connect() {
+    if (this.socket || this.retry || this.opening || this.attachments().length === 0) return
+    const abort = new AbortController()
+    this.openingAbort = abort
+    this.opening = this.open(abort.signal)
+      .catch((error) => this.failControl(error instanceof Error ? error : new Error(String(error))))
+      .finally(() => {
+        if (this.openingAbort !== abort) return
+        this.openingAbort = undefined
+        this.opening = undefined
+      })
+  }
+
+  private async open(lifetime: AbortSignal) {
+    if (process.versions.bun) {
+      // TODO: Remove the HTTP auth probe once Bun exposes ws upgrade responses.
+      // https://github.com/oven-sh/bun/issues/5951
+      const signal = AbortSignal.any([lifetime, AbortSignal.timeout(10_000)])
+      const response = await (this.server.fetch ?? globalThis.fetch)(new URL("/api/health", this.server.url), {
+        headers: this.server.authorization ? { Authorization: this.server.authorization } : undefined,
+        signal,
+      }).catch(() => undefined)
+      if (lifetime.aborted) return
+      if (!response) {
+        this.scheduleReconnect()
+        return
+      }
+      if (response.status === 401 || response.status === 403) {
+        this.failControl(new Error(`Browser control connection was rejected with HTTP ${response.status}`))
+        return
+      }
+    }
+    if (this.socket || this.retry || this.attachments().length === 0) return
+    const socket = new WebSocket(controlURL(this.server), BROWSER_CONTROL_PROTOCOL, {
+      ...(this.server.authorization ? { headers: { Authorization: this.server.authorization } } : {}),
+      handshakeTimeout: 10_000,
+      maxPayload: BrowserControlProtocol.MaxMessageBytes,
+      perMessageDeflate: false,
+      followRedirects: false,
+    })
+    this.socket = socket
+    socket.on("message", (data, binary) => {
+      if (socket !== this.socket) return
+      this.inbound = this.inbound.then(
+        () => this.receive(socket, data, binary),
+        () => this.receive(socket, data, binary),
+      )
+    })
+    socket.on("error", (error) => {
+      if (socket !== this.socket) return
+      const status = /^Unexpected server response: (401|403|426)$/.exec(error.message)?.[1]
+      if (status) this.failControl(new Error(`Browser control connection was rejected with HTTP ${status}`))
+    })
+    if (!process.versions.bun) {
+      socket.on("unexpected-response", (_request, response) => {
+        response.resume()
+        if (socket !== this.socket) return
+        if (response.statusCode === 401 || response.statusCode === 403 || response.statusCode === 426) {
+          this.failControl(new Error(`Browser control connection was rejected with HTTP ${response.statusCode}`))
+          return
+        }
+        socket.terminate()
+      })
+    }
+    socket.on("close", (code, reason) => {
+      if (socket !== this.socket) return
+      if (code === 1002 || code === 1007 || code === 1009) {
+        this.failControl(controlCloseError(code, reason))
+        return
+      }
+      this.socket = undefined
+      this.resetConnection()
+      this.scheduleReconnect()
+    })
+  }
+
+  private async receive(socket: WebSocket, data: WebSocket.RawData, binary: boolean) {
+    if (binary) return this.protocolError(socket)
+    const decoded = await Effect.runPromise(BrowserControlProtocol.decodeFromServer(rawData(data))).catch(
+      () => undefined,
+    )
+    if (!decoded || socket !== this.socket) return this.protocolError(socket)
+    if (decoded.type === "browser.control.ready") {
+      if (this.ready) return this.protocolError(socket)
+      this.ready = true
+      this.publish()
+      return
+    }
+    if (!this.ready) return this.protocolError(socket)
+    if (decoded.type === "browser.control.synced") {
+      if (!this.syncing || this.syncing.revision !== decoded.revision) return this.protocolError(socket)
+      this.synced = this.syncing.snapshot
+      this.syncedLeases = this.syncing.leases
+      this.syncing = undefined
+      this.retryAttempt = 0
+      this.resolveWaiters()
+      this.publish()
+      return
+    }
+    if (decoded.type === "browser.control.cancel") {
+      const request = this.requests.get(decoded.requestID)
+      if (!request) return
+      if (request.leaseID !== decoded.leaseID) return this.protocolError(socket)
+      this.requests.delete(decoded.requestID)
+      request.abort.abort(new Error("Browser command was cancelled"))
+      return
+    }
+    void this.request(socket, decoded)
+  }
+
+  private publish() {
+    const socket = this.socket
+    if (!socket || socket.readyState !== WebSocket.OPEN || !this.ready || this.syncing) return
+    const attachments = this.attachments().map((record) => ({
+      sessionID: record.sessionID,
+      leaseID: record.leaseID,
+      state: record.state,
+    }))
+    const snapshot = JSON.stringify(attachments)
+    if (snapshot === this.synced) return
+    const revision = this.revision++
+    this.syncing = {
+      revision,
+      snapshot,
+      leases: new Set(attachments.map((attachment) => attachmentKey(attachment.sessionID, attachment.leaseID))),
+    }
+    this.send(socket, { type: "browser.control.sync", revision, attachments })
+  }
+
+  private async request(socket: WebSocket, message: BrowserControl.Request) {
+    if (this.requests.has(message.requestID)) return this.protocolError(socket)
+    const record = this.records.get(message.sessionID)
+    if (!record?.active || record.closed || record.leaseID !== message.leaseID || !record.execute) {
+      this.send(socket, {
+        type: "browser.control.response",
+        requestID: message.requestID,
+        leaseID: message.leaseID,
+        outcome: { type: "failure", code: "not_attached", message: "The browser attachment is no longer available." },
+      })
+      return
+    }
+
+    const abort = new AbortController()
+    this.requests.set(message.requestID, { leaseID: message.leaseID, abort })
+    const outcome = await Promise.resolve()
+      .then(() => record.execute?.(message.command, { signal: abort.signal }))
+      .then(
+        (result): Browser.Outcome => {
+          if (!Schema.is(Browser.Result)(result) || result.type !== message.command.type) {
+            return { type: "failure", code: "protocol", message: "Browser driver returned an invalid command result." }
+          }
+          return { type: "success", result }
+        },
+        (error): Browser.Outcome => driverFailure(error),
+      )
+    if (this.requests.get(message.requestID)?.abort !== abort) return
+    this.requests.delete(message.requestID)
+    if (socket !== this.socket) return
+    this.send(socket, {
+      type: "browser.control.response",
+      requestID: message.requestID,
+      leaseID: message.leaseID,
+      outcome,
+    })
+    if (outcome.type === "success") {
+      const state = contractState(outcome.result.state)
+      if (state) {
+        record.state = state
+        this.changed()
+      }
+    }
+  }
+
+  private send(socket: WebSocket, message: BrowserControl.FromDesktop) {
+    if (socket !== this.socket || socket.readyState !== WebSocket.OPEN) return
+    socket.send(BrowserControlProtocol.encodeFromDesktop(message), (error) => {
+      if (error && socket === this.socket) socket.terminate()
+    })
+  }
+
+  private protocolError(socket: WebSocket) {
+    if (socket.readyState === WebSocket.OPEN) socket.close(1002, "Invalid browser control message")
+    else socket.terminate()
+  }
+
+  private waitForAttachment(record: AttachmentRecord, signal: AbortSignal) {
+    const key = attachmentKey(record.sessionID, record.leaseID)
+    if (record.closed || this.records.get(record.sessionID) !== record) {
+      return Promise.reject(new Error("Browser attachment is no longer available"))
+    }
+    if (record.active && this.syncedLeases.has(key)) return Promise.resolve()
+    if (signal.aborted) return Promise.reject(abortError(signal, "Browser attachment wait was aborted"))
+    return new Promise<void>((resolve, reject) => {
+      const waiter: Waiter = {
+        key,
+        signal,
+        resolve,
+        reject,
+        abort: () => {
+          this.waiters.delete(waiter)
+          reject(abortError(signal, "Browser attachment wait was aborted"))
+        },
+      }
+      signal.addEventListener("abort", waiter.abort, { once: true })
+      this.waiters.add(waiter)
+    })
+  }
+
+  private resolveWaiters() {
+    for (const waiter of this.waiters) {
+      if (!this.syncedLeases.has(waiter.key)) continue
+      const record = [...this.records.values()].find(
+        (item) => !item.closed && item.active && attachmentKey(item.sessionID, item.leaseID) === waiter.key,
+      )
+      if (!record) continue
+      this.waiters.delete(waiter)
+      waiter.signal.removeEventListener("abort", waiter.abort)
+      waiter.resolve()
+    }
+  }
+
+  private rejectAttachmentWaiters(record: AttachmentRecord, error: Error) {
+    const key = attachmentKey(record.sessionID, record.leaseID)
+    for (const waiter of this.waiters) {
+      if (waiter.key !== key) continue
+      this.waiters.delete(waiter)
+      waiter.signal.removeEventListener("abort", waiter.abort)
+      waiter.reject(error)
+    }
+  }
+
+  private abortRequests(leaseID?: Browser.LeaseID) {
+    for (const [requestID, request] of this.requests) {
+      if (leaseID && request.leaseID !== leaseID) continue
+      this.requests.delete(requestID)
+      request.abort.abort(new Error("Browser command was aborted"))
+    }
+  }
+
+  private stopControl() {
+    this.openingAbort?.abort()
+    this.openingAbort = undefined
+    this.opening = undefined
+    if (this.retry) clearTimeout(this.retry)
+    this.retry = undefined
+    const socket = this.socket
+    this.socket = undefined
+    this.resetConnection()
+    socket?.terminate()
+  }
+
+  private failControl(error: Error) {
+    this.failing = true
+    this.stopControl()
+    this.retryAttempt = 0
+    const records = [...this.records.values()]
+    records.forEach((record) => {
+      void this.close(record, error).catch(() => undefined)
+    })
+    this.failing = false
+  }
+
+  private resetConnection() {
+    this.ready = false
+    this.synced = undefined
+    this.syncedLeases.clear()
+    this.syncing = undefined
+    this.revision = 0
+    this.abortRequests()
+  }
+
+  private scheduleReconnect() {
+    if (this.retry || this.attachments().length === 0) return
+    const delay = Math.min(5_000, 100 * 2 ** this.retryAttempt++)
+    this.retry = setTimeout(() => {
+      this.retry = undefined
+      this.connect()
+    }, delay)
+    this.retry.unref()
+  }
+}
+
+function createDriver<Resource>(driver: BrowserDriver<Resource>, context: BrowserDriverContext, signal: AbortSignal) {
+  const creating = Promise.resolve().then(() => browserDriverFactory(driver)(context))
+  return new Promise<BrowserDriverInstance<Resource>>((resolve, reject) => {
+    let settled = false
+    const abort = () => {
+      if (settled) return
+      settled = true
+      signal.removeEventListener("abort", abort)
+      reject(abortError(signal, "Browser driver creation was aborted"))
+    }
+    signal.addEventListener("abort", abort, { once: true })
+    creating.then(
+      (instance) => {
+        if (settled) {
+          void disposeLateDriver(instance)
+          return
+        }
+        settled = true
+        signal.removeEventListener("abort", abort)
+        resolve(instance)
+      },
+      (error) => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener("abort", abort)
+        reject(error)
+      },
+    )
+    if (signal.aborted) abort()
+  })
+}
+
+async function disposeLateDriver(instance: unknown) {
+  if (instance === null || typeof instance !== "object" || !("dispose" in instance)) return
+  const dispose = instance.dispose
+  if (typeof dispose !== "function") return
+  await Promise.resolve()
+    .then(() => dispose.call(instance))
+    .catch(() => undefined)
+}
+
+function cleanup(task: () => unknown) {
+  return Promise.resolve()
+    .then(task)
+    .then(
+      () => ({ ok: true as const }),
+      (error: unknown) => ({ ok: false as const, error }),
+    )
+}
+
+function exposedProxy(proxy: ProxyServer): BrowserProxy {
+  return Object.freeze({
+    url: proxy.url,
+    host: proxy.host,
+    port: proxy.port,
+    credentials: Object.freeze({ ...proxy.credentials }),
+    certificateFingerprint: proxy.certificateFingerprint,
+  })
+}
+
+function contractState(state: Browser.State) {
+  if (!Schema.is(Browser.State)(state)) return undefined
+  return Object.freeze({ ...state })
+}
+
+function driverFailure(error: unknown): Browser.Failure {
+  return {
+    type: "failure",
+    code:
+      error !== null && typeof error === "object" && "code" in error && Schema.is(Browser.ErrorCode)(error.code)
+        ? error.code
+        : "internal",
+    message: (error instanceof Error ? error.message : String(error)).slice(0, 1_024),
+  }
+}
+
+function endpoint(options: ClientOptions): BrowserTunnelEndpoint {
+  const url = new URL(options.baseUrl)
+  if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
+    throw new TypeError("Browser server endpoint must be an HTTP URL without embedded credentials")
+  }
+  const authorization = new Headers(options.headers).get("authorization") ?? undefined
+  return Object.freeze({ url: url.href, ...(authorization ? { authorization } : {}), fetch: options.fetch })
+}
+
+function controlURL(endpoint: BrowserTunnelEndpoint) {
+  const url = new URL(endpoint.url)
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:"
+  url.pathname = "/api/browser/control"
+  url.search = ""
+  url.hash = ""
+  return url
+}
+
+function attachmentKey(sessionID: string, leaseID: Browser.LeaseID) {
+  return `${sessionID}\0${leaseID}`
+}
+
+function abortError(signal: AbortSignal | undefined, message: string) {
+  return signal?.reason instanceof Error ? signal.reason : new Error(message)
+}
+
+function controlCloseError(code: number, reason: Buffer) {
+  const detail = reason.toString("utf8").slice(0, 256)
+  return new Error(`Browser control connection closed with fatal code ${code}${detail ? `: ${detail}` : ""}`)
+}
+
+function rawData(data: WebSocket.RawData) {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data)
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data))
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+}
@@ -0,0 +1,65 @@
+import type { Browser } from "@opencode-ai/schema/browser"
+import { chromiumDriver, type ChromiumDriver, type ChromiumPort } from "./chromium.js"
+
+/** Connection details for the attachment's private authenticated proxy. */
+export interface BrowserProxy {
+  readonly url: string
+  readonly host: string
+  readonly port: number
+  readonly credentials: {
+    readonly username: string
+    readonly password: string
+  }
+  readonly certificateFingerprint: string
+}
+
+export interface BrowserDriverContext {
+  readonly proxy: BrowserProxy
+  readonly signal: AbortSignal
+}
+
+export interface BrowserDriverInstance<Resource> {
+  readonly resource: Resource
+  readonly state: () => Browser.State
+  readonly subscribe: (listener: (state: Browser.State) => void) => () => void
+  readonly execute: (command: Browser.Command, options: { readonly signal: AbortSignal }) => Promise<Browser.Result>
+  readonly dispose: () => Promise<void> | void
+}
+
+export type BrowserDriverFactory<Resource> = (
+  context: BrowserDriverContext,
+) => Promise<BrowserDriverInstance<Resource>> | BrowserDriverInstance<Resource>
+
+/** Error returned to the server when a browser adapter cannot execute a command. */
+export class BrowserDriverError extends Error {
+  override readonly name = "BrowserDriverError"
+
+  constructor(
+    readonly code: Browser.ErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+}
+
+/** Structural adapter descriptor, represented by its factory function. */
+export type BrowserDriver<Resource> = BrowserDriverFactory<Resource>
+
+export const BrowserDriver = {
+  define<Resource>(create: BrowserDriverFactory<Resource>): BrowserDriver<Resource> {
+    if (typeof create !== "function") throw new TypeError("Browser driver factory must be a function")
+    return Object.freeze(create)
+  },
+  chromium<Resource>(
+    create: (context: BrowserDriverContext) => PromiseLike<ChromiumPort<Resource>> | ChromiumPort<Resource>,
+  ): ChromiumDriver<Resource> {
+    if (typeof create !== "function") throw new TypeError("Chromium port factory must be a function")
+    return Object.freeze(chromiumDriver(create))
+  },
+}
+
+export function browserDriverFactory<Resource>(driver: BrowserDriver<Resource>) {
+  if (typeof driver !== "function") throw new TypeError("Browser driver must be a factory function")
+  return driver
+}
@@ -0,0 +1,118 @@
+import { createHash, createSign, generateKeyPairSync, randomBytes } from "node:crypto"
+
+// Certificate construction follows VS Code's MIT-licensed tunnel proxy implementation.
+// Copyright (c) Microsoft Corporation.
+
+/** Creates the ephemeral certificate pinned by the browser proxy's host. */
+export function createBrowserProxyCertificate(hostname: string) {
+  const keys = generateKeyPairSync("ec", {
+    namedCurve: "prime256v1",
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  })
+  const certificate = createCertificate(keys.privateKey, keys.publicKey, hostname)
+  const fingerprint = `sha256/${createHash("sha256").update(pemToDer(certificate)).digest("base64")}`
+  return { key: keys.privateKey, certificate, fingerprint }
+}
+
+function createCertificate(privateKey: string, publicKey: string, hostname: string) {
+  const serial = randomBytes(8)
+  serial[0] &= 0x7f
+  if (serial.every((byte) => byte === 0)) serial[serial.length - 1] = 1
+  const now = new Date(Date.now() - 60_000)
+  const expires = new Date(now)
+  expires.setUTCFullYear(expires.getUTCFullYear() + 1)
+  const name = sequence([set([sequence([oid(Buffer.from([0x55, 0x04, 0x03])), utf8("OpenCode Browser Proxy")])])])
+  const signatureAlgorithm = sequence([oid(Buffer.from([0x2a, 0x86, 0x48, 0xce, 0x3d, 0x04, 0x03, 0x02]))])
+  const extensions = Buffer.concat([
+    Buffer.from([0xa3]),
+    lengthPrefix(
+      sequence([
+        sequence([
+          oid(Buffer.from([0x55, 0x1d, 0x11])),
+          octetString(
+            sequence([tagged(0x82, Buffer.from(hostname, "ascii")), tagged(0x87, Buffer.from([127, 0, 0, 1]))]),
+          ),
+        ]),
+      ]),
+    ),
+  ])
+  const body = sequence([
+    Buffer.from([0xa0, 0x03, 0x02, 0x01, 0x02]),
+    integer(serial),
+    signatureAlgorithm,
+    name,
+    sequence([time(now), time(expires)]),
+    name,
+    pemToDer(publicKey),
+    extensions,
+  ])
+  const signer = createSign("SHA256")
+  signer.update(body)
+  const signature = signer.sign(privateKey)
+  const certificate = sequence([
+    body,
+    signatureAlgorithm,
+    Buffer.concat([Buffer.from([0x03]), length(signature.length + 1), Buffer.from([0]), signature]),
+  ])
+  const encoded = certificate
+    .toString("base64")
+    .match(/.{1,64}/g)
+    ?.join("\n")
+  if (!encoded) throw new Error("Failed to encode browser proxy certificate")
+  return `-----BEGIN CERTIFICATE-----\n${encoded}\n-----END CERTIFICATE-----\n`
+}
+
+function pemToDer(pem: string) {
+  return Buffer.from(pem.replace(/-----[A-Z ]+-----/g, "").replaceAll(/\s/g, ""), "base64")
+}
+
+function length(value: number) {
+  if (value < 0x80) return Buffer.from([value])
+  if (value < 0x100) return Buffer.from([0x81, value])
+  if (value < 0x10000) return Buffer.from([0x82, value >> 8, value & 0xff])
+  if (value < 0x1000000) return Buffer.from([0x83, value >> 16, (value >> 8) & 0xff, value & 0xff])
+  throw new RangeError(`ASN.1 value is too large: ${value}`)
+}
+
+function lengthPrefix(value: Buffer) {
+  return Buffer.concat([length(value.length), value])
+}
+
+function tagged(tag: number, value: Buffer) {
+  return Buffer.concat([Buffer.from([tag]), lengthPrefix(value)])
+}
+
+function sequence(items: ReadonlyArray<Buffer>) {
+  return tagged(0x30, Buffer.concat(items))
+}
+
+function set(items: ReadonlyArray<Buffer>) {
+  return tagged(0x31, Buffer.concat(items))
+}
+
+function integer(value: Buffer) {
+  const first = value.findIndex(
+    (byte, index) => byte !== 0 || index === value.length - 1 || (value[index + 1] & 0x80) !== 0,
+  )
+  const canonical = value.subarray(first < 0 ? value.length - 1 : first)
+  return tagged(0x02, canonical[0] & 0x80 ? Buffer.concat([Buffer.from([0]), canonical]) : canonical)
+}
+
+function oid(value: Buffer) {
+  return tagged(0x06, value)
+}
+
+function utf8(value: string) {
+  return tagged(0x0c, Buffer.from(value, "utf8"))
+}
+
+function octetString(value: Buffer) {
+  return tagged(0x04, value)
+}
+
+function time(value: Date) {
+  const encoded = value.toISOString().replaceAll(/[-:T]/g, "")
+  if (value.getUTCFullYear() < 2050) return tagged(0x17, Buffer.from(encoded.slice(2, 14) + "Z", "ascii"))
+  return tagged(0x18, Buffer.from(encoded.slice(0, 14) + "Z", "ascii"))
+}
@@ -0,0 +1,410 @@
+import { BrowserTunnel } from "@opencode-ai/schema/browser-tunnel"
+import { randomBytes, timingSafeEqual } from "node:crypto"
+import { once } from "node:events"
+import { Agent, request, type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from "node:http"
+import { createServer } from "node:https"
+import { Duplex } from "node:stream"
+import { createBrowserProxyCertificate } from "./proxy-certificate.js"
+
+export type BrowserProxyConnector = (target: BrowserTunnel.Target, signal: AbortSignal) => Promise<Duplex>
+
+/** Starts an authenticated TLS forward proxy whose target sockets can only come from the tunnel connector. */
+export async function createBrowserProxy(input: { readonly connect: BrowserProxyConnector }) {
+  const candidate = `opencode-${randomBytes(16).toString("hex")}.localhost`
+  const certificate = createBrowserProxyCertificate(candidate)
+  const username = randomBytes(16).toString("hex")
+  const password = randomBytes(32).toString("hex")
+  const expectedAuthorization = Buffer.from(`Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`)
+  const clients = new Set<Duplex>()
+  const tunnels = new Set<Duplex>()
+  const pending = new Set<AbortController>()
+  const limiter = connectionLimiter(6, 64)
+  let closed = false
+
+  const connect = async (target: BrowserTunnel.Target, signal?: AbortSignal) => {
+    if (closed) throw new Error("Browser proxy is closed")
+    const abort = new AbortController()
+    const cancel = () => abort.abort(signal?.reason)
+    const done = () => {
+      pending.delete(abort)
+      signal?.removeEventListener("abort", cancel)
+    }
+    signal?.addEventListener("abort", cancel, { once: true })
+    if (signal?.aborted) cancel()
+    pending.add(abort)
+    return limiter
+      .run(() => input.connect(target, abort.signal), abort.signal)
+      .then(
+        (tunnel) => {
+          done()
+          if (closed || abort.signal.aborted) {
+            tunnel.destroy()
+            throw abort.signal.reason ?? new Error("Browser proxy is closed")
+          }
+          tunnels.add(tunnel)
+          tunnel.once("close", () => tunnels.delete(tunnel))
+          tunnel.on("error", () => tunnel.destroy())
+          return tunnel
+        },
+        (error) => {
+          done()
+          throw error
+        },
+      )
+  }
+
+  const authorized = (header: string | undefined) => {
+    if (!header) return false
+    const actual = Buffer.from(header)
+    return actual.length === expectedAuthorization.length && timingSafeEqual(actual, expectedAuthorization)
+  }
+
+  const server = createServer(
+    { key: certificate.key, cert: certificate.certificate, allowHalfOpen: true, maxHeaderSize: 64 * 1_024 },
+    (incoming, response) => {
+      void forward(incoming, response, connect, authorized).catch(() => response.destroy())
+    },
+  )
+  server.requestTimeout = 30_000
+  server.headersTimeout = 10_000
+  server.keepAliveTimeout = 5_000
+  server.maxRequestsPerSocket = 1_000
+  server.on("connection", (socket) => {
+    clients.add(socket)
+    socket.once("close", () => clients.delete(socket))
+  })
+  server.on("connect", (incoming, socket, head) => {
+    clients.add(socket)
+    socket.once("close", () => clients.delete(socket))
+    let established = false
+    void (async () => {
+      if (!authorized(singleHeader(incoming.headers["proxy-authorization"]))) {
+        socket.end(
+          'HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic realm="OpenCode Browser Proxy"\r\nContent-Length: 0\r\nConnection: close\r\n\r\n',
+        )
+        return
+      }
+      const parsed = authority(incoming.url ?? "", 443)
+      if (!parsed) {
+        socket.end("HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+        return
+      }
+      const abort = new AbortController()
+      let tunnel: Duplex | undefined
+      const buffered: Uint8Array[] = head.byteLength ? [head] : []
+      let bufferedBytes = head.byteLength
+      const cancel = () => {
+        abort.abort(new Error("Browser proxy client closed during tunnel setup"))
+        tunnel?.destroy()
+      }
+      const onReadable = () => {
+        while (true) {
+          const data: unknown = socket.read()
+          if (data === null) break
+          if (!(data instanceof Uint8Array)) {
+            cancel()
+            socket.destroy()
+            return
+          }
+          bufferedBytes += data.byteLength
+          if (bufferedBytes > 256 * 1_024) {
+            cancel()
+            socket.destroy()
+            return
+          }
+          buffered.push(data)
+        }
+        if (socket.readableEnded) cancel()
+      }
+      incoming.once("aborted", cancel)
+      incoming.once("error", cancel)
+      socket.once("close", cancel)
+      socket.once("end", cancel)
+      socket.once("error", cancel)
+      socket.on("readable", onReadable)
+      socket.pause()
+      tunnel = await connect(target(parsed.host, parsed.port), abort.signal)
+      onReadable()
+      if (socket.destroyed || socket.readableEnded || abort.signal.aborted) {
+        socket.off("readable", onReadable)
+        tunnel.destroy()
+        return
+      }
+      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n")
+      established = true
+      for (const data of buffered) {
+        if (!tunnel.write(data)) await once(tunnel, "drain", { signal: abort.signal })
+      }
+      socket.off("readable", onReadable)
+      bridge(socket, tunnel)
+      incoming.off("aborted", cancel)
+      incoming.off("error", cancel)
+      socket.off("close", cancel)
+      socket.off("end", cancel)
+      socket.off("error", cancel)
+      socket.resume()
+    })().catch(() => {
+      if (socket.destroyed) return
+      if (established) {
+        socket.destroy()
+        return
+      }
+      socket.end("HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+    })
+  })
+  server.on("error", () => undefined)
+  server.on("clientError", (_error, socket) => {
+    if (!socket.destroyed) socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n")
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off("listening", onListening)
+      reject(error)
+    }
+    const onListening = () => {
+      server.off("error", onError)
+      resolve()
+    }
+    server.once("error", onError)
+    server.once("listening", onListening)
+    server.listen(0, "127.0.0.1")
+  })
+  const address = server.address()
+  if (!address || typeof address === "string") {
+    server.close()
+    throw new Error("Browser proxy did not bind a TCP address")
+  }
+  const host = candidate
+  let closing: Promise<void> | undefined
+
+  return {
+    url: `https://${host}:${address.port}`,
+    host,
+    port: address.port,
+    credentials: { username, password },
+    certificateFingerprint: certificate.fingerprint,
+    close() {
+      if (closing) return closing
+      closed = true
+      pending.forEach((abort) => abort.abort())
+      pending.clear()
+      limiter.close()
+      tunnels.forEach((tunnel) => tunnel.destroy())
+      tunnels.clear()
+      clients.forEach((client) => client.destroy())
+      clients.clear()
+      closing = new Promise<void>((resolve) => server.close(() => resolve()))
+      return closing
+    },
+  }
+}
+
+async function forward(
+  incoming: IncomingMessage,
+  response: ServerResponse,
+  connect: (target: BrowserTunnel.Target, signal?: AbortSignal) => Promise<Duplex>,
+  authorized: (header: string | undefined) => boolean,
+) {
+  if (!authorized(singleHeader(incoming.headers["proxy-authorization"]))) {
+    response.writeHead(407, { "Proxy-Authenticate": 'Basic realm="OpenCode Browser Proxy"' })
+    response.end()
+    return
+  }
+  const url = (() => {
+    try {
+      return new URL(incoming.url ?? "")
+    } catch {
+      return undefined
+    }
+  })()
+  if (!url || url.protocol !== "http:" || !url.hostname || url.username || url.password) {
+    response.writeHead(400)
+    response.end()
+    return
+  }
+  const port = url.port ? Number(url.port) : 80
+  const abort = new AbortController()
+  let tunnel: Duplex | undefined
+  let agent: Agent | undefined
+  const cancel = () => {
+    abort.abort(new Error("Browser proxy downstream closed"))
+    tunnel?.destroy()
+  }
+  incoming.once("aborted", cancel)
+  incoming.once("error", cancel)
+  incoming.socket.once("close", cancel)
+  incoming.socket.once("end", cancel)
+  incoming.socket.once("error", cancel)
+  response.once("close", cancel)
+  response.once("error", cancel)
+  try {
+    tunnel = await connect(target(normalizeHostname(url.hostname), port), abort.signal)
+    const headers = forwardedHeaders(incoming.headers)
+    headers.host = url.host
+    headers.connection = "close"
+    const connection = tunnel
+    agent = new Agent({ keepAlive: false, maxSockets: 1, noDelay: false })
+    agent.createConnection = () => connection
+    await new Promise<void>((resolve, reject) => {
+      const upstream = request(
+        {
+          agent,
+          hostname: url.hostname,
+          port,
+          path: `${url.pathname}${url.search}`,
+          method: incoming.method,
+          headers,
+          maxHeaderSize: 64 * 1_024,
+          signal: abort.signal,
+        },
+        (result) => {
+          const headers = forwardedHeaders(result.headers)
+          headers.connection = "close"
+          response.writeHead(result.statusCode ?? 502, result.statusMessage, headers)
+          result.once("error", reject)
+          result.once("aborted", () => reject(new Error("Browser proxy target response was aborted")))
+          result.once("end", resolve)
+          result.pipe(response)
+        },
+      )
+      upstream.once("continue", () => response.writeContinue())
+      upstream.once("error", reject)
+      incoming.pipe(upstream)
+    })
+  } finally {
+    incoming.off("aborted", cancel)
+    incoming.off("error", cancel)
+    incoming.socket.off("close", cancel)
+    incoming.socket.off("end", cancel)
+    incoming.socket.off("error", cancel)
+    response.off("close", cancel)
+    response.off("error", cancel)
+    agent?.destroy()
+    tunnel?.destroy()
+  }
+}
+
+function forwardedHeaders(input: IncomingHttpHeaders) {
+  const headers = { ...input }
+  const named = singleHeader(headers.connection)
+    ?.split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+  named?.forEach((name) => delete headers[name])
+  ;[
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+  ].forEach((name) => delete headers[name])
+  return headers
+}
+
+function bridge(client: Duplex, tunnel: Duplex) {
+  client.on("error", () => tunnel.destroy())
+  tunnel.on("error", () => client.destroy())
+  client.on("close", () => {
+    if (!tunnel.destroyed) tunnel.destroy()
+  })
+  tunnel.on("close", () => {
+    if (!client.destroyed) client.destroy()
+  })
+  client.pipe(tunnel)
+  tunnel.pipe(client)
+}
+
+function authority(value: string, defaultPort: number) {
+  const bracket = /^\[([^\]]+)](?::([0-9]+))?$/.exec(value)
+  if (bracket) return validAuthority(bracket[1], bracket[2], defaultPort)
+  if (value.includes("[")) return undefined
+  const separator = value.lastIndexOf(":")
+  if (separator < 0) return validAuthority(value, undefined, defaultPort)
+  if (value.slice(0, separator).includes(":")) return undefined
+  return validAuthority(value.slice(0, separator), value.slice(separator + 1), defaultPort)
+}
+
+function validAuthority(host: string, value: string | undefined, defaultPort: number) {
+  if (!host || (value !== undefined && !/^[0-9]+$/.test(value))) return undefined
+  const port = value === undefined ? defaultPort : Number(value)
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) return undefined
+  try {
+    return { host: BrowserTunnel.Host.make(host), port: BrowserTunnel.Port.make(port) }
+  } catch {
+    return undefined
+  }
+}
+
+function target(host: string, port: number): BrowserTunnel.Target {
+  return { host: BrowserTunnel.Host.make(host), port: BrowserTunnel.Port.make(port) }
+}
+
+function normalizeHostname(hostname: string) {
+  return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname
+}
+
+function singleHeader(value: string | ReadonlyArray<string> | undefined) {
+  return typeof value === "string" ? value : undefined
+}
+
+function connectionLimiter(limit: number, capacity: number) {
+  const queue: Array<() => void> = []
+  let active = 0
+  let closed = false
+  const drain = (): void => {
+    if (active >= limit) return
+    const start = queue.shift()
+    if (!start) return
+    start()
+    drain()
+  }
+  return {
+    run<Result>(task: () => Promise<Result>, signal: AbortSignal) {
+      return new Promise<Result>((resolve, reject) => {
+        if (closed || signal.aborted) {
+          reject(signal.reason ?? new Error("Browser proxy connection was cancelled"))
+          return
+        }
+        if (active >= limit && queue.length >= capacity) {
+          reject(new Error("Browser proxy connection queue is full"))
+          return
+        }
+        const start = () => {
+          signal.removeEventListener("abort", cancel)
+          if (closed || signal.aborted) {
+            reject(signal.reason ?? new Error("Browser proxy connection was cancelled"))
+            return
+          }
+          active++
+          void Promise.resolve()
+            .then(task)
+            .then(resolve, reject)
+            .finally(() => {
+              active--
+              drain()
+            })
+        }
+        const cancel = () => {
+          const index = queue.indexOf(start)
+          if (index === -1) return
+          queue.splice(index, 1)
+          reject(signal.reason ?? new Error("Browser proxy connection was cancelled"))
+        }
+        if (active < limit) start()
+        else {
+          signal.addEventListener("abort", cancel, { once: true })
+          queue.push(start)
+        }
+      })
+    },
+    close() {
+      closed = true
+      queue.splice(0).forEach((start) => start())
+    },
+  }
+}
@@ -0,0 +1,389 @@
+import { BrowserTunnelProtocol } from "@opencode-ai/protocol/browser-tunnel"
+import { BROWSER_TUNNEL_PROTOCOL } from "@opencode-ai/protocol/groups/browser"
+import { Browser } from "@opencode-ai/schema/browser"
+import { BrowserTunnel } from "@opencode-ai/schema/browser-tunnel"
+import { Session } from "@opencode-ai/schema/session"
+import { Effect, Schema } from "effect"
+import { Duplex } from "node:stream"
+import WebSocket from "ws"
+
+export type BrowserTunnelEndpoint = {
+  readonly url: string
+  readonly authorization?: string
+  readonly fetch?: typeof globalThis.fetch
+}
+
+export type BrowserTunnelOpen = {
+  readonly endpoint: BrowserTunnelEndpoint
+  readonly sessionID: Session.ID
+  readonly leaseID: Browser.LeaseID
+  readonly target: BrowserTunnel.Target
+  readonly signal?: AbortSignal
+}
+
+export class BrowserTunnelError extends Error {
+  constructor(
+    readonly code: BrowserTunnel.OpenErrorCode | BrowserTunnel.ResetCode | "transport",
+    message: string,
+  ) {
+    super(message)
+    this.name = "BrowserTunnelError"
+  }
+}
+
+/** Opens one flow-controlled WebSocket tunnel and exposes it as a single TCP-like stream. */
+export async function openBrowserTunnel(input: BrowserTunnelOpen): Promise<Duplex> {
+  const tunnel = new BrowserTunnelStream(input)
+  await tunnel.opened
+  return tunnel
+}
+
+class BrowserTunnelStream extends Duplex {
+  readonly opened: Promise<void>
+  readonly connecting = false
+  private resolveOpened!: () => void
+  private rejectOpened!: (error: Error) => void
+  private readonly socket: WebSocket
+  private readonly signal?: AbortSignal
+  private state: "ready" | "opening" | "open" | "closed" = "ready"
+  private inbound = Promise.resolve()
+  private timer?: ReturnType<typeof setTimeout>
+  private sendWindowBytes = 0
+  private sendWindowFrames = 0
+  private readonly outstanding: number[] = []
+  private activeWrite?: { readonly data: Buffer; offset: number; readonly callback: (error?: Error | null) => void }
+  private sending = false
+  private receiveWindowBytes = BrowserTunnelProtocol.InitialWindowBytes
+  private receiveWindowFrames = BrowserTunnelProtocol.InitialFrameWindow
+  private heldWindowBytes = 0
+  private heldWindowFrames = 0
+  private paused = false
+  private localEnded = false
+  private remoteEnded = false
+  private remoteReset = false
+  private resetCode: BrowserTunnel.ResetCode = "cancelled"
+
+  constructor(input: BrowserTunnelOpen) {
+    super({
+      allowHalfOpen: true,
+      readableHighWaterMark: BrowserTunnelProtocol.InitialWindowBytes,
+      writableHighWaterMark: BrowserTunnelProtocol.InitialWindowBytes,
+    })
+    this.opened = new Promise<void>((resolve, reject) => {
+      this.resolveOpened = resolve
+      this.rejectOpened = reject
+    })
+    this.on("error", () => undefined)
+    this.signal = input.signal
+    this.socket = new WebSocket(endpointURL(input.endpoint), BROWSER_TUNNEL_PROTOCOL, {
+      ...(input.endpoint.authorization ? { headers: { Authorization: input.endpoint.authorization } } : {}),
+      handshakeTimeout: 10_000,
+      maxPayload: Math.max(BrowserTunnelProtocol.MaxDataBytes, BrowserTunnelProtocol.MaxControlBytes) + 1,
+      perMessageDeflate: false,
+      followRedirects: false,
+    })
+    this.timer = setTimeout(
+      () => this.fail(new BrowserTunnelError("transport", "Browser tunnel handshake timed out.")),
+      15_000,
+    )
+    this.timer.unref()
+    this.socket.on("message", (data, binary) => {
+      this.socket.pause()
+      const processing = this.inbound.then(
+        () => this.receive(input, data, binary),
+        () => this.receive(input, data, binary),
+      )
+      this.inbound = processing
+      void processing.then(
+        () => {
+          if (this.inbound === processing && !this.paused && this.socket.readyState === WebSocket.OPEN) {
+            this.socket.resume()
+          }
+        },
+        (error) =>
+          this.fail(new BrowserTunnelError("transport", error instanceof Error ? error.message : String(error))),
+      )
+    })
+    this.socket.on("error", (error) => this.fail(new BrowserTunnelError("transport", error.message)))
+    this.socket.on("close", (code, reason) => {
+      if (this.state === "closed") return
+      if (this.localEnded && this.remoteEnded) {
+        this.state = "closed"
+        this.destroy()
+        return
+      }
+      this.fail(new BrowserTunnelError("transport", `Browser tunnel closed (${code}): ${reason.toString()}`))
+    })
+    this.signal?.addEventListener("abort", this.onAbort, { once: true })
+    if (this.signal?.aborted) this.onAbort()
+  }
+
+  override _read() {
+    if (!this.paused) return
+    this.paused = false
+    this.releaseReceiveWindow()
+    if (this.socket.readyState === WebSocket.OPEN) this.socket.resume()
+  }
+
+  override _write(chunk: Buffer | string, encoding: BufferEncoding, callback: (error?: Error | null) => void) {
+    const data = typeof chunk === "string" ? Buffer.from(chunk, encoding) : chunk
+    if (this.state !== "open" || this.localEnded) {
+      callback(new BrowserTunnelError("transport", "Browser tunnel is not writable."))
+      return
+    }
+    if (data.byteLength === 0) {
+      callback()
+      return
+    }
+    this.activeWrite = { data, offset: 0, callback }
+    this.pumpWrite()
+  }
+
+  override _final(callback: (error?: Error | null) => void) {
+    if (this.state !== "open" || this.localEnded) {
+      callback(new BrowserTunnelError("transport", "Browser tunnel is not writable."))
+      return
+    }
+    this.send(BrowserTunnelProtocol.encodeFromDesktop({ type: "browser.tunnel.end" }), (error) => {
+      if (error) {
+        callback(error)
+        this.fail(new BrowserTunnelError("transport", error.message))
+        return
+      }
+      this.localEnded = true
+      callback()
+      this.finish()
+    })
+  }
+
+  override _destroy(error: Error | null, callback: (error?: Error | null) => void) {
+    if (this.timer) clearTimeout(this.timer)
+    this.signal?.removeEventListener("abort", this.onAbort)
+    if (this.state === "closed") {
+      callback(error)
+      return
+    }
+    const opened = this.state === "open"
+    this.state = "closed"
+    const pending = this.activeWrite
+    this.activeWrite = undefined
+    pending?.callback(error ?? new BrowserTunnelError("cancelled", "Browser tunnel was closed."))
+    if (
+      !opened ||
+      this.remoteReset ||
+      this.socket.readyState !== WebSocket.OPEN ||
+      (this.localEnded && this.remoteEnded)
+    ) {
+      this.socket.terminate()
+      callback(error)
+      return
+    }
+    this.socket.send(
+      BrowserTunnelProtocol.encodeFromDesktop({ type: "browser.tunnel.reset", code: this.resetCode }),
+      { binary: true },
+      () => {
+        this.socket.close(1000)
+      },
+    )
+    const terminate = setTimeout(() => this.socket.terminate(), 1_000)
+    terminate.unref()
+    callback(error)
+  }
+
+  setKeepAlive() {
+    return this
+  }
+
+  setNoDelay() {
+    return this
+  }
+
+  setTimeout(_timeout: number, callback?: () => void) {
+    if (callback) this.once("timeout", callback)
+    return this
+  }
+
+  ref() {
+    return this
+  }
+
+  unref() {
+    return this
+  }
+
+  private async receive(input: BrowserTunnelOpen, data: WebSocket.RawData, binary: boolean) {
+    if (!binary) return this.protocolFailure("Browser tunnel frames must be binary.")
+    const frame = await Effect.runPromise(BrowserTunnelProtocol.decodeFromServer(rawData(data))).catch(() => undefined)
+    if (!frame || this.state === "closed") return this.protocolFailure("Browser tunnel frame is invalid.")
+    if (frame.type === "data") {
+      if (this.state !== "open" || this.remoteEnded) return this.protocolFailure("Unexpected browser tunnel data.")
+      if (frame.data.byteLength > this.receiveWindowBytes || this.receiveWindowFrames === 0) {
+        return this.protocolFailure("Browser tunnel receive window was exceeded.")
+      }
+      this.receiveWindowBytes -= frame.data.byteLength
+      this.receiveWindowFrames--
+      this.heldWindowBytes += frame.data.byteLength
+      this.heldWindowFrames++
+      if (!this.push(frame.data)) {
+        this.paused = true
+        return
+      }
+      this.releaseReceiveWindow()
+      return
+    }
+    const message = frame.message
+    if (message.type === "browser.tunnel.ready") {
+      if (this.state !== "ready") return this.protocolFailure("Browser tunnel sent duplicate ready.")
+      this.state = "opening"
+      this.send(
+        BrowserTunnelProtocol.encodeFromDesktop({
+          type: "browser.tunnel.open",
+          sessionID: input.sessionID,
+          leaseID: input.leaseID,
+          target: input.target,
+          receiveWindow: BrowserTunnel.WindowSize.make(BrowserTunnelProtocol.InitialWindowBytes),
+          receiveFrames: BrowserTunnel.FrameWindow.make(BrowserTunnelProtocol.InitialFrameWindow),
+        }),
+        (error) => {
+          if (error) this.fail(new BrowserTunnelError("transport", error.message))
+        },
+      )
+      return
+    }
+    if (message.type === "browser.tunnel.opened") {
+      if (this.state !== "opening") return this.protocolFailure("Unexpected browser tunnel opened message.")
+      this.state = "open"
+      this.sendWindowBytes = message.receiveWindow
+      this.sendWindowFrames = message.receiveFrames
+      if (this.timer) clearTimeout(this.timer)
+      this.resolveOpened()
+      this.pumpWrite()
+      return
+    }
+    if (message.type === "browser.tunnel.rejected") {
+      if (this.state !== "opening") return this.protocolFailure("Unexpected browser tunnel rejection.")
+      this.fail(new BrowserTunnelError(message.code, message.message))
+      return
+    }
+    if (message.type === "browser.tunnel.window") {
+      if (this.state !== "open" || message.frames > this.outstanding.length) {
+        return this.protocolFailure("Unexpected browser tunnel window update.")
+      }
+      const bytes = this.outstanding.slice(0, message.frames).reduce((total, size) => total + size, 0)
+      if (bytes !== message.bytes)
+        return this.protocolFailure("Browser tunnel window update does not match sent frames.")
+      this.outstanding.splice(0, message.frames)
+      this.sendWindowBytes += message.bytes
+      this.sendWindowFrames += message.frames
+      this.pumpWrite()
+      return
+    }
+    if (message.type === "browser.tunnel.end") {
+      if (this.state !== "open" || this.remoteEnded) return this.protocolFailure("Unexpected browser tunnel end.")
+      this.remoteEnded = true
+      this.push(null)
+      this.finish()
+      return
+    }
+    this.remoteReset = true
+    this.fail(new BrowserTunnelError(message.code, `Browser tunnel was reset: ${message.code}`))
+  }
+
+  private pumpWrite() {
+    const write = this.activeWrite
+    if (!write || this.sending || this.state !== "open") return
+    if (this.sendWindowBytes === 0 || this.sendWindowFrames === 0) return
+    const size = Math.min(
+      BrowserTunnelProtocol.MaxDataBytes,
+      this.sendWindowBytes,
+      write.data.byteLength - write.offset,
+    )
+    this.sendWindowBytes -= size
+    this.sendWindowFrames--
+    this.outstanding.push(size)
+    this.sending = true
+    this.send(BrowserTunnelProtocol.data(write.data.subarray(write.offset, write.offset + size)), (error) => {
+      this.sending = false
+      if (this.activeWrite !== write) return
+      if (error) {
+        this.activeWrite = undefined
+        write.callback(error)
+        this.fail(new BrowserTunnelError("transport", error.message))
+        return
+      }
+      write.offset += size
+      if (write.offset === write.data.byteLength) {
+        this.activeWrite = undefined
+        write.callback()
+        return
+      }
+      this.pumpWrite()
+    })
+  }
+
+  private releaseReceiveWindow() {
+    if (this.heldWindowFrames === 0 || this.state !== "open") return
+    const bytes = this.heldWindowBytes
+    const frames = this.heldWindowFrames
+    this.heldWindowBytes = 0
+    this.heldWindowFrames = 0
+    this.receiveWindowBytes += bytes
+    this.receiveWindowFrames += frames
+    this.send(
+      BrowserTunnelProtocol.encodeFromDesktop({
+        type: "browser.tunnel.window",
+        bytes: BrowserTunnel.WindowBytes.make(bytes),
+        frames: BrowserTunnel.FrameWindow.make(frames),
+      }),
+      (error) => {
+        if (error) this.fail(new BrowserTunnelError("transport", error.message))
+      },
+    )
+  }
+
+  private send(frame: Uint8Array, callback: (error?: Error) => void) {
+    if (this.socket.readyState !== WebSocket.OPEN) {
+      callback(new Error("Browser tunnel WebSocket is not open."))
+      return
+    }
+    this.socket.send(frame, { binary: true }, callback)
+  }
+
+  private protocolFailure(message: string) {
+    this.fail(new BrowserTunnelError("protocol_error", message))
+  }
+
+  private fail(error: BrowserTunnelError) {
+    if (this.state === "closed") return
+    if (Schema.is(BrowserTunnel.ResetCode)(error.code)) this.resetCode = error.code
+    if (this.state !== "open") this.rejectOpened(error)
+    this.destroy(error)
+  }
+
+  private finish() {
+    if (!this.localEnded || !this.remoteEnded || this.socket.readyState !== WebSocket.OPEN) return
+    this.socket.close(1000)
+  }
+
+  private readonly onAbort = () => {
+    this.fail(new BrowserTunnelError("cancelled", "Browser tunnel was cancelled."))
+  }
+}
+
+function endpointURL(endpoint: BrowserTunnelEndpoint) {
+  const url = new URL(endpoint.url)
+  if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
+    throw new TypeError("Browser server endpoint must be an HTTP URL without embedded credentials")
+  }
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:"
+  url.pathname = "/api/browser/tunnel"
+  url.search = ""
+  url.hash = ""
+  return url
+}
+
+function rawData(data: WebSocket.RawData) {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data)
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data))
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+}
@@ -0,0 +1,13 @@
+import { OpenCode } from "../promise/generated/index.js"
+import { createBrowserClient } from "./browser/client.js"
+
+export type ClientOptions = OpenCode.ClientOptions
+export type RequestOptions = OpenCode.RequestOptions
+
+/** Creates the Promise client with Node-only browser attachment support. */
+export function make(options: ClientOptions) {
+  return {
+    ...OpenCode.make(options),
+    browser: createBrowserClient(options),
+  }
+}
@@ -0,0 +1,29 @@
+export { ClientError, type ClientErrorReason } from "../promise/generated/client-error.js"
+export * from "../promise/generated/types.js"
+export type {
+  AgentApi,
+  CatalogApi,
+  CommandApi,
+  EventApi,
+  IntegrationApi,
+  ModelApi,
+  PluginApi,
+  ProviderApi,
+  ReferenceApi,
+  WebSearchApi,
+  SessionApi,
+  SkillApi,
+} from "../promise/api.js"
+export * as OpenCode from "./client.js"
+export { Browser } from "@opencode-ai/schema/browser"
+export { BrowserDriver, BrowserDriverError } from "./browser/driver.js"
+export type {
+  BrowserDriverContext,
+  BrowserDriverFactory,
+  BrowserDriverInstance,
+  BrowserProxy,
+} from "./browser/driver.js"
+export type { ChromiumController, ChromiumDriver, ChromiumPort } from "./browser/chromium.js"
+export type { BrowserAttachment, BrowserAttachOptions, BrowserClient } from "./browser/client.js"
+export type { EventSubscribeOutput as OpenCodeEvent } from "../promise/generated/types.js"
+export type OpenCodeClient = ReturnType<typeof import("./client.js").make>
@@ -8,6 +8,7 @@ export type ModelApi = Client["model"]
 export type PluginApi = Client["plugin"]
 export type ProviderApi = Client["provider"]
 export type ReferenceApi = Client["reference"]
+export type WebSearchApi = Client["websearch"]
 export type SessionApi = Client["session"]
 export type SkillApi = Client["skill"]

@@ -7,6 +7,8 @@ import type {
  LocationGetOutput,
  AgentListInput,
  AgentListOutput,
+  AgentGetInput,
+  AgentGetOutput,
  PluginListInput,
  PluginListOutput,
  SessionListInput,
@@ -207,8 +209,12 @@ import type {
  DebugLocationListOutput,
  DebugLocationEvictInput,
  DebugLocationEvictOutput,
-} from "./types"
-import { ClientError } from "./client-error"
+  WebsearchProvidersInput,
+  WebsearchProvidersOutput,
+  WebsearchQueryInput,
+  WebsearchQueryOutput,
+} from "./types.js"
+import { ClientError } from "./client-error.js"

 export interface ClientOptions {
  readonly baseUrl: string
@@ -399,6 +405,18 @@ export function make(options: ClientOptions) {
          },
          requestOptions,
        ),
+      get: (input: AgentGetInput, requestOptions?: RequestOptions) =>
+        request<AgentGetOutput>(
+          {
+            method: "GET",
+            path: `/api/agent/${encodeURIComponent(input.agentID)}`,
+            query: { location: input["location"] },
+            successStatus: 200,
+            declaredStatuses: [404, 401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ),
    },
    plugin: {
      list: (input?: PluginListInput, requestOptions?: RequestOptions) =>
@@ -1735,6 +1753,33 @@ export function make(options: ClientOptions) {
          ),
      },
    },
+    websearch: {
+      providers: (input?: WebsearchProvidersInput, requestOptions?: RequestOptions) =>
+        request<WebsearchProvidersOutput>(
+          {
+            method: "GET",
+            path: `/api/websearch/provider`,
+            query: { location: input?.["location"] },
+            successStatus: 200,
+            declaredStatuses: [503, 401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ),
+      query: (input: WebsearchQueryInput, requestOptions?: RequestOptions) =>
+        request<WebsearchQueryOutput>(
+          {
+            method: "POST",
+            path: `/api/websearch`,
+            query: { location: input["location"] },
+            body: { query: input["query"], providerID: input["providerID"] },
+            successStatus: 200,
+            declaredStatuses: [400, 503, 401],
+            empty: false,
+          },
+          requestOptions,
+        ),
+    },
  }
 }

@@ -1,3 +1,3 @@
-export { ClientError, type ClientErrorReason } from "./client-error"
-export * as OpenCode from "./client"
-export * from "./types"
+export { ClientError, type ClientErrorReason } from "./client-error.js"
+export * as OpenCode from "./client.js"
+export * from "./types.js"
@@ -6,11 +6,11 @@ export type ServiceStopResponse = { accepted: boolean }

 export type ModelRef = { id: string; providerID: string; variant?: string }

-export type ProviderSettings = { [x: string]: JsonValue }
+export type ProviderSettings = { [x: string]: any }

 export type AgentColor = string

-export type PermissionV2Effect = "allow" | "deny" | "ask"
+export type PermissionEffect = "allow" | "deny" | "ask"

 export type PluginInfo = { id: string }

@@ -98,8 +98,6 @@ export type SessionMessageShell = {
  output?: { output: string; cursor: number; size: number; truncated: boolean }
 }

-export type SessionMessageAssistantText = { type: "text"; text: string }
-
 export type SessionMessageProviderState = { [x: string]: JsonValue }

 export type SessionMessageToolStateStreaming = { status: "streaming"; input: string }
@@ -112,7 +110,7 @@ export type SessionMessageToolStateRunning = {

 export type ToolTextContent = { type: "text"; text: string }

-export type ToolFileContent = { type: "file"; uri: string; mime: string; name?: string }
+export type ToolFileContent = { type: "file"; uri: string; mime: string; name?: string | null }

 export type SessionStructuredError = { type: string; message: string }

@@ -157,8 +155,6 @@ export type ShellInfo = {
  time: { started: number; completed?: number }
 }

-export type SessionMessageProviderState3 = { [x: string]: any }
-
 export type SessionMessageProviderState4 = { [x: string]: any }

 export type SessionMessageProviderState5 = { [x: string]: any }
@@ -167,6 +163,12 @@ export type SessionMessageProviderState6 = { [x: string]: any }

 export type SessionMessageProviderState7 = { [x: string]: any }

+export type ToolFileContent1 = { type: "file"; uri: string; mime: string; name?: string | undefined }
+
+export type SessionMessageProviderState8 = { [x: string]: any }
+
+export type SessionMessageProviderState9 = { [x: string]: any }
+
 export type EventLogSynced = { type: "log.synced"; aggregateID: string; seq?: number }

 export type ModelReasoningField = "reasoning" | "reasoning_content" | "reasoning_text" | (string & {})
@@ -175,24 +177,24 @@ export type ModelCapabilities = { tools: boolean; input: Array<string>; output:

 export type ModelVariant = {
  id: string
-  settings?: { [x: string]: JsonValue }
+  settings?: { [x: string]: any }
  headers?: { [x: string]: string }
-  body?: { [x: string]: JsonValue }
+  body?: { [x: string]: any }
 }

 export type MoneyUSDPerMillionTokens = number

 export type GenerateTextResponse = { data: { text: string } }

-export type ProviderV2Info = {
+export type ProviderInfo = {
  id: string
  integrationID?: string
  name: string
  disabled?: boolean
  package: string
-  settings?: { [x: string]: JsonValue }
+  settings?: { [x: string]: any }
  headers?: { [x: string]: string }
-  body?: { [x: string]: JsonValue }
+  body?: { [x: string]: any }
 }

 export type IntegrationWhen = { key: string; op: "eq" | "neq"; value: string }
@@ -299,7 +301,7 @@ export type FormExternalField = { key: string; type: "external"; url: string; ti

 export type FormValue = string | number | boolean | Array<string>

-export type PermissionV2Source = { type: "tool"; messageID: string; callID: string }
+export type PermissionSource = { type: "tool"; messageID: string; callID: string }

 export type PermissionSavedInfo = { id: string; projectID: string; action: string; resource: string }

@@ -323,9 +325,9 @@ export type FileDiffLegacyInfo = {
  status?: "added" | "deleted" | "modified"
 }

-export type PermissionAction = "allow" | "deny" | "ask"
+export type PermissionV1Action = "allow" | "deny" | "ask"

-export type JSONSchema = { [x: string]: any }
+export type SessionV1JSONSchema = { [x: string]: any }

 export type ProviderAuthError = { name: "ProviderAuthError"; data: { providerID: string; message: string } }

@@ -356,7 +358,7 @@ export type APIError = {
  }
 }

-export type TextPart = {
+export type SessionV1TextPart = {
  id: string
  sessionID: string
  messageID: string
@@ -368,7 +370,7 @@ export type TextPart = {
  metadata?: { [x: string]: any } | undefined
 }

-export type SubtaskPart = {
+export type SessionV1SubtaskPart = {
  id: string
  sessionID: string
  messageID: string
@@ -380,7 +382,7 @@ export type SubtaskPart = {
  command?: string | undefined
 }

-export type ReasoningPart = {
+export type SessionV1ReasoningPart = {
  id: string
  sessionID: string
  messageID: string
@@ -390,13 +392,13 @@ export type ReasoningPart = {
  time: { start: number; end?: number | undefined }
 }

-export type FilePartSourceText = { value: string; start: number; end: number }
+export type SessionV1FilePartSourceText = { value: string; start: number; end: number }

-export type Range = { start: { line: number; character: number }; end: { line: number; character: number } }
+export type SessionV1Range = { start: { line: number; character: number }; end: { line: number; character: number } }

-export type ToolStatePending = { status: "pending"; input: { [x: string]: any }; raw: string }
+export type SessionV1ToolStatePending = { status: "pending"; input: { [x: string]: any }; raw: string }

-export type ToolStateRunning = {
+export type SessionV1ToolStateRunning = {
  status: "running"
  input: { [x: string]: any }
  title?: string | undefined
@@ -404,7 +406,7 @@ export type ToolStateRunning = {
  time: { start: number }
 }

-export type ToolStateError = {
+export type SessionV1ToolStateError = {
  status: "error"
  input: { [x: string]: any }
  error: string
@@ -412,7 +414,7 @@ export type ToolStateError = {
  time: { start: number; end: number }
 }

-export type StepStartPart = {
+export type SessionV1StepStartPart = {
  id: string
  sessionID: string
  messageID: string
@@ -420,7 +422,7 @@ export type StepStartPart = {
  snapshot?: string | undefined
 }

-export type StepFinishPart = {
+export type SessionV1StepFinishPart = {
  id: string
  sessionID: string
  messageID: string
@@ -437,9 +439,15 @@ export type StepFinishPart = {
  }
 }

-export type SnapshotPart = { id: string; sessionID: string; messageID: string; type: "snapshot"; snapshot: string }
+export type SessionV1SnapshotPart = {
+  id: string
+  sessionID: string
+  messageID: string
+  type: "snapshot"
+  snapshot: string
+}

-export type PatchPart = {
+export type SessionV1PatchPart = {
  id: string
  sessionID: string
  messageID: string
@@ -448,7 +456,7 @@ export type PatchPart = {
  files: Array<string>
 }

-export type AgentPart = {
+export type SessionV1AgentPart = {
  id: string
  sessionID: string
  messageID: string
@@ -457,7 +465,7 @@ export type AgentPart = {
  source?: { value: string; start: number; end: number } | undefined
 }

-export type CompactionPart = {
+export type SessionV1CompactionPart = {
  id: string
  sessionID: string
  messageID: string
@@ -467,7 +475,7 @@ export type CompactionPart = {
  tail_start_id?: string | undefined
 }

-export type PermissionV2Reply = "once" | "always" | "reject"
+export type PermissionReply = "once" | "always" | "reject"

 export type Pty = {
  id: string
@@ -480,11 +488,11 @@ export type Pty = {
  exitCode?: number
 }

-export type QuestionV2Option = { label: string; description: string }
+export type QuestionOption = { label: string; description: string }

-export type QuestionV2Tool = { messageID: string; callID: string }
+export type QuestionTool = { messageID: string; callID: string }

-export type QuestionV2Answer = Array<string>
+export type QuestionAnswer = Array<string>

 export type FormMetadata1 = { [x: string]: any }

@@ -501,12 +509,6 @@ export type SessionStatus =
    }
  | { type: "busy" }

-export type QuestionOption = { label: string; description: string }
-
-export type QuestionTool = { messageID: string; callID: string }
-
-export type QuestionAnswer = Array<string>
-
 export type ShellInfo1 = {
  id: string
  status: "running" | "exited" | "timeout" | "killed"
@@ -539,6 +541,10 @@ export type VcsFileStatus = {
  status: "added" | "deleted" | "modified"
 }

+export type WebSearchProvider = { id: string; name: string }
+
+export type WebSearchResult = { url: string; title?: string; content?: string; time: { published?: number } }
+
 export type SessionMessageModelSelected = {
  id: string
  metadata?: { [x: string]: JsonValue }
@@ -560,10 +566,10 @@ export type CommandInfo = {
 export type ProviderRequest = {
  settings: ProviderSettings
  headers: { [x: string]: string }
-  body: { [x: string]: JsonValue }
+  body: { [x: string]: any }
 }

-export type PermissionV2Rule = { action: string; resource: string; effect: PermissionV2Effect }
+export type PermissionRule = { action: string; resource: string; effect: PermissionEffect }

 export type SessionAgentSelected = {
  id: string
@@ -733,16 +739,6 @@ export type SessionTextStarted = {
  data: { sessionID: string; assistantMessageID: string; ordinal: number }
 }

-export type SessionTextEnded = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "session.text.ended"
-  durable: { aggregateID: string; seq: number; version: 1 }
-  location?: LocationRef
-  data: { sessionID: string; assistantMessageID: string; ordinal: number; text: string }
-}
-
 export type SessionToolInputStarted = {
  id: string
  created: number
@@ -1050,11 +1046,11 @@ export type ShellDeleted = {
  data: { id: string }
 }

-export type QuestionV2Rejected = {
+export type QuestionRejected = {
  id: string
  created: number
  metadata?: { [x: string]: any }
-  type: "question.v2.rejected"
+  type: "question.rejected"
  location?: LocationRef
  data: { sessionID: string; requestID: string }
 }
@@ -1068,6 +1064,15 @@ export type FormCancelled = {
  data: { id: string; sessionID: string }
 }

+export type WebsearchUpdated = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "websearch.updated"
+  location?: LocationRef
+  data: {}
+}
+
 export type SessionIdle = {
  id: string
  created: number
@@ -1183,41 +1188,6 @@ export type McpResourcesChanged = {
  data: { server: string }
 }

-export type PermissionAsked = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "permission.asked"
-  location?: LocationRef
-  data: {
-    id: string
-    sessionID: string
-    permission: string
-    patterns: Array<string>
-    metadata: { [x: string]: any }
-    always: Array<string>
-    tool?: { messageID: string; callID: string } | undefined
-  }
-}
-
-export type PermissionReplied = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "permission.replied"
-  location?: LocationRef
-  data: { sessionID: string; requestID: string; reply: "once" | "always" | "reject" }
-}
-
-export type QuestionRejected = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "question.rejected"
-  location?: LocationRef
-  data: { sessionID: string; requestID: string }
-}
-
 export type V2EventServerConnected = {
  id: string
  metadata?: { [x: string]: any } | undefined
@@ -1249,6 +1219,8 @@ export type SessionPendingSynthetic = {
  delivery: "steer" | "queue"
 }

+export type SessionMessageAssistantText = { type: "text"; text: string; state?: SessionMessageProviderState }
+
 export type SessionMessageAssistantReasoning = {
  type: "reasoning"
  text: string
@@ -1256,7 +1228,7 @@ export type SessionMessageAssistantReasoning = {
  time?: { created: number; completed?: number }
 }

-export type LLMToolContent = ToolTextContent | ToolFileContent
+export type ToolContent = ToolTextContent | ToolFileContent

 export type SessionMessageAssistantRetry = { attempt: number; at: number; error: SessionStructuredError }

@@ -1359,6 +1331,22 @@ export type ShellCreated = {
  data: { info: ShellInfo }
 }

+export type SessionTextEnded = {
+  id: string
+  created: number
+  metadata?: { [x: string]: any }
+  type: "session.text.ended"
+  durable: { aggregateID: string; seq: number; version: 1 }
+  location?: LocationRef
+  data: {
+    sessionID: string
+    assistantMessageID: string
+    ordinal: number
+    text: string
+    state?: SessionMessageProviderState4
+  }
+}
+
 export type SessionReasoningStarted = {
  id: string
  created: number
@@ -1366,7 +1354,7 @@ export type SessionReasoningStarted = {
  type: "session.reasoning.started"
  durable: { aggregateID: string; seq: number; version: 1 }
  location?: LocationRef
-  data: { sessionID: string; assistantMessageID: string; ordinal: number; state?: SessionMessageProviderState3 }
+  data: { sessionID: string; assistantMessageID: string; ordinal: number; state?: SessionMessageProviderState5 }
 }

 export type SessionReasoningEnded = {
@@ -1381,7 +1369,7 @@ export type SessionReasoningEnded = {
    assistantMessageID: string
    ordinal: number
    text: string
-    state?: SessionMessageProviderState4
+    state?: SessionMessageProviderState6
  }
 }

@@ -1398,10 +1386,12 @@ export type SessionToolCalled = {
    callID: string
    input: { [x: string]: any }
    executed: boolean
-    state?: SessionMessageProviderState5
+    state?: SessionMessageProviderState7
  }
 }

+export type ToolContent1 = ToolTextContent | ToolFileContent1
+
 export type ModelCompatibility = { reasoningField?: ModelReasoningField }

 export type ModelCost = {
@@ -1523,21 +1513,21 @@ export type FormMultiselectField = {

 export type FormAnswer = { [x: string]: FormValue }

-export type PermissionV2Request = {
+export type PermissionRequest = {
  id: string
  sessionID: string
  action: string
  resources: Array<string>
  save?: Array<string>
  metadata?: { [x: string]: JsonValue }
-  source?: PermissionV2Source
+  source?: PermissionSource
 }

-export type PermissionV2Asked = {
+export type PermissionAsked = {
  id: string
  created: number
  metadata?: { [x: string]: any }
-  type: "permission.v2.asked"
+  type: "permission.asked"
  location?: LocationRef
  data: {
    id: string
@@ -1546,17 +1536,17 @@ export type PermissionV2Asked = {
    resources: Array<string>
    save?: Array<string>
    metadata?: { [x: string]: any }
-    source?: PermissionV2Source
+    source?: PermissionSource
  }
 }

-export type PermissionRule = { permission: string; pattern: string; action: PermissionAction }
+export type PermissionV1Rule = { permission: string; pattern: string; action: PermissionV1Action }

-export type OutputFormat =
+export type SessionV1OutputFormat =
  | { type: "text" }
-  | { type: "json_schema"; schema: JSONSchema; retryCount?: number | undefined | undefined }
+  | { type: "json_schema"; schema: SessionV1JSONSchema; retryCount?: number | undefined | undefined }

-export type AssistantMessage = {
+export type SessionV1AssistantMessage = {
  id: string
  sessionID: string
  role: "assistant"
@@ -1591,7 +1581,7 @@ export type AssistantMessage = {
  finish?: string | undefined
 }

-export type RetryPart = {
+export type SessionV1RetryPart = {
  id: string
  sessionID: string
  messageID: string
@@ -1622,26 +1612,31 @@ export type SessionError = {
  }
 }

-export type FileSource = { text: FilePartSourceText; type: "file"; path: string }
+export type SessionV1FileSource = { text: SessionV1FilePartSourceText; type: "file"; path: string }

-export type ResourceSource = { text: FilePartSourceText; type: "resource"; clientName: string; uri: string }
+export type SessionV1ResourceSource = {
+  text: SessionV1FilePartSourceText
+  type: "resource"
+  clientName: string
+  uri: string
+}

-export type SymbolSource = {
-  text: FilePartSourceText
+export type SessionV1SymbolSource = {
+  text: SessionV1FilePartSourceText
  type: "symbol"
  path: string
-  range: Range
+  range: SessionV1Range
  name: string
  kind: number
 }

-export type PermissionV2Replied = {
+export type PermissionReplied = {
  id: string
  created: number
  metadata?: { [x: string]: any }
-  type: "permission.v2.replied"
+  type: "permission.replied"
  location?: LocationRef
-  data: { sessionID: string; requestID: string; reply: PermissionV2Reply }
+  data: { sessionID: string; requestID: string; reply: PermissionReply }
 }

 export type PtyCreated = {
@@ -1662,21 +1657,21 @@ export type PtyUpdated = {
  data: { info: Pty }
 }

-export type QuestionV2Info = {
+export type QuestionInfo = {
  question: string
  header: string
-  options: Array<QuestionV2Option>
+  options: Array<QuestionOption>
  multiple?: boolean
  custom?: boolean
 }

-export type QuestionV2Replied = {
+export type QuestionReplied = {
  id: string
  created: number
  metadata?: { [x: string]: any }
-  type: "question.v2.replied"
+  type: "question.replied"
  location?: LocationRef
-  data: { sessionID: string; requestID: string; answers: Array<QuestionV2Answer> }
+  data: { sessionID: string; requestID: string; answers: Array<QuestionAnswer> }
 }

 export type FormStringField1 = {
@@ -1753,26 +1748,9 @@ export type SessionStatus2 = {
  data: { sessionID: string; status: SessionStatus }
 }

-export type QuestionInfo = {
-  question: string
-  header: string
-  options: Array<QuestionOption>
-  multiple?: boolean | undefined
-  custom?: boolean | undefined
-}
-
-export type QuestionReplied = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "question.replied"
-  location?: LocationRef
-  data: { sessionID: string; requestID: string; answers: Array<QuestionAnswer> }
-}
-
 export type ReferenceSource = ReferenceLocalSource | ReferenceGitSource

-export type PermissionV2Ruleset = Array<PermissionV2Rule>
+export type PermissionRuleset = Array<PermissionRule>

 export type SessionInfo = {
  id: string
@@ -1827,7 +1805,7 @@ export type SessionPendingUserData1 = {
 export type SessionMessageToolStateCompleted = {
  status: "completed"
  input: { [x: string]: JsonValue }
-  content: [LLMToolContent, ...Array<LLMToolContent>]
+  content: [ToolContent, ...Array<ToolContent>]
  metadata?: { [x: string]: JsonValue }
 }

@@ -1835,10 +1813,15 @@ export type SessionMessageToolStateError = {
  status: "error"
  input: { [x: string]: JsonValue }
  error: SessionStructuredError
-  content?: [LLMToolContent, ...Array<LLMToolContent>]
+  content?: [ToolContent, ...Array<ToolContent>]
  metadata?: { [x: string]: JsonValue }
 }

+export type SessionMessageCompaction =
+  | SessionMessageCompactionRunning
+  | SessionMessageCompactionCompleted
+  | SessionMessageCompactionFailed
+
 export type SessionToolSuccess = {
  id: string
  created: number
@@ -1850,10 +1833,10 @@ export type SessionToolSuccess = {
    sessionID: string
    assistantMessageID: string
    callID: string
-    content: [LLMToolContent, ...Array<LLMToolContent>]
+    content: [ToolContent1, ...Array<ToolContent1>]
    metadata?: { [x: string]: JsonValue }
    executed: boolean
-    resultState?: SessionMessageProviderState6
+    resultState?: SessionMessageProviderState8
  }
 }

@@ -1869,18 +1852,13 @@ export type SessionToolFailed = {
    assistantMessageID: string
    callID: string
    error: SessionStructuredError
-    content?: [LLMToolContent, ...Array<LLMToolContent>]
+    content?: [ToolContent1, ...Array<ToolContent1>]
    metadata?: { [x: string]: JsonValue }
    executed: boolean
-    resultState?: SessionMessageProviderState7
+    resultState?: SessionMessageProviderState9
  }
 }

-export type SessionMessageCompaction =
-  | SessionMessageCompactionRunning
-  | SessionMessageCompactionCompleted
-  | SessionMessageCompactionFailed
-
 export type ModelInfo = {
  id: string
  modelID: string
@@ -1889,9 +1867,9 @@ export type ModelInfo = {
  name: string
  compatibility?: ModelCompatibility
  package?: string
-  settings?: { [x: string]: JsonValue }
+  settings?: { [x: string]: any }
  headers?: { [x: string]: string }
-  body?: { [x: string]: JsonValue }
+  body?: { [x: string]: any }
  capabilities: ModelCapabilities
  variants: Array<ModelVariant>
  time: { released: number }
@@ -1927,14 +1905,14 @@ export type FormReplied = {
  data: { id: string; sessionID: string; answer: FormAnswer }
 }

-export type PermissionRuleset = Array<PermissionRule>
+export type PermissionV1Ruleset = Array<PermissionV1Rule>

-export type UserMessage = {
+export type SessionV1UserMessage = {
  id: string
  sessionID: string
  role: "user"
  time: { created: number }
-  format?: OutputFormat | undefined
+  format?: SessionV1OutputFormat | undefined
  summary?: { title?: string | undefined; body?: string | undefined; diffs: Array<FileDiffLegacyInfo> } | undefined
  agent: string
  model: { providerID: string; modelID: string; variant?: string | undefined }
@@ -1942,23 +1920,18 @@ export type UserMessage = {
  tools?: { [x: string]: boolean } | undefined
 }

-export type FilePartSource = FileSource | SymbolSource | ResourceSource
+export type SessionV1FilePartSource = SessionV1FileSource | SessionV1SymbolSource | SessionV1ResourceSource

-export type QuestionV2Asked = {
+export type QuestionAsked = {
  id: string
  created: number
  metadata?: { [x: string]: any }
-  type: "question.v2.asked"
+  type: "question.asked"
  location?: LocationRef
-  data: { id: string; sessionID: string; questions: Array<QuestionV2Info>; tool?: QuestionV2Tool }
+  data: { id: string; sessionID: string; questions: Array<QuestionInfo>; tool?: QuestionTool }
 }

-export type QuestionV2Request = {
-  id: string
-  sessionID: string
-  questions: Array<QuestionV2Info>
-  tool?: QuestionV2Tool
-}
+export type QuestionRequest = { id: string; sessionID: string; questions: Array<QuestionInfo>; tool?: QuestionTool }

 export type FormField1 =
  | FormStringField1
@@ -1968,15 +1941,6 @@ export type FormField1 =
  | FormMultiselectField1
  | FormExternalField

-export type QuestionAsked = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "question.asked"
-  location?: LocationRef
-  data: { id: string; sessionID: string; questions: Array<QuestionInfo>; tool?: QuestionTool | undefined }
-}
-
 export type ReferenceInfo = {
  name: string
  path: string
@@ -1996,7 +1960,7 @@ export type AgentInfo = {
  hidden: boolean
  color?: AgentColor
  steps?: number
-  permissions: PermissionV2Ruleset
+  permissions: PermissionRuleset
 }

 export type SessionsResponse = { data: Array<SessionInfo>; cursor: { previous?: string | null; next?: string | null } }
@@ -2054,13 +2018,13 @@ export type SessionV1Info = {
  version: string
  metadata?: { [x: string]: any }
  time: { created: number; updated: number; compacting?: number; archived?: number }
-  permission?: PermissionRuleset
+  permission?: PermissionV1Ruleset
  revert?: { messageID: string; partID?: string; snapshot?: string; diff?: string }
 }

-export type Message = UserMessage | AssistantMessage
+export type SessionV1Message = SessionV1UserMessage | SessionV1AssistantMessage

-export type FilePart = {
+export type SessionV1FilePart = {
  id: string
  sessionID: string
  messageID: string
@@ -2068,7 +2032,7 @@ export type FilePart = {
  mime: string
  filename?: string | undefined
  url: string
-  source?: FilePartSource | undefined
+  source?: SessionV1FilePartSource | undefined
 }

 export type FormFields1 = [FormField1, ...Array<FormField1>]
@@ -2139,17 +2103,17 @@ export type MessageUpdated = {
  type: "message.updated"
  durable: { aggregateID: string; seq: number; version: 1 }
  location?: LocationRef
-  data: { sessionID: string; info: Message }
+  data: { sessionID: string; info: SessionV1Message }
 }

-export type ToolStateCompleted = {
+export type SessionV1ToolStateCompleted = {
  status: "completed"
  input: { [x: string]: any }
  output: string
  title: string
  metadata: { [x: string]: any }
  time: { start: number; end: number; compacted?: number | undefined }
-  attachments?: Array<FilePart> | undefined
+  attachments?: Array<SessionV1FilePart> | undefined
 }

 export type FormInfo1 = { id: string; sessionID: string; title: string; metadata?: FormMetadata1; fields: FormFields1 }
@@ -2175,7 +2139,11 @@ export type SessionMessageInfo =
  | SessionMessageAssistant
  | SessionMessageCompaction

-export type ToolState = ToolStatePending | ToolStateRunning | ToolStateCompleted | ToolStateError
+export type SessionV1ToolState =
+  | SessionV1ToolStatePending
+  | SessionV1ToolStateRunning
+  | SessionV1ToolStateCompleted
+  | SessionV1ToolStateError

 export type FormCreated = {
  id: string
@@ -2231,32 +2199,32 @@ export type SessionMessagesResponse = {
  cursor: { previous?: string | null; next?: string | null }
 }

-export type ToolPart = {
+export type SessionV1ToolPart = {
  id: string
  sessionID: string
  messageID: string
  type: "tool"
  callID: string
  tool: string
-  state: ToolState
+  state: SessionV1ToolState
  metadata?: { [x: string]: any } | undefined
 }

 export type SessionLogItem = SessionEventDurable | EventLogSynced

-export type Part =
-  | TextPart
-  | SubtaskPart
-  | ReasoningPart
-  | FilePart
-  | ToolPart
-  | StepStartPart
-  | StepFinishPart
-  | SnapshotPart
-  | PatchPart
-  | AgentPart
-  | RetryPart
-  | CompactionPart
+export type SessionV1Part =
+  | SessionV1TextPart
+  | SessionV1SubtaskPart
+  | SessionV1ReasoningPart
+  | SessionV1FilePart
+  | SessionV1ToolPart
+  | SessionV1StepStartPart
+  | SessionV1StepFinishPart
+  | SessionV1SnapshotPart
+  | SessionV1PatchPart
+  | SessionV1AgentPart
+  | SessionV1RetryPart
+  | SessionV1CompactionPart

 export type MessagePartUpdated = {
  id: string
@@ -2265,7 +2233,7 @@ export type MessagePartUpdated = {
  type: "message.part.updated"
  durable: { aggregateID: string; seq: number; version: 1 }
  location?: LocationRef
-  data: { sessionID: string; part: Part; time: number }
+  data: { sessionID: string; part: SessionV1Part; time: number }
 }

 export type V2Event =
@@ -2326,8 +2294,8 @@ export type V2Event =
  | SessionRevertCommitted
  | FilesystemChanged
  | ReferenceUpdated
-  | PermissionV2Asked
-  | PermissionV2Replied
+  | PermissionAsked
+  | PermissionReplied
  | PluginAdded
  | PluginUpdated
  | ProjectDirectoriesUpdated
@@ -2341,12 +2309,13 @@ export type V2Event =
  | ShellCreated
  | ShellExited
  | ShellDeleted
-  | QuestionV2Asked
-  | QuestionV2Replied
-  | QuestionV2Rejected
+  | QuestionAsked
+  | QuestionReplied
+  | QuestionRejected
  | FormCreated
  | FormReplied
  | FormCancelled
+  | WebsearchUpdated
  | SessionStatus2
  | SessionIdle
  | TuiPromptAppend
@@ -2358,11 +2327,6 @@ export type V2Event =
  | VcsBranchUpdated
  | McpStatusChanged
  | McpResourcesChanged
-  | PermissionAsked
-  | PermissionReplied
-  | QuestionAsked
-  | QuestionReplied
-  | QuestionRejected
  | SessionError
  | V2EventServerConnected

@@ -2379,6 +2343,14 @@ export type InvalidRequestError = {
 export const isInvalidRequestError = (value: unknown): value is InvalidRequestError =>
  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidRequestError"

+export type AgentNotFoundError = {
+  readonly _tag: "AgentNotFoundError"
+  readonly agentID: string
+  readonly message: string
+}
+export const isAgentNotFoundError = (value: unknown): value is AgentNotFoundError =>
+  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "AgentNotFoundError"
+
 export type InvalidCursorError = { readonly _tag: "InvalidCursorError"; readonly message: string }
 export const isInvalidCursorError = (value: unknown): value is InvalidCursorError =>
  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidCursorError"
@@ -2562,6 +2534,18 @@ export type AgentListOutput = {
  data: Array<AgentInfo>
 }

+export type AgentGetInput = {
+  readonly agentID: { readonly agentID: string }["agentID"]
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+}
+
+export type AgentGetOutput = {
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  data: AgentInfo
+}
+
 export type PluginListInput = {
  readonly location?: {
    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
@@ -3290,7 +3274,7 @@ export type ProviderListInput = {

 export type ProviderListOutput = {
  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
-  data: Array<ProviderV2Info>
+  data: Array<ProviderInfo>
 }

 export type ProviderGetInput = {
@@ -3302,7 +3286,7 @@ export type ProviderGetInput = {

 export type ProviderGetOutput = {
  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
-  data: ProviderV2Info
+  data: ProviderInfo
 }

 export type IntegrationListInput = {
@@ -4454,7 +4438,7 @@ export type PermissionRequestListInput = {

 export type PermissionRequestListOutput = {
  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
-  data: Array<PermissionV2Request>
+  data: Array<PermissionRequest>
 }

 export type PermissionSavedListInput = { readonly projectID?: { readonly projectID?: string | undefined }["projectID"] }
@@ -4532,18 +4516,18 @@ export type PermissionCreateInput = {
  }["agent"]
 }

-export type PermissionCreateOutput = { data: { id: string; effect: PermissionV2Effect } }["data"]
+export type PermissionCreateOutput = { data: { id: string; effect: PermissionEffect } }["data"]

 export type PermissionListInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }

-export type PermissionListOutput = { data: Array<PermissionV2Request> }["data"]
+export type PermissionListOutput = { data: Array<PermissionRequest> }["data"]

 export type PermissionGetInput = {
  readonly sessionID: { readonly sessionID: string; readonly requestID: string }["sessionID"]
  readonly requestID: { readonly sessionID: string; readonly requestID: string }["requestID"]
 }

-export type PermissionGetOutput = { data: PermissionV2Request }["data"]
+export type PermissionGetOutput = { data: PermissionRequest }["data"]

 export type PermissionReplyInput = {
  readonly sessionID: { readonly sessionID: string; readonly requestID: string }["sessionID"]
@@ -4842,12 +4826,12 @@ export type QuestionRequestListInput = {

 export type QuestionRequestListOutput = {
  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
-  data: Array<QuestionV2Request>
+  data: Array<QuestionRequest>
 }

 export type QuestionListInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }

-export type QuestionListOutput = { data: Array<QuestionV2Request> }["data"]
+export type QuestionListOutput = { data: Array<QuestionRequest> }["data"]

 export type QuestionReplyInput = {
  readonly sessionID: { readonly sessionID: string; readonly requestID: string }["sessionID"]
@@ -4950,3 +4934,27 @@ export type DebugLocationEvictInput = {
 }

 export type DebugLocationEvictOutput = void
+
+export type WebsearchProvidersInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+}
+
+export type WebsearchProvidersOutput = {
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  data: Array<WebSearchProvider>
+}
+
+export type WebsearchQueryInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+  readonly query: { readonly query: string; readonly providerID?: string }["query"]
+  readonly providerID?: { readonly query: string; readonly providerID?: string }["providerID"]
+}
+
+export type WebsearchQueryOutput = {
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string } }
+  data: { providerID: string; results: Array<WebSearchResult> }
+}
@@ -9,6 +9,7 @@ export type {
  PluginApi,
  ProviderApi,
  ReferenceApi,
+  WebSearchApi,
  SessionApi,
  SkillApi,
 } from "./api.js"
@@ -1,5 +1,6 @@
 import { Effect } from "effect"
 import { OpenCode as EffectOpenCode, type AppApi as EffectApi } from "../src/effect"
+import type { Session } from "@opencode-ai/schema/session"

 type EffectClient = Effect.Success<ReturnType<typeof EffectOpenCode.make>>
 type PromiseClient = ReturnType<typeof import("../src/promise").OpenCode.make>
@@ -9,6 +10,10 @@ declare const promiseClient: PromiseClient

 const effectApi: EffectApi<unknown> = effectClient

+const effectSession: Effect.Effect<Session.Info, unknown> = effectClient.session.get({
+  sessionID: "ses_test" as Session.ID,
+})
+
 declare const sessionID: Parameters<typeof effectApi.session.instructions.entry.list>[0]["sessionID"]

 const effectList: Effect.Effect<
@@ -37,4 +42,4 @@ const promiseRemove: Promise<void> = promiseClient.session.instructions.entry.re
  key: "review-notes",
 })

-void [effectList, effectPut, effectRemove, promiseList, promisePut, promiseRemove]
+void [effectSession, effectList, effectPut, effectRemove, promiseList, promisePut, promiseRemove]
@@ -14,6 +14,14 @@ test("effect entrypoint exposes canonical Schema contracts", () => {
  expect(Client.Session).toBe(Session)
 })

+test("generated Effect API names canonical and composed outputs", async () => {
+  const source = await Bun.file(new URL("../src/effect/api/api.ts", import.meta.url)).text()
+
+  expect(source).toContain("export type Endpoint5_3Output = Session.Info")
+  expect(source).toContain("export type Endpoint19_0Output = OpenCodeEvent")
+  expect(source).not.toContain("HttpApiClient.ForApi")
+})
+
 test("shared DTO schemas construct and decode plain objects", () => {
  const made = Prompt.make({ text: "hello" })
  const decoded = Schema.decodeUnknownSync(Prompt)({ text: "hello" })
@@ -5,6 +5,7 @@ import { join, resolve, sep } from "node:path"

 const directory = resolve(import.meta.dir, "..")
 const effect = realpathSync(resolve(import.meta.dir, "../node_modules/effect"))
+const ws = realpathSync(resolve(import.meta.dir, "../node_modules/ws"))
 const schema = resolve(import.meta.dir, "../../schema")
 const protocol = resolve(import.meta.dir, "../../protocol")
 const core = resolve(import.meta.dir, "../../core")
@@ -17,6 +18,7 @@ describe("public import boundaries", () => {
    expect(within(root, effect)).toEqual([])
    expect(within(root, schema)).toEqual([])
    expect(within(root, protocol)).toEqual([])
+    expect(within(root, ws)).toEqual([])
    expect(within(root, core)).toEqual([])
    expect(within(root, server)).toEqual([])

@@ -28,6 +30,15 @@ describe("public import boundaries", () => {
    expect(within(network, core)).toEqual([])
    expect(within(network, server)).toEqual([])

+    const node = await bundleInputs("@opencode-ai/client/node", "node")
+
+    expect(within(node, effect).length).toBeGreaterThan(0)
+    expect(within(node, schema).length).toBeGreaterThan(0)
+    expect(within(node, protocol).length).toBeGreaterThan(0)
+    expect(within(node, ws).length).toBeGreaterThan(0)
+    expect(within(node, core)).toEqual([])
+    expect(within(node, server)).toEqual([])
+
    const promiseService = await bundleInputs("@opencode-ai/client/service", "bun")

    expect(within(promiseService, effect)).toEqual([])
@@ -45,7 +56,7 @@ describe("public import boundaries", () => {
  })
 })

-async function bundleInputs(specifier: string, target: "browser" | "bun") {
+async function bundleInputs(specifier: string, target: "browser" | "bun" | "node") {
  const temporary = await mkdtemp(join(import.meta.dir, ".import-boundary-"))
  const entrypoint = join(temporary, "index.ts")
  const metafile = join(temporary, "meta.json")
@@ -0,0 +1,856 @@
+import { BrowserControlProtocol } from "@opencode-ai/protocol/browser-control"
+import { BrowserTunnelProtocol } from "@opencode-ai/protocol/browser-tunnel"
+import { BROWSER_CONTROL_PROTOCOL, BROWSER_TUNNEL_PROTOCOL } from "@opencode-ai/protocol/groups/browser"
+import { BrowserControl } from "@opencode-ai/schema/browser-control"
+import { BrowserTunnel } from "@opencode-ai/schema/browser-tunnel"
+import { Session } from "@opencode-ai/schema/session"
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { once } from "node:events"
+import { createServer } from "node:http"
+import { connect, type TLSSocket } from "node:tls"
+import WebSocket, { WebSocketServer } from "ws"
+import {
+  Browser,
+  BrowserDriver,
+  BrowserDriverError,
+  OpenCode,
+  type BrowserDriverContext,
+  type BrowserDriverInstance,
+  type BrowserProxy,
+} from "@opencode-ai/client/node"
+
+const initialState: Browser.State = {
+  url: "https://example.com/",
+  title: "Example",
+  loading: false,
+  canGoBack: false,
+  canGoForward: false,
+  generation: 1,
+}
+
+describe("Node browser client", () => {
+  test("rejects authentication failures on Bun without unsupported ws response events", async () => {
+    const server = await controlServer("Basic expected")
+    const adapter = driver("unauthorized")
+    const client = OpenCode.make({ baseUrl: server.url })
+
+    try {
+      const result = await Promise.race([
+        rejected(client.browser.attach({ sessionID: "ses_node_unauthorized", driver: adapter.descriptor })),
+        Bun.sleep(1_000).then(() => new Error("Authentication rejection timed out")),
+      ])
+      expect(result.message).toContain("HTTP 401")
+      expect(server.authorizations).toEqual([undefined])
+      expect(adapter.disposeCount).toBe(1)
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("cancels a pending Bun authentication probe when attachment setup is aborted", async () => {
+    const abort = new AbortController()
+    const adapter = driver("preflight")
+    let resolveStarted!: () => void
+    const started = new Promise<void>((resolve) => {
+      resolveStarted = resolve
+    })
+    let cancelled = false
+    const fetch: typeof globalThis.fetch = (_input, init) =>
+      new Promise<Response>((_resolve, reject) => {
+        resolveStarted()
+        const signal = init?.signal
+        if (!signal) return reject(new Error("Missing preflight signal"))
+        const stop = () => {
+          cancelled = true
+          reject(signal.reason)
+        }
+        signal.addEventListener("abort", stop, { once: true })
+        if (signal.aborted) stop()
+      })
+    const client = OpenCode.make({ baseUrl: "http://127.0.0.1:1", fetch })
+    const attaching = client.browser.attach({
+      sessionID: "ses_node_preflight_abort",
+      driver: adapter.descriptor,
+      signal: abort.signal,
+    })
+
+    await started
+    const reason = new Error("stop preflight")
+    abort.abort(reason)
+    expect(await rejected(attaching)).toBe(reason)
+    expect(cancelled).toBe(true)
+    expect(adapter.disposeCount).toBe(1)
+  })
+
+  test("keeps constructor authentication immutable and waits for the lease sync acknowledgement", async () => {
+    const authorization = `Basic ${Buffer.from("opencode:secret").toString("base64")}`
+    const server = await controlServer(authorization)
+    const headers = new Headers({ authorization })
+    const adapter = driver("first")
+    const client = OpenCode.make({ baseUrl: server.url, headers })
+    headers.set("authorization", "Basic changed")
+
+    try {
+      expect(client.session).toBeDefined()
+      expect(client.browser.attach).toBeFunction()
+      let settled = false
+      expect(adapter.descriptor).toBe(adapter.factory)
+      const attaching = client.browser.attach({ sessionID: "ses_node_barrier", driver: adapter.factory })
+      void attaching.then(() => {
+        settled = true
+      })
+      const socket = await server.nextConnection()
+      const next = controlReader(socket)
+
+      expect(server.authorizations).toEqual([authorization])
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      const sync = await next()
+      if (sync.type !== "browser.control.sync") throw new Error("Expected browser control sync")
+      expect(sync.attachments).toHaveLength(1)
+      expect(sync.attachments[0]?.sessionID).toBe("ses_node_barrier")
+      expect(sync.attachments[0]?.leaseID.startsWith("brl_")).toBe(true)
+      expect(adapter.proxy?.url.startsWith("https://")).toBe(true)
+      expect(adapter.proxy?.credentials.username).toBeTruthy()
+      await Bun.sleep(10)
+      expect(settled).toBe(false)
+
+      if (!adapter.proxy) throw new Error("Browser proxy is unavailable")
+      const proxyConnection = connectProxy(adapter.proxy, "target.example:443")
+      await Bun.sleep(10)
+      expect(server.tunnelConnections).toBe(0)
+
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: sync.revision }))
+      const attachment = await attaching
+      expect(attachment.resource).toEqual({ name: "first" })
+
+      const tunnel = await server.nextTunnelConnection()
+      const nextTunnel = tunnelReader(tunnel)
+      tunnel.send(BrowserTunnelProtocol.encodeFromServer({ type: "browser.tunnel.ready" }), { binary: true })
+      const open = await nextTunnel()
+      expect(open).toMatchObject({
+        type: "control",
+        message: {
+          type: "browser.tunnel.open",
+          sessionID: "ses_node_barrier",
+          leaseID: sync.attachments[0]?.leaseID,
+          target: { host: "target.example", port: 443 },
+        },
+      })
+      tunnel.send(
+        BrowserTunnelProtocol.encodeFromServer({
+          type: "browser.tunnel.opened",
+          receiveWindow: BrowserTunnel.WindowSize.make(BrowserTunnelProtocol.InitialWindowBytes),
+          receiveFrames: BrowserTunnel.FrameWindow.make(BrowserTunnelProtocol.InitialFrameWindow),
+        }),
+        { binary: true },
+      )
+      const connected = await proxyConnection
+      expect(connected.response.startsWith("HTTP/1.1 200 Connection Established")).toBe(true)
+      connected.socket.destroy()
+
+      const closed = once(socket, "close")
+      await attachment.close()
+      await closed
+      expect(adapter.disposeCount).toBe(1)
+      expect(adapter.unsubscribeCount).toBe(1)
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("multiplexes Sessions, coalesces state, routes requests and cancellation, and preserves siblings", async () => {
+    const server = await controlServer()
+    const client = OpenCode.make({ baseUrl: server.url })
+    const first = driver("first")
+    const second = driver("second")
+
+    try {
+      const attachingFirst = client.browser.attach({ sessionID: "ses_node_first", driver: first.descriptor })
+      const socket = await server.nextConnection()
+      const next = controlReader(socket)
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      const firstSync = await nextSync(next)
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: firstSync.revision }),
+      )
+      const firstAttachment = await attachingFirst
+
+      const attachingSecond = client.browser.attach({ sessionID: "ses_node_second", driver: second.descriptor })
+      const secondSync = await nextSync(next)
+      expect(secondSync.attachments.map((attachment) => attachment.sessionID)).toEqual([
+        "ses_node_first",
+        "ses_node_second",
+      ])
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: secondSync.revision }),
+      )
+      const secondAttachment = await attachingSecond
+      expect(server.connections).toBe(1)
+
+      second.setState({ ...initialState, title: "Intermediate" })
+      const pendingState = await nextSync(next)
+      second.setState({ ...initialState, title: "Latest" })
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: pendingState.revision }),
+      )
+      const latestState = await nextSync(next)
+      expect(
+        latestState.attachments.find((attachment) => attachment.sessionID === "ses_node_second")?.state.title,
+      ).toBe("Latest")
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: latestState.revision }),
+      )
+
+      const secondLease = secondSync.attachments.find(
+        (attachment) => attachment.sessionID === "ses_node_second",
+      )?.leaseID
+      if (!secondLease) throw new Error("Second browser lease is unavailable")
+      const requestID = BrowserControl.RequestID.create()
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.request",
+          requestID,
+          sessionID: Session.ID.make("ses_node_second"),
+          leaseID: secondLease,
+          command: { type: "snapshot", generation: 1 },
+        }),
+      )
+      expect(await next()).toMatchObject({
+        type: "browser.control.response",
+        requestID,
+        outcome: { type: "success", result: { type: "snapshot", content: "second" } },
+      })
+
+      const commandState = { ...initialState, title: "Updated by command", generation: 2 }
+      second.setExecute(async () => ({ type: "navigate", state: commandState }))
+      const stateRequestID = BrowserControl.RequestID.create()
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.request",
+          requestID: stateRequestID,
+          sessionID: Session.ID.make("ses_node_second"),
+          leaseID: secondLease,
+          command: { type: "navigate", url: "https://updated.example/", generation: 1 },
+        }),
+      )
+      expect(await next()).toMatchObject({
+        type: "browser.control.response",
+        requestID: stateRequestID,
+        outcome: { type: "success", result: { state: { title: "Updated by command" } } },
+      })
+      const commandStateSync = await nextSync(next)
+      expect(
+        commandStateSync.attachments.find((attachment) => attachment.sessionID === "ses_node_second")?.state,
+      ).toEqual(commandState)
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.synced",
+          revision: commandStateSync.revision,
+        }),
+      )
+
+      second.setExecute(async () => ({ type: "click", state: initialState }))
+      const invalidID = BrowserControl.RequestID.create()
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.request",
+          requestID: invalidID,
+          sessionID: Session.ID.make("ses_node_second"),
+          leaseID: secondLease,
+          command: { type: "snapshot", generation: 1 },
+        }),
+      )
+      expect(await next()).toMatchObject({
+        type: "browser.control.response",
+        requestID: invalidID,
+        outcome: { type: "failure", code: "protocol" },
+      })
+
+      second.setExecute(async () => {
+        throw new BrowserDriverError("stale_ref", "The reference is stale")
+      })
+      const errorID = BrowserControl.RequestID.create()
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.request",
+          requestID: errorID,
+          sessionID: Session.ID.make("ses_node_second"),
+          leaseID: secondLease,
+          command: { type: "click", ref: Browser.Ref.make("e1"), generation: 1 },
+        }),
+      )
+      expect(await next()).toMatchObject({
+        type: "browser.control.response",
+        requestID: errorID,
+        outcome: { type: "failure", code: "stale_ref", message: "The reference is stale" },
+      })
+
+      second.setExecute(async () => {
+        throw Object.assign(new Error("Invalid adapter code"), { code: "not_a_browser_error" })
+      })
+      const unsafeErrorID = BrowserControl.RequestID.create()
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.request",
+          requestID: unsafeErrorID,
+          sessionID: Session.ID.make("ses_node_second"),
+          leaseID: secondLease,
+          command: { type: "snapshot", generation: 2 },
+        }),
+      )
+      expect(await next()).toMatchObject({
+        type: "browser.control.response",
+        requestID: unsafeErrorID,
+        outcome: { type: "failure", code: "internal", message: "Invalid adapter code" },
+      })
+
+      let resolveStarted!: () => void
+      let resolveCancelled!: () => void
+      const started = new Promise<void>((resolve) => {
+        resolveStarted = resolve
+      })
+      const cancelled = new Promise<void>((resolve) => {
+        resolveCancelled = resolve
+      })
+      second.setExecute(
+        (_command, options) =>
+          new Promise<Browser.Result>((_, reject) => {
+            resolveStarted()
+            options.signal.addEventListener(
+              "abort",
+              () => {
+                resolveCancelled()
+                reject(Object.assign(new Error("cancelled"), { code: "aborted" }))
+              },
+              { once: true },
+            )
+          }),
+      )
+      const cancelID = BrowserControl.RequestID.create()
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.request",
+          requestID: cancelID,
+          sessionID: Session.ID.make("ses_node_second"),
+          leaseID: secondLease,
+          command: { type: "click", ref: Browser.Ref.make("e1"), generation: 1 },
+        }),
+      )
+      await started
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({
+          type: "browser.control.cancel",
+          requestID: cancelID,
+          leaseID: secondLease,
+        }),
+      )
+      await cancelled
+
+      await firstAttachment.close()
+      const detached = await nextSync(next)
+      expect(detached.attachments).toHaveLength(1)
+      expect(detached.attachments[0]?.sessionID).toBe("ses_node_second")
+      socket.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: detached.revision }),
+      )
+      expect(server.connections).toBe(1)
+      expect(second.disposeCount).toBe(0)
+
+      const closed = once(socket, "close")
+      await secondAttachment.close()
+      await closed
+      expect(first.disposeCount).toBe(1)
+      expect(second.disposeCount).toBe(1)
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("reconnects and republishes the complete attachment snapshot", async () => {
+    const server = await controlServer()
+    const client = OpenCode.make({ baseUrl: server.url })
+    const adapter = driver("reconnect")
+
+    try {
+      const attaching = client.browser.attach({ sessionID: "ses_node_reconnect", driver: adapter.descriptor })
+      const original = await server.nextConnection()
+      const nextOriginal = controlReader(original)
+      original.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      const initial = await nextSync(nextOriginal)
+      original.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: initial.revision }),
+      )
+      const attachment = await attaching
+      original.terminate()
+
+      const replacement = await server.nextConnection()
+      const nextReplacement = controlReader(replacement)
+      replacement.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      const republished = await nextSync(nextReplacement)
+      expect(republished.attachments).toEqual(initial.attachments)
+      replacement.send(
+        BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: republished.revision }),
+      )
+      expect(server.connections).toBe(2)
+
+      const closed = once(replacement, "close")
+      await attachment.close()
+      await closed
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("rejects duplicate Sessions and aborts setup while close remains idempotent", async () => {
+    const server = await controlServer()
+    const client = OpenCode.make({ baseUrl: server.url })
+    const adapter = driver("owner")
+
+    try {
+      const invalid = driver("invalid")
+      expect(
+        (await rejected(client.browser.attach({ sessionID: "invalid", driver: invalid.descriptor }))).message,
+      ).toContain("valid Session ID")
+      expect(invalid.createCount).toBe(0)
+
+      const attaching = client.browser.attach({ sessionID: "ses_node_owner", driver: adapter.descriptor })
+      const socket = await server.nextConnection()
+      const next = controlReader(socket)
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      const sync = await nextSync(next)
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: sync.revision }))
+      const attachment = await attaching
+
+      const duplicate = driver("duplicate")
+      expect(
+        (await rejected(client.browser.attach({ sessionID: "ses_node_owner", driver: duplicate.descriptor }))).message,
+      ).toContain("already attached")
+      expect(duplicate.createCount).toBe(0)
+
+      const closed = once(socket, "close")
+      await Promise.all([attachment.close(), attachment.close(), attachment[Symbol.asyncDispose]()])
+      await closed
+      expect(adapter.disposeCount).toBe(1)
+      expect(adapter.unsubscribeCount).toBe(1)
+
+      const abort = new AbortController()
+      const abortedAdapter = driver("aborted")
+      const aborted = client.browser.attach({
+        sessionID: "ses_node_aborted",
+        driver: abortedAdapter.descriptor,
+        signal: abort.signal,
+      })
+      const abortSocket = await server.nextConnection()
+      const nextAbort = controlReader(abortSocket)
+      abortSocket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      await nextSync(nextAbort)
+      const reason = new Error("stop attaching")
+      const abortClosed = once(abortSocket, "close")
+      abort.abort(reason)
+      expect(await rejected(aborted)).toBe(reason)
+      await abortClosed
+      expect(abortedAdapter.disposeCount).toBe(1)
+      expect(abortedAdapter.signal?.aborted).toBe(true)
+
+      const alreadyAborted = new AbortController()
+      alreadyAborted.abort(reason)
+      const unused = driver("unused")
+      expect(
+        await rejected(
+          client.browser.attach({
+            sessionID: "ses_node_unused",
+            driver: unused.descriptor,
+            signal: alreadyAborted.signal,
+          }),
+        ),
+      ).toBe(reason)
+      expect(unused.createCount).toBe(0)
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("fails pending attachments on fatal control closes without reconnecting", async () => {
+    const server = await controlServer()
+    const client = OpenCode.make({ baseUrl: server.url })
+    const adapter = driver("fatal")
+
+    try {
+      const attaching = client.browser.attach({ sessionID: "ses_node_fatal", driver: adapter.descriptor })
+      const socket = await server.nextConnection()
+      const next = controlReader(socket)
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      await nextSync(next)
+      const closed = once(socket, "close")
+      socket.close(1002, "invalid control state")
+
+      expect((await rejected(attaching)).message).toContain("fatal code 1002")
+      await closed
+      await Bun.sleep(250)
+      expect(server.connections).toBe(1)
+      expect(adapter.disposeCount).toBe(1)
+      expect(adapter.signal?.aborted).toBe(true)
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("aborts non-cooperative driver creation and disposes a late instance", async () => {
+    const server = await controlServer()
+    const client = OpenCode.make({ baseUrl: server.url })
+    const abort = new AbortController()
+    let resolveStarted!: () => void
+    let resolveFactory!: (instance: BrowserDriverInstance<{ readonly name: string }>) => void
+    let resolveDisposed!: () => void
+    const started = new Promise<void>((resolve) => {
+      resolveStarted = resolve
+    })
+    const disposed = new Promise<void>((resolve) => {
+      resolveDisposed = resolve
+    })
+    const factory = () => {
+      resolveStarted()
+      return new Promise<BrowserDriverInstance<{ readonly name: string }>>((resolve) => {
+        resolveFactory = resolve
+      })
+    }
+
+    try {
+      const attaching = client.browser.attach({
+        sessionID: "ses_node_blocked_factory",
+        driver: factory,
+        signal: abort.signal,
+      })
+      await started
+      const reason = new Error("abort blocked factory")
+      abort.abort(reason)
+      expect(
+        await rejected(
+          Promise.race([
+            attaching,
+            Bun.sleep(250).then(() => {
+              throw new Error("Browser attachment did not abort promptly")
+            }),
+          ]),
+        ),
+      ).toBe(reason)
+
+      resolveFactory({
+        resource: { name: "late" },
+        state: () => initialState,
+        subscribe: () => () => undefined,
+        execute: async () => ({
+          type: "snapshot",
+          state: initialState,
+          format: "opencode.semantic.v1",
+          content: "late",
+        }),
+        dispose: () => resolveDisposed(),
+      })
+      await disposed
+      expect(server.authorizations).toEqual([])
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("cleans up in reverse acquisition order and surfaces the first error", async () => {
+    const server = await controlServer()
+    const client = OpenCode.make({ baseUrl: server.url })
+    const first = new Error("unsubscribe failed")
+    const second = new Error("dispose failed")
+    const order: string[] = []
+    let proxy: BrowserProxy | undefined
+    let proxyOpenDuringDispose = false
+    const descriptor = BrowserDriver.define((context) => {
+      proxy = context.proxy
+      return {
+        resource: context.proxy,
+        state: () => initialState,
+        subscribe: () => () => {
+          order.push("unsubscribe")
+          throw first
+        },
+        execute: async () => ({
+          type: "snapshot",
+          state: initialState,
+          format: "opencode.semantic.v1",
+          content: "cleanup",
+        }),
+        dispose: async () => {
+          order.push("dispose")
+          proxyOpenDuringDispose = await proxyAvailable(context.proxy)
+          throw second
+        },
+      }
+    })
+
+    try {
+      const attaching = client.browser.attach({ sessionID: "ses_node_cleanup", driver: descriptor })
+      const socket = await server.nextConnection()
+      const next = controlReader(socket)
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.ready" }))
+      const sync = await nextSync(next)
+      socket.send(BrowserControlProtocol.encodeFromServer({ type: "browser.control.synced", revision: sync.revision }))
+      const attachment = await attaching
+
+      expect(await rejected(attachment.close())).toBe(first)
+      expect(await rejected(attachment.close())).toBe(first)
+      expect(order).toEqual(["unsubscribe", "dispose"])
+      expect(proxyOpenDuringDispose).toBe(true)
+      if (!proxy) throw new Error("Browser proxy is unavailable")
+      expect(await proxyAvailable(proxy)).toBe(false)
+    } finally {
+      await server.close()
+    }
+  })
+})
+
+type Execute = BrowserDriverInstance<unknown>["execute"]
+
+function driver(name: string) {
+  let current = initialState
+  let execute: Execute = async () => ({
+    type: "snapshot",
+    state: current,
+    format: "opencode.semantic.v1",
+    content: name,
+  })
+  let proxy: BrowserProxy | undefined
+  let signal: AbortSignal | undefined
+  let createCount = 0
+  let disposeCount = 0
+  let unsubscribeCount = 0
+  const listeners = new Set<(state: Browser.State) => void>()
+  const factory = ({ proxy: nextProxy, signal: nextSignal }: BrowserDriverContext) => {
+    createCount++
+    proxy = nextProxy
+    signal = nextSignal
+    return {
+      resource: { name },
+      state: () => current,
+      subscribe(listener) {
+        listeners.add(listener)
+        return () => {
+          if (listeners.delete(listener)) unsubscribeCount++
+        }
+      },
+      execute: (command, options) => execute(command, options),
+      dispose() {
+        disposeCount++
+      },
+    }
+  }
+  const descriptor = BrowserDriver.define(factory)
+  return {
+    factory,
+    descriptor,
+    get proxy() {
+      return proxy
+    },
+    get signal() {
+      return signal
+    },
+    get createCount() {
+      return createCount
+    },
+    get disposeCount() {
+      return disposeCount
+    },
+    get unsubscribeCount() {
+      return unsubscribeCount
+    },
+    setState(state: Browser.State) {
+      current = state
+      listeners.forEach((listener) => listener(state))
+    },
+    setExecute(next: Execute) {
+      execute = next
+    },
+  }
+}
+
+async function rejected(promise: Promise<unknown>) {
+  return promise.then(
+    () => new Error("Expected operation to reject"),
+    (error) => (error instanceof Error ? error : new Error(String(error))),
+  )
+}
+
+async function nextSync(next: () => Promise<BrowserControl.FromDesktop>) {
+  const message = await next()
+  if (message.type !== "browser.control.sync") throw new Error("Expected browser control sync")
+  return message
+}
+
+async function controlServer(authorization?: string) {
+  const http = createServer((request, response) => {
+    response.statusCode = request.headers.authorization === authorization ? 200 : 401
+    response.end()
+  })
+  const webSockets = new WebSocketServer({ noServer: true })
+  const tunnels = new WebSocketServer({ noServer: true })
+  const waiting: Array<(socket: WebSocket) => void> = []
+  const queued: WebSocket[] = []
+  const tunnelWaiting: Array<(socket: WebSocket) => void> = []
+  const tunnelQueued: WebSocket[] = []
+  const authorizations: Array<string | undefined> = []
+  let connections = 0
+  let tunnelConnections = 0
+  webSockets.on("connection", (socket) => {
+    connections++
+    const resolve = waiting.shift()
+    if (resolve) resolve(socket)
+    else queued.push(socket)
+  })
+  tunnels.on("connection", (socket) => {
+    tunnelConnections++
+    const resolve = tunnelWaiting.shift()
+    if (resolve) resolve(socket)
+    else tunnelQueued.push(socket)
+  })
+  http.on("upgrade", (request, socket, head) => {
+    authorizations.push(request.headers.authorization)
+    if (request.headers.authorization !== authorization) {
+      socket.end("HTTP/1.1 401 Unauthorized\r\n\r\n")
+      return
+    }
+    if (
+      request.url === "/api/browser/control" &&
+      request.headers["sec-websocket-protocol"] === BROWSER_CONTROL_PROTOCOL
+    ) {
+      webSockets.handleUpgrade(request, socket, head, (webSocket) => webSockets.emit("connection", webSocket, request))
+      return
+    }
+    if (
+      request.url === "/api/browser/tunnel" &&
+      request.headers["sec-websocket-protocol"] === BROWSER_TUNNEL_PROTOCOL
+    ) {
+      tunnels.handleUpgrade(request, socket, head, (webSocket) => tunnels.emit("connection", webSocket, request))
+      return
+    }
+    socket.end("HTTP/1.1 401 Unauthorized\r\n\r\n")
+  })
+  await new Promise<void>((resolve) => http.listen(0, "127.0.0.1", resolve))
+  const address = http.address()
+  if (address === null || typeof address === "string") throw new Error("Browser control server did not bind TCP")
+  return {
+    authorizations,
+    get connections() {
+      return connections
+    },
+    get tunnelConnections() {
+      return tunnelConnections
+    },
+    url: `http://127.0.0.1:${address.port}`,
+    nextConnection() {
+      const socket = queued.shift()
+      if (socket) return Promise.resolve(socket)
+      return new Promise<WebSocket>((resolve) => waiting.push(resolve))
+    },
+    nextTunnelConnection() {
+      const socket = tunnelQueued.shift()
+      if (socket) return Promise.resolve(socket)
+      return new Promise<WebSocket>((resolve) => tunnelWaiting.push(resolve))
+    },
+    async close() {
+      webSockets.clients.forEach((socket) => socket.terminate())
+      tunnels.clients.forEach((socket) => socket.terminate())
+      webSockets.close()
+      tunnels.close()
+      http.closeAllConnections()
+      http.close()
+      await Bun.sleep(10)
+    },
+  }
+}
+
+function proxyAvailable(proxy: BrowserProxy) {
+  return new Promise<boolean>((resolve) => {
+    const socket = connect({
+      host: "127.0.0.1",
+      port: proxy.port,
+      servername: proxy.host,
+      rejectUnauthorized: false,
+    })
+    let settled = false
+    const finish = (available: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      socket.destroy()
+      resolve(available)
+    }
+    const timeout = setTimeout(() => finish(false), 250)
+    timeout.unref()
+    socket.once("secureConnect", () => finish(true))
+    socket.once("error", () => finish(false))
+  })
+}
+
+function connectProxy(proxy: BrowserProxy, authority: string) {
+  return new Promise<{ readonly socket: TLSSocket; readonly response: string }>((resolve, reject) => {
+    const socket = connect(
+      {
+        host: "127.0.0.1",
+        port: proxy.port,
+        servername: proxy.host,
+        rejectUnauthorized: false,
+      },
+      () => {
+        socket.write(
+          `CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\nProxy-Authorization: Basic ${Buffer.from(`${proxy.credentials.username}:${proxy.credentials.password}`).toString("base64")}\r\n\r\n`,
+        )
+      },
+    )
+    let response = ""
+    socket.on("error", () => undefined)
+    socket.once("error", reject)
+    socket.on("data", (data) => {
+      response += data.toString()
+      if (!response.includes("\r\n\r\n")) return
+      resolve({ socket, response })
+    })
+  })
+}
+
+function tunnelReader(socket: WebSocket) {
+  const queued: WebSocket.RawData[] = []
+  const waiting: Array<(data: WebSocket.RawData) => void> = []
+  socket.on("message", (data, binary) => {
+    if (!binary) throw new Error("Expected a binary browser tunnel frame")
+    const resolve = waiting.shift()
+    if (resolve) resolve(data)
+    else queued.push(data)
+  })
+  return async () => {
+    const data = queued.shift() ?? (await new Promise<WebSocket.RawData>((resolve) => waiting.push(resolve)))
+    return Effect.runPromise(BrowserTunnelProtocol.decodeFromDesktop(rawData(data)))
+  }
+}
+
+function controlReader(socket: WebSocket) {
+  const queued: Array<{ readonly data: WebSocket.RawData; readonly binary: boolean }> = []
+  const waiting: Array<(message: { readonly data: WebSocket.RawData; readonly binary: boolean }) => void> = []
+  socket.on("message", (data, binary) => {
+    const resolve = waiting.shift()
+    if (resolve) resolve({ data, binary })
+    else queued.push({ data, binary })
+  })
+  return async () => {
+    const message =
+      queued.shift() ??
+      (await new Promise<{ readonly data: WebSocket.RawData; readonly binary: boolean }>((resolve) =>
+        waiting.push(resolve),
+      ))
+    if (message.binary) throw new Error("Expected a text browser control message")
+    return Effect.runPromise(BrowserControlProtocol.decodeFromDesktop(rawData(message.data)))
+  }
+}
+
+function rawData(data: WebSocket.RawData) {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data)
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data))
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+}
@@ -0,0 +1,363 @@
+import { describe, expect, test } from "bun:test"
+import {
+  Browser,
+  BrowserDriver,
+  BrowserDriverError,
+  type BrowserDriverContext,
+  type ChromiumPort,
+} from "@opencode-ai/client/node"
+
+type PortListener = Parameters<ChromiumPort<unknown>["subscribe"]>[0]
+type PortState = ReturnType<ChromiumPort<unknown>["state"]>
+
+describe("Chromium browser driver", () => {
+  test("increments generations and invalidates refs only for main-document changes", async () => {
+    const app = await setup()
+    const snapshot = await app.instance.execute(
+      { type: "snapshot", generation: 0 },
+      { signal: new AbortController().signal },
+    )
+    if (snapshot.type !== "snapshot") throw new Error("Expected snapshot result")
+    expect(snapshot.content).toContain('e1 [button] "Save" disabled=false')
+
+    await app.instance.execute(
+      { type: "click", ref: Browser.Ref.make("e1"), generation: 0 },
+      { signal: new AbortController().signal },
+    )
+    app.port.emit({ title: "Updated" }, false)
+    expect(app.controller.state()).toMatchObject({ title: "Updated", generation: 0 })
+
+    app.port.emit({ url: "https://next.example/" }, true)
+    expect(app.controller.state()).toMatchObject({ url: "https://next.example/", generation: 1 })
+    expect(app.port.calls.some((call) => call.method === "Runtime.releaseObject")).toBe(true)
+
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute(
+            { type: "click", ref: Browser.Ref.make("e1"), generation: 1 },
+            { signal: new AbortController().signal },
+          ),
+        ),
+      ),
+    ).toMatchObject({ code: "stale_ref", message: "The element reference is stale. Call browser_snapshot again." })
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "stale_ref", message: "The browser page changed. Call browser_snapshot again." })
+    await app.controller.dispose()
+  })
+
+  test("parses bounded snapshots and rejects untrusted oversized nodes", async () => {
+    const app = await setup()
+    const result = await app.instance.execute(
+      { type: "snapshot", generation: 0 },
+      { signal: new AbortController().signal },
+    )
+    if (result.type !== "snapshot") throw new Error("Expected snapshot result")
+    expect(result.content).toBe(
+      ["Page: Example", "URL: https://example.com/", "", '  e1 [button] "Save" disabled=false'].join("\n"),
+    )
+    expect(app.port.expressions[0]).toContain("while (visited++ < 500)")
+    expect(app.port.expressions[0]).toContain('editable ? ""')
+    expect(app.port.expressions[0]).not.toContain("textContent")
+    expect(() => new Bun.Transpiler({ loader: "js" }).transformSync(app.port.expressions[0] ?? "")).not.toThrow()
+
+    app.port.snapshotValue = {
+      nodes: Array.from({ length: 501 }, () => ({ role: "button", name: "Save", value: "", depth: 0 })),
+      nextRef: 501,
+    }
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "internal", message: "Invalid browser snapshot nodes." })
+
+    app.port.snapshotValue = {
+      nodes: [{ token: "e2", role: "bad role", name: "Save", value: "", depth: 0 }],
+      nextRef: 2,
+    }
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "internal", message: "Invalid browser snapshot nodes." })
+    expect(app.port.calls.filter((call) => call.method === "Runtime.releaseObject").length).toBeGreaterThanOrEqual(2)
+    await app.controller.dispose()
+  })
+
+  test("releases paired input and fences the port when cancellation races a press", async () => {
+    const app = await setup()
+    await app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal })
+    const abort = new AbortController()
+    const input: string[] = []
+    app.port.onSend = (method, params) => {
+      if (method !== "Input.dispatchMouseEvent") return app.port.response(method, params)
+      if (params?.type === "mousePressed") {
+        input.push("press")
+        abort.abort()
+        return new Promise<never>(() => undefined)
+      }
+      if (params?.type === "mouseReleased") input.push("release")
+      return app.port.response(method, params)
+    }
+
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "click", ref: Browser.Ref.make("e1"), generation: 0 }, { signal: abort.signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "aborted", message: "The browser action was aborted." })
+    await app.controller.dispose()
+    expect(input).toEqual(["press", "release"])
+    expect(app.port.stopCount).toBe(1)
+    expect(app.port.disposeCount).toBe(1)
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ).code,
+    ).toBe("not_attached")
+  })
+
+  test("serializes local controller work with remote commands", async () => {
+    const app = await setup()
+    const navigation = deferred()
+    const started = deferred()
+    app.port.onNavigate = () => {
+      started.resolve()
+      return navigation.promise
+    }
+
+    const local = app.controller.navigate("example.com")
+    await started.promise
+    const remote = app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal })
+    await Promise.resolve()
+    expect(app.port.calls.some((call) => call.method === "Runtime.evaluate")).toBe(false)
+    expect(app.port.navigateURLs).toEqual(["https://example.com/"])
+
+    navigation.resolve()
+    await local
+    expect((await remote).type).toBe("snapshot")
+    expect(app.port.calls.some((call) => call.method === "Runtime.evaluate")).toBe(true)
+    await app.controller.dispose()
+  })
+
+  test("maps navigation, CDP, and adapter failures to driver error codes", async () => {
+    const app = await setup()
+    expect(requireDriverError(await rejected(app.controller.navigate("javascript:alert(1)")))).toMatchObject({
+      code: "invalid_url",
+    })
+    expect(app.port.navigateURLs).toEqual([])
+
+    app.port.onNavigate = () => Promise.reject(new Error("net::ERR_NAME_NOT_RESOLVED"))
+    expect(requireDriverError(await rejected(app.controller.navigate("missing.example")))).toMatchObject({
+      code: "navigation_failed",
+      message: "net::ERR_NAME_NOT_RESOLVED",
+    })
+
+    app.port.onSend = () => Promise.reject(new Error("Could not find object with given id"))
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "stale_ref", message: "The element reference is stale. Call browser_snapshot again." })
+
+    app.port.onSend = () => Promise.reject(new Error("Method not found"))
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "internal", message: "Method not found" })
+
+    app.port.onSend = () => Promise.reject(new BrowserDriverError("page_crashed", "Renderer gone"))
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "snapshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "page_crashed", message: "Renderer gone" })
+    await app.controller.dispose()
+  })
+
+  test("preserves viewport scroll and bounded PNG capture contracts", async () => {
+    const app = await setup()
+    app.port.viewportSize = { width: 101, height: 99 }
+    await app.instance.execute(
+      { type: "scroll", direction: "down", pixels: 5_000, generation: 0 },
+      { signal: new AbortController().signal },
+    )
+    expect(app.port.calls.find((call) => call.params?.type === "mouseWheel")?.params).toEqual({
+      type: "mouseWheel",
+      x: 51,
+      y: 50,
+      deltaX: 0,
+      deltaY: 2_000,
+    })
+
+    const result = await app.instance.execute(
+      { type: "screenshot", generation: 0 },
+      { signal: new AbortController().signal },
+    )
+    if (result.type !== "screenshot") throw new Error("Expected screenshot result")
+    expect(app.port.screenshotLimits).toEqual([2_000])
+    expect(result).toMatchObject({ mediaType: "image/png", width: 100, height: 50 })
+    expect(result.data).toEqual(new Uint8Array([137, 80, 78, 71]))
+
+    app.port.screenshotValue = {
+      data: new Uint8Array(5 * 1_024 * 1_024 + 1),
+      width: 100,
+      height: 50,
+    }
+    expect(
+      requireDriverError(
+        await rejected(
+          app.instance.execute({ type: "screenshot", generation: 0 }, { signal: new AbortController().signal }),
+        ),
+      ),
+    ).toMatchObject({ code: "result_too_large", message: "The browser screenshot exceeds 5 MiB." })
+    await app.controller.dispose()
+  })
+})
+
+class FakeChromiumPort implements ChromiumPort<{ readonly name: string }> {
+  readonly resource = { name: "fake-chromium" }
+  readonly listeners = new Set<PortListener>()
+  readonly calls: Array<{ readonly method: string; readonly params?: Record<string, unknown> }> = []
+  readonly expressions: string[] = []
+  readonly navigateURLs: string[] = []
+  readonly screenshotLimits: number[] = []
+  current: PortState = {
+    url: "https://example.com/",
+    title: "Example",
+    loading: false,
+    canGoBack: false,
+    canGoForward: false,
+  }
+  snapshotValue: unknown = {
+    nodes: [{ token: "e1", role: "button", name: "Save", value: "", depth: 1, disabled: false }],
+    nextRef: 1,
+  }
+  screenshotValue = { data: new Uint8Array([137, 80, 78, 71]), width: 100, height: 50 }
+  viewportSize = { width: 800, height: 600 }
+  onNavigate?: (url: string) => PromiseLike<void> | void
+  onSend?: (method: string, params?: Record<string, unknown>) => unknown
+  stopCount = 0
+  disposeCount = 0
+  private object = 0
+
+  state() {
+    return this.current
+  }
+
+  subscribe(listener: PortListener) {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  navigate(url: string) {
+    this.navigateURLs.push(url)
+    return Promise.resolve().then(() => this.onNavigate?.(url))
+  }
+
+  back() {}
+
+  forward() {}
+
+  reload() {}
+
+  stop() {
+    this.stopCount++
+  }
+
+  send(method: string, params?: Record<string, unknown>) {
+    this.calls.push({ method, ...(params ? { params } : {}) })
+    if (method === "Runtime.evaluate" && typeof params?.expression === "string") {
+      this.expressions.push(params.expression)
+    }
+    return Promise.resolve().then(() => (this.onSend ? this.onSend(method, params) : this.response(method, params)))
+  }
+
+  response(method: string, params?: Record<string, unknown>) {
+    if (method === "Runtime.evaluate") return { result: { objectId: `snapshot-${++this.object}` } }
+    if (method !== "Runtime.callFunctionOn") return {}
+    if (params?.functionDeclaration === "function() { return this.result }") {
+      return { result: { value: this.snapshotValue } }
+    }
+    if (typeof params?.functionDeclaration === "string" && params.functionDeclaration.includes("const editable")) {
+      return { result: { value: true } }
+    }
+    return { result: { value: { x: 25, y: 40 } } }
+  }
+
+  viewport() {
+    return this.viewportSize
+  }
+
+  screenshot(options: { readonly maxDimension: number }) {
+    this.screenshotLimits.push(options.maxDimension)
+    return Promise.resolve(this.screenshotValue)
+  }
+
+  dispose() {
+    this.disposeCount++
+  }
+
+  emit(state: Partial<PortState>, mainDocumentChanged: boolean) {
+    this.current = { ...this.current, ...state }
+    this.listeners.forEach((listener) => listener({ state: this.current, mainDocumentChanged }))
+  }
+}
+
+async function setup() {
+  const port = new FakeChromiumPort()
+  const lifetime = new AbortController()
+  const driver = BrowserDriver.chromium(() => port)
+  const instance = await driver({
+    proxy: {
+      url: "https://127.0.0.1:1234",
+      host: "127.0.0.1",
+      port: 1234,
+      credentials: { username: "user", password: "pass" },
+      certificateFingerprint: "fingerprint",
+    },
+    signal: lifetime.signal,
+  } satisfies BrowserDriverContext)
+  return { port, lifetime, instance, controller: instance.resource }
+}
+
+function deferred() {
+  let resolve!: () => void
+  const promise = new Promise<void>((next) => {
+    resolve = next
+  })
+  return { promise, resolve }
+}
+
+function rejected(promise: Promise<unknown>) {
+  return promise.then(
+    () => new Error("Expected operation to reject"),
+    (error: unknown) => error,
+  )
+}
+
+function requireDriverError(input: unknown) {
+  if (!(input instanceof BrowserDriverError)) throw input
+  return input
+}
@@ -0,0 +1,165 @@
+import { expect, test } from "bun:test"
+import { mkdir, mkdtemp, rm } from "node:fs/promises"
+import { join, relative, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+
+const directory = resolve(import.meta.dir, "../..")
+
+test("built Node entrypoint imports in Node and treats HTTP authentication rejection as fatal", async () => {
+  await buildClient()
+  const output = await Bun.file(join(directory, "dist/node/index.js")).text()
+  expect(output).not.toMatch(/(?:from\s+|import\s*)["']\.\.?\//)
+
+  const temporary = await mkdtemp(join(import.meta.dir, ".node-package-"))
+  try {
+    await Bun.write(join(temporary, "index.mjs"), output)
+    await stageWorkspaceDependencies(temporary)
+    const child = Bun.spawn(
+      ["node", "--input-type=module", "-e", nodeScenario(pathToFileURL(join(temporary, "index.mjs")).href)],
+      { cwd: temporary, stdout: "pipe", stderr: "pipe" },
+    )
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+    if (exitCode !== 0) throw new Error(stderr || stdout)
+    expect(stdout.trim()).toBe("ok")
+  } finally {
+    await rm(temporary, { recursive: true, force: true })
+  }
+}, 60_000)
+
+async function buildClient() {
+  const child = Bun.spawn([process.execPath, "run", "build"], {
+    cwd: directory,
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ])
+  if (exitCode !== 0) throw new Error(stdout + stderr)
+}
+
+async function stageWorkspaceDependencies(temporary: string) {
+  const schema = join(temporary, "node_modules/@opencode-ai/schema")
+  const protocol = join(temporary, "node_modules/@opencode-ai/protocol")
+  await Promise.all([mkdir(schema, { recursive: true }), mkdir(protocol, { recursive: true })])
+
+  const schemaEntry = join(temporary, "schema.ts")
+  const protocolEntry = join(temporary, "protocol.ts")
+  await Promise.all([
+    Bun.write(
+      schemaEntry,
+      [
+        `export { Browser } from ${JSON.stringify(importPath(temporary, resolve(directory, "../schema/src/browser.ts")))}`,
+        `export { BrowserControl } from ${JSON.stringify(importPath(temporary, resolve(directory, "../schema/src/browser-control.ts")))}`,
+        `export { BrowserTunnel } from ${JSON.stringify(importPath(temporary, resolve(directory, "../schema/src/browser-tunnel.ts")))}`,
+        `export { Session } from ${JSON.stringify(importPath(temporary, resolve(directory, "../schema/src/session.ts")))}`,
+      ].join("\n"),
+    ),
+    Bun.write(
+      protocolEntry,
+      [
+        `export { BrowserControlProtocol } from ${JSON.stringify(importPath(temporary, resolve(directory, "../protocol/src/browser-control.ts")))}`,
+        `export { BrowserTunnelProtocol } from ${JSON.stringify(importPath(temporary, resolve(directory, "../protocol/src/browser-tunnel.ts")))}`,
+        `export { BROWSER_CONTROL_PROTOCOL, BROWSER_TUNNEL_PROTOCOL } from ${JSON.stringify(importPath(temporary, resolve(directory, "../protocol/src/groups/browser.ts")))}`,
+      ].join("\n"),
+    ),
+  ])
+  const [schemaBuild, protocolBuild] = await Promise.all([
+    Bun.build({
+      entrypoints: [schemaEntry],
+      outdir: schema,
+      naming: "index.js",
+      target: "node",
+      format: "esm",
+      packages: "bundle",
+    }),
+    Bun.build({
+      entrypoints: [protocolEntry],
+      outdir: protocol,
+      naming: "index.js",
+      target: "node",
+      format: "esm",
+      packages: "bundle",
+    }),
+  ])
+  if (!schemaBuild.success) throw new Error(schemaBuild.logs.map((log) => log.message).join("\n"))
+  if (!protocolBuild.success) throw new Error(protocolBuild.logs.map((log) => log.message).join("\n"))
+  await Promise.all([
+    Bun.write(
+      join(schema, "package.json"),
+      JSON.stringify({
+        type: "module",
+        exports: {
+          "./browser": "./index.js",
+          "./browser-control": "./index.js",
+          "./browser-tunnel": "./index.js",
+          "./session": "./index.js",
+        },
+      }),
+    ),
+    Bun.write(
+      join(protocol, "package.json"),
+      JSON.stringify({
+        type: "module",
+        exports: {
+          "./browser-control": "./index.js",
+          "./browser-tunnel": "./index.js",
+          "./groups/browser": "./index.js",
+        },
+      }),
+    ),
+  ])
+}
+
+function importPath(from: string, to: string) {
+  const path = relative(from, to).replaceAll("\\", "/")
+  return path.startsWith(".") ? path : `./${path}`
+}
+
+function nodeScenario(moduleURL: string) {
+  return `import { createServer } from "node:http"
+const sdk = await import(${JSON.stringify(moduleURL)})
+if (typeof sdk.OpenCode.make !== "function") throw new Error("Missing OpenCode.make")
+if (typeof sdk.BrowserDriver.define !== "function") throw new Error("Missing BrowserDriver.define")
+if (typeof sdk.BrowserDriver.chromium !== "function") throw new Error("Missing BrowserDriver.chromium")
+if (typeof sdk.BrowserDriverError !== "function") throw new Error("Missing BrowserDriverError")
+if (!sdk.Browser.State) throw new Error("Missing canonical Browser export")
+
+let upgrades = 0
+const server = createServer()
+server.on("upgrade", (_request, socket) => {
+  upgrades++
+  socket.end("HTTP/1.1 401 Unauthorized\\r\\nContent-Length: 0\\r\\nConnection: close\\r\\n\\r\\n")
+})
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve))
+const address = server.address()
+if (!address || typeof address === "string") throw new Error("Server did not bind")
+let disposed = 0
+const driver = () => ({
+  resource: undefined,
+  state: () => ({ url: "about:blank", title: "", loading: false, canGoBack: false, canGoForward: false, generation: 0 }),
+  subscribe: () => () => undefined,
+  execute: async () => { throw new sdk.BrowserDriverError("internal", "unavailable") },
+  dispose: () => { disposed++ },
+})
+const client = sdk.OpenCode.make({ baseUrl: \`http://127.0.0.1:\${address.port}\` })
+const error = await Promise.race([
+  client.browser.attach({ sessionID: "ses_node_auth_rejection", driver }).then(
+    () => new Error("Expected authentication rejection"),
+    (cause) => cause,
+  ),
+  new Promise((resolve) => setTimeout(() => resolve(new Error("Authentication rejection timed out")), 2_000)),
+])
+await new Promise((resolve) => setTimeout(resolve, 250))
+await new Promise((resolve) => server.close(resolve))
+if (!(error instanceof Error) || !error.message.includes("HTTP 401")) throw error
+if (upgrades !== 1) throw new Error(\`Expected one upgrade, received \${upgrades}\`)
+if (disposed !== 1) throw new Error(\`Expected one driver disposal, received \${disposed}\`)
+console.log("ok")`
+}
@@ -0,0 +1,22 @@
+import { createHash, X509Certificate } from "node:crypto"
+import { createSecureContext } from "node:tls"
+import { describe, expect, test } from "bun:test"
+import { createBrowserProxyCertificate } from "../../src/node/browser/proxy-certificate"
+
+describe("browser proxy certificate", () => {
+  test("creates a unique valid certificate pinned to its loopback names", () => {
+    const hostname = "opencode-test.localhost"
+    const first = createBrowserProxyCertificate(hostname)
+    const second = createBrowserProxyCertificate(hostname)
+    const certificate = new X509Certificate(first.certificate)
+    const fingerprint = createHash("sha256").update(certificate.raw).digest("base64")
+
+    expect(first.key.startsWith("-----BEGIN PRIVATE KEY-----")).toBe(true)
+    expect(first.certificate.startsWith("-----BEGIN CERTIFICATE-----")).toBe(true)
+    expect(first.fingerprint).toBe(`sha256/${fingerprint}`)
+    expect(certificate.subjectAltName).toContain(`DNS:${hostname}`)
+    expect(certificate.subjectAltName).toContain("IP Address:127.0.0.1")
+    expect(first.fingerprint).not.toBe(second.fingerprint)
+    expect(() => createSecureContext({ key: first.key, cert: first.certificate })).not.toThrow()
+  })
+})
@@ -0,0 +1,452 @@
+import { createHash } from "node:crypto"
+import { once } from "node:events"
+import { mkdtemp, rm } from "node:fs/promises"
+import { createServer } from "node:http"
+import { Socket } from "node:net"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { Duplex } from "node:stream"
+import { connect, type TLSSocket } from "node:tls"
+import { pathToFileURL } from "node:url"
+import { describe, expect, test } from "bun:test"
+import { createBrowserProxy } from "../../src/node/browser/proxy"
+
+describe("browser proxy", () => {
+  test("forwards authenticated CONNECT streams without directly dialing the target", async () => {
+    let directConnections = 0
+    const decoy = createServer((_incoming, response) => response.end("DIRECT DIAL"))
+    decoy.on("connection", () => directConnections++)
+    await new Promise<void>((resolve) => decoy.listen(0, "127.0.0.1", resolve))
+    const decoyAddress = decoy.address()
+    if (decoyAddress === null || typeof decoyAddress === "string") throw new Error("decoy server did not bind TCP")
+    const target = createServer((incoming, response) => response.end(`TARGET ${incoming.method} ${incoming.url}`))
+    await new Promise<void>((resolve) => target.listen(0, "127.0.0.1", resolve))
+    const targetAddress = target.address()
+    if (targetAddress === null || typeof targetAddress === "string") throw new Error("target server did not bind TCP")
+    const opened: Array<{ host: string; port: number }> = []
+    const proxy = await createBrowserProxy({
+      connect: async (destination, signal) => {
+        opened.push(destination)
+        const socket = new Socket({ allowHalfOpen: true })
+        const abort = () => socket.destroy(new Error("cancelled"))
+        signal.addEventListener("abort", abort, { once: true })
+        socket.once("close", () => signal.removeEventListener("abort", abort))
+        // Emulate the server-side tunnel dial. The local decoy must never receive a connection.
+        socket.connect(targetAddress.port, "127.0.0.1")
+        await once(socket, "connect")
+        return socket
+      },
+    })
+    try {
+      const tunnel = await proxyConnect(proxy, `127.0.0.1:${decoyAddress.port}`)
+      expect(tunnel.status).toBe(200)
+      tunnel.socket.write(
+        `GET /connected HTTP/1.1\r\nHost: 127.0.0.1:${decoyAddress.port}\r\nConnection: close\r\n\r\n`,
+      )
+      const response = await readAll(tunnel.socket, tunnel.leftover)
+      expect(response).toContain("TARGET GET /connected")
+      expect(opened).toEqual([{ host: "127.0.0.1", port: decoyAddress.port }])
+
+      const certificate = await peerCertificate(proxy)
+      expect(`sha256/${createHash("sha256").update(certificate).digest("base64")}`).toBe(proxy.certificateFingerprint)
+      expect(directConnections).toBe(0)
+    } finally {
+      await proxy.close()
+      await Promise.all([
+        new Promise<void>((resolve) => target.close(() => resolve())),
+        new Promise<void>((resolve) => decoy.close(() => resolve())),
+      ])
+    }
+  })
+
+  test("forwards absolute-form HTTP with Node framing and closes held-open targets", async () => {
+    expect(await nodeAbsoluteFormScenario()).toEqual({
+      unauthorized: { status: 407, body: "" },
+      forwarded: { status: 200, body: "TARGET GET /absolute?q=1" },
+      posted: { status: 200, body: "TARGET POST /post request body" },
+      chunked: { status: 200, body: "TARGET CHUNKED" },
+      held: { status: 200, body: "ok" },
+      opened: 4,
+      destinationsCorrect: true,
+      directConnections: 0,
+      heldDestroyed: true,
+    })
+  })
+
+  test("limits concurrent tunnel setup to six connections", async () => {
+    let active = 0
+    let maximum = 0
+    let started = 0
+    const releases: Array<() => void> = []
+    const proxy = await createBrowserProxy({
+      connect: (_destination, signal) =>
+        new Promise<Duplex>((resolve, reject) => {
+          active++
+          started++
+          maximum = Math.max(maximum, active)
+          const finish = (result: () => void) => {
+            signal.removeEventListener("abort", abort)
+            active--
+            result()
+          }
+          const abort = () => finish(() => reject(new Error("cancelled")))
+          signal.addEventListener("abort", abort, { once: true })
+          releases.push(() =>
+            finish(() =>
+              resolve(
+                new Duplex({
+                  read() {},
+                  write(_chunk, _encoding, callback) {
+                    callback()
+                  },
+                }),
+              ),
+            ),
+          )
+        }),
+    })
+    const connections = Array.from({ length: 7 }, () =>
+      proxyConnect(proxy, "target.example:443").then(
+        (result) => result.socket.destroy(),
+        () => undefined,
+      ),
+    )
+    try {
+      await waitFor(() => started === 6)
+      expect(maximum).toBe(6)
+      expect(started).toBe(6)
+
+      releases.shift()?.()
+      await waitFor(() => started === 7)
+      expect(maximum).toBe(6)
+    } finally {
+      await proxy.close()
+      await Promise.all(connections)
+    }
+  })
+
+  test("aborts pending CONNECT setup when the downstream client closes", async () => {
+    let aborted = false
+    let resolveStarted!: () => void
+    const started = new Promise<void>((resolve) => {
+      resolveStarted = resolve
+    })
+    const proxy = await createBrowserProxy({
+      connect: (_destination, signal) =>
+        new Promise<Duplex>((_resolve, reject) => {
+          resolveStarted()
+          const abort = () => {
+            aborted = true
+            reject(new Error("cancelled"))
+          }
+          signal.addEventListener("abort", abort, { once: true })
+          if (signal.aborted) abort()
+        }),
+    })
+    const socket = proxyClient(
+      proxy,
+      `CONNECT target.example:443 HTTP/1.1\r\nHost: target.example:443\r\nProxy-Authorization: ${authorization(proxy)}\r\n\r\n`,
+    )
+    try {
+      await started
+      socket.destroy()
+      await waitFor(() => aborted)
+    } finally {
+      socket.destroy()
+      await proxy.close()
+    }
+  })
+
+  test("aborts pending absolute-form setup when the downstream client closes", async () => {
+    let aborted = false
+    let resolveStarted!: () => void
+    const started = new Promise<void>((resolve) => {
+      resolveStarted = resolve
+    })
+    const proxy = await createBrowserProxy({
+      connect: (_destination, signal) =>
+        new Promise<Duplex>((_resolve, reject) => {
+          resolveStarted()
+          const abort = () => {
+            aborted = true
+            reject(new Error("cancelled"))
+          }
+          signal.addEventListener("abort", abort, { once: true })
+          if (signal.aborted) abort()
+        }),
+    })
+    const socket = proxyClient(
+      proxy,
+      `GET http://target.example/pending HTTP/1.1\r\nHost: target.example\r\nProxy-Authorization: ${authorization(proxy)}\r\n\r\n`,
+    )
+    try {
+      await started
+      socket.destroy()
+      await waitFor(() => aborted)
+    } finally {
+      socket.destroy()
+      await proxy.close()
+    }
+  })
+
+  test("closes absolute-form requests when the target tunnel cannot connect", async () => {
+    const proxy = await createBrowserProxy({ connect: () => Promise.reject(new Error("target unavailable")) })
+    const socket = proxyClient(
+      proxy,
+      `GET http://target.example/unavailable HTTP/1.1\r\nHost: target.example\r\nProxy-Authorization: ${authorization(proxy)}\r\n\r\n`,
+    )
+    const chunks: Buffer[] = []
+    socket.on("data", (chunk) => chunks.push(chunk))
+    try {
+      await once(socket, "close")
+      expect(Buffer.concat(chunks).toString()).not.toContain("502 Bad Gateway")
+    } finally {
+      socket.destroy()
+      await proxy.close()
+    }
+  })
+})
+
+type ProxyInfo = Awaited<ReturnType<typeof createBrowserProxy>>
+
+function authorization(proxy: ProxyInfo) {
+  return `Basic ${Buffer.from(`${proxy.credentials.username}:${proxy.credentials.password}`).toString("base64")}`
+}
+
+function proxyClient(proxy: ProxyInfo, request: string) {
+  const socket = connect(
+    {
+      host: "127.0.0.1",
+      port: proxy.port,
+      servername: proxy.host.endsWith(".localhost") ? proxy.host : undefined,
+      rejectUnauthorized: false,
+    },
+    () => socket.write(request),
+  )
+  socket.on("error", () => undefined)
+  return socket
+}
+
+async function nodeAbsoluteFormScenario() {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-browser-proxy-"))
+  try {
+    const built = await Bun.build({
+      entrypoints: [join(import.meta.dir, "../../src/node/browser/proxy.ts")],
+      outdir: directory,
+      naming: "browser-proxy.mjs",
+      target: "node",
+      format: "esm",
+    })
+    if (!built.success) throw new Error(built.logs.map((log) => log.message).join("\n"))
+    const output = built.outputs[0]
+    if (!output) throw new Error("Browser proxy Node bundle was not emitted")
+    const child = Bun.spawn(
+      ["node", "--input-type=module", "-e", absoluteFormScenario(pathToFileURL(output.path).href)],
+      { stdout: "pipe", stderr: "pipe" },
+    )
+    const [code, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+    if (code !== 0) throw new Error(stderr || stdout)
+    const result: unknown = JSON.parse(stdout)
+    return result
+  } finally {
+    await rm(directory, { recursive: true, force: true })
+  }
+}
+
+function absoluteFormScenario(moduleURL: string) {
+  return `import { createBrowserProxy } from ${JSON.stringify(moduleURL)}
+import { once } from "node:events"
+import { Agent, createServer, request } from "node:http"
+import { Socket } from "node:net"
+import { Duplex } from "node:stream"
+import { connect } from "node:tls"
+
+const proxyRequest = async (proxy, path, authenticated, options = {}) => {
+  const socket = await new Promise((resolve, reject) => {
+    const socket = connect({ host: "127.0.0.1", port: proxy.port, servername: proxy.host, rejectUnauthorized: false }, () => resolve(socket))
+    socket.once("error", reject)
+  })
+  const agent = new Agent({ keepAlive: false, maxSockets: 1, noDelay: false })
+  agent.createConnection = () => socket
+  const body = Buffer.from(options.body ?? "")
+  try {
+    return await new Promise((resolve, reject) => {
+      const incoming = request({
+        agent,
+        hostname: proxy.host,
+        path,
+        method: options.method ?? "GET",
+        headers: {
+          connection: "close",
+          ...(authenticated ? { "proxy-authorization": "Basic " + Buffer.from(proxy.credentials.username + ":" + proxy.credentials.password).toString("base64") } : {}),
+          ...(options.chunked ? { "transfer-encoding": "chunked" } : { "content-length": body.byteLength.toString() }),
+        },
+      }, (response) => {
+        const chunks = []
+        response.on("data", (chunk) => chunks.push(chunk))
+        response.once("end", () => resolve({ status: response.statusCode ?? 0, body: Buffer.concat(chunks).toString() }))
+      })
+      incoming.once("error", reject)
+      incoming.end(body)
+    })
+  } finally {
+    agent.destroy()
+    socket.destroy()
+  }
+}
+
+let directConnections = 0
+const decoy = createServer((_incoming, response) => response.end("DIRECT DIAL"))
+decoy.on("connection", () => directConnections++)
+decoy.listen(0, "127.0.0.1")
+await once(decoy, "listening")
+const decoyAddress = decoy.address()
+if (!decoyAddress || typeof decoyAddress === "string") throw new Error("decoy server did not bind TCP")
+
+const targetServer = createServer((incoming, response) => {
+  const chunks = []
+  incoming.on("data", (chunk) => chunks.push(chunk))
+  incoming.on("end", () => {
+    response.writeHead(200, { "content-type": "text/plain" })
+    if (incoming.url === "/chunked") {
+      response.write("TARGET ")
+      response.end("CHUNKED")
+      return
+    }
+    const body = Buffer.concat(chunks).toString()
+    response.end("TARGET " + incoming.method + " " + incoming.url + (body ? " " + body : ""))
+  })
+})
+targetServer.listen(0, "127.0.0.1")
+await once(targetServer, "listening")
+const targetAddress = targetServer.address()
+if (!targetAddress || typeof targetAddress === "string") throw new Error("target server did not bind TCP")
+
+const opened = []
+let held
+const proxy = await createBrowserProxy({
+  connect: async (destination, signal) => {
+    opened.push(destination)
+    if (destination.host === "held.example") {
+      let responded = false
+      held = new Duplex({
+        read() {},
+        write(chunk, _encoding, callback) {
+          if (!responded && Buffer.from(chunk).includes(Buffer.from("\\r\\n\\r\\n"))) {
+            responded = true
+            this.push(Buffer.from("HTTP/1.1 200 OK\\r\\nContent-Length: 2\\r\\n\\r\\nok"))
+          }
+          callback()
+        },
+      })
+      return held
+    }
+    const socket = new Socket({ allowHalfOpen: true })
+    const abort = () => socket.destroy(new Error("cancelled"))
+    signal.addEventListener("abort", abort, { once: true })
+    socket.once("close", () => signal.removeEventListener("abort", abort))
+    socket.connect(targetAddress.port, "127.0.0.1")
+    await once(socket, "connect")
+    return socket
+  },
+})
+
+try {
+  const base = "http://127.0.0.1:" + decoyAddress.port
+  const unauthorized = await proxyRequest(proxy, base + "/private", false)
+  const forwarded = await proxyRequest(proxy, base + "/absolute?q=1", true)
+  const posted = await proxyRequest(proxy, base + "/post", true, { method: "POST", body: "request body", chunked: true })
+  const chunked = await proxyRequest(proxy, base + "/chunked", true)
+  const heldResult = await proxyRequest(proxy, "http://held.example/held-open", true)
+  await new Promise((resolve) => setImmediate(resolve))
+  console.log(JSON.stringify({
+    unauthorized,
+    forwarded,
+    posted,
+    chunked,
+    held: heldResult,
+    opened: opened.length,
+    destinationsCorrect: opened.slice(0, 3).every((item) => item.host === "127.0.0.1" && item.port === decoyAddress.port) && opened[3]?.host === "held.example" && opened[3]?.port === 80,
+    directConnections,
+    heldDestroyed: held?.destroyed === true,
+  }))
+} finally {
+  await proxy.close()
+  targetServer.closeAllConnections()
+  decoy.closeAllConnections()
+  await Promise.all([new Promise((resolve) => targetServer.close(resolve)), new Promise((resolve) => decoy.close(resolve))])
+}`
+}
+
+function proxyConnect(proxy: ProxyInfo, destination: string) {
+  return new Promise<{ status: number; socket: TLSSocket; leftover: Buffer }>((resolve, reject) => {
+    const socket = connect(
+      {
+        host: "127.0.0.1",
+        port: proxy.port,
+        servername: proxy.host.endsWith(".localhost") ? proxy.host : undefined,
+        rejectUnauthorized: false,
+      },
+      () => {
+        socket.write(
+          `CONNECT ${destination} HTTP/1.1\r\nHost: ${destination}\r\nProxy-Authorization: ${authorization(proxy)}\r\n\r\n`,
+        )
+      },
+    )
+    let buffered = Buffer.alloc(0)
+    let settled = false
+    const onData = (chunk: Buffer) => {
+      buffered = Buffer.concat([buffered, chunk])
+      const end = buffered.indexOf("\r\n\r\n")
+      if (end < 0) return
+      socket.off("data", onData)
+      const status = Number(buffered.toString("ascii", 0, end).split(" ", 2)[1])
+      settled = true
+      resolve({ status, socket, leftover: buffered.subarray(end + 4) })
+    }
+    socket.on("data", onData)
+    socket.once("error", reject)
+    socket.once("close", () => {
+      if (!settled) reject(new Error("Browser proxy connection closed before responding"))
+    })
+  })
+}
+
+function readAll(socket: TLSSocket, initial: Buffer) {
+  return new Promise<string>((resolve, reject) => {
+    const chunks = [initial]
+    socket.on("data", (chunk) => chunks.push(chunk))
+    socket.on("end", () => resolve(Buffer.concat(chunks).toString()))
+    socket.once("error", reject)
+  })
+}
+
+function peerCertificate(proxy: ProxyInfo) {
+  return new Promise<Buffer>((resolve, reject) => {
+    const socket = connect(
+      {
+        host: "127.0.0.1",
+        port: proxy.port,
+        servername: proxy.host.endsWith(".localhost") ? proxy.host : undefined,
+        rejectUnauthorized: false,
+      },
+      () => {
+        resolve(socket.getPeerCertificate().raw)
+        socket.end()
+      },
+    )
+    socket.once("error", reject)
+  })
+}
+
+async function waitFor(check: () => boolean) {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    if (check()) return
+    await Bun.sleep(5)
+  }
+  throw new Error("Timed out waiting for browser proxy test condition")
+}
@@ -0,0 +1,208 @@
+import { BrowserTunnelProtocol } from "@opencode-ai/protocol/browser-tunnel"
+import { BROWSER_TUNNEL_PROTOCOL } from "@opencode-ai/protocol/groups/browser"
+import { Browser } from "@opencode-ai/schema/browser"
+import { BrowserTunnel } from "@opencode-ai/schema/browser-tunnel"
+import { Session } from "@opencode-ai/schema/session"
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { once } from "node:events"
+import { createServer } from "node:http"
+import WebSocket, { WebSocketServer } from "ws"
+import { BrowserTunnelError, openBrowserTunnel } from "../../src/node/browser/tunnel"
+
+const sessionID = Session.ID.make("ses_client_tunnel")
+const leaseID = Browser.LeaseID.make("brl_clienttunnel")
+
+describe("browser tunnel", () => {
+  test("enforces byte and frame windows and preserves both half-closes", async () => {
+    const server = await tunnelServer()
+    try {
+      const opening = openBrowserTunnel({
+        endpoint: server.endpoint,
+        sessionID,
+        leaseID,
+        target: { host: BrowserTunnel.Host.make("target.example"), port: BrowserTunnel.Port.make(443) },
+      })
+      const socket = await server.connected
+      const next = frameReader(socket)
+      socket.send(BrowserTunnelProtocol.encodeFromServer({ type: "browser.tunnel.ready" }), { binary: true })
+      const open = await next()
+      expect(open).toMatchObject({
+        type: "control",
+        message: {
+          type: "browser.tunnel.open",
+          sessionID,
+          leaseID,
+          target: { host: "target.example", port: 443 },
+        },
+      })
+      socket.send(
+        BrowserTunnelProtocol.encodeFromServer({
+          type: "browser.tunnel.opened",
+          receiveWindow: BrowserTunnel.WindowSize.make(BrowserTunnelProtocol.InitialWindowBytes),
+          receiveFrames: BrowserTunnel.FrameWindow.make(BrowserTunnelProtocol.InitialFrameWindow),
+        }),
+        { binary: true },
+      )
+      const tunnel = await opening
+
+      let writeSettled = false
+      const writing = new Promise<void>((resolve, reject) => {
+        tunnel.write(Buffer.alloc(BrowserTunnelProtocol.InitialWindowBytes + 1, 7), (error) => {
+          writeSettled = true
+          if (error) reject(error)
+          else resolve()
+        })
+      })
+      const sent = []
+      for (let index = 0; index < 4; index++) sent.push(await next())
+      expect(sent.every((frame) => frame.type === "data" && frame.data.byteLength === 64 * 1_024)).toBe(true)
+      await Bun.sleep(25)
+      expect(writeSettled).toBe(false)
+
+      socket.send(
+        BrowserTunnelProtocol.encodeFromServer({
+          type: "browser.tunnel.window",
+          bytes: BrowserTunnel.WindowBytes.make(64 * 1_024),
+          frames: BrowserTunnel.FrameWindow.make(1),
+        }),
+        { binary: true },
+      )
+      const final = await next()
+      expect(final.type === "data" && final.data.byteLength).toBe(1)
+      await writing
+
+      const received = once(tunnel, "data")
+      socket.send(BrowserTunnelProtocol.data(Buffer.from("from server")), { binary: true })
+      expect(Buffer.from((await received)[0]).toString()).toBe("from server")
+      expect(await next()).toEqual({
+        type: "control",
+        message: {
+          type: "browser.tunnel.window",
+          bytes: Buffer.byteLength("from server"),
+          frames: 1,
+        },
+      })
+
+      const localEnd = next()
+      tunnel.end()
+      expect(await localEnd).toEqual({ type: "control", message: { type: "browser.tunnel.end" } })
+      const remoteEnd = once(tunnel, "end")
+      socket.send(BrowserTunnelProtocol.encodeFromServer({ type: "browser.tunnel.end" }), { binary: true })
+      await remoteEnd
+    } finally {
+      await server.close()
+    }
+  })
+
+  test("rejects window credit that does not exactly match complete frames", async () => {
+    const server = await tunnelServer()
+    try {
+      const opening = openBrowserTunnel({
+        endpoint: server.endpoint,
+        sessionID,
+        leaseID,
+        target: { host: BrowserTunnel.Host.make("target.example"), port: BrowserTunnel.Port.make(80) },
+      })
+      const socket = await server.connected
+      const next = frameReader(socket)
+      socket.send(BrowserTunnelProtocol.encodeFromServer({ type: "browser.tunnel.ready" }), { binary: true })
+      await next()
+      socket.send(
+        BrowserTunnelProtocol.encodeFromServer({
+          type: "browser.tunnel.opened",
+          receiveWindow: BrowserTunnel.WindowSize.make(BrowserTunnelProtocol.InitialWindowBytes),
+          receiveFrames: BrowserTunnel.FrameWindow.make(BrowserTunnelProtocol.InitialFrameWindow),
+        }),
+        { binary: true },
+      )
+      const tunnel = await opening
+      await new Promise<void>((resolve, reject) =>
+        tunnel.write(Buffer.from("frame"), (error) => (error ? reject(error) : resolve())),
+      )
+      await next()
+      const failed = once(tunnel, "error")
+      socket.send(
+        BrowserTunnelProtocol.encodeFromServer({
+          type: "browser.tunnel.window",
+          bytes: BrowserTunnel.WindowBytes.make(4),
+          frames: BrowserTunnel.FrameWindow.make(1),
+        }),
+        { binary: true },
+      )
+      const error = (await failed)[0]
+      if (!(error instanceof BrowserTunnelError)) throw new Error("expected browser tunnel error")
+      expect(error.code).toBe("protocol_error")
+      expect(await next()).toEqual({
+        type: "control",
+        message: { type: "browser.tunnel.reset", code: "protocol_error" },
+      })
+    } finally {
+      await server.close()
+    }
+  })
+})
+
+async function tunnelServer() {
+  const authorization = `Basic ${Buffer.from("opencode:secret").toString("base64")}`
+  const http = createServer()
+  const webSockets = new WebSocketServer({ noServer: true })
+  let resolveConnected!: (socket: WebSocket) => void
+  const connected = new Promise<WebSocket>((resolve) => {
+    resolveConnected = resolve
+  })
+  webSockets.once("connection", resolveConnected)
+  http.on("upgrade", (request, socket, head) => {
+    if (
+      request.url !== "/api/browser/tunnel" ||
+      request.headers.authorization !== authorization ||
+      request.headers["sec-websocket-protocol"] !== BROWSER_TUNNEL_PROTOCOL
+    ) {
+      socket.end("HTTP/1.1 401 Unauthorized\r\n\r\n")
+      return
+    }
+    webSockets.handleUpgrade(request, socket, head, (webSocket) => webSockets.emit("connection", webSocket, request))
+  })
+  await new Promise<void>((resolve) => http.listen(0, "127.0.0.1", resolve))
+  const address = http.address()
+  if (address === null || typeof address === "string") throw new Error("browser tunnel server did not bind TCP")
+  return {
+    connected,
+    endpoint: {
+      url: `http://127.0.0.1:${address.port}`,
+      authorization,
+    },
+    async close() {
+      webSockets.clients.forEach((socket) => socket.terminate())
+      webSockets.close()
+      http.closeAllConnections()
+      http.close()
+      await Bun.sleep(10)
+    },
+  }
+}
+
+function frameReader(socket: WebSocket) {
+  const queued: Array<{ readonly data: WebSocket.RawData; readonly binary: boolean }> = []
+  const waiting: Array<(message: { readonly data: WebSocket.RawData; readonly binary: boolean }) => void> = []
+  socket.on("message", (data, binary) => {
+    const resolve = waiting.shift()
+    if (resolve) resolve({ data, binary })
+    else queued.push({ data, binary })
+  })
+  return async () => {
+    const message =
+      queued.shift() ??
+      (await new Promise<{ readonly data: WebSocket.RawData; readonly binary: boolean }>((resolve) =>
+        waiting.push(resolve),
+      ))
+    if (!message.binary) throw new Error("Expected a binary browser tunnel frame")
+    return Effect.runPromise(BrowserTunnelProtocol.decodeFromDesktop(rawData(message.data)))
+  }
+}
+
+function rawData(data: WebSocket.RawData) {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data)
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data))
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+}
@@ -32,6 +32,7 @@ test("exposes every standard HTTP API group", () => {
    "projectCopy",
    "vcs",
    "debug",
+    "websearch",
  ])
  expect(Object.keys(client.debug)).toEqual(["location"])
  expect(Object.keys(client.debug.location)).toEqual(["list", "evict"])
@@ -41,6 +42,7 @@ test("exposes every standard HTTP API group", () => {
  expect(Object.keys(client.integration.connect)).toEqual(["key"])
  expect(Object.keys(client.integration.oauth)).toEqual(["connect", "status", "complete", "cancel"])
  expect(Object.keys(client.integration.command)).toEqual(["connect", "status", "cancel"])
+  expect(Object.keys(client.websearch)).toEqual(["providers", "query"])
  expect(Object.keys(client.file)).toEqual(["read", "list", "find"])
  expect(Object.keys(client.vcs)).toEqual(["status", "diff"])
  expect(Object.keys(client.pty)).toEqual(["list", "create", "get", "update", "remove"])
@@ -48,6 +50,37 @@ test("exposes every standard HTTP API group", () => {
  expect(Object.keys(client.project)).toEqual(["list", "current", "directories"])
 })

+test("websearch.query uses the public HTTP contract", async () => {
+  let request: Request | undefined
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async (input, init) => {
+      request = input instanceof Request ? input : new Request(input, init)
+      return Response.json({
+        location: { directory: "/tmp/project", project: { id: "proj_test", directory: "/tmp/project" } },
+        data: {
+          providerID: "exa",
+          results: [{ url: "https://example.com", title: "Result", content: "result", time: {} }],
+        },
+      })
+    },
+  })
+
+  const result = await client.websearch.query({
+    query: "opencode",
+    providerID: "exa",
+    location: { directory: "/tmp/project" },
+  })
+
+  expect(result.data).toEqual({
+    providerID: "exa",
+    results: [{ url: "https://example.com", title: "Result", content: "result", time: {} }],
+  })
+  expect(request?.method).toBe("POST")
+  expect(request?.url).toBe("http://localhost:3000/api/websearch?location%5Bdirectory%5D=%2Ftmp%2Fproject")
+  expect(await request?.json()).toEqual({ query: "opencode", providerID: "exa" })
+})
+
 test("server.get uses the public HTTP contract", async () => {
  let request: Request | undefined
  const client = OpenCode.make({
@@ -0,0 +1,46 @@
+import {
+  Browser,
+  BrowserDriver,
+  BrowserDriverError,
+  OpenCode,
+  type BrowserAttachment,
+  type ChromiumController,
+  type ChromiumDriver,
+  type ChromiumPort,
+} from "@opencode-ai/client/node"
+
+const state: Browser.State = {
+  url: "about:blank",
+  title: "",
+  loading: false,
+  canGoBack: false,
+  canGoForward: false,
+  generation: 0,
+}
+
+const factory: BrowserDriver<{ readonly proxyURL: string }> = (context) => ({
+  resource: { proxyURL: context.proxy.url },
+  state: () => state,
+  subscribe: () => () => undefined,
+  execute: async (_command, options) => {
+    throw new BrowserDriverError(options.signal.aborted ? "aborted" : "internal", "Command unavailable")
+  },
+  dispose: () => undefined,
+})
+const driver = BrowserDriver.define(factory)
+declare const port: ChromiumPort<{ readonly page: true }>
+const chromium: ChromiumDriver<{ readonly page: true }> = BrowserDriver.chromium(() => port)
+
+declare const client: ReturnType<typeof OpenCode.make>
+const attachment: Promise<BrowserAttachment<{ readonly proxyURL: string }>> = client.browser.attach({
+  sessionID: "ses_type_fixture",
+  driver,
+})
+
+void attachment
+const chromiumAttachment: Promise<BrowserAttachment<ChromiumController<{ readonly page: true }>>> =
+  client.browser.attach({
+    sessionID: "ses_chromium_type_fixture",
+    driver: chromium,
+  })
+void chromiumAttachment
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["node-consumer.ts"]
+}
@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true
+  },
+  "include": ["node-consumer.ts"]
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
LukeParkerDev	850721c3e9	feat(desktop): compose V2 sidecar	2026-07-28 16:55:54 +10:00
LukeParkerDev	f147ff64f1	feat(client): add shared Chromium driver	2026-07-28 16:55:53 +10:00
LukeParkerDev	f814e4758c	feat(client): add browser host SDK	2026-07-28 16:55:53 +10:00
LukeParkerDev	57c939f188	feat(server): expose browser transport	2026-07-28 16:55:52 +10:00
LukeParkerDev	aaadc40fbc	test(core): align browser tool schemas	2026-07-28 16:55:50 +10:00
LukeParkerDev	6728681757	feat(core): add browser host authority	2026-07-28 15:35:22 +10:00
LukeParkerDev	4fd43bd45b	feat(protocol): add browser contracts	2026-07-28 15:34:55 +10:00
Luke Parker	396609b49b	fix(desktop): use channel database in local runs (#39209 )	2026-07-28 15:26:28 +10:00
Kit Langton	470e360942	test(core): align tool contract expectations (#39172 )	2026-07-28 00:48:29 +00:00
Aiden Cline	f15398efc3	feat(core): improve edit tool output (#39211 )	2026-07-27 19:11:04 -05:00
Kit Langton	4333a44e65	refactor(core): manage watcher lifecycle with RcMap (#39203 )	2026-07-27 20:01:17 -04:00
Kit Langton	8b4b0d67d7	feat(core): reload discovered plugins from source edits (#39174 )	2026-07-27 18:20:13 -04:00
Aiden Cline	9200e353bf	feat(core): improve edit tool guidance (#39198 )	2026-07-27 17:03:00 -05:00
Aiden Cline	31124312f6	fix(core): simplify tool schemas (#39184 )	2026-07-27 16:04:48 -05:00
James Long	4f622fa7cd	fix(tui): reference inferred hues in migrated themes (#39183 )	2026-07-27 17:02:35 -04:00
James Long	4e4cf9e25e	refactor(tui): extract event stream connection (#38872 )	2026-07-27 16:31:21 -04:00
Aiden Cline	6da2f3c38f	feat(core): improve read model output (#39146 )	2026-07-27 14:52:50 -05:00
Kit Langton	1b39d364bd	fix(core): align command reload pipeline and repair plugin fixture (#39171 )	2026-07-27 15:29:27 -04:00
Kit Langton	856c569458	feat(core): reload agents from config change feed (#39167 )	2026-07-27 15:14:08 -04:00
Kit Langton	92807d0bb9	feat(core): reload commands from config change feed (#39160 )	2026-07-27 15:02:40 -04:00
Kit Langton	713658c07b	test(core): add config and watcher test services (#39157 )	2026-07-27 14:32:38 -04:00
opencode-agent[bot]	f5700808c5	fix(tui): preserve subagent list position (#39156 ) Co-authored-by: Kit Langton <kit.langton@gmail.com>	2026-07-27 14:08:00 -04:00
Kit Langton	7eb51d0507	feat(core): diagnose prompt cache prefix changes (#39139 )	2026-07-27 13:44:02 -04:00
Kit Langton	02c37c401a	feat(core): expose config changes stream (#39131 )	2026-07-27 13:38:08 -04:00
opencode-agent[bot]	33e3d1ebca	fix(core): tolerate missing tool input schemas (#39130 ) Co-authored-by: Dax Raad <d@ironbay.co>	2026-07-27 11:21:47 -04:00
Kit Langton	1f2c59a1b6	fix(core): commit state before finalize publishes (#38983 )	2026-07-27 11:04:04 -04:00
Aiden Cline	65d2a4e00c	feat(core): improve read tool parity (#39126 )	2026-07-27 09:58:37 -05:00
Shoubhit Dash	7d4de3d9e4	fix(core): clarify web search provider prompt (#39123 )	2026-07-27 19:52:36 +05:30
Aiden Cline	9977ef0160	refactor(core): tag read outputs (#39122 )	2026-07-27 09:09:44 -05:00
Simon Klee	9a55d125f6	tui: render mini compaction boundaries (#39103 )	2026-07-27 14:19:03 +02:00
Simon Klee	766aaf448d	tui: add settings to command palette search (#39058 )	2026-07-27 10:45:35 +02:00
Simon Klee	f14d78afeb	tui: skip abort on mini session close (#39067 )	2026-07-27 10:42:37 +02:00
Dax Raad	0261f04b90	fix(core): handle oversized ripgrep matches	2026-07-27 03:17:08 -04:00
Aiden Cline	9b49e7bec9	test(core): implement catalog host model list (#39053 )	2026-07-26 23:32:33 -05:00
Aiden Cline	93cb113cef	fix(util): declare node tracing dependency (#39050 )	2026-07-26 23:12:36 -05:00
Aiden Cline	4216d35e4b	fix(server): declare schema dependency (#39043 )	2026-07-26 22:46:46 -05:00
Dax Raad	863645c671	test(core): update grep error assertion	2026-07-26 20:17:31 -04:00
Dax Raad	5592f5225b	fix(app): update remote sdk contracts	2026-07-26 20:16:58 -04:00
Dax Raad	8db7487c89	refactor(core): consolidate tool architecture	2026-07-26 20:16:58 -04:00
Aiden Cline	0fd73a2976	fix(core): align grep behavior and guidance (#38999 )	2026-07-26 17:29:27 -05:00
Dax Raad	80865407e0	refactor(sdk): remove local legacy package	2026-07-26 02:47:43 -04:00
Dax Raad	28f4284bd7	fix(www): canonicalize production routes	2026-07-26 02:39:12 -04:00
Aiden Cline	7affee529b	fix(core): harden grep search behavior (#38922 )	2026-07-25 23:23:53 -05:00
Aiden Cline	79c7e9446e	fix(core): clarify custom question answers (#38919 )	2026-07-25 23:00:26 -05:00
Shoubhit Dash	efb629a33a	feat(core): add pluggable web search (#35558 ) Co-authored-by: Dax Raad <d@ironbay.co>	2026-07-26 03:55:05 +00:00
Dax Raad	2ddc91a0e8	fix(tui): show shell working directory in prompt	2026-07-25 23:42:53 -04:00
Dax Raad	c7871e14d4	fix(www): remove deployment environment gate	2026-07-25 21:21:57 -04:00
Dax Raad	9840f63b12	chore(www): simplify worker routes	2026-07-25 21:17:25 -04:00
Dax Raad	56a9c0150a	fix(www): mark deploy script as module	2026-07-25 21:17:25 -04:00
Dax Raad	203a0613b8	feat(www): migrate docs to Blume	2026-07-25 21:17:25 -04:00
Aiden Cline	7d8f1bdab3	tweak(core): simplify skill tool description (#38900 )	2026-07-25 17:09:20 -05:00
Aiden Cline	9eea5bc925	fix(core): tweak glob tool description/parameters (#38899 )	2026-07-25 16:52:36 -05:00
Aiden Cline	f753103e82	fix(core): reject file glob roots (#38890 )	2026-07-25 14:43:18 -05:00
Aiden Cline	1e35d33ecb	fix(codemode): search nested namespaces (#38887 )	2026-07-25 14:17:49 -05:00
Aiden Cline	c5bf4edb10	fix(ai): preserve response message phases (#38777 )	2026-07-25 14:06:00 -05:00
Aiden Cline	cce8bb0e1c	fix(core): clarify empty Code Mode guidance (#38883 )	2026-07-25 13:20:16 -05:00
Dax Raad	02c66c5fc1	docs(core): fix OpenCode skill links	2026-07-25 14:08:29 -04:00
Aiden Cline	33390cc457	fix(core): keep execute tool cache stable (#38783 )	2026-07-25 13:01:05 -05:00
Kit Langton	b2afb35527	refactor(core): settle steps lock-free by joining tool fibers first (#38743 )	2026-07-25 13:43:17 -04:00
opencode-agent[bot]	828148909d	fix(tui): preserve workspace while reconnecting (#38788 )	2026-07-25 03:48:42 +00:00
opencode-agent[bot]	454145fe65	fix(tui): preserve workspace while reconnecting (#38788 )	2026-07-25 02:22:47 +00:00
Aiden Cline	1291dc1f11	fix(core): clarify code mode tool boundary (#38785 )	2026-07-24 20:49:55 -05:00
Aiden Cline	c7d7f61146	fix(ai): preserve Anthropic usage metadata (#38751 )	2026-07-24 16:23:51 -05:00
Aiden Cline	13b6845e7e	fix(core): scope MCP execute guidance to Code Mode (#38753 )	2026-07-24 16:02:57 -05:00
Aiden Cline	d1d97014b4	refactor(core): move static Code Mode guidance (#38746 )	2026-07-24 14:46:59 -05:00
Aiden Cline	b31747124b	fix(core): stream Code Mode tool progress (#38718 )	2026-07-24 14:46:46 -05:00
Aiden Cline	49bec25ae5	fix(ai): align Anthropic stream handling (#38733 )	2026-07-24 14:23:35 -05:00
Aiden Cline	d66d0cb904	fix(core): clarify Code Mode tool availability (#38745 )	2026-07-24 13:44:59 -05:00
Kit Langton	3193f3aa95	fix(tui): flag likely cache busts accurately (#38727 )	2026-07-24 18:35:13 +00:00
Aiden Cline	ee5460a152	fix(codemode): report interrupted tool calls (#38741 )	2026-07-24 13:32:54 -05:00
Kit Langton	b09a066fb5	fix(ai): report OpenAI cache writes (#38735 )	2026-07-24 18:26:30 +00:00
Aiden Cline	423fad730c	fix(core): authorize external glob paths (#38714 )	2026-07-24 13:24:23 -05:00
Kit Langton	5ae2d6d3f6	refactor(core): settle declined tool calls durably with typed reasons (#38734 )	2026-07-24 18:18:02 +00:00
Kit Langton	993f046dd9	fix(ai): layer prompt cache breakpoints (#38725 )	2026-07-24 18:02:35 +00:00
opencode-agent[bot]	9b640cf97d	test(core): remove flaky npm install test (#38729 ) Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>	2026-07-24 12:33:28 -05:00
Kit Langton	2200d100d0	refactor(core): name the unsettled-tool sweep scope and untangle hosted settlement (#38724 )	2026-07-24 13:32:14 -04:00
Kit Langton	68ef893818	fix(core): start all suspended sessions promptly (#38720 )	2026-07-24 16:58:50 +00:00
Kit Langton	7ab3dd04ad	refactor(core): unify tool fiber bookkeeping into one owned structure (#38719 )	2026-07-24 16:55:43 +00:00