faberwright 0.3.0

package/dist/checkpoints.js

@@ -0,0 +1,147 @@
+/**
+ * Checkpoints v2 — reversible, inspectable recovery.
+ *
+ * Each task begins a checkpoint capturing files BEFORE modification.
+ * New in v2:
+ *  - restore(id) is NON-DESTRUCTIVE: before restoring, the CURRENT state of
+ *    the same files is saved as a new "restore-point" checkpoint — so every
+ *    restore can itself be undone (that's redo). Nothing is ever lost.
+ *  - list() exposes history: id, kind, label, files touched, timestamp.
+ *  - undoLast() = restore(newest); redo = restore the restore-point that the
+ *    last restore created (tracked per session).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+let seq = 0;
+/** Timestamp + monotonic counter: unique even within the same millisecond. */
+function newId(suffix = "") {
+    seq = (seq + 1) % 10_000;
+    return new Date().toISOString().replace(/[:.]/g, "-") +
+        "-" + String(seq).padStart(4, "0") + suffix;
+}
+export class CheckpointManager {
+    workspace;
+    root;
+    current;
+    manifest = [];
+    label = "";
+    lastRestorePointId;
+    constructor(stateDir, workspace) {
+        this.workspace = workspace;
+        this.root = path.join(stateDir, "checkpoints");
+        fs.mkdirSync(this.root, { recursive: true });
+    }
+    begin(label = "") {
+        const id = newId();
+        this.current = path.join(this.root, id);
+        fs.mkdirSync(this.current, { recursive: true });
+        this.manifest = [];
+        this.label = label.replace(/\s+/g, " ").trim().slice(0, 80);
+        return id;
+    }
+    snapshot(filePath) {
+        if (!this.current)
+            this.begin();
+        const abs = path.resolve(filePath);
+        const rel = path.relative(this.workspace, abs);
+        if (this.manifest.some((e) => e.path === rel))
+            return; // keep earliest state
+        const existed = fs.existsSync(abs);
+        if (existed) {
+            const dest = path.join(this.current, "files", rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.copyFileSync(abs, dest);
+        }
+        this.manifest.push({ path: rel, existed });
+        this.writeManifest(this.current, { kind: "task", label: this.label, entries: this.manifest });
+    }
+    commit() {
+        if (this.current && this.manifest.length === 0) {
+            fs.rmSync(this.current, { recursive: true, force: true });
+        }
+        this.current = undefined;
+        this.manifest = [];
+    }
+    list() {
+        if (!fs.existsSync(this.root))
+            return [];
+        const out = [];
+        for (const d of fs.readdirSync(this.root).sort()) {
+            const mPath = path.join(this.root, d, "manifest.json");
+            if (!fs.existsSync(mPath))
+                continue;
+            try {
+                const m = JSON.parse(fs.readFileSync(mPath, "utf8"));
+                out.push({
+                    id: d, kind: m.kind ?? "task", label: m.label ?? "",
+                    files: m.entries.map((e) => e.path), mtimeMs: fs.statSync(mPath).mtimeMs,
+                });
+            }
+            catch { /* skip corrupt */ }
+        }
+        return out;
+    }
+    /**
+     * Restore files to their state in checkpoint `id`.
+     * Current state of those files is first saved as a restore-point, so this
+     * operation is always reversible. Returns restored paths, or undefined if
+     * the checkpoint does not exist.
+     */
+    restore(id) {
+        const cpDir = path.join(this.root, id);
+        const mPath = path.join(cpDir, "manifest.json");
+        if (!fs.existsSync(mPath))
+            return undefined;
+        const manifest = JSON.parse(fs.readFileSync(mPath, "utf8"));
+        // 1. save current state of the same files as a restore-point (the redo data)
+        const rpId = newId("-rp");
+        const rpDir = path.join(this.root, rpId);
+        fs.mkdirSync(rpDir, { recursive: true });
+        const rpEntries = [];
+        for (const entry of manifest.entries) {
+            const abs = path.join(this.workspace, entry.path);
+            const existsNow = fs.existsSync(abs);
+            if (existsNow) {
+                const dest = path.join(rpDir, "files", entry.path);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.copyFileSync(abs, dest);
+            }
+            rpEntries.push({ path: entry.path, existed: existsNow });
+        }
+        this.writeManifest(rpDir, { kind: "restore-point", label: `before restoring ${id}`, entries: rpEntries });
+        this.lastRestorePointId = rpId;
+        // 2. restore from the target checkpoint (data kept — restore is repeatable)
+        const restored = [];
+        for (const entry of manifest.entries) {
+            const target = path.join(this.workspace, entry.path);
+            if (entry.existed) {
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.copyFileSync(path.join(cpDir, "files", entry.path), target);
+            }
+            else if (fs.existsSync(target)) {
+                fs.unlinkSync(target);
+            }
+            restored.push(entry.path);
+        }
+        return restored;
+    }
+    /** Undo the most recent task (non-destructive; see restore). */
+    undoLast() {
+        const all = this.list();
+        const last = all.at(-1);
+        if (!last)
+            return [];
+        return this.restore(last.id) ?? [];
+    }
+    /** Redo: revert the last restore performed in this session. */
+    redo() {
+        if (!this.lastRestorePointId)
+            return undefined;
+        const id = this.lastRestorePointId;
+        this.lastRestorePointId = undefined;
+        return this.restore(id);
+    }
+    writeManifest(dir, m) {
+        fs.writeFileSync(path.join(dir, "manifest.json"), JSON.stringify(m, null, 2));
+    }
+}

package/dist/config.js

@@ -0,0 +1,68 @@
+/**
+ * Configuration: env vars > .faber/config.json > defaults.
+ * State lives in <workspace>/.faber/ — except in projects created before the
+ * rename, where an existing .codewright/ directory is adopted as-is so memory,
+ * code graph, sessions and usage history survive the upgrade untouched.
+ * FABER_* env vars are canonical; legacy CW_* names still work.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5";
+export const DEFAULT_OPENAI_MODEL = "gpt-4o";
+/** Accept both FABER_* (canonical) and CW_* (legacy) env var names. */
+export function normalizeEnv() {
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (key.startsWith("CW_")) {
+            const canonical = "FABER_" + key.slice(3);
+            if (process.env[canonical] === undefined)
+                process.env[canonical] = value;
+        }
+        else if (key.startsWith("FABER_")) {
+            const legacy = "CW_" + key.slice(6);
+            if (process.env[legacy] === undefined)
+                process.env[legacy] = value;
+        }
+    }
+}
+export function loadConfig(workspace) {
+    normalizeEnv();
+    const ws = path.resolve(workspace ?? process.cwd());
+    const legacyDir = path.join(ws, ".codewright");
+    const stateDir = fs.existsSync(legacyDir) ? legacyDir : path.join(ws, ".faber");
+    fs.mkdirSync(path.join(stateDir, "checkpoints"), { recursive: true });
+    fs.mkdirSync(path.join(stateDir, "sessions"), { recursive: true });
+    let fileCfg = {};
+    const cfgPath = path.join(stateDir, "config.json");
+    if (fs.existsSync(cfgPath)) {
+        try {
+            fileCfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+        }
+        catch { /* ignore malformed */ }
+    }
+    const s = (k) => typeof fileCfg[k] === "string" ? fileCfg[k] : undefined;
+    const provider = (process.env.CW_PROVIDER ?? s("provider") ?? "anthropic").toLowerCase();
+    const anthropic = provider === "anthropic";
+    return {
+        workspace: ws,
+        stateDir,
+        provider,
+        model: process.env.CW_MODEL ?? s("model") ?? (anthropic ? DEFAULT_ANTHROPIC_MODEL : DEFAULT_OPENAI_MODEL),
+        baseUrl: process.env.CW_BASE_URL ?? s("baseUrl") ?? (anthropic ? "https://api.anthropic.com" : "https://api.openai.com/v1"),
+        apiKey: anthropic ? (process.env.ANTHROPIC_API_KEY ?? s("apiKey")) : (process.env.OPENAI_API_KEY ?? s("apiKey")),
+        weakModel: process.env.CW_WEAK_MODEL ?? s("weakModel"),
+        maxTokens: 4096,
+        maxIterations: Number(process.env.CW_MAX_ITERATIONS ?? fileCfg["maxIterations"] ?? 40),
+        contextTokenBudget: Number(process.env.CW_CONTEXT_BUDGET ?? fileCfg["contextTokenBudget"] ?? 60_000),
+        keepRecentMessages: 12,
+        shellTimeoutMs: Number(process.env.CW_SHELL_TIMEOUT ?? fileCfg["shellTimeoutMs"] ?? 120_000),
+        maxFileReadBytes: 200_000,
+        retryMaxAttempts: 5,
+        approvalMode: (process.env.CW_APPROVAL ?? s("approvalMode") ?? "ask"),
+        memoryDb: path.join(stateDir, "memory.db"),
+        indexDb: path.join(stateDir, "index.db"),
+        sessionsDir: path.join(stateDir, "sessions"),
+        usageDb: path.join(stateDir, "usage.db"),
+    };
+}

package/dist/editor.js

@@ -0,0 +1,417 @@
+/**
+ * Raw-mode line editor with paste chips.
+ *
+ * v2: full cursor editing. Left/Right/Home/End/Delete, Ctrl-A/E/K/U,
+ * Up/Down history. Rendering is SINGLE-ROW WINDOWED: long input scrolls
+ * horizontally behind `…` markers instead of wrapping — so cursor math is
+ * always exact and the "backspace can't cross a wrapped line" bug class
+ * cannot exist. Multi-line pastes are atomic chips: one arrow-key step,
+ * one backspace, never split.
+ */
+import pc from "picocolors";
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+export class Composer {
+    stdin;
+    stdout;
+    buf = [];
+    cursor = 0; // index into buf (0..buf.length)
+    history = [];
+    histIdx = null;
+    draftBeforeHistory = "";
+    inPaste = false;
+    pasteBuf = "";
+    tail = "";
+    pasteCount = 0;
+    active = "off";
+    promptText = "";
+    resolveLine;
+    steerCb;
+    interruptCb;
+    lastRender = "";
+    boundData = (b) => this.onData(b);
+    constructor(stdin, stdout) {
+        this.stdin = stdin;
+        this.stdout = stdout;
+    }
+    start() {
+        this.stdout.write("\x1b[?2004h");
+        this.stdin.setRawMode(true);
+        this.stdin.resume();
+        this.stdin.on("data", this.boundData);
+    }
+    stop() {
+        this.stdin.removeListener("data", this.boundData);
+        if (this.stdin.isTTY)
+            this.stdin.setRawMode(false);
+        this.stdout.write("\x1b[?2004l");
+    }
+    pause() { this.stdin.removeListener("data", this.boundData); }
+    resume() { this.stdin.on("data", this.boundData); }
+    onInterrupt(cb) { this.interruptCb = cb; }
+    readLine(prompt) {
+        this.active = "prompt";
+        this.promptText = prompt;
+        this.reset();
+        this.render();
+        return new Promise((resolve) => { this.resolveLine = resolve; });
+    }
+    enterSteerMode(cb) {
+        this.active = "steer";
+        this.reset();
+        this.steerCb = cb;
+    }
+    exitSteerMode() { this.active = "off"; this.steerCb = undefined; this.reset(); }
+    // ---------------------------------------------------------------- model
+    reset() {
+        this.buf = [];
+        this.cursor = 0;
+        this.inPaste = false;
+        this.pasteBuf = "";
+        this.pasteCount = 0;
+        this.histIdx = null;
+        this.lastRender = "";
+        this.lastCursorRow = 0;
+    }
+    compose() {
+        return this.buf.map((it) => (it.kind === "ch" ? it.ch : it.value)).join("");
+    }
+    setFromString(s) {
+        this.buf = [...s].map((ch) => ({ kind: "ch", ch }));
+        this.cursor = this.buf.length;
+    }
+    // --------------------------------------------------------------- render
+    lastCursorRow = 0; // row (0-based) where cursor sat after last render
+    /**
+     * TRUE MULTI-ROW render: the draft wraps across
+     * terminal rows and the cursor is placed exactly, including across wrap
+     * boundaries. Algorithm (same family as GNU readline / linenoise):
+     *  1. return to the render origin (up lastCursorRow rows, column 0)
+     *  2. clear everything below (ESC[J)
+     *  3. print prompt + full colored content; if the content ends exactly at
+     *     the last column, emit \n to COMMIT the pending wrap so row math is
+     *     deterministic across terminals
+     *  4. compute cursor (row, col) from display-cell width and move there
+     */
+    render() {
+        if (this.active !== "prompt")
+            return;
+        const cols = Math.max(8, this.stdout.columns || 80);
+        const promptW = stripAnsi(this.promptText).length;
+        const cells = [];
+        const itemStartCell = [];
+        for (const it of this.buf) {
+            itemStartCell.push(cells.length);
+            if (it.kind === "ch")
+                cells.push({ ch: it.ch, chip: false });
+            else
+                for (const ch of it.label)
+                    cells.push({ ch, chip: true });
+        }
+        itemStartCell.push(cells.length);
+        let colored = "";
+        let inChip = false;
+        for (const c of cells) {
+            if (c.chip && !inChip) {
+                colored += "\x1b[36m";
+                inChip = true;
+            }
+            if (!c.chip && inChip) {
+                colored += "\x1b[39m";
+                inChip = false;
+            }
+            colored += c.ch;
+        }
+        if (inChip)
+            colored += "\x1b[39m";
+        const total = promptW + cells.length;
+        const endCommitsWrap = total > 0 && total % cols === 0;
+        const cursorCell = promptW + itemStartCell[this.cursor];
+        const tRow = Math.floor(cursorCell / cols);
+        const tCol = cursorCell % cols;
+        const endRow = total === 0 ? 0 : Math.floor(total / cols) - (endCommitsWrap ? 0 : 0);
+        // after printing (+ committed wrap \n when needed), terminal cursor is at:
+        const printedEndRow = endCommitsWrap ? total / cols : Math.floor(total / cols);
+        let out = "\r";
+        if (this.lastCursorRow > 0)
+            out += `\x1b[${this.lastCursorRow}A`;
+        out += "\x1b[J";
+        out += this.promptText + colored;
+        if (endCommitsWrap)
+            out += "\n";
+        // move from printed end position to the target cursor cell
+        const up = printedEndRow - tRow;
+        if (up > 0)
+            out += `\x1b[${up}A`;
+        out += "\r";
+        if (tCol > 0)
+            out += `\x1b[${tCol}C`;
+        this.lastCursorRow = tRow;
+        this.lastRender = out;
+        this.stdout.write(out);
+        void endRow;
+    }
+    /** Move the terminal cursor to the end of the draft (before submit/clear). */
+    gotoEnd() {
+        if (this.active !== "prompt")
+            return;
+        const cols = Math.max(8, this.stdout.columns || 80);
+        const promptW = stripAnsi(this.promptText).length;
+        const contentW = this.buf.reduce((n, it) => n + (it.kind === "ch" ? 1 : it.label.length), 0);
+        const total = promptW + contentW;
+        const endRow = total === 0 ? 0 : Math.floor((total % cols === 0 && total > 0 ? total - 1 : total) / cols);
+        const down = endRow - this.lastCursorRow;
+        if (down > 0)
+            this.stdout.write(`\x1b[${down}B`);
+        this.lastCursorRow = 0;
+    }
+    echoSteer(s) { this.stdout.write(pc.magenta(s)); }
+    // ----------------------------------------------------------------- keys
+    onData(buf) {
+        let s = this.tail + buf.toString("utf8");
+        this.tail = "";
+        for (let keep = Math.min(PASTE_START.length - 1, s.length); keep > 0; keep--) {
+            const suffix = s.slice(-keep);
+            if (PASTE_START.startsWith(suffix) || PASTE_END.startsWith(suffix)) {
+                this.tail = suffix;
+                s = s.slice(0, -keep);
+                break;
+            }
+        }
+        let i = 0;
+        let dirty = false;
+        const done = () => this.active === "off";
+        while (i < s.length && !done()) {
+            if (!this.inPaste && s.startsWith(PASTE_START, i)) {
+                this.inPaste = true;
+                this.pasteBuf = "";
+                i += PASTE_START.length;
+                continue;
+            }
+            if (this.inPaste) {
+                const end = s.indexOf(PASTE_END, i);
+                if (end === -1) {
+                    this.pasteBuf += s.slice(i);
+                    return;
+                }
+                this.pasteBuf += s.slice(i, end);
+                i = end + PASTE_END.length;
+                this.inPaste = false;
+                this.finishPaste();
+                dirty = true;
+                continue;
+            }
+            const ch = s[i];
+            if (ch === "\x1b") { // escape sequences
+                const seq = this.readEscape(s, i);
+                i += seq.len;
+                dirty = this.handleEscape(seq.code) || dirty;
+                continue;
+            }
+            i++;
+            switch (ch) {
+                case "\r":
+                case "\n":
+                    this.submit();
+                    break;
+                case "\x03":
+                    this.ctrlC();
+                    break;
+                case "\x04":
+                    this.ctrlD();
+                    break;
+                case "\x7f":
+                case "\b":
+                    dirty = this.backspace() || dirty;
+                    break;
+                case "\x01":
+                    this.cursor = 0;
+                    dirty = true;
+                    break; // Ctrl-A home
+                case "\x05":
+                    this.cursor = this.buf.length;
+                    dirty = true;
+                    break; // Ctrl-E end
+                case "\x0b":
+                    this.buf.splice(this.cursor);
+                    dirty = true;
+                    break; // Ctrl-K kill->end
+                case "\x15":
+                    this.buf.splice(0, this.cursor);
+                    this.cursor = 0;
+                    dirty = true;
+                    break; // Ctrl-U
+                default:
+                    if (ch >= " " || ch === "\t") {
+                        this.buf.splice(this.cursor, 0, { kind: "ch", ch });
+                        this.cursor++;
+                        if (this.active === "steer")
+                            this.echoSteer(ch);
+                        dirty = true;
+                    }
+            }
+        }
+        if (dirty && this.active === "prompt")
+            this.render();
+    }
+    readEscape(s, i) {
+        if (s[i + 1] === "[" || s[i + 1] === "O") {
+            let j = i + 2;
+            while (j < s.length && !/[A-Za-z~]/.test(s[j]))
+                j++;
+            return { code: s.slice(i + 1, j + 1), len: j + 1 - i };
+        }
+        return { code: "", len: 1 }; // bare Esc
+    }
+    handleEscape(code) {
+        switch (code) {
+            case "[D":
+                this.cursor = Math.max(0, this.cursor - 1);
+                return true;
+            case "[C":
+                this.cursor = Math.min(this.buf.length, this.cursor + 1);
+                return true;
+            case "[H":
+            case "OH":
+            case "[1~":
+                this.cursor = 0;
+                return true;
+            case "[F":
+            case "OF":
+            case "[4~":
+                this.cursor = this.buf.length;
+                return true;
+            case "[3~": // forward delete
+                if (this.cursor < this.buf.length) {
+                    this.buf.splice(this.cursor, 1);
+                    return true;
+                }
+                return false;
+            case "[A": return this.historyStep(-1); // up
+            case "[B": return this.historyStep(+1); // down
+            case "":
+                this.ctrlC();
+                return false; // bare Esc = cancel, like Ctrl-C
+            default: return false;
+        }
+    }
+    historyStep(dir) {
+        if (this.active !== "prompt" || !this.history.length)
+            return false;
+        if (this.histIdx === null) {
+            if (dir === 1)
+                return false;
+            this.draftBeforeHistory = this.compose();
+            this.histIdx = this.history.length - 1;
+        }
+        else {
+            this.histIdx += dir;
+            if (this.histIdx >= this.history.length) { // walked past newest -> restore draft
+                this.histIdx = null;
+                this.setFromString(this.draftBeforeHistory);
+                return true;
+            }
+            this.histIdx = Math.max(0, this.histIdx);
+        }
+        this.setFromString(this.history[this.histIdx] ?? "");
+        return true;
+    }
+    finishPaste() {
+        const raw = this.pasteBuf.replace(/\r\n?/g, "\n");
+        this.pasteBuf = "";
+        if (!raw)
+            return;
+        const lines = raw.split("\n").length;
+        if (lines === 1 && raw.length < 200) { // small paste: inline as chars
+            for (const ch of raw)
+                this.buf.splice(this.cursor++, 0, { kind: "ch", ch });
+            if (this.active === "steer")
+                this.echoSteer(raw);
+            return;
+        }
+        // paste-again-to-expand: same content as the chip just before the cursor
+        const prev = this.buf[this.cursor - 1];
+        if (prev?.kind === "chip" && prev.value === raw) {
+            this.buf.splice(this.cursor - 1, 1);
+            this.cursor--;
+            for (const ch of raw)
+                this.buf.splice(this.cursor++, 0, { kind: "ch", ch });
+            if (this.active === "steer")
+                this.echoSteer(raw);
+            return;
+        }
+        this.pasteCount++;
+        const hint = this.pasteCount === 1 ? " — paste again to expand" : "";
+        const label = `[pasted #${this.pasteCount} +${lines} lines${hint}]`;
+        this.buf.splice(this.cursor++, 0, { kind: "chip", value: raw, label });
+        if (this.active === "steer")
+            this.stdout.write(pc.cyan(label));
+    }
+    backspace() {
+        if (this.cursor === 0)
+            return false;
+        const removed = this.buf.splice(this.cursor - 1, 1)[0];
+        this.cursor--;
+        if (this.active === "steer") {
+            const w = removed.kind === "ch" ? 1 : removed.label.length;
+            this.stdout.write("\b \b".repeat(w));
+        }
+        return true;
+    }
+    submit() {
+        const text = this.compose();
+        this.gotoEnd();
+        this.stdout.write("\n");
+        if (this.active === "prompt") {
+            if (text.trim())
+                this.history.push(text);
+            const r = this.resolveLine;
+            this.resolveLine = undefined;
+            this.active = "off";
+            r?.(text);
+        }
+        else if (this.active === "steer" && text.trim()) {
+            this.steerCb?.(text);
+            this.reset();
+        }
+        else {
+            this.reset();
+        }
+    }
+    ctrlC() {
+        if (this.active === "steer") {
+            this.interruptCb?.();
+            return;
+        }
+        if (this.active === "prompt") {
+            if (this.buf.length) {
+                this.gotoEnd();
+                this.stdout.write("^C\n");
+                this.lastCursorRow = 0;
+                this.reset();
+                this.render();
+            }
+            else {
+                const r = this.resolveLine;
+                this.resolveLine = undefined;
+                this.active = "off";
+                this.stdout.write("\n");
+                r?.(null);
+            }
+        }
+    }
+    ctrlD() {
+        if (this.active === "prompt" && !this.buf.length) {
+            const r = this.resolveLine;
+            this.resolveLine = undefined;
+            this.active = "off";
+            this.stdout.write("\n");
+            r?.(null);
+        }
+    }
+    static describe(text) {
+        const lines = text.split("\n");
+        return lines.length <= 1 ? text.slice(0, 80) : `[${lines.length} lines]`;
+    }
+}

package/dist/errors.js

@@ -0,0 +1,52 @@
+/**
+ * Error taxonomy — three layers of defense:
+ *  1. TransientAPIError  -> retried with exponential backoff + jitter
+ *  2. ToolError          -> returned to the model (is_error) so it self-corrects
+ *  3. FatalError         -> surfaced to the user; checkpoints stay intact for /undo
+ */
+export class ForgeError extends Error {
+}
+export class ToolError extends ForgeError {
+}
+export class TransientAPIError extends ForgeError {
+    retryAfter;
+    constructor(message, retryAfter) {
+        super(message);
+        this.retryAfter = retryAfter;
+    }
+}
+export class FatalError extends ForgeError {
+}
+export class CancelledError extends ForgeError {
+    constructor() { super("Task cancelled by user."); }
+}
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => { clearTimeout(t); reject(new CancelledError()); }, { once: true });
+});
+/** Retry `fn` on TransientAPIError with exponential backoff + jitter; honors Retry-After. */
+export async function withRetries(fn, opts = {}) {
+    const { maxAttempts = 5, baseDelayMs = 1500, maxDelayMs = 60_000, signal, onRetry } = opts;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (signal?.aborted)
+            throw new CancelledError();
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (!(err instanceof TransientAPIError))
+                throw err;
+            lastErr = err;
+            if (attempt === maxAttempts)
+                break;
+            let delay = err.retryAfter != null
+                ? err.retryAfter * 1000
+                : Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+            delay *= 0.8 + 0.4 * Math.random(); // jitter
+            onRetry?.(attempt, err, delay);
+            await sleep(delay, signal);
+        }
+    }
+    throw new FatalError(`API request failed after ${maxAttempts} attempts: ${lastErr?.message}`);
+}