test(session): clarify compaction test harness

test(session): effectify remaining compaction process tests
2026-05-10 20:23:37 -04:00 · 2026-05-10 20:12:56 -04:00
223 changed files with 3300 additions and 9185 deletions
@@ -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,15 +147,17 @@
    },
    "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",
        "@ai-sdk/openai-compatible": "2.0.37",
+        "@hono/zod-validator": "catalog:",
        "@openauthjs/openauth": "0.0.0-20250322224806",
        "@opencode-ai/console-core": "workspace:*",
        "@opencode-ai/console-resource": "workspace:*",
        "ai": "catalog:",
+        "hono": "catalog:",
        "zod": "catalog:",
      },
      "devDependencies": {
@@ -169,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",
@@ -193,7 +195,7 @@
    },
    "packages/core": {
      "name": "@opencode-ai/core",
-      "version": "1.14.48",
+      "version": "1.14.46",
      "bin": {
        "opencode": "./bin/opencode",
      },
@@ -227,7 +229,7 @@
    },
    "packages/desktop": {
      "name": "@opencode-ai/desktop",
-      "version": "1.14.48",
+      "version": "1.14.46",
      "dependencies": {
        "drizzle-orm": "catalog:",
        "effect": "catalog:",
@@ -281,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:*",
@@ -311,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:",
@@ -327,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:",
@@ -340,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",
@@ -358,7 +360,7 @@
    },
    "packages/opencode": {
      "name": "opencode",
-      "version": "1.14.48",
+      "version": "1.14.46",
      "bin": {
        "opencode": "./bin/opencode",
      },
@@ -494,7 +496,7 @@
    },
    "packages/plugin": {
      "name": "@opencode-ai/plugin",
-      "version": "1.14.48",
+      "version": "1.14.46",
      "dependencies": {
        "@opencode-ai/sdk": "workspace:*",
        "effect": "catalog:",
@@ -532,7 +534,7 @@
    },
    "packages/sdk/js": {
      "name": "@opencode-ai/sdk",
-      "version": "1.14.48",
+      "version": "1.14.46",
      "dependencies": {
        "cross-spawn": "catalog:",
      },
@@ -547,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",
@@ -582,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:*",
@@ -631,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",
@@ -684,8 +686,8 @@
  },
  "catalog": {
    "@cloudflare/workers-types": "4.20251008.0",
-    "@effect/opentelemetry": "4.0.0-beta.65",
-    "@effect/platform-node": "4.0.0-beta.65",
+    "@effect/opentelemetry": "4.0.0-beta.57",
+    "@effect/platform-node": "4.0.0-beta.57",
    "@hono/zod-validator": "0.4.2",
    "@kobalte/core": "0.13.11",
    "@lydell/node-pty": "1.2.0-beta.10",
@@ -718,7 +720,7 @@
    "dompurify": "3.3.1",
    "drizzle-kit": "1.0.0-beta.19-d95b7a4",
    "drizzle-orm": "1.0.0-beta.19-d95b7a4",
-    "effect": "4.0.0-beta.65",
+    "effect": "4.0.0-beta.59",
    "fuzzysort": "3.1.0",
    "hono": "4.10.7",
    "hono-openapi": "1.1.2",
@@ -1079,11 +1081,11 @@

    "@drizzle-team/brocli": ["@drizzle-team/brocli@0.11.0", "", {}, "sha512-hD3pekGiPg0WPCCGAZmusBBJsDqGUR66Y452YgQsZOnkdQ7ViEPKuyP4huUGEZQefp8g34RRodXYmJ2TbCH+tg=="],

-    "@effect/opentelemetry": ["@effect/opentelemetry@4.0.0-beta.65", "", { "peerDependencies": { "@opentelemetry/api": "^1.9", "@opentelemetry/api-logs": ">=0.203.0 <0.300.0", "@opentelemetry/resources": "^2.0.0", "@opentelemetry/sdk-logs": ">=0.203.0 <0.300.0", "@opentelemetry/sdk-metrics": "^2.0.0", "@opentelemetry/sdk-trace-base": "^2.0.0", "@opentelemetry/sdk-trace-node": "^2.0.0", "@opentelemetry/sdk-trace-web": "^2.0.0", "@opentelemetry/semantic-conventions": "^1.33.0", "effect": "^4.0.0-beta.65" }, "optionalPeers": ["@opentelemetry/api", "@opentelemetry/api-logs", "@opentelemetry/resources", "@opentelemetry/sdk-logs", "@opentelemetry/sdk-metrics", "@opentelemetry/sdk-trace-base", "@opentelemetry/sdk-trace-node", "@opentelemetry/sdk-trace-web"] }, "sha512-0CD2fSsXrDM7FP2WFkbGJO1DwMqWR3UKHh6oBDXPHAPA+RsJSKoh3pLQsbQfldLuKnhOy87Bv0v9r9IdrIHCQw=="],
+    "@effect/opentelemetry": ["@effect/opentelemetry@4.0.0-beta.57", "", { "peerDependencies": { "@opentelemetry/api": "^1.9", "@opentelemetry/resources": "^2.0.0", "@opentelemetry/sdk-logs": ">=0.203.0 <0.300.0", "@opentelemetry/sdk-metrics": "^2.0.0", "@opentelemetry/sdk-trace-base": "^2.0.0", "@opentelemetry/sdk-trace-node": "^2.0.0", "@opentelemetry/sdk-trace-web": "^2.0.0", "@opentelemetry/semantic-conventions": "^1.33.0", "effect": "^4.0.0-beta.57" }, "optionalPeers": ["@opentelemetry/api", "@opentelemetry/resources", "@opentelemetry/sdk-logs", "@opentelemetry/sdk-metrics", "@opentelemetry/sdk-trace-base", "@opentelemetry/sdk-trace-node", "@opentelemetry/sdk-trace-web"] }, "sha512-gdjZPEP0QQg4qmI1vd+443kheeQZKytrjJIzCJncy6ZEpyk/SfrqeStLqLXdTRcms3IB0ls0vOV7KNq7YmBRVA=="],

-    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.65", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.65", "mime": "^4.1.0", "undici": "^8.0.2" }, "peerDependencies": { "effect": "^4.0.0-beta.65", "ioredis": "^5.7.0" } }, "sha512-QQy3KRcMwP0TngQdfQGl2u1zp03B7k7DuF5SNS8aZhD0dDBpKZpCwFad1ODY5qdY3ycPgMwBwKRRK7y/aw0C9w=="],
+    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.57", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.57", "mime": "^4.1.0", "undici": "^8.0.2" }, "peerDependencies": { "effect": "^4.0.0-beta.57", "ioredis": "^5.7.0" } }, "sha512-la0xxPSAYOsY0d+uVxEBxok3jYB31iPQmIaZZRUj2SNWqcGGHJc6KorKtI8guqSLuv9FGZ255kBWXRbG6hMeeg=="],

-    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.65", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.20.0" }, "peerDependencies": { "effect": "^4.0.0-beta.65" } }, "sha512-3rY8F3WLEax6Hj08GI/OvDIH+KqjfxH7RM2bAMfgR75NgRmwDtny1P49PtPkoRjH5dcdtThThtsvE4X9OTZkpQ=="],
+    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.57", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.20.0" }, "peerDependencies": { "effect": "^4.0.0-beta.57" } }, "sha512-C976X6f+qHUtLSqcqImuCrjhAHnJV17NC2RvvybsAuDfkyIWU4MyiO2XwgiBeijeNupyr1M/KPKnyjtkNxV9Hw=="],

    "@electron/asar": ["@electron/asar@3.4.1", "", { "dependencies": { "commander": "^5.0.0", "glob": "^7.1.6", "minimatch": "^3.0.4" }, "bin": { "asar": "bin/asar.js" } }, "sha512-i4/rNPRS84t0vSRa2HorerGRXWyF4vThfHesw0dmcWHp+cspK743UanA0suA5Q5y8kzY2y6YKrvbIUn69BCAiA=="],

@@ -1233,6 +1235,8 @@

    "@hono/standard-validator": ["@hono/standard-validator@0.1.5", "", { "peerDependencies": { "@standard-schema/spec": "1.0.0", "hono": ">=3.9.0" } }, "sha512-EIyZPPwkyLn6XKwFj5NBEWHXhXbgmnVh2ceIFo5GO7gKI9WmzTjPDKnppQB0KrqKeAkq3kpoW4SIbu5X1dgx3w=="],

+    "@hono/zod-validator": ["@hono/zod-validator@0.4.2", "", { "peerDependencies": { "hono": ">=3.9.0", "zod": "^3.19.1" } }, "sha512-1rrlBg+EpDPhzOV4hT9pxr5+xDVmKuz6YJl+la7VCwK6ass5ldyKm5fD+umJdV2zhHD6jROoCCv8NbTwyfhT0g=="],
+
    "@ibm/plex": ["@ibm/plex@6.4.1", "", { "dependencies": { "@ibm/telemetry-js": "^1.5.1" } }, "sha512-fnsipQywHt3zWvsnlyYKMikcVI7E2fEwpiPnIHFqlbByXVfQfANAAeJk1IV4mNnxhppUIDlhU0TzwYwL++Rn2g=="],

    "@ibm/telemetry-js": ["@ibm/telemetry-js@1.11.0", "", { "bin": { "ibmtelemetry": "dist/collect.js" } }, "sha512-RO/9j+URJnSfseWg9ZkEX9p+a3Ousd33DBU7rOafoZB08RqdzxFVYJ2/iM50dkBuD0o7WX7GYt1sLbNgCoE+pA=="],
@@ -3037,7 +3041,7 @@

    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],

-    "effect": ["effect@4.0.0-beta.65", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.6.0", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.9", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^13.0.0", "yaml": "^2.8.3" } }, "sha512-QYKvQPAj3CmtsvWkHQww15wX4KG2gNsszDWEcOO5sZCMknp66u6Si/Opmt3wwWCwsyvRmDAdIg+JIz5qzbbFIw=="],
+    "effect": ["effect@4.0.0-beta.59", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.6.0", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.9", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^13.0.0", "yaml": "^2.8.3" } }, "sha512-xyUDLeHSe8d6lWGOvR6Fgn2HL6gYeTZ/S4Jzk9uc4ZUxMPPsNZlNXrvk0C7/utQFzeX7uAWcVnG2BjbA0SRoAA=="],

    "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],

@@ -5465,6 +5469,8 @@

    "@hey-api/openapi-ts/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],

+    "@hono/zod-validator/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+
    "@jimp/core/mime": ["mime@3.0.0", "", { "bin": { "mime": "cli.js" } }, "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A=="],

    "@jimp/plugin-blit/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
@@ -1,8 +1,6 @@
 import { SECRET } from "./secret"
 import { domain } from "./stage"

-const description = "Managed by SST (Don't edit in Honeycomb UI)"
-
 const webhookRecipient = new honeycomb.WebhookRecipient("DiscordAlerts", {
  name: $app.stage === "production" ? "Discord Alerts" : `Discord Alerts (${$app.stage})`,
  url: `https://${domain}/honeycomb/webhook`,
@@ -27,16 +25,6 @@ const webhookRecipient = new honeycomb.WebhookRecipient("DiscordAlerts", {
  ],
 })

-// Honeycomb can keep stale query-local calculated fields when the name is unchanged,
-// so tie the field name to the expression while avoiding deploy-to-deploy churn.
-// https://github.com/honeycombio/terraform-provider-honeycombio/issues/852
-const calculatedField = (field: { name: string; expression: string }) => ({
-  ...field,
-  name: `${field.name}_${(
-    Array.from(field.expression).reduce((result, char) => Math.imul(31, result) + char.charCodeAt(0), 0) >>> 0
-  ).toString(36)}`,
-})
-
 const modelHttpErrorsQuery = (product: "go" | "zen") => {
  const filters = [
    { column: "model", op: "exists" },
@@ -44,26 +32,21 @@ const modelHttpErrorsQuery = (product: "go" | "zen") => {
    { column: "user_agent", op: "contains", value: "opencode" },
    { column: "isGoTier", op: "=", value: product === "go" ? "true" : "false" },
  ]
-  const failedHttpStatus = calculatedField({
-    name: "is_failed_http_status",
-    expression:
-      product === "go"
-        ? `IF(AND(GTE($status, "400"), NOT(EQUALS($status, "401")), NOT(EQUALS($status, "429"))), 1, 0)`
-        : `IF(AND(EQUALS($status, "429"), $isFreeTier), 0, AND(GTE($status, "400"), NOT(EQUALS($status, "401"))), 1, 0)`,
-  })

  return honeycomb.getQuerySpecificationOutput({
    breakdowns: ["model"],
-    calculatedFields: [failedHttpStatus],
+    calculatedFields: [
+      {
+        name: "is_failed_http_status",
+        expression:
+          product === "go"
+            ? `IF(AND(GTE($status, "400"), NOT(EQUALS($status, "401")), NOT(EQUALS($status, "429"))), 1, 0)`
+            : `IF(AND(GTE($status, "400"), NOT(EQUALS($status, "401"))), 1, 0)`,
+      },
+    ],
    calculations: [
      { op: "COUNT", name: "TOTAL", filterCombination: "AND", filters },
-      {
-        op: "SUM",
-        name: "FAILED",
-        column: failedHttpStatus.name,
-        filterCombination: "AND",
-        filters,
-      },
+      { op: "SUM", name: "FAILED", column: "is_failed_http_status", filterCombination: "AND", filters },
    ],
    formulas: [{ name: "ERROR", expression: "IF(GTE($TOTAL, 100), DIV($FAILED, $TOTAL), 0)" }],
    timeRange: 900,
@@ -76,30 +59,31 @@ const providerHttpErrorsQuery = (product: "go" | "zen") => {
    { column: "user_agent", op: "contains", value: "opencode" },
    { column: "isGoTier", op: "=", value: product === "go" ? "true" : "false" },
  ]
-  const successHttpStatus = calculatedField({
-    name: "is_success_http_status",
-    expression: `IF(AND(GTE($status, "200"), LT($status, "400")), 1, 0)`,
-  })
-  const failedProviderHttpStatus = calculatedField({
-    name: "is_failed_provider_http_status",
-    expression: `IF(GT($llm.error.code, "400"), 1, 0)`,
-  })

  return honeycomb.getQuerySpecificationOutput({
    breakdowns: ["provider"],
-    calculatedFields: [successHttpStatus, failedProviderHttpStatus],
+    calculatedFields: [
+      {
+        name: "is_success_http_status",
+        expression: `IF(AND(GTE($status, "200"), LT($status, "400")), 1, 0)`,
+      },
+      {
+        name: "is_failed_provider_http_status",
+        expression: `IF(GT($llm.error.code, "400"), 1, 0)`,
+      },
+    ],
    calculations: [
      {
        op: "SUM",
        name: "SUCCESS",
-        column: successHttpStatus.name,
+        column: "is_success_http_status",
        filterCombination: "AND",
        filters: [...filters, { column: "event_type", op: "=", value: "completions" }],
      },
      {
        op: "SUM",
        name: "FAILED",
-        column: failedProviderHttpStatus.name,
+        column: "is_failed_provider_http_status",
        filterCombination: "AND",
        filters: [...filters, { column: "event_type", op: "=", value: "llm.error" }],
      },
@@ -111,6 +95,8 @@ const providerHttpErrorsQuery = (product: "go" | "zen") => {
  }).json
 }

+const description = "Managed by SST (Don't edit in Honeycomb UI)"
+
 new honeycomb.Trigger("IncreasedModelHttpErrorsGo", {
  name: "Increased Model HTTP Errors [Go]",
  description,
@@ -1,8 +1,8 @@
 {
  "nodeModules": {
-    "x86_64-linux": "sha256-Q9r1S15YL9LQK7DRhuOpw3Fxi24BPovEM995GZJayKw=",
-    "aarch64-linux": "sha256-C0rRTLnxxuuEkCBc3JZbkR66TUVwpcPFif3BU9GRAuA=",
-    "aarch64-darwin": "sha256-1HvalOO/pOkRlYH8CZ93psapt90C+pYzui1JCadBE1Q=",
-    "x86_64-darwin": "sha256-RrndyLWfhWm4mZ88XytFF2NI+ly8la550Z5LBN/g5u4="
+    "x86_64-linux": "sha256-baGxh+hk/rPhg0xI/OdMDz6dPwncgercYNBdTPnLX9o=",
+    "aarch64-linux": "sha256-VTWKq679B3Q4ZnAoQzC4VSCYA09wWecNJ+JajvjNB1U=",
+    "aarch64-darwin": "sha256-orf2zIBMTiiQrt/6qCzE+o0oKhv6u8zXF9DH1Bo3lbo=",
+    "x86_64-darwin": "sha256-1MZC1fadRoY4lhkmjlcUQTLYH9Q8pDI1bxd5f94f1xU="
  }
 }
@@ -28,8 +28,8 @@
      "packages/slack"
    ],
    "catalog": {
-      "@effect/opentelemetry": "4.0.0-beta.65",
-      "@effect/platform-node": "4.0.0-beta.65",
+      "@effect/opentelemetry": "4.0.0-beta.57",
+      "@effect/platform-node": "4.0.0-beta.57",
      "@npmcli/arborist": "9.4.0",
      "@types/bun": "1.3.12",
      "@types/cross-spawn": "6.0.6",
@@ -55,7 +55,7 @@
      "dompurify": "3.3.1",
      "drizzle-kit": "1.0.0-beta.19-d95b7a4",
      "drizzle-orm": "1.0.0-beta.19-d95b7a4",
-      "effect": "4.0.0-beta.65",
+      "effect": "4.0.0-beta.59",
      "ai": "6.0.168",
      "cross-spawn": "7.0.6",
      "hono": "4.10.7",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/app",
-  "version": "1.14.48",
+  "version": "1.14.46",
  "description": "",
  "type": "module",
  "exports": {
@@ -231,7 +231,6 @@ export function createChildStoreManager(input: {
            limit: 5,
            message: {},
            part: {},
-            part_text_accum_delta: {},
          })
          children[key] = child
          disposers.set(key, dispose)
@@ -81,7 +81,6 @@ const baseState = (input: Partial<State> = {}) =>
    limit: 10,
    message: {},
    part: {},
-    part_text_accum_delta: {},
    ...input,
  }) as State

@@ -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,
@@ -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"])
@@ -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]
  }

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

 export type VcsCache = {
@@ -1934,7 +1934,7 @@ export default function Layout(props: ParentProps) {

    if (!created?.directory) return

-    setWorkspaceName(created.directory, created.branch ?? getFilename(created.directory), project.id, created.branch)
+    setWorkspaceName(created.directory, created.branch, project.id, created.branch)

    const local = project.worktree
    const key = pathKey(created.directory)
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/console-app",
-  "version": "1.14.48",
+  "version": "1.14.46",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -47,7 +47,6 @@ import { Resource } from "@opencode-ai/console-resource"
 import { i18n, type Key } from "~/i18n"
 import { localeFromRequest } from "~/lib/language"
 import { createModelTpmLimiter } from "./modelTpmLimiter"
-import { createModelTpsLimiter } from "./modelTpsLimiter"

 type ZenData = Awaited<ReturnType<typeof ZenData.list>>
 type RetryOptions = {
@@ -130,8 +129,6 @@ export async function handler(
    logger.metric({ source: billingSource })
    const modelTpmLimiter = createModelTpmLimiter(modelInfo.providers)
    const modelTpmLimits = await modelTpmLimiter?.check()
-    const modelTpsLimiter = createModelTpsLimiter(modelInfo.providers)
-    const modelTpsLimits = await modelTpsLimiter?.check()

    const retriableRequest = async (retry: RetryOptions = { excludeProviders: [], retryCount: 0 }) => {
      const providerInfo = selectProvider(
@@ -145,7 +142,6 @@ export async function handler(
        retry,
        stickyProvider,
        modelTpmLimits,
-        modelTpsLimits,
      )
      validateModelSettings(billingSource, authInfo)
      updateProviderKey(authInfo, providerInfo)
@@ -298,17 +294,14 @@ export async function handler(

        let buffer = ""
        let responseLength = 0
-        let timestampFirstByte = 0
-        let timestampLastByte = 0

        function pump(): Promise<void> {
          return (
            reader?.read().then(async ({ done, value: rawValue }) => {
              if (done) {
-                const timestampLastByte = Date.now()
                logger.metric({
                  response_length: responseLength,
-                  "timestamp.last_byte": timestampLastByte,
+                  "timestamp.last_byte": Date.now(),
                })
                dataDumper?.flush()
                await rateLimiter?.track()
@@ -318,13 +311,6 @@ export async function handler(
                  const costInfo = calculateCost(modelInfo, usageInfo)
                  await trialLimiter?.track(usageInfo)
                  await modelTpmLimiter?.track(providerInfo.id, providerInfo.model, usageInfo)
-                  await modelTpsLimiter?.track(
-                    providerInfo.id,
-                    providerInfo.model,
-                    timestampFirstByte,
-                    timestampLastByte,
-                    usageInfo,
-                  )
                  await trackUsage(sessionId, billingSource, authInfo, modelInfo, providerInfo, usageInfo, costInfo)
                  await reload(billingSource, authInfo, costInfo)
                  const cost = calculateOccurredCost(billingSource, costInfo)
@@ -335,10 +321,10 @@ export async function handler(
              }

              if (responseLength === 0) {
-                timestampFirstByte = Date.now()
+                const now = Date.now()
                logger.metric({
-                  time_to_first_byte: timestampFirstByte - startTimestamp,
-                  "timestamp.first_byte": timestampFirstByte,
+                  time_to_first_byte: now - startTimestamp,
+                  "timestamp.first_byte": now,
                })
              }

@@ -492,7 +478,6 @@ export async function handler(
    retry: RetryOptions,
    stickyProvider: string | undefined,
    modelTpmLimits: Record<string, number> | undefined,
-    modelTpsLimits: Record<string, boolean> | undefined,
  ) {
    const modelProvider = (() => {
      // Byok is top priority b/c if user set their own API key, we should use it
@@ -524,11 +509,6 @@ export async function handler(
            const usage = modelTpmLimits?.[`${provider.id}/${provider.model}`] ?? 0
            return usage < provider.tpmLimit * 1_000_000
          })
-          .filter((provider) => {
-            if (!provider.tpsGoal) return true
-            const isLowTps = modelTpsLimits?.[`${provider.id}/${provider.model}`] ?? false
-            return !isLowTps
-          })
          .map((provider) => {
            topPriority = Math.min(topPriority, provider.priority)
            return provider
@@ -1,89 +0,0 @@
-import { and, Database, inArray, sql } from "@opencode-ai/console-core/drizzle/index.js"
-import { ModelTpsRateLimitTable } from "@opencode-ai/console-core/schema/ip.sql.js"
-import { UsageInfo } from "./provider/provider"
-
-export function createModelTpsLimiter(providers: { id: string; model: string; tpsGoal?: number }[]) {
-  const tpsGoals = Object.fromEntries(
-    providers.flatMap((p) => {
-      return p.tpsGoal ? [[`${p.id}/${p.model}`, p.tpsGoal]] : []
-    }),
-  )
-  const ids = Object.keys(tpsGoals)
-  if (ids.length === 0) return
-
-  const toInterval = (date: Date) =>
-    parseInt(
-      date
-        .toISOString()
-        .replace(/[^0-9]/g, "")
-        .substring(0, 12),
-    )
-  const now = Date.now()
-  const currInterval = toInterval(new Date(now))
-  const prevInterval = toInterval(new Date(now - 60 * 1000))
-
-  return {
-    check: async () => {
-      const data = await Database.use((tx) =>
-        tx
-          .select()
-          .from(ModelTpsRateLimitTable)
-          .where(
-            and(
-              inArray(ModelTpsRateLimitTable.id, ids),
-              inArray(ModelTpsRateLimitTable.interval, [currInterval, prevInterval]),
-            ),
-          ),
-      )
-
-      // convert to map of model to summed count across current and previous intervals
-      const result = data.reduce(
-        (acc, curr) => {
-          const existing = acc[curr.id] ?? { qualify: 0, unqualify: 0 }
-          acc[curr.id] = {
-            qualify: existing.qualify + curr.qualify,
-            unqualify: existing.unqualify + curr.unqualify,
-          }
-          return acc
-        },
-        {} as Record<string, { qualify: number; unqualify: number }>,
-      )
-
-      return Object.fromEntries(
-        Object.entries(result).map(([id, { qualify, unqualify }]) => {
-          const isLowTps = qualify + unqualify > 10 && qualify < unqualify
-          return [id, isLowTps]
-        }),
-      )
-    },
-    track: async (provider: string, model: string, tsFirstByte: number, tsLastByte: number, usageInfo: UsageInfo) => {
-      const id = `${provider}/${model}`
-      if (!ids.includes(id)) return
-      const tpsGoal = tpsGoals[id]
-      if (!tpsGoal) return
-      if (tsFirstByte <= 0 || tsLastByte <= 0) return
-      const tokens = usageInfo.outputTokens
-      if (tokens <= 10) return
-
-      const tps = (tokens / (tsLastByte - tsFirstByte)) * 1000
-      const qualify = tps >= tpsGoal ? 1 : 0
-      const unqualify = tps < tpsGoal ? 1 : 0
-      await Database.use((tx) =>
-        tx
-          .insert(ModelTpsRateLimitTable)
-          .values({
-            id,
-            interval: currInterval,
-            qualify,
-            unqualify,
-          })
-          .onDuplicateKeyUpdate({
-            set: {
-              qualify: sql`${ModelTpsRateLimitTable.qualify} + ${qualify}`,
-              unqualify: sql`${ModelTpsRateLimitTable.unqualify} + ${unqualify}`,
-            },
-          }),
-      )
-    },
-  }
-}
@@ -1,7 +0,0 @@
-CREATE TABLE `model_tps_rate_limit` (
-	`id` varchar(255) NOT NULL,
-	`interval` bigint NOT NULL,
-	`qualify` int NOT NULL,
-	`unqualify` int NOT NULL,
-	CONSTRAINT PRIMARY KEY(`id`,`interval`)
-);
@@ -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",
@@ -36,7 +36,6 @@ export namespace ZenData {
        model: z.string(),
        priority: z.number().optional(),
        tpmLimit: z.number().optional(),
-        tpsGoal: z.number().optional(),
        weight: z.number().optional(),
        disabled: z.boolean().optional(),
        storeModel: z.string().optional(),
@@ -40,14 +40,3 @@ export const ModelTpmRateLimitTable = mysqlTable(
  },
  (table) => [primaryKey({ columns: [table.id, table.interval] })],
 )
-
-export const ModelTpsRateLimitTable = mysqlTable(
-  "model_tps_rate_limit",
-  {
-    id: varchar("id", { length: 255 }).notNull(),
-    interval: bigint("interval", { mode: "number" }).notNull(),
-    qualify: int("qualify").notNull(),
-    unqualify: int("unqualify").notNull(),
-  },
-  (table) => [primaryKey({ columns: [table.id, table.interval] })],
-)
@@ -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",
@@ -20,10 +20,12 @@
    "@ai-sdk/anthropic": "3.0.64",
    "@ai-sdk/openai": "3.0.48",
    "@ai-sdk/openai-compatible": "2.0.37",
+    "@hono/zod-validator": "catalog:",
    "@opencode-ai/console-core": "workspace:*",
    "@opencode-ai/console-resource": "workspace:*",
    "@openauthjs/openauth": "0.0.0-20250322224806",
    "ai": "catalog:",
+    "hono": "catalog:",
    "zod": "catalog:"
  }
 }
@@ -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",
@@ -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",
@@ -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.
 */
@@ -1,4 +1,5 @@
 import { Config } from "effect"
+import { InstallationChannel } from "../installation/version"

 function truthy(key: string) {
  const value = process.env[key]?.toLowerCase()
@@ -10,6 +11,13 @@ function falsy(key: string) {
  return value === "false" || value === "0"
 }

+// Channels where new experiments default to ON (unstable / internal users).
+// Stable channels (`prod`, `latest`) stay opt-in.
+const UNSTABLE_CHANNELS = new Set(["dev", "beta", "local"])
+function unstableDefault(key: string) {
+  return truthy(key) || (!falsy(key) && UNSTABLE_CHANNELS.has(InstallationChannel))
+}
+
 function number(key: string) {
  const value = process.env[key]
  if (!value) return undefined
@@ -48,6 +56,9 @@ export const Flag = {
  OPENCODE_DISABLE_CLAUDE_CODE_PROMPT: OPENCODE_DISABLE_CLAUDE_CODE || truthy("OPENCODE_DISABLE_CLAUDE_CODE_PROMPT"),
  OPENCODE_DISABLE_CLAUDE_CODE_SKILLS,
  OPENCODE_DISABLE_EXTERNAL_SKILLS: truthy("OPENCODE_DISABLE_EXTERNAL_SKILLS"),
+  // Default-on for dev/beta/local; opt-in for stable. Set
+  // OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL=false to force off, =true to force on.
+  OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL: unstableDefault("OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL"),
  OPENCODE_FAKE_VCS: process.env["OPENCODE_FAKE_VCS"],
  OPENCODE_SERVER_PASSWORD: process.env["OPENCODE_SERVER_PASSWORD"],
  OPENCODE_SERVER_USERNAME: process.env["OPENCODE_SERVER_USERNAME"],
@@ -85,7 +96,6 @@ export const Flag = {
  OPENCODE_WORKSPACE_ID: process.env["OPENCODE_WORKSPACE_ID"],
  OPENCODE_EXPERIMENTAL_WORKSPACES: OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_WORKSPACES"),
  OPENCODE_EXPERIMENTAL_EVENT_SYSTEM: OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_EVENT_SYSTEM"),
-  OPENCODE_EXPERIMENTAL_SESSION_SWITCHING: OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_SESSION_SWITCHING"),

  // Evaluated at access time (not module load) because tests, the CLI, and
  // external tooling set these env vars at runtime.
@@ -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",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/enterprise",
-  "version": "1.14.48",
+  "version": "1.14.46",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -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"]
@@ -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",
@@ -70,15 +70,19 @@ Cassettes are normal source files — review them, diff them, commit them.

 ## Request matching

-Replay walks the cassette in record order via an internal cursor: the Nth
-request executed at runtime is served by the Nth recorded interaction, and
-each one is validated as the cursor advances. Request equality is computed
-on canonicalized method, URL, headers, and JSON body (object keys sorted).
+By default, requests match on canonicalized method, URL, headers, and JSON
+body (object keys sorted). Two dispatch strategies are available:

-This is deliberately strict — content-based dispatch was removed because
-it silently returns the first recorded response for repeated identical
-requests, masking state changes that retry/polling/cache-hit tests need to
-observe. If you reorder requests in a test, re-record the cassette.
+- **`match`** (default) — find the first recorded interaction whose request
+  matches the incoming request. Same request twice returns the same response.
+- **`sequential`** — return interactions in the order they were recorded,
+  validating each one matches as the cursor advances. Use for ordered flows
+  where the same URL is hit multiple times with meaningful state changes
+  (pagination, retries, polling).
+
+```ts
+HttpRecorder.cassetteLayer("flow/poll-until-done", { dispatch: "sequential" })
+```

 Supply your own matcher via `match: (incoming, recorded) => boolean` for
 custom equivalence (e.g. ignoring a timestamp field in the body).
@@ -190,6 +194,7 @@ type RecordReplayOptions = {
  directory?: string // default: <cwd>/test/fixtures/recordings
  metadata?: Record<string, unknown> // merged into cassette.metadata
  redactor?: Redactor // default: Redactor.defaults()
+  dispatch?: "match" | "sequential" // default: "match"
  match?: (incoming, recorded) => boolean // custom matcher
 }
 ```
@@ -206,4 +211,4 @@ type RecordReplayOptions = {
 | `redaction.ts` | Lower-level header/URL primitives + secret pattern detection.                    |
 | `schema.ts`    | Effect Schema definitions for the cassette JSON format.                          |
 | `storage.ts`   | Path resolution, JSON encode/decode, sync existence check.                       |
-| `matching.ts`  | Request matcher, canonicalization, sequential cursor, mismatch diagnostics.      |
+| `matching.ts`  | Request matcher, canonicalization, dispatch strategies, mismatch diagnostics.    |
@@ -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",
@@ -11,7 +11,7 @@ import {
  UrlParams,
 } from "effect/unstable/http"
 import * as CassetteService from "./cassette"
-import { defaultMatcher, selectSequential, type RequestMatcher } from "./matching"
+import { defaultMatcher, selectMatch, selectSequential, type RequestMatcher } from "./matching"
 import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
 import { defaults, type Redactor } from "./redactor"
 import { redactUrl } from "./redaction"
@@ -24,6 +24,7 @@ export interface RecordReplayOptions {
  readonly directory?: string
  readonly metadata?: CassetteMetadata
  readonly redactor?: Redactor
+  readonly dispatch?: "match" | "sequential"
  readonly match?: RequestMatcher
 }

@@ -70,6 +71,7 @@ export const recordingLayer = (
      const match = options.match ?? defaultMatcher
      const requested = options.mode ?? "auto"
      const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
+      const sequential = options.dispatch === "sequential"
      const replay = yield* makeReplayState(cassetteService, name, httpInteractions)

      const snapshotRequest = (request: HttpClientRequest.HttpClientRequest) =>
@@ -117,12 +119,14 @@ export const recordingLayer = (
              transportError(request, `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`),
            ),
          )
-          const result = selectSequential(interactions, incoming, match, yield* replay.cursor)
+          const result = sequential
+            ? selectSequential(interactions, incoming, match, yield* replay.cursor)
+            : selectMatch(interactions, incoming, match)
          if (!result.interaction)
            return yield* Effect.fail(
              transportError(request, `Fixture "${name}" does not match the current request: ${result.detail}.`),
            )
-          yield* replay.advance
+          if (sequential) yield* replay.advance
          return HttpClientResponse.fromWeb(
            request,
            new Response(decodeResponseBody(result.interaction.response), result.interaction.response),
@@ -92,6 +92,24 @@ export const requestDiff = (expected: RequestSnapshot, received: RequestSnapshot
  return lines
 }

+export const mismatchDetail = (interactions: ReadonlyArray<HttpInteraction>, incoming: RequestSnapshot): string => {
+  if (interactions.length === 0) return "cassette has no recorded HTTP interactions"
+  const ranked = interactions
+    .map((interaction, index) => ({ index, lines: requestDiff(interaction.request, incoming) }))
+    .toSorted((a, b) => a.lines.length - b.lines.length || a.index - b.index)
+  const best = ranked[0]
+  return ["no recorded interaction matched", `closest interaction: #${best.index + 1}`, ...best.lines].join("\n")
+}
+
+export const selectMatch = (
+  interactions: ReadonlyArray<HttpInteraction>,
+  incoming: RequestSnapshot,
+  match: RequestMatcher,
+): { readonly interaction: HttpInteraction | undefined; readonly detail: string } => {
+  const interaction = interactions.find((candidate) => match(incoming, candidate.request))
+  return { interaction, detail: interaction ? "" : mismatchDetail(interactions, incoming) }
+}
+
 export const selectSequential = (
  interactions: ReadonlyArray<HttpInteraction>,
  incoming: RequestSnapshot,
@@ -230,10 +230,19 @@ describe("http-recorder", () => {
    )
  })

-  test("replay returns recorded responses in order for identical requests", async () => {
+  test("default matcher dispatches multi-interaction cassettes by request shape", async () => {
+    await run(
+      Effect.gen(function* () {
+        expect(yield* post("https://example.test/echo", { step: 2 })).toBe('{"reply":"second"}')
+        expect(yield* post("https://example.test/echo", { step: 1 })).toBe('{"reply":"first"}')
+      }),
+    )
+  })
+
+  test("sequential dispatch returns recorded responses in order for identical requests", async () => {
    await runWith(
      "record-replay/retry",
-      {},
+      { dispatch: "sequential" },
      Effect.gen(function* () {
        expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"pending"}')
        expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"complete"}')
@@ -241,8 +250,21 @@ describe("http-recorder", () => {
    )
  })

-  test("replay reports cursor exhaustion when more requests are made than recorded", async () => {
-    await run(
+  test("default matcher returns the first match for identical requests", async () => {
+    await runWith(
+      "record-replay/retry",
+      {},
+      Effect.gen(function* () {
+        expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"pending"}')
+        expect(yield* post("https://example.test/poll", { id: "job_1" })).toBe('{"status":"pending"}')
+      }),
+    )
+  })
+
+  test("sequential dispatch reports cursor exhaustion when more requests are made than recorded", async () => {
+    await runWith(
+      "record-replay/multi-step",
+      { dispatch: "sequential" },
      Effect.gen(function* () {
        yield* post("https://example.test/echo", { step: 1 })
        yield* post("https://example.test/echo", { step: 2 })
@@ -252,8 +274,10 @@ describe("http-recorder", () => {
    )
  })

-  test("replay validates each recorded request in order", async () => {
-    await run(
+  test("sequential dispatch still validates each recorded request", async () => {
+    await runWith(
+      "record-replay/multi-step",
+      { dispatch: "sequential" },
      Effect.gen(function* () {
        yield* post("https://example.test/echo", { step: 1 })
        const exit = yield* Effect.exit(post("https://example.test/echo", { step: 3 }))
@@ -307,13 +331,14 @@ describe("http-recorder", () => {
    }
  })

-  test("mismatch diagnostics show redacted request differences against the expected interaction", async () => {
+  test("mismatch diagnostics show closest redacted request differences", async () => {
    await run(
      Effect.gen(function* () {
        const exit = yield* Effect.exit(
          post("https://example.test/echo?api_key=secret-value", { step: 3, token: "sk-123456789012345678901234" }),
        )
        const message = failureText(exit)
+        expect(message).toContain("closest interaction: #1")
        expect(message).toContain("url:")
        expect(message).toContain("https://example.test/echo?api_key=%5BREDACTED%5D")
        expect(message).toContain("body:")
@@ -8,10 +8,6 @@
 - In `Effect.gen`, yield yieldable errors directly (`return yield* new MyError(...)`) instead of `Effect.fail(new MyError(...))`.
 - Use `Effect.void` instead of `Effect.succeed(undefined)` when the successful value is intentionally void.

-## Conventions
-
-Per-type constructors live on the type's namespace, not as top-level re-exports. Use `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for the request-shaped call API: `LLM.request`, `LLM.generate`, `LLM.stream`, `LLM.model`, `LLM.updateRequest`, `LLM.generateObject`. Two ways to construct the same thing is one too many.
-
 ## Tests

 - Use `testEffect(...)` from `test/lib/effect.ts` for tests requiring Effect layers.
@@ -170,12 +166,12 @@ If you find yourself copying a 3-to-5-line snippet between two protocols, lift i
 Tool loops are represented in common messages and events:

 ```ts
-const call = ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })
-const result = Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } })
+const call = LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })
+const result = LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } })

 const followUp = LLM.request({
  model,
-  messages: [Message.user("Weather?"), Message.assistant([call]), result],
+  messages: [LLM.user("Weather?"), LLM.assistant([call]), result],
 })
 ```

@@ -293,6 +289,6 @@ Filters apply in replay and record mode. Combine them with `RECORD=true` when re

 **Binary response bodies.** Most providers stream text (SSE, JSON). AWS Bedrock streams binary AWS event-stream frames whose CRC32 fields would be mangled by a UTF-8 round-trip — those bodies are stored as base64 with `bodyEncoding: "base64"` on the response snapshot. Detection is by `Content-Type` in `@opencode-ai/http-recorder` (currently `application/vnd.amazon.eventstream` and `application/octet-stream`); cassettes for SSE/JSON routes omit the field and decode as text.

-**Matching strategy.** Replay walks the cassette in record order via an internal cursor: the Nth runtime request is served by the Nth recorded interaction, and each one is validated by comparing method, URL, allow-listed headers, and the canonical JSON body. This handles tool loops (each round's request differs as history grows) and retry/polling scenarios (successive byte-identical requests with different responses) uniformly. If a test reorders its requests, re-record the cassette. `scriptedResponses` (in `test/lib/http.ts`) is the deterministic counterpart for tests that don't need a live provider; it scripts response bodies in order without reading from disk.
+**Matching strategies.** Replay defaults to structural matching, which finds an interaction by comparing method, URL, allow-listed headers, and the canonical JSON body. This is the right choice for tool loops because each round's request differs (the message history grows). For scenarios where successive requests are byte-identical and expect different responses (retries, polling), pass `dispatch: "sequential"` in `RecordReplayOptions` — replay then walks the cassette in record order via an internal cursor. `scriptedResponses` (in `test/lib/http.ts`) is the deterministic counterpart for tests that don't need a live provider; it scripts response bodies in order without reading from disk.

 Do not blanket re-record an entire test file when adding one cassette. `RECORD=true` rewrites every recorded case that runs, and provider streams contain volatile IDs, timestamps, fingerprints, and obfuscation fields. Prefer deleting the one cassette you intend to refresh, or run a focused test pattern that only registers the scenario you want to record. Keep stable existing cassettes unchanged unless their request shape or expected behavior changed.
@@ -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
@@ -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",
@@ -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 })
-}
@@ -44,8 +44,32 @@ export type RequestInput = Omit<

 export const limits = modelLimits

+export const text = Message.text
+
+export const system = SystemPart.make
+
+export const message = Message.make
+
+export const user = Message.user
+
+export const assistant = Message.assistant
+
 export const model = modelRef

+export const toolDefinition = ToolDefinition.make
+
+export const toolCall = ToolCallPart.make
+
+export const toolResult = ToolResultPart.make
+
+export const toolMessage = Message.tool
+
+export const toolChoiceName = ToolChoice.named
+
+export const toolChoice = ToolChoice.make
+
+export const generation = GenerationOptions.make
+
 export const generate = LLMClient.generate

 export const stream = LLMClient.stream
@@ -71,10 +95,10 @@ export const request = (input: RequestInput) => {
  return new LLMRequest({
    ...rest,
    system: SystemPart.content(requestSystem),
-    messages: [...(messages?.map(Message.make) ?? []), ...(prompt === undefined ? [] : [Message.user(prompt)])],
-    tools: tools?.map(ToolDefinition.make) ?? [],
-    toolChoice: requestToolChoice ? ToolChoice.make(requestToolChoice) : undefined,
-    generation: requestGeneration === undefined ? undefined : GenerationOptions.make(requestGeneration),
+    messages: [...(messages?.map(message) ?? []), ...(prompt === undefined ? [] : [user(prompt)])],
+    tools: tools?.map(toolDefinition) ?? [],
+    toolChoice: requestToolChoice ? toolChoice(requestToolChoice) : undefined,
+    generation: requestGeneration === undefined ? undefined : generation(requestGeneration),
    providerOptions: requestProviderOptions,
    http: requestHttp === undefined ? undefined : HttpOptions.make(requestHttp),
  })
@@ -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 },
  })
 }

@@ -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,
  })
 }

@@ -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,
  })
 }

@@ -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,
  })
 }

@@ -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,
  })
 }

@@ -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",
@@ -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"
@@ -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
@@ -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)

@@ -3,70 +3,15 @@ import { ContentBlockID, FinishReason, ProtocolID, ProviderMetadata, ResponseID,
 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"),
@@ -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,
  })

@@ -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>
@@ -1,266 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { Effect } from "effect"
-import { CacheHint, LLM, Message } 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: [
-            Message.user("first user"),
-            Message.assistant("assistant reply"),
-            Message.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: [Message.user("first user"), Message.assistant("reply"), Message.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: [Message.user("u1"), Message.assistant("a1"), Message.user("u2"), Message.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: [Message.user("u1"), Message.assistant("a1"), Message.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)
-  })
-})
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { LLM, LLMResponse } from "../src"
-import { LLMRequest, Message, ModelRef, ToolCallPart, ToolChoice, ToolDefinition, ToolResultPart } from "../src/schema"
+import { LLMRequest, Message, ModelRef, ToolChoice, ToolDefinition } from "../src/schema"

 describe("llm constructors", () => {
  test("builds canonical schema classes from ergonomic input", () => {
@@ -28,7 +28,7 @@ describe("llm constructors", () => {
    })
    const updated = LLM.updateRequest(base, {
      generation: { maxTokens: 20 },
-      messages: [...base.messages, Message.assistant("Hi.")],
+      messages: [...base.messages, LLM.assistant("Hi.")],
    })

    expect(updated).toBeInstanceOf(LLMRequest)
@@ -70,7 +70,7 @@ describe("llm constructors", () => {
      model: LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" }),
      prompt: "Say hello.",
    })
-    const updated = LLMRequest.update(base, { messages: [...base.messages, Message.assistant("Hi.")] })
+    const updated = LLMRequest.update(base, { messages: [...base.messages, LLM.assistant("Hi.")] })

    expect(updated).toBeInstanceOf(LLMRequest)
    expect(updated.id).toBe("req_1")
@@ -91,18 +91,18 @@ describe("llm constructors", () => {
  })

  test("builds tool choices from names and tools", () => {
-    const tool = ToolDefinition.make({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })
+    const tool = LLM.toolDefinition({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })

    expect(tool).toBeInstanceOf(ToolDefinition)
-    expect(ToolChoice.make("lookup")).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
-    expect(ToolChoice.named("required")).toEqual(new ToolChoice({ type: "tool", name: "required" }))
-    expect(ToolChoice.make(tool)).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
+    expect(LLM.toolChoice("lookup")).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
+    expect(LLM.toolChoiceName("required")).toEqual(new ToolChoice({ type: "tool", name: "required" }))
+    expect(LLM.toolChoice(tool)).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
  })

  test("builds tool choice modes from reserved strings", () => {
-    expect(ToolChoice.make("auto")).toEqual(new ToolChoice({ type: "auto" }))
-    expect(ToolChoice.make("none")).toEqual(new ToolChoice({ type: "none" }))
-    expect(ToolChoice.make("required")).toEqual(new ToolChoice({ type: "required" }))
+    expect(LLM.toolChoice("auto")).toEqual(new ToolChoice({ type: "auto" }))
+    expect(LLM.toolChoice("none")).toEqual(new ToolChoice({ type: "none" }))
+    expect(LLM.toolChoice("required")).toEqual(new ToolChoice({ type: "required" }))
    expect(
      LLM.request({
        model: LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" }),
@@ -113,11 +113,11 @@ describe("llm constructors", () => {
  })

  test("builds assistant tool calls and tool result messages", () => {
-    const call = ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })
-    const result = ToolResultPart.make({ id: "call_1", name: "lookup", result: { temperature: 72 } })
+    const call = LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })
+    const result = LLM.toolResult({ id: "call_1", name: "lookup", result: { temperature: 72 } })

-    expect(Message.assistant([call]).content).toEqual([call])
-    expect(Message.tool(result).content).toEqual([
+    expect(LLM.assistant([call]).content).toEqual([call])
+    expect(LLM.toolMessage(result).content).toEqual([
      { type: "tool-result", id: "call_1", name: "lookup", result: { type: "json", value: { temperature: 72 } } },
    ])
  })
@@ -1,55 +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 — replay walks the cassette in
-  // recording order so the second call replays the cached-hit interaction.
-  options: {
-    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)
-    }),
-  )
-})
@@ -1,7 +1,7 @@
 import { Redactor } from "@opencode-ai/http-recorder"
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMError, Message, ToolCallPart } from "../../src"
+import { LLM, LLMError } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
 import { weatherToolName } from "../recorded-scenarios"
@@ -16,12 +16,12 @@ const malformedToolOrderRequest = LLM.request({
  id: "recorded_anthropic_malformed_tool_order",
  model,
  messages: [
-    Message.assistant([
-      ToolCallPart.make({ id: "call_1", name: weatherToolName, input: { city: "Paris" } }),
+    LLM.assistant([
+      LLM.toolCall({ id: "call_1", name: weatherToolName, input: { city: "Paris" } }),
      { type: "text", text: "I will check the weather." },
    ]),
-    Message.tool({ id: "call_1", name: weatherToolName, result: { temperature: "72F" } }),
-    Message.user("Use that result to answer briefly."),
+    LLM.toolMessage({ id: "call_1", name: weatherToolName, result: { temperature: "72F" } }),
+    LLM.user("Use that result to answer briefly."),
  ],
  tools: [{ name: weatherToolName, description: "Get weather", inputSchema: { type: "object", properties: {} } }],
 })
@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { CacheHint, LLM, LLMError, Message, ToolCallPart, 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 },
 })

@@ -47,11 +44,10 @@ describe("Anthropic Messages route", () => {
          id: "req_tool_result",
          model,
          messages: [
-            Message.user("What is the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
-            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
-          cache: "none",
        }),
      )

@@ -77,7 +73,7 @@ describe("Anthropic Messages route", () => {
        LLM.request({
          model,
          messages: [
-            Message.assistant([
+            LLM.assistant([
              { type: "reasoning", text: "thinking", providerMetadata: { anthropic: { signature: "sig_1" } } },
            ]),
          ],
@@ -114,11 +110,10 @@ 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({
        providerMetadata: { anthropic: { signature: "sig_1" } },
@@ -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 } },
        },
      ])
    }),
@@ -304,8 +293,8 @@ describe("Anthropic Messages route", () => {
          id: "req_round_trip",
          model,
          messages: [
-            Message.user("Search for something."),
-            Message.assistant([
+            LLM.user("Search for something."),
+            LLM.assistant([
              {
                type: "tool-call",
                id: "srvtoolu_abc",
@@ -322,7 +311,7 @@ describe("Anthropic Messages route", () => {
              },
              { type: "text", text: "Found it." },
            ]),
-            Message.user("Thanks."),
+            LLM.user("Thanks."),
          ],
        }),
      )
@@ -355,7 +344,7 @@ describe("Anthropic Messages route", () => {
          id: "req_unknown_server_tool",
          model,
          messages: [
-            Message.assistant([
+            LLM.assistant([
              {
                type: "tool-result",
                id: "srvtoolu_abc",
@@ -378,141 +367,11 @@ describe("Anthropic Messages route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [Message.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
        }),
      ).pipe(Effect.flip)

      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: [
-            Message.user("What's the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })]),
-            Message.tool({
-              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: [Message.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()
-    }),
-  )
 })
@@ -1,55 +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 — replay walks the cassette in
-  // recording order so the second call replays the cached-hit interaction.
-})
-
-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)
-    }),
-  )
-})
@@ -2,7 +2,7 @@ import { EventStreamCodec } from "@smithy/eventstream-codec"
 import { fromUtf8, toUtf8 } from "@smithy/util-utf8"
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { CacheHint, LLM, Message, ToolCallPart, ToolChoice } from "../../src"
+import { CacheHint, LLM } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as BedrockConverse from "../../src/protocols/bedrock-converse"
 import { it } from "../lib/effect"
@@ -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 },
 })

@@ -94,7 +91,7 @@ describe("Bedrock Converse route", () => {
              inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
            },
          ],
-          toolChoice: ToolChoice.make({ type: "required" }),
+          toolChoice: LLM.toolChoice({ type: "required" }),
        }),
      )

@@ -124,11 +121,10 @@ describe("Bedrock Converse route", () => {
          id: "req_history",
          model,
          messages: [
-            Message.user("What is the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "tool_1", name: "lookup", input: { query: "weather" } })]),
-            Message.tool({ id: "tool_1", name: "lookup", result: { forecast: "sunny" } }),
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "tool_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "tool_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
-          cache: "none",
        }),
      )

@@ -294,8 +290,8 @@ describe("Bedrock Converse route", () => {
          model,
          system: [{ type: "text", text: "System prefix.", cache }],
          messages: [
-            Message.user([{ type: "text", text: "User prefix.", cache }]),
-            Message.assistant([{ type: "text", text: "Assistant prefix.", cache }]),
+            LLM.user([{ type: "text", text: "User prefix.", cache }]),
+            LLM.assistant([{ type: "text", text: "Assistant prefix.", cache }]),
          ],
          generation: { maxTokens: 16, temperature: 0 },
        }),
@@ -335,7 +331,7 @@ describe("Bedrock Converse route", () => {
          id: "req_image",
          model,
          messages: [
-            Message.user([
+            LLM.user([
              { type: "text", text: "What is in this image?" },
              { type: "media", mediaType: "image/png", data: "AAAA" },
              { type: "media", mediaType: "image/jpeg", data: "BBBB" },
@@ -343,7 +339,6 @@ describe("Bedrock Converse route", () => {
              { type: "media", mediaType: "image/webp", data: "DDDD" },
            ]),
          ],
-          cache: "none",
        }),
      )

@@ -371,7 +366,7 @@ describe("Bedrock Converse route", () => {
        LLM.request({
          id: "req_image_bytes",
          model,
-          messages: [Message.user([{ type: "media", mediaType: "image/png", data: new Uint8Array([1, 2, 3, 4, 5]) }])],
+          messages: [LLM.user([{ type: "media", mediaType: "image/png", data: new Uint8Array([1, 2, 3, 4, 5]) }])],
        }),
      )

@@ -394,7 +389,7 @@ describe("Bedrock Converse route", () => {
          id: "req_doc",
          model,
          messages: [
-            Message.user([
+            LLM.user([
              { type: "media", mediaType: "application/pdf", data: "PDFDATA", filename: "report.pdf" },
              { type: "media", mediaType: "text/csv", data: "CSVDATA" },
            ]),
@@ -424,7 +419,7 @@ describe("Bedrock Converse route", () => {
        LLM.request({
          id: "req_bad_image",
          model,
-          messages: [Message.user([{ type: "media", mediaType: "image/svg+xml", data: "x" }])],
+          messages: [LLM.user([{ type: "media", mediaType: "image/svg+xml", data: "x" }])],
        }),
      ).pipe(Effect.flip)

@@ -438,85 +433,13 @@ describe("Bedrock Converse route", () => {
        LLM.request({
          id: "req_bad_doc",
          model,
-          messages: [Message.user([{ type: "media", mediaType: "application/x-tar", data: "x", filename: "a.tar" }])],
+          messages: [LLM.user([{ type: "media", mediaType: "application/x-tar", data: "x", filename: "a.tar" }])],
        }),
      ).pipe(Effect.flip)

      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: [
-            Message.user("What's the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })]),
-            Message.tool({ 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 },
        }),
      )
@@ -583,8 +505,7 @@ describe("Bedrock Converse recorded", () => {
          system: "Call tools exactly as requested.",
          prompt: "Call get_weather with city exactly Paris.",
          tools: [weatherTool],
-          toolChoice: ToolChoice.make(weatherTool),
-          cache: "none",
+          toolChoice: LLM.toolChoice(weatherTool),
          generation: { maxTokens: 80, temperature: 0 },
        }),
      )
@@ -1,49 +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 — replay walks the cassette in
-  // recording order so the second call replays the cached-hit interaction.
-})
-
-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)
-    }),
-  )
-})
@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMError, Message, ToolCallPart, 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"
@@ -49,12 +49,12 @@ describe("Gemini route", () => {
          ],
          toolChoice: { type: "tool", name: "lookup" },
          messages: [
-            Message.user([
+            LLM.user([
              { type: "text", text: "What is in this image?" },
              { type: "media", mediaType: "image/png", data: "AAECAw==" },
            ]),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
-            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
        }),
      )
@@ -198,10 +198,9 @@ 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([
@@ -211,23 +210,20 @@ describe("Gemini route", () => {
        {
          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 },
+          },
        },
      ])
    }),
@@ -353,7 +348,7 @@ describe("Gemini route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [Message.assistant({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [LLM.assistant({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
        }),
      ).pipe(Effect.flip)

@@ -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, Message, ToolCallPart, 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"
@@ -149,9 +149,9 @@ describe("OpenAI Chat route", () => {
          id: "req_tool_result",
          model,
          messages: [
-            Message.user("What is the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
-            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
        }),
      )
@@ -185,7 +185,7 @@ describe("OpenAI Chat route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [Message.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
        }),
      ).pipe(Effect.flip)

@@ -199,7 +199,7 @@ describe("OpenAI Chat route", () => {
        LLM.request({
          id: "req_reasoning",
          model,
-          messages: [Message.assistant({ type: "reasoning", text: "hidden" })],
+          messages: [LLM.assistant({ type: "reasoning", text: "hidden" })],
        }),
      ).pipe(Effect.flip)

@@ -230,23 +230,20 @@ describe("OpenAI Chat route", () => {
        {
          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 },
            },
-          }),
+          },
        },
      ])
    }),
@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { Effect, Schema } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
-import { LLM, Message, ToolCallPart } from "../../src"
+import { LLM } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as OpenAICompatible from "../../src/providers/openai-compatible"
 import * as OpenAICompatibleChat from "../../src/protocols/openai-compatible-chat"
@@ -157,9 +157,9 @@ describe("OpenAI-compatible Chat route", () => {
          ],
          toolChoice: "lookup",
          messages: [
-            Message.user("What is the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
-            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
        }),
      )
@@ -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 — replay walks the cassette in
-  // recording order so the second call replays the cached-hit interaction,
-  // not the cold-miss one.
-})
-
-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)
-    }),
-  )
-})
@@ -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, Message, ToolCallPart, 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"
@@ -251,9 +251,9 @@ describe("OpenAI Responses route", () => {
          id: "req_tool_result",
          model,
          messages: [
-            Message.user("What is the weather?"),
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
-            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
        }),
      )
@@ -342,23 +342,20 @@ describe("OpenAI Responses route", () => {
          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 },
            },
-          }),
+          },
        },
      ])
    }),
@@ -414,13 +411,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 } },
        },
      ])
    }),
@@ -508,7 +499,7 @@ describe("OpenAI Responses route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [Message.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
        }),
      ).pipe(Effect.flip)

@@ -1,24 +1,12 @@
 import { expect } from "bun:test"
 import { Effect, Schema, Stream } from "effect"
-import { LLM, LLMEvent, LLMResponse, ToolChoice, ToolDefinition, type LLMRequest, type ModelRef } from "../src"
+import { LLM, LLMEvent, LLMResponse, type LLMRequest, type ModelRef } from "../src"
 import { LLMClient } from "../src/route"
 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 = ToolDefinition.make({
+export const weatherTool = LLM.toolDefinition({
  name: weatherToolName,
  description: "Get current weather for a city.",
  inputSchema: {
@@ -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 }
@@ -70,8 +57,7 @@ export const weatherToolRequest = (input: {
    system: "Call tools exactly as requested.",
    prompt: "Call get_weather with city exactly Paris.",
    tools: [weatherTool],
-    toolChoice: ToolChoice.make(weatherTool),
-    cache: "none",
+    toolChoice: LLM.toolChoice(weatherTool),
    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 }
@@ -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)
-  })
-})
@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect, Schema, Stream } from "effect"
-import { GenerationOptions, LLM, LLMEvent, LLMRequest, LLMResponse, ToolChoice } from "../src"
+import { LLM, LLMEvent, LLMRequest, LLMResponse } from "../src"
 import { LLMClient } from "../src/route"
 import * as AnthropicMessages from "../src/protocols/anthropic-messages"
 import * as OpenAIChat from "../src/protocols/openai-chat"
@@ -78,8 +78,8 @@ describe("LLMClient tools", () => {

      yield* TestToolRuntime.runTools({
        request: LLMRequest.update(baseRequest, {
-          generation: GenerationOptions.make({ maxTokens: 50 }),
-          toolChoice: ToolChoice.make("auto"),
+          generation: LLM.generation({ maxTokens: 50 }),
+          toolChoice: LLM.toolChoice("auto"),
        }),
        tools: { get_weather },
      }).pipe(Stream.runCollect, Effect.provide(layer))
@@ -1,4 +0,0 @@
-CREATE TABLE `data_migration` (
-	`name` text PRIMARY KEY,
-	`time_completed` integer NOT NULL
-);
@@ -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",
@@ -286,15 +286,5 @@ export default {
        ],
      },
    },
-    {
-      filetype: "diff",
-      aliases: ["udiff", "patch"],
-      wasm: "https://github.com/tree-sitter-grammars/tree-sitter-diff/releases/download/v0.1.0/tree-sitter-diff.wasm",
-      queries: {
-        highlights: [
-          "https://raw.githubusercontent.com/tree-sitter-grammars/tree-sitter-diff/master/queries/highlights.scm",
-        ],
-      },
-    },
  ],
 }
@@ -2,11 +2,7 @@

 import { z } from "zod"
 import { Config } from "@/config/config"
-import { zodObject } from "@opencode-ai/core/effect-zod"
-import { TuiJsonSchema } from "../src/cli/cmd/tui/config/tui-json-schema"
-import { Schema } from "effect"
-
-type JsonSchema = Record<string, unknown>
+import { TuiConfig } from "../src/cli/cmd/tui/config/tui"

 function generate(schema: z.ZodType) {
  const result = z.toJSONSchema(schema, {
@@ -37,7 +33,7 @@ function generate(schema: z.ZodType) {
          schema.examples = [schema.default]
        }

-        schema.description = [schema.description || "", `default: \`${formatDefault(schema.default)}\``]
+        schema.description = [schema.description || "", `default: \`${String(schema.default)}\``]
          .filter(Boolean)
          .join("\n\n")
          .trim()
@@ -55,62 +51,13 @@ function generate(schema: z.ZodType) {
  return result
 }

-function formatDefault(value: unknown) {
-  if (typeof value !== "object" || value === null) return String(value)
-  return JSON.stringify(value)
-}
-
-function generateEffect(schema: Schema.Top) {
-  const document = Schema.toJsonSchemaDocument(schema)
-  const normalized = normalize({
-    $schema: "https://json-schema.org/draft/2020-12/schema",
-    ...document.schema,
-    $defs: document.definitions,
-  })
-  if (!isRecord(normalized)) throw new Error("schema generator produced a non-object schema")
-  normalized.allowComments = true
-  normalized.allowTrailingCommas = true
-  return normalized
-}
-
-function normalize(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(normalize)
-  if (!isRecord(value)) return value
-
-  const schema = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, normalize(item)]))
-
-  if (Array.isArray(schema.anyOf)) {
-    const anyOf = schema.anyOf.filter((item) => !isRecord(item) || item.type !== "null")
-    if (anyOf.length !== schema.anyOf.length) {
-      const { anyOf: _, ...rest } = schema
-      if (anyOf.length === 1 && isRecord(anyOf[0])) return normalize({ ...anyOf[0], ...rest })
-      return { ...rest, anyOf }
-    }
-  }
-
-  if (Array.isArray(schema.allOf) && schema.allOf.length === 1 && isRecord(schema.allOf[0])) {
-    const { allOf: _, ...rest } = schema
-    return normalize({ ...schema.allOf[0], ...rest })
-  }
-
-  if (schema.type === "integer" && schema.maximum === undefined) {
-    return { ...schema, maximum: Number.MAX_SAFE_INTEGER }
-  }
-
-  return schema
-}
-
-function isRecord(value: unknown): value is JsonSchema {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
 const configFile = process.argv[2]
 const tuiFile = process.argv[3]

 console.log(configFile)
-await Bun.write(configFile, JSON.stringify(generate(zodObject(Config.Info).strict().meta({ ref: "Config" })), null, 2))
+await Bun.write(configFile, JSON.stringify(generate(Config.Info.zod), null, 2))

 if (tuiFile) {
  console.log(tuiFile)
-  await Bun.write(tuiFile, JSON.stringify(generateEffect(TuiJsonSchema.Info), null, 2))
+  await Bun.write(tuiFile, JSON.stringify(generate(TuiConfig.JsonSchemaInfo), null, 2))
 }
@@ -23,9 +23,8 @@ contracts.
 - Some services already use `Schema.TaggedErrorClass`, for example `Account`,
  `Auth`, `Permission`, `Question`, `Installation`, and parts of
  `Workspace`.
- The temporary HttpApi compatibility middleware recognizes `NamedError`,
-  `Session.BusyError`, and a few name-based cases, then emits the legacy
-  `{ name, data }` JSON body.
+- Legacy Hono error handling recognizes `NamedError`, `Session.BusyError`, and a
+  few name-based cases, then emits the legacy `{ name, data }` JSON body.
 - Effect `HttpApi` only knows how to encode errors that are declared on the
  endpoint, group, or middleware. Undeclared expected errors become defects and
  eventually fall through to generic HTTP handling.
@@ -128,7 +127,7 @@ Create an HttpApi-local error module, likely
 That module should provide:

 - Legacy-compatible public schemas for `{ name, data }` error bodies that must
-  remain SDK-compatible while route groups declare typed errors.
+  remain SDK-compatible during the Hono migration.
 - Small constructors or mapping helpers for common API errors such as not found,
  bad request, conflict, and unknown internal errors.
 - Route-group-specific adapters only when they encode domain-specific public
@@ -174,7 +173,7 @@ Add the `httpapi/errors.ts` module before converting route groups.
 - Define a legacy `{ name, data }` body helper for SDK-compatible errors.
 - Define `UnknownError` for generic internal failures with a safe public message.
 - Define `BadRequestError` and `NotFoundError` equivalents only if the actual
-  wire body must match the existing SDK surface.
+  wire body must match the legacy Hono SDK surface.
 - Put the HTTP status on the public schema with `HttpApiSchema.status(...)` or
  `{ httpApiStatus: code }`; do not keep a separate name-to-status table.
 - Keep conversion helpers pure and small. They should not inspect `Cause` or
@@ -239,7 +238,7 @@ Suggested route order:
 2. `experimental` worktree mutations.
 3. `provider` auth and model selection errors.
 4. `mcp` OAuth and connection errors.
-5. Remaining route groups as typed error contracts are declared.
+5. Remaining route groups as Hono deletion work progresses.

 ### 6. Remove Defect Recovery

@@ -287,8 +286,8 @@ For HttpApi conversions:
  errors.
 - Add a regression test that the temporary middleware is no longer needed for the
  migrated route.
- Keep compatibility tests aligned with the existing SDK contract until the
-  public error shape intentionally changes.
+- Keep bridge/parity tests aligned with legacy Hono behavior until Hono is
+  deleted or the SDK contract intentionally changes.

 ## Verification Commands

@@ -39,19 +39,26 @@ This eliminates multiple `runPromise` round-trips and lets handlers compose natu

 ## Current route files

-Current instance route files live under `src/server/routes/instance/httpapi`.
-Most handlers already yield stable services at route-layer construction and then
-close over those services in endpoint implementations.
+Current instance route files live under `src/server/routes/instance`.
+
+Files that are already mostly on the intended service-yielding shape:
+
+- [x] `server/routes/instance/question.ts` — handlers yield `Question.Service`
+- [x] `server/routes/instance/provider.ts` — handlers yield `Provider.Service`, `ProviderAuth.Service`, and `Config.Service`
+- [x] `server/routes/instance/permission.ts` — handlers yield `Permission.Service`
+- [x] `server/routes/instance/mcp.ts` — handlers mostly yield `MCP.Service`
+- [x] `server/routes/instance/pty.ts` — handlers yield `Pty.Service`

 Files still worth tracking here:

- [ ] `handlers/session.ts` — still the heaviest mixed file; some paths keep compatibility translations and direct event publication
- [ ] `handlers/experimental.ts` — mixed state; some handlers still rely on request-local context reads
- [ ] `middleware/*` — still contains compatibility policy for auth, compression, errors, instance context, and workspace routing
- [ ] `public.ts` — still owns SDK/OpenAPI compatibility translation shims
- [ ] raw route modules — WebSocket and catch-all routes should stay explicit and avoid rebuilding stable layers per request
+- [ ] `server/routes/instance/session.ts` — still the heaviest mixed file; many handlers are composed, but the file still mixes patterns and has direct `Bus.publish(...)` / `Session.list(...)` usage
+- [ ] `server/routes/instance/index.ts` — mostly converted, but still has direct `Instance.dispose()` / `Instance.*` reads for `/instance/dispose` and `/path`
+- [ ] `server/routes/instance/file.ts` — most handlers yield services, but `/find` still passes `Instance.directory` directly into ripgrep and `/find/symbol` is still stubbed
+- [ ] `server/routes/instance/experimental.ts` — mixed state; many handlers are composed, but some still rely on `runRequest(...)` or direct `Instance.project` reads
+- [ ] `server/routes/instance/middleware.ts` — still enters the instance via `Instance.provide(...)`
+- [ ] `server/routes/global.ts` — still uses `Instance.disposeAll()` and remains partly outside the fully-composed style

 ## Notes

- Route conversion is now less about backend migration and more about removing the remaining direct `Instance.*` reads, request-local service plumbing, and OpenAPI compatibility shims.
- Prefer route-layer service capture over rebuilding or providing stable layers inside individual handlers.
+- Route conversion is now less about facade removal and more about removing the remaining direct `Instance.*` reads, `Instance.provide(...)` boundaries, and small Promise-style bridges inside route files.
+- `jsonRequest(...)` / `runRequest(...)` already provide a good intermediate shape for many handlers. The remaining cleanup is mostly consistency work in the heavier files.
@@ -305,18 +305,38 @@ emitted JSON Schema must stay byte-identical.

 ### HTTP route boundaries

-The server route tree now lives under `src/server/routes/instance/httpapi` and
-uses Effect HttpApi contracts for request and response schemas. Remaining schema
-work is no longer a Hono route migration; it is compatibility cleanup around
-derived `.zod` statics, OpenAPI translation shims, and route groups that still
-need explicit SDK-visible error contracts.
+Every file in `src/server/routes/` uses hono-openapi with zod validators for
+route inputs/outputs. Migrating these individually is the last step; most
+will switch to `.zod` derived from the Schema-migrated domain types above,
+which means touching them is largely mechanical once the domain side is
+done.

-Good follow-up targets:
+- [ ] `src/server/error.ts`
+- [x] `src/server/event.ts`
+- [x] `src/server/projectors.ts`
+- [ ] `src/server/routes/control/index.ts`
+- [ ] `src/server/routes/control/workspace.ts`
+- [ ] `src/server/routes/global.ts`
+- [ ] `src/server/routes/instance/index.ts`
+- [ ] `src/server/routes/instance/config.ts`
+- [ ] `src/server/routes/instance/event.ts`
+- [ ] `src/server/routes/instance/experimental.ts`
+- [ ] `src/server/routes/instance/file.ts`
+- [ ] `src/server/routes/instance/mcp.ts`
+- [ ] `src/server/routes/instance/permission.ts`
+- [ ] `src/server/routes/instance/project.ts`
+- [ ] `src/server/routes/instance/provider.ts`
+- [ ] `src/server/routes/instance/pty.ts`
+- [ ] `src/server/routes/instance/question.ts`
+- [ ] `src/server/routes/instance/session.ts`
+- [ ] `src/server/routes/instance/sync.ts`
+- [ ] `src/server/routes/instance/tui.ts`

- shrink `public.ts` legacy OpenAPI translation shims one SDK-compatible slice at a time
- replace production `.zod.safeParse(...)` call sites with Effect Schema decoders
- remove derived `.zod` statics after their production consumers are gone
- declare route-group errors directly instead of relying on compatibility middleware
+The bigger prize for this group is the `@effect/platform` HTTP migration
+described in `specs/effect/http-api.md`. Once that lands, every one of
+these files changes shape entirely (`HttpApi.endpoint(...)` and friends),
+so the Schema-first domain types become a prerequisite rather than a
+sibling task.

 ### Everything else

@@ -1,58 +1,668 @@
-# Server Package Extraction
+# Server package extraction

-Practical reference for a future `packages/server` split after the opencode
-server moved to the Effect HttpApi backend.
+Practical reference for extracting a future `packages/server` from the current `packages/opencode` monolith while `packages/core` is still being migrated to Effect.

-## Current State
+This document is intentionally execution-oriented.

- The server still lives in `packages/opencode`.
- The runtime and app layer are centralized in `src/effect/app-runtime.ts` and
-  `src/effect/run-service.ts`.
- The route tree lives under `src/server/routes/instance/httpapi` and is hosted
-  from `src/server/server.ts`.
- OpenAPI generation is based on the HttpApi contract plus compatibility
-  translation in `src/server/routes/instance/httpapi/public.ts`.
- There is no standalone `packages/server` workspace yet.
+It should give an agent enough context to land one incremental PR at a time without needing to rediscover the package strategy, route migration rules, or current constraints.

-## Future State
+## Goal
+
+Create `packages/server` as the home for:
+
+- HTTP contract definitions
+- HTTP handler implementations
+- OpenAPI generation
+- eventual embeddable server APIs for Node apps
+
+Do this without blocking on the full `packages/core` extraction.
+
+## Future state

 Target package layout:

- `packages/core` - shared domain services and schemas
- `packages/server` - HTTP contracts, handlers, OpenAPI generation, and an
-  embeddable server API
- `packages/cli` - TUI and CLI entrypoints
- `packages/sdk` - generated from the server OpenAPI spec
- `packages/plugin` - plugin authoring surface
+- `packages/core` - all opencode services, Effect-first source of truth
+- `packages/server` - opencode server, with separate contract and implementation, still producing `openapi.json`
+- `packages/cli` - TUI + CLI entrypoints
+- `packages/sdk` - generated from the server OpenAPI spec, may add higher-level wrappers
+- `packages/plugin` - generated or semi-hand-rolled non-Effect package built from core plugin definitions

-## Extraction Rule
+Desired user stories:

-Do not create a package cycle.
+- import from `core` and build a custom agent or app-specific runtime
+- import from `server` and embed the full opencode server into an existing Node app
+- spawn the CLI and talk to the server through that boundary

-Until enough shared service code lives outside `packages/opencode`, a future
-`packages/server` should either:
+## Current state

- own pure HttpApi contracts only, or
- accept host-provided services/layers/callbacks from `packages/opencode`
+Everything still lives in `packages/opencode`.

-It should not import `packages/opencode` services while `packages/opencode`
-imports it to host routes.
+Important current facts:

-## Suggested PR Sequence
+- there is no `packages/core` or `packages/cli` workspace yet
+- there is no `packages/server` workspace yet on this branch
+- the main host server is still Hono-based in `src/server/server.ts`
+- current OpenAPI generation is Hono-based through `Server.openapi()` and `cli/cmd/generate.ts`
+- the Effect runtime and app layer are centralized in `src/effect/app-runtime.ts` and `src/effect/run-service.ts`
+- there are already bridged Effect `HttpApi` slices under `src/server/routes/instance/httpapi/*`
+- those slices are mounted into the Hono server behind `OPENCODE_EXPERIMENTAL_HTTPAPI`
+- the bridge currently covers `question`, `permission`, `provider`, partial `config`, and partial `project` routes

-1. Keep shrinking OpenAPI compatibility shims in `httpapi/public.ts`.
-2. Move stable domain schemas into shared packages only when they no longer
-   depend on opencode-local runtime modules.
-3. Extract pure HttpApi contract modules into `packages/server` once the contract
-   can compile without importing `packages/opencode` implementation details.
-4. Extract handler factories after their service dependencies can be supplied by
-   a host layer instead of imported directly.
-5. Move server hosting last, after package ownership is clear.
+This means the package split should start from an extraction path, not from greenfield package ownership.

-## Non-Goals
+## Structural reference

- Do not revive the old dual-backend migration shape.
- Do not split server hosting before service dependencies have a clean package
-  boundary.
- Do not switch SDK generation to a new package until generated output is known
-  to remain compatible.
+Use `anomalyco/opentunnel` as the structural reference for `packages/server`.
+
+The important pattern there is:
+
+- `packages/core` owns services and domain schemas
+- `packages/server/src/definition/*` owns pure `HttpApi` contracts
+- `packages/server/src/api/*` owns `HttpApiBuilder.group(...)` implementations and server-side middleware wiring
+- `packages/server/src/index.ts` becomes the composition root only after the server package really owns runtime hosting
+
+Relevant `opentunnel` files:
+
+- `packages/server/src/definition/index.ts`
+- `packages/server/src/definition/tunnel.ts`
+- `packages/server/src/api/index.ts`
+- `packages/server/src/api/tunnel.ts`
+- `packages/server/src/api/client.ts`
+- `packages/server/src/index.ts`
+
+The intended direction here is the same, but the current `opencode` package split is earlier in the migration.
+
+That means:
+
+- we should follow the same `definition` and `api` naming
+- we should keep contract and implementation as separate modules from the start
+- we should postpone the runtime composition root until `packages/core` exists enough to support it cleanly
+
+## Key decision
+
+Start `packages/server` as a contract and implementation package only.
+
+Do not make it the runtime host yet.
+
+Why:
+
+- `packages/core` does not exist yet
+- the current server host still lives in `packages/opencode`
+- moving host ownership immediately would force a large package and runtime shuffle while Effect service extraction is still in flight
+- if `packages/server` imports services from `packages/opencode` while `packages/opencode` imports `packages/server` to host routes, we create a package cycle immediately
+
+Short version:
+
+1. create `packages/server`
+2. move pure `HttpApi` contracts there
+3. move handler factories there
+4. keep `packages/opencode` as the temporary Hono host
+5. merge `packages/server` OpenAPI with the legacy Hono OpenAPI during the transition
+6. move server hosting later, after `packages/core` exists enough
+
+## Dependency rule
+
+Phase 1 rule:
+
+- `packages/server` must not import from `packages/opencode`
+
+Allowed in phase 1:
+
+- `packages/opencode` imports `packages/server`
+- `packages/server` accepts host-provided services, layers, or callbacks as inputs
+- `packages/server` may temporarily own transport-local placeholder schemas when a canonical shared schema does not exist yet
+
+Future rule after `packages/core` exists:
+
+- `packages/server` imports from `packages/core`
+- `packages/cli` imports from `packages/server` and `packages/core`
+- `packages/opencode` shrinks or disappears as package responsibilities are fully split
+
+## HttpApi model
+
+Use Effect v4 `HttpApi` as the source of truth for migrated HTTP routes.
+
+Important properties from the current `effect` / `effect-smol` model:
+
+- `HttpApi`, `HttpApiGroup`, and `HttpApiEndpoint` are pure contract definitions
+- handlers are implemented separately with `HttpApiBuilder.group(...)`
+- OpenAPI can be generated from the contract alone
+- auth and middleware can later be modeled with `HttpApiMiddleware.Service`
+- SSE and websocket routes are not good first-wave `HttpApi` targets
+
+This package split should preserve that separation explicitly.
+
+Default shape for migrated routes:
+
+- contract lives in `packages/server/src/definition/*`
+- implementation lives in `packages/server/src/api/*`
+- host mounting stays outside for now
+
+## OpenAPI rule
+
+During the transition there is still one spec artifact.
+
+Default rule:
+
+- `packages/server` generates OpenAPI from `HttpApi` contract
+- `packages/opencode` keeps generating legacy OpenAPI from Hono routes
+- the temporary exported server spec is a merged document
+- `packages/sdk` continues consuming one `openapi.json`
+
+Merge safety rules:
+
+- fail on duplicate `path + method`
+- fail on duplicate `operationId`
+- prefer explicit summary, description, and operation ids on all new `HttpApi` endpoints
+
+Practical implication:
+
+- do not make the SDK consume two specs
+- do not switch SDK generation to `packages/server` only until enough of the route surface has moved
+
+## Package shape
+
+Minimum viable `packages/server`:
+
+- `src/index.ts`
+- `src/definition/index.ts`
+- `src/definition/api.ts`
+- `src/definition/question.ts`
+- `src/api/index.ts`
+- `src/api/question.ts`
+- `src/openapi.ts`
+- `src/bridge/hono.ts`
+- `src/types.ts`
+
+Later additions, once there is enough real contract surface:
+
+- `src/api/client.ts`
+- runtime composition in `src/index.ts`
+
+Suggested initial exports:
+
+- `api`
+- `openapi`
+- `questionApi`
+- `makeQuestionHandler`
+
+Phase 1 responsibilities:
+
+- own pure API contracts
+- own handler factories for migrated slices
+- own contract-generated OpenAPI
+- expose host adapters needed by `packages/opencode`
+
+Phase 1 non-goals:
+
+- do not own `listen()`
+- do not own adapter selection
+- do not own global server middleware
+- do not own websocket or SSE transport
+- do not own process bootstrapping for CLI entrypoints
+
+## Current source inventory
+
+These files matter for the first phase.
+
+Current host and route composition:
+
+- `src/server/server.ts`
+- `src/server/control/index.ts`
+- `src/server/routes/instance/index.ts`
+- `src/server/middleware.ts`
+- `src/server/adapter.bun.ts`
+- `src/server/adapter.node.ts`
+
+Current bridged `HttpApi` slices:
+
+- `src/server/routes/instance/httpapi/question.ts`
+- `src/server/routes/instance/httpapi/permission.ts`
+- `src/server/routes/instance/httpapi/provider.ts`
+- `src/server/routes/instance/httpapi/config.ts`
+- `src/server/routes/instance/httpapi/project.ts`
+- `src/server/routes/instance/httpapi/server.ts`
+
+Current OpenAPI flow:
+
+- `src/server/server.ts` via `Server.openapi()`
+- `src/cli/cmd/generate.ts`
+- `packages/sdk/js/script/build.ts`
+
+Current runtime and service layer:
+
+- `src/effect/app-runtime.ts`
+- `src/effect/run-service.ts`
+
+## Ownership rules
+
+Move first into `packages/server`:
+
+- the experimental `question` `HttpApi` slice
+- future `provider` and `config` JSON read slices
+- any new `HttpApi` route groups
+- transport-local OpenAPI generation for migrated routes
+
+Keep in `packages/opencode` for now:
+
+- `src/server/server.ts`
+- `src/server/control/index.ts`
+- `src/server/routes/**/*.ts`
+- `src/server/middleware.ts`
+- `src/server/adapter.*.ts`
+- `src/effect/app-runtime.ts`
+- `src/effect/run-service.ts`
+- all Effect services until they move to `packages/core`
+
+## Placeholder schema rule
+
+`packages/core` is allowed to lag behind.
+
+Until shared canonical schemas move to `packages/core`:
+
+- prefer importing existing Effect Schema DTOs from current locations when practical
+- if a route only needs a transport-local type and moving the canonical schema would create unrelated churn, allow a temporary server-local placeholder schema
+- if a placeholder is introduced, leave a short note so it does not become permanent
+
+The default rule from `schema.md` still applies:
+
+- Effect Schema owns the type
+- `.zod` is compatibility only
+- avoid parallel hand-written Zod and Effect definitions for the same migrated route shape
+
+## Host boundary rule
+
+Until host ownership moves:
+
+- auth stays at the outer Hono app level
+- compression stays at the outer Hono app level
+- CORS stays at the outer Hono app level
+- instance and workspace lookup stay at the current middleware layer
+- `packages/server` handlers should assume the host already provided the right request context
+- do not redesign host middleware just to land the package split
+
+This matches the current guidance in `http-api.md`:
+
+- keep auth outside the first parallel `HttpApi` slices
+- keep instance lookup outside the first parallel `HttpApi` slices
+- keep the first migrations transport-focused and semantics-preserving
+
+## Route selection rules
+
+Good early migration targets:
+
+- `question`
+- `provider` auth read endpoint
+- `config` providers read endpoint
+- small read-only instance routes
+
+Bad early migration targets:
+
+- `session`
+- `event`
+- `pty`
+- most `global` streaming or process-heavy routes
+- anything requiring websocket upgrade handling
+- anything that mixes many mutations and streaming in one file
+
+## First vertical slice
+
+The first slice for the package split is still the existing `question` `HttpApi` group.
+
+Why `question` first:
+
+- it already exists as an experimental `HttpApi` slice
+- it already follows the desired contract and implementation split in one file
+- it is already mounted through the current Hono host
+- it is JSON-only
+- it has low blast radius
+
+Use the first slice to prove:
+
+- package boundary
+- contract and implementation split
+- host mounting from `packages/opencode`
+- merged OpenAPI output
+- test ergonomics for future slices
+
+Do not broaden scope in the first slice.
+
+## Incremental migration order
+
+Use small PRs.
+
+Each PR should be easy to review, easy to revert, and should not mix extraction work with unrelated service refactors.
+
+### PR 1. Create `packages/server`
+
+Scope:
+
+- add the new workspace package
+- add package manifest and tsconfig
+- add empty `src/index.ts`, `src/definition/api.ts`, `src/definition/index.ts`, `src/api/index.ts`, `src/openapi.ts`, and supporting scaffolding
+
+Rules:
+
+- no production behavior changes
+- no host server changes yet
+- no imports from `packages/opencode` inside `packages/server`
+- prefer `opentunnel`-style naming from the start: `definition` for contracts, `api` for implementations
+
+Done means:
+
+- `packages/server` typechecks
+- the workspace can import it
+- the package boundary is in place for follow-up PRs
+
+### PR 2. Move the experimental question contract
+
+Scope:
+
+- extract the pure `HttpApi` contract from `src/server/routes/instance/httpapi/question.ts`
+- place it in `packages/server/src/definition/question.ts`
+- aggregate it in `packages/server/src/definition/api.ts`
+- generate OpenAPI in `packages/server/src/openapi.ts`
+
+Rules:
+
+- contract only in this PR
+- no handler movement yet if that keeps the diff simpler
+- keep operation ids and docs metadata stable
+
+Done means:
+
+- question contract lives in `packages/server`
+- OpenAPI can be generated from contract alone
+- no runtime behavior changes yet
+
+### PR 3. Move the experimental question handler factory
+
+Scope:
+
+- extract the question `HttpApiBuilder.group(...)` implementation into `packages/server/src/api/question.ts`
+- expose it as a factory that accepts host-provided dependencies or wiring
+- add a small Hono bridge in `packages/server/src/bridge/hono.ts` if needed
+
+Rules:
+
+- `packages/server` must still not import from `packages/opencode`
+- handler code should stay thin and service-delegating
+- do not redesign the question service itself in this PR
+
+Done means:
+
+- `packages/server` can produce the experimental question handler
+- the package still stays cycle-free
+
+### PR 4. Mount `packages/server` question from `packages/opencode`
+
+Scope:
+
+- replace local experimental question route wiring in `packages/opencode`
+- keep the same mount path:
+- `/question`
+- `/question/:requestID/reply`
+- `/question/:requestID/reject`
+
+Rules:
+
+- no behavior change
+- preserve existing docs path
+- preserve current request and response shapes
+
+Done means:
+
+- existing question `HttpApi` test still passes
+- runtime behavior is unchanged
+- the current host server is now consuming `packages/server`
+
+### PR 5. Merge legacy and contract OpenAPI
+
+Scope:
+
+- keep `Server.openapi()` as the temporary spec entrypoint
+- generate legacy Hono spec
+- generate `packages/server` contract spec
+- merge them into one document
+- keep `cli/cmd/generate.ts` and `packages/sdk/js/script/build.ts` consuming one spec
+
+Rules:
+
+- fail loudly on duplicate `path + method`
+- fail loudly on duplicate `operationId`
+- do not silently overwrite one source with the other
+
+Done means:
+
+- one merged spec is produced
+- migrated question paths can come from `packages/server`
+- existing SDK generation path still works
+
+### PR 6. Add merged OpenAPI coverage
+
+Scope:
+
+- add one test for merged OpenAPI
+- assert both a legacy Hono route and a migrated `HttpApi` route exist
+
+Rules:
+
+- test the merged document, not just the `packages/server` contract spec in isolation
+- pick one stable legacy route and one stable migrated route
+
+Done means:
+
+- the merged-spec path is covered
+- future route migrations have a guardrail
+
+### PR 7. Migrate `GET /provider/auth`
+
+Scope:
+
+- add `GET /provider/auth` as the next `HttpApi` slice in `packages/server`
+- mount it in parallel from `packages/opencode`
+
+Why this route:
+
+- JSON-only
+- simple service delegation
+- small response shape
+- already listed as the best next `provider` candidate in `http-api.md`
+
+Done means:
+
+- route works through the current host
+- route appears in merged OpenAPI
+- no semantic change to provider auth behavior
+
+### PR 8. Migrate `GET /config/providers`
+
+Scope:
+
+- add `GET /config/providers` as a `HttpApi` slice in `packages/server`
+- mount it in parallel from `packages/opencode`
+
+Why this route:
+
+- JSON-only
+- read-only
+- low transport complexity
+- already listed as the best next `config` candidate in `http-api.md`
+
+Done means:
+
+- route works unchanged
+- route appears in merged OpenAPI
+
+### PR 9+. Migrate small read-only instance routes
+
+Candidate order:
+
+1. `GET /path`
+2. `GET /vcs`
+3. `GET /vcs/diff`
+4. `GET /command`
+5. `GET /agent`
+6. `GET /skill`
+
+Rules:
+
+- one or two endpoints per PR
+- prefer read-only routes first
+- keep outer middleware unchanged
+- keep business logic in the existing service layer
+
+Done means for each PR:
+
+- contract lives in `packages/server`
+- handler lives in `packages/server`
+- route is mounted from the current host
+- route appears in merged OpenAPI
+- behavior remains unchanged
+
+### Later PR. Move host ownership into `packages/server`
+
+Only start this after there is enough `packages/core` surface to depend on directly.
+
+Scope:
+
+- move server composition into `packages/server`
+- add embeddable APIs such as `createServer(...)`, `listen(...)`, or `createApp(...)`
+- move adapter selection and server startup out of `packages/opencode`
+
+Rules:
+
+- do not start this while `packages/server` still depends on `packages/opencode`
+- do not mix this with route migration PRs
+
+Done means:
+
+- `packages/server` can be embedded in another Node app
+- `packages/cli` can depend on `packages/server`
+- host logic no longer lives in `packages/opencode`
+
+## PR sizing rule
+
+Every migration PR should satisfy all of these:
+
+- one route group or one to two endpoints
+- no unrelated service refactor
+- no auth redesign
+- no middleware redesign
+- OpenAPI updated
+- at least one route test or spec test added or updated
+
+## Done means for a migrated route group
+
+A route group migration is complete only when:
+
+1. the `HttpApi` contract lives in `packages/server`
+2. handler implementation lives in `packages/server`
+3. the route is mounted from the current host in `packages/opencode`
+4. the route appears in merged OpenAPI
+5. request and response schemas are Effect Schema-first or clearly temporary placeholders
+6. existing behavior remains unchanged
+7. the route has straightforward test coverage
+
+## Validation expectations
+
+For package-split PRs, validate the smallest useful thing.
+
+Typical validation for the first waves:
+
+- `bun typecheck` in the touched package directory or directories
+- the relevant server / route coverage for the migrated slice
+- merged OpenAPI coverage if the PR touches spec generation
+
+Do not run tests from repo root.
+
+## Main risks
+
+### Package cycle
+
+This is the biggest risk.
+
+Bad state:
+
+- `packages/server` imports services or runtime from `packages/opencode`
+- `packages/opencode` imports route definitions or handlers from `packages/server`
+
+Avoid by:
+
+- keeping phase-1 `packages/server` free of `packages/opencode` imports
+- using factories and host-provided wiring instead of direct service imports
+
+### Spec drift
+
+During the transition there are two route-definition sources.
+
+Avoid by:
+
+- one merged spec
+- collision checks
+- explicit `operationId`s
+- merged OpenAPI tests
+
+### Middleware mismatch
+
+Current auth, compression, CORS, and instance selection are Hono-centered.
+
+Avoid by:
+
+- leaving them where they are during the first wave
+- not trying to solve `HttpApiMiddleware.Service` globally in the package-split PRs
+
+### Core lag
+
+`packages/core` will not be ready everywhere.
+
+Avoid by:
+
+- allowing small transport-local placeholder schemas where necessary
+- keeping those placeholders clearly temporary
+- not blocking the server extraction on full schema movement
+
+### Scope creep
+
+The first vertical slice is easy to overload.
+
+Avoid by:
+
+- proving the package boundary first
+- not mixing package creation, route migration, host redesign, and core extraction in the same change
+
+## Non-goals for the first wave
+
+- do not replace all Hono routes at once
+- do not migrate SSE or websocket routes first
+- do not redesign auth
+- do not redesign instance lookup
+- do not wait for full `packages/core` before starting `packages/server`
+- do not change SDK generation to consume multiple specs
+
+## Checklist
+
+- [x] create `packages/server`
+- [x] add package-level exports for contract and OpenAPI
+- [ ] extract `question` contract into `packages/server`
+- [ ] extract `question` handler factory into `packages/server`
+- [ ] mount `question` from `packages/opencode`
+- [ ] merge legacy and contract OpenAPI into one document
+- [ ] add merged-spec coverage
+- [ ] migrate `GET /provider/auth`
+- [ ] migrate `GET /config/providers`
+- [ ] migrate small read-only instance routes one or two at a time
+- [ ] move host ownership into `packages/server` only after `packages/core` is ready enough
+- [ ] split `packages/cli` after server and core boundaries are stable
+
+## Rule of thumb
+
+The fastest correct path is:
+
+1. establish `packages/server` as the contract-first boundary
+2. keep `packages/opencode` as the temporary host
+3. migrate a few safe JSON routes
+4. keep one merged OpenAPI document
+5. move actual host ownership only after `packages/core` can support it cleanly
+
+If a proposed PR would make `packages/server` import from `packages/opencode`, stop and restructure the boundary first.
@@ -24,7 +24,9 @@ import { Effect, Context, Layer, Schema } from "effect"
 import { InstanceState } from "@/effect/instance-state"
 import * as Option from "effect/Option"
 import * as OtelTracer from "@effect/opentelemetry/Tracer"
-import { type DeepMutable } from "@opencode-ai/core/schema"
+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,
@@ -46,7 +48,9 @@ export const Info = Schema.Struct({
  prompt: Schema.optional(Schema.String),
  options: Schema.Record(Schema.String, Schema.Unknown),
  steps: Schema.optional(Schema.Finite),
-}).annotate({ identifier: "Agent" })
+})
+  .annotate({ identifier: "Agent" })
+  .pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Info = DeepMutable<Schema.Schema.Type<typeof Info>>

 export interface Interface {
@@ -297,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]
@@ -1,5 +1,6 @@
 import path from "path"
 import { Effect, Layer, Record, Result, Schema, Context } from "effect"
+import { zod } from "@opencode-ai/core/effect-zod"
 import { NonNegativeInt } from "@opencode-ai/core/schema"
 import { Global } from "@opencode-ai/core/global"
 import { AppFileSystem } from "@opencode-ai/core/filesystem"
@@ -31,8 +32,9 @@ export class WellKnown extends Schema.Class<WellKnown>("WellKnownAuth")({
  token: Schema.String,
 }) {}

-export const Info = Schema.Union([Oauth, Api, WellKnown]).annotate({ discriminator: "type", identifier: "Auth" })
-export type Info = Schema.Schema.Type<typeof Info>
+const _Info = Schema.Union([Oauth, Api, WellKnown]).annotate({ discriminator: "type", identifier: "Auth" })
+export const Info = Object.assign(_Info, { zod: zod(_Info) })
+export type Info = Schema.Schema.Type<typeof _Info>

 export class AuthError extends Schema.TaggedErrorClass<AuthError>()("AuthError", {
  message: Schema.String,
@@ -74,17 +74,6 @@ const appBindingCommands = [
  "command.palette.show",
  "session.list",
  "session.new",
-  "session.cycle_recent",
-  "session.cycle_recent_reverse",
-  "session.quick_switch.1",
-  "session.quick_switch.2",
-  "session.quick_switch.3",
-  "session.quick_switch.4",
-  "session.quick_switch.5",
-  "session.quick_switch.6",
-  "session.quick_switch.7",
-  "session.quick_switch.8",
-  "session.quick_switch.9",
  "model.list",
  "model.cycle_recent",
  "model.cycle_recent_reverse",
@@ -473,37 +462,6 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
          dialog.clear()
        },
      },
-      ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
-        ? [
-            {
-              name: "session.cycle_recent",
-              title: "Cycle to previous recent session",
-              category: "Session",
-              hidden: true,
-              run: () => {
-                local.session.cycleRecent(1)
-              },
-            },
-            {
-              name: "session.cycle_recent_reverse",
-              title: "Cycle to next recent session",
-              category: "Session",
-              hidden: true,
-              run: () => {
-                local.session.cycleRecent(-1)
-              },
-            },
-            ...Array.from({ length: 9 }, (_, i) => ({
-              name: `session.quick_switch.${i + 1}`,
-              title: `Switch to session in quick slot ${i + 1}`,
-              category: "Session",
-              hidden: true,
-              run: () => {
-                local.session.quickSwitch(i + 1)
-              },
-            })),
-          ]
-        : []),
      {
        name: "model.list",
        title: "Switch model",
@@ -818,14 +776,7 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {

  useBindings(() => ({
    enabled: command.matcher,
-    bindings: tuiConfig.keybinds.gather(
-      "app",
-      Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
-        ? appBindingCommands
-        : appBindingCommands.filter(
-            (c) => !c.startsWith("session.cycle_recent") && !c.startsWith("session.quick_switch"),
-          ),
-    ),
+    bindings: tuiConfig.keybinds.gather("app", appBindingCommands),
  }))

  useBindings(() => ({
@@ -7,7 +7,6 @@ import { Locale } from "@/util/locale"
 import { useProject } from "@tui/context/project"
 import { useTheme } from "../context/theme"
 import { useSDK } from "../context/sdk"
-import { useLocal } from "../context/local"
 import { Flag } from "@opencode-ai/core/flag/flag"
 import { DialogSessionRename } from "./dialog-session-rename"
 import { createDebouncedSignal } from "../util/signal"
@@ -26,7 +25,6 @@ export function DialogSessionList() {
  const project = useProject()
  const { theme } = useTheme()
  const sdk = useSDK()
-  const local = useLocal()
  const toast = useToast()
  const [toDelete, setToDelete] = createSignal<string>()
  const [search, setSearch] = createDebouncedSignal("", 150)
@@ -130,10 +128,7 @@ export function DialogSessionList() {

  const [browseOrder] = createSignal<string[]>(orderByRecency(sync.data.session))

-  const RECENT_LIMIT = 5
-
  const options = createMemo(() => {
-    const enabled = Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
    const today = new Date().toDateString()
    const sessionMap = new Map(
      sessions()
@@ -144,74 +139,46 @@ export function DialogSessionList() {
    const searchResult = searchResults()
    const displayOrder = searchResult ? orderByRecency(searchResult) : browseOrder()

-    const dismissed = enabled ? new Set(local.session.dismissedRecent()) : new Set<string>()
-    const pinned = enabled ? local.session.pinned().filter((id) => sessionMap.has(id)) : []
-    const pinnedSet = new Set(pinned)
-    const slotByID = enabled
-      ? new Map<string, number>(local.session.slots().map((id, i) => [id, i + 1]))
-      : new Map<string, number>()
-
-    const recent = enabled
-      ? displayOrder.filter((id) => !pinnedSet.has(id) && !dismissed.has(id)).slice(0, RECENT_LIMIT)
-      : []
-    const recentSet = new Set(recent)
-
-    function buildOption(id: string, category: string) {
-      const x = sessionMap.get(id)
-      if (!x) return undefined
-      const workspace = x.workspaceID ? project.workspace.get(x.workspaceID) : undefined
-
-      let footer: JSX.Element | string = ""
-      if (Flag.OPENCODE_EXPERIMENTAL_WORKSPACES) {
-        if (x.workspaceID) {
-          footer = workspace ? (
-            <WorkspaceLabel
-              type={workspace.type}
-              name={workspace.name}
-              status={project.workspace.status(x.workspaceID) ?? "error"}
-            />
-          ) : (
-            <WorkspaceLabel type="unknown" name={x.workspaceID} status="error" />
-          )
-        }
-      } else {
-        footer = Locale.time(x.time.updated)
-      }
-
-      const isDeleting = toDelete() === x.id
-      const status = sync.data.session_status?.[x.id]
-      const isWorking = status?.type === "busy" || status?.type === "retry"
-      const slot = slotByID.get(x.id)
-      const gutter = isWorking
-        ? () => <Spinner />
-        : slot !== undefined
-          ? () => <text fg={theme.accent}>{slot}</text>
-          : undefined
-      return {
-        title: isDeleting ? `Press ${deleteHint()} again to confirm` : x.title,
-        bg: isDeleting ? theme.error : undefined,
-        value: x.id,
-        category,
-        footer,
-        gutter,
-      }
-    }
-
-    const remaining = displayOrder
-      .filter((id) => !pinnedSet.has(id) && !recentSet.has(id))
-      .map((id) => {
-        const x = sessionMap.get(id)
-        if (!x) return undefined
-        const label = new Date(x.time.updated).toDateString()
-        return buildOption(id, label === today ? "Today" : label)
-      })
+    return displayOrder
+      .map((id) => sessionMap.get(id))
      .filter((x) => x !== undefined)
+      .map((x) => {
+        const workspace = x.workspaceID ? project.workspace.get(x.workspaceID) : undefined

-    return [
-      ...pinned.map((id) => buildOption(id, "Pinned")).filter((x) => x !== undefined),
-      ...recent.map((id) => buildOption(id, "Recent")).filter((x) => x !== undefined),
-      ...remaining,
-    ]
+        let footer: JSX.Element | string = ""
+        if (Flag.OPENCODE_EXPERIMENTAL_WORKSPACES) {
+          if (x.workspaceID) {
+            footer = workspace ? (
+              <WorkspaceLabel
+                type={workspace.type}
+                name={workspace.name}
+                status={project.workspace.status(x.workspaceID) ?? "error"}
+              />
+            ) : (
+              <WorkspaceLabel type="unknown" name={x.workspaceID} status="error" />
+            )
+          }
+        } else {
+          footer = Locale.time(x.time.updated)
+        }
+
+        const date = new Date(x.time.updated)
+        let category = date.toDateString()
+        if (category === today) {
+          category = "Today"
+        }
+        const isDeleting = toDelete() === x.id
+        const status = sync.data.session_status?.[x.id]
+        const isWorking = status?.type === "busy" || status?.type === "retry"
+        return {
+          title: isDeleting ? `Press ${deleteHint()} again to confirm` : x.title,
+          bg: isDeleting ? theme.error : undefined,
+          value: x.id,
+          category,
+          footer,
+          gutter: isWorking ? () => <Spinner /> : undefined,
+        }
+      })
  })

  onMount(() => {
@@ -236,32 +203,6 @@ export function DialogSessionList() {
        dialog.clear()
      }}
      actions={[
-        ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
-          ? [
-              {
-                command: "session.pin.toggle",
-                title: "pin/unpin",
-                onTrigger: (option: { value: string }) => {
-                  local.session.togglePin(option.value)
-                },
-              },
-              {
-                command: "session.toggle.recent",
-                title: "toggle recent",
-                onTrigger: (option: { value: string }) => {
-                  if (local.session.isPinned(option.value)) {
-                    toast.show({
-                      variant: "info",
-                      message: "Unpin the session first to toggle it in Recent",
-                      duration: 3000,
-                    })
-                    return
-                  }
-                  local.session.toggleRecent(option.value)
-                },
-              },
-            ]
-          : []),
        {
          command: "session.delete",
          title: "delete",
@@ -18,8 +18,6 @@ import { Locale } from "@/util/locale"
 import type { PromptInfo } from "./history"
 import { useFrecency } from "./frecency"
 import { useBindings } from "../../keymap"
-import { Reference } from "@/reference/reference"
-import type { Config } from "@/config/config"

 function removeLineRange(input: string) {
  const hashIndex = input.lastIndexOf("#")
@@ -262,87 +260,6 @@ export function Autocomplete(props: {
    }
  }

-  function createReferenceFilePart(input: {
-    alias: string
-    root: string
-    item: string
-    lineRange?: { startLine: number; endLine?: number }
-  }) {
-    const filename = `${input.alias}/${
-      input.lineRange && !input.item.endsWith("/")
-        ? `${input.item}#${input.lineRange.startLine}${input.lineRange.endLine ? `-${input.lineRange.endLine}` : ""}`
-        : input.item
-    }`
-    const urlObj = pathToFileURL(path.join(input.root, input.item))
-
-    if (input.lineRange && !input.item.endsWith("/")) {
-      urlObj.searchParams.set("start", String(input.lineRange.startLine))
-      if (input.lineRange.endLine !== undefined) {
-        urlObj.searchParams.set("end", String(input.lineRange.endLine))
-      }
-    }
-
-    return {
-      filename,
-      url: urlObj.href,
-      part: {
-        type: "file" as const,
-        mime: input.item.endsWith("/") ? "application/x-directory" : "text/plain",
-        filename,
-        url: urlObj.href,
-        source: {
-          type: "file" as const,
-          text: {
-            start: 0,
-            end: 0,
-            value: "",
-          },
-          path: filename,
-        },
-      },
-    }
-  }
-
-  function referencePromptText(reference: Reference.Resolved) {
-    const problem = reference.kind === "invalid" ? reference.message : undefined
-    return [
-      `Referenced configured reference @${reference.name}.`,
-      ...(reference.kind === "local" ? ["Kind: local directory"] : []),
-      ...(reference.kind === "git" ? ["Kind: git repository"] : []),
-      ...(reference.kind === "invalid" ? [`Repository: ${reference.repository}`] : []),
-      ...(reference.kind === "git" ? [`Repository: ${reference.repository}`] : []),
-      ...(reference.kind === "git" && reference.branch ? [`Branch/ref: ${reference.branch}`] : []),
-      ...(reference.kind === "invalid" ? [] : [`Reference root: ${reference.path}`]),
-      ...(problem
-        ? [`Problem: ${problem}`]
-        : [
-            "For targeted context, inspect the reference path directly with Read, Glob, and Grep. For broader research, call the task tool with subagent scout and include this reference path.",
-          ]),
-    ].join("\n")
-  }
-
-  const references = createMemo(() =>
-    Reference.resolveAll({
-      references: (sync.data.config.reference ?? {}) as NonNullable<Config.Info["reference"]>,
-      directory: sync.path.directory || process.cwd(),
-      worktree: sync.path.worktree || sync.path.directory || process.cwd(),
-    }),
-  )
-
-  const referenceSearch = createMemo(() => {
-    if (!store.visible || store.visible === "/") return
-    const { lineRange, baseQuery } = extractLineRange(search())
-    const slash = baseQuery.indexOf("/")
-    if (slash === -1) return
-    const reference = references().find((item) => item.name === baseQuery.slice(0, slash))
-    if (!reference || reference.kind === "invalid") return
-    return {
-      reference,
-      query: baseQuery.slice(slash + 1),
-      lineRange,
-    }
-  })
-
  function normalizeMentionPath(filePath: string) {
    const baseDir = sync.path.directory || process.cwd()
    const absolute = path.resolve(filePath)
@@ -374,7 +291,6 @@ export function Autocomplete(props: {
    () => search(),
    async (query) => {
      if (!store.visible || store.visible === "/") return []
-      if (referenceSearch()) return []

      const { lineRange, baseQuery } = extractLineRange(query ?? "")

@@ -423,43 +339,6 @@ export function Autocomplete(props: {
    },
  )

-  const [referenceFiles] = createResource(
-    () => referenceSearch(),
-    async (match) => {
-      if (!match) return []
-
-      const result = await sdk.client.find.files({
-        directory: match.reference.path,
-        query: match.query,
-        limit: 50,
-      })
-
-      if (result.error || !result.data) return []
-
-      const width = props.anchor().width - 4
-      return result.data.map((item): AutocompleteOption => {
-        const { filename, part } = createReferenceFilePart({
-          alias: match.reference.name,
-          root: match.reference.path,
-          item,
-          lineRange: match.lineRange,
-        })
-        return {
-          display: Locale.truncateMiddle(filename, width),
-          value: filename,
-          isDirectory: item.endsWith("/"),
-          path: filename,
-          onSelect: () => {
-            insertPart(filename, part)
-          },
-        }
-      })
-    },
-    {
-      initialValue: [],
-    },
-  )
-
  const mcpResources = createMemo(() => {
    if (!store.visible || store.visible === "/") return []

@@ -518,22 +397,6 @@ export function Autocomplete(props: {
      )
  })

-  const referenceAliases = createMemo(() =>
-    references().map(
-      (reference): AutocompleteOption => ({
-        display: "@" + reference.name,
-        description: reference.kind === "invalid" ? reference.message : " configured reference",
-        onSelect: () => {
-          insertPart(reference.name, {
-            type: "text",
-            text: referencePromptText(reference),
-            synthetic: true,
-          })
-        },
-      }),
-    ),
-  )
-
  const commands = createMemo((): AutocompleteOption[] => {
    const results: AutocompleteOption[] = [...command.slashes()]

@@ -565,18 +428,11 @@ export function Autocomplete(props: {

  const options = createMemo((prev: AutocompleteOption[] | undefined) => {
    const filesValue = files()
-    const referenceFilesValue = referenceFiles()
-    const referenceSearchValue = referenceSearch()
    const agentsValue = agents()
-    const referenceAliasesValue = referenceAliases()
    const commandsValue = commands()

    const mixed: AutocompleteOption[] =
-      store.visible === "@"
-        ? referenceSearchValue
-          ? referenceFilesValue || []
-          : [...referenceAliasesValue, ...agentsValue, ...(filesValue || []), ...mcpResources()]
-        : [...commandsValue]
+      store.visible === "@" ? [...agentsValue, ...(filesValue || []), ...mcpResources()] : [...commandsValue]

    const searchValue = search()

@@ -584,7 +440,7 @@ export function Autocomplete(props: {
      return mixed
    }

-    if ((files.loading || referenceFiles.loading) && prev && prev.length > 0) {
+    if (files.loading && prev && prev.length > 0) {
      return prev
    }

@@ -649,7 +505,7 @@ export function Autocomplete(props: {
    const input = props.input()
    const currentCursorOffset = input.cursorOffset

-    const displayText = (selected.value ?? selected.display).trimEnd()
+    const displayText = selected.display.trimEnd()
    const path = displayText.startsWith("@") ? displayText.slice(1) : displayText

    input.cursorOffset = store.index
@@ -926,7 +926,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 +941,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 +964,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 +979,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")
@@ -2,7 +2,7 @@ export * as TuiKeybind from "./keybind"

 import type { KeyEvent, Renderable } from "@opentui/core"
 import type { Binding } from "@opentui/keymap"
-import type { BindingCommandMap, BindingConfig, BindingDefaults } from "@opentui/keymap/extras"
+import type { BindingCommandMap, BindingConfig, BindingDefaults, BindingValue } from "@opentui/keymap/extras"
 import z from "zod"

 const KeyStroke = z
@@ -38,7 +38,7 @@ export const LeaderDefault = "ctrl+x"

 const keybind = (value: Definition["default"], description: string): Definition => ({ default: value, description })

-export const Definitions = {
+const Definitions = {
  leader: keybind(LeaderDefault, "Leader key for keybind combinations"),

  app_exit: keybind("ctrl+c,ctrl+d,<leader>q", "Exit the application"),
@@ -80,19 +80,6 @@ export const Definitions = {
  session_child_cycle: keybind("right", "Go to next child session"),
  session_child_cycle_reverse: keybind("left", "Go to previous child session"),
  session_parent: keybind("up", "Go to parent session"),
-  session_pin_toggle: keybind("ctrl+f", "Pin or unpin session in the session list"),
-  session_toggle_recent: keybind("ctrl+h", "Show or hide session in the Recent group"),
-  session_cycle_recent: keybind("<leader>]", "Cycle to the previous recent session"),
-  session_cycle_recent_reverse: keybind("<leader>[", "Cycle to the next recent session"),
-  session_quick_switch_1: keybind("<leader>1", "Switch to session in quick slot 1"),
-  session_quick_switch_2: keybind("<leader>2", "Switch to session in quick slot 2"),
-  session_quick_switch_3: keybind("<leader>3", "Switch to session in quick slot 3"),
-  session_quick_switch_4: keybind("<leader>4", "Switch to session in quick slot 4"),
-  session_quick_switch_5: keybind("<leader>5", "Switch to session in quick slot 5"),
-  session_quick_switch_6: keybind("<leader>6", "Switch to session in quick slot 6"),
-  session_quick_switch_7: keybind("<leader>7", "Switch to session in quick slot 7"),
-  session_quick_switch_8: keybind("<leader>8", "Switch to session in quick slot 8"),
-  session_quick_switch_9: keybind("<leader>9", "Switch to session in quick slot 9"),

  stash_delete: keybind("ctrl+d", "Delete stash entry"),
  model_provider_list: keybind("ctrl+a", "Open provider list from model dialog"),
@@ -270,19 +257,6 @@ export const CommandMap = {
  session_child_cycle: "session.child.next",
  session_child_cycle_reverse: "session.child.previous",
  session_parent: "session.parent",
-  session_pin_toggle: "session.pin.toggle",
-  session_toggle_recent: "session.toggle.recent",
-  session_cycle_recent: "session.cycle_recent",
-  session_cycle_recent_reverse: "session.cycle_recent_reverse",
-  session_quick_switch_1: "session.quick_switch.1",
-  session_quick_switch_2: "session.quick_switch.2",
-  session_quick_switch_3: "session.quick_switch.3",
-  session_quick_switch_4: "session.quick_switch.4",
-  session_quick_switch_5: "session.quick_switch.5",
-  session_quick_switch_6: "session.quick_switch.6",
-  session_quick_switch_7: "session.quick_switch.7",
-  session_quick_switch_8: "session.quick_switch.8",
-  session_quick_switch_9: "session.quick_switch.9",
  stash_delete: "stash.delete",
  model_provider_list: "model.dialog.provider",
  model_favorite_toggle: "model.dialog.favorite",
@@ -1,66 +0,0 @@
-import { ConfigPlugin } from "@/config/plugin"
-import { Schema } from "effect"
-import { TuiKeybind } from "./keybind"
-
-const KeymapLeaderTimeout = Schema.Int.check(Schema.isGreaterThan(0)).annotate({
-  description: "Leader key timeout in milliseconds",
-})
-
-const KeyStroke = Schema.Struct({
-  name: Schema.String,
-  ctrl: Schema.optional(Schema.Boolean),
-  shift: Schema.optional(Schema.Boolean),
-  meta: Schema.optional(Schema.Boolean),
-  super: Schema.optional(Schema.Boolean),
-  hyper: Schema.optional(Schema.Boolean),
-})
-
-const BindingObject = Schema.StructWithRest(
-  Schema.Struct({
-    key: Schema.Union([Schema.String, KeyStroke]),
-    event: Schema.optional(Schema.Literals(["press", "release"])),
-    preventDefault: Schema.optional(Schema.Boolean),
-    fallthrough: Schema.optional(Schema.Boolean),
-  }),
-  [Schema.Record(Schema.String, Schema.Unknown)],
-)
-
-const BindingItem = Schema.Union([Schema.String, KeyStroke, BindingObject])
-const BindingValue = Schema.Union([
-  Schema.Literal(false),
-  Schema.Literal("none"),
-  BindingItem,
-  Schema.Array(BindingItem),
-])
-
-const KeybindOverrides = Schema.Struct(
-  Object.fromEntries(
-    Object.entries(TuiKeybind.Definitions).map(([name, item]) => [
-      name,
-      Schema.optional(BindingValue).annotate({ description: item.description }),
-    ]),
-  ),
-).annotate({ description: "TUI keybinding overrides" })
-
-export const Info = Schema.Struct({
-  $schema: Schema.optional(Schema.String),
-  theme: Schema.optional(Schema.String),
-  keybinds: Schema.optional(KeybindOverrides),
-  plugin: Schema.optional(Schema.Array(ConfigPlugin.Spec)),
-  plugin_enabled: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)),
-  leader_timeout: Schema.optional(KeymapLeaderTimeout),
-  scroll_speed: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0.001))).annotate({
-    description: "TUI scroll speed",
-  }),
-  scroll_acceleration: Schema.optional(
-    Schema.Struct({
-      enabled: Schema.Boolean.annotate({ description: "Enable scroll acceleration" }),
-    }),
-  ).annotate({ description: "Scroll acceleration settings" }),
-  diff_style: Schema.optional(Schema.Literals(["auto", "stacked"])).annotate({
-    description: "Control diff rendering style: 'auto' adapts to terminal width, 'stacked' always shows single column",
-  }),
-  mouse: Schema.optional(Schema.Boolean).annotate({ description: "Enable or disable mouse capture (default: true)" }),
-})
-
-export * as TuiJsonSchema from "./tui-json-schema"
@@ -31,3 +31,5 @@ export const TuiInfo = z
  })
  .extend(TuiOptions.shape)
  .strict()
+
+export const TuiJsonSchemaInfo = TuiInfo
@@ -5,10 +5,9 @@ import { createBindingLookup } from "@opentui/keymap/extras"
 import { mergeDeep, unique } from "remeda"
 import { Context, Effect, Fiber, Layer } from "effect"
 import { ConfigParse } from "@/config/parse"
-import { InvalidError } from "@/config/error"
 import * as ConfigPaths from "@/config/paths"
 import { migrateTuiConfig } from "./tui-migrate"
-import { KeymapLeaderTimeoutDefault, TuiInfo } from "./tui-schema"
+import { KeymapLeaderTimeoutDefault, TuiInfo, TuiJsonSchemaInfo } from "./tui-schema"
 import { Flag } from "@opencode-ai/core/flag/flag"
 import { isRecord } from "@/util/record"
 import { Global } from "@opencode-ai/core/global"
@@ -26,6 +25,7 @@ import { Npm } from "@opencode-ai/core/npm"
 const log = Log.create({ service: "tui.config" })

 export const Info = TuiInfo
+export const JsonSchemaInfo = TuiJsonSchemaInfo
 export type Info = z.output<typeof Info>

 type Acc = {
@@ -91,12 +91,10 @@ const loadState = Effect.fn("TuiConfig.loadState")(function* (ctx: { directory:
      if (!isRecord(data)) return {} as Info
      // Flatten a nested "tui" key so users who wrote `{ "tui": { ... } }` inside tui.json
      // (mirroring the old opencode.json shape) still get their settings applied.
-      const parsed = Info.safeParse(normalize(data))
-      if (!parsed.success) throw new InvalidError({ path: configFilepath, issues: parsed.error.issues })
-      const validated = parsed.data
+      const validated = ConfigParse.schema(Info, normalize(data), configFilepath)
      return yield* resolvePlugins(validated, configFilepath)
    }).pipe(
-      // catchCause (not tapErrorCause + orElseSucceed) because JSONC parsing and validation
+      // catchCause (not tapErrorCause + orElseSucceed) because ConfigParse.jsonc/.schema
      // can sync-throw — those become defects, which orElseSucceed wouldn't catch.
      Effect.catchCause((cause) =>
        Effect.sync(() => {
@@ -1,14 +1,11 @@
 import { createStore } from "solid-js/store"
 import { createSimpleContext } from "./helper"
-import { batch, createEffect, createMemo, on } from "solid-js"
+import { batch, createEffect, createMemo } from "solid-js"
 import { useSync } from "@tui/context/sync"
 import { useTheme } from "@tui/context/theme"
-import { useRoute } from "@tui/context/route"
-import { useEvent } from "@tui/context/event"
 import { uniqueBy } from "remeda"
 import path from "path"
 import { Global } from "@opencode-ai/core/global"
-import { Flag } from "@opencode-ai/core/flag/flag"
 import { iife } from "@/util/iife"
 import { useToast } from "../ui/toast"
 import { useArgs } from "./args"
@@ -383,192 +380,6 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
      }
    })

-    const session = iife(() => {
-      const [sessionStore, setSessionStore] = createStore<{
-        ready: boolean
-        pinned: string[]
-        dismissedRecent: string[]
-        recentOrder: string[]
-      }>({
-        ready: false,
-        pinned: [],
-        dismissedRecent: [],
-        recentOrder: [],
-      })
-
-      const filePath = path.join(Global.Path.state, "session.json")
-      const state = {
-        pending: false,
-      }
-
-      function save() {
-        if (!sessionStore.ready) {
-          state.pending = true
-          return
-        }
-        state.pending = false
-        void Filesystem.writeJson(filePath, {
-          pinned: sessionStore.pinned,
-          dismissedRecent: sessionStore.dismissedRecent,
-          recentOrder: sessionStore.recentOrder,
-        })
-      }
-
-      Filesystem.readJson(filePath)
-        .then((x: any) => {
-          if (Array.isArray(x.pinned)) setSessionStore("pinned", x.pinned)
-          if (Array.isArray(x.dismissedRecent)) setSessionStore("dismissedRecent", x.dismissedRecent)
-          if (Array.isArray(x.recentOrder)) setSessionStore("recentOrder", x.recentOrder)
-        })
-        .catch(() => {})
-        .finally(() => {
-          setSessionStore("ready", true)
-          if (state.pending) save()
-        })
-
-      const route = useRoute()
-      const event = useEvent()
-      let cycling = false
-
-      const slots = createMemo(() => {
-        const rootSessions = sync.data.session.filter((x) => x.parentID === undefined)
-        const existing = new Set(rootSessions.map((x) => x.id))
-        const dismissed = new Set(sessionStore.dismissedRecent)
-        const pins = sessionStore.pinned.filter((id) => existing.has(id))
-        const pinnedSet = new Set(pins)
-        const recent = rootSessions
-          .filter((x) => !pinnedSet.has(x.id) && !dismissed.has(x.id))
-          .toSorted((a, b) => b.time.updated - a.time.updated)
-          .map((x) => x.id)
-        return [...pins, ...recent].slice(0, 9)
-      })
-
-      function prune(sessionID: string) {
-        batch(() => {
-          if (sessionStore.pinned.includes(sessionID)) {
-            setSessionStore(
-              "pinned",
-              sessionStore.pinned.filter((x) => x !== sessionID),
-            )
-          }
-          if (sessionStore.dismissedRecent.includes(sessionID)) {
-            setSessionStore(
-              "dismissedRecent",
-              sessionStore.dismissedRecent.filter((x) => x !== sessionID),
-            )
-          }
-          if (sessionStore.recentOrder.includes(sessionID)) {
-            setSessionStore(
-              "recentOrder",
-              sessionStore.recentOrder.filter((x) => x !== sessionID),
-            )
-          }
-          save()
-        })
-      }
-
-      event.on("session.deleted", (evt) => {
-        prune(evt.properties.info.id)
-      })
-
-      if (Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING) {
-        createEffect(
-          on(
-            () => (sessionStore.ready && route.data.type === "session" ? route.data.sessionID : undefined),
-            (sessionID) => {
-              if (!sessionID) return
-              if (cycling) {
-                cycling = false
-                return
-              }
-              const filtered = sessionStore.recentOrder.filter((x) => x !== sessionID)
-              const next = [sessionID, ...filtered].slice(0, 20)
-              setSessionStore("recentOrder", next)
-              save()
-            },
-          ),
-        )
-      }
-
-      return {
-        get ready() {
-          return sessionStore.ready
-        },
-        pinned() {
-          return sessionStore.pinned
-        },
-        dismissedRecent() {
-          return sessionStore.dismissedRecent
-        },
-        recentOrder() {
-          return sessionStore.recentOrder
-        },
-        slots,
-        isPinned(sessionID: string) {
-          return sessionStore.pinned.includes(sessionID)
-        },
-        isDismissed(sessionID: string) {
-          return sessionStore.dismissedRecent.includes(sessionID)
-        },
-        togglePin(sessionID: string) {
-          batch(() => {
-            const exists = sessionStore.pinned.includes(sessionID)
-            const next = exists
-              ? sessionStore.pinned.filter((x) => x !== sessionID)
-              : [sessionID, ...sessionStore.pinned]
-            setSessionStore("pinned", next)
-            save()
-          })
-        },
-        toggleRecent(sessionID: string) {
-          batch(() => {
-            const exists = sessionStore.dismissedRecent.includes(sessionID)
-            const next = exists
-              ? sessionStore.dismissedRecent.filter((x) => x !== sessionID)
-              : [sessionID, ...sessionStore.dismissedRecent]
-            setSessionStore("dismissedRecent", next)
-            save()
-          })
-        },
-        quickSwitch(slot: number) {
-          const target = slots()[slot - 1]
-          if (!target) return
-          if (route.data.type === "session" && route.data.sessionID === target) return
-          route.navigate({ type: "session", sessionID: target })
-        },
-        cycleRecent(direction: 1 | -1) {
-          if (route.data.type !== "session") {
-            toast.show({
-              variant: "info",
-              message: "Open a session first to cycle between recent sessions",
-              duration: 3000,
-            })
-            return
-          }
-          const current = route.data.sessionID
-          const order = sessionStore.recentOrder.filter((id) =>
-            sync.data.session.some((s) => s.id === id && s.parentID === undefined),
-          )
-          if (order.length < 2) {
-            toast.show({
-              variant: "info",
-              message: "No other recent sessions to cycle to",
-              duration: 3000,
-            })
-            return
-          }
-          const index = order.indexOf(current)
-          if (index === -1) return
-          const next = index + direction
-          if (next < 0 || next >= order.length) return
-          const target = order[next]
-          if (!target || target === current) return
-          cycling = true
-          route.navigate({ type: "session", sessionID: target })
-        },
-      }
-    })
-
    const mcp = {
      isEnabled(name: string) {
        const status = sync.data.mcp[name]
@@ -601,7 +412,6 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
      model,
      agent,
      mcp,
-      session,
    }
    return result
  },
@@ -1,6 +1,5 @@
 import { createMemo, For } from "solid-js"
 import { DEFAULT_THEMES, useTheme } from "@tui/context/theme"
-import { Flag } from "@opencode-ai/core/flag/flag"

 const themeCount = Object.keys(DEFAULT_THEMES).length
 const themeTip = `Use {highlight}/themes{/highlight} or {highlight}Ctrl+X T{/highlight} to switch between ${themeCount} built-in themes`
@@ -67,14 +66,6 @@ const TIPS = [
  themeTip,
  "Press {highlight}Ctrl+X N{/highlight} or {highlight}/new{/highlight} to start a fresh conversation session",
  "Use {highlight}/sessions{/highlight} or {highlight}Ctrl+X L{/highlight} to list and continue previous conversations",
-  ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
-    ? [
-        "Press {highlight}Ctrl+F{/highlight} in the session list to pin a session so it stays at the top",
-        "Pinned and recent sessions are bound to {highlight}Ctrl+X 1{/highlight} through {highlight}Ctrl+X 9{/highlight} for one-press switching",
-        "Press {highlight}Ctrl+X ]{/highlight} / {highlight}Ctrl+X [{/highlight} to cycle through recently visited sessions",
-        "Press {highlight}Ctrl+H{/highlight} in the session list to show or hide a session in the Recent group",
-      ]
-    : []),
  "Run {highlight}/compact{/highlight} to summarize long sessions near context limits",
  "Press {highlight}Ctrl+X X{/highlight} or {highlight}/export{/highlight} to save the conversation as Markdown",
  "Press {highlight}Ctrl+X Y{/highlight} to copy the assistant's last message to clipboard",
@@ -17,6 +17,7 @@ import { TuiConfig } from "@/cli/cmd/tui/config/tui"
 import * as Log from "@opencode-ai/core/util/log"
 import { errorData, errorMessage } from "@/util/error"
 import { isRecord } from "@/util/record"
+import { WithInstance } from "@/project/with-instance"
 import {
  readPackageThemes,
  readPluginId,
@@ -837,7 +838,10 @@ async function addPluginBySpec(state: RuntimeState | undefined, raw: string) {
    state.pending.delete(spec)
    return true
  }
-  const ready = await resolveExternalPlugins([cfg], () => TuiConfig.waitForDependencies()).catch((error) => {
+  const ready = await WithInstance.provide({
+    directory: state.directory,
+    fn: () => resolveExternalPlugins([cfg], () => TuiConfig.waitForDependencies()),
+  }).catch((error) => {
    fail("failed to add tui plugin", { path: next, error })
    return [] as PluginLoad[]
  })
@@ -1030,37 +1034,42 @@ async function load(input: { api: Api; config: TuiConfig.Resolved }) {
  }
  runtime = next
  try {
-    const records = Flag.OPENCODE_PURE ? [] : (config.plugin_origins ?? [])
-    if (Flag.OPENCODE_PURE && config.plugin_origins?.length) {
-      log.info("skipping external tui plugins in pure mode", { count: config.plugin_origins.length })
-    }
+    await WithInstance.provide({
+      directory: cwd,
+      fn: async () => {
+        const records = Flag.OPENCODE_PURE ? [] : (config.plugin_origins ?? [])
+        if (Flag.OPENCODE_PURE && config.plugin_origins?.length) {
+          log.info("skipping external tui plugins in pure mode", { count: config.plugin_origins.length })
+        }

-    for (const item of INTERNAL_TUI_PLUGINS) {
-      log.info("loading internal tui plugin", { id: item.id })
-      const entry = loadInternalPlugin(item)
-      const meta = createMeta(entry.source, entry.spec, entry.target, undefined, entry.id)
-      addPluginEntry(next, {
-        id: entry.id,
-        load: entry,
-        meta,
-        themes: {},
-        plugin: entry.module.tui,
-        enabled: item.enabled ?? true,
-      })
-    }
+        for (const item of INTERNAL_TUI_PLUGINS) {
+          log.info("loading internal tui plugin", { id: item.id })
+          const entry = loadInternalPlugin(item)
+          const meta = createMeta(entry.source, entry.spec, entry.target, undefined, entry.id)
+          addPluginEntry(next, {
+            id: entry.id,
+            load: entry,
+            meta,
+            themes: {},
+            plugin: entry.module.tui,
+            enabled: item.enabled ?? true,
+          })
+        }

-    const ready = await resolveExternalPlugins(records, () => TuiConfig.waitForDependencies())
-    await addExternalPluginEntries(next, ready)
+        const ready = await resolveExternalPlugins(records, () => TuiConfig.waitForDependencies())
+        await addExternalPluginEntries(next, ready)

-    applyInitialPluginEnabledState(next, config)
-    for (const plugin of next.plugins) {
-      if (!plugin.enabled) continue
-      // Keep plugin execution sequential for deterministic side effects:
-      // command registration order affects keybind/command precedence,
-      // route registration is last-wins when ids collide,
-      // and hook chains rely on stable plugin ordering.
-      await activatePluginEntry(next, plugin, false)
-    }
+        applyInitialPluginEnabledState(next, config)
+        for (const plugin of next.plugins) {
+          if (!plugin.enabled) continue
+          // Keep plugin execution sequential for deterministic side effects:
+          // command registration order affects keybind/command precedence,
+          // route registration is last-wins when ids collide,
+          // and hook chains rely on stable plugin ordering.
+          await activatePluginEntry(next, plugin, false)
+        }
+      },
+    })
  } catch (error) {
    fail("failed to load tui plugins", { directory: cwd, error })
  }
@@ -746,7 +746,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 +756,7 @@ export function Session() {
      title: "Line down",
      value: "session.line.down",
      category: "Session",
-      hidden: true,
+      enabled: false,
      run: () => {
        scroll.scrollBy(1)
        dialog.clear()
@@ -189,8 +189,7 @@ export const TuiThreadCommand = cmd({
      const prompt = await input(args.prompt)
      const config = await TuiConfig.get()

-      const network = await resolveNetworkOptionsNoConfig(args)
-
+      const network = resolveNetworkOptionsNoConfig(args)
      const external =
        process.argv.includes("--port") ||
        process.argv.includes("--hostname") ||
@@ -5,7 +5,8 @@ import type { InstanceContext } from "@/project/instance"
 import { SessionID, MessageID } from "@/session/schema"
 import { Effect, Layer, Context, Schema } from "effect"
 import z from "zod"
-import { ZodOverride } from "@opencode-ai/core/effect-zod"
+import { zod, ZodOverride } from "@opencode-ai/core/effect-zod"
+import { withStatics } from "@opencode-ai/core/schema"
 import { Config } from "@/config/config"
 import { MCP } from "../mcp"
 import { Skill } from "../skill"
@@ -38,7 +39,9 @@ export const Info = Schema.Struct({
  template: Schema.Unknown.annotate({ [ZodOverride]: z.promise(z.string()).or(z.string()) }),
  subtask: Schema.optional(Schema.Boolean),
  hints: Schema.Array(Schema.String),
-}).annotate({ identifier: "Command" })
+})
+  .annotate({ identifier: "Command" })
+  .pipe(withStatics((s) => ({ zod: zod(s) })))

 // for some reason zod is inferring `string` for z.promise(z.string()).or(z.string()) so we have to manually override it
 export type Info = Omit<Schema.Schema.Type<typeof Info>, "template"> & { template: Promise<string> | string }
@@ -2,7 +2,8 @@ export * as ConfigAgent from "./agent"

 import { Exit, Schema, SchemaGetter } from "effect"
 import { Bus } from "@/bus"
-import { PositiveInt } from "@opencode-ai/core/schema"
+import { zod } from "@opencode-ai/core/effect-zod"
+import { PositiveInt, withStatics } from "@opencode-ai/core/schema"
 import * as Log from "@opencode-ai/core/util/log"
 import { NamedError } from "@opencode-ai/core/util/error"
 import { Glob } from "@opencode-ai/core/util/glob"
@@ -101,7 +102,9 @@ export const Info = AgentSchema.pipe(
    decode: SchemaGetter.transform(normalize),
    encode: SchemaGetter.passthrough({ strict: false }),
  }),
-).annotate({ identifier: "AgentConfig" })
+)
+  .annotate({ identifier: "AgentConfig" })
+  .pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Info = Schema.Schema.Type<typeof Info>

 export async function load(dir: string) {
@@ -131,7 +134,7 @@ export async function load(dir: string) {
      ...md.data,
      prompt: md.content.trim(),
    }
-    result[config.name] = ConfigParse.schema(Info, config, item)
+    result[config.name] = ConfigParse.effectSchema(Info, config, item)
  }
  return result
 }
@@ -1,7 +1,8 @@
 export * as ConfigAttachment from "./attachment"

 import { Schema } from "effect"
-import { PositiveInt } from "@opencode-ai/core/schema"
+import { zod } from "@opencode-ai/core/effect-zod"
+import { PositiveInt, withStatics } from "@opencode-ai/core/schema"

 export const Image = Schema.Struct({
  auto_resize: Schema.optional(Schema.Boolean).annotate({
@@ -16,10 +17,14 @@ export const Image = Schema.Struct({
  max_base64_bytes: Schema.optional(PositiveInt).annotate({
    description: "Maximum base64 payload bytes for an image attachment (default: 4718592)",
  }),
-}).annotate({ identifier: "ImageAttachmentConfig" })
+})
+  .annotate({ identifier: "ImageAttachmentConfig" })
+  .pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Image = Schema.Schema.Type<typeof Image>

 export const Info = Schema.Struct({
  image: Schema.optional(Image).annotate({ description: "Image attachment configuration" }),
-}).annotate({ identifier: "AttachmentConfig" })
+})
+  .annotate({ identifier: "AttachmentConfig" })
+  .pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Info = Schema.Schema.Type<typeof Info>
@@ -1,10 +1,12 @@
 export * as ConfigCommand from "./command"

 import * as Log from "@opencode-ai/core/util/log"
-import { Cause, Exit, Schema } from "effect"
+import { Schema } from "effect"
 import { NamedError } from "@opencode-ai/core/util/error"
 import { Glob } from "@opencode-ai/core/util/glob"
 import { Bus } from "@/bus"
+import { zod } from "@opencode-ai/core/effect-zod"
+import { withStatics } from "@opencode-ai/core/schema"
 import { configEntryNameFromPath } from "./entry-name"
 import { InvalidError } from "./error"
 import * as ConfigMarkdown from "./markdown"
@@ -18,12 +20,10 @@ export const Info = Schema.Struct({
  agent: Schema.optional(Schema.String),
  model: Schema.optional(ConfigModelID),
  subtask: Schema.optional(Schema.Boolean),
-})
+}).pipe(withStatics((s) => ({ zod: zod(s) })))

 export type Info = Schema.Schema.Type<typeof Info>

-const decodeInfo = Schema.decodeUnknownExit(Info)
-
 export async function load(dir: string) {
  const result: Record<string, Info> = {}
  for (const item of await Glob.scan("{command,commands}/**/*.md", {
@@ -51,12 +51,12 @@ export async function load(dir: string) {
      ...md.data,
      template: md.content.trim(),
    }
-    const parsed = decodeInfo(config, { errors: "all", propertyOrder: "original" })
-    if (Exit.isSuccess(parsed)) {
-      result[config.name] = parsed.value
+    const parsed = Info.zod.safeParse(config)
+    if (parsed.success) {
+      result[config.name] = parsed.data
      continue
    }
-    throw new InvalidError({ path: item, message: Cause.pretty(parsed.cause) }, { cause: Cause.squash(parsed.cause) })
+    throw new InvalidError({ path: item, issues: parsed.error.issues }, { cause: parsed.error })
  }
  return result
 }
@@ -22,7 +22,8 @@ import { InstanceState } from "@/effect/instance-state"
 import { Context, Duration, Effect, Exit, Fiber, Layer, Option, Schema } from "effect"
 import { EffectFlock } from "@opencode-ai/core/util/effect-flock"
 import { containsPath } from "../project/instance-context"
-import { NonNegativeInt, PositiveInt, type DeepMutable } from "@opencode-ai/core/schema"
+import { zod } from "@opencode-ai/core/effect-zod"
+import { NonNegativeInt, PositiveInt, withStatics, type DeepMutable } from "@opencode-ai/core/schema"
 import { ConfigAgent } from "./agent"
 import { ConfigAttachment } from "./attachment"
 import { ConfigCommand } from "./command"
@@ -111,6 +112,8 @@ async function resolveLoadedPlugins<T extends { plugin?: ConfigPlugin.Spec[] }>(
  return config
 }

+export const Server = ConfigServer.Server.zod
+export const Layout = ConfigLayout.Layout.zod
 export type Layout = ConfigLayout.Layout

 const LogLevelRef = Schema.Literals(["DEBUG", "INFO", "WARN", "ERROR"]).annotate({
@@ -118,6 +121,14 @@ const LogLevelRef = Schema.Literals(["DEBUG", "INFO", "WARN", "ERROR"]).annotate
  description: "Log level",
 })

+// The Effect Schema is the canonical source of truth. The `.zod` compatibility
+// surface is derived from it so plugin/SDK Zod consumers keep working without
+// a parallel hand-maintained Zod definition.
+//
+// The walker emits `z.object({...})` which is non-strict by default. Config
+// historically uses `.strict()` (additionalProperties: false in openapi.json),
+// so layer that on after derivation. Re-apply the Config ref afterward
+// since `.strict()` strips the walker's meta annotation.
 export const Info = Schema.Struct({
  $schema: Schema.optional(Schema.String).annotate({
    description: "JSON schema reference for configuration validation",
@@ -134,7 +145,7 @@ export const Info = Schema.Struct({
  }),
  skills: Schema.optional(ConfigSkills.Info).annotate({ description: "Additional skill folder paths" }),
  reference: Schema.optional(ConfigReference.Info).annotate({
-    description: "Named git or local directory references that can be mentioned as @alias or @alias/path",
+    description: "Named git or local directory references that can be @ mentioned as Scout-backed subagents",
  }),
  watcher: Schema.optional(
    Schema.Struct({
@@ -262,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.",
@@ -290,7 +301,15 @@ export const Info = Schema.Struct({
      }),
    }),
  ),
-}).annotate({ identifier: "Config" })
+})
+  .annotate({ identifier: "Config" })
+  .pipe(
+    withStatics((s) => ({
+      zod: (zod(s) as unknown as z.ZodObject<any>).strict().meta({ ref: "Config" }) as unknown as z.ZodType<
+        DeepMutable<Schema.Schema.Type<typeof s>>
+      >,
+    })),
+  )

 // Uses the shared `DeepMutable` from `@opencode-ai/core/schema`. See the definition
 // there for why the local variant is needed over `Types.DeepMutable` from
@@ -388,7 +407,7 @@ export const layer = Layer.effect(
        ),
      )
      const parsed = ConfigParse.jsonc(expanded, source)
-      const data = ConfigParse.schema(Info, normalizeLoadedConfig(parsed, source), source)
+      const data = ConfigParse.effectSchema(Info, normalizeLoadedConfig(parsed, source), source)
      if (!("path" in options)) return data

      yield* Effect.promise(() => resolveLoadedPlugins(data, options.path))
@@ -786,7 +805,7 @@ export const layer = Layer.effect(
      let next: Info
      let changed: boolean
      if (!file.endsWith(".jsonc")) {
-        const existing = ConfigParse.schema(Info, ConfigParse.jsonc(before, file), file)
+        const existing = ConfigParse.effectSchema(Info, ConfigParse.jsonc(before, file), file)
        const merged = mergeDeep(writable(existing), patch)
        const serialized = JSON.stringify(merged, null, 2)
        changed = serialized !== before
@@ -794,7 +813,7 @@ export const layer = Layer.effect(
        next = merged
      } else {
        const updated = patchJsonc(before, patch)
-        next = ConfigParse.schema(Info, ConfigParse.jsonc(updated, file), file)
+        next = ConfigParse.effectSchema(Info, ConfigParse.jsonc(updated, file), file)
        changed = updated !== before
        if (changed) yield* fs.writeFileString(file, updated).pipe(Effect.orDie)
      }
@@ -1,11 +1,14 @@
 import { Schema } from "effect"
+import { zod } from "@opencode-ai/core/effect-zod"
 import { NonNegativeInt } from "@opencode-ai/core/schema"

 export class ConsoleState extends Schema.Class<ConsoleState>("ConsoleState")({
  consoleManagedProviders: Schema.mutable(Schema.Array(Schema.String)),
  activeOrgName: Schema.optional(Schema.String),
  switchableOrgCount: NonNegativeInt,
-}) {}
+}) {
+  static readonly zod = zod(this)
+}

 export const emptyConsoleState: ConsoleState = ConsoleState.make({
  consoleManagedProviders: [],
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Kit Langton	746381008d	test(session): clarify compaction test harness	2026-05-10 20:23:37 -04:00
Kit Langton	1e7586a93f	test(session): effectify remaining compaction process tests	2026-05-10 20:12:56 -04:00