test(cli): stabilize acp --help snapshot against random home path length

yargs wraps the \`[string] [default: "..."]\` clause based on the pre-normalized default value's character length, so a different random tmpdir width produces a different leading-whitespace count on the wrapped continuation line. After normalizing the path to \`<HOME>\` we were left with a one-space drift between runs. Collapse the wrap-dependent whitespace immediately before the clause so the snapshot is byte-stable regardless of home path length. Verified by deleting the .snap and regenerating across 3 runs.
refactor(test/lib): simplify cli-process helpers per Effect idioms
2026-05-18 21:22:59 -04:00 · 2026-05-18 21:11:29 -04:00 · 2026-05-18 21:11:29 -04:00 · 2026-05-18 21:10:06 -04:00 · 2026-05-18 21:10:06 -04:00 · 2026-05-18 20:57:42 -04:00
61 changed files with 5628 additions and 1328 deletions
@@ -29,7 +29,7 @@
    },
    "packages/app": {
      "name": "@opencode-ai/app",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@opencode-ai/core": "workspace:*",
@@ -84,7 +84,7 @@
    },
    "packages/console/app": {
      "name": "@opencode-ai/console-app",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@cloudflare/vite-plugin": "1.15.2",
        "@ibm/plex": "6.4.1",
@@ -119,7 +119,7 @@
    },
    "packages/console/core": {
      "name": "@opencode-ai/console-core",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@aws-sdk/client-sts": "3.782.0",
        "@jsx-email/render": "1.1.1",
@@ -146,7 +146,7 @@
    },
    "packages/console/function": {
      "name": "@opencode-ai/console-function",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@ai-sdk/anthropic": "3.0.64",
        "@ai-sdk/openai": "3.0.48",
@@ -168,7 +168,7 @@
    },
    "packages/console/mail": {
      "name": "@opencode-ai/console-mail",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@jsx-email/all": "2.2.3",
        "@jsx-email/cli": "1.4.3",
@@ -192,7 +192,7 @@
    },
    "packages/core": {
      "name": "@opencode-ai/core",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "bin": {
        "opencode": "./bin/opencode",
      },
@@ -253,7 +253,7 @@
    },
    "packages/desktop": {
      "name": "@opencode-ai/desktop",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "drizzle-orm": "catalog:",
        "effect": "catalog:",
@@ -307,7 +307,7 @@
    },
    "packages/enterprise": {
      "name": "@opencode-ai/enterprise",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@opencode-ai/core": "workspace:*",
        "@opencode-ai/ui": "workspace:*",
@@ -337,7 +337,7 @@
    },
    "packages/function": {
      "name": "@opencode-ai/function",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@octokit/auth-app": "8.0.1",
        "@octokit/rest": "catalog:",
@@ -353,7 +353,7 @@
    },
    "packages/http-recorder": {
      "name": "@opencode-ai/http-recorder",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@effect/platform-node": "catalog:",
        "effect": "catalog:",
@@ -366,7 +366,7 @@
    },
    "packages/llm": {
      "name": "@opencode-ai/llm",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@smithy/eventstream-codec": "4.2.14",
        "@smithy/util-utf8": "4.2.2",
@@ -384,7 +384,7 @@
    },
    "packages/opencode": {
      "name": "opencode",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "bin": {
        "opencode": "./bin/opencode",
      },
@@ -421,6 +421,7 @@
        "@octokit/graphql": "9.0.2",
        "@octokit/rest": "catalog:",
        "@openauthjs/openauth": "catalog:",
+        "@opencode-ai/llm": "workspace:*",
        "@opencode-ai/plugin": "workspace:*",
        "@opencode-ai/script": "workspace:*",
        "@opencode-ai/sdk": "workspace:*",
@@ -489,6 +490,7 @@
        "@babel/core": "7.28.4",
        "@octokit/webhooks-types": "7.6.1",
        "@opencode-ai/core": "workspace:*",
+        "@opencode-ai/http-recorder": "workspace:*",
        "@opencode-ai/script": "workspace:*",
        "@parcel/watcher-darwin-arm64": "2.5.1",
        "@parcel/watcher-darwin-x64": "2.5.1",
@@ -520,7 +522,7 @@
    },
    "packages/plugin": {
      "name": "@opencode-ai/plugin",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@opencode-ai/sdk": "workspace:*",
        "effect": "catalog:",
@@ -558,7 +560,7 @@
    },
    "packages/sdk/js": {
      "name": "@opencode-ai/sdk",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "cross-spawn": "catalog:",
      },
@@ -573,7 +575,7 @@
    },
    "packages/slack": {
      "name": "@opencode-ai/slack",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@opencode-ai/sdk": "workspace:*",
        "@slack/bolt": "^3.17.1",
@@ -608,7 +610,7 @@
    },
    "packages/ui": {
      "name": "@opencode-ai/ui",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@opencode-ai/core": "workspace:*",
@@ -657,7 +659,7 @@
    },
    "packages/web": {
      "name": "@opencode-ai/web",
-      "version": "1.15.4",
+      "version": "1.15.5",
      "dependencies": {
        "@astrojs/cloudflare": "12.6.3",
        "@astrojs/markdown-remark": "6.3.1",
@@ -1,8 +1,8 @@
 {
  "nodeModules": {
-    "x86_64-linux": "sha256-qAkjcbc1nJqOnCrNQ0bnsM4WG2ii5K1JWS9ohAYdjus=",
-    "aarch64-linux": "sha256-Nb+F0e3CvQv+uLzHzj9JKp5hV78mCnlSqFXzgIvgR24=",
-    "aarch64-darwin": "sha256-BIXALWWrjEZLUKZrY6l6+scjZmKFscFxX26TvWOvXGQ=",
-    "x86_64-darwin": "sha256-3uaFXl/n6je7AzIfsY1pvt3Ln/U1Oshx3z7ohuVPEs8="
+    "x86_64-linux": "sha256-FI1mX42vJuYdUDdWevlfHz+OcYkDn/I/HUbHE/jdQvs=",
+    "aarch64-linux": "sha256-3CQzzKnh/4Zf5vyn56yR5P3ULsW7K7Fr8/RQpekEJDk=",
+    "aarch64-darwin": "sha256-XPDVHMxlPpXlf43BRqNnwF809unk6iE8tvd0o92d0/w=",
+    "x86_64-darwin": "sha256-dFXTi13RSgL62lMsep1EoE/KSEPF7Oh31PVdxW1tkzg="
  }
 }
@@ -0,0 +1,314 @@
+const words = [
+  "alpha",
+  "bravo",
+  "charlie",
+  "delta",
+  "echo",
+  "foxtrot",
+  "golf",
+  "hotel",
+  "india",
+  "juliet",
+  "kilo",
+  "lima",
+  "metro",
+  "nova",
+  "orbit",
+  "pixel",
+  "quartz",
+  "river",
+  "signal",
+  "vector",
+]
+
+const sourceID = "ses_smoke_source"
+const targetID = "ses_smoke_target"
+const directory = "C:/OpenCode/SmokeProject"
+const projectID = "proj_smoke_timeline"
+const model = { providerID: "opencode", modelID: "claude-opus-4-6", variant: "max" }
+
+type MessageInfo = Record<string, unknown> & { id: string; role: "user" | "assistant" }
+type MessagePart = Record<string, unknown> & { id: string; type: string; text?: string; tool?: string }
+type Message = { info: MessageInfo; parts: MessagePart[] }
+
+function lorem(seed: number, length: number) {
+  let out = ""
+  let i = seed
+  while (out.length < length) {
+    const word = words[i % words.length]
+    out += (out ? " " : "") + word
+    if (i % 17 === 0) out += ".\n\n"
+    i += 7
+  }
+  return out.slice(0, length)
+}
+
+function id(prefix: string, value: number) {
+  return `${prefix}_smoke_${String(value).padStart(4, "0")}`
+}
+
+function userMessage(sessionID: string, index: number, textLength: number, diffs: unknown[] = []): Message {
+  const messageID = id("msg_user", index)
+  return {
+    info: {
+      id: messageID,
+      sessionID,
+      role: "user",
+      time: { created: 1700000000000 + index * 10_000 },
+      summary: { diffs },
+      agent: "build",
+      model,
+    },
+    parts: [
+      {
+        id: id("prt_user_text", index),
+        sessionID,
+        messageID,
+        type: "text",
+        text: lorem(index, textLength),
+      },
+    ],
+  }
+}
+
+function assistantMessage(sessionID: string, index: number, parentID: string, parts: MessagePart[]): Message {
+  const messageID = id("msg_assistant", index)
+  return {
+    info: {
+      id: messageID,
+      sessionID,
+      role: "assistant",
+      time: { created: 1700000000000 + index * 10_000 + 1_000, completed: 1700000000000 + index * 10_000 + 8_000 },
+      parentID,
+      modelID: model.modelID,
+      providerID: model.providerID,
+      mode: "build",
+      agent: "build",
+      path: { cwd: directory, root: directory },
+      cost: 0.01,
+      tokens: { input: 100, output: 200, reasoning: 0, cache: { read: 0, write: 0 } },
+      variant: "max",
+      finish: "stop",
+    },
+    parts: parts.map((part) => ({
+      ...part,
+      sessionID,
+      messageID,
+    })),
+  }
+}
+
+function textPart(index: number, partIndex: number, length: number): MessagePart {
+  return { id: id(`prt_text_${partIndex}`, index), type: "text", text: lorem(index * 13 + partIndex, length) }
+}
+
+function reasoningPart(index: number, partIndex: number, length: number): MessagePart {
+  return {
+    id: id(`prt_reasoning_${partIndex}`, index),
+    type: "reasoning",
+    text: lorem(index * 19 + partIndex, length),
+    time: { start: 1700000000000 + index * 10_000, end: 1700000000000 + index * 10_000 + 500 },
+  }
+}
+
+function toolPart(
+  index: number,
+  partIndex: number,
+  tool: string,
+  input: Record<string, unknown>,
+  outputLength = 160,
+): MessagePart {
+  const metadata =
+    tool === "apply_patch"
+      ? { files: [patchFile(index, "update"), patchFile(index + 1, index % 2 === 0 ? "add" : "delete")] }
+      : tool === "edit" || tool === "write"
+        ? {
+            filediff: fileDiff(String(input.filePath ?? `src/generated/file-${index}.ts`), index),
+            diff: patch(index, outputLength),
+            preview: patch(index + 1, 420),
+          }
+        : tool === "question"
+          ? { answers: [["Proceed"], ["Keep sample output"]] }
+          : {}
+  return {
+    id: id(`prt_tool_${tool}_${partIndex}`, index),
+    type: "tool",
+    callID: id("call", index * 10 + partIndex),
+    tool,
+    state: {
+      status: "completed",
+      input,
+      output: lorem(index * 23 + partIndex, outputLength),
+      title: tool === "bash" ? "Verify generated output" : input.filePath || input.path || input.pattern || "completed",
+      metadata,
+      time: { start: 1700000000000 + index * 10_000, end: 1700000000000 + index * 10_000 + 400 },
+    },
+  }
+}
+
+function patchFile(seed: number, type: "add" | "update" | "delete") {
+  return {
+    filePath: `src/generated/patch-${seed}.ts`,
+    relativePath: `src/generated/patch-${seed}.ts`,
+    type,
+    additions: (seed % 7) + 1,
+    deletions: type === "add" ? 0 : seed % 4,
+    patch: patch(seed, 520),
+    before: type === "add" ? undefined : code(seed, 18),
+    after: type === "delete" ? undefined : code(seed + 1, 24),
+  }
+}
+
+function fileDiff(file: string, seed: number) {
+  return {
+    file,
+    additions: (seed % 9) + 1,
+    deletions: seed % 4,
+    before: code(seed, 32),
+    after: code(seed + 1, 38),
+  }
+}
+
+function patch(seed: number, length: number) {
+  return `diff --git a/src/generated/file-${seed}.ts b/src/generated/file-${seed}.ts\n+${lorem(seed, length).replace(/\n/g, "\n+")}`
+}
+
+function code(seed: number, lines: number) {
+  return Array.from({ length: lines }, (_, index) => `export const value${index} = "${lorem(seed + index, 32)}"`).join(
+    "\n",
+  )
+}
+
+function turn(index: number): Message[] {
+  const diff = index % 9 === 0 ? [fileDiff(`src/generated/summary-${index}.ts`, index)] : []
+  const user = userMessage(targetID, index, 100 + (index % 4) * 80, diff)
+  const parts = [
+    ...(index % 5 === 0 ? [reasoningPart(index, 0, 420)] : []),
+    ...(index % 3 === 0
+      ? [
+          toolPart(index, 0, "read", { filePath: `src/generated/file-${index}.ts`, offset: 0, limit: 80 }, 220),
+          toolPart(index, 5, "glob", { path: directory, pattern: `**/*sample-${index}*.ts` }, 140),
+          toolPart(index, 1, "grep", { path: directory, pattern: `sample-${index}`, include: "*.ts" }, 180),
+          toolPart(index, 6, "list", { path: `src/generated/${index}` }, 120),
+        ]
+      : []),
+    textPart(index, 2, 160 + (index % 6) * 90),
+    ...(index % 4 === 0 ? [toolPart(index, 3, "edit", { filePath: `src/generated/file-${index}.ts` }, 700)] : []),
+    ...(index % 6 === 0
+      ? [toolPart(index, 7, "write", { filePath: `src/generated/write-${index}.ts`, content: code(index, 28) }, 560)]
+      : []),
+    ...(index % 8 === 0
+      ? [toolPart(index, 8, "apply_patch", { files: [`src/generated/patch-${index}.ts`] }, 620)]
+      : []),
+    ...(index % 7 === 0
+      ? [toolPart(index, 4, "bash", { command: "bun typecheck", description: "Verify generated output" }, 620)]
+      : []),
+    ...(index % 10 === 0 ? [toolPart(index, 9, "webfetch", { url: "https://example.com/docs/sample" }, 120)] : []),
+    ...(index % 11 === 0 ? [toolPart(index, 10, "websearch", { query: "sample movement notes" }, 240)] : []),
+    ...(index % 13 === 0
+      ? [
+          toolPart(
+            index,
+            11,
+            "question",
+            { questions: [{ question: "Use generated fixture?" }, { question: "Keep same row shape?" }] },
+            120,
+          ),
+        ]
+      : []),
+    ...(index % 17 === 0
+      ? [toolPart(index, 12, "task", { description: "Inspect generated fixture", subagent_type: "explore" }, 160)]
+      : []),
+  ]
+  return [user, assistantMessage(targetID, index, user.info.id, parts)]
+}
+
+const targetMessages = Array.from({ length: 72 }, (_, index) => turn(index)).flat()
+const sourceMessages = Array.from({ length: 12 }, (_, index) => [
+  userMessage(sourceID, index + 1000, 120),
+  assistantMessage(sourceID, index + 1000, id("msg_user", index + 1000), [textPart(index + 1000, 0, 240)]),
+]).flat()
+
+function renderable(part: MessagePart) {
+  if (part.type === "tool" && part.tool === "todowrite") return false
+  if (part.type === "text") return !!part.text.trim()
+  if (part.type === "reasoning") return !!part.text.trim()
+  return part.type !== "step-start" && part.type !== "step-finish" && part.type !== "patch"
+}
+
+function orderedParts(message: Message) {
+  return message.parts.slice().sort((a, b) => a.id.localeCompare(b.id))
+}
+
+export const fixture = {
+  directory,
+  project: {
+    id: projectID,
+    worktree: directory,
+    vcs: "git",
+    name: "smoke-project",
+    time: { created: 1700000000000, updated: 1700000000000 },
+    sandboxes: [],
+  },
+  provider: {
+    all: [
+      {
+        id: "opencode",
+        name: "OpenCode",
+        models: { "claude-opus-4-6": { id: "claude-opus-4-6", name: "Claude Opus 4.6", limit: { context: 200_000 } } },
+      },
+    ],
+    connected: ["opencode"],
+    default: { providerID: "opencode", modelID: "claude-opus-4-6" },
+  },
+  sessions: [
+    {
+      id: sourceID,
+      slug: "source",
+      projectID,
+      directory,
+      title: "Uncommitted changes inquiry",
+      version: "dev",
+      time: { created: 1700000000000, updated: 1700000000000 },
+    },
+    {
+      id: targetID,
+      slug: "target",
+      projectID,
+      directory,
+      title: "Example Game: sample jump movement & sample physics analysis",
+      version: "dev",
+      time: { created: 1700000001000, updated: 1700000001000 },
+    },
+  ],
+  sourceID,
+  targetID,
+  messages: { [sourceID]: sourceMessages, [targetID]: targetMessages },
+  expected: {
+    sourceTitle: "Uncommitted changes inquiry",
+    targetTitle: "Example Game: sample jump movement & sample physics analysis",
+    targetMessageIDs: targetMessages
+      .filter((message) => message.info.role === "user")
+      .map((message) => message.info.id),
+    targetPartIDs: targetMessages.flatMap((message) =>
+      orderedParts(message)
+        .filter(renderable)
+        .map((part) => part.id),
+    ),
+  },
+}
+
+export function pageMessages(sessionID: string, limit: number, before?: string) {
+  const messages = fixture.messages[sessionID as keyof typeof fixture.messages] ?? []
+  const end = before
+    ? Math.max(
+        0,
+        messages.findIndex((message) => message.info.id === before),
+      )
+    : messages.length
+  const start = Math.max(0, end - limit)
+  return {
+    items: messages.slice(start, end),
+    cursor: start > 0 ? messages[start]!.info.id : undefined,
+  }
+}
@@ -0,0 +1,412 @@
+import { expect, test, type Page } from "@playwright/test"
+import { fixture, pageMessages } from "./session-timeline.fixture"
+import { trackPageErrors, expectNoSmokeErrors } from "../utils/errors"
+import { mockOpenCodeServer } from "../utils/mock-server"
+
+const forbiddenText = ["Load details", "Show earlier steps"]
+
+type SmokeState = {
+  ids: string[]
+  visibleIds: string[]
+  messageIds: string[]
+  visibleMessageIds: string[]
+  topVisibleId?: string
+  signature: string
+  scrollTop: number
+  scrollHeight: number
+  clientHeight: number
+  errorToasts: string[]
+  forbiddenText: string[]
+}
+
+type SmokeWindow = Window & {
+  __timelineSmokeState?: () => SmokeState
+  __timelineSmokeErrorToasts?: string[]
+  __timelineSmokeForbiddenText?: string[]
+}
+
+test.describe("smoke: session timeline", () => {
+  test.setTimeout(240_000)
+
+  test("renders seeded timeline in order while paging through history", async ({ page }) => {
+    const errors = trackPageErrors(page)
+    await mockOpenCodeServer(page, {
+      sessions: fixture.sessions,
+      provider: fixture.provider,
+      directory: fixture.directory,
+      project: fixture.project,
+      pageMessages,
+    })
+    await configureSmokePage(page)
+
+    await openProject(page, "SmokeProject")
+    await navigateToSession(page, fixture.sourceID, fixture.expected.sourceTitle)
+    await expectSessionReady(page, "smoke-project")
+    await navigateToSession(page, fixture.targetID, fixture.expected.targetTitle)
+    const expectedPartIDs = fixture.expected.targetPartIDs
+    const expectedMessageIDs = fixture.expected.targetMessageIDs
+    await expectSessionTimelineReady(page, expectedPartIDs, expectedMessageIDs, errors)
+    await expectCanScrollToStart(page, expectedPartIDs, expectedMessageIDs, errors)
+  })
+})
+
+async function configureSmokePage(page: Page) {
+  await page.addInitScript(() => {
+    localStorage.setItem(
+      "settings.v3",
+      JSON.stringify({
+        general: {
+          editToolPartsExpanded: true,
+          shellToolPartsExpanded: true,
+          showReasoningSummaries: true,
+          showSessionProgressBar: true,
+        },
+      }),
+    )
+
+    const smoke = window as SmokeWindow
+    smoke.__timelineSmokeErrorToasts = []
+    smoke.__timelineSmokeForbiddenText = []
+    const partSelector = "[data-timeline-part-id], [data-timeline-part-ids]"
+    const idsOf = (el: HTMLElement) =>
+      [el.dataset.timelinePartId, ...(el.dataset.timelinePartIds?.split(",") ?? [])].filter((id): id is string => !!id)
+
+    smoke.__timelineSmokeState = () => {
+      const scroller = [...document.querySelectorAll<HTMLElement>(".scroll-view__viewport")].find((el) =>
+        el.querySelector("[data-timeline-row], [data-session-title]"),
+      )
+      if (!scroller) {
+        return {
+          ids: [],
+          visibleIds: [],
+          messageIds: [],
+          visibleMessageIds: [],
+          topVisibleId: undefined,
+          signature: "",
+          scrollTop: 0,
+          scrollHeight: 0,
+          clientHeight: 0,
+          errorToasts: smoke.__timelineSmokeErrorToasts ?? [],
+          forbiddenText: smoke.__timelineSmokeForbiddenText ?? [],
+        }
+      }
+
+      const ids: string[] = []
+      const visibleIds: string[] = []
+      const scrollerRect = scroller.getBoundingClientRect()
+      let topVisibleId: string | undefined
+      for (const el of scroller.querySelectorAll<HTMLElement>(partSelector)) {
+        const next = idsOf(el)
+        ids.push(...next)
+
+        const rect = el.getBoundingClientRect()
+        if (rect.bottom >= scrollerRect.top && rect.top <= scrollerRect.bottom) {
+          if (!topVisibleId) topVisibleId = next[0]
+          visibleIds.push(...next)
+        }
+      }
+
+      const messageIds: string[] = []
+      const visibleMessageIds: string[] = []
+      const rows = [...scroller.querySelectorAll<HTMLElement>("[data-message-id]")].map((el) => {
+        const rect = el.getBoundingClientRect()
+        const id = el.dataset.messageId
+        if (id) {
+          messageIds.push(id)
+          if (rect.bottom >= scrollerRect.top && rect.top <= scrollerRect.bottom) visibleMessageIds.push(id)
+        }
+        return {
+          id,
+          top: Math.round(rect.top),
+          bottom: Math.round(rect.bottom),
+        }
+      })
+      const signature = JSON.stringify({
+        top: Math.round(scroller.scrollTop),
+        height: Math.round(scroller.scrollHeight),
+        rows,
+        ids,
+      })
+
+      return {
+        ids,
+        visibleIds,
+        messageIds,
+        visibleMessageIds,
+        topVisibleId,
+        signature,
+        scrollTop: Math.round(scroller.scrollTop),
+        scrollHeight: Math.round(scroller.scrollHeight),
+        clientHeight: Math.round(scroller.clientHeight),
+        errorToasts: smoke.__timelineSmokeErrorToasts ?? [],
+        forbiddenText: smoke.__timelineSmokeForbiddenText ?? [],
+      }
+    }
+    let recordFrame: number | undefined
+    const record = () => {
+      for (const toast of document.querySelectorAll<HTMLElement>('[data-component="toast"][data-variant="error"]')) {
+        const text = toast.textContent?.trim()
+        if (text && !smoke.__timelineSmokeErrorToasts!.includes(text)) smoke.__timelineSmokeErrorToasts!.push(text)
+      }
+      const text = document.body?.textContent ?? ""
+      for (const value of ["Load details", "Show earlier steps"]) {
+        if (text.includes(value) && !smoke.__timelineSmokeForbiddenText!.includes(value)) {
+          smoke.__timelineSmokeForbiddenText!.push(value)
+        }
+      }
+    }
+    const start = () => {
+      const root = document.documentElement ?? document.body
+      if (!root) return
+      new MutationObserver(() => {
+        if (recordFrame) return
+        recordFrame = requestAnimationFrame(() => {
+          recordFrame = undefined
+          record()
+        })
+      }).observe(root, { childList: true, subtree: true })
+      record()
+    }
+    if (document.documentElement ?? document.body) start()
+    else document.addEventListener("DOMContentLoaded", start, { once: true })
+  })
+}
+
+async function expectCanScrollToStart(
+  page: Page,
+  expectedPartIDs: string[],
+  expectedMessageIDs: string[],
+  errors: string[],
+) {
+  await pointAtTimeline(page)
+  const seenParts = new Set<string>()
+  const seenMessages = new Set<string>()
+  const samples: TraversalSample[] = []
+  let current = await timelineState(page)
+  let unchangedAtTop = 0
+
+  for (let attempt = 0; attempt < 600; attempt++) {
+    collectSeen(current, seenParts, seenMessages)
+    samples.push(sampleTraversal(current, seenParts.size, seenMessages.size))
+    expectNoSmokeErrors(errors, current.errorToasts, current.forbiddenText)
+    expectOrderedIDs(expectedPartIDs, current.ids, "mounted part")
+    expectOrderedIDs(expectedPartIDs, current.visibleIds, "visible part")
+    expectOrderedIDs(expectedMessageIDs, unique(current.messageIds), "mounted message")
+    expectOrderedIDs(expectedMessageIDs, unique(current.visibleMessageIds), "visible message")
+
+    if (
+      current.scrollTop <= 1 &&
+      seenParts.size === expectedPartIDs.length &&
+      seenMessages.size === expectedMessageIDs.length
+    ) {
+      expectCompleteScroll(current, expectedPartIDs, expectedMessageIDs, seenParts, seenMessages, samples)
+      return
+    }
+
+    const before = current
+    const changed = await scrollTimelineUp(page, current)
+    current = await timelineState(page)
+    if (!changed && current.signature === before.signature && current.scrollTop <= 1) unchangedAtTop++
+    else unchangedAtTop = 0
+    if (unchangedAtTop >= 2) break
+  }
+
+  collectSeen(current, seenParts, seenMessages)
+  samples.push(sampleTraversal(current, seenParts.size, seenMessages.size))
+  expectCompleteScroll(current, expectedPartIDs, expectedMessageIDs, seenParts, seenMessages, samples)
+}
+
+async function timelineState(page: Page) {
+  return page.evaluate(
+    () =>
+      (window as SmokeWindow).__timelineSmokeState?.() ?? {
+        ids: [],
+        visibleIds: [],
+        messageIds: [],
+        visibleMessageIds: [],
+        topVisibleId: undefined,
+        signature: "",
+        scrollTop: 0,
+        scrollHeight: 0,
+        clientHeight: 0,
+        errorToasts: [],
+        forbiddenText: [],
+      },
+  )
+}
+
+function timelineScroller(page: Page) {
+  return page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
+}
+
+async function pointAtTimeline(page: Page) {
+  const box = await timelineScroller(page).boundingBox()
+  if (!box) throw new Error("Timeline scroller is not visible")
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2)
+}
+
+async function scrollTimelineUp(page: Page, before: SmokeState) {
+  return page.evaluate(
+    (prev) =>
+      new Promise<boolean>((resolve) => {
+        const scroller = [...document.querySelectorAll<HTMLElement>(".scroll-view__viewport")].find((el) =>
+          el.querySelector("[data-timeline-row], [data-session-title]"),
+        )
+        if (!scroller) {
+          resolve(false)
+          return
+        }
+
+        scroller.dispatchEvent(new WheelEvent("wheel", { bubbles: true, cancelable: true, deltaY: -1, deltaMode: 0 }))
+        scroller.scrollTop = Math.max(0, scroller.scrollTop - Math.max(80, Math.round(scroller.clientHeight * 0.45)))
+
+        const read = () => (window as SmokeWindow).__timelineSmokeState?.().signature ?? ""
+        let frames = 0
+        let stableFrames = 0
+        let last = ""
+        let changed = false
+        const check = () => {
+          const current = read()
+          if (current !== prev) changed = true
+          if (current === last) stableFrames++
+          else {
+            stableFrames = 0
+            last = current
+          }
+          if (changed && stableFrames >= 2) {
+            resolve(true)
+            return
+          }
+          frames++
+          if (frames >= 30) {
+            resolve(changed)
+            return
+          }
+          requestAnimationFrame(check)
+        }
+        requestAnimationFrame(check)
+      }),
+    before.signature,
+  )
+}
+
+function expectOrderedIDs(expected: string[], actual: string[], label: string) {
+  expect(actual.length, `${label} ids should not be empty`).toBeGreaterThan(0)
+  const actualSet = new Set(actual)
+  expect(actual, `${label} ids`).toEqual(expected.filter((id) => actualSet.has(id)))
+}
+
+function unique(values: string[]) {
+  return values.filter((value, index) => values.indexOf(value) === index)
+}
+
+function collectSeen(state: SmokeState, seenParts: Set<string>, seenMessages: Set<string>) {
+  for (const id of state.ids) seenParts.add(id)
+  for (const id of state.visibleIds) seenParts.add(id)
+  for (const id of state.messageIds) seenMessages.add(id)
+  for (const id of state.visibleMessageIds) seenMessages.add(id)
+}
+
+type TraversalSample = ReturnType<typeof sampleTraversal>
+
+function sampleTraversal(state: SmokeState, seenParts: number, seenMessages: number) {
+  return {
+    seenParts,
+    seenMessages,
+    mounted: state.ids.length,
+    visible: state.visibleIds.length,
+    mountedMessages: unique(state.messageIds).length,
+    visibleMessages: unique(state.visibleMessageIds).length,
+    top: state.scrollTop,
+    height: state.scrollHeight,
+    first: state.ids[0],
+    last: state.ids.at(-1),
+    topVisible: state.topVisibleId,
+    visibleFirst: state.visibleIds[0],
+    visibleLast: state.visibleIds.at(-1),
+  }
+}
+
+function sampleSummary(samples: TraversalSample[]) {
+  return samples
+    .filter((_, index) => index % Math.max(1, Math.floor(samples.length / 8)) === 0 || index === samples.length - 1)
+    .map(
+      (sample, index) =>
+        `${index}: seenParts=${sample.seenParts} seenMessages=${sample.seenMessages} mounted=${sample.mounted}/${sample.mountedMessages} visible=${sample.visible}/${sample.visibleMessages} top=${sample.top}/${sample.height} first=${sample.first} last=${sample.last} topVisible=${sample.topVisible} visible=${sample.visibleFirst}..${sample.visibleLast}`,
+    )
+    .join("\n")
+}
+
+async function waitForTimelineStable(page: Page) {
+  await page.waitForFunction(
+    () =>
+      new Promise<boolean>((resolve) => {
+        requestAnimationFrame(() => {
+          const a = (window as SmokeWindow).__timelineSmokeState?.().signature ?? ""
+          requestAnimationFrame(() => {
+            const b = (window as SmokeWindow).__timelineSmokeState?.().signature ?? ""
+            requestAnimationFrame(() =>
+              resolve(!!a && a === b && b === ((window as SmokeWindow).__timelineSmokeState?.().signature ?? "")),
+            )
+          })
+        })
+      }),
+  )
+}
+
+async function expectSessionTimelineReady(
+  page: Page,
+  expectedPartIDs: string[],
+  expectedMessageIDs: string[],
+  errors: string[],
+) {
+  await waitForTimelineStable(page)
+  for (const text of forbiddenText) await expect(page.getByText(text)).toHaveCount(0)
+  const currentState = await timelineState(page)
+  expectNoSmokeErrors(errors, currentState.errorToasts, currentState.forbiddenText)
+  expectOrderedIDs(expectedPartIDs, currentState.ids, "mounted part")
+  expectOrderedIDs(expectedPartIDs, currentState.visibleIds, "visible part")
+  expectOrderedIDs(expectedMessageIDs, unique(currentState.messageIds), "mounted message")
+  expectOrderedIDs(expectedMessageIDs, unique(currentState.visibleMessageIds), "visible message")
+}
+
+function expectCompleteScroll(
+  state: SmokeState,
+  expectedPartIDs: string[],
+  expectedMessageIDs: string[],
+  seenParts: Set<string>,
+  seenMessages: Set<string>,
+  samples: TraversalSample[],
+) {
+  expect(state.scrollTop, `timeline should reach the start\n${sampleSummary(samples)}`).toBeLessThanOrEqual(1)
+  expect(
+    expectedPartIDs.filter((id) => !seenParts.has(id)),
+    `missing visible timeline parts\n${sampleSummary(samples)}`,
+  ).toEqual([])
+  expect(
+    expectedMessageIDs.filter((id) => !seenMessages.has(id)),
+    `missing visible messages\n${sampleSummary(samples)}`,
+  ).toEqual([])
+  expect(new Set(expectedPartIDs).size).toBe(expectedPartIDs.length)
+  expect(new Set(expectedMessageIDs).size).toBe(expectedMessageIDs.length)
+  expect(expectedPartIDs.length).toBe(331)
+}
+
+async function openProject(page: Page, projectName: string) {
+  await page.goto("/")
+  await page.getByRole("button", { name: new RegExp(projectName, "i") }).click()
+}
+
+async function navigateToSession(page: Page, sessionId: string, expectedTitle: string) {
+  // Use evaluate to click to avoid strict visibility/animation issues during rapid e2e navigation
+  await page
+    .locator(`a[href*="${sessionId}"]`)
+    .first()
+    .evaluate((el) => (el as HTMLElement).click())
+  await expect(page.getByRole("heading", { name: expectedTitle })).toBeVisible()
+}
+
+async function expectSessionReady(page: Page, projectName: string) {
+  await expect(page.getByText(projectName).first()).toBeVisible()
+  await expect(page.getByText("Ask anything...")).toBeVisible()
+}
@@ -1,11 +0,0 @@
-import { test } from "@playwright/test"
-
-test(
-  "test something cool",
-  {
-    annotation: { type: "todo" },
-  },
-  async () => {
-    test.fixme()
-  },
-)
@@ -0,0 +1,18 @@
+import { expect, type Page } from "@playwright/test"
+
+export function trackPageErrors(page: Page) {
+  const errors: string[] = []
+  page.on("console", (message) => {
+    if (message.type() === "error") errors.push(message.text())
+  })
+  page.on("pageerror", (error) => errors.push(error.stack ?? error.message))
+  return errors
+}
+
+export function expectNoSmokeErrors(consoleErrors: string[], toastErrors: string[], forbiddenText: string[]) {
+  expect({ consoleErrors, toastErrors, forbiddenText }).toEqual({
+    consoleErrors: [],
+    toastErrors: [],
+    forbiddenText: [],
+  })
+}
@@ -0,0 +1,86 @@
+import type { Page, Route } from "@playwright/test"
+
+const emptyList = new Set([
+  "/skill",
+  "/command",
+  "/lsp",
+  "/formatter",
+  "/permission",
+  "/question",
+  "/vcs/status",
+  "/vcs/diff",
+])
+const emptyObject = new Set(["/global/config", "/config", "/provider/auth", "/mcp", "/session/status"])
+
+export interface MockServerConfig {
+  provider: unknown
+  directory: string
+  project: unknown
+  sessions: ({ id: string } & Record<string, unknown>)[]
+  pageMessages: (sessionId: string, limit: number, before?: string) => { items: unknown[]; cursor?: string }
+}
+
+export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
+  const staticRoutes: Record<string, unknown> = {
+    "/provider": config.provider,
+    "/path": {
+      state: config.directory,
+      config: config.directory,
+      worktree: config.directory,
+      directory: config.directory,
+      home: "C:/OpenCode",
+    },
+    "/project": [config.project],
+    "/project/current": config.project,
+    "/agent": [{ name: "build", mode: "primary" }],
+    "/vcs": { branch: "main", default_branch: "main" },
+    "/session": config.sessions,
+  }
+
+  await page.route("**/*", async (route) => {
+    const url = new URL(route.request().url())
+    const targetPort = process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"
+    if (url.port !== targetPort) return route.fallback()
+
+    const path = url.pathname
+    if (path === "/global/event" || path === "/event") return sse(route)
+    if (emptyObject.has(path)) return json(route, {})
+    if (emptyList.has(path)) return json(route, [])
+    if (path in staticRoutes) return json(route, staticRoutes[path])
+
+    const sessionMatch = path.match(/^\/session\/([^/]+)$/)
+    if (sessionMatch) {
+      const session = config.sessions.find((s) => s.id === sessionMatch[1])
+      return json(route, session ?? {})
+    }
+
+    if (/^\/session\/[^/]+\/(children|todo|diff)$/.test(path)) return json(route, [])
+
+    const messagesMatch = path.match(/^\/session\/([^/]+)\/message$/)
+    if (messagesMatch) {
+      const limit = Number(url.searchParams.get("limit") ?? 80)
+      const before = url.searchParams.get("before") ?? undefined
+      const pageData = config.pageMessages(messagesMatch[1], limit, before)
+      return json(route, pageData.items, pageData.cursor ? { "x-next-cursor": pageData.cursor } : undefined)
+    }
+
+    return json(route, {})
+  })
+}
+
+function json(route: Route, body: unknown, headers?: Record<string, string>) {
+  return route.fulfill({
+    status: 200,
+    contentType: "application/json",
+    headers: {
+      "access-control-allow-origin": "*",
+      "access-control-expose-headers": "x-next-cursor",
+      ...headers,
+    },
+    body: JSON.stringify(body ?? null),
+  })
+}
+
+function sse(route: Route) {
+  return route.fulfill({ status: 200, contentType: "text/event-stream", body: ": ok\n\n" })
+}
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/app",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "description": "",
  "type": "module",
  "exports": {
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/console-app",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode-ai/console-core",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/console-function",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "$schema": "https://json.schemastore.org/package.json",
  "private": true,
  "type": "module",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/console-mail",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "dependencies": {
    "@jsx-email/all": "2.2.3",
    "@jsx-email/cli": "1.4.3",
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "name": "@opencode-ai/core",
  "type": "module",
  "license": "MIT",
@@ -1,7 +1,7 @@
 {
  "name": "@opencode-ai/desktop",
  "private": true,
-  "version": "1.15.4",
+  "version": "1.15.5",
  "type": "module",
  "license": "MIT",
  "homepage": "https://opencode.ai",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/enterprise",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -1,7 +1,7 @@
 id = "opencode"
 name = "OpenCode"
 description = "The open source coding agent."
-version = "1.15.4"
+version = "1.15.5"
 schema_version = 1
 authors = ["Anomaly"]
 repository = "https://github.com/anomalyco/opencode"
@@ -11,26 +11,26 @@ name = "OpenCode"
 icon = "./icons/opencode.svg"

 [agent_servers.opencode.targets.darwin-aarch64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.4/opencode-darwin-arm64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.5/opencode-darwin-arm64.zip"
 cmd = "./opencode"
 args = ["acp"]

 [agent_servers.opencode.targets.darwin-x86_64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.4/opencode-darwin-x64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.5/opencode-darwin-x64.zip"
 cmd = "./opencode"
 args = ["acp"]

 [agent_servers.opencode.targets.linux-aarch64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.4/opencode-linux-arm64.tar.gz"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.5/opencode-linux-arm64.tar.gz"
 cmd = "./opencode"
 args = ["acp"]

 [agent_servers.opencode.targets.linux-x86_64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.4/opencode-linux-x64.tar.gz"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.5/opencode-linux-x64.tar.gz"
 cmd = "./opencode"
 args = ["acp"]

 [agent_servers.opencode.targets.windows-x86_64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.4/opencode-windows-x64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.15.5/opencode-windows-x64.zip"
 cmd = "./opencode.exe"
 args = ["acp"]
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/function",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "$schema": "https://json.schemastore.org/package.json",
  "private": true,
  "type": "module",
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "name": "@opencode-ai/http-recorder",
  "type": "module",
  "license": "MIT",
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "name": "@opencode-ai/llm",
  "type": "module",
  "license": "MIT",
@@ -91,6 +91,7 @@ export const TextDelta = Schema.Struct({
  type: Schema.tag("text-delta"),
  id: ContentBlockID,
  text: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.TextDelta" })
 export type TextDelta = Schema.Schema.Type<typeof TextDelta>

@@ -112,6 +113,7 @@ export const ReasoningDelta = Schema.Struct({
  type: Schema.tag("reasoning-delta"),
  id: ContentBlockID,
  text: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.ReasoningDelta" })
 export type ReasoningDelta = Schema.Schema.Type<typeof ReasoningDelta>

@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "name": "opencode",
  "type": "module",
  "license": "MIT",
@@ -39,8 +39,9 @@
  "devDependencies": {
    "@babel/core": "7.28.4",
    "@octokit/webhooks-types": "7.6.1",
-    "@opencode-ai/script": "workspace:*",
    "@opencode-ai/core": "workspace:*",
+    "@opencode-ai/http-recorder": "workspace:*",
+    "@opencode-ai/script": "workspace:*",
    "@parcel/watcher-darwin-arm64": "2.5.1",
    "@parcel/watcher-darwin-x64": "2.5.1",
    "@parcel/watcher-linux-arm64-glibc": "2.5.1",
@@ -101,6 +102,7 @@
    "@octokit/graphql": "9.0.2",
    "@octokit/rest": "catalog:",
    "@openauthjs/openauth": "catalog:",
+    "@opencode-ai/llm": "workspace:*",
    "@opencode-ai/plugin": "workspace:*",
    "@opencode-ai/script": "workspace:*",
    "@opencode-ai/sdk": "workspace:*",
@@ -1,12 +1,14 @@
 import { createMemo, createResource } from "solid-js"
 import { DialogSelect } from "@tui/ui/dialog-select"
 import { useDialog } from "@tui/ui/dialog"
+import { useProject } from "@tui/context/project"
 import { useSDK } from "@tui/context/sdk"
 import { createStore } from "solid-js/store"

 export function DialogTag(props: { onSelect?: (value: string) => void }) {
  const sdk = useSDK()
  const dialog = useDialog()
+  const project = useProject()

  const [store] = createStore({
    filter: "",
@@ -17,6 +19,7 @@ export function DialogTag(props: { onSelect?: (value: string) => void }) {
    async () => {
      const result = await sdk.client.find.files({
        query: store.filter,
+        workspace: project.workspace.current(),
      })
      if (result.error) return []
      const sliced = (result.data ?? []).slice(0, 5)
@@ -6,6 +6,7 @@ import { firstBy } from "remeda"
 import { createMemo, createResource, createEffect, onMount, onCleanup, Index, Show, createSignal } from "solid-js"
 import { createStore } from "solid-js/store"
 import { useEditorContext } from "@tui/context/editor"
+import { useProject } from "@tui/context/project"
 import { useSDK } from "@tui/context/sdk"
 import { useSync } from "@tui/context/sync"
 import { getScrollAcceleration } from "../../util/scroll"
@@ -85,6 +86,7 @@ export function Autocomplete(props: {
  const editor = useEditorContext()
  const sdk = useSDK()
  const sync = useSync()
+  const project = useProject()
  const command = useCommandPalette()
  const { theme } = useTheme()
  const dimensions = useTerminalDimensions()
@@ -382,6 +384,7 @@ export function Autocomplete(props: {
      // Get files from SDK
      const result = await sdk.client.find.files({
        query: baseQuery,
+        workspace: project.workspace.current(),
      })

      const options: AutocompleteOption[] = []
@@ -50,6 +50,7 @@ export class Service extends ConfigService.Service<Service>()("@opencode/Runtime
  experimentalIconDiscovery: enabledByExperimental("OPENCODE_EXPERIMENTAL_ICON_DISCOVERY"),
  outputTokenMax: positiveInteger("OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX"),
  bashDefaultTimeoutMs: positiveInteger("OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS"),
+  experimentalNativeLlm: enabledByExperimental("OPENCODE_EXPERIMENTAL_NATIVE_LLM"),
  client: Config.string("OPENCODE_CLIENT").pipe(Config.withDefault("cli")),
 }) {}

@@ -2,7 +2,10 @@ import { Provider } from "@/provider/provider"
 import * as Log from "@opencode-ai/core/util/log"
 import { Context, Effect, Layer, Record } from "effect"
 import * as Stream from "effect/Stream"
-import { streamText, wrapLanguageModel, type ModelMessage, type Tool, tool, jsonSchema } from "ai"
+import { streamText, wrapLanguageModel, type ModelMessage, type Tool, tool as aiTool, jsonSchema } from "ai"
+import type { LLMEvent } from "@opencode-ai/llm"
+import { LLMClient, RequestExecutor } from "@opencode-ai/llm/route"
+import type { LLMClientService } from "@opencode-ai/llm/route"
 import { mergeDeep } from "remeda"
 import { GitLabWorkflowLanguageModel } from "gitlab-ai-provider"
 import { ProviderTransform } from "@/provider/transform"
@@ -23,10 +26,11 @@ import { EffectBridge } from "@/effect/bridge"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import * as Option from "effect/Option"
 import * as OtelTracer from "@effect/opentelemetry/Tracer"
+import { LLMAISDK } from "./llm/ai-sdk"
+import { LLMNativeRuntime } from "./llm/native-runtime"

 const log = Log.create({ service: "llm" })
 export const OUTPUT_TOKEN_MAX = ProviderTransform.OUTPUT_TOKEN_MAX
-type Result = Awaited<ReturnType<typeof streamText>>

 // Avoid re-instantiating remeda's deep merge types in this hot LLM path; the runtime behavior is still mergeDeep.
 const mergeOptions = (target: Record<string, any>, source: Record<string, any> | undefined): Record<string, any> =>
@@ -51,10 +55,8 @@ export type StreamRequest = StreamInput & {
  abort: AbortSignal
 }

-export type Event = Result["fullStream"] extends AsyncIterable<infer T> ? T : never
-
 export interface Interface {
-  readonly stream: (input: StreamInput) => Stream.Stream<Event, unknown>
+  readonly stream: (input: StreamInput) => Stream.Stream<LLMEvent, unknown>
 }

 export class Service extends Context.Service<Service, Interface>()("@opencode/LLM") {}
@@ -62,7 +64,13 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/LL
 const live: Layer.Layer<
  Service,
  never,
-  Auth.Service | Config.Service | Provider.Service | Plugin.Service | Permission.Service | RuntimeFlags.Service
+  | Auth.Service
+  | Config.Service
+  | Provider.Service
+  | Plugin.Service
+  | Permission.Service
+  | LLMClientService
+  | RuntimeFlags.Service
 > = Layer.effect(
  Service,
  Effect.gen(function* () {
@@ -71,6 +79,7 @@ const live: Layer.Layer<
    const provider = yield* Provider.Service
    const plugin = yield* Plugin.Service
    const perm = yield* Permission.Service
+    const llmClient = yield* LLMClient.Service
    const flags = yield* RuntimeFlags.Service

    const run = Effect.fn("LLM.run")(function* (input: StreamRequest) {
@@ -202,7 +211,7 @@ const live: Layer.Layer<
        Object.keys(tools).length === 0 &&
        hasToolCalls(input.messages)
      ) {
-        tools["_noop"] = tool({
+        tools["_noop"] = aiTool({
          description: "Do not call this tool. It exists only for API compatibility and must never be invoked.",
          inputSchema: jsonSchema({
            type: "object",
@@ -322,86 +331,141 @@ const live: Layer.Layer<
        ? (yield* InstanceState.context).project.id
        : undefined

-      return streamText({
-        onError(error) {
-          l.error("stream error", {
-            error,
-          })
-        },
-        async experimental_repairToolCall(failed) {
-          const lower = failed.toolCall.toolName.toLowerCase()
-          if (lower !== failed.toolCall.toolName && sortedTools[lower]) {
-            l.info("repairing tool call", {
-              tool: failed.toolCall.toolName,
-              repaired: lower,
+      const requestHeaders = {
+        ...(input.model.providerID.startsWith("opencode")
+          ? {
+              ...(opencodeProjectID ? { "x-opencode-project": opencodeProjectID } : {}),
+              "x-opencode-session": input.sessionID,
+              "x-opencode-request": input.user.id,
+              "x-opencode-client": flags.client,
+              "User-Agent": `opencode/${InstallationVersion}`,
+            }
+          : {
+              "x-session-affinity": input.sessionID,
+              ...(input.parentSessionID ? { "x-parent-session-id": input.parentSessionID } : {}),
+              "User-Agent": `opencode/${InstallationVersion}`,
+            }),
+        ...input.model.headers,
+        ...headers,
+      }
+
+      if (flags.experimentalNativeLlm) {
+        const native = LLMNativeRuntime.stream({
+          model: input.model,
+          provider: item,
+          auth: info,
+          llmClient,
+          isOpenaiOauth,
+          system,
+          messages,
+          tools: sortedTools,
+          toolChoice: input.toolChoice,
+          temperature: params.temperature,
+          topP: params.topP,
+          topK: params.topK,
+          maxOutputTokens: params.maxOutputTokens,
+          providerOptions: params.options,
+          headers: requestHeaders,
+          abort: input.abort,
+        })
+        if (native.type === "supported") {
+          yield* Effect.logInfo("llm runtime selected").pipe(
+            Effect.annotateLogs({
+              "llm.runtime": "native",
+              "llm.provider": input.model.providerID,
+              "llm.model": input.model.id,
+            }),
+          )
+          return {
+            type: "native" as const,
+            stream: native.stream,
+          }
+        }
+        yield* Effect.logInfo("llm runtime selected").pipe(
+          Effect.annotateLogs({
+            "llm.runtime": "ai-sdk",
+            "llm.provider": input.model.providerID,
+            "llm.model": input.model.id,
+            "llm.native_unsupported_reason": native.reason,
+          }),
+        )
+        l.info("native runtime unavailable; falling back to ai-sdk", { reason: native.reason })
+      }
+
+      yield* Effect.logInfo("llm runtime selected").pipe(
+        Effect.annotateLogs({
+          "llm.runtime": "ai-sdk",
+          "llm.provider": input.model.providerID,
+          "llm.model": input.model.id,
+        }),
+      )
+      return {
+        type: "ai-sdk" as const,
+        result: streamText({
+          onError(error) {
+            l.error("stream error", {
+              error,
            })
+          },
+          async experimental_repairToolCall(failed) {
+            const lower = failed.toolCall.toolName.toLowerCase()
+            if (lower !== failed.toolCall.toolName && sortedTools[lower]) {
+              l.info("repairing tool call", {
+                tool: failed.toolCall.toolName,
+                repaired: lower,
+              })
+              return {
+                ...failed.toolCall,
+                toolName: lower,
+              }
+            }
            return {
              ...failed.toolCall,
-              toolName: lower,
-            }
-          }
-          return {
-            ...failed.toolCall,
-            input: JSON.stringify({
-              tool: failed.toolCall.toolName,
-              error: failed.error.message,
-            }),
-            toolName: "invalid",
-          }
-        },
-        temperature: params.temperature,
-        topP: params.topP,
-        topK: params.topK,
-        providerOptions: ProviderTransform.providerOptions(input.model, params.options),
-        activeTools: Object.keys(sortedTools).filter((x) => x !== "invalid"),
-        tools: sortedTools,
-        toolChoice: input.toolChoice,
-        maxOutputTokens: params.maxOutputTokens,
-        abortSignal: input.abort,
-        headers: {
-          ...(input.model.providerID.startsWith("opencode")
-            ? {
-                "x-opencode-project": opencodeProjectID,
-                "x-opencode-session": input.sessionID,
-                "x-opencode-request": input.user.id,
-                "x-opencode-client": flags.client,
-                "User-Agent": `opencode/${InstallationVersion}`,
-              }
-            : {
-                "x-session-affinity": input.sessionID,
-                ...(input.parentSessionID ? { "x-parent-session-id": input.parentSessionID } : {}),
-                "User-Agent": `opencode/${InstallationVersion}`,
+              input: JSON.stringify({
+                tool: failed.toolCall.toolName,
+                error: failed.error.message,
              }),
-          ...input.model.headers,
-          ...headers,
-        },
-        maxRetries: input.retries ?? 0,
-        messages,
-        model: wrapLanguageModel({
-          model: language,
-          middleware: [
-            {
-              specificationVersion: "v3" as const,
-              async transformParams(args) {
-                if (args.type === "stream") {
-                  // @ts-expect-error
-                  args.params.prompt = ProviderTransform.message(args.params.prompt, input.model, options)
-                }
-                return args.params
-              },
-            },
-          ],
-        }),
-        experimental_telemetry: {
-          isEnabled: cfg.experimental?.openTelemetry,
-          functionId: "session.llm",
-          tracer: telemetryTracer,
-          metadata: {
-            userId: cfg.username ?? "unknown",
-            sessionId: input.sessionID,
+              toolName: "invalid",
+            }
          },
-        },
-      })
+          temperature: params.temperature,
+          topP: params.topP,
+          topK: params.topK,
+          providerOptions: ProviderTransform.providerOptions(input.model, params.options),
+          activeTools: Object.keys(sortedTools).filter((x) => x !== "invalid"),
+          tools: sortedTools,
+          toolChoice: input.toolChoice,
+          maxOutputTokens: params.maxOutputTokens,
+          abortSignal: input.abort,
+          headers: requestHeaders,
+          maxRetries: input.retries ?? 0,
+          messages,
+          model: wrapLanguageModel({
+            model: language,
+            middleware: [
+              {
+                specificationVersion: "v3" as const,
+                async transformParams(args) {
+                  if (args.type === "stream") {
+                    // @ts-expect-error
+                    args.params.prompt = ProviderTransform.message(args.params.prompt, input.model, options)
+                  }
+                  return args.params
+                },
+              },
+            ],
+          }),
+          experimental_telemetry: {
+            isEnabled: cfg.experimental?.openTelemetry,
+            functionId: "session.llm",
+            tracer: telemetryTracer,
+            metadata: {
+              userId: cfg.username ?? "unknown",
+              sessionId: input.sessionID,
+            },
+          },
+        }),
+      }
    })

    const stream: Interface["stream"] = (input) =>
@@ -415,7 +479,15 @@ const live: Layer.Layer<

            const result = yield* run({ ...input, abort: ctrl.signal })

-            return Stream.fromAsyncIterable(result.fullStream, (e) => (e instanceof Error ? e : new Error(String(e))))
+            if (result.type === "native") return result.stream
+
+            const state = LLMAISDK.adapterState()
+            return Stream.fromAsyncIterable(result.result.fullStream, (e) =>
+              e instanceof Error ? e : new Error(String(e)),
+            ).pipe(
+              Stream.mapEffect((event) => LLMAISDK.toLLMEvents(state, event)),
+              Stream.flatMap((events) => Stream.fromIterable(events)),
+            )
          }),
        ),
      )
@@ -432,6 +504,7 @@ export const defaultLayer = Layer.suspend(() =>
    Layer.provide(Config.defaultLayer),
    Layer.provide(Provider.defaultLayer),
    Layer.provide(Plugin.defaultLayer),
+    Layer.provide(LLMClient.layer.pipe(Layer.provide(RequestExecutor.defaultLayer))),
    Layer.provide(RuntimeFlags.defaultLayer),
  ),
 )
@@ -0,0 +1,67 @@
+# Session LLM Runtime Boundaries
+
+`../llm.ts` is the opencode session LLM service. It owns opencode concerns: auth, config, model/provider resolution, plugins, permissions, telemetry headers, and runtime selection.
+
+This folder contains adapters behind that service boundary:
+
+- `ai-sdk.ts` converts AI SDK `fullStream` parts into `@opencode-ai/llm` `LLMEvent`s. This is the default runtime path.
+- `native-request.ts` converts opencode's normalized session input into a native `@opencode-ai/llm` `LLMRequest`. It does not execute requests.
+- `native-runtime.ts` is the opt-in native runtime adapter. It decides whether a selected model is supported, builds the native request, bridges opencode tools into native executable tools, and delegates transport to `LLMClient` / `RequestExecutor`.
+
+## Runtime selection
+
+Both runtimes converge on the same `LLMEvent` stream consumed by the session processor. The gate is per-request: a single session can route some calls through native and fall back for others.
+
+```txt
+                             ╭───────────────────╮
+╭───────────────────────────▶│ session processor │
+│                            ╰─────────┬─────────╯
+│                                      │
+│                                      │
+│                                      │
+│                                      ▼
+│                         ╭─────────────────────────╮
+│                         │ LLM.Service (../llm.ts) │
+│                         ╰────────────┬────────────╯
+│                                      │
+│                                      │
+│                                      │
+│                                      ▼
+│                                ╭───────────╮
+│                              ╭─╯           ╰─╮
+│                              │  native gate  │
+│                              ╰─╮           ╭─╯
+│                                ╰─────┬─────╯
+│                                      │
+│                     ╭────── no ──────┴─────── yes ────────╮
+│                     │                                     │
+│                     ▼                                     ▼
+│       ╭───────────────────────────╮             ╭───────────────────╮
+│       │          AI SDK           │             │ native-runtime.ts │
+│       │ streamText / generateText │             ╰────────┬──────────╯
+│       ╰─────────────┬─────────────╯                      │
+│                     │                                    │
+│                 ╭───╯                                    │
+│                 │                                        │
+│                 ▼                                        ▼
+│     ╭───────────────────────╮             ╭────────────────────────────╮
+│     │       ai-sdk.ts       │             │     native-request.ts      │
+│     │ fullStream → LLMEvent │             │ session input → LLMRequest │
+│     ╰──────────┬────────────╯             ╰──────────────┬─────────────╯
+│                │                                         │
+│                │                                     ╭───╯
+│                │                                     │
+│                ▼                                     ▼
+│       ╭─────────────────╮             ╭─────────────────────────────╮
+╰───────┤ LLMEvent stream │◀────────────┤ LLMClient · RequestExecutor │
+        ╰─────────────────╯             ╰─────────────────────────────╯
+```
+
+`native-runtime.ts` evaluates the gate and either bridges into `@opencode-ai/llm` or returns control so `llm.ts` can take the AI SDK path. Tool execution stays opencode-owned in both branches; only request lowering and transport differ.
+
+Safety boundary:
+
+- AI SDK remains the default.
+- `OPENCODE_EXPERIMENTAL_NATIVE_LLM=true` or the umbrella `OPENCODE_EXPERIMENTAL=true` opts in. Native is not a global replacement.
+- Native execution currently runs only for OpenAI-compatible Responses models exposed through `@ai-sdk/openai`: direct `openai` API-key auth and console-managed `opencode`/Zen API-key config.
+- Unsupported providers, OpenAI OAuth, and missing API-key cases fall back to AI SDK.
@@ -0,0 +1,254 @@
+import { FinishReason, LLMEvent, ProviderMetadata, ToolResultValue } from "@opencode-ai/llm"
+import { Effect, Schema } from "effect"
+import { type streamText } from "ai"
+import { errorMessage } from "@/util/error"
+
+type Result = Awaited<ReturnType<typeof streamText>>
+type AISDKEvent = Result["fullStream"] extends AsyncIterable<infer T> ? T : never
+
+export function adapterState() {
+  return {
+    step: 0,
+    text: 0,
+    reasoning: 0,
+    currentTextID: undefined as string | undefined,
+    currentReasoningID: undefined as string | undefined,
+    toolNames: {} as Record<string, string>,
+  }
+}
+
+function finishReason(value: string | undefined): FinishReason {
+  return Schema.is(FinishReason)(value) ? value : "unknown"
+}
+
+function providerMetadata(value: unknown): ProviderMetadata | undefined {
+  if (value == null) return undefined
+  return Schema.is(ProviderMetadata)(value) ? value : undefined
+}
+
+function usage(value: unknown) {
+  if (!value || typeof value !== "object") return undefined
+  const item = value as {
+    inputTokens?: number
+    outputTokens?: number
+    totalTokens?: number
+    reasoningTokens?: number
+    cachedInputTokens?: number
+    inputTokenDetails?: { cacheReadTokens?: number; cacheWriteTokens?: number }
+    outputTokenDetails?: { reasoningTokens?: number }
+  }
+  const entries = Object.entries({
+    inputTokens: item.inputTokens,
+    outputTokens: item.outputTokens,
+    totalTokens: item.totalTokens,
+    reasoningTokens: item.outputTokenDetails?.reasoningTokens ?? item.reasoningTokens,
+    cacheReadInputTokens: item.inputTokenDetails?.cacheReadTokens ?? item.cachedInputTokens,
+    cacheWriteInputTokens: item.inputTokenDetails?.cacheWriteTokens,
+  }).filter((entry) => entry[1] !== undefined)
+  return entries.length === 0 ? undefined : Object.fromEntries(entries)
+}
+
+function currentTextID(state: ReturnType<typeof adapterState>, id: string | undefined) {
+  state.currentTextID = id ?? state.currentTextID ?? `text-${state.text++}`
+  return state.currentTextID
+}
+
+function currentReasoningID(state: ReturnType<typeof adapterState>, id: string | undefined) {
+  state.currentReasoningID = id ?? state.currentReasoningID ?? `reasoning-${state.reasoning++}`
+  return state.currentReasoningID
+}
+
+export function toLLMEvents(
+  state: ReturnType<typeof adapterState>,
+  event: AISDKEvent,
+): Effect.Effect<ReadonlyArray<LLMEvent>, unknown> {
+  switch (event.type) {
+    case "start":
+      return Effect.succeed([])
+
+    case "start-step":
+      return Effect.succeed([LLMEvent.stepStart({ index: state.step })])
+
+    case "finish-step":
+      return Effect.sync(() => [
+        LLMEvent.stepFinish({
+          index: state.step++,
+          reason: finishReason(event.finishReason),
+          usage: usage(event.usage),
+          providerMetadata: providerMetadata(event.providerMetadata),
+        }),
+      ])
+
+    case "finish":
+      return Effect.sync(() => {
+        const events = [
+          LLMEvent.finish({
+            reason: finishReason(event.finishReason),
+            usage: usage(event.totalUsage),
+            providerMetadata: "providerMetadata" in event ? providerMetadata(event.providerMetadata) : undefined,
+          }),
+        ]
+        // Reset so the adapter can be reused for a follow-up stream without leaking
+        // counters or block IDs. adapterState() is the single source of truth for shape.
+        Object.assign(state, adapterState())
+        return events
+      })
+
+    case "text-start":
+      return Effect.sync(() => {
+        state.currentTextID = currentTextID(state, event.id)
+        return [
+          LLMEvent.textStart({
+            id: state.currentTextID,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "text-delta":
+      return Effect.succeed([
+        LLMEvent.textDelta({
+          id: currentTextID(state, event.id),
+          text: event.text,
+          providerMetadata: providerMetadata(event.providerMetadata),
+        }),
+      ])
+
+    case "text-end":
+      return Effect.sync(() => {
+        const id = currentTextID(state, event.id)
+        state.currentTextID = undefined
+        return [
+          LLMEvent.textEnd({
+            id,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "reasoning-start":
+      return Effect.sync(() => {
+        state.currentReasoningID = currentReasoningID(state, event.id)
+        return [
+          LLMEvent.reasoningStart({
+            id: state.currentReasoningID,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "reasoning-delta":
+      return Effect.succeed([
+        LLMEvent.reasoningDelta({
+          id: currentReasoningID(state, event.id),
+          text: event.text,
+          providerMetadata: providerMetadata(event.providerMetadata),
+        }),
+      ])
+
+    case "reasoning-end":
+      return Effect.sync(() => {
+        const id = currentReasoningID(state, event.id)
+        state.currentReasoningID = undefined
+        return [
+          LLMEvent.reasoningEnd({
+            id,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "tool-input-start":
+      return Effect.sync(() => {
+        state.toolNames[event.id] = event.toolName
+        return [
+          LLMEvent.toolInputStart({
+            id: event.id,
+            name: event.toolName,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "tool-input-delta":
+      return Effect.succeed([
+        LLMEvent.toolInputDelta({
+          id: event.id,
+          name: state.toolNames[event.id] ?? "unknown",
+          text: event.delta ?? "",
+        }),
+      ])
+
+    case "tool-input-end":
+      return Effect.succeed([
+        LLMEvent.toolInputEnd({
+          id: event.id,
+          name: state.toolNames[event.id] ?? "unknown",
+          providerMetadata: providerMetadata(event.providerMetadata),
+        }),
+      ])
+
+    case "tool-call":
+      return Effect.sync(() => {
+        state.toolNames[event.toolCallId] = event.toolName
+        return [
+          LLMEvent.toolCall({
+            id: event.toolCallId,
+            name: event.toolName,
+            input: event.input,
+            providerExecuted: "providerExecuted" in event ? event.providerExecuted : undefined,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "tool-result":
+      return Effect.sync(() => {
+        const name = state.toolNames[event.toolCallId] ?? "unknown"
+        delete state.toolNames[event.toolCallId]
+        return [
+          LLMEvent.toolResult({
+            id: event.toolCallId,
+            name,
+            result: ToolResultValue.make(event.output),
+            providerExecuted: "providerExecuted" in event ? event.providerExecuted : undefined,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "tool-error":
+      return Effect.sync(() => {
+        const name = state.toolNames[event.toolCallId] ?? ("toolName" in event ? event.toolName : "unknown")
+        delete state.toolNames[event.toolCallId]
+        return [
+          LLMEvent.toolError({
+            id: event.toolCallId,
+            name,
+            message: errorMessage(event.error),
+            error: event.error,
+            providerMetadata: providerMetadata(event.providerMetadata),
+          }),
+        ]
+      })
+
+    case "error":
+      return Effect.fail(event.error)
+
+    case "abort":
+    case "source":
+    case "file":
+    case "raw":
+    case "tool-output-denied":
+    case "tool-approval-request":
+      return Effect.succeed([])
+
+    default: {
+      const _exhaustive: never = event
+      void _exhaustive
+      return Effect.succeed([])
+    }
+  }
+}
+
+export * as LLMAISDK from "./ai-sdk"
@@ -0,0 +1,188 @@
+import type { JsonSchema, LLMRequest, ProviderMetadata } from "@opencode-ai/llm"
+import { LLM, Message, SystemPart, ToolCallPart, ToolDefinition, ToolResultPart } from "@opencode-ai/llm"
+import "@opencode-ai/llm/providers"
+import type { ModelMessage } from "ai"
+import type { Provider } from "@/provider/provider"
+import { isRecord } from "@/util/record"
+
+type ToolInput = {
+  readonly description?: string
+  readonly inputSchema?: unknown
+}
+
+export type RequestInput = {
+  readonly model: Provider.Model
+  readonly apiKey?: string
+  readonly baseURL?: string
+  readonly system?: readonly string[]
+  readonly messages: readonly ModelMessage[]
+  readonly tools?: Record<string, ToolInput>
+  readonly toolChoice?: "auto" | "required" | "none"
+  readonly temperature?: number
+  readonly topP?: number
+  readonly topK?: number
+  readonly maxOutputTokens?: number
+  readonly providerOptions?: LLMRequest["providerOptions"]
+  readonly headers?: Record<string, string>
+}
+
+const DEFAULT_BASE_URL: Record<string, string> = {
+  "@ai-sdk/openai": "https://api.openai.com/v1",
+  "@ai-sdk/anthropic": "https://api.anthropic.com/v1",
+  "@ai-sdk/google": "https://generativelanguage.googleapis.com/v1beta",
+  "@ai-sdk/amazon-bedrock": "https://bedrock-runtime.us-east-1.amazonaws.com",
+  "@openrouter/ai-sdk-provider": "https://openrouter.ai/api/v1",
+}
+
+const ROUTE: Record<string, string> = {
+  "@ai-sdk/openai": "openai-responses",
+  "@ai-sdk/azure": "azure-openai-responses",
+  "@ai-sdk/anthropic": "anthropic-messages",
+  "@ai-sdk/google": "gemini",
+  "@ai-sdk/amazon-bedrock": "bedrock-converse",
+  "@ai-sdk/openai-compatible": "openai-compatible-chat",
+  "@openrouter/ai-sdk-provider": "openrouter",
+}
+
+const providerMetadata = (value: unknown): ProviderMetadata | undefined => {
+  if (!isRecord(value)) return undefined
+  const result = Object.fromEntries(
+    Object.entries(value).filter((entry): entry is [string, Record<string, unknown>] => isRecord(entry[1])),
+  )
+  return Object.keys(result).length === 0 ? undefined : result
+}
+
+const textPart = (part: Record<string, unknown>) => ({
+  type: "text" as const,
+  text: typeof part.text === "string" ? part.text : "",
+  providerMetadata: providerMetadata(part.providerOptions),
+})
+
+const mediaPart = (part: Record<string, unknown>) => {
+  if (typeof part.data !== "string" && !(part.data instanceof Uint8Array))
+    throw new Error("Native LLM request adapter only supports file parts with string or Uint8Array data")
+  return {
+    type: "media" as const,
+    mediaType: typeof part.mediaType === "string" ? part.mediaType : "application/octet-stream",
+    data: part.data,
+    filename: typeof part.filename === "string" ? part.filename : undefined,
+  }
+}
+
+const toolResult = (part: Record<string, unknown>) => {
+  const output = isRecord(part.output) ? part.output : { type: "json", value: part.output }
+  const type = output.type === "text" ? "text" : output.type === "error-text" ? "error" : "json"
+  return ToolResultPart.make({
+    id: typeof part.toolCallId === "string" ? part.toolCallId : "",
+    name: typeof part.toolName === "string" ? part.toolName : "",
+    result: "value" in output ? output.value : output,
+    resultType: type,
+    providerExecuted: typeof part.providerExecuted === "boolean" ? part.providerExecuted : undefined,
+    providerMetadata: providerMetadata(part.providerOptions),
+  })
+}
+
+const contentPart = (part: unknown) => {
+  if (!isRecord(part)) throw new Error("Native LLM request adapter only supports object content parts")
+  if (part.type === "text") return textPart(part)
+  if (part.type === "file") return mediaPart(part)
+  if (part.type === "reasoning")
+    return {
+      type: "reasoning" as const,
+      text: typeof part.text === "string" ? part.text : "",
+      providerMetadata: providerMetadata(part.providerOptions),
+    }
+  if (part.type === "tool-call")
+    return ToolCallPart.make({
+      id: typeof part.toolCallId === "string" ? part.toolCallId : "",
+      name: typeof part.toolName === "string" ? part.toolName : "",
+      input: part.input,
+      providerExecuted: typeof part.providerExecuted === "boolean" ? part.providerExecuted : undefined,
+      providerMetadata: providerMetadata(part.providerOptions),
+    })
+  if (part.type === "tool-result") return toolResult(part)
+  throw new Error(`Native LLM request adapter does not support ${String(part.type)} content parts`)
+}
+
+const content = (value: ModelMessage["content"]) =>
+  typeof value === "string" ? [{ type: "text" as const, text: value }] : value.map(contentPart)
+
+const messages = (input: readonly ModelMessage[]) => {
+  const system = input.flatMap((message) => (message.role === "system" ? [SystemPart.make(message.content)] : []))
+  const messages = input.flatMap((message) => {
+    if (message.role === "system") return []
+    return [
+      Message.make({
+        role: message.role,
+        content: content(message.content),
+        native: isRecord(message.providerOptions) ? { providerOptions: message.providerOptions } : undefined,
+      }),
+    ]
+  })
+  return { system, messages }
+}
+
+const schema = (value: unknown): JsonSchema => {
+  if (!isRecord(value)) return { type: "object", properties: {} }
+  if (isRecord(value.jsonSchema)) return value.jsonSchema
+  return value
+}
+
+const tools = (input: Record<string, ToolInput> | undefined): ToolDefinition[] =>
+  Object.entries(input ?? {}).map(([name, item]) =>
+    ToolDefinition.make({
+      name,
+      description: item.description ?? "",
+      inputSchema: schema(item.inputSchema),
+    }),
+  )
+
+const generation = (input: RequestInput) => {
+  const result = {
+    temperature: input.temperature,
+    topP: input.topP,
+    topK: input.topK,
+    maxTokens: input.maxOutputTokens,
+  }
+  return Object.values(result).some((value) => value !== undefined) ? result : undefined
+}
+
+const baseURL = (model: Provider.Model) => {
+  if (model.api.url) return model.api.url
+  const fallback = DEFAULT_BASE_URL[model.api.npm]
+  if (fallback) return fallback
+  throw new Error(`Native LLM request adapter requires a base URL for ${model.providerID}/${model.id}`)
+}
+
+export const model = (input: Provider.Model | RequestInput, headers?: Record<string, string>) => {
+  const model = "model" in input ? input.model : input
+  const route = ROUTE[model.api.npm]
+  if (!route) throw new Error(`Native LLM request adapter does not support provider package ${model.api.npm}`)
+  return LLM.model({
+    id: model.api.id,
+    provider: model.providerID,
+    route,
+    baseURL: "model" in input && input.baseURL ? input.baseURL : baseURL(model),
+    apiKey: "model" in input ? input.apiKey : undefined,
+    headers: Object.keys({ ...model.headers, ...headers }).length === 0 ? undefined : { ...model.headers, ...headers },
+    limits: {
+      context: model.limit.context,
+      output: model.limit.output,
+    },
+  })
+}
+
+export const request = (input: RequestInput) => {
+  const converted = messages(input.messages)
+  return LLM.request({
+    model: model(input, input.headers),
+    system: [...(input.system ?? []).map(SystemPart.make), ...converted.system],
+    messages: converted.messages,
+    tools: tools(input.tools),
+    toolChoice: input.toolChoice,
+    generation: generation(input),
+    providerOptions: input.providerOptions,
+  })
+}
+
+export * as LLMNative from "./native-request"
@@ -0,0 +1,119 @@
+import type { Auth } from "@/auth"
+import type { Provider } from "@/provider/provider"
+import { ProviderTransform } from "@/provider/transform"
+import { errorMessage } from "@/util/error"
+import { isRecord } from "@/util/record"
+import { asSchema, type ModelMessage, type Tool } from "ai"
+import { Effect } from "effect"
+import * as Stream from "effect/Stream"
+import { tool as nativeTool, ToolFailure, type JsonSchema, type LLMEvent } from "@opencode-ai/llm"
+import type { LLMClientShape } from "@opencode-ai/llm/route"
+import { LLMNative } from "./native-request"
+
+export type RuntimeStatus =
+  | { readonly type: "supported"; readonly apiKey: string; readonly baseURL?: string }
+  | { readonly type: "unsupported"; readonly reason: string }
+export type StreamResult =
+  | { readonly type: "supported"; readonly stream: Stream.Stream<LLMEvent, unknown> }
+  | { readonly type: "unsupported"; readonly reason: string }
+
+type StreamInput = {
+  readonly model: Provider.Model
+  readonly provider: Provider.Info
+  readonly auth: Auth.Info | undefined
+  readonly llmClient: LLMClientShape
+  readonly isOpenaiOauth: boolean
+  readonly system: string[]
+  readonly messages: ModelMessage[]
+  readonly tools: Record<string, Tool>
+  readonly toolChoice?: "auto" | "required" | "none"
+  readonly temperature?: number
+  readonly topP?: number
+  readonly topK?: number
+  readonly maxOutputTokens?: number
+  readonly providerOptions?: Record<string, any>
+  readonly headers: Record<string, string>
+  readonly abort: AbortSignal
+}
+
+export function status(input: Pick<StreamInput, "model" | "provider" | "auth">): RuntimeStatus {
+  if (input.model.providerID !== "openai" && !input.model.providerID.startsWith("opencode"))
+    return { type: "unsupported", reason: "provider is not openai or opencode" }
+  if (input.model.api.npm !== "@ai-sdk/openai") return { type: "unsupported", reason: "provider package is not OpenAI" }
+  if (input.auth?.type === "oauth") return { type: "unsupported", reason: "OAuth auth is not supported" }
+
+  const apiKey = typeof input.provider.options.apiKey === "string" ? input.provider.options.apiKey : input.provider.key
+  if (!apiKey) return { type: "unsupported", reason: "OpenAI API key is not configured" }
+
+  return {
+    type: "supported",
+    apiKey,
+    baseURL: typeof input.provider.options.baseURL === "string" ? input.provider.options.baseURL : undefined,
+  }
+}
+
+export function stream(input: StreamInput): StreamResult {
+  const current = status(input)
+  if (current.type === "unsupported") return current
+
+  return {
+    ...current,
+    stream: input.llmClient.stream({
+      request: LLMNative.request({
+        model: input.model,
+        apiKey: current.apiKey,
+        baseURL: current.baseURL,
+        system: input.isOpenaiOauth ? input.system : [],
+        messages: ProviderTransform.message(input.messages, input.model, input.providerOptions ?? {}),
+        toolChoice: input.toolChoice,
+        temperature: input.temperature,
+        topP: input.topP,
+        topK: input.topK,
+        maxOutputTokens: input.maxOutputTokens,
+        providerOptions: ProviderTransform.providerOptions(input.model, input.providerOptions ?? {}),
+        headers: { ...providerHeaders(input.provider.options.headers), ...input.headers },
+      }),
+      tools: nativeTools(input.tools, input),
+    }),
+  }
+}
+
+function providerHeaders(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) return undefined
+  return Object.fromEntries(
+    Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+  )
+}
+
+function nativeSchema(value: unknown): JsonSchema {
+  if (!value || typeof value !== "object") return { type: "object", properties: {} }
+  if ("jsonSchema" in value && value.jsonSchema && typeof value.jsonSchema === "object")
+    return value.jsonSchema as JsonSchema
+  return asSchema(value as Parameters<typeof asSchema>[0]).jsonSchema as JsonSchema
+}
+
+export function nativeTools(tools: Record<string, Tool>, input: Pick<StreamInput, "messages" | "abort">) {
+  return Object.fromEntries(
+    Object.entries(tools).map(([name, item]) => [
+      name,
+      nativeTool({
+        description: item.description ?? "",
+        jsonSchema: nativeSchema(item.inputSchema),
+        execute: (args: unknown, ctx) =>
+          Effect.tryPromise({
+            try: () => {
+              if (!item.execute) throw new Error(`Tool has no execute handler: ${name}`)
+              return item.execute(args, {
+                toolCallId: ctx?.id ?? name,
+                messages: input.messages,
+                abortSignal: input.abort,
+              })
+            },
+            catch: (error) => new ToolFailure({ message: errorMessage(error), error }),
+          }),
+      }),
+    ]),
+  )
+}
+
+export * as LLMNativeRuntime from "./native-runtime"
@@ -1,4 +1,5 @@
-import { Cause, Deferred, Effect, Exit, Layer, Context, Scope } from "effect"
+import { Image } from "@/image/image"
+import { Cause, Deferred, Effect, Exit, Layer, Context, Scope, Schema } from "effect"
 import * as Stream from "effect/Stream"
 import { Agent } from "@/agent/agent"
 import { Bus } from "@/bus"
@@ -9,7 +10,6 @@ import { Snapshot } from "@/snapshot"
 import * as Session from "./session"
 import { LLM } from "./llm"
 import { MessageV2 } from "./message-v2"
-import { Image } from "@/image/image"
 import { isOverflow } from "./overflow"
 import { PartID } from "./schema"
 import type { SessionID } from "./schema"
@@ -28,14 +28,13 @@ import { ModelV2 } from "@opencode-ai/core/model"
 import { ProviderV2 } from "@opencode-ai/core/provider"
 import * as DateTime from "effect/DateTime"
 import { RuntimeFlags } from "@/effect/runtime-flags"
+import { Usage, type LLMEvent } from "@opencode-ai/llm"

 const DOOM_LOOP_THRESHOLD = 3
 const log = Log.create({ service: "session.processor" })

 export type Result = "compact" | "stop" | "continue"

-export type Event = LLM.Event
-
 export interface Handle {
  readonly message: MessageV2.Assistant
  readonly updateToolCall: (
@@ -69,6 +68,7 @@ type ToolCall = {
  messageID: MessageV2.ToolPart["messageID"]
  sessionID: MessageV2.ToolPart["sessionID"]
  done: Deferred.Deferred<void>
+  inputEnded: boolean
 }

 interface ProcessorContext extends Input {
@@ -81,7 +81,7 @@ interface ProcessorContext extends Input {
  reasoningMap: Record<string, MessageV2.ReasoningPart>
 }

-type StreamEvent = Event
+type StreamEvent = LLMEvent

 export class Service extends Context.Service<Service, Interface>()("@opencode/SessionProcessor") {}

@@ -137,7 +137,7 @@ export const layer = Layer.effect(

      const readToolCall = Effect.fn("SessionProcessor.readToolCall")(function* (toolCallID: string) {
        const call = ctx.toolcalls[toolCallID]
-        if (!call) return
+        if (!call) return undefined
        const part = yield* session.getPart({
          partID: call.partID,
          messageID: call.messageID,
@@ -145,7 +145,7 @@ export const layer = Layer.effect(
        })
        if (!part || part.type !== "tool") {
          delete ctx.toolcalls[toolCallID]
-          return
+          return undefined
        }
        return { call, part }
      })
@@ -155,7 +155,7 @@ export const layer = Layer.effect(
        update: (part: MessageV2.ToolPart) => MessageV2.ToolPart,
      ) {
        const match = yield* readToolCall(toolCallID)
-        if (!match) return
+        if (!match) return undefined
        const part = yield* session.updatePart(update(match.part))
        ctx.toolcalls[toolCallID] = {
          ...match.call,
@@ -211,12 +211,98 @@ export const layer = Layer.effect(
        return true
      })

+      const finishReasoning = Effect.fn("SessionProcessor.finishReasoning")(function* (reasoningID: string) {
+        if (!(reasoningID in ctx.reasoningMap)) return
+        // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
+        if (flags.experimentalEventSystem) {
+          yield* events.publish(SessionEvent.Reasoning.Ended, {
+            sessionID: ctx.sessionID,
+            reasoningID,
+            text: ctx.reasoningMap[reasoningID].text,
+            timestamp: DateTime.makeUnsafe(Date.now()),
+          })
+        }
+        // oxlint-disable-next-line no-self-assign -- reactivity trigger
+        ctx.reasoningMap[reasoningID].text = ctx.reasoningMap[reasoningID].text
+        ctx.reasoningMap[reasoningID].time = { ...ctx.reasoningMap[reasoningID].time, end: Date.now() }
+        yield* session.updatePart(ctx.reasoningMap[reasoningID])
+        delete ctx.reasoningMap[reasoningID]
+      })
+
+      const ensureToolCall = Effect.fn("SessionProcessor.ensureToolCall")(function* (input: {
+        id: string
+        name: string
+        providerExecuted?: boolean
+      }) {
+        const existing = yield* readToolCall(input.id)
+        if (existing) {
+          if (!input.providerExecuted || existing.part.metadata?.providerExecuted) return existing
+          const part = yield* session.updatePart({
+            ...existing.part,
+            metadata: { ...existing.part.metadata, providerExecuted: true },
+          })
+          ctx.toolcalls[input.id] = {
+            ...existing.call,
+            partID: part.id,
+            messageID: part.messageID,
+            sessionID: part.sessionID,
+          }
+          return { call: ctx.toolcalls[input.id], part }
+        }
+        // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
+        if (flags.experimentalEventSystem) {
+          yield* events.publish(SessionEvent.Tool.Input.Started, {
+            sessionID: ctx.sessionID,
+            callID: input.id,
+            name: input.name,
+            timestamp: DateTime.makeUnsafe(Date.now()),
+          })
+        }
+        const part = yield* session.updatePart({
+          id: PartID.ascending(),
+          messageID: ctx.assistantMessage.id,
+          sessionID: ctx.assistantMessage.sessionID,
+          type: "tool",
+          tool: input.name,
+          callID: input.id,
+          state: { status: "pending", input: {}, raw: "" },
+          metadata: input.providerExecuted ? { providerExecuted: true } : undefined,
+        } satisfies MessageV2.ToolPart)
+        ctx.toolcalls[input.id] = {
+          done: yield* Deferred.make<void>(),
+          partID: part.id,
+          messageID: part.messageID,
+          sessionID: part.sessionID,
+          inputEnded: false,
+        }
+        return { call: ctx.toolcalls[input.id], part }
+      })
+
+      const isFilePart = Schema.is(MessageV2.FilePart)
+
+      const toolResultOutput = (value: Extract<StreamEvent, { type: "tool-result" }>) => {
+        if (isRecord(value.result.value) && typeof value.result.value.output === "string") {
+          return {
+            title: typeof value.result.value.title === "string" ? value.result.value.title : value.name,
+            metadata: isRecord(value.result.value.metadata) ? value.result.value.metadata : {},
+            output: value.result.value.output,
+            attachments: Array.isArray(value.result.value.attachments)
+              ? value.result.value.attachments.filter(isFilePart)
+              : undefined,
+          }
+        }
+        return {
+          title: value.name,
+          metadata: value.result.type === "json" && isRecord(value.result.value) ? value.result.value : {},
+          output:
+            typeof value.result.value === "string" ? value.result.value : (JSON.stringify(value.result.value) ?? ""),
+        }
+      }
+
+      const toolInput = (value: unknown): Record<string, any> => (isRecord(value) ? value : { value })
+
      const handleEvent = Effect.fnUntraced(function* (value: StreamEvent) {
        switch (value.type) {
-          case "start":
-            yield* status.set(ctx.sessionID, { type: "busy" })
-            return
-
          case "reasoning-start":
            if (value.id in ctx.reasoningMap) return
            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
@@ -240,6 +326,7 @@ export const layer = Layer.effect(
            return

          case "reasoning-delta":
+            // Match dev: silently drop orphan deltas (no preceding reasoning-start).
            if (!(value.id in ctx.reasoningMap)) return
            ctx.reasoningMap[value.id].text += value.text
            if (value.providerMetadata) ctx.reasoningMap[value.id].metadata = value.providerMetadata
@@ -253,59 +340,26 @@ export const layer = Layer.effect(
            return

          case "reasoning-end":
-            if (!(value.id in ctx.reasoningMap)) return
-            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
-            if (flags.experimentalEventSystem) {
-              yield* events.publish(SessionEvent.Reasoning.Ended, {
-                sessionID: ctx.sessionID,
-                reasoningID: value.id,
-                text: ctx.reasoningMap[value.id].text,
-                timestamp: DateTime.makeUnsafe(Date.now()),
-              })
+            if (value.providerMetadata && value.id in ctx.reasoningMap) {
+              ctx.reasoningMap[value.id].metadata = value.providerMetadata
            }
-            // oxlint-disable-next-line no-self-assign -- reactivity trigger
-            ctx.reasoningMap[value.id].text = ctx.reasoningMap[value.id].text
-            ctx.reasoningMap[value.id].time = { ...ctx.reasoningMap[value.id].time, end: Date.now() }
-            if (value.providerMetadata) ctx.reasoningMap[value.id].metadata = value.providerMetadata
-            yield* session.updatePart(ctx.reasoningMap[value.id])
-            delete ctx.reasoningMap[value.id]
+            yield* finishReasoning(value.id)
            return

          case "tool-input-start":
            if (ctx.assistantMessage.summary) {
-              throw new Error(`Tool call not allowed while generating summary: ${value.toolName}`)
-            }
-            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
-            if (flags.experimentalEventSystem) {
-              yield* events.publish(SessionEvent.Tool.Input.Started, {
-                sessionID: ctx.sessionID,
-                callID: value.id,
-                name: value.toolName,
-                timestamp: DateTime.makeUnsafe(Date.now()),
-              })
-            }
-            const part = yield* session.updatePart({
-              id: ctx.toolcalls[value.id]?.partID ?? PartID.ascending(),
-              messageID: ctx.assistantMessage.id,
-              sessionID: ctx.assistantMessage.sessionID,
-              type: "tool",
-              tool: value.toolName,
-              callID: value.id,
-              state: { status: "pending", input: {}, raw: "" },
-              metadata: value.providerExecuted ? { providerExecuted: true } : undefined,
-            } satisfies MessageV2.ToolPart)
-            ctx.toolcalls[value.id] = {
-              done: yield* Deferred.make<void>(),
-              partID: part.id,
-              messageID: part.messageID,
-              sessionID: part.sessionID,
+              throw new Error(`Tool call not allowed while generating summary: ${value.name}`)
            }
+            yield* ensureToolCall(value)
            return

          case "tool-input-delta":
+            // AI SDK emits a final `tool-call` with the parsed `input`; accumulating
+            // delta fragments into `state.raw` is redundant work for no current consumer.
            return

          case "tool-input-end": {
+            const toolCall = yield* ensureToolCall(value)
            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
            if (flags.experimentalEventSystem) {
              yield* events.publish(SessionEvent.Tool.Input.Ended, {
@@ -315,37 +369,52 @@ export const layer = Layer.effect(
                timestamp: DateTime.makeUnsafe(Date.now()),
              })
            }
+            ctx.toolcalls[value.id] = { ...toolCall.call, inputEnded: true }
            return
          }

          case "tool-call": {
            if (ctx.assistantMessage.summary) {
-              throw new Error(`Tool call not allowed while generating summary: ${value.toolName}`)
+              throw new Error(`Tool call not allowed while generating summary: ${value.name}`)
+            }
+            const toolCall = yield* ensureToolCall(value)
+            const input = toolInput(value.input)
+            if (!toolCall.call.inputEnded) {
+              // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
+              if (flags.experimentalEventSystem) {
+                yield* events.publish(SessionEvent.Tool.Input.Ended, {
+                  sessionID: ctx.sessionID,
+                  callID: value.id,
+                  text: "",
+                  timestamp: DateTime.makeUnsafe(Date.now()),
+                })
+              }
            }
-            const toolCall = yield* readToolCall(value.toolCallId)
            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
            if (flags.experimentalEventSystem) {
              yield* events.publish(SessionEvent.Tool.Called, {
                sessionID: ctx.sessionID,
-                callID: value.toolCallId,
-                tool: value.toolName,
-                input: value.input,
+                callID: value.id,
+                tool: value.name,
+                input,
                provider: {
-                  executed: toolCall?.part.metadata?.providerExecuted === true,
+                  executed: toolCall.part.metadata?.providerExecuted === true,
                  ...(value.providerMetadata ? { metadata: value.providerMetadata } : {}),
                },
                timestamp: DateTime.makeUnsafe(Date.now()),
              })
            }
-            yield* updateToolCall(value.toolCallId, (match) => ({
+            yield* updateToolCall(value.id, (match) => ({
              ...match,
-              tool: value.toolName,
-              state: {
-                ...match.state,
-                status: "running",
-                input: value.input,
-                time: { start: Date.now() },
-              },
+              tool: value.name,
+              state:
+                match.state.status === "running"
+                  ? { ...match.state, input }
+                  : {
+                      status: "running",
+                      input,
+                      time: { start: Date.now() },
+                    },
              metadata: match.metadata?.providerExecuted
                ? { ...value.providerMetadata, providerExecuted: true }
                : value.providerMetadata,
@@ -359,9 +428,9 @@ export const layer = Layer.effect(
              !recentParts.every(
                (part) =>
                  part.type === "tool" &&
-                  part.tool === value.toolName &&
+                  part.tool === value.name &&
                  part.state.status !== "pending" &&
-                  JSON.stringify(part.state.input) === JSON.stringify(value.input),
+                  JSON.stringify(part.state.input) === JSON.stringify(input),
              )
            ) {
              return
@@ -370,27 +439,19 @@ export const layer = Layer.effect(
            const agent = yield* agents.get(ctx.assistantMessage.agent)
            yield* permission.ask({
              permission: "doom_loop",
-              patterns: [value.toolName],
+              patterns: [value.name],
              sessionID: ctx.assistantMessage.sessionID,
-              metadata: { tool: value.toolName, input: value.input },
-              always: [value.toolName],
+              metadata: { tool: value.name, input },
+              always: [value.name],
              ruleset: agent.permission,
            })
            return
          }

          case "tool-result": {
-            const toolCall = yield* readToolCall(value.toolCallId)
-            const toolAttachments: MessageV2.FilePart[] = (
-              Array.isArray(value.output.attachments) ? value.output.attachments : []
-            ).filter(
-              (attachment: unknown): attachment is MessageV2.FilePart =>
-                isRecord(attachment) &&
-                attachment.type === "file" &&
-                typeof attachment.mime === "string" &&
-                typeof attachment.url === "string",
-            )
-            const normalized = yield* Effect.forEach(toolAttachments, (attachment) =>
+            const toolCall = yield* readToolCall(value.id)
+            const rawOutput = toolResultOutput(value)
+            const normalized = yield* Effect.forEach(rawOutput.attachments ?? [], (attachment) =>
              attachment.mime.startsWith("image/")
                ? image.normalize(attachment).pipe(
                    Effect.catchIf(
@@ -404,18 +465,18 @@ export const layer = Layer.effect(
            const omitted = normalized.filter(Exit.isFailure).length
            const attachments = normalized.filter(Exit.isSuccess).map((item) => item.value)
            const output = {
-              ...value.output,
+              ...rawOutput,
              output:
                omitted === 0
-                  ? value.output.output
-                  : `${value.output.output}\n\n[${omitted} image${omitted === 1 ? "" : "s"} omitted: could not be resized below the image size limit.]`,
-              attachments: attachments?.length ? attachments : undefined,
+                  ? rawOutput.output
+                  : `${rawOutput.output}\n\n[${omitted} image${omitted === 1 ? "" : "s"} omitted: could not be resized below the image size limit.]`,
+              attachments: attachments.length ? attachments : undefined,
            }
            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
            if (flags.experimentalEventSystem) {
              yield* events.publish(SessionEvent.Tool.Success, {
                sessionID: ctx.sessionID,
-                callID: value.toolCallId,
+                callID: value.id,
                structured: output.metadata,
                content: [
                  {
@@ -423,32 +484,32 @@ export const layer = Layer.effect(
                    text: output.output,
                  },
                  ...(output.attachments?.map((item: MessageV2.FilePart) => ({
-                    type: "file",
+                    type: "file" as const,
                    uri: item.url,
                    mime: item.mime,
                    name: item.filename,
                  })) ?? []),
                ],
                provider: {
-                  executed: toolCall?.part.metadata?.providerExecuted === true,
+                  executed: value.providerExecuted === true || toolCall?.part.metadata?.providerExecuted === true,
                },
                timestamp: DateTime.makeUnsafe(Date.now()),
              })
            }
-            yield* completeToolCall(value.toolCallId, output)
+            yield* completeToolCall(value.id, output)
            return
          }

          case "tool-error": {
-            const toolCall = yield* readToolCall(value.toolCallId)
+            const toolCall = yield* readToolCall(value.id)
            // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
            if (flags.experimentalEventSystem) {
              yield* events.publish(SessionEvent.Tool.Failed, {
                sessionID: ctx.sessionID,
-                callID: value.toolCallId,
+                callID: value.id,
                error: {
                  type: "unknown",
-                  message: errorMessage(value.error),
+                  message: value.message,
                },
                provider: {
                  executed: toolCall?.part.metadata?.providerExecuted === true,
@@ -456,14 +517,14 @@ export const layer = Layer.effect(
                timestamp: DateTime.makeUnsafe(Date.now()),
              })
            }
-            yield* failToolCall(value.toolCallId, value.error)
+            yield* failToolCall(value.id, value.error ?? new Error(value.message))
            return
          }

-          case "error":
-            throw value.error
+          case "provider-error":
+            throw new Error(value.message)

-          case "start-step":
+          case "step-start":
            if (!ctx.snapshot) ctx.snapshot = yield* snapshot.track()
            if (!ctx.assistantMessage.summary) {
              // TODO(v2): Temporary dual-write while migrating session messages to v2 events.
@@ -490,11 +551,12 @@ export const layer = Layer.effect(
            })
            return

-          case "finish-step": {
+          case "step-finish": {
            const completedSnapshot = yield* snapshot.track()
+            yield* Effect.forEach(Object.keys(ctx.reasoningMap), finishReasoning)
            const usage = Session.getUsage({
              model: ctx.model,
-              usage: value.usage,
+              usage: value.usage ?? new Usage({}),
              metadata: value.providerMetadata,
            })
            if (!ctx.assistantMessage.summary) {
@@ -502,7 +564,7 @@ export const layer = Layer.effect(
              if (flags.experimentalEventSystem) {
                yield* events.publish(SessionEvent.Step.Ended, {
                  sessionID: ctx.sessionID,
-                  finish: value.finishReason,
+                  finish: value.reason,
                  cost: usage.cost,
                  tokens: usage.tokens,
                  snapshot: completedSnapshot,
@@ -510,12 +572,12 @@ export const layer = Layer.effect(
                })
              }
            }
-            ctx.assistantMessage.finish = value.finishReason
+            ctx.assistantMessage.finish = value.reason
            ctx.assistantMessage.cost += usage.cost
            ctx.assistantMessage.tokens = usage.tokens
            yield* session.updatePart({
              id: PartID.ascending(),
-              reason: value.finishReason,
+              reason: value.reason,
              snapshot: completedSnapshot,
              messageID: ctx.assistantMessage.id,
              sessionID: ctx.assistantMessage.sessionID,
@@ -622,10 +684,6 @@ export const layer = Layer.effect(

          case "finish":
            return
-
-          default:
-            slog.info("unhandled", { event: value.type, value })
-            return
        }
      })

@@ -727,6 +785,7 @@ export const layer = Layer.effect(
          yield* Effect.gen(function* () {
            ctx.currentText = undefined
            ctx.reasoningMap = {}
+            yield* status.set(ctx.sessionID, { type: "busy" })
            const stream = llm.stream(streamInput)

            yield* stream.pipe(
@@ -8,17 +8,15 @@ import * as Session from "./session"
 import { Agent } from "../agent/agent"
 import { Provider } from "@/provider/provider"
 import { ModelID, ProviderID } from "../provider/schema"
-import { type Tool as AITool, tool, jsonSchema, type ToolExecutionOptions, asSchema } from "ai"
+import { type Tool as AITool, tool, jsonSchema } from "ai"
 import type { JSONSchema7 } from "@ai-sdk/provider"
 import { SessionCompaction } from "./compaction"
 import { Bus } from "../bus"
-import { ProviderTransform } from "@/provider/transform"
 import { SystemPrompt } from "./system"
 import { Instruction } from "./instruction"
 import { Plugin } from "../plugin"
 import MAX_STEPS from "../session/prompt/max-steps.txt"
 import { ToolRegistry } from "@/tool/registry"
-import { ToolJsonSchema } from "@/tool/json-schema"
 import { MCP } from "../mcp"
 import { LSP } from "@/lsp/lsp"
 import { ulid } from "ulid"
@@ -48,7 +46,6 @@ import * as EffectLogger from "@opencode-ai/core/effect/logger"
 import { InstanceState } from "@/effect/instance-state"
 import { TaskTool, type TaskPromptOps } from "@/tool/task"
 import { SessionRunState } from "./run-state"
-import { EffectBridge } from "@/effect/bridge"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { EventV2 } from "@opencode-ai/core/event"
 import { EventV2Bridge } from "@/event-v2-bridge"
@@ -63,6 +60,8 @@ import * as Database from "@/storage/db"
 import { SessionTable } from "./session.sql"
 import { referencePromptMetadata, referenceTextPart } from "./prompt/reference"
 import { SessionReminders } from "./reminders"
+import { SessionTools } from "./tools"
+import { LLMEvent } from "@opencode-ai/llm"

 // @ts-ignore
 globalThis.AI_SDK_LOG_WARNINGS = false
@@ -125,9 +124,6 @@ export const layer = Layer.effect(
    const references = yield* Reference.Service
    const events = yield* EventV2Bridge.Service
    const flags = yield* RuntimeFlags.Service
-    const runner = Effect.fn("SessionPrompt.runner")(function* () {
-      return yield* EffectBridge.make()
-    })
    const ops = Effect.fn("SessionPrompt.ops")(function* () {
      return {
        cancel: (sessionID: SessionID) => cancel(sessionID),
@@ -283,7 +279,7 @@ export const layer = Layer.effect(
          messages: [{ role: "user", content: "Generate a title for this conversation:\n" }, ...msgs],
        })
        .pipe(
-          Stream.filter((e): e is Extract<LLM.Event, { type: "text-delta" }> => e.type === "text-delta"),
+          Stream.filter(LLMEvent.is.textDelta),
          Stream.map((e) => e.text),
          Stream.mkString,
          Effect.orDie,
@@ -300,186 +296,6 @@ export const layer = Layer.effect(
        .pipe(Effect.catchCause((cause) => elog.error("failed to generate title", { error: Cause.squash(cause) })))
    })

-    const resolveTools = Effect.fn("SessionPrompt.resolveTools")(function* (input: {
-      agent: Agent.Info
-      model: Provider.Model
-      session: Session.Info
-      tools?: Record<string, boolean>
-      processor: Pick<SessionProcessor.Handle, "message" | "updateToolCall" | "completeToolCall">
-      bypassAgentCheck: boolean
-      messages: MessageV2.WithParts[]
-    }) {
-      using _ = log.time("resolveTools")
-      const tools: Record<string, AITool> = {}
-      const run = yield* runner()
-      const promptOps = yield* ops()
-
-      const context = (args: any, options: ToolExecutionOptions): Tool.Context => ({
-        sessionID: input.session.id,
-        abort: options.abortSignal!,
-        messageID: input.processor.message.id,
-        callID: options.toolCallId,
-        extra: { model: input.model, bypassAgentCheck: input.bypassAgentCheck, promptOps },
-        agent: input.agent.name,
-        messages: input.messages,
-        metadata: (val) =>
-          input.processor.updateToolCall(options.toolCallId, (match) => {
-            if (!["running", "pending"].includes(match.state.status)) return match
-            return {
-              ...match,
-              state: {
-                title: val.title,
-                metadata: val.metadata,
-                status: "running",
-                input: args,
-                time: { start: Date.now() },
-              },
-            }
-          }),
-        ask: (req) =>
-          permission
-            .ask({
-              ...req,
-              sessionID: input.session.id,
-              tool: { messageID: input.processor.message.id, callID: options.toolCallId },
-              ruleset: Permission.merge(input.agent.permission, input.session.permission ?? []),
-            })
-            .pipe(Effect.orDie),
-      })
-
-      for (const item of yield* registry.tools({
-        modelID: ModelID.make(input.model.api.id),
-        providerID: input.model.providerID,
-        agent: input.agent,
-      })) {
-        const schema = ProviderTransform.schema(input.model, ToolJsonSchema.fromTool(item))
-        tools[item.id] = tool({
-          description: item.description,
-          inputSchema: jsonSchema(schema),
-          execute(args, options) {
-            return run.promise(
-              Effect.gen(function* () {
-                const ctx = context(args, options)
-                yield* plugin.trigger(
-                  "tool.execute.before",
-                  { tool: item.id, sessionID: ctx.sessionID, callID: ctx.callID },
-                  { args },
-                )
-                const result = yield* item.execute(args, ctx)
-                const output = {
-                  ...result,
-                  attachments: result.attachments?.map((attachment) => ({
-                    ...attachment,
-                    id: PartID.ascending(),
-                    sessionID: ctx.sessionID,
-                    messageID: input.processor.message.id,
-                  })),
-                }
-                yield* plugin.trigger(
-                  "tool.execute.after",
-                  { tool: item.id, sessionID: ctx.sessionID, callID: ctx.callID, args },
-                  output,
-                )
-                if (options.abortSignal?.aborted) {
-                  yield* input.processor.completeToolCall(options.toolCallId, output)
-                }
-                return output
-              }),
-            )
-          },
-        })
-      }
-
-      for (const [key, item] of Object.entries(yield* mcp.tools())) {
-        const execute = item.execute
-        if (!execute) continue
-
-        const schema = yield* Effect.promise(() => Promise.resolve(asSchema(item.inputSchema).jsonSchema))
-        const transformed = ProviderTransform.schema(input.model, schema)
-        item.inputSchema = jsonSchema(transformed)
-        item.execute = (args, opts) =>
-          run.promise(
-            Effect.gen(function* () {
-              const ctx = context(args, opts)
-              yield* plugin.trigger(
-                "tool.execute.before",
-                { tool: key, sessionID: ctx.sessionID, callID: opts.toolCallId },
-                { args },
-              )
-              const result: Awaited<ReturnType<NonNullable<typeof execute>>> = yield* Effect.gen(function* () {
-                yield* ctx.ask({ permission: key, metadata: {}, patterns: ["*"], always: ["*"] })
-                return yield* Effect.promise(() => execute(args, opts))
-              }).pipe(
-                Effect.withSpan("Tool.execute", {
-                  attributes: {
-                    "tool.name": key,
-                    "tool.call_id": opts.toolCallId,
-                    "session.id": ctx.sessionID,
-                    "message.id": input.processor.message.id,
-                  },
-                }),
-              )
-              yield* plugin.trigger(
-                "tool.execute.after",
-                { tool: key, sessionID: ctx.sessionID, callID: opts.toolCallId, args },
-                result,
-              )
-
-              const textParts: string[] = []
-              const attachments: Omit<MessageV2.FilePart, "id" | "sessionID" | "messageID">[] = []
-              for (const contentItem of result.content) {
-                if (contentItem.type === "text") textParts.push(contentItem.text)
-                else if (contentItem.type === "image") {
-                  attachments.push({
-                    type: "file",
-                    mime: contentItem.mimeType,
-                    url: `data:${contentItem.mimeType};base64,${contentItem.data}`,
-                  })
-                } else if (contentItem.type === "resource") {
-                  const { resource } = contentItem
-                  if (resource.text) textParts.push(resource.text)
-                  if (resource.blob) {
-                    attachments.push({
-                      type: "file",
-                      mime: resource.mimeType ?? "application/octet-stream",
-                      url: `data:${resource.mimeType ?? "application/octet-stream"};base64,${resource.blob}`,
-                      filename: resource.uri,
-                    })
-                  }
-                }
-              }
-
-              const truncated = yield* truncate.output(textParts.join("\n\n"), {}, input.agent)
-              const metadata = {
-                ...result.metadata,
-                truncated: truncated.truncated,
-                ...(truncated.truncated && { outputPath: truncated.outputPath }),
-              }
-
-              const output = {
-                title: "",
-                metadata,
-                output: truncated.content,
-                attachments: attachments.map((attachment) => ({
-                  ...attachment,
-                  id: PartID.ascending(),
-                  sessionID: ctx.sessionID,
-                  messageID: input.processor.message.id,
-                })),
-                content: result.content,
-              }
-              if (opts.abortSignal?.aborted) {
-                yield* input.processor.completeToolCall(opts.toolCallId, output)
-              }
-              return output
-            }),
-          )
-        tools[key] = item
-      }
-
-      return tools
-    })
-
    const handleSubtask = Effect.fn("SessionPrompt.handleSubtask")(function* (input: {
      task: MessageV2.SubtaskPart
      model: Provider.Model
@@ -1551,16 +1367,23 @@ export const layer = Layer.effect(
          const outcome: "break" | "continue" = yield* Effect.gen(function* () {
            const lastUserMsg = msgs.findLast((m) => m.info.role === "user")
            const bypassAgentCheck = lastUserMsg?.parts.some((p) => p.type === "agent") ?? false
+            const promptOps = yield* ops()

-            const tools = yield* resolveTools({
+            const tools = yield* SessionTools.resolve({
              agent,
              session,
              model,
-              tools: lastUser.tools,
              processor: handle,
              bypassAgentCheck,
              messages: msgs,
-            })
+              promptOps,
+            }).pipe(
+              Effect.provideService(Plugin.Service, plugin),
+              Effect.provideService(Permission.Service, permission),
+              Effect.provideService(ToolRegistry.Service, registry),
+              Effect.provideService(MCP.Service, mcp),
+              Effect.provideService(Truncate.Service, truncate),
+            )

            if (lastUser.format?.type === "json_schema") {
              tools["StructuredOutput"] = createStructuredOutputTool({
@@ -4,7 +4,8 @@ import { BackgroundJob } from "@/background/job"
 import { BusEvent } from "@/bus/bus-event"
 import { Bus } from "@/bus"
 import { Decimal } from "decimal.js"
-import { type ProviderMetadata, type LanguageModelUsage } from "ai"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import type { ProviderMetadata, Usage } from "@opencode-ai/llm"
 import { InstallationVersion } from "@opencode-ai/core/installation/version"

 import { Database } from "@/storage/db"
@@ -374,21 +375,19 @@ export function plan(input: { slug: string; time: { created: number } }, instanc
  return path.join(base, [input.time.created, input.slug].join("-") + ".md")
 }

-export const getUsage = (input: { model: Provider.Model; usage: LanguageModelUsage; metadata?: ProviderMetadata }) => {
+export const getUsage = (input: { model: Provider.Model; usage: Usage; metadata?: ProviderMetadata }) => {
  const safe = (value: number) => {
    if (!Number.isFinite(value)) return 0
    return Math.max(0, value)
  }
  const inputTokens = safe(input.usage.inputTokens ?? 0)
  const outputTokens = safe(input.usage.outputTokens ?? 0)
-  const reasoningTokens = safe(input.usage.outputTokenDetails?.reasoningTokens ?? input.usage.reasoningTokens ?? 0)
+  const reasoningTokens = safe(input.usage.reasoningTokens ?? 0)

-  const cacheReadInputTokens = safe(
-    input.usage.inputTokenDetails?.cacheReadTokens ?? input.usage.cachedInputTokens ?? 0,
-  )
+  const cacheReadInputTokens = safe(input.usage.cacheReadInputTokens ?? 0)
  const cacheWriteInputTokens = safe(
    Number(
-      input.usage.inputTokenDetails?.cacheWriteTokens ??
+      input.usage.cacheWriteInputTokens ??
        input.metadata?.["anthropic"]?.["cacheCreationInputTokens"] ??
        // google-vertex-anthropic returns metadata under "vertex" key
        // (AnthropicMessagesLanguageModel custom provider key from 'vertex.anthropic.messages')
@@ -0,0 +1,208 @@
+import { Agent } from "@/agent/agent"
+import { Provider } from "@/provider/provider"
+import { ProviderTransform } from "@/provider/transform"
+import { MCP } from "@/mcp"
+import { Permission } from "@/permission"
+import { Tool } from "@/tool/tool"
+import { ToolJsonSchema } from "@/tool/json-schema"
+import { ToolRegistry } from "@/tool/registry"
+import { Truncate } from "@/tool/truncate"
+import { ModelID } from "@/provider/schema"
+import { Plugin } from "@/plugin"
+import type { TaskPromptOps } from "@/tool/task"
+import { type Tool as AITool, tool, jsonSchema, type ToolExecutionOptions, asSchema } from "ai"
+import { Effect } from "effect"
+import { MessageV2 } from "./message-v2"
+import * as Session from "./session"
+import { SessionProcessor } from "./processor"
+import { PartID } from "./schema"
+import * as Log from "@opencode-ai/core/util/log"
+import { EffectBridge } from "@/effect/bridge"
+
+const log = Log.create({ service: "session.tools" })
+
+export const resolve = Effect.fn("SessionTools.resolve")(function* (input: {
+  agent: Agent.Info
+  model: Provider.Model
+  session: Session.Info
+  processor: Pick<SessionProcessor.Handle, "message" | "updateToolCall" | "completeToolCall">
+  bypassAgentCheck: boolean
+  messages: MessageV2.WithParts[]
+  promptOps: TaskPromptOps
+}) {
+  using _ = log.time("resolveTools")
+  const tools: Record<string, AITool> = {}
+  const run = yield* EffectBridge.make()
+  const plugin = yield* Plugin.Service
+  const permission = yield* Permission.Service
+  const registry = yield* ToolRegistry.Service
+  const mcp = yield* MCP.Service
+  const truncate = yield* Truncate.Service
+
+  const context = (args: Record<string, unknown>, options: ToolExecutionOptions): Tool.Context => ({
+    sessionID: input.session.id,
+    abort: options.abortSignal!,
+    messageID: input.processor.message.id,
+    callID: options.toolCallId,
+    extra: { model: input.model, bypassAgentCheck: input.bypassAgentCheck, promptOps: input.promptOps },
+    agent: input.agent.name,
+    messages: input.messages,
+    metadata: (val) =>
+      input.processor.updateToolCall(options.toolCallId, (match) => {
+        if (!["running", "pending"].includes(match.state.status)) return match
+        return {
+          ...match,
+          state: {
+            title: val.title,
+            metadata: val.metadata,
+            status: "running",
+            input: args,
+            time: { start: Date.now() },
+          },
+        }
+      }),
+    ask: (req) =>
+      permission
+        .ask({
+          ...req,
+          sessionID: input.session.id,
+          tool: { messageID: input.processor.message.id, callID: options.toolCallId },
+          ruleset: Permission.merge(input.agent.permission, input.session.permission ?? []),
+        })
+        .pipe(Effect.orDie),
+  })
+
+  for (const item of yield* registry.tools({
+    modelID: ModelID.make(input.model.api.id),
+    providerID: input.model.providerID,
+    agent: input.agent,
+  })) {
+    const schema = ProviderTransform.schema(input.model, ToolJsonSchema.fromTool(item))
+    tools[item.id] = tool({
+      description: item.description,
+      inputSchema: jsonSchema(schema),
+      execute(args, options) {
+        return run.promise(
+          Effect.gen(function* () {
+            const ctx = context(args, options)
+            yield* plugin.trigger(
+              "tool.execute.before",
+              { tool: item.id, sessionID: ctx.sessionID, callID: ctx.callID },
+              { args },
+            )
+            const result = yield* item.execute(args, ctx)
+            const output = {
+              ...result,
+              attachments: result.attachments?.map((attachment) => ({
+                ...attachment,
+                id: PartID.ascending(),
+                sessionID: ctx.sessionID,
+                messageID: input.processor.message.id,
+              })),
+            }
+            yield* plugin.trigger(
+              "tool.execute.after",
+              { tool: item.id, sessionID: ctx.sessionID, callID: ctx.callID, args },
+              output,
+            )
+            if (options.abortSignal?.aborted) {
+              yield* input.processor.completeToolCall(options.toolCallId, output)
+            }
+            return output
+          }),
+        )
+      },
+    })
+  }
+
+  for (const [key, item] of Object.entries(yield* mcp.tools())) {
+    const execute = item.execute
+    if (!execute) continue
+
+    const schema = yield* Effect.promise(() => Promise.resolve(asSchema(item.inputSchema).jsonSchema))
+    const transformed = ProviderTransform.schema(input.model, schema)
+    item.inputSchema = jsonSchema(transformed)
+    item.execute = (args, opts) =>
+      run.promise(
+        Effect.gen(function* () {
+          const ctx = context(args, opts)
+          yield* plugin.trigger(
+            "tool.execute.before",
+            { tool: key, sessionID: ctx.sessionID, callID: opts.toolCallId },
+            { args },
+          )
+          const result: Awaited<ReturnType<NonNullable<typeof execute>>> = yield* Effect.gen(function* () {
+            yield* ctx.ask({ permission: key, metadata: {}, patterns: ["*"], always: ["*"] })
+            return yield* Effect.promise(() => execute(args, opts))
+          }).pipe(
+            Effect.withSpan("Tool.execute", {
+              attributes: {
+                "tool.name": key,
+                "tool.call_id": opts.toolCallId,
+                "session.id": ctx.sessionID,
+                "message.id": input.processor.message.id,
+              },
+            }),
+          )
+          yield* plugin.trigger(
+            "tool.execute.after",
+            { tool: key, sessionID: ctx.sessionID, callID: opts.toolCallId, args },
+            result,
+          )
+
+          const textParts: string[] = []
+          const attachments: Omit<MessageV2.FilePart, "id" | "sessionID" | "messageID">[] = []
+          for (const contentItem of result.content) {
+            if (contentItem.type === "text") textParts.push(contentItem.text)
+            else if (contentItem.type === "image") {
+              attachments.push({
+                type: "file",
+                mime: contentItem.mimeType,
+                url: `data:${contentItem.mimeType};base64,${contentItem.data}`,
+              })
+            } else if (contentItem.type === "resource") {
+              const { resource } = contentItem
+              if (resource.text) textParts.push(resource.text)
+              if (resource.blob) {
+                attachments.push({
+                  type: "file",
+                  mime: resource.mimeType ?? "application/octet-stream",
+                  url: `data:${resource.mimeType ?? "application/octet-stream"};base64,${resource.blob}`,
+                  filename: resource.uri,
+                })
+              }
+            }
+          }
+
+          const truncated = yield* truncate.output(textParts.join("\n\n"), {}, input.agent)
+          const metadata = {
+            ...result.metadata,
+            truncated: truncated.truncated,
+            ...(truncated.truncated && { outputPath: truncated.outputPath }),
+          }
+
+          const output = {
+            title: "",
+            metadata,
+            output: truncated.content,
+            attachments: attachments.map((attachment) => ({
+              ...attachment,
+              id: PartID.ascending(),
+              sessionID: ctx.sessionID,
+              messageID: input.processor.message.id,
+            })),
+            content: result.content,
+          }
+          if (opts.abortSignal?.aborted) {
+            yield* input.processor.completeToolCall(opts.toolCallId, output)
+          }
+          return output
+        }),
+      )
+    tools[key] = item
+  }
+
+  return tools
+})
+
+export * as SessionTools from "./tools"
@@ -40,6 +40,7 @@ import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
 import { Ripgrep } from "../file/ripgrep"
 import { Format } from "../format"
 import { InstanceState } from "@/effect/instance-state"
+import { EffectBridge } from "@/effect/bridge"
 import { Question } from "../question"
 import { Todo } from "../session/todo"
 import { LSP } from "@/lsp/lsp"
@@ -158,9 +159,12 @@ export const layer: Layer.Layer<
            description: def.description,
            execute: (args, toolCtx) =>
              Effect.gen(function* () {
+                // Bridge the host's Effect-based `ask` into a Promise-returning
+                // function for the plugin to make sure context persists
+                const bridge = yield* EffectBridge.make()
                const pluginCtx: PluginToolContext = {
                  ...toolCtx,
-                  ask: (req) => toolCtx.ask(req),
+                  ask: (req) => bridge.promise(toolCtx.ask(req)),
                  directory: ctx.directory,
                  worktree: ctx.worktree,
                }
@@ -0,0 +1,70 @@
+// Subprocess integration tests for `opencode acp`. ACP is a JSON-RPC
+// protocol spoken over stdin/stdout (not HTTP) — see src/acp/README.md.
+// This is the only test tier that exercises the full pipe of bun startup →
+// server boot → ACP agent init → stdio framing → graceful shutdown.
+import { describe, expect } from "bun:test"
+import { Duration, Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+
+describe("opencode acp (subprocess)", () => {
+  // Smoke test: send the `initialize` request from src/acp/README.md and
+  // assert the response advertises the same protocol version and a non-empty
+  // capabilities block. If this fails, every other ACP test will too — start
+  // debugging here.
+  cliIt.live(
+    "responds to initialize with protocolVersion 1 and capabilities",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* opencode.acp()
+
+        yield* acp.send({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: { protocolVersion: 1 },
+        })
+
+        // Tight deadline — the response should arrive within a few seconds
+        // once startup completes. A hang means the agent never finished init,
+        // which is a real regression and not a tuning issue.
+        const response = (yield* acp.receive.pipe(Effect.timeout(Duration.seconds(10)))) as {
+          jsonrpc: string
+          id: number
+          result?: { protocolVersion: number; agentCapabilities: Record<string, unknown> }
+          error?: unknown
+        }
+
+        expect(response.jsonrpc).toBe("2.0")
+        expect(response.id).toBe(1)
+        expect(response.error).toBeUndefined()
+        expect(response.result?.protocolVersion).toBe(1)
+        expect(response.result?.agentCapabilities).toBeDefined()
+      }),
+    60_000,
+  )
+
+  // Lock in the scope-close kill path. ACP's clean shutdown is "EOF on stdin"
+  // — if a future refactor breaks the stdin-end branch in the handler, the
+  // process would only exit on SIGTERM fallback (2s in the harness). This
+  // test passing within the inner-scope assertion proves the EOF path works.
+  cliIt.live(
+    "exits cleanly when stdin is closed (scope close)",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const exitedPromise = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const acp = yield* opencode.acp()
+            // Capture the Promise — scope-close fires the finalizer which
+            // ends stdin, and ACP should exit gracefully.
+            return acp.exited
+          }),
+        )
+
+        const code = yield* Effect.promise(() => exitedPromise)
+        // Bun returns a number for normal exit. Anything goes for SIGTERM,
+        // but we still require resolution within the test timeout.
+        expect(typeof code === "number" || code === null).toBe(true)
+      }),
+    60_000,
+  )
+})
@@ -0,0 +1,623 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode acp --help 1`] = `
+"opencode acp
+
+start ACP (Agent Client Protocol) server
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+      --port         port to listen on                                         [number] [default: 0]
+      --hostname     hostname to listen on                           [string] [default: "127.0.0.1"]
+      --mdns         enable mDNS service discovery (defaults hostname to 0.0.0.0)
+                                                                          [boolean] [default: false]
+      --mdns-domain  custom domain name for mDNS service (default: opencode.local)
+                                                                [string] [default: "opencode.local"]
+      --cors         additional domains to allow for CORS                      [array] [default: []]
+      --cwd          working directory [string] [default: "<HOME>"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp --help 1`] = `
+"opencode mcp
+
+manage MCP (Model Context Protocol) servers
+
+Commands:
+  opencode mcp add            add an MCP server
+  opencode mcp list           list MCP servers and their status                        [aliases: ls]
+  opencode mcp auth [name]    authenticate with an OAuth-enabled MCP server
+  opencode mcp logout [name]  remove OAuth credentials for an MCP server
+  opencode mcp debug <name>   debug OAuth connection for an MCP server
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode attach --help 1`] = `
+"opencode attach <url>
+
+attach to a running opencode server
+
+Positionals:
+  url  http://localhost:4096                                                     [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --dir         directory to run in                                                     [string]
+  -c, --continue    continue the last session                                              [boolean]
+  -s, --session     session id to continue                                                  [string]
+      --fork        fork the session when continuing (use with --continue or --session)    [boolean]
+  -p, --password    basic auth password (defaults to OPENCODE_SERVER_PASSWORD)              [string]
+  -u, --username    basic auth username (defaults to OPENCODE_SERVER_USERNAME or 'opencode')[string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode run --help 1`] = `
+"opencode run [message..]
+
+run opencode with a message
+
+Positionals:
+  message  message to send                                                     [array] [default: []]
+
+Options:
+  -h, --help                          show help                                            [boolean]
+  -v, --version                       show version number                                  [boolean]
+      --print-logs                    print logs to stderr                                 [boolean]
+      --log-level                     log level [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure                          run without external plugins                         [boolean]
+      --command                       the command to run, use message for args              [string]
+  -c, --continue                      continue the last session                            [boolean]
+  -s, --session                       session id to continue                                [string]
+      --fork                          fork the session before continuing (requires --continue or
+                                      --session)                                           [boolean]
+      --share                         share the session                                    [boolean]
+  -m, --model                         model to use in the format of provider/model          [string]
+      --agent                         agent to use                                          [string]
+      --format                        format: default (formatted) or json (raw JSON events)
+                                          [string] [choices: "default", "json"] [default: "default"]
+  -f, --file                          file(s) to attach to message                           [array]
+      --title                         title for the session (uses truncated prompt if no value
+                                      provided)                                             [string]
+      --attach                        attach to a running opencode server (e.g.,
+                                      http://localhost:4096)                                [string]
+  -p, --password                      basic auth password (defaults to OPENCODE_SERVER_PASSWORD)
+                                                                                            [string]
+  -u, --username                      basic auth username (defaults to OPENCODE_SERVER_USERNAME or
+                                      'opencode')                                           [string]
+      --dir                           directory to run in, path on remote server if attaching
+                                                                                            [string]
+      --port                          port for the local server (defaults to random port if no value
+                                      provided)                                             [number]
+      --variant                       model variant (provider-specific reasoning effort, e.g., high,
+                                      max, minimal)                                         [string]
+      --thinking                      show thinking blocks                                 [boolean]
+      --replay                        replay visible session history on interactive resume
+                                                                          [boolean] [default: false]
+      --replay-limit                  cap visible interactive replay to the newest N messages
+                                                                                            [number]
+  -i, --interactive                   run in direct interactive split-footer mode
+                                                                          [boolean] [default: false]
+      --dangerously-skip-permissions  auto-approve permissions that are not explicitly denied
+                                      (dangerous!)                        [boolean] [default: false]
+      --demo                          enable direct interactive demo slash commands; pass one as the
+                                      message to run it immediately       [boolean] [default: false]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode debug --help 1`] = `
+"opencode debug
+
+debugging and troubleshooting tools
+
+Commands:
+  opencode debug config        show resolved configuration
+  opencode debug lsp           LSP debugging utilities
+  opencode debug rg            ripgrep debugging utilities
+  opencode debug file          file system debugging utilities
+  opencode debug scrap         list all known projects
+  opencode debug skill         list all available skills
+  opencode debug snapshot      snapshot debugging utilities
+  opencode debug startup       print startup timing
+  opencode debug agent <name>  show agent configuration details
+  opencode debug v2            debug v2 catalog and built-in plugins
+  opencode debug info          show debug information
+  opencode debug paths         show global paths (data, config, cache, state)
+  opencode debug wait          wait indefinitely (for debugging)
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers --help 1`] = `
+"opencode providers
+
+manage AI providers and credentials
+
+Commands:
+  opencode providers list         list providers and credentials                       [aliases: ls]
+  opencode providers login [url]  log in to a provider
+  opencode providers logout       log out from a configured provider
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode agent --help 1`] = `
+"opencode agent
+
+manage agents
+
+Commands:
+  opencode agent create  create a new agent
+  opencode agent list    list all available agents
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode upgrade --help 1`] = `
+"opencode upgrade [target]
+
+upgrade opencode to the latest or a specific version
+
+Positionals:
+  target  version to upgrade to, for ex '0.1.48' or 'v0.1.48'                               [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -m, --method      installation method to use
+                          [string] [choices: "curl", "npm", "pnpm", "bun", "brew", "choco", "scoop"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode uninstall --help 1`] = `
+"opencode uninstall
+
+uninstall opencode and remove all related files
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+  -c, --keep-config  keep configuration files                             [boolean] [default: false]
+  -d, --keep-data    keep session data and snapshots                      [boolean] [default: false]
+      --dry-run      show what would be removed without removing          [boolean] [default: false]
+  -f, --force        skip confirmation prompts                            [boolean] [default: false]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode serve --help 1`] = `
+"opencode serve
+
+starts a headless opencode server
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+      --port         port to listen on                                         [number] [default: 0]
+      --hostname     hostname to listen on                           [string] [default: "127.0.0.1"]
+      --mdns         enable mDNS service discovery (defaults hostname to 0.0.0.0)
+                                                                          [boolean] [default: false]
+      --mdns-domain  custom domain name for mDNS service (default: opencode.local)
+                                                                [string] [default: "opencode.local"]
+      --cors         additional domains to allow for CORS                      [array] [default: []]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode web --help 1`] = `
+"opencode web
+
+start opencode server and open web interface
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+      --port         port to listen on                                         [number] [default: 0]
+      --hostname     hostname to listen on                           [string] [default: "127.0.0.1"]
+      --mdns         enable mDNS service discovery (defaults hostname to 0.0.0.0)
+                                                                          [boolean] [default: false]
+      --mdns-domain  custom domain name for mDNS service (default: opencode.local)
+                                                                [string] [default: "opencode.local"]
+      --cors         additional domains to allow for CORS                      [array] [default: []]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode models --help 1`] = `
+"opencode models [provider]
+
+list all available models
+
+Positionals:
+  provider  provider ID to filter models by                                                 [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --verbose     use more verbose model output (includes metadata like costs)           [boolean]
+      --refresh     refresh the models cache from models.dev                               [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode stats --help 1`] = `
+"opencode stats
+
+show token usage and cost statistics
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --days        show stats for the last N days (default: all time)                      [number]
+      --tools       number of tools to show (default: all)                                  [number]
+      --models      show model statistics (default: hidden). Pass a number to show top N, otherwise
+                    shows all
+      --project     filter by project (default: all projects, empty string: current project)[string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode export --help 1`] = `
+"opencode export [sessionID]
+
+export session data as JSON
+
+Positionals:
+  sessionID  session id to export                                                           [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --sanitize    redact sensitive transcript and file data                              [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode import --help 1`] = `
+"opencode import <file>
+
+import session data from JSON file or URL
+
+Positionals:
+  file  path to JSON file or share URL                                           [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode github --help 1`] = `
+"opencode github
+
+manage GitHub agent
+
+Commands:
+  opencode github install  install the GitHub agent
+  opencode github run      run the GitHub agent
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode pr --help 1`] = `
+"opencode pr <number>
+
+fetch and checkout a GitHub PR branch, then run opencode
+
+Positionals:
+  number  PR number to checkout                                                  [number] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode session --help 1`] = `
+"opencode session
+
+manage sessions
+
+Commands:
+  opencode session list                list sessions
+  opencode session delete <sessionID>  delete a session
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode plugin --help 1`] = `
+"opencode plugin <module>
+
+install plugin and update config
+
+Positionals:
+  module  npm module name                                                        [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -g, --global      install in global config                              [boolean] [default: false]
+  -f, --force       replace existing plugin version                       [boolean] [default: false]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode db --help 1`] = `
+"opencode db
+
+database tools
+
+Commands:
+  opencode db [query]     open an interactive sqlite3 shell or run a query                 [default]
+  opencode db path        print the database path
+  opencode db migrate     migrate JSON data to SQLite (merges with existing data)
+
+Positionals:
+  query  SQL query to execute                                                               [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --format      Output format                 [string] [choices: "json", "tsv"] [default: "tsv"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp list --help 1`] = `
+"opencode mcp list
+
+list MCP servers and their status
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp add --help 1`] = `
+"opencode mcp add
+
+add an MCP server
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp auth --help 1`] = `
+"opencode mcp auth [name]
+
+authenticate with an OAuth-enabled MCP server
+
+Commands:
+  opencode mcp auth list  list OAuth-capable MCP servers and their auth status         [aliases: ls]
+
+Positionals:
+  name  name of the MCP server                                                              [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp logout --help 1`] = `
+"opencode mcp logout [name]
+
+remove OAuth credentials for an MCP server
+
+Positionals:
+  name  name of the MCP server                                                              [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers list --help 1`] = `
+"opencode providers list
+
+list providers and credentials
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers login --help 1`] = `
+"opencode providers login [url]
+
+log in to a provider
+
+Positionals:
+  url  opencode auth provider                                                               [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -p, --provider    provider id or name to log in to (skips provider selection)             [string]
+  -m, --method      login method label (skips method selection)                             [string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers logout --help 1`] = `
+"opencode providers logout
+
+log out from a configured provider
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode agent create --help 1`] = `
+"opencode agent create
+
+create a new agent
+
+Options:
+  -h, --help                  show help                                                    [boolean]
+  -v, --version               show version number                                          [boolean]
+      --print-logs            print logs to stderr                                         [boolean]
+      --log-level             log level         [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure                  run without external plugins                                 [boolean]
+      --path                  directory path to generate the agent file                     [string]
+      --description           what the agent should do                                      [string]
+      --mode                  agent mode            [string] [choices: "all", "primary", "subagent"]
+      --permissions, --tools  comma-separated list of permissions to allow (default: all).
+                              Available: "bash, read, edit, glob, grep, webfetch, task, todowrite,
+                              websearch, lsp, skill"                                        [string]
+  -m, --model                 model to use in the format of provider/model                  [string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode agent list --help 1`] = `
+"opencode agent list
+
+list all available agents
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode session list --help 1`] = `
+"opencode session list
+
+list sessions
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -n, --max-count   limit to N most recent sessions                                         [number]
+      --format      output format             [string] [choices: "table", "json"] [default: "table"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode session delete --help 1`] = `
+"opencode session delete <sessionID>
+
+delete a session
+
+Positionals:
+  sessionID  session ID to delete                                                [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode github install --help 1`] = `
+"opencode github install
+
+install the GitHub agent
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode github run --help 1`] = `
+"opencode github run
+
+run the GitHub agent
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --event       GitHub mock event to run the agent for                                  [string]
+      --token       GitHub personal access token (github_pat_********)                      [string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode db path --help 1`] = `
+"opencode db path
+
+print the database path
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
@@ -0,0 +1,134 @@
+// Help-text snapshots for every CLI command + key subcommand. Catches
+// accidental flag removals, renames, and reordering in a single sweep —
+// any change to the user-visible CLI surface shows up here as a diff.
+//
+// This is the broad coverage layer that makes the future Effect CLI
+// migration (yargs → effect-smol/cli) safe to attempt: if a refactor
+// preserves the surface, the snapshots stay green; if it doesn't, the
+// diff tells you exactly which command(s) changed.
+//
+// Snapshots are taken at COLUMNS=120 so wrapping is stable across
+// terminal sizes. The default opencode tui command is excluded —
+// `opencode --help` includes an ASCII banner that pulls in the install
+// version (changes per release), so we'd snapshot a moving target.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import fs from "node:fs"
+import os from "node:os"
+import { cliIt } from "../../lib/cli-process"
+
+// Strips dynamic content that varies per run so snapshots are stable.
+// Currently only the tmpdir prefix bleeds in (via `--cwd` defaults that
+// resolve to `process.cwd()`). Add new patterns here as they surface.
+//
+// On macOS `os.tmpdir()` returns `/var/folders/...` but `process.cwd()`
+// inside the child returns the realpath `/private/var/folders/...` — so
+// we strip both forms.
+const TMP = os.tmpdir()
+const REAL_TMP = fs.realpathSync(TMP)
+function normalize(text: string): string {
+  return (
+    text
+      .replaceAll(REAL_TMP, "<TMPDIR>")
+      .replaceAll(TMP, "<TMPDIR>")
+      .replace(/<TMPDIR>\/oc-cli-[a-z0-9]+/g, "<HOME>")
+      // yargs wraps the `[string] [default: "..."]` clause based on the
+      // pre-normalized default's character length, so different random home
+      // path widths produce different leading-whitespace counts on the
+      // wrapped continuation. Collapse the wrap-dependent whitespace.
+      .replace(/\s+\[string\] \[default: "<HOME>"\]/g, ' [string] [default: "<HOME>"]')
+  )
+}
+
+// Top-level commands. Order matches what `opencode --help` prints today;
+// keep it in that order so the snapshot file reads as a table of contents.
+// `completion` is intentionally excluded — it's a yargs built-in that emits
+// top-level help on `--help` and exits 1; not a real opencode command.
+const TOP_LEVEL = [
+  "acp",
+  "mcp",
+  "attach",
+  "run",
+  "debug",
+  "providers", // aliased to `auth`
+  "agent",
+  "upgrade",
+  "uninstall",
+  "serve",
+  "web",
+  "models",
+  "stats",
+  "export",
+  "import",
+  "github",
+  "pr",
+  "session",
+  "plugin",
+  "db",
+] as const
+
+// Subcommands worth pinning. Not exhaustive — the goal is one snapshot per
+// distinct argv shape, not every leaf. Add new entries when a subcommand
+// gains user-visible flags that we want to lock in.
+const SUBCOMMANDS = [
+  ["mcp", "list"],
+  ["mcp", "add"],
+  ["mcp", "auth"],
+  ["mcp", "logout"],
+  ["providers", "list"],
+  ["providers", "login"],
+  ["providers", "logout"],
+  ["agent", "create"],
+  ["agent", "list"],
+  ["session", "list"],
+  ["session", "delete"],
+  ["github", "install"],
+  ["github", "run"],
+  ["db", "path"],
+] as const
+
+// Fixed wrap width so a developer's terminal doesn't affect snapshots.
+// yargs honors COLUMNS; CI runners typically default to 80 which produces
+// different wraps from a 200-col local terminal.
+const SNAPSHOT_ENV = { COLUMNS: "120" }
+
+describe("opencode CLI help-text snapshots", () => {
+  // Single test, parallel spawns. Each command's help fires under
+  // `concurrency: 8` — wall-clock stays under ~10s even for ~35 commands,
+  // versus ~1 minute if we serialized.
+  cliIt.live(
+    "every documented command emits stable help text",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const argvs: Array<readonly string[]> = [...TOP_LEVEL.map((c) => [c] as const), ...SUBCOMMANDS]
+
+        // Spawn in parallel, then assert in argv order so snapshot output is
+        // deterministic and per-command failures don't abort the rest of
+        // the sweep. `Effect.partition` is the canonical "run all, separate
+        // failures from successes" primitive — no mutable accumulator needed.
+        const [failures, results] = yield* Effect.partition(
+          argvs,
+          (argv) =>
+            Effect.gen(function* () {
+              const result = yield* opencode.spawn([...argv, "--help"], { env: SNAPSHOT_ENV })
+              if (result.exitCode !== 0) {
+                return yield* Effect.fail(`opencode ${argv.join(" ")}: exit ${result.exitCode}`)
+              }
+              return { argv, result }
+            }),
+          { concurrency: 8 },
+        )
+
+        for (const { argv, result } of results) {
+          // yargs writes --help to stderr, not stdout. Snapshotting stderr
+          // means our test catches the help body; stdout for these commands
+          // is expected to be empty.
+          expect(normalize(result.stderr)).toMatchSnapshot(`opencode ${argv.join(" ")} --help`)
+        }
+        if (failures.length > 0) {
+          throw new Error(`Help text failed for:\n  ${failures.join("\n  ")}`)
+        }
+      }),
+    180_000,
+  )
+})
@@ -0,0 +1,84 @@
+// Subprocess integration tests for `opencode run` (non-interactive mode).
+// These exercise the real CLI binary against a TestLLMServer running in the
+// same process. See `test/lib/cli-process.ts` for the harness — each test uses
+// `opencode.run(message, opts?)` to spawn `bun src/index.ts run ...` with
+// `OPENCODE_CONFIG_CONTENT` providing the test provider config inline.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+
+describe("opencode run (non-interactive subprocess)", () => {
+  // Happy path: prompt completes, output reaches stdout, process exits 0.
+  // If this fails, all the others likely will too — debug here first.
+  cliIt.live(
+    "exits 0 and writes the response to stdout on a successful prompt",
+    ({ llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* llm.text("hello from the test llm")
+        const result = yield* opencode.run("say hi")
+        opencode.expectExit(result, 0)
+        expect(result.stdout).toContain("hello from the test llm")
+      }),
+    60_000,
+  )
+
+  // Regression for #27371: an unknown model used to hang the process forever
+  // waiting on a session.status === idle event that never arrived. The fix
+  // makes the SDK call surface an error promptly so the process exits nonzero.
+  // We assert nonzero exit AND wall-clock under the harness timeout — a hang
+  // would expire the timeout and produce a different (signal-killed) failure.
+  cliIt.live(
+    "exits nonzero promptly when the model is unknown (regression for #27371)",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const result = yield* opencode.run("say hi", {
+          model: "test/nonexistent-model",
+          timeoutMs: 15_000,
+        })
+        expect(result.exitCode).not.toBe(0)
+        expect(result.durationMs).toBeLessThan(15_000)
+      }),
+    30_000,
+  )
+
+  // Locks in the current behavior: when the LLM stream errors mid-response
+  // (the prompt was accepted, then the upstream provider failed), opencode
+  // emits a session.error event and the process exits 0 today.
+  //
+  // This is debatable — a future cleanup might flip it to exit 1. If you're
+  // changing this expectation, do it deliberately and say so in the PR.
+  cliIt.live(
+    "mid-stream LLM error still exits 0 today (contract lock-in)",
+    ({ llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* llm.fail("upstream provider exploded mid-stream")
+        const result = yield* opencode.run("trigger midstream error", { timeoutMs: 30_000 })
+        expect(result.exitCode).toBe(0)
+      }),
+    60_000,
+  )
+
+  // --format json puts one JSON object per line on stdout for each emitted
+  // event. Consumers (CI scripts, tooling) parse this stream. Asserts the
+  // shape so a future event-emit change has to update this expectation.
+  cliIt.live(
+    "--format json emits parseable line-delimited JSON to stdout",
+    ({ llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* llm.text("structured output")
+        const result = yield* opencode.run("say hi", { format: "json" })
+        opencode.expectExit(result, 0)
+
+        const events = opencode.parseJsonEvents(result.stdout)
+        expect(events.length).toBeGreaterThan(0)
+        for (const evt of events) {
+          expect(typeof evt.type).toBe("string")
+          expect(typeof evt.sessionID).toBe("string")
+        }
+        // At least one `text` event should appear with the LLM's response.
+        const text = events.find((e) => e.type === "text")
+        expect(text).toBeDefined()
+      }),
+    60_000,
+  )
+})
@@ -0,0 +1,61 @@
+// Subprocess integration tests for `opencode serve`. Spawns the real CLI in
+// headless mode and exercises it over HTTP — this is the only test tier that
+// catches bugs spanning argv → server boot → routing → instance loading.
+//
+// `serve` is long-lived: the harness returns a handle (url/port/kill/exited)
+// and kills the process when the test scope closes. The OS-assigned port is
+// parsed off the "listening on http://..." line.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { HttpClient } from "effect/unstable/http"
+import { cliIt } from "../../lib/cli-process"
+
+describe("opencode serve (subprocess)", () => {
+  // Smoke test: server starts, binds a port, and /global/health responds.
+  // If this fails, all other serve tests likely will too — debug here first.
+  cliIt.live(
+    "starts, binds a port, and serves /global/health",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const server = yield* opencode.serve()
+        expect(server.port).toBeGreaterThan(0)
+        expect(server.url).toMatch(/^http:\/\//)
+
+        const client = yield* HttpClient.HttpClient
+        const res = yield* client.get(`${server.url}/global/health`)
+        expect(res.status).toBe(200)
+        // GlobalHealth schema is { success: true, ... } | { success: false, error }.
+        // We don't lock in further shape here — any 200 with parseable JSON is
+        // enough proof the routing + auth-bypass + instance loading is alive.
+        const body = yield* res.json
+        expect(body).toBeDefined()
+      }),
+    60_000,
+  )
+
+  // The scope-close finalizer must actually terminate the child. Without this
+  // test a regression in the kill path (e.g. a future refactor that forgets
+  // to wire the finalizer) would leak processes on every test run.
+  cliIt.live(
+    "kills the subprocess on scope close",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        // Inner scope so we can observe `.exited` resolving after it closes.
+        const exitedPromise = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const server = yield* opencode.serve()
+            // Capture the Promise, not the resolved value — scope closes after
+            // this gen returns, at which point the finalizer kills the child.
+            return server.exited
+          }),
+        )
+        // After scope close: finalizer fired, process must have exited.
+        const code = yield* Effect.promise(() => exitedPromise)
+        // Bun reports the exit code; SIGTERM-killed processes return non-null
+        // (typically 143 on POSIX). We just require resolution within a sane
+        // window — anything else means the kill didn't take.
+        expect(typeof code === "number" || code === null).toBe(true)
+      }),
+    60_000,
+  )
+})
@@ -1,5 +1,5 @@
 import { test, expect, describe, mock, afterEach, beforeEach } from "bun:test"
-import { Effect, Layer, Option } from "effect"
+import { Effect, Exit, Layer, Option } from "effect"
 import { NodeFileSystem, NodePath } from "@effect/platform-node"
 import { Config } from "@/config/config"
 import { ConfigManaged } from "@/config/managed"
@@ -13,7 +13,7 @@ import { Account } from "../../src/account/account"
 import { AccessToken, AccountID, OrgID } from "../../src/account/schema"
 import { AppFileSystem } from "@opencode-ai/core/filesystem"
 import { Env } from "../../src/env"
-import { provideTestInstance, provideTmpdirInstance, withTestInstance } from "../fixture/fixture"
+import { provideTestInstance, provideTmpdirInstance, TestInstance, withTestInstance } from "../fixture/fixture"
 import { tmpdir } from "../fixture/fixture"
 import { InstanceRuntime } from "@/project/instance-runtime"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
@@ -68,13 +68,6 @@ const load = (ctx: InstanceContext) =>
  Effect.runPromise(
    Config.Service.use((svc) => provideCurrentInstance(svc.get(), ctx)).pipe(Effect.scoped, Effect.provide(layer)),
  )
-const save = (config: Config.Info, ctx: InstanceContext) =>
-  Effect.runPromise(
-    Config.Service.use((svc) => provideCurrentInstance(svc.update(config), ctx)).pipe(
-      Effect.scoped,
-      Effect.provide(layer),
-    ),
-  )
 const saveGlobal = (config: Config.Info) =>
  Effect.runPromise(
    Config.Service.use((svc) => svc.updateGlobal(config)).pipe(
@@ -94,14 +87,6 @@ const listDirs = (ctx: InstanceContext) =>
      Effect.provide(layer),
    ),
  )
-const ready = (ctx: InstanceContext) =>
-  Effect.runPromise(
-    Config.Service.use((svc) => provideCurrentInstance(svc.waitForDependencies(), ctx)).pipe(
-      Effect.scoped,
-      Effect.provide(layer),
-    ),
-  )
-
 // Get managed config directory from environment (set in preload.ts)
 const managedConfigDir = process.env.OPENCODE_TEST_MANAGED_CONFIG_DIR!

@@ -123,6 +108,25 @@ async function writeConfig(dir: string, config: object, name = "opencode.json")
  await Filesystem.write(path.join(dir, name), JSON.stringify(config))
 }

+const writeConfigEffect = (dir: string, config: object, name = "opencode.json") =>
+  Effect.promise(() => writeConfig(dir, config, name))
+
+function withProcessEnv<A, E, R>(key: string, value: string, effect: Effect.Effect<A, E, R>) {
+  return Effect.acquireUseRelease(
+    Effect.sync(() => {
+      const original = process.env[key]
+      process.env[key] = value
+      return original
+    }),
+    () => effect,
+    (original) =>
+      Effect.sync(() => {
+        if (original !== undefined) process.env[key] = original
+        else delete process.env[key]
+      }),
+  )
+}
+
 async function check(map: (dir: string) => string) {
  if (process.platform !== "win32") return
  await using globalTmp = await tmpdir()
@@ -210,67 +214,42 @@ test("does not create global config when OPENCODE_CONFIG_DIR is set", async () =
  }
 })

-test("loads JSON config file", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        model: "test/model",
-        username: "testuser",
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.model).toBe("test/model")
-      expect(config.username).toBe("testuser")
-    },
-  })
-})
+it.instance(
+  "loads JSON config file",
+  Effect.gen(function* () {
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.model).toBe("test/model")
+    expect(config.username).toBe("testuser")
+  }),
+  { config: { model: "test/model", username: "testuser" } },
+)

-test("loads shell config field", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        shell: "bash",
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.shell).toBe("bash")
-    },
-  })
-})
+it.instance(
+  "loads shell config field",
+  Effect.gen(function* () {
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.shell).toBe("bash")
+  }),
+  { config: { shell: "bash" } },
+)

-test("updates config and preserves empty shell sentinel", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(
-        dir,
-        {
-          $schema: "https://opencode.ai/config.json",
-          shell: "bash",
-        },
-        "config.json",
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      await save({ shell: "" }, ctx)
+it.instance("updates config and preserves empty shell sentinel", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(
+      test.directory,
+      { $schema: "https://opencode.ai/config.json", shell: "bash" },
+      "config.json",
+    )

-      const writtenConfig = await Filesystem.readJson<{ shell?: string }>(path.join(tmp.path, "config.json"))
-      expect(writtenConfig.shell).toBe("")
-    },
-  })
-})
+    yield* Config.Service.use((svc) => svc.update(ConfigParse.schema(Config.Info, { shell: "" }, "test:config")))
+
+    const writtenConfig = yield* Effect.promise(() =>
+      Filesystem.readJson<{ shell?: string }>(path.join(test.directory, "config.json")),
+    )
+    expect(writtenConfig.shell).toBe("")
+  }),
+)

 test("updates global config and omits empty shell key in json", async () => {
  await using tmp = await tmpdir({
@@ -330,41 +309,23 @@ test("updates global config and omits empty shell key in jsonc", async () => {
  }
 })

-test("loads formatter boolean config", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        formatter: true,
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.formatter).toBe(true)
-    },
-  })
-})
+it.instance(
+  "loads formatter boolean config",
+  Effect.gen(function* () {
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.formatter).toBe(true)
+  }),
+  { config: { formatter: true } },
+)

-test("loads lsp boolean config", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        lsp: true,
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.lsp).toBe(true)
-    },
-  })
-})
+it.instance(
+  "loads lsp boolean config",
+  Effect.gen(function* () {
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.lsp).toBe(true)
+  }),
+  { config: { lsp: true } },
+)

 test("loads project config from Git Bash and MSYS2 paths on Windows", async () => {
  // Git Bash and MSYS2 both use /<drive>/... paths on Windows.
@@ -405,124 +366,118 @@ test("ignores legacy tui keys in opencode config", async () => {
  })
 })

-test("loads JSONC config file", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Filesystem.write(
-        path.join(dir, "opencode.jsonc"),
+it.instance("loads JSONC config file", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* Effect.promise(() =>
+      Filesystem.write(
+        path.join(test.directory, "opencode.jsonc"),
        `{
        // This is a comment
        "$schema": "https://opencode.ai/config.json",
        "model": "test/model",
        "username": "testuser"
      }`,
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.model).toBe("test/model")
-      expect(config.username).toBe("testuser")
-    },
-  })
-})
+      ),
+    )
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.model).toBe("test/model")
+    expect(config.username).toBe("testuser")
+  }),
+)

-test("jsonc overrides json in the same directory", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(
-        dir,
-        {
-          $schema: "https://opencode.ai/config.json",
-          model: "base",
-          username: "base",
-        },
-        "opencode.jsonc",
-      )
-      await writeConfig(dir, {
+it.instance("jsonc overrides json in the same directory", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(
+      test.directory,
+      {
        $schema: "https://opencode.ai/config.json",
-        model: "override",
+        model: "base",
+        username: "base",
+      },
+      "opencode.jsonc",
+    )
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      model: "override",
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.model).toBe("base")
+    expect(config.username).toBe("base")
+  }),
+)
+
+it.instance("handles environment variable substitution", () =>
+  withProcessEnv(
+    "TEST_VAR",
+    "test-user",
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      yield* writeConfigEffect(test.directory, {
+        $schema: "https://opencode.ai/config.json",
+        username: "{env:TEST_VAR}",
      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.model).toBe("base")
-      expect(config.username).toBe("base")
-    },
-  })
-})
+      const config = yield* Config.Service.use((svc) => svc.get())
+      expect(config.username).toBe("test-user")
+    }),
+  ),
+)

-test("handles environment variable substitution", async () => {
-  const originalEnv = process.env["TEST_VAR"]
-  process.env["TEST_VAR"] = "test-user"
-
-  try {
-    await using tmp = await tmpdir({
-      init: async (dir) => {
-        await writeConfig(dir, {
-          $schema: "https://opencode.ai/config.json",
-          username: "{env:TEST_VAR}",
-        })
-      },
-    })
-    await withTestInstance({
-      directory: tmp.path,
-      fn: async (ctx) => {
-        const config = await load(ctx)
-        expect(config.username).toBe("test-user")
-      },
-    })
-  } finally {
-    if (originalEnv !== undefined) {
-      process.env["TEST_VAR"] = originalEnv
-    } else {
-      delete process.env["TEST_VAR"]
-    }
-  }
-})
-
-test("preserves env variables when adding $schema to config", async () => {
-  const originalEnv = process.env["PRESERVE_VAR"]
-  process.env["PRESERVE_VAR"] = "secret_value"
-
-  try {
-    await using tmp = await tmpdir({
-      init: async (dir) => {
-        // Config without $schema - should trigger auto-add
-        await Filesystem.write(
-          path.join(dir, "opencode.json"),
+it.instance("preserves env variables when adding $schema to config", () =>
+  withProcessEnv(
+    "PRESERVE_VAR",
+    "secret_value",
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      // Config without $schema - should trigger auto-add
+      yield* Effect.promise(() =>
+        Filesystem.write(
+          path.join(test.directory, "opencode.json"),
          JSON.stringify({
            username: "{env:PRESERVE_VAR}",
          }),
-        )
-      },
-    })
-    await withTestInstance({
-      directory: tmp.path,
-      fn: async (ctx) => {
-        const config = await load(ctx)
-        expect(config.username).toBe("secret_value")
+        ),
+      )
+      const config = yield* Config.Service.use((svc) => svc.get())
+      expect(config.username).toBe("secret_value")

-        // Read the file to verify the env variable was preserved
-        const content = await Filesystem.readText(path.join(tmp.path, "opencode.json"))
-        expect(content).toContain("{env:PRESERVE_VAR}")
-        expect(content).not.toContain("secret_value")
-        expect(content).toContain("$schema")
-      },
+      // Read the file to verify the env variable was preserved
+      const content = yield* Effect.promise(() => Filesystem.readText(path.join(test.directory, "opencode.json")))
+      expect(content).toContain("{env:PRESERVE_VAR}")
+      expect(content).not.toContain("secret_value")
+      expect(content).toContain("$schema")
+    }),
+  ),
+)
+
+it.instance("handles file inclusion substitution", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* Effect.promise(() => Filesystem.write(path.join(test.directory, "included.txt"), "test-user"))
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      username: "{file:included.txt}",
    })
-  } finally {
-    if (originalEnv !== undefined) {
-      process.env["PRESERVE_VAR"] = originalEnv
-    } else {
-      delete process.env["PRESERVE_VAR"]
-    }
-  }
-})
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.username).toBe("test-user")
+  }),
+)
+
+it.instance("handles file inclusion with replacement tokens", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* Effect.promise(() =>
+      Filesystem.write(path.join(test.directory, "included.md"), "const out = await Bun.$`echo hi`"),
+    )
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      username: "{file:included.md}",
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.username).toBe("const out = await Bun.$`echo hi`")
+  }),
+)

 test("resolves env templates in account config with account token", async () => {
  const originalControlToken = process.env["OPENCODE_CONSOLE_TOKEN"]
@@ -589,218 +544,132 @@ test("resolves env templates in account config with account token", async () =>
  }
 })

-test("handles file inclusion substitution", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Filesystem.write(path.join(dir, "included.txt"), "test-user")
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        username: "{file:included.txt}",
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.username).toBe("test-user")
-    },
-  })
-})
+it.instance("validates config schema and throws on invalid fields", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      invalid_field: "should cause error",
+    })
+    const exit = yield* Config.Service.use((svc) => svc.get()).pipe(Effect.exit)
+    expect(Exit.isFailure(exit)).toBe(true)
+  }),
+)

-test("handles file inclusion with replacement tokens", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Filesystem.write(path.join(dir, "included.md"), "const out = await Bun.$`echo hi`")
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        username: "{file:included.md}",
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.username).toBe("const out = await Bun.$`echo hi`")
-    },
-  })
-})
+it.instance("throws error for invalid JSON", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* Effect.promise(() => Filesystem.write(path.join(test.directory, "opencode.json"), "{ invalid json }"))
+    const exit = yield* Config.Service.use((svc) => svc.get()).pipe(Effect.exit)
+    expect(Exit.isFailure(exit)).toBe(true)
+  }),
+)

-test("validates config schema and throws on invalid fields", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        invalid_field: "should cause error",
-      })
-    },
-  })
-  await provideTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      // Strict schema should throw an error for invalid fields
-      await expect(load(ctx)).rejects.toThrow()
-    },
-  })
-})
-
-test("throws error for invalid JSON", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Filesystem.write(path.join(dir, "opencode.json"), "{ invalid json }")
-    },
-  })
-  await provideTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      await expect(load(ctx)).rejects.toThrow()
-    },
-  })
-})
-
-test("handles agent configuration", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        agent: {
-          test_agent: {
-            model: "test/model",
-            temperature: 0.7,
-            description: "test agent",
-          },
-        },
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.agent?.["test_agent"]).toEqual(
-        expect.objectContaining({
+it.instance("handles agent configuration", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      agent: {
+        test_agent: {
          model: "test/model",
          temperature: 0.7,
          description: "test agent",
-        }),
-      )
-    },
-  })
-})
-
-test("treats agent variant as model-scoped setting (not provider option)", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        agent: {
-          test_agent: {
-            model: "openai/gpt-5.2",
-            variant: "xhigh",
-            max_tokens: 123,
-          },
        },
-      })
-    },
-  })
-
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      const agent = config.agent?.["test_agent"]
-
-      expect(agent?.variant).toBe("xhigh")
-      expect(agent?.options).toMatchObject({
-        max_tokens: 123,
-      })
-      expect(agent?.options).not.toHaveProperty("variant")
-    },
-  })
-})
-
-test("handles command configuration", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await writeConfig(dir, {
-        $schema: "https://opencode.ai/config.json",
-        command: {
-          test_command: {
-            template: "test template",
-            description: "test command",
-            agent: "test_agent",
-          },
-        },
-      })
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.command?.["test_command"]).toEqual({
-        template: "test template",
-        description: "test command",
-        agent: "test_agent",
-      })
-    },
-  })
-})
-
-test("migrates autoshare to share field", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Filesystem.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-          autoshare: true,
-        }),
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.share).toBe("auto")
-      expect(config.autoshare).toBe(true)
-    },
-  })
-})
-
-test("migrates mode field to agent field", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Filesystem.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-          mode: {
-            test_mode: {
-              model: "test/model",
-              temperature: 0.5,
-            },
-          },
-        }),
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const config = await load(ctx)
-      expect(config.agent?.["test_mode"]).toEqual({
+      },
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.agent?.["test_agent"]).toEqual(
+      expect.objectContaining({
        model: "test/model",
-        temperature: 0.5,
-        mode: "primary",
-        options: {},
-        permission: {},
-      })
-    },
-  })
-})
+        temperature: 0.7,
+        description: "test agent",
+      }),
+    )
+  }),
+)
+
+it.instance("treats agent variant as model-scoped setting (not provider option)", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      agent: {
+        test_agent: {
+          model: "openai/gpt-5.2",
+          variant: "xhigh",
+          max_tokens: 123,
+        },
+      },
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    const agent = config.agent?.["test_agent"]
+
+    expect(agent?.variant).toBe("xhigh")
+    expect(agent?.options).toMatchObject({
+      max_tokens: 123,
+    })
+    expect(agent?.options).not.toHaveProperty("variant")
+  }),
+)
+
+it.instance("handles command configuration", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      command: {
+        test_command: {
+          template: "test template",
+          description: "test command",
+          agent: "test_agent",
+        },
+      },
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.command?.["test_command"]).toEqual({
+      template: "test template",
+      description: "test command",
+      agent: "test_agent",
+    })
+  }),
+)
+
+it.instance("migrates autoshare to share field", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      autoshare: true,
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.share).toBe("auto")
+    expect(config.autoshare).toBe(true)
+  }),
+)
+
+it.instance("migrates mode field to agent field", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* writeConfigEffect(test.directory, {
+      $schema: "https://opencode.ai/config.json",
+      mode: {
+        test_mode: {
+          model: "test/model",
+          temperature: 0.5,
+        },
+      },
+    })
+    const config = yield* Config.Service.use((svc) => svc.get())
+    expect(config.agent?.["test_mode"]).toEqual({
+      model: "test/model",
+      temperature: 0.5,
+      mode: "primary",
+      options: {},
+      permission: {},
+    })
+  }),
+)

 test("loads config from .opencode directory", async () => {
  await using tmp = await tmpdir({
@@ -1002,30 +871,26 @@ Nested command template`,
  })
 })

-test("updates config and writes to file", async () => {
-  await using tmp = await tmpdir()
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const newConfig = { model: "updated/model" }
-      await save(newConfig as any, ctx)
+it.instance("updates config and writes to file", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    yield* Config.Service.use((svc) =>
+      svc.update(ConfigParse.schema(Config.Info, { model: "updated/model" }, "test:config")),
+    )

-      const writtenConfig = await Filesystem.readJson<{ model: string }>(path.join(tmp.path, "config.json"))
-      expect(writtenConfig.model).toBe("updated/model")
-    },
-  })
-})
+    const writtenConfig = yield* Effect.promise(() =>
+      Filesystem.readJson<{ model: string }>(path.join(test.directory, "config.json")),
+    )
+    expect(writtenConfig.model).toBe("updated/model")
+  }),
+)

-test("gets config directories", async () => {
-  await using tmp = await tmpdir()
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      const dirs = await listDirs(ctx)
-      expect(dirs.length).toBeGreaterThanOrEqual(1)
-    },
-  })
-})
+it.instance("gets config directories", () =>
+  Effect.gen(function* () {
+    const dirs = yield* Config.Service.use((svc) => svc.directories())
+    expect(dirs.length).toBeGreaterThanOrEqual(1)
+  }),
+)

 test("does not try to install dependencies in read-only OPENCODE_CONFIG_DIR", async () => {
  if (process.platform === "win32") return
@@ -62,6 +62,7 @@ describe("RuntimeFlags", () => {
      expect(flags.experimentalEventSystem).toBe(true)
      expect(flags.experimentalWorkspaces).toBe(true)
      expect(flags.experimentalIconDiscovery).toBe(true)
+      expect(flags.experimentalNativeLlm).toBe(true)
      expect(flags.client).toBe("desktop")
    }),
  )
@@ -80,6 +81,16 @@ describe("RuntimeFlags", () => {
    }),
  )

+  it.effect("enables native LLM via dedicated or umbrella flag", () =>
+    Effect.gen(function* () {
+      const explicit = yield* readFlags.pipe(Effect.provide(fromConfig({ OPENCODE_EXPERIMENTAL_NATIVE_LLM: "true" })))
+      const umbrella = yield* readFlags.pipe(Effect.provide(fromConfig({ OPENCODE_EXPERIMENTAL: "true" })))
+
+      expect(explicit.experimentalNativeLlm).toBe(true)
+      expect(umbrella.experimentalNativeLlm).toBe(true)
+    }),
+  )
+
  it.effect("layer accepts partial test overrides and fills defaults from Config definitions", () =>
    Effect.gen(function* () {
      const flags = yield* readFlags.pipe(
@@ -0,0 +1,424 @@
+// Subprocess test harness for the opencode CLI. Spawns the real binary against
+// a TestLLMServer running in-process at a random port, with full env isolation.
+//
+// This is the missing test tier: in-process tests can't catch bugs that span
+// argv parsing → server boot → SDK call → event consumption → exit code (like
+// the original /event race or #27371's invalid-model hang).
+//
+// Configuration flows through opencode's built-in test affordances:
+//   - OPENCODE_CONFIG_CONTENT      : provider config inline, no files to find
+//   - OPENCODE_TEST_HOME           : pins os.homedir() → tmpdir
+//   - OPENCODE_DISABLE_PROJECT_CONFIG : skip walking up for opencode.json
+//   - OPENCODE_PURE                : skip external plugin discovery + install
+//   - OPENCODE_DISABLE_AUTOUPDATE / AUTOCOMPACT / MODELS_FETCH : no background work
+// Plus HOME / XDG_* pointing at the tmpdir for belt-and-suspenders isolation.
+//
+// Today only `opencode.run` is fully wired. The shape supports adding more
+// builders (`opencode.serve(opts)`, `opencode.acp(opts)`, `opencode.auth(...)`)
+// without changing the fixture. Long-lived commands like `serve` will need a
+// different return shape — see the TODO at the bottom of OpencodeCli.
+import type { TestOptions } from "bun:test"
+import { Deferred, Duration, Effect, Layer, Queue, Scope, Stream } from "effect"
+import { FetchHttpClient, HttpClient } from "effect/unstable/http"
+import path from "node:path"
+import fs from "node:fs/promises"
+import os from "node:os"
+import { Process } from "@/util/process"
+import { TestLLMServer } from "./llm-server"
+import { testProviderConfig } from "./test-provider"
+import { it } from "./effect"
+
+const opencodeRoot = path.resolve(import.meta.dir, "../../")
+const cliEntry = path.join(opencodeRoot, "src/index.ts")
+
+export const testModelID = "test/test-model"
+
+// Wrap a Bun subprocess pipe (or any ReadableStream<Uint8Array>) as a Stream.
+// Centralizes the `evaluate` + `onError` boilerplate and tags errors with the
+// stream name so a stderr/stdout failure is greppable in logs.
+function fromBunStream(name: string, get: () => ReadableStream<Uint8Array>) {
+  return Stream.fromReadableStream({
+    evaluate: get,
+    onError: (cause) => new Error(`${name} stream error: ${String(cause)}`),
+  })
+}
+
+// Long-lived processes (serve, acp) all want the same stderr drain: read every
+// chunk, push to a tail buffer, swallow stream errors (the child closing the
+// pipe is normal). `log: true` surfaces a real protocol error to logs so a
+// regression doesn't silently disappear.
+function forkStderrDrain(stream: ReadableStream<Uint8Array>, into: string[]) {
+  return Effect.forkScoped(
+    fromBunStream("stderr", () => stream).pipe(
+      Stream.decodeText(),
+      Stream.runForEach((chunk) => Effect.sync(() => into.push(chunk))),
+      Effect.ignore({ log: true }),
+    ),
+  )
+}
+
+function isolatedEnv(home: string, configJson: string): Record<string, string> {
+  return {
+    OPENCODE_TEST_HOME: home,
+    HOME: home,
+    XDG_CONFIG_HOME: path.join(home, ".config"),
+    XDG_DATA_HOME: path.join(home, ".local/share"),
+    XDG_STATE_HOME: path.join(home, ".local/state"),
+    XDG_CACHE_HOME: path.join(home, ".cache"),
+    OPENCODE_CONFIG_CONTENT: configJson,
+    OPENCODE_DISABLE_PROJECT_CONFIG: "1",
+    OPENCODE_PURE: "1",
+    OPENCODE_DISABLE_AUTOUPDATE: "1",
+    OPENCODE_DISABLE_AUTOCOMPACT: "1",
+    OPENCODE_DISABLE_MODELS_FETCH: "1",
+    OPENCODE_AUTH_CONTENT: "{}",
+  }
+}
+
+export type RunResult = {
+  readonly exitCode: number
+  readonly stdout: string
+  readonly stderr: string
+  readonly durationMs: number
+}
+
+export type SpawnOpts = { readonly timeoutMs?: number; readonly env?: Record<string, string> }
+
+// Typed equivalent of constructing argv for `opencode run`. New flags should
+// land here so tests stay grep-able and refactor-safe.
+export type RunOpts = SpawnOpts & {
+  readonly model?: string
+  readonly agent?: string
+  readonly format?: "default" | "json"
+  readonly command?: string
+  readonly printLogs?: boolean
+  readonly extraArgs?: string[]
+}
+
+// `opencode serve` is a long-lived process — it never exits on its own.
+// `serve(opts)` therefore returns a handle inside the caller's Scope: the
+// subprocess is killed when the scope closes (test end), and the URL the
+// server actually bound to (port 0 means OS-assigned) is parsed off stdout.
+export type ServeOpts = SpawnOpts & {
+  readonly port?: number
+  readonly hostname?: string
+  readonly extraArgs?: string[]
+  // How long to wait for the "listening on http://..." line before failing.
+  // Default 15s — startup is dominated by bun's transpile + plugin init, not
+  // the actual listen() call.
+  readonly readyTimeoutMs?: number
+}
+
+export type ServeHandle = {
+  // Full URL the server is bound to, e.g. "http://127.0.0.1:54321". Use this
+  // as the base for HTTP requests in tests — never assume the port.
+  readonly url: string
+  readonly hostname: string
+  readonly port: number
+  // Sends SIGTERM. The scope finalizer also calls this, so tests rarely need
+  // to invoke it directly — useful for tests that assert exit behavior.
+  readonly kill: () => void
+  // Resolves with the exit code once the process exits. Bun returns a number.
+  readonly exited: Promise<number>
+}
+
+// `opencode acp` speaks newline-delimited JSON-RPC over stdin/stdout. It is
+// long-lived and exits cleanly when stdin is closed. The handle exposes the
+// duplex stream as send/receive rather than raw pipes so tests don't have to
+// reimplement framing on every call site.
+export type AcpOpts = SpawnOpts & {
+  readonly cwd?: string
+  readonly extraArgs?: string[]
+}
+
+export type AcpHandle = {
+  // Writes a single JSON-RPC message to the child's stdin as one ndjson line.
+  readonly send: (msg: object) => Effect.Effect<void>
+  // Resolves with the next parsed JSON-RPC line from the child's stdout.
+  // Lines are buffered in a queue so multiple receives in a row won't drop
+  // anything. Pair with `Effect.timeout` if a test wants a deadline.
+  readonly receive: Effect.Effect<unknown>
+  // Closes stdin. ACP exits cleanly on stdin EOF; the scope finalizer also
+  // calls this, so tests only need it when asserting exit behavior.
+  readonly close: () => void
+  readonly exited: Promise<number>
+}
+
+export type OpencodeCli = {
+  // High-level: run a single prompt against the test model. Short-lived.
+  readonly run: (message: string, opts?: RunOpts) => Effect.Effect<RunResult>
+  // Spawn `opencode serve` and wait until it's listening. Long-lived: the
+  // returned handle is killed when the caller's Scope closes. Fails if the
+  // listening line doesn't appear within `readyTimeoutMs`.
+  readonly serve: (opts?: ServeOpts) => Effect.Effect<ServeHandle, Error, Scope.Scope>
+  // Spawn `opencode acp` and return a duplex JSON-RPC handle. Long-lived:
+  // the subprocess exits on stdin close, which the scope finalizer triggers.
+  readonly acp: (opts?: AcpOpts) => Effect.Effect<AcpHandle, Error, Scope.Scope>
+  // Escape hatch: any CLI invocation with full control over argv. Used to test
+  // commands that don't yet have a typed builder.
+  readonly spawn: (args: string[], opts?: SpawnOpts) => Effect.Effect<RunResult>
+  // Convenience assertion. Dumps captured stderr/stdout on mismatch so CI
+  // failures are debuggable without re-running locally.
+  readonly expectExit: (result: RunResult, expected: number, label?: string) => void
+  // Parse `--format json` stdout into one event object per non-empty line.
+  // The CLI writes `JSON.stringify({ type, sessionID, ... }) + EOL` for each
+  // event (see src/cli/cmd/run.ts `emit`). Throws on a malformed line so
+  // tests fail loudly rather than silently skipping data.
+  readonly parseJsonEvents: (stdout: string) => Array<Record<string, unknown>>
+}
+
+export type CliFixture = {
+  readonly llm: TestLLMServer["Service"]
+  readonly home: string
+  readonly opencode: OpencodeCli
+}
+
+// Provisions a TestLLMServer + tmpdir + spawn helper and invokes fn. Cleans
+// up the tmpdir on scope exit. TestLLMServer.layer is provided internally so
+// the caller doesn't need to wire it up — the fixture's lifetime is tied to
+// the surrounding Scope.
+export function withCliFixture<A, E>(
+  fn: (input: CliFixture) => Effect.Effect<A, E, Scope.Scope | HttpClient.HttpClient>,
+): Effect.Effect<A, E | unknown, Scope.Scope> {
+  return Effect.gen(function* () {
+    const llm = yield* TestLLMServer
+
+    const home = path.join(os.tmpdir(), "oc-cli-" + Math.random().toString(36).slice(2))
+    yield* Effect.promise(() => fs.mkdir(home, { recursive: true }))
+    yield* Effect.addFinalizer(() =>
+      Effect.promise(() => fs.rm(home, { recursive: true, force: true }).catch(() => undefined)),
+    )
+
+    const configJson = JSON.stringify(testProviderConfig(llm.url))
+    const env = isolatedEnv(home, configJson)
+
+    const spawn = (args: string[], opts?: SpawnOpts): Effect.Effect<RunResult> =>
+      Effect.promise(async () => {
+        const start = Date.now()
+        // Process.run pipes stdout/stderr by default and returns them as Buffers.
+        const result = await Process.run(["bun", "run", "--conditions=browser", cliEntry, ...args], {
+          cwd: home,
+          timeout: opts?.timeoutMs ?? 30_000,
+          env: { ...process.env, ...env, ...opts?.env },
+          nothrow: true,
+        })
+        return {
+          exitCode: result.code,
+          stdout: result.stdout.toString(),
+          stderr: result.stderr.toString(),
+          durationMs: Date.now() - start,
+        }
+      })
+
+    const run = (message: string, opts?: RunOpts): Effect.Effect<RunResult> => {
+      const argv: string[] = ["run"]
+      if (opts?.printLogs) argv.push("--print-logs")
+      argv.push("--model", opts?.model ?? testModelID)
+      if (opts?.agent) argv.push("--agent", opts.agent)
+      if (opts?.format) argv.push("--format", opts.format)
+      if (opts?.command) argv.push("--command", opts.command)
+      if (opts?.extraArgs) argv.push(...opts.extraArgs)
+      argv.push(message)
+      return spawn(argv, opts)
+    }
+
+    const serve = Effect.fn("opencode.serve")(function* (opts?: ServeOpts) {
+      const argv = ["serve"]
+      // Default port 0 — let the OS pick a free port, parse the actual one
+      // off stdout. Hard-coded ports flake under parallel tests.
+      argv.push("--port", String(opts?.port ?? 0))
+      if (opts?.hostname) argv.push("--hostname", opts.hostname)
+      if (opts?.extraArgs) argv.push(...opts.extraArgs)
+
+      // Acquire the subprocess; release sends SIGTERM and awaits exit on
+      // scope close. Wrapped in Effect.ignore so a flaky kill doesn't surface
+      // as a finalizer error during test teardown.
+      const proc = yield* Effect.acquireRelease(
+        Effect.sync(() =>
+          Bun.spawn(["bun", "run", "--conditions=browser", cliEntry, ...argv], {
+            cwd: home,
+            env: { ...process.env, ...env, ...opts?.env },
+            stdout: "pipe",
+            stderr: "pipe",
+          }),
+        ),
+        (p) =>
+          Effect.promise(() => {
+            p.kill()
+            return p.exited
+          }).pipe(Effect.ignore),
+      )
+
+      // Tail buffer so timeout failures can include stderr context. The fork
+      // also keeps the OS pipe buffer from filling and wedging the child.
+      const stderrChunks: string[] = []
+      yield* forkStderrDrain(proc.stderr, stderrChunks)
+
+      // Watch stdout line-by-line for the listening sentinel. Format
+      // (see src/cli/cmd/serve.ts):
+      //   "opencode server listening on http://<host>:<port>"
+      const readyRe = /listening on (http:\/\/([^\s:]+):(\d+))/
+      const readyDeferred = yield* Deferred.make<{ url: string; hostname: string; port: number }>()
+      yield* Effect.forkScoped(
+        fromBunStream("stdout", () => proc.stdout).pipe(
+          Stream.decodeText(),
+          Stream.splitLines,
+          Stream.runForEach((line) => {
+            const m = line.match(readyRe)
+            return m ? Deferred.succeed(readyDeferred, { url: m[1], hostname: m[2], port: Number(m[3]) }) : Effect.void
+          }),
+          Effect.ignore({ log: true }),
+        ),
+      )
+
+      const readyTimeoutMs = opts?.readyTimeoutMs ?? 15_000
+      const match = yield* Deferred.await(readyDeferred).pipe(
+        Effect.timeoutOrElse({
+          duration: Duration.millis(readyTimeoutMs),
+          orElse: () =>
+            Effect.fail(
+              new Error(
+                `opencode serve did not become ready within ${readyTimeoutMs}ms\n` +
+                  `stderr (last 2000):\n${stderrChunks.join("").slice(-2000)}`,
+              ),
+            ),
+        }),
+      )
+
+      return {
+        url: match.url,
+        hostname: match.hostname,
+        port: match.port,
+        kill: () => {
+          proc.kill()
+        },
+        exited: proc.exited as Promise<number>,
+      } satisfies ServeHandle
+    })
+
+    const acp = Effect.fn("opencode.acp")(function* (opts?: AcpOpts) {
+      const argv = ["acp"]
+      if (opts?.cwd) argv.push("--cwd", opts.cwd)
+      if (opts?.extraArgs) argv.push(...opts.extraArgs)
+
+      // Acquire the subprocess. Release ends stdin (clean shutdown — ACP exits
+      // on stdin EOF) and falls back to SIGTERM if it doesn't exit promptly.
+      // Either way we await proc.exited so the test scope doesn't leak.
+      const proc = yield* Effect.acquireRelease(
+        Effect.sync(() =>
+          Bun.spawn(["bun", "run", "--conditions=browser", cliEntry, ...argv], {
+            cwd: opts?.cwd ?? home,
+            env: { ...process.env, ...env, ...opts?.env },
+            stdin: "pipe",
+            stdout: "pipe",
+            stderr: "pipe",
+          }),
+        ),
+        (p) =>
+          // Graceful shutdown: close stdin (ACP exits on EOF), give it a
+          // window to exit, then SIGTERM. The Effect.timeoutOrElse expresses
+          // exactly that race without raw setTimeout or Promise.race.
+          Effect.gen(function* () {
+            yield* Effect.sync(() => p.stdin.end())
+            yield* Effect.promise(() => p.exited).pipe(
+              Effect.timeoutOrElse({
+                duration: Duration.seconds(2),
+                orElse: () =>
+                  Effect.sync(() => {
+                    p.kill()
+                  }),
+              }),
+            )
+            yield* Effect.promise(() => p.exited)
+          }).pipe(Effect.ignore),
+      )
+
+      const stderrChunks: string[] = []
+      yield* forkStderrDrain(proc.stderr, stderrChunks)
+
+      // Each ndjson line becomes one queue entry. JSON.parse failures are
+      // surfaced as the raw string so a malformed protocol message doesn't
+      // silently wedge the test in `receive`.
+      const responses = yield* Queue.unbounded<unknown>()
+      yield* Effect.forkScoped(
+        fromBunStream("stdout", () => proc.stdout).pipe(
+          Stream.decodeText(),
+          Stream.splitLines,
+          Stream.runForEach((line) => {
+            if (line.length === 0) return Effect.void
+            let parsed: unknown
+            try {
+              parsed = JSON.parse(line)
+            } catch {
+              parsed = { _rawLine: line }
+            }
+            return Queue.offer(responses, parsed)
+          }),
+          Effect.ignore({ log: true }),
+        ),
+      )
+
+      return {
+        // `proc.stdin.write` returns `number | Promise<number>`. The promise
+        // form is the backpressure signal — if we don't await it, rapid
+        // successive sends can interleave under pipe-buffer-full conditions
+        // and corrupt the ndjson framing.
+        send: (msg: object) =>
+          Effect.promise(async () => {
+            const ret = proc.stdin.write(JSON.stringify(msg) + "\n")
+            if (typeof ret !== "number") await ret
+          }),
+        receive: Queue.take(responses),
+        // proc.stdin.end() is idempotent in Bun; no try/catch needed.
+        close: () => proc.stdin.end(),
+        exited: proc.exited as Promise<number>,
+      } satisfies AcpHandle
+    })
+
+    const opencode: OpencodeCli = { run, serve, acp, spawn, expectExit, parseJsonEvents }
+
+    return yield* fn({ llm, home, opencode })
+    // FetchHttpClient is provided so test bodies can `yield* HttpClient.HttpClient`
+    // and hit endpoints on `opencode.serve()` without rolling their own fetch.
+  }).pipe(Effect.provide(Layer.mergeAll(TestLLMServer.layer, FetchHttpClient.layer)))
+}
+
+function parseJsonEvents(stdout: string): Array<Record<string, unknown>> {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as Record<string, unknown>)
+}
+
+// Convenience for the common assertion pattern. Dumps stderr/stdout when
+// the exit code doesn't match — saves debugging time on CI failures.
+function expectExit(result: RunResult, expected: number, label = "opencode") {
+  if (result.exitCode === expected) return
+  const tail = (s: string, n: number) => (s.length > n ? "..." + s.slice(-n) : s)
+  // eslint-disable-next-line no-console
+  console.error(`[${label}] expected exit ${expected}, got ${result.exitCode} after ${result.durationMs}ms`)
+  // eslint-disable-next-line no-console
+  console.error(`[${label}] stderr (last 2000):\n${tail(result.stderr, 2000)}`)
+  // eslint-disable-next-line no-console
+  console.error(`[${label}] stdout (last 500):\n${tail(result.stdout, 500)}`)
+  throw new Error(`${label}: expected exit ${expected}, got ${result.exitCode}`)
+}
+
+// `cliIt.live(name, fixture => effect)` is the same as
+// `it.live(name, () => withCliFixture(fixture))` — one fewer nesting level at
+// every call site. Use this for any test that needs the opencode CLI fixture.
+//
+// Only `.live` is exposed because subprocess tests must run against the real
+// clock — a TestClock-paused environment can't drive a child process. If you
+// need `.only` or `.skip`, fall back to `it.live` + `withCliFixture` directly.
+// Body's R is `Scope.Scope | never` so tests can yield* scope-requiring
+// resources (e.g. `opencode.serve`) without an extra `Effect.scoped` wrapper —
+// `withCliFixture`'s outer scope is the natural lifetime.
+export const cliIt = {
+  live: <A, E>(
+    name: string,
+    body: (input: CliFixture) => Effect.Effect<A, E, Scope.Scope | HttpClient.HttpClient>,
+    opts?: number | TestOptions,
+  ) => it.live(name, () => withCliFixture(body), opts),
+}
@@ -0,0 +1,37 @@
+// Shared provider config for tests that need opencode to talk to a fake LLM
+// over a real HTTP endpoint. Registers a single provider `test` with a single
+// model `test-model` (i.e. `--model test/test-model`), pointed at the URL the
+// caller supplies (typically a TestLLMServer instance).
+//
+// Used by:
+//   - test/lib/run-process.ts          (subprocess CLI tests)
+//   - test/server/httpapi-sdk.test.ts  (in-process SDK tests)
+export function testProviderConfig(llmUrl: string) {
+  return {
+    formatter: false,
+    lsp: false,
+    provider: {
+      test: {
+        name: "Test",
+        id: "test",
+        env: [],
+        npm: "@ai-sdk/openai-compatible",
+        models: {
+          "test-model": {
+            id: "test-model",
+            name: "Test Model",
+            attachment: false,
+            reasoning: false,
+            temperature: false,
+            tool_call: true,
+            release_date: "2025-01-01",
+            limit: { context: 100_000, output: 10_000 },
+            cost: { input: 0, output: 0 },
+            options: {},
+          },
+        },
+        options: { apiKey: "test-key", baseURL: llmUrl },
+      },
+    },
+  }
+}
@@ -87,10 +87,6 @@ async function getModel(providerID: ProviderID, modelID: ModelID, ctx: InstanceC
  return run(ctx, (provider) => provider.getModel(providerID, modelID))
 }

-async function getLanguage(model: Provider.Model, ctx: InstanceContext) {
-  return run(ctx, (provider) => provider.getLanguage(model))
-}
-
 async function closest(providerID: ProviderID, query: string[], ctx: InstanceContext) {
  return run(ctx, (provider) => provider.closest(providerID, query))
 }
@@ -99,10 +95,6 @@ async function getSmallModel(providerID: ProviderID, ctx: InstanceContext) {
  return run(ctx, (provider) => provider.getSmallModel(providerID))
 }

-async function defaultModel(ctx: InstanceContext) {
-  return run(ctx, (provider) => provider.defaultModel())
-}
-
 function paid(providers: Awaited<ReturnType<typeof list>>) {
  const item = providers[ProviderID.make("opencode")]
  expect(item).toBeDefined()
@@ -361,62 +353,42 @@ it.instance(
  },
 )

-test("env variable takes precedence, config merges options", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Bun.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-          provider: {
-            anthropic: {
-              options: {
-                timeout: 60000,
-                chunkTimeout: 15000,
-              },
-            },
+it.instance(
+  "env variable takes precedence, config merges options",
+  Effect.gen(function* () {
+    yield* setProcessEnv("ANTHROPIC_API_KEY", "env-api-key")
+    const providers = yield* Provider.Service.use((provider) => provider.list())
+    expect(providers[ProviderID.anthropic]).toBeDefined()
+    // Config options should be merged
+    expect(providers[ProviderID.anthropic].options.timeout).toBe(60000)
+    expect(providers[ProviderID.anthropic].options.chunkTimeout).toBe(15000)
+  }),
+  {
+    config: {
+      provider: {
+        anthropic: {
+          options: {
+            timeout: 60000,
+            chunkTimeout: 15000,
          },
-        }),
-      )
+        },
+      },
    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      await set(ctx, "ANTHROPIC_API_KEY", "env-api-key")
-      const providers = await list(ctx)
-      expect(providers[ProviderID.anthropic]).toBeDefined()
-      // Config options should be merged
-      expect(providers[ProviderID.anthropic].options.timeout).toBe(60000)
-      expect(providers[ProviderID.anthropic].options.chunkTimeout).toBe(15000)
-    },
-  })
-})
+  },
+)

-test("getModel returns model for valid provider/model", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Bun.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-        }),
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      await set(ctx, "ANTHROPIC_API_KEY", "test-api-key")
-      const model = await getModel(ProviderID.anthropic, ModelID.make("claude-sonnet-4-20250514"), ctx)
-      expect(model).toBeDefined()
-      expect(String(model.providerID)).toBe("anthropic")
-      expect(String(model.id)).toBe("claude-sonnet-4-20250514")
-      const language = await getLanguage(model, ctx)
-      expect(language).toBeDefined()
-    },
-  })
-})
+it.instance("getModel returns model for valid provider/model", () =>
+  Effect.gen(function* () {
+    yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key")
+    const provider = yield* Provider.Service
+    const model = yield* provider.getModel(ProviderID.anthropic, ModelID.make("claude-sonnet-4-20250514"))
+    expect(model).toBeDefined()
+    expect(String(model.providerID)).toBe("anthropic")
+    expect(String(model.id)).toBe("claude-sonnet-4-20250514")
+    const language = yield* provider.getLanguage(model)
+    expect(language).toBeDefined()
+  }),
+)

 test("getModel throws ModelNotFoundError for invalid model", async () => {
  await using tmp = await tmpdir({
@@ -469,50 +441,25 @@ test("parseModel handles model IDs with slashes", () => {
  expect(String(result.modelID)).toBe("anthropic/claude-3-opus")
 })

-test("defaultModel returns first available model when no config set", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Bun.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-        }),
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      await set(ctx, "ANTHROPIC_API_KEY", "test-api-key")
-      const model = await defaultModel(ctx)
-      expect(model.providerID).toBeDefined()
-      expect(model.modelID).toBeDefined()
-    },
-  })
-})
+it.instance("defaultModel returns first available model when no config set", () =>
+  Effect.gen(function* () {
+    yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key")
+    const model = yield* Provider.Service.use((provider) => provider.defaultModel())
+    expect(model.providerID).toBeDefined()
+    expect(model.modelID).toBeDefined()
+  }),
+)

-test("defaultModel respects config model setting", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      await Bun.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-          model: "anthropic/claude-sonnet-4-20250514",
-        }),
-      )
-    },
-  })
-  await withTestInstance({
-    directory: tmp.path,
-    fn: async (ctx) => {
-      await set(ctx, "ANTHROPIC_API_KEY", "test-api-key")
-      const model = await defaultModel(ctx)
-      expect(String(model.providerID)).toBe("anthropic")
-      expect(String(model.modelID)).toBe("claude-sonnet-4-20250514")
-    },
-  })
-})
+it.instance(
+  "defaultModel respects config model setting",
+  Effect.gen(function* () {
+    yield* setProcessEnv("ANTHROPIC_API_KEY", "test-api-key")
+    const model = yield* Provider.Service.use((provider) => provider.defaultModel())
+    expect(String(model.providerID)).toBe("anthropic")
+    expect(String(model.modelID)).toBe("claude-sonnet-4-20250514")
+  }),
+  { config: { model: "anthropic/claude-sonnet-4-20250514" } },
+)

 it.instance(
  "provider with baseURL from config",
@@ -23,6 +23,7 @@ import path from "path"
 import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, TestInstance, tmpdirScoped } from "../fixture/fixture"
 import { awaitWithTimeout, testEffect } from "../lib/effect"
+import { testProviderConfig } from "../lib/test-provider"

 const noopBootstrap = Layer.succeed(InstanceBootstrap.Service, InstanceBootstrap.Service.of({ run: Effect.void }))
 const it = testEffect(
@@ -99,39 +100,6 @@ function authorization(username: string, password: string) {
  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`
 }

-function providerConfig(url: string) {
-  return {
-    formatter: false,
-    lsp: false,
-    provider: {
-      test: {
-        name: "Test",
-        id: "test",
-        env: [],
-        npm: "@ai-sdk/openai-compatible",
-        models: {
-          "test-model": {
-            id: "test-model",
-            name: "Test Model",
-            attachment: false,
-            reasoning: false,
-            temperature: false,
-            tool_call: true,
-            release_date: "2025-01-01",
-            limit: { context: 100000, output: 10000 },
-            cost: { input: 0, output: 0 },
-            options: {},
-          },
-        },
-        options: {
-          apiKey: "test-key",
-          baseURL: url,
-        },
-      },
-    },
-  }
-}
-
 function call<T>(request: () => Promise<T>) {
  return Effect.promise(request)
 }
@@ -283,7 +251,7 @@ function withStandardProject<A, E>(
 function withFakeLlm<A, E>(serverPath: ServerPath, run: (input: LlmProjectFixture) => Effect.Effect<A, E, TestScope>) {
  return Effect.gen(function* () {
    const llm = yield* TestLLMServer
-    return yield* withProject(serverPath, { config: providerConfig(llm.url) }, (input) => run({ ...input, llm }))
+    return yield* withProject(serverPath, { config: testProviderConfig(llm.url) }, (input) => run({ ...input, llm }))
  }).pipe(Effect.provide(TestLLMServer.layer))
 }

@@ -297,7 +265,7 @@ function withFakeLlmProject<A, E>(
    return yield* withProject(
      serverPath,
      {
-        config: providerConfig(llm.url),
+        config: testProviderConfig(llm.url),
        setup: options.setup,
      },
      (input) => run({ ...input, llm }),
@@ -30,6 +30,7 @@ import { TestConfig } from "../fixture/config"
 import { SyncEvent } from "@/sync"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { EventV2Bridge } from "@/event-v2-bridge"
+import { LLMEvent, Usage } from "@opencode-ai/llm"

 void Log.init({ print: false })

@@ -47,6 +48,10 @@ const ref = {
  modelID: ModelID.make("test-model"),
 }

+const usage = (input: ConstructorParameters<typeof Usage>[0]) => new Usage(input)
+
+const basicUsage = () => usage({ inputTokens: 1, outputTokens: 1, totalTokens: 2 })
+
 afterEach(() => {
  mock.restore()
 })
@@ -296,11 +301,11 @@ function readCompactionPart(sessionID: SessionID) {

 function llm() {
  const queue: Array<
-    Stream.Stream<LLM.Event, unknown> | ((input: LLM.StreamInput) => Stream.Stream<LLM.Event, unknown>)
+    Stream.Stream<LLMEvent, unknown> | ((input: LLM.StreamInput) => Stream.Stream<LLMEvent, unknown>)
  > = []

  return {
-    push(stream: Stream.Stream<LLM.Event, unknown> | ((input: LLM.StreamInput) => Stream.Stream<LLM.Event, unknown>)) {
+    push(stream: Stream.Stream<LLMEvent, unknown> | ((input: LLM.StreamInput) => Stream.Stream<LLMEvent, unknown>)) {
      queue.push(stream)
    },
    layer: Layer.succeed(
@@ -319,54 +324,22 @@ function llm() {
 function reply(
  text: string,
  capture?: (input: LLM.StreamInput) => void,
-): (input: LLM.StreamInput) => Stream.Stream<LLM.Event, unknown> {
+): (input: LLM.StreamInput) => Stream.Stream<LLMEvent, unknown> {
  return (input) => {
    capture?.(input)
    return Stream.make(
-      { type: "start" } satisfies LLM.Event,
-      { type: "text-start", id: "txt-0" } satisfies LLM.Event,
-      { type: "text-delta", id: "txt-0", delta: text, text } as LLM.Event,
-      { type: "text-end", id: "txt-0" } satisfies LLM.Event,
-      {
-        type: "finish-step",
-        finishReason: "stop",
-        rawFinishReason: "stop",
-        response: { id: "res", modelId: "test-model", timestamp: new Date() },
-        providerMetadata: undefined,
-        usage: {
-          inputTokens: 1,
-          outputTokens: 1,
-          totalTokens: 2,
-          inputTokenDetails: {
-            noCacheTokens: undefined,
-            cacheReadTokens: undefined,
-            cacheWriteTokens: undefined,
-          },
-          outputTokenDetails: {
-            textTokens: undefined,
-            reasoningTokens: undefined,
-          },
-        },
-      } satisfies LLM.Event,
-      {
-        type: "finish",
-        finishReason: "stop",
-        rawFinishReason: "stop",
-        totalUsage: {
-          inputTokens: 1,
-          outputTokens: 1,
-          totalTokens: 2,
-          inputTokenDetails: {
-            noCacheTokens: undefined,
-            cacheReadTokens: undefined,
-            cacheWriteTokens: undefined,
-          },
-          outputTokenDetails: {
-            textTokens: undefined,
-            reasoningTokens: undefined,
-          },
-        },
-      } satisfies LLM.Event,
+      LLMEvent.textStart({ id: "txt-0" }),
+      LLMEvent.textDelta({ id: "txt-0", text }),
+      LLMEvent.textEnd({ id: "txt-0" }),
+      LLMEvent.stepFinish({
+        index: 0,
+        reason: "stop",
+        usage: basicUsage(),
+      }),
+      LLMEvent.finish({
+        reason: "stop",
+        usage: basicUsage(),
+      }),
    )
  }
 }
@@ -1204,7 +1177,7 @@ describe("session.compaction.process", () => {
        Stream.fromAsyncIterable(
          {
            async *[Symbol.asyncIterator]() {
-              yield { type: "start" } as LLM.Event
+              yield LLMEvent.stepStart({ index: 0 })
              throw new APICallError({
                message: "boom",
                url: "https://example.com/v1/chat/completions",
@@ -1290,55 +1263,62 @@ describe("session.compaction.process", () => {
    { git: true },
  )

+  itCompaction.instance(
+    "silently drops reasoning-delta arriving without prior reasoning-start",
+    () => {
+      // Regression: PR initially auto-created a reasoning Part for orphan deltas (no preceding
+      // reasoning-start). Reverted to match dev — drop silently. Pinned here so any future
+      // change to processor.ts reasoning-delta handling triggers this test.
+      const stub = llm()
+      stub.push(
+        Stream.make(
+          LLMEvent.reasoningDelta({ id: "orphan-1", text: "stray reasoning" }),
+          LLMEvent.textStart({ id: "txt-0" }),
+          LLMEvent.textDelta({ id: "txt-0", text: "summary" }),
+          LLMEvent.textEnd({ id: "txt-0" }),
+          LLMEvent.stepFinish({ index: 0, reason: "stop", usage: basicUsage() }),
+          LLMEvent.finish({ reason: "stop", usage: basicUsage() }),
+        ),
+      )
+      return Effect.gen(function* () {
+        const ssn = yield* SessionNs.Service
+        const session = yield* ssn.create({})
+        const msg = yield* createUserMessage(session.id, "hello")
+        const msgs = yield* ssn.messages({ sessionID: session.id })
+        yield* SessionCompaction.use.process({
+          parentID: msg.id,
+          messages: msgs,
+          sessionID: session.id,
+          auto: false,
+        })
+
+        const summary = (yield* ssn.messages({ sessionID: session.id })).find(
+          (item) => item.info.role === "assistant" && item.info.summary,
+        )
+        expect(summary?.parts.some((part) => part.type === "reasoning")).toBe(false)
+        // Sanity: the text part still got through.
+        expect(summary?.parts.some((part) => part.type === "text" && part.text === "summary")).toBe(true)
+      }).pipe(withCompaction({ llm: stub.layer }))
+    },
+    { git: true },
+  )
+
  itCompaction.instance(
    "does not allow tool calls while generating the summary",
    () => {
      const stub = llm()
      stub.push(
        Stream.make(
-          { type: "start" } satisfies LLM.Event,
-          { type: "tool-input-start", id: "call-1", toolName: "_noop" } satisfies LLM.Event,
-          { type: "tool-call", toolCallId: "call-1", toolName: "_noop", input: {} } satisfies LLM.Event,
-          {
-            type: "finish-step",
-            finishReason: "tool-calls",
-            rawFinishReason: "tool_calls",
-            response: { id: "res", modelId: "test-model", timestamp: new Date() },
-            providerMetadata: undefined,
-            usage: {
-              inputTokens: 1,
-              outputTokens: 1,
-              totalTokens: 2,
-              inputTokenDetails: {
-                noCacheTokens: undefined,
-                cacheReadTokens: undefined,
-                cacheWriteTokens: undefined,
-              },
-              outputTokenDetails: {
-                textTokens: undefined,
-                reasoningTokens: undefined,
-              },
-            },
-          } satisfies LLM.Event,
-          {
-            type: "finish",
-            finishReason: "tool-calls",
-            rawFinishReason: "tool_calls",
-            totalUsage: {
-              inputTokens: 1,
-              outputTokens: 1,
-              totalTokens: 2,
-              inputTokenDetails: {
-                noCacheTokens: undefined,
-                cacheReadTokens: undefined,
-                cacheWriteTokens: undefined,
-              },
-              outputTokenDetails: {
-                textTokens: undefined,
-                reasoningTokens: undefined,
-              },
-            },
-          } satisfies LLM.Event,
+          LLMEvent.toolCall({ id: "call-1", name: "_noop", input: {} }),
+          LLMEvent.stepFinish({
+            index: 0,
+            reason: "tool-calls",
+            usage: basicUsage(),
+          }),
+          LLMEvent.finish({
+            reason: "tool-calls",
+            usage: basicUsage(),
+          }),
        ),
      )
      return Effect.gen(function* () {
@@ -1544,20 +1524,7 @@ describe("SessionNs.getUsage", () => {
    const model = createModel({ context: 100_000, output: 32_000 })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1000,
-        outputTokens: 500,
-        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 1000, outputTokens: 500, totalTokens: 1500 }),
    })

    expect(result.tokens.input).toBe(1000)
@@ -1571,20 +1538,7 @@ describe("SessionNs.getUsage", () => {
    const model = createModel({ context: 100_000, output: 32_000 })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1000,
-        outputTokens: 500,
-        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: 800,
-          cacheReadTokens: 200,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 1000, outputTokens: 500, totalTokens: 1500, cacheReadInputTokens: 200 }),
    })

    expect(result.tokens.input).toBe(800)
@@ -1595,20 +1549,7 @@ describe("SessionNs.getUsage", () => {
    const model = createModel({ context: 100_000, output: 32_000 })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1000,
-        outputTokens: 500,
-        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 1000, outputTokens: 500, totalTokens: 1500 }),
      metadata: {
        anthropic: {
          cacheCreationInputTokens: 300,
@@ -1624,20 +1565,7 @@ describe("SessionNs.getUsage", () => {
    // AI SDK v6 normalizes inputTokens to include cached tokens for all providers
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1000,
-        outputTokens: 500,
-        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: 800,
-          cacheReadTokens: 200,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 1000, outputTokens: 500, totalTokens: 1500, cacheReadInputTokens: 200 }),
      metadata: {
        anthropic: {},
      },
@@ -1651,20 +1579,7 @@ describe("SessionNs.getUsage", () => {
    const model = createModel({ context: 100_000, output: 32_000 })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1000,
-        outputTokens: 500,
-        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: 400,
-          reasoningTokens: 100,
-        },
-      },
+      usage: usage({ inputTokens: 1000, outputTokens: 500, reasoningTokens: 100, totalTokens: 1500 }),
    })

    expect(result.tokens.input).toBe(1000)
@@ -1685,20 +1600,7 @@ describe("SessionNs.getUsage", () => {
    })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 0,
-        outputTokens: 1_000_000,
-        totalTokens: 1_000_000,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: 750_000,
-          reasoningTokens: 250_000,
-        },
-      },
+      usage: usage({ inputTokens: 0, outputTokens: 1_000_000, reasoningTokens: 250_000, totalTokens: 1_000_000 }),
    })

    expect(result.tokens.output).toBe(750_000)
@@ -1710,20 +1612,7 @@ describe("SessionNs.getUsage", () => {
    const model = createModel({ context: 100_000, output: 32_000 })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 0,
-        outputTokens: 0,
-        totalTokens: 0,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 0, outputTokens: 0, totalTokens: 0 }),
    })

    expect(result.tokens.input).toBe(0)
@@ -1746,20 +1635,7 @@ describe("SessionNs.getUsage", () => {
    })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1_000_000,
-        outputTokens: 100_000,
-        totalTokens: 1_100_000,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 1_000_000, outputTokens: 100_000, totalTokens: 1_100_000 }),
    })

    expect(result.cost).toBe(3 + 1.5)
@@ -1796,20 +1672,12 @@ describe("SessionNs.getUsage", () => {
    })
    const result = SessionNs.getUsage({
      model,
-      usage: {
+      usage: usage({
        inputTokens: 650_000,
        outputTokens: 100_000,
        totalTokens: 750_000,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: 100_000,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+        cacheReadInputTokens: 100_000,
+      }),
    })

    expect(result.tokens.input).toBe(550_000)
@@ -1841,20 +1709,7 @@ describe("SessionNs.getUsage", () => {
    })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 300_000,
-        outputTokens: 100_000,
-        totalTokens: 400_000,
-        inputTokenDetails: {
-          noCacheTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 300_000, outputTokens: 100_000, totalTokens: 400_000 }),
    })

    expect(result.cost).toBe(0.9 + 0.4)
@@ -1865,24 +1720,16 @@ describe("SessionNs.getUsage", () => {
    (npm) => {
      const model = createModel({ context: 100_000, output: 32_000, npm })
      // AI SDK v6: inputTokens includes cached tokens for all providers
-      const usage = {
+      const item = usage({
        inputTokens: 1000,
        outputTokens: 500,
        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: 800,
-          cacheReadTokens: 200,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      }
+        cacheReadInputTokens: 200,
+      })
      if (npm === "@ai-sdk/amazon-bedrock") {
        const result = SessionNs.getUsage({
          model,
-          usage,
+          usage: item,
          metadata: {
            bedrock: {
              usage: {
@@ -1903,7 +1750,7 @@ describe("SessionNs.getUsage", () => {

      const result = SessionNs.getUsage({
        model,
-        usage,
+        usage: item,
        metadata: {
          anthropic: {
            cacheCreationInputTokens: 300,
@@ -1924,20 +1771,7 @@ describe("SessionNs.getUsage", () => {
    const model = createModel({ context: 100_000, output: 32_000, npm: "@ai-sdk/google-vertex/anthropic" })
    const result = SessionNs.getUsage({
      model,
-      usage: {
-        inputTokens: 1000,
-        outputTokens: 500,
-        totalTokens: 1500,
-        inputTokenDetails: {
-          noCacheTokens: 800,
-          cacheReadTokens: 200,
-          cacheWriteTokens: undefined,
-        },
-        outputTokenDetails: {
-          textTokens: undefined,
-          reasoningTokens: undefined,
-        },
-      },
+      usage: usage({ inputTokens: 1000, outputTokens: 500, totalTokens: 1500, cacheReadInputTokens: 200 }),
      metadata: {
        vertex: {
          cacheCreationInputTokens: 300,
@@ -0,0 +1,283 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { HttpRecorder, Redactor } from "@opencode-ai/http-recorder"
+import { describe, expect } from "bun:test"
+import { tool } from "ai"
+import { Effect, Layer, Stream } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import path from "node:path"
+import z from "zod"
+import { Auth } from "@/auth"
+import { Config } from "@/config/config"
+import { Plugin } from "@/plugin"
+import { Provider } from "@/provider/provider"
+import { ModelID, ProviderID } from "@/provider/schema"
+import { Filesystem } from "@/util/filesystem"
+import { LLMClient, RequestExecutor } from "@opencode-ai/llm/route"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import type { Agent } from "../../src/agent/agent"
+import { LLM } from "../../src/session/llm"
+import { MessageV2 } from "../../src/session/message-v2"
+import { MessageID, SessionID } from "../../src/session/schema"
+import type { ModelsDev } from "@opencode-ai/core/models-dev"
+import { TestInstance } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+
+const OPENAI_CASSETTE = "session/native-openai-tool-call"
+const ZEN_CASSETTE = "session/native-zen-tool-call"
+const FIXTURES_DIR = path.join(import.meta.dir, "../fixtures/recordings")
+const OPENAI_API_KEY = process.env.OPENCODE_RECORD_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY
+const CONSOLE_TOKEN = process.env.OPENCODE_RECORD_CONSOLE_TOKEN
+const ZEN_ORG_ID = process.env.OPENCODE_RECORD_ZEN_ORG_ID
+const ZEN_API_URL =
+  process.env.OPENCODE_RECORD_ZEN_API_URL ?? "https://console.opencode.ai/proxy/connections/fixture/v1"
+
+const shouldRecord = process.env.RECORD === "true"
+const canRunOpenAI = shouldRecord
+  ? Boolean(OPENAI_API_KEY)
+  : HttpRecorder.hasCassetteSync(OPENAI_CASSETTE, { directory: FIXTURES_DIR })
+const canRunZen = shouldRecord
+  ? Boolean(CONSOLE_TOKEN && ZEN_ORG_ID)
+  : HttpRecorder.hasCassetteSync(ZEN_CASSETTE, { directory: FIXTURES_DIR })
+
+async function loadFixture(providerID: string, modelID: string) {
+  const data = await Filesystem.readJson<Record<string, ModelsDev.Provider>>(
+    path.join(import.meta.dir, "../tool/fixtures/models-api.json"),
+  )
+  const provider = data[providerID]
+  if (!provider) throw new Error(`Missing provider in fixture: ${providerID}`)
+  const model = provider.models[modelID]
+  if (!model) throw new Error(`Missing model in fixture: ${modelID}`)
+  return model
+}
+
+const openAIConfig = (model: ModelsDev.Provider["models"][string]): Partial<Config.Info> => ({
+  enabled_providers: ["openai"],
+  provider: {
+    openai: {
+      name: "OpenAI",
+      env: ["OPENAI_API_KEY"],
+      npm: "@ai-sdk/openai",
+      api: "https://api.openai.com/v1",
+      models: {
+        [model.id]: JSON.parse(JSON.stringify(model)) as NonNullable<
+          NonNullable<Config.Info["provider"]>[string]["models"]
+        >[string],
+      },
+      options: {
+        apiKey: OPENAI_API_KEY ?? "fixture-openai-key",
+        baseURL: "https://api.openai.com/v1",
+      },
+    },
+  },
+})
+
+const zenConfig = (model: ModelsDev.Provider["models"][string]): Partial<Config.Info> => ({
+  enabled_providers: ["opencode"],
+  provider: {
+    opencode: {
+      name: "OpenCode Zen",
+      env: ["OPENCODE_CONSOLE_TOKEN"],
+      npm: "@ai-sdk/openai-compatible",
+      api: ZEN_API_URL,
+      models: {
+        [model.id]: JSON.parse(JSON.stringify(model)) as NonNullable<
+          NonNullable<Config.Info["provider"]>[string]["models"]
+        >[string],
+      },
+      options: {
+        apiKey: CONSOLE_TOKEN ?? "fixture-console-token",
+        headers: {
+          "x-org-id": ZEN_ORG_ID ?? "fixture-org",
+        },
+      },
+    },
+  },
+})
+
+function recordedNativeLLMLayer(cassette: string, metadata: Record<string, unknown>) {
+  const cassetteService = HttpRecorder.Cassette.fileSystem({ directory: FIXTURES_DIR }).pipe(
+    Layer.provide(NodeFileSystem.layer),
+  )
+  // Only the HTTP client is recorded; RequestExecutor and the opencode LLM stack remain real.
+  const recorder = HttpRecorder.recordingLayer(cassette, {
+    mode: shouldRecord ? "record" : "replay",
+    metadata,
+    redactor: Redactor.compose(
+      Redactor.defaults({
+        url: {
+          transform: (url) => url.replace(/\/proxy\/connections\/[^/]+\/v1/, "/proxy/connections/{connection}/v1"),
+        },
+      }),
+      {
+        response: (snapshot) => ({ ...snapshot, body: snapshot.body.replace(/wrk_[A-Z0-9]+/g, "wrk_redacted") }),
+      },
+    ),
+  }).pipe(Layer.provide(FetchHttpClient.layer))
+  const executor = RequestExecutor.layer.pipe(Layer.provide(recorder))
+  const client = LLMClient.layer.pipe(Layer.provide(executor))
+
+  const providerLayer = Provider.defaultLayer.pipe(
+    Layer.provide(Auth.defaultLayer),
+    Layer.provide(Config.defaultLayer),
+    Layer.provide(Plugin.defaultLayer),
+  )
+  const llmLayer = LLM.layer.pipe(
+    Layer.provide(Auth.defaultLayer),
+    Layer.provide(Config.defaultLayer),
+    Layer.provide(Provider.defaultLayer),
+    Layer.provide(Plugin.defaultLayer),
+    Layer.provide(client),
+    Layer.provide(cassetteService),
+    Layer.provide(RuntimeFlags.layer({ experimentalNativeLlm: true })),
+  )
+
+  return Layer.mergeAll(providerLayer, llmLayer)
+}
+
+const openAIIt = testEffect(
+  recordedNativeLLMLayer(OPENAI_CASSETTE, {
+    provider: "openai",
+    protocol: "openai-responses",
+    route: "openai-responses",
+    tags: ["opencode", "native", "tool-call"],
+  }),
+)
+const zenIt = testEffect(
+  recordedNativeLLMLayer(ZEN_CASSETTE, {
+    provider: "opencode",
+    protocol: "openai-responses",
+    route: "openai-responses",
+    tags: ["opencode", "zen", "native", "tool-call"],
+  }),
+)
+const recordedOpenAIInstance = canRunOpenAI ? openAIIt.instance : openAIIt.instance.skip
+const recordedZenInstance = canRunZen ? zenIt.instance : zenIt.instance.skip
+
+const writeConfig = (
+  directory: string,
+  model: ModelsDev.Provider["models"][string],
+  config: (model: ModelsDev.Provider["models"][string]) => Partial<Config.Info> = openAIConfig,
+) =>
+  Effect.promise(() =>
+    Bun.write(
+      path.join(directory, "opencode.json"),
+      JSON.stringify({ $schema: "https://opencode.ai/config.json", ...config(model) }),
+    ),
+  )
+
+const getModel = (providerID: ProviderID, modelID: ModelID) =>
+  Effect.gen(function* () {
+    const provider = yield* Provider.Service
+    return yield* provider.getModel(providerID, modelID)
+  })
+
+const collect = (input: LLM.StreamInput) =>
+  Effect.gen(function* () {
+    const llm = yield* LLM.Service
+    return Array.from(yield* llm.stream(input).pipe(Stream.runCollect))
+  })
+
+describe("session.llm native recorded", () => {
+  recordedOpenAIInstance("uses real RequestExecutor with HTTP recorder for native OpenAI tools", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const model = yield* Effect.promise(() => loadFixture("openai", "gpt-4.1-mini"))
+      yield* writeConfig(test.directory, model)
+
+      const sessionID = SessionID.make("session-recorded-native-tool")
+      const agent = {
+        name: "test",
+        mode: "primary",
+        prompt: "Call tools exactly as instructed.",
+        options: {},
+        permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        temperature: 0,
+      } satisfies Agent.Info
+      const resolved = yield* getModel(ProviderID.openai, ModelID.make(model.id))
+      let executed: unknown
+
+      const events = yield* collect({
+        user: {
+          id: MessageID.make("msg_user-recorded-native-tool"),
+          sessionID,
+          role: "user",
+          time: { created: 0 },
+          agent: agent.name,
+          model: { providerID: ProviderID.make("openai"), modelID: ModelID.make(model.id) },
+        } satisfies MessageV2.User,
+        sessionID,
+        model: resolved,
+        agent,
+        system: ["You must call the lookup tool exactly once with query weather. Do not answer in text."],
+        messages: [{ role: "user", content: "Use lookup." }],
+        toolChoice: "required",
+        tools: {
+          lookup: tool({
+            description: "Lookup data.",
+            inputSchema: z.object({ query: z.string() }),
+            execute: async (args, options) => {
+              executed = { args, toolCallId: options.toolCallId }
+              return { output: "looked up" }
+            },
+          }),
+        },
+      })
+
+      expect(events.filter((event) => event.type === "step-finish")).toHaveLength(1)
+      expect(events.filter((event) => event.type === "finish")).toHaveLength(1)
+      expect(events.some((event) => event.type === "tool-result")).toBe(true)
+      expect(executed).toMatchObject({ args: { query: "weather" }, toolCallId: expect.any(String) })
+    }),
+  )
+
+  recordedZenInstance("uses console-managed Zen config with native OpenAI-compatible tools", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const model = yield* Effect.promise(() => loadFixture("opencode", "gpt-5.2-codex"))
+      yield* writeConfig(test.directory, model, zenConfig)
+
+      const sessionID = SessionID.make("session-recorded-native-zen-tool")
+      const agent = {
+        name: "test",
+        mode: "primary",
+        prompt: "Call tools exactly as instructed.",
+        options: {},
+        permission: [{ permission: "*", pattern: "*", action: "allow" }],
+      } satisfies Agent.Info
+      const resolved = yield* getModel(ProviderID.opencode, ModelID.make(model.id))
+      let executed: unknown
+
+      const events = yield* collect({
+        user: {
+          id: MessageID.make("msg_user-recorded-native-zen-tool"),
+          sessionID,
+          role: "user",
+          time: { created: 0 },
+          agent: agent.name,
+          model: { providerID: ProviderID.opencode, modelID: ModelID.make(model.id) },
+        } satisfies MessageV2.User,
+        sessionID,
+        model: resolved,
+        agent,
+        system: ["You must call the lookup tool exactly once with query weather. Do not answer in text."],
+        messages: [{ role: "user", content: "Use lookup." }],
+        toolChoice: "required",
+        tools: {
+          lookup: tool({
+            description: "Lookup data.",
+            inputSchema: z.object({ query: z.string() }),
+            execute: async (args, options) => {
+              executed = { args, toolCallId: options.toolCallId }
+              return { output: "looked up" }
+            },
+          }),
+        },
+      })
+
+      expect(events.filter((event) => event.type === "step-finish")).toHaveLength(1)
+      expect(events.filter((event) => event.type === "finish")).toHaveLength(1)
+      expect(events.some((event) => event.type === "tool-result")).toBe(true)
+      expect(executed).toMatchObject({ args: { query: "weather" }, toolCallId: expect.any(String) })
+    }),
+  )
+})
@@ -0,0 +1,385 @@
+import { describe, expect, test } from "bun:test"
+import { ToolFailure } from "@opencode-ai/llm"
+import { LLMClient, RequestExecutor } from "@opencode-ai/llm/route"
+import { jsonSchema, tool, type ModelMessage } from "ai"
+import { Effect } from "effect"
+import { LLMNative } from "@/session/llm/native-request"
+import { LLMNativeRuntime } from "@/session/llm/native-runtime"
+import type { Provider } from "@/provider/provider"
+import { ModelID, ProviderID } from "@/provider/schema"
+
+const baseModel: Provider.Model = {
+  id: ModelID.make("gpt-5-mini"),
+  providerID: ProviderID.make("openai"),
+  api: {
+    id: "gpt-5-mini",
+    url: "https://api.openai.com/v1",
+    npm: "@ai-sdk/openai",
+  },
+  name: "GPT-5 Mini",
+  capabilities: {
+    temperature: true,
+    reasoning: true,
+    attachment: true,
+    toolcall: true,
+    input: {
+      text: true,
+      audio: false,
+      image: true,
+      video: false,
+      pdf: false,
+    },
+    output: {
+      text: true,
+      audio: false,
+      image: false,
+      video: false,
+      pdf: false,
+    },
+    interleaved: false,
+  },
+  cost: {
+    input: 0,
+    output: 0,
+    cache: {
+      read: 0,
+      write: 0,
+    },
+  },
+  limit: {
+    context: 128_000,
+    input: 128_000,
+    output: 32_000,
+  },
+  status: "active",
+  options: {},
+  headers: {
+    "x-model": "model-header",
+  },
+  release_date: "2026-01-01",
+}
+
+const providerInfo: Provider.Info = {
+  id: ProviderID.make("openai"),
+  name: "OpenAI",
+  source: "config",
+  env: ["OPENAI_API_KEY"],
+  options: { apiKey: "test-openai-key" },
+  models: {},
+}
+
+describe("session.llm-native.request", () => {
+  test("maps normalized stream inputs to a native LLM request", () => {
+    const messages: ModelMessage[] = [
+      {
+        role: "system",
+        content: "system from messages",
+      },
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "hello", providerOptions: { openai: { cacheControl: { type: "ephemeral" } } } },
+          { type: "file", mediaType: "image/png", filename: "img.png", data: "data:image/png;base64,Zm9v" },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [
+          { type: "reasoning", text: "thinking", providerOptions: { openai: { encryptedContent: "secret" } } },
+          { type: "text", text: "I'll run it" },
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "bash",
+            input: { command: "ls" },
+            providerOptions: { openai: { itemId: "item-1" } },
+          },
+        ],
+      },
+      {
+        role: "tool",
+        content: [
+          {
+            type: "tool-result",
+            toolCallId: "call-1",
+            toolName: "bash",
+            output: { type: "text", value: "ok" },
+            providerOptions: { openai: { outputId: "output-1" } },
+          },
+        ],
+      },
+    ]
+
+    const request = LLMNative.request({
+      model: baseModel,
+      system: ["agent system"],
+      messages,
+      tools: {
+        bash: tool({
+          description: "Run a shell command",
+          inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+              command: { type: "string" },
+            },
+            required: ["command"],
+          }),
+        }),
+      },
+      toolChoice: "required",
+      temperature: 0.2,
+      topP: 0.9,
+      topK: 40,
+      maxOutputTokens: 1024,
+      providerOptions: { openai: { store: false } },
+      headers: { "x-request": "request-header" },
+    })
+
+    expect(request.model).toMatchObject({
+      id: "gpt-5-mini",
+      provider: "openai",
+      route: "openai-responses",
+      baseURL: "https://api.openai.com/v1",
+      headers: {
+        "x-model": "model-header",
+        "x-request": "request-header",
+      },
+      limits: {
+        context: 128_000,
+        output: 32_000,
+      },
+    })
+    expect(request.system).toEqual([
+      { type: "text", text: "agent system" },
+      { type: "text", text: "system from messages" },
+    ])
+    expect(request.generation).toMatchObject({
+      temperature: 0.2,
+      topP: 0.9,
+      topK: 40,
+      maxTokens: 1024,
+    })
+    expect(request.providerOptions).toEqual({ openai: { store: false } })
+    expect(request.toolChoice).toMatchObject({ type: "required" })
+    expect(request.tools).toMatchObject([
+      {
+        name: "bash",
+        description: "Run a shell command",
+        inputSchema: {
+          type: "object",
+          properties: {
+            command: { type: "string" },
+          },
+          required: ["command"],
+        },
+      },
+    ])
+    expect(request.messages).toMatchObject([
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "hello", providerMetadata: { openai: { cacheControl: { type: "ephemeral" } } } },
+          { type: "media", mediaType: "image/png", filename: "img.png", data: "data:image/png;base64,Zm9v" },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [
+          { type: "reasoning", text: "thinking", providerMetadata: { openai: { encryptedContent: "secret" } } },
+          { type: "text", text: "I'll run it" },
+          {
+            type: "tool-call",
+            id: "call-1",
+            name: "bash",
+            input: { command: "ls" },
+            providerMetadata: { openai: { itemId: "item-1" } },
+          },
+        ],
+      },
+      {
+        role: "tool",
+        content: [
+          {
+            type: "tool-result",
+            id: "call-1",
+            name: "bash",
+            result: { type: "text", value: "ok" },
+            providerMetadata: { openai: { outputId: "output-1" } },
+          },
+        ],
+      },
+    ])
+  })
+
+  test("selects native routes from existing provider packages", () => {
+    expect(
+      LLMNative.model({ ...baseModel, api: { ...baseModel.api, url: "", npm: "@ai-sdk/anthropic" } }),
+    ).toMatchObject({
+      route: "anthropic-messages",
+      baseURL: "https://api.anthropic.com/v1",
+    })
+    expect(LLMNative.model({ ...baseModel, api: { ...baseModel.api, url: "", npm: "@ai-sdk/google" } })).toMatchObject({
+      route: "gemini",
+      baseURL: "https://generativelanguage.googleapis.com/v1beta",
+    })
+    expect(
+      LLMNative.model({ ...baseModel, api: { ...baseModel.api, npm: "@ai-sdk/openai-compatible" } }),
+    ).toMatchObject({
+      route: "openai-compatible-chat",
+      baseURL: "https://api.openai.com/v1",
+    })
+    expect(
+      LLMNative.model({ ...baseModel, api: { ...baseModel.api, url: "", npm: "@openrouter/ai-sdk-provider" } }),
+    ).toMatchObject({
+      route: "openrouter",
+      baseURL: "https://openrouter.ai/api/v1",
+    })
+  })
+
+  test("fails fast for unsupported provider packages", () => {
+    expect(() =>
+      LLMNative.request({
+        model: { ...baseModel, api: { ...baseModel.api, npm: "unknown-provider" } },
+        messages: [],
+      }),
+    ).toThrow("Native LLM request adapter does not support provider package unknown-provider")
+  })
+
+  test("only enables native runtime for supported OpenAI API-key models", () => {
+    expect(LLMNativeRuntime.status({ model: baseModel, provider: providerInfo, auth: undefined })).toMatchObject({
+      type: "supported",
+      apiKey: "test-openai-key",
+    })
+    expect(
+      LLMNativeRuntime.status({
+        model: { ...baseModel, providerID: ProviderID.make("opencode") },
+        provider: { ...providerInfo, id: ProviderID.make("opencode") },
+        auth: undefined,
+      }),
+    ).toMatchObject({
+      type: "supported",
+      apiKey: "test-openai-key",
+    })
+    expect(
+      LLMNativeRuntime.status({
+        model: { ...baseModel, providerID: ProviderID.make("anthropic") },
+        provider: { ...providerInfo, id: ProviderID.make("anthropic") },
+        auth: undefined,
+      }),
+    ).toEqual({ type: "unsupported", reason: "provider is not openai or opencode" })
+    expect(
+      LLMNativeRuntime.status({
+        model: baseModel,
+        provider: providerInfo,
+        auth: { type: "oauth", refresh: "refresh", access: "access", expires: 1 },
+      }),
+    ).toEqual({ type: "unsupported", reason: "OAuth auth is not supported" })
+
+    expect(
+      LLMNativeRuntime.status({
+        model: { ...baseModel, api: { ...baseModel.api, npm: "@ai-sdk/anthropic" } },
+        provider: providerInfo,
+        auth: undefined,
+      }),
+    ).toEqual({ type: "unsupported", reason: "provider package is not OpenAI" })
+
+    expect(
+      LLMNativeRuntime.status({
+        model: baseModel,
+        provider: { ...providerInfo, options: {} },
+        auth: undefined,
+      }),
+    ).toEqual({ type: "unsupported", reason: "OpenAI API key is not configured" })
+  })
+
+  test("prefers console provider api key over stored opencode auth", () => {
+    expect(
+      LLMNativeRuntime.status({
+        model: { ...baseModel, providerID: ProviderID.make("opencode") },
+        provider: {
+          ...providerInfo,
+          id: ProviderID.make("opencode"),
+          options: { apiKey: "console-token" },
+          key: "zen-token",
+        },
+        auth: { type: "api", key: "zen-token" },
+      }),
+    ).toMatchObject({
+      type: "supported",
+      apiKey: "console-token",
+    })
+    expect(
+      LLMNativeRuntime.status({
+        model: baseModel,
+        provider: { ...providerInfo, options: {}, key: "provider-key" },
+        auth: undefined,
+      }),
+    ).toMatchObject({
+      type: "supported",
+      apiKey: "provider-key",
+    })
+  })
+
+  test("native tool wrapper converts thrown errors into typed ToolFailure", async () => {
+    const wrapped = LLMNativeRuntime.nativeTools(
+      {
+        explode: {
+          description: "always throws",
+          inputSchema: jsonSchema({ type: "object" }),
+          execute: async () => {
+            throw new Error("boom")
+          },
+        } as any,
+      },
+      { messages: [] as ModelMessage[], abort: new AbortController().signal },
+    )
+
+    const failure = await Effect.runPromise(
+      Effect.flip(wrapped.explode!.execute!({}, { id: "call-1", name: "explode" })),
+    )
+    expect(failure).toBeInstanceOf(ToolFailure)
+    expect((failure as ToolFailure).message).toBe("boom")
+  })
+
+  test("native tool wrapper raises ToolFailure when the source tool has no execute handler", async () => {
+    // The AI SDK Tool shape allows execute to be omitted (e.g., client-side / MCP tools).
+    // The native runtime owns execution, so encountering such a tool here means upstream
+    // wiring is wrong; we want a typed failure, not a silent skip or unhandled exception.
+    const wrapped = LLMNativeRuntime.nativeTools(
+      { incomplete: { description: "no execute", inputSchema: jsonSchema({ type: "object" }) } as any },
+      { messages: [] as ModelMessage[], abort: new AbortController().signal },
+    )
+
+    const failure = await Effect.runPromise(
+      Effect.flip(wrapped.incomplete!.execute!({}, { id: "call-1", name: "incomplete" })),
+    )
+    expect(failure).toBeInstanceOf(ToolFailure)
+    expect((failure as ToolFailure).message).toContain("incomplete")
+  })
+
+  test("compiles through the native OpenAI Responses route", async () => {
+    const prepared = await Effect.runPromise(
+      LLMClient.prepare(
+        LLMNative.request({
+          model: baseModel,
+          messages: [{ role: "user", content: "hello" }],
+          providerOptions: { openai: { store: false } },
+          maxOutputTokens: 512,
+          headers: { "x-request": "request-header" },
+        }),
+      ).pipe(Effect.provide(LLMClient.layer), Effect.provide(RequestExecutor.defaultLayer)),
+    )
+
+    expect(prepared).toMatchObject({
+      route: "openai-responses",
+      protocol: "openai-responses",
+      body: {
+        model: "gpt-5-mini",
+        input: [{ role: "user", content: [{ type: "input_text", text: "hello" }] }],
+        max_output_tokens: 512,
+        store: false,
+        stream: true,
+      },
+    })
+  })
+})
@@ -1,15 +1,20 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test"
 import path from "path"
 import { tool, type ModelMessage } from "ai"
-import { Cause, Effect, Exit, Stream } from "effect"
+import { Cause, Effect, Exit, Layer, Stream } from "effect"
+import { HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
 import z from "zod"
 import { makeRuntime } from "../../src/effect/run-service"
 import { InstanceRef } from "../../src/effect/instance-ref"
 import { LLM } from "../../src/session/llm"
 import type { InstanceContext } from "../../src/project/instance-context"
+import { LLMClient, RequestExecutor } from "@opencode-ai/llm/route"
+import { Auth } from "@/auth"
+import { Config } from "@/config/config"
 import { Provider } from "@/provider/provider"
 import { ProviderTransform } from "@/provider/transform"
 import { ModelsDev } from "@opencode-ai/core/models-dev"
+import { Plugin } from "@/plugin"
 import { ProviderID, ModelID } from "../../src/provider/schema"
 import { Filesystem } from "@/util/filesystem"
 import { tmpdir, withTestInstance } from "../fixture/fixture"
@@ -17,6 +22,33 @@ import type { Agent } from "../../src/agent/agent"
 import { MessageV2 } from "../../src/session/message-v2"
 import { SessionID, MessageID } from "../../src/session/schema"
 import { AppRuntime } from "../../src/effect/app-runtime"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import { Permission } from "@/permission"
+import { LLMAISDK } from "@/session/llm/ai-sdk"
+import { Session as SessionNs } from "@/session/session"
+
+const openAIConfig = (model: ModelsDev.Provider["models"][string], baseURL: string): Partial<Config.Info> => {
+  const { experimental: _experimental, ...configModel } = model
+  type ConfigModel = NonNullable<NonNullable<Config.Info["provider"]>[string]["models"]>[string]
+  return {
+    enabled_providers: ["openai"],
+    provider: {
+      openai: {
+        name: "OpenAI",
+        env: ["OPENAI_API_KEY"],
+        npm: "@ai-sdk/openai",
+        api: "https://api.openai.com/v1",
+        models: {
+          [model.id]: JSON.parse(JSON.stringify(configModel)) as ConfigModel,
+        },
+        options: {
+          apiKey: "test-openai-key",
+          baseURL,
+        },
+      },
+    },
+  }
+}

 async function getModel(providerID: ProviderID, modelID: ModelID, ctx: InstanceContext) {
  const effect = Effect.gen(function* () {
@@ -35,6 +67,26 @@ async function drain(input: LLM.StreamInput, ctx: InstanceContext) {
  })
 }

+async function drainWith(layer: Layer.Layer<LLM.Service>, input: LLM.StreamInput, ctx: InstanceContext) {
+  return Effect.runPromise(
+    LLM.Service.use((svc) => svc.stream(input).pipe(Stream.runDrain)).pipe(
+      Effect.provide(layer),
+      Effect.provideService(InstanceRef, ctx),
+    ),
+  )
+}
+
+function llmLayerWithExecutor(executor: Layer.Layer<RequestExecutor.Service>, flags: Partial<RuntimeFlags.Info> = {}) {
+  return LLM.layer.pipe(
+    Layer.provide(Auth.defaultLayer),
+    Layer.provide(Config.defaultLayer),
+    Layer.provide(Provider.defaultLayer),
+    Layer.provide(Plugin.defaultLayer),
+    Layer.provide(LLMClient.layer.pipe(Layer.provide(executor))),
+    Layer.provide(RuntimeFlags.layer(flags)),
+  )
+}
+
 describe("session.llm.hasToolCalls", () => {
  test("returns false for empty messages array", () => {
    expect(LLM.hasToolCalls([])).toBe(false)
@@ -122,6 +174,338 @@ describe("session.llm.hasToolCalls", () => {
  })
 })

+describe("session.llm.ai-sdk adapter", () => {
+  type AISDKAdapterEvent = Parameters<typeof LLMAISDK.toLLMEvents>[1]
+
+  const adapt = (events: ReadonlyArray<AISDKAdapterEvent>) => {
+    const state = LLMAISDK.adapterState()
+    return Effect.runPromise(
+      Effect.forEach(events, (event) => LLMAISDK.toLLMEvents(state, event)).pipe(Effect.map((items) => items.flat())),
+    )
+  }
+  // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- tests defensive adapter branches outside AI SDK's current typed surface
+  const uncheckedAdapterEvent = (input: unknown) => input as AISDKAdapterEvent
+
+  test("maps AI SDK stream chunks without losing session-visible fields", async () => {
+    const metadata = { openai: { itemID: "item-1" } }
+    const events = await adapt([
+      { type: "start" },
+      { type: "start-step", request: {}, warnings: [] },
+      { type: "text-start", id: "text-1", providerMetadata: metadata },
+      { type: "text-delta", id: "text-1", text: "Hel", providerMetadata: { openai: { delta: 1 } } },
+      { type: "text-delta", id: "text-1", text: "lo", providerMetadata: { openai: { delta: 2 } } },
+      { type: "text-end", id: "text-1", providerMetadata: { openai: { done: true } } },
+      { type: "reasoning-start", id: "reasoning-1", providerMetadata: metadata },
+      { type: "reasoning-delta", id: "reasoning-1", text: "Think", providerMetadata: { openai: { delta: 3 } } },
+      { type: "reasoning-end", id: "reasoning-1", providerMetadata: { openai: { done: true } } },
+      { type: "tool-input-start", id: "call-1", toolName: "lookup", providerMetadata: metadata },
+      { type: "tool-input-delta", id: "call-1", delta: '{"query":' },
+      { type: "tool-input-delta", id: "call-1", delta: '"weather"}' },
+      { type: "tool-input-end", id: "call-1", providerMetadata: { openai: { inputDone: true } } },
+      {
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "lookup",
+        input: { query: "weather" },
+        providerExecuted: true,
+        providerMetadata: { openai: { called: true } },
+      },
+      {
+        type: "tool-result",
+        toolCallId: "call-1",
+        toolName: "lookup",
+        input: { query: "weather" },
+        output: { title: "Lookup", output: "sunny", metadata: { ok: true } },
+        providerExecuted: true,
+        providerMetadata: { openai: { result: true } },
+      },
+      {
+        type: "finish-step",
+        response: { id: "response-1", timestamp: new Date(0), modelId: "gpt-test" },
+        finishReason: "other",
+        rawFinishReason: "other",
+        usage: {
+          inputTokens: 10,
+          outputTokens: 5,
+          totalTokens: 15,
+          inputTokenDetails: { noCacheTokens: 5, cacheReadTokens: 3, cacheWriteTokens: 2 },
+          outputTokenDetails: { textTokens: 4, reasoningTokens: 1 },
+        },
+        providerMetadata: { openai: { step: true } },
+      },
+      {
+        type: "finish",
+        finishReason: "other",
+        rawFinishReason: "other",
+        totalUsage: {
+          inputTokens: 11,
+          outputTokens: 6,
+          totalTokens: 17,
+          cachedInputTokens: 4,
+          reasoningTokens: 2,
+          inputTokenDetails: { noCacheTokens: 7, cacheReadTokens: 4, cacheWriteTokens: undefined },
+          outputTokenDetails: { textTokens: 4, reasoningTokens: 2 },
+        },
+      },
+    ])
+
+    expect(events).toMatchObject([
+      { type: "step-start", index: 0 },
+      { type: "text-start", id: "text-1", providerMetadata: metadata },
+      { type: "text-delta", id: "text-1", text: "Hel", providerMetadata: { openai: { delta: 1 } } },
+      { type: "text-delta", id: "text-1", text: "lo", providerMetadata: { openai: { delta: 2 } } },
+      { type: "text-end", id: "text-1", providerMetadata: { openai: { done: true } } },
+      { type: "reasoning-start", id: "reasoning-1", providerMetadata: metadata },
+      { type: "reasoning-delta", id: "reasoning-1", text: "Think", providerMetadata: { openai: { delta: 3 } } },
+      { type: "reasoning-end", id: "reasoning-1", providerMetadata: { openai: { done: true } } },
+      { type: "tool-input-start", id: "call-1", name: "lookup", providerMetadata: metadata },
+      { type: "tool-input-delta", id: "call-1", name: "lookup", text: '{"query":' },
+      { type: "tool-input-delta", id: "call-1", name: "lookup", text: '"weather"}' },
+      { type: "tool-input-end", id: "call-1", name: "lookup", providerMetadata: { openai: { inputDone: true } } },
+      {
+        type: "tool-call",
+        id: "call-1",
+        name: "lookup",
+        input: { query: "weather" },
+        providerExecuted: true,
+        providerMetadata: { openai: { called: true } },
+      },
+      {
+        type: "tool-result",
+        id: "call-1",
+        name: "lookup",
+        result: { type: "json", value: { title: "Lookup", output: "sunny", metadata: { ok: true } } },
+        providerExecuted: true,
+        providerMetadata: { openai: { result: true } },
+      },
+      {
+        type: "step-finish",
+        index: 0,
+        reason: "unknown",
+        usage: {
+          inputTokens: 10,
+          outputTokens: 5,
+          totalTokens: 15,
+          reasoningTokens: 1,
+          cacheReadInputTokens: 3,
+          cacheWriteInputTokens: 2,
+        },
+        providerMetadata: { openai: { step: true } },
+      },
+      {
+        type: "finish",
+        reason: "unknown",
+        usage: {
+          inputTokens: 11,
+          outputTokens: 6,
+          totalTokens: 17,
+          reasoningTokens: 2,
+          cacheReadInputTokens: 4,
+        },
+      },
+    ])
+  })
+
+  test("creates stable block ids when AI SDK omits them", async () => {
+    const events = await adapt([
+      uncheckedAdapterEvent({ type: "text-delta", text: "implicit text" }),
+      uncheckedAdapterEvent({ type: "text-end" }),
+      uncheckedAdapterEvent({ type: "reasoning-delta", text: "implicit reasoning" }),
+      uncheckedAdapterEvent({ type: "reasoning-end" }),
+    ])
+
+    expect(events).toMatchObject([
+      { type: "text-delta", id: "text-0", text: "implicit text" },
+      { type: "text-end", id: "text-0" },
+      { type: "reasoning-delta", id: "reasoning-0", text: "implicit reasoning" },
+      { type: "reasoning-end", id: "reasoning-0" },
+    ])
+  })
+
+  test("explicitly ignores non-session-visible AI SDK chunks", async () => {
+    expect(
+      await adapt([
+        uncheckedAdapterEvent({ type: "abort" }),
+        uncheckedAdapterEvent({ type: "source" }),
+        uncheckedAdapterEvent({ type: "file" }),
+        uncheckedAdapterEvent({ type: "raw" }),
+        uncheckedAdapterEvent({ type: "tool-output-denied" }),
+        uncheckedAdapterEvent({ type: "tool-approval-request" }),
+      ]),
+    ).toEqual([])
+  })
+
+  test("preserves tool-error cause", async () => {
+    const error = new Permission.RejectedError()
+    const events = await Effect.runPromise(
+      LLMAISDK.toLLMEvents(LLMAISDK.adapterState(), {
+        type: "tool-error",
+        toolCallId: "call_123",
+        toolName: "bash",
+        input: {},
+        error,
+      }),
+    )
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      type: "tool-error",
+      id: "call_123",
+      name: "bash",
+      message: error.message,
+      error,
+    })
+  })
+
+  test("emits undefined usage when every AI SDK usage field is missing", async () => {
+    // If every numeric field is undefined the translator should signal "no usage info"
+    // by emitting undefined, not by polluting the event with usage: {}. Downstream cost
+    // telemetry distinguishes "missing" from "zero," so emitting an empty object causes
+    // false positives ("usage was tracked, just empty") instead of correct nulls.
+    const events = await adapt([
+      {
+        type: "finish-step",
+        response: { id: "response-1", timestamp: new Date(0), modelId: "gpt-test" },
+        finishReason: "stop",
+        rawFinishReason: "stop",
+        providerMetadata: undefined,
+        usage: {
+          inputTokens: undefined,
+          outputTokens: undefined,
+          totalTokens: undefined,
+          reasoningTokens: undefined,
+          cachedInputTokens: undefined,
+          inputTokenDetails: { noCacheTokens: undefined, cacheReadTokens: undefined, cacheWriteTokens: undefined },
+          outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
+        },
+      },
+    ])
+
+    expect(events).toHaveLength(1)
+    const stepFinish = events[0]
+    if (stepFinish.type !== "step-finish") throw new Error("expected step-finish")
+    expect(stepFinish.usage).toBeUndefined()
+  })
+
+  test("reuses adapter state cleanly across streams once finish has fired", async () => {
+    // adapterState() is meant to be per-stream, but the only thing finish currently clears
+    // is toolNames — step, text counters, and the current text/reasoning IDs all leak
+    // forward. A caller that reuses a state across two streams sees text-1/reasoning-1/
+    // step index 1 on the second stream's first events. The test pins the intended
+    // contract: after finish, the same state can be reused and starts fresh.
+    const state = LLMAISDK.adapterState()
+    const run = (events: ReadonlyArray<AISDKAdapterEvent>) =>
+      Effect.runPromise(
+        Effect.forEach(events, (event) => LLMAISDK.toLLMEvents(state, event)).pipe(Effect.map((items) => items.flat())),
+      )
+
+    await run([
+      { type: "start-step", request: {}, warnings: [] },
+      uncheckedAdapterEvent({ type: "text-delta", text: "first" }),
+      uncheckedAdapterEvent({ type: "text-end" }),
+      uncheckedAdapterEvent({ type: "reasoning-delta", text: "first reasoning" }),
+      uncheckedAdapterEvent({ type: "reasoning-end" }),
+      {
+        type: "finish-step",
+        response: { id: "r1", timestamp: new Date(0), modelId: "gpt-test" },
+        finishReason: "stop",
+        rawFinishReason: "stop",
+        providerMetadata: undefined,
+        usage: {
+          inputTokens: 1,
+          outputTokens: 1,
+          totalTokens: 2,
+          inputTokenDetails: { noCacheTokens: undefined, cacheReadTokens: undefined, cacheWriteTokens: undefined },
+          outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
+        },
+      },
+      {
+        type: "finish",
+        finishReason: "stop",
+        rawFinishReason: "stop",
+        totalUsage: {
+          inputTokens: 1,
+          outputTokens: 1,
+          totalTokens: 2,
+          inputTokenDetails: { noCacheTokens: undefined, cacheReadTokens: undefined, cacheWriteTokens: undefined },
+          outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
+        },
+      },
+    ])
+
+    const secondStream = await run([
+      { type: "start-step", request: {}, warnings: [] },
+      uncheckedAdapterEvent({ type: "text-delta", text: "second" }),
+      uncheckedAdapterEvent({ type: "text-end" }),
+      uncheckedAdapterEvent({ type: "reasoning-delta", text: "second reasoning" }),
+      uncheckedAdapterEvent({ type: "reasoning-end" }),
+    ])
+
+    expect(secondStream).toMatchObject([
+      { type: "step-start", index: 0 },
+      { type: "text-delta", id: "text-0", text: "second" },
+      { type: "text-end", id: "text-0" },
+      { type: "reasoning-delta", id: "reasoning-0", text: "second reasoning" },
+      { type: "reasoning-end", id: "reasoning-0" },
+    ])
+  })
+
+  // Anthropic emits cache write counts in providerMetadata.anthropic.cacheCreationInputTokens
+  // rather than usage.inputTokenDetails.cacheWriteTokens. Session.getUsage falls back to the
+  // metadata path — but only if the adapter preserves providerMetadata on step-finish.
+  test("preserves providerMetadata on step-finish so Anthropic cache writes survive getUsage", async () => {
+    const events = await adapt([
+      {
+        type: "finish-step",
+        response: { id: "msg_test", timestamp: new Date(0), modelId: "claude-3-5-sonnet" },
+        finishReason: "stop",
+        rawFinishReason: "stop",
+        // Anthropic's AI SDK shape: cacheWriteTokens is NOT in usage, it arrives via providerMetadata.
+        usage: {
+          inputTokens: 1000,
+          outputTokens: 500,
+          totalTokens: 1500,
+          inputTokenDetails: { noCacheTokens: 800, cacheReadTokens: 200, cacheWriteTokens: undefined },
+          outputTokenDetails: { textTokens: 500, reasoningTokens: undefined },
+        },
+        providerMetadata: { anthropic: { cacheCreationInputTokens: 300 } },
+      },
+    ])
+
+    expect(events).toHaveLength(1)
+    const stepFinish = events[0]
+    if (stepFinish.type !== "step-finish") throw new Error("expected step-finish")
+    expect(stepFinish.providerMetadata).toEqual({ anthropic: { cacheCreationInputTokens: 300 } })
+    expect(stepFinish.usage?.cacheWriteInputTokens).toBeUndefined()
+    expect(stepFinish.usage?.cacheReadInputTokens).toBe(200)
+
+    // End-to-end: with the metadata preserved, getUsage extracts cache.write from the fallback path.
+    const result = SessionNs.getUsage({
+      model: {
+        id: "claude-3-5-sonnet",
+        providerID: "anthropic",
+        name: "Claude",
+        limit: { context: 200_000, output: 8_000 },
+        cost: { input: 0, output: 0, cache: { read: 0, write: 0 } },
+        capabilities: {
+          toolcall: true,
+          attachment: false,
+          reasoning: false,
+          temperature: true,
+          input: { text: true, image: false, audio: false, video: false },
+          output: { text: true, image: false, audio: false, video: false },
+        },
+        api: { npm: "@ai-sdk/anthropic" },
+        options: {},
+      } as never,
+      usage: stepFinish.usage!,
+      metadata: stepFinish.providerMetadata,
+    })
+    expect(result.tokens.cache.write).toBe(300)
+    expect(result.tokens.cache.read).toBe(200)
+  })
+})
+
 type Capture = {
  url: URL
  headers: Headers
@@ -608,6 +992,18 @@ describe("session.llm.stream", () => {
          service_tier: null,
        },
      },
+      {
+        type: "response.output_item.added",
+        output_index: 0,
+        item: { type: "message", id: "item-1", status: "in_progress", role: "assistant", content: [] },
+      },
+      {
+        type: "response.content_part.added",
+        item_id: "item-1",
+        output_index: 0,
+        content_index: 0,
+        part: { type: "output_text", text: "", annotations: [] },
+      },
      {
        type: "response.output_text.delta",
        item_id: "item-1",
@@ -630,32 +1026,7 @@ describe("session.llm.stream", () => {
    ]
    const request = waitRequest("/responses", createEventResponse(responseChunks, true))

-    await using tmp = await tmpdir({
-      init: async (dir) => {
-        await Bun.write(
-          path.join(dir, "opencode.json"),
-          JSON.stringify({
-            $schema: "https://opencode.ai/config.json",
-            enabled_providers: ["openai"],
-            provider: {
-              openai: {
-                name: "OpenAI",
-                env: ["OPENAI_API_KEY"],
-                npm: "@ai-sdk/openai",
-                api: "https://api.openai.com/v1",
-                models: {
-                  [model.id]: configModel(model),
-                },
-                options: {
-                  apiKey: "test-openai-key",
-                  baseURL: `${server.url.origin}/v1`,
-                },
-              },
-            },
-          }),
-        )
-      },
-    })
+    await using tmp = await tmpdir({ config: openAIConfig(model, `${server.url.origin}/v1`) })

    await withTestInstance({
      directory: tmp.path,
@@ -706,6 +1077,438 @@ describe("session.llm.stream", () => {
    })
  })

+  test("keeps supported OpenAI models on AI SDK path when native flag is off", async () => {
+    const server = state.server
+    if (!server) {
+      throw new Error("Server not initialized")
+    }
+
+    const source = await loadFixture("openai", "gpt-5.2")
+    const model = source.model
+    const request = waitRequest(
+      "/responses",
+      createEventResponse(
+        [
+          {
+            type: "response.created",
+            response: {
+              id: "resp-flag-off",
+              created_at: Math.floor(Date.now() / 1000),
+              model: model.id,
+              service_tier: null,
+            },
+          },
+          {
+            type: "response.output_item.added",
+            output_index: 0,
+            item: { type: "message", id: "item-flag-off", status: "in_progress", role: "assistant", content: [] },
+          },
+          {
+            type: "response.content_part.added",
+            item_id: "item-flag-off",
+            output_index: 0,
+            content_index: 0,
+            part: { type: "output_text", text: "", annotations: [] },
+          },
+          {
+            type: "response.output_text.delta",
+            item_id: "item-flag-off",
+            delta: "Flag off",
+            logprobs: null,
+          },
+          {
+            type: "response.completed",
+            response: {
+              incomplete_details: null,
+              usage: {
+                input_tokens: 1,
+                input_tokens_details: null,
+                output_tokens: 1,
+                output_tokens_details: null,
+              },
+              service_tier: null,
+            },
+          },
+        ],
+        true,
+      ),
+    )
+    const failingNativeClient = Layer.succeed(
+      LLMClient.Service,
+      LLMClient.Service.of({
+        prepare: () => Effect.die(new Error("native LLM client should not be used when the flag is off")),
+        stream: () => Stream.die(new Error("native LLM client should not be used when the flag is off")),
+        generate: () => Effect.die(new Error("native LLM client should not be used when the flag is off")),
+      }),
+    )
+
+    await using tmp = await tmpdir({ config: openAIConfig(model, `${server.url.origin}/v1`) })
+
+    await withTestInstance({
+      directory: tmp.path,
+      fn: async (ctx) => {
+        const resolved = await getModel(ProviderID.openai, ModelID.make(model.id), ctx)
+        const sessionID = SessionID.make("session-test-native-flag-off")
+        const agent = {
+          name: "test",
+          mode: "primary",
+          options: {},
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        } satisfies Agent.Info
+
+        await drainWith(
+          LLM.layer.pipe(
+            Layer.provide(Auth.defaultLayer),
+            Layer.provide(Config.defaultLayer),
+            Layer.provide(Provider.defaultLayer),
+            Layer.provide(Plugin.defaultLayer),
+            Layer.provide(failingNativeClient),
+            Layer.provide(RuntimeFlags.layer({ experimentalNativeLlm: false })),
+          ),
+          {
+            user: {
+              id: MessageID.make("msg_user-native-flag-off"),
+              sessionID,
+              role: "user",
+              time: { created: Date.now() },
+              agent: agent.name,
+              model: { providerID: ProviderID.make("openai"), modelID: resolved.id, variant: "high" },
+            } satisfies MessageV2.User,
+            sessionID,
+            model: resolved,
+            agent,
+            system: ["You are a helpful assistant."],
+            messages: [{ role: "user", content: "Hello" }],
+            tools: {},
+          },
+          ctx,
+        )
+
+        const capture = await request
+        expect(capture.url.pathname.endsWith("/responses")).toBe(true)
+        expect(capture.body.model).toBe(resolved.api.id)
+      },
+    })
+  })
+
+  test("streams OpenAI through native runtime when opted in", async () => {
+    const server = state.server
+    if (!server) {
+      throw new Error("Server not initialized")
+    }
+
+    const source = await loadFixture("openai", "gpt-5.2")
+    const model = source.model
+    const chunks = [
+      {
+        type: "response.created",
+        response: {
+          id: "resp-native",
+        },
+      },
+      {
+        type: "response.output_item.added",
+        item: { type: "message", id: "item-native", status: "in_progress" },
+      },
+      {
+        type: "response.output_text.delta",
+        item_id: "item-native",
+        delta: "Hello native",
+      },
+      {
+        type: "response.completed",
+        response: {
+          incomplete_details: null,
+          usage: {
+            input_tokens: 1,
+            input_tokens_details: null,
+            output_tokens: 1,
+            output_tokens_details: null,
+          },
+        },
+      },
+    ]
+    const request = waitRequest("/responses", createEventResponse(chunks, true))
+
+    await using tmp = await tmpdir({ config: openAIConfig(model, `${server.url.origin}/v1`) })
+
+    await withTestInstance({
+      directory: tmp.path,
+      fn: async (ctx) => {
+        const resolved = await getModel(ProviderID.openai, ModelID.make(model.id), ctx)
+        const sessionID = SessionID.make("session-test-native")
+        const agent = {
+          name: "test",
+          mode: "primary",
+          options: {},
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+          temperature: 0.2,
+        } satisfies Agent.Info
+
+        await drainWith(
+          llmLayerWithExecutor(RequestExecutor.defaultLayer, { experimentalNativeLlm: true }),
+          {
+            user: {
+              id: MessageID.make("msg_user-native"),
+              sessionID,
+              role: "user",
+              time: { created: Date.now() },
+              agent: agent.name,
+              model: { providerID: ProviderID.make("openai"), modelID: resolved.id, variant: "high" },
+            } satisfies MessageV2.User,
+            sessionID,
+            model: resolved,
+            agent,
+            system: ["You are a helpful assistant."],
+            messages: [{ role: "user", content: "Hello" }],
+            tools: {},
+          },
+          ctx,
+        )
+
+        const capture = await request
+        expect(capture.url.pathname.endsWith("/responses")).toBe(true)
+        expect(capture.headers.get("Authorization")).toBe("Bearer test-openai-key")
+        expect(capture.body.model).toBe(model.id)
+        expect(capture.body.stream).toBe(true)
+        expect((capture.body.reasoning as { effort?: string } | undefined)?.effort).toBe("high")
+        expect(JSON.stringify(capture.body.input)).toContain("You are a helpful assistant.")
+        expect(capture.body.input).toContainEqual({ role: "user", content: [{ type: "input_text", text: "Hello" }] })
+      },
+    })
+  })
+
+  test("uses injected native request executor for tool calls", async () => {
+    const source = await loadFixture("openai", "gpt-5.2")
+    const model = source.model
+    const chunks = [
+      {
+        type: "response.output_item.added",
+        item: { type: "function_call", id: "item-injected-tool", call_id: "call-injected-tool", name: "lookup" },
+      },
+      {
+        type: "response.function_call_arguments.delta",
+        item_id: "item-injected-tool",
+        delta: '{"query":"weather"}',
+      },
+      {
+        type: "response.output_item.done",
+        item: {
+          type: "function_call",
+          id: "item-injected-tool",
+          call_id: "call-injected-tool",
+          name: "lookup",
+          arguments: '{"query":"weather"}',
+        },
+      },
+      {
+        type: "response.completed",
+        response: { incomplete_details: null, usage: { input_tokens: 1, output_tokens: 1 } },
+      },
+    ]
+    let captured: Record<string, unknown> | undefined
+    let executed: unknown
+    const executor = Layer.succeed(
+      RequestExecutor.Service,
+      RequestExecutor.Service.of({
+        execute: (request) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(request).pipe(Effect.orDie)
+            captured = (yield* Effect.promise(() => web.json())) as Record<string, unknown>
+            return HttpClientResponse.fromWeb(request, createEventResponse(chunks, true))
+          }),
+      }),
+    )
+
+    await using tmp = await tmpdir({ config: openAIConfig(model, "https://injected-openai.test/v1") })
+
+    await withTestInstance({
+      directory: tmp.path,
+      fn: async (ctx) => {
+        const resolved = await getModel(ProviderID.openai, ModelID.make(model.id), ctx)
+        const sessionID = SessionID.make("session-test-native-injected-tool")
+        const agent = {
+          name: "test",
+          mode: "primary",
+          options: {},
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        } satisfies Agent.Info
+
+        await drainWith(
+          llmLayerWithExecutor(executor, { experimentalNativeLlm: true }),
+          {
+            user: {
+              id: MessageID.make("msg_user-native-injected-tool"),
+              sessionID,
+              role: "user",
+              time: { created: Date.now() },
+              agent: agent.name,
+              model: { providerID: ProviderID.make("openai"), modelID: resolved.id },
+            } satisfies MessageV2.User,
+            sessionID,
+            model: resolved,
+            agent,
+            system: [],
+            messages: [{ role: "user", content: "Use lookup" }],
+            tools: {
+              lookup: tool({
+                description: "Lookup data",
+                inputSchema: z.object({ query: z.string() }),
+                execute: async (args, options) => {
+                  executed = { args, toolCallId: options.toolCallId }
+                  return { output: "looked up" }
+                },
+              }),
+            },
+          },
+          ctx,
+        )
+
+        expect(captured?.model).toBe(model.id)
+        expect(captured?.tools).toEqual([
+          {
+            type: "function",
+            name: "lookup",
+            description: "Lookup data",
+            parameters: {
+              type: "object",
+              properties: { query: { type: "string" } },
+              required: ["query"],
+              additionalProperties: false,
+              $schema: "http://json-schema.org/draft-07/schema#",
+            },
+          },
+        ])
+        expect(executed).toEqual({ args: { query: "weather" }, toolCallId: "call-injected-tool" })
+      },
+    })
+  })
+
+  test("executes OpenAI tool calls through native runtime", async () => {
+    const server = state.server
+    if (!server) {
+      throw new Error("Server not initialized")
+    }
+
+    const source = await loadFixture("openai", "gpt-5.2")
+    const model = source.model
+    const chunks = [
+      {
+        type: "response.output_item.added",
+        item: { type: "function_call", id: "item-native-tool", call_id: "call-native-tool", name: "lookup" },
+      },
+      {
+        type: "response.function_call_arguments.delta",
+        item_id: "item-native-tool",
+        delta: '{"query":"weather"}',
+      },
+      {
+        type: "response.output_item.done",
+        item: {
+          type: "function_call",
+          id: "item-native-tool",
+          call_id: "call-native-tool",
+          name: "lookup",
+          arguments: '{"query":"weather"}',
+        },
+      },
+      {
+        type: "response.completed",
+        response: { incomplete_details: null, usage: { input_tokens: 1, output_tokens: 1 } },
+      },
+    ]
+    const request = waitRequest("/responses", createEventResponse(chunks, true))
+    let executed: unknown
+
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        await Bun.write(
+          path.join(dir, "opencode.json"),
+          JSON.stringify({
+            $schema: "https://opencode.ai/config.json",
+            enabled_providers: ["openai"],
+            provider: {
+              openai: {
+                name: "OpenAI",
+                env: ["OPENAI_API_KEY"],
+                npm: "@ai-sdk/openai",
+                api: "https://api.openai.com/v1",
+                models: {
+                  [model.id]: model,
+                },
+                options: {
+                  apiKey: "test-openai-key",
+                  baseURL: `${server.url.origin}/v1`,
+                },
+              },
+            },
+          }),
+        )
+      },
+    })
+
+    await withTestInstance({
+      directory: tmp.path,
+      fn: async (ctx) => {
+        const resolved = await getModel(ProviderID.openai, ModelID.make(model.id), ctx)
+        const sessionID = SessionID.make("session-test-native-tool")
+        const agent = {
+          name: "test",
+          mode: "primary",
+          options: {},
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        } satisfies Agent.Info
+
+        await drainWith(
+          llmLayerWithExecutor(RequestExecutor.defaultLayer, { experimentalNativeLlm: true }),
+          {
+            user: {
+              id: MessageID.make("msg_user-native-tool"),
+              sessionID,
+              role: "user",
+              time: { created: Date.now() },
+              agent: agent.name,
+              model: { providerID: ProviderID.make("openai"), modelID: resolved.id },
+            } satisfies MessageV2.User,
+            sessionID,
+            model: resolved,
+            agent,
+            system: [],
+            messages: [{ role: "user", content: "Use lookup" }],
+            tools: {
+              lookup: tool({
+                description: "Lookup data",
+                inputSchema: z.object({ query: z.string() }),
+                execute: async (args, options) => {
+                  executed = { args, toolCallId: options.toolCallId }
+                  return { output: "looked up" }
+                },
+              }),
+            },
+          },
+          ctx,
+        )
+
+        const capture = await request
+        expect(capture.body.tools).toEqual([
+          {
+            type: "function",
+            name: "lookup",
+            description: "Lookup data",
+            parameters: {
+              type: "object",
+              properties: { query: { type: "string" } },
+              required: ["query"],
+              additionalProperties: false,
+              $schema: "http://json-schema.org/draft-07/schema#",
+            },
+          },
+        ])
+        expect(executed).toEqual({ args: { query: "weather" }, toolCallId: "call-native-tool" })
+      },
+    })
+  })
+
  test("accepts user image attachments as data URLs for OpenAI models", async () => {
    const server = state.server
    if (!server) {
@@ -724,6 +1527,18 @@ describe("session.llm.stream", () => {
          service_tier: null,
        },
      },
+      {
+        type: "response.output_item.added",
+        output_index: 0,
+        item: { type: "message", id: "item-data-url", status: "in_progress", role: "assistant", content: [] },
+      },
+      {
+        type: "response.content_part.added",
+        item_id: "item-data-url",
+        output_index: 0,
+        content_index: 0,
+        part: { type: "output_text", text: "", annotations: [] },
+      },
      {
        type: "response.output_text.delta",
        item_id: "item-data-url",
@@ -1,7 +1,9 @@
 import { NodeFileSystem } from "@effect/platform-node"
 import { expect } from "bun:test"
+import { tool } from "ai"
 import { Cause, Effect, Exit, Fiber, Layer } from "effect"
 import path from "path"
+import z from "zod"
 import type { Agent } from "../../src/agent/agent"
 import { Agent as AgentSvc } from "../../src/agent/agent"
 import { Bus } from "../../src/bus"
@@ -661,6 +663,71 @@ it.live("session.processor effect tests compact on structured context overflow",
  ),
 )

+it.live("session.processor effect tests complete AI SDK tool calls when native flag is off", () =>
+  provideTmpdirServer(
+    ({ dir, llm }) =>
+      Effect.gen(function* () {
+        const { processors, session, provider } = yield* boot()
+
+        yield* llm.tool("lookup", { query: "weather" })
+
+        const chat = yield* session.create({})
+        const parent = yield* user(chat.id, "tool")
+        const msg = yield* assistant(chat.id, parent.id, path.resolve(dir))
+        const mdl = yield* provider.getModel(ref.providerID, ref.modelID)
+        const handle = yield* processors.create({
+          assistantMessage: msg,
+          sessionID: chat.id,
+          model: mdl,
+        })
+
+        const value = yield* handle.process({
+          user: {
+            id: parent.id,
+            sessionID: chat.id,
+            role: "user",
+            time: parent.time,
+            agent: parent.agent,
+            model: { providerID: ref.providerID, modelID: ref.modelID },
+          } satisfies MessageV2.User,
+          sessionID: chat.id,
+          model: mdl,
+          agent: agent(),
+          system: [],
+          messages: [{ role: "user", content: "tool" }],
+          tools: {
+            lookup: tool({
+              description: "Look up information",
+              inputSchema: z.object({ query: z.string() }),
+              execute: async (input) => ({
+                title: "Weather lookup",
+                output: `result:${input.query}`,
+                metadata: { source: "test" },
+              }),
+            }),
+          },
+        })
+
+        const parts = MessageV2.parts(msg.id)
+        const call = parts.find((part): part is MessageV2.ToolPart => part.type === "tool")
+
+        expect(value).toBe("continue")
+        expect(yield* llm.calls).toBe(1)
+        expect(call?.callID).toBe("call_1")
+        expect(call?.tool).toBe("lookup")
+        expect(call?.state.status).toBe("completed")
+        if (call?.state.status !== "completed") return
+        expect(call.state.input).toEqual({ query: "weather" })
+        expect(call.state.output).toBe("result:weather")
+        expect(call.state.title).toBe("Weather lookup")
+        expect(call.state.metadata).toEqual({ source: "test" })
+        expect(call.state.time.start).toBeDefined()
+        expect(call.state.time.end).toBeDefined()
+      }),
+    { git: true, config: (url) => providerCfg(url) },
+  ),
+)
+
 it.live("session.processor effect tests mark pending tools as aborted on cleanup", () =>
  provideTmpdirServer(
    ({ dir, llm }) =>
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode-ai/plugin",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,5 +1,4 @@
 import { z } from "zod"
-import { Effect } from "effect"

 export type ToolContext = {
  sessionID: string
@@ -17,7 +16,7 @@ export type ToolContext = {
  worktree: string
  abort: AbortSignal
  metadata(input: { title?: string; metadata?: { [key: string]: any } }): void
-  ask(input: AskInput): Effect.Effect<void>
+  ask(input: AskInput): Promise<void>
 }

 type AskInput = {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode-ai/sdk",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/slack",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/ui",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "type": "module",
  "license": "MIT",
  "exports": {
@@ -1563,7 +1563,7 @@ PART_MAPPING["reasoning"] = function ReasoningPartDisplay(props) {
  const streaming = createMemo(
    () => props.message.role === "assistant" && typeof (props.message as AssistantMessage).time.completed !== "number",
  )
-  const text = () => (data.store.part_text_accum_delta?.[part().id] ?? part().text).trim()
+  const text = () => (data.store.part_text_accum_delta?.[part().id] ?? part().text ?? "").trim()

  return (
    <Show when={text()}>
@@ -2,7 +2,7 @@
  "name": "@opencode-ai/web",
  "type": "module",
  "license": "MIT",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "scripts": {
    "dev": "astro dev",
    "dev:remote": "VITE_API_URL=https://api.opencode.ai astro dev",
@@ -51,25 +51,30 @@ Repeated setup work, long sleeps/timeouts, serial integration tests, filesystem/

 ## Hypothesis Loop

-| Hypothesis                                                                                                | Change                                                                                         | Before    | After   | Decision | Notes                                                                                                                       |
-| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Repeated full-suite runs are too expensive for discovery                                                  | Switched full-suite benchmark to one run and added per-file profiler                           | ~250s/run | pending | keep     | Bun has no slowest-test reporter in this version; profile files directly.                                                   |
-| Plugin install concurrency test spends time spawning more workers than needed to exercise lock contention | Reduced worker counts from 12/10/8 to 6/6/5; kept `holdMs: 30`                                 | 7.800s    | 6.204s  | keep     | Median from 3 targeted runs; still covers concurrent cross-process writes to server, server+tui, and existing json config.  |
-| `httpapi-listen` PTY route tests pay for git repositories they do not assert on                           | Removed `git: true` from temp dirs while keeping config setup                                  | 10.554s   | 7.818s  | keep     | Median from 3 targeted runs; HTTP routes, tickets, websocket upgrade, restart, and no-auth paths still pass.                |
-| `workspace.waitForSync` timeout test waits the full production timeout                                    | Added optional timeout parameter defaulting to production timeout; timeout test uses 25ms      | 12.949s   | 8.305s  | keep     | Median from 3 targeted runs; production callers keep the 5000ms default.                                                    |
-| `config.test` waits after dependencies even though `.gitignore` is written synchronously                  | Removed obsolete 1000ms sleep from writable `OPENCODE_CONFIG_DIR` test                         | 10.270s   | 9.433s  | keep     | Median from 5 targeted runs because one run was noisy; simpler test and no fixed sleep.                                     |
-| SDK parity helpers create git repos for tests that only need files/config/session state                   | Changed `withProject` default to no git; explicit git init test still opts into no-git fixture | 8.011s    | 5.180s  | keep     | Median from 5 targeted runs because first run was cold/noisy.                                                               |
-| Provider plugin filter test waits on plugin dependency readiness setup                                    | Marked local plugin dependencies ready using the existing fixture helper                       | 7.543s    | 6.366s  | keep     | Median from 3 targeted runs; matches neighboring plugin provider test setup.                                                |
-| HTTP provider tests generate local plugins without dependency-ready fixture state                         | Marked generated `.opencode` plugin fixtures dependency-ready                                  | 7.905s    | 2.980s  | keep     | Median from 3 targeted runs; avoids unrelated plugin dependency setup in route tests.                                       |
-| TUI plugin lifecycle timeout coverage waits the full production cleanup timeout                           | Added optional runtime dispose timeout override and used 25ms in the timeout test              | 7.330s    | 1.507s  | keep     | Median from 3 targeted runs; production default remains 5000ms.                                                             |
-| Skill tool test initializes git even though it only reads local skill files                               | Removed `git: true` from the temporary directory fixture                                       | 2.320s    | 1.425s  | keep     | Single targeted rerun; still exercises skill discovery, permission request, and bundled file output.                        |
-| Prompt shell semantics tests initialize git though they only assert shell/session behavior                | Removed `git: true` from shell-focused prompt fixtures while preserving config setup           | 26.930s   | 23.400s | keep     | Three targeted reruns passed after the change: 23.80s, 23.55s, 23.40s.                                                      |
-| Remaining prompt behavior tests mostly do not require repository state                                    | Removed git setup from safe loop/reference/error fixtures; restored shell queue/cancel cases   | 23.400s   | 19.610s | keep     | Safety review found shell runner readiness depends on git-backed setup in several tests; current single rerun passes.       |
-| Session processor effect tests do not require repository state                                            | Removed git setup from all processor-effect temp server fixtures                               | 12.500s   | 9.230s  | keep     | Two targeted reruns passed after the change: 9.61s, 9.23s.                                                                  |
-| HTTP listen PTY ticket tests restart the same listener topology twice                                     | Folded directory-scoped ticket regression into the broader unsafe-ticket test                  | 7.051s    | 6.170s  | keep     | Two targeted reruns passed after the change: 6.76s, 6.17s; still covers mint failure and successful same-directory upgrade. |
-| File watcher readiness can write before async native subscriptions are active                             | Retried short readiness writes and accepted symlink-realpath HEAD events                       | failed    | 4.62s   | keep     | Three sequential focused watcher runs passed: 4.62s, 4.57s, 4.64s; full suite no longer failed in `watcher.test.ts`.        |
-| First provider config/env/filtering block can use Effect-aware instance fixtures                          | Migrated six `tmpdir` + `withTestInstance` cases to `it.instance`                              | 6.06s     | 6.07s   | keep     | Neutral timing, but removes manual config file writes and instance plumbing; use as the pattern for later provider slices.  |
-| Custom provider/model config cases can use Effect-aware instance fixtures                                 | Migrated three more config-heavy provider cases to `it.instance`                               | 6.07s     | 6.12s   | keep     | Neutral timing within noise, but continues removing manual config file writes on top of the first provider fixture PR.      |
+| Hypothesis                                                                                                | Change                                                                                         | Before    | After   | Decision | Notes                                                                                                                        |
+| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Repeated full-suite runs are too expensive for discovery                                                  | Switched full-suite benchmark to one run and added per-file profiler                           | ~250s/run | pending | keep     | Bun has no slowest-test reporter in this version; profile files directly.                                                    |
+| Plugin install concurrency test spends time spawning more workers than needed to exercise lock contention | Reduced worker counts from 12/10/8 to 6/6/5; kept `holdMs: 30`                                 | 7.800s    | 6.204s  | keep     | Median from 3 targeted runs; still covers concurrent cross-process writes to server, server+tui, and existing json config.   |
+| `httpapi-listen` PTY route tests pay for git repositories they do not assert on                           | Removed `git: true` from temp dirs while keeping config setup                                  | 10.554s   | 7.818s  | keep     | Median from 3 targeted runs; HTTP routes, tickets, websocket upgrade, restart, and no-auth paths still pass.                 |
+| `workspace.waitForSync` timeout test waits the full production timeout                                    | Added optional timeout parameter defaulting to production timeout; timeout test uses 25ms      | 12.949s   | 8.305s  | keep     | Median from 3 targeted runs; production callers keep the 5000ms default.                                                     |
+| `config.test` waits after dependencies even though `.gitignore` is written synchronously                  | Removed obsolete 1000ms sleep from writable `OPENCODE_CONFIG_DIR` test                         | 10.270s   | 9.433s  | keep     | Median from 5 targeted runs because one run was noisy; simpler test and no fixed sleep.                                      |
+| SDK parity helpers create git repos for tests that only need files/config/session state                   | Changed `withProject` default to no git; explicit git init test still opts into no-git fixture | 8.011s    | 5.180s  | keep     | Median from 5 targeted runs because first run was cold/noisy.                                                                |
+| Provider plugin filter test waits on plugin dependency readiness setup                                    | Marked local plugin dependencies ready using the existing fixture helper                       | 7.543s    | 6.366s  | keep     | Median from 3 targeted runs; matches neighboring plugin provider test setup.                                                 |
+| HTTP provider tests generate local plugins without dependency-ready fixture state                         | Marked generated `.opencode` plugin fixtures dependency-ready                                  | 7.905s    | 2.980s  | keep     | Median from 3 targeted runs; avoids unrelated plugin dependency setup in route tests.                                        |
+| TUI plugin lifecycle timeout coverage waits the full production cleanup timeout                           | Added optional runtime dispose timeout override and used 25ms in the timeout test              | 7.330s    | 1.507s  | keep     | Median from 3 targeted runs; production default remains 5000ms.                                                              |
+| Skill tool test initializes git even though it only reads local skill files                               | Removed `git: true` from the temporary directory fixture                                       | 2.320s    | 1.425s  | keep     | Single targeted rerun; still exercises skill discovery, permission request, and bundled file output.                         |
+| Prompt shell semantics tests initialize git though they only assert shell/session behavior                | Removed `git: true` from shell-focused prompt fixtures while preserving config setup           | 26.930s   | 23.400s | keep     | Three targeted reruns passed after the change: 23.80s, 23.55s, 23.40s.                                                       |
+| Remaining prompt behavior tests mostly do not require repository state                                    | Removed git setup from safe loop/reference/error fixtures; restored shell queue/cancel cases   | 23.400s   | 19.610s | keep     | Safety review found shell runner readiness depends on git-backed setup in several tests; current single rerun passes.        |
+| Session processor effect tests do not require repository state                                            | Removed git setup from all processor-effect temp server fixtures                               | 12.500s   | 9.230s  | keep     | Two targeted reruns passed after the change: 9.61s, 9.23s.                                                                   |
+| HTTP listen PTY ticket tests restart the same listener topology twice                                     | Folded directory-scoped ticket regression into the broader unsafe-ticket test                  | 7.051s    | 6.170s  | keep     | Two targeted reruns passed after the change: 6.76s, 6.17s; still covers mint failure and successful same-directory upgrade.  |
+| File watcher readiness can write before async native subscriptions are active                             | Retried short readiness writes and accepted symlink-realpath HEAD events                       | failed    | 4.62s   | keep     | Three sequential focused watcher runs passed: 4.62s, 4.57s, 4.64s; full suite no longer failed in `watcher.test.ts`.         |
+| First provider config/env/filtering block can use Effect-aware instance fixtures                          | Migrated six `tmpdir` + `withTestInstance` cases to `it.instance`                              | 6.06s     | 6.07s   | keep     | Neutral timing, but removes manual config file writes and instance plumbing; use as the pattern for later provider slices.   |
+| Custom provider/model config cases can use Effect-aware instance fixtures                                 | Migrated three more config-heavy provider cases to `it.instance`                               | 6.07s     | 6.12s   | keep     | Neutral timing within noise, but continues removing manual config file writes on top of the first provider fixture PR.       |
+| Provider env precedence and model lookup cases can use Effect-aware instance fixtures                     | Migrated four more provider lookup/default-model cases to `it.instance`                        | 6.12s     | 6.36s   | keep     | Noisy 5-run median; kept as a small stacked cleanup slice but do not claim speedup from this migration.                      |
+| Simple config load cases can use Effect-aware instance fixtures                                           | Migrated JSON, shell, formatter, and lsp config load cases to `it.instance`                    | 14.18s    | 3.93s   | keep     | Three-run medians before/after; removes manual `tmpdir` + `withTestInstance` setup from the first simple config block.       |
+| Config template, file include, and simple agent cases can use Effect-aware instance fixtures              | Migrated JSONC, env/file substitution, invalid config, and agent config cases to `it.instance` | 1.87s     | 1.90s   | keep     | Stacked on the first config slice; neutral timing but removes more manual `tmpdir` + instance plumbing.                      |
+| Agent option, command, and legacy migration config cases can use Effect-aware instance fixtures           | Migrated agent variant, command, autoshare, and mode migration cases to `it.instance`          | 1.90s     | 1.83s   | keep     | Stacked on the config template slice; small neutral-to-positive timing and less manual setup.                                |
+| Local config update and directory cases can use Effect-aware instance fixtures                            | Migrated local `update` and `directories` cases to `it.instance`                               | 1.77s     | 1.71s   | keep     | Three-run medians; small positive/neutral timing, removes manual instance plumbing, and eliminates one existing unsafe cast. |

 ## Profiling Results

@@ -2,7 +2,7 @@
  "name": "opencode",
  "displayName": "opencode",
  "description": "opencode for VS Code",
-  "version": "1.15.4",
+  "version": "1.15.5",
  "publisher": "sst-dev",
  "repository": {
    "type": "git",
Author	SHA1	Message	Date
Kit Langton	af1e67d850	test(cli): stabilize acp --help snapshot against random home path length yargs wraps the \`[string] [default: "..."]\` clause based on the pre-normalized default value's character length, so a different random tmpdir width produces a different leading-whitespace count on the wrapped continuation line. After normalizing the path to \`<HOME>\` we were left with a one-space drift between runs. Collapse the wrap-dependent whitespace immediately before the clause so the snapshot is byte-stable regardless of home path length. Verified by deleting the .snap and regenerating across 3 runs.	2026-05-18 21:22:59 -04:00
Kit Langton	13e68a5892	refactor(test/lib): simplify cli-process helpers per Effect idioms Applied review findings from the simplify pass: 1. Extract fromBunStream(name, get) and forkStderrDrain(stream, into) helpers — 4 duplicated Stream.fromReadableStream call sites collapse to one factory, and the identical stderr drain across serve/acp is now a single helper. Error messages now include the underlying cause instead of swallowing it. 2. acp.send awaits proc.stdin.write's backpressure promise. The bare Effect.sync was discarding the Promise<number> form, which can reorder ndjson lines under pipe-buffer-full conditions and corrupt framing. 3. acp.close drops the try/catch around proc.stdin.end() — idempotent in Bun, the bare catch only masked future regressions. 4. Effect.ignore on stream drains is now Effect.ignore({ log: true }) so a real protocol or decode error surfaces in test debug output instead of disappearing silently. 5. Help-snapshots replaces the manual failures[] accumulator + continue with Effect.partition. Same behavior, no mutable state, declarative. 324/324 CLI tests stay green; typecheck clean.	2026-05-18 21:11:29 -04:00
Kit Langton	8db5e421ab	test(cli): help-text snapshots for every CLI command One test file. Spawns `opencode <cmd> --help` for every documented command + key subcommand (35 in total) in parallel under concurrency:8, snapshots the stderr output (yargs writes --help to stderr, not stdout). Snapshots are normalized — the tmpdir prefix that bleeds through `acp --cwd`'s default is rewritten to `<HOME>` so test runs in different sandboxes stay stable. macOS `/private` realpath form and the unresolved `os.tmpdir()` form both covered. Pinned snapshots catch flag removals, renames, reordering, and exit-code regressions across the entire user-facing CLI surface in one place. Diff in the .snap file is the surface-change report. Excluded: `opencode completion --help` is a yargs built-in that emits top-level help and exits 1; not a real opencode command. ~6s wall-clock thanks to parallel spawns.	2026-05-18 21:11:29 -04:00
Kit Langton	8513472542	refactor(test/lib): use Effect.timeoutOrElse for acp release shutdown Replaces raw Promise.race + setTimeout in the acp builder's release finalizer with an Effect.gen that expresses the graceful-then-SIGTERM race using Effect.timeoutOrElse(Duration.seconds(2)). Same behavior, no leaked timer, consistent with the serve builder.	2026-05-18 21:10:06 -04:00
Kit Langton	29cf700361	test(cli): subprocess integration tests for opencode acp Adds the second long-lived-command builder to the cli-process harness: `opencode.acp(opts)` spawns the real CLI in JSON-RPC-over-stdio mode and returns a duplex handle (`send`/`receive`/`close`/`exited`) scoped to the test's lifetime. Stdin EOF triggers a clean shutdown; the scope finalizer also falls back to SIGTERM after 2s for a hung child. ACP frames each JSON-RPC message as one ndjson line on stdout. The builder forks a scope-bound `Stream.fromReadableStream` + `splitLines` pipeline that feeds parsed responses into a `Queue.unbounded`, so tests can `yield* acp.receive` without worrying about backpressure or framing. Two smoke tests: - `initialize` round-trip — sends the protocol handshake from the ACP README and asserts the response advertises the same protocolVersion and a non-empty agentCapabilities block. - Clean shutdown on stdin EOF — proves the scope finalizer's stdin.end() triggers a graceful exit, not a SIGTERM-fallback exit.	2026-05-18 21:10:06 -04:00
Kit Langton	c032e821bc	Migrate config update tests to instance fixtures (#28266 )	2026-05-18 20:57:42 -04:00
opencode-agent[bot]	6f160bb48f	chore: generate	2026-05-19 00:57:09 +00:00
Kit Langton	ebb672ac39	test(cli): subprocess integration tests for opencode serve (#28263 )	2026-05-19 00:55:58 +00:00
Kit Langton	9a19e84265	Migrate config agent tests to instance fixtures (#28213 )	2026-05-18 23:55:33 +00:00
Kit Langton	338666d13e	Migrate config template tests to instance fixtures (#28211 )	2026-05-18 23:37:58 +00:00
Kit Langton	7b8a1037a0	refactor(test/lib): generalize run-process harness into cli-process (#28253 )	2026-05-18 19:16:10 -04:00
Kit Langton	ee5cf45ef9	Migrate simple config tests to instance fixtures (#28210 )	2026-05-18 19:13:16 -04:00
opencode-agent[bot]	2e1593dea5	chore: generate	2026-05-18 22:33:32 +00:00
Kit Langton	0f3d168fdd	test(cli): subprocess integration test harness + regression suite for opencode run (#28230 )	2026-05-18 18:32:20 -04:00
opencode-agent[bot]	ce09fc8356	chore: generate	2026-05-18 22:03:00 +00:00
Luke Parker	44a35c5895	test(app): add session timeline smoke coverage (#26619 )	2026-05-18 22:01:29 +00:00
Kit Langton	8a321c4536	fix(native-llm): prefer console opencode token (#28237 )	2026-05-18 17:23:57 -04:00
opencode	ef9e567e5f	sync release versions for v1.15.5	2026-05-18 20:57:13 +00:00
Kit Langton	b396b71c6f	fix(ui): guard reasoning renderer against undefined text (#28222 )	2026-05-18 16:04:07 -04:00
Aiden Cline	d8efc575fa	refactor(session): extract prompt tool resolution (#28204 )	2026-05-18 14:50:31 -05:00
opencode-agent[bot]	e1fbed8fb6	chore: update nix node_modules hashes	2026-05-18 19:12:18 +00:00
James Long	12ae22378f	fix(plugin): `ask` in tools from plugins returns promise instead of effect (#28217 )	2026-05-18 18:57:29 +00:00
opencode-agent[bot]	a88b436eec	chore: generate	2026-05-18 18:42:55 +00:00
Kit Langton	dbe36851bc	Preview native LLM runtime stack (#27114 )	2026-05-18 14:41:36 -04:00
James Long	ff9d7cab5c	fix(core): fix file references in workspaces (#28209 )	2026-05-18 18:23:35 +00:00
Kit Langton	88681d389b	Migrate provider lookup tests to instance fixtures Migrate provider env precedence, model lookup, and default model tests to Effect-aware instance fixtures while keeping behavior unchanged.	2026-05-18 18:01:53 +00:00