cheap-agent 0.0.0-stage → 1.1.0

package/dist/plan.js

@@ -0,0 +1,117 @@
+import { DIFFICULTIES } from "./routing.js";
+const REQUIRED = ["files", "done-when"];
+/** The plan grammar in one line, for Claude: the delegate tool description and every plan-error FAIL carry it. */
+export const PLAN_FORMAT = 'Plan format: one "# <title>" line, then per step a "## <id> <title>" heading followed by "files: <paths>", "do: <what>", "done-when: <check>" (optional "dont:", "needs: <step ids>", "difficulty: easy|medium|hard"), each key at the start of its line, not a bullet. In done-when, `backticked` text is run as a shell command that must succeed; put only commands in backticks.';
+/** Parses a plan; throws with a precise, line-numbered reason when it does not follow the format. */
+export function parsePlan(source) {
+    const lines = source.split(/\r?\n/);
+    let title;
+    const context = [];
+    const steps = [];
+    let field;
+    lines.forEach((line, i) => {
+        const at = `line ${i + 1}`;
+        if (/^# /.test(line)) {
+            if (title !== undefined)
+                throw new Error(`${at}: a plan has exactly one H1 title`);
+            title = line.slice(2).trim();
+            return;
+        }
+        if (/^## /.test(line)) {
+            if (title === undefined)
+                throw new Error(`${at}: step before the plan's H1 title`);
+            const m = line.match(/^## +(\d+[a-z]?)(?: +(.*))?$/);
+            if (!m)
+                throw new Error(`${at}: step heading needs an id (integer or integer+letter), e.g. "## 3 add route"`);
+            if (steps.some((s) => s.id === m[1]))
+                throw new Error(`${at}: duplicate step id ${m[1]}`);
+            steps.push({ id: m[1], title: (m[2] ?? "").trim(), fields: {}, text: line, line: i + 1 });
+            field = undefined;
+            return;
+        }
+        const step = steps.at(-1);
+        if (!step) {
+            if (title !== undefined && line.trim())
+                context.push(line);
+            return;
+        }
+        step.text += `\n${line}`;
+        const kv = line.match(/^([a-z][a-z-]*):\s?(.*)$/);
+        if (kv) {
+            field = kv[1];
+            step.fields[field] = kv[2].trim();
+        }
+        else if (/^ {2,}\S/.test(line) && field) {
+            step.fields[field] += `\n${line.trim()}`;
+        }
+        else if (line.trim()) {
+            field = undefined; // free prose inside a step is kept in its text, not a field
+        }
+    });
+    if (title === undefined)
+        throw new Error("plan has no H1 title (\"# <title>\")");
+    if (!steps.length)
+        throw new Error("plan has no steps (\"## <id> <title>\")");
+    for (const step of steps) {
+        const missing = REQUIRED.filter((key) => !step.fields[key]);
+        if (missing.length)
+            throw new Error(`step ${step.id} (line ${step.line}): missing ${missing.map((k) => `${k}:`).join(", ")}`);
+        const d = step.fields.difficulty;
+        if (d !== undefined && !DIFFICULTIES.includes(d))
+            throw new Error(`step ${step.id} (line ${step.line}): difficulty: must be ${DIFFICULTIES.join(", ")} or left out`);
+    }
+    return { title, context: context.join("\n").trim(), steps: steps.map(({ line, ...step }) => ({ ...step, text: step.text.trim() })) };
+}
+/**
+ * Resolves a steps string to groups (spec D2): `"3"` one step, `"3-5"` a range run in order as one group, and commas
+ * separate groups (`"1-2,3,4"`). Groups come back in plan order; a step may be in only one group.
+ */
+export function selectGroups(plan, spec) {
+    const index = (id) => {
+        const i = plan.steps.findIndex((s) => s.id === id);
+        if (i < 0)
+            throw new Error(`step ${id} not found (plan steps: ${plan.steps.map((s) => s.id).join(", ")})`);
+        return i;
+    };
+    const seen = new Set();
+    const groups = spec.split(",").map((raw) => {
+        const part = raw.trim();
+        const m = part.match(/^(\d+[a-z]?)(?:\s*-\s*(\d+[a-z]?))?$/);
+        if (!m)
+            throw new Error(`steps "${spec}": "${part}" is not a step id or range; use e.g. "3", "3-5" or "1-2,3,4"`);
+        const [from, to] = [index(m[1]), index(m[2] ?? m[1])];
+        if (to < from)
+            throw new Error(`steps "${spec}": range ${part} runs backwards`);
+        const steps = plan.steps.slice(from, to + 1);
+        for (const s of steps) {
+            if (seen.has(s.id))
+                throw new Error(`steps "${spec}": step ${s.id} is in more than one group`);
+            seen.add(s.id);
+        }
+        return { label: m[2] ? `${m[1]}-${m[2]}` : m[1], steps, at: from };
+    });
+    const sorted = groups.sort((a, b) => a.at - b.at).map(({ at, ...g }) => g);
+    // groups land in step order, so a group waiting on a later one would never land
+    sorted.forEach((g, i) => {
+        const later = needsOf(g).find((id) => sorted.slice(i + 1).some((o) => o.steps.some((s) => s.id === id)));
+        if (later)
+            throw new Error(`steps "${spec}": step ${g.label} needs ${later}, which comes later in the plan; put dependencies first`);
+    });
+    return sorted;
+}
+/** Where two groups' `files:` overlap: an equal entry, or one inside the other's directory entry. Returns the inner path. */
+export function overlap(a, b) {
+    const files = (g) => g.steps.flatMap((s) => s.fields.files.split(/[,\n]/)).map((f) => f.trim().replace(/^\.\//, "").replace(/\/+$/, "")).filter(Boolean);
+    const theirs = files(b);
+    for (const x of files(a)) {
+        for (const y of theirs) {
+            if (x === y || x.startsWith(`${y}/`))
+                return x;
+            if (y.startsWith(`${x}/`))
+                return y;
+        }
+    }
+    return undefined;
+}
+/** The step ids a group's `needs:` names, outside the group itself (a range already runs in order). */
+export const needsOf = (g) => [...new Set(g.steps.flatMap((s) => (s.fields.needs ?? "").split(/[\s,]+/).filter(Boolean)))].filter((id) => !g.steps.some((s) => s.id === id));

package/dist/platform.js

@@ -0,0 +1,112 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, symlinkSync, unlinkSync } from "node:fs";
+import { delimiter, dirname, join, sep } from "node:path";
+/**
+ * Platform: everything OS-specific lives here (spec A18). Windows is supported through junctions, taskkill and
+ * PATHEXT lookup here; callers stay platform-free.
+ */
+/** Links a dependency directory into a worktree. Junctions need no privilege on Windows, unlike directory symlinks. */
+export function link(target, path) {
+    symlinkSync(target, path, process.platform === "win32" ? "junction" : "dir");
+}
+/** Removes a link made by `link`, never what it points to; does nothing if `path` is not a link. */
+export function removeLink(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            unlinkSync(path);
+    }
+    catch {
+        // already gone
+    }
+}
+/** Forward-slash form of a relative path, as result blocks show paths. */
+export const normalisePath = (path) => path.split(sep).join("/");
+/** Whether a process is still running (one we may not signal still counts as running). */
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** How OpenCode's per-platform npm packages name this OS, and its binary's file name. */
+export function opencodePlatform() {
+    const os = process.platform === "win32" ? "windows" : process.platform;
+    return { os, binary: os === "windows" ? "opencode.exe" : "opencode" };
+}
+/** Signals a whole process group (a child spawned `detached`), ignoring one that is already gone. */
+export function killProcessGroup(pid, signal = "SIGTERM") {
+    if (!pid)
+        return;
+    if (process.platform === "win32") {
+        // no process groups on Windows; taskkill walks the tree instead and ignores the signal
+        spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // already gone
+    }
+}
+/** The first executable named `name` on `env`'s PATH, or undefined. On Windows it tries PATHEXT extensions, bare name last. */
+export function which(name, platform = process.platform, env = process.env) {
+    const dirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const candidates = platform === "win32"
+        ? [...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((ext) => name + ext), name]
+        : [name];
+    for (const dir of dirs) {
+        for (const candidate of candidates) {
+            if (platform !== "win32") {
+                const full = join(dir, candidate);
+                if (existsSync(full))
+                    return full;
+                continue;
+            }
+            // Windows filesystems are case-insensitive; read the dir so a case difference still matches
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                break;
+            }
+            const hit = entries.find((entry) => entry.toLowerCase() === candidate.toLowerCase());
+            if (hit)
+                return join(dir, hit);
+        }
+    }
+    return undefined;
+}
+/**
+ * Git for Windows' bash, for running bash-syntax commands on Windows. Never a bare `bash` from PATH: on Windows that
+ * can be WSL's System32\bash.exe, which resolves Windows paths differently.
+ */
+export function gitBash(platform = process.platform, env = process.env) {
+    if (platform !== "win32")
+        return undefined;
+    // Claude Code's own variable; trust it when it points at a real file
+    const override = env.CLAUDE_CODE_GIT_BASH_PATH;
+    if (override && existsSync(override))
+        return override;
+    const git = which("git", platform, env);
+    if (!git)
+        return undefined;
+    // Git for Windows: git.exe in <Git>\cmd, bash.exe in <Git>\bin
+    const bash = join(dirname(git), "..", "bin", "bash.exe");
+    return existsSync(bash) ? bash : undefined;
+}
+/** Double-quotes an argument Node will re-split under `shell: true` on Windows. */
+const quoteWinArg = (arg) => (/[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg);
+export function runCli(name, args, opts) {
+    const file = which(name);
+    if (!file)
+        return undefined;
+    if (/\.(cmd|bat)$/i.test(file)) {
+        return spawnSync(file, args.map(quoteWinArg), { ...opts, shell: true, windowsHide: true });
+    }
+    return spawnSync(file, args, opts);
+}

package/dist/report.js

@@ -0,0 +1,178 @@
+const STATUS_SECTIONS = {
+    OK: [],
+    PARTIAL: ["found", "missing", "worktree"],
+    FAIL: ["error", "found", "tried", "reason", "worktree"],
+    BLOCKED: ["question"],
+    CONFLICT: ["conflict", "worktree"],
+    CANCELLED: ["reason", "worktree"],
+    TIMEOUT: ["found", "reason", "missing", "worktree"],
+    BUDGET: ["found", "reason", "worktree"],
+};
+// D6 urgency; CANCELLED is not ranked by the spec and sits with BUDGET/TIMEOUT
+const URGENCY = ["BLOCKED", "CONFLICT", "FAIL", "BUDGET", "TIMEOUT", "CANCELLED", "PARTIAL", "RUNNING", "OK"];
+const rank = (s) => (s === "TIMEOUT" || s === "CANCELLED" ? URGENCY.indexOf("BUDGET") : URGENCY.indexOf(s));
+const BUDGET_TOKENS = 400;
+const LINE_MAX = 200;
+const FULL = { changed: 15, tried: Infinity, risks: 5, review: 5, error: Infinity, summary: 160 };
+/** A FAIL before any job exists (bad input, setup). */
+export const failBlock = (reason) => `FAIL reason: ${reason}`;
+/** A job block within `budget` tokens (chars/4), cutting in D9 order only while over it. Never cut: headline, question/options, conflict, reason, worktree, log. */
+export function renderJob(r, budget = BUDGET_TOKENS) {
+    if (r.status === "RUNNING")
+        return fit(`RUNNING ${r.job} step=${r.steps} turns=${r.usage.turns}`);
+    let cuts = FULL;
+    let text = layout(r, cuts);
+    const over = () => text.length / 4 > budget;
+    const cut = (c) => {
+        if (over())
+            text = layout(r, (cuts = { ...cuts, ...c }));
+    };
+    cut({ changed: 5 });
+    cut({ tried: 1 });
+    cut({ risks: 3 });
+    cut({ review: 3 });
+    for (let n = r.error?.length ?? 0; n > 12 && over();)
+        cut({ error: --n });
+    cut({ summary: 100 });
+    return text;
+}
+function layout(r, c) {
+    const sections = STATUS_SECTIONS[r.status];
+    const has = (s) => sections.includes(s);
+    const add = r.changed.reduce((n, x) => n + x.add, 0);
+    const del = r.changed.reduce((n, x) => n + x.del, 0);
+    const lines = [
+        [
+            r.status, r.job, `step=${r.steps}`, `files=${r.changed.length}`, `+${add}/-${del}`, r.tests && `tests=${r.tests}`,
+            `turns=${r.usage.turns}`, `cost=$${r.usage.costUsd.toFixed(3)}`,
+            r.selfFix && `fix=${r.selfFix}`, r.models.escalated && "esc=1",
+            r.models.final !== r.models.requested && `model=${r.models.final}`, r.redo && "redo=1", r.billing && `billing=${r.billing}`, r.repro && `repro=${r.repro}`, r.test && `test=${r.test}`,
+        ].filter(Boolean).join(" "),
+    ];
+    const keep = new Set(); // question/options lines are never elided
+    if (r.summary)
+        lines.push(`summary: ${clip(oneLine(r.summary), c.summary)}`);
+    // D5: a BLOCKED block counts its files in the headline but lists them only once the job settles
+    if (r.changed.length && r.status !== "BLOCKED") {
+        lines.push("changed:", ...r.changed.slice(0, c.changed).map((x) => `  ${x.status} ${x.path}${x.add ? ` +${x.add}` : ""}${x.del ? ` -${x.del}` : ""}`));
+        if (r.changed.length > c.changed)
+            lines.push(`  … +${r.changed.length - c.changed} more`);
+    }
+    if (r.risks.length)
+        lines.push("risks:", ...r.risks.slice(0, c.risks).map((x) => `  - ${clip(oneLine(x), 120)}`));
+    if (r.review.length)
+        lines.push(`review: ${r.review.slice(0, c.review).map((v) => `${v.path}:${v.start}-${v.end}`).join(", ")}`);
+    const asked = r.questions ?? (r.question ? [r.question] : []);
+    if (has("question"))
+        asked.forEach((question, n) => {
+            const q = [`question${asked.length > 1 ? ` ${n + 1}` : ""}: ${oneLine(question.text)}`];
+            if (question.options.length)
+                q.push("options:", ...question.options.slice(0, 4).map((o, i) => `  ${"abcd"[i]}) ${oneLine(o)}`));
+            q.forEach((l) => keep.add(l));
+            lines.push(...q);
+        });
+    if (has("conflict") && r.conflict?.length)
+        lines.push("conflict:", ...r.conflict.map((x) => `  ${oneLine(x)}`));
+    if (has("error") && r.error?.length) {
+        const e = r.error.slice(0, c.error);
+        if (e.length < r.error.length)
+            e[e.length - 1] = `  … +${r.error.length - e.length + 1} more lines (see log)`;
+        lines.push(`error: ${e[0]}`, ...e.slice(1));
+    }
+    if (has("found") && r.found)
+        lines.push(...wrap(`found: ${oneLine(r.found)}`));
+    if (has("tried") && r.tried?.length)
+        lines.push("tried:", ...r.tried.slice(-c.tried).map((x) => `  - ${oneLine(x)}`));
+    if (has("reason") && r.reason)
+        lines.push(`reason: ${oneLine(r.reason)}`);
+    if (has("missing") && r.missing.length)
+        lines.push("missing:", ...r.missing.map((x) => `  - ${oneLine(x)}`));
+    if (has("worktree") && r.worktree)
+        lines.push(`worktree: ${r.worktree}/`);
+    lines.push(`log: .cheapag/jobs/${r.job}/`);
+    return lines.map((l) => (keep.has(l) ? l.replaceAll("\t", "  ") : fit(l))).join("\n");
+}
+/** D7. A research CONSENT renders through `renderConsent`. */
+export function renderResearch(r) {
+    const lines = [
+        [
+            r.status, r.job, `files_read=${r.filesRead}`, `turns=${r.usage.turns}`, `cost=$${r.usage.costUsd.toFixed(3)}`,
+            r.models && r.models.final !== r.models.requested && `model=${r.models.final}`,
+        ].filter(Boolean).join(" "),
+    ];
+    // a scout brief (ticket 23.4): ranked files, the reproduction, dead ends, then the prose
+    if (r.refs.length)
+        lines.push(`files: ${r.refs.map((v) => `${v.path}:${v.start}${v.end !== v.start ? `-${v.end}` : ""}`).join(", ")}`);
+    if (r.repro)
+        lines.push(`repro: ${oneLine(r.repro)}`);
+    if (r.deadEnds)
+        lines.push(`dead ends: ${oneLine(r.deadEnds)}`);
+    // prose is word-wrapped, not elided like other long lines
+    if (r.answer.trim())
+        lines.push("notes:", ...r.answer.trim().split("\n").flatMap((l) => wrap(l.trimEnd())));
+    if (r.confidence)
+        lines.push(`confidence: ${r.confidence}`);
+    if (r.reason)
+        lines.push(`reason: ${oneLine(r.reason)}`);
+    const n = r.unlanded.length;
+    if (n)
+        lines.push(`note: ${n} job${n > 1 ? "s" : ""} not yet landed (${r.unlanded.join(", ")}); their changes are not visible to research`);
+    lines.push(`log: .cheapag/jobs/${r.job}/`);
+    return lines.map(fit).join("\n");
+}
+/**
+ * D6: header, notes, integration error, the integration fix job's block, then job blocks by urgency (RUNNING ones as
+ * adjacent single lines), then `next:`. The fix job is not a group: it counts in the cost only.
+ */
+export function renderBatch(b, jobs, fix) {
+    const sorted = [...jobs].sort((x, y) => rank(x.status) - rank(y.status));
+    const counts = URGENCY.map((s) => [s, sorted.filter((j) => j.status === s).length]).filter(([, n]) => n);
+    const head = [
+        [
+            `BATCH ${b.batch} groups=${b.groups.length}`, ...counts.map(([s, n]) => `${s}=${n}`),
+            `landed=${jobs.filter((j) => j.landed).length}`, `integration=${b.integration}`,
+            `cost=$${[...jobs, ...(fix ? [fix] : [])].reduce((n, j) => n + j.usage.costUsd, 0).toFixed(3)}`,
+        ].join(" "),
+    ];
+    if (b.notes.length)
+        head.push(`note: ${b.notes.join("; ")}`);
+    if (b.integrationError?.length)
+        head.push(`error: ${b.integrationError[0]}`, ...b.integrationError.slice(1));
+    const chunks = fix ? [renderJob(fix)] : [];
+    sorted.forEach((j, i) => {
+        if (j.status === "RUNNING" && sorted[i - 1]?.status === "RUNNING")
+            chunks[chunks.length - 1] += `\n${renderJob(j)}`;
+        else
+            chunks.push(renderJob(j));
+    });
+    const blocked = sorted.find((j) => j.status === "BLOCKED");
+    const next = [
+        blocked && `reply(job="${blocked.job}", ...)`,
+        (b.integration === "running" || sorted.some((j) => j.status === "BLOCKED" || j.status === "RUNNING")) && `jobs(action="wait", job="${b.batch}")`,
+    ].filter(Boolean).join(" then ");
+    return [head.map(fit).join("\n"), chunks.join("\n\n"), next && fit(`next: ${next}`)].filter(Boolean).join("\n");
+}
+/** D5 CONSENT: no job is created. */
+export const renderConsent = (c) => [`CONSENT repo=${c.repo}`, `send: ${c.send}`, `retention: ${c.retention}`, `approve: ${c.approve}`].map(fit).join("\n");
+const oneLine = (s) => s.trim().replace(/\s*\n\s*/g, " ");
+const clip = (s, max) => (s.length > max ? `${s.slice(0, max - 1)}…` : s);
+/** A line broken at spaces into lines of at most 200 chars (a longer word is left to `fit`). */
+function wrap(line) {
+    const out = [""];
+    for (const word of line.replaceAll("\t", "  ").split(" ")) {
+        const last = out[out.length - 1];
+        if (last && last.length + 1 + word.length > LINE_MAX)
+            out.push(word);
+        else
+            out[out.length - 1] = last ? `${last} ${word}` : word;
+    }
+    return out;
+}
+/** D9 line rules: no tabs (2 spaces), at most 200 chars with the middle elided. */
+function fit(line) {
+    const l = line.replaceAll("\t", "  ");
+    if (l.length <= LINE_MAX)
+        return l;
+    const half = (LINE_MAX - 1) / 2;
+    return `${l.slice(0, Math.ceil(half))}…${l.slice(l.length - Math.floor(half))}`;
+}