@tea-agent/loop-agent 0.29.3 → 0.31.0

package/dist/workflows/dag/backend-test-writer-completeness.js

@@ -5,11 +5,23 @@ import { z } from "zod";
 /**
  * Maps a backend-test generation writer task id to its writer-progress role.
  * Returns undefined for nodes that are not completeness-gated generators.
+ *
+ * Recognizes both the legacy single-node literal ids
+ * (`generate-backend-md-cases-pi` / `generate-backend-pytest-pi`) and the
+ * map_agent sharded child ids (`generate-backend-md-case-0001` /
+ * `generate-backend-pytest-case-0001`). The literal fallback keeps hand-
+ * written test DAGs that bypass buildHybridDagFromTask green.
  */
 export function backendTestWriterProgressRoleForTask(taskId) {
-    if (taskId === "generate-backend-md-cases-pi")
+    if (!taskId)
+        return undefined;
+    if (taskId === "generate-backend-md-cases-pi" ||
+        taskId === "generate-backend-md-plan-pi" ||
+        taskId.startsWith("generate-backend-md-case-"))
         return "md-generate";
-    if (taskId === "generate-backend-pytest-pi")
+    if (taskId === "generate-backend-pytest-pi" ||
+        taskId === "generate-backend-pytest-plan-pi" ||
+        taskId.startsWith("generate-backend-pytest-case-"))
         return "pytest-generate";
     return undefined;
 }
@@ -96,7 +108,13 @@ function looksLikeValidModuleStem(raw) {
         return false;
     return true;
 }
-function extractModuleStemsFromReadme(readme) {
+/**
+ * Exported for reuse by the manifest-shell node that materializes the
+ * module list JSON consumed by the map_agent expansion. Kept deterministic
+ * (same extractor as the completeness gate) so the shard set always matches
+ * the README index the gate trusts.
+ */
+export function extractModuleStemsFromReadme(readme) {
     const stems = [];
     // Only trust testcase/md/<stem>.md mentions that appear inside markdown
     // table rows (`| ... testcase/md/x.md ... |`) or as canonical relative
@@ -135,21 +153,94 @@ async function listMarkdownModules(workspaceRoot) {
         entry.name.toLowerCase() !== "readme.md")
         .map((entry) => path.posix.join("testcase/md", entry.name.replaceAll("\\", "/"))));
 }
+/**
+ * Recursively list `.py` file paths relative to `dirRoot` (forward slashes).
+ * Used by the pytest plan-node completeness check to discover shared
+ * helpers/factories resources.
+ */
+async function listPythonFiles(dirRoot) {
+    if (!(await exists(dirRoot)))
+        return [];
+    const out = [];
+    const walk = async (rel) => {
+        const absolute = path.join(dirRoot, rel);
+        const entries = await readdir(absolute, { withFileTypes: true });
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(childRel);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".py")) {
+                out.push(childRel.replaceAll("\\", "/"));
+            }
+        }
+    };
+    await walk("");
+    return orderedUnique(out);
+}
+const MODULE_REQUIRED_SECTIONS = [
+    "\u8986\u76d6\u89c4\u5219",
+    "\u6d4b\u8bd5\u70b9",
+    "\u573a\u666f\u7c7b\u578b",
+    "\u524d\u7f6e\u6761\u4ef6",
+    "\u64cd\u4f5c\u6b65\u9aa4",
+    "\u9884\u671f\u7ed3\u679c",
+    "\u81ea\u52a8\u5316\u6620\u5c04",
+];
+/**
+ * Structural check for a backend-test Markdown module file. Returns structured
+ * reasons instead of a bare boolean so the Completeness Gate T5 detail and the
+ * retry prompt can tell the model exactly what is wrong (empty file / wrong
+ * case heading level / invalid case id format / missing sections). This avoids
+ * the "model cannot fix what it does not know" retry death-loop.
+ */
 function moduleStructurallyComplete(markdown) {
-    if (!markdown.trim())
-        return false;
-    if (!/^##\s+BE-[A-Z0-9_-]+-\d{2,3}\b/m.test(markdown))
-        return false;
-    const required = [
-        "\u8986\u76d6\u89c4\u5219",
-        "\u6d4b\u8bd5\u70b9",
-        "\u573a\u666f\u7c7b\u578b",
-        "\u524d\u7f6e\u6761\u4ef6",
-        "\u64cd\u4f5c\u6b65\u9aa4",
-        "\u9884\u671f\u7ed3\u679c",
-        "\u81ea\u52a8\u5316\u6620\u5c04"
-    ];
-    return required.every((heading) => markdown.includes(`### ${heading}`));
+    if (!markdown.trim()) {
+        return { ok: false, reasons: ["file is empty"] };
+    }
+    const h2CaseMatch = /^##\s+BE-[A-Z0-9_-]+-\d{2,3}\b/m.exec(markdown);
+    if (!h2CaseMatch) {
+        // Distinguish "wrong level (### or ####)" from "invalid format / no case at all"
+        // so the retry hint is actionable.
+        const wrongLevel = /^#{3,4}\s+BE-[A-Z0-9_-]+-\d{2,3}\b/m.exec(markdown);
+        if (wrongLevel) {
+            const hashes = /^#+/.exec(wrongLevel[0])?.[0].length ?? 3;
+            return {
+                ok: false,
+                reasons: [
+                    `case heading at wrong level: found '${hashes > 3 ? "####" : "###"} ${wrongLevel[0].replace(/^#+\s+/, "")}', require exactly 2 hashes '## BE-<MODULE>-<NNN>'`,
+                ],
+            };
+        }
+        const anyCaseId = /^#{2,4}\s+BE-[A-Z0-9_-]+-\d{1,4}/m.exec(markdown);
+        if (anyCaseId) {
+            return {
+                ok: false,
+                reasons: [
+                    `invalid case heading format: '${anyCaseId[0].replace(/^#+\s+/, "")}' (need exactly 2-3 digit zero-padded NNN, e.g. BE-MOD-001)`,
+                ],
+            };
+        }
+        return {
+            ok: false,
+            reasons: [
+                "no h2 case heading found (require exactly '## BE-<MODULE>-<NNN>')",
+            ],
+        };
+    }
+    const missing = MODULE_REQUIRED_SECTIONS.filter((heading) => !markdown.includes(`### ${heading}`));
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            reasons: [`missing required sections: [${missing.join(", ")}]`],
+        };
+    }
+    return { ok: true, reasons: [] };
+}
+function moduleStructuralDetail(result) {
+    if (result.ok)
+        return "module file is structurally complete";
+    return `module file is empty or has structural issues: ${result.reasons.join("; ")}`;
 }
 function pythonParseable(source) {
     const text = source.replace(/\r\n/g, "\n");
@@ -180,6 +271,27 @@ function pythonParseable(source) {
     // legal multi-line definitions such as `def f(\n    x,\n):` — removed.
     return true;
 }
+/**
+ * Looser Python validity check for shared helpers/factories emitted by the
+ * pytest plan node. Unlike pythonParseable, it does NOT require balanced
+ * brackets/braces: shared pytest resources legitimately contain fixture
+ * strings with unbalanced delimiters (e.g. a malformed-JSON test payload
+ * `return "{bad json"`). Only verifies the file is non-empty, declares a
+ * Python construct (def/class/import/from), and has balanced triple quotes.
+ */
+function looksLikeValidPythonModule(source) {
+    const text = source.replace(/\r\n/g, "\n");
+    if (!text.trim())
+        return false;
+    if (/^\s*(?:def|class|import|from)\b/m.test(text) === false)
+        return false;
+    if (/("""|''')[\s\S]*$/.test(text)) {
+        const triples = text.match(/("""|''')/g) ?? [];
+        if (triples.length % 2 !== 0)
+            return false;
+    }
+    return true;
+}
 export function buildOutputLimitRecoveryPrompt(input) {
     return buildOutputLimitRecoverySection(input);
 }
@@ -189,19 +301,33 @@ export function buildOutputLimitRecoveryPrompt(input) {
  * not depend on reading `.harness/**` (which is forbidden for Pi writers).
  */
 export function buildOutputLimitRecoverySection(input) {
-    const paths = input.targetPaths.length > 0
-        ? input.targetPaths.map((item) => `  - ${item}`).join("\n")
-        : "  - (none)";
+    const hasDiagnostics = !!input.diagnostics && Object.keys(input.diagnostics).length > 0;
+    const pathsBlock = hasDiagnostics
+        ? input.targetPaths
+            .map((p) => {
+            const reasons = (input.diagnostics?.[p] ?? []).slice(0, 3);
+            if (reasons.length === 0)
+                return `  - ${p}`;
+            const issueLines = reasons.map((r) => `        - ${r}`).join("\n");
+            return `  - ${p}\n      issues:\n${issueLines}`;
+        })
+            .join("\n")
+        : input.targetPaths.length > 0
+            ? input.targetPaths.map((item) => `  - ${item}`).join("\n")
+            : "  - (none)";
     return [
         "<retry_instruction>",
         `OUTPUT_LIMIT_RECOVERY attempt=${input.attempt}/${input.maxAttempts}`,
         `reason=${input.reason}`,
         "target_paths_only:",
-        paths,
+        pathsBlock,
         "Rules:",
         "- Continue or repair ONLY listed paths; do not delete or shrink in-scope cases/rules/TPs.",
         "- One file per write/edit; no chat dump of full bodies.",
         "- Prefer edit/append for truncated files; rewrite a file only if unparseable or empty.",
+        ...(hasDiagnostics
+            ? ["- Fix the exact structural issues listed under each path; do not change unrelated content."]
+            : []),
         "- After targets are complete, short IMPLEMENTATION_OUTCOME only.",
         "- Do not mark already-satisfied if any target_path still missing or structurally broken.",
         "- Preserve quality invariants: no scope shrink, no skip/xfail, no secret-shaped samples.",
@@ -228,6 +354,85 @@ export async function loadBackendTestWriterProgressForRetry(runDir, taskId) {
         return undefined;
     }
 }
+/**
+ * Per-shard-child completeness assessment for map_agent children
+ * (generate-backend-md-case-NNNN / generate-backend-pytest-case-NNNN).
+ *
+ * Unlike the workspace-wide {@link assessBackendTestMdWriterCompleteness} /
+ * {@link assessBackendTestPytestWriterCompleteness} gates (which run for the
+ * legacy single-node writers and for the post-map review/validate nodes), a
+ * sharded child owns ONLY the single file in its rendered writeSet. Running
+ * the workspace-wide gate mid-map would flag every not-yet-written sibling
+ * module as a recoverable miss and loop. This function scopes the gate to the
+ * child's own target file(s): md children are checked for structural
+ * completeness, pytest children for parseability. Sibling modules are ignored.
+ */
+export async function assessBackendTestShardChildCompleteness(input) {
+    const role = input.role;
+    const targetPaths = input.writeSet
+        .map((entry) => entry.trim().replace(/\\/g, "/").replace(/^\.\//, ""))
+        .filter((entry) => entry.length > 0);
+    const issues = [];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    for (const target of targetPaths) {
+        // Rendered map-child writeSet entries are concrete (e.g.
+        // testcase/md/health.md / testcase/test_orders.py); glob-only entries are
+        // not produced for these children.
+        if (target.includes("*"))
+            continue;
+        const absolute = path.join(input.workspaceRoot, target);
+        if (!(await exists(absolute))) {
+            missingPaths.push(target);
+            issues.push({
+                code: "T3",
+                path: target,
+                detail: `shard child target ${target} was not written`,
+                recoverable: true,
+            });
+            continue;
+        }
+        actualPaths.push(target);
+        const body = await readFile(absolute, "utf8");
+        if (role === "md-generate") {
+            const structural = moduleStructurallyComplete(body);
+            if (!structural.ok) {
+                brokenPaths.push(target);
+                issues.push({
+                    code: "T5",
+                    path: target,
+                    detail: moduleStructuralDetail(structural),
+                    recoverable: true,
+                });
+            }
+        }
+        else {
+            if (!pythonParseable(body)) {
+                brokenPaths.push(target);
+                issues.push({
+                    code: "T5",
+                    path: target,
+                    detail: "pytest script appears truncated or unparseable",
+                    recoverable: true,
+                });
+            }
+        }
+    }
+    const recoverableTargets = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = recoverableTargets.length > 0 || issues.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role,
+        status,
+        expectedPaths: orderedUnique(targetPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths: recoverableTargets,
+        issues,
+    };
+}
 export async function assessBackendTestMdWriterCompleteness(workspaceRoot) {
     const issues = [];
     const expectedPaths = ["testcase/md/README.md"];
@@ -292,12 +497,13 @@ export async function assessBackendTestMdWriterCompleteness(workspaceRoot) {
         }
         actualPaths.push(existing);
         const body = await readFile(path.join(workspaceRoot, existing), "utf8");
-        if (!moduleStructurallyComplete(body)) {
+        const structural = moduleStructurallyComplete(body);
+        if (!structural.ok) {
             brokenPaths.push(existing);
             issues.push({
                 code: "T5",
                 path: existing,
-                detail: "module file is empty or missing required case sections",
+                detail: moduleStructuralDetail(structural),
                 recoverable: true,
             });
         }
@@ -306,12 +512,13 @@ export async function assessBackendTestMdWriterCompleteness(workspaceRoot) {
         if (!actualPaths.includes(rel))
             actualPaths.push(rel);
         const body = await readFile(path.join(workspaceRoot, rel), "utf8");
-        if (!moduleStructurallyComplete(body) && !brokenPaths.includes(rel)) {
+        const structural = moduleStructurallyComplete(body);
+        if (!structural.ok && !brokenPaths.includes(rel)) {
             brokenPaths.push(rel);
             issues.push({
                 code: "T5",
                 path: rel,
-                detail: "module file is empty or missing required case sections",
+                detail: moduleStructuralDetail(structural),
                 recoverable: true,
             });
         }
@@ -498,5 +705,170 @@ export function isBackendTestCompletenessRetryCandidate(task) {
         return false;
     }
     return (task.id === "generate-backend-md-cases-pi" ||
-        task.id === "generate-backend-pytest-pi");
+        task.id === "generate-backend-pytest-pi" ||
+        task.id === "generate-backend-md-plan-pi" ||
+        task.id === "generate-backend-pytest-plan-pi" ||
+        (task.id?.startsWith("generate-backend-md-case-") ?? false) ||
+        (task.id?.startsWith("generate-backend-pytest-case-") ?? false));
+}
+/**
+ * Is this task a materialized map_agent shard child (as opposed to the legacy
+ * single-node generator)? Shard children must scope the Completeness Gate to
+ * their own rendered writeSet rather than the whole workspace.
+ */
+export function isBackendTestShardChildTask(task) {
+    return Boolean(task.id?.startsWith("generate-backend-md-case-") ||
+        task.id?.startsWith("generate-backend-pytest-case-"));
+}
+/**
+ * Is this task the README-only plan node of the map-sharded md topology?
+ * The plan node writes testcase/md/README.md alone; module case cards are
+ * produced by the downstream map_agent children, so the Completeness Gate
+ * must NOT require module files to exist at plan time.
+ */
+export function isBackendTestMdPlanTask(task) {
+    return task.id === "generate-backend-md-plan-pi";
+}
+/**
+ * Is this task the shared-resources plan node of the map-sharded pytest
+ * topology? The plan node writes helpers/factories only; per-module pytest
+ * scripts are produced by the downstream map_agent children, so the Gate
+ * must NOT require mapped pytest scripts to exist at plan time.
+ */
+export function isBackendTestPytestPlanTask(task) {
+    return task.id === "generate-backend-pytest-plan-pi";
+}
+/**
+ * Plan-node completeness for the md topology: verify the README itself is
+ * structurally complete (Coverage Scope, Coverage Matrix, a non-empty module
+ * index), WITHOUT requiring the indexed module files to exist yet — those are
+ * written by the downstream map_agent shard children.
+ */
+export async function assessBackendTestMdPlanCompleteness(workspaceRoot) {
+    const issues = [];
+    const expectedPaths = ["testcase/md/README.md"];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    const readmePath = path.join(workspaceRoot, "testcase", "md", "README.md");
+    if (!(await exists(readmePath))) {
+        missingPaths.push("testcase/md/README.md");
+        issues.push({
+            code: "T3",
+            path: "testcase/md/README.md",
+            detail: "README.md is missing",
+            recoverable: true,
+        });
+    }
+    else {
+        actualPaths.push("testcase/md/README.md");
+        const readme = await readFile(readmePath, "utf8");
+        if (!readme.includes("## Coverage Scope")) {
+            brokenPaths.push("testcase/md/README.md");
+            issues.push({
+                code: "T5",
+                path: "testcase/md/README.md",
+                detail: "README.md is missing ## Coverage Scope",
+                recoverable: true,
+            });
+        }
+        if (!readme.includes("## Coverage Matrix") ||
+            !hasMarkdownTable(readme, "Rule Key")) {
+            if (!brokenPaths.includes("testcase/md/README.md")) {
+                brokenPaths.push("testcase/md/README.md");
+            }
+            issues.push({
+                code: "T5",
+                path: "testcase/md/README.md",
+                detail: "README.md Coverage Matrix table is missing or broken",
+                recoverable: true,
+            });
+        }
+        // The README must advertise a non-empty module index so the downstream
+        // manifest shell has stems to shard; the indexed module files themselves
+        // are produced by map_agent children and are NOT required here.
+        const indexedStems = extractModuleStemsFromReadme(readme);
+        if (indexedStems.length === 0) {
+            if (!brokenPaths.includes("testcase/md/README.md")) {
+                brokenPaths.push("testcase/md/README.md");
+            }
+            issues.push({
+                code: "T5",
+                path: "testcase/md/README.md",
+                detail: "README.md module index is empty; downstream map_agent has no stems to shard",
+                recoverable: true,
+            });
+        }
+    }
+    const targetPaths = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = targetPaths.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role: "md-generate",
+        status,
+        expectedPaths: orderedUnique(expectedPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths,
+        issues,
+    };
+}
+/**
+ * Plan-node completeness for the pytest topology: verify the shared
+ * helpers/factories resources were produced and are Python-parseable, WITHOUT
+ * requiring per-module pytest scripts to exist yet — those are written by the
+ * downstream map_agent shard children.
+ */
+export async function assessBackendTestPytestPlanCompleteness(workspaceRoot) {
+    const issues = [];
+    const expectedPaths = [];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    // Discover shared pytest resources under testcase/**/helpers/** and
+    // testcase/**/factories/** (the plan node writeSet globs).
+    const candidates = [];
+    for (const dir of ["testcase/helpers", "testcase/factories"]) {
+        const absolute = path.join(workspaceRoot, dir);
+        if (await exists(absolute)) {
+            for (const file of await listPythonFiles(absolute)) {
+                candidates.push(`${dir}/${file}`);
+            }
+        }
+    }
+    if (candidates.length === 0) {
+        issues.push({
+            code: "T3",
+            detail: "no shared helpers/factories were produced; pytest plan must emit at least one shared resource",
+            recoverable: true,
+        });
+    }
+    for (const rel of candidates) {
+        expectedPaths.push(rel);
+        actualPaths.push(rel);
+        const body = await readFile(path.join(workspaceRoot, rel), "utf8");
+        if (!looksLikeValidPythonModule(body)) {
+            brokenPaths.push(rel);
+            issues.push({
+                code: "T5",
+                path: rel,
+                detail: "shared pytest resource appears truncated or unparseable",
+                recoverable: true,
+            });
+        }
+    }
+    const targetPaths = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = targetPaths.length > 0 || issues.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role: "pytest-generate",
+        status,
+        expectedPaths: orderedUnique(expectedPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths,
+        issues,
+    };
 }

package/dist/workflows/dag/dynamic-runtime/map.js

@@ -27,6 +27,9 @@ export function buildExpandedChildTask(input) {
         forbiddenPaths: renderDynamicPatternList(child.forbiddenPaths, item, index, expansion.itemName) ?? [],
         writeSet: renderDynamicPatternList(child.writeSet, item, index, expansion.itemName),
         outputContract: child.outputContract,
+        writerOutcomePolicy: child.writerOutcomePolicy,
+        writeGuardPolicy: child.writeGuardPolicy,
+        retryPolicy: child.retryPolicy,
         static: child.executor === "static"
             ? { resultMarkdown: staticResult ?? "dynamic child completed" }
             : undefined,
@@ -305,11 +308,14 @@ export async function executeDynamicMapExpansion(input) {
         });
         const executedTokens = input.state.nodes[child.id]?.tokensUsed ?? 0;
         totalTokensUsed += executedTokens;
+        // Only a true total-budget ceiling exhausts the map and cascades SKIPPED
+        // onto remaining children. A single child exceeding maxTokensPerCase is
+        // a per-child concern (it still FINISHED/ERROR'd on its own); it must NOT
+        // starve sibling shards — otherwise the map-shard topology that gives
+        // each module an independent 16K budget degrades back to a shared pool.
         if (tokenBudget &&
-            ((tokenBudget.maxTokensPerCase !== undefined &&
-                executedTokens >= tokenBudget.maxTokensPerCase) ||
-                (tokenBudget.maxTotalTokens !== undefined &&
-                    totalTokensUsed >= tokenBudget.maxTotalTokens))) {
+            tokenBudget.maxTotalTokens !== undefined &&
+            totalTokensUsed >= tokenBudget.maxTotalTokens) {
             tokenBudgetExhausted = true;
         }
     }