@tea-agent/loop-agent 0.26.5-beta.2 → 0.27.1-beta.0

package/dist/application/task-lifecycle/gates.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+export function normalizeWriteSet(writeSet) {
+    return [
+        ...new Set(writeSet.map((entry) => entry.replace(/\\/g, "/").trim()).filter(Boolean)),
+    ].sort((a, b) => a.localeCompare(b));
+}
+export function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+export function hashCanonicalPayload(value) {
+    return `sha256:${sha256Hex(stableStringify(value))}`;
+}
+export function buildGateBinding(input) {
+    return {
+        taskId: input.taskId,
+        contractRevision: input.contractRevision,
+        contractCanonicalHash: input.contractCanonicalHash,
+        sourceBindingHash: input.sourceBindingHash,
+        dagSpecHash: input.dagSpecHash,
+        writeSet: normalizeWriteSet(input.writeSet),
+        controllerIdentityAnchor: input.controllerIdentityAnchor,
+    };
+}
+export function computeGateDigest(bound) {
+    return hashCanonicalPayload({
+        kind: "task-lifecycle-gate",
+        version: 1,
+        ...bound,
+        writeSet: normalizeWriteSet(bound.writeSet),
+    });
+}
+export function buildWriteSetGate(input) {
+    const digest = computeGateDigest(input.bound);
+    const id = "write-set-review";
+    return {
+        id,
+        type: "human-approval",
+        digest,
+        writeSet: normalizeWriteSet(input.bound.writeSet),
+        rationale: input.rationale ?? "validated DAG is ready; writer has not started",
+        approveCommand: `loop-agent task advance ${input.taskId} --approve-gate ${id}:${digest} --json`,
+        rejectCommand: `loop-agent task advance ${input.taskId} --reject-gate ${id}:${digest} --reason <text> --json`,
+        bound: input.bound,
+    };
+}
+export function parseGateToken(token) {
+    const separator = token.indexOf(":");
+    if (separator <= 0 || separator === token.length - 1) {
+        throw new Error(`invalid gate token ${token}; expected <gate-id>:<digest>`);
+    }
+    return {
+        id: token.slice(0, separator),
+        digest: token.slice(separator + 1),
+    };
+}
+export function gateMatches(gate, token) {
+    return gate.id === token.id && gate.digest === token.digest;
+}
+export function controllerIdentityAnchor(input) {
+    if (!input?.packageName || !input.packageVersion)
+        return null;
+    return [
+        input.packageName,
+        input.packageVersion,
+        input.packageFingerprintValue ?? "",
+    ].join("@");
+}

package/dist/application/task-lifecycle/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./gates.js";
+export * from "./record.js";
+export * from "./observe.js";
+export * from "./plan-transitions.js";
+export { buildTaskLifecycleRecommendations, applyAcceptedRecommendations, } from "./recommendations.js";
+export * from "./advance.js";

package/dist/application/task-lifecycle/observe.js

@@ -0,0 +1,395 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { getTaskDir, getTaskPaths, getTaskStatus, loadTaskConfig, } from "../../task/runtime.js";
+import { logicalRevisionForState, observeTaskContractState, } from "../../task/contract/index.js";
+import { assessDagRunLiveness, listAllDagRunEntries, readDagRunSpec, readDagRunState, } from "../../workflows/dag/lifecycle.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
+import { loadLifecycleRecord } from "./record.js";
+import { buildGateBinding, buildWriteSetGate, controllerIdentityAnchor, hashCanonicalPayload, normalizeWriteSet, sha256Hex, } from "./gates.js";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function closeoutPath(repoRoot, taskId) {
+    const slug = taskId.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+    const datePrefix = taskId.match(/^\d{4}-\d{2}-\d{2}/)?.[0] ??
+        new Date().toISOString().slice(0, 10);
+    return path.join(repoRoot, ".harness", "task-pool", "artifacts", "closeout", `${datePrefix}-${slug}.md`);
+}
+function collectWriterWriteSet(spec) {
+    const defaults = spec.defaults?.writePolicy ?? "none";
+    const entries = [];
+    for (const task of spec.tasks) {
+        const writePolicy = task.writePolicy ?? defaults;
+        if (writePolicy !== "exclusive")
+            continue;
+        for (const entry of task.writeSet ?? []) {
+            if (typeof entry === "string" && entry.trim())
+                entries.push(entry);
+        }
+    }
+    return normalizeWriteSet(entries);
+}
+function hashDagSpecBytes(raw) {
+    return `sha256:${sha256Hex(raw)}`;
+}
+function hashSourceBinding(spec) {
+    if (!spec.sourceBinding)
+        return null;
+    return hashCanonicalPayload(spec.sourceBinding);
+}
+async function taskExists(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    return exists(paths.taskConfigPath);
+}
+/**
+ * Explicit Task↔DAG association only:
+ * - lifecycle.json recorded runAssociations
+ * - DagSpec.taskContractBinding.taskId
+ * - DagSpec.sourceBinding.taskId
+ * - state.workerAssociation.taskId
+ *
+ * Never uses taskId substring or full JSON string includes.
+ */
+export async function listExplicitlyAssociatedRuns(repoRoot, taskId) {
+    const record = await loadLifecycleRecord(repoRoot, taskId);
+    const recorded = new Map((record?.runAssociations ?? []).map((entry) => [entry.runId, entry.source]));
+    const entries = await listAllDagRunEntries(repoRoot);
+    const related = [];
+    for (const entry of entries) {
+        let source = recorded.get(entry.runId) ?? null;
+        let stateStatus;
+        let failureCategory;
+        let lastMeaningfulProgressAt;
+        try {
+            const state = await readDagRunState(entry.runDir);
+            stateStatus = state.status;
+            const liveness = assessDagRunLiveness({ state });
+            const activeNode = Object.values(state.nodes ?? {}).find((node) => node.status === "RUNNING");
+            lastMeaningfulProgressAt =
+                activeNode?.lastMeaningfulProgressAt ??
+                    activeNode?.lastProviderActivityAt ??
+                    activeNode?.lastToolActivityAt ??
+                    activeNode?.lastOutputActivityAt ??
+                    activeNode?.lastActivityAt ??
+                    activeNode?.startedAt ??
+                    null;
+            if (liveness.status === "orphaned" ||
+                liveness.status === "stale" ||
+                liveness.status === "needs-attention" ||
+                liveness.status === "suspected-stall") {
+                failureCategory =
+                    state.failureCategory ??
+                        (liveness.status === "orphaned"
+                            ? "orphaned"
+                            : liveness.status === "stale"
+                                ? "stale-heartbeat"
+                                : liveness.status);
+            }
+            else {
+                failureCategory = state.failureCategory ?? null;
+            }
+            const workerTaskId = state.workerAssociation?.taskId;
+            if (!source && workerTaskId === taskId) {
+                source = "worker-association";
+            }
+        }
+        catch {
+            // state unreadable; may still match via binding
+        }
+        if (!source) {
+            try {
+                const spec = await readDagRunSpec(entry.runDir);
+                if (spec.taskContractBinding?.taskId === taskId) {
+                    source = "task-contract-binding";
+                }
+                else if (spec.sourceBinding?.taskId === taskId) {
+                    source = "source-binding";
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (!source)
+            continue;
+        related.push({
+            runId: entry.runId,
+            lifecycle: entry.lifecycle,
+            runDir: entry.runDir,
+            status: stateStatus,
+            failureCategory,
+            lastMeaningfulProgressAt,
+            source,
+        });
+    }
+    return related.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+function deriveLifecycleState(input) {
+    if (!input.exists)
+        return "absent";
+    if (input.needsAttention)
+        return "needs-attention";
+    if (input.awaitingDecision)
+        return "awaiting-decision";
+    if (input.activeRun)
+        return "running";
+    if (input.closeoutExists && input.promotionReady)
+        return "evidence-closed";
+    if (input.latestRun?.lifecycle === "completed") {
+        if (input.latestRun.status === "finished")
+            return "run-succeeded";
+        return "run-failed";
+    }
+    if (input.gateOpen)
+        return "awaiting-write-set-approval";
+    if (input.dagValidated)
+        return "dag-validated";
+    if (input.contractManaged && input.sourceReady)
+        return "contract-managed";
+    return "intake-incomplete";
+}
+export async function observeTaskLifecycle(repoRoot, taskId) {
+    const existsFlag = await taskExists(repoRoot, taskId);
+    if (!existsFlag) {
+        return {
+            schemaVersion: 1,
+            taskId,
+            exists: false,
+            lifecycleState: "absent",
+            runs: [],
+            completedTransitions: [],
+            blockers: [],
+            warnings: [],
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${taskId} --prd <path> --allowed-path <glob> --json`,
+            },
+        };
+    }
+    const paths = getTaskPaths(repoRoot, taskId);
+    const taskDir = getTaskDir(repoRoot, taskId);
+    const record = await loadLifecycleRecord(repoRoot, taskId);
+    const contractState = await observeTaskContractState(repoRoot, taskId);
+    let title;
+    let taskConfigAllowed = [];
+    try {
+        const config = await loadTaskConfig(repoRoot, taskId);
+        title = config.title;
+        taskConfigAllowed = config.allowedPaths ?? [];
+    }
+    catch {
+        // keep optional
+    }
+    const requirementPath = path.join(paths.sourceDir, "需求.md");
+    const constraintsPath = path.join(paths.sourceDir, "执行约束.md");
+    const requirementReady = await exists(requirementPath);
+    const constraintsReady = await exists(constraintsPath);
+    const missing = [
+        ...(requirementReady ? [] : [requirementPath]),
+        ...(constraintsReady ? [] : [constraintsPath]),
+    ];
+    let importedPrdCount = 0;
+    const referencesDir = path.join(paths.sourceDir, "references");
+    if (await exists(referencesDir)) {
+        // Count is best-effort; absence is fine.
+        try {
+            const { readdir } = await import("node:fs/promises");
+            const entries = await readdir(referencesDir);
+            importedPrdCount = entries.filter((name) => name.endsWith(".md")).length;
+        }
+        catch {
+            importedPrdCount = 0;
+        }
+    }
+    const dagDraftPath = paths.dagDraftPath;
+    const dagDraftExists = await exists(dagDraftPath);
+    let specHash = null;
+    let sourceBindingTaskId = null;
+    let taskContractBindingTaskId = null;
+    let writeSet = [];
+    let rawSpecText = null;
+    let parsedSpec = null;
+    if (dagDraftExists) {
+        try {
+            rawSpecText = await readFile(dagDraftPath, "utf-8");
+            specHash = hashDagSpecBytes(rawSpecText);
+            parsedSpec = JSON.parse(rawSpecText);
+            sourceBindingTaskId = parsedSpec.sourceBinding?.taskId ?? null;
+            taskContractBindingTaskId =
+                parsedSpec.taskContractBinding?.taskId ?? null;
+            writeSet = collectWriterWriteSet(parsedSpec);
+            if (writeSet.length === 0 && taskConfigAllowed.length > 0) {
+                writeSet = normalizeWriteSet(taskConfigAllowed);
+            }
+        }
+        catch {
+            specHash = null;
+        }
+    }
+    const runs = await listExplicitlyAssociatedRuns(repoRoot, taskId);
+    const activeRun = runs.find((run) => run.lifecycle === "active" || run.lifecycle === "paused") ?? null;
+    const latestRun = runs.length > 0 ? runs[runs.length - 1] : null;
+    const strictValidated = Boolean(record?.strictValidatedAt) &&
+        Boolean(record?.lastDagSpecHash) &&
+        record?.lastDagSpecHash === specHash;
+    const identity = resolveRunningControllerIdentity();
+    const gateBound = dagDraftExists && specHash
+        ? buildGateBinding({
+            taskId,
+            contractRevision: logicalRevisionForState(contractState),
+            contractCanonicalHash: contractState.ref?.canonicalHash ??
+                contractState.observedCanonicalHash ??
+                null,
+            sourceBindingHash: parsedSpec ? hashSourceBinding(parsedSpec) : null,
+            dagSpecHash: specHash,
+            writeSet,
+            controllerIdentityAnchor: controllerIdentityAnchor(identity
+                ? {
+                    packageName: identity.packageName,
+                    packageVersion: identity.packageVersion,
+                    packageFingerprintValue: identity.packageFingerprint.value,
+                }
+                : null),
+        })
+        : null;
+    const lastGate = record?.lastGate;
+    const currentDigest = gateBound != null
+        ? buildWriteSetGate({ taskId, bound: gateBound }).digest
+        : null;
+    const rejectedCurrent = lastGate?.status === "rejected" &&
+        Boolean(currentDigest) &&
+        lastGate.digest === currentDigest;
+    const approvedCurrent = lastGate?.status === "approved" &&
+        Boolean(currentDigest) &&
+        lastGate.digest === currentDigest;
+    // Open gate only when draft is strict-validated and the current binding is
+    // not already approved/rejected. Rejected same-digest gates stay closed
+    // until contract/source/DAG/writeSet/controller binding changes.
+    const gate = gateBound && strictValidated && !approvedCurrent && !rejectedCurrent
+        ? buildWriteSetGate({ taskId, bound: gateBound })
+        : null;
+    const gateOpen = Boolean(gate);
+    let legacyState;
+    try {
+        legacyState = await getTaskStatus(repoRoot, taskId);
+    }
+    catch {
+        legacyState = null;
+    }
+    const promotionReady = Boolean(legacyState?.artifacts.modifyLog && legacyState?.artifacts.verifyResult);
+    const closeout = closeoutPath(repoRoot, taskId);
+    const closeoutExists = await exists(closeout);
+    const awaitingDecision = activeRun?.lifecycle === "paused" ||
+        activeRun?.status === "paused" ||
+        Boolean(activeRun?.status === "waiting-for-human");
+    const needsAttention = activeRun?.status === "error" ||
+        (activeRun?.lifecycle === "active" &&
+            (activeRun.failureCategory === "termination-unconfirmed" ||
+                activeRun.failureCategory === "orphaned" ||
+                activeRun.failureCategory === "stale-heartbeat" ||
+                activeRun.failureCategory === "needs-attention" ||
+                activeRun.failureCategory === "suspected-stall" ||
+                activeRun.failureCategory === "monitor-timeout"));
+    const contractManaged = contractState.effectiveStatus === "managed" || Boolean(contractState.ref);
+    const lifecycleState = deriveLifecycleState({
+        exists: true,
+        contractManaged,
+        sourceReady: requirementReady,
+        dagValidated: strictValidated,
+        gateOpen: Boolean(gate),
+        activeRun,
+        latestRun,
+        promotionReady,
+        closeoutExists: closeoutExists || Boolean(record?.closeout),
+        needsAttention: Boolean(needsAttention),
+        awaitingDecision: Boolean(awaitingDecision),
+    });
+    const next = deriveNextFromSnapshot({
+        taskId,
+        lifecycleState,
+        gate,
+    });
+    return {
+        schemaVersion: 1,
+        taskId,
+        exists: true,
+        lifecycleState,
+        title,
+        taskDir,
+        contract: {
+            effectiveStatus: contractState.effectiveStatus,
+            revision: logicalRevisionForState(contractState),
+            canonicalHash: contractState.ref?.canonicalHash ?? null,
+            observedCanonicalHash: contractState.observedCanonicalHash ?? null,
+            transactionIncomplete: contractState.effectiveStatus === "transaction-incomplete",
+            taskConfigSha256: contractState.ref?.taskConfigSha256 ?? null,
+            projectionVersion: contractState.ref?.projectionVersion ?? null,
+            canonicalizerVersion: contractState.ref?.canonicalizerVersion ?? null,
+            taskConfigSchemaVersion: contractState.ref?.taskConfigSchemaVersion ?? null,
+        },
+        source: {
+            requirementReady,
+            constraintsReady,
+            importedPrdCount,
+            missing,
+        },
+        dagDraft: {
+            path: dagDraftPath,
+            exists: dagDraftExists,
+            specHash,
+            sourceBindingTaskId,
+            taskContractBindingTaskId,
+            writeSet,
+            strictValidated,
+        },
+        gate,
+        activeRun,
+        latestRun,
+        runs,
+        promotion: {
+            required: Boolean(latestRun && latestRun.lifecycle === "completed"),
+            ready: promotionReady || Boolean(record?.promotion),
+        },
+        closeout: {
+            path: closeout,
+            exists: closeoutExists || Boolean(record?.closeout),
+        },
+        completedTransitions: record?.completedTransitions ?? [],
+        blockers: [],
+        warnings: [],
+        next,
+    };
+}
+function deriveNextFromSnapshot(input) {
+    if (input.lifecycleState === "evidence-closed") {
+        return { kind: "none" };
+    }
+    if (input.gate && input.lifecycleState === "awaiting-write-set-approval") {
+        return {
+            kind: "approve-gate",
+            command: input.gate.approveCommand,
+        };
+    }
+    if (input.lifecycleState === "running") {
+        return {
+            kind: "status",
+            command: `loop-agent task status ${input.taskId} --json`,
+        };
+    }
+    return {
+        kind: "advance",
+        command: `loop-agent task advance ${input.taskId} --json`,
+    };
+}
+export function hashDagSpecFileContent(content) {
+    return hashDagSpecBytes(content);
+}
+export function collectNormalizedWriteSetFromSpec(spec) {
+    return collectWriterWriteSet(spec);
+}