@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

package/dist/workflows/dag/frontend-writer-status.js

@@ -0,0 +1,244 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+/**
+ * M4: fact-derived frontend writer status + bounded in-node micro-loop.
+ *
+ * `frontend-implement-pi` derives its implementation status from mechanical
+ * facts (write-tool events, run delta, cumulative diff, write guard, requirement
+ * coverage, focused-check failures) instead of parsing the
+ * `IMPLEMENTATION_OUTCOME:` first line. The legacy `implementation-outcome-v1`
+ * protocol (backend/README/module writers + `frontend-repair-pi`) is untouched.
+ *
+ * Everything here is either a pure function (deterministically testable) or an
+ * IO collector that is only reached through a dynamic import from the Pi
+ * executor, avoiding an executor↔workflows static cycle.
+ */
+/**
+ * Write/edit-style tool names emitted by DAG writer customTools. Kept in sync
+ * with the `SDK_WRITE_TOOL_NAMES` set in pi-sdk-executor.ts so the persisted
+ * session-event count and the in-memory writeToolCallCount agree.
+ */
+export const FRONTEND_WRITE_TOOL_NAMES = new Set([
+    "edit",
+    "write",
+    "str_replace_editor",
+]);
+/**
+ * AC-001/AC-003: derive the writer status from mechanical facts only. The
+ * first-line text is never consulted. Ordering:
+ *  1. write-guard violation → blocked
+ *  2. non-empty diff → changed (diff is the mechanical fact source)
+ *  3. empty diff + runtime already-satisfied evidence → already-satisfied
+ *  4. empty diff, zero writes, zero diff → blocked (no progress)
+ *  5. otherwise → empty-diff (fail-closed)
+ */
+export function deriveFrontendWriterStatus(facts) {
+    if (!facts.writeGuardOk) {
+        return {
+            status: "blocked",
+            reason: `write guard violations: ${facts.writeGuardViolations.join(", ") || "unknown"}`,
+        };
+    }
+    if (facts.changedFiles.length > 0) {
+        return {
+            status: "changed",
+            reason: `non-empty run-attributed diff (${facts.changedFiles.length} file${facts.changedFiles.length === 1 ? "" : "s"})`,
+        };
+    }
+    if (facts.alreadySatisfiedEvidence) {
+        return {
+            status: "already-satisfied",
+            reason: `empty diff with runtime already-satisfied evidence (${facts.alreadySatisfiedEvidence.requirementTargets.length} target${facts.alreadySatisfiedEvidence.requirementTargets.length === 1 ? "" : "s"})`,
+        };
+    }
+    if (facts.writeToolEvents === 0 && facts.changedFiles.length === 0) {
+        return {
+            status: "blocked",
+            reason: "zero write-tool events and zero diff: no implementation progress",
+        };
+    }
+    return {
+        status: "empty-diff",
+        reason: "empty diff without runtime already-satisfied evidence (fail-closed)",
+    };
+}
+/**
+ * Deterministic failure fingerprint over the normalized failure signature:
+ * category + focused-check failures (target + detail) + guard status. Used for
+ * repeated-failure deduplication inside the bounded micro-loop.
+ */
+export function computeFailureFingerprint(facts) {
+    const signature = normalizeFailureSignature(facts);
+    return createHash("sha256").update(signature).digest("hex");
+}
+function normalizeFailureSignature(facts) {
+    const parts = [];
+    if (!facts.writeGuardOk) {
+        parts.push("write-guard");
+    }
+    for (const failure of facts.focusedCheckFailures) {
+        parts.push(`${failure.category}:${failure.targetId ?? ""}:${failure.detail}`);
+    }
+    if (facts.changedFiles.length === 0 && facts.writeToolEvents === 0) {
+        parts.push("no-progress");
+    }
+    return parts.sort().join("\n");
+}
+export const DEFAULT_FRONTEND_MICRO_LOOP_BUDGET = {
+    maxFocusedCheckRounds: 3,
+    maxWriteAttempts: 5,
+    maxWallTimeMs: 15 * 60 * 1000,
+    maxTokens: 200_000,
+    maxRepeatedFingerprints: 2,
+};
+/**
+ * Pure micro-loop continuation gate. Deterministic: same budget + history +
+ * timestamps always yield the same decision. The caller (executor) drives the
+ * loop by re-checking this function after each focused-check round.
+ */
+export function evaluateMicroLoopContinuation(budget, history, startWallTimeMs, nowWallTimeMs) {
+    const rounds = history.length;
+    const last = history[rounds - 1];
+    if (last) {
+        const resolved = (last.status === "changed" &&
+            last.writeGuardOk &&
+            last.focusedCheckFailures.length === 0) ||
+            last.status === "already-satisfied" ||
+            last.status === "blocked";
+        if (resolved) {
+            return { continue: false, reason: "status-resolved" };
+        }
+        if (last.writeAttempts >= budget.maxWriteAttempts) {
+            return { continue: false, reason: "budget-write-attempts" };
+        }
+        if (last.tokensUsed >= budget.maxTokens) {
+            return { continue: false, reason: "budget-tokens" };
+        }
+        if (nowWallTimeMs - startWallTimeMs >= budget.maxWallTimeMs) {
+            return { continue: false, reason: "budget-wall-time" };
+        }
+        const repeatCount = history.filter((round) => round.fingerprint === last.fingerprint).length;
+        if (repeatCount >= budget.maxRepeatedFingerprints) {
+            return { continue: false, reason: "budget-repeated-fingerprint" };
+        }
+    }
+    if (rounds >= budget.maxFocusedCheckRounds) {
+        return { continue: false, reason: "budget-focused-check-rounds" };
+    }
+    return { continue: true };
+}
+/**
+ * Build a deterministic per-round checkpoint payload. Persistence stays with the
+ * caller (executor writes `runDir/<nodeId>/` only, never root `artifacts/**`).
+ */
+export function buildFrontendMicroLoopCheckpoint(input) {
+    return {
+        schemaVersion: 1,
+        nodeId: input.nodeId,
+        round: input.round,
+        status: deriveFrontendWriterStatus(input.facts).status,
+        fingerprint: computeFailureFingerprint(input.facts),
+        changedFiles: [...input.facts.changedFiles].sort(),
+        focusedCheckFailures: input.facts.focusedCheckFailures.map((failure) => ({
+            ...failure,
+        })),
+        writeGuardOk: input.facts.writeGuardOk,
+        recordedAt: input.recordedAt,
+        wallTimeMs: input.facts.wallTimeMs,
+        tokensUsed: input.facts.tokensUsed,
+        writeAttempts: input.facts.writeAttempts,
+    };
+}
+/**
+ * Shadow comparison between the fact-derived status and the legacy
+ * `IMPLEMENTATION_OUTCOME:` first-line parse. Never used to decide ok/fail —
+ * only persisted for the M4 shadow evaluation.
+ */
+export function compareFactStatusToLegacyOutcome(factStatus, legacyOutcome) {
+    const factVerdict = factStatus === "changed" || factStatus === "already-satisfied"
+        ? "ok"
+        : "fail";
+    const legacyVerdict = legacyOutcome === "changed" || legacyOutcome === "already-satisfied"
+        ? "ok"
+        : "fail";
+    return {
+        factStatus,
+        legacyOutcome,
+        factVerdict,
+        legacyVerdict,
+        match: factVerdict === legacyVerdict,
+    };
+}
+/**
+ * Pure session-event scanner: count write-tool events from the persisted
+ * session-events.jsonl content. Fail-closed: an unparseable line never counts
+ * as a write, so a corrupt/empty log cannot inflate progress.
+ */
+export function countWriteToolEventsFromSessionEvents(content) {
+    let count = 0;
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_WRITE_TOOL_NAMES.has(event.toolName)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * IO collector for frontend facts. Reads only the persisted session-events
+ * file; every other fact is passed in by the executor so this stays narrow and
+ * deterministic under test (tests inject session content by writing to a temp
+ * path or call the pure scanner directly).
+ */
+export async function collectFrontendWriterFacts(input) {
+    let writeToolEvents = 0;
+    try {
+        const content = await readFile(input.sessionEventsPath, "utf8");
+        writeToolEvents = countWriteToolEventsFromSessionEvents(content);
+    }
+    catch {
+        // Missing/unreadable session log → fail-closed at zero, never fail-open.
+        writeToolEvents = 0;
+    }
+    return {
+        changedFiles: [...input.changedFiles].sort(),
+        writeToolEvents,
+        writeGuardOk: input.writeGuard.ok,
+        writeGuardViolations: [...input.writeGuard.violations],
+        requirementTargets: [...new Set(input.requirementTargets)].sort(),
+        coveredRequirementIds: [...new Set(input.coveredRequirementIds)].sort(),
+        focusedCheckFailures: input.focusedCheckFailures.map((failure) => ({
+            ...failure,
+        })),
+        ...(input.alreadySatisfiedEvidence
+            ? {
+                alreadySatisfiedEvidence: {
+                    requirementTargets: [
+                        ...input.alreadySatisfiedEvidence.requirementTargets,
+                    ].sort(),
+                    proofSha256: input.alreadySatisfiedEvidence.proofSha256,
+                },
+            }
+            : {}),
+        tokensUsed: input.tokensUsed ?? 0,
+        wallTimeMs: input.wallTimeMs ?? 0,
+        rounds: input.rounds ?? 1,
+        writeAttempts: input.writeAttempts ?? 1,
+        ...(input.firstLineText !== undefined
+            ? { firstLineText: input.firstLineText }
+            : {}),
+    };
+}