@tea-agent/loop-agent 0.1.0

package/dist/workflows/dag/recovery-recommendation.js

@@ -0,0 +1,226 @@
+export const DAG_RECOVERY_ACTIONS = [
+    "none",
+    "monitor",
+    "retry-node",
+    "rerun-after-fix",
+    "resume-or-reject",
+    "manual-review",
+    "inspect-upstream",
+    "unknown",
+];
+const REPORT_DERIVED_ONLY = "Derived planning hint only; dag report does not execute retry or resume.";
+const TRANSIENT_EXECUTOR_RAW = new Set([
+    "network",
+    "quota",
+    "rate-limit",
+    "unavailable",
+]);
+function isInProgressStatus(status) {
+    return (status === "PENDING" ||
+        status === "RUNNING" ||
+        status === "pending" ||
+        status === "running");
+}
+function isPausedRunStatus(status) {
+    return status === "paused";
+}
+function executorAction(raw) {
+    if (raw !== undefined && TRANSIENT_EXECUTOR_RAW.has(raw)) {
+        return "retry-node";
+    }
+    return "rerun-after-fix";
+}
+function writeGuardAction(raw) {
+    if (raw === "write-guard") {
+        return "manual-review";
+    }
+    return "manual-review";
+}
+function isPausedContext(status, lifecycle, runStatus) {
+    return (isPausedRunStatus(status) ||
+        runStatus === "paused" ||
+        lifecycle === "paused");
+}
+function decisionEnvelopeAction(status, lifecycle, runStatus) {
+    if (isPausedContext(status, lifecycle, runStatus)) {
+        return "resume-or-reject";
+    }
+    return "manual-review";
+}
+function planByNormalizedCategory(input) {
+    const { status, normalizedFailureCategory: category, failureCategory: raw, nodeId, runId, lifecycle, runStatus, } = input;
+    const target = nodeId ?? runId ?? "run";
+    switch (category) {
+        case "success":
+            return {
+                action: "none",
+                summary: "No recovery needed.",
+                reason: `${target} finished successfully.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "skipped":
+            return {
+                action: "inspect-upstream",
+                summary: "Inspect upstream failures before retrying downstream nodes.",
+                reason: `${target} was skipped because an upstream dependency failed or was rejected.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Resolve upstream ERROR/SKIPPED nodes first; do not auto-retry skipped nodes until upstream is fixed.",
+            };
+        case "timeout":
+            return {
+                action: "retry-node",
+                summary: `Retry ${target} after confirming the timeout was transient.`,
+                reason: `${target} exceeded its execution time limit${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: true,
+                commandHint: `Investigate logs/artifacts, then re-run ${target}. ${REPORT_DERIVED_ONLY}`,
+            };
+        case "executor":
+            return {
+                action: executorAction(raw),
+                summary: executorAction(raw) === "retry-node"
+                    ? `Retry ${target} if the executor/backend error looks transient.`
+                    : `Fix executor/backend conditions, then re-run ${target}.`,
+                reason: `${target} failed in the executor layer${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: executorAction(raw) === "retry-node",
+                commandHint: executorAction(raw) === "retry-node"
+                    ? `Retry ${target} once transient network/quota/rate-limit issues clear. ${REPORT_DERIVED_ONLY}`
+                    : `Inspect backend logs and node artifacts before re-running ${target}. ${REPORT_DERIVED_ONLY}`,
+            };
+        case "auth":
+            return {
+                action: "rerun-after-fix",
+                summary: "Fix credentials/API keys, then re-run the affected node or DAG.",
+                reason: `${target} failed due to missing or invalid auth${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Update API keys/credentials in the environment or repo config, then re-run.",
+            };
+        case "write-guard":
+            return {
+                action: writeGuardAction(raw),
+                summary: "Review writeSet/writePolicy and approve or adjust writes before re-run.",
+                reason: `${target} was blocked by the write guard${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Inspect writeSet/writePolicy, node prompt, and result.summary.md; revise policy or scope before re-run.",
+            };
+        case "validation":
+            return {
+                action: "rerun-after-fix",
+                summary: "Fix schema/output/test validation issues, then re-run the node.",
+                reason: `${target} produced invalid or unverifiable output${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Inspect schema/output/tests and node artifacts; correct the underlying issue before re-run.",
+            };
+        case "shell-command":
+            return {
+                action: "rerun-after-fix",
+                summary: "Inspect shell output/result.summary.md, fix the command, then re-run.",
+                reason: `${target} shell command failed${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Review shell stdout/stderr and result.summary.md; adjust shell config or repo state before re-run.",
+            };
+        case "static-error":
+            return {
+                action: "rerun-after-fix",
+                summary: "Inspect static executor config/output, then re-run the node.",
+                reason: `${target} static executor reported an error${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Review static executor configuration and emitted markdown before re-run.",
+            };
+        case "decision-envelope":
+            return {
+                action: decisionEnvelopeAction(status, lifecycle, runStatus),
+                summary: decisionEnvelopeAction(status, lifecycle, runStatus) ===
+                    "resume-or-reject"
+                    ? "Resume after human approval or reject the paused run."
+                    : "Manually review the decision envelope before continuing.",
+                reason: `${target} requires decision-gate review${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: decisionEnvelopeAction(status, lifecycle, runStatus) ===
+                    "resume-or-reject"
+                    ? "Use dag approve / dag reject, then dag resume when approved."
+                    : "Inspect decision.envelope.json and human-escalation artifacts.",
+            };
+        case "human-required": {
+            const action = isPausedContext(status, lifecycle, runStatus)
+                ? "resume-or-reject"
+                : "manual-review";
+            return {
+                action,
+                summary: action === "resume-or-reject"
+                    ? "Provide human input, then resume or reject the paused run."
+                    : "Provide human input before choosing the next recovery action.",
+                reason: `${target} is waiting for human escalation${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: action === "resume-or-reject"
+                    ? "Use dag approve / dag reject, then dag resume when approved."
+                    : "Inspect human-escalation artifacts and update the run/task contract before continuing.",
+            };
+        }
+        case "human-rejected":
+            return {
+                action: "manual-review",
+                summary: "Revise contract/source or escalation options before any retry.",
+                reason: `${target} was human-rejected${raw ? ` (${raw})` : ""}; automatic retry is not recommended.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Review human-rejection.json and update the DAG/task contract before starting a new run.",
+            };
+        case "unknown":
+            return {
+                action: "manual-review",
+                summary: "Manually inspect failure artifacts; no automatic retry recommended.",
+                reason: `${target} failed with an unclassified category${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Inspect node artifacts, executor.jsonl, and state.json before choosing a recovery path.",
+            };
+        default: {
+            const exhaustive = category;
+            return {
+                action: "unknown",
+                summary: "Unknown recovery path.",
+                reason: `Unhandled normalized category: ${exhaustive}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        }
+    }
+}
+export function planDagRecovery(input) {
+    if (isInProgressStatus(input.status)) {
+        return {
+            action: "monitor",
+            summary: "Monitor the in-progress run; no recovery action yet.",
+            reason: `${input.nodeId ?? input.runId ?? "Run"} is still ${input.status.toLowerCase()}.`,
+            humanRequired: false,
+            autoRetryEligible: false,
+            commandHint: "Wait for the node/run to finish or pause before planning recovery.",
+        };
+    }
+    if (isPausedRunStatus(input.status)) {
+        const pausedRecommendation = planByNormalizedCategory(input);
+        if (pausedRecommendation.action === "none") {
+            return {
+                action: "resume-or-reject",
+                summary: "Resume after review or reject the paused run.",
+                reason: "Run is paused and awaiting human decision.",
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Use dag approve / dag reject, then dag resume when approved.",
+            };
+        }
+        return pausedRecommendation;
+    }
+    return planByNormalizedCategory(input);
+}

package/dist/workflows/dag/repair-artifact.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+export const repairFailureClassSchema = z.enum([
+    "syntax",
+    "runtime",
+    "logic",
+    "boundary",
+    "environment",
+    "governance",
+    "unknown",
+]);
+export const repairArtifactSchema = z.object({
+    schemaVersion: z.literal(1),
+    verdict: z.enum(["pass", "request-revision"]),
+    failureClass: repairFailureClassSchema,
+    rootCause: z.string().min(1),
+    fixScope: z.array(z.string().min(1)).default([]),
+    invariant: z.string().min(1),
+    evidenceRefs: z.array(z.string().min(1)).default([]),
+    rawLogFallbackAllowed: z.boolean().default(false),
+});
+const REPAIR_ARTIFACT_FENCE = /```(?:REPAIR_ARTIFACT_JSON|json)\s*([\s\S]*?)```/gi;
+function extractCandidateJsonBlocks(text) {
+    const blocks = [];
+    for (const match of text.matchAll(REPAIR_ARTIFACT_FENCE)) {
+        const candidate = match[1]?.trim();
+        if (candidate)
+            blocks.push(candidate);
+    }
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        blocks.push(trimmed);
+    }
+    return blocks;
+}
+export function parseRepairArtifactFromText(text) {
+    const candidates = extractCandidateJsonBlocks(text);
+    if (candidates.length === 0) {
+        return { ok: false, reason: "missing REPAIR_ARTIFACT_JSON fenced block" };
+    }
+    const errors = [];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            const result = repairArtifactSchema.safeParse(parsed);
+            if (result.success) {
+                return { ok: true, artifact: result.data };
+            }
+            errors.push(result.error.issues.map((issue) => issue.message).join(", "));
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return {
+        ok: false,
+        reason: `invalid repair artifact JSON: ${errors.join("; ")}`,
+    };
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isPathLikeScope(scope) {
+    const normalized = normalizePath(scope);
+    if (normalized === "none")
+        return false;
+    if (normalized === "." || normalized === "**" || normalized === "/*")
+        return false;
+    return (normalized.includes("/") ||
+        /\.(ts|tsx|js|jsx|mjs|cjs|json|md|sh|yml|yaml)$/.test(normalized));
+}
+function scopeWithinPatterns(scope, patterns) {
+    if (patterns.length === 0)
+        return true;
+    const normalized = normalizePath(scope);
+    return patterns.some((pattern) => pathMatchesPattern(normalized, pattern));
+}
+export function validateRepairArtifactScope(input) {
+    const { artifact, repairTask } = input;
+    if (artifact.verdict === "pass") {
+        if (artifact.fixScope.length > 0) {
+            return {
+                ok: false,
+                reason: "pass repair artifact requires empty fixScope",
+            };
+        }
+        return { ok: true, artifact };
+    }
+    if (artifact.fixScope.length === 0) {
+        return {
+            ok: false,
+            reason: "request-revision repair artifact requires non-empty fixScope",
+        };
+    }
+    if (!repairTask) {
+        return {
+            ok: false,
+            reason: "repair artifact gate cannot find downstream repair task",
+        };
+    }
+    const allowed = repairTask.allowedPaths ?? [];
+    const writeSet = repairTask.writeSet ?? [];
+    const forbidden = repairTask.forbiddenPaths ?? [];
+    for (const scope of artifact.fixScope) {
+        if (!isPathLikeScope(scope)) {
+            return {
+                ok: false,
+                reason: `fixScope "${scope}" must be a concrete path or glob inside repair task allowedPaths/writeSet`,
+            };
+        }
+        if (!scopeWithinPatterns(scope, allowed) || !scopeWithinPatterns(scope, writeSet)) {
+            return {
+                ok: false,
+                reason: `fixScope "${scope}" is outside repair task allowedPaths/writeSet`,
+            };
+        }
+        if (forbidden.some((pattern) => pathMatchesPattern(normalizePath(scope), pattern))) {
+            return {
+                ok: false,
+                reason: `fixScope "${scope}" matches repair task forbiddenPaths`,
+            };
+        }
+    }
+    return { ok: true, artifact };
+}
+export function formatRepairArtifactForPrompt(artifact) {
+    return [
+        "Repair artifact:",
+        `- verdict: ${artifact.verdict}`,
+        `- failureClass: ${artifact.failureClass}`,
+        `- rootCause: ${artifact.rootCause}`,
+        `- fixScope: ${artifact.fixScope.length > 0 ? artifact.fixScope.join(", ") : "(none)"}`,
+        `- invariant: ${artifact.invariant}`,
+        `- evidenceRefs: ${artifact.evidenceRefs.length > 0 ? artifact.evidenceRefs.join(", ") : "(none)"}`,
+    ].join("\n");
+}