test(provider): migrate more config-backed cases (#26984 )

test(provider): migrate provider tests to effect runner
test(project): stabilize VCS branch update test (#26979 )
2026-05-11 22:21:50 -04:00 · 2026-05-11 22:13:26 -04:00 · 2026-05-11 22:12:07 -04:00 · 2026-05-11 21:42:17 -04:00 · 2026-05-11 21:42:04 -04:00 · 2026-05-11 21:41:56 -04:00
292 changed files with 13774 additions and 8927 deletions
@@ -23,7 +23,7 @@ runs:
        fi

    - name: Setup Bun
-      uses: oven-sh/setup-bun@v2
+      uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
      with:
        bun-version-file: ${{ !steps.bun-url.outputs.url && 'package.json' || '' }}
        bun-download-url: ${{ steps.bun-url.outputs.url }}
@@ -34,7 +34,7 @@ runs:
      run: echo "dir=$(bun pm cache)" >> "$GITHUB_OUTPUT"

    - name: Cache Bun dependencies
-      uses: actions/cache@v4
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
      with:
        path: ${{ steps.cache.outputs.dir }}
        key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
@@ -19,7 +19,7 @@ runs:
  steps:
    - name: Create app token
      id: apptoken
-      uses: actions/create-github-app-token@v2
+      uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2.2.2
      with:
        app-id: ${{ inputs.opencode-app-id }}
        private-key: ${{ inputs.opencode-app-secret }}
@@ -13,7 +13,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0

@@ -12,9 +12,9 @@ jobs:
      contents: read
      issues: write
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

-      - uses: oven-sh/setup-bun@v2
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
        with:
          bun-version: latest

@@ -21,7 +21,7 @@ jobs:
    timeout-minutes: 15
    steps:
      - name: Close inactive PRs
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
@@ -16,7 +16,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Close non-compliant issues and PRs after 2 hours
-        uses: actions/github-script@v7
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
        with:
          script: |
            const { data: items } = await github.rest.issues.listForRepo({
@@ -21,18 +21,18 @@ jobs:
      REGISTRY: ghcr.io/${{ github.repository_owner }}
      TAG: "24.04"
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - uses: ./.github/actions/setup-bun

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

      - name: Login to GHCR
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
@@ -13,11 +13,11 @@ jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0

      - uses: ./.github/actions/setup-bun

-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "24"

@@ -16,7 +16,7 @@ jobs:
      contents: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          fetch-depth: 0
@@ -18,7 +18,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0 # Fetch full history to access commits

@@ -43,7 +43,7 @@ jobs:

      - name: Run opencode
        if: steps.commits.outputs.has_commits == 'true'
-        uses: sst/opencode/github@latest
+        uses: sst/opencode/github@2c14fc5586fe0b88e5c04732d2e846769cc35671 # latest
        env:
          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
        with:
@@ -13,7 +13,7 @@ jobs:
      issues: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 1

@@ -125,7 +125,7 @@ jobs:
      issues: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 1

@@ -13,7 +13,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Setup Bun
        uses: ./.github/actions/setup-bun
@@ -20,10 +20,10 @@ jobs:
    timeout-minutes: 15
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Nix
-        uses: nixbuild/nix-quick-install-action@v34
+        uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34

      - name: Evaluate flake outputs (all systems)
        run: |
@@ -41,10 +41,10 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Nix
-        uses: nixbuild/nix-quick-install-action@v34
+        uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34

      - name: Compute node_modules hash
        id: hash
@@ -72,7 +72,7 @@ jobs:
          echo "Computed hash for ${SYSTEM}: $HASH"

      - name: Upload hash
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: hash-${{ matrix.system }}
          path: hash.txt
@@ -85,7 +85,7 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          fetch-depth: 0
@@ -102,7 +102,7 @@ jobs:
          git pull --rebase --autostash origin "$GITHUB_REF_NAME"

      - name: Download hash artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          path: hashes
          pattern: hash-*
@@ -9,6 +9,6 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Send nicely-formatted embed to Discord
-        uses: SethCohen/github-releases-to-discord@v1
+        uses: SethCohen/github-releases-to-discord@24d166886aee4646d448c8a389ff9e1ebcab3682 # v1.20.0
        with:
          webhook_url: ${{ secrets.DISCORD_WEBHOOK }}
@@ -21,12 +21,12 @@ jobs:
      issues: read
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - uses: ./.github/actions/setup-bun

      - name: Run opencode
-        uses: anomalyco/opencode/github@latest
+        uses: anomalyco/opencode/github@2c14fc5586fe0b88e5c04732d2e846769cc35671 # latest
        env:
          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
          OPENCODE_PERMISSION: '{"bash": "deny"}'
@@ -12,7 +12,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 1

@@ -78,7 +78,7 @@ jobs:
      issues: write
    steps:
      - name: Add Contributor Label
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
        with:
          script: |
            const isPR = !!context.payload.pull_request;
@@ -12,7 +12,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Check PR standards
-        uses: actions/github-script@v7
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
        with:
          script: |
            const pr = context.payload.pull_request;
@@ -159,7 +159,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Check PR template compliance
-        uses: actions/github-script@v7
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
        with:
          script: |
            const pr = context.payload.pull_request;
@@ -16,7 +16,7 @@ jobs:
  publish:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
        with:
          fetch-depth: 0

@@ -15,7 +15,7 @@ jobs:
  publish:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
        with:
          fetch-depth: 0

@@ -35,7 +35,7 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    if: github.repository == 'anomalyco/opencode'
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
        with:
          fetch-depth: 0

@@ -72,7 +72,7 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    if: github.repository == 'anomalyco/opencode'
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
        with:
          fetch-tags: true

@@ -95,14 +95,14 @@ jobs:
          GH_REPO: ${{ needs.version.outputs.repo }}
          GH_TOKEN: ${{ steps.committer.outputs.token }}

-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: opencode-cli
          path: |
            packages/opencode/dist/opencode-darwin*
            packages/opencode/dist/opencode-linux*

-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: opencode-cli-windows
          path: packages/opencode/dist/opencode-windows*
@@ -123,9 +123,9 @@ jobs:
      AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE }}
      AZURE_TRUSTED_SIGNING_ENDPOINT: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0

-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: opencode-cli-windows
          path: packages/opencode/dist
@@ -138,13 +138,13 @@ jobs:
          opencode-app-secret: ${{ secrets.OPENCODE_APP_SECRET }}

      - name: Azure login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2.3.0
        with:
          client-id: ${{ env.AZURE_CLIENT_ID }}
          tenant-id: ${{ env.AZURE_TENANT_ID }}
          subscription-id: ${{ env.AZURE_SUBSCRIPTION_ID }}

-      - uses: azure/artifact-signing-action@v1
+      - uses: azure/artifact-signing-action@b443cf8ea4124818d2ea9f043cba29fc3ec47b16 # v1.2.0
        with:
          endpoint: ${{ env.AZURE_TRUSTED_SIGNING_ENDPOINT }}
          signing-account-name: ${{ env.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
@@ -201,7 +201,7 @@ jobs:
            --clobber `
            --repo "${{ needs.version.outputs.repo }}"

-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: opencode-cli-signed-windows
          path: |
@@ -249,9 +249,9 @@ jobs:
            platform_flag: --linux
    runs-on: ${{ matrix.settings.host }}
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0

-      - uses: apple-actions/import-codesign-certs@v2
+      - uses: apple-actions/import-codesign-certs@8f3fb608891dd2244cdab3d69cd68c0d37a7fe93 # v2.0.0
        if: runner.os == 'macOS'
        with:
          keychain: build
@@ -268,19 +268,19 @@ jobs:

      - name: Azure login
        if: runner.os == 'Windows'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2.3.0
        with:
          client-id: ${{ env.AZURE_CLIENT_ID }}
          tenant-id: ${{ env.AZURE_TENANT_ID }}
          subscription-id: ${{ env.AZURE_SUBSCRIPTION_ID }}

-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "24"

      - name: Cache apt packages
        if: contains(matrix.settings.host, 'ubuntu')
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: ~/apt-cache
          key: ${{ runner.os }}-${{ matrix.settings.target }}-apt-electron-${{ hashFiles('.github/workflows/publish.yml') }}
@@ -388,12 +388,12 @@ jobs:
            }
          }

-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: opencode-desktop-${{ matrix.settings.target }}
          path: packages/desktop/dist/*

-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: needs.version.outputs.release
        with:
          name: latest-yml-${{ matrix.settings.target }}
@@ -408,44 +408,44 @@ jobs:
    if: always() && !failure() && !cancelled()
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0

      - uses: ./.github/actions/setup-bun

      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"

-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: opencode-cli
          path: packages/opencode/dist

-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: opencode-cli-windows
          path: packages/opencode/dist

-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: opencode-cli-signed-windows
          path: packages/opencode/dist

-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        if: needs.version.outputs.release
        with:
          pattern: latest-yml-*
@@ -459,7 +459,7 @@ jobs:
          opencode-app-secret: ${{ secrets.OPENCODE_APP_SECRET }}

      - name: Cache apt packages (AUR)
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: /var/cache/apt/archives
          key: ${{ runner.os }}-apt-aur-${{ hashFiles('.github/workflows/publish.yml') }}
@@ -16,7 +16,7 @@ jobs:
  release:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0

@@ -25,7 +25,7 @@ jobs:
          fi

      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 1

@@ -16,7 +16,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Setup Bun
        uses: ./.github/actions/setup-bun
@@ -29,7 +29,7 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Setup Bun
        uses: ./.github/actions/setup-bun
@@ -10,7 +10,7 @@ jobs:
    name: Release Zed Extension
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0

@@ -37,12 +37,12 @@ jobs:
        shell: bash
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "24"

@@ -55,7 +55,7 @@ jobs:
          git config --global user.name "opencode"

      - name: Cache Turbo
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: node_modules/.cache/turbo
          key: turbo-${{ runner.os }}-${{ hashFiles('turbo.json', '**/package.json') }}-${{ github.sha }}
@@ -75,7 +75,7 @@ jobs:

      - name: Publish unit reports
        if: always()
-        uses: mikepenz/action-junit-report@v6
+        uses: mikepenz/action-junit-report@bccf2e31636835cf0874589931c4116687171386 # v6.4.0
        with:
          report_paths: packages/*/.artifacts/unit/junit.xml
          check_name: "unit results (${{ matrix.settings.name }})"
@@ -85,7 +85,7 @@ jobs:

      - name: Upload unit artifacts
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: unit-${{ matrix.settings.name }}-${{ github.run_attempt }}
          include-hidden-files: true
@@ -111,12 +111,12 @@ jobs:
        shell: bash
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "24"

@@ -131,7 +131,7 @@ jobs:

      - name: Cache Playwright browsers
        id: playwright-cache
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: ${{ github.workspace }}/.playwright-browsers
          key: ${{ runner.os }}-${{ runner.arch }}-playwright-${{ steps.playwright-version.outputs.version }}-chromium
@@ -155,7 +155,7 @@ jobs:

      - name: Upload Playwright artifacts
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: playwright-${{ matrix.settings.name }}-${{ github.run_attempt }}
          if-no-files-found: ignore
@@ -12,7 +12,7 @@ jobs:
      issues: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 1

@@ -12,7 +12,7 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Setup Bun
        uses: ./.github/actions/setup-bun
@@ -29,7 +29,7 @@
    },
    "packages/app": {
      "name": "@opencode-ai/app",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@opencode-ai/core": "workspace:*",
@@ -85,7 +85,7 @@
    },
    "packages/console/app": {
      "name": "@opencode-ai/console-app",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "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.46",
+      "version": "1.14.48",
      "dependencies": {
        "@aws-sdk/client-sts": "3.782.0",
        "@jsx-email/render": "1.1.1",
@@ -147,17 +147,15 @@
    },
    "packages/console/function": {
      "name": "@opencode-ai/console-function",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "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": {
@@ -171,7 +169,7 @@
    },
    "packages/console/mail": {
      "name": "@opencode-ai/console-mail",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@jsx-email/all": "2.2.3",
        "@jsx-email/cli": "1.4.3",
@@ -195,7 +193,7 @@
    },
    "packages/core": {
      "name": "@opencode-ai/core",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "bin": {
        "opencode": "./bin/opencode",
      },
@@ -229,7 +227,7 @@
    },
    "packages/desktop": {
      "name": "@opencode-ai/desktop",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "drizzle-orm": "catalog:",
        "effect": "catalog:",
@@ -283,7 +281,7 @@
    },
    "packages/enterprise": {
      "name": "@opencode-ai/enterprise",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@opencode-ai/core": "workspace:*",
        "@opencode-ai/ui": "workspace:*",
@@ -313,7 +311,7 @@
    },
    "packages/function": {
      "name": "@opencode-ai/function",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@octokit/auth-app": "8.0.1",
        "@octokit/rest": "catalog:",
@@ -329,7 +327,7 @@
    },
    "packages/http-recorder": {
      "name": "@opencode-ai/http-recorder",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@effect/platform-node": "catalog:",
        "effect": "catalog:",
@@ -342,7 +340,7 @@
    },
    "packages/llm": {
      "name": "@opencode-ai/llm",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@smithy/eventstream-codec": "4.2.14",
        "@smithy/util-utf8": "4.2.2",
@@ -360,7 +358,7 @@
    },
    "packages/opencode": {
      "name": "opencode",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "bin": {
        "opencode": "./bin/opencode",
      },
@@ -496,7 +494,7 @@
    },
    "packages/plugin": {
      "name": "@opencode-ai/plugin",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@opencode-ai/sdk": "workspace:*",
        "effect": "catalog:",
@@ -534,7 +532,7 @@
    },
    "packages/sdk/js": {
      "name": "@opencode-ai/sdk",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "cross-spawn": "catalog:",
      },
@@ -549,7 +547,7 @@
    },
    "packages/slack": {
      "name": "@opencode-ai/slack",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@opencode-ai/sdk": "workspace:*",
        "@slack/bolt": "^3.17.1",
@@ -584,7 +582,7 @@
    },
    "packages/ui": {
      "name": "@opencode-ai/ui",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@opencode-ai/core": "workspace:*",
@@ -633,7 +631,7 @@
    },
    "packages/web": {
      "name": "@opencode-ai/web",
-      "version": "1.14.46",
+      "version": "1.14.48",
      "dependencies": {
        "@astrojs/cloudflare": "12.6.3",
        "@astrojs/markdown-remark": "6.3.1",
@@ -686,8 +684,8 @@
  },
  "catalog": {
    "@cloudflare/workers-types": "4.20251008.0",
-    "@effect/opentelemetry": "4.0.0-beta.57",
-    "@effect/platform-node": "4.0.0-beta.57",
+    "@effect/opentelemetry": "4.0.0-beta.65",
+    "@effect/platform-node": "4.0.0-beta.65",
    "@hono/zod-validator": "0.4.2",
    "@kobalte/core": "0.13.11",
    "@lydell/node-pty": "1.2.0-beta.10",
@@ -720,7 +718,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.59",
+    "effect": "4.0.0-beta.65",
    "fuzzysort": "3.1.0",
    "hono": "4.10.7",
    "hono-openapi": "1.1.2",
@@ -1081,11 +1079,11 @@

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

-    "@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/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/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": ["@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-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=="],
+    "@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=="],

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

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

    "@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=="],
@@ -3041,7 +3037,7 @@

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

-    "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=="],
+    "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=="],

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

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

    "@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,6 +1,8 @@
 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`,
@@ -25,6 +27,16 @@ 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" },
@@ -32,21 +44,26 @@ 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: [
-      {
-        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)`,
-      },
-    ],
+    calculatedFields: [failedHttpStatus],
    calculations: [
      { op: "COUNT", name: "TOTAL", filterCombination: "AND", filters },
-      { op: "SUM", name: "FAILED", column: "is_failed_http_status", filterCombination: "AND", filters },
+      {
+        op: "SUM",
+        name: "FAILED",
+        column: failedHttpStatus.name,
+        filterCombination: "AND",
+        filters,
+      },
    ],
    formulas: [{ name: "ERROR", expression: "IF(GTE($TOTAL, 100), DIV($FAILED, $TOTAL), 0)" }],
    timeRange: 900,
@@ -59,31 +76,30 @@ 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: [
-      {
-        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)`,
-      },
-    ],
+    calculatedFields: [successHttpStatus, failedProviderHttpStatus],
    calculations: [
      {
        op: "SUM",
        name: "SUCCESS",
-        column: "is_success_http_status",
+        column: successHttpStatus.name,
        filterCombination: "AND",
        filters: [...filters, { column: "event_type", op: "=", value: "completions" }],
      },
      {
        op: "SUM",
        name: "FAILED",
-        column: "is_failed_provider_http_status",
+        column: failedProviderHttpStatus.name,
        filterCombination: "AND",
        filters: [...filters, { column: "event_type", op: "=", value: "llm.error" }],
      },
@@ -95,8 +111,6 @@ 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-baGxh+hk/rPhg0xI/OdMDz6dPwncgercYNBdTPnLX9o=",
-    "aarch64-linux": "sha256-VTWKq679B3Q4ZnAoQzC4VSCYA09wWecNJ+JajvjNB1U=",
-    "aarch64-darwin": "sha256-orf2zIBMTiiQrt/6qCzE+o0oKhv6u8zXF9DH1Bo3lbo=",
-    "x86_64-darwin": "sha256-1MZC1fadRoY4lhkmjlcUQTLYH9Q8pDI1bxd5f94f1xU="
+    "x86_64-linux": "sha256-Q9r1S15YL9LQK7DRhuOpw3Fxi24BPovEM995GZJayKw=",
+    "aarch64-linux": "sha256-C0rRTLnxxuuEkCBc3JZbkR66TUVwpcPFif3BU9GRAuA=",
+    "aarch64-darwin": "sha256-1HvalOO/pOkRlYH8CZ93psapt90C+pYzui1JCadBE1Q=",
+    "x86_64-darwin": "sha256-RrndyLWfhWm4mZ88XytFF2NI+ly8la550Z5LBN/g5u4="
  }
 }
@@ -28,8 +28,8 @@
      "packages/slack"
    ],
    "catalog": {
-      "@effect/opentelemetry": "4.0.0-beta.57",
-      "@effect/platform-node": "4.0.0-beta.57",
+      "@effect/opentelemetry": "4.0.0-beta.65",
+      "@effect/platform-node": "4.0.0-beta.65",
      "@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.59",
+      "effect": "4.0.0-beta.65",
      "ai": "6.0.168",
      "cross-spawn": "7.0.6",
      "hono": "4.10.7",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/app",
-  "version": "1.14.46",
+  "version": "1.14.48",
  "description": "",
  "type": "module",
  "exports": {
@@ -231,6 +231,7 @@ export function createChildStoreManager(input: {
            limit: 5,
            message: {},
            part: {},
+            part_text_accum_delta: {},
          })
          children[key] = child
          disposers.set(key, dispose)
@@ -81,6 +81,7 @@ const baseState = (input: Partial<State> = {}) =>
    limit: 10,
    message: {},
    part: {},
+    part_text_accum_delta: {},
    ...input,
  }) as State

@@ -211,6 +211,12 @@ 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]
        }),
      )
@@ -219,6 +225,11 @@ 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])
@@ -240,6 +251,11 @@ 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)
@@ -263,6 +279,7 @@ 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,6 +39,7 @@ 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: [] },
@@ -47,12 +48,14 @@ 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()
@@ -70,6 +73,7 @@ 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: {},
@@ -78,6 +82,7 @@ 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,6 +18,7 @@ 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>) {
@@ -27,6 +28,9 @@ 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,6 +72,9 @@ export type State = {
  part: {
    [messageID: string]: Part[]
  }
+  part_text_accum_delta: {
+    [partID: string]: string
+  }
 }

 export type VcsCache = {
@@ -43,6 +43,7 @@ type SessionView = {
  reviewOpen?: string[]
  pendingMessage?: string
  pendingMessageAt?: number
+  todoCollapsed?: boolean
 }

 type TabHandoff = {
@@ -759,6 +760,18 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
          setScroll(tab: string, pos: SessionScroll) {
            scroll.setScroll(key(), tab, pos)
          },
+          todoCollapsed: {
+            get: () => s().todoCollapsed ?? false,
+            set(collapsed: boolean) {
+              const session = key()
+              const current = store.sessionView[session]
+              if (!current) {
+                setStore("sessionView", session, { scroll: {}, todoCollapsed: collapsed })
+              } else {
+                setStore("sessionView", session, "todoCollapsed", collapsed)
+              }
+            },
+          },
          terminal: {
            opened: terminalOpened,
            open() {
@@ -1934,7 +1934,7 @@ export default function Layout(props: ParentProps) {

    if (!created?.directory) return

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

    const local = project.worktree
    const key = pathKey(created.directory)
@@ -2,6 +2,7 @@ import { Show, createEffect, createMemo, onCleanup } from "solid-js"
 import { createStore } from "solid-js/store"
 import { useNavigate } from "@solidjs/router"
 import { useSpring } from "@opencode-ai/ui/motion-spring"
+import { useLayout } from "@/context/layout"
 import { PromptInput } from "@/components/prompt-input"
 import { useLanguage } from "@/context/language"
 import { usePrompt } from "@/context/prompt"
@@ -46,10 +47,12 @@ export function SessionComposerRegion(props: {
  setPromptDockRef: (el: HTMLDivElement) => void
 }) {
  const navigate = useNavigate()
+  const layout = useLayout()
  const prompt = usePrompt()
  const language = useLanguage()
  const route = useSessionKey()
  const sync = useSync()
+  const view = layout.view(route.sessionKey)

  const handoffPrompt = createMemo(() => getSessionHandoff(route.sessionKey())?.prompt)
  const info = createMemo(() => (route.params.id ? sync.session.get(route.params.id) : undefined))
@@ -207,6 +210,8 @@ export function SessionComposerRegion(props: {
                  <SessionTodoDock
                    sessionID={route.params.id}
                    todos={props.state.todos()}
+                    collapsed={view.todoCollapsed.get()}
+                    onToggle={() => view.todoCollapsed.set(!view.todoCollapsed.get())}
                    collapseLabel={language.t("session.todo.collapse")}
                    expandLabel={language.t("session.todo.expand")}
                    dockProgress={value()}
@@ -42,18 +42,17 @@ function dot(status: Todo["status"]) {
 export function SessionTodoDock(props: {
  sessionID?: string
  todos: Todo[]
+  collapsed: boolean
+  onToggle: () => void
  collapseLabel: string
  expandLabel: string
  dockProgress: number
 }) {
  const language = useLanguage()
  const [store, setStore] = createStore({
-    collapsed: false,
    height: 320,
  })

-  const toggle = () => setStore("collapsed", (value) => !value)
-
  const total = createMemo(() => props.todos.length)
  const done = createMemo(() => props.todos.filter((todo) => todo.status === "completed").length)
  const label = createMemo(() => language.t("session.todo.progress", { done: done(), total: total() }))
@@ -72,7 +71,7 @@ export function SessionTodoDock(props: {
  )

  const preview = createMemo(() => active()?.content ?? "")
-  const collapse = useSpring(() => (store.collapsed ? 1 : 0), { visualDuration: 0.3, bounce: 0 })
+  const collapse = useSpring(() => (props.collapsed ? 1 : 0), { visualDuration: 0.3, bounce: 0 })
  const dock = createMemo(() => Math.max(0, Math.min(1, props.dockProgress)))
  const shut = createMemo(() => 1 - dock())
  const value = createMemo(() => Math.max(0, Math.min(1, collapse())))
@@ -107,11 +106,11 @@ export function SessionTodoDock(props: {
          class="pl-3 pr-2 py-2 flex items-center gap-2 overflow-visible"
          role="button"
          tabIndex={0}
-          onClick={toggle}
+          onClick={props.onToggle}
          onKeyDown={(event) => {
            if (event.key !== "Enter" && event.key !== " ") return
            event.preventDefault()
-            toggle()
+            props.onToggle()
          }}
        >
          <span
@@ -148,7 +147,7 @@ export function SessionTodoDock(props: {
          >
            <TextReveal
              class="text-14-regular text-text-base cursor-default"
-              text={store.collapsed ? preview() : undefined}
+              text={props.collapsed ? preview() : undefined}
              duration={600}
              travel={25}
              edge={17}
@@ -161,7 +160,7 @@ export function SessionTodoDock(props: {
          <div class="ml-auto">
            <IconButton
              data-action="session-todo-toggle-button"
-              data-collapsed={store.collapsed ? "true" : "false"}
+              data-collapsed={props.collapsed ? "true" : "false"}
              icon="chevron-down"
              size="normal"
              variant="ghost"
@@ -172,16 +171,16 @@ export function SessionTodoDock(props: {
              }}
              onClick={(event) => {
                event.stopPropagation()
-                toggle()
+                props.onToggle()
              }}
-              aria-label={store.collapsed ? props.expandLabel : props.collapseLabel}
+              aria-label={props.collapsed ? props.expandLabel : props.collapseLabel}
            />
          </div>
        </div>

        <div
          data-slot="session-todo-list"
-          aria-hidden={store.collapsed || off()}
+          aria-hidden={props.collapsed || off()}
          classList={{
            "pointer-events-none": hide() > 0.1,
          }}
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/console-app",
-  "version": "1.14.46",
+  "version": "1.14.48",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -47,6 +47,7 @@ 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 = {
@@ -129,6 +130,8 @@ 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(
@@ -142,6 +145,7 @@ export async function handler(
        retry,
        stickyProvider,
        modelTpmLimits,
+        modelTpsLimits,
      )
      validateModelSettings(billingSource, authInfo)
      updateProviderKey(authInfo, providerInfo)
@@ -294,14 +298,17 @@ 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": Date.now(),
+                  "timestamp.last_byte": timestampLastByte,
                })
                dataDumper?.flush()
                await rateLimiter?.track()
@@ -311,6 +318,13 @@ 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)
@@ -321,10 +335,10 @@ export async function handler(
              }

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

@@ -478,6 +492,7 @@ 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
@@ -509,6 +524,11 @@ 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
@@ -0,0 +1,89 @@
+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}`,
+            },
+          }),
+      )
+    },
+  }
+}
@@ -0,0 +1,7 @@
+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.46",
+  "version": "1.14.48",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -36,6 +36,7 @@ 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,3 +40,14 @@ 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.46",
+  "version": "1.14.48",
  "$schema": "https://json.schemastore.org/package.json",
  "private": true,
  "type": "module",
@@ -20,12 +20,10 @@
    "@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.46",
+  "version": "1.14.48",
  "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.46",
+  "version": "1.14.48",
  "name": "@opencode-ai/core",
  "type": "module",
  "license": "MIT",
@@ -1,370 +0,0 @@
-import { Effect, Option, Schema, SchemaAST } from "effect"
-import z from "zod"
-
-/**
- * Annotation key for providing a hand-crafted Zod schema that the walker
- * should use instead of re-deriving from the AST.  Attach it via
- * `Schema.String.annotate({ [ZodOverride]: z.string().startsWith("per") })`.
- */
-export const ZodOverride: unique symbol = Symbol.for("effect-zod/override")
-
-// AST nodes are immutable and frequently shared across schemas (e.g. a single
-// Schema.Class embedded in multiple parents). Memoizing by node identity
-// avoids rebuilding equivalent Zod subtrees and keeps derived children stable
-// by reference across callers.
-const walkCache = new WeakMap<SchemaAST.AST, z.ZodTypeAny>()
-
-// Shared empty ParseOptions for the rare callers that need one — avoids
-// allocating a fresh object per parse inside refinements and transforms.
-const EMPTY_PARSE_OPTIONS = {} as SchemaAST.ParseOptions
-
-export function zod<S extends Schema.Top>(schema: S): z.ZodType<Schema.Schema.Type<S>> {
-  return walk(schema.ast) as z.ZodType<Schema.Schema.Type<S>>
-}
-
-/**
- * Derive a Zod value from an Effect Schema (or a Schema-backed export with a
- * `.zod` static) and narrow the result to `z.ZodObject<any>` so `.shape`,
- * `.omit`, `.extend`, and friends are accessible.
- *
- * The `zod()` walker returns `z.ZodType<T>` because not every AST node decodes
- * to an object; this helper keeps the "I started from a `Schema.Struct`" cast
- * in one place instead of sprinkling `as unknown as z.ZodObject<any>` across
- * call sites.
- *
- * The return is intentionally loose — carrying Schema field types through the
- * 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`,
- * `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.
- */
-export function zodObject<S extends Schema.Top>(schema: S): z.ZodObject<any> {
-  const derived: z.ZodTypeAny = "zod" in schema && isZodType(schema.zod) ? schema.zod : walk(schema.ast)
-  return derived as unknown as z.ZodObject<any>
-}
-
-function isZodType(value: unknown): value is z.ZodTypeAny {
-  return typeof value === "object" && value !== null && "_zod" in value
-}
-
-/**
- * Emit a JSON Schema for a tool/route parameter schema — derives the zod form
- * via the walker so Effect Schema inputs flow through the same zod-openapi
- * pipeline the LLM/SDK layer already depends on.  `io: "input"` mirrors what
- * `session/prompt.ts` has always passed to `ai`'s `jsonSchema()` helper.
- */
-export function toJsonSchema<S extends Schema.Top>(schema: S) {
-  return z.toJSONSchema(zod(schema), { io: "input" })
-}
-
-function walk(ast: SchemaAST.AST): z.ZodTypeAny {
-  const cached = walkCache.get(ast)
-  if (cached) return cached
-  const result = walkUncached(ast)
-  walkCache.set(ast, result)
-  return result
-}
-
-function walkUncached(ast: SchemaAST.AST): z.ZodTypeAny {
-  const override = (ast.annotations as any)?.[ZodOverride] as z.ZodTypeAny | undefined
-  // `description` annotations layer on top of an override so callers can
-  // reuse a shared override schema (e.g. `SessionID`) and still add a
-  // per-field description on the outer wrapper.
-  const base = override ?? bodyWithChecks(ast)
-  const desc = SchemaAST.resolveDescription(ast)
-  const ref = SchemaAST.resolveIdentifier(ast)
-  const described = desc ? base.describe(desc) : base
-  return ref ? described.meta({ ref }) : described
-}
-
-function bodyWithChecks(ast: SchemaAST.AST): z.ZodTypeAny {
-  // Schema.Class wraps its fields in a Declaration AST plus an encoding that
-  // constructs the class instance. For the Zod derivation we want the plain
-  // field shape (the decoded/consumer view), not the class instance — so
-  // Declarations fall through to body(), not encoded(). User-level
-  // Schema.decodeTo / Schema.transform attach encoding to non-Declaration
-  // nodes, where we do apply the transform.
-  //
-  // Schema.withDecodingDefault also attaches encoding, but we want `.default(v)`
-  // on the inner Zod rather than a transform wrapper — so optional ASTs whose
-  // encoding resolves a default from Option.none() route through body()/opt().
-  const hasEncoding = ast.encoding?.length && (ast._tag !== "Declaration" || ast.typeParameters.length === 0)
-  const hasTransform = hasEncoding && !(SchemaAST.isOptional(ast) && extractDefault(ast) !== undefined)
-  const base = hasTransform ? encoded(ast) : body(ast)
-  return ast.checks?.length ? applyChecks(base, ast.checks, ast) : base
-}
-
-// Walk the encoded side and apply each link's decode to produce the decoded
-// shape. A node `Target` produced by `from.decodeTo(Target)` carries
-// `Target.encoding = [Link(from, transformation)]`. Chained decodeTo calls
-// nest the encoding via `Link.to` so walking it recursively threads all
-// prior transforms — typical encoding.length is 1.
-function encoded(ast: SchemaAST.AST): z.ZodTypeAny {
-  const encoding = ast.encoding!
-  return encoding.reduce<z.ZodTypeAny>(
-    (acc, link) => acc.transform((v) => decode(link.transformation, v)),
-    walk(encoding[0].to),
-  )
-}
-
-// Transformations built via pure `SchemaGetter.transform(fn)` (the common
-// decodeTo case) resolve synchronously, so running with no services is safe.
-// Effectful / middleware-based transforms will surface as Effect defects.
-function decode(transformation: SchemaAST.Link["transformation"], value: unknown): unknown {
-  const exit = Effect.runSyncExit(
-    (transformation.decode as any).run(Option.some(value), EMPTY_PARSE_OPTIONS) as Effect.Effect<
-      Option.Option<unknown>
-    >,
-  )
-  if (exit._tag === "Failure") throw new Error(`effect-zod: transform failed: ${String(exit.cause)}`)
-  return Option.getOrElse(exit.value, () => value)
-}
-
-// Flatten FilterGroups and any nested variants into a linear list of Filters.
-// Well-known filters (Schema.isInt, isGreaterThan, isPattern, …) are
-// translated into native Zod methods so their JSON Schema output includes
-// the corresponding constraint (type: integer, exclusiveMinimum, pattern, …).
-// Anything else falls back to a single .superRefine layer — runtime-only,
-// emits no JSON Schema constraint.
-function applyChecks(out: z.ZodTypeAny, checks: SchemaAST.Checks, ast: SchemaAST.AST): z.ZodTypeAny {
-  const filters: SchemaAST.Filter<unknown>[] = []
-  const collect = (c: SchemaAST.Check<unknown>) => {
-    if (c._tag === "FilterGroup") c.checks.forEach(collect)
-    else filters.push(c)
-  }
-  checks.forEach(collect)
-
-  const unhandled: SchemaAST.Filter<unknown>[] = []
-  const translated = filters.reduce<z.ZodTypeAny>((acc, filter) => {
-    const next = translateFilter(acc, filter)
-    if (next) return next
-    unhandled.push(filter)
-    return acc
-  }, out)
-
-  if (unhandled.length === 0) return translated
-
-  return translated.superRefine((value, ctx) => {
-    for (const filter of unhandled) {
-      const issue = filter.run(value, ast, EMPTY_PARSE_OPTIONS)
-      if (!issue) continue
-      const message = issueMessage(issue) ?? (filter.annotations as any)?.message ?? "Validation failed"
-      ctx.addIssue({ code: "custom", message })
-    }
-  })
-}
-
-// Translate a well-known Effect Schema filter into a native Zod method call on
-// `out`. Dispatch is keyed on `filter.annotations.meta._tag`, which every
-// built-in check factory (isInt, isGreaterThan, isPattern, …) attaches at
-// construction time. Returns `undefined` for unrecognised filters so the
-// caller can fall back to the generic .superRefine path.
-function translateFilter(out: z.ZodTypeAny, filter: SchemaAST.Filter<unknown>): z.ZodTypeAny | undefined {
-  const meta = (filter.annotations as { meta?: Record<string, unknown> } | undefined)?.meta
-  if (!meta || typeof meta._tag !== "string") return undefined
-  switch (meta._tag) {
-    case "isInt":
-      return call(out, "int")
-    case "isFinite":
-      return call(out, "finite")
-    case "isGreaterThan":
-      return call(out, "gt", meta.exclusiveMinimum)
-    case "isGreaterThanOrEqualTo":
-      return call(out, "gte", meta.minimum)
-    case "isLessThan":
-      return call(out, "lt", meta.exclusiveMaximum)
-    case "isLessThanOrEqualTo":
-      return call(out, "lte", meta.maximum)
-    case "isBetween": {
-      const lo = meta.exclusiveMinimum ? call(out, "gt", meta.minimum) : call(out, "gte", meta.minimum)
-      if (!lo) return undefined
-      return meta.exclusiveMaximum ? call(lo, "lt", meta.maximum) : call(lo, "lte", meta.maximum)
-    }
-    case "isMultipleOf":
-      return call(out, "multipleOf", meta.divisor)
-    case "isMinLength":
-      return call(out, "min", meta.minLength)
-    case "isMaxLength":
-      return call(out, "max", meta.maxLength)
-    case "isLengthBetween": {
-      const lo = call(out, "min", meta.minimum)
-      if (!lo) return undefined
-      return call(lo, "max", meta.maximum)
-    }
-    case "isPattern":
-      return call(out, "regex", meta.regExp)
-    case "isStartsWith":
-      return call(out, "startsWith", meta.startsWith)
-    case "isEndsWith":
-      return call(out, "endsWith", meta.endsWith)
-    case "isIncludes":
-      return call(out, "includes", meta.includes)
-    case "isUUID":
-      return call(out, "uuid")
-    case "isULID":
-      return call(out, "ulid")
-    case "isBase64":
-      return call(out, "base64")
-    case "isBase64Url":
-      return call(out, "base64url")
-  }
-  return undefined
-}
-
-// Invoke a named Zod method on `target` if it exists, otherwise return
-// undefined so the caller can fall back. Using this helper instead of a
-// typed cast keeps `translateFilter` free of per-case narrowing noise.
-function call(target: z.ZodTypeAny, method: string, ...args: unknown[]): z.ZodTypeAny | undefined {
-  const fn = (target as unknown as Record<string, ((...a: unknown[]) => z.ZodTypeAny) | undefined>)[method]
-  return typeof fn === "function" ? fn.apply(target, args) : undefined
-}
-
-function issueMessage(issue: any): string | undefined {
-  if (typeof issue?.annotations?.message === "string") return issue.annotations.message
-  if (typeof issue?.message === "string") return issue.message
-  return undefined
-}
-
-function body(ast: SchemaAST.AST): z.ZodTypeAny {
-  if (SchemaAST.isOptional(ast)) return opt(ast)
-
-  switch (ast._tag) {
-    case "String":
-      return z.string()
-    case "Number":
-      return z.number()
-    case "Boolean":
-      return z.boolean()
-    case "Null":
-      return z.null()
-    case "Undefined":
-      return z.undefined()
-    case "Any":
-    case "Unknown":
-      return z.unknown()
-    case "Never":
-      return z.never()
-    case "Literal":
-      return z.literal(ast.literal)
-    case "Union":
-      return union(ast)
-    case "Objects":
-      return object(ast)
-    case "Arrays":
-      return array(ast)
-    case "Declaration":
-      return decl(ast)
-    default:
-      return fail(ast)
-  }
-}
-
-function opt(ast: SchemaAST.AST): z.ZodTypeAny {
-  if (ast._tag !== "Union") return fail(ast)
-  const items = ast.types.filter((item) => item._tag !== "Undefined")
-  const inner =
-    items.length === 1
-      ? walk(items[0])
-      : items.length > 1
-        ? z.union(items.map(walk) as [z.ZodTypeAny, z.ZodTypeAny, ...Array<z.ZodTypeAny>])
-        : z.undefined()
-  // Schema.withDecodingDefault attaches an encoding `Link` whose transformation
-  // decode Getter resolves `Option.none()` to `Option.some(default)`.  Invoke
-  // it to extract the default and emit `.default(...)` instead of `.optional()`.
-  const fallback = extractDefault(ast)
-  if (fallback !== undefined) return inner.default(fallback.value)
-  return inner.optional()
-}
-
-type DecodeLink = {
-  readonly transformation: {
-    readonly decode: {
-      readonly run: (
-        input: Option.Option<unknown>,
-        options: SchemaAST.ParseOptions,
-      ) => Effect.Effect<Option.Option<unknown>, unknown>
-    }
-  }
-}
-
-function extractDefault(ast: SchemaAST.AST): { value: unknown } | undefined {
-  const encoding = (ast as { encoding?: ReadonlyArray<DecodeLink> }).encoding
-  if (!encoding?.length) return undefined
-  // Walk the chain of encoding Links in order; the first Getter that produces
-  // a value from Option.none wins.  withDecodingDefault always puts its
-  // defaulting Link adjacent to the optional Union.
-  for (const link of encoding) {
-    const probe = Effect.runSyncExit(link.transformation.decode.run(Option.none(), {}))
-    if (probe._tag !== "Success") continue
-    if (Option.isSome(probe.value)) return { value: probe.value.value }
-  }
-  return undefined
-}
-
-function union(ast: SchemaAST.Union): z.ZodTypeAny {
-  // When every member is a string literal, emit z.enum() so that
-  // JSON Schema produces { "enum": [...] } instead of { "anyOf": [{ "const": ... }] }.
-  if (ast.types.length >= 2 && ast.types.every((t) => t._tag === "Literal" && typeof t.literal === "string")) {
-    return z.enum(ast.types.map((t) => (t as SchemaAST.Literal).literal as string) as [string, ...string[]])
-  }
-
-  const items = ast.types.map(walk)
-  if (items.length === 1) return items[0]
-  if (items.length < 2) return fail(ast)
-
-  const discriminator = ast.annotations?.discriminator
-  if (typeof discriminator === "string") {
-    return z.discriminatedUnion(discriminator, items as [z.ZodObject<any>, z.ZodObject<any>, ...z.ZodObject<any>[]])
-  }
-
-  return z.union(items as [z.ZodTypeAny, z.ZodTypeAny, ...Array<z.ZodTypeAny>])
-}
-
-function object(ast: SchemaAST.Objects): z.ZodTypeAny {
-  // Pure record: { [k: string]: V }
-  if (ast.propertySignatures.length === 0 && ast.indexSignatures.length === 1) {
-    const sig = ast.indexSignatures[0]
-    if (sig.parameter._tag !== "String") return fail(ast)
-    return z.record(z.string(), walk(sig.type))
-  }
-
-  // Pure object with known fields and no index signatures.
-  if (ast.indexSignatures.length === 0) {
-    return z.object(Object.fromEntries(ast.propertySignatures.map((sig) => [String(sig.name), walk(sig.type)])))
-  }
-
-  // Struct with a catchall (StructWithRest): known fields + index signature.
-  // Only supports a single string-keyed index signature; multi-signature or
-  // symbol/number keys fall through to fail.
-  if (ast.indexSignatures.length !== 1) return fail(ast)
-  const sig = ast.indexSignatures[0]
-  if (sig.parameter._tag !== "String") return fail(ast)
-  return z
-    .object(Object.fromEntries(ast.propertySignatures.map((p) => [String(p.name), walk(p.type)])))
-    .catchall(walk(sig.type))
-}
-
-function array(ast: SchemaAST.Arrays): z.ZodTypeAny {
-  // Pure variadic arrays: { elements: [], rest: [item] }
-  if (ast.elements.length === 0) {
-    if (ast.rest.length !== 1) return fail(ast)
-    return z.array(walk(ast.rest[0]))
-  }
-  // Fixed-length tuples: { elements: [a, b, ...], rest: [] }
-  // Tuples with a variadic tail (...rest) are not yet supported.
-  if (ast.rest.length > 0) return fail(ast)
-  const items = ast.elements.map(walk)
-  return z.tuple(items as [z.ZodTypeAny, ...Array<z.ZodTypeAny>])
-}
-
-function decl(ast: SchemaAST.Declaration): z.ZodTypeAny {
-  if (ast.typeParameters.length !== 1) return fail(ast)
-  return walk(ast.typeParameters[0])
-}
-
-function fail(ast: SchemaAST.AST): never {
-  const ref = SchemaAST.resolveIdentifier(ast)
-  throw new Error(`unsupported effect schema: ${ref ?? ast._tag}`)
-}
@@ -1,5 +1,4 @@
 import { Config } from "effect"
-import { InstallationChannel } from "../installation/version"

 function truthy(key: string) {
  const value = process.env[key]?.toLowerCase()
@@ -11,13 +10,6 @@ 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
@@ -56,9 +48,6 @@ 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"],
@@ -96,6 +85,7 @@ 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,5 +1,4 @@
 import { Option, Schema, SchemaGetter } from "effect"
-import { zod, ZodOverride } from "./effect-zod"

 /**
 * Integer greater than zero.
@@ -21,7 +20,6 @@ export const optionalOmitUndefined = <S extends Schema.Top>(schema: S) =>
      decode: SchemaGetter.passthrough({ strict: false }),
      encode: SchemaGetter.transformOptional(Option.filter((value) => value !== undefined)),
    }),
-    Schema.annotate({ [ZodOverride]: zod(schema).optional() }),
  )

 /**
@@ -1,7 +1,7 @@
 {
  "name": "@opencode-ai/desktop",
  "private": true,
-  "version": "1.14.46",
+  "version": "1.14.48",
  "type": "module",
  "license": "MIT",
  "homepage": "https://opencode.ai",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/enterprise",
-  "version": "1.14.46",
+  "version": "1.14.48",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -1,7 +1,7 @@
 id = "opencode"
 name = "OpenCode"
 description = "The open source coding agent."
-version = "1.14.46"
+version = "1.14.48"
 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.46/opencode-darwin-arm64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/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.46/opencode-darwin-x64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/opencode-darwin-x64.zip"
 cmd = "./opencode"
 args = ["acp"]

 [agent_servers.opencode.targets.linux-aarch64]
-archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.46/opencode-linux-arm64.tar.gz"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/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.46/opencode-linux-x64.tar.gz"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/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.46/opencode-windows-x64.zip"
+archive = "https://github.com/anomalyco/opencode/releases/download/v1.14.48/opencode-windows-x64.zip"
 cmd = "./opencode.exe"
 args = ["acp"]
@@ -1,6 +1,6 @@
 {
  "name": "@opencode-ai/function",
-  "version": "1.14.46",
+  "version": "1.14.48",
  "$schema": "https://json.schemastore.org/package.json",
  "private": true,
  "type": "module",
@@ -70,19 +70,15 @@ Cassettes are normal source files — review them, diff them, commit them.

 ## Request matching

-By default, requests match on canonicalized method, URL, headers, and JSON
-body (object keys sorted). Two dispatch strategies are available:
+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).

- **`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" })
-```
+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.

 Supply your own matcher via `match: (incoming, recorded) => boolean` for
 custom equivalence (e.g. ignoring a timestamp field in the body).
@@ -194,7 +190,6 @@ 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
 }
 ```
@@ -211,4 +206,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, dispatch strategies, mismatch diagnostics.    |
+| `matching.ts`  | Request matcher, canonicalization, sequential cursor, mismatch diagnostics.      |
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.14.46",
+  "version": "1.14.48",
  "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, selectMatch, selectSequential, type RequestMatcher } from "./matching"
+import { defaultMatcher, selectSequential, type RequestMatcher } from "./matching"
 import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
 import { defaults, type Redactor } from "./redactor"
 import { redactUrl } from "./redaction"
@@ -24,7 +24,6 @@ export interface RecordReplayOptions {
  readonly directory?: string
  readonly metadata?: CassetteMetadata
  readonly redactor?: Redactor
-  readonly dispatch?: "match" | "sequential"
  readonly match?: RequestMatcher
 }

@@ -71,7 +70,6 @@ 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) =>
@@ -119,14 +117,12 @@ export const recordingLayer = (
              transportError(request, `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`),
            ),
          )
-          const result = sequential
-            ? selectSequential(interactions, incoming, match, yield* replay.cursor)
-            : selectMatch(interactions, incoming, match)
+          const result = selectSequential(interactions, incoming, match, yield* replay.cursor)
          if (!result.interaction)
            return yield* Effect.fail(
              transportError(request, `Fixture "${name}" does not match the current request: ${result.detail}.`),
            )
-          if (sequential) yield* replay.advance
+          yield* replay.advance
          return HttpClientResponse.fromWeb(
            request,
            new Response(decodeResponseBody(result.interaction.response), result.interaction.response),
@@ -92,24 +92,6 @@ 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,19 +230,10 @@ describe("http-recorder", () => {
    )
  })

-  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 () => {
+  test("replay 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"}')
@@ -250,21 +241,8 @@ describe("http-recorder", () => {
    )
  })

-  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" },
+  test("replay reports cursor exhaustion when more requests are made than recorded", async () => {
+    await run(
      Effect.gen(function* () {
        yield* post("https://example.test/echo", { step: 1 })
        yield* post("https://example.test/echo", { step: 2 })
@@ -274,10 +252,8 @@ describe("http-recorder", () => {
    )
  })

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

-  test("mismatch diagnostics show closest redacted request differences", async () => {
+  test("mismatch diagnostics show redacted request differences against the expected interaction", 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,6 +8,10 @@
 - 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.
@@ -166,12 +170,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 = LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })
-const result = LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } })
+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 followUp = LLM.request({
  model,
-  messages: [LLM.user("Weather?"), LLM.assistant([call]), result],
+  messages: [Message.user("Weather?"), Message.assistant([call]), result],
 })
 ```

@@ -289,6 +293,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 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.
+**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.

 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.
@@ -0,0 +1,129 @@
+# @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.46",
+  "version": "1.14.48",
  "name": "@opencode-ai/llm",
  "type": "module",
  "license": "MIT",
@@ -0,0 +1,111 @@
+// 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,32 +44,8 @@ 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
@@ -95,10 +71,10 @@ export const request = (input: RequestInput) => {
  return new LLMRequest({
    ...rest,
    system: SystemPart.content(requestSystem),
-    messages: [...(messages?.map(message) ?? []), ...(prompt === undefined ? [] : [user(prompt)])],
-    tools: tools?.map(toolDefinition) ?? [],
-    toolChoice: requestToolChoice ? toolChoice(requestToolChoice) : undefined,
-    generation: requestGeneration === undefined ? undefined : generation(requestGeneration),
+    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),
    providerOptions: requestProviderOptions,
    http: requestHttp === undefined ? undefined : HttpOptions.make(requestHttp),
  })
@@ -16,6 +16,8 @@ import {
  type ToolResultPart,
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
+import * as Cache from "./utils/cache"
+import { Lifecycle } from "./utils/lifecycle"
 import { ToolStream } from "./utils/tool-stream"

 const ADAPTER = "anthropic-messages"
@@ -25,7 +27,10 @@ export const PATH = "/messages"
 // =============================================================================
 // Request Body Schema
 // =============================================================================
-const AnthropicCacheControl = Schema.Struct({ type: Schema.tag("ephemeral") })
+const AnthropicCacheControl = Schema.Struct({
+  type: Schema.tag("ephemeral"),
+  ttl: Schema.optional(Schema.Literals(["5m", "1h"])),
+})

 const AnthropicTextBlock = Schema.Struct({
  type: Schema.tag("text"),
@@ -186,6 +191,7 @@ type AnthropicEvent = Schema.Schema.Type<typeof AnthropicEvent>
 interface ParserState {
  readonly tools: ToolStream.State<number>
  readonly usage?: Usage
+  readonly lifecycle: Lifecycle.State
 }

 const invalid = ProviderShared.invalidRequest
@@ -193,8 +199,24 @@ const invalid = ProviderShared.invalidRequest
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const cacheControl = (cache: CacheHint | undefined) =>
-  cache?.type === "ephemeral" ? { type: "ephemeral" as const } : undefined
+// 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 anthropicMetadata = (metadata: Record<string, unknown>): ProviderMetadata => ({ anthropic: metadata })

@@ -204,10 +226,11 @@ const signatureFromMetadata = (metadata: ProviderMetadata | undefined): string |
  return typeof anthropic.signature === "string" ? anthropic.signature : undefined
 }

-const lowerTool = (tool: ToolDefinition): AnthropicTool => ({
+const lowerTool = (breakpoints: Cache.Breakpoints, 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"]>) =>
@@ -249,7 +272,10 @@ 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) {
+const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
+  request: LLMRequest,
+  breakpoints: Cache.Breakpoints,
+) {
  const messages: AnthropicMessage[] = []

  for (const message of request.messages) {
@@ -258,7 +284,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (re
      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(part.cache) })
+        content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
      }
      messages.push({ role: "user", content })
      continue
@@ -268,7 +294,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (re
      const content: AnthropicAssistantBlock[] = []
      for (const part of message.content) {
        if (part.type === "text") {
-          content.push({ type: "text", text: part.text, cache_control: cacheControl(part.cache) })
+          content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
          continue
        }
        if (part.type === "reasoning") {
@@ -304,6 +330,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (re
        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 })
@@ -330,18 +357,33 @@ 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:
-      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),
+    system,
+    messages,
+    tools,
    tool_choice: toolChoice,
    stream: true as const,
    max_tokens: generation?.maxTokens ?? request.model.limits.output ?? 4096,
@@ -364,34 +406,56 @@ 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: usage.input_tokens,
+    inputTokens,
    outputTokens: usage.output_tokens,
-    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,
+    nonCachedInputTokens: nonCached,
+    cacheReadInputTokens: cacheRead,
+    cacheWriteInputTokens: cacheWrite,
+    totalTokens: ProviderShared.totalTokens(inputTokens, usage.output_tokens, undefined),
+    providerMetadata: { anthropic: 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`. `totalTokens` is
-// recomputed from the merged input/output to stay consistent.
+// 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`.
 const mergeUsage = (left: Usage | undefined, right: Usage | undefined) => {
  if (!left) return right
  if (!right) return left
-  const inputTokens = right.inputTokens ?? left.inputTokens
+  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 outputTokens = right.outputTokens ?? left.outputTokens
  return new Usage({
    inputTokens,
    outputTokens,
-    cacheReadInputTokens: right.cacheReadInputTokens ?? left.cacheReadInputTokens,
-    cacheWriteInputTokens: right.cacheWriteInputTokens ?? left.cacheWriteInputTokens,
+    nonCachedInputTokens,
+    cacheReadInputTokens,
+    cacheWriteInputTokens,
    totalTokens: ProviderShared.totalTokens(inputTokens, outputTokens, undefined),
-    native: { ...left.native, ...right.native },
+    providerMetadata: {
+      anthropic: {
+        ...(left.providerMetadata?.["anthropic"] ?? {}),
+        ...(right.providerMetadata?.["anthropic"] ?? {}),
+      },
+    },
  })
 }

@@ -438,37 +502,45 @@ const onContentBlockStart = (state: ParserState, event: AnthropicEvent): StepRes
  if (!block) return [state, NO_EVENTS]

  if ((block.type === "tool_use" || block.type === "server_tool_use") && event.index !== undefined) {
+    const events: LLMEvent[] = []
+    const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
    return [
      {
        ...state,
+        lifecycle,
        tools: ToolStream.start(state.tools, event.index, {
          id: block.id ?? String(event.index),
          name: block.name ?? "",
          providerExecuted: block.type === "server_tool_use",
        }),
      },
-      NO_EVENTS,
+      [...events, LLMEvent.toolInputStart({ id: block.id ?? String(event.index), name: block.name ?? "" })],
    ]
  }

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

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

  const result = serverToolResultEvent(block)
-  return [state, result ? [result] : NO_EVENTS]
+  if (!result) return [state, NO_EVENTS]
+  const events: LLMEvent[] = []
+  return [{ ...state, lifecycle: Lifecycle.stepStart(state.lifecycle, events) }, [...events, result]]
 }

 const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(function* (
@@ -478,25 +550,37 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
  const delta = event.delta

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

  if (delta?.type === "thinking_delta" && delta.thinking) {
+    const events: LLMEvent[] = []
    return [
-      state,
-      [LLMEvent.reasoningDelta({ id: `reasoning-${event.index ?? 0}`, text: delta.thinking })],
+      {
+        ...state,
+        lifecycle: Lifecycle.reasoningDelta(state.lifecycle, events, `reasoning-${event.index ?? 0}`, delta.thinking),
+      },
+      events,
    ] satisfies StepResult
  }

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

@@ -510,7 +594,10 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
      "Anthropic Messages tool argument delta is missing its tool call",
    )
    if (ToolStream.isError(result)) return yield* result
-    return [{ ...state, tools: result.tools }, result.event ? [result.event] : NO_EVENTS] satisfies StepResult
+    const events: LLMEvent[] = []
+    const lifecycle = result.events.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
+    events.push(...result.events)
+    return [{ ...state, lifecycle, tools: result.tools }, events] satisfies StepResult
  }

  return [state, NO_EVENTS] satisfies StepResult
@@ -522,23 +609,30 @@ const onContentBlockStop = Effect.fn("AnthropicMessages.onContentBlockStop")(fun
 ) {
  if (event.index === undefined) return [state, NO_EVENTS] satisfies StepResult
  const result = yield* ToolStream.finish(ADAPTER, state.tools, event.index)
-  return [{ ...state, tools: result.tools }, result.event ? [result.event] : NO_EVENTS] satisfies StepResult
+  const events: LLMEvent[] = []
+  const resultEvents = result.events ?? []
+  const lifecycle = resultEvents.length
+    ? Lifecycle.stepStart(state.lifecycle, events)
+    : Lifecycle.reasoningEnd(
+        Lifecycle.textEnd(state.lifecycle, events, `text-${event.index}`),
+        events,
+        `reasoning-${event.index}`,
+      )
+  events.push(...resultEvents)
+  return [{ ...state, lifecycle, tools: result.tools }, events] satisfies StepResult
 })

 const onMessageDelta = (state: ParserState, event: AnthropicEvent): StepResult => {
  const usage = mergeUsage(state.usage, mapUsage(event.usage))
-  return [
-    { ...state, usage },
-    [
-      LLMEvent.requestFinish({
-        reason: mapFinishReason(event.delta?.stop_reason),
-        usage,
-        providerMetadata: event.delta?.stop_sequence
-          ? anthropicMetadata({ stopSequence: event.delta.stop_sequence })
-          : undefined,
-      }),
-    ],
-  ]
+  const events: LLMEvent[] = []
+  const lifecycle = Lifecycle.finish(state.lifecycle, events, {
+    reason: mapFinishReason(event.delta?.stop_reason),
+    usage,
+    providerMetadata: event.delta?.stop_sequence
+      ? anthropicMetadata({ stopSequence: event.delta.stop_sequence })
+      : undefined,
+  })
+  return [{ ...state, lifecycle, usage }, events]
 }

 const onError = (state: ParserState, event: AnthropicEvent): StepResult => [
@@ -572,7 +666,7 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: Protocol.jsonEvent(AnthropicEvent),
-    initial: () => ({ tools: ToolStream.empty<number>() }),
+    initial: () => ({ tools: ToolStream.empty<number>(), lifecycle: Lifecycle.initial() }),
    step,
  },
 })
@@ -17,6 +17,7 @@ import { JsonObject, optionalArray, ProviderShared } from "./shared"
 import { BedrockAuth, type Credentials as BedrockCredentials } from "./utils/bedrock-auth"
 import { BedrockCache } from "./utils/bedrock-cache"
 import { BedrockMedia } from "./utils/bedrock-media"
+import { Lifecycle } from "./utils/lifecycle"
 import { ToolStream } from "./utils/tool-stream"

 const ADAPTER = "bedrock-converse"
@@ -108,7 +109,7 @@ type BedrockMessage = Schema.Schema.Type<typeof BedrockMessage>
 const BedrockSystemBlock = Schema.Union([BedrockTextBlock, BedrockCache.CachePointBlock])
 type BedrockSystemBlock = Schema.Schema.Type<typeof BedrockSystemBlock>

-const BedrockTool = Schema.Struct({
+const BedrockToolSpec = Schema.Struct({
  toolSpec: Schema.Struct({
    name: Schema.String,
    description: Schema.String,
@@ -117,6 +118,9 @@ const BedrockTool = 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([
@@ -214,7 +218,7 @@ type BedrockEvent = Schema.Schema.Type<typeof BedrockEvent>
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const lowerTool = (tool: ToolDefinition): BedrockTool => ({
+const lowerToolSpec = (tool: ToolDefinition): BedrockToolSpec => ({
  toolSpec: {
    name: tool.name,
    description: tool.description,
@@ -222,11 +226,22 @@ const lowerTool = (tool: ToolDefinition): BedrockTool => ({
  },
 })

+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(cache)
+  const cachePoint = BedrockCache.block(breakpoints, cache)
  return cachePoint ? [{ text }, cachePoint] : [{ text }]
 }

@@ -257,7 +272,10 @@ const lowerToolResult = (part: ToolResultPart): BedrockToolResultBlock => ({
  },
 })

-const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (request: LLMRequest) {
+const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
+  request: LLMRequest,
+  breakpoints: BedrockCache.Breakpoints,
+) {
  const messages: BedrockMessage[] = []

  for (const message of request.messages) {
@@ -267,7 +285,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (requ
        if (!ProviderShared.supportsContent(part, ["text", "media"]))
          return yield* ProviderShared.unsupportedContent("Bedrock Converse", "user", ["text", "media"])
        if (part.type === "text") {
-          content.push(...textWithCache(part.text, part.cache))
+          content.push(...textWithCache(breakpoints, part.text, part.cache))
          continue
        }
        if (part.type === "media") {
@@ -289,7 +307,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (requ
            "tool-call",
          ])
        if (part.type === "text") {
-          content.push(...textWithCache(part.text, part.cache))
+          content.push(...textWithCache(breakpoints, part.text, part.cache))
          continue
        }
        if (part.type === "reasoning") {
@@ -309,11 +327,13 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (requ
      continue
    }

-    const content: BedrockToolResultBlock[] = []
+    const content: BedrockUserBlock[] = []
    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 })
  }
@@ -323,16 +343,32 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (requ

 // System prompts share the cache-point convention: emit the text block, then
 // optionally a positional `cachePoint` marker.
-const lowerSystem = (system: ReadonlyArray<LLMRequest["system"][number]>): BedrockSystemBlock[] =>
-  system.flatMap((part) => textWithCache(part.text, part.cache))
+const lowerSystem = (
+  breakpoints: BedrockCache.Breakpoints,
+  system: ReadonlyArray<LLMRequest["system"][number]>,
+): BedrockSystemBlock[] => system.flatMap((part) => textWithCache(breakpoints, 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: yield* lowerMessages(request),
-    system: request.system.length === 0 ? undefined : lowerSystem(request.system),
+    messages,
+    system,
    inferenceConfig:
      generation?.maxTokens === undefined &&
      generation?.temperature === undefined &&
@@ -345,10 +381,7 @@ const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request:
            topP: generation?.topP,
            stopSequences: generation?.stop,
          },
-    toolConfig:
-      request.tools.length > 0 && request.toolChoice?.type !== "none"
-        ? { tools: request.tools.map(lowerTool), toolChoice }
-        : undefined,
+    toolConfig,
  }
 })

@@ -363,15 +396,22 @@ 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,
-    totalTokens: ProviderShared.totalTokens(usage.inputTokens, usage.outputTokens, usage.totalTokens),
+    nonCachedInputTokens: nonCached,
    cacheReadInputTokens: usage.cacheReadInputTokens,
    cacheWriteInputTokens: usage.cacheWriteInputTokens,
-    native: usage,
+    totalTokens: ProviderShared.totalTokens(usage.inputTokens, usage.outputTokens, usage.totalTokens),
+    providerMetadata: { bedrock: usage },
  })
 }

@@ -381,45 +421,64 @@ interface ParserState {
  // `metadata` (carries usage). Hold the terminal event in state so `onHalt`
  // can emit exactly one finish after both chunks have had a chance to arrive.
  readonly pendingFinish: { readonly reason: FinishReason; readonly usage?: Usage } | undefined
+  readonly hasToolCalls: boolean
+  readonly lifecycle: Lifecycle.State
 }

 const step = (state: ParserState, event: BedrockEvent) =>
  Effect.gen(function* () {
    if (event.contentBlockStart?.start?.toolUse) {
      const index = event.contentBlockStart.contentBlockIndex
+      const events: LLMEvent[] = []
+      const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
      return [
        {
          ...state,
+          lifecycle,
          tools: ToolStream.start(state.tools, index, {
            id: event.contentBlockStart.start.toolUse.toolUseId,
            name: event.contentBlockStart.start.toolUse.name,
          }),
        },
-        [],
+        [
+          ...events,
+          LLMEvent.toolInputStart({
+            id: event.contentBlockStart.start.toolUse.toolUseId,
+            name: event.contentBlockStart.start.toolUse.name,
+          }),
+        ],
      ] as const
    }

    if (event.contentBlockDelta?.delta?.text) {
+      const events: LLMEvent[] = []
      return [
-        state,
-        [
-          LLMEvent.textDelta({
-            id: `text-${event.contentBlockDelta.contentBlockIndex}`,
-            text: event.contentBlockDelta.delta.text,
-          }),
-        ],
+        {
+          ...state,
+          lifecycle: Lifecycle.textDelta(
+            state.lifecycle,
+            events,
+            `text-${event.contentBlockDelta.contentBlockIndex}`,
+            event.contentBlockDelta.delta.text,
+          ),
+        },
+        events,
      ] as const
    }

    if (event.contentBlockDelta?.delta?.reasoningContent?.text) {
+      const events: LLMEvent[] = []
      return [
-        state,
-        [
-          LLMEvent.reasoningDelta({
-            id: `reasoning-${event.contentBlockDelta.contentBlockIndex}`,
-            text: event.contentBlockDelta.delta.reasoningContent.text,
-          }),
-        ],
+        {
+          ...state,
+          lifecycle: Lifecycle.reasoningDelta(
+            state.lifecycle,
+            events,
+            `reasoning-${event.contentBlockDelta.contentBlockIndex}`,
+            event.contentBlockDelta.delta.reasoningContent.text,
+          ),
+        },
+        events,
      ] as const
    }

@@ -433,12 +492,33 @@ const step = (state: ParserState, event: BedrockEvent) =>
        "Bedrock Converse tool delta is missing its tool call",
      )
      if (ToolStream.isError(result)) return yield* result
-      return [{ ...state, tools: result.tools }, result.event ? [result.event] : []] as const
+      const events: LLMEvent[] = []
+      const lifecycle = result.events.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
+      events.push(...result.events)
+      return [{ ...state, lifecycle, tools: result.tools }, events] as const
    }

    if (event.contentBlockStop) {
      const result = yield* ToolStream.finish(ADAPTER, state.tools, event.contentBlockStop.contentBlockIndex)
-      return [{ ...state, tools: result.tools }, result.event ? [result.event] : []] as const
+      const events: LLMEvent[] = []
+      const resultEvents = result.events ?? []
+      const lifecycle = resultEvents.length
+        ? Lifecycle.stepStart(state.lifecycle, events)
+        : Lifecycle.reasoningEnd(
+            Lifecycle.textEnd(state.lifecycle, events, `text-${event.contentBlockStop.contentBlockIndex}`),
+            events,
+            `reasoning-${event.contentBlockStop.contentBlockIndex}`,
+          )
+      events.push(...resultEvents)
+      return [
+        {
+          ...state,
+          hasToolCalls: resultEvents.some(LLMEvent.is.toolCall) ? true : state.hasToolCalls,
+          lifecycle,
+          tools: result.tools,
+        },
+        events,
+      ] as const
    }

    if (event.messageStop) {
@@ -478,7 +558,15 @@ const framing = BedrockEventStream.framing(ADAPTER)

 const onHalt = (state: ParserState): ReadonlyArray<LLMEvent> =>
  state.pendingFinish
-    ? [LLMEvent.requestFinish({ reason: state.pendingFinish.reason, usage: state.pendingFinish.usage })]
+    ? (() => {
+        const events: LLMEvent[] = []
+        Lifecycle.finish(state.lifecycle, events, {
+          reason:
+            state.pendingFinish.reason === "stop" && state.hasToolCalls ? "tool-calls" : state.pendingFinish.reason,
+          usage: state.pendingFinish.usage,
+        })
+        return events
+      })()
    : []

 // =============================================================================
@@ -496,7 +584,12 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: BedrockEvent,
-    initial: () => ({ tools: ToolStream.empty<number>(), pendingFinish: undefined }),
+    initial: () => ({
+      tools: ToolStream.empty<number>(),
+      pendingFinish: undefined,
+      hasToolCalls: false,
+      lifecycle: Lifecycle.initial(),
+    }),
    step,
    onHalt,
  },
@@ -16,6 +16,7 @@ import {
 } from "../schema"
 import { JsonObject, optionalArray, ProviderShared } from "./shared"
 import { GeminiToolSchema } from "./utils/gemini-tool-schema"
+import { Lifecycle } from "./utils/lifecycle"

 const ADAPTER = "gemini"
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
@@ -134,10 +135,9 @@ interface ParserState {
  readonly hasToolCalls: boolean
  readonly nextToolCallId: number
  readonly usage?: Usage
+  readonly lifecycle: Lifecycle.State
 }

-const invalid = ProviderShared.invalidRequest
-
 const mediaData = ProviderShared.mediaBytes

 // =============================================================================
@@ -281,15 +281,28 @@ 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: usage.candidatesTokenCount,
+    outputTokens,
+    nonCachedInputTokens: nonCached,
+    cacheReadInputTokens: cached,
    reasoningTokens: usage.thoughtsTokenCount,
-    cacheReadInputTokens: usage.cachedContentTokenCount,
-    totalTokens: ProviderShared.totalTokens(usage.promptTokenCount, usage.candidatesTokenCount, usage.totalTokenCount),
-    native: usage,
+    totalTokens: ProviderShared.totalTokens(usage.promptTokenCount, outputTokens, usage.totalTokenCount),
+    providerMetadata: { google: usage },
  })
 }

@@ -311,7 +324,14 @@ const mapFinishReason = (finishReason: string | undefined, hasToolCalls: boolean

 const finish = (state: ParserState): ReadonlyArray<LLMEvent> =>
  state.finishReason || state.usage
-    ? [LLMEvent.requestFinish({ reason: mapFinishReason(state.finishReason, state.hasToolCalls), usage: state.usage })]
+    ? (() => {
+        const events: LLMEvent[] = []
+        Lifecycle.finish(state.lifecycle, events, {
+          reason: mapFinishReason(state.finishReason, state.hasToolCalls),
+          usage: state.usage,
+        })
+        return events
+      })()
    : []

 const step = (state: ParserState, event: GeminiEvent) => {
@@ -328,21 +348,21 @@ const step = (state: ParserState, event: GeminiEvent) => {

  const events: LLMEvent[] = []
  let hasToolCalls = nextState.hasToolCalls
+  let lifecycle = nextState.lifecycle
  let nextToolCallId = nextState.nextToolCallId

  for (const part of candidate.content.parts) {
    if ("text" in part && part.text.length > 0) {
-      events.push(
-        part.thought
-          ? LLMEvent.reasoningDelta({ id: "reasoning-0", text: part.text })
-          : LLMEvent.textDelta({ id: "text-0", text: part.text }),
-      )
+      lifecycle = part.thought
+        ? Lifecycle.reasoningDelta(lifecycle, events, "reasoning-0", part.text)
+        : Lifecycle.textDelta(lifecycle, events, "text-0", part.text)
      continue
    }

    if ("functionCall" in part) {
      const input = part.functionCall.args
      const id = `tool_${nextToolCallId++}`
+      lifecycle = Lifecycle.stepStart(lifecycle, events)
      events.push(LLMEvent.toolCall({ id, name: part.functionCall.name, input }))
      hasToolCalls = true
    }
@@ -352,6 +372,7 @@ const step = (state: ParserState, event: GeminiEvent) => {
    {
      ...nextState,
      hasToolCalls,
+      lifecycle,
      nextToolCallId,
      finishReason: candidate.finishReason ?? nextState.finishReason,
    },
@@ -375,7 +396,7 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: Protocol.jsonEvent(GeminiEvent),
-    initial: () => ({ hasToolCalls: false, nextToolCallId: 0 }),
+    initial: () => ({ hasToolCalls: false, nextToolCallId: 0, lifecycle: Lifecycle.initial() }),
    step,
    onHalt: finish,
  },
@@ -16,6 +16,7 @@ import {
 } from "../schema"
 import { isRecord, JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
 import { OpenAIOptions } from "./utils/openai-options"
+import { Lifecycle } from "./utils/lifecycle"
 import { ToolStream } from "./utils/tool-stream"

 const ADAPTER = "openai-chat"
@@ -147,6 +148,7 @@ interface ParserState {
  readonly toolCallEvents: ReadonlyArray<LLMEvent>
  readonly usage?: Usage
  readonly finishReason?: FinishReason
+  readonly lifecycle: Lifecycle.State
 }

 const invalid = ProviderShared.invalidRequest
@@ -290,15 +292,24 @@ 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,
-    reasoningTokens: usage.completion_tokens_details?.reasoning_tokens,
-    cacheReadInputTokens: usage.prompt_tokens_details?.cached_tokens,
+    nonCachedInputTokens: nonCached,
+    cacheReadInputTokens: cached,
+    reasoningTokens: reasoning,
    totalTokens: ProviderShared.totalTokens(usage.prompt_tokens, usage.completion_tokens, usage.total_tokens),
-    native: usage,
+    providerMetadata: { openai: usage },
  })
 }

@@ -312,7 +323,9 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
    const toolDeltas = delta?.tool_calls ?? []
    let tools = state.tools

-    if (delta?.content) events.push(LLMEvent.textDelta({ id: "text-0", text: delta.content }))
+    let lifecycle = state.lifecycle
+
+    if (delta?.content) lifecycle = Lifecycle.textDelta(lifecycle, events, "text-0", delta.content)

    for (const tool of toolDeltas) {
      const result = ToolStream.appendOrStart(
@@ -324,7 +337,8 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
      )
      if (ToolStream.isError(result)) return yield* result
      tools = result.tools
-      if (result.event) events.push(result.event)
+      if (result.events.length) lifecycle = Lifecycle.stepStart(lifecycle, events)
+      events.push(...result.events)
    }

    // Finalize accumulated tool inputs eagerly when finish_reason arrives so
@@ -340,15 +354,20 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
        toolCallEvents: finished?.events ?? state.toolCallEvents,
        usage,
        finishReason,
+        lifecycle,
      },
      events,
    ] as const
  })

 const finishEvents = (state: ParserState): ReadonlyArray<LLMEvent> => {
+  const events: LLMEvent[] = []
  const hasToolCalls = state.toolCallEvents.length > 0
  const reason = state.finishReason === "stop" && hasToolCalls ? "tool-calls" : state.finishReason
-  return [...state.toolCallEvents, ...(reason ? [LLMEvent.requestFinish({ reason, usage: state.usage })] : [])]
+  const lifecycle = state.toolCallEvents.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
+  events.push(...state.toolCallEvents)
+  if (reason) Lifecycle.finish(lifecycle, events, { reason, usage: state.usage })
+  return events
 }

 // =============================================================================
@@ -368,7 +387,7 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: Protocol.jsonEvent(OpenAIChatEvent),
-    initial: () => ({ tools: ToolStream.empty<number>(), toolCallEvents: [] }),
+    initial: () => ({ tools: ToolStream.empty<number>(), toolCallEvents: [], lifecycle: Lifecycle.initial() }),
    step,
    onHalt: finishEvents,
  },
@@ -17,6 +17,7 @@ import {
 } from "../schema"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared"
 import { OpenAIOptions } from "./utils/openai-options"
+import { Lifecycle } from "./utils/lifecycle"
 import { ToolStream } from "./utils/tool-stream"

 const ADAPTER = "openai-responses"
@@ -165,6 +166,7 @@ type OpenAIResponsesEvent = Schema.Schema.Type<typeof OpenAIResponsesEvent>
 interface ParserState {
  readonly tools: ToolStream.State<string>
  readonly hasFunctionCall: boolean
+  readonly lifecycle: Lifecycle.State
 }

 const invalid = ProviderShared.invalidRequest
@@ -276,15 +278,23 @@ 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,
-    reasoningTokens: usage.output_tokens_details?.reasoning_tokens,
-    cacheReadInputTokens: usage.input_tokens_details?.cached_tokens,
+    nonCachedInputTokens: nonCached,
+    cacheReadInputTokens: cached,
+    reasoningTokens: reasoning,
    totalTokens: ProviderShared.totalTokens(usage.input_tokens, usage.output_tokens, usage.total_tokens),
-    native: usage,
+    providerMetadata: { openai: usage },
  })
 }

@@ -377,23 +387,32 @@ const TERMINAL_TYPES = new Set(["response.completed", "response.incomplete", "re

 const onOutputTextDelta = (state: ParserState, event: OpenAIResponsesEvent): StepResult => {
  if (!event.delta) return [state, NO_EVENTS]
-  return [state, [LLMEvent.textDelta({ id: event.item_id ?? "text-0", text: event.delta })]]
+  const events: LLMEvent[] = []
+  return [
+    { ...state, lifecycle: Lifecycle.textDelta(state.lifecycle, events, event.item_id ?? "text-0", event.delta) },
+    events,
+  ]
 }

 const onOutputItemAdded = (state: ParserState, event: OpenAIResponsesEvent): StepResult => {
  const item = event.item
  if (item?.type !== "function_call" || !item.id) return [state, NO_EVENTS]
+  const providerMetadata = openaiMetadata({ itemId: item.id })
+  const events: LLMEvent[] = []
+  const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
  return [
    {
+      ...state,
+      lifecycle,
      hasFunctionCall: state.hasFunctionCall,
      tools: ToolStream.start(state.tools, item.id, {
        id: item.call_id ?? item.id,
        name: item.name ?? "",
        input: item.arguments ?? "",
-        providerMetadata: openaiMetadata({ itemId: item.id }),
+        providerMetadata,
      }),
    },
-    NO_EVENTS,
+    [...events, LLMEvent.toolInputStart({ id: item.call_id ?? item.id, name: item.name ?? "", providerMetadata })],
  ]
 }

@@ -410,10 +429,10 @@ const onFunctionCallArgumentsDelta = Effect.fn("OpenAIResponses.onFunctionCallAr
    "OpenAI Responses tool argument delta is missing its tool call",
  )
  if (ToolStream.isError(result)) return yield* result
-  return [
-    { hasFunctionCall: state.hasFunctionCall, tools: result.tools },
-    result.event ? [result.event] : NO_EVENTS,
-  ] satisfies StepResult
+  const events: LLMEvent[] = []
+  const lifecycle = result.events.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
+  events.push(...result.events)
+  return [{ ...state, lifecycle, tools: result.tools }, events] satisfies StepResult
 })

 const onOutputItemDone = Effect.fn("OpenAIResponses.onOutputItemDone")(function* (
@@ -432,33 +451,46 @@ const onOutputItemDone = Effect.fn("OpenAIResponses.onOutputItemDone")(function*
      item.arguments === undefined
        ? yield* ToolStream.finish(ADAPTER, tools, item.id)
        : yield* ToolStream.finishWithInput(ADAPTER, tools, item.id, item.arguments)
+    const events: LLMEvent[] = []
+    const resultEvents = result.events ?? []
+    const lifecycle = resultEvents.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
+    events.push(...resultEvents)
    return [
-      { hasFunctionCall: result.event ? true : state.hasFunctionCall, tools: result.tools },
-      result.event ? [result.event] : NO_EVENTS,
+      {
+        ...state,
+        lifecycle,
+        hasFunctionCall: resultEvents.some(LLMEvent.is.toolCall) ? true : state.hasFunctionCall,
+        tools: result.tools,
+      },
+      events,
    ] satisfies StepResult
  }

-  if (isHostedToolItem(item)) return [state, hostedToolEvents(item)] satisfies StepResult
+  if (isHostedToolItem(item)) {
+    const events: LLMEvent[] = []
+    const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
+    events.push(...hostedToolEvents(item))
+    return [{ ...state, lifecycle }, events] satisfies StepResult
+  }

  return [state, NO_EVENTS] satisfies StepResult
 })

-const onResponseFinish = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
-  state,
-  [
-    LLMEvent.requestFinish({
-      reason: mapFinishReason(event, state.hasFunctionCall),
-      usage: mapUsage(event.response?.usage),
-      providerMetadata:
-        event.response?.id || event.response?.service_tier
-          ? openaiMetadata({
-              responseId: event.response.id,
-              serviceTier: event.response.service_tier,
-            })
-          : undefined,
-    }),
-  ],
-]
+const onResponseFinish = (state: ParserState, event: OpenAIResponsesEvent): StepResult => {
+  const events: LLMEvent[] = []
+  const lifecycle = Lifecycle.finish(state.lifecycle, events, {
+    reason: mapFinishReason(event, state.hasFunctionCall),
+    usage: mapUsage(event.response?.usage),
+    providerMetadata:
+      event.response?.id || event.response?.service_tier
+        ? openaiMetadata({
+            responseId: event.response.id,
+            serviceTier: event.response.service_tier,
+          })
+        : undefined,
+  })
+  return [{ ...state, lifecycle }, events]
+}

 const onResponseFailed = (state: ParserState, event: OpenAIResponsesEvent): StepResult => [
  state,
@@ -498,7 +530,7 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: Protocol.jsonEvent(OpenAIResponsesEvent),
-    initial: () => ({ hasFunctionCall: false, tools: ToolStream.empty<string>() }),
+    initial: () => ({ hasFunctionCall: false, tools: ToolStream.empty<string>(), lifecycle: Lifecycle.initial() }),
    step,
    terminal: (event) => TERMINAL_TYPES.has(event.type),
  },
@@ -42,6 +42,13 @@ 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,
@@ -53,6 +60,35 @@ 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,20 +1,37 @@
 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.
+// after the content the caller wants treated as a cacheable prefix. Bedrock
+// accepts optional `ttl: "5m" | "1h"` on cachePoint, mirroring Anthropic.
 export const CachePointBlock = Schema.Struct({
-  cachePoint: Schema.Struct({ type: Schema.tag("default") }),
+  cachePoint: Schema.Struct({
+    type: Schema.tag("default"),
+    ttl: Schema.optional(Schema.Literals(["5m", "1h"])),
+  }),
 })
 export type CachePointBlock = Schema.Schema.Type<typeof CachePointBlock>

-// 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" } }
+// 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

-export const block = (cache: CacheHint | undefined): CachePointBlock | undefined => {
+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 => {
  if (cache?.type !== "ephemeral" && cache?.type !== "persistent") return undefined
-  return DEFAULT
+  if (breakpoints.remaining <= 0) {
+    breakpoints.dropped += 1
+    return undefined
+  }
+  breakpoints.remaining -= 1
+  return ttlBucket(cache.ttlSeconds) === "1h" ? DEFAULT_1H : DEFAULT_5M
 }

 export * as BedrockCache from "./bedrock-cache"
@@ -0,0 +1,16 @@
+// 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
@@ -0,0 +1,88 @@
+import { LLMEvent, type FinishReason, type ProviderMetadata, type Usage } from "../../schema"
+
+export interface State {
+  readonly stepStarted: boolean
+  readonly text: ReadonlySet<string>
+  readonly reasoning: ReadonlySet<string>
+}
+
+export const initial = (): State => ({ stepStarted: false, text: new Set(), reasoning: new Set() })
+
+export const stepStart = (state: State, events: LLMEvent[]): State => {
+  if (state.stepStarted) return state
+  events.push(LLMEvent.stepStart({ index: 0 }))
+  return { ...state, stepStarted: true }
+}
+
+export const textDelta = (state: State, events: LLMEvent[], id: string, text: string): State => {
+  const stepped = stepStart(state, events)
+  if (stepped.text.has(id)) {
+    events.push(LLMEvent.textDelta({ id, text }))
+    return stepped
+  }
+  events.push(LLMEvent.textStart({ id }), LLMEvent.textDelta({ id, text }))
+  return { ...stepped, text: new Set([...stepped.text, id]) }
+}
+
+export const reasoningDelta = (state: State, events: LLMEvent[], id: string, text: string): State => {
+  const stepped = stepStart(state, events)
+  if (stepped.reasoning.has(id)) {
+    events.push(LLMEvent.reasoningDelta({ id, text }))
+    return stepped
+  }
+  events.push(LLMEvent.reasoningStart({ id }), LLMEvent.reasoningDelta({ id, text }))
+  return { ...stepped, reasoning: new Set([...stepped.reasoning, id]) }
+}
+
+export const reasoningEnd = (
+  state: State,
+  events: LLMEvent[],
+  id: string,
+  providerMetadata?: ProviderMetadata,
+): State => {
+  if (!state.reasoning.has(id)) return state
+  const stepped = stepStart(state, events)
+  events.push(LLMEvent.reasoningEnd({ id, providerMetadata }))
+  const reasoning = new Set(stepped.reasoning)
+  reasoning.delete(id)
+  return { ...stepped, reasoning }
+}
+
+export const textEnd = (state: State, events: LLMEvent[], id: string, providerMetadata?: ProviderMetadata): State => {
+  if (!state.text.has(id)) return state
+  const stepped = stepStart(state, events)
+  events.push(LLMEvent.textEnd({ id, providerMetadata }))
+  const text = new Set(stepped.text)
+  text.delete(id)
+  return { ...stepped, text }
+}
+
+const closeOpenBlocks = (state: State, events: LLMEvent[]): State => {
+  for (const id of state.reasoning) events.push(LLMEvent.reasoningEnd({ id }))
+  for (const id of state.text) events.push(LLMEvent.textEnd({ id }))
+  return { ...state, text: new Set(), reasoning: new Set() }
+}
+
+export const finish = (
+  state: State,
+  events: LLMEvent[],
+  input: {
+    readonly reason: FinishReason
+    readonly usage?: Usage
+    readonly providerMetadata?: ProviderMetadata
+  },
+): State => {
+  const stepped = closeOpenBlocks(stepStart(state, events), events)
+  events.push(
+    LLMEvent.stepFinish({
+      index: 0,
+      reason: input.reason,
+      usage: input.usage,
+      providerMetadata: input.providerMetadata,
+    }),
+    LLMEvent.requestFinish(input),
+  )
+  return { ...stepped, stepStarted: false }
+}
+
+export * as Lifecycle from "./lifecycle"
@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall, type ToolInputDelta } from "../../schema"
+import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall } from "../../schema"
 import { eventError, parseToolInput, type ToolAccumulator } from "../shared"

 type StreamKey = string | number
@@ -27,13 +27,13 @@ export type State<K extends StreamKey> = Partial<Record<K, PendingTool>>
 /**
 * Result of adding argument text to one pending tool call. It returns both the
 * next `tools` state and the updated `tool` because parsers often need the
- * current id/name immediately. `event` is present only when new text arrived;
- * metadata-only deltas update identity without emitting `tool-input-delta`.
+ * current id/name immediately. `events` contains lifecycle and delta events
+ * produced by the append; metadata-only deltas update identity without output.
 */
 export interface AppendOutcome<K extends StreamKey> {
  readonly tools: State<K>
  readonly tool: PendingTool
-  readonly event?: ToolInputDelta
+  readonly events: ReadonlyArray<LLMEvent>
 }

 /** Create empty accumulator state for one provider stream. */
@@ -49,7 +49,14 @@ const withoutTool = <K extends StreamKey>(tools: State<K>, key: K): State<K> =>
  return next
 }

-const inputDelta = (tool: PendingTool, text: string): ToolInputDelta =>
+const inputStart = (tool: PendingTool) =>
+  LLMEvent.toolInputStart({
+    id: tool.id,
+    name: tool.name,
+    providerMetadata: tool.providerMetadata,
+  })
+
+const inputDelta = (tool: PendingTool, text: string) =>
  LLMEvent.toolInputDelta({
    id: tool.id,
    name: tool.name,
@@ -76,11 +83,16 @@ const appendTool = <K extends StreamKey>(
  key: K,
  tool: PendingTool,
  text: string,
-): AppendOutcome<K> => ({
-  tools: withTool(tools, key, tool),
-  tool,
-  event: text.length === 0 ? undefined : inputDelta(tool, text),
-})
+): AppendOutcome<K> => {
+  const events: LLMEvent[] = []
+  if (!tools[key]) events.push(inputStart(tool))
+  if (text.length > 0) events.push(inputDelta(tool, text))
+  return {
+    tools: withTool(tools, key, tool),
+    tool,
+    events,
+  }
+}

 export const isError = <K extends StreamKey>(result: AppendOutcome<K> | LLMError): result is LLMError =>
  result instanceof LLMError
@@ -121,7 +133,8 @@ export const appendOrStart = <K extends StreamKey>(
    providerExecuted: current?.providerExecuted,
    providerMetadata: current?.providerMetadata,
  }
-  if (current && delta.text.length === 0 && current.id === id && current.name === name) return { tools, tool: current }
+  if (current && delta.text.length === 0 && current.id === id && current.name === name)
+    return { tools, tool: current, events: [] }
  return appendTool(tools, key, tool, delta.text)
 }

@@ -139,7 +152,7 @@ export const appendExisting = <K extends StreamKey>(
 ): AppendOutcome<K> | LLMError => {
  const current = tools[key]
  if (!current) return eventError(route, missingToolMessage)
-  if (text.length === 0) return { tools, tool: current }
+  if (text.length === 0) return { tools, tool: current, events: [] }
  return appendTool(tools, key, { ...current, input: `${current.input}${text}` }, text)
 }

@@ -152,7 +165,13 @@ export const finish = <K extends StreamKey>(route: string, tools: State<K>, key:
  Effect.gen(function* () {
    const tool = tools[key]
    if (!tool) return { tools }
-    return { tools: withoutTool(tools, key), event: yield* toolCall(route, tool) }
+    return {
+      tools: withoutTool(tools, key),
+      events: [
+        LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+        yield* toolCall(route, tool),
+      ],
+    }
  })

 /**
@@ -164,7 +183,13 @@ export const finishWithInput = <K extends StreamKey>(route: string, tools: State
  Effect.gen(function* () {
    const tool = tools[key]
    if (!tool) return { tools }
-    return { tools: withoutTool(tools, key), event: yield* toolCall(route, tool, input) }
+    return {
+      tools: withoutTool(tools, key),
+      events: [
+        LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+        yield* toolCall(route, tool, input),
+      ],
+    }
  })

 /**
@@ -179,7 +204,14 @@ export const finishAll = <K extends StreamKey>(route: string, tools: State<K>) =
    )
    return {
      tools: empty<K>(),
-      events: yield* Effect.forEach(pending, (tool) => toolCall(route, tool)),
+      events: yield* Effect.forEach(pending, (tool) =>
+        toolCall(route, tool).pipe(
+          Effect.map((call) => [
+            LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+            call,
+          ]),
+        ),
+      ).pipe(Effect.map((events) => events.flat())),
    }
  })

@@ -8,6 +8,7 @@ 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"
@@ -400,7 +401,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 = resolveRequestOptions(request)
+  const resolved = applyCachePolicy(resolveRequestOptions(request))
  const route = registeredRoute(resolved.model.route)
  if (!route) return yield* noRoute(resolved.model)

@@ -3,15 +3,70 @@ 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),
-  reasoningTokens: Schema.optional(Schema.Number),
+  nonCachedInputTokens: Schema.optional(Schema.Number),
  cacheReadInputTokens: Schema.optional(Schema.Number),
  cacheWriteInputTokens: Schema.optional(Schema.Number),
+  reasoningTokens: Schema.optional(Schema.Number),
  totalTokens: Schema.optional(Schema.Number),
-  native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-}) {}
+  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))
+  }
+}

 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, GenerationOptions, HttpOptions, ModelRef, ProviderOptions } from "./options"
+import { CacheHint, CachePolicy, GenerationOptions, HttpOptions, ModelRef, ProviderOptions } from "./options"

 const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value)
@@ -79,6 +79,7 @@ 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" }),
@@ -94,6 +95,7 @@ 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,
    }),
@@ -151,6 +153,7 @@ 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)),
 }) {}
@@ -203,6 +206,7 @@ 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)),
 }) {}

@@ -220,6 +224,7 @@ export namespace LLMRequest {
    providerOptions: request.providerOptions,
    http: request.http,
    responseFormat: request.responseFormat,
+    cache: request.cache,
    metadata: request.metadata,
  })

@@ -200,3 +200,31 @@ 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>
@@ -154,8 +154,8 @@ const accumulate = (state: StepState, event: LLMEvent) => {
    )
    return
  }
-  if (event.type === "request-finish") {
-    state.finishReason = event.reason
+  if (event.type === "step-finish" || event.type === "request-finish") {
+    state.finishReason = event.reason === "stop" && state.toolCalls.length > 0 ? "tool-calls" : event.reason
  }
 }

@@ -0,0 +1,266 @@
+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, ToolChoice, ToolDefinition } from "../src/schema"
+import { LLMRequest, Message, ModelRef, ToolCallPart, ToolChoice, ToolDefinition, ToolResultPart } 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, LLM.assistant("Hi.")],
+      messages: [...base.messages, Message.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, LLM.assistant("Hi.")] })
+    const updated = LLMRequest.update(base, { messages: [...base.messages, Message.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 = LLM.toolDefinition({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })
+    const tool = ToolDefinition.make({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })

    expect(tool).toBeInstanceOf(ToolDefinition)
-    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" }))
+    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" }))
  })

  test("builds tool choice modes from reserved strings", () => {
-    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(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.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 = LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })
-    const result = LLM.toolResult({ id: "call_1", name: "lookup", result: { temperature: 72 } })
+    const call = ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })
+    const result = ToolResultPart.make({ id: "call_1", name: "lookup", result: { temperature: 72 } })

-    expect(LLM.assistant([call]).content).toEqual([call])
-    expect(LLM.toolMessage(result).content).toEqual([
+    expect(Message.assistant([call]).content).toEqual([call])
+    expect(Message.tool(result).content).toEqual([
      { type: "tool-result", id: "call_1", name: "lookup", result: { type: "json", value: { temperature: 72 } } },
    ])
  })
@@ -0,0 +1,55 @@
+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 } from "../../src"
+import { LLM, LLMError, Message, ToolCallPart } 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: [
-    LLM.assistant([
-      LLM.toolCall({ id: "call_1", name: weatherToolName, input: { city: "Paris" } }),
+    Message.assistant([
+      ToolCallPart.make({ id: "call_1", name: weatherToolName, input: { city: "Paris" } }),
      { type: "text", text: "I will check the weather." },
    ]),
-    LLM.toolMessage({ id: "call_1", name: weatherToolName, result: { temperature: "72F" } }),
-    LLM.user("Use that result to answer briefly."),
+    Message.tool({ id: "call_1", name: weatherToolName, result: { temperature: "72F" } }),
+    Message.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 } from "../../src"
+import { CacheHint, LLM, LLMError, Message, ToolCallPart, Usage } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
 import { it } from "../lib/effect"
@@ -18,6 +18,9 @@ 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 },
 })

@@ -44,10 +47,11 @@ describe("Anthropic Messages route", () => {
          id: "req_tool_result",
          model,
          messages: [
-            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" } }),
+            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" } }),
          ],
+          cache: "none",
        }),
      )

@@ -73,7 +77,7 @@ describe("Anthropic Messages route", () => {
        LLM.request({
          model,
          messages: [
-            LLM.assistant([
+            Message.assistant([
              { type: "reasoning", text: "thinking", providerMetadata: { anthropic: { signature: "sig_1" } } },
            ]),
          ],
@@ -110,10 +114,11 @@ describe("Anthropic Messages route", () => {
      expect(response.text).toBe("Hello!")
      expect(response.reasoning).toBe("thinking")
      expect(response.usage).toMatchObject({
-        inputTokens: 5,
+        inputTokens: 6,
        outputTokens: 2,
+        nonCachedInputTokens: 5,
        cacheReadInputTokens: 1,
-        totalTokens: 7,
+        totalTokens: 8,
      })
      expect(response.events.find((event) => event.type === "reasoning-end")).toMatchObject({
        providerMetadata: { anthropic: { signature: "sig_1" } },
@@ -141,18 +146,46 @@ describe("Anthropic Messages route", () => {
          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
        }),
      ).pipe(Effect.provide(fixedResponse(body)))
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 1,
+        nonCachedInputTokens: 5,
+        cacheReadInputTokens: undefined,
+        cacheWriteInputTokens: undefined,
+        totalTokens: 6,
+        providerMetadata: { anthropic: { input_tokens: 5, output_tokens: 1 } },
+      })

      expect(response.toolCalls).toEqual([
-        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
      ])
      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "tool-input-start", id: "call_1", name: "lookup" },
        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
-        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata: undefined },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+        { type: "step-finish", index: 0, reason: "tool-calls", usage, providerMetadata: undefined },
        {
          type: "request-finish",
          reason: "tool-calls",
-          usage: { inputTokens: 5, outputTokens: 1, totalTokens: 6, native: { input_tokens: 5, output_tokens: 1 } },
+          providerMetadata: undefined,
+          usage,
        },
      ])
    }),
@@ -293,8 +326,8 @@ describe("Anthropic Messages route", () => {
          id: "req_round_trip",
          model,
          messages: [
-            LLM.user("Search for something."),
-            LLM.assistant([
+            Message.user("Search for something."),
+            Message.assistant([
              {
                type: "tool-call",
                id: "srvtoolu_abc",
@@ -311,7 +344,7 @@ describe("Anthropic Messages route", () => {
              },
              { type: "text", text: "Found it." },
            ]),
-            LLM.user("Thanks."),
+            Message.user("Thanks."),
          ],
        }),
      )
@@ -344,7 +377,7 @@ describe("Anthropic Messages route", () => {
          id: "req_unknown_server_tool",
          model,
          messages: [
-            LLM.assistant([
+            Message.assistant([
              {
                type: "tool-result",
                id: "srvtoolu_abc",
@@ -367,11 +400,141 @@ describe("Anthropic Messages route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [Message.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()
+    }),
+  )
 })
@@ -0,0 +1,55 @@
+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 } from "../../src"
+import { CacheHint, LLM, Message, ToolCallPart, ToolChoice } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as BedrockConverse from "../../src/protocols/bedrock-converse"
 import { it } from "../lib/effect"
@@ -63,6 +63,9 @@ 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 },
 })

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

@@ -121,10 +124,11 @@ describe("Bedrock Converse route", () => {
          id: "req_history",
          model,
          messages: [
-            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" } }),
+            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" } }),
          ],
+          cache: "none",
        }),
      )

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

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

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

@@ -433,13 +438,85 @@ describe("Bedrock Converse route", () => {
        LLM.request({
          id: "req_bad_doc",
          model,
-          messages: [LLM.user([{ type: "media", mediaType: "application/x-tar", data: "x", filename: "a.tar" }])],
+          messages: [Message.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=...
@@ -484,6 +561,7 @@ describe("Bedrock Converse recorded", () => {
          model: recordedModel(),
          system: "Reply with the single word 'Hello'.",
          prompt: "Say hello.",
+          cache: "none",
          generation: { maxTokens: 16, temperature: 0 },
        }),
      )
@@ -505,7 +583,8 @@ describe("Bedrock Converse recorded", () => {
          system: "Call tools exactly as requested.",
          prompt: "Call get_weather with city exactly Paris.",
          tools: [weatherTool],
-          toolChoice: LLM.toolChoice(weatherTool),
+          toolChoice: ToolChoice.make(weatherTool),
+          cache: "none",
          generation: { maxTokens: 80, temperature: 0 },
        }),
      )
@@ -0,0 +1,49 @@
+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 } from "../../src"
+import { LLM, LLMError, Message, ToolCallPart, Usage } 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: [
-            LLM.user([
+            Message.user([
              { type: "text", text: "What is in this image?" },
              { type: "media", mediaType: "image/png", data: "AAECAw==" },
            ]),
-            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
-            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
          ],
        }),
      )
@@ -198,32 +198,43 @@ describe("Gemini route", () => {
      expect(response.reasoning).toBe("thinking")
      expect(response.usage).toMatchObject({
        inputTokens: 5,
-        outputTokens: 2,
-        reasoningTokens: 1,
+        outputTokens: 3,
+        nonCachedInputTokens: 4,
        cacheReadInputTokens: 1,
+        reasoningTokens: 1,
        totalTokens: 7,
      })
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 3,
+        nonCachedInputTokens: 4,
+        cacheReadInputTokens: 1,
+        reasoningTokens: 1,
+        totalTokens: 7,
+        providerMetadata: {
+          google: {
+            promptTokenCount: 5,
+            candidatesTokenCount: 2,
+            totalTokenCount: 7,
+            thoughtsTokenCount: 1,
+            cachedContentTokenCount: 1,
+          },
+        },
+      })
      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "reasoning-start", id: "reasoning-0" },
        { type: "reasoning-delta", id: "reasoning-0", text: "thinking" },
+        { type: "text-start", id: "text-0" },
        { type: "text-delta", id: "text-0", text: "Hello" },
        { type: "text-delta", id: "text-0", text: "!" },
+        { type: "reasoning-end", id: "reasoning-0" },
+        { type: "text-end", id: "text-0" },
+        { type: "step-finish", index: 0, reason: "stop", usage, providerMetadata: undefined },
        {
          type: "request-finish",
          reason: "stop",
-          usage: {
-            inputTokens: 5,
-            outputTokens: 2,
-            reasoningTokens: 1,
-            cacheReadInputTokens: 1,
-            totalTokens: 7,
-            native: {
-              promptTokenCount: 5,
-              candidatesTokenCount: 2,
-              totalTokenCount: 7,
-              thoughtsTokenCount: 1,
-              cachedContentTokenCount: 1,
-            },
-          },
+          usage,
        },
      ])
    }),
@@ -248,21 +259,41 @@ describe("Gemini route", () => {
          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
        }),
      ).pipe(Effect.provide(fixedResponse(body)))
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 1,
+        nonCachedInputTokens: 5,
+        cacheReadInputTokens: undefined,
+        reasoningTokens: undefined,
+        totalTokens: 6,
+        providerMetadata: { google: { promptTokenCount: 5, candidatesTokenCount: 1 } },
+      })

      expect(response.toolCalls).toEqual([
-        { type: "tool-call", id: "tool_0", name: "lookup", input: { query: "weather" } },
+        {
+          type: "tool-call",
+          id: "tool_0",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
      ])
      expect(response.events).toEqual([
-        { type: "tool-call", id: "tool_0", name: "lookup", input: { query: "weather" } },
+        { type: "step-start", index: 0 },
+        {
+          type: "tool-call",
+          id: "tool_0",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+        { type: "step-finish", index: 0, reason: "tool-calls", usage, providerMetadata: undefined },
        {
          type: "request-finish",
          reason: "tool-calls",
-          usage: {
-            inputTokens: 5,
-            outputTokens: 1,
-            totalTokens: 6,
-            native: { promptTokenCount: 5, candidatesTokenCount: 1 },
-          },
+          usage,
        },
      ])
    }),
@@ -313,8 +344,10 @@ describe("Gemini route", () => {
        ),
      )

-      expect(length.events).toEqual([{ type: "request-finish", reason: "length" }])
-      expect(filtered.events).toEqual([{ type: "request-finish", reason: "content-filter" }])
+      expect(length.events.map((event) => event.type)).toEqual(["step-start", "step-finish", "request-finish"])
+      expect(length.events.at(-1)).toMatchObject({ type: "request-finish", reason: "length" })
+      expect(filtered.events.map((event) => event.type)).toEqual(["step-start", "step-finish", "request-finish"])
+      expect(filtered.events.at(-1)).toMatchObject({ type: "request-finish", reason: "content-filter" })
    }),
  )

@@ -348,7 +381,7 @@ describe("Gemini route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [LLM.assistant({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [Message.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 } from "../../src"
+import { LLM, LLMError, Message, ToolCallPart, Usage } 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: [
-            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" } }),
+            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" } }),
          ],
        }),
      )
@@ -185,7 +185,7 @@ describe("OpenAI Chat route", () => {
        LLM.request({
          id: "req_media",
          model,
-          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+          messages: [Message.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: [LLM.assistant({ type: "reasoning", text: "hidden" })],
+          messages: [Message.assistant({ type: "reasoning", text: "hidden" })],
        }),
      ).pipe(Effect.flip)

@@ -222,28 +222,36 @@ describe("OpenAI Chat route", () => {
        }),
      )
      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 2,
+        nonCachedInputTokens: 4,
+        cacheReadInputTokens: 1,
+        reasoningTokens: 0,
+        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 },
+          },
+        },
+      })

      expect(response.text).toBe("Hello!")
      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "text-start", id: "text-0" },
        { type: "text-delta", id: "text-0", text: "Hello" },
        { type: "text-delta", id: "text-0", text: "!" },
+        { type: "text-end", id: "text-0" },
+        { type: "step-finish", index: 0, reason: "stop", usage, providerMetadata: undefined },
        {
          type: "request-finish",
          reason: "stop",
-          usage: {
-            inputTokens: 5,
-            outputTokens: 2,
-            reasoningTokens: 0,
-            cacheReadInputTokens: 1,
-            totalTokens: 7,
-            native: {
-              prompt_tokens: 5,
-              completion_tokens: 2,
-              total_tokens: 7,
-              prompt_tokens_details: { cached_tokens: 1 },
-              completion_tokens_details: { reasoning_tokens: 0 },
-            },
-          },
+          usage,
        },
      ])
    }),
@@ -266,9 +274,20 @@ describe("OpenAI Chat route", () => {
      ).pipe(Effect.provide(fixedResponse(body)))

      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata: undefined },
        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
-        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata: undefined },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+        { type: "step-finish", index: 0, reason: "tool-calls", usage: undefined, providerMetadata: undefined },
        { type: "request-finish", reason: "tool-calls", usage: undefined },
      ])
    }),
@@ -290,6 +309,8 @@ describe("OpenAI Chat route", () => {
      ).pipe(Effect.provide(fixedResponse(body)))

      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata: undefined },
        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
      ])
@@ -349,7 +370,7 @@ describe("OpenAI Chat route", () => {
      const events = Array.from(
        yield* LLMClient.stream(request).pipe(Stream.take(1), Stream.runCollect, Effect.provide(fixedResponse(body))),
      )
-      expect(events.map((event) => event.type)).toEqual(["text-delta"])
+      expect(events.map((event) => event.type)).toEqual(["step-start"])
    }),
  )
 })
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Kit LangtonandGitHub	613a8d1beb	test(provider): migrate more config-backed cases (#26984 )	2026-05-11 22:21:50 -04:00
Kit Langton	708557880b	test(provider): migrate provider tests to effect runner	2026-05-11 22:13:26 -04:00
Kit LangtonandGitHub	0f5d4ae648	test(project): stabilize VCS branch update test (#26979 )	2026-05-11 22:12:07 -04:00
Kit LangtonandGitHub	ce72020750	test(tool): migrate edit tests to Effect runner (#26977 )	2026-05-11 21:42:17 -04:00
Kit LangtonandGitHub	c43d606f8e	agent: use Effect schema for generated agent object (#26973 )	2026-05-11 21:42:04 -04:00
Kit LangtonandGitHub	1007630347	Migrate runtime validators to Effect Schema (#26975 )	2026-05-11 21:41:56 -04:00
Kit LangtonandGitHub	9e8274d2da	Remove internal Zod schemas (#26974 )	2026-05-11 21:40:44 -04:00
Kit LangtonandGitHub	74aa735e6a	fix(tui): guard prompt submit against concurrent invocation (#26972 )	2026-05-12 01:35:28 +00:00
Kit LangtonandGitHub	8030a6c187	Emit LLM stream lifecycle events (#26971 )	2026-05-11 21:31:48 -04:00
Kit LangtonandGitHub	e5aa5161f2	Remove effect-zod bridge (#26956 )	2026-05-11 21:14:55 -04:00
Kit LangtonandGitHub	abb1ee6278	docs(test): add Effect migration orchestration notes (#26963 )	2026-05-11 20:59:51 -04:00
Kit LangtonandGitHub	c4003579bb	test(project): migrate VCS tests to Effect runner (#26965 )	2026-05-11 20:59:34 -04:00
Kit LangtonandGitHub	0d9c534184	test(snapshot): migrate snapshot tests to Effect runner (#26964 )	2026-05-11 20:59:31 -04:00
Aiden ClineandGitHub	5773d43cbf	ci: GitHub Actions dependencies (#26962 )	2026-05-11 19:50:35 -05:00
opencode-agent[bot]	e0e9414cbd	chore: generate	2026-05-12 00:41:30 +00:00
Kit LangtonandGitHub	44edb639c2	test(session): migrate message pagination to Effect runner (#26957 )	2026-05-12 00:40:23 +00:00
Kit LangtonandGitHub	fbd52ca2f4	test(file): migrate file tests to Effect runner (#26959 )	2026-05-12 00:39:31 +00:00
opencode-agent[bot]	8015ff7ca5	chore: generate	2026-05-12 00:33:34 +00:00
Kit LangtonandGitHub	ec9584177f	docs(test): plan Effect test migration (#26954 )	2026-05-11 20:32:27 -04:00
Kit LangtonandGitHub	061efc6cf2	Fix run JSON output draining (#26955 )	2026-05-11 20:30:23 -04:00
Brendan AllanandGitHub	fe374aea46	feat(app): persist todo dock collapsed state (#26953 )	2026-05-11 23:59:38 +00:00
Kit LangtonandGitHub	46edc98f10	Validate TUI config with Effect Schema (#26952 )	2026-05-11 23:51:45 +00:00
Kit LangtonandGitHub	fdeb2748e1	test(agent): isolate plugin agent regression (#26948 )	2026-05-11 19:38:54 -04:00
Kit LangtonandGitHub	59e6967b8f	Generate config schema from Effect Schema (#26939 )	2026-05-11 19:24:58 -04:00
opencode-agent[bot]	0c619cb59c	chore: generate	2026-05-11 22:34:04 +00:00
Frank	0cf90109dc	zen: tps rate limit	2026-05-11 18:32:39 -04:00
Kit LangtonandGitHub	812668ae2f	Generate TUI schema from Effect Schema (#26945 )	2026-05-11 17:50:14 -04:00
Kit LangtonandGitHub	a5c35bf182	Avoid bootstrapping server plugins from TUI plugin runtime (#26938 )	2026-05-11 17:32:16 -04:00
opencode-agent[bot]	bdd5a80886	chore: update nix node_modules hashes	2026-05-11 21:28:49 +00:00
Kit LangtonandGitHub	fd65d29dcc	Drop unused opencode Zod statics (#26935 )	2026-05-11 17:14:18 -04:00
Kit LangtonandGitHub	d3caac5270	chore(deps): upgrade effect to 4.0.0-beta.65 (#26934 )	2026-05-11 21:09:57 +00:00
Kit LangtonandGitHub	fe7ca3421e	Drop Config Info Zod static (#26933 )	2026-05-11 16:49:22 -04:00
Kit LangtonandGitHub	cc95197d72	Drop prompt input Zod statics (#26923 )	2026-05-11 16:49:08 -04:00
James LongandGitHub	9067218b74	fix(core): always start worktrees as detached (#26931 )	2026-05-11 16:22:25 -04:00
Kit LangtonandGitHub	42a0453945	Drop small session Zod statics (#26921 )	2026-05-11 16:12:31 -04:00
Kit LangtonandGitHub	4d9eb6c320	Validate structured output tests with Effect Schema (#26919 )	2026-05-11 16:11:25 -04:00
Kit LangtonandGitHub	c060c436b6	Drop LSP config Zod statics (#26920 )	2026-05-11 16:11:11 -04:00
Kit LangtonandGitHub	45adfedd64	Drop unused domain Zod statics (#26927 )	2026-05-11 16:10:58 -04:00
opencode-agent[bot]	0bced8ec96	chore: update nix node_modules hashes	2026-05-11 17:32:56 +00:00
Kit LangtonandGitHub	8d9b9719be	Drop unused small ID Zod statics (#26908 )	2026-05-11 13:22:59 -04:00
Kit LangtonandGitHub	c7e084c32c	Simplify single-backend HttpApi exerciser (#26906 )	2026-05-11 13:22:31 -04:00
Kit LangtonandGitHub	6f2f759fbb	Clean up post-Hono references (#26903 )	2026-05-11 13:20:54 -04:00
opencode-agent[bot]	cddab63808	chore: generate	2026-05-11 17:17:38 +00:00
Shoubhit DashandGitHub	12583b18f0	feat(tui): pin, quick-switch, and cycle recent sessions (#26858 )	2026-05-11 22:46:27 +05:30
Kit LangtonandGitHub	df386bd651	feat(skill): enable customize-opencode by default, link full schema (#26899 )	2026-05-11 13:13:41 -04:00
opencode-agent[bot]	25b12ed754	chore: generate	2026-05-11 17:06:57 +00:00
Kit LangtonandGitHub	023e1c711e	refactor(llm): colocate per-type factories on their namespaces (#26799 )	2026-05-11 13:05:41 -04:00
Kit LangtonandGitHub	52f7ba7d4d	fix(llm): drop removed dispatch option from recorded cache tests (#26900 )	2026-05-11 11:48:30 -04:00
opencode-agent[bot]	19fce2bc6f	chore: generate	2026-05-11 15:21:20 +00:00
Shoubhit DashandGitHub	4bae84c8b0	feat(scout): autocomplete configured mentions (#26843 )	2026-05-11 20:50:03 +05:30
Kit LangtonandGitHub	f240bba8e7	chore(http-recorder): remove content-matching dispatch mode (#26792 )	2026-05-11 11:10:18 -04:00
Kit LangtonandGitHub	bcee247988	Define project update input with Effect Schema (#26803 )	2026-05-11 15:05:31 +00:00
Kit LangtonandGitHub	64c504212a	Parse command config with Effect Schema (#26801 )	2026-05-11 10:22:45 -04:00
opencode-agent[bot]	6592d80460	chore: generate	2026-05-11 14:13:39 +00:00
SebastianandGitHub	d821650b48	add default diff parser for markdown fenced code blocks (#26887 )	2026-05-11 14:12:32 +00:00
Victor NavarroandGitHub	6c9f12bb2d	chore: exclude status 429 from free model alerts (#26879 )	2026-05-11 16:04:54 +02:00
opencode-agent[bot]	fca89e5e4d	chore: generate	2026-05-11 13:44:39 +00:00
Frank	1eff01b6a5	sync	2026-05-11 09:43:12 -04:00
opencode-agent[bot]	e93b1f3a7f	chore: generate	2026-05-11 13:38:44 +00:00
Frank	8874d4a42f	zen: deekseek v4 flash free	2026-05-11 09:37:14 -04:00
Brendan AllanandGitHub	c933504d9c	fix(ui): better handle patch file support when rendering patch/edit tools (#26828 )	2026-05-11 17:21:59 +08:00
Shoubhit DashandGitHub	2d0d3d596e	feat(compaction): serialize compaction tail (#26830 )	2026-05-11 13:40:36 +05:30
opencode-agent[bot]	3bd98ea055	chore: generate	2026-05-11 07:28:32 +00:00
Shoubhit DashandGitHub	7e997cfba4	refactor(scout): resolve configured reference mentions (#26701 )	2026-05-11 12:57:26 +05:30
Brendan AllanandGitHub	5d6f2a1524	fix(ui): use part_text_accum_delta to prevent markdown cutoff during streaming (#26822 )	2026-05-11 15:15:03 +08:00
opencode-agent[bot]	b1cb71856e	chore: generate	2026-05-11 05:27:40 +00:00
Aiden ClineandGitHub	518264fcd9	fix(opencode): fix full session fork (#26811 )	2026-05-11 00:26:36 -05:00
DaxandGitHub	7235c9c9b8	Trace data migrations (#26809 )	2026-05-11 03:23:01 +00:00
Kit LangtonandGitHub	274033cd52	Validate prompt messages with Effect Schema (#26796 )	2026-05-11 02:59:20 +00:00
Kit LangtonandGitHub	9b369ee815	chore(llm): make cache: 'auto' the default (#26798 )	2026-05-10 22:46:01 -04:00
SebastianandGitHub	721ff5121e	fix prompt history behaviour and session line up/down commands (#26797 )	2026-05-11 02:27:46 +00:00
opencode-agent[bot]	cfbf5d1c6f	chore: update nix node_modules hashes	2026-05-11 02:20:35 +00:00
opencode-agent[bot]	02cb7e7b71	chore: generate	2026-05-11 02:11:07 +00:00
Kit LangtonandGitHub	942630eb4a	feat(llm): cache-policy auto-placement (#26786 )	2026-05-10 22:09:55 -04:00
opencode	ce66b191d1	sync release versions for v1.14.48	2026-05-11 02:07:48 +00:00
Kit LangtonandGitHub	6f1f5944ce	Delete unused opencode Zod helpers (#26793 )	2026-05-10 21:57:18 -04:00
opencode-agent[bot]	1c49b2ed67	chore: generate	2026-05-11 01:55:22 +00:00
opencode-agent[bot]	3c6be604ec	chore: update nix node_modules hashes	2026-05-11 01:54:13 +00:00
Kit LangtonandGitHub	ddc02c2893	Drop synchronous SyncEvent facades (#26789 )	2026-05-11 01:53:50 +00:00
Kit LangtonandGitHub	2703eff2e2	refactor(llm): normalize Usage as inclusive total + non-overlapping breakdown (#26735 )	2026-05-10 21:52:50 -04:00
opencode-agent[bot]	38e4540119	chore: generate	2026-05-11 01:41:26 +00:00
Dax Raad	4100fcbd17	disable image resizing	2026-05-10 21:40:12 -04:00
Kit LangtonandGitHub	83cb0f60ec	Drop EventV2 run facade (#26783 )	2026-05-10 21:26:28 -04:00
Kit LangtonandGitHub	effd96755e	Use SyncEvent service at event call sites (#26782 )	2026-05-10 21:20:13 -04:00
opencode-agent[bot]	5801cce1b5	chore: generate	2026-05-11 01:18:39 +00:00
Kit LangtonandGitHub	77e6c0d329	feat(llm): cache hint TTL, breakpoint cap, and tool placement (#26779 )	2026-05-10 21:17:38 -04:00
Kit LangtonandGitHub	fed716ada5	Clarify compaction test harness (#26777 )	2026-05-10 20:41:21 -04:00
opencode	426d92e352	sync release versions for v1.14.47	2026-05-11 00:23:17 +00:00
opencode-agent[bot]	d0412a213b	chore: generate	2026-05-11 00:18:03 +00:00
Kit LangtonandGitHub	16aa67086b	Effectify remaining compaction process tests (#26776 )	2026-05-10 20:17:01 -04:00
DaxandGitHub	7cea32ee08	Add background code migration service (#26652 )	2026-05-11 00:16:42 +00:00