@tea-agent/loop-agent 0.10.0 → 0.12.0

package/dist/workflows/dag/runner.js

@@ -5,10 +5,14 @@ import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/r
 import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
 import { moveToCompletedRunDir, moveToPausedRunDir, prepareActiveRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { createDagNodeExecutor } from "./executor-registry.js";
-import { executeDagCursorNode } from "../../executors/dag-cursor-executor.js";
+import { executeDagPiNode } from "../../executors/dag-pi-executor.js";
 import { assertValidDagSpec } from "./validate.js";
+import { assertRuntimeContractCompatible, DAG_CONTROLLER_CAPABILITIES, } from "./runtime-contract.js";
+import { captureControllerIdentity, verifyControllerIdentityForResume, } from "./controller-identity.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { normalizeDagPromptSources } from "./prompt-source.js";
 import { relocateConvergenceArtifactPaths, relocateRunArtifactPaths, } from "./upstream-artifacts.js";
+import { createSkillSnapshot, prepareSkillSnapshotForContinuation, writeSkillSnapshot, } from "./skill-snapshot.js";
 import { buildNodePrompt, buildNodePromptWithResolvedSkillInstructions, executeDagNode, } from "./node-execution.js";
 import { runConvergencePassController, shouldEnableDagConvergence, } from "./convergence/controller.js";
 import { executeDagRanksOnce, isConditionSkippedReason, } from "./scheduler.js";
@@ -144,6 +148,15 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
 }
 export async function runDag(spec, opts) {
     assertValidDagSpec(spec);
+    // Capability preflight must fail closed before any run directory or node work.
+    const runningIdentity = resolveRunningControllerIdentity();
+    if (!runningIdentity) {
+        throw new Error("running controller identity could not be resolved; refuse to create an unpinned DAG run");
+    }
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        controllerVersion: runningIdentity.packageVersion,
+    });
     const { ranks } = topoSortToRanks(spec);
     const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
     let runId = opts.runId;
@@ -162,6 +175,25 @@ export async function runDag(spec, opts) {
     const runDir = activeRunDir;
     await prepareActiveRunDir(runDir);
     await writeRunSpec(runDir, spec);
+    // Freeze the running controller identity as a run-owned fact before the
+    // first canonical state write, reusing the identity resolved for preflight.
+    state.controllerIdentityRef = await captureControllerIdentity({
+        runDir,
+        identity: runningIdentity,
+    });
+    // Resolve and snapshot all skill profiles before any node executes.
+    try {
+        const snapshot = await createSkillSnapshot({
+            runId: state.runId,
+            spec,
+            cwd: opts.cwd,
+            mode: "run-start",
+        });
+        state.skillSnapshotRef = await writeSkillSnapshot(runDir, snapshot);
+    }
+    catch (error) {
+        throw new Error(`failed to create run-start skill snapshot: ${error instanceof Error ? error.message : String(error)}`);
+    }
     await writeRunState(runDir, state);
     await notifyRunObserver(opts.observer, "onRunStart", state);
     if (opts.dryRun || opts.initOnly) {
@@ -190,7 +222,6 @@ export async function runDag(spec, opts) {
         });
     }
     finally {
-        await stopCursorWorkerIfRunning();
     }
 }
 export async function resumeDagRun(opts) {
@@ -211,6 +242,20 @@ export async function resumeDagRun(opts) {
     if (isTerminalDagRunStatus(state.status)) {
         throw new Error(`dag run ${opts.runId} is already terminal (status=${state.status})`);
     }
+    // Runtime contract + controller identity must be re-verified before executing
+    // any remaining node on resume; drift fails closed.
+    const runningIdentity = resolveRunningControllerIdentity();
+    if (!runningIdentity) {
+        throw new Error("running controller identity could not be resolved; refuse to resume an unpinned DAG run");
+    }
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        controllerVersion: runningIdentity.packageVersion,
+    });
+    await verifyControllerIdentityForResume({
+        runDir,
+        state,
+    });
     const decisionNodeId = state.humanDecisionNodeId;
     if (!decisionNodeId) {
         throw new Error(`dag run ${opts.runId} has no human decision checkpoint; was it approved?`);
@@ -221,6 +266,25 @@ export async function resumeDagRun(opts) {
     catch {
         throw new Error(`dag run ${opts.runId} is missing human-approval.json for node ${decisionNodeId}`);
     }
+    // Validate or backfill before mutating runner/status for this resume attempt.
+    try {
+        const prepared = await prepareSkillSnapshotForContinuation({
+            runDir,
+            runId: state.runId,
+            spec,
+            state,
+            cwd: state.cwd,
+            ref: state.skillSnapshotRef,
+        });
+        if (prepared.backfilled) {
+            console.warn(`[dag resume] warning: run ${state.runId} has no skill snapshot ref; creating a legacy-resume-backfill that freezes remaining nodes only`);
+            state.skillSnapshotRef = prepared.ref;
+            await writeRunState(runDir, state);
+        }
+    }
+    catch (error) {
+        throw new Error(`skill snapshot validation failed on resume: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
     state.status = "running";
     const resumedAt = new Date().toISOString();
@@ -249,7 +313,6 @@ export async function resumeDagRun(opts) {
         });
     }
     finally {
-        await stopCursorWorkerIfRunning();
     }
 }
 async function executeDagCheckpoint(input) {
@@ -314,10 +377,10 @@ async function executeDagCheckpoint(input) {
                 tasksById,
                 maxConcurrent,
                 persistState,
-                createExecuteNodeForRank: (rankCursorNodeIds) => buildRankAwareExecuteNode({
+                createExecuteNodeForRank: (rankWriterNodeIds) => buildRankAwareExecuteNode({
                     baseExecuteNode,
                     customExecuteNode: input.executeNode,
-                    rankCursorNodeIds,
+                    rankWriterNodeIds,
                     tasksById,
                     meta: { runDir, runId: state.runId, spec },
                 }),
@@ -413,16 +476,10 @@ function finalizeTerminalRunStatus(state, taskCount) {
         state.status = "failed";
     }
 }
-async function stopCursorWorkerIfRunning() {
-    const { isCursorWorkerRunning, stopCursorWorker } = await import("../../executors/cursor-worker-client.js");
-    if (isCursorWorkerRunning()) {
-        await stopCursorWorker();
-    }
-}
-function concurrentSiblingWriteSetsForNode(rankCursorNodeIds, nodeId, tasksById) {
-    if (rankCursorNodeIds.length <= 1)
+function concurrentSiblingWriteSetsForNode(rankWriterNodeIds, nodeId, tasksById) {
+    if (rankWriterNodeIds.length <= 1)
         return [];
-    return rankCursorNodeIds
+    return rankWriterNodeIds
         .filter((id) => id !== nodeId)
         .map((id) => tasksById.get(id)?.writeSet ?? [])
         .filter((writeSet) => writeSet.length > 0);
@@ -432,13 +489,16 @@ function buildRankAwareExecuteNode(input) {
         return input.baseExecuteNode;
     }
     return async (nodeInput) => {
-        if (nodeInput.task.executor !== "cursor" || !nodeInput.model) {
+        const isPiWriter = nodeInput.task.executor === "pi" &&
+            nodeInput.task.toolProfile === "write" &&
+            Boolean(nodeInput.model);
+        if (!isPiWriter) {
             return input.baseExecuteNode(nodeInput);
         }
         const siblingWriteSets = nodeInput.task.writePolicy === "exclusive"
-            ? concurrentSiblingWriteSetsForNode(input.rankCursorNodeIds, nodeInput.task.id, input.tasksById)
+            ? concurrentSiblingWriteSetsForNode(input.rankWriterNodeIds, nodeInput.task.id, input.tasksById)
             : [];
-        return executeDagCursorNode({ ...nodeInput, model: nodeInput.model }, {
+        return executeDagPiNode({ ...nodeInput, model: nodeInput.model }, {
             ...input.meta,
             concurrentSiblingWriteSets: siblingWriteSets.length > 0 ? siblingWriteSets : undefined,
             writeGuardAttribution: siblingWriteSets.length > 0 ? "best-effort" : "per-node",

package/dist/workflows/dag/runtime-contract.js

@@ -0,0 +1,87 @@
+import { DAG_AGENT_RUNTIME_PI_ONLY, DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1, DAG_RUNTIME_CONTRACT_SCHEMA_VERSION, } from "./types.js";
+export const DAG_CONTROLLER_CAPABILITIES = {
+    schemaVersion: DAG_RUNTIME_CONTRACT_SCHEMA_VERSION,
+    agentRuntime: DAG_AGENT_RUNTIME_PI_ONLY,
+    repairWriterProtocol: DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1,
+};
+function parseSemver(value) {
+    const match = value.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/** Returns true when `actual` is greater than or equal to `required`. */
+export function semverGte(actual, required) {
+    const a = parseSemver(actual);
+    const r = parseSemver(required);
+    if (!a || !r)
+        return false;
+    if (a.major !== r.major)
+        return a.major > r.major;
+    if (a.minor !== r.minor)
+        return a.minor > r.minor;
+    return a.patch >= r.patch;
+}
+/**
+ * Decide whether a controller can run a DagSpec's declared runtimeContract.
+ *
+ * Capability fields are authoritative: an unsupported agentRuntime or
+ * repairWriterProtocol fails closed regardless of version. minimumControllerVersion
+ * is only consulted for diagnosis when the controller version is known and the
+ * capabilities otherwise match.
+ *
+ * Legacy DagSpecs without a runtimeContract are always compatible (they predate
+ * the capability handshake and rely on runtime-side derivation).
+ */
+export function checkRuntimeContractCompatible(contract, capabilities = DAG_CONTROLLER_CAPABILITIES) {
+    if (!contract)
+        return { ok: true };
+    if (contract.schemaVersion !== capabilities.schemaVersion) {
+        return {
+            ok: false,
+            reason: `runtime contract schemaVersion ${contract.schemaVersion} is not supported by this controller (supports ${capabilities.schemaVersion}); regenerate the DAG or upgrade the controller`,
+        };
+    }
+    if (contract.agentRuntime !== capabilities.agentRuntime) {
+        return {
+            ok: false,
+            reason: `runtime contract requires agentRuntime "${contract.agentRuntime}" but this controller advertises "${capabilities.agentRuntime}"; upgrade the controller or regenerate the DAG`,
+        };
+    }
+    if (contract.repairWriterProtocol !== capabilities.repairWriterProtocol) {
+        return {
+            ok: false,
+            reason: `runtime contract requires repairWriterProtocol "${contract.repairWriterProtocol}" but this controller advertises "${capabilities.repairWriterProtocol}"; upgrade the controller or regenerate the DAG`,
+        };
+    }
+    if (contract.minimumControllerVersion &&
+        !capabilities.controllerVersion) {
+        return {
+            ok: false,
+            reason: `runtime contract requires controller version >= ${contract.minimumControllerVersion} but the running controller version could not be resolved; refuse to continue unpinned`,
+        };
+    }
+    if (contract.minimumControllerVersion &&
+        capabilities.controllerVersion &&
+        !semverGte(capabilities.controllerVersion, contract.minimumControllerVersion)) {
+        return {
+            ok: false,
+            reason: `runtime contract requires controller version >= ${contract.minimumControllerVersion} but this controller reports ${capabilities.controllerVersion}; upgrade the controller`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Fail closed before any node execution when the DagSpec's runtimeContract is
+ * incompatible with this controller.
+ */
+export function assertRuntimeContractCompatible(spec, capabilities = DAG_CONTROLLER_CAPABILITIES) {
+    const result = checkRuntimeContractCompatible(spec.runtimeContract, capabilities);
+    if (!result.ok) {
+        throw new Error(`incompatible DAG runtime contract: ${result.reason}`);
+    }
+}

package/dist/workflows/dag/scheduler.js

@@ -55,8 +55,13 @@ export async function executeDagRanksOnce(input) {
             return isPauseOnHumanDecisionGate(task);
         });
         const regularRunnable = runnable.filter((id) => !pauseGateRunnable.includes(id));
-        const rankCursorNodeIds = runnable.filter((id) => input.tasksById.get(id)?.executor === "cursor");
-        const executeNode = input.createExecuteNodeForRank(rankCursorNodeIds);
+        const rankWriterNodeIds = runnable.filter((id) => {
+            const task = input.tasksById.get(id);
+            return (task?.executor === "pi" &&
+                task.toolProfile === "write" &&
+                task.writePolicy === "exclusive");
+        });
+        const executeNode = input.createExecuteNodeForRank(rankWriterNodeIds);
         for (const nodeId of pauseGateRunnable) {
             await input.executeScheduledNode(nodeId, executeNode, (id, pausedAt, pauseReason) => {
                 pausedByNodeId = id;

package/dist/workflows/dag/sdd-embedded.js

@@ -0,0 +1,128 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+/**
+ * SDD embedded-mode optional enhancement.
+ *
+ * When the target project ships repo-local `SDD-*` skills (under
+ * `.agents/skills/<name>/SKILL.md`), loop-agent can
+ * reuse them as knowledge/method references inside individual DAG nodes. This
+ * module probes those repo-local paths and, on a hit, appends the matched skill
+ * name to the mapped node's `task.skills` (so it flows through the existing
+ * run-owned skill snapshot via `resolveDagNodeSkills`) plus a loop-agent-managed
+ * embedded-mode constraint block to the node prompt.
+ *
+ * loop-agent always owns process/state/verification/closeout. SDD state
+ * transitions, confirmation gates, and archival are explicitly forbidden inside
+ * the embedded-mode block.
+ */
+/** The three SDD skills that may be reused as repo-local knowledge. */
+export const SDD_SKILL_NAMES = [
+    "SDD-requirement-analysis",
+    "SDD-design-analysis",
+    "SDD-implementation-test-review",
+];
+/**
+ * DAG node id -> mapped SDD skill name. `verify-pi` is present in standard and
+ * review-gated templates; supervised verification stays shell-based. The init skills
+ * (`SDD-code-spec-init`, `SDD-project-how-to-spec-init`) are intentionally
+ * absent: they are never auto-executed inside a normal feature DAG.
+ */
+export const SDD_NODE_SKILL_MAP = {
+    "contract-pi": "SDD-requirement-analysis",
+    "plan-pi": "SDD-design-analysis",
+    "implement-pi": "SDD-implementation-test-review",
+    "repair-pi": "SDD-implementation-test-review",
+    "verify-pi": "SDD-implementation-test-review",
+    "review-pi": "SDD-implementation-test-review",
+};
+/** DAG node id -> SDD phase label injected into the constraint block. */
+export const SDD_NODE_PHASE_LABEL = {
+    "contract-pi": "需求",
+    "plan-pi": "设计",
+    "implement-pi": "实现",
+    "repair-pi": "修复",
+    "verify-pi": "验证",
+    "review-pi": "审查",
+};
+/** Fence tokens used to delimit the embedded-mode constraint block. */
+export const SDD_EMBEDDED_MODE_OPEN = "[SDD-EMBEDDED-MODE]";
+export const SDD_EMBEDDED_MODE_CLOSE = "[/SDD-EMBEDDED-MODE]";
+const SDD_SKILL_CANDIDATE_BASES = [".agents/skills"];
+/**
+     * Probe the target project repo for repo-local SDD skills. Only the canonical
+     * repo-relative `.agents/skills` base is checked; this deliberately does NOT reuse
+ * the skill loader candidate list (which also falls back to user-level and
+ * bundled package skills) so user-level/package skills never trigger
+ * auto-enhancement.
+ *
+ * Returns the set of SDD skill names whose `SKILL.md` exists under at least one
+ * repo-local base. Returns an empty set when `repoRoot` is absent so callers
+ * that do not pass a repo root preserve byte-level default output.
+ */
+export async function probeRepoLocalSddSkills(repoRoot) {
+    if (!repoRoot)
+        return new Set();
+    const hits = new Set();
+    for (const name of SDD_SKILL_NAMES) {
+        for (const base of SDD_SKILL_CANDIDATE_BASES) {
+            const candidate = path.join(repoRoot, base, name, "SKILL.md");
+            try {
+                await access(candidate);
+                hits.add(name);
+                break;
+            }
+            catch {
+                // not present at this candidate base; try the next
+            }
+        }
+    }
+    return hits;
+}
+/**
+ * Build the loop-agent-managed embedded-mode constraint block for a node. The
+ * block declares DAG-node-boundary priority and forbids SDD state transitions,
+ * confirmation gates, working_requirements_status updates, and archival.
+ *
+ * Returns `null` for unmapped node ids (e.g. scouts, shell gates, closeout).
+ */
+export function buildSddEmbeddedConstraintBlock(nodeId) {
+    const phase = SDD_NODE_PHASE_LABEL[nodeId];
+    if (!phase)
+        return null;
+    return [
+        SDD_EMBEDDED_MODE_OPEN,
+        `当前 DAG 节点: ${nodeId}，阶段: ${phase}`,
+        "loop-agent 拥有流程、状态、验证与收口控制权；SDD skill 仅作 repo-local 知识与方法参考。",
+        "禁止：更新 working_requirements_status.md；推进 SDD 阶段；触发 SDD 用户确认；执行归档。",
+        "优先级：本节点的读写边界、当前阶段与输出契约优先于任何 SDD 指令冲突。",
+        "implement/repair writer 仍必须服从当前 writeSet/allowedPaths/forbiddenPaths；不得把 ai_workspace 加入隐式写范围，也不得解析或写入 SDD 工作区状态机。",
+        SDD_EMBEDDED_MODE_CLOSE,
+    ].join("\n");
+}
+/**
+ * Apply SDD embedded-mode enhancements in place on a fully-constructed DAG spec.
+ *
+ * For each mapped task whose mapped skill is present in the hit set:
+ *  - append the skill name to `task.skills` (de-duplicated, order-preserving);
+ *  - append the constraint block to the end of `task.subtask_prompt` (once).
+ *
+ * When the hit set is empty this is a no-op, preserving the default DAG byte
+ * for byte. The function is idempotent.
+ */
+export function applySddEmbeddedEnhancements(spec, hitSkills) {
+    if (hitSkills.size === 0)
+        return;
+    for (const task of spec.tasks) {
+        const mapped = SDD_NODE_SKILL_MAP[task.id];
+        if (!mapped || !hitSkills.has(mapped))
+            continue;
+        const existing = task.skills ?? [];
+        if (!existing.includes(mapped)) {
+            task.skills = [...existing, mapped];
+        }
+        const block = buildSddEmbeddedConstraintBlock(task.id);
+        if (block && !task.subtask_prompt.includes(SDD_EMBEDDED_MODE_OPEN)) {
+            task.subtask_prompt = `${task.subtask_prompt}\n\n${block}`;
+        }
+    }
+}

package/dist/workflows/dag/skill-instructions.js

@@ -41,11 +41,12 @@ function buildSkillCandidatePaths(input) {
     }
     const piSkillsDir = path.join(input.homeDir, ".pi", "agent", "skills");
     candidates.push(normalizeCandidate(path.join(piSkillsDir, input.name, "SKILL.md")), normalizeCandidate(path.join(piSkillsDir, `${input.name}.md`)));
-    candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
-    // Agent-compatible project path (e.g. OpenCode). `skills/` stays the primary
-    // loop-agent repo-local path; `.agents/skills` is searched after it and before
-    // bundled skills so a project with only the mirror can still resolve.
+    // Canonical target-project repo-local skill path.
     candidates.push(normalizeCandidate(path.join(input.cwd, ".agents", "skills", input.name, "SKILL.md")));
+    // Source-repository compatibility: the loop-agent package itself still ships
+    // bundled skills under `skills/`, and local source development may resolve them
+    // before the package fallback is found.
+    candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
     if (input.name === "loop-agent") {
         candidates.push(normalizeCandidate(path.join(input.cwd, "skill", "SKILL.md")));
     }