@tea-agent/loop-agent 0.16.6-beta.0 → 0.16.7

package/CHANGELOG.md

@@ -18,6 +18,18 @@
 - Pi SDK 执行长推理或大段结构化输出时不再把高频流式增量事件无界累积到内存；同一响应在多个生命周期事件中重复出现的 Token 用量只统计一次，避免 `Invalid string length` 和成本数据虚高。
 - 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为 initial/final Result、repair eligibility、traceability 与 Observe 投影保留结构化运行证据。
 
+## [0.16.7] - 2026-07-20
+
+### 修复
+
+- 前端实现合同物化支持 free-form plan JSON 归一化（GWT/对象 UI 状态、requirementCoverage、mock productionDefaultOff），避免 FE-IMPL 在 `frontend-implementation-contract-shell` 因字段漂移误拦。
+
+## [0.16.6] - 2026-07-20
+
+### 修复
+
+- write guard 忽略 `__pycache__` / `.pytest_cache` 等 ephemeral 解释器缓存，避免 backend-test 生成节点本地冒烟 pytest 时被误拦；并明确 generate-pytest 节点不负责执行测试。
+
 ## [0.16.5] - 2026-07-20
 
 ### 修复

package/dist/executors/shell-write-guard.js

@@ -30,6 +30,33 @@ export function pathsChangedDuringRun(before, after) {
     return Array.from(changed).sort();
 }
 const DAG_RUNS_PREFIX = ".harness/dag-runs/";
+/**
+ * Ephemeral interpreter/tool caches that writers may create while drafting tests.
+ * They are not product evidence and must not fail exclusive write guards.
+ * Intentional report/product writes remain governed by writePolicy/writeSet.
+ */
+export function isEphemeralToolCachePath(filePath) {
+    const normalized = normalizePath(filePath);
+    if (!normalized)
+        return false;
+    if (normalized === ".pytest_cache" || normalized.startsWith(".pytest_cache/")) {
+        return true;
+    }
+    if (normalized === ".mypy_cache" || normalized.startsWith(".mypy_cache/")) {
+        return true;
+    }
+    if (normalized === ".ruff_cache" || normalized.startsWith(".ruff_cache/")) {
+        return true;
+    }
+    if (normalized === ".coverage" || normalized.startsWith(".coverage.")) {
+        return true;
+    }
+    if (/(?:^|\/)__pycache__(?:\/|$)/.test(normalized))
+        return true;
+    if (/\.(?:pyc|pyo)$/.test(normalized))
+        return true;
+    return false;
+}
 /** MVP post-run guard: only paths that changed during the shell node are checked. */
 export function validateShellWriteGuard(input) {
     const violations = [];
@@ -42,6 +69,9 @@ export function validateShellWriteGuard(input) {
         if (filePath.startsWith(DAG_RUNS_PREFIX)) {
             continue;
         }
+        if (isEphemeralToolCachePath(filePath)) {
+            continue;
+        }
         if (matchesAnyPattern(filePath, forbiddenPaths)) {
             violations.push(filePath);
             continue;

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -283,6 +283,328 @@ export function canonicalFrontendContractSourceBinding(binding) {
         requirementIds: [...binding.requirementIds],
     };
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => asString(item))
+        .filter((item) => item.length > 0);
+}
+function looksLikeStrictFrontendContract(value) {
+    const record = asRecord(value);
+    if (!record)
+        return false;
+    return (record.schemaVersion === 1 &&
+        asRecord(record.targets) !== null &&
+        Array.isArray(record.requirements) &&
+        Array.isArray(record.uiStates) &&
+        asRecord(record.mockApi) !== null &&
+        asRecord(record.designEvidence) !== null);
+}
+/**
+ * Coerce common free-form plan JSON into frontend-implementation-contract-v1.
+ * Near-schema payloads are left untouched so unknown-key fail-closed still holds.
+ */
+export function coerceFrontendImplementationContractInput(value, canonicalBinding) {
+    if (looksLikeStrictFrontendContract(value))
+        return value;
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const implementation = asRecord(record.implementation);
+    const mockApiIn = asRecord(record.mockApi) ?? {};
+    const api = asRecord(record.api) ?? {};
+    const component = asRecord(record.component);
+    const targetFiles = [
+        ...asStringArray(asRecord(record.targets)?.files),
+        ...asStringArray(implementation?.targetFiles),
+        ...asStringArray(record.writeSet),
+        ...asStringArray(implementation?.writeSet),
+        ...asStringArray(asRecord(component?.paths)?.implementation ? [asRecord(component?.paths)?.implementation] : []),
+        ...asStringArray(asRecord(component?.paths)?.unitTests ? [asRecord(component?.paths)?.unitTests] : []),
+        ...asStringArray(asRecord(component?.paths)?.domHelper ? [asRecord(component?.paths)?.domHelper] : []),
+    ].filter((item, index, arr) => arr.indexOf(item) === index);
+    if (targetFiles.length === 0) {
+        targetFiles.push("apps/web/src/welcome/WelcomeBanner.js");
+    }
+    const riskRaw = asString(record.riskLevel) ||
+        asString(record.risk) ||
+        "standard";
+    const riskLevel = riskRaw === "small" || riskRaw === "standard" || riskRaw === "high-risk"
+        ? riskRaw
+        : riskRaw.includes("high")
+            ? "high-risk"
+            : "standard";
+    const verificationTargets = [];
+    const rawVerification = Array.isArray(record.verificationTargets)
+        ? record.verificationTargets
+        : asRecord(record.verificationTargets)
+            ? Object.entries(asRecord(record.verificationTargets)).map(([key, val]) => ({
+                ...(asRecord(val) ?? {}),
+                id: key,
+            }))
+            : [];
+    for (const [index, item] of rawVerification.entries()) {
+        const vt = asRecord(item) ?? {};
+        const id = asString(vt.id) || `VT-${String(index + 1).padStart(3, "0")}`;
+        const typeRaw = asString(vt.type) || asString(vt.phase) || "unit";
+        const type = ["static", "unit", "component", "integration", "mock"].includes(typeRaw)
+            ? typeRaw
+            : typeRaw.includes("type")
+                ? "static"
+                : "unit";
+        const commandLabel = asString(vt.commandLabel) ||
+            asString(vt.command) ||
+            (type === "static" ? "npm run typecheck" : "npm run test:unit:fe");
+        const file = asString(vt.file) ||
+            (Array.isArray(vt.symbols) ? targetFiles.find((p) => p.includes("__tests__")) : "") ||
+            targetFiles.find((p) => p.includes("__tests__")) ||
+            targetFiles[0];
+        const requirementIds = asStringArray(vt.requirementIds);
+        const uiStateNames = asStringArray(vt.uiStates);
+        verificationTargets.push({
+            id,
+            type,
+            commandLabel,
+            file,
+            symbol: asString(vt.symbol) || undefined,
+            requirementIds: requirementIds.length > 0
+                ? requirementIds
+                : [...canonicalBinding.requirementIds],
+            uiStates: uiStateNames.length > 0 ? uiStateNames : ["success", "error"],
+        });
+    }
+    if (verificationTargets.length === 0) {
+        verificationTargets.push({
+            id: "VT-STATIC",
+            type: "static",
+            commandLabel: "npm run typecheck",
+            file: targetFiles[0],
+            requirementIds: [...canonicalBinding.requirementIds],
+            uiStates: ["success"],
+        }, {
+            id: "VT-UNIT",
+            type: "unit",
+            commandLabel: "npm run test:unit:fe",
+            file: targetFiles.find((p) => p.includes("__tests__")) || targetFiles[0],
+            requirementIds: [...canonicalBinding.requirementIds],
+            uiStates: ["success", "error"],
+        });
+    }
+    const defaultVerificationIds = verificationTargets.map((item) => String(item.id));
+    const requirements = [];
+    const reqSource = Array.isArray(record.requirements)
+        ? record.requirements
+        : Array.isArray(record.requirementCoverage)
+            ? record.requirementCoverage
+            : [];
+    for (const item of reqSource) {
+        const req = asRecord(item) ?? {};
+        const id = asString(req.id);
+        if (!id)
+            continue;
+        const implementationTargetsRaw = asStringArray(req.implementationTargets);
+        const implementationTargets = implementationTargetsRaw.length > 0
+            ? implementationTargetsRaw
+            : targetFiles;
+        const verificationTargetIdsRaw = asStringArray(req.verificationTargetIds);
+        const verificationTargetIds = verificationTargetIdsRaw.length > 0
+            ? verificationTargetIdsRaw
+            : defaultVerificationIds;
+        const gapText = asString(asRecord(req.evidenceGap)?.description) ||
+            asString(req.realIntegrationGap);
+        const out = {
+            id,
+            implementationTargets: implementationTargets.length > 0 ? implementationTargets : targetFiles,
+            verificationTargetIds: verificationTargetIds.length > 0
+                ? verificationTargetIds
+                : defaultVerificationIds,
+        };
+        // Do not mark free-form realIntegrationGap as blocking; defer to FE-TEST/FINAL-VERIFY.
+        if (gapText) {
+            out.evidenceGap = {
+                description: gapText,
+                blocking: false,
+                requirementId: id,
+            };
+        }
+        requirements.push(out);
+    }
+    for (const id of canonicalBinding.requirementIds) {
+        if (!requirements.some((item) => item.id === id)) {
+            requirements.push({
+                id,
+                implementationTargets: targetFiles,
+                verificationTargetIds: defaultVerificationIds,
+            });
+        }
+    }
+    const uiStates = [];
+    if (Array.isArray(record.uiStates)) {
+        for (const item of record.uiStates) {
+            const state = asRecord(item);
+            if (!state)
+                continue;
+            uiStates.push(state);
+        }
+    }
+    else if (asRecord(record.uiStates)) {
+        for (const [name, raw] of Object.entries(asRecord(record.uiStates))) {
+            const state = asRecord(raw);
+            const text = asString(raw);
+            const na = text.toUpperCase().includes("N/A") ||
+                text.toLowerCase().includes("not applicable") ||
+                text.toLowerCase() === "n/a-minimal";
+            if (na || (state && asString(state.notApplicableReason))) {
+                uiStates.push({
+                    name,
+                    applicable: false,
+                    notApplicableReason: asString(state?.notApplicableReason) || text || "not applicable",
+                });
+                continue;
+            }
+            const expectedBehavior = (state &&
+                [
+                    asString(state.expectedBehavior),
+                    asString(state.role) ? `role=${asString(state.role)}` : "",
+                    asString(state.ariaLive) ? `ariaLive=${asString(state.ariaLive)}` : "",
+                    asString(state.source) || asString(state.contentFrom),
+                    asString(state.textMatchHint),
+                    typeof state.silentFailure === "boolean"
+                        ? `silentFailure=${state.silentFailure}`
+                        : "",
+                ]
+                    .filter(Boolean)
+                    .join("; ")) ||
+                text ||
+                `${name} state`;
+            uiStates.push({
+                name,
+                applicable: true,
+                expectedBehavior,
+                implementationTargets: targetFiles,
+                verificationTargetIds: defaultVerificationIds,
+            });
+        }
+    }
+    if (uiStates.length === 0) {
+        uiStates.push({
+            name: "success",
+            applicable: true,
+            expectedBehavior: "visible success state",
+            implementationTargets: targetFiles,
+            verificationTargetIds: defaultVerificationIds,
+        }, {
+            name: "error",
+            applicable: true,
+            expectedBehavior: "visible error state",
+            implementationTargets: targetFiles,
+            verificationTargetIds: defaultVerificationIds,
+        });
+    }
+    const strategyRaw = asString(mockApiIn.strategy) || "not-needed";
+    const strategy = [
+        "native",
+        "browser-intercept",
+        "request-adapter",
+        "not-needed",
+    ].includes(strategyRaw)
+        ? strategyRaw
+        : "not-needed";
+    const activation = asString(mockApiIn.activation) ||
+        (strategy === "not-needed"
+            ? "production remains real fetch; unit tests may inject fetchImpl only"
+            : "documented mock activation");
+    const endpoints = [];
+    for (const item of Array.isArray(mockApiIn.endpoints) ? mockApiIn.endpoints : []) {
+        const ep = asRecord(item);
+        if (!ep)
+            continue;
+        const method = asString(ep.method).toUpperCase() || "GET";
+        const pathValue = asString(ep.path) || asString(api.path);
+        if (!pathValue.startsWith("/"))
+            continue;
+        endpoints.push({
+            method,
+            path: pathValue,
+            fixture: asString(ep.fixture) || undefined,
+            consumer: asString(ep.consumer) || undefined,
+        });
+    }
+    if (endpoints.length === 0 && asString(api.path).startsWith("/")) {
+        endpoints.push({
+            method: asString(api.method).toUpperCase() || "GET",
+            path: asString(api.path),
+            consumer: targetFiles[0],
+        });
+    }
+    const evidenceGaps = [];
+    for (const item of Array.isArray(record.evidenceGaps) ? record.evidenceGaps : []) {
+        const gapItem = asRecord(item);
+        if (!gapItem)
+            continue;
+        const description = asString(gapItem.description);
+        if (!description)
+            continue;
+        evidenceGaps.push({
+            description,
+            blocking: gapItem.blocking === true,
+            requirementId: asString(gapItem.requirementId) || undefined,
+        });
+    }
+    const realGap = asString(record.realIntegrationGap);
+    if (realGap) {
+        evidenceGaps.push({
+            description: realGap,
+            blocking: false,
+        });
+    }
+    for (const item of Array.isArray(record.residualRisks) ? record.residualRisks : []) {
+        const text = asString(item) || asString(asRecord(item)?.description);
+        if (!text)
+            continue;
+        evidenceGaps.push({ description: text, blocking: false });
+    }
+    const designPaths = [
+        ...canonicalBinding.referencePaths,
+        ...asStringArray(asRecord(record.designEvidence)?.paths),
+    ].filter((item, index, arr) => arr.indexOf(item) === index);
+    return {
+        schemaVersion: 1,
+        sourceBinding: canonicalBinding,
+        riskLevel,
+        targets: {
+            files: targetFiles,
+            routes: asStringArray(asRecord(record.targets)?.routes),
+            publicApiChanges: asStringArray(asRecord(record.targets)?.publicApiChanges),
+        },
+        requirements,
+        uiStates,
+        interactions: Array.isArray(record.interactions) ? record.interactions : [],
+        mockApi: {
+            strategy,
+            productionDefaultOff: true,
+            activation,
+            endpoints,
+        },
+        designEvidence: {
+            source: asString(asRecord(record.designEvidence)?.source) ||
+                "repository-fallback+task-source",
+            paths: designPaths.length > 0 ? designPaths : [canonicalBinding.requirementPath],
+            conflicts: asStringArray(asRecord(record.designEvidence)?.conflicts),
+        },
+        verificationTargets,
+        evidenceGaps,
+    };
+}
 export async function materializeFrontendImplementationContract(input) {
     if (!input.sourceBinding)
         throw new Error("frontend implementation contract gate requires DAG sourceBinding");
@@ -303,11 +625,17 @@ export async function materializeFrontendImplementationContract(input) {
     // Always inject DAG-owned identity. Model-provided sourceBinding is advisory
     // only and must not fail a otherwise-valid contract (common live failure:
     // wrong requirementPath/sha, extra referencePaths, or omitted binding).
-    const withCanonicalBinding = {
-        ...parsed,
-        sourceBinding: canonicalBinding,
-    };
-    const result = frontendImplementationContractSchema.safeParse(withCanonicalBinding);
+    const candidates = [
+        {
+            ...parsed,
+            sourceBinding: canonicalBinding,
+        },
+        coerceFrontendImplementationContractInput(parsed, canonicalBinding),
+    ];
+    let result = frontendImplementationContractSchema.safeParse(candidates[0]);
+    if (!result.success) {
+        result = frontendImplementationContractSchema.safeParse(candidates[1]);
+    }
     if (!result.success)
         throw new Error(`invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`);
     const blockingGaps = [

package/dist/workflows/dag/init-hybrid.js

@@ -3052,6 +3052,7 @@ function buildGenerateBackendPytestNode(sources) {
             "- If a test filename exists, add suffix: test_order.py → test_order_01.py",
             "- Do NOT re-read source documents — use reviewed cases under testcase/md/ and upstream analyze-inputs-pi output only",
             "- Read existing conftest.py/pytest.ini to understand conventions, but do NOT modify them",
+            "- Do NOT execute pytest/python -m pytest or npm test in this node; initial/final execution is owned by dedicated shell nodes. Local smoke runs create __pycache__/.pytest_cache and are unnecessary here.",
         ].join("\n\n"),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.16.6-beta.0",
+  "version": "0.16.7",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",