@mikenguyen69/harness 0.1.0-beta.1

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

@@ -0,0 +1,111 @@
+/**
+ * activity — the durable, append-only per-run activity log (docs/plan/
+ * 2026-09-02-run-activity-capture-and-synthesis.md). One JSONL file per run
+ * under `<repo>/.harness/runs/<run-id>/activity.jsonl`, written alongside
+ * (never instead of) the in-memory `RunLog` snapshot that drives the spool/
+ * board feed — the two are independent channels (design principle 3).
+ *
+ * `orchestrator.step`/`agent.activity` mirror `RunLog`'s `lane.step`/
+ * `lane.activity` events but add a durable `at` timestamp and (for agent
+ * activity) `kind`/`tool`/`target` — fields the snapshot never carries, since
+ * widening `RunEvent` would touch the golden-tested `projectRunState` reducer
+ * for no benefit to the live feed.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/** default hard cap; `text` events are dropped past this, `tool`/`tool-result`/step/bookend events never are. */
+export const ACTIVITY_LOG_MAX_LINES = 50_000;
+function toIso(at) {
+    return new Date(at).toISOString();
+}
+/**
+ * Flush-per-line, no fd management — matches the codebase's existing
+ * preference for simplicity over buffering (e.g. `StubRunner`'s
+ * `writeFileSync`). Every `writeX` method throws on fs failure; callers (the
+ * loop) catch and degrade via `log.append({t:"lane.note",...})`, exactly like
+ * `RunLog.recordLaneActivity`'s existing catch block — the writer itself stays
+ * trivial and never swallows its own errors.
+ */
+export class ActivityLogWriter {
+    path;
+    resumes;
+    maxLines;
+    linesWritten = 0;
+    truncated = false;
+    log = [];
+    constructor(opts) {
+        this.path = opts.path;
+        this.resumes = opts.resumes;
+        this.maxLines = opts.maxLines ?? ACTIVITY_LOG_MAX_LINES;
+        mkdirSync(dirname(this.path), { recursive: true });
+    }
+    write(ev) {
+        this.log.push(ev);
+        appendFileSync(this.path, JSON.stringify(ev) + "\n");
+        this.linesWritten += 1;
+    }
+    writeRunStarted(ev) {
+        this.write({
+            t: "run.started",
+            at: toIso(ev.at),
+            run_id: ev.runId,
+            dag_size: ev.dagSize,
+            max_parallel: ev.maxParallel,
+            ...(this.resumes ? { resumes: this.resumes } : {}),
+        });
+    }
+    writeRunEnded(ev) {
+        this.write({ t: "run.ended", at: toIso(ev.at), run_id: ev.runId, outcome: ev.outcome });
+    }
+    writeOrchestratorStep(ev) {
+        this.write({
+            t: "orchestrator.step",
+            at: toIso(ev.at),
+            run_id: ev.runId,
+            unit_id: ev.unitId,
+            step: ev.step,
+            attempt: ev.attempt,
+            session: ev.session,
+        });
+    }
+    writeAgentActivity(ev) {
+        if (this.linesWritten >= this.maxLines) {
+            if (!this.truncated) {
+                this.truncated = true;
+                this.write({
+                    t: "activity.truncated",
+                    at: toIso(ev.at),
+                    run_id: ev.runId,
+                    after_lines: this.maxLines,
+                });
+            }
+            // tool / tool-result events carry the findings-relevant signal — only
+            // drop `text` turns once the cap is crossed.
+            if (ev.kind === "text" || ev.kind === undefined)
+                return;
+        }
+        this.write({
+            t: "agent.activity",
+            at: toIso(ev.at),
+            run_id: ev.runId,
+            unit_id: ev.unitId,
+            step: ev.step,
+            attempt: ev.attempt,
+            session: ev.session,
+            runner: ev.runner,
+            model: ev.model,
+            turn: ev.turn,
+            line: ev.line,
+            tokens: ev.tokens,
+            ...(ev.kind ? { kind: ev.kind } : {}),
+            ...(ev.tool ? { tool: ev.tool } : {}),
+            ...(ev.target ? { target: ev.target } : {}),
+        });
+    }
+    /** in-memory mirror of every line written this process — lets the
+     * same-process post-run analyze step (P2) skip a re-read of the file. */
+    events() {
+        return this.log;
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,237 @@
+const DEFAULT_HIGH_TURN_COUNT = 50;
+const IMPLEMENT_STEPS = new Set(["implement"]);
+const REVIEW_STEPS = new Set(["review"]);
+export function parseActivityLog(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        out.push(JSON.parse(t));
+    }
+    return out;
+}
+function isAgentActivity(e) {
+    return e.t === "agent.activity";
+}
+function isStep(e) {
+    return e.t === "orchestrator.step";
+}
+function unitMetrics(unitId, steps, activity, costByUnit) {
+    const allTimestamps = [...steps.map((s) => s.at), ...activity.map((a) => a.at)].sort();
+    const wallMs = allTimestamps.length >= 2
+        ? Date.parse(allTimestamps[allTimestamps.length - 1]) - Date.parse(allTimestamps[0])
+        : 0;
+    const turnsTotal = activity.filter((a) => a.kind === "tool" || a.kind === "text").length;
+    const toolFailures = activity.filter((a) => a.kind === "tool-result").length;
+    const attempts = Math.max(0, ...steps.map((s) => s.attempt), ...activity.map((a) => a.attempt));
+    let agentMs = 0;
+    const agentSpanEvents = activity.filter((a) => IMPLEMENT_STEPS.has(a.step) || REVIEW_STEPS.has(a.step));
+    if (agentSpanEvents.length >= 2) {
+        const times = agentSpanEvents.map((a) => Date.parse(a.at)).sort((x, y) => x - y);
+        agentMs = times[times.length - 1] - times[0];
+    }
+    const orchestratorMs = Math.max(0, wallMs - agentMs);
+    const out = {
+        unitId,
+        turnsTotal,
+        toolFailures,
+        attempts,
+        wallMs,
+        orchestratorMs,
+        agentMs,
+        runner: activity[0]?.runner ?? "",
+        model: activity[0]?.model ?? "",
+    };
+    const cost = costByUnit?.get(unitId);
+    if (cost !== undefined)
+        out.costUsd = cost;
+    return out;
+}
+export function findRepeatedRead(unitEvents) {
+    const byAttempt = new Map();
+    for (const e of unitEvents) {
+        const list = byAttempt.get(e.attempt) ?? [];
+        list.push(e);
+        byAttempt.set(e.attempt, list);
+    }
+    const findings = [];
+    for (const events of byAttempt.values()) {
+        const byTarget = new Map();
+        for (const e of events) {
+            if (e.kind !== "tool" || e.tool !== "read" || !e.target)
+                continue;
+            const list = byTarget.get(e.target) ?? [];
+            list.push(e);
+            byTarget.set(e.target, list);
+        }
+        for (const [target, reads] of byTarget) {
+            if (reads.length < 3)
+                continue;
+            findings.push({
+                id: "repeated-read",
+                severity: "warn",
+                unitId: reads[0].unit_id,
+                message: `read "${target}" ${reads.length} times in one attempt — briefing/claim output may already answer this`,
+                evidence: reads.map((r) => ({ line: r.line, at: r.at })),
+            });
+        }
+    }
+    return findings;
+}
+export function findToolFailureCluster(unitEvents) {
+    const findings = [];
+    let cluster = [];
+    for (const e of unitEvents) {
+        if (e.kind === "tool-result") {
+            cluster.push(e);
+            continue;
+        }
+        if (e.kind === "tool" || e.kind === "text") {
+            if (cluster.length >= 3) {
+                findings.push({
+                    id: "tool-failure-cluster",
+                    severity: "warn",
+                    unitId: cluster[0].unit_id,
+                    message: `${cluster.length} tool failures before the next successful action — check environment/scope setup`,
+                    evidence: cluster.map((c) => ({ line: c.line, at: c.at })),
+                });
+            }
+            cluster = [];
+        }
+    }
+    if (cluster.length >= 3) {
+        findings.push({
+            id: "tool-failure-cluster",
+            severity: "warn",
+            unitId: cluster[0].unit_id,
+            message: `${cluster.length} tool failures with no successful action after them`,
+            evidence: cluster.map((c) => ({ line: c.line, at: c.at })),
+        });
+    }
+    return findings;
+}
+export function findHighTurnCount(unitEvents, threshold) {
+    const turns = unitEvents.filter((e) => e.kind === "tool" || e.kind === "text");
+    if (turns.length <= threshold)
+        return [];
+    return [
+        {
+            id: "high-turn-count",
+            severity: "action",
+            unitId: turns[0].unit_id,
+            message: `${turns.length} turns exceeds the ${threshold}-turn threshold — consider splitting the unit or narrowing scope`,
+            evidence: turns.slice(0, 5).map((t) => ({ line: t.line, at: t.at })),
+        },
+    ];
+}
+/** v0: conservative — the same evidence line repeated across the last failure
+ * of one attempt and the first failure of the next. Wiring real `retryFor`
+ * evidence (see captain-driven plan) is out of scope here. */
+export function findRetryWithoutDelta(unitEvents) {
+    const byAttempt = new Map();
+    for (const e of unitEvents) {
+        const list = byAttempt.get(e.attempt) ?? [];
+        list.push(e);
+        byAttempt.set(e.attempt, list);
+    }
+    const attempts = [...byAttempt.keys()].sort((a, b) => a - b);
+    const findings = [];
+    for (let i = 0; i + 1 < attempts.length; i++) {
+        const prevFailures = (byAttempt.get(attempts[i]) ?? []).filter((e) => e.kind === "tool-result");
+        const nextFailures = (byAttempt.get(attempts[i + 1]) ?? []).filter((e) => e.kind === "tool-result");
+        const lastPrev = prevFailures.at(-1);
+        const firstNext = nextFailures[0];
+        if (lastPrev && firstNext && lastPrev.line === firstNext.line) {
+            findings.push({
+                id: "retry-without-delta",
+                severity: "warn",
+                unitId: firstNext.unit_id,
+                message: `attempt ${attempts[i + 1]} reproduced the same failure as attempt ${attempts[i]} — retry evidence may not be reaching the briefing`,
+                evidence: [
+                    { line: lastPrev.line, at: lastPrev.at },
+                    { line: firstNext.line, at: firstNext.at },
+                ],
+            });
+        }
+    }
+    return findings;
+}
+export function findExploreBeforeEdit(unitEvents) {
+    const findings = [];
+    let sinceEditCount = 0;
+    const seen = [];
+    const EXPLORE_THRESHOLD = 15;
+    for (const e of unitEvents) {
+        if (e.kind !== "tool")
+            continue;
+        const isEdit = e.tool === "write" || e.tool === "edit";
+        if (isEdit) {
+            if (sinceEditCount > EXPLORE_THRESHOLD) {
+                findings.push({
+                    id: "explore-before-edit",
+                    severity: "info",
+                    unitId: e.unit_id,
+                    message: `${sinceEditCount} tool turns before the first edit — briefing/prompt may want tuning`,
+                    evidence: seen.slice(0, 5).map((s) => ({ line: s.line, at: s.at })),
+                });
+            }
+            return findings; // only the first edit per unit's events matters for this rule
+        }
+        sinceEditCount += 1;
+        seen.push(e);
+    }
+    return findings;
+}
+export function findVerifyHeavierThanImplement(unitEvents) {
+    const implementTurns = unitEvents.filter((e) => IMPLEMENT_STEPS.has(e.step) && (e.kind === "tool" || e.kind === "text")).length;
+    const reviewTurns = unitEvents.filter((e) => REVIEW_STEPS.has(e.step) && (e.kind === "tool" || e.kind === "text")).length;
+    if (reviewTurns <= implementTurns || reviewTurns === 0)
+        return [];
+    return [
+        {
+            id: "verify-heavier-than-implement",
+            severity: "info",
+            unitId: unitEvents[0].unit_id,
+            message: `review took ${reviewTurns} turns vs ${implementTurns} for implement — check verifier prompt or diff size`,
+            evidence: [],
+        },
+    ];
+}
+export function analyzeRun(events, opts) {
+    const now = opts.now ?? Date.now;
+    const runId = events.find((e) => e.t === "run.started")
+        ?.run_id ?? "";
+    const highTurnCount = opts.thresholds?.highTurnCount ?? DEFAULT_HIGH_TURN_COUNT;
+    const stepsByUnit = new Map();
+    const activityByUnit = new Map();
+    for (const e of events) {
+        if (isStep(e)) {
+            const list = stepsByUnit.get(e.unit_id) ?? [];
+            list.push(e);
+            stepsByUnit.set(e.unit_id, list);
+        }
+        else if (isAgentActivity(e)) {
+            const list = activityByUnit.get(e.unit_id) ?? [];
+            list.push(e);
+            activityByUnit.set(e.unit_id, list);
+        }
+    }
+    const unitIds = new Set([...stepsByUnit.keys(), ...activityByUnit.keys()]);
+    const units = [];
+    const findings = [];
+    for (const unitId of unitIds) {
+        const steps = stepsByUnit.get(unitId) ?? [];
+        const activity = activityByUnit.get(unitId) ?? [];
+        units.push(unitMetrics(unitId, steps, activity, opts.costByUnit));
+        findings.push(...findRepeatedRead(activity), ...findToolFailureCluster(activity), ...findHighTurnCount(activity, highTurnCount), ...findRetryWithoutDelta(activity), ...findExploreBeforeEdit(activity), ...findVerifyHeavierThanImplement(activity));
+    }
+    return {
+        runId,
+        generatedAt: new Date(now()).toISOString(),
+        units,
+        findings,
+        logRef: opts.logRef,
+    };
+}
+//# sourceMappingURL=index.js.map