@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/orchestration/runners/codex/exec.js

@@ -0,0 +1,114 @@
+/**
+ * exec — the ONLY module that shells `codex exec`. Everything else in
+ * `src/runners/codex/` is plain glue over the agent-neutral `Runner` contract.
+ * If the Codex CLI's flag surface shifts, this file is the blast radius.
+ *
+ * `codex exec` runs one non-interactive turn. Surface used (verify against the
+ * installed `codex` at integration time — do not guess further):
+ *   codex exec "<prompt>" --model <m> --cd <cwd> --sandbox <mode> --json
+ * `--json` streams JSONL events on stdout; the last assistant/message event is
+ * the result. Exit 0 = the turn completed.
+ *
+ * `execImpl` is injectable so the runner's tests never spawn `codex`.
+ */
+import { execFile } from "node:child_process";
+export async function execCodexProcess(bin, args, opts) {
+    return new Promise((resolve) => {
+        // Stay in the parent's process group / console (execFile is not detached)
+        // so the facade's process-group interrupt reaches Codex.
+        const child = execFile(bin, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            encoding: "utf8",
+            maxBuffer: 32 * 1024 * 1024,
+            ...(opts.timeoutMs !== undefined ? { timeout: opts.timeoutMs } : {}),
+        }, (error, stdout, stderr) => resolve(foldProcessExit(error, stdout, stderr, opts.timeoutMs)));
+        // `codex exec` treats piped stdin as additional prompt input. execFile
+        // otherwise leaves this pipe open, so Codex waits forever before starting.
+        child.stdin?.end();
+    });
+}
+function foldProcessExit(error, stdout, stderr, timeoutMs) {
+    if (!error)
+        return { code: 0, stdout, stderr };
+    const timedOut = timeoutMs !== undefined &&
+        (error.killed === true || error.signal != null || error.code === "ETIMEDOUT");
+    const timeoutError = timedOut ? `codex exec timed out after ${timeoutMs}ms` : "";
+    return {
+        code: typeof error.code === "number" ? error.code : 1,
+        stdout,
+        stderr: [stderr.trim(), timeoutError].filter(Boolean).join("\n"),
+    };
+}
+export async function runCodexExec(params) {
+    const bin = params.bin ?? "codex";
+    const args = [
+        "exec",
+        params.prompt,
+        "--model",
+        params.model,
+        "--cd",
+        params.cwd,
+        "--sandbox",
+        params.sandbox,
+        "--json",
+    ];
+    const exec = params.execImpl
+        ? params.execImpl
+        : execCodexProcess.bind(undefined, bin);
+    const { code, stdout, stderr } = await exec(args, {
+        cwd: params.cwd,
+        env: params.env,
+        ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs } : {}),
+    });
+    return foldCodexStream(stdout, code, stderr);
+}
+/** Parse `codex exec --json` JSONL into a flat result. Tolerant of unknown event shapes. */
+export function foldCodexStream(stdout, code, stderr) {
+    let resultText = "";
+    let costUsd = 0;
+    for (const line of stdout.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        // last message-ish event wins as the result text.
+        const msg = pickString(ev, ["message", "text", "content", "last_message"]) ??
+            (ev.type === "message" ? pickString(ev, ["data"]) : undefined) ??
+            pickAgentMessage(ev);
+        if (msg)
+            resultText = msg;
+        // token usage → a rough cost, if present.
+        const usage = ev.usage;
+        if (usage) {
+            costUsd +=
+                ((usage.input_tokens ?? 0) / 1e6) * 3 + ((usage.output_tokens ?? 0) / 1e6) * 15;
+        }
+    }
+    return code === 0
+        ? { ok: true, resultText, costUsd }
+        : { ok: false, resultText, costUsd, error: (stderr || stdout).trim() || `codex exec exit ${code}` };
+}
+function pickAgentMessage(ev) {
+    if (ev.type !== "item.completed" || !isRecord(ev.item))
+        return undefined;
+    return ev.item.type === "agent_message"
+        ? pickString(ev.item, ["text", "message"])
+        : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pickString(o, keys) {
+    for (const k of keys)
+        if (typeof o[k] === "string")
+            return o[k];
+    return undefined;
+}
+//# sourceMappingURL=exec.js.map

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

@@ -0,0 +1,72 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseVerdict, renderImplementerPrompt, renderVerifierPrompt, } from "../../prompts/index.js";
+import { runCodexExec } from "./exec.js";
+/** the agent has escalated when its output carries this sentinel (codex has no escalate verb). */
+const ESCALATE_RE = /ESCALATE:\s*(.+?)(?:\s+WANTS:\s*(.+))?$/im;
+export class CodexRunner {
+    opts;
+    name = "codex";
+    constructor(opts) {
+        this.opts = opts;
+    }
+    capabilities() {
+        return { scopeHook: false, sessionTelemetry: false };
+    }
+    async run(briefing, policy, kind, workspace, _onActivity) {
+        const isVerifier = kind === "verifier";
+        const prompt = isVerifier
+            ? renderVerifierPrompt(briefing, (await this.opts.diffFor?.(briefing.unitId)) ?? "")
+            : renderImplementerPrompt(briefing, this.opts.retryFor?.(briefing.unitId, "implementer"));
+        const r = await runCodexExec({
+            prompt,
+            model: policy.model,
+            cwd: workspace?.path ?? this.opts.cwd,
+            sandbox: isVerifier ? "read-only" : "workspace-write",
+            env: {
+                ...withCodexHome(this.opts.env ?? process.env),
+                HARNESS_BIN: this.opts.harnessBin,
+                HARNESS_UNIT_ID: briefing.unitId,
+            },
+            ...(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 (isVerifier) {
+            return {
+                ok: r.ok,
+                filesTouched: [], // read-only sandbox; the loop's post-hoc diff is the backstop
+                cost: r.costUsd,
+                transcriptRef: codexTranscriptRef(briefing.unitId, "verifier", r.error),
+                verdict: parseVerdict(r.resultText),
+            };
+        }
+        const esc = ESCALATE_RE.exec(r.resultText);
+        const result = {
+            ok: r.ok && !esc,
+            // codex exec reports no file list — the loop cross-checks with `git diff`.
+            filesTouched: [],
+            cost: r.costUsd,
+            transcriptRef: codexTranscriptRef(briefing.unitId, "implementer", r.error),
+        };
+        if (esc) {
+            result.escalation = {
+                reason: esc[1]?.trim() ?? "codex session escalated",
+                wants: esc[2]?.trim() ?? "operator decision",
+            };
+        }
+        return result;
+    }
+}
+function codexTranscriptRef(unitId, kind, error) {
+    const ref = `codex-exec://${unitId}/${kind}`;
+    return error ? `${ref}#error=${encodeURIComponent(error)}` : ref;
+}
+function withCodexHome(env) {
+    if (env.CODEX_HOME?.trim())
+        return env;
+    return { ...env, CODEX_HOME: join(homedir(), ".codex") };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,169 @@
+/**
+ * conformance — the shared scenario set every `Runner` implementation must
+ * satisfy, mirroring agent-harness's adapter conformance suite (AH P2.4). A
+ * scenario names a `RunnerBehavior` and asserts the loop outcome it must
+ * produce; the runner's identity never appears in the assertions.
+ *
+ * `checkRunnerConformance(makeRunner, applyBehavior)` runs the scenarios against
+ * any runner: `applyBehavior` translates the abstract behaviour into that
+ * runner's own scripting (a `FakeRunner`'s `.on()`, a `CodexRunner`'s mock
+ * `execImpl`, a replay `queryImpl` for `ClaudeRunner`). The FakeRunner applier
+ * is the default.
+ */
+import { FakeHarness } from "../../harness/index.js";
+import { DEFAULT_CONFIG, FakeGit, runLoop, } from "../../loop/index.js";
+import { FakeRouteSource } from "../../routes/index.js";
+import { RunLog } from "../../runstate/index.js";
+import { FakeRunner } from "../../runner/index.js";
+export const SCENARIOS = [
+    {
+        name: "clean run — implementer ok, verifier approves, unit merges",
+        units: [{ id: "a", mergeFacts: { door: "two-way" } }],
+        behavior: { kind: "clean" },
+        check: (s) => {
+            assert(s.outcome === "completed", `outcome ${s.outcome} != completed`);
+            assert(s.counts.merged === 1, `merged ${s.counts.merged} != 1`);
+            assert(s.counts.inFlight === 0, "a lane was left in flight");
+        },
+    },
+    {
+        name: "gate failure then recovery — one implementer retry, then merge",
+        units: [{ id: "a", mergeFacts: { door: "two-way" } }],
+        config: { retryBudget: 2 },
+        behavior: { kind: "fail-then-ok" },
+        check: (s) => {
+            assert(s.outcome === "completed", `outcome ${s.outcome}`);
+            assert(s.counts.merged === 1, `merged ${s.counts.merged}`);
+        },
+    },
+    {
+        name: "gate failure past budget — halts with retry-exhausted",
+        units: [{ id: "a", mergeFacts: { door: "two-way" } }],
+        config: { retryBudget: 1 },
+        behavior: { kind: "fail-always" },
+        check: (s) => {
+            assert(s.outcome === "halted", `outcome ${s.outcome}`);
+            assert(s.needsYou.some((n) => n.kind === "retry-exhausted"), "no retry-exhausted needs-you entry");
+        },
+    },
+    {
+        name: "escalation — parks the unit, never spends the retry budget",
+        units: [{ id: "a" }],
+        config: { retryBudget: 3 },
+        behavior: { kind: "escalate", reason: "scope too narrow", wants: "widen scope" },
+        check: (s) => {
+            assert(s.outcome === "halted", `outcome ${s.outcome}`);
+            assert(s.counts.escalated === 1, `escalated ${s.counts.escalated}`);
+            assert(s.needsYou.some((n) => n.kind === "escalation"), "no escalation needs-you entry");
+        },
+    },
+    {
+        name: "scope violation (degraded tier) — rejected, never a merge candidate",
+        units: [{ id: "a", scope: ["src/a/**"] }],
+        config: { retryBudget: 0 },
+        behavior: {
+            kind: "scope-violation",
+            filesTouched: ["src/a/ok.ts", "src/other/leak.ts"],
+        },
+        check: (s) => {
+            assert(s.outcome === "halted", `outcome ${s.outcome}`);
+            assert(s.counts.merged === 0, "a scope-violating unit merged");
+            assert(s.needsYou.some((n) => n.kind === "retry-exhausted"), "scope violation did not exhaust into a halt");
+        },
+    },
+    {
+        name: "dead session — a stranded in-review unit halts the startup sweep",
+        units: [{ id: "a", state: "in-review" }],
+        behavior: { kind: "none" },
+        check: (s) => {
+            assert(s.outcome === "halted", `outcome ${s.outcome}`);
+            assert(s.needsYou.some((n) => n.kind === "stranded-in-review"), "no stranded-in-review needs-you entry");
+        },
+    },
+];
+function assert(cond, msg) {
+    if (!cond)
+        throw new Error(msg);
+}
+/** The default applier: script a `FakeRunner` from a `RunnerBehavior`. */
+export function applyFakeBehavior(runner, behavior, unitId) {
+    switch (behavior.kind) {
+        case "clean":
+        case "none":
+            return;
+        case "fail-then-ok":
+            runner.on(unitId, "implementer", { kind: "fail" }, 1);
+            runner.on(unitId, "implementer", { kind: "ok" }, 2);
+            return;
+        case "fail-always":
+            runner.on(unitId, "implementer", { kind: "fail" });
+            return;
+        case "escalate":
+            runner.on(unitId, "implementer", {
+                kind: "escalate",
+                reason: behavior.reason,
+                wants: behavior.wants,
+            });
+            return;
+        case "scope-violation":
+            runner.on(unitId, "implementer", {
+                kind: "scope-violation",
+                filesTouched: behavior.filesTouched,
+            });
+            return;
+    }
+}
+/**
+ * Run every scenario against a runner built by `makeRunner`. `applyBehavior`
+ * scripts the runner for each scenario — defaults to the `FakeRunner` applier.
+ * For the scope-violation scenario the runner is forced to the degraded tier.
+ */
+export async function checkRunnerConformance(makeRunner, applyBehavior = (r, b, u) => {
+    if (r instanceof FakeRunner)
+        applyFakeBehavior(r, b, u);
+}) {
+    const out = [];
+    for (const sc of SCENARIOS) {
+        const degraded = sc.behavior.kind === "scope-violation";
+        const runner = degraded
+            ? makeRunner({ scopeHook: false, sessionTelemetry: false })
+            : makeRunner();
+        const target = sc.target ?? sc.units[0].id;
+        await applyBehavior(runner, sc.behavior, target, sc);
+        const git = new FakeGit();
+        if (sc.behavior.kind === "scope-violation") {
+            // the degraded tier's cross-check reads `git diff` — make it see the leak.
+            git.setChangedFiles(`unit/${target}`, sc.behavior.filesTouched);
+        }
+        const deps = {
+            harness: new FakeHarness(sc.units),
+            routes: new FakeRouteSource({
+                runner: runner.name,
+                model: "conformance-model",
+                mode: "auto",
+            }),
+            runners: new Map([[runner.name, runner]]),
+            git,
+            config: { ...DEFAULT_CONFIG, runnersEnabled: [runner.name], ...sc.config },
+            log: new RunLog(),
+            mintSession: (() => {
+                let n = 0;
+                return () => `s-${++n}`;
+            })(),
+        };
+        try {
+            const state = await runLoop(deps, {
+                specRef: "conformance",
+                systemId: "conformance",
+                dagSize: sc.units.length,
+            });
+            sc.check(state);
+            out.push({ name: sc.name, ok: true });
+        }
+        catch (e) {
+            out.push({ name: sc.name, ok: false, error: e.message });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=index.js.map