whobrokeit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berkan Atik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# whobrokeit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Find the commit that broke it, and prove it.**
+
+English · [Türkçe](README.tr.md)
+
+Describe a bug in one sentence. An AI agent writes a test that shows it, whobrokeit walks your git history to the first commit where that test fails, and proves the result: the test fails at that commit and passes at its parent. Then it explains what went wrong and suggests a fix, which it shows only after the test passes with it.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="whobrokeit finds the commit that broke subtotal(), in 37 seconds" width="860">
+</p>
+
+```sh
+npx whobrokeit demo        # try it on a generated repo with a hidden bug (no AI needed)
+npx whobrokeit demo --ai   # the same, with an AI agent writing the test
+```
+
+## Use it
+
+Describe the bug, from anywhere inside your repo:
+
+```sh
+whobrokeit "Adding 3 mugs costs the same as 1 mug."
+```
+
+This needs [Claude Code](https://github.com/anthropics/claude-code) or [Codex](https://github.com/openai/codex) installed and logged in. whobrokeit uses whichever it finds.
+
+Or bring your own failing test, and no AI is involved:
+
+```sh
+whobrokeit --test "npm test -- cart.test.js"
+whobrokeit --test "pytest tests/test_cart.py -x"
+whobrokeit --test "node repro.mjs" --with repro.mjs   # a test you haven't committed yet
+```
+
+Any command works. Exit code 0 means it works, 125 means this commit can't be tested (skip it), anything else means broken. Add `--explain` to get the explanation and a fix in this mode too.
+
+## On GitHub issues
+
+whobrokeit can also run as a GitHub Action. When you label an issue `whobrokeit`, or comment `/whobrokeit`, it looks for the commit that broke it and replies on the issue with the culprit, the proof and a fix it has tested.
+
+Add an `ANTHROPIC_API_KEY` secret to the repo, then save this as `.github/workflows/whobrokeit.yml`:
+
+```yaml
+name: whobrokeit
+
+on:
+  issues:
+    types: [labeled]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  whobrokeit:
+    # Only people who can label issues, or members and collaborators who comment /whobrokeit.
+    if: >-
+      (github.event_name == 'issues' && github.event.label.name == 'whobrokeit') ||
+      (github.event_name == 'issue_comment' && !github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, '/whobrokeit') &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0               # whobrokeit needs the history
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22             # whatever your project uses
+      - uses: BerkanAtik/whobrokeit@v0
+        with:
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+By default it works from the issue's title and body. Text after `/whobrokeit` replaces them, so you can put the bug more precisely: `/whobrokeit Adding 3 mugs costs the same as 1 mug.`
+
+| Input | |
+|---|---|
+| `anthropic-api-key` | Anthropic API key. Or `claude-code-oauth-token`, made with `claude setup-token`, to use a Claude subscription. |
+| `bug` | What is broken. Default: the comment text after `/whobrokeit`, else the issue. |
+| `test` | Your own failing test command. No AI writes the test then. |
+| `explain` | `auto` (default), `true` or `false`. |
+| `agent`, `model`, `good`, `bad`, `setup`, `timeout` | As on the command line. `setup: none` turns installs off. |
+| `working-directory` | The repository to search, if it is not the workspace root. |
+| `comment` | Set to `false` to skip the issue comment. The report is in the job summary either way. |
+
+Outputs: `exit-code`, `commit` (short hash of the culprit) and `report` (path to the Markdown report). The job fails only on errors. A bug it could not reproduce is reported on the issue like any other result.
+
+Read an issue before you start a run on it. The agent only reads code, but whobrokeit runs the test it writes, and issue text can try to steer the agent. The tests whobrokeit runs never get the AI key or the GitHub token in their environment, and the token can't change anything but comments. Code on the runner runs as the same user, though, so use an API key with a spending limit.
+
+## What it does
+
+1. **Reproduce.** The agent reads your code and writes a small script that prints a `WHOBROKEIT_BUG:` line when it sees the bug. whobrokeit runs it at `HEAD` and only goes on if it fails there for that reason. A crash without that line counts as "can't tell", so a test that calls a function older commits don't have never blames the wrong commit.
+2. **Find a commit where it still worked.** It walks back 1, 2, 4, 8… commits until the test passes. Or pass `--good <ref>`.
+3. **Bisect.** `git bisect` narrows it down to the first bad commit, skipping commits the test can't tell about.
+4. **Prove it.** It runs the test again at the culprit (fails) and at its parent (passes).
+5. **Explain and fix.** The agent says why the change broke things and proposes an edit. whobrokeit applies it, runs the test, and shows the fix only if the test passes. It saves it as a patch you can `git apply`.
+
+## Tested on real bugs
+
+I ran it on 12 closed regression issues from commander, semver, postcss, luxon, marked, express, markdown-it, fastify and yargs. It got only the issue text, exactly as the reporter wrote it. It proved the commit the maintainers had identified in **11 of 12** cases, in about 100 seconds each. The cases, the one miss and how to rerun everything are in [bench/](bench).
+
+## Safe to run on your repo
+
+- **Your working copy is never touched.** Every check runs in a temporary `git worktree`, which is removed at the end. Uncommitted changes, open files and your current branch stay as they are.
+- **The agent can only read.** Claude Code runs with the Read, Grep and Glob tools only, and with your hooks, plugins and MCP servers turned off. Codex runs in its read-only sandbox. whobrokeit runs the test the agent writes, so check it if you don't trust the repo.
+- **Nothing is taken on faith.** The test has to fail at `HEAD` for the reported reason, the culprit has to be proven against its parent, and a fix has to make the test pass.
+- **Dependencies are installed per commit** when `package.json` or a lockfile changes (npm, pnpm, yarn, bun). Use `--setup "<cmd>"` for anything else, or `--no-setup`.
+
+## Options
+
+| Option | |
+|---|---|
+| `-t, --test <cmd>` | A command that fails while the bug is present. |
+| `--agent <name>` | Who writes the test: `claude`, `codex`, or any command that reads a prompt on stdin and answers on stdout. Default: `claude`, else `codex`. |
+| `--model <name>` | Model for the agent, e.g. `sonnet`. |
+| `--explain` / `--no-explain` | Explain the culprit and test a fix. On by default when you describe a bug, off with `--test`. |
+| `-w, --with <file>` | Copy this file from your working copy into every commit tested. Repeatable. |
+| `-g, --good <ref>` | A commit where it still worked. Default: found automatically. |
+| `-b, --bad <ref>` | A commit where it is broken. Default: `HEAD`. |
+| `--setup <cmd>` / `--no-setup` | Install command, re-run when dependency files change. Default: auto. |
+| `--timeout <sec>` | Time limit for each test run. Default: 600, or 300 for agent-written tests. |
+| `--report <file>` | Also write a Markdown report, ready to paste into an issue or PR. |
+| `--json` | Print the result as JSON. |
+
+Exit codes: `0` found and proven · `1` error · `2` bug not reproduced · `3` no working commit found · `4` inconclusive.
+
+## Good to know
+
+- Requires Node.js 20+ and git. No other dependencies.
+- The test can be in any language your project uses. Automatic dependency install covers JavaScript package managers; for other stacks, use `--setup`.
+- With an agent, a run usually makes two requests: one to write the test, one to explain the culprit (each is retried once if its result doesn't hold up). On the demo repo the whole run takes 30 to 60 seconds.
+- If the project commits no lockfile, old commits get today's versions of their dependencies. A bug that depends on a dependency's version can then be traced to the wrong commit.
+- After a run, the agent's test and the fix are in `.git/whobrokeit/`, outside your working tree.
+
+## License
+
+[MIT](LICENSE)

package/README.tr.md

@@ -0,0 +1,143 @@
+# whobrokeit
+
+**Hatayı getiren commit'i bulur ve kanıtlar.**
+
+[English](README.md) · Türkçe
+
+Hatayı tek cümleyle anlatırsın. Bir yapay zekâ ajanı hatayı gösteren bir test yazar; whobrokeit git geçmişinde bu testin ilk başarısız olduğu commit'e kadar gider ve sonucu kanıtlar: test o commit'te başarısız, bir öncekinde başarılıdır. Ardından neyin bozulduğunu açıklar ve bir düzeltme önerir. Düzeltmeyi ancak test onunla geçtikten sonra gösterir.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="whobrokeit, subtotal() fonksiyonunu bozan commit'i 37 saniyede buluyor" width="860">
+</p>
+
+```sh
+npx whobrokeit demo        # içine hata gizlenmiş örnek bir repoda dene (yapay zekâ gerekmez)
+npx whobrokeit demo --ai   # aynısı, testi yapay zekâ ajanı yazar
+```
+
+## Kullanım
+
+Reponun içindeyken hatayı anlat:
+
+```sh
+whobrokeit "Sepete 3 kupa ekleyince fiyat 1 kupa kadar çıkıyor."
+```
+
+Bunun için [Claude Code](https://github.com/anthropics/claude-code) ya da [Codex](https://github.com/openai/codex) kurulu ve giriş yapılmış olmalı. whobrokeit hangisini bulursa onu kullanır. Açıklama, hatayı hangi dilde yazdıysan o dilde gelir.
+
+Ya da başarısız olan testi kendin ver, o zaman yapay zekâ hiç devreye girmez:
+
+```sh
+whobrokeit --test "npm test -- cart.test.js"
+whobrokeit --test "pytest tests/test_cart.py -x"
+whobrokeit --test "node repro.mjs" --with repro.mjs   # henüz commit'lemediğin bir test
+```
+
+Her komut olur. Çıkış kodu 0 çalışıyor, 125 bu commit test edilemiyor (atla), diğer her şey bozuk demektir. Bu modda da açıklama ve düzeltme istersen `--explain` ekle.
+
+## GitHub issue'larında
+
+whobrokeit bir GitHub Action olarak da çalışır. Bir issue'ya `whobrokeit` etiketini koyduğunda ya da `/whobrokeit` yorumunu yazdığında hatayı getiren commit'i arar. Sonra issue'ya bir yorum yazar: suçlu commit, kanıtı ve test edilmiş bir düzeltme.
+
+Repoya `ANTHROPIC_API_KEY` adında bir secret ekle, sonra şunu `.github/workflows/whobrokeit.yml` olarak kaydet:
+
+```yaml
+name: whobrokeit
+
+on:
+  issues:
+    types: [labeled]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  whobrokeit:
+    # Yalnız issue etiketleyebilenler ya da /whobrokeit yazan üyeler ve katkıcılar.
+    if: >-
+      (github.event_name == 'issues' && github.event.label.name == 'whobrokeit') ||
+      (github.event_name == 'issue_comment' && !github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, '/whobrokeit') &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0               # whobrokeit geçmişe ihtiyaç duyar
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22             # projen hangisini kullanıyorsa
+      - uses: BerkanAtik/whobrokeit@v0
+        with:
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+Varsayılan olarak issue'nun başlığı ve metniyle çalışır. `/whobrokeit`'ten sonra bir metin yazarsan onların yerine o kullanılır. Böylece hatayı daha net anlatabilirsin: `/whobrokeit Sepete 3 kupa ekleyince fiyat 1 kupa kadar çıkıyor.`
+
+| Girdi | |
+|---|---|
+| `anthropic-api-key` | Anthropic API anahtarı. Claude aboneliğini kullanmak için onun yerine `claude setup-token` ile alınan `claude-code-oauth-token`. |
+| `bug` | Bozuk olan şey. Varsayılan: yorumda `/whobrokeit`'ten sonraki metin, o da yoksa issue. |
+| `test` | Başarısız olan kendi test komutun. O zaman testi yapay zekâ yazmaz. |
+| `explain` | `auto` (varsayılan), `true` ya da `false`. |
+| `agent`, `model`, `good`, `bad`, `setup`, `timeout` | Komut satırındakiyle aynı. `setup: none` kurulumu kapatır. |
+| `working-directory` | Aranacak repo, çalışma alanının kökü değilse. |
+| `comment` | Issue'ya yorum yazmasın istersen `false`. Rapor her durumda job özetinde de olur. |
+
+Çıktılar: `exit-code`, `commit` (suçlu commit'in kısa hash'i) ve `report` (Markdown raporun yolu). Job yalnız bir hata olursa başarısız olur. Yeniden üretilemeyen bir hata da diğer sonuçlar gibi issue'ya yazılır.
+
+Bir issue'da çalıştırmadan önce issue'yu oku. Ajan yalnız kodu okur, ama yazdığı testi whobrokeit çalıştırır, ve issue metni ajanı yönlendirmeye çalışabilir. whobrokeit'in çalıştırdığı testlerin ortamında AI anahtarı da GitHub token'ı da olmaz, token da yorumlar dışında hiçbir şeyi değiştiremez. Yine de runner'daki kod aynı kullanıcıyla çalışır; harcama sınırı olan bir API anahtarı kullan.
+
+## Ne yapar
+
+1. **Hatayı yeniden üretir.** Ajan kodu okur ve hatayı görünce `WHOBROKEIT_BUG:` satırı basan küçük bir betik yazar. whobrokeit onu `HEAD`'de çalıştırır, yalnız bu sebeple başarısız olursa devam eder. Bu satır olmadan gelen bir çökme "belli değil" sayılır; eski commit'lerde olmayan bir fonksiyonu çağıran test yüzünden yanlış commit suçlanmaz.
+2. **Hâlâ çalıştığı bir commit bulur.** Test geçene kadar 1, 2, 4, 8… commit geri gider. İstersen `--good <ref>` ile kendin verirsin.
+3. **Bisect yapar.** `git bisect` ile ilk bozuk commit'e iner, testin karar veremediği commit'leri atlar.
+4. **Kanıtlar.** Testi suçlu commit'te (başarısız) ve bir öncekinde (başarılı) yeniden çalıştırır.
+5. **Açıklar ve düzeltir.** Ajan değişikliğin neyi bozduğunu anlatır ve bir düzenleme önerir. whobrokeit düzenlemeyi uygular, testi çalıştırır, yalnız test geçerse gösterir. `git apply` ile uygulanabilen bir patch olarak da kaydeder.
+
+## Gerçek hatalarda denendi
+
+commander, semver, postcss, luxon, marked, express, markdown-it, fastify ve yargs projelerinden kapanmış 12 regresyon issue'sunda çalıştırdım. Araca yalnız issue metni verildi, raporu yazan kişinin yazdığı haliyle. **12 vakanın 11'inde** proje sahiplerinin belirlediği commit'i kanıtladı; her biri yaklaşık 100 saniye sürdü. Vakalar, tutmayan tek vaka ve hepsini yeniden çalıştırma adımları [bench/](bench) klasöründe.
+
+## Reponda güvenle çalışır
+
+- **Çalışma kopyana dokunmaz.** Her kontrol geçici bir `git worktree` içinde yapılır ve sonunda silinir. Commit'lenmemiş değişikliklerin, açık dosyaların ve bulunduğun branch olduğu gibi kalır.
+- **Ajan yalnız okuyabilir.** Claude Code yalnız Read, Grep ve Glob araçlarıyla, hook'ların, eklentilerin ve MCP sunucuların kapalıyken çalışır. Codex kendi salt okunur sandbox'ında çalışır. Ajanın yazdığı testi whobrokeit çalıştırır; güvenmediğin bir repoda bu testi kontrol et.
+- **Hiçbir şey sözle kabul edilmez.** Test `HEAD`'de bildirilen sebeple başarısız olmalı, suçlu commit bir öncekiyle karşılaştırılarak kanıtlanmalı, düzeltme de testi geçirmeli.
+- **Bağımlılıklar commit başına kurulur:** `package.json` ya da lockfile değiştiğinde (npm, pnpm, yarn, bun). Başka bir şey için `--setup "<komut>"`, hiç kurmamak için `--no-setup`.
+
+## Seçenekler
+
+| Seçenek | |
+|---|---|
+| `-t, --test <cmd>` | Hata varken başarısız olan bir komut. |
+| `--agent <name>` | Testi kim yazar: `claude`, `codex` ya da stdin'den talimat alıp stdout'a cevap yazan herhangi bir komut. Varsayılan: `claude`, yoksa `codex`. |
+| `--model <name>` | Ajanın modeli, örn. `sonnet`. |
+| `--explain` / `--no-explain` | Suçlu commit'i açıkla ve düzeltme dene. Hatayı anlattığında açık, `--test` ile kapalı. |
+| `-w, --with <file>` | Bu dosyayı çalışma kopyandan test edilen her commit'e kopyala. Birden çok verilebilir. |
+| `-g, --good <ref>` | Hâlâ çalıştığı bir commit. Varsayılan: otomatik bulunur. |
+| `-b, --bad <ref>` | Bozuk olduğu bir commit. Varsayılan: `HEAD`. |
+| `--setup <cmd>` / `--no-setup` | Kurulum komutu, bağımlılık dosyaları değişince yeniden çalışır. Varsayılan: otomatik. |
+| `--timeout <sec>` | Her test çalıştırması için süre sınırı. Varsayılan: 600, ajanın yazdığı testlerde 300. |
+| `--report <file>` | Ayrıca issue ya da PR'a yapıştırmaya hazır bir Markdown rapor yaz. |
+| `--json` | Sonucu JSON olarak bas. |
+
+Çıkış kodları: `0` bulundu ve kanıtlandı · `1` hata · `2` hata yeniden üretilemedi · `3` çalışan commit bulunamadı · `4` sonuçsuz.
+
+## Bilmekte fayda var
+
+- Node.js 20+ ve git gerekir. Başka bağımlılık yok.
+- Test, projenin kullandığı herhangi bir dilde olabilir. Otomatik bağımlılık kurulumu JavaScript paket yöneticilerini kapsar; diğerleri için `--setup` kullan.
+- Ajanla bir çalıştırma genelde iki istek yapar: biri testi yazmak, biri suçlu commit'i açıklamak için (sonuç tutmazsa her biri bir kez daha denenir). Demo reposunda tüm süreç 30–60 saniye sürer.
+- Proje lockfile commit'lemiyorsa eski commit'ler bağımlılıklarının bugünkü sürümleriyle kurulur. Bir bağımlılığın sürümüne bağlı hatalarda yanlış commit bulunabilir.
+- İş bitince ajanın yazdığı test ve düzeltme `.git/whobrokeit/` içinde durur, çalışma klasörünün dışında.
+
+## Lisans
+
+[MIT](LICENSE)

package/dist/agent.js

@@ -0,0 +1,185 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { UserError } from './errors.js';
+import { runCommand } from './exec.js';
+const PRESETS = ['claude', 'codex'];
+const LABELS = { claude: 'Claude Code', codex: 'Codex' };
+/**
+ * `undefined` picks the first installed preset. A preset name picks that one.
+ * Anything else is a custom command: it gets the prompt on stdin and answers on stdout.
+ */
+export async function pickAgent(choice, cwd, model) {
+    if (model !== undefined && !/^[\w.:/@[\]-]+$/.test(model))
+        throw new UserError(`--model ${model} is not a valid model name.`);
+    if (choice !== undefined && !PRESETS.includes(choice)) {
+        if (model !== undefined)
+            throw new UserError('--model only works with --agent claude or --agent codex.');
+        return customAgent(choice);
+    }
+    const candidates = choice ? [choice] : [...PRESETS];
+    for (const name of candidates) {
+        const probe = await runCommand(`${name} --version`, cwd, 30_000);
+        if (probe.code === 0)
+            return name === 'claude' ? claudeAgent(model) : codexAgent(model);
+    }
+    if (choice) {
+        throw new UserError(`${LABELS[choice]} (\`${choice}\`) is not installed or not on your PATH.`);
+    }
+    throw new UserError('Describing a bug in plain words needs Claude Code or Codex installed.', 'Install one of them, use --agent "<command>" for another tool, or pass your own test with --test "<command>".');
+}
+function claudeAgent(model) {
+    const label = LABELS.claude;
+    const command = [
+        'claude -p',
+        '--output-format stream-json --verbose',
+        // Read-only tools, no hooks, plugins or MCP servers, nothing left in the session list.
+        '--tools Read,Grep,Glob',
+        '--permission-prompts none',
+        '--safe-mode --strict-mcp-config',
+        '--no-session-persistence',
+        model ? `--model ${model}` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return {
+        label,
+        async ask(prompt, cwd, { timeoutMs, onActivity }) {
+            let result;
+            const lines = lineSplitter((line) => {
+                if (!line.startsWith('{'))
+                    return;
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (event.type === 'assistant') {
+                    for (const part of event.message?.content ?? []) {
+                        if (part.type === 'tool_use')
+                            onActivity?.(describeTool(part.name, part.input ?? {}, cwd));
+                    }
+                }
+                else if (event.type === 'result') {
+                    result = { text: event.result ?? '', isError: Boolean(event.is_error), subtype: event.subtype };
+                }
+            });
+            // The user's `language` setting survives --safe-mode and beats the prompt's "write in the bug
+            // report's language" rule, so a Turkish setting turned English reports into Turkish answers.
+            const dir = await mkdtemp(join(tmpdir(), 'whobrokeit-claude-'));
+            const settings = join(dir, 'settings.json');
+            let run;
+            try {
+                await writeFile(settings, JSON.stringify({ language: '' }));
+                run = await runCommand(`${command} --settings "${settings}"`, cwd, timeoutMs, { input: prompt, onStdout: lines.push });
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
+            }
+            lines.flush();
+            // Its own error message (a bad key, no credit) says more than the exit code does.
+            if (!result?.isError || run.timedOut)
+                failIfBroken(label, run, timeoutMs, result === undefined);
+            if (result?.isError) {
+                throw new UserError(`${label} stopped with an error: ${result.text || result.subtype || 'unknown error'}`);
+            }
+            return result?.text ?? '';
+        },
+    };
+}
+function codexAgent(model) {
+    const label = LABELS.codex;
+    return {
+        label,
+        async ask(prompt, cwd, { timeoutMs }) {
+            const dir = await mkdtemp(join(tmpdir(), 'whobrokeit-codex-'));
+            const answerFile = join(dir, 'answer.txt');
+            try {
+                const command = [
+                    'codex exec',
+                    '--sandbox read-only --skip-git-repo-check --ephemeral --color never',
+                    model ? `-m ${model}` : '',
+                    `-o "${answerFile}"`,
+                    '-',
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                const run = await runCommand(command, cwd, timeoutMs, { input: prompt });
+                const answer = await readFile(answerFile, 'utf8').catch(() => null);
+                failIfBroken(label, run, timeoutMs, answer === null);
+                return answer ?? '';
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
+            }
+        },
+    };
+}
+function customAgent(command) {
+    return {
+        label: command,
+        async ask(prompt, cwd, { timeoutMs }) {
+            let stdout = '';
+            const run = await runCommand(command, cwd, timeoutMs, { input: prompt, onStdout: (text) => (stdout += text) });
+            failIfBroken(command, run, timeoutMs, false);
+            return stdout;
+        },
+    };
+}
+function failIfBroken(label, run, timeoutMs, noAnswer) {
+    if (run.timedOut) {
+        throw new UserError(`${label} did not answer within ${Math.round(timeoutMs / 60_000)} minutes.`);
+    }
+    if (run.code === 0 && !noAnswer)
+        return;
+    // Drop the JSON event stream; keep what a human would read.
+    const said = run.output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('{'))
+        .slice(-8)
+        .join('\n');
+    throw new UserError(`${label} failed (exit code ${run.code}).${said ? `\n${said}` : ''}`, 'Check that it works on its own in this terminal (is it logged in?), or pass your own test with --test.');
+}
+function describeTool(name, input, cwd) {
+    const str = (key) => (typeof input[key] === 'string' ? input[key] : '');
+    const where = (path) => {
+        if (!path)
+            return '';
+        const rel = isAbsolute(path) ? relative(cwd, path) : path;
+        if (!rel)
+            return '.';
+        return rel.startsWith('..') ? path : rel.split(sep).join('/');
+    };
+    switch (name) {
+        case 'Read':
+            return `reading ${where(str('file_path'))}`;
+        case 'Grep':
+            return `searching for "${str('pattern')}"${str('path') ? ` in ${where(str('path'))}` : ''}`;
+        case 'Glob':
+            return `looking for ${str('pattern')}${str('path') ? ` in ${where(str('path'))}` : ''}`;
+        default:
+            return `using ${name ?? 'a tool'}`;
+    }
+}
+/** Turns arbitrary stdout chunks into whole lines. */
+function lineSplitter(onLine) {
+    let buffer = '';
+    return {
+        push: (text) => {
+            buffer += text;
+            let newline;
+            while ((newline = buffer.indexOf('\n')) !== -1) {
+                onLine(buffer.slice(0, newline).trim());
+                buffer = buffer.slice(newline + 1);
+            }
+        },
+        flush: () => {
+            if (buffer.trim())
+                onLine(buffer.trim());
+            buffer = '';
+        },
+    };
+}