@tea-agent/loop-agent 0.1.0

package/dist/cli/program.js

@@ -0,0 +1,505 @@
+import path from "node:path";
+import { Command } from "commander";
+import { resolveAdapter } from "../adapters/index.js";
+import { runCloseout } from "../commands/closeout.js";
+import { runCoverageAudit } from "../commands/coverage-audit.js";
+import { runCursorWorker } from "../commands/cursor-worker.js";
+import { parseCursorPromptArgs, printCursorPromptUsage, runCursorPrompt, } from "../commands/cursor-prompt.js";
+import { runDagApprove } from "../commands/dag-approve.js";
+import { runDagFinalVerification } from "../commands/dag-final-verification.js";
+import { runDagInitHybrid } from "../commands/dag-init-hybrid.js";
+import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
+import { runDagReject } from "../commands/dag-reject.js";
+import { runDagCloseoutDraft, runDagReport } from "../commands/dag-report.js";
+import { runDagResume } from "../commands/dag-resume.js";
+import { runDagRunTask } from "../commands/dag-run-task.js";
+import { runDagValidate } from "../commands/dag-validate.js";
+import { runDagWorkflowCompile } from "../commands/dag-workflow-compile.js";
+import { runDagWorkflowPlan } from "../commands/dag-workflow-plan.js";
+import { runDagWorkflowValidate } from "../commands/dag-workflow-validate.js";
+import { runDelegate } from "../commands/delegate.js";
+import { runDocsArchive } from "../commands/docs-archive.js";
+import { runDocsAudit } from "../commands/docs-audit.js";
+import { runDoctor } from "../commands/doctor.js";
+import { runGoal } from "../commands/goal.js";
+import { runHandoffCheck } from "../commands/handoff-check.js";
+import { runHarvest } from "../commands/harvest.js";
+import { runInspect } from "../commands/inspect.js";
+import { runInstructions } from "../commands/instructions.js";
+import { runKnowledge } from "../commands/knowledge.js";
+import { runLoop } from "../commands/loop.js";
+import { runLoopBenchmark } from "../commands/loop-benchmark.js";
+import { runNewTask } from "../commands/new-task.js";
+import { runPiReuseBenchmark } from "../commands/pi-reuse-benchmark.js";
+import { parsePiPromptArgs, printPiPromptUsage, runPiPrompt, } from "../commands/pi-prompt.js";
+import { runPlanList } from "../commands/plan-list.js";
+import { runPromoteRun } from "../commands/promote-run.js";
+import { runReferenceIndex } from "../commands/reference-index.js";
+import { runRunDag } from "../commands/run-dag.js";
+import { runSpine } from "../commands/spine.js";
+import { runStats } from "../commands/stats.js";
+import { runStatus } from "../commands/status.js";
+import { runStudyInit } from "../commands/study-init.js";
+import { runWorkflowCommand } from "../commands/workflow.js";
+import { runWorktreeCreate } from "../commands/worktree-create.js";
+import { runWorktreeList } from "../commands/worktree-list.js";
+import { runWorktreeRemove } from "../commands/worktree-remove.js";
+import { handleStandaloneOneShotCommandError } from "../shared/one-shot-prompt-args.js";
+import { runDagDecisionInspect, runDagDecisionValidate, } from "../workflows/dag/decision-envelope.js";
+import { runDagDoctor, runDagStatus } from "../workflows/dag/lifecycle.js";
+import { CODE_AGENT_COMMAND_MANIFEST } from "./catalog.js";
+function collectGlobalOptions(command) {
+    let current = command;
+    const merged = {};
+    while (current) {
+        Object.assign(merged, current.opts());
+        current = current.parent;
+    }
+    return {
+        repoRoot: merged.repoRoot,
+        adapter: merged.adapter,
+        worktree: merged.worktree,
+    };
+}
+function commandChain(command) {
+    const names = [];
+    let current = command;
+    while (current?.parent) {
+        const name = current.name();
+        if (name)
+            names.unshift(name);
+        current = current.parent;
+    }
+    return names;
+}
+async function resolveDispatchContext(command, defaultRepoRoot) {
+    const options = collectGlobalOptions(command);
+    const repoRoot = path.resolve(options.repoRoot ?? defaultRepoRoot);
+    const adapter = await resolveAdapter(repoRoot, options.adapter);
+    if (options.adapter)
+        console.log(`[loop-agent] adapter: ${adapter.name}`);
+    if (options.repoRoot)
+        console.log(`[loop-agent] repo root: ${repoRoot}`);
+    return {
+        adapter,
+        repoRoot,
+        explicitWorktree: options.worktree,
+    };
+}
+async function dispatchRegisteredCommand(commandObject, defaultRepoRoot, rawArgs) {
+    const chain = commandChain(commandObject);
+    const command = chain[0] ?? "";
+    const [subcommand, ...rest] = chain.length <= 1 ? rawArgs : [chain[1], ...chain.slice(2), ...rawArgs];
+    const ctx = await resolveDispatchContext(commandObject, defaultRepoRoot);
+    await runCommanderAction(ctx, command, subcommand, rest);
+}
+async function runCommanderAction(ctx, command, subcommand, rest) {
+    switch (command) {
+        case "inspect":
+            await runInspect(ctx.adapter, ctx.repoRoot);
+            return;
+        case "doctor":
+            await runDoctor(ctx.adapter, ctx.repoRoot);
+            return;
+        case "docs":
+            if (subcommand === "audit") {
+                await runDocsAudit(ctx.repoRoot);
+                return;
+            }
+            if (subcommand === "archive") {
+                const [planPath] = rest;
+                if (!planPath)
+                    throw new Error("usage: docs archive <active-plan-path>");
+                await runDocsArchive(ctx.repoRoot, planPath);
+                return;
+            }
+            throw new Error("usage: docs <audit|archive> ...");
+        case "new-task": {
+            const [taskId, ...titleParts] = [subcommand, ...rest];
+            if (!taskId)
+                throw new Error("taskId required");
+            await runNewTask(ctx.repoRoot, taskId, titleParts.join(" ") || undefined);
+            return;
+        }
+        case "status": {
+            if (!subcommand)
+                throw new Error("taskId required");
+            await runStatus(ctx.repoRoot, subcommand);
+            return;
+        }
+        case "instructions":
+            await runInstructions(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "promote-run":
+            await runPromoteRun(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "closeout":
+            await runCloseout(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "stats":
+            await runStats(ctx.repoRoot);
+            return;
+        case "plan":
+            if (subcommand === "list") {
+                await runPlanList(ctx.repoRoot);
+                return;
+            }
+            throw new Error("usage: plan <list>");
+        case "spine":
+            await runSpine(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "handoff":
+            if (subcommand === "check") {
+                await runHandoffCheck(ctx.repoRoot, rest[0]);
+                return;
+            }
+            if (subcommand === "coverage") {
+                const [taskId, ...flags] = rest;
+                if (!taskId) {
+                    throw new Error("usage: handoff coverage <taskId> [--json|--markdown]");
+                }
+                const exitCode = await runCoverageAudit(ctx.repoRoot, taskId, {
+                    json: flags.includes("--json"),
+                    markdown: flags.includes("--markdown"),
+                });
+                process.exitCode = exitCode;
+                return;
+            }
+            throw new Error("usage: handoff <check|coverage> [taskId]");
+        case "goal":
+            await runGoal(ctx.repoRoot, subcommand, rest);
+            return;
+        case "reference":
+            if (subcommand === "index") {
+                const [taskId] = rest;
+                if (!taskId)
+                    throw new Error("usage: reference index <task-id>");
+                await runReferenceIndex(ctx.repoRoot, taskId);
+                return;
+            }
+            throw new Error("usage: reference <index> <task-id>");
+        case "study":
+            if (subcommand === "init") {
+                await runStudyInit(ctx.repoRoot, rest);
+                return;
+            }
+            throw new Error("usage: study init <task-id> [title] ...");
+        case "worktree":
+            if (subcommand === "create") {
+                await runWorktreeCreate(ctx.repoRoot, rest);
+                return;
+            }
+            if (subcommand === "list") {
+                await runWorktreeList(ctx.repoRoot);
+                return;
+            }
+            if (subcommand === "remove") {
+                await runWorktreeRemove(ctx.repoRoot, rest);
+                return;
+            }
+            throw new Error("usage: worktree <create|list|remove> ...");
+        case "delegate":
+            await runDelegate(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "harvest":
+            await runHarvest(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "cursor-worker":
+            await runCursorWorker(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "knowledge":
+            await runKnowledge(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "dag":
+            await runDagAction(ctx.repoRoot, subcommand, rest);
+            return;
+        case "run-dag":
+            await runRunDag(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "workflow":
+            await runWorkflowCommand(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "loop":
+            await runLoop(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "pi-reuse-benchmark":
+            await runPiReuseBenchmark(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        case "loop-benchmark":
+            await runLoopBenchmark(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
+        default:
+            throw new Error(`commander command is not wired to an action: ${command}`);
+    }
+}
+async function runDagAction(repoRoot, subcommand, rest) {
+    const args = compactArgs(rest);
+    switch (subcommand) {
+        case "init-hybrid":
+            await runDagInitHybrid(repoRoot, args);
+            return;
+        case "validate":
+            await runDagValidate(repoRoot, args);
+            return;
+        case "workflow-validate":
+            await runDagWorkflowValidate(repoRoot, args);
+            return;
+        case "workflow-plan":
+            await runDagWorkflowPlan(repoRoot, args);
+            return;
+        case "workflow-compile":
+            await runDagWorkflowCompile(repoRoot, args);
+            return;
+        case "approve":
+            await runDagApprove(repoRoot, args);
+            return;
+        case "reject":
+            await runDagReject(repoRoot, args);
+            return;
+        case "resume":
+            await runDagResume(repoRoot, args);
+            return;
+        case "status":
+            await runDagStatus(repoRoot, args);
+            return;
+        case "doctor":
+            await runDagDoctor(repoRoot, args);
+            return;
+        case "run-task":
+            await runDagRunTask(repoRoot, args);
+            return;
+        case "report":
+            await runDagReport(repoRoot, args);
+            return;
+        case "closeout-draft":
+            await runDagCloseoutDraft(repoRoot, args);
+            return;
+        case "reconcile-tasks":
+            await runDagReconcileTasks(repoRoot, args);
+            return;
+        case "final-verification":
+            await runDagFinalVerification(repoRoot, args);
+            return;
+        case "decision": {
+            const [decisionSubcommand, ...decisionArgs] = args;
+            if (decisionSubcommand === "inspect") {
+                await runDagDecisionInspect(repoRoot, decisionArgs);
+                return;
+            }
+            if (decisionSubcommand === "validate") {
+                await runDagDecisionValidate(repoRoot, decisionArgs);
+                return;
+            }
+            throw new Error("usage: dag decision <inspect|validate> --run-id <id> [--node-id <node-id>]");
+        }
+        default:
+            throw new Error("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> ...");
+    }
+}
+function compactArgs(args) {
+    return args.filter((arg) => Boolean(arg));
+}
+function createRawArgsCommand(name, description, defaultRepoRoot) {
+    return new Command(name)
+        .description(description)
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .argument("[args...]", "command-specific arguments")
+        .action(async (args, _options, command) => {
+        await dispatchRegisteredCommand(command, defaultRepoRoot, args);
+    });
+}
+function addRawSubcommands(parent, subcommands, defaultRepoRoot) {
+    for (const subcommand of subcommands) {
+        parent.addCommand(createRawArgsCommand(subcommand, `${parent.name()} ${subcommand}`, defaultRepoRoot));
+    }
+}
+function configureDagValidate(command) {
+    command
+        .description("Validate an Agent DAG spec")
+        .option("--dag <path>", "DAG spec path")
+        .option("--strict-models", "fail on model routing warnings")
+        .option("--strict-governance", "fail on governance warnings")
+        .option("--forbid-executor <executor>", "forbid executor", (value, previous = []) => [
+        ...previous,
+        value,
+    ])
+        .option("--spine-task <task-id>", "run spine audit for task id");
+}
+function configureRunDag(command) {
+    command
+        .description("Execute a reviewed Agent DAG spec")
+        .option("--dag <path>", "DAG spec path")
+        .option("-C, --cwd <dir>", "working directory")
+        .option("--init-only", "initialize run artifacts without executing")
+        .option("--dry-run", "validate and plan without executing")
+        .option("--max-concurrent <n>", "maximum concurrent nodes")
+        .option("--run-id <id>", "run id")
+        .option("--no-cursor", "disable Cursor execution")
+        .option("--canvas-path <path>", "absolute canvas output path")
+        .option("--canvas <name>", "canvas name")
+        .option("--canvases-dir <dir>", "canvas output directory");
+}
+function configureDagRunTask(command) {
+    command
+        .description("Create and optionally execute a DAG for a task")
+        .option("-o, --output <path>", "output DAG path")
+        .option("--profile <profile>", "auto|minimal|standard|reviewed|supervised")
+        .option("--strict-models", "fail on model routing warnings")
+        .option("--no-cursor", "disable Cursor execution")
+        .option("--execute", "execute after creating the DAG")
+        .option("--init-only", "initialize run artifacts without executing")
+        .option("--dry-run", "validate and plan without executing")
+        .option("--cwd <dir>", "working directory")
+        .option("--max-concurrent <n>", "maximum concurrent nodes")
+        .option("--run-id <id>", "run id")
+        .option("--canvas-path <path>", "absolute canvas output path")
+        .option("--canvas <name>", "canvas name")
+        .option("--canvases-dir <dir>", "canvas output directory");
+}
+function optionTokens(command) {
+    const tokens = [];
+    const options = command.opts();
+    for (const option of command.options) {
+        const value = options[option.attributeName()];
+        if (value === undefined)
+            continue;
+        const flag = option.long ?? option.short;
+        if (!flag)
+            continue;
+        if (option.negate) {
+            if (value === false)
+                tokens.push(flag);
+            continue;
+        }
+        if (value === false)
+            continue;
+        if (value === true)
+            tokens.push(flag);
+        else if (Array.isArray(value)) {
+            for (const item of value)
+                tokens.push(flag, String(item));
+        }
+        else
+            tokens.push(flag, String(value));
+    }
+    return tokens;
+}
+function commandArgsWithOptions(args, command) {
+    return [...args, ...optionTokens(command)];
+}
+function replaceActionWithOptionAwareDispatch(command, defaultRepoRoot) {
+    command.action(async (args, _options, actionCommand) => {
+        await dispatchRegisteredCommand(actionCommand, defaultRepoRoot, commandArgsWithOptions(args, actionCommand));
+    });
+}
+function addDagCommand(program, defaultRepoRoot) {
+    const dag = new Command("dag").description("Agent DAG commands");
+    addRawSubcommands(dag, [
+        "init-hybrid",
+        "workflow-plan",
+        "workflow-validate",
+        "workflow-compile",
+        "approve",
+        "reject",
+        "resume",
+        "status",
+        "doctor",
+        "report",
+        "closeout-draft",
+        "reconcile-tasks",
+        "final-verification",
+    ], defaultRepoRoot);
+    const validate = createRawArgsCommand("validate", "Validate an Agent DAG spec", defaultRepoRoot);
+    configureDagValidate(validate);
+    replaceActionWithOptionAwareDispatch(validate, defaultRepoRoot);
+    dag.addCommand(validate);
+    const runTask = createRawArgsCommand("run-task", "Create and optionally execute a DAG for a task", defaultRepoRoot);
+    configureDagRunTask(runTask);
+    replaceActionWithOptionAwareDispatch(runTask, defaultRepoRoot);
+    dag.addCommand(runTask);
+    const decision = new Command("decision").description("DAG decision envelope commands");
+    addRawSubcommands(decision, ["inspect", "validate"], defaultRepoRoot);
+    dag.addCommand(decision);
+    program.addCommand(dag);
+}
+async function runCursorPromptCommand(args) {
+    try {
+        const parsed = parseCursorPromptArgs(args);
+        if ("listModels" in parsed) {
+            const { listModels } = await import("../commands/cursor-prompt.js");
+            listModels();
+            return;
+        }
+        await runCursorPrompt(parsed);
+    }
+    catch (err) {
+        handleStandaloneOneShotCommandError(err, printCursorPromptUsage);
+    }
+}
+async function runPiPromptCommand(args) {
+    try {
+        const parsed = parsePiPromptArgs(args);
+        await runPiPrompt(parsed);
+    }
+    catch (err) {
+        handleStandaloneOneShotCommandError(err, printPiPromptUsage);
+    }
+}
+export function buildLoopAgentProgram(options) {
+    const program = new Command();
+    program
+        .name("loop-agent")
+        .description("Loop Agent task and DAG automation CLI")
+        .showHelpAfterError()
+        .option("--repo-root <path>", "repository root")
+        .option("--adapter <name>", "harness adapter name")
+        .option("--worktree <path>", "explicit worktree path");
+    for (const entry of CODE_AGENT_COMMAND_MANIFEST) {
+        if (entry.name === "dag") {
+            addDagCommand(program, options.defaultRepoRoot);
+            continue;
+        }
+        if (entry.name === "cursor-prompt") {
+            program
+                .command("cursor-prompt")
+                .description(entry.intent)
+                .allowUnknownOption(true)
+                .allowExcessArguments(true)
+                .argument("[args...]", "prompt arguments")
+                .action(async (args) => runCursorPromptCommand(args));
+            continue;
+        }
+        if (entry.name === "pi-prompt") {
+            program
+                .command("pi-prompt")
+                .description(entry.intent)
+                .allowUnknownOption(true)
+                .allowExcessArguments(true)
+                .argument("[args...]", "prompt arguments")
+                .action(async (args) => runPiPromptCommand(args));
+            continue;
+        }
+        const command = createRawArgsCommand(entry.name, entry.intent, options.defaultRepoRoot);
+        if (entry.name === "run-dag") {
+            configureRunDag(command);
+            replaceActionWithOptionAwareDispatch(command, options.defaultRepoRoot);
+        }
+        if (entry.subcommands)
+            addRawSubcommands(command, entry.subcommands, options.defaultRepoRoot);
+        program.addCommand(command);
+    }
+    return program;
+}
+export function getRegisteredCommandNames(program) {
+    return program.commands.map((command) => command.name());
+}
+export function findRegisteredCommand(program, pathSegments) {
+    let current = program;
+    for (const segment of pathSegments) {
+        current = current.commands.find((command) => command.name() === segment);
+        if (!current)
+            return undefined;
+    }
+    return current;
+}

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { buildLoopAgentProgram } from "./cli/program.js";
+async function main() {
+    const program = buildLoopAgentProgram({
+        defaultRepoRoot: process.cwd(),
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/commands/closeout.js

@@ -0,0 +1,13 @@
+import { closeoutTask } from '../records/promotion.js';
+export function parseCloseoutArgs(args) {
+    const [subcommand, taskId, ...rest] = args;
+    if (subcommand !== 'task' || !taskId || rest.length > 0) {
+        throw new Error('usage: closeout task <task-id>');
+    }
+    return { taskId };
+}
+export async function runCloseout(repoRoot, args) {
+    const parsed = parseCloseoutArgs(args);
+    const result = await closeoutTask(repoRoot, parsed.taskId);
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/commands/coverage-audit.js

@@ -0,0 +1,14 @@
+import { formatRequirementCoverageJson, formatRequirementCoverageMarkdown, runRequirementCoverageAudit, } from '../governance/requirement-coverage.js';
+export async function runCoverageAudit(repoRoot, taskId, options = {}) {
+    const audit = await runRequirementCoverageAudit(repoRoot, taskId);
+    if (options.json) {
+        process.stdout.write(formatRequirementCoverageJson(audit));
+    }
+    else if (options.markdown) {
+        process.stdout.write(formatRequirementCoverageMarkdown(audit));
+    }
+    else {
+        process.stdout.write(`${formatRequirementCoverageJson(audit)}`);
+    }
+    return audit.ok ? 0 : 1;
+}