@tea-agent/loop-agent 0.31.1 → 0.32.0

package/dist/worker/feature/next-action.js

@@ -1,3 +1,4 @@
+import { resolveWorkerRecoveryDecision } from "../pool/recovery-decision.js";
 export function projectNextAction(input, status) {
     const featureArgs = `--feature-dir ${quote(input.featureDir)} --repo ${quote(input.repoRoot)}`;
     const resolvedFailures = new Set(input.resolvedFailureTaskIds ?? []);
@@ -31,20 +32,59 @@ export function projectNextAction(input, status) {
     }
     const failed = input.tasks.find((task) => task.status === "Failed" && !resolvedFailures.has(task.taskId));
     if (failed) {
-        if (failed.failureCategory === "EnvFailure") {
+        const decision = resolveWorkerRecoveryDecision({
+            state: {
+                status: failed.status ?? "Failed",
+                ...(failed.workerRunId ? { workerRunId: failed.workerRunId } : {}),
+                ...(failed.failureCategory
+                    ? {
+                        failure: {
+                            category: failed.failureCategory,
+                            recommendedFollowUpKind: "feature-review",
+                            derivedFollowUpTaskId: `${failed.taskId}-review`,
+                            source: "fallback",
+                        },
+                    }
+                    : {}),
+            },
+        });
+        if (decision.recommendedAction === "retry") {
             return {
                 kind: "retry_task",
-                label: `重试环境失败任务 ${failed.taskId}`,
+                label: `重试失败任务 ${failed.taskId}`,
                 command: `agent-worker task retry ${quote(failed.taskId)} --feature-id ${quote(input.featureId)} --repo ${quote(input.repoRoot)}`,
             };
         }
-        return {
-            kind: "handle_failure",
-            label: `根据失败证据处理 ${failed.taskId}；ProductBug 可生成并人工批准 Follow-up`,
-        };
+        if (decision.recommendedAction === "decide") {
+            return {
+                kind: "handle_failure",
+                label: `根据失败证据处理 ${failed.taskId}；ProductBug 可生成并人工批准 Follow-up`,
+            };
+        }
     }
     const blocked = input.tasks.find((task) => ["Blocked", "HumanReview", "Abandoned"].includes(task.status ?? ""));
     if (blocked) {
+        const decision = resolveWorkerRecoveryDecision({
+            state: {
+                status: blocked.status ?? "Blocked",
+                ...(blocked.failureCategory
+                    ? {
+                        failure: {
+                            category: blocked.failureCategory,
+                            recommendedFollowUpKind: "feature-review",
+                            derivedFollowUpTaskId: `${blocked.taskId}-review`,
+                            source: "fallback",
+                        },
+                    }
+                    : {}),
+            },
+        });
+        if (decision.recommendedAction === "revise-contract") {
+            return {
+                kind: "revise_contract",
+                label: `修订 ${blocked.taskId} 的 contract/spec 后再 materialize`,
+            };
+        }
         return {
             kind: "resolve_human_gate",
             label: `处理 ${blocked.taskId} 的人工 Gate 或阻塞原因`,
@@ -65,6 +105,16 @@ export function projectNextAction(input, status) {
             command: `agent-worker batch run-ready ${featureArgs}`,
         };
     }
+    if (status === "awaiting_qa" || status === "deliverable") {
+        const gap = input.acceptanceGaps?.find((entry) => entry.nextCommand);
+        if (gap?.nextCommand) {
+            return {
+                kind: status === "deliverable" ? "advance_delivery" : "complete_qa",
+                label: `补齐 ${gap.acId} 验收缺口（${gap.status}）`,
+                command: gap.nextCommand,
+            };
+        }
+    }
     if (status === "awaiting_qa") {
         const finalish = input.tasks.find((task) => /(final[-_]?(verify|verification))|closeout/i.test(task.taskId));
         if (finalish && (finalish.status === "Done" || finalish.status === "Ready")) {

package/dist/worker/feature/profile-schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { acceptancePolicySchema } from "./acceptance-policy.js";
 /**
  * Feature-level profile for a Feature Packet (M4 `fullstack-v1`).
  *
@@ -36,6 +37,8 @@ export const featureProfileSchema = z
     })
         .strict()
         .optional(),
+    /** Phase 6 ADR 0007 acceptance / verify-final / delivery policy. */
+    acceptance_policy: acceptancePolicySchema.optional(),
 })
     .strict();
 /** Whether a parsed profile activates the fullstack-v1 gate set. */

package/dist/worker/feature/reducer.js

@@ -81,6 +81,7 @@ export function reduceFeature(input) {
             status: task.status ?? (isReady(task.taskId, input) ? "Ready" : "Draft"),
         })),
         acceptanceCoverage: input.acceptance,
+        acceptanceGaps: input.acceptanceGaps ?? [],
         nextAction: projectNextAction(input, status),
         alternativeActions: [],
         evidence: {

package/dist/worker/feature/review.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import YAML from "yaml";
 import { z } from "zod";
 import { getRunsJsonlPath, getTaskPoolRoot, readFeatureTaskPoolStates, readJsonlFile } from "../pool/run-store.js";
+import { readRunOwner } from "../pool/run-owner-store.js";
 import { artifactMatchesEvidenceToken, isShellVerificationToken, } from "../outcomes/evidence-tokens.js";
 import { readVerifiedOutcome } from "../outcomes/store.js";
 import { acceptanceSpecSchema } from "../task-graph/acceptance-schema.js";
@@ -14,6 +15,7 @@ import { followUpActionCardSchema, followUpApprovalSchema, followUpDraftSchema,
 import { readFollowUpIndex, resolveRepoFile, sha256File as sha256FollowUpFile } from "../follow-up/store.js";
 import { projectReadyPlan } from "./ready-plan-projection.js";
 import { reduceFeature } from "./reducer.js";
+import { buildAcceptanceGaps, indexRawAcceptanceItems, parseAcceptancePolicy, } from "./acceptance-policy.js";
 export async function reviewFeature(input) {
     const projection = await loadFeatureProjection(input);
     return reduceFeature(projection);
@@ -61,14 +63,27 @@ async function loadFeatureProjection(input) {
         });
     }
     let acceptance = acceptanceSpecSchema.safeParse({});
+    let acceptanceRaw = {};
     let graph = taskGraphSpecSchema.safeParse({});
+    let featurePacketRaw = {};
     try {
-        acceptance = acceptanceSpecSchema.safeParse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
+        acceptanceRaw = YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8"));
+        acceptance = acceptanceSpecSchema.safeParse(acceptanceRaw);
         graph = taskGraphSpecSchema.safeParse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
     }
     catch (error) {
         projectionWarnings.push(`cannot read Feature Packet: ${message(error)}`);
     }
+    try {
+        const featureYamlPath = path.join(featureDir, "feature.yaml");
+        if (await exists(featureYamlPath)) {
+            featurePacketRaw = YAML.parse(await readFile(featureYamlPath, "utf-8"));
+        }
+    }
+    catch (error) {
+        projectionWarnings.push(`cannot read feature.yaml: ${message(error)}`);
+    }
+    const acceptancePolicy = parseAcceptancePolicy(featurePacketRaw);
     if (!acceptance.success)
         projectionWarnings.push("acceptance.yaml is invalid");
     if (!graph.success)
@@ -186,18 +201,49 @@ async function loadFeatureProjection(input) {
     catch (error) {
         projectionWarnings.push(`follow-up index is corrupt: ${message(error)}`);
     }
+    const ownerByWorkerRunId = new Map();
+    await Promise.all(Object.values(states).map(async (state) => {
+        if (!state.workerRunId)
+            return;
+        const owner = await readRunOwner(repoRoot, state.workerRunId).catch(() => undefined);
+        if (owner)
+            ownerByWorkerRunId.set(state.workerRunId, owner);
+    }));
     const tasks = graphNodes.map((node) => {
         const rawState = states[node.id];
         const stateRun = rawState?.workerRunId
             ? runs.find((run) => run.workerRunId === rawState.workerRunId)
             : undefined;
-        const state = rawState?.workerRunId && !stateRun
-            ? undefined
-            : stateRun && stateRun.featureId !== validation.featureId
-                ? undefined
-                : rawState;
-        if (rawState && !state) {
-            projectionWarnings.push(`Task Pool state for ${node.id} has missing or cross-Feature run ownership`);
+        const live = rawState?.status === "Running" ||
+            rawState?.status === "Queued" ||
+            rawState?.status === "AgentCompleted" ||
+            rawState?.status === "VerificationRunning" ||
+            rawState?.status === "HumanReview";
+        const owner = rawState?.workerRunId
+            ? ownerByWorkerRunId.get(rawState.workerRunId)
+            : undefined;
+        let state = rawState;
+        if (rawState?.workerRunId) {
+            if (stateRun && stateRun.featureId !== validation.featureId) {
+                state = undefined;
+            }
+            else if (owner && owner.featureId !== validation.featureId) {
+                state = undefined;
+            }
+            else if (!stateRun && !live) {
+                state = undefined;
+            }
+            else if (!stateRun && live) {
+                const stateFeatureOk = !rawState.featureId || rawState.featureId === validation.featureId;
+                const ownerOk = !owner || owner.featureId === validation.featureId;
+                state = stateFeatureOk && ownerOk ? rawState : undefined;
+            }
+            else {
+                state = rawState;
+            }
+            if (rawState && !state) {
+                projectionWarnings.push(`Task Pool state for ${node.id} has missing or cross-Feature run ownership`);
+            }
         }
         const latest = [...runs].reverse().find((run) => run.featureId === validation.featureId && run.taskId === node.id);
         return {
@@ -241,6 +287,17 @@ async function loadFeatureProjection(input) {
             };
         })
         : [];
+    const acceptanceGaps = acceptance.success
+        ? buildAcceptanceGaps({
+            policy: acceptancePolicy,
+            acceptanceItems: acceptance.data.acceptance,
+            rawByAcId: indexRawAcceptanceItems(acceptanceRaw),
+            coverage,
+            tasks,
+            featureDir,
+            repoRoot,
+        })
+        : [];
     const deliveryPath = path.join(deliveryRoot, "delivery-manifest.json");
     const morningReportPath = path.join(getTaskPoolRoot(repoRoot), "reports", "morning-report.md");
     const observeSnapshotPath = path.join(getTaskPoolRoot(repoRoot), "observability", "snapshot.json");
@@ -321,6 +378,13 @@ async function loadFeatureProjection(input) {
         validationErrors: validation.errors.map((error) => `${error.code}: ${error.message}`),
         tasks,
         acceptance: coverage,
+        acceptanceGaps,
+        acceptancePolicy: {
+            authority: acceptancePolicy.authority ?? "feature-verify-final",
+            coverageWriter: acceptancePolicy.coverage_writer ?? "feature-verify-final",
+            verifyFinalCommand: acceptancePolicy.final_verification?.command ??
+                "agent-worker feature verify-final",
+        },
         ...(closeout ? { closeout } : {}),
         ...(delivery ? { delivery } : {}),
         pendingFollowUps,

package/dist/worker/feature/scaffold.js

@@ -228,6 +228,16 @@ export function renderWritePlan(input, repoRoot) {
             schema_version: 1,
             feature_id: featureId,
             profile: "generic",
+            acceptance_policy: {
+                schema_version: 1,
+                authority: "feature-verify-final",
+                independent_qa_required: true,
+                coverage_writer: "feature-verify-final",
+                final_verification: {
+                    command: "agent-worker feature verify-final",
+                },
+                delivery_sequence: ["verify-final", "delivery", "closeout"],
+            },
         }),
     });
     files.push({
@@ -325,6 +335,8 @@ function buildAcceptance(input) {
                 then: item.then,
                 verification: {
                     expected_task_refs: taskRefs,
+                    authority: "feature-verify-final",
+                    required_evidence_kinds: ["canonical-qa-evidence"],
                 },
             };
         });
@@ -341,6 +353,8 @@ function buildAcceptance(input) {
             then: "验收目标达成且 verify.commands 通过",
             verification: {
                 expected_task_refs: taskRefs,
+                authority: "feature-verify-final",
+                required_evidence_kinds: ["canonical-qa-evidence"],
             },
         },
     ];

package/dist/worker/loop-agent/controller-protocol.js

@@ -0,0 +1,143 @@
+/**
+ * Worker ↔ Controller protocol envelope (Phase 5).
+ * Identity proves who; this envelope proves semantic compatibility.
+ */
+export const WORKER_ADAPTER_PROTOCOL_RANGE = ">=1 <2";
+export const WORKER_CONTROLLER_REQUIREMENTS_V1 = {
+    schemaVersion: 1,
+    protocolRange: WORKER_ADAPTER_PROTOCOL_RANGE,
+    requiredCapabilities: [
+        "task-advance-managed-contract-v2",
+        "worker-association-v1",
+        "events-jsonl-v1",
+    ],
+    optionalCapabilities: [
+        "document-index-closure-v1",
+        "worker-attempt-owner-v1",
+        "worker-attempt-revision-v1",
+        "recovery-decision-v2",
+    ],
+};
+export function evaluateControllerCompatibility(input) {
+    const requirements = input.requirements ?? WORKER_CONTROLLER_REQUIREMENTS_V1;
+    const envelope = input.envelope;
+    if (!envelope || envelope.schemaVersion !== 1) {
+        return {
+            status: "invalid-envelope",
+            evidence: { reason: "missing or invalid ControllerProtocolEnvelopeV1" },
+        };
+    }
+    if (!Number.isFinite(envelope.controllerProtocolVersion)) {
+        return {
+            status: "invalid-envelope",
+            evidence: { reason: "controllerProtocolVersion missing" },
+        };
+    }
+    if (!protocolRangeIncludes(requirements.protocolRange, envelope.controllerProtocolVersion)) {
+        return {
+            status: "unsupported",
+            missing: [`protocol ${requirements.protocolRange}`],
+            evidence: {
+                protocolVersion: envelope.controllerProtocolVersion,
+                availableCapabilities: envelope.capabilities,
+            },
+        };
+    }
+    const available = new Set(envelope.capabilities);
+    const missing = requirements.requiredCapabilities.filter((cap) => !available.has(cap));
+    if (missing.length > 0) {
+        return {
+            status: "unsupported",
+            missing,
+            evidence: {
+                protocolVersion: envelope.controllerProtocolVersion,
+                availableCapabilities: envelope.capabilities,
+            },
+        };
+    }
+    const missingOptional = requirements.optionalCapabilities.filter((cap) => !available.has(cap));
+    if (missingOptional.length > 0) {
+        return {
+            status: "upgrade-recommended",
+            evidence: {
+                matchedCapabilities: requirements.requiredCapabilities,
+                missingOptional,
+                protocolVersion: envelope.controllerProtocolVersion,
+            },
+        };
+    }
+    return {
+        status: "compatible",
+        evidence: {
+            matchedCapabilities: requirements.requiredCapabilities,
+            protocolVersion: envelope.controllerProtocolVersion,
+        },
+    };
+}
+function protocolRangeIncludes(range, version) {
+    // Minimal parser for ">=N <M" used by Worker requirements.
+    const match = range.match(/^>=\s*(\d+)\s*<\s*(\d+)$/);
+    if (!match)
+        return false;
+    const min = Number(match[1]);
+    const max = Number(match[2]);
+    return version >= min && version < max;
+}
+export function assertCompatibleBeforeWrite(result) {
+    if (result.status === "compatible" || result.status === "upgrade-recommended") {
+        return;
+    }
+    const detail = result.status === "unsupported"
+        ? `missing=${result.missing.join(",")}`
+        : result.evidence.reason;
+    throw new Error(`controller incompatible before canonical write: ${result.status} (${detail})`);
+}
+/**
+ * Envelope advertised by this package's published controller surface.
+ * Identity pin still proves "who"; this proves semantic capabilities.
+ */
+export function buildPublishedControllerProtocolEnvelope(packageVersion) {
+    return {
+        schemaVersion: 1,
+        controllerProtocolVersion: 1,
+        workerAdapterProtocolRange: WORKER_ADAPTER_PROTOCOL_RANGE,
+        capabilities: [
+            ...WORKER_CONTROLLER_REQUIREMENTS_V1.requiredCapabilities,
+            ...WORKER_CONTROLLER_REQUIREMENTS_V1.optionalCapabilities,
+        ],
+        packageVersion,
+    };
+}
+/** Extract protocol envelope from operator capabilities JSON when present. */
+export function extractControllerProtocolEnvelope(capabilities) {
+    if (!capabilities || typeof capabilities !== "object")
+        return undefined;
+    const raw = capabilities.controllerProtocol;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    if (record.schemaVersion !== 1)
+        return undefined;
+    if (typeof record.controllerProtocolVersion !== "number")
+        return undefined;
+    if (typeof record.workerAdapterProtocolRange !== "string")
+        return undefined;
+    if (!Array.isArray(record.capabilities))
+        return undefined;
+    if (typeof record.packageVersion !== "string")
+        return undefined;
+    const capabilitiesList = record.capabilities.filter((entry) => typeof entry === "string");
+    const deprecated = Array.isArray(record.deprecatedCapabilities)
+        ? record.deprecatedCapabilities.filter((entry) => typeof entry === "string")
+        : undefined;
+    return {
+        schemaVersion: 1,
+        controllerProtocolVersion: record.controllerProtocolVersion,
+        workerAdapterProtocolRange: record.workerAdapterProtocolRange,
+        capabilities: capabilitiesList,
+        packageVersion: record.packageVersion,
+        ...(deprecated && deprecated.length > 0
+            ? { deprecatedCapabilities: deprecated }
+            : {}),
+    };
+}

package/dist/worker/materialize/harness-task-lifecycle-probe.js

@@ -0,0 +1,126 @@
+/**
+ * Worker-local harness Task lifecycle probe.
+ * Uses workflows/DAG facts only — must not import src/application/**.
+ */
+import { assessDagRunLiveness, assessDagRunRecoveryEligibility, listAllDagRunEntries, readDagRunSpec, readDagRunState, } from "../../workflows/dag/lifecycle.js";
+import { resolveWorkerRecoveryDecision } from "../pool/recovery-decision.js";
+export async function listWorkerAssociatedDagRuns(repoRoot, harnessTaskId) {
+    const entries = await listAllDagRunEntries(repoRoot);
+    const related = [];
+    for (const entry of entries) {
+        let matched = false;
+        try {
+            const state = await readDagRunState(entry.runDir);
+            if (state.workerAssociation?.taskId === harnessTaskId) {
+                matched = true;
+            }
+        }
+        catch {
+            // state unreadable; may still match via binding
+        }
+        if (!matched) {
+            try {
+                const spec = await readDagRunSpec(entry.runDir);
+                if (spec.taskContractBinding?.taskId === harnessTaskId ||
+                    spec.sourceBinding?.taskId === harnessTaskId) {
+                    matched = true;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (!matched)
+            continue;
+        related.push({
+            runId: entry.runId,
+            lifecycle: entry.lifecycle,
+        });
+    }
+    return related.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+export async function detectPausedAssociatedRun(repoRoot, harnessTaskId) {
+    const runs = await listWorkerAssociatedDagRuns(repoRoot, harnessTaskId);
+    const paused = runs.find((run) => run.lifecycle === "paused");
+    return paused ? { runId: paused.runId } : undefined;
+}
+export async function detectRecoveryRequired(repoRoot, harnessTaskId, _revisionId) {
+    const entries = await listAllDagRunEntries(repoRoot);
+    let hasActiveOrRecoverableDag = false;
+    let dagCanResume = false;
+    let factsIncomplete = false;
+    let runFailed = false;
+    let needsAttention = false;
+    for (const entry of entries) {
+        let associated = false;
+        try {
+            const state = await readDagRunState(entry.runDir);
+            if (state.workerAssociation?.taskId === harnessTaskId) {
+                associated = true;
+            }
+            if (!associated)
+                continue;
+            const liveness = assessDagRunLiveness({ state });
+            const recovery = assessDagRunRecoveryEligibility({
+                lifecycle: entry.lifecycle,
+                state,
+                liveness: liveness.status,
+            });
+            if (entry.lifecycle === "active" ||
+                entry.lifecycle === "paused" ||
+                liveness.status === "active" ||
+                liveness.status === "node-quiet") {
+                hasActiveOrRecoverableDag = true;
+            }
+            if (entry.lifecycle === "paused" || recovery.canResume) {
+                dagCanResume = true;
+            }
+            if (liveness.status === "orphaned" ||
+                liveness.status === "stale" ||
+                liveness.status === "needs-attention" ||
+                liveness.status === "suspected-stall") {
+                needsAttention = true;
+                hasActiveOrRecoverableDag = true;
+            }
+            if (entry.lifecycle === "completed" && state.status !== "finished") {
+                runFailed = true;
+            }
+        }
+        catch {
+            try {
+                const spec = await readDagRunSpec(entry.runDir);
+                if (spec.taskContractBinding?.taskId === harnessTaskId ||
+                    spec.sourceBinding?.taskId === harnessTaskId) {
+                    factsIncomplete = true;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    if (factsIncomplete) {
+        return resolveWorkerRecoveryDecision({ factsIncomplete: true });
+    }
+    if (needsAttention || dagCanResume) {
+        const decision = resolveWorkerRecoveryDecision({
+            dagCanResume,
+            hasActiveOrRecoverableDag,
+        });
+        if (decision.recommendedAction === "reconcile" ||
+            decision.recommendedAction === "decide" ||
+            decision.recommendedAction === "revise-contract") {
+            return decision;
+        }
+    }
+    if (runFailed) {
+        const decision = resolveWorkerRecoveryDecision({
+            dagCanResume: false,
+            hasActiveOrRecoverableDag: false,
+        });
+        if (decision.recommendedAction === "revise-contract") {
+            return decision;
+        }
+    }
+    return undefined;
+}