@cairn-tool/cairn 3.4.0 → 3.5.0

package/dist/qa/agent.js

@@ -0,0 +1,142 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, writeFileSync, writeSync } from "node:fs";
+import { once } from "node:events";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { flatten, isBlank } from "./format.js";
+import { signalNumber } from "./async.js";
+import { shellJoin } from "./cases.js";
+/**
+ * Signal the whole process group — `detached: true` gave the child its own session, so a
+ * negative pid reaches cursor-agent and everything it spawned. Never uses `child.killed` as a
+ * guard: that stays false when the group is signalled directly.
+ */
+export function killGroup(child, sig) {
+    if (child.pid === undefined)
+        return;
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        process.kill(-child.pid, sig);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return;
+        try {
+            child.kill(sig);
+        }
+        catch {
+            /* already reaped */
+        }
+    }
+}
+/** Python reports -9 for a SIGKILLed child; Node reports {code: null, signal}. */
+export function effectiveExitCode(code, sig) {
+    if (code !== null)
+        return code;
+    return sig ? -signalNumber(sig) : null;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export async function runAgent(spec) {
+    mkdirSync(spec.logDir, { recursive: true });
+    writeFileSync(join(spec.logDir, "command.txt"), `${shellJoin(spec.argv)}\n`, "utf8");
+    const [file, ...args] = spec.argv;
+    const child = spawn(file, args, {
+        cwd: spec.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: true, // == start_new_session=True; do NOT unref, we must await this child
+    });
+    // Python raises FileNotFoundError synchronously; Node reports it on 'error'. Convert it back
+    // so a bad --agent becomes a per-case error record, not an unhandled rejection.
+    //
+    // Both listeners are removed as soon as one of them wins. A bare Promise.race leaves the
+    // loser attached, and Node emits 'error' on a ChildProcess *after* spawn when a kill fails
+    // — reachable from killGroup, where a process.kill(-pid) failing with anything but ESRCH
+    // falls through to child.kill(). That would reject a promise nothing awaits, and Cleanup's
+    // unhandled-rejection handler calls process.exit(1), tearing down every other running case
+    // and truncating a pending --format json write.
+    await new Promise((resolve, reject) => {
+        const onSpawned = () => {
+            child.off("error", onFailed);
+            resolve();
+        };
+        const onFailed = (err) => {
+            child.off("spawn", onSpawned);
+            reject(err);
+        };
+        child.once("spawn", onSpawned);
+        child.once("error", onFailed);
+    });
+    spec.onSpawn(child);
+    // Note: Node reads up to its 64 KiB highWaterMark rather than the Python's 8 KiB, and spawn
+    // does not expose that knob for stdio pipes. The streamed-bytes total is identical; only the
+    // on-screen counter's step size differs.
+    const streamFd = openSync(join(spec.logDir, "stream.jsonl"), "a");
+    const stderrFd = openSync(join(spec.logDir, "stderr.txt"), "w");
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        killGroup(child, "SIGKILL");
+    }, spec.timeoutMs);
+    const pumpStderr = (async () => {
+        for await (const chunk of child.stderr)
+            writeSync(stderrFd, chunk);
+    })();
+    const pumpStdout = (async () => {
+        // StringDecoder holds a multi-byte character split across a chunk boundary. The Python
+        // decodes each chunk independently and corrupts those.
+        const decoder = new StringDecoder("utf8");
+        let buf = "";
+        // One path for every line, so the final unterminated one is parsed rather than merely
+        // logged. An agent whose last line lacks a newline would otherwise lose its `result`
+        // event entirely — the case recording usage: null while stream.jsonl shows the tokens.
+        const dispatch = (line) => {
+            if (isBlank(line))
+                return;
+            writeSync(streamFd, `${line}\n`);
+            let obj;
+            try {
+                obj = JSON.parse(line);
+            }
+            catch {
+                spec.onRawLine(flatten(line).slice(0, 200));
+                return;
+            }
+            if (isRecord(obj))
+                spec.onEvent(obj);
+        };
+        for await (const chunk of child.stdout) {
+            const bytes = chunk;
+            spec.onBytes(bytes.length);
+            buf += decoder.write(bytes);
+            let nl = buf.indexOf("\n");
+            while (nl !== -1) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                nl = buf.indexOf("\n");
+                dispatch(line);
+            }
+        }
+        buf += decoder.end();
+        dispatch(buf);
+    })();
+    try {
+        // 'close' fires after both pipes hit EOF *and* the child exits — the faithful composite of
+        // the Python's `async with asyncio.timeout(...): await read_stdout(); await proc.wait()`.
+        const [code, sig] = (await Promise.all([pumpStdout, pumpStderr, once(child, "close")]).then(([, , closed]) => closed));
+        return { exitCode: effectiveExitCode(code, sig), signal: sig, timedOut };
+    }
+    finally {
+        clearTimeout(timer);
+        for (const fd of [streamFd, stderrFd]) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/qa/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/qa/agent.ts"],"names":[],"mappings":"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"}

package/dist/qa/agents/claude-code.d.ts

@@ -0,0 +1,2 @@
+import type { QaAgentProfile } from "./types.js";
+export declare const claudeCodeProfile: QaAgentProfile;

package/dist/qa/agents/claude-code.js

@@ -0,0 +1,121 @@
+import { isRecord, num, sessionIdOf } from "./types.js";
+const TOOL_ARG_FIELDS = [
+    "command",
+    "file_path",
+    "path",
+    "pattern",
+    "glob",
+    "query",
+    "url",
+];
+/**
+ * Claude Code's print+stream-json dialect, captured from claude 2.1.263:
+ *
+ * - `-p --output-format stream-json` refuses without `--verbose`.
+ * - Tools are `tool_use` content blocks inside `assistant` messages, not `tool_call` events.
+ * - Thinking is a `thinking` content block on `assistant`, not a `thinking` event.
+ * - The terminal `result` event carries one authoritative `usage` total (snake_case).
+ *   Assistant lines also carry per-request usage and must not be summed — they fan out
+ *   the way the transcript does, and the result is the session figure.
+ * - `session_id` appears on every event; `system`/`init` carries `model`.
+ */
+function claudeUsage(raw) {
+    if (!isRecord(raw))
+        return null;
+    return {
+        inputTokens: num(raw["input_tokens"]),
+        outputTokens: num(raw["output_tokens"]),
+        cacheReadTokens: num(raw["cache_read_input_tokens"]),
+        cacheWriteTokens: num(raw["cache_creation_input_tokens"]),
+    };
+}
+function toolSummary(input) {
+    for (const field of TOOL_ARG_FIELDS) {
+        const value = input[field];
+        if (value !== undefined && value !== null && value !== "" && value !== 0 && value !== false) {
+            return String(value);
+        }
+    }
+    return "";
+}
+export const claudeCodeProfile = {
+    name: "claude-code",
+    binaries: ["claude"],
+    defaultModel: "sonnet",
+    buildArgv(input, binary) {
+        return [
+            binary,
+            "-p",
+            "--verbose",
+            "--output-format",
+            "stream-json",
+            "--dangerously-skip-permissions",
+            "--model",
+            input.model,
+            input.prompt,
+        ];
+    },
+    normalize(raw) {
+        const kind = raw["type"];
+        const subtype = raw["subtype"];
+        const sessionId = sessionIdOf(raw);
+        if (kind === "system" && subtype === "init") {
+            const model = raw["model"];
+            return { kind: "init", model: model ? String(model) : undefined, sessionId };
+        }
+        if (kind === "assistant") {
+            const message = isRecord(raw["message"]) ? raw["message"] : {};
+            const rawContent = message["content"];
+            const content = Array.isArray(rawContent)
+                ? rawContent
+                : typeof rawContent === "string"
+                    ? [{ type: "text", text: rawContent }]
+                    : [];
+            const events = [];
+            for (const part of content) {
+                if (!isRecord(part))
+                    continue;
+                const partType = part["type"];
+                if (partType === "text" && part["text"]) {
+                    events.push({ kind: "text", text: String(part["text"]), sessionId });
+                }
+                else if (partType === "thinking" && part["thinking"]) {
+                    events.push({
+                        kind: "thinking",
+                        phase: "completed",
+                        text: String(part["thinking"]),
+                        sessionId,
+                    });
+                }
+                else if (partType === "tool_use") {
+                    const name = typeof part["name"] === "string" ? part["name"] : "tool";
+                    const input = isRecord(part["input"]) ? part["input"] : {};
+                    events.push({
+                        kind: "tool",
+                        phase: "started",
+                        name,
+                        summary: toolSummary(input),
+                        sessionId,
+                    });
+                }
+            }
+            return events.length === 0 ? null : events;
+        }
+        if (kind === "result") {
+            const usage = claudeUsage(raw["usage"]);
+            const error = raw["is_error"]
+                ? String(raw["result"] ? raw["result"] : "agent reported an error")
+                : undefined;
+            if (!usage && !error)
+                return null;
+            return {
+                kind: "usage",
+                usage: usage ?? {},
+                ...(error ? { error } : {}),
+                sessionId,
+            };
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=claude-code.js.map

package/dist/qa/agents/claude-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../../src/qa/agents/claude-code.ts"],"names":[],"mappings":"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"}

package/dist/qa/agents/cursor.d.ts

@@ -0,0 +1,5 @@
+import type { QaAgentProfile } from "./types.js";
+/** Return [display name, short args] from a Cursor `tool_call` object. */
+export declare function toolLabel(toolCall: Record<string, unknown>): [string, string];
+export declare function toolFailed(toolCall: Record<string, unknown>): boolean;
+export declare const cursorProfile: QaAgentProfile;

package/dist/qa/agents/cursor.js

@@ -0,0 +1,143 @@
+import { flatten } from "../format.js";
+import { isRecord, num, sessionIdOf } from "./types.js";
+const TOOL_ARG_FIELDS = [
+    "command",
+    "path",
+    "globPattern",
+    "pattern",
+    "query",
+    "target_notebook",
+    "url",
+];
+/** Return [display name, short args] from a Cursor `tool_call` object. */
+export function toolLabel(toolCall) {
+    for (const [key, payload] of Object.entries(toolCall)) {
+        if (!(key.endsWith("ToolCall") && isRecord(payload)))
+            continue;
+        const raw = key.slice(0, -"ToolCall".length);
+        const name = raw ? raw[0].toUpperCase() + raw.slice(1) : key;
+        const args = isRecord(payload["args"]) ? payload["args"] : {};
+        let summary = "";
+        for (const fieldName of TOOL_ARG_FIELDS) {
+            const value = args[fieldName];
+            if (value !== undefined && value !== null && value !== "" && value !== 0 && value !== false) {
+                summary = flatten(String(value));
+                break;
+            }
+        }
+        return [name, summary];
+    }
+    return ["tool", ""];
+}
+export function toolFailed(toolCall) {
+    for (const [key, payload] of Object.entries(toolCall)) {
+        if (key.endsWith("ToolCall") && isRecord(payload)) {
+            const result = payload["result"];
+            return isRecord(result) && "error" in result;
+        }
+    }
+    return false;
+}
+function cursorUsage(raw) {
+    if (!isRecord(raw))
+        return null;
+    return {
+        inputTokens: num(raw["inputTokens"]),
+        outputTokens: num(raw["outputTokens"]),
+        cacheReadTokens: num(raw["cacheReadTokens"]),
+        cacheWriteTokens: num(raw["cacheWriteTokens"]),
+    };
+}
+export const cursorProfile = {
+    name: "cursor",
+    binaries: ["cursor-agent", "agent"],
+    defaultModel: "cursor-grok-4.6-high",
+    buildArgv(input, binary) {
+        return [
+            binary,
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--force",
+            "--trust",
+            "--workspace",
+            input.repo,
+            "--model",
+            input.model,
+            input.prompt,
+        ];
+    },
+    normalize(raw) {
+        const kind = raw["type"];
+        const subtype = raw["subtype"];
+        const sessionId = sessionIdOf(raw);
+        if (kind === "thinking") {
+            if (subtype === "delta") {
+                const text = raw["text"];
+                return {
+                    kind: "thinking",
+                    phase: "delta",
+                    text: typeof text === "string" ? text : "",
+                    sessionId,
+                };
+            }
+            if (subtype === "completed")
+                return { kind: "thinking", phase: "completed", sessionId };
+            return null;
+        }
+        if (kind === "assistant") {
+            const message = isRecord(raw["message"]) ? raw["message"] : {};
+            const rawContent = message["content"];
+            const content = typeof rawContent === "string"
+                ? [{ type: "text", text: rawContent }]
+                : Array.isArray(rawContent)
+                    ? rawContent
+                    : [];
+            const events = [];
+            for (const part of content) {
+                if (isRecord(part) && part["type"] === "text" && part["text"]) {
+                    events.push({ kind: "text", text: String(part["text"]), sessionId });
+                }
+            }
+            return events.length === 0 ? null : events;
+        }
+        if (kind === "tool_call") {
+            const tool = isRecord(raw["tool_call"]) ? raw["tool_call"] : {};
+            const [name, summary] = toolLabel(tool);
+            if (subtype === "started") {
+                return { kind: "tool", phase: "started", name, summary, sessionId };
+            }
+            if (subtype === "completed") {
+                return {
+                    kind: "tool",
+                    phase: "completed",
+                    name,
+                    summary,
+                    failed: toolFailed(tool),
+                    sessionId,
+                };
+            }
+            return null;
+        }
+        if (kind === "result") {
+            const usage = cursorUsage(raw["usage"]);
+            const error = raw["is_error"]
+                ? String(raw["result"] ? raw["result"] : "agent reported an error")
+                : undefined;
+            if (!usage && !error)
+                return null;
+            return {
+                kind: "usage",
+                usage: usage ?? {},
+                ...(error ? { error } : {}),
+                sessionId,
+            };
+        }
+        if (kind === "system" && subtype === "init") {
+            const model = raw["model"];
+            return { kind: "init", model: model ? String(model) : undefined, sessionId };
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=cursor.js.map

package/dist/qa/agents/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/qa/agents/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,eAAe,GAAG;IACtB,SAAS;IACT,MAAM;IACN,aAAa;IACb,SAAS;IACT,OAAO;IACP,iBAAiB;IACjB,KAAK;CACG,CAAC;AAEX,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,QAAiC;IACzD,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC;YAAE,SAAS;QAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,KAAK,MAAM,SAAS,IAAI,eAAe,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;gBAC5F,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBACjC,MAAM;YACR,CAAC;QACH,CAAC;QACD,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,QAAiC;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAClD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YACjC,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,IAAI,MAAM,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO;QACL,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACpC,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACtC,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC5C,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,cAAc,EAAE,OAAO,CAAC;IACnC,YAAY,EAAE,sBAAsB;IACpC,SAAS,CAAC,KAAqB,EAAE,MAAc;QAC7C,OAAO;YACL,MAAM;YACN,IAAI;YACJ,iBAAiB;YACjB,aAAa;YACb,SAAS;YACT,SAAS;YACT,aAAa;YACb,KAAK,CAAC,IAAI;YACV,SAAS;YACT,KAAK,CAAC,KAAK;YACX,KAAK,CAAC,MAAM;SACb,CAAC;IACJ,CAAC;IACD,SAAS,CAAC,GAA4B;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAEnC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;gBACzB,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,KAAK,EAAE,OAAO;oBACd,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;oBAC1C,SAAS;iBACV,CAAC;YACJ,CAAC;YACD,IAAI,OAAO,KAAK,WAAW;gBAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;YACxF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;YACtC,MAAM,OAAO,GACX,OAAO,UAAU,KAAK,QAAQ;gBAC5B,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;gBACtC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;oBACzB,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,EAAE,CAAC;YACX,MAAM,MAAM,GAAc,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC9D,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;gBACvE,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QAC7C,CAAC;QAED,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;YACtE,CAAC;YACD,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5B,OAAO;oBACL,IAAI,EAAE,MAAM;oBACZ,KAAK,EAAE,WAAW;oBAClB,IAAI;oBACJ,OAAO;oBACP,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC;oBACxB,SAAS;iBACV,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACxC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;gBAC3B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC;gBACnE,CAAC,CAAC,SAAS,CAAC;YACd,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YAClC,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,KAAK,IAAI,EAAE;gBAClB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3B,SAAS;aACV,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;QAC/E,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAC"}

package/dist/qa/agents/index.d.ts

@@ -0,0 +1,32 @@
+import type { QaAgentProfile } from "./types.js";
+/**
+ * Every backend `qa run` can spawn.
+ *
+ * Registering another assistant is a new module plus a line here. Nothing
+ * outside this directory may branch on an agent's name: argv, event parsing,
+ * and the default model are read from the profile.
+ */
+export declare const AGENTS: readonly QaAgentProfile[];
+export declare const SUPPORTED_AGENTS: readonly string[];
+export declare function resolveAgent(name: string): QaAgentProfile;
+export declare function defaultModels(): Record<string, string>;
+/**
+ * Resolve the executable for one profile. An explicit `--agent` path overrides
+ * every backend — that is the fake-agent test hook. PATH lookup is lazy and
+ * cached per profile so a cursor-only queue does not fail because `claude` is
+ * absent.
+ */
+export declare function resolveBinary(name: string, explicit: string | null): string;
+/**
+ * The executable to *display* for a profile, for --dry-run only.
+ *
+ * Falls back to the profile's first candidate name when nothing is on PATH: previewing a
+ * queue launches nothing, so requiring the backend to be installed would make `qa run
+ * --dry-run` fail on exactly the machine you would preview a queue on — and would make the
+ * e2e suite depend on cursor-agent and claude being present on the CI runner. An explicit
+ * --agent is still validated, because a bad path there is a real invocation error.
+ */
+export declare function displayBinary(name: string, explicit: string | null): string;
+export declare function agentCaps(parallel: number): ReadonlyMap<string, number>;
+export type { AgentArgvInput, NormalizedEvents, QaAgentProfile, QaEvent } from "./types.js";
+export { asEventList } from "./types.js";

package/dist/qa/agents/index.js

@@ -0,0 +1,83 @@
+import { UserError, which } from "../config.js";
+import { findExplicitAgent } from "../config.js";
+import { claudeCodeProfile } from "./claude-code.js";
+import { cursorProfile } from "./cursor.js";
+/**
+ * Every backend `qa run` can spawn.
+ *
+ * Registering another assistant is a new module plus a line here. Nothing
+ * outside this directory may branch on an agent's name: argv, event parsing,
+ * and the default model are read from the profile.
+ */
+export const AGENTS = [cursorProfile, claudeCodeProfile];
+for (const profile of AGENTS) {
+    if (profile.maxParallel !== undefined &&
+        (!Number.isInteger(profile.maxParallel) || profile.maxParallel < 1)) {
+        throw new Error(`qa agent profile ${profile.name} maxParallel must be >= 1`);
+    }
+}
+export const SUPPORTED_AGENTS = AGENTS.map((profile) => profile.name);
+const BY_NAME = new Map(AGENTS.map((profile) => [profile.name, profile]));
+const binaryCache = new Map();
+export function resolveAgent(name) {
+    const profile = BY_NAME.get(name);
+    if (!profile) {
+        throw new UserError(`Unknown agent: ${name} (known: ${SUPPORTED_AGENTS.join(", ")})`);
+    }
+    return profile;
+}
+export function defaultModels() {
+    return Object.fromEntries(AGENTS.map((profile) => [profile.name, profile.defaultModel]));
+}
+/**
+ * Resolve the executable for one profile. An explicit `--agent` path overrides
+ * every backend — that is the fake-agent test hook. PATH lookup is lazy and
+ * cached per profile so a cursor-only queue does not fail because `claude` is
+ * absent.
+ */
+export function resolveBinary(name, explicit) {
+    if (explicit)
+        return findExplicitAgent(explicit);
+    const hit = binaryCache.get(name);
+    if (hit)
+        return hit;
+    const profile = resolveAgent(name);
+    for (const candidate of profile.binaries) {
+        const found = which(candidate);
+        if (found) {
+            binaryCache.set(name, found);
+            return found;
+        }
+    }
+    throw new UserError(`${profile.binaries[0]} not on PATH; pass --agent /path/to/${profile.binaries[0]}`);
+}
+/**
+ * The executable to *display* for a profile, for --dry-run only.
+ *
+ * Falls back to the profile's first candidate name when nothing is on PATH: previewing a
+ * queue launches nothing, so requiring the backend to be installed would make `qa run
+ * --dry-run` fail on exactly the machine you would preview a queue on — and would make the
+ * e2e suite depend on cursor-agent and claude being present on the CI runner. An explicit
+ * --agent is still validated, because a bad path there is a real invocation error.
+ */
+export function displayBinary(name, explicit) {
+    if (explicit)
+        return findExplicitAgent(explicit);
+    try {
+        return resolveBinary(name, null);
+    }
+    catch {
+        return resolveAgent(name).binaries[0];
+    }
+}
+export function agentCaps(parallel) {
+    const caps = new Map();
+    for (const profile of AGENTS) {
+        // An absent cap means --parallel alone decides, so a queue of one backend can use
+        // every slot the user asked for.
+        caps.set(profile.name, Math.min(profile.maxParallel ?? parallel, parallel));
+    }
+    return caps;
+}
+export { asEventList } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/qa/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/qa/agents/index.ts"],"names":[],"mappings":"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"}

package/dist/qa/agents/types.d.ts

@@ -0,0 +1,61 @@
+import type { Usage } from "../outcome.js";
+/**
+ * Normalized harness event. Slot.applyEvent consumes only this; vendor JSON never
+ * reaches the TUI, reports, or tracker.
+ */
+export type QaEvent = {
+    kind: "text";
+    text: string;
+    sessionId?: string;
+} | {
+    kind: "thinking";
+    phase: "delta" | "completed";
+    text?: string;
+    sessionId?: string;
+} | {
+    kind: "tool";
+    phase: "started" | "completed";
+    name: string;
+    summary: string;
+    failed?: boolean;
+    sessionId?: string;
+} | {
+    kind: "usage";
+    usage: Usage;
+    error?: string;
+    sessionId?: string;
+} | {
+    kind: "init";
+    model?: string;
+    sessionId?: string;
+};
+export type NormalizedEvents = QaEvent | QaEvent[] | null;
+/** Enough of a case for argv construction without importing Case. */
+export interface AgentArgvInput {
+    repo: string;
+    model: string;
+    prompt: string;
+}
+/**
+ * Per-backend profile. Registering another assistant is a new module plus a
+ * line in index.ts. Nothing outside src/qa/agents/ may branch on an agent's name.
+ */
+export interface QaAgentProfile {
+    readonly name: string;
+    /** PATH candidates, first match wins. */
+    readonly binaries: readonly string[];
+    readonly defaultModel: string;
+    /**
+     * A real concurrency limit for this backend, or absent when the vendor imposes none we
+     * know of. Combined with --parallel by min(), so an absent cap means --parallel alone
+     * decides. Never set this to the *default* of --parallel: that silently caps the flag.
+     * Must be >= 1 when present.
+     */
+    readonly maxParallel?: number;
+    buildArgv(input: AgentArgvInput, binary: string): string[];
+    normalize(raw: Record<string, unknown>): NormalizedEvents;
+}
+export declare function asEventList(events: NormalizedEvents): QaEvent[];
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function sessionIdOf(raw: Record<string, unknown>): string | undefined;
+export declare function num(value: unknown): number | undefined;

package/dist/qa/agents/types.js

@@ -0,0 +1,18 @@
+export function asEventList(events) {
+    if (events === null)
+        return [];
+    if (Array.isArray(events))
+        return [...events];
+    return [events];
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function sessionIdOf(raw) {
+    const value = raw["session_id"];
+    return value ? String(value) : undefined;
+}
+export function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+//# sourceMappingURL=types.js.map

package/dist/qa/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/qa/agents/types.ts"],"names":[],"mappings":"AAmEA,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAC9C,OAAO,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAA4B;IACtD,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC"}