@tea-agent/loop-agent 0.1.0 → 0.2.0

package/dist/application/dag/report-dag.js

@@ -0,0 +1,14 @@
+import { buildDagReport, serializeDagReportJson, } from "../../workflows/dag/report.js";
+export async function reportDagUseCase(input) {
+    return buildDagReport({
+        repoRoot: input.repoRoot,
+        runId: input.runId,
+        lifecycle: input.lifecycle,
+        failedOnly: input.failedOnly,
+        latest: input.latest,
+        action: input.action,
+    });
+}
+export function serializeReportDagJson(report) {
+    return serializeDagReportJson(report);
+}

package/dist/application/dag/run-dag.js

@@ -0,0 +1,93 @@
+import { readFile } from "node:fs/promises";
+import { createDagCanvasObserver, resolveCanvasPath, } from "../../workflows/dag/canvas-observer.js";
+import { loadDagSpecFromFile, runDag } from "../../workflows/dag/runner.js";
+import { assertValidDagSpec, collectForbiddenExecutorIssues, } from "../../workflows/dag/validate.js";
+async function loadRawTaskExecutorMap(dagPath) {
+    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
+    const map = new Map();
+    for (const task of raw.tasks ?? []) {
+        if (typeof task.id === "string")
+            map.set(task.id, task.executor);
+    }
+    return map;
+}
+function assertNoCursorTasks(spec, rawTaskExecutors) {
+    const issues = collectForbiddenExecutorIssues(spec, ["cursor"]);
+    if (issues.length === 0)
+        return;
+    const details = issues
+        .map((issue) => {
+        const implicitDefault = rawTaskExecutors.get(issue.taskId) === undefined;
+        return `task=${issue.taskId}${implicitDefault ? " (implicit cursor default)" : ""}`;
+    })
+        .join("; ");
+    throw new Error(`--no-cursor forbids cursor executor tasks: ${details}`);
+}
+function getCanvasFlushErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function flushCanvasSafely(canvas) {
+    if (!canvas)
+        return undefined;
+    try {
+        await canvas.flush();
+        return undefined;
+    }
+    catch (error) {
+        // Canvas is a derived view; failed writes must not decide canonical DAG success.
+        return getCanvasFlushErrorMessage(error);
+    }
+}
+export async function runDagUseCase(input) {
+    const spec = await loadDagSpecFromFile(input.dagPath);
+    if (input.noCursor) {
+        const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
+        assertNoCursorTasks(spec, rawTaskExecutors);
+    }
+    assertValidDagSpec(spec);
+    const resolvedCanvasPath = resolveCanvasPath({
+        canvasPath: input.canvasPath,
+        canvasName: input.canvasName,
+        canvasesDir: input.canvasesDir,
+        cwd: input.cwd,
+    });
+    const canvas = resolvedCanvasPath
+        ? createDagCanvasObserver({ canvasPath: resolvedCanvasPath, spec })
+        : undefined;
+    if (input.dryRun) {
+        const summary = await runDag(spec, {
+            cwd: input.cwd,
+            dryRun: true,
+            runId: input.runId,
+            observer: canvas?.observer,
+        });
+        const canvasError = await flushCanvasSafely(canvas);
+        return {
+            mode: "dry-run",
+            title: spec.title,
+            taskCount: spec.tasks.length,
+            ranks: summary.ranks,
+            runId: summary.runId,
+            runDir: summary.runDir,
+            ...(resolvedCanvasPath ? { canvasPath: resolvedCanvasPath } : {}),
+            ...(canvasError ? { canvasError } : {}),
+        };
+    }
+    const summary = await runDag(spec, {
+        cwd: input.cwd,
+        initOnly: input.initOnly,
+        dryRun: false,
+        maxConcurrent: input.maxConcurrent,
+        runId: input.runId,
+        observer: canvas?.observer,
+    });
+    const canvasError = await flushCanvasSafely(canvas);
+    if (resolvedCanvasPath) {
+        return {
+            ...summary,
+            canvasPath: resolvedCanvasPath,
+            ...(canvasError ? { canvasError } : {}),
+        };
+    }
+    return summary;
+}

package/dist/application/dag/validate-dag.js

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { loadDagSpecFromFile } from "../../workflows/dag/runner.js";
+import { assertValidDagSpec, collectExecutorModelWarnings, collectForbiddenExecutorIssues, collectGovernanceWarnings, validateDagSpec, } from "../../workflows/dag/validate.js";
+import { inferGovernanceProfile } from "../../workflows/dag/governance-profile.js";
+import { topoSortToRanks } from "../../workflows/dag/topo.js";
+import { runSpineAudit } from "../../governance/spine-audit.js";
+function formatModelMatrixWarnings(warnings) {
+    return warnings.map((warning) => ({
+        executor: warning.executor,
+        complexity: warning.complexity,
+        expected: warning.expected,
+        actual: warning.actual,
+    }));
+}
+function formatGovernanceWarnings(warnings) {
+    return warnings.map((warning) => ({
+        type: warning.type,
+        message: warning.message,
+    }));
+}
+function ensureStrictModelMatrix(warnings) {
+    if (warnings.length === 0) {
+        return;
+    }
+    const details = warnings
+        .map((entry) => `executor=${entry.executor}, complexity=${entry.complexity}, expected=${entry.expected}, actual=${entry.actual}`)
+        .join("; ");
+    throw new Error(`non-canonical executorModels overrides are blocked by --strict-models: ${details}`);
+}
+async function loadRawTaskExecutorMap(dagPath) {
+    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
+    const map = new Map();
+    for (const task of raw.tasks ?? []) {
+        if (typeof task.id === "string")
+            map.set(task.id, task.executor);
+    }
+    return map;
+}
+function ensureNoForbiddenExecutors(spec, forbidExecutors, rawTaskExecutors) {
+    const supported = new Set(["cursor", "pi", "shell", "static"]);
+    const normalized = forbidExecutors.map((executor) => {
+        if (!supported.has(executor)) {
+            throw new Error(`unsupported executor for --forbid-executor: ${executor}`);
+        }
+        return executor;
+    });
+    const issues = collectForbiddenExecutorIssues(spec, normalized);
+    if (issues.length === 0)
+        return;
+    const details = issues
+        .map((issue) => {
+        const implicitDefault = rawTaskExecutors.get(issue.taskId) === undefined;
+        return `task=${issue.taskId}, executor=${issue.executor}${implicitDefault ? " (implicit default)" : ""}`;
+    })
+        .join("; ");
+    throw new Error(`forbidden executor present: ${details}`);
+}
+export async function validateDagUseCase(input) {
+    const spec = await loadDagSpecFromFile(input.dagPath);
+    const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
+    ensureNoForbiddenExecutors(spec, input.forbidExecutors, rawTaskExecutors);
+    const validationIssues = validateDagSpec(spec);
+    const warnings = collectExecutorModelWarnings(spec);
+    const governanceWarnings = collectGovernanceWarnings(validationIssues);
+    if (input.strictModelMatrix) {
+        ensureStrictModelMatrix(warnings);
+    }
+    const spineAudit = input.spineTaskId
+        ? await runSpineAudit(input.repoRoot, input.spineTaskId)
+        : undefined;
+    if (input.strictGovernance && spineAudit && !spineAudit.ok) {
+        throw new Error(`minimal spec spine audit failed for ${input.spineTaskId}: ${spineAudit.findings
+            .filter((finding) => finding.severity === "error")
+            .map((finding) => `${finding.type}: ${finding.message}`)
+            .join("; ")}`);
+    }
+    assertValidDagSpec(spec, {
+        issues: validationIssues,
+        strictGovernance: input.strictGovernance,
+    });
+    const { ranks } = topoSortToRanks(spec);
+    const governanceProfile = inferGovernanceProfile(spec);
+    return {
+        title: spec.title,
+        taskCount: spec.tasks.length,
+        ranks,
+        governanceProfile,
+        spineAudit: spineAudit
+            ? {
+                ok: spineAudit.ok,
+                taskId: spineAudit.taskId,
+                findings: spineAudit.findings,
+                verifyCommandLabels: spineAudit.verifyCommandLabels,
+            }
+            : undefined,
+        warnings: [
+            ...formatModelMatrixWarnings(warnings),
+            ...formatGovernanceWarnings(governanceWarnings),
+        ],
+    };
+}

package/dist/application/loop/run-action.js

@@ -0,0 +1,23 @@
+import { runLoopCursorFix } from "../../workflows/loop/actions/cursor-fix.js";
+import { runLoopDagAction } from "../../workflows/loop/actions/dag-action.js";
+import { runLoopPiReview } from "../../workflows/loop/actions/pi-review.js";
+import { runLoopShellVerification, } from "../../workflows/loop/actions/shell-verify.js";
+import { runLoopWorkflowAction, runLoopWorkflowGateSignalAction, } from "../../workflows/loop/actions/workflow-action.js";
+export async function runLoopAction(input) {
+    if (input.action === "shell-verify") {
+        return runLoopShellVerification(input.repoRoot, input.taskId, input.options);
+    }
+    if (input.action === "pi-review") {
+        return runLoopPiReview(input.repoRoot, input.taskId, input.options);
+    }
+    if (input.action === "cursor-fix") {
+        return runLoopCursorFix(input.repoRoot, input.taskId, input.options);
+    }
+    if (input.action === "dag") {
+        return runLoopDagAction(input.repoRoot, input.taskId, input.options);
+    }
+    if (input.action === "workflow") {
+        return runLoopWorkflowAction(input.repoRoot, input.taskId, input.options);
+    }
+    return runLoopWorkflowGateSignalAction(input.repoRoot, input.taskId, input.options?.signals);
+}

package/dist/cli/catalog.js

@@ -1,241 +1,6 @@
+import { COMMAND_DEFINITIONS, toCommandManifestEntry, } from "./command-definitions.js";
 /** Order remains stable for compatibility; tiers provide the selection signal. */
-export const CODE_AGENT_COMMAND_MANIFEST = [
-    {
-        name: "inspect",
-        adapter: "required",
-        tier: "operator",
-        intent: "Inspect the target repo harness manifest.",
-        usage: "inspect",
-    },
-    {
-        name: "doctor",
-        adapter: "required",
-        tier: "operator",
-        intent: "Check local loop-agent runtime health.",
-        usage: "doctor",
-    },
-    {
-        name: "docs",
-        adapter: "required",
-        tier: "operator",
-        intent: "Audit or archive repo governance documents.",
-        usage: "docs <audit|archive> ...",
-        subcommands: ["audit", "archive"],
-    },
-    {
-        name: "new-task",
-        adapter: "required",
-        tier: "primary",
-        intent: "Create a harness task before DAG autonomous work.",
-        usage: "new-task <task-id> [title]",
-    },
-    {
-        name: "status",
-        adapter: "required",
-        tier: "operator",
-        intent: "Inspect a task state and machine-readable action context.",
-        usage: "status <task-id> [--json]",
-    },
-    {
-        name: "instructions",
-        adapter: "required",
-        tier: "operator",
-        intent: "Resolve task artifact targets, dependencies, templates, and write policy.",
-        usage: "instructions <source|dag-draft|task-artifacts|promotion|closeout> --task <task-id> [--json]",
-    },
-    {
-        name: "promote-run",
-        adapter: "required",
-        tier: "operator",
-        intent: "Promote completed DAG or one-shot run evidence into task artifacts without mutating run facts.",
-        usage: "promote-run <task-id> --run-id <run-id>",
-    },
-    {
-        name: "closeout",
-        adapter: "required",
-        tier: "operator",
-        intent: "Create deterministic task closeout/progress records from promoted task artifacts.",
-        usage: "closeout task <task-id>",
-        subcommands: ["task"],
-    },
-    {
-        name: "stats",
-        adapter: "required",
-        tier: "operator",
-        intent: "Inspect historical step duration statistics.",
-        usage: "stats",
-    },
-    {
-        name: "plan",
-        adapter: "required",
-        tier: "operator",
-        intent: "List repo execution plans.",
-        usage: "plan <list>",
-        subcommands: ["list"],
-    },
-    {
-        name: "spine",
-        adapter: "required",
-        tier: "operator",
-        intent: "Audit a task minimal spec spine: source, path ownership, requirements, and final verification coverage.",
-        usage: "spine audit <task-id> [--json|--markdown]",
-        subcommands: ["audit"],
-    },
-    {
-        name: "handoff",
-        adapter: "required",
-        tier: "operator",
-        intent: "Check task handoff completeness and requirement coverage.",
-        usage: "handoff <check|coverage> [taskId]",
-        subcommands: ["check", "coverage"],
-    },
-    {
-        name: "goal",
-        adapter: "required",
-        tier: "compatibility",
-        compatibilityStatus: "deprecated-candidate",
-        intent: "Manage legacy task continuation goals (compatibility-only; prefer Agent DAG closeout).",
-        usage: "goal <set|get|pause|resume|clear> ...",
-    },
-    {
-        name: "reference",
-        adapter: "required",
-        tier: "compatibility",
-        compatibilityStatus: "compatibility-only",
-        intent: "Index external references for feature-study tasks (compatibility-only).",
-        usage: "reference <index> <task-id>",
-        subcommands: ["index"],
-    },
-    {
-        name: "study",
-        adapter: "required",
-        tier: "compatibility",
-        compatibilityStatus: "compatibility-only",
-        intent: "Initialize feature-study tasks (compatibility-only; prefer DAG work).",
-        usage: "study init <task-id> [title] ...",
-        subcommands: ["init"],
-    },
-    {
-        name: "worktree",
-        adapter: "required",
-        tier: "escape-hatch",
-        intent: "Manage delegated worktrees directly.",
-        usage: "worktree <create|list|remove> ...",
-        subcommands: ["create", "list", "remove"],
-    },
-    {
-        name: "delegate",
-        adapter: "required",
-        tier: "escape-hatch",
-        intent: "Prepare or run isolated executor delegation outside the normal DAG path.",
-        usage: "delegate <task-id> [options]",
-    },
-    {
-        name: "harvest",
-        adapter: "required",
-        tier: "escape-hatch",
-        intent: "Merge and close isolated delegated work after completion.",
-        usage: "harvest <task-id> [options]",
-    },
-    {
-        name: "cursor-worker",
-        adapter: "required",
-        tier: "escape-hatch",
-        intent: "Inspect or control the optional Cursor SDK worker process.",
-        usage: "cursor-worker <status|stop|ping>",
-    },
-    {
-        name: "knowledge",
-        adapter: "required",
-        tier: "operator",
-        intent: "Curate completed convergence patterns into human-gated learned guidance proposals.",
-        usage: "knowledge curate [--json|--markdown] [--output <path>]",
-        subcommands: ["curate"],
-    },
-    {
-        name: "dag",
-        adapter: "required",
-        tier: "primary",
-        intent: "Generate, validate, inspect, recover, close out Agent DAG runs, and use experimental dynamic workflow compile seams.",
-        usage: "dag <init-hybrid|run-task|validate|workflow-plan|workflow-validate|workflow-compile|approve|reject|resume|status|doctor|report|closeout-draft|reconcile-tasks|final-verification|decision> ...",
-        subcommands: [
-            "init-hybrid",
-            "run-task",
-            "validate",
-            "workflow-plan",
-            "workflow-validate",
-            "workflow-compile",
-            "approve",
-            "reject",
-            "resume",
-            "status",
-            "doctor",
-            "report",
-            "closeout-draft",
-            "reconcile-tasks",
-            "final-verification",
-            "decision",
-        ],
-    },
-    {
-        name: "run-dag",
-        adapter: "required",
-        tier: "primary",
-        intent: "Execute a reviewed Agent DAG spec.",
-        usage: "run-dag --dag <path> [options]",
-    },
-    {
-        name: "workflow",
-        adapter: "required",
-        tier: "experimental",
-        intent: "List, save, inspect, run, diff, and replay saved dynamic workflows.",
-        usage: "workflow <list|inspect|save|run|diff|replay> [name] [options]",
-        subcommands: ["list", "inspect", "save", "run", "diff", "replay"],
-    },
-    {
-        name: "loop",
-        adapter: "required",
-        tier: "experimental",
-        intent: "Manage durable long-running task loop state above Agent DAG rounds.",
-        usage: "loop <init|status|run|record-round|add-signal|closeout> <task-id> [options]",
-        subcommands: [
-            "init",
-            "status",
-            "run",
-            "record-round",
-            "add-signal",
-            "closeout",
-        ],
-    },
-    {
-        name: "cursor-prompt",
-        adapter: "none",
-        tier: "escape-hatch",
-        intent: "Run one-shot Cursor diagnostics without harness state.",
-        usage: "cursor-prompt [options] [task]",
-    },
-    {
-        name: "pi-prompt",
-        adapter: "none",
-        tier: "escape-hatch",
-        intent: "Run one-shot Pi diagnostics without harness state.",
-        usage: "pi-prompt [options] [task]",
-    },
-    {
-        name: "pi-reuse-benchmark",
-        adapter: "required",
-        tier: "operator",
-        intent: "Read existing Pi runtime reuse benchmark evidence.",
-        usage: "pi-reuse-benchmark [--report <path>] [--approval <path>] [--off-executor|--off-task ...] [--on-executor|--on-task ...] [--json] [--markdown]",
-    },
-    {
-        name: "loop-benchmark",
-        adapter: "required",
-        tier: "operator",
-        intent: "Generate deterministic loop convergence benchmark baseline evidence.",
-        usage: "loop-benchmark [--json|--markdown] [--output <path>]",
-    },
-];
+export const CODE_AGENT_COMMAND_MANIFEST = COMMAND_DEFINITIONS.map(toCommandManifestEntry);
 export const CODE_AGENT_TOP_LEVEL_COMMANDS = CODE_AGENT_COMMAND_MANIFEST.map((entry) => entry.name);
 export function listCommandsByTier(tier, manifest = CODE_AGENT_COMMAND_MANIFEST) {
     return manifest.filter((entry) => entry.tier === tier);