@tea-agent/loop-agent 0.31.0 → 0.32.0

package/dist/worker/materialize/harness-task-materializer.js

@@ -1,17 +1,25 @@
-import { createHash } from "node:crypto";
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
 import { writeTaskConfig, writeTaskArtifactFile, } from "../../infrastructure/harness/task-store.js";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { adoptTaskContract } from "../../task/contract/adopt.js";
 import { observeTaskContractState } from "../../task/contract/observe.js";
 import { sha256Utf8 } from "../../task/contract/hash.js";
 import { resolveLoopAgentProfile, } from "../profile-mapping.js";
-import { mapRiskLevelToComplexity } from "../task-spec/complexity-mapping.js";
 import { resolveWorkflow } from "../task-spec/workflow-routing.js";
 import { validateTaskSpec } from "../task-spec/validate.js";
+import { mapRiskLevelToComplexity } from "../task-spec/complexity-mapping.js";
+import { detectPausedAssociatedRun, detectRecoveryRequired, } from "./harness-task-lifecycle-probe.js";
+import { buildHarnessTaskId as buildHarnessTaskLocatorId, buildHarnessTaskLineage, computeRevisionDigests, expandAllowedPathsForWorkflow, parseLineageIndex, parseLineageRevisionManifest, resolveRevisionDigestsForTaskSpec, } from "./harness-task-lineage.js";
+const LINEAGE_MANIFEST_NAME = "lineage-revision-manifest.json";
+const LINEAGE_INDEX_DIR = "_lineage-index";
 export async function materializeTaskSpec(options) {
+    const result = await materializeTaskSpecV2(options);
+    return result.manifest;
+}
+export async function materializeTaskSpecV2(options) {
     const now = options.now ?? new Date();
     const validation = await validateTaskSpec(options.taskSpec, {
         taskSpecPath: options.taskSpecPath,
@@ -20,43 +28,179 @@ export async function materializeTaskSpec(options) {
         const codes = validation.errors.map((error) => error.code).join(", ");
         throw new Error(`TaskSpec validation failed: ${codes}`);
     }
-    const harnessTaskId = buildHarnessTaskId(options.taskSpec, now);
-    const resolvedWorkflow = resolveWorkflow(options.taskSpec);
+    const resolved = await resolveRevisionDigestsForTaskSpec({
+        taskSpec: options.taskSpec,
+        taskSpecPath: options.taskSpecPath,
+    });
+    const lineage = resolved.lineage;
+    const digests = resolved.digests;
+    const harnessTaskId = buildHarnessTaskLocatorId(lineage.lineageId, digests.revisionId);
+    const lineageIndex = await readLineageIndex(options.repoRoot, lineage.lineageId);
+    const existingManifest = await readLineageRevisionManifest(options.repoRoot, harnessTaskId);
+    assertManifestDigestConsistency(existingManifest, digests, harnessTaskId);
+    const indexEntry = lineageIndex?.revisions.find((entry) => entry.revisionId === digests.revisionId);
+    if (indexEntry &&
+        indexEntry.harnessTaskId !== harnessTaskId &&
+        indexEntry.sourceDigest === digests.sourceDigest &&
+        indexEntry.contractDigest === digests.contractDigest) {
+        throw new Error(`lineage index collision for ${lineage.lineageId}: revision ${digests.revisionId} maps to ${indexEntry.harnessTaskId}, expected ${harnessTaskId}`);
+    }
     const existingConfig = await loadExistingTaskConfig(options.repoRoot, harnessTaskId);
-    if (!existingConfig) {
-        // Prefer task advance create path (new-task is being purged from the public surface).
-        const newTaskResult = await options.client.run(["task", "advance", harnessTaskId, options.taskSpec.title, "--json"], {
-            cwd: options.repoRoot,
-            artifactName: `task-advance-create-${harnessTaskId}`,
+    const pausedRun = existingConfig
+        ? await detectPausedAssociatedRun(options.repoRoot, harnessTaskId)
+        : undefined;
+    if (pausedRun) {
+        const manifest = await buildManifestFromExisting({
+            repoRoot: options.repoRoot,
+            harnessTaskId,
+            taskSpec: options.taskSpec,
+            lineage,
+            digests,
+            workflow: resolved.workflow,
+            loopAgentProfile: resolved.loopAgentProfile,
+            materializeOutcome: "resume-existing",
         });
-        if (!newTaskResult.ok) {
-            const racedConfig = await loadExistingTaskConfig(options.repoRoot, harnessTaskId);
-            if (!racedConfig) {
-                throw new Error(`loop-agent task advance (create) failed with exit ${newTaskResult.exitCode}: ${newTaskResult.stderr}`);
-            }
+        return {
+            outcome: {
+                type: "resume-existing",
+                revisionId: digests.revisionId,
+                runId: pausedRun.runId,
+            },
+            manifest,
+        };
+    }
+    if (existingConfig && existingManifest) {
+        const recovery = await detectRecoveryRequired(options.repoRoot, harnessTaskId, digests.revisionId);
+        if (recovery) {
+            return {
+                outcome: {
+                    type: "recovery-required",
+                    revisionId: digests.revisionId,
+                    recovery,
+                },
+                manifest: await buildManifestFromExisting({
+                    repoRoot: options.repoRoot,
+                    harnessTaskId,
+                    taskSpec: options.taskSpec,
+                    lineage,
+                    digests,
+                    workflow: resolved.workflow,
+                    loopAgentProfile: resolved.loopAgentProfile,
+                    materializeOutcome: "recovery-required",
+                }),
+            };
         }
     }
-    const paths = getTaskPaths(options.repoRoot, harnessTaskId);
-    const baseConfig = await loadTaskConfig(options.repoRoot, harnessTaskId);
-    // backend-test hybrid DAG writes under testcase/** (pytest + md cases + helpers).
-    // TaskSpecs often list legacy tests/api/** surfaces; union runtime write roots so
-    // git checkpoint / path guard can promote green BE-TEST runs.
-    const allowedPaths = expandAllowedPathsForWorkflow(resolvedWorkflow.workflow, options.taskSpec.constraints.allowed_paths);
+    let outcome;
+    let previousRevisionId;
+    if (existingConfig && existingManifest) {
+        outcome = {
+            type: "idempotent-reuse",
+            lineageId: lineage.lineageId,
+            revisionId: digests.revisionId,
+            harnessTaskId,
+        };
+    }
+    else if (lineageIndex && lineageIndex.revisions.length > 0) {
+        previousRevisionId = lineageIndex.currentRevisionId;
+        outcome = {
+            type: "new-revision",
+            lineageId: lineage.lineageId,
+            previousRevisionId,
+            revisionId: digests.revisionId,
+            harnessTaskId,
+        };
+    }
+    else {
+        outcome = {
+            type: "created",
+            lineageId: lineage.lineageId,
+            revisionId: digests.revisionId,
+            harnessTaskId,
+        };
+    }
+    const skipContractRewrite = outcome.type === "idempotent-reuse";
+    if (!existingConfig) {
+        await ensureHarnessTaskCreated({
+            repoRoot: options.repoRoot,
+            harnessTaskId,
+            title: options.taskSpec.title,
+            client: options.client,
+        });
+    }
+    if (!skipContractRewrite) {
+        await writeHarnessTaskMaterials({
+            repoRoot: options.repoRoot,
+            harnessTaskId,
+            taskSpec: options.taskSpec,
+            taskSpecPath: options.taskSpecPath,
+            workflow: resolved.workflow,
+            taskKind: resolved.taskKind,
+            allowedPaths: resolved.allowedPaths,
+            now,
+        });
+    }
+    else {
+        await touchIdempotentReuseTask({
+            repoRoot: options.repoRoot,
+            harnessTaskId,
+            title: options.taskSpec.title,
+        });
+    }
+    const revision = {
+        schemaVersion: 1,
+        lineageId: lineage.lineageId,
+        revisionId: digests.revisionId,
+        sourceDigest: digests.sourceDigest,
+        contractDigest: digests.contractDigest,
+        createdAt: existingManifest?.revision.createdAt ?? now.toISOString(),
+    };
+    const lineageManifest = {
+        schemaVersion: 1,
+        lineage,
+        revision,
+        harnessTaskId,
+        ...(previousRevisionId ? { previousRevisionId } : {}),
+    };
+    await writeLineageRevisionManifest(options.repoRoot, harnessTaskId, lineageManifest);
+    await upsertLineageIndex({
+        repoRoot: options.repoRoot,
+        lineage,
+        digests,
+        harnessTaskId,
+        createdAt: revision.createdAt,
+    });
+    const manifest = await buildMaterializeManifest({
+        repoRoot: options.repoRoot,
+        harnessTaskId,
+        taskSpec: options.taskSpec,
+        lineage,
+        digests,
+        workflow: resolved.workflow,
+        loopAgentProfile: resolved.loopAgentProfile,
+        materializeOutcome: outcome.type,
+    });
+    await writeTaskArtifactFile(options.repoRoot, harnessTaskId, "materialize-manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
+    return { outcome, manifest };
+}
+async function writeHarnessTaskMaterials(input) {
+    const paths = getTaskPaths(input.repoRoot, input.harnessTaskId);
+    const baseConfig = await loadTaskConfig(input.repoRoot, input.harnessTaskId);
     const taskConfig = {
         ...baseConfig,
-        taskId: harnessTaskId,
-        title: options.taskSpec.title,
-        taskKind: resolvedWorkflow.taskKind,
-        featureId: options.taskSpec.feature_id,
-        allowedPaths,
-        forbiddenPaths: options.taskSpec.constraints.forbidden_paths,
-        hardConstraints: options.taskSpec.constraints.hard_constraints,
-        complexity: mapRiskLevelToComplexity(options.taskSpec.risk_level),
-        capabilities: options.taskSpec.capabilities ?? [],
-        verifyMode: options.taskSpec.verify.mode,
-        verifyPreset: options.taskSpec.verify.preset,
-        verifyQuota: options.taskSpec.verify.quota,
-        verifyCommands: options.taskSpec.verify.commands
+        taskId: input.harnessTaskId,
+        title: input.taskSpec.title,
+        taskKind: input.taskKind,
+        featureId: input.taskSpec.feature_id,
+        allowedPaths: input.allowedPaths,
+        forbiddenPaths: input.taskSpec.constraints.forbidden_paths,
+        hardConstraints: input.taskSpec.constraints.hard_constraints,
+        complexity: mapRiskLevelToComplexity(input.taskSpec.risk_level),
+        capabilities: input.taskSpec.capabilities ?? [],
+        verifyMode: input.taskSpec.verify.mode,
+        verifyPreset: input.taskSpec.verify.preset,
+        verifyQuota: input.taskSpec.verify.quota,
+        verifyCommands: input.taskSpec.verify.commands
             .filter((command) => command.required)
             .map((command) => ({
             label: command.label,
@@ -65,7 +209,7 @@ export async function materializeTaskSpec(options) {
         })),
         autoCommitAfterVerify: false,
     };
-    await writeTaskConfig(options.repoRoot, harnessTaskId, taskConfig);
+    await writeTaskConfig(input.repoRoot, input.harnessTaskId, taskConfig);
     const sourcePaths = {
         requirementPath: path.join(paths.sourceDir, "需求.md"),
         constraintsPath: path.join(paths.sourceDir, "执行约束.md"),
@@ -73,48 +217,170 @@ export async function materializeTaskSpec(options) {
     };
     await mkdir(paths.sourceDir, { recursive: true });
     const referencePaths = await materializeSourceDocs({
-        taskSpec: options.taskSpec,
-        taskSpecPath: options.taskSpecPath,
+        taskSpec: input.taskSpec,
+        taskSpecPath: input.taskSpecPath,
         sourceDir: paths.sourceDir,
     });
     const sourceDocTrace = await buildSourceDocTrace({
-        taskSpec: options.taskSpec,
-        taskSpecPath: options.taskSpecPath,
+        taskSpec: input.taskSpec,
+        taskSpecPath: input.taskSpecPath,
         referencePaths,
     });
     const acceptanceSummaries = await buildAcceptanceSummaries({
-        taskSpec: options.taskSpec,
-        taskSpecPath: options.taskSpecPath,
+        taskSpec: input.taskSpec,
+        taskSpecPath: input.taskSpecPath,
         referencePaths,
     });
-    await writeFile(sourcePaths.requirementPath, renderRequirementMarkdown(options.taskSpec, {
+    await writeFile(sourcePaths.requirementPath, renderRequirementMarkdown(input.taskSpec, {
         sourceDocTrace,
         acceptanceSummaries,
     }), "utf-8");
-    await writeFile(sourcePaths.constraintsPath, renderConstraintsMarkdown(options.taskSpec), "utf-8");
-    await writeFile(sourcePaths.taskYamlPath, YAML.stringify(options.taskSpec), "utf-8");
+    await writeFile(sourcePaths.constraintsPath, renderConstraintsMarkdown(input.taskSpec), "utf-8");
+    await writeFile(sourcePaths.taskYamlPath, YAML.stringify(input.taskSpec), "utf-8");
     await ensureMaterializedTaskContractManaged({
-        repoRoot: options.repoRoot,
-        taskId: harnessTaskId,
-        taskSpecPath: options.taskSpecPath,
+        repoRoot: input.repoRoot,
+        taskId: input.harnessTaskId,
+        taskSpecPath: input.taskSpecPath,
+    });
+}
+async function touchIdempotentReuseTask(input) {
+    const baseConfig = await loadTaskConfig(input.repoRoot, input.harnessTaskId);
+    if (baseConfig.title === input.title)
+        return;
+    await writeTaskConfig(input.repoRoot, input.harnessTaskId, {
+        ...baseConfig,
+        title: input.title,
     });
-    const profileMapping = resolveLoopAgentProfile(options.taskSpec);
-    const manifest = {
+}
+async function ensureHarnessTaskCreated(input) {
+    const newTaskResult = await input.client.run(["task", "advance", input.harnessTaskId, input.title, "--json"], {
+        cwd: input.repoRoot,
+        artifactName: `task-advance-create-${input.harnessTaskId}`,
+    });
+    if (!newTaskResult.ok) {
+        const racedConfig = await loadExistingTaskConfig(input.repoRoot, input.harnessTaskId);
+        if (!racedConfig) {
+            throw new Error(`loop-agent task advance (create) failed with exit ${newTaskResult.exitCode}: ${newTaskResult.stderr}`);
+        }
+    }
+}
+function assertManifestDigestConsistency(existingManifest, digests, harnessTaskId) {
+    if (!existingManifest)
+        return;
+    if (existingManifest.revision.sourceDigest !== digests.sourceDigest ||
+        existingManifest.revision.contractDigest !== digests.contractDigest) {
+        throw new Error(`lineage manifest digest mismatch for ${harnessTaskId}: stored revision does not match canonical TaskSpec digest (fail-closed)`);
+    }
+    if (existingManifest.revision.revisionId !== digests.revisionId) {
+        throw new Error(`lineage manifest revisionId mismatch for ${harnessTaskId}: stored ${existingManifest.revision.revisionId} vs canonical ${digests.revisionId}`);
+    }
+}
+function lineageIndexPath(repoRoot, lineageId) {
+    return path.join(repoRoot, ".harness", "tasks", LINEAGE_INDEX_DIR, `${lineageId}.json`);
+}
+function lineageManifestPath(repoRoot, harnessTaskId) {
+    return path.join(repoRoot, ".harness", "tasks", harnessTaskId, "artifacts", LINEAGE_MANIFEST_NAME);
+}
+async function readLineageRevisionManifest(repoRoot, harnessTaskId) {
+    try {
+        const raw = await readFile(lineageManifestPath(repoRoot, harnessTaskId), "utf-8");
+        return parseLineageRevisionManifest(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+async function writeLineageRevisionManifest(repoRoot, harnessTaskId, manifest) {
+    await writeTaskArtifactFile(repoRoot, harnessTaskId, LINEAGE_MANIFEST_NAME, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+async function readLineageIndex(repoRoot, lineageId) {
+    try {
+        const raw = await readFile(lineageIndexPath(repoRoot, lineageId), "utf-8");
+        return parseLineageIndex(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+async function upsertLineageIndex(input) {
+    const indexPath = lineageIndexPath(input.repoRoot, input.lineage.lineageId);
+    await mkdir(path.dirname(indexPath), { recursive: true });
+    const existing = await readLineageIndex(input.repoRoot, input.lineage.lineageId);
+    const revisions = existing?.revisions ?? [];
+    const withoutCurrent = revisions.filter((entry) => entry.revisionId !== input.digests.revisionId);
+    const next = {
         schemaVersion: 1,
-        businessId: options.taskSpec.id,
-        harnessTaskId,
-        featureId: options.taskSpec.feature_id,
-        workflow: resolvedWorkflow.workflow,
-        loopAgentProfile: profileMapping.loopAgentProfile,
+        lineageId: input.lineage.lineageId,
+        featureId: input.lineage.featureId,
+        taskId: input.lineage.taskId,
+        currentRevisionId: input.digests.revisionId,
+        revisions: [
+            ...withoutCurrent,
+            {
+                revisionId: input.digests.revisionId,
+                harnessTaskId: input.harnessTaskId,
+                sourceDigest: input.digests.sourceDigest,
+                contractDigest: input.digests.contractDigest,
+                createdAt: input.createdAt,
+            },
+        ].sort((left, right) => left.revisionId.localeCompare(right.revisionId)),
+    };
+    await writeJsonAtomic(indexPath, next, { repoRoot: input.repoRoot });
+}
+async function buildManifestFromExisting(input) {
+    return buildMaterializeManifest(input);
+}
+async function buildMaterializeManifest(input) {
+    const paths = getTaskPaths(input.repoRoot, input.harnessTaskId);
+    const referencePaths = await readExistingReferencePaths(paths.sourceDir, input.taskSpec);
+    return {
+        schemaVersion: 1,
+        businessId: input.taskSpec.id,
+        harnessTaskId: input.harnessTaskId,
+        featureId: input.taskSpec.feature_id,
+        lineageId: input.lineage.lineageId,
+        revisionId: input.digests.revisionId,
+        sourceDigest: input.digests.sourceDigest,
+        contractDigest: input.digests.contractDigest,
+        materializeOutcome: input.materializeOutcome,
+        workflow: input.workflow,
+        loopAgentProfile: input.loopAgentProfile,
         taskConfigPath: paths.taskConfigPath,
         source: {
-            ...sourcePaths,
-            // Reference copies make the upstream requirement/design/test cases concrete.
+            requirementPath: path.join(paths.sourceDir, "需求.md"),
+            constraintsPath: path.join(paths.sourceDir, "执行约束.md"),
+            taskYamlPath: path.join(paths.sourceDir, "task.yaml"),
             referencePaths,
         },
     };
-    await writeTaskArtifactFile(options.repoRoot, harnessTaskId, "materialize-manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
-    return manifest;
+}
+// Re-export lineage helpers used by tests and callers.
+export { expandAllowedPathsForWorkflow } from "./harness-task-lineage.js";
+async function readExistingReferencePaths(sourceDir, taskSpec) {
+    const referenceDir = path.join(sourceDir, "references");
+    const referencePaths = {};
+    for (const key of Object.keys(taskSpec.source_docs)) {
+        const candidates = [
+            path.join(referenceDir, `${key}.md`),
+            path.join(referenceDir, `${key}.yaml`),
+            path.join(referenceDir, `${key}.yml`),
+        ];
+        for (const candidate of candidates) {
+            try {
+                await readFile(candidate);
+                referencePaths[key] = candidate;
+                break;
+            }
+            catch {
+                // continue
+            }
+        }
+    }
+    return referencePaths;
 }
 async function materializeSourceDocs(input) {
     const referenceDir = path.join(input.sourceDir, "references");
@@ -132,20 +398,6 @@ async function materializeSourceDocs(input) {
     }
     return referencePaths;
 }
-export function buildHarnessTaskId(taskSpec, now) {
-    const date = now.toISOString().slice(0, 10);
-    const slug = slugify(`${taskSpec.id}-${taskSpec.title}`);
-    return `${date}-${slug}`;
-}
-function slugify(value) {
-    return value
-        .normalize("NFKD")
-        .replace(/[\u0300-\u036f]/g, "")
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .replace(/-{2,}/g, "-");
-}
 /** Exported for unit tests: derived contract must point back to immutable references. */
 async function ensureMaterializedTaskContractManaged(input) {
     const state = await observeTaskContractState(input.repoRoot, input.taskId);
@@ -217,6 +469,7 @@ export function renderRequirementMarkdown(taskSpec, options = {}) {
     return `${lines.join("\n").trimEnd()}\n`;
 }
 async function buildSourceDocTrace(input) {
+    const { createHash } = await import("node:crypto");
     const entries = [];
     for (const [key, relativePath] of Object.entries(input.taskSpec.source_docs)) {
         if (!relativePath)
@@ -351,15 +604,6 @@ function bulletLines(values) {
         return ["- None"];
     return values.map((value) => `- ${value}`);
 }
-/** Union TaskSpec allowed_paths with workflow-owned write roots. */
-export function expandAllowedPathsForWorkflow(workflow, allowedPaths) {
-    const extras = workflow === "backend-test"
-        ? ["testcase/**", "docs/test-reports/**"]
-        : workflow === "frontend-test"
-            ? ["testcase/frontend/**", "docs/test-reports/**"]
-            : [];
-    return Array.from(new Set([...allowedPaths, ...extras]));
-}
 async function loadExistingTaskConfig(repoRoot, taskId) {
     try {
         return await loadTaskConfig(repoRoot, taskId);
@@ -376,3 +620,29 @@ function isNotFound(error) {
         "code" in error &&
         error.code === "ENOENT");
 }
+/**
+ * Resolve the bounded harness task locator for a TaskSpec.
+ * `now` is accepted for legacy callers but does not affect identity.
+ */
+export async function buildHarnessTaskId(taskSpec, _now, taskSpecPath) {
+    if (taskSpecPath) {
+        const resolved = await resolveRevisionDigestsForTaskSpec({
+            taskSpec,
+            taskSpecPath,
+        });
+        return buildHarnessTaskLocatorId(resolved.lineage.lineageId, resolved.digests.revisionId);
+    }
+    const lineage = buildHarnessTaskLineage(taskSpec);
+    const resolvedWorkflow = resolveWorkflow(taskSpec);
+    const profileMapping = resolveLoopAgentProfile(taskSpec);
+    const allowedPaths = expandAllowedPathsForWorkflow(resolvedWorkflow.workflow, taskSpec.constraints.allowed_paths);
+    const { revisionId } = computeRevisionDigests({
+        taskSpec,
+        workflow: resolvedWorkflow.workflow,
+        taskKind: resolvedWorkflow.taskKind,
+        loopAgentProfile: profileMapping.loopAgentProfile,
+        allowedPaths,
+        sourceRefHashes: {},
+    });
+    return buildHarnessTaskLocatorId(lineage.lineageId, revisionId);
+}

package/dist/worker/observability/progress-composite.js

@@ -21,6 +21,7 @@ export function createCompositeProgressReporter(options) {
                     batchRunId: input.batchRunId ?? context.batchRunId,
                     workerRunId: input.workerRunId ?? context.workerRunId,
                     taskId: input.taskId ?? context.taskId,
+                    featureId: input.featureId ?? context.featureId,
                 }, { now });
                 await eventStore.append(event);
             }