@tea-agent/loop-agent 0.1.0 → 0.2.1

package/dist/workflows/dag/node-execution.js

@@ -0,0 +1,262 @@
+import path from "node:path";
+import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
+import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
+import { buildDagNodePromptEnvelope } from "./prompt.js";
+import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
+import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
+import { resolveDagNodeSkills } from "./skills.js";
+import { parseRepairArtifactFromText, validateRepairArtifactScope, } from "./repair-artifact.js";
+import { resolveModelForTask, } from "./types.js";
+export function buildNodePrompt(spec, task, upstream) {
+    return buildDagNodePromptEnvelope({
+        spec,
+        task,
+        upstream,
+        resolvedSkills: resolveDagNodeSkills(spec, task),
+    });
+}
+export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd) {
+    const skillNames = resolveDagNodeSkills(spec, task);
+    const resolvedSkillInstructions = task.executor === "cursor" || task.executor === "pi"
+        ? await resolveDagSkillInstructions(skillNames, {
+            cwd,
+            includeLearnedPatterns: task.role === "implementer",
+        })
+        : [];
+    return {
+        prompt: buildDagNodePromptEnvelope({
+            spec,
+            task,
+            upstream,
+            resolvedSkills: skillNames,
+            resolvedSkillInstructions,
+        }),
+        resolvedSkills: skillInstructionMetadata(resolvedSkillInstructions),
+    };
+}
+export function parseProcessVerdict(node) {
+    const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "VERDICT: pass")
+            return "pass";
+        if (trimmed === "VERDICT: request-revision")
+            return "request-revision";
+    }
+    return "unknown";
+}
+function assertRepairArtifactVerdictMatchesSupervisor(input) {
+    const supervisorVerdict = parseProcessVerdict(input.node);
+    if (supervisorVerdict === "unknown")
+        return;
+    if (supervisorVerdict !== input.artifactVerdict) {
+        throw new Error(`repair artifact gate failed: verdict mismatch between supervisor ${supervisorVerdict} and REPAIR_ARTIFACT_JSON ${input.artifactVerdict}`);
+    }
+}
+function findRepairTaskForGate(input) {
+    return Array.from(input.tasksById.values()).find((candidate) => candidate.depends_on.includes(input.gateTask.id) &&
+        candidate.id === "repair-cursor");
+}
+function parseSupervisorRepairArtifact(node) {
+    const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
+    return parseRepairArtifactFromText(text);
+}
+function validateRepairArtifactGateBeforeShell(input) {
+    const gate = input.task.shell?.repairArtifactGate;
+    if (!gate)
+        return;
+    const upstream = input.state.nodes[gate.fromNodeId];
+    const parsed = parseSupervisorRepairArtifact(upstream);
+    if (!parsed.ok) {
+        throw new Error(`repair artifact gate failed: ${parsed.reason}`);
+    }
+    assertRepairArtifactVerdictMatchesSupervisor({
+        node: upstream,
+        artifactVerdict: parsed.artifact.verdict,
+    });
+    upstream.repairArtifact = parsed.artifact;
+    const scoped = validateRepairArtifactScope({
+        artifact: parsed.artifact,
+        repairTask: findRepairTaskForGate({
+            tasksById: input.tasksById,
+            gateTask: input.task,
+        }),
+    });
+    if (!scoped.ok) {
+        throw new Error(`repair artifact gate failed: ${scoped.reason}`);
+    }
+}
+function recordRepairArtifactForSupervisorNode(input) {
+    const dependentGate = Object.values(input.state.nodes).find((record) => record.id === "process-gate-shell");
+    if (input.task.id !== "process-supervisor-pi" || !dependentGate)
+        return;
+    const parsed = parseSupervisorRepairArtifact(input.node);
+    if (parsed.ok) {
+        input.node.repairArtifact = parsed.artifact;
+    }
+}
+async function notifyNodeObserver(observer, event, nodeId, state, chunk) {
+    try {
+        if (event === "onNodeOutput") {
+            await observer?.onNodeOutput?.(nodeId, chunk ?? "", state);
+            return;
+        }
+        await observer?.[event]?.(nodeId, state);
+    }
+    catch {
+        // Observers are derived views; they must not affect canonical DAG execution.
+    }
+}
+export async function executeDagNode(input) {
+    const { nodeId, tasksById, state, spec, cwd, runDir, executeNode } = input;
+    const task = tasksById.get(nodeId);
+    const node = state.nodes[nodeId];
+    node.status = "RUNNING";
+    node.startedAt = new Date().toISOString();
+    if (task.shell?.verifyEvidence) {
+        node.verifyEvidence = task.shell.verifyEvidence;
+    }
+    await input.persistState();
+    await notifyNodeObserver(input.observer, "onNodeStart", nodeId, state);
+    if (task.dynamicExpansion ||
+        task.dynamicReduction ||
+        task.dynamicCondition ||
+        task.dynamicLoopUntil) {
+        const started = Date.now();
+        try {
+            const result = await input.executeDynamicNode({
+                task,
+                tasksById,
+                state,
+                spec,
+                cwd,
+                runDir,
+                executeNode,
+                observer: input.observer,
+                persistState: input.persistState,
+            });
+            node.durationMs = result.durationMs ?? Date.now() - started;
+            node.stdout = result.stdout;
+            node.stderr = result.stderr;
+            node.failureCategory = result.failureCategory;
+            node.finishedAt = new Date().toISOString();
+            node.status = result.ok ? "FINISHED" : "ERROR";
+        }
+        catch (error) {
+            node.status = "ERROR";
+            node.stderr = error instanceof Error ? error.message : String(error);
+            node.finishedAt = new Date().toISOString();
+            node.durationMs = Date.now() - started;
+        }
+        if (node.status === "FINISHED") {
+            const artifactMeta = await persistLongNodeOutputArtifacts({
+                runDir,
+                nodeId,
+                stdout: node.stdout,
+                assistantText: node.assistantText,
+            });
+            Object.assign(node, artifactMeta);
+        }
+        state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+        await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+        await input.persistState();
+        await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+        return;
+    }
+    const { prompt, resolvedSkills } = await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd);
+    node.resolvedSkills = resolvedSkills;
+    await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
+    const model = resolveModelForTask(task, spec.executorModels);
+    const started = Date.now();
+    try {
+        validateRepairArtifactGateBeforeShell({
+            task,
+            tasksById,
+            state,
+        });
+        const result = await executeNode({ task, cwd, model, prompt });
+        node.durationMs = result.durationMs ?? Date.now() - started;
+        node.stdout = result.stdout;
+        node.stderr = result.stderr;
+        node.failureCategory = result.failureCategory;
+        if (result.assistantText !== undefined) {
+            node.assistantText = result.assistantText;
+        }
+        if (result.backend !== undefined)
+            node.backend = result.backend;
+        if (result.sdkAttempted !== undefined) {
+            node.sdkAttempted = result.sdkAttempted;
+        }
+        if (result.tokensUsed !== undefined)
+            node.tokensUsed = result.tokensUsed;
+        if (result.parsedEvents !== undefined) {
+            node.parsedEvents = result.parsedEvents;
+        }
+        recordRepairArtifactForSupervisorNode({
+            task,
+            node,
+            state,
+        });
+        const outputChunk = result.assistantText ?? result.stdout;
+        if (outputChunk.trim()) {
+            await notifyNodeObserver(input.observer, "onNodeOutput", nodeId, state, outputChunk);
+        }
+        node.finishedAt = new Date().toISOString();
+        node.status = result.ok ? "FINISHED" : "ERROR";
+        if (result.ok) {
+            const decisionRecord = await recordDecisionEnvelopeForNode({
+                task,
+                runDir,
+                nodeId,
+                assistantText: node.assistantText ?? result.assistantText,
+            });
+            if (decisionRecord) {
+                node.decisionEnvelope = decisionRecord.nodeRecord;
+                if (!decisionRecord.nodeRecord.parseOk) {
+                    node.status = "ERROR";
+                    node.failureCategory = "decision-envelope-invalid";
+                    node.stderr = [
+                        node.stderr,
+                        ...(decisionRecord.nodeRecord.errors ?? []),
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                }
+                else if (shouldPauseOnHumanEscalation(task, decisionRecord.nodeRecord) &&
+                    decisionRecord.envelope) {
+                    const pausedAt = new Date().toISOString();
+                    const nodeArtifactsDir = path.join(runDir, nodeId);
+                    const { jsonPath } = await writeHumanEscalationArtifacts({
+                        nodeArtifactsDir,
+                        runId: state.runId,
+                        nodeId,
+                        envelope: decisionRecord.envelope,
+                        pausedAt,
+                    });
+                    node.pauseReason = "decision-gate-requires-human";
+                    node.escalationArtifactPath = jsonPath;
+                    input.onPause(nodeId, pausedAt, node.pauseReason);
+                }
+            }
+        }
+    }
+    catch (error) {
+        node.status = "ERROR";
+        node.stderr = error instanceof Error ? error.message : String(error);
+        node.finishedAt = new Date().toISOString();
+        node.durationMs = Date.now() - started;
+    }
+    if (node.status === "FINISHED") {
+        const artifactMeta = await persistLongNodeOutputArtifacts({
+            runDir,
+            nodeId,
+            stdout: node.stdout,
+            assistantText: node.assistantText,
+        });
+        Object.assign(node, artifactMeta);
+    }
+    state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+    await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+    await input.persistState();
+    await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+}

package/dist/workflows/dag/report.js

@@ -7,6 +7,7 @@ import { repairArtifactSchema } from "./repair-artifact.js";
 import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 export const DAG_CLOSEOUT_DRAFT_DISCLAIMER = "> **Advisory only.** Derived from completed run facts. Canonical source remains `dag report --json` and `.harness/dag-runs/completed/<run-id>/`. Do not treat this draft as authoritative.";
 import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from "./failure-category.js";
+import { dagProductLineFailureCategoryValues, routeDagFailure, } from "./failure-routing.js";
 import { DAG_RECOVERY_ACTIONS, planDagRecovery, } from "./recovery-recommendation.js";
 import { dagNodeExecutorSchema, dagNodeStatusSchema, LEGACY_TOP_LEVEL_MODELS_ERROR, parseDagSpec, resolveModelForTask, } from "./types.js";
 export const DAG_REPORT_SCHEMA_VERSION = 1;
@@ -21,6 +22,7 @@ const dagRunStatusSchema = z.enum([
     "paused",
 ]);
 const dagRecoveryActionSchema = z.enum(DAG_RECOVERY_ACTIONS);
+const dagProductLineFailureCategorySchema = z.enum(dagProductLineFailureCategoryValues);
 const dagArtifactRefSchema = z
     .object({
     path: z.string(),
@@ -44,6 +46,8 @@ const dagReportPrimaryFailureSchema = z
     nodeStatus: dagNodeStatusSchema.optional(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
 })
     .strict();
 const dagReportDownstreamSkippedNodeSchema = z
@@ -51,6 +55,8 @@ const dagReportDownstreamSkippedNodeSchema = z
     nodeId: z.string(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
 })
     .strict();
 const dagConvergencePassArtifactRefSchema = z
@@ -130,6 +136,8 @@ const dagNodeReportRowSchema = z
     tokensUsed: z.number().nonnegative().optional(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     backend: z.enum(["sdk", "cli"]).optional(),
     sdkAttempted: z.boolean().optional(),
@@ -150,6 +158,8 @@ const dagRunReportEntrySchema = z
     finishedAt: z.string().optional(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     primaryFailure: dagReportPrimaryFailureSchema,
     primaryRecovery: dagRecoveryRecommendationSchema,
@@ -250,12 +260,18 @@ function buildPrimaryFailure(run, primaryNode) {
             nodeStatus: primaryNode.status,
             failureCategory: primaryNode.failureCategory,
             normalizedFailureCategory: primaryNode.normalizedFailureCategory,
+            productLineFailureCategory: primaryNode.productLineFailureCategory,
+            recommendedFollowUp: primaryNode.recommendedFollowUp,
         };
     }
     return {
         scope: "run",
         failureCategory: run.failureCategory,
         normalizedFailureCategory: run.normalizedFailureCategory,
+        ...routeDagFailure({
+            rawFailureCategory: run.failureCategory,
+            normalizedFailureCategory: run.normalizedFailureCategory,
+        }),
     };
 }
 function resolvePrimaryRecovery(run, primaryNode) {
@@ -302,6 +318,8 @@ function collectDownstreamSkippedNodes(nodes, spec, primaryNode) {
         nodeId: node.nodeId,
         failureCategory: node.failureCategory,
         normalizedFailureCategory: node.normalizedFailureCategory,
+        productLineFailureCategory: node.productLineFailureCategory,
+        recommendedFollowUp: node.recommendedFollowUp,
     }));
 }
 function isFailedReportRun(run) {
@@ -342,6 +360,12 @@ export async function buildDagRunReportEntry(input) {
                 continue;
             const task = tasks.get(nodeId);
             const normalizedFailureCategory = normalizeDagFailureCategory(node.failureCategory, node.status);
+            const failureRouting = routeDagFailure({
+                rawFailureCategory: node.failureCategory,
+                normalizedFailureCategory,
+                nodeId,
+                executor: node.executor,
+            });
             nodes.push({
                 nodeId,
                 rank,
@@ -355,6 +379,7 @@ export async function buildDagRunReportEntry(input) {
                 tokensUsed: node.tokensUsed,
                 failureCategory: node.failureCategory,
                 normalizedFailureCategory,
+                ...failureRouting,
                 recoveryRecommendation: planDagRecovery({
                     status: node.status,
                     normalizedFailureCategory,
@@ -406,6 +431,11 @@ export async function buildDagRunReportEntry(input) {
         lifecycle: input.lifecycle,
         runStatus: input.state.status,
     });
+    const runFailureRouting = routeDagFailure({
+        rawFailureCategory: runRecoverySource.failureCategory,
+        normalizedFailureCategory: runRecoverySource.normalizedFailureCategory,
+        nodeId: "nodeId" in runRecoverySource ? runRecoverySource.nodeId : undefined,
+    });
     const partialEntry = {
         runId: input.state.runId,
         title: input.state.title,
@@ -416,6 +446,7 @@ export async function buildDagRunReportEntry(input) {
         finishedAt: input.state.finishedAt,
         failureCategory: input.state.failureCategory,
         normalizedFailureCategory,
+        ...runFailureRouting,
         recoveryRecommendation,
         pausedByNodeId: input.state.pausedByNodeId,
         pauseReason: input.state.pauseReason,
@@ -638,11 +669,15 @@ function formatPrimaryFailureSection(run) {
         return [
             `- **Node**: ${failure.nodeId} (${failure.nodeStatus ?? "unknown"})`,
             `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+            `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+            `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
         ];
     }
     return [
         `- **Scope**: run`,
         `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+        `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+        `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
     ];
 }
 function formatPrimaryRecoverySection(run) {
@@ -784,7 +819,7 @@ export function formatDagReportHandoffMarkdown(report) {
                 ? `- **Failure (raw/normalized)**: ${node.failureCategory} / ${node.normalizedFailureCategory ?? "-"}`
                 : "", `- **Executor**: ${node.executor}${node.backend ? ` (backend: ${node.backend})` : ""}`, `- **Model**: ${node.model ?? "—"}`, `- **Duration**: ${formatDuration(node.durationMs)}`, `- **Tokens**: ${formatTokens(node.tokensUsed)}`, `- **Started**: ${formatTimestamp(node.startedAt)}`, `- **Finished**: ${formatTimestamp(node.finishedAt)}`, "");
         }
-        lines.push("## Failures", ...formatFailureSection(run), "", "## Recovery Plan", ...formatRecoveryPlanSection(run), "", "## Artifacts", ...formatArtifactsSection(run), "", "## Suggested Next Action", `- ${suggestedNextAction(run)}`, "");
+        lines.push("## Failures", ...formatFailureSection(run), "", "## Recovery Plan", ...formatRecoveryPlanSection(run), "", "## Operator Next Steps", ...formatRecommendedOperatorAction(run), "", "## Artifacts", ...formatArtifactsSection(run), "", "## Suggested Next Action", `- ${suggestedNextAction(run)}`, "");
         return lines
             .filter((line) => line !== undefined)
             .join("\n");
@@ -869,6 +904,8 @@ function formatCloseoutPrimaryFailureSection(run) {
             `- **Scope**: node`,
             `- **Node**: ${failure.nodeId} (${failure.nodeStatus ?? "unknown"})`,
             `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+            `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+            `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
         ];
     }
     if (run.primaryRecovery.action === "none" &&
@@ -879,6 +916,8 @@ function formatCloseoutPrimaryFailureSection(run) {
     return [
         `- **Scope**: ${failure.scope}`,
         `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+        `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+        `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
     ];
 }
 function formatCloseoutRecoverySection(run) {
@@ -939,6 +978,39 @@ function formatRemainingRisksSection(run) {
     return risks;
 }
 export function formatDagCloseoutDraftMarkdown(run) {
+    if (isFailedReportRun(run)) {
+        const lines = [
+            `# Failure Handoff: ${run.runId}`,
+            "",
+            DAG_CLOSEOUT_DRAFT_DISCLAIMER,
+            "",
+            "## What failed",
+            ...formatCloseoutPrimaryFailureSection(run),
+            "",
+            "## Evidence",
+            ...formatCloseoutVerificationEvidence(run),
+            "",
+            "## Classification",
+            `- raw_failure_category: ${run.primaryFailure.failureCategory ?? "-"}`,
+            `- dag_normalized_failure_category: ${run.primaryFailure.normalizedFailureCategory ?? "-"}`,
+            `- product_line_failure_category: ${run.primaryFailure.productLineFailureCategory ?? "-"}`,
+            `- recommended_follow_up: ${run.primaryFailure.recommendedFollowUp ?? "-"}`,
+            "",
+            "## Recommended follow-up",
+            ...formatCloseoutRecoverySection(run),
+            "",
+            "## Safe retry conditions",
+            `- Retry only after completing \`${run.primaryFailure.recommendedFollowUp ?? run.primaryRecovery.action}\` and preserving the original DAG run facts.`,
+            "- Do not rewrite `.harness/dag-runs/completed/**`; create a new run or task artifact for follow-up evidence.",
+            "",
+            "## Human decision needed",
+            run.primaryRecovery.humanRequired
+                ? "- Yes. Human review is required before retry or promotion."
+                : "- No required human gate was derived, but review the failure evidence before retry.",
+            "",
+        ];
+        return lines.join("\n");
+    }
     const lines = [
         `# DAG Closeout Draft: ${run.runId}`,
         "",

package/dist/workflows/dag/run-store.js

@@ -0,0 +1,36 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { readDagRunSpec, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
+export async function readRunState(runDir) {
+    return readDagRunState(runDir);
+}
+export async function writeRunState(runDir, state, options) {
+    await writeDagRunState(runDir, state, options);
+}
+export async function readRunSpec(runDir) {
+    return readDagRunSpec(runDir);
+}
+export async function prepareActiveRunDir(runDir) {
+    await rm(runDir, { recursive: true, force: true });
+    await mkdir(runDir, { recursive: true });
+}
+export async function writeRunSpec(runDir, spec) {
+    await writeJsonAtomic(path.join(runDir, "run.json"), spec);
+}
+export async function writeNodeRecord(runDir, nodeId, record) {
+    await writeJsonAtomic(path.join(runDir, `${nodeId}.json`), record);
+}
+export async function writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills) {
+    if (resolvedSkills.length === 0)
+        return;
+    const nodeDir = path.join(runDir, nodeId);
+    await mkdir(nodeDir, { recursive: true });
+    await writeJsonAtomic(path.join(nodeDir, "skills.json"), { resolvedSkills });
+}
+export async function moveToPausedRunDir(runDir, pausedRunDir) {
+    return transferDagRunDir(runDir, pausedRunDir);
+}
+export async function moveToCompletedRunDir(runDir, completedRunDir) {
+    return transferDagRunDir(runDir, completedRunDir);
+}