@tea-agent/loop-agent 0.39.0-next.3 → 0.39.0-next.4

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "version": "0.37.0",
-  "gitSha": "944355b6e1204f12ebd4a7b0cc9c52fabff8ff97",
-  "builtAt": "2026-08-17T09:28:57.068Z"
+  "gitSha": "2151d87d0e2ad4aaab0dd6a894945df8cf59d940",
+  "builtAt": "2026-08-17T11:03:51.721Z"
 }

package/dist/executors/dag-pi-executor.js

@@ -1043,6 +1043,7 @@ export function mapPiResultToDagNodeResult(result, firstProtocolLine) {
         sdkAttempted: result.sdkAttempted,
         tokensUsed: result.tokensUsed,
         parsedEvents: result.parsedEvents,
+        stopReason: readWriterThinkingExhaustionEvidence(result).stopReason,
     };
 }
 function canonicalizeProtocolFirstLine(assistantText, firstProtocolLine) {

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

@@ -20,6 +20,7 @@ import { applySddEmbeddedEnhancements, probeRepoLocalSddSkills, } from "./sdd-em
 import { discoverProjectGovernancePresence } from "./project-governance-context.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { materializeTaskReferenceDocs } from "../../task/source-references.js";
+import { REQUIREMENT_FACT_ROLES } from "../../task/source-prepare/artifact-meta.js";
 import { observeTaskContract } from "../../task/contract/observe.js";
 import { dagHasWriterExecution } from "./task-contract-binding.js";
 import { DEFAULT_VERIFY_TIMEOUT_MS, resolveVerifyPreset, } from "../../executors/shell-verification.js";
@@ -1499,11 +1500,27 @@ function buildSourceContextBlock(sources) {
             .relative(path.join(sources.taskDir, "source"), reference.path)
             .replaceAll(path.sep, "/");
         const referenceRef = toDagSourcePath(sources, reference.path);
-        const referenceExcerpt = excerptMarkdown(reference.markdown, {
-            sourceRef: referenceRef,
-        });
-        boundReadPaths.push(`- reference ${relativePath}: ${referenceRef}`);
-        parts.push(`## Task source reference: ${relativePath}`, `Bound readPath (use for Pi read-tool calls): ${referenceRef}`, referenceExcerpt.text);
+        // Fact-source roles (requirement/acceptance) carry the fields contracts
+        // depend on (AC/scope/columns). Inject them in full so a fixed excerpt
+        // cannot silently drop definitions; archival roles stay excerpted.
+        const isFactRole = reference.role !== undefined &&
+            REQUIREMENT_FACT_ROLES.has(reference.role);
+        const referenceExcerpt = isFactRole
+            ? {
+                text: reference.markdown.trim(),
+                truncated: false,
+                originalChars: reference.markdown.trim().length,
+                maxChars: Number.POSITIVE_INFINITY,
+            }
+            : excerptMarkdown(reference.markdown, {
+                sourceRef: referenceRef,
+            });
+        boundReadPaths.push(`- reference ${relativePath}${isFactRole ? " (full source)" : ""}: ${referenceRef}`);
+        parts.push(`## Task source reference: ${relativePath}`, `Bound readPath (use for Pi read-tool calls): ${referenceRef}`, ...(isFactRole
+            ? [
+                `Full source injected (role: ${reference.role}) — complete and authoritative; no excerpt truncation applied.`,
+            ]
+            : []), referenceExcerpt.text);
     }
     parts.push("## Bound source read paths", ...boundReadPaths, "Use these repository-readable paths for any Pi read-tool calls. Bound files under `.harness/tasks/<taskId>/source/**` are read-only inputs: reading them is allowed even though writing `.harness/**` is forbidden.", "Never resolve task-relative citations such as `source/需求.md` or `source/references/*` against the repository root, invent `source/<taskId>/...`, search for substitutes, or fall back to `docs/**` when a bound read fails.", "## Task config summary", `- taskId: ${sources.taskConfig.taskId}`, `- flow: ${sources.taskConfig.flow}`, `- complexity: ${sources.taskConfig.complexity}`, `- contextProfile: ${sources.taskConfig.contextProfile}`, `- allowedPaths: ${sources.taskConfig.allowedPaths.join(", ") || "(none — review before execute)"}`, `- forbiddenPaths: ${sources.taskConfig.forbiddenPaths.join(", ") || "(none)"}`, '- Pi DAG nodes are read-only unless toolProfile="write" is explicitly selected for a bounded writer node.', "- Agent DAG read-only nodes must not write root artifacts/**; root artifacts/ is not a per-node scratchpad.", `- Derived execution contract and immutable references live under the Bound source read paths above (not as repo-root \`source/...\`).`);
     if (sources.taskConfig.hardConstraints.length > 0) {
@@ -1541,10 +1558,49 @@ async function loadMaterializedSourceReferences(sourceDir) {
     }
     await collect(referenceDir);
     referencePaths.sort((left, right) => left.localeCompare(right));
-    return Promise.all(referencePaths.map(async (filePath) => ({
-        path: filePath,
-        markdown: await readFile(filePath, "utf-8"),
-    })));
+    const roleByPath = await loadReferenceRoles(sourceDir);
+    return Promise.all(referencePaths.map(async (filePath) => {
+        const relative = path
+            .relative(sourceDir, filePath)
+            .replaceAll(path.sep, "/");
+        const role = roleByPath.get(relative);
+        return {
+            path: filePath,
+            markdown: await readFile(filePath, "utf-8"),
+            ...(role !== undefined ? { role } : {}),
+        };
+    }));
+}
+/**
+ * Reads `source-manifest.json` into a materializedPath → role map so the DAG
+ * generator can tell fact-source references (requirement/acceptance) apart
+ * from archival ones (analysis/clarification/design). A missing or malformed
+ * manifest yields an empty map; such references keep the bounded-excerpt
+ * treatment instead of being injected in full.
+ */
+async function loadReferenceRoles(sourceDir) {
+    const roleByPath = new Map();
+    const manifestPath = path.join(sourceDir, "source-manifest.json");
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf-8");
+    }
+    catch {
+        return roleByPath;
+    }
+    try {
+        const manifest = JSON.parse(raw);
+        for (const document of manifest.documents ?? []) {
+            if (typeof document.materializedPath === "string" &&
+                typeof document.role === "string") {
+                roleByPath.set(document.materializedPath.replaceAll(path.sep, "/"), document.role);
+            }
+        }
+    }
+    catch {
+        // A malformed manifest must never break reference injection.
+    }
+    return roleByPath;
 }
 export async function loadTaskHybridSources(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
@@ -2463,6 +2519,11 @@ async function buildFrontendHybridDagFromTask(sources) {
         `Non-static targets (type unit/component/integration/mock) MUST set file to a concrete code file inside the implementation writeSet (task allowedPaths); the prewrite gate rejects any non-static target whose file falls outside the writeSet.`,
         `Command-level checks that run project-wide (all tests, typecheck, build, governance) MUST use type "static" and must NOT be bound as non-static targets with file=package.json/tsconfig.json/vite.config.ts/scripts/*. Static targets are exempt from the writeSet containment check.`,
     ].join("\n");
+    const mandatorySourceReadInstruction = [
+        "## Mandatory full source read before contracting",
+        "Before producing this contract/plan, use the Pi read tool to read the FULL bound source files (需求.md, 执行约束.md, and every `references/*` Bound readPath listed above) — the inline copies above may be truncated excerpts, and requirement/acceptance references are authoritative only in their full form.",
+        "Do not drop scope fields, acceptance criteria, non-goals, UI states, or column/field definitions that exist in the full sources but are absent from the inline excerpts; if a field appears in the full source, it belongs in the contract.",
+    ].join("\n");
     const strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
     const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
@@ -2648,6 +2709,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read task source and produce a concise frontend implementation contract.",
                     "Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations.",
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    mandatorySourceReadInstruction,
                     sourceContext,
                 ].join("\n\n"),
             },
@@ -2687,19 +2749,20 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Markdown implementation plan with Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks, ending with exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once and must not contain or be followed by any raw JSON or extra fenced block. No file writes.",
+                outputContract: "One-line lead-in, then exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. After the citation block, an optional Markdown explanation may follow covering Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks; this explanation may be omitted and may be truncated, and must not be placed before the contract JSON. Apart from the contract JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
                 subtask_prompt: [
                     "Based on frontend-contract-pi, frontend-scout-pi, task sources, and the generation-time Mock capability evidence, return a minimal frontend implementation plan.",
                     "Select the Mock / API strategy inside the plan and structured contract. Carry endpoint/fixture mapping, explicit activation, production-default-off rule, verification commands, and Real Integration Gap into both outputs.",
                     "Include ordered steps, target files, UI state handling, styling/component strategy, interaction notes, Mock/API strategy, dependency policy, deterministic verification entrypoints, and residual risks. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
                     "Every target file and verification target must be selected from the current target workspace and task scope. Do not reuse paths or symbols from examples, prior tasks, or loop-agent itself; if the project uses app/, packages/, spec/, __tests__, or another layout, preserve that layout.",
                     "Consume the Scout TARGET_SURFACE evidence before selecting files. Preserve the discovered existing entrypoint and data source. If implementationPaths or testPaths are outside task allowedPaths, record a blocking scope conflict; do not substitute a new page or silently broaden the writeSet.",
-                    "End with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response; the plan text must not contain other balanced JSON objects.",
+                    "Output in this exact order: (1) exactly one fenced json object conforming to frontend-implementation-contract-v1 — this fenced block is the single authoritative contract the prewrite gate materializes; (2) exactly one openspec-citations citation fenced block appended immediately after it; (3) optional Markdown explanation. The Markdown explanation may be omitted and may be truncated; never place evidence excerpts, duplicated upstream context, or long prose before the contract JSON. Do not emit any raw JSON or JSON objects in prose. Apart from the single contract JSON fenced block and the openspec-citations block, do not emit any other fenced block.",
                     "Each requirement must state its user-observable or logic-observable expectedOutcome. Each interaction must state its trigger and expectedBehavior. IDs plus file paths are not sufficient behavior semantics.",
                     requirementCoverageInstruction,
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     verificationTargetFileInstruction,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    mandatorySourceReadInstruction,
                     fixedVerificationContext,
                     sourceContext,
                     mockContextBlock,
@@ -2747,7 +2810,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "When the initial design review requests revision, return a complete Markdown revision plan followed by exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once and must not contain or be followed by any raw JSON or extra fenced block. Do NOT include multiple fenced JSON blocks; only the single authoritative contract JSON block is accepted. No file writes.",
+                outputContract: "When the initial design review requests revision, return a one-line lead-in followed by exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. After the citation block, an optional Markdown revision plan explanation may follow covering Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks; this explanation may be omitted and may be truncated, and must not be placed before the contract JSON. Apart from the contract JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
                 subtask_prompt: [
                     "Consume frontend-plan-pi (original plan) and frontend-design-review-pi (first design review findings).",
                     "This node runs only when frontend-design-review-pi emitted VERDICT: request-revision. Produce a complete revised implementation plan that addresses every Required Plan Correction from the design findings.",
@@ -2755,7 +2818,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     requirementCoverageInstruction,
                     "Do not turn MOCK_STRATEGY: blocked into an implementable strategy without new repository or contract evidence that resolves every blocker.",
                     "Read-only: do not modify code, docs, artifacts, or repository files. This node revises the plan only.",
-                    "End the response with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer when the design review requests revision: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response. Bind it to the supplied task sources; map every requirement and applicable UI state to concrete implementation and verification targets or an explicit blocking evidence gap. Do not include secrets or unsafe paths.",
+                    "Output in this exact order: (1) exactly one fenced json object conforming to frontend-implementation-contract-v1 — this fenced block is the single authoritative contract the prewrite gate materializes; (2) exactly one openspec-citations citation fenced block appended immediately after it; (3) optional Markdown explanation. The Markdown explanation may be omitted and may be truncated; never place evidence excerpts, duplicated upstream context, or long prose before the contract JSON. Bind the contract to the supplied task sources; map every requirement and applicable UI state to concrete implementation and verification targets or an explicit blocking evidence gap. Do not emit any raw JSON or JSON objects in prose. Apart from the single contract JSON fenced block and the openspec-citations block, do not emit any other fenced block. Do not include secrets or unsafe paths.",
                     "Preserve each requirement expectedOutcome and each interaction trigger/expectedBehavior in the revised contract; do not reduce behavior semantics to IDs and paths.",
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     verificationTargetFileInstruction,

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

@@ -152,6 +152,20 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             previousProtocolReason,
             "Return exactly one fenced json block conforming to the frontend-implementation-contract-v1 schema.",
             "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
+            "The Markdown explanation may be omitted; prioritize a complete contract.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "structured-output-truncated" &&
+        task.structuredContractOutput) {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt was truncated by the provider (stopReason=length) before the JSON contract was completed.",
+            "This attempt: output ONLY the single fenced json contract block, immediately followed by exactly one openspec-citations block.",
+            "Do not emit any Markdown explanation, evidence excerpts, or duplicated upstream context.",
+            "The contract JSON must be complete; the trailing Markdown explanation may be omitted entirely.",
             "</retry_instruction>",
         ].join("\n");
     }
@@ -768,10 +782,16 @@ export async function executeDagNode(input) {
                     sourceBinding: spec.sourceBinding,
                 });
                 if (!contractCheck.ok) {
+                    // A provider stopReason=length means the response was cut before the
+                    // JSON contract could complete; separate it from an ordinary bad
+                    // contract so the retry switches to a JSON-only output strategy.
+                    const attemptStopReason = result.stopReason;
                     result = {
                         ...result,
                         ok: false,
-                        failureCategory: "invalid-output",
+                        failureCategory: attemptStopReason === "length"
+                            ? "structured-output-truncated"
+                            : "invalid-output",
                         stderr: [result.stderr, contractCheck.reason]
                             .filter(Boolean)
                             .join("\n"),

package/dist/workflows/dag/retry-policy.js

@@ -21,6 +21,8 @@ export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
 export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
 /** Recoverable model artifact/schema formatting failure on read-only structured nodes. */
 export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
+/** Provider stopReason=length truncated the response before the JSON contract completed. */
+export const STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY = "structured-output-truncated";
 /** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
 export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
 /** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
@@ -36,6 +38,7 @@ export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
     ...DEFAULT_DAG_RETRY_CATEGORIES,
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
     STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
 ];
 /** Categories allowed on nodes that declare a machine-readable outputProtocol. */
 export const PROTOCOL_AWARE_DAG_RETRY_CATEGORIES = [
@@ -48,6 +51,7 @@ export const ALL_DAG_RETRY_CATEGORIES = [
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
     PROTOCOL_INVALID_RETRY_CATEGORY,
     STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
     WRITER_EMPTY_DIFF_RETRY_CATEGORY,
     INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
     WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-next.3",
+  "version": "0.39.0-next.4",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",