perf(tui): tighten markdown demo rendering

bun.lock

@@ -29,7 +29,7 @@
     },
     "packages/app": {
       "name": "@opencode-ai/app",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@kobalte/core": "catalog:",
         "@opencode-ai/core": "workspace:*",
@@ -85,7 +85,7 @@
     },
     "packages/console/app": {
       "name": "@opencode-ai/console-app",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@cloudflare/vite-plugin": "1.15.2",
         "@ibm/plex": "6.4.1",
@@ -120,7 +120,7 @@
     },
     "packages/console/core": {
       "name": "@opencode-ai/console-core",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@aws-sdk/client-sts": "3.782.0",
         "@jsx-email/render": "1.1.1",
@@ -147,7 +147,7 @@
     },
     "packages/console/function": {
       "name": "@opencode-ai/console-function",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@ai-sdk/anthropic": "3.0.64",
         "@ai-sdk/openai": "3.0.48",
@@ -171,7 +171,7 @@
     },
     "packages/console/mail": {
       "name": "@opencode-ai/console-mail",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@jsx-email/all": "2.2.3",
         "@jsx-email/cli": "1.4.3",
@@ -195,7 +195,7 @@
     },
     "packages/core": {
       "name": "@opencode-ai/core",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "bin": {
         "opencode": "./bin/opencode",
       },
@@ -229,7 +229,7 @@
     },
     "packages/desktop": {
       "name": "@opencode-ai/desktop",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "drizzle-orm": "catalog:",
         "effect": "catalog:",
@@ -283,7 +283,7 @@
     },
     "packages/enterprise": {
       "name": "@opencode-ai/enterprise",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@opencode-ai/core": "workspace:*",
         "@opencode-ai/ui": "workspace:*",
@@ -313,7 +313,7 @@
     },
     "packages/function": {
       "name": "@opencode-ai/function",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@octokit/auth-app": "8.0.1",
         "@octokit/rest": "catalog:",
@@ -329,7 +329,7 @@
     },
     "packages/http-recorder": {
       "name": "@opencode-ai/http-recorder",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@effect/platform-node": "catalog:",
         "effect": "catalog:",
@@ -342,7 +342,7 @@
     },
     "packages/llm": {
       "name": "@opencode-ai/llm",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@smithy/eventstream-codec": "4.2.14",
         "@smithy/util-utf8": "4.2.2",
@@ -360,7 +360,7 @@
     },
     "packages/opencode": {
       "name": "opencode",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "bin": {
         "opencode": "./bin/opencode",
       },
@@ -496,7 +496,7 @@
     },
     "packages/plugin": {
       "name": "@opencode-ai/plugin",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@opencode-ai/sdk": "workspace:*",
         "effect": "catalog:",
@@ -534,7 +534,7 @@
     },
     "packages/sdk/js": {
       "name": "@opencode-ai/sdk",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "cross-spawn": "catalog:",
       },
@@ -549,7 +549,7 @@
     },
     "packages/slack": {
       "name": "@opencode-ai/slack",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@opencode-ai/sdk": "workspace:*",
         "@slack/bolt": "^3.17.1",
@@ -584,7 +584,7 @@
     },
     "packages/ui": {
       "name": "@opencode-ai/ui",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@kobalte/core": "catalog:",
         "@opencode-ai/core": "workspace:*",
@@ -633,7 +633,7 @@
     },
     "packages/web": {
       "name": "@opencode-ai/web",
-      "version": "1.14.48",
+      "version": "1.14.46",
       "dependencies": {
         "@astrojs/cloudflare": "12.6.3",
         "@astrojs/markdown-remark": "6.3.1",

package.json

@@ -7,6 +7,8 @@
   "packageManager": "bun@1.3.13",
   "scripts": {
     "dev": "bun run --cwd packages/opencode --conditions=browser src/index.ts",
+    "dev:demo": "bun run --cwd packages/opencode --conditions=browser src/index.ts --demo",
+    "dev:run-demo": "bun run --cwd packages/opencode --conditions=browser src/index.ts run --interactive --demo",
     "dev:desktop": "bun --cwd packages/desktop dev",
     "dev:web": "bun --cwd packages/app dev",
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",

packages/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/app",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "description": "",
   "type": "module",
   "exports": {

packages/app/src/context/global-sync/child-store.ts

@@ -231,7 +231,6 @@ export function createChildStoreManager(input: {
             limit: 5,
             message: {},
             part: {},
-            part_text_accum_delta: {},
           })
           children[key] = child
           disposers.set(key, dispose)

packages/app/src/context/global-sync/event-reducer.test.ts

@@ -81,7 +81,6 @@ const baseState = (input: Partial<State> = {}) =>
     limit: 10,
     message: {},
     part: {},
-    part_text_accum_delta: {},
     ...input,
   }) as State
 

packages/app/src/context/global-sync/event-reducer.ts

@@ -211,12 +211,6 @@ export function applyDirectoryEvent(input: {
             const result = Binary.search(messages, props.messageID, (m) => m.id)
             if (result.found) messages.splice(result.index, 1)
           }
-          const parts = draft.part[props.messageID]
-          if (parts) {
-            for (const part of parts) {
-              delete draft.part_text_accum_delta[part.id]
-            }
-          }
           delete draft.part[props.messageID]
         }),
       )
@@ -225,11 +219,6 @@ export function applyDirectoryEvent(input: {
     case "message.part.updated": {
       const part = (event.properties as { part: Part }).part
       if (SKIP_PARTS.has(part.type)) break
-      input.setStore(
-        produce((draft) => {
-          delete draft.part_text_accum_delta[part.id]
-        }),
-      )
       const parts = input.store.part[part.messageID]
       if (!parts) {
         input.setStore("part", part.messageID, [part])
@@ -251,11 +240,6 @@ export function applyDirectoryEvent(input: {
     }
     case "message.part.removed": {
       const props = event.properties as { messageID: string; partID: string }
-      input.setStore(
-        produce((draft) => {
-          delete draft.part_text_accum_delta[props.partID]
-        }),
-      )
       const parts = input.store.part[props.messageID]
       if (!parts) break
       const result = Binary.search(parts, props.partID, (p) => p.id)
@@ -279,7 +263,6 @@ export function applyDirectoryEvent(input: {
       if (!parts) break
       const result = Binary.search(parts, props.partID, (p) => p.id)
       if (!result.found) break
-      input.setStore("part_text_accum_delta", props.partID, (existing) => (existing ?? "") + props.delta)
       input.setStore(
         "part",
         props.messageID,

packages/app/src/context/global-sync/session-cache.test.ts

@@ -39,7 +39,6 @@ describe("app session cache", () => {
       part: Record<string, Part[] | undefined>
       permission: Record<string, PermissionRequest[] | undefined>
       question: Record<string, QuestionRequest[] | undefined>
-      part_text_accum_delta: Record<string, string | undefined>
     } = {
       session_status: { ses_1: { type: "busy" } as SessionStatus },
       session_diff: { ses_1: [] },
@@ -48,14 +47,12 @@ describe("app session cache", () => {
       part: { msg_1: [part("prt_1", "ses_1", "msg_1")] },
       permission: { ses_1: [] as PermissionRequest[] },
       question: { ses_1: [] as QuestionRequest[] },
-      part_text_accum_delta: { prt_1: "streamed text" },
     }
 
     dropSessionCaches(store, ["ses_1"])
 
     expect(store.message.ses_1).toBeUndefined()
     expect(store.part.msg_1).toBeUndefined()
-    expect(store.part_text_accum_delta.prt_1).toBeUndefined()
     expect(store.todo.ses_1).toBeUndefined()
     expect(store.session_diff.ses_1).toBeUndefined()
     expect(store.session_status.ses_1).toBeUndefined()
@@ -73,7 +70,6 @@ describe("app session cache", () => {
       part: Record<string, Part[] | undefined>
       permission: Record<string, PermissionRequest[] | undefined>
       question: Record<string, QuestionRequest[] | undefined>
-      part_text_accum_delta: Record<string, string | undefined>
     } = {
       session_status: {},
       session_diff: {},
@@ -82,7 +78,6 @@ describe("app session cache", () => {
       part: { [m.id]: [part("prt_1", "ses_1", m.id)] },
       permission: {},
       question: {},
-      part_text_accum_delta: {},
     }
 
     dropSessionCaches(store, ["ses_1"])

packages/app/src/context/global-sync/session-cache.ts

@@ -18,7 +18,6 @@ type SessionCache = {
   part: Record<string, Part[] | undefined>
   permission: Record<string, PermissionRequest[] | undefined>
   question: Record<string, QuestionRequest[] | undefined>
-  part_text_accum_delta: Record<string, string | undefined>
 }
 
 export function dropSessionCaches(store: SessionCache, sessionIDs: Iterable<string>) {
@@ -28,9 +27,6 @@ export function dropSessionCaches(store: SessionCache, sessionIDs: Iterable<stri
   for (const key of Object.keys(store.part)) {
     const parts = store.part[key]
     if (!parts?.some((part) => stale.has(part?.sessionID ?? ""))) continue
-    for (const part of parts) {
-      delete store.part_text_accum_delta[part.id]
-    }
     delete store.part[key]
   }
 

packages/app/src/context/global-sync/types.ts

@@ -72,9 +72,6 @@ export type State = {
   part: {
     [messageID: string]: Part[]
   }
-  part_text_accum_delta: {
-    [partID: string]: string
-  }
 }
 
 export type VcsCache = {

packages/console/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/console-app",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "type": "module",
   "license": "MIT",
   "scripts": {

packages/console/app/src/routes/workspace/[id]/usage/usage-section.module.css

@@ -67,7 +67,6 @@
         display: inline-flex;
         align-items: center;
         justify-content: center;
-        flex-shrink: 0;
         padding: 0;
         background: transparent;
         border: none;
@@ -80,7 +79,6 @@
         }
 
         svg {
-          flex-shrink: 0;
           width: 16px;
           height: 16px;
         }

packages/console/app/src/routes/workspace/[id]/usage/usage-section.tsx

@@ -53,7 +53,7 @@ export function UsageSection() {
   }
 
   const calculateTotalOutputTokens = (u: Awaited<ReturnType<typeof getUsageInfo>>[0]) => {
-    return u.outputTokens
+    return u.outputTokens + (u.reasoningTokens ?? 0)
   }
 
   const goPrev = async () => {

packages/console/app/src/routes/zen/util/handler.ts

@@ -889,6 +889,10 @@ export async function handler(
 
     const inputCost = modelCost.input * inputTokens * 100
     const outputCost = modelCost.output * outputTokens * 100
+    const reasoningCost = (() => {
+      if (!reasoningTokens) return undefined
+      return modelCost.output * reasoningTokens * 100
+    })()
     const cacheReadCost = (() => {
       if (!cacheReadTokens) return undefined
       if (!modelCost.cacheRead) return undefined
@@ -905,11 +909,17 @@ export async function handler(
       return modelCost.cacheWrite1h * cacheWrite1hTokens * 100
     })()
     const totalCostInCent =
-      inputCost + outputCost + (cacheReadCost ?? 0) + (cacheWrite5mCost ?? 0) + (cacheWrite1hCost ?? 0)
+      inputCost +
+      outputCost +
+      (reasoningCost ?? 0) +
+      (cacheReadCost ?? 0) +
+      (cacheWrite5mCost ?? 0) +
+      (cacheWrite1hCost ?? 0)
     return {
       totalCostInCent,
       inputCost,
       outputCost,
+      reasoningCost,
       cacheReadCost,
       cacheWrite5mCost,
       cacheWrite1hCost,
@@ -931,7 +941,8 @@ export async function handler(
   ) {
     const { inputTokens, outputTokens, reasoningTokens, cacheReadTokens, cacheWrite5mTokens, cacheWrite1hTokens } =
       usageInfo
-    const { totalCostInCent, inputCost, outputCost, cacheReadCost, cacheWrite5mCost, cacheWrite1hCost } = costInfo
+    const { totalCostInCent, inputCost, outputCost, reasoningCost, cacheReadCost, cacheWrite5mCost, cacheWrite1hCost } =
+      costInfo
 
     logger.metric({
       "tokens.input": inputTokens,
@@ -942,12 +953,14 @@ export async function handler(
       "tokens.cache_write_1h": cacheWrite1hTokens,
       "cost.input.microcents": centsToMicroCents(inputCost),
       "cost.output.microcents": centsToMicroCents(outputCost),
+      "cost.reasoning.microcents": reasoningCost ? centsToMicroCents(reasoningCost) : undefined,
       "cost.cache_read.microcents": cacheReadCost ? centsToMicroCents(cacheReadCost) : undefined,
       "cost.cache_write.microcents": cacheWrite5mCost ? centsToMicroCents(cacheWrite5mCost) : undefined,
       "cost.total.microcents": centsToMicroCents(totalCostInCent),
       // deprecated - remove after May 20, 2026
       "cost.input": Math.round(inputCost),
       "cost.output": Math.round(outputCost),
+      "cost.reasoning": reasoningCost ? Math.round(reasoningCost) : undefined,
       "cost.cache_read": cacheReadCost ? Math.round(cacheReadCost) : undefined,
       "cost.cache_write_5m": cacheWrite5mCost ? Math.round(cacheWrite5mCost) : undefined,
       "cost.cache_write_1h": cacheWrite1hCost ? Math.round(cacheWrite1hCost) : undefined,

packages/console/app/src/routes/zen/util/provider/openai.ts

@@ -50,7 +50,7 @@ export const openaiHelper: ProviderHelper = ({ workspaceID }) => ({
     const cacheReadTokens = usage.input_tokens_details?.cached_tokens ?? undefined
     return {
       inputTokens: inputTokens - (cacheReadTokens ?? 0),
-      outputTokens,
+      outputTokens: outputTokens - (reasoningTokens ?? 0),
       reasoningTokens,
       cacheReadTokens,
       cacheWrite5mTokens: undefined,

packages/console/core/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode-ai/console-core",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "private": true,
   "type": "module",
   "license": "MIT",

packages/console/function/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/console-function",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "$schema": "https://json.schemastore.org/package.json",
   "private": true,
   "type": "module",

packages/console/mail/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/console-mail",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "dependencies": {
     "@jsx-email/all": "2.2.3",
     "@jsx-email/cli": "1.4.3",

packages/core/package.json

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

packages/core/src/effect-zod.ts

@@ -36,7 +36,7 @@ export function zod<S extends Schema.Top>(schema: S): z.ZodType<Schema.Schema.Ty
  * mapped `.omit()` / `.extend()` surface triggers brand-intersection
  * explosions for branded primitives (`string & Brand<"SessionID">` extends
  * `object` via the brand and gets walked into the prototype by `DeepPartial`,
- * mapped-schema helpers, and zod's inference through `z.ZodType<T | undefined>`
+ * `updateSchema`, etc.), and zod's inference through `z.ZodType<T | undefined>`
  * wrappers also can't reconstruct `T` cleanly. Consumers that care about the
  * post-`.omit()` shape should cast `c.req.valid(...)` to the expected type.
  */

packages/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opencode-ai/desktop",
   "private": true,
-  "version": "1.14.48",
+  "version": "1.14.46",
   "type": "module",
   "license": "MIT",
   "homepage": "https://opencode.ai",

packages/enterprise/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/enterprise",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "private": true,
   "type": "module",
   "license": "MIT",

packages/extensions/zed/extension.toml

@@ -1,7 +1,7 @@
 id = "opencode"
 name = "OpenCode"
 description = "The open source coding agent."
-version = "1.14.48"
+version = "1.14.46"
 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.14.48/opencode-darwin-arm64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.46/opencode-darwin-arm64.zip"
 cmd = "./opencode"
 args = ["acp"]
 
 [agent_servers.opencode.targets.darwin-x86_64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/opencode-darwin-x64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.46/opencode-darwin-x64.zip"
 cmd = "./opencode"
 args = ["acp"]
 
 [agent_servers.opencode.targets.linux-aarch64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/opencode-linux-arm64.tar.gz"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.46/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.14.48/opencode-linux-x64.tar.gz"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.46/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.14.48/opencode-windows-x64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.46/opencode-windows-x64.zip"
 cmd = "./opencode.exe"
 args = ["acp"]

packages/function/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/function",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "$schema": "https://json.schemastore.org/package.json",
   "private": true,
   "type": "module",

packages/http-recorder/README.md

@@ -16,9 +16,8 @@ import { HttpRecorder } from "@opencode-ai/http-recorder"
 ## Quickstart
 
 Provide `cassetteLayer(name)` in place of (or layered over) your `HttpClient`.
-By default the layer records on first run and replays on subsequent runs —
-no env-var ternary at the call site, and `CI=true` forces strict replay so
-missing cassettes fail loudly in CI rather than silently re-recording.
+The first run records to `test/fixtures/recordings/<name>.json`; subsequent
+runs replay from it.
 
 ```ts
 import { Effect } from "effect"
@@ -31,22 +30,28 @@ const program = Effect.gen(function* () {
   return yield* response.json
 })
 
-// Records if the cassette is missing, replays if it exists.
-// In CI (CI=true) always replays — fails loudly on missing fixtures.
+// Replay (default). Fails if the cassette is missing.
 Effect.runPromise(program.pipe(Effect.provide(HttpRecorder.cassetteLayer("users/get-one"))))
 
-// Force a refresh — always hits upstream and overwrites.
+// Record. Hits the upstream and writes the cassette.
 Effect.runPromise(program.pipe(Effect.provide(HttpRecorder.cassetteLayer("users/get-one", { mode: "record" }))))
 ```
 
+Set the mode from the environment in your test setup:
+
+```ts
+HttpRecorder.cassetteLayer("users/get-one", {
+  mode: process.env.RECORD === "true" ? "record" : "replay",
+})
+```
+
 ## Modes
 
-| Mode          | Behavior                                                                            |
-| ------------- | ----------------------------------------------------------------------------------- |
-| `auto`        | Default. Replay if the cassette exists; record if missing. `CI=true` forces replay. |
-| `replay`      | Strict — match the request to a recorded interaction; error if none.                |
-| `record`      | Execute upstream, append the interaction, write the cassette.                       |
-| `passthrough` | Bypass the recorder entirely — just call upstream.                                  |
+| Mode          | Behavior                                                             |
+| ------------- | -------------------------------------------------------------------- |
+| `replay`      | Default. Match the request to a recorded interaction; error if none. |
+| `record`      | Execute upstream, append the interaction, write the cassette.        |
+| `passthrough` | Bypass the recorder entirely — just call upstream.                   |
 
 ## Cassette format
 
@@ -96,6 +101,7 @@ secrets escape. Redaction is configured by composing a `Redactor`:
 import { HttpRecorder, Redactor } from "@opencode-ai/http-recorder"
 
 HttpRecorder.cassetteLayer("anthropic/messages", {
+  mode: process.env.RECORD === "true" ? "record" : "replay",
   redactor: Redactor.defaults({
     requestHeaders: { allow: ["content-type", "anthropic-version"] },
     url: { transform: (url) => url.replace(/\/accounts\/[^/]+/, "/accounts/{account}") },
@@ -151,6 +157,7 @@ const program = Effect.gen(function* () {
   const cassette = yield* HttpRecorder.Cassette.Service
   const executor = yield* HttpRecorder.makeWebSocketExecutor({
     name: "ws/subscribe",
+    mode: process.env.RECORD === "true" ? "record" : "replay",
     cassette,
     live: liveExecutor,
   })
@@ -160,9 +167,9 @@ const program = Effect.gen(function* () {
 
 ## Inspecting cassettes programmatically
 
-`Cassette.Service` exposes `read`, `append`, `exists`, and `list`. `read`
-returns the recorded interactions for a name; the file format is hidden
-behind the seam. Useful for CI checks:
+`Cassette.Service` exposes `read`, `write`, `append`, `exists`, `list`, and
+`scan` (re-running the secret detector over an existing cassette). Useful
+for CI checks:
 
 ```ts
 import { HttpRecorder } from "@opencode-ai/http-recorder"
@@ -170,27 +177,18 @@ import { Effect } from "effect"
 
 const audit = Effect.gen(function* () {
   const cassettes = yield* HttpRecorder.Cassette.Service
-  const entries = yield* cassettes.list()
-  const issues = yield* Effect.forEach(entries, (entry) =>
-    cassettes
-      .read(entry.name)
-      .pipe(Effect.map((interactions) => ({ name: entry.name, findings: HttpRecorder.secretFindings(interactions) }))),
+  const findings = yield* Effect.forEach(yield* cassettes.list(), (entry) =>
+    cassettes.read(entry.name).pipe(Effect.map((c) => ({ entry, findings: cassettes.scan(c) }))),
   )
-  return issues.filter((i) => i.findings.length > 0)
+  return findings.filter((r) => r.findings.length > 0)
 })
 ```
 
-`cassetteLayer` is the batteries-included entry point — it provides
-`Cassette.fileSystem({ directory })` automatically. If you want to provide
-your own `Cassette.Service` (e.g. an in-memory adapter for the recorder's
-own unit tests), use `recordingLayer` and supply `Cassette.fileSystem` /
-`Cassette.memory` yourself.
-
 ## Options reference
 
 ```ts
 type RecordReplayOptions = {
-  mode?: "auto" | "replay" | "record" | "passthrough" // default: "auto" (CI=true forces "replay")
+  mode?: "record" | "replay" | "passthrough" // default: "replay"
   directory?: string // default: <cwd>/test/fixtures/recordings
   metadata?: Record<string, unknown> // merged into cassette.metadata
   redactor?: Redactor // default: Redactor.defaults()

packages/http-recorder/package.json

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

packages/http-recorder/src/cassette.ts

@@ -1,76 +1,62 @@
-import { Context, Effect, FileSystem, Layer, Schema } from "effect"
-import * as fs from "node:fs"
+import { Context, Effect, FileSystem, Layer, PlatformError } from "effect"
 import * as path from "node:path"
-import { secretFindings, type SecretFinding } from "./redaction"
-import { decodeCassette, encodeCassette, type Cassette, type CassetteMetadata, type Interaction } from "./schema"
+import { cassetteSecretFindings, secretFindings, type SecretFinding } from "./redaction"
+import type { Cassette, CassetteMetadata, Interaction } from "./schema"
+import { cassetteFor, cassettePath, DEFAULT_RECORDINGS_DIR, formatCassette, parseCassette } from "./storage"
 
-const DEFAULT_RECORDINGS_DIR = path.resolve(process.cwd(), "test", "fixtures", "recordings")
-
-export class CassetteNotFoundError extends Schema.TaggedErrorClass<CassetteNotFoundError>()("CassetteNotFoundError", {
-  cassetteName: Schema.String,
-}) {
-  override get message() {
-    return `Cassette "${this.cassetteName}" not found`
-  }
-}
-
-export interface AppendResult {
-  readonly findings: ReadonlyArray<SecretFinding>
+export interface Entry {
+  readonly name: string
+  readonly path: string
 }
 
 export interface Interface {
-  readonly read: (name: string) => Effect.Effect<ReadonlyArray<Interaction>, CassetteNotFoundError>
-  readonly append: (name: string, interaction: Interaction, metadata?: CassetteMetadata) => Effect.Effect<AppendResult>
+  readonly path: (name: string) => string
+  readonly read: (name: string) => Effect.Effect<Cassette, PlatformError.PlatformError>
+  readonly write: (name: string, cassette: Cassette) => Effect.Effect<void, PlatformError.PlatformError>
+  readonly append: (
+    name: string,
+    interaction: Interaction,
+    metadata: CassetteMetadata | undefined,
+  ) => Effect.Effect<
+    {
+      readonly cassette: Cassette
+      readonly findings: ReadonlyArray<SecretFinding>
+    },
+    PlatformError.PlatformError
+  >
   readonly exists: (name: string) => Effect.Effect<boolean>
-  readonly list: () => Effect.Effect<ReadonlyArray<string>>
+  readonly list: () => Effect.Effect<ReadonlyArray<Entry>, PlatformError.PlatformError>
+  readonly scan: (cassette: Cassette) => ReadonlyArray<SecretFinding>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode-ai/http-recorder/Cassette") {}
 
-export const hasCassetteSync = (name: string, options: { readonly directory?: string } = {}) =>
-  fs.existsSync(path.join(options.directory ?? DEFAULT_RECORDINGS_DIR, `${name}.json`))
-
-const buildCassette = (
-  name: string,
-  interactions: ReadonlyArray<Interaction>,
-  metadata: CassetteMetadata | undefined,
-): Cassette => ({
-  version: 1,
-  metadata: { name, recordedAt: new Date().toISOString(), ...(metadata ?? {}) },
-  interactions,
-})
-
-const formatCassette = (cassette: Cassette) => `${JSON.stringify(encodeCassette(cassette), null, 2)}\n`
-
-const parseCassette = (raw: string) => decodeCassette(JSON.parse(raw))
-
-export const fileSystem = (
-  options: { readonly directory?: string } = {},
-): Layer.Layer<Service, never, FileSystem.FileSystem> =>
+export const layer = (options: { readonly directory?: string } = {}) =>
   Layer.effect(
     Service,
     Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem
+      const fileSystem = yield* FileSystem.FileSystem
       const directory = options.directory ?? DEFAULT_RECORDINGS_DIR
       const recorded = new Map<string, { interactions: Interaction[]; findings: SecretFinding[] }>()
       const directoriesEnsured = new Set<string>()
 
-      const cassettePath = (name: string) => path.join(directory, `${name}.json`)
+      const pathFor = (name: string) => cassettePath(name, directory)
 
-      const ensureDirectory = (name: string) =>
-        Effect.gen(function* () {
-          const dir = path.dirname(cassettePath(name))
-          if (directoriesEnsured.has(dir)) return
-          yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.orDie)
-          directoriesEnsured.add(dir)
-        })
+      const ensureDirectory = Effect.fn("Cassette.ensureDirectory")(function* (name: string) {
+        const dir = path.dirname(pathFor(name))
+        if (directoriesEnsured.has(dir)) return
+        yield* fileSystem.makeDirectory(dir, { recursive: true })
+        directoriesEnsured.add(dir)
+      })
 
-      const walk = (current: string): Effect.Effect<ReadonlyArray<string>> =>
+      const walk = (directory: string): Effect.Effect<ReadonlyArray<string>, PlatformError.PlatformError> =>
         Effect.gen(function* () {
-          const entries = yield* fs.readDirectory(current).pipe(Effect.catch(() => Effect.succeed([] as string[])))
+          const entries = yield* fileSystem
+            .readDirectory(directory)
+            .pipe(Effect.catch(() => Effect.succeed([] as string[])))
           const nested = yield* Effect.forEach(entries, (entry) => {
-            const full = path.join(current, entry)
-            return fs.stat(full).pipe(
+            const full = path.join(directory, entry)
+            return fileSystem.stat(full).pipe(
               Effect.flatMap((stat) => (stat.type === "Directory" ? walk(full) : Effect.succeed([full]))),
               Effect.catch(() => Effect.succeed([] as string[])),
             )
@@ -78,73 +64,50 @@ export const fileSystem = (
           return nested.flat()
         })
 
-      return Service.of({
-        read: (name) =>
-          fs.readFileString(cassettePath(name)).pipe(
-            Effect.map((raw) => parseCassette(raw).interactions),
-            Effect.catch(() => Effect.fail(new CassetteNotFoundError({ cassetteName: name }))),
-          ),
-        append: (name, interaction, metadata) =>
-          Effect.gen(function* () {
-            const entry = recorded.get(name) ?? { interactions: [], findings: [] }
-            if (!recorded.has(name)) recorded.set(name, entry)
-            entry.interactions.push(interaction)
-            entry.findings.push(...secretFindings(interaction))
-            const cassette = buildCassette(name, entry.interactions, metadata)
-            const findings = [...entry.findings, ...secretFindings(cassette.metadata ?? {})]
-            if (findings.length === 0) {
-              yield* ensureDirectory(name)
-              yield* fs.writeFileString(cassettePath(name), formatCassette(cassette)).pipe(Effect.orDie)
-            }
-            return { findings }
-          }),
-        exists: (name) =>
-          fs.access(cassettePath(name)).pipe(
-            Effect.as(true),
-            Effect.catch(() => Effect.succeed(false)),
-          ),
-        list: () =>
-          walk(directory).pipe(
-            Effect.map((files) =>
-              files
-                .filter((file) => file.endsWith(".json"))
-                .map((file) =>
-                  path
-                    .relative(directory, file)
-                    .replace(/\\/g, "/")
-                    .replace(/\.json$/, ""),
-                )
-                .toSorted((a, b) => a.localeCompare(b)),
-            ),
-          ),
+      const read = Effect.fn("Cassette.read")(function* (name: string) {
+        return parseCassette(yield* fileSystem.readFileString(pathFor(name)))
       })
+
+      const write = Effect.fn("Cassette.write")(function* (name: string, cassette: Cassette) {
+        yield* ensureDirectory(name)
+        yield* fileSystem.writeFileString(pathFor(name), formatCassette(cassette))
+      })
+
+      const append = Effect.fn("Cassette.append")(function* (
+        name: string,
+        interaction: Interaction,
+        metadata: CassetteMetadata | undefined,
+      ) {
+        const entry = recorded.get(name) ?? { interactions: [], findings: [] }
+        entry.interactions.push(interaction)
+        entry.findings.push(...secretFindings(interaction))
+        recorded.set(name, entry)
+        const cassette = cassetteFor(name, entry.interactions, metadata)
+        const findings = [...entry.findings, ...secretFindings(cassette.metadata ?? {})]
+        if (findings.length === 0) yield* write(name, cassette)
+        return { cassette, findings }
+      })
+
+      const exists = Effect.fn("Cassette.exists")(function* (name: string) {
+        return yield* fileSystem.access(pathFor(name)).pipe(
+          Effect.as(true),
+          Effect.catch(() => Effect.succeed(false)),
+        )
+      })
+
+      const list = Effect.fn("Cassette.list")(function* () {
+        return (yield* walk(directory))
+          .filter((file) => file.endsWith(".json"))
+          .map((file) => ({
+            name: path
+              .relative(directory, file)
+              .replace(/\\/g, "/")
+              .replace(/\.json$/, ""),
+            path: file,
+          }))
+          .toSorted((a, b) => a.name.localeCompare(b.name))
+      })
+
+      return Service.of({ path: pathFor, read, write, append, exists, list, scan: cassetteSecretFindings })
     }),
   )
-
-export const memory = (initial: Record<string, ReadonlyArray<Interaction>> = {}): Layer.Layer<Service> =>
-  Layer.sync(Service, () => {
-    const stored = new Map<string, Interaction[]>(
-      Object.entries(initial).map(([name, interactions]) => [name, [...interactions]]),
-    )
-    const accumulatedFindings = new Map<string, SecretFinding[]>()
-
-    return Service.of({
-      read: (name) =>
-        stored.has(name)
-          ? Effect.succeed(stored.get(name) ?? [])
-          : Effect.fail(new CassetteNotFoundError({ cassetteName: name })),
-      append: (name, interaction, metadata) =>
-        Effect.sync(() => {
-          const existing = stored.get(name)
-          if (existing) existing.push(interaction)
-          else stored.set(name, [interaction])
-          const findings = accumulatedFindings.get(name)
-          if (findings) findings.push(...secretFindings(interaction))
-          else accumulatedFindings.set(name, [...secretFindings(interaction)])
-          if (metadata) accumulatedFindings.get(name)!.push(...secretFindings({ name, ...metadata }))
-          return { findings: accumulatedFindings.get(name) ?? [] }
-        }),
-      exists: (name) => Effect.sync(() => stored.has(name)),
-      list: () => Effect.sync(() => Array.from(stored.keys()).toSorted()),
-    })
-  })

packages/http-recorder/src/effect.ts

@@ -12,12 +12,12 @@ import {
 } from "effect/unstable/http"
 import * as CassetteService from "./cassette"
 import { defaultMatcher, selectMatch, selectSequential, type RequestMatcher } from "./matching"
-import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
+import { appendOrFail, makeReplayState } from "./recorder"
 import { defaults, type Redactor } from "./redactor"
 import { redactUrl } from "./redaction"
 import { httpInteractions, type CassetteMetadata, type HttpInteraction, type ResponseSnapshot } from "./schema"
 
-export type RecordReplayMode = "auto" | "record" | "replay" | "passthrough"
+export type RecordReplayMode = "record" | "replay" | "passthrough"
 
 export interface RecordReplayOptions {
   readonly mode?: RecordReplayMode
@@ -69,8 +69,7 @@ export const recordingLayer = (
       const cassetteService = yield* CassetteService.Service
       const redactor = options.redactor ?? defaults()
       const match = options.match ?? defaultMatcher
-      const requested = options.mode ?? "auto"
-      const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
+      const mode = options.mode ?? "replay"
       const sequential = options.dispatch === "sequential"
       const replay = yield* makeReplayState(cassetteService, name, httpInteractions)
 
@@ -115,9 +114,7 @@ export const recordingLayer = (
         return Effect.gen(function* () {
           const incoming = yield* snapshotRequest(request)
           const interactions = yield* replay.load.pipe(
-            Effect.mapError(() =>
-              transportError(request, `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`),
-            ),
+            Effect.mapError(() => transportError(request, `Fixture "${name}" not found.`)),
           )
           const result = sequential
             ? selectSequential(interactions, incoming, match, yield* replay.cursor)
@@ -138,7 +135,7 @@ export const recordingLayer = (
 
 export const cassetteLayer = (name: string, options: RecordReplayOptions = {}): Layer.Layer<HttpClient.HttpClient> =>
   recordingLayer(name, options).pipe(
-    Layer.provide(CassetteService.fileSystem({ directory: options.directory })),
+    Layer.provide(CassetteService.layer({ directory: options.directory })),
     Layer.provide(FetchHttpClient.layer),
     Layer.provide(NodeFileSystem.layer),
   )

packages/http-recorder/src/index.ts

@@ -7,9 +7,9 @@ export type {
   WebSocketFrame,
   WebSocketInteraction,
 } from "./schema"
-export { CassetteNotFoundError, hasCassetteSync } from "./cassette"
+export { hasCassetteSync } from "./storage"
 export { defaultMatcher, type RequestMatcher } from "./matching"
-export { redactHeaders, redactUrl, secretFindings, type SecretFinding } from "./redaction"
+export { cassetteSecretFindings, redactHeaders, redactUrl, type SecretFinding } from "./redaction"
 export { UnsafeCassetteError } from "./recorder"
 export { cassetteLayer, recordingLayer, type RecordReplayMode, type RecordReplayOptions } from "./effect"
 export {

packages/http-recorder/src/recorder.ts

@@ -1,49 +1,37 @@
-import { Effect, Ref, Schema, Scope } from "effect"
+import { Effect, PlatformError, Ref, Scope } from "effect"
 import type * as CassetteService from "./cassette"
-import type { CassetteNotFoundError } from "./cassette"
-import { SecretFindingSchema } from "./redaction"
-import type { CassetteMetadata, Interaction } from "./schema"
+import type { SecretFinding } from "./redaction"
+import type { Cassette, CassetteMetadata, Interaction } from "./schema"
 
-export class UnsafeCassetteError extends Schema.TaggedErrorClass<UnsafeCassetteError>()("UnsafeCassetteError", {
-  cassetteName: Schema.String,
-  findings: Schema.Array(SecretFindingSchema),
-}) {
-  override get message() {
-    return `Refusing to write cassette "${this.cassetteName}" because it contains possible secrets: ${this.findings
-      .map((finding) => `${finding.path} (${finding.reason})`)
-      .join(", ")}`
+export class UnsafeCassetteError extends Error {
+  readonly _tag = "UnsafeCassetteError"
+  constructor(
+    readonly cassetteName: string,
+    readonly findings: ReadonlyArray<SecretFinding>,
+  ) {
+    super(
+      `Refusing to write cassette "${cassetteName}" because it contains possible secrets: ${findings
+        .map((finding) => `${finding.path} (${finding.reason})`)
+        .join(", ")}`,
+    )
   }
 }
 
-export type ResolvedMode = "record" | "replay" | "passthrough"
-
-const isCI = () => {
-  const value = process.env.CI
-  return value !== undefined && value !== "" && value !== "false" && value !== "0"
-}
-
-export const resolveAutoMode = (cassette: CassetteService.Interface, name: string): Effect.Effect<ResolvedMode> =>
-  Effect.gen(function* () {
-    if (isCI()) return "replay"
-    return (yield* cassette.exists(name)) ? "replay" : "record"
-  })
-
 export const appendOrFail = (
   cassette: CassetteService.Interface,
   name: string,
   interaction: Interaction,
   metadata: CassetteMetadata | undefined,
-): Effect.Effect<void, UnsafeCassetteError> =>
-  cassette
-    .append(name, interaction, metadata)
-    .pipe(
-      Effect.flatMap(({ findings }) =>
-        findings.length === 0 ? Effect.void : Effect.fail(new UnsafeCassetteError({ cassetteName: name, findings })),
-      ),
-    )
+): Effect.Effect<Cassette, UnsafeCassetteError> =>
+  cassette.append(name, interaction, metadata).pipe(
+    Effect.orDie,
+    Effect.flatMap(({ cassette: result, findings }) =>
+      findings.length === 0 ? Effect.succeed(result) : Effect.fail(new UnsafeCassetteError(name, findings)),
+    ),
+  )
 
 export interface ReplayState<T> {
-  readonly load: Effect.Effect<ReadonlyArray<T>, CassetteNotFoundError>
+  readonly load: Effect.Effect<ReadonlyArray<T>, PlatformError.PlatformError>
   readonly cursor: Effect.Effect<number>
   readonly advance: Effect.Effect<void>
 }
@@ -51,7 +39,7 @@ export interface ReplayState<T> {
 export const makeReplayState = <T>(
   cassette: CassetteService.Interface,
   name: string,
-  project: (interactions: ReadonlyArray<Interaction>) => ReadonlyArray<T>,
+  project: (cassette: Cassette) => ReadonlyArray<T>,
 ): Effect.Effect<ReplayState<T>, never, Scope.Scope> =>
   Effect.gen(function* () {
     const load = yield* Effect.cached(cassette.read(name).pipe(Effect.map(project)))

packages/http-recorder/src/redaction.ts

@@ -1,3 +1,5 @@
+import type { Cassette } from "./schema"
+
 export const REDACTED = "[REDACTED]"
 
 const DEFAULT_REDACT_HEADERS = [
@@ -95,13 +97,10 @@ export const redactHeaders = (
   )
 }
 
-import { Schema } from "effect"
-
-export const SecretFindingSchema = Schema.Struct({
-  path: Schema.String,
-  reason: Schema.String,
-})
-export type SecretFinding = Schema.Schema.Type<typeof SecretFindingSchema>
+export type SecretFinding = {
+  readonly path: string
+  readonly reason: string
+}
 
 export const secretFindings = (value: unknown): ReadonlyArray<SecretFinding> =>
   stringEntries(value).flatMap((entry) => [
@@ -113,3 +112,5 @@ export const secretFindings = (value: unknown): ReadonlyArray<SecretFinding> =>
       .filter((item) => entry.value.includes(item.value))
       .map((item) => ({ path: entry.path, reason: `environment secret ${item.name}` })),
   ])
+
+export const cassetteSecretFindings = (cassette: Cassette) => secretFindings(cassette)

packages/http-recorder/src/schema.ts

@@ -52,10 +52,9 @@ export const isHttpInteraction = InteractionSchema.guards.http
 
 export const isWebSocketInteraction = InteractionSchema.guards.websocket
 
-export const httpInteractions = (interactions: ReadonlyArray<Interaction>) => interactions.filter(isHttpInteraction)
+export const httpInteractions = (cassette: Cassette) => cassette.interactions.filter(isHttpInteraction)
 
-export const webSocketInteractions = (interactions: ReadonlyArray<Interaction>) =>
-  interactions.filter(isWebSocketInteraction)
+export const webSocketInteractions = (cassette: Cassette) => cassette.interactions.filter(isWebSocketInteraction)
 
 export const CassetteSchema = Schema.Struct({
   version: Schema.Literal(1),

packages/http-recorder/src/storage.ts

@@ -0,0 +1,28 @@
+import { Option } from "effect"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { encodeCassette, decodeCassette, type Cassette, type CassetteMetadata, type Interaction } from "./schema"
+
+export const DEFAULT_RECORDINGS_DIR = path.resolve(process.cwd(), "test", "fixtures", "recordings")
+
+export const cassettePath = (name: string, directory = DEFAULT_RECORDINGS_DIR) => path.join(directory, `${name}.json`)
+
+export const cassetteFor = (
+  name: string,
+  interactions: ReadonlyArray<Interaction>,
+  metadata: CassetteMetadata | undefined,
+): Cassette => ({
+  version: 1,
+  metadata: { name, recordedAt: new Date().toISOString(), ...(metadata ?? {}) },
+  interactions,
+})
+
+export const formatCassette = (cassette: Cassette) => `${JSON.stringify(encodeCassette(cassette), null, 2)}\n`
+
+export const parseCassette = (raw: string) => decodeCassette(JSON.parse(raw))
+
+export const hasCassetteSync = (name: string, options: { readonly directory?: string } = {}) => {
+  const file = cassettePath(name, options.directory)
+  if (!fs.existsSync(file)) return false
+  return Option.isSome(Option.liftThrowable(parseCassette)(fs.readFileSync(file, "utf8")))
+}

packages/http-recorder/src/websocket.ts

@@ -2,8 +2,7 @@ import { Effect, Option, Ref, Scope, Stream } from "effect"
 import type { Headers } from "effect/unstable/http"
 import * as CassetteService from "./cassette"
 import { canonicalizeJson, decodeJson } from "./matching"
-import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
-import type { RecordReplayMode } from "./effect"
+import { appendOrFail, makeReplayState } from "./recorder"
 import { defaults, type Redactor } from "./redactor"
 import { webSocketInteractions, type CassetteMetadata, type WebSocketFrame } from "./schema"
 
@@ -24,7 +23,7 @@ export interface WebSocketExecutor<E> {
 
 export interface WebSocketRecordReplayOptions<E> {
   readonly name: string
-  readonly mode?: RecordReplayMode
+  readonly mode?: "record" | "replay" | "passthrough"
   readonly metadata?: CassetteMetadata
   readonly cassette: CassetteService.Interface
   readonly live: WebSocketExecutor<E>
@@ -72,8 +71,7 @@ export const makeWebSocketExecutor = <E>(
   options: WebSocketRecordReplayOptions<E>,
 ): Effect.Effect<WebSocketExecutor<E>, never, Scope.Scope> =>
   Effect.gen(function* () {
-    const requested = options.mode ?? "auto"
-    const mode = requested === "auto" ? yield* resolveAutoMode(options.cassette, options.name) : requested
+    const mode = options.mode ?? "replay"
     const redactor = options.redactor ?? defaults()
     const openSnapshot = (request: WebSocketRequest) => {
       const redacted = redactor.request({

packages/http-recorder/test/record-replay.test.ts

@@ -7,15 +7,7 @@ import * as os from "node:os"
 import * as path from "node:path"
 import { HttpRecorder } from "../src"
 import { redactedErrorRequest } from "../src/effect"
-import type { Interaction } from "../src/schema"
-
-const seedCassetteDirectory = (directory: string, name: string, interactions: ReadonlyArray<Interaction>) =>
-  Effect.runPromise(
-    Effect.gen(function* () {
-      const cassette = yield* HttpRecorder.Cassette.Service
-      yield* Effect.forEach(interactions, (interaction) => cassette.append(name, interaction))
-    }).pipe(Effect.provide(HttpRecorder.Cassette.fileSystem({ directory })), Effect.provide(NodeFileSystem.layer)),
-  )
+import { cassetteFor, formatCassette, parseCassette } from "../src/storage"
 
 const post = (url: string, body: object) =>
   Effect.gen(function* () {
@@ -42,7 +34,7 @@ const runRecorder = <A, E>(effect: Effect.Effect<A, E, HttpRecorder.Cassette.Ser
     Effect.scoped(
       effect.pipe(
         Effect.provide(
-          HttpRecorder.Cassette.fileSystem({ directory: fs.mkdtempSync(path.join(os.tmpdir(), "http-recorder-")) }),
+          HttpRecorder.Cassette.layer({ directory: fs.mkdtempSync(path.join(os.tmpdir(), "http-recorder-")) }),
         ),
         Effect.provide(NodeFileSystem.layer),
       ),
@@ -117,7 +109,7 @@ describe("http-recorder", () => {
 
   test("detects secret-looking values without returning the secret", () => {
     expect(
-      HttpRecorder.secretFindings({
+      HttpRecorder.cassetteSecretFindings({
         version: 1,
         interactions: [
           {
@@ -145,7 +137,7 @@ describe("http-recorder", () => {
 
   test("detects secret-looking values inside metadata", () => {
     expect(
-      HttpRecorder.secretFindings({
+      HttpRecorder.cassetteSecretFindings({
         version: 1,
         metadata: { token: "sk-123456789012345678901234" },
         interactions: [],
@@ -153,42 +145,60 @@ describe("http-recorder", () => {
     ).toEqual([{ path: "metadata.token", reason: "API key" }])
   })
 
-  test("replays websocket interactions seeded into the in-memory cassette adapter", async () => {
-    await Effect.runPromise(
-      Effect.scoped(
-        Effect.gen(function* () {
-          const cassette = yield* HttpRecorder.Cassette.Service
-          const executor = yield* HttpRecorder.makeWebSocketExecutor({
-            name: "websocket/replay",
-            cassette,
-            compareClientMessagesAsJson: true,
-            live: { open: () => Effect.die(new Error("unexpected live WebSocket open")) },
-          })
-          const connection = yield* executor.open({
-            url: "wss://example.test/realtime",
-            headers: Headers.fromInput({ "content-type": "application/json" }),
-          })
-          yield* connection.sendText(JSON.stringify({ type: "response.create" }))
-          const messages: Array<string | Uint8Array> = []
-          yield* connection.messages.pipe(Stream.runForEach((message) => Effect.sync(() => messages.push(message))))
-          yield* connection.close
+  test("formats websocket cassettes with shared metadata", () => {
+    const cassette = cassetteFor(
+      "websocket/basic",
+      [
+        {
+          transport: "websocket",
+          open: { url: "wss://example.test/realtime", headers: { "content-type": "application/json" } },
+          client: [{ kind: "text", body: JSON.stringify({ type: "response.create" }) }],
+          server: [{ kind: "text", body: JSON.stringify({ type: "response.completed" }) }],
+        },
+      ],
+      { provider: "openai" },
+    )
 
-          expect(messages).toEqual([JSON.stringify({ type: "response.completed" })])
-        }).pipe(
-          Effect.provide(
-            HttpRecorder.Cassette.memory({
-              "websocket/replay": [
-                {
-                  transport: "websocket",
-                  open: { url: "wss://example.test/realtime", headers: { "content-type": "application/json" } },
-                  client: [{ kind: "text", body: JSON.stringify({ type: "response.create" }) }],
-                  server: [{ kind: "text", body: JSON.stringify({ type: "response.completed" }) }],
-                },
-              ],
-            }),
+    expect(cassette.metadata).toMatchObject({ name: "websocket/basic", provider: "openai" })
+    expect(parseCassette(formatCassette(cassette))).toEqual(cassette)
+  })
+
+  test("replays websocket interactions from the shared cassette service", async () => {
+    await runRecorder(
+      Effect.gen(function* () {
+        const cassette = yield* HttpRecorder.Cassette.Service
+        yield* cassette.write(
+          "websocket/replay",
+          cassetteFor(
+            "websocket/replay",
+            [
+              {
+                transport: "websocket",
+                open: { url: "wss://example.test/realtime", headers: { "content-type": "application/json" } },
+                client: [{ kind: "text", body: JSON.stringify({ type: "response.create" }) }],
+                server: [{ kind: "text", body: JSON.stringify({ type: "response.completed" }) }],
+              },
+            ],
+            undefined,
           ),
-        ),
-      ),
+        )
+        const executor = yield* HttpRecorder.makeWebSocketExecutor({
+          name: "websocket/replay",
+          cassette,
+          compareClientMessagesAsJson: true,
+          live: { open: () => Effect.die(new Error("unexpected live WebSocket open")) },
+        })
+        const connection = yield* executor.open({
+          url: "wss://example.test/realtime",
+          headers: Headers.fromInput({ "content-type": "application/json" }),
+        })
+        yield* connection.sendText(JSON.stringify({ type: "response.create" }))
+        const messages: Array<string | Uint8Array> = []
+        yield* connection.messages.pipe(Stream.runForEach((message) => Effect.sync(() => messages.push(message))))
+        yield* connection.close
+
+        expect(messages).toEqual([JSON.stringify({ type: "response.completed" })])
+      }),
     )
   })
 
@@ -218,14 +228,17 @@ describe("http-recorder", () => {
         yield* connection.messages.pipe(Stream.runDrain)
         yield* connection.close
 
-        expect(yield* cassette.read("websocket/record")).toMatchObject([
-          {
-            transport: "websocket",
-            open: { url: "wss://example.test/realtime", headers: { "content-type": "application/json" } },
-            client: [{ kind: "text", body: JSON.stringify({ type: "response.create" }) }],
-            server: [{ kind: "text", body: JSON.stringify({ type: "response.completed" }) }],
-          },
-        ])
+        expect(yield* cassette.read("websocket/record")).toMatchObject({
+          metadata: { name: "websocket/record", provider: "test" },
+          interactions: [
+            {
+              transport: "websocket",
+              open: { url: "wss://example.test/realtime", headers: { "content-type": "application/json" } },
+              client: [{ kind: "text", body: JSON.stringify({ type: "response.create" }) }],
+              server: [{ kind: "text", body: JSON.stringify({ type: "response.completed" }) }],
+            },
+          ],
+        })
       }),
     )
   })
@@ -288,49 +301,6 @@ describe("http-recorder", () => {
     )
   })
 
-  test("auto mode replays when the cassette exists", async () => {
-    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "http-recorder-auto-"))
-    await seedCassetteDirectory(directory, "auto-replay", [
-      {
-        transport: "http",
-        request: {
-          method: "POST",
-          url: "https://example.test/echo",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ step: 1 }),
-        },
-        response: { status: 200, headers: { "content-type": "application/json" }, body: '{"reply":"hi"}' },
-      },
-    ])
-
-    const result = await runWith(
-      "auto-replay",
-      { directory, mode: "auto" },
-      post("https://example.test/echo", { step: 1 }),
-    )
-    expect(result).toBe('{"reply":"hi"}')
-  })
-
-  test("auto mode forces replay when CI=true even if cassette is missing", async () => {
-    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "http-recorder-auto-ci-"))
-    const previous = process.env.CI
-    process.env.CI = "true"
-    try {
-      const exit = await Effect.runPromise(
-        Effect.exit(
-          post("https://example.test/echo", { step: 1 }).pipe(
-            Effect.provide(HttpRecorder.cassetteLayer("missing-cassette", { directory, mode: "auto" })),
-          ),
-        ),
-      )
-      expect(Exit.isFailure(exit)).toBe(true)
-      expect(failureText(exit)).toContain('Fixture "missing-cassette" not found')
-    } finally {
-      if (previous === undefined) delete process.env.CI
-      else process.env.CI = previous
-    }
-  })
-
   test("mismatch diagnostics show closest redacted request differences", async () => {
     await run(
       Effect.gen(function* () {

packages/llm/README.md

@@ -1,129 +0,0 @@
-# @opencode-ai/llm
-
-Schema-first LLM core for opencode. One typed request, response, event, and tool language; provider quirks live in adapters, not in calling code.
-
-```ts
-import { Effect } from "effect"
-import { LLM, LLMClient } from "@opencode-ai/llm"
-import { OpenAI } from "@opencode-ai/llm/providers"
-
-const model = OpenAI.model("gpt-4o-mini", { apiKey: process.env.OPENAI_API_KEY })
-
-const request = LLM.request({
-  model,
-  system: "You are concise.",
-  prompt: "Say hello in one short sentence.",
-  generation: { maxTokens: 40 },
-})
-
-const program = Effect.gen(function* () {
-  const response = yield* LLMClient.generate(request)
-  console.log(response.text)
-})
-```
-
-Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
-
-## Public API
-
-- **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
-- **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
-- **`LLM.user(...)` / `LLM.assistant(...)` / `LLM.toolMessage(...)`** — message constructors.
-- **`LLM.toolCall(...)` / `LLM.toolResult(...)` / `LLM.toolDefinition(...)`** — tool-related parts.
-- **`LLMClient.prepare(request)`** — compile a request through protocol body construction, validation, and HTTP preparation without sending. Useful for inspection and testing.
-- **`LLMEvent.is.*`** — typed guards (`is.text`, `is.toolCall`, `is.requestFinish`, …) for filtering streams.
-
-## Caching
-
-Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "auto"` unless the caller opts out with `cache: "none"`. Each protocol translates `CacheHint`s to its wire format (`cache_control` on Anthropic, `cachePoint` on Bedrock; OpenAI and Gemini do implicit caching server-side and don't need inline markers — auto is a no-op there).
-
-### Auto placement
-
-`"auto"` places three breakpoints — last tool definition, last system part, latest user message. The last-user-message boundary is the load-bearing detail: in a tool-use loop, a single user turn expands into many assistant/tool round-trips, all sharing that prefix. Caching at that boundary lets every intra-turn API call hit.
-
-The math justifies the default: Anthropic's 5-minute cache write is 1.25× base, read is 0.1×, so a single reuse within 5 minutes already wins. One-shot completions below the per-model minimum-cacheable-token threshold silently no-op on the wire, so the worst case is harmless.
-
-### Opting out
-
-```ts
-LLM.request({
-  model,
-  system,
-  prompt: "one-off question",
-  cache: "none",
-})
-```
-
-### Granular policy
-
-```ts
-cache: {
-  tools?: boolean,
-  system?: boolean,
-  messages?: "latest-user-message" | "latest-assistant" | { tail: number },
-  ttlSeconds?: number,         // ≥ 3600 → 1h on Anthropic/Bedrock; else 5m
-}
-```
-
-### Manual hints
-
-Inline `CacheHint` on any text / system / tool / tool-result part overrides automatic placement. The auto policy preserves manual hints; it only fills gaps.
-
-```ts
-LLM.request({
-  model,
-  system: [
-    { type: "text", text: "stable system prompt", cache: { type: "ephemeral" } },
-  ],
-  ...
-})
-```
-
-### Provider behavior table
-
-| Protocol                | `cache: "auto"`                                                           |
-| ----------------------- | ------------------------------------------------------------------------- |
-| Anthropic Messages      | emits up to 3 `cache_control` markers (4-breakpoint cap enforced)         |
-| Bedrock Converse        | emits up to 3 `cachePoint` blocks (4-breakpoint cap enforced)             |
-| OpenAI Chat / Responses | no-op (implicit caching above 1024 tokens)                                |
-| Gemini                  | no-op (implicit caching on 2.5+; explicit `CachedContent` is out-of-band) |
-
-Normalized cache usage is read back into `response.usage.cacheReadInputTokens` and `cacheWriteInputTokens` across every provider.
-
-## Providers
-
-Each provider exports a `model(...)` helper that records identity, protocol, capabilities, auth, and defaults.
-
-```ts
-import { Anthropic } from "@opencode-ai/llm/providers"
-
-const model = Anthropic.model("claude-sonnet-4-6", {
-  apiKey: process.env.ANTHROPIC_API_KEY,
-})
-```
-
-Included providers: OpenAI, Anthropic, Google (Gemini), Amazon Bedrock, Azure OpenAI, Cloudflare, GitHub Copilot, OpenRouter, xAI, plus generic OpenAI-compatible helpers for DeepSeek, Cerebras, Groq, Fireworks, Together, etc.
-
-## Provider options & HTTP overlays
-
-Three escape hatches in order of stability:
-
-1. **`generation`** — portable knobs (`maxTokens`, `temperature`, `topP`, `topK`, penalties, seed, stop).
-2. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `promptCacheKey`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
-3. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.
-
-Model-level defaults are overridden by request-level values for each axis.
-
-## Routes
-
-Adding a new model or deployment is usually 5–15 lines using `Route.make({ protocol, transport, ... })`. The four orthogonal pieces are protocol (body construction + stream parsing), transport (endpoint + auth + framing + encoding), defaults, and capabilities. See `AGENTS.md` for the architectural detail.
-
-## Effect
-
-This package is built on Effect. Public methods return `Effect` or `Stream`; provide `LLMClient.layer` (the default registers every shipped route) for runtime dispatch. The example at `example/tutorial.ts` is a runnable walkthrough.
-
-## See also
-
-- `AGENTS.md` — architecture, route construction, contributor guide
-- `example/tutorial.ts` — runnable end-to-end walkthrough
-- `test/provider/*.test.ts` — fixture-first protocol tests; `*.recorded.test.ts` files cover live cassettes

packages/llm/example/tutorial.ts

@@ -184,7 +184,7 @@ const FakeProtocol = Protocol.make<FakeBody, string, string, void>({
   stream: {
     event: Schema.String,
     initial: () => undefined,
-    step: (_, frame) => Effect.succeed([undefined, [{ type: "text-delta", id: "text-0", text: frame }]] as const),
+    step: (_, frame) => Effect.succeed([undefined, [{ type: "text-delta", text: frame }]] as const),
     onHalt: () => [{ type: "request-finish", reason: "stop" }],
   },
 })

packages/llm/package.json

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

packages/llm/src/cache-policy.ts

@@ -1,111 +0,0 @@
-// Apply an `LLMRequest.cache` policy by injecting `CacheHint`s onto the parts
-// the policy designates. Runs once at compile time, before the per-protocol
-// body builder, so the existing inline-hint lowering path handles the rest.
-//
-// The default `"auto"` shape places one breakpoint at the last tool definition,
-// one at the last system part, and one at the latest user message. This
-// matches what production agent harnesses (LangChain's caching middleware,
-// kern-ai's 10x cost-reduction playbook) converge on for tool-use loops: the
-// latest user message stays put while a single turn explodes into many
-// assistant/tool round-trips, so caching at that boundary lets every
-// intra-turn API call hit the prefix.
-//
-// Manual `cache: CacheHint` placements on individual parts are preserved —
-// this function only fills gaps the caller left empty.
-import { CacheHint, type CachePolicy, type CachePolicyObject } from "./schema/options"
-import { LLMRequest, Message, ToolDefinition, type ContentPart } from "./schema/messages"
-
-const AUTO: CachePolicyObject = {
-  tools: true,
-  system: true,
-  messages: "latest-user-message",
-}
-
-const NONE: CachePolicyObject = {}
-
-// Resolution rules:
-//   - undefined   → "auto" — caching is on by default. The math favors it:
-//                   Anthropic 5m-cache write is 1.25x base, read is 0.1x,
-//                   so a single reuse within 5 minutes already wins.
-//   - "auto"      → tools + system + latest user msg.
-//   - "none"      → no auto placement; manual `CacheHint`s still flow.
-//   - object form → exactly what the caller asked for.
-const resolve = (policy: CachePolicy | undefined): CachePolicyObject => {
-  if (policy === undefined || policy === "auto") return AUTO
-  if (policy === "none") return NONE
-  return policy
-}
-
-// Protocols whose wire format ignores inline cache markers (OpenAI's implicit
-// prefix caching, Gemini's implicit + out-of-band CachedContent). Skip the
-// whole policy pass for these — emitting hints would be harmless but pointless.
-const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse"])
-
-const makeHint = (ttlSeconds: number | undefined): CacheHint =>
-  ttlSeconds !== undefined ? new CacheHint({ type: "ephemeral", ttlSeconds }) : new CacheHint({ type: "ephemeral" })
-
-const markLastTool = (tools: ReadonlyArray<ToolDefinition>, hint: CacheHint): ReadonlyArray<ToolDefinition> => {
-  if (tools.length === 0) return tools
-  const last = tools.length - 1
-  if (tools[last]!.cache) return tools
-  return tools.map((tool, i) => (i === last ? new ToolDefinition({ ...tool, cache: hint }) : tool))
-}
-
-const markLastSystem = (system: LLMRequest["system"], hint: CacheHint): LLMRequest["system"] => {
-  if (system.length === 0) return system
-  const last = system.length - 1
-  if (system[last]!.cache) return system
-  return system.map((part, i) => (i === last ? { ...part, cache: hint } : part))
-}
-
-const lastIndexOfRole = (messages: ReadonlyArray<Message>, role: Message["role"]): number =>
-  messages.findLastIndex((m) => m.role === role)
-
-// Mark the last text part of `messages[index]`. If no text part exists, mark
-// the last content part regardless of type — that's the breakpoint position
-// in tool-result-only messages too.
-const markMessageAt = (messages: ReadonlyArray<Message>, index: number, hint: CacheHint): ReadonlyArray<Message> => {
-  if (index < 0 || index >= messages.length) return messages
-  const target = messages[index]!
-  if (target.content.length === 0) return messages
-  const lastTextIndex = target.content.findLastIndex((part) => part.type === "text")
-  const markAt = lastTextIndex >= 0 ? lastTextIndex : target.content.length - 1
-  const existing = target.content[markAt]!
-  if ("cache" in existing && existing.cache) return messages
-  const nextContent = target.content.map((part, i) => (i === markAt ? ({ ...part, cache: hint } as ContentPart) : part))
-  const next = new Message({ ...target, content: nextContent })
-  // Single pass over `messages`, substituting the one updated entry. Long
-  // conversations call this on every request, so avoid `.map()` here — its
-  // closure dispatch and identity copies show up in profiling.
-  const result = messages.slice()
-  result[index] = next
-  return result
-}
-
-const markMessages = (
-  messages: ReadonlyArray<Message>,
-  strategy: NonNullable<CachePolicyObject["messages"]>,
-  hint: CacheHint,
-): ReadonlyArray<Message> => {
-  if (messages.length === 0) return messages
-  if (strategy === "latest-user-message") return markMessageAt(messages, lastIndexOfRole(messages, "user"), hint)
-  if (strategy === "latest-assistant") return markMessageAt(messages, lastIndexOfRole(messages, "assistant"), hint)
-  const start = Math.max(0, messages.length - strategy.tail)
-  let next = messages
-  for (let i = start; i < messages.length; i++) next = markMessageAt(next, i, hint)
-  return next
-}
-
-export const applyCachePolicy = (request: LLMRequest): LLMRequest => {
-  if (!RESPECTS_INLINE_HINTS.has(request.model.route)) return request
-  const policy = resolve(request.cache)
-  if (!policy.tools && !policy.system && !policy.messages) return request
-
-  const hint = makeHint(policy.ttlSeconds)
-  const tools = policy.tools ? markLastTool(request.tools, hint) : request.tools
-  const system = policy.system ? markLastSystem(request.system, hint) : request.system
-  const messages = policy.messages ? markMessages(request.messages, policy.messages, hint) : request.messages
-
-  if (tools === request.tools && system === request.system && messages === request.messages) return request
-  return LLMRequest.update(request, { tools, system, messages })
-}

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

@@ -5,10 +5,10 @@ import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
 import { Protocol } from "../route/protocol"
 import {
-  LLMEvent,
   Usage,
   type CacheHint,
   type FinishReason,
+  type LLMEvent,
   type LLMRequest,
   type ProviderMetadata,
   type ToolCallPart,
@@ -16,7 +16,6 @@ import {
   type ToolResultPart,
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
-import * as Cache from "./utils/cache"
 import { ToolStream } from "./utils/tool-stream"
 
 const ADAPTER = "anthropic-messages"
@@ -26,10 +25,7 @@ export const PATH = "/messages"
 // =============================================================================
 // Request Body Schema
 // =============================================================================
-const AnthropicCacheControl = Schema.Struct({
-  type: Schema.tag("ephemeral"),
-  ttl: Schema.optional(Schema.Literals(["5m", "1h"])),
-})
+const AnthropicCacheControl = Schema.Struct({ type: Schema.tag("ephemeral") })
 
 const AnthropicTextBlock = Schema.Struct({
   type: Schema.tag("text"),
@@ -197,24 +193,8 @@ const invalid = ProviderShared.invalidRequest
 // =============================================================================
 // Request Lowering
 // =============================================================================
-// Anthropic accepts at most 4 explicit cache_control breakpoints per request,
-// across `tools`, `system`, and `messages`. Beyond the cap the API returns a
-// 400 — so the lowering layer counts emitted markers and silently drops any
-// that exceed it.
-const ANTHROPIC_BREAKPOINT_CAP = 4
-
-const EPHEMERAL_5M = { type: "ephemeral" as const }
-const EPHEMERAL_1H = { type: "ephemeral" as const, ttl: "1h" as const }
-
-const cacheControl = (breakpoints: Cache.Breakpoints, cache: CacheHint | undefined) => {
-  if (cache?.type !== "ephemeral" && cache?.type !== "persistent") return undefined
-  if (breakpoints.remaining <= 0) {
-    breakpoints.dropped += 1
-    return undefined
-  }
-  breakpoints.remaining -= 1
-  return Cache.ttlBucket(cache.ttlSeconds) === "1h" ? EPHEMERAL_1H : EPHEMERAL_5M
-}
+const cacheControl = (cache: CacheHint | undefined) =>
+  cache?.type === "ephemeral" ? { type: "ephemeral" as const } : undefined
 
 const anthropicMetadata = (metadata: Record<string, unknown>): ProviderMetadata => ({ anthropic: metadata })
 
@@ -224,11 +204,10 @@ const signatureFromMetadata = (metadata: ProviderMetadata | undefined): string |
   return typeof anthropic.signature === "string" ? anthropic.signature : undefined
 }
 
-const lowerTool = (breakpoints: Cache.Breakpoints, tool: ToolDefinition): AnthropicTool => ({
+const lowerTool = (tool: ToolDefinition): AnthropicTool => ({
   name: tool.name,
   description: tool.description,
   input_schema: tool.inputSchema,
-  cache_control: cacheControl(breakpoints, tool.cache),
 })
 
 const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
@@ -270,10 +249,7 @@ const lowerServerToolResult = Effect.fn("AnthropicMessages.lowerServerToolResult
   return { type: wireType, tool_use_id: part.id, content: part.result.value } satisfies AnthropicServerToolResultBlock
 })
 
-const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
-  request: LLMRequest,
-  breakpoints: Cache.Breakpoints,
-) {
+const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (request: LLMRequest) {
   const messages: AnthropicMessage[] = []
 
   for (const message of request.messages) {
@@ -282,7 +258,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
       for (const part of message.content) {
         if (!ProviderShared.supportsContent(part, ["text"]))
           return yield* ProviderShared.unsupportedContent("Anthropic Messages", "user", ["text"])
-        content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
+        content.push({ type: "text", text: part.text, cache_control: cacheControl(part.cache) })
       }
       messages.push({ role: "user", content })
       continue
@@ -292,7 +268,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
       const content: AnthropicAssistantBlock[] = []
       for (const part of message.content) {
         if (part.type === "text") {
-          content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
+          content.push({ type: "text", text: part.text, cache_control: cacheControl(part.cache) })
           continue
         }
         if (part.type === "reasoning") {
@@ -328,7 +304,6 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
         tool_use_id: part.id,
         content: ProviderShared.toolResultText(part),
         is_error: part.result.type === "error" ? true : undefined,
-        cache_control: cacheControl(breakpoints, part.cache),
       })
     }
     messages.push({ role: "user", content })
@@ -355,33 +330,18 @@ const lowerThinking = Effect.fn("AnthropicMessages.lowerThinking")(function* (re
 const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (request: LLMRequest) {
   const toolChoice = request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined
   const generation = request.generation
-  // Allocate the 4-breakpoint budget in invalidation order: tools → system →
-  // messages. Tools live highest in the cache hierarchy, so when callers
-  // over-mark we keep their tool hints and shed the message-tail ones first.
-  const breakpoints = Cache.newBreakpoints(ANTHROPIC_BREAKPOINT_CAP)
-  const tools =
-    request.tools.length === 0 || request.toolChoice?.type === "none"
-      ? undefined
-      : request.tools.map((tool) => lowerTool(breakpoints, tool))
-  const system =
-    request.system.length === 0
-      ? undefined
-      : request.system.map((part) => ({
-          type: "text" as const,
-          text: part.text,
-          cache_control: cacheControl(breakpoints, part.cache),
-        }))
-  const messages = yield* lowerMessages(request, breakpoints)
-  if (breakpoints.dropped > 0) {
-    yield* Effect.logWarning(
-      `Anthropic Messages: dropped ${breakpoints.dropped} cache breakpoint(s); the API allows at most ${ANTHROPIC_BREAKPOINT_CAP} per request.`,
-    )
-  }
   return {
     model: request.model.id,
-    system,
-    messages,
-    tools,
+    system:
+      request.system.length === 0
+        ? undefined
+        : request.system.map((part) => ({
+            type: "text" as const,
+            text: part.text,
+            cache_control: cacheControl(part.cache),
+          })),
+    messages: yield* lowerMessages(request),
+    tools: request.tools.length === 0 || request.toolChoice?.type === "none" ? undefined : request.tools.map(lowerTool),
     tool_choice: toolChoice,
     stream: true as const,
     max_tokens: generation?.maxTokens ?? request.model.limits.output ?? 4096,
@@ -404,56 +364,34 @@ const mapFinishReason = (reason: string | null | undefined): FinishReason => {
   return "unknown"
 }
 
-// Anthropic reports the non-overlapping breakdown natively — its
-// `input_tokens` is the *non-cached* count per the Messages API docs, with
-// cache reads and writes as separate fields. We sum them to derive the
-// inclusive `inputTokens` the rest of the contract expects. Extended
-// thinking tokens are *not* broken out by Anthropic — they're billed as
-// part of `output_tokens`, so `reasoningTokens` stays `undefined` and
-// `outputTokens` carries the combined total.
 const mapUsage = (usage: AnthropicUsage | undefined): Usage | undefined => {
   if (!usage) return undefined
-  const nonCached = usage.input_tokens
-  const cacheRead = usage.cache_read_input_tokens ?? undefined
-  const cacheWrite = usage.cache_creation_input_tokens ?? undefined
-  const inputTokens = ProviderShared.sumTokens(nonCached, cacheRead, cacheWrite)
   return new Usage({
-    inputTokens,
+    inputTokens: usage.input_tokens,
     outputTokens: usage.output_tokens,
-    nonCachedInputTokens: nonCached,
-    cacheReadInputTokens: cacheRead,
-    cacheWriteInputTokens: cacheWrite,
-    totalTokens: ProviderShared.totalTokens(inputTokens, usage.output_tokens, undefined),
-    providerMetadata: { anthropic: usage },
+    cacheReadInputTokens: usage.cache_read_input_tokens ?? undefined,
+    cacheWriteInputTokens: usage.cache_creation_input_tokens ?? undefined,
+    totalTokens: ProviderShared.totalTokens(usage.input_tokens, usage.output_tokens, undefined),
+    native: usage,
   })
 }
 
 // Anthropic emits usage on `message_start` and again on `message_delta` — the
 // final delta carries the authoritative totals. Right-biased merge: each
-// field prefers `right` when defined, falls back to `left`. `inputTokens` is
-// recomputed from the merged breakdown so the inclusive total stays
-// consistent with `nonCached + cacheRead + cacheWrite`.
+// field prefers `right` when defined, falls back to `left`. `totalTokens` is
+// recomputed from the merged input/output to stay consistent.
 const mergeUsage = (left: Usage | undefined, right: Usage | undefined) => {
   if (!left) return right
   if (!right) return left
-  const nonCachedInputTokens = right.nonCachedInputTokens ?? left.nonCachedInputTokens
-  const cacheReadInputTokens = right.cacheReadInputTokens ?? left.cacheReadInputTokens
-  const cacheWriteInputTokens = right.cacheWriteInputTokens ?? left.cacheWriteInputTokens
-  const inputTokens = ProviderShared.sumTokens(nonCachedInputTokens, cacheReadInputTokens, cacheWriteInputTokens)
+  const inputTokens = right.inputTokens ?? left.inputTokens
   const outputTokens = right.outputTokens ?? left.outputTokens
   return new Usage({
     inputTokens,
     outputTokens,
-    nonCachedInputTokens,
-    cacheReadInputTokens,
-    cacheWriteInputTokens,
+    cacheReadInputTokens: right.cacheReadInputTokens ?? left.cacheReadInputTokens,
+    cacheWriteInputTokens: right.cacheWriteInputTokens ?? left.cacheWriteInputTokens,
     totalTokens: ProviderShared.totalTokens(inputTokens, outputTokens, undefined),
-    providerMetadata: {
-      anthropic: {
-        ...(left.providerMetadata?.["anthropic"] ?? {}),
-        ...(right.providerMetadata?.["anthropic"] ?? {}),
-      },
-    },
+    native: { ...left.native, ...right.native },
   })
 }
 
@@ -477,13 +415,14 @@ const serverToolResultEvent = (block: NonNullable<AnthropicEvent["content_block"
       ? String((block.content as Record<string, unknown>).type)
       : ""
   const isError = errorPayload.endsWith("_tool_result_error")
-  return LLMEvent.toolResult({
+  return {
+    type: "tool-result",
     id: block.tool_use_id ?? "",
     name: SERVER_TOOL_RESULT_NAMES[block.type],
     result: isError ? { type: "error", value: block.content } : { type: "json", value: block.content },
     providerExecuted: true,
     providerMetadata: anthropicMetadata({ blockType: block.type }),
-  })
+  }
 }
 
 type StepResult = readonly [ParserState, ReadonlyArray<LLMEvent>]
@@ -514,17 +453,18 @@ const onContentBlockStart = (state: ParserState, event: AnthropicEvent): StepRes
   }
 
   if (block.type === "text" && block.text) {
-    return [state, [LLMEvent.textDelta({ id: `text-${event.index ?? 0}`, text: block.text })]]
+    return [state, [{ type: "text-delta", text: block.text }]]
   }
 
   if (block.type === "thinking" && block.thinking) {
     return [
       state,
       [
-        LLMEvent.reasoningDelta({
-          id: `reasoning-${event.index ?? 0}`,
+        {
+          type: "reasoning-delta",
           text: block.thinking,
-        }),
+          ...(block.signature ? { providerMetadata: anthropicMetadata({ signature: block.signature }) } : {}),
+        },
       ],
     ]
   }
@@ -540,25 +480,17 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
   const delta = event.delta
 
   if (delta?.type === "text_delta" && delta.text) {
-    return [state, [LLMEvent.textDelta({ id: `text-${event.index ?? 0}`, text: delta.text })]] satisfies StepResult
+    return [state, [{ type: "text-delta", text: delta.text }]] satisfies StepResult
   }
 
   if (delta?.type === "thinking_delta" && delta.thinking) {
-    return [
-      state,
-      [LLMEvent.reasoningDelta({ id: `reasoning-${event.index ?? 0}`, text: delta.thinking })],
-    ] satisfies StepResult
+    return [state, [{ type: "reasoning-delta", text: delta.thinking }]] satisfies StepResult
   }
 
   if (delta?.type === "signature_delta" && delta.signature) {
     return [
       state,
-      [
-        LLMEvent.reasoningEnd({
-          id: `reasoning-${event.index ?? 0}`,
-          providerMetadata: anthropicMetadata({ signature: delta.signature }),
-        }),
-      ],
+      [{ type: "reasoning-delta", text: "", providerMetadata: anthropicMetadata({ signature: delta.signature }) }],
     ] satisfies StepResult
   }
 
@@ -592,20 +524,21 @@ const onMessageDelta = (state: ParserState, event: AnthropicEvent): StepResult =
   return [
     { ...state, usage },
     [
-      LLMEvent.requestFinish({
+      {
+        type: "request-finish",
         reason: mapFinishReason(event.delta?.stop_reason),
         usage,
-        providerMetadata: event.delta?.stop_sequence
-          ? anthropicMetadata({ stopSequence: event.delta.stop_sequence })
-          : undefined,
-      }),
+        ...(event.delta?.stop_sequence
+          ? { providerMetadata: anthropicMetadata({ stopSequence: event.delta.stop_sequence }) }
+          : {}),
+      },
     ],
   ]
 }
 
 const onError = (state: ParserState, event: AnthropicEvent): StepResult => [
   state,
-  [LLMEvent.providerError({ message: event.error?.message ?? "Anthropic Messages stream error" })],
+  [{ type: "provider-error", message: event.error?.message ?? "Anthropic Messages stream error" }],
 ]
 
 const step = (state: ParserState, event: AnthropicEvent) => {

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

@@ -3,10 +3,10 @@ import { Route, type RouteModelInput } from "../route/client"
 import { Endpoint } from "../route/endpoint"
 import { Protocol } from "../route/protocol"
 import {
-  LLMEvent,
   Usage,
   type CacheHint,
   type FinishReason,
+  type LLMEvent,
   type LLMRequest,
   type ToolCallPart,
   type ToolDefinition,
@@ -108,7 +108,7 @@ type BedrockMessage = Schema.Schema.Type<typeof BedrockMessage>
 const BedrockSystemBlock = Schema.Union([BedrockTextBlock, BedrockCache.CachePointBlock])
 type BedrockSystemBlock = Schema.Schema.Type<typeof BedrockSystemBlock>
 
-const BedrockToolSpec = Schema.Struct({
+const BedrockTool = Schema.Struct({
   toolSpec: Schema.Struct({
     name: Schema.String,
     description: Schema.String,
@@ -117,9 +117,6 @@ const BedrockToolSpec = Schema.Struct({
     }),
   }),
 })
-type BedrockToolSpec = Schema.Schema.Type<typeof BedrockToolSpec>
-
-const BedrockTool = Schema.Union([BedrockToolSpec, BedrockCache.CachePointBlock])
 type BedrockTool = Schema.Schema.Type<typeof BedrockTool>
 
 const BedrockToolChoice = Schema.Union([
@@ -217,7 +214,7 @@ type BedrockEvent = Schema.Schema.Type<typeof BedrockEvent>
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const lowerToolSpec = (tool: ToolDefinition): BedrockToolSpec => ({
+const lowerTool = (tool: ToolDefinition): BedrockTool => ({
   toolSpec: {
     name: tool.name,
     description: tool.description,
@@ -225,22 +222,11 @@ const lowerToolSpec = (tool: ToolDefinition): BedrockToolSpec => ({
   },
 })
 
-const lowerTools = (breakpoints: BedrockCache.Breakpoints, tools: ReadonlyArray<ToolDefinition>): BedrockTool[] => {
-  const result: BedrockTool[] = []
-  for (const tool of tools) {
-    result.push(lowerToolSpec(tool))
-    const cachePoint = BedrockCache.block(breakpoints, tool.cache)
-    if (cachePoint) result.push(cachePoint)
-  }
-  return result
-}
-
 const textWithCache = (
-  breakpoints: BedrockCache.Breakpoints,
   text: string,
   cache: CacheHint | undefined,
 ): Array<BedrockTextBlock | BedrockCache.CachePointBlock> => {
-  const cachePoint = BedrockCache.block(breakpoints, cache)
+  const cachePoint = BedrockCache.block(cache)
   return cachePoint ? [{ text }, cachePoint] : [{ text }]
 }
 
@@ -271,10 +257,7 @@ const lowerToolResult = (part: ToolResultPart): BedrockToolResultBlock => ({
   },
 })
 
-const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
-  request: LLMRequest,
-  breakpoints: BedrockCache.Breakpoints,
-) {
+const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (request: LLMRequest) {
   const messages: BedrockMessage[] = []
 
   for (const message of request.messages) {
@@ -284,7 +267,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
         if (!ProviderShared.supportsContent(part, ["text", "media"]))
           return yield* ProviderShared.unsupportedContent("Bedrock Converse", "user", ["text", "media"])
         if (part.type === "text") {
-          content.push(...textWithCache(breakpoints, part.text, part.cache))
+          content.push(...textWithCache(part.text, part.cache))
           continue
         }
         if (part.type === "media") {
@@ -306,7 +289,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
             "tool-call",
           ])
         if (part.type === "text") {
-          content.push(...textWithCache(breakpoints, part.text, part.cache))
+          content.push(...textWithCache(part.text, part.cache))
           continue
         }
         if (part.type === "reasoning") {
@@ -326,13 +309,11 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
       continue
     }
 
-    const content: BedrockUserBlock[] = []
+    const content: BedrockToolResultBlock[] = []
     for (const part of message.content) {
       if (!ProviderShared.supportsContent(part, ["tool-result"]))
         return yield* ProviderShared.unsupportedContent("Bedrock Converse", "tool", ["tool-result"])
       content.push(lowerToolResult(part))
-      const cachePoint = BedrockCache.block(breakpoints, part.cache)
-      if (cachePoint) content.push(cachePoint)
     }
     messages.push({ role: "user", content })
   }
@@ -342,32 +323,16 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
 
 // System prompts share the cache-point convention: emit the text block, then
 // optionally a positional `cachePoint` marker.
-const lowerSystem = (
-  breakpoints: BedrockCache.Breakpoints,
-  system: ReadonlyArray<LLMRequest["system"][number]>,
-): BedrockSystemBlock[] => system.flatMap((part) => textWithCache(breakpoints, part.text, part.cache))
+const lowerSystem = (system: ReadonlyArray<LLMRequest["system"][number]>): BedrockSystemBlock[] =>
+  system.flatMap((part) => textWithCache(part.text, part.cache))
 
 const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request: LLMRequest) {
   const toolChoice = request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined
   const generation = request.generation
-  // Bedrock-Claude shares Anthropic's 4-breakpoint cap. Spend the budget in
-  // tools → system → messages order to favour the highest-impact prefixes.
-  const breakpoints = BedrockCache.breakpoints()
-  const toolConfig =
-    request.tools.length > 0 && request.toolChoice?.type !== "none"
-      ? { tools: lowerTools(breakpoints, request.tools), toolChoice }
-      : undefined
-  const system = request.system.length === 0 ? undefined : lowerSystem(breakpoints, request.system)
-  const messages = yield* lowerMessages(request, breakpoints)
-  if (breakpoints.dropped > 0) {
-    yield* Effect.logWarning(
-      `Bedrock Converse: dropped ${breakpoints.dropped} cache breakpoint(s); the API allows at most ${BedrockCache.BEDROCK_BREAKPOINT_CAP} per request.`,
-    )
-  }
   return {
     modelId: request.model.id,
-    messages,
-    system,
+    messages: yield* lowerMessages(request),
+    system: request.system.length === 0 ? undefined : lowerSystem(request.system),
     inferenceConfig:
       generation?.maxTokens === undefined &&
       generation?.temperature === undefined &&
@@ -380,7 +345,10 @@ const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request:
             topP: generation?.topP,
             stopSequences: generation?.stop,
           },
-    toolConfig,
+    toolConfig:
+      request.tools.length > 0 && request.toolChoice?.type !== "none"
+        ? { tools: request.tools.map(lowerTool), toolChoice }
+        : undefined,
   }
 })
 
@@ -395,22 +363,15 @@ const mapFinishReason = (reason: string): FinishReason => {
   return "unknown"
 }
 
-// AWS Bedrock Converse reports `inputTokens` (inclusive total) with
-// `cacheReadInputTokens` and `cacheWriteInputTokens` as subsets. Pass
-// the total through and derive the non-cached breakdown. Bedrock does
-// not break reasoning out of `outputTokens` for any current model.
 const mapUsage = (usage: BedrockUsageSchema | undefined): Usage | undefined => {
   if (!usage) return undefined
-  const cacheTotal = (usage.cacheReadInputTokens ?? 0) + (usage.cacheWriteInputTokens ?? 0)
-  const nonCached = ProviderShared.subtractTokens(usage.inputTokens, cacheTotal)
   return new Usage({
     inputTokens: usage.inputTokens,
     outputTokens: usage.outputTokens,
-    nonCachedInputTokens: nonCached,
+    totalTokens: ProviderShared.totalTokens(usage.inputTokens, usage.outputTokens, usage.totalTokens),
     cacheReadInputTokens: usage.cacheReadInputTokens,
     cacheWriteInputTokens: usage.cacheWriteInputTokens,
-    totalTokens: ProviderShared.totalTokens(usage.inputTokens, usage.outputTokens, usage.totalTokens),
-    providerMetadata: { bedrock: usage },
+    native: usage,
   })
 }
 
@@ -439,26 +400,13 @@ const step = (state: ParserState, event: BedrockEvent) =>
     }
 
     if (event.contentBlockDelta?.delta?.text) {
-      return [
-        state,
-        [
-          LLMEvent.textDelta({
-            id: `text-${event.contentBlockDelta.contentBlockIndex}`,
-            text: event.contentBlockDelta.delta.text,
-          }),
-        ],
-      ] as const
+      return [state, [{ type: "text-delta" as const, text: event.contentBlockDelta.delta.text }]] as const
     }
 
     if (event.contentBlockDelta?.delta?.reasoningContent?.text) {
       return [
         state,
-        [
-          LLMEvent.reasoningDelta({
-            id: `reasoning-${event.contentBlockDelta.contentBlockIndex}`,
-            text: event.contentBlockDelta.delta.reasoningContent.text,
-          }),
-        ],
+        [{ type: "reasoning-delta" as const, text: event.contentBlockDelta.delta.reasoningContent.text }],
       ] as const
     }
 
@@ -501,13 +449,16 @@ const step = (state: ParserState, event: BedrockEvent) =>
         event.modelStreamErrorException?.message ??
         event.serviceUnavailableException?.message ??
         "Bedrock Converse stream error"
-      return [state, [LLMEvent.providerError({ message, retryable: true })]] as const
+      return [state, [{ type: "provider-error" as const, message, retryable: true }]] as const
     }
 
     if (event.validationException || event.throttlingException) {
       const message =
         event.validationException?.message ?? event.throttlingException?.message ?? "Bedrock Converse error"
-      return [state, [LLMEvent.providerError({ message, retryable: event.throttlingException !== undefined })]] as const
+      return [
+        state,
+        [{ type: "provider-error" as const, message, retryable: event.throttlingException !== undefined }],
+      ] as const
     }
 
     return [state, []] as const
@@ -517,7 +468,7 @@ const framing = BedrockEventStream.framing(ADAPTER)
 
 const onHalt = (state: ParserState): ReadonlyArray<LLMEvent> =>
   state.pendingFinish
-    ? [LLMEvent.requestFinish({ reason: state.pendingFinish.reason, usage: state.pendingFinish.usage })]
+    ? [{ type: "request-finish", reason: state.pendingFinish.reason, usage: state.pendingFinish.usage }]
     : []
 
 // =============================================================================

packages/llm/src/protocols/gemini.ts

@@ -5,9 +5,9 @@ import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
 import { Protocol } from "../route/protocol"
 import {
-  LLMEvent,
   Usage,
   type FinishReason,
+  type LLMEvent,
   type LLMRequest,
   type MediaPart,
   type TextPart,
@@ -281,28 +281,15 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
 // =============================================================================
 // Stream Parsing
 // =============================================================================
-// Gemini reports `promptTokenCount` (inclusive total) with a
-// `cachedContentTokenCount` subset. `candidatesTokenCount` is *exclusive*
-// of `thoughtsTokenCount` — visible-only, not a total — so we sum the two
-// to produce the inclusive `outputTokens` the rest of the contract expects.
 const mapUsage = (usage: GeminiUsage | undefined) => {
   if (!usage) return undefined
-  const cached = usage.cachedContentTokenCount
-  const nonCached = ProviderShared.subtractTokens(usage.promptTokenCount, cached)
-  // `candidatesTokenCount` is visible-only; sum with thoughts to produce the
-  // inclusive `outputTokens` the contract expects. Only compute the total
-  // when the visible component is reported — otherwise we'd fabricate an
-  // inclusive number from a partial breakdown.
-  const outputTokens =
-    usage.candidatesTokenCount !== undefined ? usage.candidatesTokenCount + (usage.thoughtsTokenCount ?? 0) : undefined
   return new Usage({
     inputTokens: usage.promptTokenCount,
-    outputTokens,
-    nonCachedInputTokens: nonCached,
-    cacheReadInputTokens: cached,
+    outputTokens: usage.candidatesTokenCount,
     reasoningTokens: usage.thoughtsTokenCount,
-    totalTokens: ProviderShared.totalTokens(usage.promptTokenCount, outputTokens, usage.totalTokenCount),
-    providerMetadata: { google: usage },
+    cacheReadInputTokens: usage.cachedContentTokenCount,
+    totalTokens: ProviderShared.totalTokens(usage.promptTokenCount, usage.candidatesTokenCount, usage.totalTokenCount),
+    native: usage,
   })
 }
 
@@ -324,7 +311,7 @@ const mapFinishReason = (finishReason: string | undefined, hasToolCalls: boolean
 
 const finish = (state: ParserState): ReadonlyArray<LLMEvent> =>
   state.finishReason || state.usage
-    ? [LLMEvent.requestFinish({ reason: mapFinishReason(state.finishReason, state.hasToolCalls), usage: state.usage })]
+    ? [{ type: "request-finish", reason: mapFinishReason(state.finishReason, state.hasToolCalls), usage: state.usage }]
     : []
 
 const step = (state: ParserState, event: GeminiEvent) => {
@@ -345,18 +332,14 @@ const step = (state: ParserState, event: GeminiEvent) => {
 
   for (const part of candidate.content.parts) {
     if ("text" in part && part.text.length > 0) {
-      events.push(
-        part.thought
-          ? LLMEvent.reasoningDelta({ id: "reasoning-0", text: part.text })
-          : LLMEvent.textDelta({ id: "text-0", text: part.text }),
-      )
+      events.push({ type: part.thought ? "reasoning-delta" : "text-delta", text: part.text })
       continue
     }
 
     if ("functionCall" in part) {
       const input = part.functionCall.args
       const id = `tool_${nextToolCallId++}`
-      events.push(LLMEvent.toolCall({ id, name: part.functionCall.name, input }))
+      events.push({ type: "tool-call", id, name: part.functionCall.name, input })
       hasToolCalls = true
     }
   }

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

@@ -6,9 +6,9 @@ import { Framing } from "../route/framing"
 import { HttpTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
-  LLMEvent,
   Usage,
   type FinishReason,
+  type LLMEvent,
   type LLMRequest,
   type TextPart,
   type ToolCallPart,
@@ -290,24 +290,15 @@ const mapFinishReason = (reason: string | null | undefined): FinishReason => {
   return "unknown"
 }
 
-// OpenAI Chat reports `prompt_tokens` (inclusive total) with a
-// `cached_tokens` subset, and `completion_tokens` (inclusive total) with
-// a `reasoning_tokens` subset. We pass the inclusive totals through and
-// derive the non-cached breakdown so the `LLM.Usage` contract is
-// satisfied on both sides.
 const mapUsage = (usage: OpenAIChatEvent["usage"]): Usage | undefined => {
   if (!usage) return undefined
-  const cached = usage.prompt_tokens_details?.cached_tokens
-  const reasoning = usage.completion_tokens_details?.reasoning_tokens
-  const nonCached = ProviderShared.subtractTokens(usage.prompt_tokens, cached)
   return new Usage({
     inputTokens: usage.prompt_tokens,
     outputTokens: usage.completion_tokens,
-    nonCachedInputTokens: nonCached,
-    cacheReadInputTokens: cached,
-    reasoningTokens: reasoning,
+    reasoningTokens: usage.completion_tokens_details?.reasoning_tokens,
+    cacheReadInputTokens: usage.prompt_tokens_details?.cached_tokens,
     totalTokens: ProviderShared.totalTokens(usage.prompt_tokens, usage.completion_tokens, usage.total_tokens),
-    providerMetadata: { openai: usage },
+    native: usage,
   })
 }
 
@@ -321,7 +312,7 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
     const toolDeltas = delta?.tool_calls ?? []
     let tools = state.tools
 
-    if (delta?.content) events.push(LLMEvent.textDelta({ id: "text-0", text: delta.content }))
+    if (delta?.content) events.push({ type: "text-delta", text: delta.content })
 
     for (const tool of toolDeltas) {
       const result = ToolStream.appendOrStart(
@@ -357,7 +348,10 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
 const finishEvents = (state: ParserState): ReadonlyArray<LLMEvent> => {
   const hasToolCalls = state.toolCallEvents.length > 0
   const reason = state.finishReason === "stop" && hasToolCalls ? "tool-calls" : state.finishReason
-  return [...state.toolCallEvents, ...(reason ? [LLMEvent.requestFinish({ reason, usage: state.usage })] : [])]
+  return [
+    ...state.toolCallEvents,
+    ...(reason ? ([{ type: "request-finish", reason, usage: state.usage }] satisfies ReadonlyArray<LLMEvent>) : []),
+  ]
 }
 
 // =============================================================================

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

@@ -6,9 +6,9 @@ import { Framing } from "../route/framing"
 import { HttpTransport, WebSocketTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
-  LLMEvent,
   Usage,
   type FinishReason,
+  type LLMEvent,
   type LLMRequest,
   type ProviderMetadata,
   type TextPart,
@@ -276,23 +276,15 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
 // =============================================================================
 // Stream Parsing
 // =============================================================================
-// OpenAI Responses reports `input_tokens` (inclusive total) with a
-// `cached_tokens` subset, and `output_tokens` (inclusive total) with a
-// `reasoning_tokens` subset. Pass the totals through and derive the
-// non-cached breakdown.
 const mapUsage = (usage: OpenAIResponsesUsage | null | undefined) => {
   if (!usage) return undefined
-  const cached = usage.input_tokens_details?.cached_tokens
-  const reasoning = usage.output_tokens_details?.reasoning_tokens
-  const nonCached = ProviderShared.subtractTokens(usage.input_tokens, cached)
   return new Usage({
     inputTokens: usage.input_tokens,
     outputTokens: usage.output_tokens,
-    nonCachedInputTokens: nonCached,
-    cacheReadInputTokens: cached,
-    reasoningTokens: reasoning,
+    reasoningTokens: usage.output_tokens_details?.reasoning_tokens,
+    cacheReadInputTokens: usage.input_tokens_details?.cached_tokens,
     totalTokens: ProviderShared.totalTokens(usage.input_tokens, usage.output_tokens, usage.total_tokens),
-    providerMetadata: { openai: usage },
+    native: usage,
   })
 }
 
@@ -356,20 +348,22 @@ const hostedToolEvents = (
   const tool = HOSTED_TOOLS[item.type]
   const providerMetadata = openaiMetadata({ itemId: item.id })
   return [
-    LLMEvent.toolCall({
+    {
+      type: "tool-call",
       id: item.id,
       name: tool.name,
       input: tool.input(item),
       providerExecuted: true,
       providerMetadata,
-    }),
-    LLMEvent.toolResult({
+    },
+    {
+      type: "tool-result",
       id: item.id,
       name: tool.name,
       result: hostedToolResult(item),
       providerExecuted: true,
       providerMetadata,
-    }),
+    },
   ]
 }
 
@@ -385,7 +379,17 @@ const TERMINAL_TYPES = new Set(["response.completed", "response.incomplete", "re
 
 const onOutputTextDelta = (state: ParserState, event: OpenAIResponsesEvent): StepResult => {
   if (!event.delta) return [state, NO_EVENTS]
-  return [state, [LLMEvent.textDelta({ id: event.item_id ?? "text-0", text: event.delta })]]
+  return [
+    state,
+    [
+      {
+        type: "text-delta",
+        id: event.item_id,
+        text: event.delta,
+        ...(event.item_id ? { providerMetadata: openaiMetadata({ itemId: event.item_id }) } : {}),
+      },
+    ],
+  ]
 }
 
 const onOutputItemAdded = (state: ParserState, event: OpenAIResponsesEvent): StepResult => {
@@ -454,28 +458,30 @@ const onOutputItemDone = Effect.fn("OpenAIResponses.onOutputItemDone")(function*
 const onResponseFinish = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
   state,
   [
-    LLMEvent.requestFinish({
+    {
+      type: "request-finish",
       reason: mapFinishReason(event, state.hasFunctionCall),
       usage: mapUsage(event.response?.usage),
-      providerMetadata:
-        event.response?.id || event.response?.service_tier
-          ? openaiMetadata({
+      ...(event.response?.id || event.response?.service_tier
+        ? {
+            providerMetadata: openaiMetadata({
               responseId: event.response.id,
               serviceTier: event.response.service_tier,
-            })
-          : undefined,
-    }),
+            }),
+          }
+        : {}),
+    },
   ],
 ]
 
 const onResponseFailed = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
   state,
-  [LLMEvent.providerError({ message: event.message ?? event.code ?? "OpenAI Responses response failed" })],
+  [{ type: "provider-error", message: event.message ?? event.code ?? "OpenAI Responses response failed" }],
 ]
 
 const onError = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
   state,
-  [LLMEvent.providerError({ message: event.message ?? event.code ?? "OpenAI Responses stream error" })],
+  [{ type: "provider-error", message: event.message ?? event.code ?? "OpenAI Responses stream error" }],
 ]
 
 const step = (state: ParserState, event: OpenAIResponsesEvent) => {

packages/llm/src/protocols/shared.ts

@@ -42,13 +42,6 @@ export interface ToolAccumulator {
  * supplied total; otherwise falls back to `inputTokens + outputTokens` only
  * when at least one is defined. Returns `undefined` when neither input nor
  * output is known so routes don't publish a misleading `0`.
- *
- * Under the additive `LLM.Usage` contract, `inputTokens` and `outputTokens`
- * are the non-cached input and visible output only. The provider-supplied
- * `total` is the source of truth when present; the computed fallback
- * under-counts cache and reasoning by design and exists mainly so
- * Anthropic-style providers (which don't surface a total) still get a
- * sensible aggregate on the input + output axes.
  */
 export const totalTokens = (
   inputTokens: number | undefined,
@@ -60,35 +53,6 @@ export const totalTokens = (
   return (inputTokens ?? 0) + (outputTokens ?? 0)
 }
 
-/**
- * Subtract `subtrahend` from `total`, clamping to zero if the provider
- * reports a non-sensical breakdown (e.g. `cached_tokens > prompt_tokens`).
- * Used by protocol mappers when deriving a non-overlapping breakdown field
- * from a provider's inclusive total — `nonCachedInputTokens` from
- * `inputTokens - cacheReadInputTokens - cacheWriteInputTokens`.
- *
- * If `total` is `undefined`, returns `undefined` (we don't fabricate
- * counts). If `subtrahend` is `undefined`, returns `total` unchanged. The
- * provider-native breakdown stays available on `Usage.native` for debugging.
- */
-export const subtractTokens = (total: number | undefined, subtrahend: number | undefined): number | undefined => {
-  if (total === undefined) return undefined
-  if (subtrahend === undefined) return total
-  return Math.max(0, total - subtrahend)
-}
-
-/**
- * Sum a list of optional token counts, returning `undefined` only when
- * every value is `undefined` (so we don't fabricate a `0`). Used by
- * protocol mappers to derive the inclusive `inputTokens` total from a
- * provider that natively reports a non-overlapping breakdown
- * (e.g. Anthropic, whose `input_tokens` is already non-cached only).
- */
-export const sumTokens = (...values: ReadonlyArray<number | undefined>): number | undefined => {
-  if (values.every((value) => value === undefined)) return undefined
-  return values.reduce<number>((acc, value) => acc + (value ?? 0), 0)
-}
-
 export const eventError = (route: string, message: string, raw?: string) =>
   new LLMError({
     module: "ProviderShared",

packages/llm/src/protocols/utils/bedrock-cache.ts

@@ -1,37 +1,20 @@
 import { Schema } from "effect"
 import type { CacheHint } from "../../schema"
-import { newBreakpoints, ttlBucket, type Breakpoints } from "./cache"
 
 // Bedrock cache markers are positional: emit a `cachePoint` block immediately
-// after the content the caller wants treated as a cacheable prefix. Bedrock
-// accepts optional `ttl: "5m" | "1h"` on cachePoint, mirroring Anthropic.
+// after the content the caller wants treated as a cacheable prefix.
 export const CachePointBlock = Schema.Struct({
-  cachePoint: Schema.Struct({
-    type: Schema.tag("default"),
-    ttl: Schema.optional(Schema.Literals(["5m", "1h"])),
-  }),
+  cachePoint: Schema.Struct({ type: Schema.tag("default") }),
 })
 export type CachePointBlock = Schema.Schema.Type<typeof CachePointBlock>
 
-// Bedrock-Claude enforces the same 4-breakpoint cap as the Anthropic Messages
-// API. Callers pass a shared counter through every `block()` call site so the
-// budget is respected across `system`, `messages`, and `tools`.
-export const BEDROCK_BREAKPOINT_CAP = 4
+// Bedrock recently added optional `ttl: "5m" | "1h"` on cachePoint. Map
+// `CacheHint.ttlSeconds` here once a recorded cassette validates the wire shape.
+const DEFAULT: CachePointBlock = { cachePoint: { type: "default" } }
 
-export type { Breakpoints } from "./cache"
-export const breakpoints = () => newBreakpoints(BEDROCK_BREAKPOINT_CAP)
-
-const DEFAULT_5M: CachePointBlock = { cachePoint: { type: "default" } }
-const DEFAULT_1H: CachePointBlock = { cachePoint: { type: "default", ttl: "1h" } }
-
-export const block = (breakpoints: Breakpoints, cache: CacheHint | undefined): CachePointBlock | undefined => {
+export const block = (cache: CacheHint | undefined): CachePointBlock | undefined => {
   if (cache?.type !== "ephemeral" && cache?.type !== "persistent") return undefined
-  if (breakpoints.remaining <= 0) {
-    breakpoints.dropped += 1
-    return undefined
-  }
-  breakpoints.remaining -= 1
-  return ttlBucket(cache.ttlSeconds) === "1h" ? DEFAULT_1H : DEFAULT_5M
+  return DEFAULT
 }
 
 export * as BedrockCache from "./bedrock-cache"

packages/llm/src/protocols/utils/cache.ts

@@ -1,16 +0,0 @@
-// Shared helpers for provider cache-marker lowering. Anthropic and Bedrock
-// both enforce a 4-breakpoint cap per request and accept the same `5m`/`1h`
-// TTL buckets, so the counter and TTL mapping live here.
-
-export interface Breakpoints {
-  remaining: number
-  dropped: number
-}
-
-export const newBreakpoints = (cap: number): Breakpoints => ({ remaining: cap, dropped: 0 })
-
-// Returns `"1h"` for any `ttlSeconds >= 3600`, otherwise `undefined` (the
-// provider default 5m). Anthropic & Bedrock both treat anything shorter than
-// an hour as 5m.
-export const ttlBucket = (ttlSeconds: number | undefined): "1h" | undefined =>
-  ttlSeconds !== undefined && ttlSeconds >= 3600 ? "1h" : undefined

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

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall, type ToolInputDelta } from "../../schema"
+import { LLMError, type ProviderMetadata, type ToolCall, type ToolInputDelta } from "../../schema"
 import { eventError, parseToolInput, type ToolAccumulator } from "../shared"
 
 type StreamKey = string | number
@@ -49,24 +49,34 @@ const withoutTool = <K extends StreamKey>(tools: State<K>, key: K): State<K> =>
   return next
 }
 
-const inputDelta = (tool: PendingTool, text: string): ToolInputDelta =>
-  LLMEvent.toolInputDelta({
-    id: tool.id,
-    name: tool.name,
-    text,
-  })
+const inputDelta = (tool: PendingTool, text: string): ToolInputDelta => ({
+  type: "tool-input-delta",
+  id: tool.id,
+  name: tool.name,
+  text,
+  ...(tool.providerMetadata ? { providerMetadata: tool.providerMetadata } : {}),
+})
 
 const toolCall = (route: string, tool: PendingTool, inputOverride?: string) =>
   parseToolInput(route, tool.name, inputOverride ?? tool.input).pipe(
     Effect.map(
       (input): ToolCall =>
-        LLMEvent.toolCall({
-          id: tool.id,
-          name: tool.name,
-          input,
-          providerExecuted: tool.providerExecuted ? true : undefined,
-          providerMetadata: tool.providerMetadata,
-        }),
+        tool.providerExecuted
+          ? {
+              type: "tool-call",
+              id: tool.id,
+              name: tool.name,
+              input,
+              providerExecuted: true,
+              ...(tool.providerMetadata ? { providerMetadata: tool.providerMetadata } : {}),
+            }
+          : {
+              type: "tool-call",
+              id: tool.id,
+              name: tool.name,
+              input,
+              ...(tool.providerMetadata ? { providerMetadata: tool.providerMetadata } : {}),
+            },
     ),
   )
 

packages/llm/src/route/client.ts

@@ -8,7 +8,6 @@ import type { Transport, TransportRuntime } from "./transport"
 import { WebSocketExecutor } from "./transport"
 import type { Service as WebSocketExecutorService } from "./transport/websocket"
 import type { Protocol } from "./protocol"
-import { applyCachePolicy } from "../cache-policy"
 import * as ProviderShared from "../protocols/shared"
 import * as ToolRuntime from "../tool-runtime"
 import type { Tools } from "../tool"
@@ -401,7 +400,7 @@ export function make<Body, Prepared, Frame, Event, State>(
 // validated provider body plus transport-private prepared data, but does not
 // execute transport.
 const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest) {
-  const resolved = applyCachePolicy(resolveRequestOptions(request))
+  const resolved = resolveRequestOptions(request)
   const route = registeredRoute(resolved.model.route)
   if (!route) return yield* noRoute(resolved.model)
 

packages/llm/src/schema/events.ts

@@ -1,155 +1,73 @@
 import { Schema } from "effect"
-import { ContentBlockID, FinishReason, ProtocolID, ProviderMetadata, ResponseID, RouteID, ToolCallID } from "./ids"
+import { FinishReason, ProtocolID, ProviderMetadata, RouteID } from "./ids"
 import { ModelRef } from "./options"
 import { ToolResultValue } from "./messages"
 
-/**
- * Token usage reported by an LLM provider.
- *
- * **Inclusive totals** (match AI SDK / OpenAI / LangChain convention — a
- * reader from any of those ecosystems sees the number they expect):
- *
- * - `inputTokens` — total prompt tokens, *including* cached reads/writes.
- * - `outputTokens` — total output tokens, *including* reasoning.
- * - `totalTokens` — provider-supplied total, or `inputTokens + outputTokens`.
- *
- * **Non-overlapping breakdown** (every field is independently meaningful;
- * consumers never have to subtract):
- *
- * - `nonCachedInputTokens` — the "fresh" portion of the prompt.
- * - `cacheReadInputTokens` — input tokens served from cache.
- * - `cacheWriteInputTokens` — input tokens written to cache.
- * - `reasoningTokens` — subset of `outputTokens` spent on hidden reasoning.
- *
- * **Invariant**: `nonCachedInputTokens + cacheReadInputTokens +
- * cacheWriteInputTokens = inputTokens`, and `reasoningTokens ≤ outputTokens`.
- * Each protocol mapper computes whichever side it doesn't get natively,
- * with `Math.max(0, …)` clamping for defense against provider bugs. Because
- * every breakdown field is stored independently, downstream consumers can
- * read whatever they need (cost-by-category, context-pressure, AI-SDK-style
- * inclusive total) without ever subtracting — eliminating the underflow
- * class of bug where a clamped difference would silently store the wrong
- * value.
- *
- * **Semantics by provider**:
- *
- * - OpenAI Chat / Responses / Gemini / Bedrock: provider reports inclusive
- *   `inputTokens` and an inclusive `outputTokens`; mapper subtracts to
- *   derive the breakdown.
- * - Anthropic: provider reports the breakdown natively (`input_tokens` is
- *   non-cached only); mapper sums to derive the inclusive `inputTokens`.
- *   Anthropic does *not* break extended-thinking out of `output_tokens`, so
- *   `reasoningTokens` is `undefined` and `outputTokens` carries the
- *   combined total — a documented limitation of the Anthropic API.
- *
- * `providerMetadata` always carries the provider's raw usage payload —
- * keyed by provider name (`{ openai: ... }`, `{ anthropic: ... }`, etc.)
- * — for fields we don't normalize and for billing-level audit trails.
- * Matches the same escape-hatch field on `LLMEvent`.
- */
 export class Usage extends Schema.Class<Usage>("LLM.Usage")({
   inputTokens: Schema.optional(Schema.Number),
   outputTokens: Schema.optional(Schema.Number),
-  nonCachedInputTokens: Schema.optional(Schema.Number),
+  reasoningTokens: Schema.optional(Schema.Number),
   cacheReadInputTokens: Schema.optional(Schema.Number),
   cacheWriteInputTokens: Schema.optional(Schema.Number),
-  reasoningTokens: Schema.optional(Schema.Number),
   totalTokens: Schema.optional(Schema.Number),
-  providerMetadata: Schema.optional(ProviderMetadata),
-}) {
-  /**
-   * Visible output tokens — `outputTokens` minus `reasoningTokens`, clamped
-   * to zero. The one place subtraction happens in this contract; the clamp
-   * means a provider reporting `reasoningTokens > outputTokens` produces a
-   * harmless zero rather than a negative that crashes downstream schemas.
-   */
-  get visibleOutputTokens() {
-    return Math.max(0, (this.outputTokens ?? 0) - (this.reasoningTokens ?? 0))
-  }
-}
+  native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+}) {}
 
 export const RequestStart = Schema.Struct({
-  type: Schema.tag("request-start"),
-  id: ResponseID,
+  type: Schema.Literal("request-start"),
+  id: Schema.String,
   model: ModelRef,
 }).annotate({ identifier: "LLM.Event.RequestStart" })
 export type RequestStart = Schema.Schema.Type<typeof RequestStart>
 
 export const StepStart = Schema.Struct({
-  type: Schema.tag("step-start"),
+  type: Schema.Literal("step-start"),
   index: Schema.Number,
 }).annotate({ identifier: "LLM.Event.StepStart" })
 export type StepStart = Schema.Schema.Type<typeof StepStart>
 
 export const TextStart = Schema.Struct({
-  type: Schema.tag("text-start"),
-  id: ContentBlockID,
+  type: Schema.Literal("text-start"),
+  id: Schema.String,
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.TextStart" })
 export type TextStart = Schema.Schema.Type<typeof TextStart>
 
 export const TextDelta = Schema.Struct({
-  type: Schema.tag("text-delta"),
-  id: ContentBlockID,
+  type: Schema.Literal("text-delta"),
+  id: Schema.optional(Schema.String),
   text: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.TextDelta" })
 export type TextDelta = Schema.Schema.Type<typeof TextDelta>
 
 export const TextEnd = Schema.Struct({
-  type: Schema.tag("text-end"),
-  id: ContentBlockID,
+  type: Schema.Literal("text-end"),
+  id: Schema.String,
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.TextEnd" })
 export type TextEnd = Schema.Schema.Type<typeof TextEnd>
 
-export const ReasoningStart = Schema.Struct({
-  type: Schema.tag("reasoning-start"),
-  id: ContentBlockID,
-  providerMetadata: Schema.optional(ProviderMetadata),
-}).annotate({ identifier: "LLM.Event.ReasoningStart" })
-export type ReasoningStart = Schema.Schema.Type<typeof ReasoningStart>
-
 export const ReasoningDelta = Schema.Struct({
-  type: Schema.tag("reasoning-delta"),
-  id: ContentBlockID,
+  type: Schema.Literal("reasoning-delta"),
+  id: Schema.optional(Schema.String),
   text: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.ReasoningDelta" })
 export type ReasoningDelta = Schema.Schema.Type<typeof ReasoningDelta>
 
-export const ReasoningEnd = Schema.Struct({
-  type: Schema.tag("reasoning-end"),
-  id: ContentBlockID,
-  providerMetadata: Schema.optional(ProviderMetadata),
-}).annotate({ identifier: "LLM.Event.ReasoningEnd" })
-export type ReasoningEnd = Schema.Schema.Type<typeof ReasoningEnd>
-
-export const ToolInputStart = Schema.Struct({
-  type: Schema.tag("tool-input-start"),
-  id: ToolCallID,
-  name: Schema.String,
-  providerMetadata: Schema.optional(ProviderMetadata),
-}).annotate({ identifier: "LLM.Event.ToolInputStart" })
-export type ToolInputStart = Schema.Schema.Type<typeof ToolInputStart>
-
 export const ToolInputDelta = Schema.Struct({
-  type: Schema.tag("tool-input-delta"),
-  id: ToolCallID,
+  type: Schema.Literal("tool-input-delta"),
+  id: Schema.String,
   name: Schema.String,
   text: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.ToolInputDelta" })
 export type ToolInputDelta = Schema.Schema.Type<typeof ToolInputDelta>
 
-export const ToolInputEnd = Schema.Struct({
-  type: Schema.tag("tool-input-end"),
-  id: ToolCallID,
-  name: Schema.String,
-  providerMetadata: Schema.optional(ProviderMetadata),
-}).annotate({ identifier: "LLM.Event.ToolInputEnd" })
-export type ToolInputEnd = Schema.Schema.Type<typeof ToolInputEnd>
-
 export const ToolCall = Schema.Struct({
-  type: Schema.tag("tool-call"),
-  id: ToolCallID,
+  type: Schema.Literal("tool-call"),
+  id: Schema.String,
   name: Schema.String,
   input: Schema.Unknown,
   providerExecuted: Schema.optional(Schema.Boolean),
@@ -158,8 +76,8 @@ export const ToolCall = Schema.Struct({
 export type ToolCall = Schema.Schema.Type<typeof ToolCall>
 
 export const ToolResult = Schema.Struct({
-  type: Schema.tag("tool-result"),
-  id: ToolCallID,
+  type: Schema.Literal("tool-result"),
+  id: Schema.String,
   name: Schema.String,
   result: ToolResultValue,
   providerExecuted: Schema.optional(Schema.Boolean),
@@ -168,8 +86,8 @@ export const ToolResult = Schema.Struct({
 export type ToolResult = Schema.Schema.Type<typeof ToolResult>
 
 export const ToolError = Schema.Struct({
-  type: Schema.tag("tool-error"),
-  id: ToolCallID,
+  type: Schema.Literal("tool-error"),
+  id: Schema.String,
   name: Schema.String,
   message: Schema.String,
   providerMetadata: Schema.optional(ProviderMetadata),
@@ -177,7 +95,7 @@ export const ToolError = Schema.Struct({
 export type ToolError = Schema.Schema.Type<typeof ToolError>
 
 export const StepFinish = Schema.Struct({
-  type: Schema.tag("step-finish"),
+  type: Schema.Literal("step-finish"),
   index: Schema.Number,
   reason: FinishReason,
   usage: Schema.optional(Usage),
@@ -186,7 +104,7 @@ export const StepFinish = Schema.Struct({
 export type StepFinish = Schema.Schema.Type<typeof StepFinish>
 
 export const RequestFinish = Schema.Struct({
-  type: Schema.tag("request-finish"),
+  type: Schema.Literal("request-finish"),
   reason: FinishReason,
   usage: Schema.optional(Usage),
   providerMetadata: Schema.optional(ProviderMetadata),
@@ -194,7 +112,7 @@ export const RequestFinish = Schema.Struct({
 export type RequestFinish = Schema.Schema.Type<typeof RequestFinish>
 
 export const ProviderErrorEvent = Schema.Struct({
-  type: Schema.tag("provider-error"),
+  type: Schema.Literal("provider-error"),
   message: Schema.String,
   retryable: Schema.optional(Schema.Boolean),
   providerMetadata: Schema.optional(ProviderMetadata),
@@ -207,12 +125,8 @@ const llmEventTagged = Schema.Union([
   TextStart,
   TextDelta,
   TextEnd,
-  ReasoningStart,
   ReasoningDelta,
-  ReasoningEnd,
-  ToolInputStart,
   ToolInputDelta,
-  ToolInputEnd,
   ToolCall,
   ToolResult,
   ToolError,
@@ -221,52 +135,20 @@ const llmEventTagged = Schema.Union([
   ProviderErrorEvent,
 ]).pipe(Schema.toTaggedUnion("type"))
 
-type WithID<Event extends { readonly id: unknown }, ID> = Omit<Event, "type" | "id"> & { readonly id: ID | string }
-
-const responseID = (value: ResponseID | string) => ResponseID.make(value)
-const contentBlockID = (value: ContentBlockID | string) => ContentBlockID.make(value)
-const toolCallID = (value: ToolCallID | string) => ToolCallID.make(value)
-
 /**
  * camelCase aliases for `LLMEvent.guards` (provided by `Schema.toTaggedUnion`).
  * Lets consumers write `events.filter(LLMEvent.is.toolCall)` instead of
  * `events.filter(LLMEvent.guards["tool-call"])`.
  */
 export const LLMEvent = Object.assign(llmEventTagged, {
-  requestStart: (input: WithID<RequestStart, ResponseID>) => RequestStart.make({ ...input, id: responseID(input.id) }),
-  stepStart: StepStart.make,
-  textStart: (input: WithID<TextStart, ContentBlockID>) => TextStart.make({ ...input, id: contentBlockID(input.id) }),
-  textDelta: (input: WithID<TextDelta, ContentBlockID>) => TextDelta.make({ ...input, id: contentBlockID(input.id) }),
-  textEnd: (input: WithID<TextEnd, ContentBlockID>) => TextEnd.make({ ...input, id: contentBlockID(input.id) }),
-  reasoningStart: (input: WithID<ReasoningStart, ContentBlockID>) =>
-    ReasoningStart.make({ ...input, id: contentBlockID(input.id) }),
-  reasoningDelta: (input: WithID<ReasoningDelta, ContentBlockID>) =>
-    ReasoningDelta.make({ ...input, id: contentBlockID(input.id) }),
-  reasoningEnd: (input: WithID<ReasoningEnd, ContentBlockID>) =>
-    ReasoningEnd.make({ ...input, id: contentBlockID(input.id) }),
-  toolInputStart: (input: WithID<ToolInputStart, ToolCallID>) =>
-    ToolInputStart.make({ ...input, id: toolCallID(input.id) }),
-  toolInputDelta: (input: WithID<ToolInputDelta, ToolCallID>) =>
-    ToolInputDelta.make({ ...input, id: toolCallID(input.id) }),
-  toolInputEnd: (input: WithID<ToolInputEnd, ToolCallID>) => ToolInputEnd.make({ ...input, id: toolCallID(input.id) }),
-  toolCall: (input: WithID<ToolCall, ToolCallID>) => ToolCall.make({ ...input, id: toolCallID(input.id) }),
-  toolResult: (input: WithID<ToolResult, ToolCallID>) => ToolResult.make({ ...input, id: toolCallID(input.id) }),
-  toolError: (input: WithID<ToolError, ToolCallID>) => ToolError.make({ ...input, id: toolCallID(input.id) }),
-  stepFinish: StepFinish.make,
-  requestFinish: RequestFinish.make,
-  providerError: ProviderErrorEvent.make,
   is: {
     requestStart: llmEventTagged.guards["request-start"],
     stepStart: llmEventTagged.guards["step-start"],
     textStart: llmEventTagged.guards["text-start"],
     textDelta: llmEventTagged.guards["text-delta"],
     textEnd: llmEventTagged.guards["text-end"],
-    reasoningStart: llmEventTagged.guards["reasoning-start"],
     reasoningDelta: llmEventTagged.guards["reasoning-delta"],
-    reasoningEnd: llmEventTagged.guards["reasoning-end"],
-    toolInputStart: llmEventTagged.guards["tool-input-start"],
     toolInputDelta: llmEventTagged.guards["tool-input-delta"],
-    toolInputEnd: llmEventTagged.guards["tool-input-end"],
     toolCall: llmEventTagged.guards["tool-call"],
     toolResult: llmEventTagged.guards["tool-result"],
     toolError: llmEventTagged.guards["tool-error"],

packages/llm/src/schema/ids.ts

@@ -14,15 +14,6 @@ export type ModelID = typeof ModelID.Type
 export const ProviderID = Schema.String.pipe(Schema.brand("LLM.ProviderID"))
 export type ProviderID = typeof ProviderID.Type
 
-export const ResponseID = Schema.String
-export type ResponseID = Schema.Schema.Type<typeof ResponseID>
-
-export const ContentBlockID = Schema.String
-export type ContentBlockID = Schema.Schema.Type<typeof ContentBlockID>
-
-export const ToolCallID = Schema.String
-export type ToolCallID = Schema.Schema.Type<typeof ToolCallID>
-
 export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
 export const ReasoningEffort = Schema.Literals(ReasoningEfforts)
 export type ReasoningEffort = Schema.Schema.Type<typeof ReasoningEffort>

packages/llm/src/schema/messages.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect"
 import { JsonSchema, MessageRole, ProviderMetadata } from "./ids"
-import { CacheHint, CachePolicy, GenerationOptions, HttpOptions, ModelRef, ProviderOptions } from "./options"
+import { CacheHint, GenerationOptions, HttpOptions, ModelRef, ProviderOptions } from "./options"
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
@@ -79,7 +79,6 @@ export const ToolResultPart = Object.assign(
     name: Schema.String,
     result: ToolResultValue,
     providerExecuted: Schema.optional(Schema.Boolean),
-    cache: Schema.optional(CacheHint),
     metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
     providerMetadata: Schema.optional(ProviderMetadata),
   }).annotate({ identifier: "LLM.Content.ToolResult" }),
@@ -95,7 +94,6 @@ export const ToolResultPart = Object.assign(
       name: input.name,
       result: ToolResultValue.make(input.result, input.resultType),
       providerExecuted: input.providerExecuted,
-      cache: input.cache,
       metadata: input.metadata,
       providerMetadata: input.providerMetadata,
     }),
@@ -153,7 +151,6 @@ export class ToolDefinition extends Schema.Class<ToolDefinition>("LLM.ToolDefini
   name: Schema.String,
   description: Schema.String,
   inputSchema: JsonSchema,
-  cache: Schema.optional(CacheHint),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
   native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 }) {}
@@ -206,7 +203,6 @@ export class LLMRequest extends Schema.Class<LLMRequest>("LLM.Request")({
   providerOptions: Schema.optional(ProviderOptions),
   http: Schema.optional(HttpOptions),
   responseFormat: Schema.optional(ResponseFormat),
-  cache: Schema.optional(CachePolicy),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 }) {}
 
@@ -224,7 +220,6 @@ export namespace LLMRequest {
     providerOptions: request.providerOptions,
     http: request.http,
     responseFormat: request.responseFormat,
-    cache: request.cache,
     metadata: request.metadata,
   })
 

packages/llm/src/schema/options.ts

@@ -200,31 +200,3 @@ export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({
   type: Schema.Literals(["ephemeral", "persistent"]),
   ttlSeconds: Schema.optional(Schema.Number),
 }) {}
-
-// Auto-placement policy for prompt caching. The protocol-neutral lowering step
-// reads this and injects `CacheHint`s at the configured boundaries; the
-// per-protocol body builders then translate those hints into wire markers as
-// usual. `"auto"` is the recommended default for agent loops — it places one
-// breakpoint at the last tool definition, one at the last system part, and one
-// at the latest user message. The combination of provider invalidation
-// hierarchy (tools → system → messages) and Anthropic/Bedrock's 20-block
-// lookback means three trailing breakpoints reliably cover the static prefix.
-//
-// Pass `"none"` to opt out entirely (the legacy behavior). Pass the granular
-// object form to override individual choices.
-export const CachePolicyObject = Schema.Struct({
-  tools: Schema.optional(Schema.Boolean),
-  system: Schema.optional(Schema.Boolean),
-  messages: Schema.optional(
-    Schema.Union([
-      Schema.Literal("latest-user-message"),
-      Schema.Literal("latest-assistant"),
-      Schema.Struct({ tail: Schema.Number }),
-    ]),
-  ),
-  ttlSeconds: Schema.optional(Schema.Number),
-})
-export type CachePolicyObject = Schema.Schema.Type<typeof CachePolicyObject>
-
-export const CachePolicy = Schema.Union([Schema.Literal("auto"), Schema.Literal("none"), CachePolicyObject])
-export type CachePolicy = Schema.Schema.Type<typeof CachePolicy>

packages/llm/src/tool-runtime.ts

@@ -4,7 +4,7 @@ import {
   type ContentPart,
   type FinishReason,
   type LLMError,
-  LLMEvent,
+  type LLMEvent,
   LLMRequest,
   Message,
   type ProviderMetadata,
@@ -115,19 +115,11 @@ interface StepState {
 
 const accumulate = (state: StepState, event: LLMEvent) => {
   if (event.type === "text-delta") {
-    appendStreamingText(state, "text", event.text, undefined)
+    appendStreamingText(state, "text", event.text, event.providerMetadata)
     return
   }
   if (event.type === "reasoning-delta") {
-    appendStreamingText(state, "reasoning", event.text, undefined)
-    return
-  }
-  if (event.type === "reasoning-end") {
-    appendStreamingText(state, "reasoning", "", event.providerMetadata)
-    return
-  }
-  if (event.type === "text-end") {
-    appendStreamingText(state, "text", "", event.providerMetadata)
+    appendStreamingText(state, "reasoning", event.text, event.providerMetadata)
     return
   }
   if (event.type === "tool-call") {
@@ -227,10 +219,10 @@ const decodeAndExecute = (tool: AnyTool, input: unknown): Effect.Effect<ToolResu
 const emitEvents = (call: ToolCallPart, result: ToolResultValue): ReadonlyArray<LLMEvent> =>
   result.type === "error"
     ? [
-        LLMEvent.toolError({ id: call.id, name: call.name, message: String(result.value) }),
-        LLMEvent.toolResult({ id: call.id, name: call.name, result }),
+        { type: "tool-error", id: call.id, name: call.name, message: String(result.value) },
+        { type: "tool-result", id: call.id, name: call.name, result },
       ]
-    : [LLMEvent.toolResult({ id: call.id, name: call.name, result })]
+    : [{ type: "tool-result", id: call.id, name: call.name, result }]
 
 const followUpRequest = (
   request: LLMRequest,

packages/llm/test/adapter.test.ts

@@ -50,9 +50,7 @@ const request = LLM.request({
 })
 
 const raiseEvent = (event: FakeEvent): import("../src/schema").LLMEvent =>
-  event.type === "finish"
-    ? { type: "request-finish", reason: event.reason }
-    : { type: "text-delta", id: "text-0", text: event.text }
+  event.type === "finish" ? { type: "request-finish", reason: event.reason } : { type: "text-delta", text: event.text }
 
 const fakeProtocol = Protocol.make<FakeBody, FakeEvent, FakeEvent, void>({
   id: "fake",

packages/llm/test/cache-policy.test.ts

@@ -1,262 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { Effect } from "effect"
-import { CacheHint, LLM } from "../src"
-import { LLMClient } from "../src/route"
-import * as AnthropicMessages from "../src/protocols/anthropic-messages"
-import * as BedrockConverse from "../src/protocols/bedrock-converse"
-import * as Gemini from "../src/protocols/gemini"
-import * as OpenAIChat from "../src/protocols/openai-chat"
-import { applyCachePolicy } from "../src/cache-policy"
-import { it } from "./lib/effect"
-
-const anthropicModel = AnthropicMessages.model({
-  id: "claude-sonnet-4-5",
-  baseURL: "https://api.anthropic.test/v1/",
-  headers: { "x-api-key": "test" },
-})
-
-const bedrockModel = BedrockConverse.model({
-  id: "anthropic.claude-3-5-sonnet-20241022-v2:0",
-  credentials: { region: "us-east-1", accessKeyId: "fixture", secretAccessKey: "fixture" },
-})
-
-const openaiModel = OpenAIChat.model({
-  id: "gpt-4o-mini",
-  baseURL: "https://api.openai.test/v1/",
-  headers: { authorization: "Bearer test" },
-})
-
-const geminiModel = Gemini.model({
-  id: "gemini-2.5-flash",
-  baseURL: "https://generativelanguage.test/v1beta/",
-  headers: { "x-goog-api-key": "test" },
-})
-
-describe("applyCachePolicy", () => {
-  it.effect("undefined cache resolves to 'auto' (the recommended default)", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          system: "You are concise.",
-          prompt: "hi",
-        }),
-      )
-
-      // No explicit cache field → auto policy fires → last system part + latest
-      // user message both get cache_control markers.
-      expect(prepared.body).toMatchObject({
-        system: [{ type: "text", text: "You are concise.", cache_control: { type: "ephemeral" } }],
-        messages: [{ role: "user", content: [{ type: "text", text: "hi", cache_control: { type: "ephemeral" } }] }],
-      })
-    }),
-  )
-
-  it.effect("'auto' marks the last tool, last system part, and latest user message on Anthropic", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          system: "Sys A",
-          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
-          messages: [LLM.user("first user"), LLM.assistant("assistant reply"), LLM.user("latest user message")],
-          cache: "auto",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        tools: [{ name: "t1", cache_control: { type: "ephemeral" } }],
-        system: [{ type: "text", text: "Sys A", cache_control: { type: "ephemeral" } }],
-        messages: [
-          { role: "user", content: [{ type: "text", text: "first user" }] },
-          { role: "assistant", content: [{ type: "text", text: "assistant reply" }] },
-          {
-            role: "user",
-            content: [{ type: "text", text: "latest user message", cache_control: { type: "ephemeral" } }],
-          },
-        ],
-      })
-    }),
-  )
-
-  it.effect("'auto' is a no-op on OpenAI (implicit caching protocol)", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: openaiModel,
-          system: "Sys",
-          prompt: "hi",
-          cache: "auto",
-        }),
-      )
-
-      const body = prepared.body as { messages: Array<{ content: unknown }> }
-      // OpenAI doesn't accept cache_control on messages — policy must skip.
-      const flat = JSON.stringify(body)
-      expect(flat).not.toContain("cache_control")
-      expect(flat).not.toContain("cachePoint")
-    }),
-  )
-
-  it.effect("'auto' is a no-op on Gemini (out-of-band caching protocol)", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: geminiModel,
-          system: "Sys",
-          prompt: "hi",
-          cache: "auto",
-        }),
-      )
-
-      const flat = JSON.stringify(prepared.body)
-      expect(flat).not.toContain("cache_control")
-      expect(flat).not.toContain("cachePoint")
-    }),
-  )
-
-  it.effect("'auto' on Bedrock emits cachePoint markers in the right places", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: bedrockModel,
-          system: "Sys",
-          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
-          messages: [LLM.user("first user"), LLM.assistant("reply"), LLM.user("latest user")],
-          cache: "auto",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        toolConfig: {
-          tools: [{ toolSpec: { name: "t1" } }, { cachePoint: { type: "default" } }],
-        },
-        system: [{ text: "Sys" }, { cachePoint: { type: "default" } }],
-        messages: [
-          { role: "user", content: [{ text: "first user" }] },
-          { role: "assistant", content: [{ text: "reply" }] },
-          { role: "user", content: [{ text: "latest user" }, { cachePoint: { type: "default" } }] },
-        ],
-      })
-    }),
-  )
-
-  it.effect("'none' disables auto placement even when manual hints exist", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          system: "Sys",
-          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
-          prompt: "hi",
-          cache: "none",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        tools: [{ name: "t1", cache_control: undefined }],
-        system: [{ type: "text", text: "Sys", cache_control: undefined }],
-      })
-    }),
-  )
-
-  it.effect("granular object form: tools-only marks just tools", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          system: "Sys",
-          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
-          prompt: "hi",
-          cache: { tools: true },
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        tools: [{ name: "t1", cache_control: { type: "ephemeral" } }],
-        system: [{ type: "text", text: "Sys", cache_control: undefined }],
-      })
-    }),
-  )
-
-  it.effect("auto policy preserves manual CacheHints on other parts", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          system: [
-            { type: "text", text: "first system", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3600 }) },
-            { type: "text", text: "last system" },
-          ],
-          prompt: "hi",
-          cache: "auto",
-        }),
-      )
-
-      const body = prepared.body as { system: Array<{ text: string; cache_control?: unknown }> }
-      expect(body.system[0]?.cache_control).toEqual({ type: "ephemeral", ttl: "1h" })
-      expect(body.system[1]?.cache_control).toEqual({ type: "ephemeral" })
-    }),
-  )
-
-  it.effect("ttlSeconds in the policy flows through to wire markers", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          system: "Sys",
-          prompt: "hi",
-          cache: { system: true, ttlSeconds: 3600 },
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        system: [{ type: "text", text: "Sys", cache_control: { type: "ephemeral", ttl: "1h" } }],
-      })
-    }),
-  )
-
-  it.effect("messages: { tail: 2 } marks the last 2 message boundaries", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          messages: [LLM.user("u1"), LLM.assistant("a1"), LLM.user("u2"), LLM.assistant("a2")],
-          cache: { messages: { tail: 2 } },
-        }),
-      )
-
-      const body = prepared.body as { messages: Array<{ content: Array<{ cache_control?: unknown }> }> }
-      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
-      expect(body.messages[1]?.content[0]?.cache_control).toBeUndefined()
-      expect(body.messages[2]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
-      expect(body.messages[3]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
-    }),
-  )
-
-  it.effect("'latest-assistant' marks the last assistant message", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model: anthropicModel,
-          messages: [LLM.user("u1"), LLM.assistant("a1"), LLM.user("u2")],
-          cache: { messages: "latest-assistant" },
-        }),
-      )
-
-      const body = prepared.body as { messages: Array<{ content: Array<{ cache_control?: unknown }> }> }
-      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
-      expect(body.messages[1]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
-      expect(body.messages[2]?.content[0]?.cache_control).toBeUndefined()
-    }),
-  )
-
-  test("returns the same request reference when policy is a no-op (pure function)", () => {
-    const request = LLM.request({
-      model: anthropicModel,
-      prompt: "hi",
-      cache: "none",
-    })
-    expect(applyCachePolicy(request)).toBe(request)
-  })
-})

packages/llm/test/llm.test.ts

@@ -126,7 +126,7 @@ describe("llm constructors", () => {
     expect(
       LLMResponse.text({
         events: [
-          { type: "text-delta", id: "text-0", text: "hi" },
+          { type: "text-delta", text: "hi" },
           { type: "request-finish", reason: "stop" },
         ],
       }),

packages/llm/test/provider/anthropic-messages-cache.recorded.test.ts

@@ -1,56 +0,0 @@
-import { Redactor } from "@opencode-ai/http-recorder"
-import { describe, expect } from "bun:test"
-import { Effect } from "effect"
-import { CacheHint, LLM } from "../../src"
-import { LLMClient } from "../../src/route"
-import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
-import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
-import { recordedTests } from "../recorded-test"
-
-const model = AnthropicMessages.model({
-  id: "claude-haiku-4-5-20251001",
-  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
-})
-
-// Two identical generations in a row. The first call writes the prefix into
-// Anthropic's cache; the second should report a cache read against the same
-// prefix. Cassette captures both interactions in order.
-const cacheRequest = LLM.request({
-  id: "recorded_anthropic_cache",
-  model,
-  system: [{ type: "text", text: LARGE_CACHEABLE_SYSTEM, cache: new CacheHint({ type: "ephemeral" }) }],
-  prompt: "Say hi.",
-  // Manual hint on the system part is the only marker we want here — skip the
-  // auto-policy's latest-user-message breakpoint so the cassette body matches.
-  cache: "none",
-  generation: { maxTokens: 16, temperature: 0 },
-})
-
-const recorded = recordedTests({
-  prefix: "anthropic-messages-cache",
-  provider: "anthropic",
-  protocol: "anthropic-messages",
-  requires: ["ANTHROPIC_API_KEY"],
-  // Two identical requests in one cassette — match by recording order so the
-  // second call replays the cached-hit interaction.
-  options: {
-    dispatch: "sequential",
-    redactor: Redactor.defaults({ requestHeaders: { allow: ["content-type", "anthropic-version"] } }),
-  },
-})
-
-describe("Anthropic Messages cache recorded", () => {
-  recorded.effect.with("writes then reads cache_control on identical second call", { tags: ["cache"] }, () =>
-    Effect.gen(function* () {
-      const first = yield* LLMClient.generate(cacheRequest)
-      // The first call may write the cache (cacheWriteInputTokens > 0) or it
-      // may be a fresh miss (both fields 0) depending on whether the prefix is
-      // already warm on Anthropic's side. The assertion that matters is that
-      // the SECOND call reports a non-zero cache read.
-      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
-
-      const second = yield* LLMClient.generate(cacheRequest)
-      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
-    }),
-  )
-})

packages/llm/test/provider/anthropic-messages.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { CacheHint, LLM, LLMError, Usage } from "../../src"
+import { CacheHint, LLM, LLMError } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
 import { it } from "../lib/effect"
@@ -18,9 +18,6 @@ const request = LLM.request({
   model,
   system: { type: "text", text: "You are concise.", cache: new CacheHint({ type: "ephemeral" }) },
   prompt: "Say hello.",
-  // This fixture predates the `cache: "auto"` default; pin the policy off so
-  // existing wire-shape assertions only see the manual hint on the system part.
-  cache: "none",
   generation: { maxTokens: 20, temperature: 0 },
 })
 
@@ -51,7 +48,6 @@ describe("Anthropic Messages route", () => {
             LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
             LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
           ],
-          cache: "none",
         }),
       )
 
@@ -114,13 +110,12 @@ describe("Anthropic Messages route", () => {
       expect(response.text).toBe("Hello!")
       expect(response.reasoning).toBe("thinking")
       expect(response.usage).toMatchObject({
-        inputTokens: 6,
+        inputTokens: 5,
         outputTokens: 2,
-        nonCachedInputTokens: 5,
         cacheReadInputTokens: 1,
-        totalTokens: 8,
+        totalTokens: 7,
       })
-      expect(response.events.find((event) => event.type === "reasoning-end")).toMatchObject({
+      expect(response.events.find((event) => event.type === "reasoning-delta" && event.text === "")).toMatchObject({
         providerMetadata: { anthropic: { signature: "sig_1" } },
       })
       expect(response.events.at(-1)).toMatchObject({
@@ -157,13 +152,7 @@ describe("Anthropic Messages route", () => {
         {
           type: "request-finish",
           reason: "tool-calls",
-          usage: new Usage({
-            inputTokens: 5,
-            outputTokens: 1,
-            nonCachedInputTokens: 5,
-            totalTokens: 6,
-            providerMetadata: { anthropic: { input_tokens: 5, output_tokens: 1 } },
-          }),
+          usage: { inputTokens: 5, outputTokens: 1, totalTokens: 6, native: { input_tokens: 5, output_tokens: 1 } },
         },
       ])
     }),
@@ -385,134 +374,4 @@ describe("Anthropic Messages route", () => {
       expect(error.message).toContain("Anthropic Messages user messages only support text content for now")
     }),
   )
-
-  it.effect("maps ttlSeconds >= 3600 to cache_control ttl: '1h'", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          system: { type: "text", text: "system", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3600 }) },
-          prompt: "hi",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        system: [{ type: "text", text: "system", cache_control: { type: "ephemeral", ttl: "1h" } }],
-      })
-    }),
-  )
-
-  it.effect("emits cache_control on tool definitions and tool-result blocks", () =>
-    Effect.gen(function* () {
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          tools: [
-            {
-              name: "lookup",
-              description: "lookup tool",
-              inputSchema: { type: "object", properties: {} },
-              cache: new CacheHint({ type: "ephemeral" }),
-            },
-          ],
-          messages: [
-            LLM.user("What's the weather?"),
-            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: {} })]),
-            LLM.toolMessage({
-              id: "call_1",
-              name: "lookup",
-              result: { temp: 72 },
-              cache: new CacheHint({ type: "ephemeral" }),
-            }),
-          ],
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        tools: [{ name: "lookup", cache_control: { type: "ephemeral" } }],
-        messages: [
-          { role: "user", content: [{ type: "text", text: "What's the weather?" }] },
-          { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "lookup" }] },
-          {
-            role: "user",
-            content: [{ type: "tool_result", tool_use_id: "call_1", cache_control: { type: "ephemeral" } }],
-          },
-        ],
-      })
-    }),
-  )
-
-  it.effect("drops cache_control breakpoints past the 4-per-request cap", () =>
-    Effect.gen(function* () {
-      const hint = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          system: [
-            { type: "text", text: "a", cache: hint },
-            { type: "text", text: "b", cache: hint },
-            { type: "text", text: "c", cache: hint },
-            { type: "text", text: "d", cache: hint },
-            { type: "text", text: "e", cache: hint },
-            { type: "text", text: "f", cache: hint },
-          ],
-          prompt: "hi",
-        }),
-      )
-
-      const system = (prepared.body as { system: Array<{ cache_control?: unknown }> }).system
-      const marked = system.filter((part) => part.cache_control !== undefined)
-      expect(marked).toHaveLength(4)
-      expect(system[4]?.cache_control).toBeUndefined()
-      expect(system[5]?.cache_control).toBeUndefined()
-    }),
-  )
-
-  it.effect("spends breakpoint budget on tools before system before messages", () =>
-    Effect.gen(function* () {
-      const hint = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          tools: [
-            {
-              name: "t1",
-              description: "t1",
-              inputSchema: { type: "object", properties: {} },
-              cache: hint,
-            },
-            {
-              name: "t2",
-              description: "t2",
-              inputSchema: { type: "object", properties: {} },
-              cache: hint,
-            },
-            {
-              name: "t3",
-              description: "t3",
-              inputSchema: { type: "object", properties: {} },
-              cache: hint,
-            },
-            {
-              name: "t4",
-              description: "t4",
-              inputSchema: { type: "object", properties: {} },
-              cache: hint,
-            },
-          ],
-          system: [{ type: "text", text: "system-tail", cache: hint }],
-          messages: [LLM.user([{ type: "text", text: "message-tail", cache: hint }])],
-        }),
-      )
-
-      const body = prepared.body as {
-        tools: Array<{ cache_control?: unknown }>
-        system: Array<{ cache_control?: unknown }>
-        messages: Array<{ content: Array<{ cache_control?: unknown }> }>
-      }
-      expect(body.tools.every((t) => t.cache_control !== undefined)).toBe(true)
-      expect(body.system[0]?.cache_control).toBeUndefined()
-      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
-    }),
-  )
 })

packages/llm/test/provider/bedrock-converse-cache.recorded.test.ts

@@ -1,56 +0,0 @@
-import { describe, expect } from "bun:test"
-import { Effect } from "effect"
-import { CacheHint, LLM } from "../../src"
-import { LLMClient } from "../../src/route"
-import * as BedrockConverse from "../../src/protocols/bedrock-converse"
-import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
-import { recordedTests } from "../recorded-test"
-
-const RECORDING_REGION = process.env.BEDROCK_RECORDING_REGION ?? "us-east-1"
-
-// Use a Claude model on Bedrock — Nova has automatic prefix caching that
-// doesn't reliably surface `cacheRead`/`cacheWrite` in usage, so the second
-// call wouldn't deterministically prove cache mapping works. Override with
-// BEDROCK_CACHE_MODEL_ID if your account has access elsewhere.
-const model = BedrockConverse.model({
-  id: process.env.BEDROCK_CACHE_MODEL_ID ?? "us.anthropic.claude-haiku-4-5-20251001-v1:0",
-  credentials: {
-    region: RECORDING_REGION,
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "fixture",
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "fixture",
-    sessionToken: process.env.AWS_SESSION_TOKEN,
-  },
-})
-
-const cacheRequest = LLM.request({
-  id: "recorded_bedrock_cache",
-  model,
-  system: [{ type: "text", text: LARGE_CACHEABLE_SYSTEM, cache: new CacheHint({ type: "ephemeral" }) }],
-  prompt: "Say hi.",
-  // Manual hint on the system part is the only marker we want here — skip the
-  // auto-policy's latest-user-message breakpoint so the cassette body matches.
-  cache: "none",
-  generation: { maxTokens: 16, temperature: 0 },
-})
-
-const recorded = recordedTests({
-  prefix: "bedrock-converse-cache",
-  provider: "amazon-bedrock",
-  protocol: "bedrock-converse",
-  requires: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
-  // Two identical requests in one cassette — match by recording order so the
-  // second call replays the cached-hit interaction.
-  options: { dispatch: "sequential" },
-})
-
-describe("Bedrock Converse cache recorded", () => {
-  recorded.effect.with("writes then reads cachePoint on identical second call", { tags: ["cache"] }, () =>
-    Effect.gen(function* () {
-      const first = yield* LLMClient.generate(cacheRequest)
-      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
-
-      const second = yield* LLMClient.generate(cacheRequest)
-      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
-    }),
-  )
-})

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

@@ -63,9 +63,6 @@ const baseRequest = LLM.request({
   model,
   system: "You are concise.",
   prompt: "Say hello.",
-  // Wire-shape assertions in this file predate the `cache: "auto"` default;
-  // pin the policy off so they only exercise the lowering path itself.
-  cache: "none",
   generation: { maxTokens: 64, temperature: 0 },
 })
 
@@ -128,7 +125,6 @@ describe("Bedrock Converse route", () => {
             LLM.assistant([LLM.toolCall({ id: "tool_1", name: "lookup", input: { query: "weather" } })]),
             LLM.toolMessage({ id: "tool_1", name: "lookup", result: { forecast: "sunny" } }),
           ],
-          cache: "none",
         }),
       )
 
@@ -343,7 +339,6 @@ describe("Bedrock Converse route", () => {
               { type: "media", mediaType: "image/webp", data: "DDDD" },
             ]),
           ],
-          cache: "none",
         }),
       )
 
@@ -445,78 +440,6 @@ describe("Bedrock Converse route", () => {
       expect(error.message).toContain("Bedrock Converse does not support media type application/x-tar")
     }),
   )
-
-  it.effect("maps ttlSeconds >= 3600 to cachePoint ttl: '1h'", () =>
-    Effect.gen(function* () {
-      const cache = new CacheHint({ type: "ephemeral", ttlSeconds: 3600 })
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          system: [{ type: "text", text: "system", cache }],
-          prompt: "hi",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        system: [{ text: "system" }, { cachePoint: { type: "default", ttl: "1h" } }],
-      })
-    }),
-  )
-
-  it.effect("appends cachePoint after marked tool definitions and tool-result blocks", () =>
-    Effect.gen(function* () {
-      const cache = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          tools: [{ name: "lookup", description: "lookup", inputSchema: { type: "object", properties: {} }, cache }],
-          messages: [
-            LLM.user("What's the weather?"),
-            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: {} })]),
-            LLM.toolMessage({ id: "call_1", name: "lookup", result: { temp: 72 }, cache }),
-          ],
-          cache: "none",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        toolConfig: {
-          tools: [{ toolSpec: { name: "lookup" } }, { cachePoint: { type: "default" } }],
-        },
-        messages: [
-          { role: "user", content: [{ text: "What's the weather?" }] },
-          { role: "assistant", content: [{ toolUse: { toolUseId: "call_1" } }] },
-          {
-            role: "user",
-            content: [{ toolResult: { toolUseId: "call_1" } }, { cachePoint: { type: "default" } }],
-          },
-        ],
-      })
-    }),
-  )
-
-  it.effect("drops cachePoint markers past the 4-per-request cap", () =>
-    Effect.gen(function* () {
-      const cache = new CacheHint({ type: "ephemeral" })
-      const prepared = yield* LLMClient.prepare(
-        LLM.request({
-          model,
-          system: [
-            { type: "text", text: "a", cache },
-            { type: "text", text: "b", cache },
-            { type: "text", text: "c", cache },
-            { type: "text", text: "d", cache },
-            { type: "text", text: "e", cache },
-            { type: "text", text: "f", cache },
-          ],
-          prompt: "hi",
-        }),
-      )
-
-      const system = (prepared.body as { system: Array<{ cachePoint?: unknown }> }).system
-      expect(system.filter((part) => "cachePoint" in part)).toHaveLength(4)
-    }),
-  )
 })
 
 // Live recorded integration tests. Run with `RECORD=true AWS_ACCESS_KEY_ID=...
@@ -561,7 +484,6 @@ describe("Bedrock Converse recorded", () => {
           model: recordedModel(),
           system: "Reply with the single word 'Hello'.",
           prompt: "Say hello.",
-          cache: "none",
           generation: { maxTokens: 16, temperature: 0 },
         }),
       )
@@ -584,7 +506,6 @@ describe("Bedrock Converse recorded", () => {
           prompt: "Call get_weather with city exactly Paris.",
           tools: [weatherTool],
           toolChoice: LLM.toolChoice(weatherTool),
-          cache: "none",
           generation: { maxTokens: 80, temperature: 0 },
         }),
       )

packages/llm/test/provider/gemini-cache.recorded.test.ts

@@ -1,50 +0,0 @@
-import { describe, expect } from "bun:test"
-import { Effect } from "effect"
-import { LLM } from "../../src"
-import { LLMClient } from "../../src/route"
-import * as Gemini from "../../src/protocols/gemini"
-import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
-import { recordedTests } from "../recorded-test"
-
-const model = Gemini.model({
-  id: "gemini-2.5-flash",
-  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY ?? process.env.GEMINI_API_KEY ?? "fixture",
-})
-
-// Gemini does implicit prefix caching on 2.5+ models above ~1024 tokens. The
-// `CacheHint` is currently a no-op for Gemini (the explicit `CachedContent`
-// API is out-of-band and intentionally not wired up). This test exists to
-// pin the usage-parsing path: `cachedContentTokenCount` should surface as
-// `cacheReadInputTokens` on the second identical call.
-const cacheRequest = LLM.request({
-  id: "recorded_gemini_cache",
-  model,
-  system: LARGE_CACHEABLE_SYSTEM,
-  prompt: "Say hi.",
-  generation: { maxTokens: 16, temperature: 0 },
-})
-
-const recorded = recordedTests({
-  prefix: "gemini-cache",
-  provider: "google",
-  protocol: "gemini",
-  requires: ["GOOGLE_GENERATIVE_AI_API_KEY"],
-  // Two identical requests in one cassette — match by recording order so the
-  // second call replays the cached-hit interaction.
-  options: { dispatch: "sequential" },
-})
-
-describe("Gemini cache recorded", () => {
-  recorded.effect.with("reports cachedContentTokenCount on identical second call", { tags: ["cache"] }, () =>
-    Effect.gen(function* () {
-      const first = yield* LLMClient.generate(cacheRequest)
-      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
-
-      const second = yield* LLMClient.generate(cacheRequest)
-      // Implicit caching is best-effort on Gemini's side; we assert the field
-      // is at least populated and non-negative. When re-recording, verify the
-      // cassette shows > 0 in the second response's usage.
-      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
-    }),
-  )
-})

packages/llm/test/provider/gemini.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMError, Usage } from "../../src"
+import { LLM, LLMError } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as Gemini from "../../src/protocols/gemini"
 import { it } from "../lib/effect"
@@ -198,36 +198,32 @@ describe("Gemini route", () => {
       expect(response.reasoning).toBe("thinking")
       expect(response.usage).toMatchObject({
         inputTokens: 5,
-        outputTokens: 3,
-        nonCachedInputTokens: 4,
-        cacheReadInputTokens: 1,
+        outputTokens: 2,
         reasoningTokens: 1,
+        cacheReadInputTokens: 1,
         totalTokens: 7,
       })
       expect(response.events).toEqual([
-        { type: "reasoning-delta", id: "reasoning-0", text: "thinking" },
-        { type: "text-delta", id: "text-0", text: "Hello" },
-        { type: "text-delta", id: "text-0", text: "!" },
+        { type: "reasoning-delta", text: "thinking" },
+        { type: "text-delta", text: "Hello" },
+        { type: "text-delta", text: "!" },
         {
           type: "request-finish",
           reason: "stop",
-          usage: new Usage({
+          usage: {
             inputTokens: 5,
-            outputTokens: 3,
-            nonCachedInputTokens: 4,
-            cacheReadInputTokens: 1,
+            outputTokens: 2,
             reasoningTokens: 1,
+            cacheReadInputTokens: 1,
             totalTokens: 7,
-            providerMetadata: {
-              google: {
-                promptTokenCount: 5,
-                candidatesTokenCount: 2,
-                totalTokenCount: 7,
-                thoughtsTokenCount: 1,
-                cachedContentTokenCount: 1,
-              },
+            native: {
+              promptTokenCount: 5,
+              candidatesTokenCount: 2,
+              totalTokenCount: 7,
+              thoughtsTokenCount: 1,
+              cachedContentTokenCount: 1,
             },
-          }),
+          },
         },
       ])
     }),
@@ -261,13 +257,12 @@ describe("Gemini route", () => {
         {
           type: "request-finish",
           reason: "tool-calls",
-          usage: new Usage({
+          usage: {
             inputTokens: 5,
             outputTokens: 1,
-            nonCachedInputTokens: 5,
             totalTokens: 6,
-            providerMetadata: { google: { promptTokenCount: 5, candidatesTokenCount: 1 } },
-          }),
+            native: { promptTokenCount: 5, candidatesTokenCount: 1 },
+          },
         },
       ])
     }),

packages/llm/test/provider/openai-chat.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { Effect, Schema, Stream } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
-import { LLM, LLMError, Usage } from "../../src"
+import { LLM, LLMError } from "../../src"
 import * as Azure from "../../src/providers/azure"
 import * as OpenAI from "../../src/providers/openai"
 import * as OpenAIChat from "../../src/protocols/openai-chat"
@@ -225,28 +225,25 @@ describe("OpenAI Chat route", () => {
 
       expect(response.text).toBe("Hello!")
       expect(response.events).toEqual([
-        { type: "text-delta", id: "text-0", text: "Hello" },
-        { type: "text-delta", id: "text-0", text: "!" },
+        { type: "text-delta", text: "Hello" },
+        { type: "text-delta", text: "!" },
         {
           type: "request-finish",
           reason: "stop",
-          usage: new Usage({
+          usage: {
             inputTokens: 5,
             outputTokens: 2,
-            nonCachedInputTokens: 4,
-            cacheReadInputTokens: 1,
             reasoningTokens: 0,
+            cacheReadInputTokens: 1,
             totalTokens: 7,
-            providerMetadata: {
-              openai: {
-                prompt_tokens: 5,
-                completion_tokens: 2,
-                total_tokens: 7,
-                prompt_tokens_details: { cached_tokens: 1 },
-                completion_tokens_details: { reasoning_tokens: 0 },
-              },
+            native: {
+              prompt_tokens: 5,
+              completion_tokens: 2,
+              total_tokens: 7,
+              prompt_tokens_details: { cached_tokens: 1 },
+              completion_tokens_details: { reasoning_tokens: 0 },
             },
-          }),
+          },
         },
       ])
     }),

packages/llm/test/provider/openai-responses-cache.recorded.test.ts

@@ -1,47 +0,0 @@
-import { describe, expect } from "bun:test"
-import { Effect } from "effect"
-import { LLM } from "../../src"
-import { LLMClient } from "../../src/route"
-import * as OpenAIResponses from "../../src/protocols/openai-responses"
-import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
-import { recordedTests } from "../recorded-test"
-
-const model = OpenAIResponses.model({
-  id: "gpt-4.1-mini",
-  apiKey: process.env.OPENAI_API_KEY ?? "fixture",
-})
-
-// OpenAI caches prefixes automatically once they cross the 1024-token threshold;
-// `CacheHint` is a no-op for the wire body. The stable signal is the
-// `prompt_cache_key` routing hint, which keeps repeated calls on the same shard
-// so cache hits are observable.
-const cacheRequest = LLM.request({
-  id: "recorded_openai_responses_cache",
-  model,
-  system: LARGE_CACHEABLE_SYSTEM,
-  prompt: "Say hi.",
-  generation: { maxTokens: 16, temperature: 0 },
-  providerOptions: { openai: { promptCacheKey: "recorded-cache-test" } },
-})
-
-const recorded = recordedTests({
-  prefix: "openai-responses-cache",
-  provider: "openai",
-  protocol: "openai-responses",
-  requires: ["OPENAI_API_KEY"],
-  // Two identical requests in one cassette — match by recording order so the
-  // second call replays the cached-hit interaction, not the cold-miss one.
-  options: { dispatch: "sequential" },
-})
-
-describe("OpenAI Responses cache recorded", () => {
-  recorded.effect.with("reports cached_tokens on identical second call", { tags: ["cache"] }, () =>
-    Effect.gen(function* () {
-      const first = yield* LLMClient.generate(cacheRequest)
-      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
-
-      const second = yield* LLMClient.generate(cacheRequest)
-      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
-    }),
-  )
-})

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

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { ConfigProvider, Effect, Layer, Stream } from "effect"
 import { Headers, HttpClientRequest } from "effect/unstable/http"
-import { LLM, LLMError, Usage } from "../../src"
+import { LLM, LLMError } from "../../src"
 import { Auth, LLMClient, RequestExecutor, WebSocketExecutor } from "../../src/route"
 import * as Azure from "../../src/providers/azure"
 import * as OpenAI from "../../src/providers/openai"
@@ -336,29 +336,26 @@ describe("OpenAI Responses route", () => {
 
       expect(response.text).toBe("Hello!")
       expect(response.events).toEqual([
-        { type: "text-delta", id: "msg_1", text: "Hello" },
-        { type: "text-delta", id: "msg_1", text: "!" },
+        { type: "text-delta", id: "msg_1", text: "Hello", providerMetadata: { openai: { itemId: "msg_1" } } },
+        { type: "text-delta", id: "msg_1", text: "!", providerMetadata: { openai: { itemId: "msg_1" } } },
         {
           type: "request-finish",
           reason: "stop",
           providerMetadata: { openai: { responseId: "resp_1", serviceTier: "default" } },
-          usage: new Usage({
+          usage: {
             inputTokens: 5,
             outputTokens: 2,
-            nonCachedInputTokens: 4,
-            cacheReadInputTokens: 1,
             reasoningTokens: 0,
+            cacheReadInputTokens: 1,
             totalTokens: 7,
-            providerMetadata: {
-              openai: {
-                input_tokens: 5,
-                output_tokens: 2,
-                total_tokens: 7,
-                input_tokens_details: { cached_tokens: 1 },
-                output_tokens_details: { reasoning_tokens: 0 },
-              },
+            native: {
+              input_tokens: 5,
+              output_tokens: 2,
+              total_tokens: 7,
+              input_tokens_details: { cached_tokens: 1 },
+              output_tokens_details: { reasoning_tokens: 0 },
             },
-          }),
+          },
         },
       ])
     }),
@@ -397,12 +394,14 @@ describe("OpenAI Responses route", () => {
           id: "call_1",
           name: "lookup",
           text: '{"query"',
+          providerMetadata: { openai: { itemId: "item_1" } },
         },
         {
           type: "tool-input-delta",
           id: "call_1",
           name: "lookup",
           text: ':"weather"}',
+          providerMetadata: { openai: { itemId: "item_1" } },
         },
         {
           type: "tool-call",
@@ -414,13 +413,7 @@ describe("OpenAI Responses route", () => {
         {
           type: "request-finish",
           reason: "tool-calls",
-          usage: new Usage({
-            inputTokens: 5,
-            outputTokens: 1,
-            nonCachedInputTokens: 5,
-            totalTokens: 6,
-            providerMetadata: { openai: { input_tokens: 5, output_tokens: 1 } },
-          }),
+          usage: { inputTokens: 5, outputTokens: 1, totalTokens: 6, native: { input_tokens: 5, output_tokens: 1 } },
         },
       ])
     }),

packages/llm/test/recorded-scenarios.ts

@@ -6,18 +6,6 @@ import { tool } from "../src/tool"
 
 export const weatherToolName = "get_weather"
 
-// A deterministic system prompt long enough to clear every supported provider's
-// minimum cacheable-prefix threshold (Anthropic Haiku 3.5: 2048 tokens; Anthropic
-// Opus/Haiku 4.5: 4096 tokens; OpenAI/Gemini/Bedrock: lower). Built by repeating
-// a fixed sentence — the cassette replays bit-for-bit, so the exact text matters
-// only when re-recording with `RECORD=true`.
-export const LARGE_CACHEABLE_SYSTEM = (() => {
-  const sentence = "You are a concise, factual assistant. Answer precisely and avoid filler. Cite numbers when known. "
-  // ~100 chars per sentence × 250 repeats ≈ 25,000 chars ≈ 5k+ tokens, safely
-  // above every provider's threshold.
-  return sentence.repeat(250)
-})()
-
 export const weatherTool = LLM.toolDefinition({
   name: weatherToolName,
   description: "Get current weather for a city.",
@@ -51,7 +39,6 @@ export const textRequest = (input: {
     model: input.model,
     system: "You are concise.",
     prompt: input.prompt ?? "Reply with exactly: Hello!",
-    cache: "none",
     generation:
       input.temperature === false
         ? { maxTokens: input.maxTokens ?? 20 }
@@ -71,7 +58,6 @@ export const weatherToolRequest = (input: {
     prompt: "Call get_weather with city exactly Paris.",
     tools: [weatherTool],
     toolChoice: LLM.toolChoice(weatherTool),
-    cache: "none",
     generation:
       input.temperature === false
         ? { maxTokens: input.maxTokens ?? 80 }
@@ -90,7 +76,6 @@ export const weatherToolLoopRequest = (input: {
     model: input.model,
     system: input.system ?? "Use the get_weather tool, then answer in one short sentence.",
     prompt: "What is the weather in Paris?",
-    cache: "none",
     generation:
       input.temperature === false
         ? { maxTokens: input.maxTokens ?? 80 }

packages/llm/test/recorded-test.ts

@@ -53,7 +53,7 @@ export const recordedTests = (options: RecordedTestsOptions) =>
         ...metadata,
       }
       const mode = recorderOptions?.mode ?? (recording ? "record" : "replay")
-      const cassetteService = HttpRecorder.Cassette.fileSystem({ directory: FIXTURES_DIR }).pipe(
+      const cassetteService = HttpRecorder.Cassette.layer({ directory: FIXTURES_DIR }).pipe(
         Layer.provide(NodeFileSystem.layer),
       )
       const requestExecutor = RequestExecutor.layer.pipe(

packages/llm/test/recorded-websocket.ts

@@ -1,13 +1,14 @@
-import { Cassette, makeWebSocketExecutor, type RecordReplayMode } from "@opencode-ai/http-recorder"
+import { Cassette, makeWebSocketExecutor } from "@opencode-ai/http-recorder"
 import { Effect, Layer } from "effect"
 import { WebSocketExecutor } from "../src/route"
 import type { Service as WebSocketExecutorService } from "../src/route/transport/websocket"
 
 const liveWebSocket = WebSocketExecutor.open
+type Mode = "record" | "replay" | "passthrough"
 
 export const webSocketCassetteLayer = (
   cassette: string,
-  input: { readonly metadata?: Record<string, unknown>; readonly mode: RecordReplayMode },
+  input: { readonly metadata?: Record<string, unknown>; readonly mode: Mode },
 ): Layer.Layer<WebSocketExecutorService, never, Cassette.Service> =>
   Layer.effect(
     WebSocketExecutor.Service,

packages/llm/test/schema.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { Schema } from "effect"
-import { ContentPart, LLMEvent, LLMRequest, ModelID, ModelLimits, ModelRef, ProviderID, Usage } from "../src/schema"
-import { ProviderShared } from "../src/protocols/shared"
+import { ContentPart, LLMEvent, LLMRequest, ModelID, ModelLimits, ModelRef, ProviderID } from "../src/schema"
 
 const model = new ModelRef({
   id: ModelID.make("fake-model"),
@@ -49,30 +48,3 @@ describe("llm schema", () => {
     expect(ContentPart.guards.media({ type: "text", text: "hi" })).toBe(false)
   })
 })
-
-describe("LLM.Usage", () => {
-  test("subtractTokens clamps non-sensical breakdowns to zero", () => {
-    // Defense against a provider reporting cached_tokens > prompt_tokens or
-    // reasoning_tokens > completion_tokens — the negative would otherwise
-    // round-trip through the pipeline and crash strict downstream schemas.
-    expect(ProviderShared.subtractTokens(5, 3)).toBe(2)
-    expect(ProviderShared.subtractTokens(5, 10)).toBe(0)
-    expect(ProviderShared.subtractTokens(5, undefined)).toBe(5)
-    expect(ProviderShared.subtractTokens(undefined, 3)).toBeUndefined()
-    expect(ProviderShared.subtractTokens(undefined, undefined)).toBeUndefined()
-  })
-
-  test("sumTokens returns undefined only when every input is undefined", () => {
-    expect(ProviderShared.sumTokens(1, 2, 3)).toBe(6)
-    expect(ProviderShared.sumTokens(1, undefined, 3)).toBe(4)
-    expect(ProviderShared.sumTokens(undefined, undefined, undefined)).toBeUndefined()
-    expect(ProviderShared.sumTokens()).toBeUndefined()
-  })
-
-  test("visibleOutputTokens clamps reasoning > output to zero", () => {
-    expect(new Usage({ outputTokens: 10, reasoningTokens: 4 }).visibleOutputTokens).toBe(6)
-    expect(new Usage({ outputTokens: 10 }).visibleOutputTokens).toBe(10)
-    expect(new Usage({ outputTokens: 4, reasoningTokens: 10 }).visibleOutputTokens).toBe(0)
-    expect(new Usage({}).visibleOutputTokens).toBe(0)
-  })
-})

packages/opencode/AGENTS.md

@@ -9,13 +9,6 @@
 - **Output**: creates `migration/<timestamp>_<slug>/migration.sql` and `snapshot.json`.
 - **Tests**: migration tests should read the per-folder layout (no `_journal.json`).
 
-## Development server
-
-- Running `bun dev` from `packages/opencode` starts the live interactive TUI. Do not run it as a blocking foreground command when you need to inspect the result.
-- Start it in `tmux` instead: `tmux new-session -d -s opencode-dev 'bun dev'`.
-- Capture the current TUI output with: `tmux capture-pane -pt opencode-dev`.
-- Stop the session explicitly when done: `tmux kill-session -t opencode-dev`.
-
 # Module shape
 
 Do not use `export namespace Foo { ... }` for module organization. It is not

packages/opencode/CONTEXT.md

@@ -1,45 +0,0 @@
-# opencode
-
-The runtime that powers the opencode CLI/TUI: it manages projects on disk, runs
-agent sessions against LLM providers, and exposes a control plane so other
-clients (web, IDE, remote workspaces) can connect to the same state.
-
-## Language
-
-### Location & runtime
-
-**Project**:
-The persisted, VCS-rooted thing the user owns — one row per repo (or per non-VCS directory).
-_Avoid_: repo, codebase, folder
-
-**Worktree**:
-A git worktree of a **Project** — a branch checkout sitting at a directory on disk.
-_Avoid_: branch dir, checkout, workspace
-
-**Workspace**:
-A control-plane connection target for a **Project**, identified by a `wrk_…` ID. Local or remote. Describes _how_ a client is connected to a Project, not where the Project lives on disk.
-_Avoid_: worktree, session, project (the connection is not the project itself)
-
-**Instance**:
-The runtime `(project, worktree, directory)` ALS context the opencode process is currently operating inside. Not persisted; not user-visible.
-_Avoid_: session, context, runtime
-
-**Directory**:
-A filesystem path string. The Instance always has one as its current working directory.
-_Avoid_: folder, cwd (in domain prose; fine in code)
-
-## Relationships
-
-- A **Project** has zero or more **Worktrees**.
-- A **Worktree** belongs to exactly one **Project**.
-- A **Workspace** points at exactly one **Project** (and optionally a specific branch/directory inside it).
-- An **Instance** is bound to one **Project**, one **Worktree**, and one **Directory** for the life of an async context.
-
-## Example dialogue
-
-> **Dev:** "When the user opens a remote target, do we create a new **Worktree**?"
-> **Maintainer:** "No — a remote target is a **Workspace** pointing at a **Project** on the other side. The remote host already has its own **Worktrees**; we just connect to one."
-
-## Flagged ambiguities
-
-- "workspace" was used in `src/project/project.ts` to mean **Worktree** ("Startup script to run when creating a new workspace (worktree)") — resolved: these are distinct. The start command runs when creating a **Worktree**, not a **Workspace**.

packages/opencode/migration/20260511000411_data_migration_state/migration.sql

@@ -1,4 +0,0 @@
-CREATE TABLE `data_migration` (
-	`name` text PRIMARY KEY,
-	`time_completed` integer NOT NULL
-);

packages/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.14.48",
+  "version": "1.14.46",
   "name": "opencode",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,8 @@
     "build": "bun run script/build.ts",
     "fix-node-pty": "bun run script/fix-node-pty.ts",
     "dev": "bun run --conditions=browser ./src/index.ts",
+    "dev:demo": "bun run --conditions=browser ./src/index.ts --demo",
+    "dev:run-demo": "bun run --conditions=browser ./src/index.ts run --interactive --demo",
     "dev:temporary": "bun run --conditions=browser ./src/temporary.ts",
     "db": "bun drizzle-kit"
   },

packages/opencode/src/agent/agent.ts

@@ -26,6 +26,7 @@ import * as Option from "effect/Option"
 import * as OtelTracer from "@effect/opentelemetry/Tracer"
 import { zod } from "@opencode-ai/core/effect-zod"
 import { withStatics, type DeepMutable } from "@opencode-ai/core/schema"
+import { Reference } from "@/reference/reference"
 
 export const Info = Schema.Struct({
   name: Schema.String,
@@ -300,6 +301,76 @@ export const layer = Layer.effect(
           item.permission = Permission.merge(item.permission, Permission.fromConfig(value.permission ?? {}))
         }
 
+        function referencePrompt(reference: Reference.Resolved) {
+          if (reference.kind === "local") {
+            return [
+              `You are configured reference @${reference.name}, a read-only research agent for external reference material.`,
+              `Local directory: ${reference.path}`,
+              `Inspect this directory as the primary reference source. Prefer repo_overview with path ${JSON.stringify(reference.path)} before broader searches. Do not edit files.`,
+              `Return exact absolute file paths for findings whenever possible.`,
+            ].join("\n\n")
+          }
+
+          if (reference.kind === "invalid") {
+            return [
+              `You are configured reference @${reference.name}, but this reference is not usable yet.`,
+              `Configured repository: ${reference.repository}`,
+              `Problem: ${reference.message}`,
+              `Explain this configuration problem if invoked. Do not edit files or attempt fallback clones.`,
+            ].join("\n\n")
+          }
+
+          return [
+            `You are configured reference @${reference.name}, a read-only research agent for external reference material.`,
+            `Repository: ${reference.repository}`,
+            ...(reference.branch ? [`Branch/ref: ${reference.branch}`] : []),
+            `Cached directory: ${reference.path}`,
+            `OpenCode materializes this configured repository before use. Do not call repo_clone for this reference.`,
+            `Inspect the cached directory as the primary reference source. Prefer repo_overview with path ${JSON.stringify(reference.path)} before broader searches, then use Glob, Grep, and Read inside that directory. Do not edit files.`,
+            `Return exact absolute file paths for findings whenever possible.`,
+          ].join("\n\n")
+        }
+
+        function referenceDescription(reference: Reference.Resolved) {
+          if (reference.kind === "local") return `Scout reference for local directory ${reference.path}`
+          if (reference.kind === "git") return `Scout reference for repository ${reference.repository}`
+          return `Invalid Scout reference for repository ${reference.repository}`
+        }
+
+        if (Flag.OPENCODE_EXPERIMENTAL_SCOUT) {
+          const resolvedReferences = Reference.resolveAll({
+            references: cfg.reference ?? {},
+            directory: ctx.directory,
+            worktree: ctx.worktree,
+          })
+          for (const resolved of resolvedReferences) {
+            if (agents[resolved.name]) continue
+            const localPath = resolved.kind === "invalid" ? undefined : resolved.path
+            agents[resolved.name] = {
+              name: resolved.name,
+              description: referenceDescription(resolved),
+              permission: Permission.merge(
+                agents.scout.permission,
+                Permission.fromConfig({
+                  repo_clone: "deny",
+                  ...(localPath
+                    ? {
+                        external_directory: {
+                          [localPath]: "allow",
+                          [path.join(localPath, "*")]: "allow",
+                        },
+                      }
+                    : {}),
+                }),
+              ),
+              prompt: referencePrompt(resolved),
+              options: { reference: cfg.reference?.[resolved.name], resolved },
+              mode: "subagent",
+              native: false,
+            }
+          }
+        }
+
         // Ensure Truncate.GLOB is allowed unless explicitly configured
         for (const name in agents) {
           const agent = agents[name]

packages/opencode/src/cli/cmd/demo-fixtures.ts

@@ -0,0 +1,181 @@
+export const SAMPLE_MARKDOWN = [
+  "# Direct Mode Demo",
+  "",
+  "This is a realistic assistant response for direct-mode formatting checks.",
+  "It mixes **bold**, _italic_, `inline code`, links, code fences, and tables in one streamed reply.",
+  "",
+  "## Summary",
+  "",
+  "- Restored the final markdown flush so the last block is committed on idle.",
+  "- Switched markdown scrollback commits back to top-level block boundaries.",
+  "- Added footer-level regression coverage for split-footer rendering.",
+  "",
+  "## Status",
+  "",
+  "| Area | Before | After | Notes |",
+  "| --- | --- | --- | --- |",
+  "| Direct mode | Missing final rows | Stable | Final markdown block now flushes on idle |",
+  "| Tables | Dropped in streaming mode | Visible | Block-based commits match the working OpenTUI demo |",
+  "| Tests | Partial coverage | Broader coverage | Includes a footer-level split render capture |",
+  "",
+  "> This sample intentionally includes a wide table so you can spot wrapping and commit bugs quickly.",
+  "",
+  "```ts",
+  "const result = { markdown: true, tables: 2, stable: true }",
+  "```",
+  "",
+  "## Files",
+  "",
+  "| File | Change |",
+  "| --- | --- |",
+  "| `scrollback.surface.ts` | Align markdown commit logic with the split-footer demo |",
+  "| `footer.ts` | Keep active surfaces across footer-height-only resizes |",
+  "| `footer.test.ts` | Capture real split-footer markdown payloads during idle completion |",
+  "",
+  "Next step: run `/fmt table` if you want a tighter table-only sample.",
+].join("\n")
+
+export const SAMPLE_TABLE = [
+  "# Table Sample",
+  "",
+  "| Kind | Example | Notes |",
+  "| --- | --- | --- |",
+  "| Pipe | `A\\|B` | Escaped pipes should stay in one cell |",
+  "| Unicode | `漢字` | Wide characters should remain aligned |",
+  "| Wrap | `LongTokenWithoutNaturalBreaks_1234567890` | Useful for width stress |",
+  "| Status | done | Final row should still appear after idle |",
+].join("\n")
+
+export const MARKDOWN_PATTERNS = {
+  "md-code": [
+    "# Interleaved Code",
+    "",
+    "Start with a short conclusion before any code appears.",
+    "",
+    "```ts",
+    "export function parse(input: string) {",
+    "  return input.trim().split(/\\s+/)",
+    "}",
+    "```",
+    "",
+    "Then continue with prose immediately after the code block. This should not inherit code styling or indentation.",
+    "",
+    "```tsx",
+    "<Show when={props.enabled}>",
+    "  <markdown content={props.text} streaming />",
+    "</Show>",
+    "```",
+    "",
+    "Final paragraph after a second fence with `inline code`, **bold text**, and _emphasis_ mixed together.",
+  ].join("\n"),
+  "md-fence": [
+    "# Fence Boundaries",
+    "",
+    "The renderer should recover cleanly around multiple fences and nearby paragraphs.",
+    "",
+    "```bash",
+    "bun run test -- --grep markdown",
+    "```",
+    "Text directly after a fence.",
+    "```json",
+    "{",
+    '  "status": "ok",',
+    '  "items": ["one", "two"]',
+    "}",
+    "```",
+    "Trailing paragraph after JSON. The next fence intentionally has no language.",
+    "```",
+    "plain fenced text",
+    "with multiple lines",
+    "```",
+  ].join("\n"),
+  "md-list": [
+    "# Lists With Code",
+    "",
+    "1. First ordered item with `inline code`.",
+    "2. Second ordered item before a nested list:",
+    "   - Nested bullet with a long phrase that should wrap without swallowing the marker or changing indentation.",
+    "   - Nested bullet before fenced code:",
+    "",
+    "     ```ts",
+    "     const nested = true",
+    "     ```",
+    "",
+    "3. Third ordered item after the nested fence.",
+    "",
+    "- Top-level bullet after ordered list.",
+    "- Another bullet with a paragraph below.",
+    "",
+    "  Continuation paragraph should stay associated with the bullet without becoming code.",
+  ].join("\n"),
+  "md-table-code": [
+    "# Tables And Code",
+    "",
+    "| Case | Input | Expected |",
+    "| --- | --- | --- |",
+    "| Inline code | `const x = 1` | stays inline |",
+    "| Escaped pipe | `A\\|B` | one cell |",
+    "| Long token | `LongTokenWithoutNaturalBreaks_1234567890_abcdefghijklmnopqrstuvwxyz` | wraps or scrolls predictably |",
+    "",
+    "A code block follows the table:",
+    "",
+    "```ts",
+    "const rows = [",
+    '  { case: "inline code", expected: "stays inline" },',
+    '  { case: "escaped pipe", expected: "one cell" },',
+    "]",
+    "```",
+    "",
+    "And then another compact table:",
+    "",
+    "| A | B |",
+    "| - | - |",
+    "| done | yes |",
+  ].join("\n"),
+  "md-inline": [
+    "# Inline Markdown",
+    "",
+    "This paragraph mixes [a normal link](https://opencode.ai), `https://example.com/code-link`, `inline code`, **strong**, _emphasis_, and ~~strikethrough~~.",
+    "",
+    "> Blockquote with `inline code` and [a link](https://example.com) should keep quote styling while wrapping.",
+    "",
+    "A horizontal rule follows.",
+    "",
+    "---",
+    "",
+    "After the rule, text should resume normal spacing.",
+  ].join("\n"),
+  "md-kitchen": [
+    "# Markdown Kitchen Sink",
+    "",
+    "This combines headings, paragraphs, lists, blockquotes, tables, inline code, and multiple code fences.",
+    "",
+    "## Steps",
+    "",
+    "1. Read the response.",
+    "2. Notice `inline code` before a block.",
+    "",
+    "```ts",
+    "type Result = { ok: boolean; reason?: string }",
+    "const result: Result = { ok: true }",
+    "```",
+    "",
+    "3. Continue the list after the block.",
+    "",
+    "> Quoted note after the list. It should not merge into the previous item.",
+    "",
+    "| Feature | Stress |",
+    "| --- | --- |",
+    "| Markdown | prose/code/table interleave |",
+    "| Renderer | wrapping and spacing |",
+    "",
+    "```diff",
+    "- const renderer = oldMarkdown",
+    "+ const renderer = experimentalMarkdown",
+    "```",
+    "",
+    "Final paragraph with [docs](https://opencode.ai/docs) and `https://example.com/from-code`.",
+  ].join("\n"),
+} as const
+
+export const MARKDOWN_PATTERN_KINDS = Object.keys(MARKDOWN_PATTERNS) as Array<keyof typeof MARKDOWN_PATTERNS>

packages/opencode/src/cli/cmd/run/demo.ts

@@ -19,9 +19,11 @@ import type { Event, ToolPart } from "@opencode-ai/sdk/v2"
 import { createSessionData, reduceSessionData, type SessionData } from "./session-data"
 import { writeSessionOutput } from "./stream"
 import type { FooterApi, PermissionReply, QuestionReject, QuestionReply, RunPrompt, StreamCommit } from "./types"
+import { MARKDOWN_PATTERN_KINDS, MARKDOWN_PATTERNS, SAMPLE_MARKDOWN, SAMPLE_TABLE } from "../demo-fixtures"
 
 const KINDS = [
   "markdown",
+  ...MARKDOWN_PATTERN_KINDS,
   "table",
   "text",
   "reasoning",
@@ -51,53 +53,9 @@ function questionKind(value: string | undefined): QuestionKind | undefined {
   return QUESTIONS.find((item) => item === next)
 }
 
-const SAMPLE_MARKDOWN = [
-  "# Direct Mode Demo",
-  "",
-  "This is a realistic assistant response for direct-mode formatting checks.",
-  "It mixes **bold**, _italic_, `inline code`, links, code fences, and tables in one streamed reply.",
-  "",
-  "## Summary",
-  "",
-  "- Restored the final markdown flush so the last block is committed on idle.",
-  "- Switched markdown scrollback commits back to top-level block boundaries.",
-  "- Added footer-level regression coverage for split-footer rendering.",
-  "",
-  "## Status",
-  "",
-  "| Area | Before | After | Notes |",
-  "| --- | --- | --- | --- |",
-  "| Direct mode | Missing final rows | Stable | Final markdown block now flushes on idle |",
-  "| Tables | Dropped in streaming mode | Visible | Block-based commits match the working OpenTUI demo |",
-  "| Tests | Partial coverage | Broader coverage | Includes a footer-level split render capture |",
-  "",
-  "> This sample intentionally includes a wide table so you can spot wrapping and commit bugs quickly.",
-  "",
-  "```ts",
-  "const result = { markdown: true, tables: 2, stable: true }",
-  "```",
-  "",
-  "## Files",
-  "",
-  "| File | Change |",
-  "| --- | --- |",
-  "| `scrollback.surface.ts` | Align markdown commit logic with the split-footer demo |",
-  "| `footer.ts` | Keep active surfaces across footer-height-only resizes |",
-  "| `footer.test.ts` | Capture real split-footer markdown payloads during idle completion |",
-  "",
-  "Next step: run `/fmt table` if you want a tighter table-only sample.",
-].join("\n")
-
-const SAMPLE_TABLE = [
-  "# Table Sample",
-  "",
-  "| Kind | Example | Notes |",
-  "| --- | --- | --- |",
-  "| Pipe | `A\\|B` | Escaped pipes should stay in one cell |",
-  "| Unicode | `漢字` | Wide characters should remain aligned |",
-  "| Wrap | `LongTokenWithoutNaturalBreaks_1234567890` | Useful for width stress |",
-  "| Status | done | Final row should still appear after idle |",
-].join("\n")
+function markdownPattern(value: string): keyof typeof MARKDOWN_PATTERNS | undefined {
+  if (value in MARKDOWN_PATTERNS) return value as keyof typeof MARKDOWN_PATTERNS
+}
 
 type Ref = {
   msg: string
@@ -1031,6 +989,12 @@ async function emitFmt(state: State, kind: string, body: string, signal?: AbortS
     return true
   }
 
+  const pattern = markdownPattern(kind)
+  if (pattern) {
+    await emitText(state, body || MARKDOWN_PATTERNS[pattern], signal)
+    return true
+  }
+
   if (kind === "table") {
     await emitText(state, body || SAMPLE_TABLE, signal)
     return true

packages/opencode/src/cli/cmd/run/runtime.ts

@@ -14,7 +14,7 @@
 //   4. runs the prompt queue until the footer closes.
 import { createOpencodeClient } from "@opencode-ai/sdk/v2"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { createRunDemo } from "./demo"
+import type { createRunDemo } from "./demo"
 import { resolveDiffStyle, resolveFooterKeybinds, resolveModelInfo, resolveSessionInfo } from "./runtime.boot"
 import { createRuntimeLifecycle } from "./runtime.lifecycle"
 import { recordRunSpanError, setRunSpanAttributes, withRunSpan } from "./otel"
@@ -135,6 +135,10 @@ function variantsFor(providers: RunProvider[], model: RunInput["model"]) {
   return Object.keys(providers.find((item) => item.id === model.providerID)?.models?.[model.modelID]?.variants ?? {})
 }
 
+async function createDemo(input: Parameters<typeof createRunDemo>[0]) {
+  return (await import("./demo")).createRunDemo(input)
+}
+
 async function resolveExitTitle(
   ctx: BootContext,
   input: RunRuntimeInput,
@@ -425,7 +429,7 @@ async function runInteractiveRuntime(input: RunRuntimeInput): Promise<void> {
 
       if (input.demo) {
         await ensureSession()
-        state.demo = createRunDemo({
+        state.demo = await createDemo({
           footer,
           sessionID: state.sessionID,
           thinking: input.thinking,
@@ -548,7 +552,7 @@ async function runInteractiveRuntime(input: RunRuntimeInput): Promise<void> {
                   state.history = []
                   includeFiles = true
                   state.demo = input.demo
-                    ? createRunDemo({
+                    ? await createDemo({
                         footer,
                         sessionID: state.sessionID,
                         thinking: input.thinking,

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -93,6 +93,7 @@ const appBindingCommands = [
   "theme.mode.lock",
   "help.show",
   "docs.open",
+  "app.exit",
   "app.debug",
   "app.console",
   "app.heap_snapshot",
@@ -647,6 +648,11 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
         title: "Exit the app",
         slashName: "exit",
         slashAliases: ["quit", "q"],
+        enabled: () => {
+          const current = promptRef.current
+          if (!current?.focused) return true
+          return current.current.input === ""
+        },
         run: () => exit(),
         category: "System",
       },
@@ -779,17 +785,6 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
     bindings: tuiConfig.keybinds.gather("app", appBindingCommands),
   }))
 
-  useBindings(() => ({
-    enabled: () => {
-      const ok = command.matcher.get()
-      if (!ok) return false
-      const current = promptRef.current
-      if (!current?.focused) return true
-      return current.current.input === ""
-    },
-    bindings: tuiConfig.keybinds.gather("app_exit", ["app.exit"]),
-  }))
-
   event.on(TuiEvent.CommandExecute.type, (evt) => {
     command.run(evt.properties.command)
   })

packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx

@@ -712,6 +712,7 @@ export function Prompt(props: PromptProps) {
       ...input.traits,
       ...computePromptTraits({
         mode: store.mode,
+        disabled: !!props.disabled,
         autocompleteVisible: !!auto()?.visible,
       }),
     }
@@ -926,7 +927,13 @@ export function Prompt(props: PromptProps) {
       target: inputTarget,
       enabled: (() => {
         cursorVersion()
-        return inputTarget() !== undefined && !props.disabled && !auto()?.visible && input !== undefined
+        return (
+          inputTarget() !== undefined &&
+          !props.disabled &&
+          !auto()?.visible &&
+          input !== undefined &&
+          (input.cursorOffset === 0 || input.visualCursor.visualRow === 0)
+        )
       })(),
       commands: [
         {
@@ -935,12 +942,12 @@ export function Prompt(props: PromptProps) {
           category: "Prompt",
           run() {
             if (input.cursorOffset !== 0) {
-              if (input.scrollY + input.visualCursor.visualRow === 0) input.cursorOffset = 0
-              return false
+              input.cursorOffset = 0
+              return
             }
 
             const item = history.move(-1, input.plainText)
-            if (!item) return false
+            if (!item) return
             input.setText(item.input)
             setStore("prompt", item)
             setStore("mode", item.mode ?? "normal")
@@ -958,7 +965,13 @@ export function Prompt(props: PromptProps) {
       target: inputTarget,
       enabled: (() => {
         cursorVersion()
-        return inputTarget() !== undefined && !props.disabled && !auto()?.visible && input !== undefined
+        return (
+          inputTarget() !== undefined &&
+          !props.disabled &&
+          !auto()?.visible &&
+          input !== undefined &&
+          (input.cursorOffset === input.plainText.length || input.visualCursor.visualRow === input.height - 1)
+        )
       })(),
       commands: [
         {
@@ -967,16 +980,12 @@ export function Prompt(props: PromptProps) {
           category: "Prompt",
           run() {
             if (input.cursorOffset !== input.plainText.length) {
-              if (
-                input.scrollY + input.visualCursor.visualRow ===
-                Math.max(0, input.editorView.getTotalVirtualLineCount() - 1)
-              )
-                input.cursorOffset = input.plainText.length
-              return false
+              input.cursorOffset = input.plainText.length
+              return
             }
 
             const item = history.move(1, input.plainText)
-            if (!item) return false
+            if (!item) return
             input.setText(item.input)
             setStore("prompt", item)
             setStore("mode", item.mode ?? "normal")

packages/opencode/src/cli/cmd/tui/component/prompt/traits.ts

@@ -4,6 +4,7 @@ export type PromptMode = "normal" | "shell"
 
 export interface PromptTraitsInput {
   mode: PromptMode
+  disabled: boolean
   autocompleteVisible: boolean
 }
 
@@ -15,9 +16,10 @@ export type PromptTraits = EditorTraits & {
 /**
  * Compute the textarea editor traits for the prompt.
  *
- * The OpenTUI managed textarea keymap owns `traits.suspend`. Prompt traits
- * only expose capture/status metadata so focus changes cannot unsuspend the
- * keymap-managed editor mappings.
+ * `traits.suspend` gates the textarea's keybinding actions (backspace,
+ * delete-word, arrow movement, undo/redo, etc.). Shell mode is an active
+ * editing mode — only `disabled` should suspend the textarea, otherwise
+ * users can type in shell mode but cannot delete or move the cursor.
  */
 export function computePromptTraits(input: PromptTraitsInput): PromptTraits {
   const capture =
@@ -28,6 +30,7 @@ export function computePromptTraits(input: PromptTraitsInput): PromptTraits {
       : undefined
   return {
     capture,
+    suspend: input.disabled,
     status: input.mode === "shell" ? "SHELL" : undefined,
     owner: "opencode",
     role: "prompt",

packages/opencode/src/cli/cmd/tui/context/theme.tsx

@@ -962,6 +962,8 @@ function getSyntaxRules(theme: Theme) {
       style: {
         foreground: theme.markdownHeading,
         bold: true,
+        italic: true,
+        underline: true,
       },
     },
     {
@@ -1175,6 +1177,7 @@ function getSyntaxRules(theme: Theme) {
       scope: ["markup.strikethrough"],
       style: {
         foreground: theme.textMuted,
+        strikethrough: true,
       },
     },
     {

packages/opencode/src/cli/cmd/tui/demo.ts

@@ -0,0 +1,285 @@
+import type {
+  Agent,
+  AssistantMessage,
+  Config,
+  Message,
+  Model,
+  Part,
+  Path,
+  Project,
+  Provider,
+  Session,
+} from "@opencode-ai/sdk/v2"
+import type { EventSource } from "./context/sdk"
+import { MARKDOWN_PATTERNS, SAMPLE_MARKDOWN, SAMPLE_TABLE } from "../demo-fixtures"
+
+const sessionID = "demo_tui_markdown"
+const userMessageID = "demo_tui_user"
+const assistantMessageID = "demo_tui_assistant"
+const now = Date.now()
+
+const markdown = [
+  "# Fullscreen TUI Markdown Demo",
+  "",
+  "This fake assistant response runs through the fullscreen session timeline without calling an LLM.",
+  "Use it to compare spacing, wrapping, code fence boundaries, table behavior, and inline markdown rendering.",
+  "",
+  "## Baseline",
+  "",
+  SAMPLE_MARKDOWN,
+  "",
+  "## Table Baseline",
+  "",
+  SAMPLE_TABLE,
+  "",
+  ...Object.entries(MARKDOWN_PATTERNS).flatMap(([name, value]) => ["## " + name, "", value, ""]),
+].join("\n")
+
+const model = {
+  id: "demo",
+  providerID: "demo",
+  api: {
+    id: "demo",
+    url: "https://example.com/demo",
+    npm: "demo",
+  },
+  name: "Demo",
+  capabilities: {
+    temperature: false,
+    reasoning: true,
+    attachment: false,
+    toolcall: true,
+    input: {
+      text: true,
+      audio: false,
+      image: false,
+      video: false,
+      pdf: false,
+    },
+    output: {
+      text: true,
+      audio: false,
+      image: false,
+      video: false,
+      pdf: false,
+    },
+    interleaved: true,
+  },
+  cost: {
+    input: 0,
+    output: 0,
+    cache: {
+      read: 0,
+      write: 0,
+    },
+  },
+  limit: {
+    context: 128_000,
+    output: 16_000,
+  },
+  status: "active",
+  options: {},
+  headers: {},
+  release_date: "2026-01-01",
+} satisfies Model
+
+const provider = {
+  id: "demo",
+  name: "Demo",
+  source: "custom",
+  env: [],
+  options: {},
+  models: {
+    demo: model,
+  },
+} satisfies Provider
+
+const agent = {
+  name: "build",
+  description: "Demo agent",
+  mode: "primary",
+  native: true,
+  permission: [],
+  model: {
+    providerID: "demo",
+    modelID: "demo",
+  },
+  options: {},
+} satisfies Agent
+
+function json(data: unknown, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      "content-type": "application/json",
+    },
+  })
+}
+
+export function createTuiDemo(input: { directory: string }) {
+  const paths = {
+    home: process.env.HOME ?? input.directory,
+    state: input.directory,
+    config: input.directory,
+    worktree: input.directory,
+    directory: input.directory,
+  } satisfies Path
+
+  const project = {
+    id: "demo_project",
+    worktree: input.directory,
+    vcs: "git",
+    name: "Markdown Demo",
+    time: {
+      created: now,
+      updated: now,
+    },
+    sandboxes: [],
+  } satisfies Project
+
+  const session = {
+    id: sessionID,
+    slug: "markdown-demo",
+    projectID: project.id,
+    directory: input.directory,
+    title: "Markdown Rendering Demo",
+    agent: agent.name,
+    model: {
+      id: model.id,
+      providerID: provider.id,
+    },
+    version: "demo",
+    time: {
+      created: now,
+      updated: now + 2,
+    },
+  } satisfies Session
+
+  const user = {
+    id: userMessageID,
+    sessionID,
+    role: "user",
+    time: {
+      created: now,
+    },
+    agent: agent.name,
+    model: {
+      providerID: provider.id,
+      modelID: model.id,
+    },
+  } satisfies Message
+
+  const assistant = {
+    id: assistantMessageID,
+    sessionID,
+    role: "assistant",
+    time: {
+      created: now + 1,
+      completed: now + 2,
+    },
+    parentID: userMessageID,
+    modelID: model.id,
+    providerID: provider.id,
+    mode: "demo",
+    agent: agent.name,
+    path: {
+      cwd: input.directory,
+      root: input.directory,
+    },
+    cost: 0,
+    tokens: {
+      input: 120,
+      output: 3_200,
+      reasoning: 0,
+      cache: {
+        read: 0,
+        write: 0,
+      },
+    },
+  } satisfies AssistantMessage
+
+  const messages = [
+    {
+      info: user,
+      parts: [
+        {
+          id: "demo_tui_user_text",
+          sessionID,
+          messageID: userMessageID,
+          type: "text",
+          text: "Show me the fullscreen TUI markdown rendering stress cases.",
+          time: {
+            start: now,
+            end: now,
+          },
+        },
+      ],
+    },
+    {
+      info: assistant,
+      parts: [
+        {
+          id: "demo_tui_assistant_text",
+          sessionID,
+          messageID: assistantMessageID,
+          type: "text",
+          text: markdown,
+          time: {
+            start: now + 1,
+            end: now + 2,
+          },
+        },
+      ],
+    },
+  ] satisfies Array<{ info: Message; parts: Part[] }>
+
+  const fetch = (async (...args: Parameters<typeof globalThis.fetch>) => {
+    const request = new Request(args[0], args[1])
+    const url = new URL(request.url)
+    const pathname = url.pathname
+
+    if (request.method === "GET" && pathname === "/path") return json(paths)
+    if (request.method === "GET" && pathname === "/project/current") return json(project)
+    if (request.method === "GET" && pathname === "/config/providers") {
+      return json({ providers: [provider], default: { build: "demo/demo" } })
+    }
+    if (request.method === "GET" && pathname === "/provider") {
+      return json({ all: [provider], default: { build: "demo/demo" }, connected: [provider.id] })
+    }
+    if (request.method === "GET" && pathname === "/experimental/console") {
+      return json({ consoleManagedProviders: [], switchableOrgCount: 0 })
+    }
+    if (request.method === "GET" && pathname === "/agent") return json([agent])
+    if (request.method === "GET" && pathname === "/config") {
+      return json({ model: "demo/demo", default_agent: agent.name } satisfies Config)
+    }
+    if (request.method === "GET" && pathname === "/session") return json([session])
+    if (request.method === "GET" && pathname === "/command") return json([])
+    if (request.method === "GET" && pathname === "/lsp") return json([])
+    if (request.method === "GET" && pathname === "/mcp") return json({})
+    if (request.method === "GET" && pathname === "/experimental/resource") return json({})
+    if (request.method === "GET" && pathname === "/formatter") return json([])
+    if (request.method === "GET" && pathname === "/session/status") return json({ [sessionID]: { type: "idle" } })
+    if (request.method === "GET" && pathname === "/provider/auth") return json({})
+    if (request.method === "GET" && pathname === "/vcs") return json({ branch: "demo", default_branch: "dev" })
+    if (request.method === "GET" && pathname === "/experimental/workspace") return json([])
+    if (request.method === "GET" && pathname === "/experimental/workspace/status") return json([])
+    if (request.method === "GET" && pathname === `/session/${sessionID}`) return json(session)
+    if (request.method === "GET" && pathname === `/session/${sessionID}/message`) return json(messages)
+    if (request.method === "GET" && pathname === `/session/${sessionID}/todo`) return json([])
+    if (request.method === "GET" && pathname === `/session/${sessionID}/diff`) return json([])
+    if (request.method === "GET" && pathname === `/session/${sessionID}/children`) return json([])
+
+    return json({ message: `Unhandled demo endpoint: ${request.method} ${pathname}` }, 404)
+  }) as typeof globalThis.fetch
+
+  const events = {
+    subscribe: async () => () => {},
+  } satisfies EventSource
+
+  return {
+    sessionID,
+    fetch,
+    events,
+  }
+}

packages/opencode/src/cli/cmd/tui/keymap.tsx

@@ -8,9 +8,9 @@ import {
 import {
   KeymapProvider,
   reactiveMatcherFromSignal,
+  useBindings,
   useKeymap,
   useKeymapSelector,
-  useBindings,
 } from "@opentui/keymap/solid"
 import type { Accessor } from "solid-js"
 import type { TuiConfig } from "./config/tui"
@@ -26,28 +26,6 @@ export { reactiveMatcherFromSignal, useBindings, useKeymapSelector }
 
 export type OpenTuiKeymap = ReturnType<typeof useKeymap>
 
-const KEY_ALIASES = {
-  enter: "return",
-  esc: "escape",
-} as const
-
-function expandKeyAliases(input: string) {
-  const result = Object.entries(KEY_ALIASES).reduce(
-    (acc, [alias, key]) => acc.replace(new RegExp(`(^|[+,\\s>])${alias}(?=$|[+,\\s<])`, "gi"), `$1${key}`),
-    input,
-  )
-  if (result === input) return
-  return result
-}
-
-function registerKeyAliases(keymap: OpenTuiKeymap) {
-  return keymap.appendBindingExpander((ctx) => {
-    const key = expandKeyAliases(ctx.input)
-    if (!key) return
-    return [{ key, displays: ctx.displays }]
-  })
-}
-
 const inputCommands = [
   "input.move.left",
   "input.move.right",
@@ -120,13 +98,8 @@ export function formatKeyBindings(
   return formatCommandBindingsExtra(bindings, formatOptions(config))
 }
 
-export function registerOpencodeKeymap(
-  keymap: OpenTuiKeymap,
-  renderer: CliRenderer,
-  config: Pick<TuiConfig.Resolved, "keybinds" | "leader_timeout">,
-) {
+export function registerOpencodeKeymap(keymap: OpenTuiKeymap, renderer: CliRenderer, config: TuiConfig.Resolved) {
   const offCommaBindings = addons.registerCommaBindings(keymap)
-  const offAliasExpander = registerKeyAliases(keymap)
   const offBaseLayout = addons.registerBaseLayoutFallback(keymap)
   const offLeader = addons.registerTimedLeader(keymap, {
     trigger: config.keybinds.get(LEADER_TOKEN),
@@ -135,17 +108,20 @@ export function registerOpencodeKeymap(
   })
   const offEscape = addons.registerEscapeClearsPendingSequence(keymap)
   const offBackspace = addons.registerBackspacePopsPendingSequence(keymap)
-  const offInputBindings = addons.registerManagedTextareaLayer(keymap, renderer, {
+  const offInputCommands = addons.registerEditBufferCommands(keymap, renderer)
+  const offInputSuspension = addons.registerTextareaMappingSuspension(keymap, renderer)
+  const offInputBindings = keymap.registerLayer({
     enabled: () => renderer.currentFocusedEditor !== null,
     bindings: config.keybinds.gather("input", inputCommands),
   })
 
   return () => {
     offInputBindings()
+    offInputSuspension()
+    offInputCommands()
     offBackspace()
     offEscape()
     offLeader()
-    offAliasExpander()
     offBaseLayout()
     offCommaBindings()
   }

packages/opencode/src/cli/cmd/tui/routes/session/index.tsx

@@ -21,7 +21,20 @@ import { useEvent } from "@tui/context/event"
 import { SplitBorder } from "@tui/component/border"
 import { Spinner } from "@tui/component/spinner"
 import { selectedForeground, useTheme } from "@tui/context/theme"
-import { BoxRenderable, ScrollBoxRenderable, addDefaultParsers, TextAttributes, RGBA } from "@opentui/core"
+import {
+  BoxRenderable,
+  ScrollBoxRenderable,
+  addDefaultParsers,
+  TextAttributes,
+  RGBA,
+  type MarkdownOptions,
+  type MarkdownRenderable,
+  CodeRenderable,
+  TextTableRenderable,
+  TextRenderable,
+  StyledText,
+  type TextChunk,
+} from "@opentui/core"
 import { Prompt, type PromptRef } from "@tui/component/prompt"
 import type {
   AssistantMessage,
@@ -746,7 +759,7 @@ export function Session() {
       title: "Line up",
       value: "session.line.up",
       category: "Session",
-      hidden: true,
+      enabled: false,
       run: () => {
         scroll.scrollBy(-1)
         dialog.clear()
@@ -756,7 +769,7 @@ export function Session() {
       title: "Line down",
       value: "session.line.down",
       category: "Session",
-      hidden: true,
+      enabled: false,
       run: () => {
         scroll.scrollBy(1)
         dialog.clear()
@@ -1525,15 +1538,180 @@ function ReasoningPart(props: { last: boolean; part: ReasoningPart; message: Ass
 function TextPart(props: { last: boolean; part: TextPart; message: AssistantMessage }) {
   const ctx = use()
   const { theme, syntax } = useTheme()
+  const text = createMemo(() => props.part.text.trim())
+  const diffCache = new Map<string, TextChunk[]>()
+  const colorDiffChunks = (text: string) => {
+    const key = `${theme.diffAdded.toString()}:${theme.diffRemoved.toString()}:${text}`
+    const cached = diffCache.get(key)
+    if (cached) return cached
+
+    let line: "added" | "removed" | undefined
+    let start = true
+    const chunks = (text.match(/[^\n]+|\n/g) ?? [text]).map((part): TextChunk => {
+      if (start && part !== "\n") {
+        line = part.startsWith("+") ? "added" : part.startsWith("-") ? "removed" : undefined
+        start = false
+      }
+      const next = {
+        __isChunk: true,
+        text: part,
+        ...(line === "added" ? { fg: theme.diffAdded } : {}),
+        ...(line === "removed" ? { fg: theme.diffRemoved } : {}),
+      } satisfies TextChunk
+      if (part === "\n") {
+        line = undefined
+        start = true
+      }
+      return next
+    })
+    diffCache.set(key, chunks)
+    if (diffCache.size > 20) diffCache.delete(diffCache.keys().next().value!)
+    return chunks
+  }
+  const renderBlockquoteBar = (chunks: TextChunk[]) => {
+    let lineStart = true
+    let spaces = 0
+    let replaced = false
+    let skipWhitespace = false
+    return chunks.flatMap((chunk) => {
+      const result: TextChunk[] = []
+      let next = ""
+      const flush = () => {
+        if (!next) return
+        result.push(next === chunk.text ? chunk : { ...chunk, text: next })
+        next = ""
+      }
+      for (const char of chunk.text) {
+        if (skipWhitespace && (char === " " || char === "\t")) {
+          skipWhitespace = false
+          continue
+        }
+        skipWhitespace = false
+        if (lineStart && !replaced && char === " " && spaces < 3) {
+          spaces++
+          next += char
+          continue
+        }
+        if (lineStart && !replaced && char === ">") {
+          flush()
+          result.push({ __isChunk: true, text: "│ ", fg: theme.textMuted, attributes: TextAttributes.NONE })
+          replaced = true
+          skipWhitespace = true
+          continue
+        }
+        next += char
+        if (char === "\n") {
+          lineStart = true
+          spaces = 0
+          replaced = false
+          skipWhitespace = false
+          continue
+        }
+        lineStart = false
+      }
+      flush()
+      return result
+    })
+  }
+  const trimCodeIndent = (value: string) => {
+    const lines = value.split("\n")
+    const indents = lines.filter((line) => line.trim()).map((line) => line.match(/^[ \t]*/)?.[0].length ?? 0)
+    const indent = Math.min(...indents)
+    if (!Number.isFinite(indent) || indent === 0) return value
+    return lines.map((line) => (line.trim() ? line.slice(indent) : line)).join("\n")
+  }
+  const padTableCells = (renderable: TextTableRenderable) => {
+    renderable.content = renderable.content.map((row) =>
+      row.map((cell) => {
+        const content = cell ?? []
+        return [{ __isChunk: true, text: " " }, ...content, { __isChunk: true, text: " " }] satisfies TextChunk[]
+      }),
+    )
+  }
+  const configureMarkdown = (node: MarkdownRenderable | undefined) => {
+    if (!node) return
+    const renderNode: NonNullable<MarkdownOptions["renderNode"]> = (token, context) => {
+      const content = text()
+      const firstBlock = content.startsWith(token.raw.trimStart())
+
+      if (token.type === "hr") {
+        return new BoxRenderable(node.ctx, {
+          width: "100%",
+          height: 1,
+          border: ["top"],
+          borderColor: theme.border,
+          flexShrink: 0,
+        })
+      }
+
+      if (token.type === "blockquote") {
+        const renderable = context.defaultRender()
+        if (renderable instanceof CodeRenderable) {
+          const code = renderable
+          const onChunks = code.onChunks
+          code.onChunks = (chunks, context) => {
+            const result = onChunks?.call(code, chunks, context)
+            if (result instanceof Promise) return result.then((next) => renderBlockquoteBar(next ?? chunks))
+            return renderBlockquoteBar(result ?? chunks)
+          }
+        }
+        if (!firstBlock && renderable) {
+          renderable.marginTop = typeof renderable.marginTop === "number" ? Math.max(renderable.marginTop, 1) : 1
+        }
+        return renderable
+      }
+
+      const needsCodeTopGap = token.type === "code" && !firstBlock
+      if (token.type === "code" && /^[ \t]{4,}(```|~~~)/.test(token.raw)) {
+        token.text = trimCodeIndent(token.text)
+      }
+
+      if (token.type === "table") {
+        const renderable = context.defaultRender()
+        if (renderable instanceof TextTableRenderable) padTableCells(renderable)
+        return renderable
+      }
+
+      if (token.type === "code" && token.lang?.trim().toLowerCase() === "diff") {
+        const renderable = new TextRenderable(node.ctx, {
+          content: new StyledText(colorDiffChunks(token.text)),
+          width: "100%",
+          flexShrink: 0,
+        })
+        if (needsCodeTopGap) renderable.marginTop = 1
+        return renderable
+      }
+
+      const renderable = context.defaultRender()
+      if (token.type === "heading" && token.depth === 1 && !firstBlock && renderable) {
+        renderable.marginTop = typeof renderable.marginTop === "number" ? Math.max(renderable.marginTop, 2) : 2
+      }
+      if (needsCodeTopGap && renderable) {
+        renderable.marginTop = typeof renderable.marginTop === "number" ? Math.max(renderable.marginTop, 1) : 1
+      }
+      return renderable
+    }
+
+    // OpenTUI Solid constructs elements with only `{ id }`, so constructor-only
+    // MarkdownOptions need to be installed on the renderable directly.
+    const target = node as unknown as {
+      _internalBlockMode: "top-level"
+      _renderNode: typeof renderNode
+    }
+    target._internalBlockMode = "top-level"
+    target._renderNode = renderNode
+  }
   return (
-    <Show when={props.part.text.trim()}>
+    <Show when={text()}>
       <box id={"text-" + props.part.id} paddingLeft={3} marginTop={1} flexShrink={0}>
         <Switch>
           <Match when={Flag.OPENCODE_EXPERIMENTAL_MARKDOWN}>
             <markdown
               syntaxStyle={syntax()}
               streaming={true}
-              content={props.part.text.trim()}
+              ref={configureMarkdown}
+              tableOptions={{ style: "grid", widthMode: "content" }}
+              content={text()}
               conceal={ctx.conceal()}
               fg={theme.markdownText}
               bg={theme.background}
@@ -1545,7 +1723,7 @@ function TextPart(props: { last: boolean; part: TextPart; message: AssistantMess
               drawUnstyledText={false}
               streaming={true}
               syntaxStyle={syntax()}
-              content={props.part.text.trim()}
+              content={text()}
               conceal={ctx.conceal()}
               fg={theme.text}
             />

packages/opencode/src/cli/cmd/tui/thread.ts

@@ -111,6 +111,10 @@ export const TuiThreadCommand = cmd({
       .option("agent", {
         type: "string",
         describe: "agent to use",
+      })
+      .option("demo", {
+        type: "boolean",
+        describe: "open a fake fullscreen TUI session for renderer debugging",
       }),
   handler: async (args) => {
     // Keep ENABLE_PROCESSED_INPUT cleared even if other code flips it.
@@ -130,7 +134,6 @@ export const TuiThreadCommand = cmd({
       // Resolve relative --project paths from PWD, then use the real cwd after
       // chdir so the thread and worker share the same directory key.
       const next = resolveThreadDirectory(args.project)
-      const file = await target()
       try {
         process.chdir(next)
       } catch {
@@ -138,6 +141,32 @@ export const TuiThreadCommand = cmd({
         return
       }
       const cwd = Filesystem.resolve(process.cwd())
+      const config = TuiConfig.get()
+      config.catch(() => {})
+
+      if (args.demo) {
+        const { createTuiDemo } = await import("./demo")
+        const { tui } = await import("./app")
+        const demo = createTuiDemo({ directory: cwd })
+        await tui({
+          url: "http://opencode.demo",
+          config: await config,
+          directory: cwd,
+          fetch: demo.fetch,
+          events: demo.events,
+          args: {
+            continue: false,
+            sessionID: demo.sessionID,
+            agent: args.agent,
+            model: args.model,
+            prompt: await input(args.prompt),
+            fork: false,
+          },
+        })
+        return
+      }
+
+      const file = await target()
       const env = sanitizedProcessEnv({
         [OPENCODE_PROCESS_ROLE]: "worker",
         [OPENCODE_RUN_ID]: ensureRunID(),
@@ -187,8 +216,6 @@ export const TuiThreadCommand = cmd({
       }
 
       const prompt = await input(args.prompt)
-      const config = await TuiConfig.get()
-
       const network = resolveNetworkOptionsNoConfig(args)
       const external =
         process.argv.includes("--port") ||
@@ -236,7 +263,7 @@ export const TuiThreadCommand = cmd({
             const server = await client.call("snapshot", undefined)
             return [tui, server]
           },
-          config,
+          config: await config,
           directory: cwd,
           fetch: transport.fetch,
           events: transport.events,

packages/opencode/src/cli/cmd/tui/validate-session.ts

@@ -1,8 +1,5 @@
 import { createOpencodeClient } from "@opencode-ai/sdk/v2"
 import { SessionID } from "@/session/schema"
-import { Schema } from "effect"
-
-const decodeSessionID = Schema.decodeUnknownSync(SessionID)
 
 export async function validateSession(input: {
   url: string
@@ -13,11 +10,9 @@ export async function validateSession(input: {
 }) {
   if (!input.sessionID) return
 
-  let sessionID: SessionID
-  try {
-    sessionID = decodeSessionID(input.sessionID)
-  } catch (error) {
-    throw new Error(`Invalid session ID: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error })
+  const result = SessionID.zod.safeParse(input.sessionID)
+  if (!result.success) {
+    throw new Error(`Invalid session ID: ${result.error.issues.at(0)?.message ?? "unknown error"}`)
   }
 
   await createOpencodeClient({
@@ -25,5 +20,5 @@ export async function validateSession(input: {
     directory: input.directory,
     fetch: input.fetch,
     headers: input.headers,
-  }).session.get({ sessionID }, { throwOnError: true })
+  }).session.get({ sessionID: result.data }, { throwOnError: true })
 }

packages/opencode/src/config/config.ts

@@ -273,10 +273,10 @@ export const Info = Schema.Struct({
       }),
       tail_turns: Schema.optional(NonNegativeInt).annotate({
         description:
-          "Number of recent user turns, including their following assistant/tool responses, to serialize into the compaction summary (default: 2)",
+          "Number of recent user turns, including their following assistant/tool responses, to keep verbatim during compaction (default: 2)",
       }),
       preserve_recent_tokens: Schema.optional(NonNegativeInt).annotate({
-        description: "Maximum number of tokens from recent turns to serialize into the compaction summary",
+        description: "Maximum number of tokens from recent turns to preserve verbatim after compaction",
       }),
       reserved: Schema.optional(NonNegativeInt).annotate({
         description: "Token buffer for compaction. Leaves enough window to avoid overflow during compaction.",

packages/opencode/src/control-plane/schema.ts

@@ -1,6 +1,7 @@
 import { Schema } from "effect"
 
 import { Identifier } from "@/id/id"
+import { zod } from "@opencode-ai/core/effect-zod"
 import { withStatics } from "@opencode-ai/core/schema"
 
 const workspaceIdSchema = Schema.String.check(Schema.isStartsWith("wrk")).pipe(Schema.brand("WorkspaceID"))
@@ -10,5 +11,6 @@ export type WorkspaceID = typeof workspaceIdSchema.Type
 export const WorkspaceID = workspaceIdSchema.pipe(
   withStatics((schema: typeof workspaceIdSchema) => ({
     ascending: (id?: string) => schema.make(Identifier.ascending("workspace", id)),
+    zod: zod(schema),
   })),
 )

packages/opencode/src/control-plane/workspace.ts

@@ -641,7 +641,7 @@ export const layer = Layer.effect(
 
             // "claim" this session so any future events coming from
             // the old workspace are ignored
-            yield* sync.claim(input.sessionID, input.workspaceID ?? previous.projectID)
+            SyncEvent.claim(input.sessionID, input.workspaceID ?? previous.projectID)
           }
         }
 
@@ -676,12 +676,14 @@ export const layer = Layer.effect(
         }
 
         if (input.workspaceID === null) {
-          yield* sync.run(Session.Event.Updated, {
-            sessionID: input.sessionID,
-            info: {
-              workspaceID: null,
-            },
-          })
+          yield* Effect.sync(() =>
+            SyncEvent.run(Session.Event.Updated, {
+              sessionID: input.sessionID,
+              info: {
+                workspaceID: null,
+              },
+            }),
+          )
 
           log.info("session warp complete", {
             workspaceID: input.workspaceID,

packages/opencode/src/data-migration.sql.ts

@@ -1,6 +0,0 @@
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core"
-
-export const DataMigrationTable = sqliteTable("data_migration", {
-  name: text().primaryKey(),
-  time_completed: integer().notNull(),
-})

packages/opencode/src/data-migration.ts

@@ -1,59 +0,0 @@
-import { Context, Effect, Layer } from "effect"
-import { Database } from "./storage/db"
-import { DataMigrationTable } from "./data-migration.sql"
-import * as Log from "@opencode-ai/core/util/log"
-import { eq } from "drizzle-orm"
-
-export type Migration<R = never> = {
-  name: string
-  run: Effect.Effect<void, unknown, R>
-}
-
-const log = Log.create({ service: "data-migration" })
-
-export interface Interface {}
-
-export class Service extends Context.Service<Service, Interface>()("@opencode/DataMigration") {}
-
-export const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const migrations: Migration[] = []
-
-    yield* Effect.gen(function* () {
-      if (migrations.length === 0) return
-
-      // Migrations run in a background fiber, so they must be resumable until
-      // their completion row is written.
-      for (const migration of migrations) {
-        const completed = Database.use((db) =>
-          db
-            .select({ name: DataMigrationTable.name })
-            .from(DataMigrationTable)
-            .where(eq(DataMigrationTable.name, migration.name))
-            .get(),
-        )
-        if (completed) continue
-
-        log.info("running data migration", { name: migration.name })
-        yield* migration.run.pipe(Effect.withSpan("DataMigration", { attributes: { name: migration.name } }))
-        Database.use((db) =>
-          db
-            .insert(DataMigrationTable)
-            .values({ name: migration.name, time_completed: Date.now() })
-            .onConflictDoNothing()
-            .run(),
-        )
-      }
-    }).pipe(
-      Effect.tapCause((cause) => Effect.logError("failed to run data migrations", { cause })),
-      Effect.ignore,
-      Effect.forkScoped,
-    )
-    return Service.of({})
-  }),
-)
-
-export const defaultLayer = layer
-
-export * as DataMigration from "./data-migration"

packages/opencode/src/effect/app-runtime.ts

@@ -30,6 +30,7 @@ import { SessionProcessor } from "@/session/processor"
 import { SessionCompaction } from "@/session/compaction"
 import { SessionRevert } from "@/session/revert"
 import { SessionSummary } from "@/session/summary"
+import { SessionTimeline } from "@/session/timeline"
 import { SessionPrompt } from "@/session/prompt"
 import { Instruction } from "@/session/instruction"
 import { LLM } from "@/session/llm"
@@ -54,7 +55,6 @@ import { SessionShare } from "@/share/session"
 import { SyncEvent } from "@/sync"
 import { Npm } from "@opencode-ai/core/npm"
 import { memoMap } from "@opencode-ai/core/effect/memo-map"
-import { DataMigration } from "@/data-migration"
 
 export const AppLayer = Layer.mergeAll(
   Npm.defaultLayer,
@@ -86,6 +86,7 @@ export const AppLayer = Layer.mergeAll(
   SessionCompaction.defaultLayer,
   SessionRevert.defaultLayer,
   SessionSummary.defaultLayer,
+  SessionTimeline.defaultLayer,
   SessionPrompt.defaultLayer,
   Instruction.defaultLayer,
   LLM.defaultLayer,
@@ -107,7 +108,6 @@ export const AppLayer = Layer.mergeAll(
   ShareNext.defaultLayer,
   SessionShare.defaultLayer,
   SyncEvent.defaultLayer,
-  DataMigration.defaultLayer,
 ).pipe(Layer.provideMerge(InstanceLayer.layer), Layer.provideMerge(Observability.layer))
 
 const rt = ManagedRuntime.make(AppLayer, { memoMap })

packages/opencode/src/project/instance-store.ts

@@ -86,7 +86,7 @@ export const layer: Layer.Layer<Service, never, Project.Service | InstanceBootst
       )
 
     const disposeContext = Effect.fn("InstanceStore.disposeContext")(function* (ctx: InstanceContext) {
-      yield* Effect.logInfo("disposing instance").pipe(Effect.annotateLogs("directory", ctx.directory))
+      yield* Effect.logInfo("disposing instance", { directory: ctx.directory })
       yield* Effect.promise(() => runDisposers(ctx.directory))
       yield* emitDisposed({ directory: ctx.directory, project: ctx.project.id })
     })
@@ -109,7 +109,7 @@ export const layer: Layer.Layer<Service, never, Project.Service | InstanceBootst
           const entry: Entry = { deferred: Deferred.makeUnsafe<InstanceContext>() }
           cache.set(directory, entry)
           yield* Effect.gen(function* () {
-            yield* Effect.logInfo("creating instance").pipe(Effect.annotateLogs("directory", directory))
+            yield* Effect.logInfo("creating instance", { directory })
             yield* completeLoad(directory, input, entry)
           }).pipe(Effect.forkIn(scope, { startImmediately: true }))
           return yield* restore(Deferred.await(entry.deferred))
@@ -125,7 +125,7 @@ export const layer: Layer.Layer<Service, never, Project.Service | InstanceBootst
           const entry: Entry = { deferred: Deferred.makeUnsafe<InstanceContext>() }
           cache.set(directory, entry)
           yield* Effect.gen(function* () {
-            yield* Effect.logInfo("reloading instance").pipe(Effect.annotateLogs("directory", directory))
+            yield* Effect.logInfo("reloading instance", { directory })
             if (previous) {
               yield* Deferred.await(previous.deferred).pipe(Effect.ignore)
               yield* Effect.promise(() => runDisposers(directory))

packages/opencode/src/project/project.ts

@@ -34,7 +34,7 @@ const ProjectIcon = Schema.Struct({
 
 const ProjectCommands = Schema.Struct({
   start: optionalOmitUndefined(
-    Schema.String.annotate({ description: "Startup script to run when creating a new worktree" }),
+    Schema.String.annotate({ description: "Startup script to run when creating a new workspace (worktree)" }),
   ),
 })
 

packages/opencode/src/server/routes/instance/httpapi/api.ts

@@ -21,7 +21,6 @@ import { TuiApi } from "./groups/tui"
 import { WorkspaceApi } from "./groups/workspace"
 import { V2Api } from "./groups/v2"
 import { Authorization } from "./middleware/authorization"
-import { SchemaErrorMiddleware } from "./middleware/schema-error"
 
 // SSE event schemas built from the BusEvent/SyncEvent registries.
 const EventSchema = Schema.Union(BusEvent.effectPayloads()).annotate({ identifier: "Event" })
@@ -30,7 +29,6 @@ const SyncEventSchemas = SyncEvent.effectPayloads()
 export const RootHttpApi = HttpApi.make("opencode-root")
   .addHttpApi(ControlApi)
   .addHttpApi(GlobalApi)
-  .middleware(SchemaErrorMiddleware)
   .middleware(Authorization)
 
 export const InstanceHttpApi = HttpApi.make("opencode-instance")
@@ -49,7 +47,6 @@ export const InstanceHttpApi = HttpApi.make("opencode-instance")
   .addHttpApi(V2Api)
   .addHttpApi(TuiApi)
   .addHttpApi(WorkspaceApi)
-  .middleware(SchemaErrorMiddleware)
 
 export const OpenCodeHttpApi = HttpApi.make("opencode")
   .addHttpApi(RootHttpApi)

packages/opencode/src/server/routes/instance/httpapi/groups/session.ts

@@ -236,9 +236,9 @@ export const SessionApi = HttpApi.make("session")
         HttpApiEndpoint.post("fork", SessionPaths.fork, {
           params: { sessionID: SessionID },
           query: WorkspaceRoutingQuery,
-          payload: Schema.optional(ForkPayload),
+          payload: ForkPayload,
           success: described(Session.Info, "200"),
-          error: [HttpApiError.BadRequest, ApiNotFoundError],
+          error: ApiNotFoundError,
         }).annotateMerge(
           OpenApi.annotations({
             identifier: "session.fork",