@tea-agent/loop-agent 0.1.0

package/dist/commands/goal.js

@@ -0,0 +1,92 @@
+/**
+ * Legacy task goal command surface (compatibility-only / deprecated-candidate).
+ * Public CLI retained; prefer Agent DAG for new autonomous implementation work.
+ */
+import { clearTaskGoal, getTaskGoal, setTaskGoal, updateTaskGoalStatus, } from '../task/runtime.js';
+import { loadHarnessManifest } from '../governance/harness.js';
+import { assertGoalsFeatureEnabled } from '../task/goal-policy.js';
+function parseTokenBudget(args) {
+    const index = args.indexOf('--token-budget');
+    if (index < 0)
+        return { rest: args };
+    const next = args[index + 1];
+    if (next === undefined) {
+        throw new Error('usage: goal set <taskId> <objective> [--token-budget <number>]');
+    }
+    if (next.toLowerCase() === 'null') {
+        return {
+            tokenBudget: null,
+            rest: args.filter((_arg, i) => i !== index && i !== index + 1),
+        };
+    }
+    const value = Number.parseInt(next, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error('token budget must be a positive integer or "null"');
+    }
+    return {
+        tokenBudget: value,
+        rest: args.filter((_arg, i) => i !== index && i !== index + 1),
+    };
+}
+export async function runGoal(repoRoot, command, args) {
+    const manifest = await loadHarnessManifest(repoRoot);
+    assertGoalsFeatureEnabled(manifest);
+    if (!command) {
+        throw new Error('usage: goal <set|get|pause|resume|clear> ...');
+    }
+    if (command === 'set') {
+        const parsed = parseTokenBudget(args);
+        const forceReplace = parsed.rest.includes('--force');
+        const filtered = parsed.rest.filter((arg) => arg !== '--force');
+        const [taskId, ...objectiveParts] = filtered;
+        if (!taskId || objectiveParts.length === 0) {
+            throw new Error('usage: goal set <taskId> <objective> [--token-budget <number>] [--force]');
+        }
+        const objective = objectiveParts.join(' ').trim();
+        const existing = await getTaskGoal(repoRoot, taskId);
+        if (existing.objective
+            && existing.objective !== objective
+            && !forceReplace) {
+            throw new Error('goal already exists with a different objective; rerun with --force to replace existing goal objective');
+        }
+        const goal = await setTaskGoal(repoRoot, taskId, objective, {
+            status: 'active',
+            tokenBudget: parsed.tokenBudget,
+        });
+        console.log(JSON.stringify({ taskId, goal }, null, 2));
+        return;
+    }
+    if (command === 'get') {
+        const [taskId] = args;
+        if (!taskId)
+            throw new Error('usage: goal get <taskId>');
+        const goal = await getTaskGoal(repoRoot, taskId);
+        console.log(JSON.stringify({ taskId, goal }, null, 2));
+        return;
+    }
+    if (command === 'pause') {
+        const [taskId] = args;
+        if (!taskId)
+            throw new Error('usage: goal pause <taskId>');
+        const goal = await updateTaskGoalStatus(repoRoot, taskId, 'paused');
+        console.log(JSON.stringify({ taskId, goal }, null, 2));
+        return;
+    }
+    if (command === 'resume') {
+        const [taskId] = args;
+        if (!taskId)
+            throw new Error('usage: goal resume <taskId>');
+        const goal = await updateTaskGoalStatus(repoRoot, taskId, 'active');
+        console.log(JSON.stringify({ taskId, goal }, null, 2));
+        return;
+    }
+    if (command === 'clear') {
+        const [taskId] = args;
+        if (!taskId)
+            throw new Error('usage: goal clear <taskId>');
+        await clearTaskGoal(repoRoot, taskId);
+        console.log(JSON.stringify({ taskId, cleared: true }, null, 2));
+        return;
+    }
+    throw new Error('usage: goal <set|get|pause|resume|clear> ...');
+}

package/dist/commands/handoff-check.js

@@ -0,0 +1,5 @@
+import { checkTaskHandoff } from '../governance/checks.js';
+export async function runHandoffCheck(repoRoot, taskId) {
+    const result = await checkTaskHandoff(repoRoot, taskId);
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/commands/harvest.js

@@ -0,0 +1,44 @@
+import { harvestTask } from '../records/harvest.js';
+import { loadHarnessManifest } from '../governance/harness.js';
+export function parseHarvestArgs(args) {
+    if (args.length === 0) {
+        throw new Error('usage: harvest <taskId> [--squash] [--no-archive] [--keep-worktree]');
+    }
+    let taskId;
+    let squash = false;
+    let archive = true;
+    let keepWorktree = false;
+    for (const arg of args) {
+        if (arg === '--squash') {
+            squash = true;
+        }
+        else if (arg === '--no-archive') {
+            archive = false;
+        }
+        else if (arg === '--keep-worktree') {
+            keepWorktree = true;
+        }
+        else if (!arg.startsWith('--')) {
+            if (taskId)
+                throw new Error(`unexpected positional argument: ${arg}`);
+            taskId = arg;
+        }
+        else {
+            throw new Error(`unknown harvest flag: ${arg}`);
+        }
+    }
+    if (!taskId) {
+        throw new Error('harvest requires <taskId> as the first positional argument');
+    }
+    return { taskId, squash, archive, keepWorktree };
+}
+export async function runHarvest(repoRoot, rawArgs) {
+    const parsed = parseHarvestArgs(rawArgs);
+    const manifest = await loadHarnessManifest(repoRoot);
+    const result = await harvestTask(repoRoot, manifest, parsed.taskId, {
+        squash: parsed.squash,
+        archive: parsed.archive,
+        keepWorktree: parsed.keepWorktree,
+    });
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/commands/inspect.js

@@ -0,0 +1,11 @@
+export async function runInspect(adapter, repoRoot) {
+    const manifest = await adapter.loadHarnessManifest(repoRoot);
+    console.log(JSON.stringify({
+        project: manifest.project,
+        governanceRoot: manifest.governanceRoot,
+        adapter: adapter.name,
+        entrypoints: manifest.entrypoints,
+        artifacts: manifest.artifacts,
+        scripts: manifest.scripts,
+    }, null, 2));
+}

package/dist/commands/instructions.js

@@ -0,0 +1,195 @@
+import { access, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { getArtifactPath, getArtifactRelativePath, } from '../shared/artifacts-core.js';
+import { defaultHybridDagOutputPath } from '../workflows/dag/init-hybrid.js';
+import { getTaskDir, getTaskPaths, loadTaskConfig } from '../task/runtime.js';
+const STAGES = new Set([
+    'source',
+    'dag-draft',
+    'task-artifacts',
+    'promotion',
+    'closeout',
+]);
+export function parseInstructionsArgs(args) {
+    const [stageRaw, ...rest] = args;
+    if (!stageRaw || !STAGES.has(stageRaw)) {
+        throw new Error('usage: instructions <source|dag-draft|task-artifacts|promotion|closeout> --task <task-id> [--json]');
+    }
+    let taskId;
+    let json = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === '--task') {
+            taskId = rest[++i];
+            if (!taskId)
+                throw new Error('instructions --task requires a task id');
+            continue;
+        }
+        if (arg.startsWith('--task=')) {
+            taskId = arg.slice('--task='.length);
+            continue;
+        }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        throw new Error(`unknown instructions flag: ${arg}`);
+    }
+    if (!taskId)
+        throw new Error('instructions requires --task <task-id>');
+    return { stage: stageRaw, taskId, json };
+}
+export async function runInstructions(repoRoot, args) {
+    const parsed = parseInstructionsArgs(args);
+    const doc = await buildInstructions(repoRoot, parsed.stage, parsed.taskId);
+    if (!parsed.json) {
+        console.log(formatInstructionsMarkdown(doc));
+        return;
+    }
+    console.log(JSON.stringify(doc, null, 2));
+}
+export async function buildInstructions(repoRoot, stage, taskId) {
+    const taskDir = getTaskDir(repoRoot, taskId);
+    const paths = getTaskPaths(repoRoot, taskId);
+    const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    const allowedEditRoots = taskConfig.allowedPaths.length > 0
+        ? taskConfig.allowedPaths
+        : [path.relative(repoRoot, taskDir).replace(/\\/g, '/')];
+    const writePolicy = {
+        mode: stage === 'promotion'
+            ? 'run-evidence-read-only'
+            : stage === 'closeout'
+                ? 'docs-progress'
+                : 'task-owned',
+        allowedEditRoots,
+        forbiddenPaths: taskConfig.forbiddenPaths,
+    };
+    const base = {
+        artifactId: stage,
+        taskId,
+        existingFiles: await listExistingFiles(taskDir),
+        writePolicy,
+    };
+    if (stage === 'source') {
+        return refreshInstructionBlockers(withMissingDependencies({
+            ...base,
+            outputPath: paths.sourceDir,
+            dependencies: [paths.taskConfigPath],
+            template: { requiredHeadings: ['# 需求', '# 执行约束'] },
+            completionCriteria: [
+                'source/需求.md exists with concrete requirements',
+                'source/执行约束.md exists when path or behavioral constraints matter',
+            ],
+        }));
+    }
+    if (stage === 'dag-draft') {
+        return refreshInstructionBlockers(withMissingDependencies({
+            ...base,
+            outputPath: defaultHybridDagOutputPath(taskId),
+            dependencies: [
+                paths.taskConfigPath,
+                path.join(paths.sourceDir, '需求.md'),
+            ],
+            template: { requiredHeadings: ['version', 'title', 'objective', 'tasks', 'executorModels'] },
+            completionCriteria: [
+                'dag draft validates with dag validate --strict-models --strict-governance',
+                'writeSet is narrow and matches task constraints',
+            ],
+        }));
+    }
+    if (stage === 'promotion') {
+        return refreshInstructionBlockers(withMissingDependencies({
+            ...base,
+            outputPath: path.join(taskDir, 'artifacts'),
+            dependencies: [
+                path.join(repoRoot, '.harness', 'dag-runs', 'completed'),
+                path.join(repoRoot, '.harness', 'runs', 'completed'),
+            ],
+            template: { requiredHeadings: ['# 修改记录', '# 验证结果'] },
+            completionCriteria: [
+                'completed run facts remain read-only',
+                'task artifacts summarize real run evidence without inventing verification',
+            ],
+        }));
+    }
+    if (stage === 'closeout') {
+        return refreshInstructionBlockers(withMissingDependencies({
+            ...base,
+            outputPath: path.join(repoRoot, 'docs', 'progress', `${taskId}.md`),
+            dependencies: [
+                getArtifactPath(taskDir, 'implement'),
+                getArtifactPath(taskDir, 'verify'),
+            ],
+            template: { requiredHeadings: ['# Progress', '## Summary', '## Verification', '## Remaining Risk'] },
+            completionCriteria: [
+                'records commands actually run and their outcome',
+                'links remaining risks or follow-up tasks',
+            ],
+        }));
+    }
+    const artifactSteps = ['analyze', 'plan', 'implement', 'verify', 'retrospective'];
+    return refreshInstructionBlockers(withMissingDependencies({
+        ...base,
+        outputPath: path.join(taskDir, 'artifacts'),
+        dependencies: [paths.taskConfigPath, paths.statePath],
+        template: {
+            requiredHeadings: artifactSteps.map((step) => getArtifactRelativePath(step)),
+        },
+        completionCriteria: [
+            'artifact content is substantive and not the new-task template',
+            'verification artifact names exact commands and pass/fail results',
+        ],
+    }));
+}
+function withMissingDependencies(doc) {
+    return {
+        ...doc,
+        blocked: false,
+        missingDependencies: [],
+    };
+}
+async function listExistingFiles(root) {
+    try {
+        const names = await readdir(root, { recursive: true });
+        return names
+            .map((name) => String(name))
+            .filter((name) => !name.includes('/logs/'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function refreshInstructionBlockers(doc) {
+    const missing = [];
+    for (const dep of doc.dependencies) {
+        try {
+            await access(dep);
+        }
+        catch {
+            missing.push(dep);
+        }
+    }
+    return {
+        ...doc,
+        blocked: missing.length > 0,
+        missingDependencies: missing,
+    };
+}
+function formatInstructionsMarkdown(doc) {
+    const lines = [
+        `# Instructions: ${doc.artifactId}`,
+        '',
+        `- task: \`${doc.taskId}\``,
+        `- output: \`${doc.outputPath}\``,
+        `- write policy: \`${doc.writePolicy.mode}\``,
+        `- blocked: ${doc.blocked ? 'yes' : 'no'}`,
+        '',
+        '## Dependencies',
+        ...doc.dependencies.map((dep) => `- \`${dep}\``),
+        '',
+        '## Completion Criteria',
+        ...doc.completionCriteria.map((criterion) => `- ${criterion}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}

package/dist/commands/knowledge.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { curateKnowledgePatterns } from "../workflows/dag/knowledge-curator.js";
+export function parseKnowledgeArgs(args) {
+    const [command, ...rest] = args;
+    if (command !== "curate") {
+        throw new Error("usage: knowledge curate [--json|--markdown] [--output <path>]");
+    }
+    let outputPath;
+    let json = false;
+    let markdown = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--markdown") {
+            markdown = true;
+            continue;
+        }
+        if (arg === "--output") {
+            outputPath = rest[++i];
+            if (!outputPath)
+                throw new Error("knowledge curate --output requires a path");
+            continue;
+        }
+        if (arg.startsWith("--output=")) {
+            outputPath = arg.slice("--output=".length);
+            continue;
+        }
+        throw new Error(`unknown knowledge curate argument: ${arg}`);
+    }
+    if (!json && !markdown)
+        json = true;
+    return { command, outputPath, json, markdown };
+}
+export async function runKnowledge(repoRoot, args) {
+    const parsed = parseKnowledgeArgs(args);
+    const result = await curateKnowledgePatterns({
+        repoRoot,
+        outputPath: parsed.outputPath,
+    });
+    if (!result.ok) {
+        process.exitCode = 1;
+    }
+    if (result.outputPath) {
+        console.error(`[loop-agent] wrote knowledge proposal: ${path.relative(repoRoot, result.outputPath)}`);
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify({
+            ok: result.ok,
+            patternsPath: path.relative(repoRoot, result.patternsPath),
+            outputPath: result.outputPath ? path.relative(repoRoot, result.outputPath) : undefined,
+            patternCount: result.patternCount,
+            safetyFindings: result.safetyFindings,
+            message: result.message,
+        }, null, 2));
+    }
+    if (parsed.markdown && result.proposalMarkdown && !result.outputPath) {
+        if (parsed.json)
+            console.log("");
+        process.stdout.write(result.proposalMarkdown);
+    }
+}

package/dist/commands/loop-benchmark.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { buildLoopBenchmarkResult, formatLoopBenchmarkMarkdown, writeLoopBenchmarkMarkdown, } from "../workflows/loop/benchmark.js";
+export function parseLoopBenchmarkArgs(args) {
+    let json = false;
+    let markdown = false;
+    let outputPath;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--markdown") {
+            markdown = true;
+            continue;
+        }
+        if (arg === "--output") {
+            outputPath = args[++i];
+            if (!outputPath) {
+                throw new Error("loop-benchmark --output requires a path");
+            }
+            continue;
+        }
+        if (arg.startsWith("--output=")) {
+            outputPath = arg.slice("--output=".length);
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            printLoopBenchmarkUsage();
+            process.exit(0);
+        }
+        throw new Error(`unknown loop-benchmark argument: ${arg}`);
+    }
+    if (!json && !markdown) {
+        json = true;
+    }
+    return { json, markdown, outputPath };
+}
+export function printLoopBenchmarkUsage() {
+    console.log(`usage: loop-benchmark [options]
+
+Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
+
+Options:
+  --json              Emit JSON (default when no format flag is set)
+  --markdown          Emit Markdown report
+  --output <path>     Write Markdown report to a repo-relative or absolute path
+  -h, --help          Show this help
+
+Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
+Recommendation never changes convergence.enabled default.`);
+}
+export async function runLoopBenchmark(repoRoot, rawArgs) {
+    const parsed = parseLoopBenchmarkArgs(rawArgs);
+    const result = buildLoopBenchmarkResult();
+    if (parsed.outputPath) {
+        if (!parsed.markdown) {
+            throw new Error("loop-benchmark --output requires --markdown");
+        }
+        const resolved = await writeLoopBenchmarkMarkdown(repoRoot, parsed.outputPath, result);
+        console.error(`[loop-agent] wrote loop benchmark report: ${path.relative(repoRoot, resolved)}`);
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    if (parsed.markdown && !parsed.outputPath) {
+        if (parsed.json) {
+            console.log("");
+        }
+        process.stdout.write(formatLoopBenchmarkMarkdown(result));
+    }
+}