@tea-agent/loop-agent 0.35.0 → 0.35.1-beta.1

package/dist/workflows/dag/runner.js

@@ -21,7 +21,7 @@ import { createSkillSnapshot, prepareSkillSnapshotForContinuation, writeSkillSna
 import { captureWorkspaceCheckpoint, WORKSPACE_CHECKPOINT_START_REL, WORKSPACE_CHECKPOINT_TERMINAL_REL, writeWorkspaceCheckpoint, } from "./workspace-checkpoint.js";
 import { buildNodePrompt, buildNodePromptWithResolvedSkillInstructions, executeDagNode, } from "./node-execution.js";
 import { runConvergencePassController, } from "./convergence/controller.js";
-import { executeDagRanksOnce, isConditionSkippedReason } from "./scheduler.js";
+import { executeDagRanksOnce, FRONTEND_WRITER_NODE_IDS, isConditionSkippedReason, readFrontendPrewriteResult, } from "./scheduler.js";
 import { topoSortToRanks } from "./topo.js";
 import { parseDagSpec, resolveModelForTask, } from "./types.js";
 import { executeDynamicCondition } from "./dynamic-runtime/condition.js";
@@ -448,6 +448,39 @@ async function executeDagCheckpoint(input) {
         void persistState().catch(() => { });
     }, runnerLivenessPolicy.heartbeatIntervalMs);
     heartbeatTimer.unref();
+    // Graceful terminal persistence: an outer SIGTERM/SIGINT (operator hard
+    // timeout, supervision layer, or shell wall-clock) must not leave the run
+    // orphaned in RUNNING with a dead heartbeat. Persist a terminal failed
+    // state with an explicit terminalReason before exiting so downstream
+    // liveness/doctor tooling sees a diagnosable terminal instead of an orphan.
+    let terminalSignal;
+    const shutdownOnSignal = (signal) => {
+        if (terminalSignal)
+            return;
+        terminalSignal = signal;
+        clearInterval(heartbeatTimer);
+        if (state.runner)
+            state.runner.heartbeatAt = new Date().toISOString();
+        state.status = "failed";
+        state.finishedAt = new Date().toISOString();
+        state.terminalReason = `runner terminated by ${signal} before run completion`;
+        console.warn(`[run-dag] received ${signal}; persisting terminal state and exiting`);
+        const exit = () => process.exit(signal === "SIGINT" ? 130 : 143);
+        // Best-effort atomic persist with a hard exit deadline so a stuck write
+        // queue cannot keep the process alive past the supervisor's kill window.
+        const hardExit = setTimeout(exit, 5000);
+        hardExit.unref();
+        void persistState()
+            .catch(() => { })
+            .finally(() => {
+            clearTimeout(hardExit);
+            exit();
+        });
+    };
+    const onSigTerm = () => shutdownOnSignal("SIGTERM");
+    const onSigInt = () => shutdownOnSignal("SIGINT");
+    process.once("SIGTERM", onSigTerm);
+    process.once("SIGINT", onSigInt);
     try {
         const tasksById = new Map(spec.tasks.map((task) => [task.id, task]));
         const baseExecuteNode = input.executeNode ??
@@ -504,6 +537,7 @@ async function executeDagCheckpoint(input) {
             tasksById,
             maxConcurrent,
             persistState,
+            runDir,
             abortSignal: input.abortSignal,
             createExecuteNodeForRank: (rankWriterNodeIds) => buildRankAwareExecuteNode({
                 baseExecuteNode,
@@ -595,7 +629,7 @@ async function executeDagCheckpoint(input) {
             runDir = await moveToPausedRunDir(runDir, pausedRunDir);
         }
         else {
-            finalizeTerminalRunStatus(state, spec.tasks.length);
+            await finalizeTerminalRunStatus(state, spec.tasks.length, runDir);
             await persistState();
             await notifyRunObserver(input.observer, "onRunFinish", state);
             try {
@@ -628,6 +662,8 @@ async function executeDagCheckpoint(input) {
     }
     finally {
         clearInterval(heartbeatTimer);
+        process.removeListener("SIGTERM", onSigTerm);
+        process.removeListener("SIGINT", onSigInt);
     }
 }
 async function notifyRunObserver(observer, event, state) {
@@ -695,7 +731,20 @@ function isSuccessfulConvergenceTerminal(state) {
         return true;
     return SUCCESSFUL_CONVERGENCE_TERMINAL_REASONS.has(reason);
 }
-function finalizeTerminalRunStatus(state, taskCount) {
+export async function finalizeTerminalRunStatus(state, taskCount, runDir) {
+    // Terminal override: a denied frontend writer must never surface as a
+    // mechanical partial_failed just because prewrite FINISHED while the writer
+    // was SKIPPED. Fail closed on retryable-invalid/blocked before aggregation.
+    const hasFrontendWriter = Object.keys(state.nodes).some((id) => FRONTEND_WRITER_NODE_IDS.includes(id));
+    if (hasFrontendWriter) {
+        const admission = await readFrontendPrewriteResult(runDir);
+        if (admission.ok &&
+            (admission.result.classification === "retryable-invalid" ||
+                admission.result.classification === "blocked")) {
+            state.status = "failed";
+            return;
+        }
+    }
     const finishedCount = Object.values(state.nodes).filter((n) => n.status === "FINISHED").length;
     const { supersededIds, supersededFailures } = collectSupersededIntermediateFailures(state);
     if (state.convergence && supersededFailures.length > 0) {

package/dist/workflows/dag/scheduler.js

@@ -1,5 +1,9 @@
+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";
 export function isConditionSkippedReason(reason) {
     return Boolean(reason?.startsWith("condition "));
 }
@@ -104,6 +108,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 = [];
@@ -168,6 +224,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 +277,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.35.0",
+  "version": "0.35.1-beta.1",
   "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",