@tea-agent/loop-agent 0.42.0-next.9 → 0.42.1

package/dist/workflows/dag/frontend-recovery-run.js

@@ -1,10 +1,13 @@
 import { copyFile, mkdir, readdir, readFile, rm, access } from "node:fs/promises";
 import path from "node:path";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { sha256Hex } from "./frontend-implementation-contract.js";
 import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, FRONTEND_RECOVERY_STAGING_PREFIX, computeFrontendRecoveryPlan, computeFrontendRecoveryPlanForSource, } from "./frontend-recovery-plan.js";
-import { dagRunDirExists, getDagRunDir, readDagRunSpec, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
+import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
 import { buildDagRunId } from "./runner.js";
+import { buildFrontendTopologyBinding } from "./frontend-shape.js";
+import { FRONTEND_SHAPE_BOUNDARIES, isCanonicalFrontendShapeDag, } from "./frontend-shape-facts.js";
 import { prepareRunDir, writeNodeRecord } from "./run-store.js";
 import { FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT, readFrontendWriterAdmissionResult, } from "./scheduler.js";
 import { topoSortToRanks } from "./topo.js";
@@ -273,34 +276,52 @@ async function casUpdateFrontendRecoveryState(parentRunDir, expectedRevision, de
     await deps.writeParentState(parentRunDir, state);
 }
 async function materializeChildStaging(input) {
-    const { cwd, parentRunDir, parentRunId, parentSpec, parentState, recovery, requestId, childRunId, stagingDir, createdAt, } = input;
+    const { cwd, parentRunDir, parentRunId, parentSpec, parentState, recovery, recoveryPlan, requestId, childRunId, stagingDir, createdAt, } = input;
     await prepareRunDir(stagingDir);
     // Design-review rejection must be visible to the reset planner. Recovery
     // children otherwise copy the old spec and only rerun design review, which
     // deterministically re-rejects the unchanged plan. Bind the parent's typed
     // findings into the child spec as ordinary rerun feedback.
     let childSpec = parentSpec;
-    if (recovery.failureSource === "frontend-plan-pi") {
+    if (recovery.failureSource === "frontend-plan-pi" ||
+        recovery.failureSource === "frontend-review-pi") {
+        const designRecovery = parentState.terminalReason === "design-request-changes";
+        const reviewRecovery = recovery.failureSource === "frontend-review-pi" ||
+            parentState.terminalReason === "review-request-changes";
+        let feedback;
         try {
             const { deriveDagRerunFeedback } = await import("./rerun-feedback.js");
             const taskId = parentSpec.taskContractBinding?.taskId ??
                 parentSpec.sourceBinding?.taskId ??
                 parentRunId;
-            const feedback = await deriveDagRerunFeedback({
+            feedback = await deriveDagRerunFeedback({
                 parentRunId,
                 taskId,
                 runDir: parentRunDir,
                 spec: parentSpec,
                 state: parentState,
             });
-            if (feedback)
-                childSpec = { ...parentSpec, rerunFeedback: feedback };
+            if (reviewRecovery &&
+                feedback &&
+                feedback.sourceNodeId !== "frontend-review-pi") {
+                // Do not accidentally carry an older design/verify finding when a
+                // review-triggered continuation has lost its typed review fact.
+                feedback = undefined;
+            }
         }
         catch (error) {
-            // A design rejection cannot be safely retried without its typed
+            if (designRecovery || reviewRecovery) {
+                throw new Error(`frontend recovery feedback unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (feedback) {
+            childSpec = { ...parentSpec, rerunFeedback: feedback };
+        }
+        else if (designRecovery || reviewRecovery) {
+            // A design/review rejection cannot be safely retried without its typed
             // findings. Fail closed instead of deterministically re-running the
             // unchanged plan and producing another rejection.
-            throw new Error(`frontend recovery feedback unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`frontend recovery feedback unavailable: no typed ${reviewRecovery ? "review" : "design"} findings were found for recovery`);
         }
     }
     await writeJsonVerified(stagingDir, "run.json", childSpec);
@@ -308,7 +329,10 @@ async function materializeChildStaging(input) {
     // (frontend-implement-pi) instead of the candidate producer; everything
     // upstream is imported as verified parent facts.
     let plan;
-    if (recovery.failureSource) {
+    if (recoveryPlan) {
+        plan = recoveryPlan;
+    }
+    else if (recovery.failureSource) {
         plan = computeFrontendRecoveryPlanForSource({
             spec: parentSpec,
             parentRunId,
@@ -373,7 +397,25 @@ async function materializeChildStaging(input) {
         newRunDir: stagingDir,
         relativePath: FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT,
     });
+    // The scheduler gates every shape boundary by its committed fact once the
+    // boundary's source node is FINISHED. Imported nodes stay FINISHED in the
+    // child, so their boundaries must inherit the parent's committed facts or
+    // the child hard-blocks at the first gated rank. Reset boundaries re-commit
+    // their own facts when their source nodes re-run.
+    const inheritedCommittedFacts = {};
+    if (isCanonicalFrontendShapeDag(new Map(childSpec.tasks.map((task) => [task.id, task])))) {
+        for (const entry of FRONTEND_SHAPE_BOUNDARIES) {
+            if (!importedSet.has(entry.sourceNodeId))
+                continue;
+            const parentFact = parentState.frontendShapeState?.committedFacts[entry.boundary];
+            if (parentFact) {
+                inheritedCommittedFacts[entry.boundary] = structuredClone(parentFact);
+            }
+        }
+    }
     const childState = {
+        ...(parentState.budget ? { budget: structuredClone(parentState.budget) } : {}),
+        ...(parentState.budgetLedger ? { budgetLedger: structuredClone(parentState.budgetLedger) } : {}),
         version: 1,
         title: parentSpec.title,
         runId: childRunId,
@@ -382,7 +424,20 @@ async function materializeChildStaging(input) {
         status: "pending",
         ranks,
         nodes,
+        // Mirror createInitialRunState: a canonical frontend child must carry its
+        // own frozen topology binding or executeDag's binding assert rejects the
+        // staged child before its first node runs.
+        ...(isCanonicalFrontendShapeDag(new Map(childSpec.tasks.map((task) => [task.id, task])))
+            ? {
+                frontendShapeState: {
+                    frozenTopology: buildFrontendTopologyBinding(childSpec.tasks.map((task) => task.id)),
+                    revision: 0,
+                    committedFacts: inheritedCommittedFacts,
+                },
+            }
+            : {}),
         frontendRecoveryState: {
+            ...(parentState.budgetLedger ? { budgetLineage: { parentLedgerSha256: sha256OfCanonicalJson(parentState.budgetLedger), inheritedAt: createdAt, inheritedConsumed: structuredClone(parentState.budgetLedger.consumed) } } : {}),
             schemaVersion: 1,
             phase: "child-running",
             requestId,
@@ -390,8 +445,11 @@ async function materializeChildStaging(input) {
             parentRunId,
             childRunId,
             attemptId: recovery.attemptId,
-            attemptIndex: 1,
-            continuationCount: 1,
+            attemptIndex: recovery.attemptIndex + 1,
+            continuationCount: recovery.continuationCount + 1,
+            ...(recovery.failureSource
+                ? { failureSource: recovery.failureSource }
+                : {}),
             revision: 0,
         },
         ...(parentState.evaluation
@@ -460,7 +518,41 @@ export async function stageRecoveryChild(options) {
     const parentRunDir = getDagRunDir(cwd, "active", parentRunId);
     const parentState = await deps.readParentState(parentRunDir);
     const parentSpec = await readDagRunSpec(parentRunDir);
-    const recovery = parentState.frontendRecoveryState;
+    let recovery = parentState.frontendRecoveryState;
+    if (options.recoveryIntent) {
+        const intent = options.recoveryIntent;
+        if (intent.parentRunId !== parentRunId ||
+            intent.requestId.length === 0 ||
+            intent.phase !== "child-staging" ||
+            intent.childRunId !== undefined ||
+            intent.revision !== 0) {
+            throw new Error("frontend recovery intent binding mismatch");
+        }
+        if (recovery?.requestId === intent.requestId) {
+            if (recovery.parentRunId !== intent.parentRunId ||
+                recovery.recoveryRootRunId !== intent.recoveryRootRunId ||
+                recovery.attemptIndex !== intent.attemptIndex ||
+                recovery.continuationCount !== intent.continuationCount ||
+                recovery.failureSource !== intent.failureSource) {
+                throw new Error("frontend recovery intent replay binding mismatch");
+            }
+        }
+        else {
+            const previousAttemptIndex = recovery?.attemptIndex ?? 0;
+            const previousContinuationCount = recovery?.continuationCount ?? 0;
+            const expectedRoot = recovery?.recoveryRootRunId ?? parentRunId;
+            if (intent.recoveryRootRunId !== expectedRoot ||
+                intent.attemptIndex !== previousAttemptIndex ||
+                intent.continuationCount !== previousContinuationCount) {
+                throw new Error("frontend recovery intent lineage mismatch");
+            }
+            recovery = structuredClone(intent);
+            await deps.writeParentState(parentRunDir, {
+                ...parentState,
+                frontendRecoveryState: recovery,
+            });
+        }
+    }
     if (!recovery) {
         throw new Error(`parent run ${parentRunId} has no frontend recovery intent`);
     }
@@ -468,17 +560,49 @@ export async function stageRecoveryChild(options) {
     if (!requestId) {
         throw new Error(`parent run ${parentRunId} recovery intent has no requestId`);
     }
+    if (options.recoveryPlan) {
+        if (options.recoveryPlan.parentRunId !== parentRunId ||
+            options.recoveryPlan.requestId !== requestId ||
+            options.recoveryPlan.failureSource !== recovery.failureSource) {
+            throw new Error("frontend recovery plan binding mismatch");
+        }
+        const expectedPlan = computeFrontendRecoveryPlanForSource({
+            spec: parentSpec,
+            parentRunId,
+            requestId,
+            failureSource: recovery.failureSource,
+        });
+        if (JSON.stringify(expectedPlan.resetNodeIds) !==
+            JSON.stringify(options.recoveryPlan.resetNodeIds) ||
+            JSON.stringify(expectedPlan.importedNodeIds) !==
+                JSON.stringify(options.recoveryPlan.importedNodeIds)) {
+            throw new Error("frontend recovery plan drifted from parent DAG");
+        }
+    }
     // Idempotent short-circuit (D4.2): reserved childRunId + activated marker +
     // existing child dir means the request was already fully committed.
     if (recovery.childRunId) {
         const existingMarker = await readFrontendRecoveryMarker(parentRunDir, requestId);
         if (existingMarker) {
-            const existingChildDir = getDagRunDir(cwd, "active", existingMarker.childRunId);
-            if (await dagRunDirExists(existingChildDir)) {
+            const existingChild = await locateDagRun(cwd, existingMarker.childRunId);
+            if (existingChild &&
+                (existingChild.lifecycle === "active" ||
+                    existingChild.lifecycle === "paused" ||
+                    existingChild.lifecycle === "completed")) {
+                await verifyThreeWayConsistency({
+                    parentRunDir,
+                    activeChildDir: existingChild.runDir,
+                    marker: existingMarker,
+                    parentRunId,
+                    requestId,
+                    recoveryRootRunId: recovery.recoveryRootRunId,
+                    childRunId: existingMarker.childRunId,
+                    deps,
+                });
                 return {
                     ok: true,
                     childRunId: existingMarker.childRunId,
-                    childRunDir: existingChildDir,
+                    childRunDir: existingChild.runDir,
                     marker: existingMarker,
                     idempotentReplay: true,
                 };
@@ -489,8 +613,13 @@ export async function stageRecoveryChild(options) {
     // buildDagRunId is deterministic for the same task title on the same day. A
     // recovery child must never reuse its still-active parent directory, or the
     // staging path aliases the parent and the required import manifest is absent.
+    // The default builder must receive `{ cwd }` (its options object), not the
+    // bare string: only the options form enables the collision-safe `-rN`
+    // suffix across active/completed/paused runs.
     const childRunId = recovery.childRunId ?? await (async () => {
-        const generatedChildRunId = await (options.buildChildRunId ?? buildDagRunId)(parentSpec, cwd);
+        const generatedChildRunId = options.buildChildRunId
+            ? await options.buildChildRunId(parentSpec, cwd)
+            : await buildDagRunId(parentSpec, { cwd });
         return generatedChildRunId === parentRunId
             ? `${generatedChildRunId}-recovery-${requestId.slice(0, 8)}`
             : generatedChildRunId;
@@ -528,6 +657,7 @@ export async function stageRecoveryChild(options) {
             parentSpec,
             parentState,
             recovery,
+            recoveryPlan: options.recoveryPlan,
             requestId,
             childRunId,
             stagingDir,

package/dist/workflows/dag/frontend-review-scopes.js

@@ -0,0 +1,139 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, realpath, lstat } from "node:fs/promises";
+import path from "node:path";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+import { readCommittedEvents } from "./frontend-typed-event-store.js";
+import { stageTypedEventFact, adoptTypedEventFact } from "./frontend-typed-event-transaction.js";
+const invalidScope = (message) => Object.assign(new Error(`FRONTEND_REVIEW_SCOPE_INVALID: ${message}`), { code: "FRONTEND_REVIEW_SCOPE_INVALID" });
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isArtifactReference = (value) => isRecord(value)
+    && typeof value.path === "string" && value.path.length > 0
+    && typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256);
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+/** The section index is navigation; reconstruct coverage against the canonical source before using it. */
+export async function loadFrontendReviewScopes(runDir, phase, targetBytes) {
+    const root = await realpath(runDir);
+    const files = new Map();
+    async function read(relative, expected) {
+        const absolute = path.resolve(root, relative);
+        if (!absolute.startsWith(root + path.sep) || (await lstat(absolute)).isSymbolicLink() || !(await realpath(absolute)).startsWith(root + path.sep))
+            throw invalidScope("artifact escaped run");
+        const text = await readFile(absolute, "utf8");
+        const sha256 = hash(text);
+        if (expected && sha256 !== expected)
+            throw Error(`FRONTEND_REVIEW_SCOPE_DRIFT: ${relative}`);
+        files.set(relative, sha256);
+        return { id: relative, text, sha256 };
+    }
+    let indexArtifact;
+    try {
+        indexArtifact = await read("contracts/frontend-implementation-contract.index.json");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const index = JSON.parse(indexArtifact.text);
+    if (!isRecord(index) || !isArtifactReference(index.contract) || !Array.isArray(index.sections))
+        throw invalidScope("malformed contract index");
+    const canonicalArtifact = await read(index.contract.path, index.contract.sha256);
+    const canonical = JSON.parse(canonicalArtifact.text);
+    if (!isRecord(canonical))
+        throw invalidScope("canonical contract must be an object");
+    const covered = new Map();
+    const sections = [];
+    const ids = new Set();
+    for (const entry of index.sections) {
+        if (!isRecord(entry) || !isArtifactReference(entry) || !Array.isArray(entry.slices))
+            throw invalidScope("malformed section index entry");
+        if (ids.has(entry.path))
+            throw invalidScope("duplicate section identity");
+        ids.add(entry.path);
+        const section = await read(entry.path, entry.sha256);
+        const payload = JSON.parse(section.text);
+        if (!isRecord(payload) || !Array.isArray(payload.slices) || !isRecord(payload.data))
+            throw invalidScope(`malformed section: ${entry.path}`);
+        if (payload.contractSha256 !== canonicalArtifact.sha256 || sha256OfCanonicalJson(payload.slices) !== sha256OfCanonicalJson(entry.slices))
+            throw invalidScope("unbound section");
+        for (const slice of payload.slices) {
+            if (!isRecord(slice) || typeof slice.field !== "string" || !Object.hasOwn(canonical, slice.field) || !Object.hasOwn(payload.data, slice.field))
+                throw invalidScope(`missing or invalid field reference in ${entry.path}: ${String(slice?.field)}`);
+            const value = canonical[slice.field];
+            const positions = covered.get(slice.field) ?? new Set();
+            if (Array.isArray(value)) {
+                if (!Number.isInteger(slice.start) || !Number.isInteger(slice.end) || slice.start < 0 || slice.end < slice.start || slice.end > value.length || slice.total !== value.length)
+                    throw invalidScope("invalid array coverage");
+                if ((value.length === 0 && covered.has(slice.field)) || (value.length > 0 && slice.start === slice.end))
+                    throw invalidScope(`empty or duplicate array coverage: ${slice.field}`);
+                for (let i = slice.start; i < slice.end; i++) {
+                    if (positions.has(i))
+                        throw invalidScope("overlapping coverage");
+                    positions.add(i);
+                }
+            }
+            else {
+                if (["start", "end", "total"].some(key => Object.hasOwn(slice, key)))
+                    throw invalidScope(`scalar field has array range: ${slice.field}`);
+                if (positions.size)
+                    throw invalidScope("duplicate field");
+                positions.add(0);
+            }
+            const range = Array.isArray(value) ? value.slice(slice.start, slice.end) : value;
+            if (sha256OfCanonicalJson(range) !== sha256OfCanonicalJson(payload.data[slice.field]))
+                throw invalidScope(`section differs from canonical obligation: ${slice.field}`);
+            covered.set(slice.field, positions);
+        }
+        const sectionFields = new Set(payload.slices.map(slice => slice.field));
+        if (Object.keys(payload.data).some(field => !sectionFields.has(field)))
+            throw invalidScope(`unindexed section data: ${entry.path}`);
+        sections.push(section);
+    }
+    if (Object.keys(canonical).some(field => !covered.has(field) || covered.get(field).size !== (Array.isArray(canonical[field]) ? canonical[field].length : 1)))
+        throw invalidScope("canonical field coverage incomplete");
+    const scopes = Buffer.byteLength(canonicalArtifact.text) <= targetBytes ? [canonicalArtifact] : sections;
+    if (phase === "review") {
+        const context = await read("contracts/frontend-review-context.json");
+        const payload = JSON.parse(context.text);
+        if (payload.contractRef.sha256 !== canonicalArtifact.sha256 || payload.contractRef.indexSha256 !== indexArtifact.sha256)
+            throw Error("FRONTEND_REVIEW_SCOPE_DRIFT: review context contract binding");
+        const diff = await read(payload.diff.reviewIndexPath);
+        const diffIndex = JSON.parse(diff.text);
+        await read(payload.diff.patchPath, payload.diff.patchSha256);
+        if (diffIndex.patchSha256 !== payload.diff.patchSha256)
+            throw Error("FRONTEND_REVIEW_SCOPE_DRIFT: review diff binding");
+        scopes.push(context);
+        for (const hunk of diffIndex.hunks)
+            scopes.push(await read(hunk.patchPath, hunk.sha256));
+    }
+    return { scopes, digest: sha256OfCanonicalJson([...files]), validate: async () => { for (const [relative, expected] of files)
+            await read(relative, expected); } };
+}
+/** Checkpoints attest explicit model completion of already supplied, hash-bound scopes. */
+export function createFrontendReviewScopeProtocol(input) {
+    const kind = input.phase === "design" ? "design-scope-completed" : "review-scope-completed";
+    let active = new Set();
+    const completedScopeIds = () => new Set(readCommittedEvents(input.getStore(), input.attemptId).filter(r => r.fact.kind === kind).map(r => String(r.fact.id)));
+    const receipt = (details) => ({ content: [{ type: "text", text: JSON.stringify(details) }], details });
+    return {
+        setActiveScope(ids) { active = new Set(ids); },
+        completedScopeIds,
+        committedFacts: () => readCommittedEvents(input.getStore(), input.attemptId),
+        assertComplete() { const missing = input.inventory?.scopes.filter(s => !completedScopeIds().has(s.id)) ?? []; if (missing.length)
+            throw Object.assign(Error(`FRONTEND_REVIEW_SCOPE_INCOMPLETE: ${missing.map(s => s.id).join(", ")}`), { code: "FRONTEND_REVIEW_SCOPE_INCOMPLETE" }); },
+        customTools: !input.inventory ? [] : [{ name: "complete_review_scope", label: "complete_review_scope", description: "After reviewing the supplied complete scope and saving its findings, checkpoint its exact runtime id. This does not approve the implementation or design.", parameters: { type: "object", properties: { id: { type: "string", minLength: 1 } }, required: ["id"], additionalProperties: false },
+                async execute(callId, params) {
+                    const scope = input.inventory.scopes.find(s => s.id === params.id);
+                    if (!scope || !active.has(params.id))
+                        return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "Only the supplied active review scope may be completed" });
+                    await input.inventory.validate();
+                    const store = input.getStore();
+                    const requestId = `${input.attemptId}:${callId}:${randomUUID()}`;
+                    const fact = { kind, id: scope.id, sha256: scope.sha256 };
+                    const staged = stageTypedEventFact({ store, requestId, attemptId: input.attemptId, fact });
+                    const committed = await adoptTypedEventFact({ store, requestId, attemptId: input.attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
+                    return receipt({ ok: true, kind, revision: committed.revision });
+                },
+            }],
+    };
+}

package/dist/workflows/dag/frontend-risk.js

@@ -70,8 +70,10 @@ function blobOf(input) {
     ].join("\n");
 }
 function pathSpreadScore(paths) {
+    const auxiliaryRoot = /^(?:test|tests|__tests__|e2e|cypress|spec|specs|docs|documentation)$/i;
     const tops = new Set(paths
         .map((p) => p.replace(/\\/g, "/").split("/").filter(Boolean)[0] ?? "")
+        .filter((root) => !auxiliaryRoot.test(root))
         .filter(Boolean));
     return tops.size;
 }