Add files using upload-large-folder tool

.github/APPROVED_CONTRIBUTORS

@@ -0,0 +1,395 @@
+# GitHub handles approved to bypass contribution auto-close
+# Format: <username> <capability>
+# capability:
+#   issue  future issues stay open
+#   pr     future issues and PRs stay open
+
+herrnel pr
+julien-c pr
+barapa pr
+alasano pr
+aadishv pr
+airtonix pr
+aliou pr
+aos pr
+austinm911 pr
+banteg pr
+ben-vargas pr
+butelo pr
+can1357 pr
+CarlosGtrz pr
+cau1k pr
+cmf pr
+crcatala pr
+Cursivez pr
+cv pr
+dannote pr
+default-anton pr
+dnouri pr
+DronNick pr
+enisdenjo pr
+ferologics pr
+fightbulc pr
+ghoulr pr
+gnattu pr
+HACKE-RC pr
+hewliyang pr
+hjanuschka pr
+iamd3vil pr
+jblwilliams pr
+joshp123 pr
+jsinge97 pr
+justram pr
+kaofelix pr
+kiliman pr
+kim0 pr
+lockmeister pr
+LukeFost pr
+lukele pr
+m-box-mr pr
+marckrenn pr
+markusylisiurunen pr
+mcinteerj pr
+melihmucuk pr
+mitsuhiko pr
+mrexodia pr
+nathyong pr
+nickseelert pr
+nicobailon pr
+ninlds pr
+ogulcancelik pr
+patrick-kidger pr
+paulbettner pr
+Perlence pr
+pjtf93 pr
+prateekmedia pr
+prathamdby pr
+ribelo pr
+richardgill pr
+robinwander pr
+ronyrus pr
+roshanasingh4 pr
+scutifer pr
+skuridin pr
+steipete pr
+svkozak pr
+tallshort pr
+theBucky pr
+thomasmhr pr
+tiagoefreitas pr
+timolins pr
+tmustier pr
+tudoroancea pr
+unexge pr
+vaayne pr
+VaclavSynacek pr
+vsabavat pr
+w-winter pr
+Whamp pr
+WismutHansen pr
+XesGaDeus pr
+yevhen pr
+badlogictest pr
+terrorobe pr
+zedrdave pr
+mrud pr
+toorusr pr
+andresaraujo pr
+lightningRalf pr
+williballenthin pr
+masonc15 pr
+4h9fbZ pr
+haoqixu pr
+Graffioh pr
+charles-cooper pr
+emanuelst pr
+juanibiapina pr
+liby pr
+pasky pr
+odysseus0 pr
+giuseppeg pr
+michaelpersonal pr
+academo pr
+PriNova pr
+semtexzv pr
+jasonish pr
+markusn pr
+SamFold pr
+Soleone pr
+virtuald pr
+NateSmyth pr
+7Sageer pr
+MatthieuBizien pr
+sumeet pr
+marchellodev pr
+vedang pr
+lucemia pr
+mcollina pr
+lajarre pr
+smithbm2316 pr
+drewburr pr
+gordonhwc pr
+deybhayden pr
+tintinweb pr
+asoules pr
+zhahaoyu pr
+in0vik pr
+jtac pr
+yzhg1983 pr
+smcllns pr
+dmmulroy pr
+zmberber pr
+andresvi94 pr
+sudosubin pr
+Mic92 pr
+pmateusz pr
+wirjo pr
+jay-aye-see-kay pr
+lucasmeijer pr
+Evizero pr
+
+ofa1 pr
+
+crisog issue
+
+mpazik pr
+
+vekexasia pr
+
+Michaelliv pr
+
+cmraible pr
+
+dljsjr pr
+
+drio pr
+
+jlaneve pr
+
+tantara pr
+
+Nutlope pr
+
+xl0 pr
+
+mdsjip pr
+
+Exrun94 pr
+
+marcbloech pr
+
+pidalf pr
+
+injaneity pr
+
+thirtythreeforty pr
+
+justinpbarnett pr
+
+cristinaponcela pr
+
+LooSik pr
+
+mchenco pr
+
+Phoen1xCode pr
+
+louis030195 pr
+
+technocidal pr
+
+pandada8 pr
+
+npupko issue
+
+chrisvariety pr
+
+maximilianzuern pr
+
+brianmichel pr
+
+abhinavmathur-atlan pr
+
+mattiacerutti pr
+
+josephyoung pr
+
+mbazso pr
+
+AJM10565 pr
+
+DanielThomas pr
+
+MichaelYochpaz pr
+
+stephanmck pr
+
+rolfvreijdenberger pr
+
+psoukie pr
+
+vastxie pr
+
+ItsumoSeito pr
+
+davidlifschitz pr
+
+vdxz pr
+
+dangooddd pr
+
+Mearman pr
+
+dodiego pr
+
+any-victor pr
+
+geraschenko pr
+
+skhoroshavin pr
+
+cyzlmh pr
+
+xz-dev pr
+
+rajp152k pr
+
+affanali2k3 pr
+
+ArcadiaLin pr
+
+anilgulecha pr
+
+DeviosLang pr
+
+HarrodRen pr
+
+aaronkyriesenbach pr
+
+farid-fari pr
+
+petrroll pr
+
+vibeinging pr
+
+DivineDominion pr
+
+ananthakumaran pr
+
+andrebreijao pr
+
+anh-chu pr
+
+rsaryev pr
+
+QuintinShaw pr
+
+R-Taneja pr
+
+zaycruz pr
+
+mteam88 pr
+
+christianbasch pr
+
+cpacker pr
+
+rgarcia pr
+
+renaudhartert-db pr
+
+HyeokjaeLee pr
+
+arajkumar pr
+
+brianstanley pr
+
+scruffymongrel pr
+
+SI-RUI-ZHANG pr
+
+sunnyyoung pr
+
+muyiyr pr
+
+hi-neason pr
+
+acmerfight pr
+
+tizmagik pr
+
+jingtao-wisdomgraph pr
+
+XRX193 pr
+
+autopeasant pr
+
+Snail-Turbo pr
+
+futile pr
+
+arasovic pr
+
+xXJSONDeruloXx pr
+
+Marvae pr
+
+skkdevcraft pr
+
+PierrunoYT pr
+
+zhichli pr
+
+wesleyzhangwq pr
+
+dgokeeffe pr
+
+vipentti pr
+
+midastruth pr
+
+Maximo-Guk pr
+
+bigoldcat123 pr
+
+johnatbasicas pr
+
+powerfooI pr
+
+yearth pr
+
+pablasso pr
+
+bilby91 pr
+
+giannisCKS pr
+
+Panoplos pr
+
+haoyongchun1125-maker pr
+
+gwokhou pr
+
+gaoyk19 pr
+
+cad0p pr
+
+Jaaneek pr
+
+CaiJichang212 pr
+
+Mallikarjun-0 pr
+
+wutongyuonce pr
+
+Terminator666666 pr
+
+y-nk pr
+
+edverma pr
+
+Charlie0113-T pr
+
+RedBeard0531 pr
+
+metaist pr

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,45 @@
+name: Bug Report
+description: Report something that's broken
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before you start:** Read [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/main/CONTRIBUTING.md).
+
+        New issues from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. Issues that do not meet the quality bar in [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/main/CONTRIBUTING.md) will not be reopened or receive a reply.
+
+        Keep this short. If it doesn't fit on one screen, it's too long. Write in your own voice.
+
+        **Important:** before reporting an issue in core, please validate first with `pi -ne` that this is not caused by an extension you loaded.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Be specific. Include error messages if any.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to trigger the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: e.g. 0.49.0
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions
+    url: https://discord.com/invite/3cU7Bz4UPx
+    about: Ask questions on Discord instead of opening an issue

.github/ISSUE_TEMPLATE/contribution.yml

@@ -0,0 +1,36 @@
+name: Contribution Proposal
+description: Propose a change or feature (required for new contributors before submitting a PR)
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before you start:** Read [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/main/CONTRIBUTING.md).
+
+        New issues from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. Issues that do not meet the quality bar in [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/main/CONTRIBUTING.md) will not be reopened or receive a reply.
+
+        Keep this short. If it doesn't fit on one screen, it's too long. Write in your own voice.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What do you want to change?
+      description: Be specific and concise.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why?
+      description: What problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How? (optional)
+      description: Brief technical approach if you have one in mind.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/package-report.yml

@@ -0,0 +1,49 @@
+name: Package Report
+description: Report a problematic Pi package listed on pi.dev
+labels: ["package-report"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form to report a package listed on pi.dev. For Pi core bugs, use the bug report template instead.
+
+        New issues from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. Issues that do not meet the quality bar in [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/main/CONTRIBUTING.md) will not be reopened or receive a reply.
+
+        Keep this short. If it doesn't fit on one screen, it's too long. Write in your own voice.
+
+  - type: input
+    id: package-name
+    attributes:
+      label: Package name
+      description: The npm package name from pi.dev.
+      placeholder: "@scope/package"
+    validations:
+      required: true
+
+  - type: input
+    id: package-version
+    attributes:
+      label: Version
+      description: The package version shown on pi.dev.
+      placeholder: "0.1.0"
+    validations:
+      required: false
+
+  - type: dropdown
+    id: report-type
+    attributes:
+      label: What are you reporting?
+      options:
+        - Malicious or unsafe behavior
+        - Impersonation
+        - Trademark / TOS Violations
+    validations:
+      required: true
+
+  - type: textarea
+    id: details
+    attributes:
+      label: Details
+      description: Describe the concern and include links, logs, or screenshots if helpful.
+    validations:
+      required: true

.github/workflows/approve-contributor.yml

@@ -0,0 +1,223 @@
+name: Approve Contributor
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  approve:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Update contributor approval
+        id: update
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require('fs');
+
+            const APPROVED_FILE = '.github/APPROVED_CONTRIBUTORS';
+            const VALID_CAPABILITIES = new Set(['issue', 'pr']);
+            const issueAuthor = context.payload.issue.user.login;
+            const commenter = context.payload.comment.user.login;
+            const commentBody = (context.payload.comment.body || '').trim();
+
+            const approvalAtStartPattern = /^[\s.]*(?:@[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?(?:\s*,\s*|[.:]\s*|\s+))*(lgtmi|lgtm)(?=$|[\s]|[^\p{L}\p{N}_\s])/iu;
+            const approvalAtEndPattern = /(?:^|[\s.])(lgtmi|lgtm)\s*(?:[^\p{L}\p{N}_\s])?\s*$/iu;
+            const approvalMatch = commentBody.match(approvalAtStartPattern) ?? commentBody.match(approvalAtEndPattern);
+
+            if (!approvalMatch) {
+              console.log('Comment does not start or end with lgtm or lgtmi');
+              core.setOutput('status', 'skipped');
+              return;
+            }
+
+            const targetCapability = approvalMatch[1].toLowerCase() === 'lgtmi' ? 'issue' : 'pr';
+
+            try {
+              const { data: permissionLevel } = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username: commenter,
+              });
+
+              if (!['admin', 'maintain', 'write'].includes(permissionLevel.permission)) {
+                console.log(`${commenter} does not have write access`);
+                core.setOutput('status', 'skipped');
+                return;
+              }
+            } catch {
+              console.log(`${commenter} does not have collaborator access`);
+              core.setOutput('status', 'skipped');
+              return;
+            }
+
+            function parseMentionedUsers(body) {
+              const users = [];
+              const seenUsers = new Set();
+              const mentionPattern = /(^|[^A-Za-z0-9_])@([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)(?![A-Za-z0-9-]|\/)/g;
+
+              for (const match of body.matchAll(mentionPattern)) {
+                const username = match[2];
+                const normalizedUser = username.toLowerCase();
+                if (seenUsers.has(normalizedUser)) {
+                  continue;
+                }
+                seenUsers.add(normalizedUser);
+                users.push(username);
+              }
+
+              return users;
+            }
+
+            function parseApprovedUsers(content) {
+              const lines = content.split('\n');
+              const entries = [];
+              const users = new Map();
+
+              for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#')) {
+                  entries.push({ type: 'other', line });
+                  continue;
+                }
+
+                const parts = trimmed.split(/\s+/);
+                if (parts.length !== 2) {
+                  console.log(`Skipping malformed line: ${line}`);
+                  entries.push({ type: 'other', line });
+                  continue;
+                }
+
+                const [username, capability] = parts;
+                const normalizedCapability = capability.toLowerCase();
+                if (!VALID_CAPABILITIES.has(normalizedCapability)) {
+                  console.log(`Skipping line with invalid capability: ${line}`);
+                  entries.push({ type: 'other', line });
+                  continue;
+                }
+
+                const normalizedUser = username.toLowerCase();
+                const entry = { type: 'user', username, normalizedUser, capability: normalizedCapability };
+                entries.push(entry);
+                users.set(normalizedUser, entry);
+              }
+
+              return { entries, users };
+            }
+
+            function stringifyApprovedUsers(entries) {
+              const normalizedEntries = [...entries];
+
+              while (normalizedEntries.length > 0) {
+                const lastEntry = normalizedEntries[normalizedEntries.length - 1];
+                if (lastEntry.type !== 'other' || lastEntry.line.trim() !== '') {
+                  break;
+                }
+                normalizedEntries.pop();
+              }
+
+              return `${normalizedEntries
+                .map((entry) => (entry.type === 'user' ? `${entry.username} ${entry.capability}` : entry.line))
+                .join('\n')}\n`;
+            }
+
+            const content = fs.readFileSync(APPROVED_FILE, 'utf8');
+            const { entries, users } = parseApprovedUsers(content);
+            const mentionedUsers = parseMentionedUsers(commentBody);
+            const approvalTargets = mentionedUsers.length > 0 ? mentionedUsers : [issueAuthor];
+            const changedTargets = [];
+            const alreadyTargets = [];
+
+            for (const username of approvalTargets) {
+              const normalizedUser = username.toLowerCase();
+              const existingEntry = users.get(normalizedUser);
+              const existingCapability = existingEntry?.capability ?? null;
+
+              if (existingCapability === 'pr' || existingCapability === targetCapability) {
+                alreadyTargets.push(existingEntry?.username ?? username);
+                console.log(`${username} is already approved for ${existingCapability}`);
+                continue;
+              }
+
+              if (existingEntry) {
+                existingEntry.capability = targetCapability;
+                changedTargets.push(existingEntry.username);
+              } else {
+                const entry = { type: 'user', username, normalizedUser, capability: targetCapability };
+                entries.push(entry);
+                users.set(normalizedUser, entry);
+                changedTargets.push(username);
+              }
+
+              console.log(`Set ${username} capability to ${targetCapability}`);
+            }
+
+            core.setOutput('capability', targetCapability);
+            core.setOutput('changed_targets', JSON.stringify(changedTargets));
+            core.setOutput('already_targets', JSON.stringify(alreadyTargets));
+
+            if (changedTargets.length === 0) {
+              core.setOutput('status', 'already');
+              return;
+            }
+
+            fs.writeFileSync(APPROVED_FILE, stringifyApprovedUsers(entries));
+            core.setOutput('status', 'changed');
+
+      - name: Commit and push
+        if: steps.update.outputs.status == 'changed'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github/APPROVED_CONTRIBUTORS
+          git diff --staged --quiet || git commit -m "chore: approve contributors from issue #${{ github.event.issue.number }}"
+          git push
+
+      - name: Comment on issue
+        if: steps.update.outputs.status == 'changed' || steps.update.outputs.status == 'already'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          CAPABILITY: ${{ steps.update.outputs.capability }}
+          CHANGED_TARGETS: ${{ steps.update.outputs.changed_targets }}
+          ALREADY_TARGETS: ${{ steps.update.outputs.already_targets }}
+        with:
+          script: |
+            const capability = process.env.CAPABILITY;
+            const changedTargets = JSON.parse(process.env.CHANGED_TARGETS || '[]');
+            const alreadyTargets = JSON.parse(process.env.ALREADY_TARGETS || '[]');
+            const defaultBranch = context.payload.repository.default_branch;
+            const formatTargets = (targets) => targets.map((target) => `@${target}`).join(', ');
+            const bodyLines = [];
+
+            if (changedTargets.length > 0) {
+              if (capability === 'issue') {
+                bodyLines.push(`${formatTargets(changedTargets)} approved for issues. Future issues will not be auto-closed. PRs still require \`lgtm\` at the start of a maintainer reply (optionally after one or more \`@username\` mentions) or at the end.`);
+              } else {
+                bodyLines.push(`${formatTargets(changedTargets)} approved for issues and PRs. Future issues and PRs will not be auto-closed.`);
+              }
+            }
+
+            if (alreadyTargets.length > 0) {
+              const verb = alreadyTargets.length === 1 ? 'is' : 'are';
+              bodyLines.push(`${formatTargets(alreadyTargets)} ${verb} already approved.`);
+            }
+
+            bodyLines.push('', `See [CONTRIBUTING.md](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/${defaultBranch}/CONTRIBUTING.md).`);
+            const body = bodyLines.join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body,
+            });
+

.github/workflows/build-binaries.yml

@@ -0,0 +1,444 @@
+name: Build Binaries
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to build (e.g., v0.12.0)'
+        required: true
+        type: string
+      source_ref:
+        description: 'Source ref to build/publish (defaults to tag; use only for release recovery)'
+        required: false
+        type: string
+
+permissions: {}
+
+concurrency:
+  group: build-binaries-${{ github.event.inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  # Keep the public GitHub Release publication last. Binary assets are staged in
+  # a draft release first; cleanup removes the draft if later publishing fails.
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+      SOURCE_REF: ${{ github.event.inputs.source_ref || github.event.inputs.tag || github.ref_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.SOURCE_REF }}
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.14
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Hydrate release model data
+        run: npm run hydrate:model-data
+
+      - name: Create source archive
+        run: |
+          set -euo pipefail
+
+          VERSION="${RELEASE_TAG#v}"
+          mkdir -p release-assets
+          ./scripts/create-source-archive.sh \
+            --version "${VERSION}" \
+            --ref HEAD \
+            --out "release-assets/pi-${VERSION}-source.tar.gz"
+
+      - name: Build binaries from source archive
+        run: |
+          set -euo pipefail
+
+          VERSION="${RELEASE_TAG#v}"
+          build_root="$(mktemp -d)"
+          trap 'rm -rf "${build_root}"' EXIT
+          tar -xzf "release-assets/pi-${VERSION}-source.tar.gz" -C "${build_root}"
+          "${build_root}/pi-${VERSION}/scripts/build-binaries.sh" \
+            --offline-model-data \
+            --out "${GITHUB_WORKSPACE}/packages/coding-agent/binaries"
+
+      - name: Prepare GitHub release payload
+        run: |
+          set -euo pipefail
+
+          mkdir -p release-assets
+
+          VERSION="${RELEASE_TAG}"
+          VERSION="${VERSION#v}"  # Remove 'v' prefix
+          node scripts/release-notes.mjs extract --version "${VERSION}" --tag "${RELEASE_TAG}" --out release-assets/RELEASE_NOTES.md
+          node scripts/generate-coding-agent-install-lock.mjs --check
+          cp packages/coding-agent/install-lock/package.json release-assets/pi-coding-agent-install-package.json
+          cp packages/coding-agent/install-lock/package-lock.json release-assets/pi-coding-agent-install-package-lock.json
+
+          cd packages/coding-agent/binaries
+
+          binary_assets=(
+            pi-darwin-arm64.tar.gz
+            pi-darwin-x64.tar.gz
+            pi-linux-x64.tar.gz
+            pi-linux-arm64.tar.gz
+            pi-windows-x64.zip
+            pi-windows-arm64.zip
+          )
+
+          for asset in "${binary_assets[@]}"; do
+            test -f "${asset}"
+          done
+
+          cp "${binary_assets[@]}" "${GITHUB_WORKSPACE}/release-assets/"
+
+          cd "${GITHUB_WORKSPACE}/release-assets"
+          source_asset="pi-${VERSION}-source.tar.gz"
+          release_assets=(
+            "${source_asset}"
+            pi-darwin-arm64.tar.gz
+            pi-darwin-x64.tar.gz
+            pi-linux-x64.tar.gz
+            pi-linux-arm64.tar.gz
+            pi-windows-x64.zip
+            pi-windows-arm64.zip
+            pi-coding-agent-install-package.json
+            pi-coding-agent-install-package-lock.json
+          )
+          sha256sum "${release_assets[@]}" > SHA256SUMS
+
+      - name: Upload GitHub release payload
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-assets-${{ env.RELEASE_TAG }}
+          path: release-assets/*
+          if-no-files-found: error
+          retention-days: 14
+
+  smoke-test-binaries:
+    runs-on: ${{ matrix.runner }}
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        runner:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+    permissions:
+      actions: read
+    env:
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+    steps:
+      - name: Download binary archives
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-assets-${{ env.RELEASE_TAG }}
+          path: release-assets
+
+      - name: Extract current-platform binary
+        id: binary
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          runtime_platform="$(node -p '`${process.platform}-${process.arch}`')"
+          case "${runtime_platform}" in
+            darwin-arm64|darwin-x64|linux-arm64|linux-x64)
+              platform="${runtime_platform}"
+              archive="release-assets/pi-${platform}.tar.gz"
+              root="extracted/pi"
+              binary="${root}/pi"
+              ;;
+            win32-arm64)
+              platform="windows-arm64"
+              archive="release-assets/pi-${platform}.zip"
+              root="extracted"
+              binary="${root}/pi.exe"
+              ;;
+            win32-x64)
+              platform="windows-x64"
+              archive="release-assets/pi-${platform}.zip"
+              root="extracted"
+              binary="${root}/pi.exe"
+              ;;
+            *)
+              echo "::error::Unsupported runner platform ${runtime_platform}"
+              exit 1
+              ;;
+          esac
+
+          mkdir -p extracted
+          if [[ "${archive}" == *.zip ]]; then
+            export ARCHIVE_PATH="$(cygpath -w "${archive}")"
+            export DESTINATION_PATH="$(cygpath -w extracted)"
+            powershell.exe -NoProfile -NonInteractive -Command \
+              'Expand-Archive -LiteralPath $env:ARCHIVE_PATH -DestinationPath $env:DESTINATION_PATH -Force'
+          else
+            tar -xf "${archive}" -C extracted
+          fi
+          echo "root=${root}" >> "${GITHUB_OUTPUT}"
+          echo "binary=${binary}" >> "${GITHUB_OUTPUT}"
+
+      - name: Smoke-test binary
+        shell: bash
+        run: |
+          "${{ steps.binary.outputs.binary }}" --help
+          "${{ steps.binary.outputs.binary }}" --version
+
+  stage-github-release:
+    runs-on: ubuntu-latest
+    needs:
+      - build
+      - smoke-test-binaries
+    permissions:
+      actions: read
+      contents: write
+    env:
+      GH_REPO: ${{ github.repository }}
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+    steps:
+      - name: Download GitHub release payload
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-assets-${{ env.RELEASE_TAG }}
+          path: release-assets
+
+      - name: Validate GitHub release payload
+        run: |
+          set -euo pipefail
+
+          cd release-assets
+
+          VERSION="${RELEASE_TAG#v}"
+          source_asset="pi-${VERSION}-source.tar.gz"
+          expected_assets=(
+            "${source_asset}"
+            pi-darwin-arm64.tar.gz
+            pi-darwin-x64.tar.gz
+            pi-linux-x64.tar.gz
+            pi-linux-arm64.tar.gz
+            pi-windows-x64.zip
+            pi-windows-arm64.zip
+            pi-coding-agent-install-package.json
+            pi-coding-agent-install-package-lock.json
+            SHA256SUMS
+            RELEASE_NOTES.md
+          )
+
+          for asset in "${expected_assets[@]}"; do
+            test -f "${asset}"
+          done
+
+          sha256sum -c SHA256SUMS
+
+      - name: Create draft GitHub Release and upload assets
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          cd release-assets
+
+          VERSION="${RELEASE_TAG#v}"
+          source_asset="pi-${VERSION}-source.tar.gz"
+          release_assets=(
+            "${source_asset}"
+            pi-darwin-arm64.tar.gz
+            pi-darwin-x64.tar.gz
+            pi-linux-x64.tar.gz
+            pi-linux-arm64.tar.gz
+            pi-windows-x64.zip
+            pi-windows-arm64.zip
+            pi-coding-agent-install-package.json
+            pi-coding-agent-install-package-lock.json
+            SHA256SUMS
+          )
+
+          existing_release="$(gh release view "${RELEASE_TAG}" --json isDraft --jq .isDraft 2>/dev/null || true)"
+          if [[ "${existing_release}" == "false" ]]; then
+            echo "::error::GitHub Release ${RELEASE_TAG} is already published. Refusing to mutate a public release."
+            exit 1
+          fi
+          if [[ "${existing_release}" == "true" ]]; then
+            gh release delete "${RELEASE_TAG}" --yes
+          fi
+
+          gh release create "${RELEASE_TAG}" \
+            --verify-tag \
+            --draft \
+            --title "${RELEASE_TAG}" \
+            --notes-file RELEASE_NOTES.md \
+            "${release_assets[@]}"
+
+          expected_asset_names="$(printf '%s\n' "${release_assets[@]}" | sort)"
+          actual_asset_names="$(gh release view "${RELEASE_TAG}" --json assets --jq '.assets[].name' | sort)"
+
+          if [[ "${actual_asset_names}" != "${expected_asset_names}" ]]; then
+            echo "::error::Draft GitHub Release asset set does not match expected files."
+            diff -u <(printf '%s\n' "${expected_asset_names}") <(printf '%s\n' "${actual_asset_names}") || true
+            exit 1
+          fi
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    needs: stage-github-release
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+      SOURCE_REF: ${{ github.event.inputs.source_ref || github.event.inputs.tag || github.ref_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.SOURCE_REF }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev fd-find ripgrep
+          sudo ln -s $(which fdfind) /usr/local/bin/fd
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Build
+        run: npm run build
+
+      - name: Check
+        run: npm run check
+
+      - name: Test
+        run: npm test
+
+      - name: Smoke-test packed npm consumer
+        run: npm run check:package-install
+
+      - name: Upgrade npm for trusted publishing
+        run: |
+          npm install -g npm@11.16.0 --ignore-scripts
+          npm --version
+
+      - name: Publish npm packages
+        run: node scripts/publish.mjs
+
+  announce-pi-dev-release:
+    runs-on: ubuntu-latest
+    needs: publish-npm
+    environment: pi-model-upload
+    concurrency:
+      group: announce-pi-dev-release
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    env:
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+      SOURCE_REF: ${{ github.event.inputs.source_ref || github.event.inputs.tag || github.ref_name }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.PI_ARTIFACTS_R2_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.PI_ARTIFACTS_R2_SECRET_ACCESS_KEY }}
+      AWS_DEFAULT_REGION: auto
+      AWS_EC2_METADATA_DISABLED: 'true'
+      R2_ENDPOINT: https://67c0d357268b0fca6e0b465bb9d01b84.r2.cloudflarestorage.com
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.SOURCE_REF }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+
+      - name: Verify AWS CLI
+        run: aws --version
+
+      - name: Announce verified release on pi.dev
+        run: |
+          node scripts/publish-release-announcement.mjs \
+            --version "${RELEASE_TAG#v}" \
+            --bucket pi-artifacts \
+            --endpoint "$R2_ENDPOINT" \
+            --installer-package-json packages/coding-agent/install-lock/package.json \
+            --installer-package-lock packages/coding-agent/install-lock/package-lock.json
+
+  publish-github-release:
+    runs-on: ubuntu-latest
+    needs:
+      - stage-github-release
+      - publish-npm
+      - announce-pi-dev-release
+    permissions:
+      contents: write
+    env:
+      GH_REPO: ${{ github.repository }}
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+    steps:
+      - name: Publish staged GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          existing_release="$(gh release view "${RELEASE_TAG}" --json isDraft --jq .isDraft 2>/dev/null || true)"
+          if [[ "${existing_release}" == "" ]]; then
+            echo "::error::Draft GitHub Release ${RELEASE_TAG} does not exist."
+            exit 1
+          fi
+          if [[ "${existing_release}" == "false" ]]; then
+            echo "::error::GitHub Release ${RELEASE_TAG} is already published."
+            exit 1
+          fi
+
+          gh release edit "${RELEASE_TAG}" --draft=false
+
+  cleanup-draft-github-release:
+    runs-on: ubuntu-latest
+    needs:
+      - build
+      - stage-github-release
+      - publish-npm
+      - announce-pi-dev-release
+      - publish-github-release
+    if: ${{ always() && needs.stage-github-release.result != 'skipped' && (needs.stage-github-release.result != 'success' || needs.publish-npm.result != 'success' || needs.announce-pi-dev-release.result != 'success' || needs.publish-github-release.result != 'success') }}
+    permissions:
+      contents: write
+    env:
+      GH_REPO: ${{ github.repository }}
+      RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+    steps:
+      - name: Delete draft GitHub Release after failure
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          existing_release="$(gh release view "${RELEASE_TAG}" --json isDraft --jq .isDraft 2>/dev/null || true)"
+          if [[ "${existing_release}" == "true" ]]; then
+            gh release delete "${RELEASE_TAG}" --yes
+          fi

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-check-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev fd-find ripgrep
+          sudo ln -s $(which fdfind) /usr/local/bin/fd
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Build
+        run: npm run build
+
+      - name: Check
+        run: npm run check
+
+      - name: Test
+        run: npm test

.github/workflows/issue-analysis.yml

@@ -0,0 +1,688 @@
+# Runs the repo's /is prompt against an issue when the `pi-analyze` label is added
+# or when a staff member comments `@issuron analyze` anywhere on an issue.
+#
+# Comment triggers can include one `#run-on-*` tag anywhere in the text:
+#   @issuron analyze #run-on-linux    -> ubuntu-latest (default)
+#   @issuron analyze #run-on-windows  -> windows-latest
+#   @issuron analyze #run-on-mac      -> macos-latest
+#
+# Label triggers always run on the default Linux runner. Runner selection is
+# intentionally restricted to hardcoded aliases in the authorization step.
+#
+# Setup required before this works:
+#   1. Create a `pi-analyze` GitHub environment on the repo and add a
+#      `PI_AUTH_JSON` secret containing the contents of a pi auth.json
+#      (~/.pi/agent/auth.json).
+#   2. Create the `pi-analyze` label.
+#   3. Add a repository secret `EARENDIL_ORG_READ_TOKEN` with permission to
+#      read `earendil-works` org membership. The authorization job uses it to
+#      verify that the label actor is an active member of `earendil-works/staff`.
+#   4. Add an environment secret `PI_GIST_TOKEN` on `pi-analyze` with gist
+#      creation permission. The analysis job uses it to upload the exported
+#      session gist.
+#   5. Add an environment secret `PI_AUTH_UPDATE_TOKEN` on `pi-analyze` with
+#      permission to update this repo's environment secrets. The analysis job
+#      uses it to write back refreshed `PI_AUTH_JSON` contents. Fine-grained
+#      tokens need repository permission `Environments: read and write` on this
+#      repo; classic tokens need the `repo` scope. The `Secrets` permission is
+#      not enough: it only covers repository-level Actions secrets, while every
+#      `/repos/{owner}/{repo}/environments/{env}/secrets/*` endpoint is governed
+#      by `Environments`. Without it `gh secret set` fails with "Resource not
+#      accessible by personal access token" and the stored credential goes stale
+#      until its refresh token is rejected.
+#
+# `PI_AUTH_JSON` must come from a login dedicated to this workflow. OpenAI Codex
+# rotates refresh tokens on every refresh, so sharing one auth.json with a
+# developer machine invalidates whichever copy refreshes second, and analysis
+# then fails with "OAuth refresh failed for openai-codex".
+#
+# The selected runner must have Node.js support plus gh, fd, and ripgrep. GitHub
+# hosted runners are bootstrapped below; future self-hosted aliases should have
+# those dependencies preinstalled or installable by the setup steps.
+#
+# The session runs in a high-entropy checkout directory so the recorded cwd is
+# a unique string. Import the session into a local checkout with the
+# /ir extension command (.pi/extensions/import-repro.ts):
+#   pi "/ir <gist-id | gist-url | pi.dev/session URL>"
+
+name: Issue Analysis
+
+on:
+  issues:
+    types: [labeled]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: issue-analysis-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  authorize:
+    runs-on: ubuntu-latest
+    outputs:
+      should_run: ${{ steps.verify.outputs.should_run }}
+      extra_instructions: ${{ steps.verify.outputs.extra_instructions }}
+      runs_on: ${{ steps.verify.outputs.runs_on }}
+      runner_os: ${{ steps.verify.outputs.runner_os }}
+      runner_profile: ${{ steps.verify.outputs.runner_profile }}
+    steps:
+      - name: Verify sender permission
+        id: verify
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          ORG_READ_TOKEN: ${{ secrets.EARENDIL_ORG_READ_TOKEN }}
+        with:
+          script: |
+            const ANALYZE_LABEL = 'pi-analyze';
+            const TRIGGER_RE = /@issuron\s+analyze\b/i;
+            const RUN_ON_TAG_RE = /#run-on-([a-z0-9][a-z0-9_-]*)\b/gi;
+            const RUNNER_PROFILES = {
+              linux: { runsOn: 'ubuntu-latest', os: 'linux' },
+              windows: { runsOn: 'windows-latest', os: 'windows' },
+              mac: { runsOn: 'macos-latest', os: 'macos' },
+            };
+            const RUN_ON_ALIASES = {
+              linux: 'linux',
+              ubuntu: 'linux',
+              'ubuntu-latest': 'linux',
+              windows: 'windows',
+              win: 'windows',
+              'windows-latest': 'windows',
+              mac: 'mac',
+              macos: 'mac',
+              darwin: 'mac',
+              'macos-latest': 'mac',
+            };
+
+            const username = context.payload.sender.login;
+            let extraInstructions = '';
+            let runnerProfile = 'linux';
+
+            core.setOutput('should_run', 'false');
+            core.setOutput('extra_instructions', '');
+            core.setOutput('runs_on', JSON.stringify(RUNNER_PROFILES.linux.runsOn));
+            core.setOutput('runner_os', RUNNER_PROFILES.linux.os);
+            core.setOutput('runner_profile', runnerProfile);
+
+            if (context.eventName === 'issues') {
+              if (context.payload.action !== 'labeled' || context.payload.label?.name !== ANALYZE_LABEL) {
+                console.log('Not a pi-analyze label event');
+                return;
+              }
+            } else if (context.eventName === 'issue_comment') {
+              if (context.payload.issue.pull_request) {
+                console.log('Ignoring pull request comment');
+                return;
+              }
+              const body = context.payload.comment.body || '';
+              if (!TRIGGER_RE.test(body)) {
+                console.log('Comment does not contain an @issuron analyze trigger');
+                return;
+              }
+
+              const resolvedProfiles = new Set();
+              const unknownTags = [];
+              for (const match of body.matchAll(RUN_ON_TAG_RE)) {
+                const tag = match[1].toLowerCase();
+                const resolved = RUN_ON_ALIASES[tag];
+                if (!resolved) {
+                  unknownTags.push(tag);
+                } else {
+                  resolvedProfiles.add(resolved);
+                }
+              }
+
+              if (unknownTags.length > 0) {
+                core.setFailed(`Unknown issue analysis runner tag(s): ${unknownTags.map((tag) => `#run-on-${tag}`).join(', ')}`);
+                return;
+              }
+              if (resolvedProfiles.size > 1) {
+                core.setFailed(
+                  `Conflicting issue analysis runner tags: ${Array.from(resolvedProfiles)
+                    .map((profile) => `#run-on-${profile}`)
+                    .join(', ')}`,
+                );
+                return;
+              }
+
+              runnerProfile = Array.from(resolvedProfiles)[0] || 'linux';
+              extraInstructions = body.replace(TRIGGER_RE, ' ').replace(RUN_ON_TAG_RE, ' ').trim();
+            } else {
+              console.log(`Unsupported event: ${context.eventName}`);
+              return;
+            }
+
+            async function removeTriggerLabel() {
+              if (context.eventName !== 'issues') return;
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  name: ANALYZE_LABEL,
+                });
+              } catch (error) {
+                if (error.status !== 404) throw error;
+              }
+            }
+
+            if (!process.env.ORG_READ_TOKEN) {
+              await removeTriggerLabel();
+              core.setFailed('EARENDIL_ORG_READ_TOKEN is not configured; refusing to run issue analysis.');
+              return;
+            }
+
+            try {
+              const response = await fetch(
+                `https://api.github.com/orgs/earendil-works/teams/staff/memberships/${encodeURIComponent(username)}`,
+                {
+                  headers: {
+                    Accept: 'application/vnd.github+json',
+                    Authorization: `Bearer ${process.env.ORG_READ_TOKEN}`,
+                    'X-GitHub-Api-Version': '2022-11-28',
+                  },
+                },
+              );
+
+              if (response.status === 404) {
+                await removeTriggerLabel();
+                core.setFailed(`@${username} is not an active earendil-works/staff member.`);
+                return;
+              }
+
+              if (!response.ok) {
+                const body = await response.text();
+                await removeTriggerLabel();
+                core.setFailed(
+                  `Could not verify earendil-works/staff membership for @${username}: HTTP ${response.status} ${body}`,
+                );
+                return;
+              }
+
+              const membership = await response.json();
+              if (membership.state !== 'active') {
+                await removeTriggerLabel();
+                core.setFailed(`@${username} is not an active earendil-works/staff member.`);
+                return;
+              }
+              console.log(`earendil-works/staff membership for @${username}: ${membership.state}`);
+            } catch (error) {
+              await removeTriggerLabel();
+              core.setFailed(
+                `Could not verify earendil-works/staff membership for @${username}: ${
+                  error instanceof Error ? error.message : String(error)
+                }`,
+              );
+              return;
+            }
+
+            const { data } = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username,
+            });
+            if (!['admin', 'write'].includes(data.permission)) {
+              await removeTriggerLabel();
+              core.setFailed(
+                `@${username} has '${data.permission}' permission; write or admin is required to trigger issue analysis.`,
+              );
+              return;
+            }
+
+            if (context.eventName === 'issue_comment') {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                labels: [ANALYZE_LABEL],
+              });
+            }
+
+            const profile = RUNNER_PROFILES[runnerProfile];
+            console.log(`Selected issue analysis runner profile: ${runnerProfile} (${JSON.stringify(profile.runsOn)})`);
+            core.setOutput('should_run', 'true');
+            core.setOutput('extra_instructions', extraInstructions);
+            core.setOutput('runs_on', JSON.stringify(profile.runsOn));
+            core.setOutput('runner_os', profile.os);
+            core.setOutput('runner_profile', runnerProfile);
+
+  analyze:
+    needs: authorize
+    if: needs.authorize.outputs.should_run == 'true'
+    runs-on: ${{ fromJSON(needs.authorize.outputs.runs_on) }}
+    environment: pi-analyze
+    timeout-minutes: 45
+    concurrency:
+      group: issue-analysis-pi-auth
+      cancel-in-progress: false
+    env:
+      ISSUE_ANALYSIS_MODEL: openai-codex/gpt-5.5
+      ISSUE_ANALYSIS_THINKING: high
+    steps:
+      - name: Create high-entropy working directory name
+        id: workdir
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const crypto = require('crypto');
+            core.setOutput('name', `pi-ci-${crypto.randomBytes(16).toString('hex')}`);
+
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: ${{ steps.workdir.outputs.name }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: ${{ steps.workdir.outputs.name }}/package-lock.json
+
+      - name: Install system dependencies (Linux)
+        if: needs.authorize.outputs.runner_os == 'linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y fd-find ripgrep
+          sudo ln -sf "$(which fdfind)" /usr/local/bin/fd
+
+      - name: Install system dependencies (macOS)
+        if: needs.authorize.outputs.runner_os == 'macos'
+        run: |
+          if ! command -v fd >/dev/null 2>&1; then
+            brew install fd
+          fi
+          if ! command -v rg >/dev/null 2>&1; then
+            brew install ripgrep
+          fi
+
+      - name: Install system dependencies (Windows)
+        if: needs.authorize.outputs.runner_os == 'windows'
+        shell: pwsh
+        run: |
+          $packages = @()
+          if (-not (Get-Command fd -ErrorAction SilentlyContinue)) {
+            $packages += "fd"
+          }
+          if (-not (Get-Command rg -ErrorAction SilentlyContinue)) {
+            $packages += "ripgrep"
+          }
+          if ($packages.Count -gt 0) {
+            if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
+              throw "fd and ripgrep must be installed on Windows runners, or Chocolatey must be available to install them."
+            }
+            choco install $packages -y --no-progress
+          }
+          fd --version
+          rg --version
+
+      - name: Install dependencies
+        working-directory: ${{ steps.workdir.outputs.name }}
+        run: npm ci --ignore-scripts
+
+      - name: Build
+        working-directory: ${{ steps.workdir.outputs.name }}
+        run: npm run build
+
+      - name: Write auth.json
+        id: write_auth
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PI_AUTH_JSON: ${{ secrets.PI_AUTH_JSON }}
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const authJson = process.env.PI_AUTH_JSON;
+            if (!authJson) {
+              throw new Error('PI_AUTH_JSON secret is not configured for the pi-analyze environment');
+            }
+
+            const agentDir = path.join(process.env.RUNNER_TEMP, 'pi-agent');
+            fs.mkdirSync(agentDir, { recursive: true });
+            const authPath = path.join(agentDir, 'auth.json');
+            fs.writeFileSync(authPath, authJson, { mode: 0o600 });
+            if (process.platform !== 'win32') {
+              fs.chmodSync(authPath, 0o600);
+            }
+
+      - name: Run pi /is
+        id: run_pi
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PI_CODING_AGENT_DIR: ${{ runner.temp }}/pi-agent
+          GH_TOKEN: ${{ github.token }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+          EXTRA_INSTRUCTIONS: ${{ needs.authorize.outputs.extra_instructions }}
+          WORKDIR: ${{ steps.workdir.outputs.name }}
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const { spawn } = require('child_process');
+
+            const workdir = path.join(process.env.GITHUB_WORKSPACE, process.env.WORKDIR);
+            const outDir = path.join(process.env.RUNNER_TEMP, 'pi-out');
+            const sessionDir = path.join(outDir, 'session');
+            fs.mkdirSync(sessionDir, { recursive: true });
+
+            let prompt = `/is ${process.env.ISSUE_URL}`;
+            if (process.env.EXTRA_INSTRUCTIONS) {
+              prompt += '\n\nAdditional instructions from @issuron analyze comment:\n';
+              prompt += process.env.EXTRA_INSTRUCTIONS;
+            }
+
+            const outputPath = path.join(outDir, 'output.md');
+            const output = fs.createWriteStream(outputPath);
+            const args = [
+              'packages/coding-agent/src/cli.ts',
+              '-p',
+              '--approve',
+              '--session-dir',
+              sessionDir,
+              '--model',
+              process.env.ISSUE_ANALYSIS_MODEL,
+              '--thinking',
+              process.env.ISSUE_ANALYSIS_THINKING,
+              prompt,
+            ];
+
+            const exitCode = await new Promise((resolve, reject) => {
+              const child = spawn('node', args, {
+                cwd: workdir,
+                env: process.env,
+                stdio: ['ignore', 'pipe', 'pipe'],
+              });
+              child.stdout.on('data', (chunk) => {
+                process.stdout.write(chunk);
+                output.write(chunk);
+              });
+              child.stderr.on('data', (chunk) => {
+                process.stderr.write(chunk);
+              });
+              child.on('error', reject);
+              child.on('close', resolve);
+            });
+            await new Promise((resolve) => output.end(resolve));
+
+            if (exitCode !== 0) {
+              throw new Error(`pi /is failed with exit code ${exitCode}`);
+            }
+
+      - name: Persist refreshed auth.json
+        if: always() && steps.write_auth.outcome == 'success'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_TOKEN: ${{ secrets.PI_AUTH_UPDATE_TOKEN }}
+          PI_AUTH_JSON: ${{ secrets.PI_AUTH_JSON }}
+          PI_CODING_AGENT_DIR: ${{ runner.temp }}/pi-agent
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const { spawn } = require('child_process');
+
+            if (!process.env.GH_TOKEN) {
+              throw new Error('PI_AUTH_UPDATE_TOKEN is not configured for the pi-analyze environment');
+            }
+
+            const authPath = path.join(process.env.PI_CODING_AGENT_DIR, 'auth.json');
+            if (!fs.existsSync(authPath)) {
+              core.warning('auth.json was not created; skipping auth persistence');
+              return;
+            }
+
+            const authJson = fs.readFileSync(authPath, 'utf8');
+            let parsed;
+            try {
+              parsed = JSON.parse(authJson);
+            } catch (error) {
+              throw new Error(`Refusing to persist malformed auth.json: ${error instanceof Error ? error.message : String(error)}`);
+            }
+
+            const codexAuth = parsed['openai-codex'];
+            if (codexAuth?.type !== 'oauth' || typeof codexAuth.refresh !== 'string' || codexAuth.refresh.length === 0) {
+              throw new Error('Refusing to persist auth.json without openai-codex OAuth refresh credentials');
+            }
+
+            if (authJson === process.env.PI_AUTH_JSON) {
+              console.log('auth.json is unchanged; skipping secret update');
+              return;
+            }
+
+            await new Promise((resolve, reject) => {
+              const child = spawn(
+                'gh',
+                ['secret', 'set', 'PI_AUTH_JSON', '--env', 'pi-analyze', '--repo', process.env.GITHUB_REPOSITORY],
+                { env: process.env, stdio: ['pipe', 'inherit', 'pipe'] },
+              );
+              const stderrChunks = [];
+              child.stderr.on('data', (chunk) => {
+                stderrChunks.push(chunk);
+                process.stderr.write(chunk);
+              });
+              child.on('error', reject);
+              child.on('close', (code) => {
+                if (code === 0) {
+                  resolve();
+                  return;
+                }
+                const details = Buffer.concat(stderrChunks).toString().trim();
+                reject(
+                  new Error(
+                    `gh secret set failed with exit code ${code}${details ? `: ${details}` : ''}. ` +
+                      'PI_AUTH_UPDATE_TOKEN needs repository permission "Environments: read and write" on this repo.',
+                  ),
+                );
+              });
+              child.stdin.end(authJson);
+            });
+
+      - name: Export session files
+        id: export_session_files
+        if: always()
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PI_CODING_AGENT_DIR: ${{ runner.temp }}/pi-agent
+          WORKDIR: ${{ steps.workdir.outputs.name }}
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const { spawn } = require('child_process');
+
+            function findFirstJsonl(dir) {
+              if (!fs.existsSync(dir)) return undefined;
+              const entries = fs.readdirSync(dir, { withFileTypes: true });
+              for (const entry of entries) {
+                const entryPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                  const nested = findFirstJsonl(entryPath);
+                  if (nested) return nested;
+                } else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+                  return entryPath;
+                }
+              }
+              return undefined;
+            }
+
+            const outDir = path.join(process.env.RUNNER_TEMP, 'pi-out');
+            const sessionFile = findFirstJsonl(path.join(outDir, 'session'));
+            if (!sessionFile) {
+              throw new Error('No session jsonl file found');
+            }
+
+            const sessionJsonl = path.join(outDir, 'session.jsonl');
+            const sessionHtml = path.join(outDir, 'session.html');
+            fs.copyFileSync(sessionFile, sessionJsonl);
+
+            const workdir = path.join(process.env.GITHUB_WORKSPACE, process.env.WORKDIR);
+            const exitCode = await new Promise((resolve, reject) => {
+              const child = spawn(
+                'node',
+                ['packages/coding-agent/src/cli.ts', '--no-extensions', '--export', sessionJsonl, sessionHtml],
+                { cwd: workdir, env: process.env, stdio: 'inherit' },
+              );
+              child.on('error', reject);
+              child.on('close', resolve);
+            });
+            if (exitCode !== 0) {
+              throw new Error(`session export failed with exit code ${exitCode}`);
+            }
+
+      - name: Upload session gist
+        id: gist
+        if: always() && steps.export_session_files.outcome == 'success'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PI_GIST_TOKEN: ${{ secrets.PI_GIST_TOKEN }}
+        with:
+          github-token: ${{ secrets.PI_GIST_TOKEN }}
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            if (!process.env.PI_GIST_TOKEN) {
+              throw new Error('PI_GIST_TOKEN is not configured');
+            }
+
+            const outDir = path.join(process.env.RUNNER_TEMP, 'pi-out');
+            const files = {};
+            for (const filename of ['session.html', 'session.jsonl']) {
+              files[filename] = { content: fs.readFileSync(path.join(outDir, filename), 'utf8') };
+            }
+
+            const response = await github.rest.gists.create({
+              public: false,
+              files,
+            });
+            const gistUrl = response.data.html_url;
+            const gistId = response.data.id;
+            core.setOutput('url', gistUrl);
+            core.setOutput('id', gistId);
+            core.setOutput('share_url', `https://pi.dev/session/#${gistId}`);
+
+      - name: Comment with session import instructions
+        if: always() && steps.run_pi.outcome == 'success' && steps.gist.outcome == 'success'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GIST_URL: ${{ steps.gist.outputs.url }}
+          GIST_ID: ${{ steps.gist.outputs.id }}
+          SHARE_URL: ${{ steps.gist.outputs.share_url }}
+          SESSION_JSONL: ${{ runner.temp }}/pi-out/session.jsonl
+        with:
+          script: |
+            const fs = require('fs');
+
+            function extractLastAgentMessage(sessionPath) {
+              const lines = fs.readFileSync(sessionPath, 'utf8').split(/\r?\n/).filter(Boolean);
+              let lastText = '';
+
+              for (const line of lines) {
+                let entry;
+                try {
+                  entry = JSON.parse(line);
+                } catch {
+                  continue;
+                }
+
+                if (entry.type !== 'message' || entry.message?.role !== 'assistant') continue;
+
+                const content = entry.message.content;
+                const parts = [];
+                if (typeof content === 'string') {
+                  parts.push(content);
+                } else if (Array.isArray(content)) {
+                  for (const block of content) {
+                    if (block?.type === 'text' && typeof block.text === 'string') {
+                      parts.push(block.text);
+                    }
+                  }
+                }
+
+                const text = parts.join('\n\n').trim();
+                if (text) lastText = text;
+              }
+
+              if (!lastText) return '_No assistant output found._';
+              const maxLength = 55000;
+              if (lastText.length <= maxLength) return lastText;
+              return `${lastText.slice(0, maxLength)}\n\n_[truncated]_`;
+            }
+
+            const gistUrl = process.env.GIST_URL;
+            const gistId = process.env.GIST_ID;
+            const shareUrl = process.env.SHARE_URL;
+            const lastAgentMessage = extractLastAgentMessage(process.env.SESSION_JSONL);
+            const body = [
+              'Pi issue analysis finished.',
+              '',
+              `Share URL: ${shareUrl}`,
+              `Gist: ${gistUrl}`,
+              '',
+              'Continue locally from a checkout with:',
+              '',
+              '```sh',
+              `pi "/ir ${gistId}"`,
+              '```',
+              '',
+              '<details>',
+              '<summary>Agent analysis summary</summary>',
+              '',
+              lastAgentMessage,
+              '',
+              '</details>',
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body,
+            });
+
+      - name: Comment on analysis failure
+        if: always() && steps.run_pi.outcome == 'failure'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GIST_URL: ${{ steps.gist.outputs.url }}
+          SHARE_URL: ${{ steps.gist.outputs.share_url }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        with:
+          script: |
+            const lines = ['Pi issue analysis failed; no analysis was produced.', '', `Run: ${process.env.RUN_URL}`];
+            if (process.env.SHARE_URL) {
+              lines.push(`Partial session: ${process.env.SHARE_URL}`);
+            }
+            if (process.env.GIST_URL) {
+              lines.push(`Gist: ${process.env.GIST_URL}`);
+            }
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: lines.join('\n'),
+            });
+
+      - name: Remove trigger label
+        if: always()
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            try {
+              await github.rest.issues.removeLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                name: 'pi-analyze',
+              });
+            } catch (error) {
+              if (error.status !== 404) throw error;
+            }

.github/workflows/issue-gate.yml

@@ -0,0 +1,129 @@
+name: Issue Gate
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  check-contributor:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Check issue author
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const APPROVED_FILE = '.github/APPROVED_CONTRIBUTORS';
+            const VALID_CAPABILITIES = new Set(['issue', 'pr']);
+            const TRUSTED_BOT_AUTHORS = new Set(['dependabot[bot]', 'sentry[bot]', 'claude[bot]']);
+            const issueAuthor = context.payload.issue.user.login;
+            const defaultBranch = context.payload.repository.default_branch;
+            const isBotAuthor = issueAuthor.endsWith('[bot]');
+
+            if (TRUSTED_BOT_AUTHORS.has(issueAuthor)) {
+              console.log(`Skipping trusted bot: ${issueAuthor}`);
+              return;
+            }
+
+            async function getPermission(username) {
+              try {
+                const { data: permissionLevel } = await github.rest.repos.getCollaboratorPermissionLevel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  username,
+                });
+                return permissionLevel.permission;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getTextFile(path) {
+              const { data: fileContent } = await github.rest.repos.getContent({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                path,
+                ref: defaultBranch,
+              });
+
+              if (!('content' in fileContent) || typeof fileContent.content !== 'string') {
+                throw new Error(`Expected file content for ${path}`);
+              }
+
+              return Buffer.from(fileContent.content, 'base64').toString('utf8');
+            }
+
+            function parseApprovedUsers(content) {
+              const users = new Map();
+
+              for (const rawLine of content.split('\n')) {
+                const line = rawLine.trim();
+                if (!line || line.startsWith('#')) continue;
+
+                const parts = line.split(/\s+/);
+                if (parts.length !== 2) {
+                  console.log(`Skipping malformed line: ${rawLine}`);
+                  continue;
+                }
+
+                const [username, capability] = parts;
+                const normalizedCapability = capability.toLowerCase();
+                if (!VALID_CAPABILITIES.has(normalizedCapability)) {
+                  console.log(`Skipping line with invalid capability: ${rawLine}`);
+                  continue;
+                }
+
+                users.set(username.toLowerCase(), normalizedCapability);
+              }
+
+              return users;
+            }
+
+            const permission = await getPermission(issueAuthor);
+            if (!isBotAuthor && ['admin', 'maintain', 'write'].includes(permission)) {
+              console.log(`${issueAuthor} is a collaborator with ${permission} access`);
+              return;
+            }
+
+            const approvedContent = await getTextFile(APPROVED_FILE);
+            const approvedUsers = parseApprovedUsers(approvedContent);
+            const capability = approvedUsers.get(issueAuthor.toLowerCase());
+
+            if (!isBotAuthor && (capability === 'issue' || capability === 'pr')) {
+              console.log(`${issueAuthor} is approved for ${capability}`);
+              return;
+            }
+
+            const message = [
+              'This issue was auto-closed. All issues from new contributors are auto-closed by default.',
+              '',
+              `Maintainers review auto-closed issues daily and reopen worthwhile ones. Issues that do not meet the quality bar in [CONTRIBUTING.md](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/${defaultBranch}/CONTRIBUTING.md) will not be reopened or receive a reply.`,
+              '',
+              'If a maintainer replies `lgtmi` on one of your issues, your future issues will stay open. If a maintainer replies `lgtm`, your future issues and PRs will stay open. The command must be at the start of the reply (optionally after one or more `@username` mentions) or at the end.',
+              '',
+              `See [CONTRIBUTING.md](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/${defaultBranch}/CONTRIBUTING.md).`,
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: message,
+            });
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['untriaged'],
+            });
+
+            await github.rest.issues.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              state: 'closed',
+              state_reason: 'not_planned',
+            });

.github/workflows/issue-triage-labels.yml

@@ -0,0 +1,142 @@
+name: Issue Triage Labels
+
+on:
+  issues:
+    types: [reopened, labeled]
+
+jobs:
+  update-labels:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Update triage labels
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const UNTRIAGED_LABEL = 'untriaged';
+            const NO_ACTION_LABEL = 'no-action';
+            const LAST_READ_LABEL = 'last-read';
+            const TO_DISCUSS_LABEL = 'to-discuss';
+            const INPROGRESS_LABEL = 'inprogress';
+
+            function issueHasLabel(issue, labelName) {
+              return (issue.labels ?? []).some((label) => label.name === labelName);
+            }
+
+            async function removeLabelIfPresent(issueNumber, issue, labelName) {
+              if (!issueHasLabel(issue, labelName)) {
+                console.log(`Issue #${issueNumber} does not have ${labelName}`);
+                return;
+              }
+
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issueNumber,
+                  name: labelName,
+                });
+                console.log(`Removed ${labelName} from #${issueNumber}`);
+              } catch (error) {
+                if (error.status === 404) {
+                  console.log(`Label ${labelName} was already absent from #${issueNumber}`);
+                  return;
+                }
+                throw error;
+              }
+            }
+
+            if (context.payload.action === 'reopened') {
+              await removeLabelIfPresent(context.issue.number, context.payload.issue, UNTRIAGED_LABEL);
+              await removeLabelIfPresent(context.issue.number, context.payload.issue, NO_ACTION_LABEL);
+              return;
+            }
+
+            if (context.payload.action === 'labeled' && context.payload.label?.name === NO_ACTION_LABEL) {
+              await removeLabelIfPresent(context.issue.number, context.payload.issue, UNTRIAGED_LABEL);
+              return;
+            }
+
+            if (context.payload.action !== 'labeled' || context.payload.label?.name !== LAST_READ_LABEL) {
+              console.log('Not a last-read label event');
+              return;
+            }
+
+            const currentIssueNumber = context.issue.number;
+            const lastReadIssues = await github.paginate(github.rest.issues.listForRepo, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'all',
+              labels: LAST_READ_LABEL,
+              per_page: 100,
+            });
+
+            const previousIssueNumbers = lastReadIssues
+              .filter((issue) => !issue.pull_request)
+              .map((issue) => issue.number)
+              .filter((issueNumber) => issueNumber !== currentIssueNumber);
+
+            if (previousIssueNumbers.length === 0) {
+              console.log('No previous last-read issue found');
+              return;
+            }
+
+            const previousIssueNumber = Math.max(...previousIssueNumbers);
+            if (currentIssueNumber <= previousIssueNumber) {
+              console.log(
+                `Last-read was added to old issue #${currentIssueNumber}; latest last-read is #${previousIssueNumber}`,
+              );
+              return;
+            }
+
+            const untriagedIssues = await github.paginate(github.rest.issues.listForRepo, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'all',
+              labels: UNTRIAGED_LABEL,
+              per_page: 100,
+            });
+
+            const issuesToMark = untriagedIssues
+              .filter((issue) => !issue.pull_request)
+              .filter((issue) => issue.number >= previousIssueNumber && issue.number <= currentIssueNumber)
+              .sort((a, b) => a.number - b.number);
+
+            if (issuesToMark.length === 0) {
+              console.log(`No untriaged issues found from #${previousIssueNumber} to #${currentIssueNumber}`);
+              return;
+            }
+
+            for (const issue of issuesToMark) {
+              if (issueHasLabel(issue, TO_DISCUSS_LABEL)) {
+                console.log(`Skipped ${NO_ACTION_LABEL} for #${issue.number} because it has ${TO_DISCUSS_LABEL}`);
+              } else {
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issue.number,
+                  labels: [NO_ACTION_LABEL],
+                });
+                console.log(`Added ${NO_ACTION_LABEL} to #${issue.number}`);
+              }
+
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                state: 'closed',
+                state_reason: 'not_planned',
+              });
+              console.log(`Closed #${issue.number} as not planned`);
+
+              await removeLabelIfPresent(issue.number, issue, INPROGRESS_LABEL);
+
+              await github.rest.issues.removeLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                name: UNTRIAGED_LABEL,
+              });
+              console.log(`Removed ${UNTRIAGED_LABEL} from #${issue.number}`);
+            }

.github/workflows/npm-audit.yml

@@ -0,0 +1,31 @@
+name: npm audit
+
+on:
+  schedule:
+    - cron: '37 7 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies without lifecycle scripts
+        run: npm ci --ignore-scripts --no-audit --no-fund
+
+      - name: Audit production vulnerabilities
+        run: npm audit --omit=dev --audit-level=moderate
+
+      - name: Verify registry signatures
+        run: npm audit signatures --omit=dev

.github/workflows/pr-gate.yml

@@ -0,0 +1,128 @@
+name: PR Gate
+
+on:
+  pull_request_target:
+    types: [opened]
+
+jobs:
+  check-contributor:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Check if contributor is approved
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const APPROVED_FILE = '.github/APPROVED_CONTRIBUTORS';
+            const VALID_CAPABILITIES = new Set(['issue', 'pr']);
+            const TRUSTED_BOT_AUTHORS = new Set(['dependabot[bot]', 'sentry[bot]', 'claude[bot]']);
+            const prAuthor = context.payload.pull_request.user.login;
+            const defaultBranch = context.payload.repository.default_branch;
+            const isBotAuthor = prAuthor.endsWith('[bot]');
+
+            if (TRUSTED_BOT_AUTHORS.has(prAuthor)) {
+              console.log(`Skipping trusted bot: ${prAuthor}`);
+              return;
+            }
+
+            async function getPermission(username) {
+              try {
+                const { data: permissionLevel } = await github.rest.repos.getCollaboratorPermissionLevel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  username,
+                });
+                return permissionLevel.permission;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getTextFile(path) {
+              const { data: fileContent } = await github.rest.repos.getContent({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                path,
+                ref: defaultBranch,
+              });
+
+              if (!('content' in fileContent) || typeof fileContent.content !== 'string') {
+                throw new Error(`Expected file content for ${path}`);
+              }
+
+              return Buffer.from(fileContent.content, 'base64').toString('utf8');
+            }
+
+            function parseApprovedUsers(content) {
+              const users = new Map();
+
+              for (const rawLine of content.split('\n')) {
+                const line = rawLine.trim();
+                if (!line || line.startsWith('#')) continue;
+
+                const parts = line.split(/\s+/);
+                if (parts.length !== 2) {
+                  console.log(`Skipping malformed line: ${rawLine}`);
+                  continue;
+                }
+
+                const [username, capability] = parts;
+                const normalizedCapability = capability.toLowerCase();
+                if (!VALID_CAPABILITIES.has(normalizedCapability)) {
+                  console.log(`Skipping line with invalid capability: ${rawLine}`);
+                  continue;
+                }
+
+                users.set(username.toLowerCase(), normalizedCapability);
+              }
+
+              return users;
+            }
+
+            async function closePullRequest(message) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.payload.pull_request.number,
+                body: message,
+              });
+
+              await github.rest.pulls.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.pull_request.number,
+                state: 'closed',
+              });
+            }
+
+            const permission = await getPermission(prAuthor);
+            if (!isBotAuthor && ['admin', 'maintain', 'write'].includes(permission)) {
+              console.log(`${prAuthor} is a collaborator with ${permission} access`);
+              return;
+            }
+
+            const approvedContent = await getTextFile(APPROVED_FILE);
+            const approvedUsers = parseApprovedUsers(approvedContent);
+            const capability = approvedUsers.get(prAuthor.toLowerCase());
+
+            if (!isBotAuthor && capability === 'pr') {
+              console.log(`${prAuthor} is approved for PRs`);
+              return;
+            }
+
+            console.log(`${prAuthor} is not approved, closing PR`);
+
+            const message = [
+              'This PR was auto-closed. Only contributors approved with `lgtm` can open PRs. Open an issue first and ask a maintainer for approval.',
+              '',
+              `Maintainers review auto-closed issues daily. Issues that do not meet the quality bar in [CONTRIBUTING.md](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/${defaultBranch}/CONTRIBUTING.md) will not be reopened or receive a reply.`,
+              '',
+              'If a maintainer replies `lgtmi`, your future issues will stay open. If a maintainer replies `lgtm`, your future issues and PRs will stay open. The command must be at the start of the reply (optionally after one or more `@username` mentions) or at the end.',
+              '',
+              `See [CONTRIBUTING.md](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/${defaultBranch}/CONTRIBUTING.md).`,
+            ].join('\n');
+
+            await closePullRequest(message);

.github/workflows/publish-model-catalog.yml

@@ -0,0 +1,146 @@
+name: Publish Model Catalog
+
+on:
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+  pull_request:
+    paths:
+      - '.github/workflows/publish-model-catalog.yml'
+      - '.gitignore'
+      - 'package.json'
+      - 'packages/ai/**'
+      - 'scripts/publish-model-catalog.mjs'
+  # GitHub schedules use UTC. Run hourly candidates across the CET/CEST
+  # boundaries; the publish job only uploads at 10:17, 12:17, and 14:17
+  # Europe/Vienna time.
+  schedule:
+    - cron: '17 8-13 * * 1-5'
+  workflow_dispatch:
+    inputs:
+      source_ref:
+        description: 'Commit, branch, or tag to generate from'
+        required: false
+        default: 'main'
+        type: string
+      publish:
+        description: 'Upload the generated catalog to production R2'
+        required: true
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  generate:
+    if: ${{ github.event_name != 'workflow_run' || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main') }}
+    runs-on: ubuntu-latest
+    env:
+      SOURCE_REF: ${{ github.event.workflow_run.head_sha || inputs.source_ref || github.sha }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.SOURCE_REF }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Generate model catalog JSON
+        run: npm run generate:model-catalog
+
+      - name: Validate model catalog JSON
+        run: npm run check:model-catalog
+
+      - name: Upload model catalog JSON
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: model-catalog-json
+          path: .artifacts/model-catalog
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_run' || (github.event_name == 'workflow_dispatch' && inputs.publish) }}
+    needs: generate
+    runs-on: ubuntu-latest
+    environment: pi-model-upload
+    concurrency:
+      group: publish-model-catalog-r2
+      cancel-in-progress: true
+    env:
+      SOURCE_REF: ${{ github.event.workflow_run.head_sha || inputs.source_ref || github.sha }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.PI_ARTIFACTS_R2_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.PI_ARTIFACTS_R2_SECRET_ACCESS_KEY }}
+      AWS_DEFAULT_REGION: auto
+      AWS_EC2_METADATA_DISABLED: 'true'
+      R2_ENDPOINT: https://67c0d357268b0fca6e0b465bb9d01b84.r2.cloudflarestorage.com
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.SOURCE_REF }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+
+      - name: Download model catalog JSON
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: model-catalog-json
+          path: .artifacts/model-catalog
+
+      - name: Verify AWS CLI
+        run: aws --version
+
+      - name: Check publication window
+        id: publication-window
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          MANUAL_PUBLISH: ${{ inputs.publish || false }}
+        run: |
+          set -euo pipefail
+
+          local_day="$(TZ=Europe/Vienna date +%u)"
+          local_hour_text="$(TZ=Europe/Vienna date +%H)"
+          local_hour="$((10#$local_hour_text))"
+          local_time="$(TZ=Europe/Vienna date '+%Y-%m-%d %H:%M:%S %Z')"
+          allowed=false
+          reason="outside the Monday-Friday 10:00-15:00 Europe/Vienna publication window"
+
+          if [[ "$EVENT_NAME" == "workflow_dispatch" && "$MANUAL_PUBLISH" == "true" ]]; then
+            allowed=true
+            reason="manual publication"
+          elif (( local_day <= 5 && local_hour >= 10 && local_hour < 15 )); then
+            if [[ "$EVENT_NAME" != "schedule" ]] || (( (local_hour - 10) % 2 == 0 )); then
+              allowed=true
+              reason="business-hours publication"
+            else
+              reason="not a scheduled 10:17, 12:17, or 14:17 Europe/Vienna publication"
+            fi
+          fi
+
+          echo "allowed=$allowed" >> "$GITHUB_OUTPUT"
+          echo "R2 publication allowed: $allowed ($reason; local time: $local_time)"
+
+      - name: Publish model catalog to R2
+        if: steps.publication-window.outputs.allowed == 'true'
+        run: |
+          node scripts/publish-model-catalog.mjs \
+            --input .artifacts/model-catalog \
+            --bucket pi-artifacts \
+            --endpoint "$R2_ENDPOINT" \
+            --source-commit "$(git rev-parse HEAD)"

.github/workflows/remove-inprogress-on-close.yml

@@ -0,0 +1,31 @@
+name: Remove In Progress Label On Close
+
+on:
+  issues:
+    types: [closed]
+
+jobs:
+  remove-label:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Remove inprogress label
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const labelName = 'inprogress';
+            const labels = context.payload.issue.labels ?? [];
+            const hasLabel = labels.some((label) => label.name === labelName);
+
+            if (!hasLabel) {
+              console.log(`Issue does not have ${labelName} label`);
+              return;
+            }
+
+            await github.rest.issues.removeLabel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              name: labelName,
+            });

.pi/extensions/import-repro.ts

@@ -0,0 +1,351 @@
+/**
+ * Import a pi session shared as a gist by the issue-analysis CI workflow
+ * (.github/workflows/issue-analysis.yml) and switch to it.
+ *
+ * The CI job runs in a high-entropy checkout directory; this command rewrites
+ * the recorded cwd to the local checkout, installs the session file into the
+ * current session directory, and switches to it.
+ *
+ * Usage:
+ *   /ir b4d100022aefb12f25dd2d8485e0a82a
+ *   /ir https://gist.github.com/mitsuhiko/b4d100022aefb12f25dd2d8485e0a82a
+ *   /ir https://pi.dev/session/#b4d100022aefb12f25dd2d8485e0a82a
+ *   /ir https://github.com/earendil-works/pi/issues/123
+ *
+ *   pi "/ir <gist-id>"
+ */
+
+import { Buffer } from "node:buffer";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+const GIST_ID_RE = /^[0-9a-fA-F]{20,}$/;
+const GIST_URL_RE = /^https:\/\/gist\.github\.com\/(?:[^/]+\/)?([0-9a-fA-F]{20,})(?:[/#?].*)?$/;
+const SHARE_URL_RE = /^https:\/\/pi\.dev\/session\/#([0-9a-fA-F]{20,})(?:[/#?].*)?$/;
+const ISSUE_URL_RE = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)(?:[/#?].*)?$/;
+const GIST_URL_IN_TEXT_RE = /https:\/\/gist\.github\.com\/(?:[^/\s]+\/)?([0-9a-fA-F]{20,})\b/g;
+const SESSION_DATA_RE = /<script id="session-data" type="application\/json">([^<]+)<\/script>/;
+
+interface SessionHeader {
+	type: "session";
+	id: string;
+	cwd: string;
+	[key: string]: unknown;
+}
+
+interface ExportedSessionData {
+	header: SessionHeader | null;
+	entries: Array<Record<string, unknown>>;
+}
+
+interface GistFile {
+	filename?: string;
+	raw_url?: string;
+	content?: string;
+	truncated?: boolean;
+}
+
+interface GistResponse {
+	files?: Record<string, GistFile>;
+}
+
+interface IssueComment {
+	body?: string | null;
+	user?: { login?: string } | null;
+}
+
+function parseRef(
+	ref: string,
+	cwd: string,
+): { type: "gist"; id: string } | { type: "file"; path: string } | { type: "issue"; owner: string; repo: string; issue: string } {
+	if (ref.endsWith(".html") || ref.endsWith(".jsonl")) {
+		return { type: "file", path: isAbsolute(ref) ? ref : resolve(cwd, ref) };
+	}
+
+	const shareMatch = ref.match(SHARE_URL_RE);
+	if (shareMatch) return { type: "gist", id: shareMatch[1] };
+
+	const gistMatch = ref.match(GIST_URL_RE);
+	if (gistMatch) return { type: "gist", id: gistMatch[1] };
+
+	const issueMatch = ref.match(ISSUE_URL_RE);
+	if (issueMatch) return { type: "issue", owner: issueMatch[1], repo: issueMatch[2], issue: issueMatch[3] };
+
+	if (GIST_ID_RE.test(ref)) return { type: "gist", id: ref };
+
+	throw new Error(`expected a gist ID, gist URL, pi.dev share URL, issue URL, .html file, or .jsonl file: ${ref}`);
+}
+
+function parseSessionJsonl(raw: string): { header: SessionHeader; jsonl: string } {
+	const newlineIndex = raw.indexOf("\n");
+	const firstLine = newlineIndex === -1 ? raw : raw.slice(0, newlineIndex);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(firstLine);
+	} catch {
+		throw new Error("first line of session file is not valid JSON");
+	}
+	const header = parsed as Partial<SessionHeader>;
+	if (header.type !== "session" || typeof header.id !== "string" || typeof header.cwd !== "string" || header.cwd === "") {
+		throw new Error("session file has no valid session header with a cwd");
+	}
+	return { header: header as SessionHeader, jsonl: raw };
+}
+
+function decodeExportedHtml(html: string): { header: SessionHeader; jsonl: string } {
+	const match = html.match(SESSION_DATA_RE);
+	if (!match) throw new Error("HTML does not contain embedded pi session data");
+
+	let data: unknown;
+	try {
+		data = JSON.parse(Buffer.from(match[1], "base64").toString("utf8"));
+	} catch {
+		throw new Error("embedded pi session data is not valid JSON");
+	}
+
+	const sessionData = data as Partial<ExportedSessionData>;
+	const header = sessionData.header;
+	if (!header || header.type !== "session" || typeof header.id !== "string" || typeof header.cwd !== "string") {
+		throw new Error("embedded pi session data has no valid session header");
+	}
+	if (!Array.isArray(sessionData.entries)) {
+		throw new Error("embedded pi session data has no entries array");
+	}
+
+	const lines = [header, ...sessionData.entries].map((entry) => JSON.stringify(entry));
+	return { header, jsonl: `${lines.join("\n")}\n` };
+}
+
+type SessionPlatform = "windows" | "unix" | "unknown";
+
+function escapeJsonString(value: string): string {
+	return JSON.stringify(value).slice(1, -1);
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function trimTrailingPathSeparators(value: string): string {
+	return value.replace(/[\\/]+$/, "");
+}
+
+function getPathTailName(value: string): string {
+	const trimmed = trimTrailingPathSeparators(value);
+	return trimmed.split(/[\\/]/).filter(Boolean).at(-1) ?? "";
+}
+
+function getWindowsDrivePathParts(value: string): { drive: string; rest: string } | undefined {
+	const trimmed = trimTrailingPathSeparators(value);
+	const driveMatch = trimmed.match(/^([A-Za-z]):[\\/](.*)$/);
+	if (driveMatch) {
+		return { drive: driveMatch[1].toUpperCase(), rest: driveMatch[2].replace(/[\\/]+/g, "/") };
+	}
+
+	const msysMatch = trimmed.match(/^\/([A-Za-z])\/(.*)$/);
+	if (msysMatch) {
+		return { drive: msysMatch[1].toUpperCase(), rest: msysMatch[2].replace(/[\\/]+/g, "/") };
+	}
+
+	return undefined;
+}
+
+function getCwdRewriteVariants(sourceCwd: string): string[] {
+	const trimmed = trimTrailingPathSeparators(sourceCwd);
+	const variants = new Set<string>();
+	if (trimmed) variants.add(trimmed);
+
+	const driveParts = getWindowsDrivePathParts(trimmed);
+	if (driveParts) {
+		const rest = driveParts.rest.replace(/^\/+|\/+$/g, "");
+		const backslashRest = rest.replace(/\//g, "\\");
+		variants.add(`${driveParts.drive}:\\${backslashRest}`);
+		variants.add(`${driveParts.drive}:/${rest}`);
+		variants.add(`/${driveParts.drive.toLowerCase()}/${rest}`);
+		variants.add(`/${driveParts.drive}/${rest}`);
+	}
+
+	return Array.from(variants).filter(Boolean).sort((a, b) => b.length - a.length);
+}
+
+function getCiWorkdirName(sourceCwd: string): string | undefined {
+	const name = getPathTailName(sourceCwd);
+	return /^pi-ci-[0-9a-f]{32}$/i.test(name) ? name : undefined;
+}
+
+function detectSessionPlatform(cwd: string): SessionPlatform {
+	if (/^[A-Za-z]:[\\/]/.test(cwd) || /^\/[A-Za-z]\//.test(cwd)) return "windows";
+	if (cwd.startsWith("/")) return "unix";
+	return "unknown";
+}
+
+function getLocalPlatform(): Exclude<SessionPlatform, "unknown"> {
+	return process.platform === "win32" ? "windows" : "unix";
+}
+
+function getPlatformContinuationNotice(sourceCwd: string): string | undefined {
+	const sourcePlatform = detectSessionPlatform(sourceCwd);
+	const localPlatform = getLocalPlatform();
+	if (sourcePlatform === "unknown" || sourcePlatform === localPlatform) return undefined;
+	if (localPlatform === "unix") {
+		return "This session was continued on a non-Windows machine; paths are now Unix style.";
+	}
+	return "This session was continued on a Windows machine; paths are now Windows style.";
+}
+
+/** Rewrite occurrences of the recorded CI cwd (JSON-escaped) to the target cwd. */
+function rewriteSessionCwd(raw: string, sourceCwd: string, targetCwd: string): string {
+	const target = escapeJsonString(targetCwd);
+	let rewritten = raw;
+
+	for (const sourceVariant of getCwdRewriteVariants(sourceCwd)) {
+		if (sourceVariant === targetCwd) continue;
+		rewritten = rewritten.split(escapeJsonString(sourceVariant)).join(target);
+	}
+
+	const ciWorkdirName = getCiWorkdirName(sourceCwd);
+	if (ciWorkdirName) {
+		const escapedName = escapeRegExp(ciWorkdirName);
+		const windowsPathPatterns = [
+			new RegExp(`[A-Za-z]:(?:[^"\\r\\n])*?${escapedName}`, "g"),
+			new RegExp(`/[A-Za-z]/(?:[^"\\r\\n])*?${escapedName}`, "g"),
+		];
+		for (const pattern of windowsPathPatterns) {
+			rewritten = rewritten.replace(pattern, target);
+		}
+	}
+
+	return rewritten;
+}
+
+async function fetchText(url: string): Promise<string> {
+	const response = await fetch(url, { headers: { Accept: "application/vnd.github+json" } });
+	if (!response.ok) {
+		throw new Error(`failed to fetch ${url}: HTTP ${response.status}`);
+	}
+	return await response.text();
+}
+
+async function readGistFile(file: GistFile): Promise<string> {
+	if (file.content && !file.truncated) return file.content;
+	if (!file.raw_url) throw new Error(`gist file ${file.filename ?? "<unknown>"} has no raw URL`);
+	return await fetchText(file.raw_url);
+}
+
+async function findIssueGistId(owner: string, repo: string, issue: string): Promise<string> {
+	const gistIds: string[] = [];
+	let page = 1;
+	while (true) {
+		const response = await fetch(
+			`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues/${encodeURIComponent(issue)}/comments?per_page=100&page=${page}`,
+			{ headers: { Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" } },
+		);
+		if (!response.ok) throw new Error(`failed to fetch issue comments: HTTP ${response.status}`);
+
+		const comments = (await response.json()) as IssueComment[];
+		for (const comment of comments) {
+			if (comment.user?.login !== "github-actions[bot]") continue;
+			for (const match of (comment.body ?? "").matchAll(GIST_URL_IN_TEXT_RE)) {
+				gistIds.push(match[1]);
+			}
+		}
+
+		if (comments.length < 100) break;
+		page++;
+	}
+
+	const gistId = gistIds.at(-1);
+	if (!gistId) throw new Error(`no github-actions gist link found in comments on ${owner}/${repo}#${issue}`);
+	return gistId;
+}
+
+async function fetchGistSession(gistId: string): Promise<{ header: SessionHeader; jsonl: string }> {
+	const response = await fetch(`https://api.github.com/gists/${gistId}`, {
+		headers: {
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28",
+		},
+	});
+	if (!response.ok) throw new Error(`failed to fetch gist ${gistId}: HTTP ${response.status}`);
+
+	const gist = (await response.json()) as GistResponse;
+	const files = Object.values(gist.files ?? {});
+	const jsonlFile = files.find((file) => file.filename?.endsWith(".jsonl"));
+	if (jsonlFile) return parseSessionJsonl(await readGistFile(jsonlFile));
+
+	const htmlFile = files.find((file) => file.filename?.endsWith(".html"));
+	if (htmlFile) return decodeExportedHtml(await readGistFile(htmlFile));
+
+	throw new Error(`gist ${gistId} has no .jsonl or .html session file`);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("ir", {
+		description: "Import a CI issue-analysis session from a gist ID, share URL, or issue URL and switch to it",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const ref = args.trim();
+			if (!ref) {
+				ctx.ui.notify("Usage: /ir <gist-id | gist-url | pi.dev/session URL | issue URL>", "error");
+				return;
+			}
+
+			try {
+				const targetCwd = ctx.sessionManager.getCwd();
+				const sessionDir = ctx.sessionManager.getSessionDir();
+				const parsedRef = parseRef(ref, targetCwd);
+
+				ctx.ui.notify(`Importing repro session from ${ref}...`, "info");
+
+				let sourceName: string;
+				let decoded: { header: SessionHeader; jsonl: string };
+				if (parsedRef.type === "gist") {
+					decoded = await fetchGistSession(parsedRef.id);
+					sourceName = `${parsedRef.id}.jsonl`;
+				} else if (parsedRef.type === "issue") {
+					const gistId = await findIssueGistId(parsedRef.owner, parsedRef.repo, parsedRef.issue);
+					decoded = await fetchGistSession(gistId);
+					sourceName = `${gistId}.jsonl`;
+				} else {
+					if (!existsSync(parsedRef.path)) throw new Error(`session file not found: ${parsedRef.path}`);
+					const raw = readFileSync(parsedRef.path, "utf8");
+					decoded = parsedRef.path.endsWith(".html") ? decodeExportedHtml(raw) : parseSessionJsonl(raw);
+					sourceName = basename(parsedRef.path).replace(/\.html$/, ".jsonl");
+				}
+
+				const platformNotice = getPlatformContinuationNotice(decoded.header.cwd);
+				const rewritten = rewriteSessionCwd(decoded.jsonl, decoded.header.cwd, targetCwd);
+				const destination = join(sessionDir, sourceName);
+				if (existsSync(destination)) {
+					const overwrite = await ctx.ui.confirm(
+						"Session already imported",
+						`Overwrite ${destination}? Local changes to that session will be lost.`,
+					);
+					if (!overwrite) {
+						ctx.ui.notify("Import cancelled", "warning");
+						return;
+					}
+				}
+				writeFileSync(destination, rewritten);
+
+				ctx.ui.notify(`Imported session ${decoded.header.id} (cwd ${decoded.header.cwd} -> ${targetCwd})`, "info");
+				await ctx.switchSession(destination, {
+					withSession: async (nextCtx) => {
+						if (!platformNotice) return;
+						await nextCtx.sendMessage(
+							{
+								customType: "import-repro",
+								content: platformNotice,
+								display: true,
+								details: { sourceCwd: decoded.header.cwd, targetCwd },
+							},
+							{ triggerTurn: false },
+						);
+					},
+				});
+			} catch (error) {
+				ctx.ui.notify(`ir: ${error instanceof Error ? error.message : String(error)}`, "error");
+			}
+		},
+	});
+}

.pi/extensions/prompt-url-widget.ts

@@ -0,0 +1,270 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { DynamicBorder, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, hyperlink, Text } from "@earendil-works/pi-tui";
+
+const PR_PROMPT_PATTERN = /^\s*You are given one or more GitHub PR URLs:\s*(\S+)/im;
+const ISSUE_PROMPT_PATTERN = /^\s*Analyze GitHub issue\(s\):\s*(\S+)/im;
+const ADVISORY_PROMPT_PATTERN = /^\s*Update a GitHub security advisory for publication:\s*(\S+)/im;
+
+type PromptMatch = {
+	kind: "pr" | "issue" | "advisory";
+	target: string;
+};
+
+type GhMetadata = {
+	title?: string;
+	detail?: string;
+	displayUrl?: string;
+	author?: {
+		login?: string;
+		name?: string | null;
+	};
+};
+
+type GitHubAdvisoryMetadata = {
+	ghsa_id?: string;
+	summary?: string;
+	severity?: string;
+	state?: string;
+	html_url?: string;
+	cve_id?: string | null;
+};
+
+type AdvisoryRef = {
+	owner: string;
+	repo: string;
+	ghsaId: string;
+	url: string;
+};
+
+function extractPromptMatch(prompt: string): PromptMatch | undefined {
+	const prMatch = prompt.match(PR_PROMPT_PATTERN);
+	if (prMatch?.[1]) {
+		return { kind: "pr", target: prMatch[1].trim() };
+	}
+
+	const issueMatch = prompt.match(ISSUE_PROMPT_PATTERN);
+	if (issueMatch?.[1]) {
+		return { kind: "issue", target: issueMatch[1].trim() };
+	}
+
+	const advisoryMatch = prompt.match(ADVISORY_PROMPT_PATTERN);
+	if (advisoryMatch?.[1]) {
+		return { kind: "advisory", target: advisoryMatch[1].trim() };
+	}
+
+	return undefined;
+}
+
+function getPromptLabel(kind: PromptMatch["kind"]): string {
+	if (kind === "pr") return "PR";
+	if (kind === "issue") return "Issue";
+	return "Advisory";
+}
+
+function parseAdvisoryUrl(value: string): AdvisoryRef | undefined {
+	const match = value.match(
+		/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/security\/advisories\/(GHSA-[A-Za-z0-9-]+)(?:[/?#].*)?$/i,
+	);
+	if (!match?.[1] || !match[2] || !match[3]) return undefined;
+	return {
+		owner: match[1],
+		repo: match[2],
+		ghsaId: match[3],
+		url: `https://github.com/${match[1]}/${match[2]}/security/advisories/${match[3]}`,
+	};
+}
+
+function unquoteYamlValue(value: string): string {
+	const trimmed = value.trim();
+	if (
+		(trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+		(trimmed.startsWith("'") && trimmed.endsWith("'"))
+	) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+function resolveDraftPath(cwd: string, target: string): string {
+	if (target === "~") return homedir();
+	if (target.startsWith("~/")) return resolve(homedir(), target.slice(2));
+	return resolve(cwd, target);
+}
+
+async function readAdvisoryRefFromDraft(cwd: string, target: string): Promise<AdvisoryRef | undefined> {
+	try {
+		const content = await readFile(resolveDraftPath(cwd, target), "utf8");
+		const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+		const body = frontmatter?.[1] ?? content;
+		const urlMatch = body.match(/^advisory_url:\s*(.+)$/m);
+		if (!urlMatch?.[1]) return undefined;
+		return parseAdvisoryUrl(unquoteYamlValue(urlMatch[1]));
+	} catch {
+		return undefined;
+	}
+}
+
+function formatAdvisoryDetail(advisory: GitHubAdvisoryMetadata): string | undefined {
+	const parts = [advisory.ghsa_id, advisory.cve_id ?? undefined, advisory.severity, advisory.state]
+		.map((part) => part?.trim())
+		.filter((part): part is string => part !== undefined && part.length > 0);
+	return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+async function fetchAdvisoryMetadata(pi: ExtensionAPI, cwd: string, target: string): Promise<GhMetadata | undefined> {
+	const advisoryRef = parseAdvisoryUrl(target) ?? (await readAdvisoryRefFromDraft(cwd, target));
+	if (!advisoryRef) return undefined;
+
+	try {
+		const result = await pi.exec("gh", [
+			"api",
+			`repos/${advisoryRef.owner}/${advisoryRef.repo}/security-advisories/${advisoryRef.ghsaId}`,
+		]);
+		if (result.code !== 0 || !result.stdout) return { displayUrl: advisoryRef.url };
+		const advisory = JSON.parse(result.stdout) as GitHubAdvisoryMetadata;
+		return {
+			title: advisory.summary,
+			detail: formatAdvisoryDetail(advisory),
+			displayUrl: advisory.html_url ?? advisoryRef.url,
+		};
+	} catch {
+		return { displayUrl: advisoryRef.url };
+	}
+}
+
+async function fetchGhMetadata(
+	pi: ExtensionAPI,
+	kind: PromptMatch["kind"],
+	target: string,
+	cwd: string,
+): Promise<GhMetadata | undefined> {
+	if (kind === "advisory") {
+		return fetchAdvisoryMetadata(pi, cwd, target);
+	}
+
+	const args =
+		kind === "pr"
+			? ["pr", "view", target, "--json", "title,author"]
+			: ["issue", "view", target, "--json", "title,author"];
+
+	try {
+		const result = await pi.exec("gh", args);
+		if (result.code !== 0 || !result.stdout) return undefined;
+		return JSON.parse(result.stdout) as GhMetadata;
+	} catch {
+		return undefined;
+	}
+}
+
+function formatAuthor(author?: GhMetadata["author"]): string | undefined {
+	if (!author) return undefined;
+	const name = author.name?.trim();
+	const login = author.login?.trim();
+	if (name && login) return `${name} (@${login})`;
+	if (login) return `@${login}`;
+	if (name) return name;
+	return undefined;
+}
+
+export default function promptUrlWidgetExtension(pi: ExtensionAPI) {
+	const setWidget = (ctx: ExtensionContext, match: PromptMatch, metadata?: GhMetadata) => {
+		ctx.ui.setWidget("prompt-url", (_tui, thm) => {
+			const displayTarget = metadata?.displayUrl ?? match.target;
+			const titleText = metadata?.title
+				? thm.fg("accent", metadata.title)
+				: hyperlink(thm.fg("accent", displayTarget), displayTarget);
+			const detailText = metadata?.detail ?? formatAuthor(metadata?.author);
+			const detailLine = detailText ? thm.fg("muted", detailText) : undefined;
+			const urlLine = hyperlink(thm.fg("dim", displayTarget), displayTarget);
+
+			const lines = [titleText];
+			if (detailLine) lines.push(detailLine);
+			lines.push(urlLine);
+
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => thm.fg("muted", s)));
+			container.addChild(new Text(lines.join("\n"), 1, 0));
+			return container;
+		});
+	};
+
+	const applySessionName = (ctx: ExtensionContext, match: PromptMatch, metadata?: GhMetadata) => {
+		const label = getPromptLabel(match.kind);
+		const displayTarget = metadata?.displayUrl ?? match.target;
+		const trimmedTitle = metadata?.title?.trim();
+		const fallbackName = `${label}: ${match.target}`;
+		const desiredFallbackName = `${label}: ${displayTarget}`;
+		const desiredName = trimmedTitle ? `${label}: ${trimmedTitle} (${displayTarget})` : desiredFallbackName;
+		const currentName = pi.getSessionName()?.trim();
+		if (!currentName) {
+			pi.setSessionName(desiredName);
+			return;
+		}
+		if (currentName === match.target || currentName === fallbackName || currentName === desiredFallbackName) {
+			pi.setSessionName(desiredName);
+		}
+	};
+
+	const updatePromptContext = (ctx: ExtensionContext, match: PromptMatch) => {
+		setWidget(ctx, match);
+		applySessionName(ctx, match);
+		void fetchGhMetadata(pi, match.kind, match.target, ctx.cwd).then((meta) => {
+			setWidget(ctx, match, meta);
+			applySessionName(ctx, match, meta);
+		});
+	};
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!ctx.hasUI) return;
+		const match = extractPromptMatch(event.prompt);
+		if (!match) {
+			return;
+		}
+
+		updatePromptContext(ctx, match);
+	});
+
+	pi.on("session_switch", async (_event, ctx) => {
+		rebuildFromSession(ctx);
+	});
+
+	const getUserText = (content: string | { type: string; text?: string }[] | undefined): string => {
+		if (!content) return "";
+		if (typeof content === "string") return content;
+		return (
+			content
+				.filter((block): block is { type: "text"; text: string } => block.type === "text")
+				.map((block) => block.text)
+				.join("\n") ?? ""
+		);
+	};
+
+	const rebuildFromSession = (ctx: ExtensionContext) => {
+		if (!ctx.hasUI) return;
+
+		const entries = ctx.sessionManager.getEntries();
+		const lastMatch = [...entries].reverse().find((entry) => {
+			if (entry.type !== "message" || entry.message.role !== "user") return false;
+			const text = getUserText(entry.message.content);
+			return !!extractPromptMatch(text);
+		});
+
+		const content =
+			lastMatch?.type === "message" && lastMatch.message.role === "user" ? lastMatch.message.content : undefined;
+		const text = getUserText(content);
+		const match = text ? extractPromptMatch(text) : undefined;
+		if (!match) {
+			ctx.ui.setWidget("prompt-url", undefined);
+			return;
+		}
+
+		updatePromptContext(ctx, match);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		rebuildFromSession(ctx);
+	});
+}

.pi/extensions/redraws.ts

@@ -0,0 +1,24 @@
+/**
+ * Redraws Extension
+ *
+ * Exposes /tui to show TUI redraw stats.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("tui", {
+		description: "Show TUI stats",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) return;
+			let redraws = 0;
+			await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
+				redraws = tui.fullRedraws;
+				done(undefined);
+				return new Text("", 0, 0);
+			});
+			ctx.ui.notify(`TUI full redraws: ${redraws}`, "info");
+		},
+	});
+}

.pi/extensions/tps.ts

@@ -0,0 +1,47 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+function isAssistantMessage(message: unknown): message is AssistantMessage {
+	if (!message || typeof message !== "object") return false;
+	const role = (message as { role?: unknown }).role;
+	return role === "assistant";
+}
+
+export default function (pi: ExtensionAPI) {
+	let agentStartMs: number | null = null;
+
+	pi.on("agent_start", () => {
+		agentStartMs = Date.now();
+	});
+
+	pi.on("agent_end", (event, ctx) => {
+		if (!ctx.hasUI) return;
+		if (agentStartMs === null) return;
+
+		const elapsedMs = Date.now() - agentStartMs;
+		agentStartMs = null;
+		if (elapsedMs <= 0) return;
+
+		let input = 0;
+		let output = 0;
+		let cacheRead = 0;
+		let cacheWrite = 0;
+		let totalTokens = 0;
+
+		for (const message of event.messages) {
+			if (!isAssistantMessage(message)) continue;
+			input += message.usage.input || 0;
+			output += message.usage.output || 0;
+			cacheRead += message.usage.cacheRead || 0;
+			cacheWrite += message.usage.cacheWrite || 0;
+			totalTokens += message.usage.totalTokens || 0;
+		}
+
+		if (output <= 0) return;
+
+		const elapsedSeconds = elapsedMs / 1000;
+		const tokensPerSecond = output / elapsedSeconds;
+		const message = `TPS ${tokensPerSecond.toFixed(1)} tok/s. out ${output.toLocaleString()}, in ${input.toLocaleString()}, cache r/w ${cacheRead.toLocaleString()}/${cacheWrite.toLocaleString()}, total ${totalTokens.toLocaleString()}, ${elapsedSeconds.toFixed(1)}s`;
+		ctx.ui.notify(message, "info");
+	});
+}

.pi/git/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.pi/npm/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.pi/prompts/cl.md

@@ -0,0 +1,54 @@
+---
+description: Audit changelog entries before release
+---
+Audit changelog entries for all commits since the last release.
+
+## Process
+
+1. **Find the last release tag:**
+   ```bash
+   git tag --sort=-version:refname | head -1
+   ```
+
+2. **List all commits since that tag:**
+   ```bash
+   git log <tag>..HEAD --oneline
+   ```
+
+3. **Read each package's [Unreleased] section:**
+   - packages/ai/CHANGELOG.md
+   - packages/tui/CHANGELOG.md
+   - packages/coding-agent/CHANGELOG.md
+
+4. **For each commit, check:**
+   - Skip: changelog updates, doc-only changes, release housekeeping
+   - Skip: changes to generated model catalogs (for example `packages/ai/src/models.generated.ts`) unless accompanied by an intentional product-facing change in non-generated source/docs.
+   - Determine which package(s) the commit affects (use `git show <hash> --stat`)
+   - Verify a changelog entry exists in the affected package(s)
+   - For external contributions (PRs), verify format: `Description ([#N](url) by [@user](url))`
+
+5. **Cross-package duplication rule:**
+   Changes in `ai`, `agent` or `tui` that affect end users should be duplicated to `coding-agent` changelog, since coding-agent is the user-facing package that depends on them.
+
+6. **Add New Features section after changelog fixes:**
+   - Insert a `### New Features` section at the start of `## [Unreleased]` in `packages/coding-agent/CHANGELOG.md`.
+   - Propose the top new features to the user for confirmation before writing them.
+   - Link to relevant docs and sections whenever possible.
+
+7. **Report:**
+   - List commits with missing entries
+   - List entries that need cross-package duplication
+   - Add any missing entries directly
+
+## Changelog Format Reference
+
+Sections (in order):
+- `### Breaking Changes` - API changes requiring migration
+- `### Added` - New features
+- `### Changed` - Changes to existing functionality
+- `### Fixed` - Bug fixes
+- `### Removed` - Removed features
+
+Attribution:
+- Internal: `Fixed foo ([#123](https://github.com/earendil-works/pi/issues/123))`
+- External: `Added bar ([#456](https://github.com/earendil-works/pi/pull/456) by [@user](https://github.com/user))`

.pi/prompts/deslop.md

@@ -0,0 +1,67 @@
+---
+description: simplify a completed workpackage
+---
+
+Review the completed workpackage and simplify its implementation without changing its intended behavior.
+
+## Scope
+
+- Focus on code added or affected by the workpackage and the nearby code needed to simplify it coherently.
+- Do not perform unrelated cleanup.
+- Read the affected files in full and understand the relevant invariants, call sites, tests, and public API before editing.
+- Optimize for a direct, coherent, maintainable design—not the smallest diff.
+
+## What to remove or simplify
+
+- Remove abstractions that have no clear responsibility or do not reduce real complexity.
+- Inline trivial helpers, wrappers, adapters, and pass-through layers when they obscure rather than clarify behavior.
+- Remove duplicated logic and put shared behavior at the appropriate existing layer.
+- Remove speculative flexibility, configuration, extension points, and generic machinery that have no current requirement.
+- Remove speculative defensive programming inside trusted code. Validate at real trust boundaries; rely on types and established invariants internally.
+- Do not keep fallback behavior for states that should be impossible. Prefer fixing the invariant or type model.
+- Simplify excessive state, boolean flags, branching, indirection, and special cases. Rework the underlying representation when that is clearer.
+- Tighten TypeScript types so invalid states are unrepresentable. Avoid `any`, unnecessary assertions, broad types, and optional fields for impossible states.
+- Prefer direct, readable code over cleverness, premature abstraction, and framework-like infrastructure.
+- Delete comments that merely restate the code, but preserve comments that explain constraints, intent, or non-obvious decisions.
+
+## Approval gate for significant removals
+
+Before making any significant or potentially intentional removal, stop and ask the user for approval. First explain:
+
+1. what you propose to remove or change;
+2. why it appears unnecessary or overly defensive;
+3. what behavior, compatibility, extensibility, validation, or failure handling could be affected;
+4. the simpler replacement, if any; and
+5. your recommendation.
+
+Wait for explicit approval before applying that change. Do not bundle approval for multiple independent decisions; present them separately when the tradeoffs differ.
+
+Treat a decision as significant when it removes or materially changes any of the following:
+
+- user-visible behavior or supported workflows;
+- public APIs, persisted formats, protocol behavior, or backward compatibility;
+- validation, authorization, security checks, recovery, retries, fallbacks, or error handling;
+- an abstraction or extension point that appears deliberate or has multiple consumers;
+- functionality covered by tests or documentation;
+- code whose purpose or invariant is uncertain.
+
+Routine, behavior-preserving cleanup does not require approval, such as inlining a single-use trivial helper, removing an unreachable branch proven impossible by the type model, or deleting newly added duplication. If uncertain whether a removal is significant, ask.
+
+## Constraints
+
+- Preserve intended behavior unless the user explicitly approves a change.
+- Do not remove code merely because it is unused until you have checked whether it is a public API, extension point, generated entry point, or intentionally retained compatibility surface.
+- Do not replace clear code with a new abstraction solely to reduce line count.
+- Do not weaken tests to permit simplification. Update tests only when an approved behavior change or a cleaner equivalent structure requires it.
+- Follow the repository's validation and testing instructions after edits.
+
+## Completion
+
+After editing, review the final diff for avoidable complexity, duplication, indirection, defensive branches, and accidental behavior changes. Report:
+
+- what was simplified;
+- which invariants the implementation now relies on;
+- any significant removals you did not make because approval was not granted; and
+- the validation performed and its results.
+
+Passing tests and type checks is necessary but not sufficient. Leave the affected code easier to understand and change.

.pi/prompts/is.md

@@ -0,0 +1,28 @@
+---
+description: Analyze GitHub issues (bugs or feature requests)
+argument-hint: "<issue>"
+---
+Analyze GitHub issue(s): $ARGUMENTS
+
+For each issue:
+
+1. If running under CI (`CI=true`), do not add the `inprogress` label and do not assign the issue. Otherwise, add the `inprogress` label to the issue via GitHub CLI and assign the issue to the local `gh` user before analysis starts. If either action fails, report that explicitly and continue.
+2. Read the issue in full, including all comments and linked issues/PRs. Use fields supported by GitHub CLI, for example:
+   ```sh
+   gh issue view <issue> --json title,body,comments,labels,assignees,state,url,author,createdAt,updatedAt,closedByPullRequestsReferences
+   ```
+3. Do not trust analysis written in the issue. Independently verify behavior and derive your own analysis from the code and execution path.
+
+4. **For bugs**:
+   - Ignore any root cause analysis in the issue (likely wrong)
+   - Read all related code files in full (no truncation)
+   - Trace the code path and identify the actual root cause
+   - Propose a fix
+
+5. **For feature requests**:
+   - Do not trust implementation proposals in the issue without verification
+   - Read all related code files in full (no truncation)
+   - Propose the most concise implementation approach
+   - List affected files and changes needed
+
+Do NOT implement unless explicitly asked. Analyze and propose only.

.pi/prompts/pr.md

@@ -0,0 +1,37 @@
+---
+description: Review PRs from URLs with structured issue and code analysis
+argument-hint: "<PR-URL>"
+---
+You are given one or more GitHub PR URLs: $@
+
+For each PR URL, do the following in order:
+1. Add the `inprogress` label to the PR via GitHub CLI before analysis starts. If adding the label fails, report that explicitly and continue.
+2. Read the PR page in full. Include description, all comments, all commits, and all changed files.
+3. Identify any linked issues referenced in the PR body, comments, commit messages, or cross links. Read each issue in full, including all comments.
+4. Analyze the PR diff without checking out or switching to the PR branch. Use `gh pr diff`, `gh pr view`, `gh api`, and local main-branch files; if PR file contents are needed, use fetched refs with `git show <ref>:<path>` or temporary files. Read all relevant code files in full with no truncation and compare against the diff. Do not fetch PR file blobs unless a file is missing on main or the diff context is insufficient. Include related code paths that are not in the diff but are required to validate behavior.
+5. Do not check for a changelog entry. Per CONTRIBUTING.md, contributor PRs must not edit `CHANGELOG.md` — the maintainer adds the entry when merging.
+6. Check if packages/coding-agent/README.md, packages/coding-agent/docs/*.md, packages/coding-agent/examples/**/*.md require modification. This is usually the case when existing features have been changed, or new features have been added.
+7. Provide a structured review with these sections:
+   - What it does: one short paragraph describing the change and its intent.
+   - Good: solid choices or improvements.
+   - Bad: concrete issues, regressions, missing tests, or risks.
+   - Ugly: subtle or high impact problems.
+   - Tests: what is covered, what is missing, and whether existing tests are adequate.
+   - Open questions for you: only things blocking a merge decision that need the user's input. Omit the section entirely if there are none.
+
+Output format per PR:
+PR: <url>
+What it does:
+- ...
+Good:
+- ...
+Bad:
+- ...
+Ugly:
+- ...
+Tests:
+- ...
+Open questions for you:
+- ...
+
+If no issues are found, say so under Bad and Ugly.

.pi/prompts/sa.md

@@ -0,0 +1,163 @@
+---
+description: Update a GitHub security advisory for publication
+argument-hint: "<advisory-url-or-draft-path>"
+---
+Update a GitHub security advisory for publication: $ARGUMENTS
+
+Use `gh` for all GitHub operations. Do not publish the advisory, change its state, or request a CVE unless the user explicitly agrees or the draft markdown explicitly says `request_cve: true`.
+
+GitHub does not expose repository security advisory comments/discussion through the documented REST OpenAPI schema or public GraphQL schema. A 404 from guessed API endpoints such as `api.github.com/repos/.../security-advisories/<GHSA>/comments`, `.../timeline`, or `.../events` is expected and is not, by itself, an auth failure. Do not use a browser session, browser cookies, or cookie extraction to fetch advisory comments. Instead, clearly tell the user that advisory comments were not included and that they can paste any relevant comments if they want them considered.
+
+## Input handling
+
+- If `$ARGUMENTS` is a GitHub security advisory URL, start the investigation and drafting workflow.
+- If `$ARGUMENTS` is a path to an existing markdown draft, read it and apply that draft to the advisory.
+- In a follow-up message after this prompt, if the user says "update", "apply", "looks good", or similar, treat it as approval to apply the previously written temp markdown draft. Re-read the file from disk before updating GitHub.
+- If applying a draft and there is no known draft path, ask the user for the markdown file path.
+
+## Initial advisory workflow
+
+1. Parse the advisory URL into `owner`, `repo`, and `GHSA` id.
+2. Fetch the advisory with:
+   ```sh
+   gh api repos/<owner>/<repo>/security-advisories/<GHSA>
+   ```
+   Record the advisory's original severity, CVSS vector, and CVSS score exactly as returned before proposing changes.
+3. Do not fetch advisory comments/discussion unless the user pasted them into the conversation:
+   - Inspect the advisory JSON for references, credits, linked issues/PRs, and any discussion fields.
+   - Do not rely on invented API endpoints such as `/comments`, `/timeline`, or `/events`; they commonly return 404 because GitHub does not expose draft advisory comments through the public API.
+   - Do not use a browser session, browser cookies, or cookie extraction to fetch comments.
+   - Explicitly tell the user: `Advisory comments were not included because GitHub does not expose them through the public API. Paste any relevant comments if you want them considered.`
+   - If the user pasted comments, read and consider them.
+   - Never pretend comments were read.
+4. Investigate independently:
+   - Read the advisory text, metadata, affected package(s), version ranges, CVSS, CWE, references, and linked issues/PRs/commits.
+   - Inspect relevant code history, releases, changelogs, package metadata, and tags.
+   - Determine whether the vulnerability is already fixed.
+   - If fixed, identify the patched version(s) and the correct affected version range.
+   - Do not trust the reporter's analysis without verification.
+5. Discuss CVSS with the user before drafting the final update:
+   - Propose a CVSS vector, score, and severity.
+   - Explain the controversial metrics briefly.
+   - Ask the user to confirm or adjust it.
+6. Ask whether a CVE should be requested from GitHub for this advisory.
+7. Draft a publication-ready advisory markdown file under `/tmp`, for example `/tmp/sa-<GHSA>.md`. Include both the original CVSS from the advisory and the proposed/confirmed updated CVSS.
+8. Tell the user:
+   - the path to the temp markdown file
+   - the original advisory URL
+   - that they can edit the file and then say "update" or provide the path
+
+## Draft markdown format
+
+The draft file must contain YAML frontmatter followed by the advisory body. Include all fields needed to update GitHub and to decide whether to request a CVE.
+
+```markdown
+---
+advisory_url: https://github.com/<owner>/<repo>/security/advisories/<GHSA>
+owner: <owner>
+repo: <repo>
+ghsa_id: <GHSA>
+summary: <short advisory summary>
+original_severity: <low|medium|high|critical|null>
+original_cvss_vector: <original CVSS:3.1/... or null>
+original_cvss_score: <original number or null>
+severity: <proposed/confirmed low|medium|high|critical>
+cvss_vector: <proposed/confirmed CVSS:3.1/...>
+cvss_score: <proposed/confirmed number>
+cwe_ids:
+  - CWE-...
+vulnerabilities:
+  - package:
+      ecosystem: npm
+      name: <package-name>
+    vulnerable_version_range: <range>
+    patched_versions: <range-or-version>
+request_cve: false
+---
+
+# <Advisory title>
+
+<Concise description of the vulnerability and vulnerable behavior.>
+
+## Info
+
+<Technical explanation of the root cause and affected component. Focus on facts needed by defenders and maintainers. Do not include PoC steps, exploit payloads, or copy-pastable exploit strings.>
+
+## Impact
+
+<Who can exploit it, prerequisites, confidentiality/integrity/availability impact, and realistic deployment assumptions.>
+
+## Affected versions
+
+- Affected: `<range>`
+- Patched: `<version or range>`
+
+## The solution
+
+<Describe the fix and the patched release.>
+
+## Recommendations
+
+<Upgrade guidance and operational mitigations.>
+
+## Workarounds
+
+<Workarounds if any; otherwise skip this section entirely>
+
+## Timeline
+
+- YYYY-MM-DD: Report received
+- YYYY-MM-DD: Fix committed
+- YYYY-MM-DD: Fixed version released
+- YYYY-MM-DD: Advisory published
+
+## Credits
+
+<Reporter/researcher attribution if appropriate, otherwise skip section.>
+
+## References
+
+- <links to releases, commits, advisories, documentation>
+```
+
+Use the curl advisory style as inspiration: clear sections, direct language, affected/fixed version facts, recommendations, timeline, and credits. Do not include a PoC.
+
+## Applying a draft to GitHub
+
+When the user approves with "update"/similar or provides a markdown path:
+
+1. Re-read the markdown file from disk. Never rely on the previously generated content in memory.
+2. Parse the YAML frontmatter and body.
+3. Build a JSON payload in a temporary file. Map fields as follows:
+   - `summary` from frontmatter
+   - `description` from the markdown body after frontmatter
+   - `severity` from frontmatter if present
+   - `cvss_vector_string` from `cvss_vector`
+   - `cwe_ids` from frontmatter
+   - `vulnerabilities` from frontmatter
+   - Do not send `original_severity`, `original_cvss_vector`, or `original_cvss_score`; those fields are retained only for audit context.
+4. Update the advisory with:
+   ```sh
+   gh api -X PATCH repos/<owner>/<repo>/security-advisories/<GHSA> --input /tmp/<payload>.json
+   ```
+5. If and only if the markdown frontmatter has `request_cve: true`, request a CVE with:
+   ```sh
+   gh api -X POST repos/<owner>/<repo>/security-advisories/<GHSA>/cve
+   ```
+   Treat "already requested" or "already assigned" as non-fatal and report it.
+6. Report what was updated:
+   - advisory URL
+   - summary
+   - affected range
+   - patched versions
+   - original CVSS vector/score/severity
+   - updated CVSS vector/score/severity
+   - whether CVE was requested
+
+## Safety rules
+
+- Do not include PoC material in the final advisory body.
+- Do not request a CVE unless `request_cve: true` is present in the markdown file.
+- Do not publish the advisory or change its state unless the user explicitly asks.
+- Do not fetch advisory comments through browser sessions or cookies. State that comments were not included and invite the user to paste relevant comments if they want them considered.
+- If there is uncertainty in affected ranges, patched versions, CVSS, or CVE request status, ask the user before applying.

.pi/prompts/wr.md

@@ -0,0 +1,41 @@
+---
+description: Finish the current task end-to-end with changelog, commit, and push
+argument-hint: "[instructions]"
+---
+Wrap it.
+
+Additional instructions: $ARGUMENTS
+
+Determine context from the conversation history first.
+
+Rules for context detection:
+- If the conversation already mentions a GitHub issue or PR, use that existing context.
+- If the work came from `/is` or `/pr`, assume the issue or PR context is already known from the conversation and from the analysis work already done.
+- If there is no GitHub issue or PR in the conversation history, treat this as non-GitHub work.
+
+Unless I explicitly override something in this request, do the following in order:
+
+1. Add or update the relevant package changelog entry under `## [Unreleased]` using the repo changelog rules.
+2. If this task is tied to a GitHub issue or PR and a final issue or PR comment has not already been posted in this session, draft it in my tone, preview it, and post exactly one final comment. The comment must end with this exact standalone disclaimer line, with no variations:
+
+   ```text
+   This comment is AI-generated by `/wr`
+   ```
+3. Commit only files you changed in this session.
+4. If this task is tied to exactly one GitHub issue, include `closes #<issue>` in the commit message. If it is tied to multiple issues, stop and ask which one to use. If it is not tied to any issue, do not include `closes #` or `fixes #` in the commit message.
+5. Check the current git branch. If it is not `main`, stop and ask what to do. Do not push from another branch unless I explicitly say so.
+6. Push the current branch.
+7. If this task is tied to exactly one GitHub issue, explicitly close that issue with reason `completed` after the push so the issue-close workflows in `.github/` run. This applies to issues only, not PRs.
+   - Inspect `gh issue view <issue> --json state,stateReason,labels`.
+   - If the issue is open, run `gh issue close <issue> --reason completed`.
+   - If the issue is already closed with any reason other than `COMPLETED`, reopen it first, then close it with `gh issue close <issue> --reason completed` so GitHub emits a fresh close event.
+   - If the issue is already closed as `COMPLETED`, leave it closed unless the `inprogress` label is still present; in that case reopen it and close it again with reason `completed`.
+
+Constraints:
+- Never stage unrelated files.
+- Never use `git add .` or `git add -A`.
+- Run required checks before committing if code changed.
+- Do not open a PR unless I explicitly ask.
+- If this is not GitHub issue or PR work, do not post a GitHub comment.
+- If a final issue or PR comment was already posted in this session, do not post another one unless I explicitly ask.
+- When working against a branch other than `main`, skip the changelog.

.pi/skills/add-llm-provider.md

@@ -0,0 +1,57 @@
+---
+name: add-llm-provider
+description: Checklist for adding a new LLM provider to packages/ai. Covers core types, provider implementation, lazy registration, model generation, the full test matrix, coding-agent wiring, and docs.
+---
+
+# Adding a New LLM Provider (packages/ai)
+
+A new provider touches multiple files. Work through these steps in order.
+
+## 1. Core Types (`packages/ai/src/types.ts`)
+
+- Add API identifier to `Api` type union (e.g. `"bedrock-converse-stream"`).
+- Create options interface extending `StreamOptions`.
+- Add mapping to `ApiOptionsMap`.
+- Add provider name to `KnownProvider` type union.
+
+## 2. Provider Implementation (`packages/ai/src/providers/`)
+
+Create a provider file exporting:
+
+- `stream<Provider>()` returning `AssistantMessageEventStream`.
+- `streamSimple<Provider>()` for `SimpleStreamOptions` mapping.
+- Provider-specific options interface.
+- Message/tool conversion functions.
+- Response parsing that emits standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`).
+
+## 3. Provider Exports and Lazy Registration
+
+- Add a package subpath export in `packages/ai/package.json` pointing at `./dist/providers/<provider>.js`.
+- Add `export type` re-exports in `packages/ai/src/index.ts` for provider option types that should remain available from the root entry.
+- Register the provider in `packages/ai/src/providers/register-builtins.ts` via lazy loader wrappers; do not statically import provider implementation modules there.
+- Add credential detection in `packages/ai/src/env-api-keys.ts`.
+
+## 4. Model Generation (`packages/ai/scripts/generate-models.ts`)
+
+- Add logic to fetch/parse models from the provider source.
+- Map to the standardized `Model` interface.
+
+## 5. Tests (`packages/ai/test/`)
+
+- Always add the provider to `stream.test.ts` with at least one representative model, even if it reuses an existing API impl such as `openai-completions`.
+- Add the provider to the broader matrix where applicable: `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `unicode-surrogate.test.ts`, `tool-call-without-result.test.ts`, `image-tool-result.test.ts`, `total-tokens.test.ts`, `cross-provider-handoff.test.ts`.
+- For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If the provider exposes multiple model families (e.g. GPT and Claude), add at least one pair per family.
+- For non-standard auth, create a utility (e.g. `bedrock-utils.ts`) with credential detection.
+
+## 6. Coding Agent (`packages/coding-agent/`)
+
+- `src/core/model-resolver.ts`: add default model ID to `defaultModelPerProvider`.
+- `src/core/provider-display-names.ts`: add API-key login display name so `/login` and related UI show the provider for built-in API-key auth.
+- `src/cli/args.ts`: add env var documentation.
+- `README.md`: add provider setup instructions.
+- `docs/providers.md`: add setup instructions, env var, and `auth.json` key.
+
+## 7. Documentation
+
+- `packages/ai/README.md`: add to providers table, document options/auth, add env vars.
+- `packages/ai/CHANGELOG.md`: add entry under `## [Unreleased]`.

.pi/skills/interactive-testing.md

@@ -0,0 +1,19 @@
+---
+name: interactive-testing
+description: Test and debug pi's interactive mode in a controlled tmux terminal. Use for TUI behavior checks and interactive release smoke tests.
+---
+
+# Testing pi Interactive Mode with tmux
+
+Run the TUI in a controlled terminal (from the repo root, two directories above this skill):
+
+```bash
+tmux new-session -d -s pi-test -x 80 -y 24
+tmux send-keys -t pi-test "./pi-test.sh" Enter
+sleep 3 && tmux capture-pane -t pi-test -p     # capture after startup
+tmux send-keys -t pi-test "your prompt here" Enter
+tmux send-keys -t pi-test Escape               # special keys (also C-o for ctrl+o, etc.)
+tmux kill-session -t pi-test
+```
+
+For release smoke tests, start the tmux session with `-c /tmp` and replace `./pi-test.sh` with the absolute path to the release binary. Test both Node and Bun binaries separately, submit a prompt, and wait for the model reply; startup alone is not a passing smoke test.

.pi/skills/release.md

@@ -0,0 +1,48 @@
+---
+name: release
+description: Prepare, publish, verify, and recover pi releases. Use for release preparation, local release smoke tests, publishing, and failed release CI or announcements.
+---
+
+# Releasing pi
+
+Run repository commands from the repo root (two directories above this skill), unless instructed otherwise.
+
+**Lockstep versioning**: all packages share one version; every release updates all together. `patch` = fixes + additions, `minor` = breaking changes. No major releases.
+
+1. **Update CHANGELOGs**: ask the user whether they ran the `/cl` prompt on the latest commit on `main`. If not, they must run `/cl` first to audit and update each package's `[Unreleased]` section before releasing.
+
+2. **Local smoke test**: build an unpublished release and smoke test from outside the repo (so it can't resolve workspace files):
+   ```bash
+   npm run release:local -- --out /tmp/pi-local-release --force
+   cd /tmp
+
+   # Node package install smoke tests
+   /tmp/pi-local-release/node/pi --help
+   /tmp/pi-local-release/node/pi --version
+   /tmp/pi-local-release/node/pi --list-models
+   /tmp/pi-local-release/node/pi -p "Say exactly: ok"
+   /tmp/pi-local-release/node/pi
+
+   # Bun binary smoke tests
+   /tmp/pi-local-release/bun/pi --help
+   /tmp/pi-local-release/bun/pi --version
+   /tmp/pi-local-release/bun/pi --list-models
+   /tmp/pi-local-release/bun/pi -p "Say exactly: ok"
+   /tmp/pi-local-release/bun/pi
+   ```
+   Verify both Node and Bun startup, model/account listing, interactive startup, and at least one real prompt with the intended default provider. The bare commands `/tmp/pi-local-release/node/pi` and `/tmp/pi-local-release/bun/pi` start interactive mode; run each in tmux, submit a prompt, and wait for the model reply before considering the interactive smoke test passed. Failures are release blockers unless the user explicitly accepts the risk.
+
+   Load and follow [interactive-testing.md](interactive-testing.md) for the tmux workflow. Start each release binary from `/tmp`, not the repo root.
+
+3. **Run the release script**:
+   ```bash
+   PI_ALLOW_LOCKFILE_CHANGE=1 npm_config_min_release_age=0 npm run release:patch    # fixes + additions
+   PI_ALLOW_LOCKFILE_CHANGE=1 npm_config_min_release_age=0 npm run release:minor    # breaking changes
+   ```
+   Use `npm_config_min_release_age=0` only for the release command. The repo's normal npm age gate can otherwise block the release lockfile refresh when the current workspace package version was published recently. Review any lockfile or shrinkwrap diffs the release creates before push.
+
+   The release script bumps all package versions, updates changelogs, regenerates release artifacts, runs `npm run check`, commits `Release vX.Y.Z`, tags `vX.Y.Z`, adds fresh `## [Unreleased]` changelog sections, commits `Add [Unreleased] section for next cycle`, then pushes `main` and the tag. Do not rerun the release script after a tag was pushed.
+
+4. **CI verifies and announces the npm release**: pushing the `vX.Y.Z` tag triggers `.github/workflows/build-binaries.yml`. The `publish-npm` job uses npm trusted publishing through GitHub Actions OIDC with environment `npm-publish`; no local `npm publish`, `npm whoami`, OTP, or WebAuthn flow is required. After publishing, `announce-pi-dev-release` verifies every public workspace package resolves at the exact release version and that its npm tarball is available, then writes the verified release marker to R2. `pi.dev/api/latest-version` reads that marker; it must never announce a release from npm before this job succeeds.
+
+5. **If CI publish or announcement fails**: inspect the failed job. The publish helper is idempotent and skips package versions already present on npm; the announcement job rechecks availability before updating the R2 marker. Rerun the failed job or workflow after fixing CI or transient npm issues. Do not rerun `npm run release:patch` or `npm run release:minor` for the same version.

packages/ai/test/anthropic-eager-tool-input-compat.test.ts

@@ -0,0 +1,166 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { Type } from "typebox";
+import { describe, expect, it } from "vitest";
+import { stream as streamAnthropic } from "../src/api/anthropic-messages.ts";
+import type { Context, Model, Tool } from "../src/types.ts";
+
+interface CapturedRequest {
+	headers: IncomingMessage["headers"];
+	body: Record<string, unknown>;
+}
+
+function createModel(baseUrl: string, compat?: Model<"anthropic-messages">["compat"]): Model<"anthropic-messages"> {
+	return {
+		id: "claude-opus-4-8",
+		name: "Claude Opus 4.8",
+		api: "anthropic-messages",
+		provider: "test-anthropic",
+		baseUrl,
+		reasoning: true,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200000,
+		maxTokens: 32000,
+		compat: { forceAdaptiveThinking: true, ...compat },
+	};
+}
+
+const tool: Tool = {
+	name: "lookup",
+	description: "Look up a value",
+	parameters: Type.Object({ value: Type.String() }),
+};
+
+const schemaCompatibilityTool: Tool = {
+	...tool,
+	parameters: Type.Object({ value: Type.String() }, { additionalProperties: false, title: "LookupInput" }),
+};
+
+const strictTool: Tool = {
+	...tool,
+	parameters: Type.Object(
+		{ value: Type.String(), optional: Type.Optional(Type.Number()) },
+		{ title: "StrictLookupInput" },
+	),
+	constrainedSampling: { type: "json_schema", strict: "prefer" },
+};
+
+function createContext(tools: Tool[] = [tool]): Context {
+	return {
+		messages: [{ role: "user", content: "Use the tool", timestamp: Date.now() }],
+		...(tools.length > 0 ? { tools } : {}),
+	};
+}
+
+async function readRequestBody(request: IncomingMessage): Promise<Record<string, unknown>> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of request) {
+		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	}
+	return JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown>;
+}
+
+function writeEmptySseResponse(response: ServerResponse): void {
+	response.writeHead(200, { "content-type": "text/event-stream" });
+	response.end();
+}
+
+async function captureAnthropicRequest(
+	compat: Model<"anthropic-messages">["compat"],
+	context: Context,
+): Promise<CapturedRequest> {
+	let capturedRequest: CapturedRequest | undefined;
+
+	const server = createServer(async (request, response) => {
+		capturedRequest = {
+			headers: request.headers,
+			body: await readRequestBody(request),
+		};
+		writeEmptySseResponse(response);
+	});
+
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address() as AddressInfo;
+
+	try {
+		const stream = streamAnthropic(createModel(`http://127.0.0.1:${address.port}`, compat), context, {
+			apiKey: "test-key",
+			cacheRetention: "none",
+		});
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+	} finally {
+		await new Promise<void>((resolve, reject) => {
+			server.close((error) => (error ? reject(error) : resolve()));
+		});
+	}
+
+	if (!capturedRequest) {
+		throw new Error("Anthropic request was not captured");
+	}
+	return capturedRequest;
+}
+
+function getFirstTool(body: Record<string, unknown>): Record<string, unknown> {
+	const tools = body.tools;
+	if (!Array.isArray(tools) || typeof tools[0] !== "object" || tools[0] === null) {
+		throw new Error("Expected first tool in request body");
+	}
+	return tools[0] as Record<string, unknown>;
+}
+
+function getFirstToolInputSchema(body: Record<string, unknown>): Record<string, unknown> {
+	const inputSchema = getFirstTool(body).input_schema;
+	if (typeof inputSchema !== "object" || inputSchema === null || Array.isArray(inputSchema)) {
+		throw new Error("Expected first tool input schema in request body");
+	}
+	return inputSchema as Record<string, unknown>;
+}
+
+describe("Anthropic eager tool input streaming compatibility", () => {
+	it("sends per-tool eager_input_streaming by default", async () => {
+		const request = await captureAnthropicRequest(undefined, createContext());
+
+		expect(getFirstTool(request.body).eager_input_streaming).toBe(true);
+		expect(request.headers["anthropic-beta"]).toBeUndefined();
+	});
+
+	it("uses the legacy fine-grained tool streaming beta when eager tool input streaming is disabled", async () => {
+		const request = await captureAnthropicRequest({ supportsEagerToolInputStreaming: false }, createContext());
+
+		expect(getFirstTool(request.body).eager_input_streaming).toBeUndefined();
+		expect(request.headers["anthropic-beta"]).toBe("fine-grained-tool-streaming-2025-05-14");
+	});
+
+	it("does not send the legacy fine-grained tool streaming beta when there are no tools", async () => {
+		const request = await captureAnthropicRequest({ supportsEagerToolInputStreaming: false }, createContext([]));
+
+		expect(request.body.tools).toBeUndefined();
+		expect(request.headers["anthropic-beta"]).toBeUndefined();
+	});
+
+	it("only sends the full input schema for strict JSON-schema tools", async () => {
+		const legacyRequest = await captureAnthropicRequest(
+			{ supportsStrictTools: true },
+			createContext([schemaCompatibilityTool]),
+		);
+		const parameters = schemaCompatibilityTool.parameters as { properties?: unknown; required?: unknown };
+		expect(getFirstToolInputSchema(legacyRequest.body)).toEqual({
+			type: "object",
+			properties: parameters.properties,
+			required: parameters.required,
+		});
+
+		const strictRequest = await captureAnthropicRequest({ supportsStrictTools: true }, createContext([strictTool]));
+		expect(getFirstTool(strictRequest.body).strict).toBe(true);
+		expect(getFirstToolInputSchema(strictRequest.body)).toMatchObject({
+			additionalProperties: false,
+			required: ["value", "optional"],
+			properties: { optional: { anyOf: [{ type: "number" }, { type: "null" }] } },
+			title: "StrictLookupInput",
+		});
+	});
+});

packages/ai/test/bedrock-convert-messages.test.ts

@@ -0,0 +1,410 @@
+import { Type } from "typebox";
+import { describe, expect, it, vi } from "vitest";
+
+const bedrockMock = vi.hoisted(() => ({
+	constructorCalls: [] as Array<Record<string, unknown>>,
+	streamEvents: undefined as unknown[] | undefined,
+}));
+
+vi.mock("@aws-sdk/client-bedrock-runtime", () => {
+	class BedrockRuntimeServiceException extends Error {}
+
+	class BedrockRuntimeClient {
+		constructor(config: Record<string, unknown>) {
+			bedrockMock.constructorCalls.push(config);
+		}
+
+		send(): Promise<unknown> {
+			if (bedrockMock.streamEvents) {
+				const events = bedrockMock.streamEvents;
+				return Promise.resolve({
+					$metadata: { httpStatusCode: 200 },
+					stream: (async function* () {
+						yield* events;
+					})(),
+				});
+			}
+			return Promise.reject(new Error("mock send"));
+		}
+	}
+
+	class ConverseStreamCommand {
+		readonly input: unknown;
+
+		constructor(input: unknown) {
+			this.input = input;
+		}
+	}
+
+	return {
+		BedrockRuntimeClient,
+		BedrockRuntimeServiceException,
+		ConverseStreamCommand,
+		StopReason: {
+			END_TURN: "end_turn",
+			STOP_SEQUENCE: "stop_sequence",
+			MAX_TOKENS: "max_tokens",
+			MODEL_CONTEXT_WINDOW_EXCEEDED: "model_context_window_exceeded",
+			TOOL_USE: "tool_use",
+		},
+		CachePointType: { DEFAULT: "default" },
+		CacheTTL: { ONE_HOUR: "ONE_HOUR" },
+		ConversationRole: { ASSISTANT: "assistant", USER: "user" },
+		ImageFormat: { JPEG: "jpeg", PNG: "png", GIF: "gif", WEBP: "webp" },
+		ToolResultStatus: { ERROR: "error", SUCCESS: "success" },
+	};
+});
+
+import { stream as streamBedrock } from "../src/api/bedrock-converse-stream.ts";
+import type { Context, Message, Model } from "../src/types.ts";
+
+const baseModel: Model<"bedrock-converse-stream"> = {
+	id: "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+	name: "Claude Sonnet 4.5 (US)",
+	api: "bedrock-converse-stream",
+	provider: "amazon-bedrock",
+	baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
+	reasoning: true,
+	input: ["text", "image"],
+	cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+	contextWindow: 200000,
+	maxTokens: 64000,
+	compat: { supportsStrictMode: true },
+};
+
+const novaModel: Model<"bedrock-converse-stream"> = {
+	...baseModel,
+	id: "amazon.nova-lite-v1:0",
+	name: "Nova Lite",
+	reasoning: false,
+	compat: undefined,
+};
+
+async function capturePayload(context: Context, model = baseModel): Promise<unknown> {
+	let capturedPayload: unknown;
+	const s = streamBedrock(model, context, {
+		cacheRetention: "none",
+		signal: AbortSignal.abort(),
+		onPayload: (payload) => {
+			capturedPayload = payload;
+			return payload;
+		},
+	});
+	for await (const event of s) {
+		if (event.type === "error") break;
+	}
+	return capturedPayload;
+}
+
+describe("Bedrock constrained sampling", () => {
+	it("gates native strict tool use by model capability", async () => {
+		const context: Context = {
+			messages: [{ role: "user", content: "Use the tool", timestamp: Date.now() }],
+			tools: [
+				{
+					name: "lookup",
+					description: "Look up a value",
+					parameters: Type.Object({ value: Type.String() }),
+					constrainedSampling: { type: "json_schema", strict: "require" },
+				},
+			],
+		};
+		const payload = await capturePayload(context);
+		const toolConfig = (payload as { toolConfig: { tools: Array<{ toolSpec: { strict?: boolean } }> } }).toolConfig;
+		expect(toolConfig.tools[0].toolSpec.strict).toBe(true);
+
+		context.tools![0].constrainedSampling = { type: "json_schema", strict: "prefer" };
+		const novaPayload = await capturePayload(context, novaModel);
+		const novaToolConfig = (
+			novaPayload as {
+				toolConfig: { tools: Array<{ toolSpec: { strict?: boolean } }> };
+			}
+		).toolConfig;
+		expect(novaToolConfig.tools[0].toolSpec.strict).toBeUndefined();
+	});
+});
+
+describe("Bedrock tool arguments", () => {
+	it("preserves empty property names in streamed tool arguments", async () => {
+		bedrockMock.streamEvents = [
+			{ messageStart: { role: "assistant" } },
+			{
+				contentBlockStart: {
+					contentBlockIndex: 0,
+					start: { toolUse: { toolUseId: "tool-1", name: "edit" } },
+				},
+			},
+			{
+				contentBlockDelta: {
+					contentBlockIndex: 0,
+					delta: {
+						toolUse: {
+							input: '{"path":"/workspace/foobar/file.js","edits":[{"oldText":"first","newText":"updated first"},{"oldText":"second","newText":"updated second","":""}]}',
+						},
+					},
+				},
+			},
+			{ contentBlockStop: { contentBlockIndex: 0 } },
+			{ messageStop: { stopReason: "tool_use" } },
+		];
+
+		try {
+			const message = await streamBedrock(
+				baseModel,
+				{ messages: [{ role: "user", content: "Use the tool", timestamp: Date.now() }] },
+				{ cacheRetention: "none" },
+			).result();
+
+			expect(message.content[0]).toEqual({
+				type: "toolCall",
+				id: "tool-1",
+				name: "edit",
+				arguments: {
+					path: "/workspace/foobar/file.js",
+					edits: [
+						{ oldText: "first", newText: "updated first" },
+						{ oldText: "second", newText: "updated second", "": "" },
+					],
+				},
+			});
+		} finally {
+			bedrockMock.streamEvents = undefined;
+		}
+	});
+});
+
+describe("bedrock convertMessages skips unknown content types", () => {
+	it("skips unknown user content blocks instead of throwing", async () => {
+		const messages: Message[] = [
+			{
+				role: "user",
+				content: [
+					{ type: "text", text: "hello" },
+					{ type: "unknown", data: "foo" },
+				] as any,
+				timestamp: Date.now(),
+			},
+		];
+		const payload = await capturePayload({ messages });
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content).toHaveLength(1);
+		expect(p.messages[0].content[0]).toEqual({ text: "hello" });
+	});
+
+	it("skips unknown assistant content blocks instead of throwing", async () => {
+		const messages: Message[] = [
+			{
+				role: "assistant",
+				content: [
+					{ type: "text", text: "hello" },
+					{ type: "unknown", data: "foo" },
+				] as any,
+				api: "bedrock-converse-stream",
+				provider: "amazon-bedrock",
+				model: baseModel.id,
+				usage: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					totalTokens: 0,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+				stopReason: "stop",
+				timestamp: Date.now(),
+			},
+		];
+		const payload = await capturePayload({ messages });
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content).toHaveLength(1);
+		expect(p.messages[0].content[0]).toEqual({ text: "hello" });
+	});
+
+	it("replaces user messages with only unknown content blocks with a placeholder", async () => {
+		const messages: Message[] = [
+			{
+				role: "user",
+				content: [{ type: "unknown", data: "foo" }] as any,
+				timestamp: Date.now(),
+			},
+		];
+		const payload = await capturePayload({ messages });
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content).toEqual([{ text: "<empty>" }]);
+	});
+
+	it("replaces blank user string content with a placeholder", async () => {
+		const payload = await capturePayload({
+			messages: [{ role: "user", content: "   ", timestamp: Date.now() }],
+		});
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content).toEqual([{ text: "<empty>" }]);
+	});
+
+	it("filters blank user text blocks when other content remains", async () => {
+		const payload = await capturePayload({
+			messages: [
+				{
+					role: "user",
+					content: [
+						{ type: "text", text: "" },
+						{ type: "text", text: "hello" },
+					],
+					timestamp: Date.now(),
+				},
+			],
+		});
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content).toEqual([{ text: "hello" }]);
+	});
+
+	it("replaces user content emptied by surrogate sanitization with a placeholder", async () => {
+		const payload = await capturePayload({
+			messages: [{ role: "user", content: String.fromCharCode(0xd83d), timestamp: Date.now() }],
+		});
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content).toEqual([{ text: "<empty>" }]);
+	});
+
+	it("skips assistant text blocks emptied by surrogate sanitization", async () => {
+		const messages: Message[] = [
+			{
+				role: "assistant",
+				content: [{ type: "text", text: String.fromCharCode(0xd83d) }],
+				api: "bedrock-converse-stream",
+				provider: "amazon-bedrock",
+				model: baseModel.id,
+				usage: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					totalTokens: 0,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+				stopReason: "stop",
+				timestamp: Date.now(),
+			},
+		];
+		const payload = await capturePayload({ messages });
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(0);
+	});
+
+	it("replaces blank tool result content with a placeholder", async () => {
+		const messages: Message[] = [
+			{
+				role: "toolResult",
+				toolCallId: "tool-1",
+				toolName: "tool",
+				content: [{ type: "text", text: "" }],
+				isError: false,
+				timestamp: Date.now(),
+			},
+		];
+		const payload = await capturePayload({ messages });
+		expect(payload).toBeDefined();
+		const p = payload as {
+			messages: Array<{ role: string; content: Array<{ toolResult: { content: unknown[] } }> }>;
+		};
+		expect(p.messages).toHaveLength(1);
+		expect(p.messages[0].content[0].toolResult.content).toEqual([{ text: "<empty>" }]);
+	});
+
+	it("skips assistant messages with only unknown content blocks", async () => {
+		const messages: Message[] = [
+			{
+				role: "assistant",
+				content: [{ type: "unknown", data: "foo" }] as any,
+				api: "bedrock-converse-stream",
+				provider: "amazon-bedrock",
+				model: baseModel.id,
+				usage: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					totalTokens: 0,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+				stopReason: "stop",
+				timestamp: Date.now(),
+			},
+		];
+		const payload = await capturePayload({ messages });
+		expect(payload).toBeDefined();
+		const p = payload as { messages: Array<{ role: string; content: unknown[] }> };
+		expect(p.messages).toHaveLength(0);
+	});
+
+	it("removes empty property names only from replayed Bedrock input", async () => {
+		const toolArguments = {
+			path: "/workspace/foobar/file.js",
+			edits: [
+				{ oldText: "first", newText: "updated first" },
+				{ oldText: "second", newText: "updated second", "": "" },
+			],
+		};
+		const messages: Message[] = [
+			{
+				role: "assistant",
+				content: [
+					{
+						type: "toolCall",
+						id: "tool-1",
+						name: "edit",
+						arguments: toolArguments,
+					},
+				],
+				api: "bedrock-converse-stream",
+				provider: "amazon-bedrock",
+				model: baseModel.id,
+				usage: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					totalTokens: 0,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+				stopReason: "toolUse",
+				timestamp: Date.now(),
+			},
+			{
+				role: "toolResult",
+				toolCallId: "tool-1",
+				toolName: "edit",
+				content: [{ type: "text", text: "done" }],
+				isError: false,
+				timestamp: Date.now(),
+			},
+			{ role: "user", content: "Continue", timestamp: Date.now() },
+		];
+
+		const payload = await capturePayload({ messages });
+		const p = payload as {
+			messages: Array<{ content: Array<{ toolUse?: { input: unknown } }> }>;
+		};
+		expect(p.messages[0].content[0].toolUse?.input).toEqual({
+			path: "/workspace/foobar/file.js",
+			edits: [
+				{ oldText: "first", newText: "updated first" },
+				{ oldText: "second", newText: "updated second" },
+			],
+		});
+		expect(toolArguments.edits[1]).toEqual({ oldText: "second", newText: "updated second", "": "" });
+	});
+});

packages/ai/test/bedrock-error-metadata.test.ts

@@ -0,0 +1,212 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type SendResult = { kind: "reject"; error: unknown } | { kind: "resolve"; response: unknown };
+
+const bedrockMock = vi.hoisted(() => ({
+	send: undefined as SendResult | undefined,
+	// Exposed so tests can build errors that are real instances of the mocked base class.
+	ServiceException: undefined as unknown as new (message?: string) => Error,
+}));
+
+vi.mock("@aws-sdk/client-bedrock-runtime", () => {
+	class BedrockRuntimeServiceException extends Error {}
+	bedrockMock.ServiceException = BedrockRuntimeServiceException;
+
+	class BedrockRuntimeClient {
+		middlewareStack = { add: () => {} };
+
+		send(): Promise<unknown> {
+			const outcome = bedrockMock.send;
+			if (!outcome) return Promise.reject(new Error("test did not configure a send outcome"));
+			return outcome.kind === "reject" ? Promise.reject(outcome.error) : Promise.resolve(outcome.response);
+		}
+	}
+
+	class ConverseStreamCommand {
+		readonly input: unknown;
+		constructor(input: unknown) {
+			this.input = input;
+		}
+	}
+
+	return {
+		BedrockRuntimeClient,
+		BedrockRuntimeServiceException,
+		ConverseStreamCommand,
+		StopReason: {
+			END_TURN: "end_turn",
+			STOP_SEQUENCE: "stop_sequence",
+			MAX_TOKENS: "max_tokens",
+			MODEL_CONTEXT_WINDOW_EXCEEDED: "model_context_window_exceeded",
+			TOOL_USE: "tool_use",
+		},
+		CachePointType: { DEFAULT: "default" },
+		CacheTTL: { ONE_HOUR: "ONE_HOUR" },
+		ConversationRole: { ASSISTANT: "assistant", USER: "user" },
+		ImageFormat: { JPEG: "jpeg", PNG: "png", GIF: "gif", WEBP: "webp" },
+		ToolResultStatus: { ERROR: "error", SUCCESS: "success" },
+	};
+});
+
+import { stream as streamBedrock } from "../src/api/bedrock-converse-stream.ts";
+import { getModel } from "../src/compat.ts";
+import type { AssistantMessage, Context, Model } from "../src/types.ts";
+import type { AssistantMessageDiagnostic } from "../src/utils/diagnostics.ts";
+
+const DIAGNOSTIC_TYPE = "bedrock_response_failure";
+const VALIDATION_MESSAGE = "The provided model identifier is invalid.";
+const REQUEST_ID = "11111111-2222-3333-4444-555555555555";
+
+const context: Context = {
+	messages: [{ role: "user", content: "hello", timestamp: Date.now() }],
+};
+
+function getModelFixture(): Model<"bedrock-converse-stream"> {
+	return getModel("amazon-bedrock", "us.anthropic.claude-opus-4-8");
+}
+
+/** What the SDK's `handleError` path throws for a non-2xx response; `name` is the modeled AWS error code. */
+function makeServiceException(name: string, extra: Record<string, unknown> = {}): Error {
+	const error = new bedrockMock.ServiceException(VALIDATION_MESSAGE) as Error & Record<string, unknown>;
+	error.name = name;
+	Object.assign(error, extra);
+	return error;
+}
+
+/** Fails after `messageStart`, throwing from inside the iterator like `getMessageUnmarshaller` does. */
+function respondWithFailingStream(thrown: unknown): SendResult {
+	return {
+		kind: "resolve",
+		response: {
+			$metadata: { httpStatusCode: 200, requestId: REQUEST_ID },
+			stream: (async function* () {
+				yield { messageStart: { role: "assistant" } };
+				throw thrown;
+			})(),
+		},
+	};
+}
+
+async function runBedrock(signal?: AbortSignal): Promise<AssistantMessage> {
+	return streamBedrock(getModelFixture(), context, { cacheRetention: "none", signal }).result();
+}
+
+function findDiagnostic(message: AssistantMessage): AssistantMessageDiagnostic | undefined {
+	return message.diagnostics?.find((d) => d.type === DIAGNOSTIC_TYPE);
+}
+
+beforeEach(() => {
+	bedrockMock.send = undefined;
+});
+
+describe("bedrock failure diagnostics", () => {
+	it("records status, error code and request id for a non-2xx from client.send()", async () => {
+		bedrockMock.send = {
+			kind: "reject",
+			error: makeServiceException("ValidationException", {
+				$metadata: { httpStatusCode: 400, requestId: REQUEST_ID },
+			}),
+		};
+
+		const message = await runBedrock();
+		const diagnostic = findDiagnostic(message);
+
+		expect(message.stopReason).toBe("error");
+		expect(diagnostic?.details).toEqual({ status: 400, errorCode: "ValidationException", requestId: REQUEST_ID });
+		expect(diagnostic?.error).toBeUndefined();
+		expect(Object.keys(diagnostic ?? {}).sort()).toEqual(["details", "timestamp", "type"]);
+	});
+
+	it("leaves errorMessage untouched so retry classification is unaffected", async () => {
+		bedrockMock.send = {
+			kind: "reject",
+			error: makeServiceException("ValidationException", {
+				$metadata: { httpStatusCode: 400, requestId: REQUEST_ID },
+				$response: { body: { pipe: () => {} } },
+			}),
+		};
+
+		expect((await runBedrock()).errorMessage).toBe(`Validation error: ${VALIDATION_MESSAGE}`);
+	});
+
+	it("reports only the request id for a modeled mid-stream exception", async () => {
+		// The SDK throws a bare object literal here, so the code is genuinely unavailable.
+		bedrockMock.send = respondWithFailingStream({ message: "Too many requests, please wait." });
+
+		const message = await runBedrock();
+
+		expect(message.stopReason).toBe("error");
+		expect(findDiagnostic(message)?.details).toEqual({ requestId: REQUEST_ID });
+	});
+
+	it("captures the error code for an unmodeled mid-stream error", async () => {
+		// This branch throws a real `Error` named after the frame's `:error-code`.
+		const unmodeled = new Error("Model stream terminated unexpectedly.");
+		unmodeled.name = "ModelStreamErrorException";
+		bedrockMock.send = respondWithFailingStream(unmodeled);
+
+		expect(findDiagnostic(await runBedrock())?.details).toEqual({
+			errorCode: "ModelStreamErrorException",
+			requestId: REQUEST_ID,
+		});
+	});
+
+	it("does not report a transport failure name as a provider error code", async () => {
+		// Real `Error`s with informative names, but not AWS codes; modeled ones end in "Exception".
+		const timeout = new Error("Connection timed out after 1000 ms");
+		timeout.name = "TimeoutError";
+		bedrockMock.send = respondWithFailingStream(timeout);
+
+		expect(findDiagnostic(await runBedrock())?.details).toEqual({ requestId: REQUEST_ID });
+	});
+
+	it("emits no diagnostic when the failure carries no provider metadata", async () => {
+		bedrockMock.send = { kind: "reject", error: new Error("socket hang up") };
+
+		const message = await runBedrock();
+
+		expect(message.stopReason).toBe("error");
+		expect(message.errorMessage).toBe("socket hang up");
+		expect(findDiagnostic(message)).toBeUndefined();
+	});
+
+	it("emits no diagnostic for an aborted turn", async () => {
+		const controller = new AbortController();
+		controller.abort();
+		bedrockMock.send = {
+			kind: "reject",
+			error: makeServiceException("ValidationException", {
+				$metadata: { httpStatusCode: 400, requestId: REQUEST_ID },
+			}),
+		};
+
+		const message = await runBedrock(controller.signal);
+
+		expect(message.stopReason).toBe("aborted");
+		expect(findDiagnostic(message)).toBeUndefined();
+	});
+
+	it("drops header-derived values that exceed the length bound", async () => {
+		bedrockMock.send = {
+			kind: "reject",
+			error: makeServiceException(`${"E".repeat(5000)}Exception`, {
+				$metadata: { httpStatusCode: 400, requestId: "R".repeat(5000) },
+			}),
+		};
+
+		expect(findDiagnostic(await runBedrock())?.details).toEqual({ status: 400 });
+	});
+
+	it("omits the SDK's Unknown placeholder instead of reporting it as a code", async () => {
+		// The SDK's fallback when the response carried no `x-amzn-errortype`.
+		bedrockMock.send = {
+			kind: "reject",
+			error: makeServiceException("Unknown", { $metadata: { httpStatusCode: 403, requestId: REQUEST_ID } }),
+		};
+
+		expect(findDiagnostic(await runBedrock())?.details).toEqual({
+			status: 403,
+			requestId: REQUEST_ID,
+		});
+	});
+});

packages/ai/test/cloudflare-stream.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { cloudflareStreams } from "../src/providers/cloudflare-stream.ts";
+import type { Api, Context, Model } from "../src/types.ts";
+import { AssistantMessageEventStream } from "../src/utils/event-stream.ts";
+
+const model: Model<Api> = {
+	id: "model",
+	name: "model",
+	api: "openai-completions",
+	provider: "cloudflare-ai-gateway",
+	baseUrl: "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai",
+	reasoning: false,
+	input: ["text"],
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	contextWindow: 1000,
+	maxTokens: 100,
+};
+
+const context: Context = { messages: [] };
+
+describe("Cloudflare provider streams", () => {
+	it("materializes the model endpoint before dispatch", () => {
+		const captured: string[] = [];
+		const streams = cloudflareStreams({
+			stream: (requestModel) => {
+				captured.push(requestModel.baseUrl);
+				return new AssistantMessageEventStream();
+			},
+			streamSimple: (requestModel) => {
+				captured.push(requestModel.baseUrl);
+				return new AssistantMessageEventStream();
+			},
+		});
+		const env = {
+			CLOUDFLARE_ACCOUNT_ID: "account",
+			CLOUDFLARE_GATEWAY_ID: "gateway",
+		};
+
+		streams.stream(model, context, { env });
+		streams.streamSimple(model, context, { env });
+
+		expect(captured).toEqual([
+			"https://gateway.ai.cloudflare.com/v1/account/gateway/openai",
+			"https://gateway.ai.cloudflare.com/v1/account/gateway/openai",
+		]);
+	});
+
+	it("keeps placeholders when the provider env does not resolve them", () => {
+		let captured: string | undefined;
+		const streams = cloudflareStreams({
+			stream: (requestModel) => {
+				captured = requestModel.baseUrl;
+				return new AssistantMessageEventStream();
+			},
+			streamSimple: (requestModel) => {
+				captured = requestModel.baseUrl;
+				return new AssistantMessageEventStream();
+			},
+		});
+
+		streams.streamSimple(model, context, {});
+
+		expect(captured).toBe(model.baseUrl);
+	});
+});

packages/ai/test/error-body.test.ts

@@ -0,0 +1,226 @@
+// Unit tests for the shared provider error-body normalizer.
+//
+// See issues/provider-error-body-passthrough. These cover one synthesized error
+// object per SDK shape (Mistral, openai APIError, @google/genai ApiError, AWS
+// Bedrock ServiceException), plus the non-Error fallback, truncation, the empty
+// parsed-body edge case, and the formatProviderError compose helper.
+
+import { describe, expect, it } from "vitest";
+import { formatProviderError, MAX_PROVIDER_ERROR_BODY_CHARS, normalizeProviderError } from "../src/utils/error-body.ts";
+
+describe("normalizeProviderError", () => {
+	it("extracts status and body from a Mistral-shaped error", () => {
+		const error = Object.assign(new Error("Mistral request failed"), {
+			statusCode: 403,
+			body: '{"error":"blocked by gateway WAF"}',
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.status).toBe(403);
+		expect(norm.body).toBe('{"error":"blocked by gateway WAF"}');
+		expect(norm.messageCarriesBody).toBe(false);
+	});
+
+	it("reads the parsed body off an openai APIError when the message is opaque", () => {
+		// makeMessage(status, error, message) yields "<status> status code (no body)"
+		// when the parsed body is unparsed, while the body stays on error.error.
+		const error = Object.assign(new Error("403 status code (no body)"), {
+			status: 403,
+			error: { error: "blocked by gateway WAF" },
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.status).toBe(403);
+		expect(norm.body).toBe('{"error":"blocked by gateway WAF"}');
+		expect(norm.messageCarriesBody).toBe(false);
+	});
+
+	it("preserves the message when @google/genai already folds the body into it", () => {
+		const body = { error: { code: 403, message: "Permission denied" } };
+		const error = Object.assign(new Error(JSON.stringify(body)), {
+			status: 403,
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.status).toBe(403);
+		expect(norm.messageCarriesBody).toBe(true);
+		expect(norm.message).toBe(JSON.stringify(body));
+	});
+
+	it("extracts status and body from a Bedrock-shaped ServiceException", () => {
+		const error = Object.assign(new Error("UnknownError"), {
+			name: "UnknownError",
+			$metadata: { httpStatusCode: 403 },
+			$response: { statusCode: 403, body: '{"message":"blocked by gateway WAF"}' },
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.status).toBe(403);
+		expect(norm.body).toBe('{"message":"blocked by gateway WAF"}');
+		expect(norm.messageCarriesBody).toBe(false);
+	});
+
+	it("ignores a Bedrock response stream instead of serializing its internals", () => {
+		const error = Object.assign(
+			new Error("Invocation of model ID anthropic.claude-opus-5 with on-demand throughput isn't supported."),
+			{
+				name: "ValidationException",
+				$metadata: { httpStatusCode: 400 },
+				$response: {
+					statusCode: 400,
+					body: { pipe: () => undefined, _events: { close: [null, null] } },
+				},
+			},
+		);
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.status).toBe(400);
+		expect(norm.body).toBeUndefined();
+		expect(norm.message).toContain("on-demand throughput isn't supported");
+		expect(norm.messageCarriesBody).toBe(true);
+	});
+
+	it("ignores a class-instance response body without a pipe method instead of serializing it", () => {
+		// Not every SDK response wrapper is a node stream: web ReadableStreams
+		// and SDK-specific wrapper classes have no `pipe`, but serializing them
+		// still yields internals-noise that would replace the real message.
+		class SdkHttpResponseBody {
+			locked = false;
+			state = { storedError: undefined };
+		}
+		const error = Object.assign(new Error("Input is too long for requested model."), {
+			name: "ValidationException",
+			$metadata: { httpStatusCode: 400 },
+			$response: { statusCode: 400, body: new SdkHttpResponseBody() },
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.status).toBe(400);
+		expect(norm.body).toBeUndefined();
+		expect(norm.message).toContain("Input is too long");
+		expect(norm.messageCarriesBody).toBe(true);
+	});
+
+	it("ignores a class-instance `error` field instead of serializing it", () => {
+		class SdkInnerError {
+			code = "EPROTO";
+			internalState = {};
+		}
+		const error = Object.assign(new Error("TLS handshake failed"), {
+			status: 502,
+			error: new SdkInnerError(),
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.body).toBeUndefined();
+		expect(norm.message).toBe("TLS handshake failed");
+		expect(norm.messageCarriesBody).toBe(true);
+	});
+
+	it("still surfaces a plain parsed JSON body object", () => {
+		const error = Object.assign(new Error("400 status code (no body)"), {
+			status: 400,
+			error: { message: "schema validation failed", field: "tools[0]" },
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.body).toBe('{"message":"schema validation failed","field":"tools[0]"}');
+		expect(norm.messageCarriesBody).toBe(false);
+	});
+
+	it("JSON-stringifies a non-Error thrown value", () => {
+		const norm = normalizeProviderError({ reason: "boom" });
+
+		expect(norm.status).toBeUndefined();
+		expect(norm.body).toBeUndefined();
+		expect(norm.message).toBe('{"reason":"boom"}');
+		expect(norm.messageCarriesBody).toBe(false);
+	});
+
+	it("treats an empty parsed body object as no body", () => {
+		const error = Object.assign(new Error("403 status code (no body)"), {
+			status: 403,
+			error: {},
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.body).toBeUndefined();
+		expect(norm.messageCarriesBody).toBe(true);
+	});
+
+	it("truncates the body at the cap", () => {
+		const longBody = "x".repeat(MAX_PROVIDER_ERROR_BODY_CHARS + 50);
+		const error = Object.assign(new Error("failed"), {
+			statusCode: 500,
+			body: longBody,
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.body).toContain("... [truncated 50 chars]");
+		expect(norm.body?.length).toBeLessThan(longBody.length);
+	});
+
+	it("sets messageCarriesBody when the message already contains the extracted body", () => {
+		const error = Object.assign(new Error("500: upstream exploded"), {
+			statusCode: 500,
+			body: "upstream exploded",
+		});
+
+		const norm = normalizeProviderError(error);
+
+		expect(norm.messageCarriesBody).toBe(true);
+	});
+});
+
+describe("formatProviderError", () => {
+	it("surfaces status and body without a prefix", () => {
+		const norm = normalizeProviderError(
+			Object.assign(new Error("403 status code (no body)"), {
+				status: 403,
+				error: { error: "blocked by gateway WAF" },
+			}),
+		);
+
+		const formatted = formatProviderError(norm);
+
+		expect(formatted).toContain("403");
+		expect(formatted).toContain("blocked by gateway WAF");
+		expect(formatted).not.toBe("403 status code (no body)");
+	});
+
+	it("applies a provider prefix with status and body", () => {
+		const norm = normalizeProviderError(
+			Object.assign(new Error("403 status code (no body)"), {
+				status: 403,
+				error: { error: "blocked by gateway WAF" },
+			}),
+		);
+
+		expect(formatProviderError(norm, "OpenAI API error")).toBe(
+			'OpenAI API error (403): {"error":"blocked by gateway WAF"}',
+		);
+	});
+
+	it("preserves the message (with prefix + status) when it already carries the body", () => {
+		const body = JSON.stringify({ error: { message: "Permission denied" } });
+		const norm = normalizeProviderError(Object.assign(new Error(body), { status: 403 }));
+
+		expect(formatProviderError(norm, "OpenAI API error")).toBe(`OpenAI API error (403): ${body}`);
+	});
+
+	it("returns the bare message for a non-Error value", () => {
+		const norm = normalizeProviderError({ reason: "boom" });
+
+		expect(formatProviderError(norm)).toBe('{"reason":"boom"}');
+	});
+});

packages/ai/test/fetch-option.test.ts

@@ -0,0 +1,178 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { streamSimple as streamAnthropic } from "../src/api/anthropic-messages.ts";
+import { streamSimple as streamAzureOpenAIResponses } from "../src/api/azure-openai-responses.ts";
+import { streamSimple as streamGoogleGenerativeAI } from "../src/api/google-generative-ai.ts";
+import { streamSimple as streamGoogleVertex } from "../src/api/google-vertex.ts";
+import { streamSimple as streamMistral } from "../src/api/mistral-conversations.ts";
+import { streamSimple as streamOpenAICodexResponses } from "../src/api/openai-codex-responses.ts";
+import { streamSimple as streamOpenAICompletions } from "../src/api/openai-completions.ts";
+import { streamSimple as streamOpenAIResponses } from "../src/api/openai-responses.ts";
+import { generateImages } from "../src/api/openrouter-images.ts";
+import { streamSimple as streamPiMessages } from "../src/api/pi-messages.ts";
+import type { Api, Context, FetchFunction, ImagesModel, Model } from "../src/types.ts";
+
+const context: Context = {
+	messages: [{ role: "user", content: "hello", timestamp: 1 }],
+};
+
+function createModel<TApi extends Api>(api: TApi): Model<TApi> {
+	return {
+		id: "test-model",
+		name: "Test Model",
+		api,
+		provider: "test-provider",
+		baseUrl: "https://upstream.test/v1",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 10_000,
+		maxTokens: 1_000,
+	};
+}
+
+function mockFetches() {
+	const fallback = vi.fn<FetchFunction>(async () => {
+		throw new Error("ambient fetch must not be called");
+	});
+	const custom = vi.fn<FetchFunction>(
+		async () =>
+			new Response(JSON.stringify({ error: { message: "upstream rejected request" } }), {
+				status: 401,
+				headers: { "content-type": "application/json" },
+			}),
+	);
+	vi.stubGlobal("fetch", fallback);
+	return { custom, fallback };
+}
+
+function expectOnlyCustomFetch(
+	custom: ReturnType<typeof vi.fn<FetchFunction>>,
+	fallback: ReturnType<typeof vi.fn<FetchFunction>>,
+) {
+	expect(custom).toHaveBeenCalled();
+	expect(fallback).not.toHaveBeenCalled();
+	expect(globalThis.fetch).toBe(fallback);
+}
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+describe("fetch stream option", () => {
+	it("passes fetch through streamSimple to the Anthropic SDK", async () => {
+		const { custom, fallback } = mockFetches();
+		await streamAnthropic(createModel("anthropic-messages"), context, {
+			apiKey: "test-key",
+			fetch: custom,
+			maxRetries: 0,
+		}).result();
+		expectOnlyCustomFetch(custom, fallback);
+	});
+
+	it("passes fetch through streamSimple to OpenAI SDK adapters", async () => {
+		const adapters = [
+			() =>
+				streamOpenAICompletions(createModel("openai-completions"), context, {
+					apiKey: "test-key",
+					fetch: custom,
+					maxRetries: 0,
+				}).result(),
+			() =>
+				streamOpenAIResponses(createModel("openai-responses"), context, {
+					apiKey: "test-key",
+					fetch: custom,
+					maxRetries: 0,
+				}).result(),
+			() =>
+				streamAzureOpenAIResponses(createModel("azure-openai-responses"), context, {
+					apiKey: "test-key",
+					fetch: custom,
+					maxRetries: 0,
+				}).result(),
+		];
+		const { custom, fallback } = mockFetches();
+		for (const run of adapters) {
+			await run();
+		}
+		expect(custom).toHaveBeenCalledTimes(adapters.length);
+		expect(fallback).not.toHaveBeenCalled();
+		expect(globalThis.fetch).toBe(fallback);
+	});
+
+	it("uses fetch for Mistral, Codex SSE, and pi-messages HTTP requests", async () => {
+		const { custom, fallback } = mockFetches();
+		await streamMistral(createModel("mistral-conversations"), context, {
+			apiKey: "test-key",
+			fetch: custom,
+		}).result();
+		await streamOpenAICodexResponses(createModel("openai-codex-responses"), context, {
+			apiKey: `header.${btoa(JSON.stringify({ "https://api.openai.com/auth": { chatgpt_account_id: "account" } }))}.signature`,
+			fetch: custom,
+			transport: "sse",
+			maxRetries: 0,
+		}).result();
+		await streamPiMessages(createModel("pi-messages"), context, {
+			apiKey: "test-key",
+			fetch: custom,
+		}).result();
+		expect(custom).toHaveBeenCalledTimes(3);
+		expect(fallback).not.toHaveBeenCalled();
+		expect(globalThis.fetch).toBe(fallback);
+	});
+
+	it("rejects custom fetch for Google adapters instead of silently bypassing it", async () => {
+		const { custom, fallback } = mockFetches();
+		const google = await streamGoogleGenerativeAI(createModel("google-generative-ai"), context, {
+			apiKey: "test-key",
+			fetch: custom,
+		}).result();
+		const vertex = await streamGoogleVertex(createModel("google-vertex"), context, {
+			apiKey: "test-key",
+			fetch: custom,
+		}).result();
+
+		expect(google.errorMessage).toContain("Custom fetch is not supported by the Google Generative AI adapter");
+		expect(vertex.errorMessage).toContain("Custom fetch is not supported by the Google Vertex adapter");
+		expect(custom).not.toHaveBeenCalled();
+		expect(fallback).not.toHaveBeenCalled();
+		expect(globalThis.fetch).toBe(fallback);
+	});
+
+	it("allows Google adapters to receive globalThis.fetch explicitly", async () => {
+		const ambient = vi.fn<FetchFunction>(
+			async () =>
+				new Response(JSON.stringify({ error: { message: "upstream rejected request" } }), {
+					status: 401,
+					headers: { "content-type": "application/json" },
+				}),
+		);
+		vi.stubGlobal("fetch", ambient);
+		const result = await streamGoogleGenerativeAI(createModel("google-generative-ai"), context, {
+			apiKey: "test-key",
+			fetch: ambient,
+		}).result();
+
+		expect(ambient).toHaveBeenCalledOnce();
+		expect(result.errorMessage).not.toContain("Custom fetch is not supported");
+		expect(globalThis.fetch).toBe(ambient);
+	});
+
+	it("uses fetch for image generation", async () => {
+		const { custom, fallback } = mockFetches();
+		const model: ImagesModel<"openrouter-images"> = {
+			...createModel("openrouter-images"),
+			provider: "openrouter",
+			output: ["image"],
+		};
+		await generateImages(
+			model,
+			{ input: [{ type: "text", text: "draw" }] },
+			{
+				apiKey: "test-key",
+				fetch: custom,
+				maxRetries: 0,
+			},
+		);
+		expectOnlyCustomFetch(custom, fallback);
+	});
+});

packages/ai/test/image-tool-result.test.ts

@@ -0,0 +1,550 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Type } from "typebox";
+import { describe, expect, it } from "vitest";
+import type { Api, Context, Model, Tool, ToolResultMessage } from "../src/compat.ts";
+import { complete, getModel } from "../src/compat.ts";
+import type { StreamOptions } from "../src/types.ts";
+
+type StreamOptionsWithExtras = StreamOptions & Record<string, unknown>;
+
+import { hasAzureOpenAICredentials, resolveAzureDeploymentName } from "./azure-utils.ts";
+import { hasBedrockCredentials } from "./bedrock-utils.ts";
+import { resolveApiKey } from "./oauth.ts";
+
+// Resolve OAuth tokens at module level (async, runs before tests)
+const oauthTokens = await Promise.all([
+	resolveApiKey("anthropic"),
+	resolveApiKey("github-copilot"),
+	resolveApiKey("openai-codex"),
+]);
+const [anthropicOAuthToken, githubCopilotToken, openaiCodexToken] = oauthTokens;
+
+/**
+ * Test that tool results containing only images work correctly across all providers.
+ * This verifies that:
+ * 1. Tool results can contain image content blocks
+ * 2. Providers correctly pass images from tool results to the LLM
+ * 3. The LLM can see and describe images returned by tools
+ */
+async function handleToolWithImageResult<TApi extends Api>(model: Model<TApi>, options?: StreamOptionsWithExtras) {
+	// Check if the model supports images
+	if (!model.input.includes("image")) {
+		console.log(`Skipping tool image result test - model ${model.id} doesn't support images`);
+		return;
+	}
+
+	// Read the test image
+	const imagePath = join(__dirname, "data", "red-circle.png");
+	const imageBuffer = readFileSync(imagePath);
+	const base64Image = imageBuffer.toString("base64");
+
+	// Define a tool that returns only an image (no text)
+	const getImageSchema = Type.Object({});
+	const getImageTool: Tool<typeof getImageSchema> = {
+		name: "get_circle",
+		description: "Returns a circle image for visualization",
+		parameters: getImageSchema,
+	};
+
+	const context: Context = {
+		systemPrompt: "You are a helpful assistant that uses tools when asked.",
+		messages: [
+			{
+				role: "user",
+				content: "Call the get_circle tool to get an image, and describe what you see, shapes, colors, etc.",
+				timestamp: Date.now(),
+			},
+		],
+		tools: [getImageTool],
+	};
+
+	// First request - LLM should call the tool
+	const firstResponse = await complete(model, context, options);
+	expect(firstResponse.stopReason).toBe("toolUse");
+
+	// Find the tool call
+	const toolCall = firstResponse.content.find((b) => b.type === "toolCall");
+	expect(toolCall).toBeTruthy();
+	if (!toolCall || toolCall.type !== "toolCall") {
+		throw new Error("Expected tool call");
+	}
+	expect(toolCall.name).toBe("get_circle");
+
+	// Add the tool call to context
+	context.messages.push(firstResponse);
+
+	// Create tool result with ONLY an image (no text)
+	const toolResult: ToolResultMessage = {
+		role: "toolResult",
+		toolCallId: toolCall.id,
+		toolName: toolCall.name,
+		content: [
+			{
+				type: "image",
+				data: base64Image,
+				mimeType: "image/png",
+			},
+		],
+		isError: false,
+		timestamp: Date.now(),
+	};
+
+	context.messages.push(toolResult);
+
+	// Second request - LLM should describe the image from the tool result
+	const secondResponse = await complete(model, context, options);
+	expect(secondResponse.stopReason).toBe("stop");
+	expect(secondResponse.errorMessage).toBeFalsy();
+
+	// Verify the LLM can see and describe the image
+	const textContent = secondResponse.content.find((b) => b.type === "text");
+	expect(textContent).toBeTruthy();
+	if (textContent && textContent.type === "text") {
+		const lowerContent = textContent.text.toLowerCase();
+		// Should mention red and circle since that's what the image shows
+		expect(lowerContent).toContain("red");
+		expect(lowerContent).toContain("circle");
+	}
+}
+
+/**
+ * Test that tool results containing both text and images work correctly across all providers.
+ * This verifies that:
+ * 1. Tool results can contain mixed content blocks (text + images)
+ * 2. Providers correctly pass both text and images from tool results to the LLM
+ * 3. The LLM can see both the text and images in tool results
+ */
+async function handleToolWithTextAndImageResult<TApi extends Api>(
+	model: Model<TApi>,
+	options?: StreamOptionsWithExtras,
+) {
+	// Check if the model supports images
+	if (!model.input.includes("image")) {
+		console.log(`Skipping tool text+image result test - model ${model.id} doesn't support images`);
+		return;
+	}
+
+	// Read the test image
+	const imagePath = join(__dirname, "data", "red-circle.png");
+	const imageBuffer = readFileSync(imagePath);
+	const base64Image = imageBuffer.toString("base64");
+
+	// Define a tool that returns both text and an image
+	const getImageSchema = Type.Object({});
+	const getImageTool: Tool<typeof getImageSchema> = {
+		name: "get_circle_with_description",
+		description: "Returns a circle image with a text description",
+		parameters: getImageSchema,
+	};
+
+	const context: Context = {
+		systemPrompt: "You are a helpful assistant that uses tools when asked.",
+		messages: [
+			{
+				role: "user",
+				content:
+					"Use the get_circle_with_description tool and tell me what you learned. Also say what color the shape is.",
+				timestamp: Date.now(),
+			},
+		],
+		tools: [getImageTool],
+	};
+
+	// First request - LLM should call the tool
+	const firstResponse = await complete(model, context, options);
+	expect(firstResponse.stopReason).toBe("toolUse");
+
+	// Find the tool call
+	const toolCall = firstResponse.content.find((b) => b.type === "toolCall");
+	expect(toolCall).toBeTruthy();
+	if (!toolCall || toolCall.type !== "toolCall") {
+		throw new Error("Expected tool call");
+	}
+	expect(toolCall.name).toBe("get_circle_with_description");
+
+	// Add the tool call to context
+	context.messages.push(firstResponse);
+
+	// Create tool result with BOTH text and image
+	const toolResult: ToolResultMessage = {
+		role: "toolResult",
+		toolCallId: toolCall.id,
+		toolName: toolCall.name,
+		content: [
+			{
+				type: "text",
+				text: "This is a geometric shape with specific properties: it has a diameter of 100 pixels.",
+			},
+			{
+				type: "image",
+				data: base64Image,
+				mimeType: "image/png",
+			},
+		],
+		isError: false,
+		timestamp: Date.now(),
+	};
+
+	context.messages.push(toolResult);
+
+	// Second request - LLM should describe both the text and image from the tool result
+	const secondResponse = await complete(model, context, options);
+	expect(secondResponse.stopReason).toBe("stop");
+	expect(secondResponse.errorMessage).toBeFalsy();
+
+	// Verify the LLM can see both text and image
+	const textContent = secondResponse.content.find((b) => b.type === "text");
+	expect(textContent).toBeTruthy();
+	if (textContent && textContent.type === "text") {
+		const lowerContent = textContent.text.toLowerCase();
+		// Should mention details from the text (diameter/pixels)
+		expect(lowerContent.match(/diameter|100|pixel/)).toBeTruthy();
+		// Should also mention the visual properties (red and circle)
+		expect(lowerContent).toContain("red");
+		expect(lowerContent).toContain("circle");
+	}
+}
+
+describe("Tool Results with Images", () => {
+	describe.skipIf(!process.env.GEMINI_API_KEY)("Google Provider (gemini-2.5-flash)", () => {
+		const llm = getModel("google", "gemini-2.5-flash");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.OPENAI_API_KEY)("OpenAI Completions Provider (gpt-4o-mini)", () => {
+		const { compat: _compat, ...baseModel } = getModel("openai", "gpt-4o-mini");
+		void _compat;
+		const llm: Model<"openai-completions"> = {
+			...baseModel,
+			api: "openai-completions",
+		};
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.OPENAI_API_KEY)("OpenAI Responses Provider (gpt-5-mini)", () => {
+		const llm = getModel("openai", "gpt-5-mini");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!hasAzureOpenAICredentials())("Azure OpenAI Responses Provider (gpt-4o-mini)", () => {
+		const llm = getModel("azure-openai-responses", "gpt-4o-mini");
+		const azureDeploymentName = resolveAzureDeploymentName(llm.id);
+		const azureOptions = azureDeploymentName ? { azureDeploymentName } : {};
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm, azureOptions);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm, azureOptions);
+		});
+	});
+
+	describe.skipIf(!process.env.ANTHROPIC_API_KEY)("Anthropic Provider (claude-haiku-4-5)", () => {
+		const model = getModel("anthropic", "claude-haiku-4-5");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(model);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(model);
+		});
+	});
+
+	describe.skipIf(!process.env.OPENROUTER_API_KEY)("OpenRouter Provider (glm-4.5v)", () => {
+		const llm = getModel("openrouter", "z-ai/glm-4.5v");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.MISTRAL_API_KEY)("Mistral Provider (pixtral-12b)", () => {
+		const llm = getModel("mistral", "pixtral-12b");
+
+		it("should handle tool result with only image", { retry: 5, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 5, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.TOGETHER_API_KEY)("Together AI Provider (Kimi-K2.6)", () => {
+		const llm = getModel("together", "moonshotai/Kimi-K2.6");
+		const options = { reasoningEffort: "high" } satisfies StreamOptionsWithExtras;
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm, options);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm, options);
+		});
+	});
+
+	describe.skipIf(!process.env.BASETEN_API_KEY)("Baseten Provider (Kimi-K2.6)", () => {
+		const llm = getModel("baseten", "moonshotai/Kimi-K2.6");
+		const options = { reasoningEffort: "high" } satisfies StreamOptionsWithExtras;
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm, options);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm, options);
+		});
+	});
+
+	describe.skipIf(!process.env.XIAOMI_API_KEY)("Xiaomi MiMo (API billing) Provider (mimo-v2.5-pro)", () => {
+		const llm = getModel("xiaomi", "mimo-v2.5-pro");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		// FIXME(xiaomi): when a tool_result contains both a descriptive text block
+		// and an image block, MiMo locks onto the text and ignores the image (it
+		// reports the text-derived diameter but never mentions the image's color).
+		// The image-only case above proves the image reaches the model, and the
+		// text-only path obviously works, so this is a multimodal-fusion quality
+		// issue in the model, not a transport bug. Re-enable when upstream model
+		// quality improves.
+		it.skip("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.XIAOMI_TOKEN_PLAN_CN_API_KEY)(
+		"Xiaomi MiMo Token Plan (CN) Provider (mimo-v2.5-pro)",
+		() => {
+			const llm = getModel("xiaomi-token-plan-cn", "mimo-v2.5-pro");
+
+			it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+				await handleToolWithImageResult(llm);
+			});
+
+			// FIXME(xiaomi): see the API-billing block above — same multimodal-fusion
+			// limitation applies to Token Plan endpoints (same model behind both).
+			it.skip("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+				await handleToolWithTextAndImageResult(llm);
+			});
+		},
+	);
+
+	describe.skipIf(!process.env.XIAOMI_TOKEN_PLAN_AMS_API_KEY)(
+		"Xiaomi MiMo Token Plan (AMS) Provider (mimo-v2.5-pro)",
+		() => {
+			const llm = getModel("xiaomi-token-plan-ams", "mimo-v2.5-pro");
+
+			it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+				await handleToolWithImageResult(llm);
+			});
+
+			// FIXME(xiaomi): see the API-billing block above — same multimodal-fusion
+			// limitation applies to Token Plan endpoints (same model behind both).
+			it.skip("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+				await handleToolWithTextAndImageResult(llm);
+			});
+		},
+	);
+
+	describe.skipIf(!process.env.XIAOMI_TOKEN_PLAN_SGP_API_KEY)(
+		"Xiaomi MiMo Token Plan (SGP) Provider (mimo-v2.5-pro)",
+		() => {
+			const llm = getModel("xiaomi-token-plan-sgp", "mimo-v2.5-pro");
+
+			it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+				await handleToolWithImageResult(llm);
+			});
+
+			// FIXME(xiaomi): see the API-billing block above — same multimodal-fusion
+			// limitation applies to Token Plan endpoints (same model behind both).
+			it.skip("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+				await handleToolWithTextAndImageResult(llm);
+			});
+		},
+	);
+
+	describe.skipIf(!process.env.QWEN_TOKEN_PLAN_API_KEY)("Qwen Token Plan Provider (qwen3.7-max)", () => {
+		const llm = getModel("qwen-token-plan", "qwen3.7-max");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.QWEN_TOKEN_PLAN_API_KEY)("Qwen Token Plan Individual Provider (qwen3.8-max)", () => {
+		const llm = getModel("qwen-token-plan-individual", "qwen3.8-max");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.QWEN_TOKEN_PLAN_CN_API_KEY)("Qwen Token Plan (CN) Provider (qwen3.7-max)", () => {
+		const llm = getModel("qwen-token-plan-cn", "qwen3.7-max");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.KIMI_API_KEY)("Kimi For Coding Provider (kimi-for-coding)", () => {
+		const llm = getModel("kimi-coding", "kimi-for-coding");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!process.env.AI_GATEWAY_API_KEY)("Vercel AI Gateway Provider (google/gemini-2.5-flash)", () => {
+		const llm = getModel("vercel-ai-gateway", "google/gemini-2.5-flash");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	describe.skipIf(!hasBedrockCredentials())("Amazon Bedrock Provider (claude-sonnet-4-5)", () => {
+		const llm = getModel("amazon-bedrock", "global.anthropic.claude-sonnet-4-5-20250929-v1:0");
+
+		it("should handle tool result with only image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithImageResult(llm);
+		});
+
+		it("should handle tool result with text and image", { retry: 3, timeout: 30000 }, async () => {
+			await handleToolWithTextAndImageResult(llm);
+		});
+	});
+
+	// =========================================================================
+	// OAuth-based providers (credentials from ~/.pi/agent/oauth.json)
+	// =========================================================================
+
+	describe("Anthropic OAuth Provider (claude-sonnet-4-5)", () => {
+		const model = getModel("anthropic", "claude-sonnet-4-5");
+
+		it.skipIf(!anthropicOAuthToken)(
+			"should handle tool result with only image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				await handleToolWithImageResult(model, { apiKey: anthropicOAuthToken });
+			},
+		);
+
+		it.skipIf(!anthropicOAuthToken)(
+			"should handle tool result with text and image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				await handleToolWithTextAndImageResult(model, { apiKey: anthropicOAuthToken });
+			},
+		);
+	});
+
+	describe("GitHub Copilot Provider", () => {
+		it.skipIf(!githubCopilotToken)(
+			"claude-haiku-4.5 - should handle tool result with only image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				const llm = getModel("github-copilot", "claude-haiku-4.5");
+				await handleToolWithImageResult(llm, { apiKey: githubCopilotToken });
+			},
+		);
+
+		it.skipIf(!githubCopilotToken)(
+			"claude-haiku-4.5 - should handle tool result with text and image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				const llm = getModel("github-copilot", "claude-haiku-4.5");
+				await handleToolWithTextAndImageResult(llm, { apiKey: githubCopilotToken });
+			},
+		);
+
+		it.skipIf(!githubCopilotToken)(
+			"claude-sonnet-4 - should handle tool result with only image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				const llm = getModel("github-copilot", "claude-sonnet-4.6");
+				await handleToolWithImageResult(llm, { apiKey: githubCopilotToken });
+			},
+		);
+
+		it.skipIf(!githubCopilotToken)(
+			"claude-sonnet-4 - should handle tool result with text and image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				const llm = getModel("github-copilot", "claude-sonnet-4.6");
+				await handleToolWithTextAndImageResult(llm, { apiKey: githubCopilotToken });
+			},
+		);
+	});
+
+	describe("OpenAI Codex Provider", () => {
+		it.skipIf(!openaiCodexToken)(
+			"gpt-5.5 - should handle tool result with only image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				const llm = getModel("openai-codex", "gpt-5.5");
+				await handleToolWithImageResult(llm, { apiKey: openaiCodexToken });
+			},
+		);
+
+		it.skipIf(!openaiCodexToken)(
+			"gpt-5.5 - should handle tool result with text and image",
+			{ retry: 3, timeout: 30000 },
+			async () => {
+				const llm = getModel("openai-codex", "gpt-5.5");
+				await handleToolWithTextAndImageResult(llm, { apiKey: openaiCodexToken });
+			},
+		);
+	});
+});

packages/ai/test/kimi-coding-oauth.test.ts

@@ -0,0 +1,270 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { kimiCodingOAuth } from "../src/auth/oauth/kimi-coding.ts";
+import type { ProviderAuthInteraction } from "../src/auth/types.ts";
+
+const CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098";
+const OAUTH_HOST = "https://auth.kimi.com";
+
+function jsonResponse(body: unknown, status: number = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+function getUrl(input: unknown): string {
+	if (typeof input === "string") return input;
+	if (input instanceof URL) return input.toString();
+	if (input instanceof Request) return input.url;
+	throw new Error(`Unsupported fetch input: ${String(input)}`);
+}
+
+function deviceAuthorizationResponse(overrides?: Record<string, unknown>): Response {
+	return jsonResponse({
+		user_code: "ABCD-1234",
+		device_code: "device-code-123",
+		verification_uri: "https://www.kimi.com/code",
+		verification_uri_complete: "https://www.kimi.com/code?user_code=ABCD-1234",
+		interval: 5,
+		expires_in: 600,
+		...overrides,
+	});
+}
+
+function createInteraction(events: Array<Record<string, unknown>>): ProviderAuthInteraction {
+	return {
+		signal: new AbortController().signal,
+		prompt: async () => {
+			throw new Error("Kimi Code login should not prompt");
+		},
+		notify: (event) => events.push(event),
+	};
+}
+
+describe("Kimi Code OAuth", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+		vi.unstubAllGlobals();
+		vi.unstubAllEnvs();
+		vi.useRealTimers();
+	});
+
+	it("logs in with the device authorization flow", async () => {
+		vi.useFakeTimers();
+		const startTime = new Date("2026-07-20T00:00:00Z");
+		vi.setSystemTime(startTime);
+
+		const events: Array<Record<string, unknown>> = [];
+		const pollResponses = [
+			jsonResponse({ error: "authorization_pending" }, 400),
+			jsonResponse({ access_token: "access-token", refresh_token: "refresh-token", expires_in: 3600 }),
+		];
+		const pollTimes: number[] = [];
+
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (input: unknown, init?: RequestInit): Promise<Response> => {
+				const url = getUrl(input);
+				if (url === `${OAUTH_HOST}/api/oauth/device_authorization`) {
+					expect(init?.method).toBe("POST");
+					expect(init?.headers).toMatchObject({
+						"Content-Type": "application/x-www-form-urlencoded",
+						Accept: "application/json",
+					});
+					expect(new URLSearchParams(String(init?.body)).get("client_id")).toBe(CLIENT_ID);
+					return deviceAuthorizationResponse();
+				}
+				if (url === `${OAUTH_HOST}/api/oauth/token`) {
+					pollTimes.push(Date.now());
+					const params = new URLSearchParams(String(init?.body));
+					expect(params.get("grant_type")).toBe("urn:ietf:params:oauth:grant-type:device_code");
+					expect(params.get("client_id")).toBe(CLIENT_ID);
+					expect(params.get("device_code")).toBe("device-code-123");
+					const response = pollResponses.shift();
+					if (!response) throw new Error("Unexpected extra token poll");
+					return response;
+				}
+				throw new Error(`Unexpected fetch URL: ${url}`);
+			}),
+		);
+
+		const credentialPromise = kimiCodingOAuth.login(createInteraction(events));
+		for (let i = 0; i < 5 && events.length === 0; i++) {
+			await vi.advanceTimersByTimeAsync(0);
+		}
+		expect(events).toEqual([
+			{
+				type: "device_code",
+				userCode: "ABCD-1234",
+				verificationUri: "https://www.kimi.com/code?user_code=ABCD-1234",
+				intervalSeconds: 5,
+				expiresInSeconds: 600,
+			},
+		]);
+
+		// waitBeforeFirstPoll: first poll happens after the 5s interval.
+		await vi.advanceTimersByTimeAsync(4999);
+		expect(pollTimes).toEqual([]);
+		await vi.advanceTimersByTimeAsync(1);
+		expect(pollTimes).toEqual([startTime.getTime() + 5000]);
+
+		await vi.advanceTimersByTimeAsync(5000);
+		await expect(credentialPromise).resolves.toEqual({
+			type: "oauth",
+			access: "access-token",
+			refresh: "refresh-token",
+			expires: startTime.getTime() + 10000 + 3600 * 1000,
+		});
+		expect(pollTimes).toEqual([startTime.getTime() + 5000, startTime.getTime() + 10000]);
+	});
+
+	it("fails when the device code expires", async () => {
+		vi.useFakeTimers();
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (input: unknown): Promise<Response> => {
+				const url = getUrl(input);
+				if (url === `${OAUTH_HOST}/api/oauth/device_authorization`) {
+					return deviceAuthorizationResponse();
+				}
+				if (url === `${OAUTH_HOST}/api/oauth/token`) {
+					return jsonResponse({ error: "expired_token" }, 400);
+				}
+				throw new Error(`Unexpected fetch URL: ${url}`);
+			}),
+		);
+
+		const credentialPromise = kimiCodingOAuth.login(createInteraction([]));
+		const assertion = expect(credentialPromise).rejects.toThrow("expired");
+		await vi.advanceTimersByTimeAsync(5000);
+		await assertion;
+	});
+
+	it("fails when the user denies the login", async () => {
+		vi.useFakeTimers();
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (input: unknown): Promise<Response> => {
+				const url = getUrl(input);
+				if (url === `${OAUTH_HOST}/api/oauth/device_authorization`) {
+					return deviceAuthorizationResponse();
+				}
+				if (url === `${OAUTH_HOST}/api/oauth/token`) {
+					return jsonResponse({ error: "access_denied" }, 400);
+				}
+				throw new Error(`Unexpected fetch URL: ${url}`);
+			}),
+		);
+
+		const credentialPromise = kimiCodingOAuth.login(createInteraction([]));
+		const assertion = expect(credentialPromise).rejects.toThrow("denied");
+		await vi.advanceTimersByTimeAsync(5000);
+		await assertion;
+	});
+
+	it("honors the KIMI_CODE_OAUTH_HOST override", async () => {
+		vi.useFakeTimers();
+		vi.stubEnv("KIMI_CODE_OAUTH_HOST", "https://auth.example.com/");
+
+		const urls: string[] = [];
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (input: unknown): Promise<Response> => {
+				const url = getUrl(input);
+				urls.push(url);
+				if (url === "https://auth.example.com/api/oauth/device_authorization") {
+					return deviceAuthorizationResponse({ interval: 1 });
+				}
+				if (url === "https://auth.example.com/api/oauth/token") {
+					return jsonResponse({ access_token: "a", refresh_token: "r", expires_in: 60 });
+				}
+				throw new Error(`Unexpected fetch URL: ${url}`);
+			}),
+		);
+
+		const credentialPromise = kimiCodingOAuth.login(createInteraction([]));
+		await vi.advanceTimersByTimeAsync(1000);
+		await expect(credentialPromise).resolves.toMatchObject({ access: "a", refresh: "r" });
+		expect(urls).toEqual([
+			"https://auth.example.com/api/oauth/device_authorization",
+			"https://auth.example.com/api/oauth/token",
+		]);
+	});
+
+	it("refreshes tokens and returns a Bearer header for requests", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (input: unknown, init?: RequestInit): Promise<Response> => {
+				const url = getUrl(input);
+				expect(url).toBe(`${OAUTH_HOST}/api/oauth/token`);
+				const params = new URLSearchParams(String(init?.body));
+				expect(params.get("grant_type")).toBe("refresh_token");
+				expect(params.get("refresh_token")).toBe("old-refresh");
+				expect(params.get("client_id")).toBe(CLIENT_ID);
+				return jsonResponse({ access_token: "new-access", refresh_token: "new-refresh", expires_in: 3600 });
+			}),
+		);
+
+		const before = Date.now();
+		const credential = await kimiCodingOAuth.refresh(
+			{
+				type: "oauth",
+				access: "old-access",
+				refresh: "old-refresh",
+				expires: before,
+			},
+			new AbortController().signal,
+		);
+		expect(credential).toEqual({
+			type: "oauth",
+			access: "new-access",
+			refresh: "new-refresh",
+			expires: expect.any(Number),
+		});
+		expect(credential.expires).toBeGreaterThanOrEqual(before + 3600 * 1000);
+
+		await expect(kimiCodingOAuth.toAuth(credential)).resolves.toEqual({
+			headers: { Authorization: "Bearer new-access" },
+		});
+	});
+
+	it("retries refresh on 429 and fails unauthorized on invalid_grant", async () => {
+		vi.useFakeTimers();
+
+		// 429 once, then success.
+		let calls = 0;
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (): Promise<Response> => {
+				calls += 1;
+				if (calls === 1) return jsonResponse({ error: "temporarily_unavailable" }, 429);
+				return jsonResponse({ access_token: "a", refresh_token: "r", expires_in: 60 });
+			}),
+		);
+
+		const refreshPromise = kimiCodingOAuth.refresh(
+			{
+				type: "oauth",
+				access: "old",
+				refresh: "old",
+				expires: 0,
+			},
+			new AbortController().signal,
+		);
+		await vi.advanceTimersByTimeAsync(1000);
+		await expect(refreshPromise).resolves.toMatchObject({ access: "a" });
+		expect(calls).toBe(2);
+
+		// invalid_grant is not retried.
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(async (): Promise<Response> => jsonResponse({ error: "invalid_grant" }, 400)),
+		);
+		await expect(
+			kimiCodingOAuth.refresh(
+				{ type: "oauth", access: "old", refresh: "old", expires: 0 },
+				new AbortController().signal,
+			),
+		).rejects.toThrow("unauthorized");
+	});
+});

packages/ai/test/mistral-raw-stop-reason.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { stream as streamMistral } from "../src/api/mistral-conversations.ts";
+import { getModel } from "../src/compat.ts";
+import type { Context, FetchFunction } from "../src/types.ts";
+
+const model = getModel("mistral", "devstral-medium-latest");
+const context: Context = {
+	messages: [{ role: "user", content: "hello", timestamp: Date.now() }],
+};
+
+function createFetch(finishReason: string): FetchFunction {
+	return async () =>
+		new Response(
+			`data: ${JSON.stringify({
+				id: "mistral-response-id",
+				model: model.id,
+				choices: [
+					{
+						index: 0,
+						finish_reason: finishReason,
+						delta: {},
+					},
+				],
+				usage: {
+					prompt_tokens: 1,
+					completion_tokens: 0,
+					total_tokens: 1,
+				},
+			})}\n\ndata: [DONE]\n\n`,
+			{ headers: { "content-type": "text/event-stream" } },
+		);
+}
+
+describe("Mistral raw stop reasons", () => {
+	it("preserves raw Mistral finish reasons for successful stops", async () => {
+		const message = await streamMistral(model, context, { apiKey: "test", fetch: createFetch("stop") }).result();
+
+		expect(message.stopReason).toBe("stop");
+		expect(message.rawStopReason).toBe("stop");
+		expect(message.errorMessage).toBeUndefined();
+	});
+
+	it("preserves raw Mistral finish reasons for provider error stops", async () => {
+		const message = await streamMistral(model, context, { apiKey: "test", fetch: createFetch("error") }).result();
+
+		expect(message.stopReason).toBe("error");
+		expect(message.rawStopReason).toBe("error");
+		expect(message.errorMessage).toBe("Provider stopped with: error");
+	});
+
+	it("treats unknown Mistral finish reasons as provider error stops", async () => {
+		const message = await streamMistral(model, context, {
+			apiKey: "test",
+			fetch: createFetch("unmapped_error"),
+		}).result();
+
+		expect(message.stopReason).toBe("error");
+		expect(message.rawStopReason).toBe("unmapped_error");
+		expect(message.errorMessage).toBe("Provider stopped with: unmapped_error");
+	});
+});

packages/ai/test/oauth.ts

@@ -0,0 +1,85 @@
+/**
+ * Test helper for resolving API keys from ~/.pi/agent/auth.json
+ *
+ * Supports both API key and OAuth credentials.
+ * OAuth tokens are automatically refreshed if expired and saved back to auth.json.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import type { OAuthCredentials } from "../src/auth/types.ts";
+import { builtinProviders } from "../src/providers/all.ts";
+
+const AUTH_PATH = join(homedir(), ".pi", "agent", "auth.json");
+
+type ApiKeyCredential = {
+	type: "api_key";
+	key: string;
+};
+
+type OAuthCredentialEntry = {
+	type: "oauth";
+} & OAuthCredentials;
+
+type AuthCredential = ApiKeyCredential | OAuthCredentialEntry;
+
+type AuthStorage = Record<string, AuthCredential>;
+
+function loadAuthStorage(): AuthStorage {
+	if (!existsSync(AUTH_PATH)) {
+		return {};
+	}
+	try {
+		const content = readFileSync(AUTH_PATH, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return {};
+	}
+}
+
+function saveAuthStorage(storage: AuthStorage): void {
+	const configDir = dirname(AUTH_PATH);
+	if (!existsSync(configDir)) {
+		mkdirSync(configDir, { recursive: true, mode: 0o700 });
+	}
+	writeFileSync(AUTH_PATH, JSON.stringify(storage, null, 2), "utf-8");
+	chmodSync(AUTH_PATH, 0o600);
+}
+
+/**
+ * Resolve API key for a provider from ~/.pi/agent/auth.json
+ *
+ * For API key credentials, returns the key directly.
+ * For OAuth credentials, returns the access token (refreshing if expired and saving back).
+ *
+ */
+export async function resolveApiKey(provider: string): Promise<string | undefined> {
+	const storage = loadAuthStorage();
+	const entry = storage[provider];
+
+	if (!entry) return undefined;
+
+	if (entry.type === "api_key") {
+		return entry.key;
+	}
+
+	if (entry.type === "oauth") {
+		const oauth = builtinProviders().find((candidate) => candidate.id === provider)?.auth.oauth;
+		if (!oauth) return undefined;
+		let credential = entry;
+		try {
+			if (Date.now() >= credential.expires) {
+				credential = await oauth.refresh(credential, new AbortController().signal);
+			}
+		} catch (error) {
+			console.log(JSON.stringify(error));
+			return undefined;
+		}
+		storage[provider] = credential;
+		saveAuthStorage(storage);
+		return (await oauth.toAuth(credential)).apiKey;
+	}
+
+	return undefined;
+}

packages/ai/test/openai-completions-prompt-cache.test.ts

@@ -0,0 +1,271 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { stream as streamOpenAICompletions } from "../src/api/openai-completions.ts";
+import { getModel } from "../src/compat.ts";
+import type { Model } from "../src/types.ts";
+
+interface FakeOpenAIClientOptions {
+	apiKey: string;
+	baseURL: string;
+	dangerouslyAllowBrowser: boolean;
+	defaultHeaders?: Record<string, string>;
+}
+
+interface CapturedCompletionsPayload {
+	prompt_cache_key?: string;
+	prompt_cache_retention?: "24h" | "in-memory" | null;
+	session_id?: string;
+}
+
+const mockState = vi.hoisted(() => ({
+	lastParams: undefined as CapturedCompletionsPayload | undefined,
+	lastClientOptions: undefined as FakeOpenAIClientOptions | undefined,
+}));
+
+vi.mock("openai", () => {
+	class FakeOpenAI {
+		chat = {
+			completions: {
+				create: (params: CapturedCompletionsPayload) => {
+					mockState.lastParams = params;
+					const stream = {
+						async *[Symbol.asyncIterator]() {
+							yield {
+								choices: [{ delta: {}, finish_reason: "stop" }],
+								usage: {
+									prompt_tokens: 1,
+									completion_tokens: 1,
+									prompt_tokens_details: { cached_tokens: 0 },
+									completion_tokens_details: { reasoning_tokens: 0 },
+								},
+							};
+						},
+					};
+					const promise = Promise.resolve(stream) as Promise<typeof stream> & {
+						withResponse: () => Promise<{
+							data: typeof stream;
+							response: { status: number; headers: Headers };
+						}>;
+					};
+					promise.withResponse = async () => ({
+						data: stream,
+						response: { status: 200, headers: new Headers() },
+					});
+					return promise;
+				},
+			},
+		};
+
+		constructor(options: FakeOpenAIClientOptions) {
+			mockState.lastClientOptions = options;
+		}
+	}
+
+	return { default: FakeOpenAI };
+});
+
+describe("openai-completions prompt caching", () => {
+	const originalEnv = process.env.PI_CACHE_RETENTION;
+
+	beforeEach(() => {
+		mockState.lastParams = undefined;
+		mockState.lastClientOptions = undefined;
+		delete process.env.PI_CACHE_RETENTION;
+	});
+
+	afterEach(() => {
+		if (originalEnv === undefined) {
+			delete process.env.PI_CACHE_RETENTION;
+		} else {
+			process.env.PI_CACHE_RETENTION = originalEnv;
+		}
+	});
+
+	function createModel(overrides: Partial<Model<"openai-completions">> = {}): Model<"openai-completions"> {
+		const { compat: _compat, ...baseModel } = getModel("openai", "gpt-4o-mini");
+		return {
+			...(baseModel as Omit<Model<"openai-completions">, "api">),
+			api: "openai-completions",
+			...overrides,
+		};
+	}
+
+	async function captureRequest(
+		options?: {
+			cacheRetention?: "none" | "short" | "long";
+			sessionId?: string;
+			headers?: Record<string, string>;
+		},
+		model: Model<"openai-completions"> = createModel(),
+	) {
+		await streamOpenAICompletions(
+			model,
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{ apiKey: "test-key", ...options },
+		).result();
+
+		return {
+			payload: mockState.lastParams,
+			headers: mockState.lastClientOptions?.defaultHeaders ?? {},
+		};
+	}
+
+	it("sets prompt_cache_key for direct OpenAI requests when caching is enabled", async () => {
+		const { payload } = await captureRequest({ sessionId: "session-123" });
+
+		expect(payload?.prompt_cache_key).toBe("session-123");
+		expect(payload?.prompt_cache_retention).toBeUndefined();
+	});
+
+	it("sets prompt_cache_retention to 24h for direct OpenAI requests when cacheRetention is long", async () => {
+		const { payload } = await captureRequest({ cacheRetention: "long", sessionId: "session-456" });
+
+		expect(payload?.prompt_cache_key).toBe("session-456");
+		expect(payload?.prompt_cache_retention).toBe("24h");
+	});
+
+	it("clamps prompt_cache_key to OpenAI's 64-character limit", async () => {
+		const sessionId = "x".repeat(67);
+		const { payload } = await captureRequest({ sessionId });
+
+		expect(payload?.prompt_cache_key).toBe("x".repeat(64));
+	});
+
+	it("omits prompt cache fields when cacheRetention is none", async () => {
+		const { payload } = await captureRequest({ cacheRetention: "none", sessionId: "session-789" });
+
+		expect(payload?.prompt_cache_key).toBeUndefined();
+		expect(payload?.prompt_cache_retention).toBeUndefined();
+	});
+
+	it("omits prompt cache fields for non-OpenAI base URLs without compatible long retention", async () => {
+		const model = createModel({
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { supportsLongCacheRetention: false },
+		});
+		const { payload } = await captureRequest({ cacheRetention: "long", sessionId: "session-proxy" }, model);
+
+		expect(payload?.prompt_cache_key).toBeUndefined();
+		expect(payload?.prompt_cache_retention).toBeUndefined();
+	});
+
+	it("uses PI_CACHE_RETENTION for direct OpenAI requests", async () => {
+		process.env.PI_CACHE_RETENTION = "long";
+		const { payload } = await captureRequest({ sessionId: "session-env" });
+
+		expect(payload?.prompt_cache_key).toBe("session-env");
+		expect(payload?.prompt_cache_retention).toBe("24h");
+	});
+
+	it("sends known session-affinity headers when compat.sendSessionAffinityHeaders is enabled", async () => {
+		const model = createModel({
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sendSessionAffinityHeaders: true },
+		});
+		const { headers } = await captureRequest({ sessionId: "session-affinity" }, model);
+
+		expect(headers.session_id).toBe("session-affinity");
+		expect(headers["x-client-request-id"]).toBe("session-affinity");
+		expect(headers["x-session-affinity"]).toBe("session-affinity");
+	});
+
+	it.each(["accounts/fireworks/models/glm-5p2", "accounts/fireworks/routers/glm-5p2-fast"] as const)(
+		"sends Fireworks session affinity for %s",
+		async (modelId) => {
+			const model = getModel("fireworks", modelId);
+			const { headers } = await captureRequest({ sessionId: "fireworks-session" }, model);
+
+			expect(headers["x-session-affinity"]).toBe("fireworks-session");
+		},
+	);
+
+	it("uses OpenAI no-session format when configured", async () => {
+		const model = createModel({
+			compat: { sendSessionAffinityHeaders: true, sessionAffinityFormat: "openai-nosession" },
+		});
+		const { payload, headers } = await captureRequest({ sessionId: "session-nosession" }, model);
+
+		expect(payload?.session_id).toBeUndefined();
+		expect(payload?.prompt_cache_key).toBe("session-nosession");
+		expect(headers.session_id).toBeUndefined();
+		expect(headers["x-client-request-id"]).toBe("session-nosession");
+		expect(headers["x-session-affinity"]).toBe("session-nosession");
+		expect(headers["x-session-id"]).toBeUndefined();
+	});
+
+	it("uses OpenRouter session-affinity header when configured", async () => {
+		const model = createModel({
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sendSessionAffinityHeaders: true, sessionAffinityFormat: "openrouter" },
+		});
+		const { payload, headers } = await captureRequest({ sessionId: "session-proxy" }, model);
+
+		expect(payload?.session_id).toBeUndefined();
+		expect(payload?.prompt_cache_key).toBeUndefined();
+		expect(headers["x-session-id"]).toBe("session-proxy");
+		expect(headers.session_id).toBeUndefined();
+		expect(headers["x-client-request-id"]).toBeUndefined();
+		expect(headers["x-session-affinity"]).toBeUndefined();
+	});
+
+	it("sends OpenRouter session-affinity header by default for built-in OpenRouter models", async () => {
+		const model = getModel("openrouter", "auto");
+		const { payload, headers } = await captureRequest({ sessionId: "session-openrouter" }, model);
+
+		expect(payload?.session_id).toBeUndefined();
+		expect(payload?.prompt_cache_key).toBeUndefined();
+		expect(headers["x-session-id"]).toBe("session-openrouter");
+		expect(headers.session_id).toBeUndefined();
+		expect(headers["x-client-request-id"]).toBeUndefined();
+		expect(headers["x-session-affinity"]).toBeUndefined();
+	});
+
+	it("omits OpenRouter session-affinity data when disabled", async () => {
+		const model = createModel({
+			provider: "openrouter",
+			baseUrl: "https://openrouter.ai/api/v1",
+			compat: { sendSessionAffinityHeaders: false },
+		});
+		const { payload, headers } = await captureRequest({ sessionId: "session-openrouter" }, model);
+
+		expect(payload?.session_id).toBeUndefined();
+		expect(payload?.prompt_cache_key).toBeUndefined();
+		expect(headers["x-session-id"]).toBeUndefined();
+	});
+
+	it("omits session-affinity headers when cacheRetention is none", async () => {
+		const model = createModel({
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sendSessionAffinityHeaders: true },
+		});
+		const { headers } = await captureRequest({ cacheRetention: "none", sessionId: "session-affinity" }, model);
+
+		expect(headers.session_id).toBeUndefined();
+		expect(headers["x-client-request-id"]).toBeUndefined();
+		expect(headers["x-session-affinity"]).toBeUndefined();
+	});
+
+	it("lets explicit headers override generated session-affinity headers", async () => {
+		const model = createModel({
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sendSessionAffinityHeaders: true },
+		});
+		const { headers } = await captureRequest(
+			{
+				sessionId: "session-affinity",
+				headers: {
+					session_id: "override-session",
+					"x-client-request-id": "override-request",
+					"x-session-affinity": "override-affinity",
+				},
+			},
+			model,
+		);
+
+		expect(headers.session_id).toBe("override-session");
+		expect(headers["x-client-request-id"]).toBe("override-request");
+		expect(headers["x-session-affinity"]).toBe("override-affinity");
+	});
+});

packages/ai/test/openai-completions-raw-stop-reason.test.ts

@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { stream as streamOpenAICompletions } from "../src/api/openai-completions.ts";
+import type { Context, Model } from "../src/types.ts";
+
+const mockState = vi.hoisted(() => ({
+	chunks: [] as unknown[],
+}));
+
+vi.mock("openai", () => {
+	class FakeOpenAI {
+		chat = {
+			completions: {
+				create: () => {
+					const chunks = mockState.chunks;
+					const stream = {
+						async *[Symbol.asyncIterator]() {
+							for (const chunk of chunks) yield chunk;
+						},
+					};
+					const promise = Promise.resolve(stream) as Promise<typeof stream> & {
+						withResponse: () => Promise<{
+							data: typeof stream;
+							response: { status: number; headers: Headers };
+						}>;
+					};
+					promise.withResponse = async () => ({
+						data: stream,
+						response: { status: 200, headers: new Headers() },
+					});
+					return promise;
+				},
+			},
+		};
+	}
+	return { default: FakeOpenAI };
+});
+
+const model: Model<"openai-completions"> = {
+	id: "test-model",
+	name: "Test Model",
+	api: "openai-completions",
+	provider: "openai",
+	baseUrl: "https://api.openai.com/v1",
+	reasoning: false,
+	input: ["text"],
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	contextWindow: 128_000,
+	maxTokens: 4096,
+};
+
+const context: Context = {
+	messages: [{ role: "user", content: "hello", timestamp: Date.now() }],
+};
+
+describe("OpenAI completions raw stop reasons", () => {
+	beforeEach(() => {
+		mockState.chunks = [];
+	});
+
+	it("preserves raw finish reasons for successful stops", async () => {
+		mockState.chunks = [{ id: "chatcmpl-1", choices: [{ index: 0, delta: {}, finish_reason: "stop" }] }];
+
+		const message = await streamOpenAICompletions(model, context, { apiKey: "test" }).result();
+
+		expect(message.stopReason).toBe("stop");
+		expect(message.rawStopReason).toBe("stop");
+		expect(message.errorMessage).toBeUndefined();
+	});
+
+	it("preserves raw finish reasons for provider error stops", async () => {
+		mockState.chunks = [{ id: "chatcmpl-2", choices: [{ index: 0, delta: {}, finish_reason: "content_filter" }] }];
+
+		const message = await streamOpenAICompletions(model, context, { apiKey: "test" }).result();
+
+		expect(message.stopReason).toBe("error");
+		expect(message.rawStopReason).toBe("content_filter");
+		expect(message.errorMessage).toBe("Provider finish_reason: content_filter");
+	});
+});

packages/ai/test/openai-completions-vllm-priority.test.ts

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { stream as streamOpenAICompletions } from "../src/api/openai-completions.ts";
+import { getModel } from "../src/compat.ts";
+import type { Model } from "../src/types.ts";
+
+interface CapturedCompletionsPayload {
+	priority?: number;
+	[key: string]: unknown;
+}
+
+const mockState = vi.hoisted(() => ({
+	lastParams: undefined as CapturedCompletionsPayload | undefined,
+}));
+
+vi.mock("openai", () => {
+	class FakeOpenAI {
+		chat = {
+			completions: {
+				create: (params: CapturedCompletionsPayload) => {
+					mockState.lastParams = params;
+					const stream = {
+						async *[Symbol.asyncIterator]() {
+							yield {
+								choices: [{ delta: {}, finish_reason: "stop" }],
+								usage: {
+									prompt_tokens: 1,
+									completion_tokens: 1,
+									prompt_tokens_details: { cached_tokens: 0 },
+									completion_tokens_details: { reasoning_tokens: 0 },
+								},
+							};
+						},
+					};
+					const promise = Promise.resolve(stream) as Promise<typeof stream> & {
+						withResponse: () => Promise<{
+							data: typeof stream;
+							response: { status: number; headers: Headers };
+						}>;
+					};
+					promise.withResponse = async () => ({
+						data: stream,
+						response: { status: 200, headers: new Headers() },
+					});
+					return promise;
+				},
+			},
+		};
+	}
+
+	return { default: FakeOpenAI };
+});
+
+function createModel(overrides: Partial<Model<"openai-completions">> = {}): Model<"openai-completions"> {
+	const { compat: _compat, ...baseModel } = getModel("openai", "gpt-4o-mini");
+	return {
+		...(baseModel as Omit<Model<"openai-completions">, "api">),
+		api: "openai-completions",
+		...overrides,
+	};
+}
+
+async function captureRequest(model: Model<"openai-completions">) {
+	await streamOpenAICompletions(
+		model,
+		{
+			systemPrompt: "sys",
+			messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+		},
+		{ apiKey: "test-key" },
+	).result();
+
+	return mockState.lastParams;
+}
+
+describe("openai-completions vllm priority", () => {
+	beforeEach(() => {
+		mockState.lastParams = undefined;
+	});
+
+	it("sends compat.vllmPriority as the top-level priority request field", async () => {
+		const payload = await captureRequest(
+			createModel({ compat: { vllmPriority: 10 } as Model<"openai-completions">["compat"] }),
+		);
+
+		expect(payload?.priority).toBe(10);
+	});
+
+	it("omits priority when vllmPriority is not set", async () => {
+		const payload = await captureRequest(createModel());
+
+		expect(payload?.priority).toBeUndefined();
+	});
+});

packages/ai/test/openai-responses-compat.test.ts

@@ -0,0 +1,599 @@
+import { Type } from "typebox";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { stream as streamOpenAIResponses } from "../src/api/openai-responses.ts";
+import { getModel } from "../src/compat.ts";
+import type { Model } from "../src/types.ts";
+
+type CapturedHeaders = Headers | string[][] | Record<string, string | readonly string[]> | undefined;
+
+interface CapturedResponsesPayload {
+	prompt_cache_key?: string;
+	session_id?: string;
+	tools?: Array<{ name?: string; strict?: boolean }>;
+}
+
+function getHeader(headers: CapturedHeaders, name: string): string | null {
+	if (!headers) return null;
+	if (headers instanceof Headers) return headers.get(name);
+
+	const lowerName = name.toLowerCase();
+	if (Array.isArray(headers)) {
+		const match = headers.find(([key]) => key?.toLowerCase() === lowerName);
+		return match?.[1] ?? null;
+	}
+
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === lowerName) return typeof value === "string" ? value : value.join(", ");
+	}
+	return null;
+}
+
+async function captureOpenAIResponseHeaders(
+	options: Parameters<typeof streamOpenAIResponses>[2],
+	model: Model<"openai-responses"> = getModel("openai", "gpt-5.4"),
+): Promise<{
+	sessionId: string | null;
+	clientRequestId: string | null;
+	xSessionId: string | null;
+}> {
+	const captured = {
+		sessionId: null as string | null,
+		clientRequestId: null as string | null,
+		xSessionId: null as string | null,
+	};
+	vi.spyOn(globalThis, "fetch").mockImplementation(async (_input, init) => {
+		captured.sessionId = getHeader(init?.headers, "session_id");
+		captured.clientRequestId = getHeader(init?.headers, "x-client-request-id");
+		captured.xSessionId = getHeader(init?.headers, "x-session-id");
+		return new Response("data: [DONE]\n\n", {
+			status: 200,
+			headers: { "content-type": "text/event-stream" },
+		});
+	});
+
+	const stream = streamOpenAIResponses(
+		model,
+		{
+			systemPrompt: "sys",
+			messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+		},
+		{ apiKey: "test-key", ...options },
+	);
+
+	for await (const event of stream) {
+		if (event.type === "done" || event.type === "error") break;
+	}
+
+	return captured;
+}
+
+describe("openai-responses provider defaults", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("omits reasoning when no reasoning is requested", async () => {
+		const model = getModel("github-copilot", "gpt-5-mini");
+		let capturedPayload: unknown;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			model,
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{
+				apiKey: "test-key",
+				onPayload: (payload) => {
+					capturedPayload = payload;
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(capturedPayload).not.toBeNull();
+		expect(capturedPayload).not.toMatchObject({
+			reasoning: expect.anything(),
+		});
+	});
+
+	it("forwards required tool choice", async () => {
+		let capturedPayload: unknown;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			getModel("openai", "gpt-5.4"),
+			{
+				messages: [
+					{
+						role: "user",
+						content: "Do not call ping. Respond with text instead.",
+						timestamp: Date.now(),
+					},
+				],
+				tools: [
+					{
+						name: "ping",
+						description: "Ping",
+						parameters: Type.Object({ value: Type.String() }),
+					},
+				],
+			},
+			{
+				apiKey: "test-key",
+				toolChoice: "required",
+				onPayload: (payload) => {
+					capturedPayload = payload;
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(capturedPayload).toMatchObject({
+			tool_choice: "required",
+			tools: [expect.objectContaining({ name: "ping" })],
+		});
+	});
+
+	it("sets strict mode explicitly for Cloudflare OpenAI Responses tools", async () => {
+		const model = getModel("cloudflare-ai-gateway", "gpt-5.6-sol");
+		let capturedPayload: CapturedResponsesPayload | undefined;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			model,
+			{
+				messages: [{ role: "user", content: "Use a tool.", timestamp: Date.now() }],
+				tools: [
+					{
+						name: "ordinary",
+						description: "An ordinary tool",
+						parameters: Type.Object({
+							path: Type.String(),
+							offset: Type.Optional(Type.Number()),
+						}),
+					},
+					{
+						name: "constrained",
+						description: "A constrained tool",
+						parameters: Type.Object({ value: Type.String() }),
+						constrainedSampling: { type: "json_schema", strict: "prefer" },
+					},
+				],
+			},
+			{
+				apiKey: "test-key",
+				onPayload: (payload) => {
+					capturedPayload = payload as CapturedResponsesPayload;
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(model.compat?.supportsStrictMode).toBe(true);
+		expect(capturedPayload?.tools).toEqual([
+			expect.objectContaining({ name: "ordinary", strict: false }),
+			expect.objectContaining({ name: "constrained", strict: true }),
+		]);
+	});
+
+	it.each([
+		"gpt-5.1",
+		"gpt-5.2",
+		"gpt-5.3-codex",
+		"gpt-5.4",
+		"gpt-5.4-mini",
+		"gpt-5.4-nano",
+		"gpt-5.5",
+		"gpt-5.6-sol",
+		"gpt-5.6-terra",
+		"gpt-5.6-luna",
+	] as const)("sends none reasoning effort for OpenAI %s when no reasoning is requested", async (modelId) => {
+		const model = getModel("openai", modelId);
+		let capturedPayload: unknown;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			model,
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{
+				apiKey: "test-key",
+				onPayload: (payload) => {
+					capturedPayload = payload;
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(capturedPayload).toMatchObject({
+			reasoning: { effort: "none" },
+		});
+	});
+
+	it.each(["gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.2-pro", "gpt-5.4-pro", "gpt-5.5-pro"] as const)(
+		"omits reasoning effort for OpenAI %s when off is unsupported",
+		async (modelId) => {
+			const model = getModel("openai", modelId);
+			let capturedPayload: unknown;
+
+			vi.spyOn(globalThis, "fetch").mockResolvedValue(
+				new Response("data: [DONE]\n\n", {
+					status: 200,
+					headers: { "content-type": "text/event-stream" },
+				}),
+			);
+
+			const stream = streamOpenAIResponses(
+				model,
+				{
+					systemPrompt: "sys",
+					messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+				},
+				{
+					apiKey: "test-key",
+					onPayload: (payload) => {
+						capturedPayload = payload;
+					},
+				},
+			);
+
+			for await (const event of stream) {
+				if (event.type === "done" || event.type === "error") break;
+			}
+
+			expect(capturedPayload).not.toMatchObject({
+				reasoning: expect.anything(),
+			});
+		},
+	);
+
+	it("sets cache-affinity headers for official OpenAI Responses requests with a sessionId", async () => {
+		const captured = await captureOpenAIResponseHeaders({ sessionId: "session-123" });
+
+		expect(captured.sessionId).toBe("session-123");
+		expect(captured.clientRequestId).toBe("session-123");
+	});
+
+	it("clamps prompt_cache_key to OpenAI's 64-character limit", async () => {
+		const sessionId = "x".repeat(67);
+		let capturedPayload: Pick<CapturedResponsesPayload, "prompt_cache_key"> | undefined;
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			getModel("openai", "gpt-5.4"),
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{
+				apiKey: "test-key",
+				sessionId,
+				onPayload: (payload) => {
+					capturedPayload = payload as Pick<CapturedResponsesPayload, "prompt_cache_key">;
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(capturedPayload?.prompt_cache_key).toBe("x".repeat(64));
+	});
+
+	it("sets cache-affinity headers for proxy OpenAI Responses requests with a sessionId", async () => {
+		const proxyModel: Model<"openai-responses"> = {
+			...getModel("openai", "gpt-5.4"),
+			provider: "opencode",
+			baseUrl: "https://proxy.example.com/v1",
+		};
+		const captured = await captureOpenAIResponseHeaders({ sessionId: "session-123" }, proxyModel);
+
+		expect(captured.sessionId).toBe("session-123");
+		expect(captured.clientRequestId).toBe("session-123");
+	});
+
+	it("uses OpenRouter session-affinity header when configured", async () => {
+		const proxyModel: Model<"openai-responses"> = {
+			...getModel("openai", "gpt-5.4"),
+			provider: "proxy",
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sessionAffinityFormat: "openrouter" },
+		};
+		let capturedPayload: CapturedResponsesPayload | undefined;
+		const captured = await captureOpenAIResponseHeaders(
+			{
+				sessionId: "session-proxy",
+				onPayload: (payload) => {
+					capturedPayload = payload as CapturedResponsesPayload;
+				},
+			},
+			proxyModel,
+		);
+
+		expect(captured.sessionId).toBeNull();
+		expect(captured.clientRequestId).toBeNull();
+		expect(captured.xSessionId).toBe("session-proxy");
+		expect(capturedPayload?.session_id).toBeUndefined();
+		expect(capturedPayload?.prompt_cache_key).toBe("session-proxy");
+	});
+
+	it("auto-detects OpenRouter session-affinity header for OpenRouter Responses endpoints", async () => {
+		const openRouterModel: Model<"openai-responses"> = {
+			...getModel("openai", "gpt-5.4"),
+			provider: "openrouter",
+			baseUrl: "https://openrouter.ai/api/v1",
+		};
+		let capturedPayload: CapturedResponsesPayload | undefined;
+		const captured = await captureOpenAIResponseHeaders(
+			{
+				sessionId: "session-openrouter",
+				onPayload: (payload) => {
+					capturedPayload = payload as CapturedResponsesPayload;
+				},
+			},
+			openRouterModel,
+		);
+
+		expect(captured.sessionId).toBeNull();
+		expect(captured.clientRequestId).toBeNull();
+		expect(captured.xSessionId).toBe("session-openrouter");
+		expect(capturedPayload?.session_id).toBeUndefined();
+		expect(capturedPayload?.prompt_cache_key).toBe("session-openrouter");
+	});
+
+	it("uses OpenAI no-session format when configured", async () => {
+		const proxyModel: Model<"openai-responses"> = {
+			...getModel("openai", "gpt-5.4"),
+			provider: "proxy",
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sessionAffinityFormat: "openai-nosession" },
+		};
+		let capturedPayload: CapturedResponsesPayload | undefined;
+		const captured = await captureOpenAIResponseHeaders(
+			{
+				sessionId: "session-proxy",
+				onPayload: (payload) => {
+					capturedPayload = payload as CapturedResponsesPayload;
+				},
+			},
+			proxyModel,
+		);
+
+		expect(captured.sessionId).toBeNull();
+		expect(captured.clientRequestId).toBe("session-proxy");
+		expect(captured.xSessionId).toBeNull();
+		expect(capturedPayload?.session_id).toBeUndefined();
+		expect(capturedPayload?.prompt_cache_key).toBe("session-proxy");
+	});
+
+	it("uses OpenAI no-session format for OpenCode Responses models", async () => {
+		const model = getModel("opencode", "gpt-5.4");
+		let capturedPayload: CapturedResponsesPayload | undefined;
+		const captured = await captureOpenAIResponseHeaders(
+			{
+				sessionId: "session-opencode",
+				onPayload: (payload) => {
+					capturedPayload = payload as CapturedResponsesPayload;
+				},
+			},
+			model,
+		);
+
+		expect(model.compat?.sessionAffinityFormat).toBe("openai-nosession");
+		expect(captured.sessionId).toBeNull();
+		expect(captured.clientRequestId).toBe("session-opencode");
+		expect(captured.xSessionId).toBeNull();
+		expect(capturedPayload?.prompt_cache_key).toBe("session-opencode");
+	});
+
+	it("can omit OpenAI session_id header while preserving other affinity data", async () => {
+		const proxyModel: Model<"openai-responses"> = {
+			...getModel("openai", "gpt-5.4"),
+			provider: "opencode",
+			baseUrl: "https://proxy.example.com/v1",
+			compat: { sessionAffinityFormat: "openai-nosession" },
+		};
+		let capturedPayload: CapturedResponsesPayload | undefined;
+		const captured = await captureOpenAIResponseHeaders(
+			{
+				sessionId: "session-123",
+				onPayload: (payload) => {
+					capturedPayload = payload as CapturedResponsesPayload;
+				},
+			},
+			proxyModel,
+		);
+
+		expect(captured.sessionId).toBeNull();
+		expect(captured.clientRequestId).toBe("session-123");
+		expect(capturedPayload?.prompt_cache_key).toBe("session-123");
+	});
+
+	it("lets explicit headers override the default OpenAI cache-affinity headers", async () => {
+		const captured = await captureOpenAIResponseHeaders({
+			sessionId: "session-123",
+			headers: {
+				session_id: "override-session",
+				"x-client-request-id": "override-request",
+			},
+		});
+
+		expect(captured.sessionId).toBe("override-session");
+		expect(captured.clientRequestId).toBe("override-request");
+	});
+
+	it("omits OpenAI cache-affinity headers when cacheRetention is none", async () => {
+		const captured = await captureOpenAIResponseHeaders({ cacheRetention: "none", sessionId: "session-123" });
+
+		expect(captured.sessionId).toBeNull();
+		expect(captured.clientRequestId).toBeNull();
+	});
+
+	it.each([
+		["gpt-5.4", "priority", 2],
+		["gpt-5.5", "priority", 2.5],
+		["gpt-5.5", "flex", 0.5],
+	] as const)("applies %s %s service-tier cost multiplier", async (modelId, serviceTier, multiplier) => {
+		const model = getModel("openai", modelId);
+		const tokenCount = 100_000;
+		const tokenScale = tokenCount / 1_000_000;
+		const sse = `${[
+			`data: ${JSON.stringify({
+				type: "response.completed",
+				response: {
+					status: "completed",
+					service_tier: serviceTier,
+					usage: {
+						input_tokens: tokenCount,
+						output_tokens: tokenCount,
+						total_tokens: tokenCount * 2,
+						input_tokens_details: { cached_tokens: 0 },
+					},
+				},
+			})}`,
+		].join("\n\n")}\n\n`;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response(sse, {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			model,
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{ apiKey: "test-key", serviceTier },
+		);
+
+		const result = await stream.result();
+
+		expect(result.usage.cost.input).toBe(model.cost.input * multiplier * tokenScale);
+		expect(result.usage.cost.output).toBe(model.cost.output * multiplier * tokenScale);
+		expect(result.usage.cost.total).toBe((model.cost.input + model.cost.output) * multiplier * tokenScale);
+	});
+});
+
+describe("openai-responses max_output_tokens compat", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("sends max_output_tokens by default", async () => {
+		let capturedPayload: { max_output_tokens?: number } | undefined;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			getModel("openai", "gpt-5.4"),
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{
+				apiKey: "test-key",
+				maxTokens: 1024,
+				onPayload: (payload) => {
+					capturedPayload = payload as { max_output_tokens?: number };
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(capturedPayload?.max_output_tokens).toBe(1024);
+	});
+
+	it("omits max_output_tokens when supportsMaxOutputTokens is false", async () => {
+		const baseModel = getModel("openai", "gpt-5.4");
+		const model: Model<"openai-responses"> = {
+			...baseModel,
+			compat: { ...baseModel.compat, supportsMaxOutputTokens: false },
+		};
+		let capturedPayload: { max_output_tokens?: number } | undefined;
+
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response("data: [DONE]\n\n", {
+				status: 200,
+				headers: { "content-type": "text/event-stream" },
+			}),
+		);
+
+		const stream = streamOpenAIResponses(
+			model,
+			{
+				systemPrompt: "sys",
+				messages: [{ role: "user", content: "hi", timestamp: Date.now() }],
+			},
+			{
+				apiKey: "test-key",
+				maxTokens: 1024,
+				onPayload: (payload) => {
+					capturedPayload = payload as { max_output_tokens?: number };
+				},
+			},
+		);
+
+		for await (const event of stream) {
+			if (event.type === "done" || event.type === "error") break;
+		}
+
+		expect(capturedPayload?.max_output_tokens).toBeUndefined();
+	});
+});

packages/ai/test/openai-responses-partial-json-cleanup.test.ts

@@ -0,0 +1,106 @@
+import type { ResponseStreamEvent } from "openai/resources/responses/responses.js";
+import { describe, expect, it, vi } from "vitest";
+import { processResponsesStream } from "../src/api/openai-responses-shared.ts";
+import type { AssistantMessage, AssistantMessageEvent, Model } from "../src/types.ts";
+import { AssistantMessageEventStream } from "../src/utils/event-stream.ts";
+
+function createOutput(model: Model<"openai-responses">): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "pending",
+		timestamp: Date.now(),
+	};
+}
+
+async function* createFunctionCallEvents(argumentsJson: string): AsyncIterable<ResponseStreamEvent> {
+	yield {
+		type: "response.output_item.added",
+		item: {
+			type: "function_call",
+			id: "fc_test",
+			call_id: "call_test",
+			name: "edit",
+			arguments: "",
+		},
+	} as ResponseStreamEvent;
+	yield {
+		type: "response.function_call_arguments.delta",
+		delta: '{"path":"README.md"',
+	} as ResponseStreamEvent;
+	yield {
+		type: "response.function_call_arguments.delta",
+		delta: ',"content":"updated"}',
+	} as ResponseStreamEvent;
+	yield {
+		type: "response.function_call_arguments.done",
+		arguments: argumentsJson,
+	} as ResponseStreamEvent;
+	yield {
+		type: "response.output_item.done",
+		item: {
+			type: "function_call",
+			id: "fc_test",
+			call_id: "call_test",
+			name: "edit",
+			arguments: argumentsJson,
+		},
+	} as ResponseStreamEvent;
+	yield {
+		type: "response.completed",
+		sequence_number: 5,
+		response: { id: "resp_test", status: "completed" },
+	} as ResponseStreamEvent;
+}
+
+describe("openai responses partialJson cleanup", () => {
+	it("removes partialJson from persisted tool-call blocks at output_item.done", async () => {
+		const model: Model<"openai-responses"> = {
+			id: "gpt-5-mini",
+			name: "GPT-5 Mini",
+			api: "openai-responses",
+			provider: "openai",
+			baseUrl: "https://api.openai.com/v1",
+			reasoning: true,
+			input: ["text"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: 400000,
+			maxTokens: 128000,
+		};
+		const output = createOutput(model);
+		const stream = new AssistantMessageEventStream();
+		const pushSpy = vi.spyOn(stream, "push");
+		const argumentsJson = '{"path":"README.md","content":"updated"}';
+
+		await processResponsesStream(createFunctionCallEvents(argumentsJson), output, stream, model);
+
+		expect(output.content).toHaveLength(1);
+		const persistedToolCall = output.content[0];
+		expect(persistedToolCall?.type).toBe("toolCall");
+		if (!persistedToolCall || persistedToolCall.type !== "toolCall") {
+			throw new Error("Expected toolCall block");
+		}
+		expect(persistedToolCall.arguments).toEqual({ path: "README.md", content: "updated" });
+		expect("partialJson" in persistedToolCall).toBe(false);
+
+		const emittedEvents = pushSpy.mock.calls.map(([event]) => event as AssistantMessageEvent);
+		const toolCallEnd = emittedEvents.find((event) => event.type === "toolcall_end");
+		expect(toolCallEnd).toBeDefined();
+		if (!toolCallEnd || toolCallEnd.type !== "toolcall_end") {
+			throw new Error("Expected toolcall_end event");
+		}
+		expect(toolCallEnd.toolCall).toBe(persistedToolCall);
+		expect("partialJson" in toolCallEnd.toolCall).toBe(false);
+	});
+});

packages/ai/test/openai-responses-reasoning-replay-e2e.test.ts

@@ -0,0 +1,291 @@
+import { Type } from "typebox";
+import { describe, expect, it } from "vitest";
+import { complete, getEnvApiKey, getModel } from "../src/compat.ts";
+import type { AssistantMessage, Context, Message, Tool, ToolCall } from "../src/types.ts";
+
+const testToolSchema = Type.Object({
+	value: Type.Number({ description: "A number to double" }),
+});
+
+const testTool: Tool<typeof testToolSchema> = {
+	name: "double_number",
+	description: "Doubles a number and returns the result",
+	parameters: testToolSchema,
+};
+
+describe.skipIf(!process.env.OPENAI_API_KEY || !process.env.ANTHROPIC_API_KEY)(
+	"OpenAI Responses reasoning replay e2e",
+	() => {
+		it("skips reasoning-only history after an aborted turn", { retry: 2 }, async () => {
+			const model = getModel("openai", "gpt-5-mini");
+
+			const apiKey = getEnvApiKey("openai");
+			if (!apiKey) {
+				throw new Error("Missing OPENAI_API_KEY");
+			}
+
+			const userMessage: Message = {
+				role: "user",
+				content: "Use the double_number tool to double 21.",
+				timestamp: Date.now(),
+			};
+
+			const assistantResponse = await complete(
+				model,
+				{
+					systemPrompt: "You are a helpful assistant. Use the tool.",
+					messages: [userMessage],
+					tools: [testTool],
+				},
+				{
+					apiKey,
+					reasoningEffort: "high",
+				},
+			);
+
+			const thinkingBlock = assistantResponse.content.find(
+				(block) => block.type === "thinking" && block.thinkingSignature,
+			);
+			if (!thinkingBlock || thinkingBlock.type !== "thinking") {
+				throw new Error("Missing thinking signature from OpenAI Responses");
+			}
+
+			const corruptedAssistant: AssistantMessage = {
+				...assistantResponse,
+				content: [thinkingBlock],
+				stopReason: "aborted",
+			};
+
+			const followUp: Message = {
+				role: "user",
+				content: "Say hello to confirm you can continue.",
+				timestamp: Date.now(),
+			};
+
+			const context: Context = {
+				systemPrompt: "You are a helpful assistant.",
+				messages: [userMessage, corruptedAssistant, followUp],
+				tools: [testTool],
+			};
+
+			const response = await complete(model, context, {
+				apiKey,
+				reasoningEffort: "high",
+			});
+
+			// The key assertion: no 400 error from orphaned reasoning item
+			expect(response.stopReason, `Error: ${response.errorMessage}`).not.toBe("error");
+			expect(response.errorMessage).toBeFalsy();
+			// Model should respond (text or tool call)
+			expect(response.content.length).toBeGreaterThan(0);
+		});
+
+		it("handles same-provider different-model handoff with tool calls", { retry: 2 }, async () => {
+			// This tests the scenario where:
+			// 1. Model A (gpt-5-mini) generates reasoning + function_call
+			// 2. User switches to Model B (gpt-5.2-codex) - same provider, different model
+			// 3. transform-messages: isSameModel=false, thinking converted to text
+			// 4. But tool call ID still has OpenAI pairing history (fc_xxx paired with rs_xxx)
+			// 5. Without fix: OpenAI returns 400 "function_call without required reasoning item"
+			// 6. With fix: tool calls/results converted to text, conversation continues
+
+			const modelA = getModel("openai", "gpt-5-mini");
+			const modelB = getModel("openai", "gpt-5.5");
+
+			const apiKey = getEnvApiKey("openai");
+			if (!apiKey) {
+				throw new Error("Missing OPENAI_API_KEY");
+			}
+
+			const userMessage: Message = {
+				role: "user",
+				content: "Use the double_number tool to double 21.",
+				timestamp: Date.now(),
+			};
+
+			// Get a real response from Model A with reasoning + tool call
+			const assistantResponse = await complete(
+				modelA,
+				{
+					systemPrompt: "You are a helpful assistant. Always use the tool when asked.",
+					messages: [userMessage],
+					tools: [testTool],
+				},
+				{
+					apiKey,
+					reasoningEffort: "high",
+				},
+			);
+
+			const toolCallBlock = assistantResponse.content.find((block) => block.type === "toolCall") as
+				| ToolCall
+				| undefined;
+
+			if (!toolCallBlock) {
+				throw new Error("Missing tool call from OpenAI Responses - model did not use the tool");
+			}
+
+			// Provide a tool result
+			const toolResult: Message = {
+				role: "toolResult",
+				toolCallId: toolCallBlock.id,
+				toolName: toolCallBlock.name,
+				content: [{ type: "text", text: "42" }],
+				isError: false,
+				timestamp: Date.now(),
+			};
+
+			const followUp: Message = {
+				role: "user",
+				content: "What was the result? Answer with just the number.",
+				timestamp: Date.now(),
+			};
+
+			// Now continue with Model B (different model, same provider)
+			const context: Context = {
+				systemPrompt: "You are a helpful assistant. Answer concisely.",
+				messages: [userMessage, assistantResponse, toolResult, followUp],
+				tools: [testTool],
+			};
+
+			let capturedPayload: any = null;
+			const response = await complete(modelB, context, {
+				apiKey,
+				reasoningEffort: "high",
+				onPayload: (payload) => {
+					capturedPayload = payload;
+				},
+			});
+
+			// The key assertion: no 400 error from orphaned function_call
+			expect(response.stopReason, `Error: ${response.errorMessage}`).not.toBe("error");
+			expect(response.errorMessage).toBeFalsy();
+			expect(response.content.length).toBeGreaterThan(0);
+
+			// Log what was sent for debugging
+			const input = capturedPayload?.input as any[];
+			const functionCalls = input?.filter((item: any) => item.type === "function_call") || [];
+			const reasoningItems = input?.filter((item: any) => item.type === "reasoning") || [];
+
+			console.log("Payload sent to API:");
+			console.log("- function_calls:", functionCalls.length);
+			console.log("- reasoning items:", reasoningItems.length);
+			console.log("- full input:", JSON.stringify(input, null, 2));
+
+			// Verify the model understood the context
+			const responseText = response.content
+				.filter((b) => b.type === "text")
+				.map((b) => (b as any).text)
+				.join("");
+			expect(responseText).toContain("42");
+		});
+
+		it("handles cross-provider handoff from Anthropic to OpenAI Codex", { retry: 2 }, async () => {
+			// This tests cross-provider handoff:
+			// 1. Anthropic model generates thinking + function_call (toolu_xxx ID)
+			// 2. User switches to OpenAI Codex
+			// 3. transform-messages: isSameModel=false, thinking converted to text
+			// 4. Tool call ID is Anthropic format (toolu_xxx), no OpenAI pairing history
+			// 5. Should work because foreign IDs have no pairing expectation
+
+			const anthropicModel = getModel("anthropic", "claude-sonnet-4-5");
+			const codexModel = getModel("openai", "gpt-5.5");
+
+			const anthropicApiKey = getEnvApiKey("anthropic");
+			const openaiApiKey = getEnvApiKey("openai");
+			if (!anthropicApiKey || !openaiApiKey) {
+				throw new Error("Missing API keys");
+			}
+
+			const userMessage: Message = {
+				role: "user",
+				content: "Use the double_number tool to double 21.",
+				timestamp: Date.now(),
+			};
+
+			// Get a real response from Anthropic with thinking + tool call
+			const assistantResponse = await complete(
+				anthropicModel,
+				{
+					systemPrompt: "You are a helpful assistant. Always use the tool when asked.",
+					messages: [userMessage],
+					tools: [testTool],
+				},
+				{
+					apiKey: anthropicApiKey,
+					thinkingEnabled: true,
+					thinkingBudgetTokens: 5000,
+				},
+			);
+
+			const toolCallBlock = assistantResponse.content.find((block) => block.type === "toolCall") as
+				| ToolCall
+				| undefined;
+
+			if (!toolCallBlock) {
+				throw new Error("Missing tool call from Anthropic - model did not use the tool");
+			}
+
+			console.log("Anthropic tool call ID:", toolCallBlock.id);
+
+			// Provide a tool result
+			const toolResult: Message = {
+				role: "toolResult",
+				toolCallId: toolCallBlock.id,
+				toolName: toolCallBlock.name,
+				content: [{ type: "text", text: "42" }],
+				isError: false,
+				timestamp: Date.now(),
+			};
+
+			const followUp: Message = {
+				role: "user",
+				content: "What was the result? Answer with just the number.",
+				timestamp: Date.now(),
+			};
+
+			// Now continue with Codex (different provider)
+			const context: Context = {
+				systemPrompt: "You are a helpful assistant. Answer concisely.",
+				messages: [userMessage, assistantResponse, toolResult, followUp],
+				tools: [testTool],
+			};
+
+			let capturedPayload: any = null;
+			const response = await complete(codexModel, context, {
+				apiKey: openaiApiKey,
+				reasoningEffort: "high",
+				onPayload: (payload) => {
+					capturedPayload = payload;
+				},
+			});
+
+			// Log what was sent
+			const input = capturedPayload?.input as any[];
+			const functionCalls = input?.filter((item: any) => item.type === "function_call") || [];
+			const reasoningItems = input?.filter((item: any) => item.type === "reasoning") || [];
+
+			console.log("Payload sent to Codex:");
+			console.log("- function_calls:", functionCalls.length);
+			console.log("- reasoning items:", reasoningItems.length);
+			if (functionCalls.length > 0) {
+				console.log(
+					"- function_call IDs:",
+					functionCalls.map((fc: any) => fc.id),
+				);
+			}
+
+			// The key assertion: no 400 error
+			expect(response.stopReason, `Error: ${response.errorMessage}`).not.toBe("error");
+			expect(response.errorMessage).toBeFalsy();
+			expect(response.content.length).toBeGreaterThan(0);
+
+			// Verify the model understood the context
+			const responseText = response.content
+				.filter((b) => b.type === "text")
+				.map((b) => (b as any).text)
+				.join("");
+			expect(responseText).toContain("42");
+		});
+	},
+);

packages/ai/test/openrouter-cache-write-repro.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { completeSimple, getModel } from "../src/compat.ts";
+
+function createLongSystemPrompt(): string {
+	const nonce = `${Date.now()}-${Math.random()}`;
+	return `You are a concise assistant.\nCache nonce: ${nonce}\n\n${Array(80)
+		.fill(
+			"Prompt-caching probe content. Keep this exact text stable across requests so the provider can reuse prefix tokens and report cache read and cache write usage.",
+		)
+		.join("\n\n")}`;
+}
+
+describe.skipIf(!process.env.OPENROUTER_API_KEY)("OpenRouter cache_write repro E2E", () => {
+	it(
+		"regression: preserves cache_write_tokens on openai-completions stream path",
+		{ retry: 2, timeout: 90000 },
+		async () => {
+			const model = getModel("openrouter", "google/gemini-2.5-flash");
+			const context = {
+				systemPrompt: createLongSystemPrompt(),
+				messages: [
+					{
+						role: "user" as const,
+						content: "Reply with exactly: OK",
+						timestamp: Date.now(),
+					},
+				],
+			};
+
+			const options = {
+				apiKey: process.env.OPENROUTER_API_KEY!,
+				maxTokens: 32,
+				temperature: 0,
+				onPayload: (payload: unknown) => {
+					const params = payload as {
+						messages?: Array<{
+							role?: string;
+							content?: string | Array<{ type?: string; text?: string; cache_control?: { type: string } }>;
+						}>;
+					};
+					const messages = params.messages;
+					if (!Array.isArray(messages)) return payload;
+
+					for (let i = messages.length - 1; i >= 0; i--) {
+						const msg = messages[i];
+						if (msg.role !== "user") continue;
+						if (typeof msg.content === "string") {
+							msg.content = [{ type: "text", text: msg.content, cache_control: { type: "ephemeral" } }];
+							break;
+						}
+						if (!Array.isArray(msg.content)) continue;
+						for (let j = msg.content.length - 1; j >= 0; j--) {
+							const part = msg.content[j];
+							if (part.type === "text") {
+								part.cache_control = { type: "ephemeral" };
+								break;
+							}
+						}
+						break;
+					}
+					return payload;
+				},
+			};
+
+			const first = await completeSimple(model, context, options);
+			expect(first.stopReason, first.errorMessage).toBe("stop");
+
+			const second = await completeSimple(model, context, options);
+			expect(second.stopReason, second.errorMessage).toBe("stop");
+
+			// Regression expectation: cache_write_tokens from provider usage must be preserved.
+			// With the cache_control marker above, at least one of the two calls should create cache.
+			const hasCacheWrite = first.usage.cacheWrite > 0 || second.usage.cacheWrite > 0;
+			expect(hasCacheWrite).toBe(true);
+		},
+	);
+});

packages/ai/test/openrouter-reasoning-options.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { getOpenRouterThinkingLevelMap } from "../scripts/openrouter-reasoning-options.ts";
+import { streamSimple } from "../src/api/openai-completions.ts";
+import type { Context, Model, ThinkingLevelMap } from "../src/types.ts";
+
+const context: Context = {
+	messages: [{ role: "user", content: "Hello", timestamp: 0 }],
+};
+
+function openRouterModel(thinkingLevelMap?: ThinkingLevelMap): Model<"openai-completions"> {
+	return {
+		id: "stealth/ox-alpha",
+		name: "Ox Alpha",
+		api: "openai-completions",
+		provider: "openrouter",
+		baseUrl: "https://example.invalid/v1",
+		reasoning: true,
+		thinkingLevelMap,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 4096,
+		compat: { thinkingFormat: "openrouter" },
+	};
+}
+
+async function capturePayload(model: Model<"openai-completions">, reasoning?: "low") {
+	let payload: { reasoning?: { effort?: string } } | undefined;
+	await streamSimple(model, context, {
+		apiKey: "test",
+		reasoning,
+		onPayload: (request) => {
+			payload = request as { reasoning?: { effort?: string } };
+			throw new Error("payload captured");
+		},
+	}).result();
+	if (!payload) throw new Error("OpenRouter payload was not captured");
+	return payload;
+}
+
+describe("getOpenRouterThinkingLevelMap", () => {
+	it("marks mandatory reasoning and unsupported efforts unavailable", () => {
+		expect(
+			getOpenRouterThinkingLevelMap({
+				mandatory: true,
+				default_enabled: true,
+				supported_efforts: ["max", "high", "low"],
+				default_effort: "max",
+			}),
+		).toEqual({
+			off: null,
+			minimal: null,
+			low: "low",
+			medium: null,
+			high: "high",
+			xhigh: null,
+			max: "max",
+		});
+	});
+
+	it("still marks off unavailable when OpenRouter omits effort metadata", () => {
+		expect(getOpenRouterThinkingLevelMap({ mandatory: true })).toEqual({ off: null });
+	});
+
+	it("keeps off available while restricting optional models to supported efforts", () => {
+		expect(
+			getOpenRouterThinkingLevelMap({
+				mandatory: false,
+				default_enabled: true,
+				supported_efforts: ["high", "low"],
+			}),
+		).toEqual({
+			off: "none",
+			minimal: null,
+			low: "low",
+			medium: null,
+			high: "high",
+			xhigh: null,
+			max: null,
+		});
+	});
+
+	it("does not add metadata for optional models without effort controls", () => {
+		expect(getOpenRouterThinkingLevelMap({ mandatory: false })).toBeUndefined();
+	});
+});
+
+describe("OpenRouter mandatory reasoning payloads", () => {
+	const mandatoryMap = getOpenRouterThinkingLevelMap({
+		mandatory: true,
+		supported_efforts: ["max", "high", "low"],
+	});
+
+	it("omits reasoning when a background call does not request it", async () => {
+		expect(await capturePayload(openRouterModel(mandatoryMap))).not.toHaveProperty("reasoning");
+	});
+
+	it("still sends an explicitly selected supported effort", async () => {
+		expect(await capturePayload(openRouterModel(mandatoryMap), "low")).toMatchObject({
+			reasoning: { effort: "low" },
+		});
+	});
+
+	it("continues to explicitly disable reasoning for optional models", async () => {
+		expect(await capturePayload(openRouterModel())).toMatchObject({
+			reasoning: { effort: "none" },
+		});
+	});
+});

packages/ai/test/overflow.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "vitest";
+import type { AssistantMessage } from "../src/types.ts";
+import { isContextOverflow, isRecoverableLength } from "../src/utils/overflow.ts";
+
+function createErrorMessage(errorMessage: string): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: "openai-completions",
+		provider: "ollama",
+		model: "qwen3.5:35b",
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				total: 0,
+			},
+		},
+		stopReason: "error",
+		errorMessage,
+		timestamp: Date.now(),
+	};
+}
+
+describe("isContextOverflow", () => {
+	it("detects explicit Ollama prompt-too-long errors", () => {
+		const message = createErrorMessage("400 `prompt too long; exceeded max context length by 100918 tokens`");
+		expect(isContextOverflow(message, 32768)).toBe(true);
+	});
+
+	it("detects Together AI context length errors", () => {
+		const message = createErrorMessage(
+			"400 The input (516368 tokens) is longer than the model's context length (262144 tokens).",
+		);
+		expect(isContextOverflow(message, 262144)).toBe(true);
+	});
+
+	it("detects LiteLLM-wrapped OpenAI maximum context length errors", () => {
+		const message = createErrorMessage(
+			"Error: 503 litellm.ServiceUnavailableError: litellm.MidStreamFallbackError: litellm.APIConnectionError: APIConnectionError: OpenAIException - Requested token count exceeds the model's maximum context length of 131072 tokens.",
+		);
+		expect(isContextOverflow(message, 131072)).toBe(true);
+	});
+
+	it("detects OpenAI-compatible parenthesized maximum context length errors", () => {
+		const message = createErrorMessage(
+			"Error: 400 Input length (265330) exceeds model's maximum context length (262144).",
+		);
+		expect(isContextOverflow(message, 262144)).toBe(true);
+	});
+
+	it("detects OpenRouter Poolside maximum allowed input length errors", () => {
+		const message = createErrorMessage(
+			"Provider returned error: Input length 131393 exceeds the maximum allowed input length of 131040 tokens.",
+		);
+		expect(isContextOverflow(message, 131072)).toBe(true);
+	});
+
+	it("detects DS4 configured context size errors", () => {
+		const message = createErrorMessage(
+			"400 Prompt has 256468 tokens, but the configured context size is 256000 tokens",
+		);
+		expect(isContextOverflow(message, 256000)).toBe(true);
+
+		const commaMessage = createErrorMessage(
+			"Prompt has 5,958,968 tokens, but the configured context size is 256,000 tokens",
+		);
+		expect(isContextOverflow(commaMessage, 256000)).toBe(true);
+	});
+
+	it("does not treat generic non-overflow Ollama errors as overflow", () => {
+		const message = createErrorMessage("500 `model runner crashed unexpectedly`");
+		expect(isContextOverflow(message, 32768)).toBe(false);
+	});
+
+	it("does not treat Bedrock throttling 'Too many tokens' as overflow", () => {
+		// Bedrock returns this for HTTP 429 rate limiting, NOT context overflow.
+		// formatBedrockError uses a human-readable prefix for ThrottlingException.
+		const message = createErrorMessage("Throttling error: Too many tokens, please wait before trying again.");
+		expect(isContextOverflow(message, 200000)).toBe(false);
+	});
+
+	it("does not treat Bedrock service unavailable as overflow", () => {
+		const message = createErrorMessage("Service unavailable: The service is temporarily unavailable.");
+		expect(isContextOverflow(message, 200000)).toBe(false);
+	});
+
+	it("does not treat generic rate limit errors as overflow", () => {
+		const message = createErrorMessage("Rate limit exceeded, please retry after 30 seconds.");
+		expect(isContextOverflow(message, 200000)).toBe(false);
+	});
+
+	it("does not treat HTTP 429 style errors as overflow", () => {
+		const message = createErrorMessage("Too many requests. Please slow down.");
+		expect(isContextOverflow(message, 200000)).toBe(false);
+	});
+
+	function createLengthStopMessage(options: {
+		input: number;
+		cacheRead: number;
+		output: number;
+		cacheWrite?: number;
+		api?: AssistantMessage["api"];
+		provider?: string;
+		model?: string;
+	}): AssistantMessage {
+		const cacheWrite = options.cacheWrite ?? 0;
+		return {
+			role: "assistant",
+			content: [],
+			api: options.api ?? "openai-completions",
+			provider: options.provider ?? "test-provider",
+			model: options.model ?? "test-model",
+			usage: {
+				input: options.input,
+				output: options.output,
+				cacheRead: options.cacheRead,
+				cacheWrite,
+				totalTokens: options.input + options.cacheRead + cacheWrite + options.output,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "length",
+			timestamp: Date.now(),
+		};
+	}
+
+	it("detects Xiaomi-style overflow (length stop with zero output and filled context)", () => {
+		const message = createLengthStopMessage({
+			input: 58,
+			cacheRead: 1048512,
+			output: 0,
+			provider: "xiaomi",
+			model: "mimo-v2.5-pro",
+		});
+		expect(isContextOverflow(message, 1048576)).toBe(true);
+	});
+
+	it("treats a length stop below the desired output limit as recoverable", () => {
+		const message = createLengthStopMessage({
+			input: 3,
+			cacheRead: 253584,
+			cacheWrite: 25554,
+			output: 16,
+			api: "openai-responses",
+			provider: "openai",
+			model: "gpt-5.6-sol",
+		});
+		expect(isRecoverableLength(message, 128000)).toBe(true);
+	});
+
+	it("does not recover a length stop that reached the desired output limit", () => {
+		const message = createLengthStopMessage({ input: 4062, cacheRead: 0, output: 1024 });
+		expect(isRecoverableLength(message, 1024)).toBe(false);
+	});
+
+	it("treats zero-output length stops as recoverable without context metadata", () => {
+		const message = createLengthStopMessage({ input: 100, cacheRead: 0, output: 0 });
+		expect(isRecoverableLength(message, 128000)).toBe(true);
+	});
+
+	it("does not treat normal length stops with output as context overflow", () => {
+		const message = createLengthStopMessage({ input: 1000, cacheRead: 0, output: 4096 });
+		expect(isContextOverflow(message, 200000)).toBe(false);
+	});
+
+	it("does not treat zero-output length stops far below context as context overflow", () => {
+		const message = createLengthStopMessage({ input: 100, cacheRead: 0, output: 0 });
+		expect(isContextOverflow(message, 200000)).toBe(false);
+	});
+});

packages/ai/test/together-models.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { getModel } from "../src/compat.ts";
+import { findEnvKeys, getEnvApiKey } from "../src/env-api-keys.ts";
+
+const originalTogetherApiKey = process.env.TOGETHER_API_KEY;
+
+afterEach(() => {
+	if (originalTogetherApiKey === undefined) {
+		delete process.env.TOGETHER_API_KEY;
+	} else {
+		process.env.TOGETHER_API_KEY = originalTogetherApiKey;
+	}
+});
+
+describe("Together models", () => {
+	it("registers the default Kimi K2.6 model via OpenAI-compatible Chat Completions API", () => {
+		const model = getModel("together", "moonshotai/Kimi-K2.6");
+
+		expect(model).toBeDefined();
+		expect(model.api).toBe("openai-completions");
+		expect(model.provider).toBe("together");
+		expect(model.baseUrl).toBe("https://api.together.ai/v1");
+		expect(model.reasoning).toBe(true);
+		expect(model.thinkingLevelMap).toEqual({ minimal: null, low: null, medium: null });
+		expect(model.input).toEqual(["text", "image"]);
+		expect(model.contextWindow).toBe(262144);
+		expect(model.maxTokens).toBe(131000);
+		expect(model.cost).toEqual({
+			input: 1.2,
+			output: 4.5,
+			cacheRead: 0.2,
+			cacheWrite: 0,
+		});
+		expect(model.compat).toEqual({
+			supportsStore: false,
+			supportsDeveloperRole: false,
+			supportsReasoningEffort: false,
+			maxTokensField: "max_tokens",
+			thinkingFormat: "together",
+			supportsStrictMode: false,
+			supportsLongCacheRetention: false,
+		});
+	});
+
+	it("models Together reasoning controls from the Together API surface", () => {
+		const gptOss = getModel("together", "openai/gpt-oss-120b");
+		expect(gptOss.thinkingLevelMap).toEqual({
+			off: null,
+			minimal: null,
+			low: "low",
+			medium: "medium",
+			high: "high",
+			max: null,
+			xhigh: null,
+		});
+		expect(gptOss.compat).toMatchObject({
+			supportsReasoningEffort: true,
+			thinkingFormat: "openai",
+		});
+
+		const deepSeekV4 = getModel("together", "deepseek-ai/DeepSeek-V4-Pro");
+		expect(deepSeekV4.thinkingLevelMap).toEqual({
+			minimal: null,
+			low: null,
+			medium: null,
+			high: "high",
+			xhigh: null,
+		});
+		expect(deepSeekV4.compat).toMatchObject({
+			supportsReasoningEffort: true,
+			thinkingFormat: "together",
+		});
+
+		const minimax = getModel("together", "MiniMaxAI/MiniMax-M2.7");
+		expect(minimax.thinkingLevelMap).toEqual({ off: null, minimal: null, low: null, medium: null });
+		expect(minimax.compat?.thinkingFormat).toBeUndefined();
+		expect(minimax.compat?.supportsReasoningEffort).toBe(false);
+	});
+
+	it("resolves TOGETHER_API_KEY from the environment", () => {
+		process.env.TOGETHER_API_KEY = "test-together-key";
+
+		expect(findEnvKeys("together")).toEqual(["TOGETHER_API_KEY"]);
+		expect(getEnvApiKey("together")).toBe("test-together-key");
+	});
+});