@tea-agent/loop-agent 0.35.2 → 0.35.3

package/dist/workflows/dag/scheduler.js

@@ -1,5 +1,10 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import { isPauseOnHumanDecisionGate } from "./decision-envelope.js";
 import { evaluateConditionExpression } from "./dynamic-runtime/condition.js";
+import { sha256Hex } from "./frontend-implementation-contract.js";
+import { frontendPrewriteResultV1Schema, FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME, } from "./frontend-prewrite-gate.js";
+import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, } from "./frontend-recovery-plan.js";
 export function isConditionSkippedReason(reason) {
     return Boolean(reason?.startsWith("condition "));
 }
@@ -104,6 +109,58 @@ async function mapConcurrent(items, limit, fn) {
     }
     await Promise.all(executing);
 }
+export const FRONTEND_WRITER_NODE_IDS = [
+    "frontend-implement-pi",
+    "frontend-repair-pi",
+];
+/** Run-relative artifact location written by the prewrite gate generator. */
+export const FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT = path.posix.join("contracts", FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME);
+/**
+ * Read and validate the frontend-prewrite-result-v1 artifact. Fail-closed:
+ * a missing file or invalid payload returns ok:false and never throws.
+ */
+export async function readFrontendPrewriteResult(runDir) {
+    const artifactPath = path.join(runDir, "contracts", FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME);
+    let raw;
+    try {
+        raw = await readFile(artifactPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                ok: false,
+                reason: `frontend prewrite result artifact missing: ${artifactPath}`,
+            };
+        }
+        throw error;
+    }
+    const artifactHash = sha256Hex(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `frontend prewrite result artifact is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const result = frontendPrewriteResultV1Schema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            ok: false,
+            reason: "frontend prewrite result artifact failed schema validation",
+        };
+    }
+    return { ok: true, result: result.data, artifactHash };
+}
+/** Authorize only accepted / accepted-normalized classifications. */
+export function isFrontendWriterAuthorized(result) {
+    return result.classification === "accepted" ||
+        result.classification === "accepted-normalized"
+        ? "authorized"
+        : "denied";
+}
 /** Fail-closed: leave no PENDING nodes that look "still scheduled" after abort. */
 export function markPendingNodesControllerInterrupted(state, reason = "run aborted by controller (abortSignal)") {
     const affected = [];
@@ -122,8 +179,166 @@ export function markPendingNodesControllerInterrupted(state, reason = "run abort
     }
     return affected;
 }
+/**
+ * True when this run is a candidate-continuation child: it has a recovery
+ * lineage whose attemptIndex is >= 1 and whose recovery root is another run.
+ * The root/parent keeps `recoveryRootRunId === state.runId`.
+ */
+export function isFrontendRecoveryChild(state) {
+    const recovery = state.frontendRecoveryState;
+    return Boolean(recovery &&
+        recovery.attemptIndex >= 1 &&
+        recovery.recoveryRootRunId !== state.runId);
+}
+function isValidFrontendRecoveryActivationMarker(raw) {
+    return (raw.schemaVersion === 1 &&
+        typeof raw.requestId === "string" &&
+        raw.requestId.length > 0 &&
+        typeof raw.parentRunId === "string" &&
+        raw.parentRunId.length > 0 &&
+        typeof raw.recoveryRootRunId === "string" &&
+        raw.recoveryRootRunId.length > 0 &&
+        typeof raw.childRunId === "string" &&
+        raw.childRunId.length > 0 &&
+        typeof raw.importManifestSha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(raw.importManifestSha256));
+}
+/**
+ * Activation marker gate (phase 3c AC-1). Fail-closed: an active child is only
+ * executable when its parent is `child-running`, points at this child, carries
+ * a structurally valid activation marker whose lineage matches, and the marker
+ * hash matches the child's import manifest. Read-only and never throws.
+ */
+export async function checkFrontendRecoveryActivation(state, childRunDir) {
+    if (!isFrontendRecoveryChild(state)) {
+        return { applicable: false };
+    }
+    const recovery = state.frontendRecoveryState;
+    const parentRunId = recovery.parentRunId;
+    const parentRunDir = path.join(path.dirname(childRunDir), parentRunId);
+    let parentState;
+    try {
+        parentState = JSON.parse(await readFile(path.join(parentRunDir, "state.json"), "utf8"));
+    }
+    catch {
+        return { applicable: true, ok: false, reason: "parent state unreadable" };
+    }
+    const parentRecovery = parentState.frontendRecoveryState;
+    if (parentRecovery?.phase !== "child-running") {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "parent phase not child-running",
+        };
+    }
+    if (parentRecovery.childRunId !== state.runId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "parent childRunId mismatch",
+        };
+    }
+    const markerPath = path.join(parentRunDir, FRONTEND_RECOVERY_INTENT_REL_DIR, `${recovery.requestId}.json`);
+    let markerRaw;
+    try {
+        markerRaw = JSON.parse(await readFile(markerPath, "utf8"));
+    }
+    catch {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "activation marker missing",
+        };
+    }
+    if (typeof markerRaw !== "object" ||
+        markerRaw === null ||
+        !isValidFrontendRecoveryActivationMarker(markerRaw)) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "activation marker invalid",
+        };
+    }
+    const marker = markerRaw;
+    if (marker.requestId !== recovery.requestId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker requestId mismatch",
+        };
+    }
+    if (marker.parentRunId !== parentRunId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker parentRunId mismatch",
+        };
+    }
+    if (marker.recoveryRootRunId !== recovery.recoveryRootRunId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker recoveryRootRunId mismatch",
+        };
+    }
+    if (marker.childRunId !== state.runId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker childRunId mismatch",
+        };
+    }
+    let manifestSha256;
+    try {
+        manifestSha256 = sha256Hex(await readFile(path.join(childRunDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH), "utf8"));
+    }
+    catch {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "import manifest unreadable",
+        };
+    }
+    if (manifestSha256 !== marker.importManifestSha256) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "import manifest sha256 mismatch",
+        };
+    }
+    return {
+        applicable: true,
+        ok: true,
+        requestId: recovery.requestId,
+        childRunId: state.runId,
+    };
+}
 export async function executeDagRanksOnce(input) {
     let pausedByNodeId;
+    // Activation marker gate (phase 3c AC-1): a recovery child without a valid
+    // activation marker must never be scheduled or executed. Fail-closed before
+    // any executeScheduledNode call, so zero writer/provider invocations happen.
+    if (input.runDir) {
+        const hasPending = Object.values(input.state.nodes).some((node) => node.status === "PENDING");
+        if (hasPending) {
+            const activation = await checkFrontendRecoveryActivation(input.state, input.runDir);
+            if (activation.applicable && !activation.ok) {
+                const finishedAt = new Date().toISOString();
+                let affected = 0;
+                for (const node of Object.values(input.state.nodes)) {
+                    if (node.status !== "PENDING")
+                        continue;
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-recovery-child-not-activated";
+                    node.finishedAt = finishedAt;
+                    affected += 1;
+                }
+                if (affected > 0)
+                    await input.persistState();
+                return undefined;
+            }
+        }
+    }
     for (const rank of input.ranks) {
         if (input.abortSignal?.aborted) {
             const marked = markPendingNodesControllerInterrupted(input.state, input.abortSignal.reason
@@ -168,6 +383,45 @@ export async function executeDagRanksOnce(input) {
             await input.persistState();
         const conditionSkippedSet = new Set(conditionSettled);
         const actuallyRunnable = runnable.filter((id) => !conditionSkippedSet.has(id));
+        const frontendAdmissionSettled = [];
+        if (input.runDir) {
+            for (const id of actuallyRunnable) {
+                if (!FRONTEND_WRITER_NODE_IDS.includes(id))
+                    continue;
+                const node = input.state.nodes[id];
+                const checkedAt = new Date().toISOString();
+                const admission = await readFrontendPrewriteResult(input.runDir);
+                if (!admission.ok) {
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-prewrite-not-authorized";
+                    node.finishedAt = checkedAt;
+                    frontendAdmissionSettled.push(id);
+                    continue;
+                }
+                const decision = isFrontendWriterAuthorized(admission.result);
+                node.frontendWriterAdmission = {
+                    schemaVersion: 1,
+                    writerNodeId: id,
+                    decision,
+                    sourceArtifact: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+                    artifactHash: admission.artifactHash,
+                    checkedAt,
+                    reason: decision === "denied"
+                        ? `classification: ${admission.result.classification}`
+                        : null,
+                };
+                if (decision === "denied") {
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-prewrite-not-authorized";
+                    node.finishedAt = checkedAt;
+                    frontendAdmissionSettled.push(id);
+                }
+            }
+            if (frontendAdmissionSettled.length > 0)
+                await input.persistState();
+        }
+        const frontendAdmissionSkippedSet = new Set(frontendAdmissionSettled);
+        const runnableAfterAdmission = actuallyRunnable.filter((id) => !frontendAdmissionSkippedSet.has(id));
         const blocked = pending.filter((id) => {
             const task = input.tasksById.get(id);
             return (dependencyReadiness(task, input.state.nodes, input.tasksById) === "skip");
@@ -182,12 +436,12 @@ export async function executeDagRanksOnce(input) {
         if (blocked.length > 0) {
             await input.persistState();
         }
-        const pauseGateRunnable = actuallyRunnable.filter((id) => {
+        const pauseGateRunnable = runnableAfterAdmission.filter((id) => {
             const task = input.tasksById.get(id);
             return isPauseOnHumanDecisionGate(task);
         });
-        const regularRunnable = actuallyRunnable.filter((id) => !pauseGateRunnable.includes(id));
-        const rankWriterNodeIds = actuallyRunnable.filter((id) => {
+        const regularRunnable = runnableAfterAdmission.filter((id) => !pauseGateRunnable.includes(id));
+        const rankWriterNodeIds = runnableAfterAdmission.filter((id) => {
             const task = input.tasksById.get(id);
             return (task?.executor === "pi" &&
                 task.toolProfile === "write" &&

package/dist/workflows/dag/types.js

@@ -654,8 +654,15 @@ export const dagConvergenceSpecSchema = z
     chainNodeIds: z.array(z.string()).optional(),
 })
     .optional();
-export const dagTaskSchema = z.object({
-    id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
+/**
+ * Schema ids that may opt a node into producing-node structured contract
+ * self-validation. Validators are registered in the contract output registry
+ * (src/workflows/dag/contract-output-registry.ts).
+ */
+export const structuredContractOutputSchemaIds = [
+    "frontend-implementation-contract-v1",
+];
+export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
     depends_on: z.array(z.string()).default([]),
     /**
      * How SKIPPED upstreams affect readiness.
@@ -704,6 +711,20 @@ export const dagTaskSchema = z.object({
      * on safe read-only Pi nodes before the node becomes ERROR.
      */
     outputProtocol: dagOutputProtocolSchema.optional(),
+    /**
+     * Node-level structured contract self-check: after the Pi output is
+     * produced, validate it against the named contract schema at the node so
+     * schema/typo/null violations become invalid-output (retryable on the node)
+     * instead of failing later at a downstream deterministic gate. Validators
+     * are resolved via the contract output registry keyed by schemaId.
+     */
+    structuredContractOutput: z
+        .object({
+        schemaId: z.enum(structuredContractOutputSchemaIds),
+        retryOnInvalid: z.boolean().default(true),
+    })
+        .strict()
+        .optional(),
     /**
      * Fail-closed outcome/diff consistency contract for bounded Pi writers.
      * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
@@ -874,6 +895,113 @@ export const dagSpecSchema = z
         });
     }
 });
+export const FRONTEND_RECOVERY_STATE_SCHEMA_VERSION = 1;
+export const FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION = 1;
+/**
+ * Frontend candidate-continuation recovery phase (decision B, phase-3 subset).
+ * Phase 3a parents converge first, so `rollback-pending` is not produced and
+ * was removed by AC-1; the phase starts at `child-staging` and ends at
+ * `settled`.
+ */
+export const frontendRecoveryPhaseSchema = z.enum([
+    "child-staging",
+    "child-activating",
+    "child-running",
+    "settled",
+]);
+/**
+ * Single-writer recovery intent/lineage stored on `DagRunState`. The parent run
+ * owns the authoritative copy and advances it via revision-guarded CAS writes;
+ * the child carries a frozen lineage snapshot so the activation gate can prove
+ * it is the reserved child of a child-running parent.
+ *
+ * Invariants: `attemptIndex ∈ {0,1}`; `continuationCount ∈ {0,1}`; a child's
+ * `recoveryRootRunId` always equals the root runId; `revision` is the CAS
+ * pre-comparison counter. `revision` monotonicity is enforced at runtime by the
+ * runner's `(existing?.revision ?? 0) + 1` CAS write (the schema only bounds it
+ * non-negative). `childRunId` may be absent through `child-activating` and must
+ * be non-empty from `child-running` onward.
+ */
+export const frontendRecoveryStateSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_STATE_SCHEMA_VERSION),
+    phase: frontendRecoveryPhaseSchema,
+    requestId: z.string().min(1),
+    recoveryRootRunId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    attemptId: z.string().min(1),
+    attemptIndex: z.number().int().min(0).max(1),
+    continuationCount: z.number().int().min(0).max(1),
+    /** Node id of the reset-closure root: frontend-plan-pi /
+     *  frontend-plan-revision-pi / frontend-prewrite-gate-shell /
+     *  frontend-implement-pi (writer partial write). */
+    failureSource: z.string().min(1).optional(),
+    revision: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const requiresChild = value.phase === "child-running" || value.phase === "settled";
+    if (requiresChild && !value.childRunId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `phase ${value.phase} requires a non-empty childRunId`,
+            path: ["childRunId"],
+        });
+    }
+});
+export const frontendRecoveryOutcomeSchema = z.enum([
+    "none",
+    "recovered",
+    "candidate-contract-invalid",
+    "prewrite-blocked",
+    "repair-exhausted",
+    "auto-recovery-blocked",
+]);
+export const frontendRecoveryOriginSchema = z
+    .object({
+    kind: z.enum(["frontend-prewrite-gate", "frontend-writer"]),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    requestId: z.string().min(1),
+    failedNodeId: z.string(),
+})
+    .strict();
+export const frontendRecoveryFailureClassSchema = z
+    .object({
+    code: z.enum([
+        "candidate-contract-invalid",
+        "prewrite-blocked",
+        "staging-failed",
+        "writer-transient-partial-write",
+    ]),
+    classification: z.string(),
+    reason: z.string(),
+})
+    .strict();
+export const frontendRecoveryEvidenceRefSchema = z
+    .object({
+    runId: z.string().min(1),
+    relativePath: z.string().min(1),
+    sha256: z.string().min(1),
+})
+    .strict();
+/**
+ * Terminal frontend recovery result. `failureClass` is absent for `none`,
+ * `recovered` and `auto-recovery-blocked` outcomes. The schema intentionally
+ * stays permissive (failureClass optional, evidenceRefs may be empty) so it
+ * accepts the runner's actual phase-3a products, which do not always carry a
+ * failure class or evidence reference.
+ */
+export const frontendRecoveryResultSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION),
+    outcome: frontendRecoveryOutcomeSchema,
+    origin: frontendRecoveryOriginSchema,
+    failureClass: frontendRecoveryFailureClassSchema.optional(),
+    evidenceRefs: z.array(frontendRecoveryEvidenceRefSchema),
+})
+    .strict();
 export const DEFAULT_DAG_EXECUTOR_MODELS = {
     pi: {
         LOW: "gpt-5.3-codex-spark",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.35.2",
+  "version": "0.35.3",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -45,7 +45,7 @@
     "pi-prompt": "node --import tsx/esm src/cli.ts pi-prompt",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "brand:sync": "node scripts/sync-brand-assets.mjs",
-    "build": "npm run brand:sync && npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\" && npm run console:build",
+    "build": "npm run brand:sync && npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\" && npm run console:build && node scripts/write-build-stamp.mjs",
     "console:typecheck": "tsc -p src/worker/console/tsconfig.json",
     "console:build": "npm run console:typecheck && vite build --config src/worker/console/vite.config.ts",
     "prepack": "npm run build",
@@ -88,5 +88,6 @@
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vitest": "^3.2.4"
-  }
+  },
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319"
 }