@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/orchestration/runners/cursor/index.js

@@ -0,0 +1,184 @@
+import { parseVerdict, renderImplementerPrompt, renderRetryFollowup, renderReviewFollowup, renderVerifierPrompt, } from "../../prompts/index.js";
+import { runCursorAgent } from "./exec.js";
+/** the agent has escalated when its output carries this sentinel (cursor has no escalate verb). */
+const ESCALATE_RE = /ESCALATE:\s*(.+?)(?:\s+WANTS:\s*(.+))?$/im;
+export class CursorRunner {
+    opts;
+    name = "cursor";
+    constructor(opts) {
+        this.opts = opts;
+    }
+    capabilities() {
+        return { scopeHook: false, sessionTelemetry: false };
+    }
+    async run(briefing, policy, kind, workspace, onActivity) {
+        const isVerifier = kind === "verifier";
+        const diff = isVerifier ? ((await this.opts.diffFor?.(briefing.unitId)) ?? "") : "";
+        const retry = isVerifier
+            ? undefined
+            : this.opts.retryFor?.(briefing.unitId, "implementer");
+        // Resume the prior session for this unit+kind when it ran on the same model
+        // — the agent keeps its own context, so the follow-up is terse instead of a
+        // full re-brief + re-exploration.
+        const stored = this.opts.resumeFor?.(briefing.unitId, kind);
+        const resumeSessionId = stored && stored.model === policy.model ? stored.id : undefined;
+        const prompt = resumeSessionId
+            ? isVerifier
+                ? renderReviewFollowup(diff)
+                : renderRetryFollowup(retry ?? { attempt: 0, source: "the previous attempt", evidence: "(no evidence captured)" })
+            : isVerifier
+                ? renderVerifierPrompt(briefing, diff)
+                : renderImplementerPrompt(briefing, retry);
+        process.stderr.write(formatCursorSessionBanner(briefing.unitId, kind) + "\n");
+        const onCursorActivity = (u) => {
+            if (onActivity !== undefined) {
+                // Forward unclamped (Cursor's own LINE_CLAMP is 400) and carry
+                // kind/tool/target through — the loop's makeActivitySink is where the
+                // 160-char board clamp happens (recordLaneActivity), not here. Re-
+                // clamping to 160 at this call site was a bug: it defeated the durable
+                // activity log's ability to keep the longer, more useful line.
+                onActivity({
+                    line: u.line,
+                    turn: u.turn,
+                    tokens: u.tokens,
+                    ...(u.kind ? { kind: u.kind } : {}),
+                    ...(u.tool ? { tool: u.tool } : {}),
+                    ...(u.target ? { target: u.target } : {}),
+                });
+            }
+            else if (this.opts.onActivity !== undefined) {
+                this.opts.onActivity(u);
+            }
+            const useWatch = this.opts.watchStderr === true ||
+                (onActivity === undefined && this.opts.onActivity === undefined);
+            if (useWatch) {
+                process.stderr.write(formatCursorWatchLine(briefing.unitId, u) + "\n");
+            }
+        };
+        const r = await runCursorAgent({
+            prompt,
+            model: policy.model,
+            cwd: workspace?.path ?? this.opts.cwd,
+            posture: isVerifier ? "read-only" : "workspace-write",
+            env: {
+                ...(this.opts.env ?? process.env),
+                HARNESS_BIN: this.opts.harnessBin,
+                HARNESS_UNIT_ID: briefing.unitId,
+            },
+            onActivity: onCursorActivity,
+            ...(resumeSessionId ? { resumeSessionId } : {}),
+            ...(this.opts.deadlineAt !== undefined
+                ? { timeoutMs: Math.max(1, this.opts.deadlineAt - Date.now()) }
+                : {}),
+            ...(this.opts.bin ? { bin: this.opts.bin } : {}),
+            ...(this.opts.execImpl ? { execImpl: this.opts.execImpl } : {}),
+        });
+        if (r.sessionId) {
+            this.opts.recordSession?.(briefing.unitId, kind, r.sessionId, policy.model);
+        }
+        if (isVerifier) {
+            return {
+                ok: r.ok,
+                filesTouched: [],
+                cost: r.costUsd,
+                transcriptRef: cursorTranscriptRef(briefing.unitId, "verifier", r.error),
+                verdict: parseVerdict(r.resultText),
+            };
+        }
+        const esc = ESCALATE_RE.exec(r.resultText);
+        const result = {
+            ok: r.ok && !esc,
+            filesTouched: [],
+            cost: r.costUsd,
+            transcriptRef: cursorTranscriptRef(briefing.unitId, "implementer", r.error),
+        };
+        if (esc) {
+            result.escalation = {
+                reason: esc[1]?.trim() ?? "cursor session escalated",
+                wants: esc[2]?.trim() ?? "operator decision",
+            };
+        }
+        return result;
+    }
+}
+function cursorTranscriptRef(unitId, kind, error) {
+    const ref = `cursor-agent://${unitId}/${kind}`;
+    return error ? `${ref}#error=${encodeURIComponent(error)}` : ref;
+}
+/** Session divider printed once when a Cursor lane starts. */
+export function formatCursorSessionBanner(unitId, kind) {
+    const useColor = process.env.CURSOR_WATCH_COLOR !== "0";
+    const role = kind === "verifier" ? "verify" : "implement";
+    const label = `${shortUnitId(unitId)} · ${role}`;
+    const bar = "─".repeat(Math.max(8, 44 - label.length));
+    const line = `── ${label} ${bar}`;
+    if (!useColor)
+        return line;
+    return `\x1b[2m${line}\x1b[0m`;
+}
+/** ANSI watch line for orchestrate stderr — scannable columns, not a flat dump. */
+export function formatCursorWatchLine(unitId, u) {
+    // Cursor IDE sets NO_COLOR; don't fight it with FORCE_COLOR (Node warns).
+    // Opt out with CURSOR_WATCH_COLOR=0.
+    const useColor = process.env.CURSOR_WATCH_COLOR !== "0";
+    const unit = shortUnitId(unitId);
+    const turn = String(u.turn).padStart(3, " ");
+    const badge = kindBadge(u.kind);
+    const { head, rest } = splitActivityLine(u.line, u.kind);
+    const talk = u.line.replace(/^assistant:\s*/i, "");
+    if (!useColor) {
+        const plain = u.kind === "text"
+            ? talk
+            : u.kind === "tool" && rest
+                ? `${head}  ${rest}`
+                : u.line;
+        return `  ${unit.padEnd(10)} t${turn}  ${badge.padEnd(4)}  ${plain}`;
+    }
+    const reset = "\x1b[0m";
+    const dim = "\x1b[2m";
+    const bold = "\x1b[1m";
+    const cyan = "\x1b[36m";
+    const yellow = "\x1b[33m";
+    const red = "\x1b[31m";
+    const magenta = "\x1b[35m";
+    const unitCol = `${dim}${unit.padEnd(10)}${reset}`;
+    const turnCol = `${dim}t${turn}${reset}`;
+    const badgeCol = u.kind === "tool"
+        ? `${cyan}${bold}${badge.padEnd(4)}${reset}`
+        : u.kind === "tool-result"
+            ? `${red}${bold}${badge.padEnd(4)}${reset}`
+            : `${magenta}${bold}${badge.padEnd(4)}${reset}`;
+    let body;
+    if (u.kind === "tool") {
+        body = rest
+            ? `${cyan}${bold}${head}${reset}  ${cyan}${rest}${reset}`
+            : `${cyan}${head}${reset}`;
+    }
+    else if (u.kind === "tool-result") {
+        body = `${red}${bold}${u.line}${reset}`;
+    }
+    else {
+        body = `${yellow}${talk}${reset}`;
+    }
+    return `  ${unitCol} ${turnCol}  ${badgeCol}  ${body}`;
+}
+function shortUnitId(unitId) {
+    return unitId.replace(/^live-activity-/, "").slice(0, 10);
+}
+function kindBadge(kind) {
+    if (kind === "tool")
+        return "TOOL";
+    if (kind === "tool-result")
+        return "FAIL";
+    return "SAY";
+}
+/** Split `tool: target` so the tool name can be emphasized. */
+function splitActivityLine(line, kind) {
+    if (kind !== "tool")
+        return { head: line, rest: "" };
+    const i = line.indexOf(": ");
+    if (i <= 0)
+        return { head: line, rest: "" };
+    return { head: line.slice(0, i), rest: line.slice(i + 2) };
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/orchestration/runners/stub/index.js

@@ -0,0 +1,168 @@
+/**
+ * StubRunner — a deterministic `Runner` with NO LLM, for the CLI-level
+ * end-to-end (G3). It exercises the whole wiring path — `runLoop` / `plan` /
+ * `step` / `startupSweep`, a real `ShellGit`, a real `LocalForge`, a real git
+ * repo — with only the *agent intelligence* replaced.
+ *
+ * Given a briefing it:
+ *   - implementer: branches `briefing.branch` off the base, writes ONE real
+ *     in-scope file, `git commit`s it with a `Unit: <id>` trailer, restores the
+ *     base branch (so the orchestrator's checkout mirrors the real world, where
+ *     the agent works elsewhere), and returns `ok` with the commit sha.
+ *   - verifier: touches nothing and returns `VERDICT: APPROVE`.
+ *
+ * Declares `{scopeHook: false, sessionTelemetry: false}` so the M2.5 degraded
+ * tier (post-hoc scope check + orchestrator-reconstructed telemetry) is
+ * exercised too. Scriptable per unit to drive the failure branches:
+ *   `.scriptOutOfScope(id)` — the implementer writes OUTSIDE `briefing.scope`
+ *   `.scriptFail(id)`       — the implementer returns `ok: false`
+ *   `.scriptEscalate(id)`   — the implementer raises an escalation
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Deterministic P0 fixture: a couple of tool turns with `tool`/`target`, one
+ * text turn — enough for `ActivityLogWriter` golden tests and the
+ * `ORCHESTRATE_STUB_RUNNER=1` E2E acceptance check to see real `agent.activity`
+ * lines without needing a live LLM.
+ */
+export const DEFAULT_STUB_ACTIVITY = [
+    { line: "read: src/spec.ts", turn: 1, tokens: { in: 0, out: 0 }, kind: "tool", tool: "read", target: "src/spec.ts" },
+    { line: "write: src/impl.ts", turn: 2, tokens: { in: 0, out: 0 }, kind: "tool", tool: "write", target: "src/impl.ts" },
+    { line: "assistant: implemented", turn: 3, tokens: { in: 12, out: 34 }, kind: "text" },
+];
+export class StubRunner {
+    opts;
+    name;
+    baseBranch;
+    gitBin;
+    cost;
+    script = new Map();
+    activityScript = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        this.name = opts.name ?? "claude";
+        this.baseBranch = opts.baseBranch ?? "main";
+        this.gitBin = opts.gitBin ?? "git";
+        this.cost = opts.costPerSession ?? 0.01;
+    }
+    capabilities() {
+        return this.opts.capabilities ?? { scopeHook: false, sessionTelemetry: false };
+    }
+    /** the implementer writes a file OUTSIDE the declared scope (M2.5 path). */
+    scriptOutOfScope(unitId) {
+        this.script.set(unitId, "out-of-scope");
+        return this;
+    }
+    /** the implementer returns `ok: false` (retry / exhaust path). */
+    scriptFail(unitId) {
+        this.script.set(unitId, "fail");
+        return this;
+    }
+    /** the implementer raises an escalation (park, never retry). */
+    scriptEscalate(unitId) {
+        this.script.set(unitId, "escalate");
+        return this;
+    }
+    /** replay this activity through `onActivity` on the implementer path for `unitId`. */
+    scriptActivity(unitId, activity) {
+        this.activityScript.set(unitId, activity);
+        return this;
+    }
+    git(args, cwd = this.opts.cwd) {
+        return execFileSync(this.gitBin, args, {
+            cwd,
+            encoding: "utf8",
+        }).trim();
+    }
+    async run(briefing, _policy, kind, workspace, onActivity) {
+        if (kind === "verifier") {
+            // read-only: touches nothing, approves. Verifier lanes stay silent —
+            // v0 only scripts implementer activity (deliberate, not an oversight;
+            // see plan doc).
+            return {
+                ok: true,
+                filesTouched: [],
+                cost: this.cost,
+                transcriptRef: `stub://${briefing.unitId}/verifier`,
+                verdict: {
+                    approved: true,
+                    reasons: ["VERDICT: APPROVE — stub verifier: meets acceptance criteria"],
+                },
+            };
+        }
+        const activity = this.activityScript.get(briefing.unitId) ??
+            this.opts.defaultActivity ??
+            DEFAULT_STUB_ACTIVITY;
+        for (const a of activity)
+            onActivity?.(a);
+        const mode = this.script.get(briefing.unitId);
+        if (mode === "escalate") {
+            return {
+                ok: false,
+                filesTouched: [],
+                cost: this.cost,
+                transcriptRef: `stub://${briefing.unitId}/implementer`,
+                escalation: {
+                    reason: "stub: scripted escalation",
+                    wants: "operator decision: widen | split | abort",
+                },
+            };
+        }
+        const rel = mode === "out-of-scope"
+            ? "src/__unscoped__/leak.ts"
+            : inScopePath(briefing.scope, briefing.unitId);
+        // work on the unit branch, forked from the base, then restore the base —
+        // the orchestrator's checkout stays on the base branch, exactly as it would
+        // if a real agent had done the work in its own sandbox.
+        const cwd = workspace?.path ?? this.opts.cwd;
+        if (!workspace)
+            this.git(["checkout", "-q", "-B", briefing.branch, this.baseBranch], cwd);
+        const abs = join(cwd, rel);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, `// ${briefing.unitId} — deterministic stub implementation\n` +
+            `// intent: ${briefing.intent}\n` +
+            `export const unit = ${JSON.stringify(briefing.unitId)};\n`);
+        this.git(["add", "-A"], cwd);
+        this.git([
+            "commit",
+            "-q",
+            "-m",
+            `${firstLine(briefing.intent)}\n\nUnit: ${briefing.unitId}`,
+        ], cwd);
+        const sha = this.git(["rev-parse", "HEAD"], cwd);
+        if (!workspace)
+            this.git(["checkout", "-q", this.baseBranch], cwd);
+        await this.opts.afterImplement?.(briefing.unitId);
+        if (mode === "fail") {
+            return {
+                ok: false,
+                commitSha: sha,
+                filesTouched: [rel],
+                cost: this.cost,
+                transcriptRef: `stub://${briefing.unitId}/implementer`,
+            };
+        }
+        return {
+            ok: true,
+            commitSha: sha,
+            filesTouched: [rel],
+            cost: this.cost,
+            transcriptRef: `stub://${briefing.unitId}/implementer`,
+        };
+    }
+}
+/** the literal prefix of the first scope glob + `<unit>.ts` — always in scope. */
+export function inScopePath(scope, unitId) {
+    const glob = scope[0] ?? "src/**";
+    const star = glob.search(/[*?[]/);
+    const head = star === -1 ? glob : glob.slice(0, star);
+    const dir = head.endsWith("/") ? head : head.replace(/[^/]*$/, "");
+    const safe = unitId.replace(/[^A-Za-z0-9_-]+/g, "-");
+    return `${dir || "src/"}${safe}.ts`;
+}
+function firstLine(s) {
+    return s.split("\n")[0].slice(0, 72);
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/orchestration/runners/telemetry.js

@@ -0,0 +1,36 @@
+export function reconstructSessionEvents(p) {
+    const common = {
+        session: p.session,
+        body: {
+            unit_id: p.unitId,
+            session_id: p.session,
+            runner: p.runner,
+            model: p.model,
+            kind: p.kind,
+            emitter: "orchestrator",
+        },
+    };
+    const outcome = p.result.escalation
+        ? "escalated"
+        : p.result.ok
+            ? "ok"
+            : "failed";
+    return [
+        { type: "session.started", unitId: p.unitId, ...common },
+        {
+            type: "session.ended",
+            unitId: p.unitId,
+            session: p.session,
+            body: {
+                ...common.body,
+                outcome,
+                cost: p.result.cost,
+                transcript_ref: p.result.transcriptRef ?? null,
+                files_touched: p.result.filesTouched,
+                ...(p.result.escalation ? { escalation: p.result.escalation } : {}),
+                ...(p.result.verdict ? { verdict: p.result.verdict } : {}),
+            },
+        },
+    ];
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/internal/orchestration/runstate/index.js

@@ -0,0 +1,213 @@
+/**
+ * runstate (D0) — the run's live picture, as a PURE PROJECTION of an in-process
+ * event log. Not the ledger: in-flight state (attempt counts, cost ticking, a
+ * session mid-run) is high-churn and worthless after the run, so it never
+ * touches the hash-chained provenance ledger (dashboard-plan §"Why the feed is
+ * not ledger events"). The durable outcomes it leads to reach the ledger through
+ * their own channels.
+ *
+ *   RunLog.append(event)  — the loop records every transition here
+ *   projectRunState(events) → RunState  — pure fold, golden-tested
+ *
+ * D1 serializes a `RunState` to a `run-status` document and publishes it via
+ * `harness runstatus publish`. D2 renders the final one as the end-of-run HTML
+ * report. Both are downstream of this projection.
+ */
+/** Pure fold. Same events in → identical `RunState` out (golden test). */
+export function projectRunState(events) {
+    const state = {
+        runId: "",
+        machineId: "",
+        systemId: "",
+        specRef: "",
+        startedAt: 0,
+        heartbeatAt: 0,
+        dagSize: 0,
+        lanes: [],
+        parked: [],
+        needsYou: [],
+        notes: [],
+        counts: { merged: 0, escalated: 0, parked: 0, inFlight: 0, needsYou: 0 },
+    };
+    const lanes = new Map();
+    const merged = new Set();
+    const escalated = new Set();
+    for (const e of events) {
+        switch (e.t) {
+            case "run.started":
+                state.runId = e.runId;
+                state.machineId = e.machineId;
+                state.systemId = e.systemId;
+                state.specRef = e.specRef;
+                state.startedAt = e.at;
+                state.heartbeatAt = e.at;
+                state.dagSize = e.dagSize;
+                break;
+            case "unit.parked":
+                if (!state.parked.some((p) => p.unitId === e.unitId))
+                    state.parked.push({ unitId: e.unitId, reason: e.reason });
+                break;
+            case "lane.opened":
+                lanes.set(e.unitId, {
+                    unitId: e.unitId,
+                    session: e.session,
+                    runner: e.runner,
+                    model: e.model,
+                    step: "claim",
+                    attempt: 1,
+                    retryBudget: e.retryBudget,
+                    cost: 0,
+                    emitter: e.emitter,
+                    settled: false,
+                });
+                break;
+            case "lane.step": {
+                const lane = lanes.get(e.unitId);
+                if (lane) {
+                    lane.step = e.step;
+                    if (e.step === "merge" || e.step === "land")
+                        lane.settled = true;
+                }
+                break;
+            }
+            case "lane.attempt": {
+                const lane = lanes.get(e.unitId);
+                if (lane)
+                    lane.attempt = e.attempt;
+                break;
+            }
+            case "lane.cost": {
+                const lane = lanes.get(e.unitId);
+                if (lane)
+                    lane.cost += e.delta;
+                break;
+            }
+            case "lane.retry": {
+                const lane = lanes.get(e.unitId);
+                if (lane) {
+                    lane.attempt = e.attempt;
+                    lane.step = "implement";
+                    lane.settled = false;
+                }
+                break;
+            }
+            case "lane.note":
+                state.notes.push({ unitId: e.unitId, note: e.note });
+                break;
+            case "lane.activity": {
+                const lane = lanes.get(e.unitId);
+                if (lane) {
+                    lane.activity = e.line;
+                    lane.activityAt = e.at;
+                    lane.turn = e.turn;
+                    lane.tokens = e.tokens;
+                    const recent = [...(lane.recent ?? []), e.line];
+                    lane.recent = recent.length > 5 ? recent.slice(-5) : recent;
+                }
+                // A publishing agent IS a heartbeat — a step that runs long (implement
+                // can take 10s of minutes) must not go "stale" on the board while it
+                // is visibly, actively working (dashboard UX gap: activity vs. liveness
+                // were wrongly coupled through this single clock).
+                state.heartbeatAt = Math.max(state.heartbeatAt, e.at);
+                break;
+            }
+            case "lane.envelope": {
+                const lane = lanes.get(e.unitId);
+                if (lane)
+                    lane.envelopeHash = e.hash;
+                break;
+            }
+            case "lane.door": {
+                const lane = lanes.get(e.unitId);
+                if (lane)
+                    lane.doorId = e.doorId;
+                break;
+            }
+            case "unit.merged": {
+                merged.add(e.unitId);
+                const lane = lanes.get(e.unitId);
+                if (lane) {
+                    lane.step = "land";
+                    lane.settled = true;
+                }
+                break;
+            }
+            case "unit.escalated": {
+                escalated.add(e.unitId);
+                const lane = lanes.get(e.unitId);
+                if (lane)
+                    lane.settled = true;
+                break;
+            }
+            case "needs.you":
+                // dedupe on (kind, unitId) — a heartbeat re-publish must not stack them.
+                if (!state.needsYou.some((n) => n.kind === e.kind && n.unitId === e.unitId)) {
+                    const entry = {
+                        kind: e.kind,
+                        message: e.message,
+                        unblock: e.unblock,
+                    };
+                    if (e.unitId !== undefined)
+                        entry.unitId = e.unitId;
+                    state.needsYou.push(entry);
+                }
+                break;
+            case "heartbeat":
+                state.heartbeatAt = e.at;
+                break;
+            case "run.ended":
+                state.outcome = e.outcome;
+                state.heartbeatAt = Math.max(state.heartbeatAt, e.at);
+                break;
+        }
+    }
+    state.lanes = [...lanes.values()];
+    state.counts = {
+        merged: merged.size,
+        escalated: escalated.size,
+        parked: state.parked.length,
+        inFlight: state.lanes.filter((l) => !l.settled).length,
+        needsYou: state.needsYou.length,
+    };
+    return state;
+}
+/** In-process event log the loop appends to; `snapshot()` folds it. */
+export class RunLog {
+    events = [];
+    nowFn;
+    /** optional clock shared with the loop — activity_at is stamped from this, not wall-clock ad hoc. */
+    setClock(now) {
+        this.nowFn = now;
+    }
+    append(event) {
+        this.events.push(event);
+    }
+    /** Record a lane activity update; stamps `activity_at` from the log clock. */
+    recordLaneActivity(unitId, update) {
+        this.append({
+            t: "lane.activity",
+            unitId,
+            line: update.line.length <= 160 ? update.line : update.line.slice(0, 160),
+            turn: update.turn,
+            tokens: update.tokens,
+            at: this.clock(),
+        });
+    }
+    clock() {
+        if (this.nowFn)
+            return this.nowFn();
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const e = this.events[i];
+            if ("at" in e && typeof e.at === "number")
+                return e.at;
+        }
+        return 0;
+    }
+    all() {
+        return this.events;
+    }
+    snapshot() {
+        return projectRunState(this.events);
+    }
+}
+//# sourceMappingURL=index.js.map