@tea-agent/loop-agent 0.16.4 → 0.16.5

package/CHANGELOG.md

@@ -15,6 +15,12 @@
 - Pi SDK 执行长推理或大段结构化输出时不再把高频流式增量事件无界累积到内存；同一响应在多个生命周期事件中重复出现的 Token 用量只统计一次，避免 `Invalid string length` 和成本数据虚高。
 - 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为 initial/final Result、repair eligibility、traceability 与 Observe 投影保留结构化运行证据。
 
+## [0.16.5] - 2026-07-20
+
+### 修复
+
+- 后端测试分析/执行合同物化支持 free-form 环境侦察与 GWT/嵌套 endpoint 形状的严格 schema 归一化，避免 BE-TEST 在 contracts 门被模型字段漂移误拦。
+
 ## [0.16.4] - 2026-07-19
 
 ### 修复

package/dist/workflows/dag/backend-test-analysis-contract.js

@@ -108,25 +108,317 @@ export function extractStrictJsonObject(text) {
     }
     return JSON.parse(blocks[0][1]);
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function firstSourceRef(value, fallback = "source/需求.md") {
+    const record = asRecord(value);
+    if (!record)
+        return fallback;
+    if (typeof record.sourceRef === "string" && record.sourceRef.trim())
+        return record.sourceRef.trim();
+    const refs = asArray(record.sourceRefs).filter((item) => typeof item === "string" && item.trim().length > 0);
+    return refs[0]?.trim() || fallback;
+}
+function coerceField(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.name !== "string" || !record.name.trim())
+        return null;
+    const sourceRefs = asArray(record.sourceRefs).filter((item) => typeof item === "string" && item.trim().length > 0);
+    const field = {
+        name: record.name.trim(),
+        sourceRefs,
+    };
+    if (typeof record.type === "string" && record.type.trim())
+        field.type = record.type.trim();
+    if (typeof record.required === "boolean")
+        field.required = record.required;
+    if (typeof record.description === "string")
+        field.description = record.description;
+    else if (typeof record.notes === "string")
+        field.description = record.notes;
+    if (typeof record.format === "string" && record.format.trim())
+        field.format = record.format.trim();
+    if (record.comparison === "exact" || record.comparison === "parseable-only" || record.comparison === "semantic") {
+        field.comparison = record.comparison;
+    }
+    if (typeof record.precision === "string" && record.precision.trim())
+        field.precision = record.precision.trim();
+    return field;
+}
+function coerceAcceptanceCriterion(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.id !== "string" || !record.id.trim())
+        return null;
+    const textParts = [];
+    if (typeof record.text === "string" && record.text.trim())
+        textParts.push(record.text.trim());
+    else {
+        if (typeof record.title === "string" && record.title.trim())
+            textParts.push(record.title.trim());
+        const gwt = ["given", "when", "then"]
+            .map((key) => (typeof record[key] === "string" && record[key].trim() ? `${key}: ${String(record[key]).trim()}` : ""))
+            .filter(Boolean);
+        if (gwt.length)
+            textParts.push(gwt.join("; "));
+        else if (typeof record.description === "string" && record.description.trim())
+            textParts.push(record.description.trim());
+    }
+    const text = textParts.join(" — ").trim();
+    if (!text)
+        return null;
+    return { id: record.id.trim(), text, sourceRef: firstSourceRef(record) };
+}
+function coerceEndpoint(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.id !== "string" || !record.id.trim())
+        return null;
+    if (typeof record.method !== "string" || typeof record.path !== "string")
+        return null;
+    const method = record.method.trim().toUpperCase();
+    const pathValue = record.path.trim();
+    if (!pathValue.startsWith("/"))
+        return null;
+    const request = asRecord(record.request);
+    const successResponse = asRecord(record.successResponse);
+    const nestedBody = asRecord(successResponse?.responseBody) ?? asRecord(record.responseBody);
+    const requestFields = [
+        ...asArray(record.requestFields),
+        ...asArray(request?.headers),
+        ...asArray(request?.query),
+        ...asArray(request?.pathParams),
+    ]
+        .map(coerceField)
+        .filter((item) => item !== null);
+    const responseFields = [
+        ...asArray(record.responseFields),
+        ...asArray(successResponse?.fields),
+    ]
+        .map(coerceField)
+        .filter((item) => item !== null);
+    const successStatuses = asArray(record.successStatuses)
+        .map((item) => (typeof item === "number" ? item : Number.NaN))
+        .filter((item) => Number.isInteger(item) && item >= 100 && item <= 399);
+    if (typeof successResponse?.status === "number" && successResponse.status >= 100 && successResponse.status <= 399) {
+        successStatuses.push(successResponse.status);
+    }
+    const uniqueSuccess = [...new Set(successStatuses)];
+    const errorCases = [
+        ...asArray(record.errorCases),
+        ...asArray(record.errorResponses),
+    ]
+        .map((item) => {
+        const err = asRecord(item);
+        if (!err)
+            return null;
+        const description = (typeof err.description === "string" && err.description.trim()) ||
+            (typeof err.message === "string" && err.message.trim()) ||
+            (typeof err.code === "string" && err.code.trim()) ||
+            (typeof err.status === "number" ? `HTTP ${err.status}` : "");
+        if (!description)
+            return null;
+        const out = { description };
+        if (typeof err.status === "number" && err.status >= 400 && err.status <= 599)
+            out.status = err.status;
+        if (typeof err.code === "string" && err.code.trim())
+            out.code = err.code.trim();
+        if (typeof err.messageField === "string" && err.messageField.trim())
+            out.messageField = err.messageField.trim();
+        return out;
+    })
+        .filter((item) => item !== null);
+    const kind = nestedBody && typeof nestedBody.kind === "string" && ["array", "object", "scalar", "empty", "unknown"].includes(nestedBody.kind)
+        ? nestedBody.kind
+        : "unknown";
+    const ordering = nestedBody && typeof nestedBody.ordering === "string" && ["specified", "unspecified", "not-applicable"].includes(nestedBody.ordering)
+        ? nestedBody.ordering
+        : "unspecified";
+    const responseBody = { kind, ordering };
+    if (nestedBody && typeof nestedBody.itemSchemaRef === "string" && nestedBody.itemSchemaRef.trim()) {
+        responseBody.itemSchemaRef = nestedBody.itemSchemaRef.trim();
+    }
+    if (nestedBody && typeof nestedBody.description === "string" && nestedBody.description.trim()) {
+        responseBody.description = nestedBody.description.trim();
+    }
+    else if (nestedBody && typeof nestedBody.schemaRef === "string" && nestedBody.schemaRef.trim()) {
+        responseBody.description = `schemaRef=${nestedBody.schemaRef.trim()}`;
+    }
+    const sourceRefs = [
+        ...asArray(record.sourceRefs),
+        ...asArray(successResponse?.sourceRefs),
+    ].filter((item) => typeof item === "string" && item.trim().length > 0);
+    return {
+        id: record.id.trim(),
+        method,
+        path: pathValue,
+        requestFields,
+        responseFields,
+        responseBody,
+        successStatuses: uniqueSuccess.length ? uniqueSuccess : [200],
+        errorCases,
+        sourceRefs,
+    };
+}
+function coerceEvidencedIdItem(value, textKey) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const id = (typeof record.id === "string" && record.id.trim()) ||
+        (typeof record.name === "string" && record.name.trim()) ||
+        "";
+    if (!id)
+        return null;
+    const text = (typeof record[textKey] === "string" && String(record[textKey]).trim()) ||
+        (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        (typeof record.notes === "string" && record.notes.trim()) ||
+        (typeof record.title === "string" && record.title.trim()) ||
+        "";
+    if (!text)
+        return null;
+    return { id, [textKey]: text, sourceRef: firstSourceRef(record) };
+}
+function coerceBoundary(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const field = (typeof record.field === "string" && record.field.trim()) ||
+        (typeof record.id === "string" && record.id.trim()) ||
+        (typeof record.name === "string" && record.name.trim()) ||
+        "";
+    const constraint = (typeof record.constraint === "string" && record.constraint.trim()) ||
+        (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        "";
+    if (!field || !constraint)
+        return null;
+    return { field, constraint, sourceRef: firstSourceRef(record) };
+}
+const OPTIONAL_EVIDENCE_KNOWN_KEYS = new Set([
+    "name",
+    "id",
+    "description",
+    "notes",
+    "text",
+    "title",
+    "sourceRef",
+    "sourceRefs",
+    "severity",
+    "mitigation",
+    "level",
+    "impact",
+    "kind",
+    "required",
+]);
+function coerceOptionalEvidence(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    // Fail closed on unknown keys so near-schema payloads cannot strip extras and pass.
+    for (const key of Object.keys(record)) {
+        if (!OPTIONAL_EVIDENCE_KNOWN_KEYS.has(key)) {
+            throw new Error(`optional evidence has unrecognized key: ${key}`);
+        }
+    }
+    const description = (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.notes === "string" && record.notes.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        (typeof record.title === "string" && record.title.trim()) ||
+        "";
+    if (!description)
+        return null;
+    const out = { description };
+    const name = (typeof record.name === "string" && record.name.trim()) ||
+        (typeof record.id === "string" && record.id.trim()) ||
+        "";
+    if (name)
+        out.name = name;
+    const sourceRef = firstSourceRef(record, "");
+    if (sourceRef)
+        out.sourceRef = sourceRef;
+    return out;
+}
+function coerceEvidenceGap(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const description = (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        "";
+    if (!description)
+        return null;
+    const out = { description };
+    if (typeof record.requirementId === "string" && record.requirementId.trim())
+        out.requirementId = record.requirementId.trim();
+    else if (typeof record.acId === "string" && record.acId.trim())
+        out.requirementId = record.acId.trim();
+    const sourceRef = firstSourceRef(record, "");
+    if (sourceRef)
+        out.sourceRef = sourceRef;
+    return out;
+}
+/** Coerce common free-form model shapes into Backend Test Analysis v2 before strict parse. */
+export function coerceBackendTestAnalysisInput(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const next = { ...record, schemaVersion: 2 };
+    next.acceptanceCriteria = asArray(record.acceptanceCriteria)
+        .map(coerceAcceptanceCriterion)
+        .filter((item) => item !== null);
+    next.endpoints = asArray(record.endpoints)
+        .map(coerceEndpoint)
+        .filter((item) => item !== null);
+    next.dataModels = asArray(record.dataModels)
+        .map((item) => coerceEvidencedIdItem(item, "description"))
+        .filter((item) => item !== null);
+    next.businessRules = asArray(record.businessRules)
+        .map((item) => coerceEvidencedIdItem(item, "text"))
+        .filter((item) => item !== null);
+    next.stateTransitions = asArray(record.stateTransitions);
+    next.boundaryConstraints = asArray(record.boundaryConstraints)
+        .map(coerceBoundary)
+        .filter((item) => item !== null);
+    next.externalDependencies = asArray(record.externalDependencies)
+        .map(coerceOptionalEvidence)
+        .filter((item) => item !== null);
+    next.risks = asArray(record.risks)
+        .map(coerceOptionalEvidence)
+        .filter((item) => item !== null);
+    next.evidenceGaps = asArray(record.evidenceGaps)
+        .map(coerceEvidenceGap)
+        .filter((item) => item !== null);
+    return next;
+}
 function normalizeAnalysis(value) {
-    const v2 = backendTestAnalysisContractSchema.safeParse(value);
-    if (v2.success)
-        return v2.data;
-    const v1 = analysisV1Schema.safeParse(value);
-    if (!v1.success) {
-        throw new Error(v2.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+    const candidates = [value, coerceBackendTestAnalysisInput(value)];
+    let lastError = "invalid analysis contract";
+    for (const candidate of candidates) {
+        const v2 = backendTestAnalysisContractSchema.safeParse(candidate);
+        if (v2.success)
+            return v2.data;
+        lastError = v2.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+        const v1 = analysisV1Schema.safeParse(candidate);
+        if (v1.success) {
+            return backendTestAnalysisContractSchema.parse({
+                ...v1.data,
+                schemaVersion: 2,
+                endpoints: v1.data.endpoints.map((endpoint) => ({
+                    ...endpoint,
+                    requestFields: endpoint.requestFields.map((field) => ({ ...field, sourceRefs: [] })),
+                    responseFields: endpoint.responseFields.map((field) => ({ ...field, sourceRefs: [] })),
+                    responseBody: { kind: "unknown", ordering: "unspecified" },
+                    sourceRefs: [],
+                })),
+            });
+        }
     }
-    return backendTestAnalysisContractSchema.parse({
-        ...v1.data,
-        schemaVersion: 2,
-        endpoints: v1.data.endpoints.map((endpoint) => ({
-            ...endpoint,
-            requestFields: endpoint.requestFields.map((field) => ({ ...field, sourceRefs: [] })),
-            responseFields: endpoint.responseFields.map((field) => ({ ...field, sourceRefs: [] })),
-            responseBody: { kind: "unknown", ordering: "unspecified" },
-            sourceRefs: [],
-        })),
-    });
+    throw new Error(lastError);
 }
 function assertSourceBinding(contract, binding) {
     const requirement = binding.sources.find((source) => source.kind === "requirement");

package/dist/workflows/dag/backend-test-execution-contract.js

@@ -324,6 +324,171 @@ export function assertBackendTestExecutionPreflight(input) {
         workingDirectory,
     };
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Coerce free-form environment scout JSON into Backend Test Execution Contract v1.
+ * Prefer exact schema payloads; otherwise map common discovery shapes onto the
+ * pytest-centric runtime contract without inventing secrets or managed commands.
+ */
+export function coerceBackendTestExecutionInput(value) {
+    const direct = backendTestExecutionContractSchema.safeParse(value);
+    if (direct.success)
+        return direct.data;
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    // Near-schema payloads (string framework + runner + testRoot) must stay fail-closed.
+    // Only free-form discovery envelopes are rewritten onto the pytest contract.
+    const looksSchemaShaped = typeof record.framework === "string" &&
+        asRecord(record.runner) !== null &&
+        typeof record.testRoot === "string";
+    if (looksSchemaShaped)
+        return value;
+    if (typeof record.framework === "string" && record.framework !== "pytest") {
+        return value;
+    }
+    const frameworkObj = asRecord(record.framework);
+    const discovered = asRecord(record.discoveredFixtures);
+    const verification = asRecord(record.verification);
+    const layout = asRecord(record.repositoryLayout);
+    const environment = asRecord(record.environment);
+    const commandHints = [];
+    if (typeof record.primaryCommand === "string" && record.primaryCommand.trim()) {
+        commandHints.push(record.primaryCommand.trim());
+    }
+    if (frameworkObj && typeof frameworkObj.primaryCommand === "string" && frameworkObj.primaryCommand.trim()) {
+        commandHints.push(frameworkObj.primaryCommand.trim());
+    }
+    for (const item of Array.isArray(verification?.commands) ? verification.commands : []) {
+        if (typeof item === "string" && item.trim())
+            commandHints.push(item.trim());
+    }
+    if (commandHints.length === 0) {
+        commandHints.push(`python -m pytest ${BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT}/ -v`);
+    }
+    const existingFixtures = [];
+    for (const item of Array.isArray(record.existingFixtures) ? record.existingFixtures : []) {
+        const fixture = asRecord(item);
+        if (!fixture)
+            continue;
+        if (typeof fixture.name === "string" && typeof fixture.sourcePath === "string" && typeof fixture.kind === "string") {
+            existingFixtures.push({
+                name: fixture.name,
+                sourcePath: fixture.sourcePath,
+                kind: fixture.kind,
+            });
+        }
+    }
+    if (existingFixtures.length === 0 && discovered) {
+        const bootstrap = asRecord(discovered.serverBootstrap);
+        if (bootstrap && typeof bootstrap.module === "string" && bootstrap.module.trim()) {
+            existingFixtures.push({
+                name: typeof bootstrap.symbol === "string" && bootstrap.symbol.trim()
+                    ? bootstrap.symbol.trim()
+                    : "server-bootstrap",
+                sourcePath: bootstrap.module.trim(),
+                kind: "server-bootstrap",
+            });
+        }
+        for (const key of ["auth", "database", "remoteServices"]) {
+            const val = discovered[key];
+            if (typeof val === "string" && val.trim() && val.trim() !== "none") {
+                existingFixtures.push({
+                    name: key,
+                    sourcePath: ".",
+                    kind: val.trim(),
+                });
+            }
+        }
+    }
+    if (existingFixtures.length === 0) {
+        // Fail-closed in-process contract still needs one fixture entry; use default test root as a non-secret anchor.
+        existingFixtures.push({
+            name: "pytest-test-root",
+            sourcePath: BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT,
+            kind: "test-root",
+        });
+    }
+    const authenticationMode = (typeof record.authenticationMode === "string" && record.authenticationMode.trim()) ||
+        (typeof discovered?.auth === "string" && discovered.auth.trim()) ||
+        "none";
+    const evidenceRefs = [];
+    for (const item of Array.isArray(record.evidenceRefs) ? record.evidenceRefs : []) {
+        if (typeof item === "string" && item.trim())
+            evidenceRefs.push(item.trim());
+    }
+    if (layout) {
+        for (const key of [
+            "apiContractDoc",
+            "routeImplementation",
+            "serviceImplementation",
+            "serverEntry",
+        ]) {
+            const val = layout[key];
+            if (typeof val === "string" && val.trim())
+                evidenceRefs.push(val.trim());
+        }
+        for (const item of Array.isArray(layout.existingApiTests) ? layout.existingApiTests : []) {
+            if (typeof item === "string" && item.trim())
+                evidenceRefs.push(item.trim());
+        }
+    }
+    const targetMode = record.targetMode === "external-running-service" ||
+        record.targetMode === "managed-command" ||
+        record.targetMode === "in-process"
+        ? record.targetMode
+        : "in-process";
+    const coerced = {
+        schemaVersion: 1,
+        framework: "pytest",
+        runner: {
+            frozenCommandHints: [...new Set(commandHints)],
+        },
+        testRoot: (typeof record.testRoot === "string" && record.testRoot.trim()) ||
+            BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT,
+        workingDirectory: (typeof record.workingDirectory === "string" && record.workingDirectory.trim()) ||
+            ".",
+        report: asRecord(record.report) ?? {
+            format: "junit",
+            relativeHint: "reports/backend-test-junit.xml",
+        },
+        targetMode,
+        existingFixtures,
+        authenticationMode,
+        requiredEnvNames: Array.isArray(record.requiredEnvNames)
+            ? record.requiredEnvNames.filter((item) => typeof item === "string" && item.trim().length > 0)
+            : [],
+        dataIsolation: asRecord(record.dataIsolation) ?? {
+            mode: "ephemeral-local",
+            evidence: "coerced from free-form environment scout; no durable shared fixtures",
+        },
+        evidenceGaps: Array.isArray(record.evidenceGaps) ? record.evidenceGaps : [],
+        evidenceRefs: [...new Set(evidenceRefs)],
+    };
+    if (typeof record.baseUrlEnvName === "string" && record.baseUrlEnvName.trim()) {
+        coerced.baseUrlEnvName = record.baseUrlEnvName.trim();
+    }
+    if (Array.isArray(record.readiness))
+        coerced.readiness = record.readiness;
+    if (asRecord(record.managedCommand))
+        coerced.managedCommand = record.managedCommand;
+    // Preserve free-form discovery notes as non-blocking evidence gaps when useful.
+    if (frameworkObj &&
+        typeof frameworkObj.testRunner === "string" &&
+        frameworkObj.testRunner !== "pytest") {
+        const gaps = Array.isArray(coerced.evidenceGaps) ? [...coerced.evidenceGaps] : [];
+        gaps.push({
+            description: `environment scout reported testRunner=${frameworkObj.testRunner}; runtime contract remains pytest with default testRoot=${BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT}`,
+            sourceRef: typeof environment?.cwd === "string" ? "package.json" : "source/需求.md",
+        });
+        coerced.evidenceGaps = gaps;
+    }
+    return coerced;
+}
 export async function materializeBackendTestExecutionContract(input) {
     if (!/^[a-z0-9][a-z0-9._-]*\.json$/.test(input.artifactName) ||
         !/^[a-z0-9][a-z0-9._-]*$/.test(input.outputDir)) {
@@ -339,17 +504,29 @@ export async function materializeBackendTestExecutionContract(input) {
     catch (error) {
         throw new Error(`invalid-output: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const secrets = secretIssues(parsed);
-    if (secrets.length) {
-        throw new Error(`invalid-output: ${secrets.join("; ")}`);
-    }
-    const result = backendTestExecutionContractSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new Error(`invalid-output: ${result.error.issues
+    const candidates = [parsed, coerceBackendTestExecutionInput(parsed)];
+    let accepted = null;
+    let lastSchemaError = "invalid execution contract";
+    let lastSecretError = "";
+    for (const candidate of candidates) {
+        const secrets = secretIssues(candidate);
+        if (secrets.length) {
+            lastSecretError = secrets.join("; ");
+            continue;
+        }
+        const result = backendTestExecutionContractSchema.safeParse(candidate);
+        if (result.success) {
+            accepted = result.data;
+            break;
+        }
+        lastSchemaError = result.error.issues
             .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
-            .join("; ")}`);
+            .join("; ");
+    }
+    if (!accepted) {
+        throw new Error(`invalid-output: ${lastSecretError || lastSchemaError}`);
     }
-    const normalized = normalizeContractPaths(result.data);
+    const normalized = normalizeContractPaths(accepted);
     // evidenceGaps may record greenfield/incomplete discovery (no test_*.py yet,
     // missing pytest.ini, projected schema path, etc.). Do not block materialize:
     // generate-functional-cases / generate-pytest are expected to fill automation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.16.4",
+  "version": "0.16.5",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",