@mikenguyen69/harness 0.1.0-beta.1

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

@@ -0,0 +1,90 @@
+export const ACTIVITY_LINE_MAX = 160;
+export function clampActivityLine(line) {
+    return line.length <= ACTIVITY_LINE_MAX ? line : line.slice(0, ACTIVITY_LINE_MAX);
+}
+export class FakeRunner {
+    name;
+    caps;
+    defaultCost;
+    /** keyed `${unitId}:${kind}` (or `${unitId}:${kind}:${attempt}`) → outcome. */
+    script = new Map();
+    calls = [];
+    attempts = new Map();
+    constructor(opts = {}) {
+        this.name = opts.name ?? "fake";
+        this.caps = opts.capabilities ?? { scopeHook: true, sessionTelemetry: true };
+        this.defaultCost = opts.defaultCost ?? 1;
+    }
+    capabilities() {
+        return this.caps;
+    }
+    /** script an outcome. Attempt-scoped key (`unit:kind:2`) beats the loose key. */
+    on(unitId, kind, outcome, attempt) {
+        const key = attempt ? `${unitId}:${kind}:${attempt}` : `${unitId}:${kind}`;
+        this.script.set(key, outcome);
+        return this;
+    }
+    async run(briefing, _policy, kind, _workspace, _onActivity) {
+        const attemptKey = `${briefing.unitId}:${kind}`;
+        const attempt = (this.attempts.get(attemptKey) ?? 0) + 1;
+        this.attempts.set(attemptKey, attempt);
+        this.calls.push({ unitId: briefing.unitId, kind, attempt });
+        const outcome = this.script.get(`${briefing.unitId}:${kind}:${attempt}`) ??
+            this.script.get(`${briefing.unitId}:${kind}`) ??
+            { kind: "ok" };
+        const cost = ("cost" in outcome && outcome.cost) || this.defaultCost;
+        const inScopeFile = briefing.scope[0]?.replace(/\*+.*$/, "") + "file.ts";
+        switch (outcome.kind) {
+            case "ok":
+                // a verifier is read-only — it touches nothing and returns a verdict.
+                if (kind === "verifier") {
+                    return {
+                        ok: true,
+                        filesTouched: outcome.filesTouched ?? [],
+                        transcriptRef: `transcript://${briefing.unitId}/verifier/${attempt}`,
+                        cost,
+                        verdict: { approved: true, reasons: ["meets acceptance criteria"] },
+                    };
+                }
+                return {
+                    ok: true,
+                    commitSha: `sha-${briefing.unitId}-implementer-${attempt}`,
+                    filesTouched: outcome.filesTouched ?? [inScopeFile],
+                    transcriptRef: `transcript://${briefing.unitId}/implementer/${attempt}`,
+                    cost,
+                };
+            case "fail":
+                return {
+                    ok: false,
+                    filesTouched: outcome.filesTouched ?? [inScopeFile],
+                    transcriptRef: `transcript://${briefing.unitId}/${kind}/${attempt}`,
+                    cost,
+                };
+            case "escalate":
+                return {
+                    ok: false,
+                    filesTouched: [],
+                    transcriptRef: `transcript://${briefing.unitId}/${kind}/${attempt}`,
+                    cost,
+                    escalation: { reason: outcome.reason, wants: outcome.wants },
+                };
+            case "reject":
+                return {
+                    ok: true,
+                    filesTouched: [],
+                    transcriptRef: `transcript://${briefing.unitId}/${kind}/${attempt}`,
+                    cost,
+                    verdict: { approved: false, reasons: outcome.reasons },
+                };
+            case "scope-violation":
+                return {
+                    ok: true,
+                    commitSha: `sha-${briefing.unitId}-${kind}-${attempt}`,
+                    filesTouched: outcome.filesTouched,
+                    transcriptRef: `transcript://${briefing.unitId}/${kind}/${attempt}`,
+                    cost,
+                };
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,246 @@
+import { parseVerdict, renderImplementerPrompt, renderVerifierPrompt, } from "../../prompts/index.js";
+import { runClaudeSession } from "./sdk.js";
+import { claudeEnv, ensureAgentHarnessHook, emitClaudeSessionTelemetry, writeCurrentUnit, } from "./wiring.js";
+/** write tools the implementer may use; the verifier gets NONE of these. */
+const WRITE_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
+/** read-only tool set for verifier sessions. */
+const VERIFIER_TOOLS = ["Read", "Grep", "Glob", "Bash"];
+export class ClaudeRunner {
+    opts;
+    name = "claude";
+    sessionSequence = 0;
+    spentUsd = 0;
+    reservedUsd = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    capabilities() {
+        return { scopeHook: true, sessionTelemetry: true };
+    }
+    async run(briefing, policy, kind, workspace, onActivity) {
+        const cwd = workspace?.path ?? this.opts.cwd;
+        const limits = this.reserveLimits();
+        if (!limits) {
+            return {
+                ok: false,
+                filesTouched: [],
+                cost: 0,
+                telemetryError: "Claude session was not dispatched: run cost or duration budget exhausted",
+            };
+        }
+        const session = `${this.opts.sessionPrefix ?? "claude"}-${briefing.unitId}-${kind}-${++this.sessionSequence}`;
+        // wire agent-harness under the session (ring-0 scope + session.* telemetry).
+        writeCurrentUnit({
+            cwd,
+            briefing,
+            session,
+            harnessBin: this.opts.harnessBin,
+            agentHarnessBin: this.opts.agentHarnessBin,
+        });
+        ensureAgentHarnessHook({
+            cwd,
+            briefing,
+            session,
+            harnessBin: this.opts.harnessBin,
+            agentHarnessBin: this.opts.agentHarnessBin,
+            ...(this.opts.agentHarnessBinArgs?.length
+                ? { agentHarnessBinArgs: this.opts.agentHarnessBinArgs }
+                : {}),
+        });
+        const env = claudeEnv(this.opts.env ?? process.env, {
+            harnessBin: this.opts.harnessBin,
+            session,
+            unitId: briefing.unitId,
+            ...(this.opts.harnessBinArgs?.length ? { harnessBinArgs: this.opts.harnessBinArgs } : {}),
+            ...(this.opts.ledgerDir ? { ledgerDir: this.opts.ledgerDir } : {}),
+            ...(this.opts.systemId ? { systemId: this.opts.systemId } : {}),
+        });
+        const emit = async (phase, body) => {
+            if (this.opts.emitTelemetry)
+                return this.opts.emitTelemetry({ phase, body });
+            return emitClaudeSessionTelemetry({
+                agentHarnessBin: this.opts.agentHarnessBin,
+                ...(this.opts.agentHarnessBinArgs?.length
+                    ? { agentHarnessBinArgs: this.opts.agentHarnessBinArgs }
+                    : {}),
+                phase,
+                body,
+                cwd,
+                env,
+            });
+        };
+        const common = {
+            session_id: session,
+            unit_id: briefing.unitId,
+            component_id: briefing.component ?? "unknown",
+            model: policy.model,
+            runner: this.name,
+            role: kind,
+            emitter: "adapter",
+        };
+        try {
+            await emit("started", common);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                sessionId: session,
+                filesTouched: [],
+                cost: 0,
+                telemetryError: error.message,
+            };
+        }
+        let result;
+        try {
+            result = kind === "verifier"
+                ? await this.runVerifier(briefing, policy, env, limits, cwd, onActivity)
+                : await this.runImplementer(briefing, policy, env, limits, cwd, onActivity);
+            result.sessionId = session;
+            if (result.escalation) {
+                await emit("escalated", { ...common, escalation: result.escalation });
+            }
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                sessionId: session,
+                filesTouched: [],
+                cost: 0,
+                telemetryError: error.message,
+            };
+        }
+        this.releaseBudget(limits.reservedUsd, result.cost);
+        try {
+            await emit("ended", {
+                ...common,
+                tokens: result.tokens ?? { in: 0, out: 0 },
+                cost_usd: result.cost,
+                transcript_ref: result.transcriptRef ?? null,
+                ended: {
+                    outcome: result.escalation ? "escalated" : result.ok ? "handed-off" : "abandoned",
+                },
+            });
+        }
+        catch (error) {
+            result.ok = false;
+            result.telemetryError = error.message;
+        }
+        return result;
+    }
+    async runImplementer(briefing, policy, env, limits, cwd, onActivity) {
+        const prompt = renderImplementerPrompt(briefing, this.opts.retryFor?.(briefing.unitId, "implementer"));
+        const activitySink = onActivity
+            ? (u) => 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 } : {}),
+            })
+            : undefined;
+        const r = await runClaudeSession({
+            prompt,
+            model: policy.model,
+            cwd,
+            permissionMode: "acceptEdits",
+            allowedTools: [...WRITE_TOOLS, "Read", "Grep", "Glob", "Bash"],
+            env,
+            settingSources: ["project"],
+            ...(this.opts.maxTurns ? { maxTurns: this.opts.maxTurns } : {}),
+            ...(limits.maxBudgetUsd !== undefined
+                ? { maxBudgetUsd: limits.maxBudgetUsd }
+                : {}),
+            ...(limits.abortSignal ? { abortSignal: limits.abortSignal } : {}),
+            ...(this.opts.queryImpl ? { queryImpl: this.opts.queryImpl } : {}),
+            ...(activitySink ? { onActivity: activitySink } : {}),
+        });
+        const result = {
+            ok: r.ok && !r.permissionDenied,
+            filesTouched: [], // the loop cross-checks with `git diff` (M2.5 + M3)
+            cost: r.totalCostUsd,
+            tokens: r.tokens,
+            ...(r.sessionId ? { transcriptRef: `claude-session://${r.sessionId}` } : {}),
+        };
+        // a denied write is a scope violation the ring-0 hook caught in-session.
+        if (r.permissionDenied) {
+            result.escalation = {
+                reason: "the ring-0 scope hook denied a write outside the declared scope",
+                wants: "widen scope or split the unit",
+            };
+        }
+        return result;
+    }
+    async runVerifier(briefing, policy, env, limits, cwd, onActivity) {
+        const diff = (await this.opts.diffFor?.(briefing.unitId)) ?? "";
+        const prompt = renderVerifierPrompt(briefing, diff);
+        const activitySink = onActivity
+            ? (u) => 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 } : {}),
+            })
+            : undefined;
+        const r = await runClaudeSession({
+            prompt,
+            model: policy.model,
+            cwd,
+            // read-only: NO write tools at all, and never auto-accept an edit.
+            permissionMode: "default",
+            allowedTools: VERIFIER_TOOLS,
+            disallowedTools: WRITE_TOOLS,
+            env,
+            settingSources: ["project"],
+            ...(this.opts.maxTurns ? { maxTurns: this.opts.maxTurns } : {}),
+            ...(limits.maxBudgetUsd !== undefined
+                ? { maxBudgetUsd: limits.maxBudgetUsd }
+                : {}),
+            ...(limits.abortSignal ? { abortSignal: limits.abortSignal } : {}),
+            ...(this.opts.queryImpl ? { queryImpl: this.opts.queryImpl } : {}),
+            ...(activitySink ? { onActivity: activitySink } : {}),
+        });
+        const verdict = parseVerdict(r.resultText);
+        return {
+            ok: r.ok,
+            filesTouched: [], // a verifier must touch nothing; the loop's post-hoc diff is the backstop
+            cost: r.totalCostUsd,
+            tokens: r.tokens,
+            ...(r.sessionId ? { transcriptRef: `claude-session://${r.sessionId}` } : {}),
+            verdict,
+        };
+    }
+    reserveLimits() {
+        let reservedUsd = 0;
+        let maxBudgetUsd;
+        if (this.opts.maxRunCost !== undefined) {
+            const available = this.opts.maxRunCost - this.spentUsd - this.reservedUsd;
+            if (available <= 0)
+                return null;
+            reservedUsd = available;
+            maxBudgetUsd = available;
+            this.reservedUsd += reservedUsd;
+        }
+        let abortSignal;
+        if (this.opts.deadlineAt !== undefined) {
+            const remaining = this.opts.deadlineAt - Date.now();
+            if (remaining <= 0) {
+                this.reservedUsd -= reservedUsd;
+                return null;
+            }
+            abortSignal = AbortSignal.timeout(remaining);
+        }
+        return {
+            reservedUsd,
+            ...(maxBudgetUsd !== undefined ? { maxBudgetUsd } : {}),
+            ...(abortSignal ? { abortSignal } : {}),
+        };
+    }
+    releaseBudget(reservedUsd, actualUsd) {
+        this.reservedUsd = Math.max(0, this.reservedUsd - reservedUsd);
+        this.spentUsd += actualUsd;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/orchestration/runners/claude/sdk.js

@@ -0,0 +1,198 @@
+const LINE_CLAMP = 160;
+const ARG_CLAMP = 80;
+async function loadRealQuery() {
+    const mod = await import("@anthropic-ai/claude-agent-sdk");
+    return mod.query;
+}
+export async function runClaudeSession(params) {
+    const query = params.queryImpl ?? (await loadRealQuery());
+    const options = {
+        model: params.model,
+        cwd: params.cwd,
+        permissionMode: params.permissionMode,
+        env: params.env,
+        ...(params.allowedTools ? { allowedTools: params.allowedTools } : {}),
+        ...(params.disallowedTools ? { disallowedTools: params.disallowedTools } : {}),
+        ...(params.settingSources ? { settingSources: params.settingSources } : {}),
+        ...(params.maxTurns ? { maxTurns: params.maxTurns } : {}),
+        ...(params.maxBudgetUsd !== undefined
+            ? { maxBudgetUsd: params.maxBudgetUsd }
+            : {}),
+        ...(params.abortSignal
+            ? { abortController: abortControllerFor(params.abortSignal) }
+            : {}),
+    };
+    const result = {
+        ok: false,
+        resultText: "",
+        totalCostUsd: 0,
+        sessionId: null,
+        numTurns: 0,
+        tokens: { in: 0, out: 0 },
+        permissionDenied: false,
+    };
+    let turn = 0;
+    let latestTokens = { in: 0, out: 0 };
+    const toolNames = new Map();
+    const emit = (line, kind, tool, target) => {
+        if (!params.onActivity)
+            return;
+        try {
+            params.onActivity({
+                line: clamp(line, LINE_CLAMP),
+                turn,
+                tokens: { ...latestTokens },
+                kind,
+                ...(tool ? { tool } : {}),
+                ...(target ? { target } : {}),
+            });
+        }
+        catch {
+            // broken sink must not change the session result
+        }
+    };
+    try {
+        for await (const msg of query({ prompt: params.prompt, options })) {
+            const m = msg;
+            const usageTokens = extractUsageTokens(m);
+            if (usageTokens)
+                latestTokens = usageTokens;
+            if (m.type === "assistant") {
+                turn += 1;
+                const blocks = contentBlocks(m);
+                let emitted = false;
+                for (const block of blocks) {
+                    if (block.type === "tool_use") {
+                        const name = typeof block.name === "string" && block.name ? block.name : "tool";
+                        if (typeof block.id === "string")
+                            toolNames.set(block.id, name);
+                        const arg = clamp(primaryArgument(block.input), ARG_CLAMP);
+                        emit(`${name}: ${arg}`, "tool", name, arg || undefined);
+                        emitted = true;
+                    }
+                    else if (block.type === "text") {
+                        const excerpt = clamp(typeof block.text === "string" ? block.text : "", ARG_CLAMP);
+                        emit(excerpt ? `assistant: ${excerpt}` : "assistant", "text");
+                        emitted = true;
+                    }
+                }
+                if (!emitted)
+                    emit("assistant", "text");
+            }
+            else if (m.type === "user") {
+                for (const block of contentBlocks(m)) {
+                    if (block.type !== "tool_result")
+                        continue;
+                    const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+                    const name = toolNames.get(id) ?? "tool";
+                    emit(block.is_error === true ? `${name} -> error` : `${name} -> ok`, "tool-result", name);
+                }
+            }
+            else if (m.type === "result") {
+                result.totalCostUsd = numberOr(m.total_cost_usd, result.totalCostUsd);
+                result.numTurns = numberOr(m.num_turns, result.numTurns);
+                const usage = m.usage;
+                if (usage) {
+                    result.tokens = {
+                        in: numberOr(usage.input_tokens, result.tokens.in),
+                        out: numberOr(usage.output_tokens, result.tokens.out),
+                    };
+                    latestTokens = { ...result.tokens };
+                }
+                if (typeof m.session_id === "string")
+                    result.sessionId = m.session_id;
+                if (typeof m.result === "string")
+                    result.resultText = m.result;
+                const denials = m.permission_denials;
+                if (Array.isArray(denials) && denials.length > 0)
+                    result.permissionDenied = true;
+                if (m.subtype === "success") {
+                    result.ok = true;
+                }
+                else {
+                    result.ok = false;
+                    result.error =
+                        (Array.isArray(m.errors) && m.errors.join("; ")) ||
+                            (typeof m.subtype === "string" ? m.subtype : "error");
+                }
+            }
+        }
+    }
+    catch (e) {
+        result.ok = false;
+        result.error = e.message;
+    }
+    return result;
+}
+function contentBlocks(msg) {
+    const nested = msg.message;
+    const raw = nested?.content ?? msg.content;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((b) => !!b && typeof b === "object" && !Array.isArray(b));
+}
+/** Prefer well-known tool input keys, else the first string value. */
+function primaryArgument(input) {
+    if (input == null)
+        return "";
+    if (typeof input === "string")
+        return input;
+    if (typeof input !== "object" || Array.isArray(input)) {
+        try {
+            return JSON.stringify(input);
+        }
+        catch {
+            return "";
+        }
+    }
+    const obj = input;
+    const preferred = [
+        "file_path",
+        "path",
+        "command",
+        "pattern",
+        "query",
+        "url",
+        "prompt",
+    ];
+    for (const key of preferred) {
+        const v = obj[key];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    for (const v of Object.values(obj)) {
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    try {
+        return JSON.stringify(input);
+    }
+    catch {
+        return "";
+    }
+}
+function extractUsageTokens(msg) {
+    const nested = msg.message;
+    const usage = (nested?.usage ?? msg.usage);
+    if (!usage)
+        return null;
+    return {
+        in: numberOr(usage.input_tokens, 0),
+        out: numberOr(usage.output_tokens, 0),
+    };
+}
+function clamp(s, max) {
+    return s.length <= max ? s : s.slice(0, max);
+}
+function numberOr(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function abortControllerFor(signal) {
+    const ac = new AbortController();
+    if (signal.aborted)
+        ac.abort();
+    else
+        signal.addEventListener("abort", () => ac.abort(), { once: true });
+    return ac;
+}
+//# sourceMappingURL=sdk.js.map

package/dist/internal/orchestration/runners/claude/wiring.js

@@ -0,0 +1,98 @@
+/**
+ * wiring — puts an agent-harness adapter under a Claude session so it gets
+ * ring-0 scope enforcement + first-hand `session.*` telemetry (v0-plan M2
+ * "Session wiring (Claude)"):
+ *   - write `.harness/current-unit.json` (the hook reads the unit + scope from here)
+ *   - ensure the `harness hook pre-tool-use` PreToolUse entry in
+ *     `.claude/settings.json` (no internal binary path, no AGENT_HARNESS_BIN).
+ *     Session-time ensure of the same public command; the named owner of
+ *     init-composes-hook-install is system-harness `init` → agent-harness
+ *     `adapter/install`.
+ *   - set `HARNESS_BIN` / `HARNESS_SESSION_ID` in the session env (process env
+ *     for the adapter to reach the system CLI — not a user-facing install step)
+ *
+ * All writes land in the session `cwd` (the driven project's checkout). Pure
+ * except for those three fs effects; each is idempotent.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { callProcess } from "../../harness/cli.js";
+/** Public facade hook command — never an absolute internal CLI path. */
+export const HOOK_COMMAND = "harness hook pre-tool-use";
+/** `.harness/current-unit.json` — the shape `agent-harness`'s `loadUnitContext` reads. */
+export function writeCurrentUnit(opts) {
+    const path = join(opts.cwd, ".harness", "current-unit.json");
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({
+        unit_id: opts.briefing.unitId,
+        component_id: opts.briefing.component ?? null,
+        scope: opts.briefing.scope,
+        session_id: opts.session,
+    }, null, 2) + "\n");
+    return path;
+}
+/**
+ * Merge the PreToolUse hooks block into `.claude/settings.json`.
+ * Idempotent: if a PreToolUse entry already runs `harness hook pre-tool-use`
+ * (or the legacy `hook pre-tool-use` form), nothing changes.
+ */
+export function ensureAgentHarnessHook(opts) {
+    const path = join(opts.cwd, ".claude", "settings.json");
+    const snippet = {
+        PreToolUse: [
+            {
+                matcher: "Write|Edit|MultiEdit|NotebookEdit",
+                hooks: [{ type: "command", command: HOOK_COMMAND }],
+            },
+        ],
+    };
+    let settings = {};
+    if (existsSync(path)) {
+        try {
+            settings = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            settings = {};
+        }
+    }
+    const hooks = (settings.hooks ??= {});
+    const pre = (hooks.PreToolUse ??= []);
+    const already = JSON.stringify(pre).includes("harness hook pre-tool-use") ||
+        JSON.stringify(pre).includes("hook pre-tool-use");
+    if (!already && Array.isArray(snippet.PreToolUse)) {
+        pre.push(...snippet.PreToolUse);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+    return path;
+}
+/** The session env: the base env plus HARNESS_BIN + HARNESS_SESSION_ID. */
+export function claudeEnv(base, opts) {
+    return {
+        ...base,
+        HARNESS_BIN: opts.harnessBin,
+        ...(opts.harnessBinArgs?.length
+            ? { HARNESS_BIN_ARGS: JSON.stringify(opts.harnessBinArgs) }
+            : {}),
+        HARNESS_SESSION_ID: opts.session,
+        HARNESS_UNIT_ID: opts.unitId,
+        ...(opts.ledgerDir ? { HARNESS_LEDGER_DIR: opts.ledgerDir } : {}),
+        ...(opts.systemId ? { HARNESS_SYSTEM: opts.systemId } : {}),
+    };
+}
+/** Invoke the adapter's public session surface; any failure is authoritative. */
+export function emitClaudeSessionTelemetry(opts) {
+    return callProcess({
+        command: opts.agentHarnessBin,
+        args: [...(opts.agentHarnessBinArgs ?? []), "session", opts.phase],
+        cwd: opts.cwd,
+        env: opts.env,
+        stdin: JSON.stringify(opts.body),
+    }).then((result) => {
+        if (result.code !== 0) {
+            const detail = (result.stderr || result.stdout).trim();
+            throw new Error(`agent-harness session ${opts.phase} failed (${result.code}): ${detail}`);
+        }
+    });
+}
+//# sourceMappingURL=wiring.js.map