huddle-cli 0.1.0 → 0.1.3

package/dist/orchestrator/budget.js

@@ -0,0 +1,283 @@
+// The cost guard. A run costs real money on someone's subscriptions: the
+// round-6 capstone runs took ~4–6M tokens, an improve run once hit 13M. So:
+//
+//   - Before a run, an estimate printed with the plan: "≈ 4–6M tokens, ~15–20
+//     min with 3 agents", from the plan's size, the agent count and what past
+//     runs in this repo's Room cost (built-in defaults from the capstone data
+//     until there is history). It is an estimate, and says so.
+//   - --budget=5M (or prefs "budget"): at 90% Huddle starts no new work — no
+//     new tasks, takeovers, QA rounds, buddy checks or pairings — and lets the
+//     running tasks finish; at 120% it stops the running agents, as Ctrl-C does.
+//     Either way the RESULT says what was left undone.
+//
+// What counts: every token the agents' meters report (usage.ts), cached
+// context INCLUDED — the same number the live footer, the estimate and the
+// RESULT's COST line show, so "--budget=5M" means the 5M you see there. Cached
+// reads are billed at a fraction (~10%), so this is conservative: a
+// cache-heavy run reaches its budget before its bill does. The COST line shows
+// the cached share next to it. Read-only asks (reviews, buddy checks, council
+// turns) report no usage, so the budget can't see them; the estimate counts
+// council turns from its defaults.
+import { fmtDuration, fmtTokens } from "../adapters/usage.js";
+/** Stop new work at this share of the budget… */
+export const SOFT_AT = 0.9;
+/** …and stop the running agents at this one. */
+export const HARD_AT = 1.2;
+/** "5M", "800k", "1.5m", "250000", "2,000,000" → tokens; null if it isn't one. */
+export function parseTokens(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) && v > 0 ? Math.round(v) : null;
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([kmb])?\s*(?:tok(?:ens)?)?\s*$/i.exec(String(v ?? "").replace(/[,_]/g, ""));
+    if (!m)
+        return null;
+    const n = Number(m[1]) * ({ k: 1e3, m: 1e6, b: 1e9 }[(m[2] ?? "").toLowerCase()] ?? 1);
+    return n > 0 ? Math.round(n) : null;
+}
+/** `--budget=5M` (or `--budget 5M`) anywhere in a typed goal: the goal without it, and the value. */
+export function budgetFlag(goal) {
+    const m = /(^|\s)--budget(?:=|\s+)(\S+)(?=\s|$)/.exec(goal);
+    if (!m)
+        return { goal };
+    return { goal: goal.replace(m[0], " ").replace(/\s+/g, " ").trim(), budget: m[2] };
+}
+export class Budget {
+    limit;
+    meters = new Map();
+    extra = { tokens: 0, cached: 0 };
+    listeners = [];
+    /** Only goes up: once new work stopped, it stays stopped for the run. */
+    level = "ok";
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /** Count this agent launch's meter (read live, every check). `who`: the agent, for its pace. */
+    track(m, who = "", now = Date.now()) {
+        if (!this.meters.has(m))
+            this.meters.set(m, { who: who.split("#")[0], start: now, lastAt: now, last: 0 });
+    }
+    /** Tokens measured outside a meter (the planner's own). */
+    add(tokens, cached = 0) {
+        this.extra.tokens += Math.max(0, tokens || 0);
+        this.extra.cached += Math.max(0, cached || 0);
+    }
+    get tokens() {
+        let n = this.extra.tokens;
+        for (const m of this.meters.keys())
+            n += m.tokens;
+        return n;
+    }
+    get cached() {
+        let n = this.extra.cached;
+        for (const m of this.meters.keys())
+            n += m.cached;
+        return n;
+    }
+    /**
+     * Tokens used plus an estimate of what's in flight but not reported yet.
+     * Found live (0.1.2): Codex reports usage only when its whole turn ends, so
+     * a 1m45s task counted 0 and then 406k at once, and the 90% line fired at
+     * 108%. A launch that hasn't reported is estimated at its agent's own pace
+     * this run (tokens per second of its earlier launches), capped at twice
+     * that agent's average launch. Only the soft line reads this: stopping
+     * running agents (the hard line) waits for real numbers.
+     */
+    projected(now = Date.now()) {
+        this.note(now);
+        const pace = new Map();
+        for (const [m, t] of this.meters) {
+            if (!m.seen || m.tokens <= 0)
+                continue;
+            const p = pace.get(t.who) ?? { tokens: 0, ms: 0, n: 0 };
+            p.tokens += m.tokens;
+            p.ms += Math.max(1000, t.lastAt - t.start);
+            p.n++;
+            pace.set(t.who, p);
+        }
+        let guess = 0;
+        for (const [m, t] of this.meters) {
+            if (m.seen)
+                continue;
+            const p = pace.get(t.who);
+            if (!p)
+                continue;
+            guess += Math.min((p.tokens / p.ms) * (now - t.start), (2 * p.tokens) / p.n);
+        }
+        return this.tokens + Math.round(guess);
+    }
+    /** Each meter's count went up: when (its pace). */
+    note(now) {
+        for (const [m, t] of this.meters)
+            if (m.tokens > t.last) {
+                t.last = m.tokens;
+                t.lastAt = now;
+            }
+    }
+    /** Share of the budget used (0 with no budget). */
+    get used() {
+        return this.limit ? this.tokens / this.limit : 0;
+    }
+    /** Past the soft line: start nothing new. */
+    get stopping() {
+        return this.check() !== "ok";
+    }
+    /** Re-read the meters; tells the listeners when the level goes up. */
+    check() {
+        if (!this.limit)
+            return this.level;
+        const u = this.used;
+        const next = u >= HARD_AT ? "hard" : u >= SOFT_AT || this.projected() / this.limit >= SOFT_AT ? "soft" : "ok";
+        const rank = { ok: 0, soft: 1, hard: 2 };
+        if (rank[next] <= rank[this.level])
+            return this.level;
+        // Straight to hard: the soft listeners still hear "soft" first (stop new work, then stop agents).
+        if (this.level === "ok" && next === "hard") {
+            this.level = "soft";
+            for (const f of this.listeners)
+                f("soft", this);
+        }
+        this.level = next;
+        for (const f of this.listeners)
+            f(next, this);
+        return this.level;
+    }
+    onLevel(f) {
+        this.listeners.push(f);
+    }
+    /** Check every `ms` until the returned stop() (agents' meters move between scheduler ticks). */
+    watch(ms = 1000) {
+        if (!this.limit)
+            return () => { };
+        const t = setInterval(() => this.check(), ms);
+        t.unref?.();
+        return () => clearInterval(t);
+    }
+}
+/** "5.1M of 6M budget (85%)" — or "" with no budget. */
+export function budgetUse(b) {
+    if (!b.limit)
+        return "";
+    return `${fmtTokens(b.tokens)} of ${fmtTokens(b.limit)} budget (${Math.round(b.used * 100)}%)`;
+}
+/** From the capstone runs (round 6): ~350k tokens a task, ~550k a QA round, ~60k a council turn. */
+export const DEFAULT_COSTS = { perTask: 350_000, perQaRound: 550_000, perCouncilTurn: 60_000, taskMs: 4 * 60_000, qaRoundMs: 4 * 60_000 };
+const avg = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+/**
+ * What past runs in this Room cost: tokens and agent time per task (merged or
+ * failed, a takeover's first rounds included) and per QA check. Each number
+ * falls back to its default until there are enough samples (3 tasks, 2 checks).
+ */
+export function runHistory(db) {
+    const costs = { ...DEFAULT_COSTS };
+    if (!db)
+        return { costs, tasks: 0, checks: 0 };
+    let evs = [];
+    try {
+        evs = db.eventsOfType(["run.merged", "run.failed", "run.takeover", "qa.done"], 0, 1000);
+    }
+    catch {
+        return { costs, tasks: 0, checks: 0 };
+    }
+    const p = (e) => {
+        try {
+            return JSON.parse(e.payload || "{}");
+        }
+        catch {
+            return {};
+        }
+    };
+    const tasks = [];
+    let handedOver = 0; // a rescued task's first agent's rounds: no merged/failed event carries them
+    const checks = [];
+    for (const e of evs) {
+        const x = p(e);
+        if (e.type === "run.takeover")
+            handedOver += x.kind === "rescue" ? Number(x.tokens) || 0 : 0;
+        else if (e.type === "qa.done") {
+            if (x.ok && Number(x.tokens) > 0)
+                checks.push({ tokens: Number(x.tokens), ms: Number(x.ms) || 0, bugs: Number(x.bugs) || 0 });
+        }
+        else if (Number(x.tokens) > 0)
+            tasks.push({ tokens: Number(x.tokens), ms: Number(x.ms) || 0 });
+    }
+    if (tasks.length >= 3) {
+        costs.perTask = Math.round((tasks.reduce((n, t) => n + t.tokens, 0) + handedOver) / tasks.length);
+        const ms = tasks.map((t) => t.ms).filter((m) => m > 0);
+        if (ms.length)
+            costs.taskMs = Math.round(avg(ms));
+    }
+    if (checks.length >= 2) {
+        const bugs = avg(checks.map((c) => c.bugs));
+        costs.perQaRound = Math.round(avg(checks.map((c) => c.tokens)) + bugs * costs.perTask);
+        costs.qaRoundMs = Math.round(avg(checks.map((c) => c.ms)) + (bugs > 0 ? costs.taskMs : 0));
+    }
+    return { costs, tasks: tasks.length >= 3 ? tasks.length : 0, checks: checks.length >= 2 ? checks.length : 0 };
+}
+/**
+ * A range, not a promise: tasks × per-task cost (±15%), QA as 1 round (low)
+ * to all rounds (high), plus the council's turns. Time: the tasks in waves of
+ * `agents` at a time, then QA.
+ */
+export function estimateRun(o) {
+    const h = o.history ?? { costs: DEFAULT_COSTS, tasks: 0, checks: 0 };
+    const c = h.costs;
+    const agents = Math.max(1, o.agents);
+    const council = (o.councilTurns ?? 0) * c.perCouncilTurn;
+    const qaLow = o.qaRounds ? 1 : 0;
+    const low = o.tasks * c.perTask * 0.85 + qaLow * c.perQaRound + council;
+    const high = o.tasks * c.perTask * 1.15 + o.qaRounds * c.perQaRound + council;
+    const waves = Math.ceil(o.tasks / agents);
+    const lowMs = waves * c.taskMs * 0.85 + qaLow * c.qaRoundMs;
+    const highMs = waves * c.taskMs * 1.15 + o.qaRounds * c.qaRoundMs;
+    const from = [h.tasks ? `${h.tasks} past task(s)` : "", h.checks ? `${h.checks} past QA check(s)` : ""].filter(Boolean);
+    const basis = from.length ? `from this repo's ${from.join(" and ")}` : "from Huddle's defaults (no history in this repo yet)";
+    return { low, high, lowMs, highMs, agents, basis };
+}
+/** Round a token range outward to steps that read well: 4–6M, 1.5–2M, 350–500k. */
+export function fmtTokenRange(low, high) {
+    const step = high >= 3e6 ? 1e6 : high >= 1e6 ? 5e5 : high >= 1e5 ? 5e4 : 1e4;
+    const lo = Math.max(step, Math.floor(low / step) * step);
+    const hi = Math.max(lo + step, Math.ceil(high / step) * step);
+    const unit = (n) => (n >= 1e6 ? `${+(n / 1e6).toFixed(1)}` : `${Math.round(n / 1e3)}`);
+    const suffix = (n) => (n >= 1e6 ? "M" : "k");
+    return suffix(lo) === suffix(hi) ? `${unit(lo)}–${unit(hi)}${suffix(hi)}` : `${fmtTokens(lo)}–${fmtTokens(hi)}`;
+}
+/** "~15–20 min", "~1h05m–1h20m" */
+export function fmtMsRange(low, high) {
+    const lo = Math.max(1, Math.round(low / 60_000));
+    const hi = Math.max(lo + 1, Math.round(high / 60_000));
+    return hi < 60 ? `~${lo}–${hi} min` : `~${fmtDuration(lo * 60_000)}–${fmtDuration(hi * 60_000)}`;
+}
+/** "≈ 4–6M tokens, ~15–20 min with 3 agents" */
+export function estimateText(e) {
+    return `≈ ${fmtTokenRange(e.low, e.high)} tokens, ${fmtMsRange(e.lowMs, e.highMs)} with ${e.agents} agent${e.agents === 1 ? "" : "s"}`;
+}
+/**
+ * The line printed with the plan: "≈ 4–6M tokens, ~15–20 min with 3 agents ·
+ * an estimate, from …", plus what the budget will do.
+ */
+export function costPreview(o) {
+    const turns = o.council ? o.council.proposals.length + o.council.critiques.length + (o.council.ratify?.length ?? 0) : 0;
+    const e = estimateRun({ tasks: o.tasks, agents: o.agents, qaRounds: o.qaRounds, councilTurns: turns, history: o.history });
+    const lim = o.budget?.limit;
+    const over = lim && e.low > lim ? " — the low end is past it: expect a partial run" : "";
+    const b = lim ? ` · budget ${fmtTokens(lim)}: new work stops at ${fmtTokens(lim * SOFT_AT)}, agents at ${fmtTokens(lim * HARD_AT)}${over}` : "";
+    return `${estimateText(e)} · an estimate, ${e.basis}${b}`;
+}
+/** The RESULT's budget lines: why the run stopped short and what it left undone. [] when it didn't. */
+export function budgetNotes(b, o) {
+    if (!b.limit || b.level === "ok")
+        return [];
+    const out = [
+        b.level === "hard"
+            ? `budget: ${fmtTokens(b.tokens)} passed ${Math.round(HARD_AT * 100)}% of ${fmtTokens(b.limit)} — running agents were stopped`
+            : `budget: ${Math.round(SOFT_AT * 100)}% of ${fmtTokens(b.limit)} reached — no new work started after it; running tasks finished`,
+    ];
+    if (o.left.length)
+        out.push(`left undone (${o.left.length}): ${o.left.join(" · ")}`);
+    if (o.qaCut)
+        out.push("left undone: QA (no round started past the budget line)");
+    if (o.left.length || o.qaCut)
+        out.push("what merged stays on main; a bigger --budget (or a follow-up goal) finishes the rest");
+    return out;
+}
+//# sourceMappingURL=budget.js.map

package/dist/orchestrator/busy.js

@@ -0,0 +1,106 @@
+// Busy, or stuck? An agent that prints nothing and calls no huddle_* tool for
+// the silence window used to be taken over. Found live (evolve run,
+// 2026-10-16): claude was taken over by codex while it was running Huddle's
+// own 8-minute test suite — quiet, but working. So before an agent counts as
+// silent, Huddle looks at what it is doing:
+//
+//   - a child or grandchild process used CPU since the last look (the test
+//     suite, a build, an install), or
+//   - files in its worktree changed since the last look, or
+//   - its log grew.
+//
+// Any of those = busy: the silence clock restarts from that look, so a long
+// command gets its full window again once it ends. A hard cap (default 3× the
+// window, HUDDLE_SILENCE_MAX_MIN) since its last real output still takes it
+// over, so a runaway loop can't hold a task forever.
+import fs from "node:fs";
+import path from "node:path";
+import { descendants } from "../platform.js";
+/** Longest an agent may go without output or a huddle_* call, busy or not. HUDDLE_SILENCE_MAX_MIN overrides; default 3× the silence window. */
+export function silenceMaxMsFromEnv(silenceMs) {
+    const v = Number(process.env.HUDDLE_SILENCE_MAX_MIN);
+    return Math.max(silenceMs, v > 0 ? v * 60_000 : 3 * silenceMs);
+}
+/** CPU a process tree must use between two looks to count as working: 2% of the wall time, at least 50ms. */
+export const busyCpuMs = (elapsedMs) => Math.max(50, elapsedMs * 0.02);
+/** Folders never walked for changed files: git's own, and installs too big to walk every tick. */
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+const MAX_WALK = 5000;
+/** A file under `dir` modified after `since`, or null. Bounded: at most MAX_WALK entries. */
+export function changedSince(dir, since) {
+    const stack = [dir];
+    let n = 0;
+    while (stack.length && n < MAX_WALK) {
+        const d = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (++n > MAX_WALK)
+                break;
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    stack.push(p);
+                continue;
+            }
+            try {
+                if (fs.statSync(p).mtimeMs > since)
+                    return path.relative(dir, p);
+            }
+            catch {
+                /* gone while we looked */
+            }
+        }
+    }
+    return null;
+}
+const sizeOf = (f) => {
+    try {
+        return fs.statSync(f).size;
+    }
+    catch {
+        return 0;
+    }
+};
+/** Remembers each agent's last look and compares the next one with it. */
+export class BusyWatch {
+    looks = new Map();
+    /** Compare `t` (agent `id`) with its last look. `table` = one process snapshot (null: the OS wouldn't say). */
+    look(id, t, table, now = Date.now()) {
+        const kids = table ? descendants(table, t.pid) : [];
+        const cpu = new Map(kids.map((p) => [p.pid, p.cpuMs]));
+        const before = this.looks.get(id);
+        const log = sizeOf(t.logPath);
+        this.looks.set(id, { at: now, pid: t.pid, cpu, log });
+        if (!before || before.pid !== t.pid)
+            return null;
+        // A process born since the last look did all its work since then.
+        let used = 0;
+        let top = null;
+        for (const p of kids) {
+            const d = p.cpuMs - (before.cpu.get(p.pid) ?? 0);
+            if (d <= 0)
+                continue;
+            used += d;
+            if (!top || d > top.ms)
+                top = { name: p.name, ms: d };
+        }
+        if (used >= busyCpuMs(now - before.at))
+            return { busy: true, why: `${top?.name || "a child process"} is using CPU (${(used / 1000).toFixed(1)}s since the last look)` };
+        if (log > before.log)
+            return { busy: true, why: "its log is growing" };
+        const f = changedSince(t.worktree, before.at);
+        if (f)
+            return { busy: true, why: `files are changing (${f})` };
+        return { busy: false, why: kids.length ? `${kids.length} child process(es), none using CPU; no files changing` : "no child processes; no files changing" };
+    }
+    forget(id) {
+        this.looks.delete(id);
+    }
+}
+//# sourceMappingURL=busy.js.map