@tea-agent/loop-agent 0.1.0

package/dist/commands/run-dag.js

@@ -0,0 +1,184 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+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";
+export function parseRunDagArgs(args, defaultCwd) {
+    if (args.length === 0) {
+        throw new Error("usage: run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]]");
+    }
+    let dagPath;
+    let cwd;
+    let initOnly = false;
+    let dryRun = false;
+    let maxConcurrent;
+    let runId;
+    let noCursor = false;
+    let canvasPath;
+    let canvasName;
+    let canvasesDir;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--dag") {
+            dagPath = args[++i];
+        }
+        else if (arg.startsWith("--dag=")) {
+            dagPath = arg.slice(6);
+        }
+        else if (arg === "--cwd" || arg === "-C") {
+            cwd = args[++i];
+        }
+        else if (arg.startsWith("--cwd=")) {
+            cwd = arg.slice(6);
+        }
+        else if (arg === "--init-only") {
+            initOnly = true;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--max-concurrent") {
+            maxConcurrent = Number(args[++i]);
+        }
+        else if (arg === "--run-id") {
+            runId = args[++i];
+        }
+        else if (arg === "--no-cursor") {
+            noCursor = true;
+        }
+        else if (arg === "--canvas-path") {
+            canvasPath = args[++i];
+        }
+        else if (arg.startsWith("--canvas-path=")) {
+            canvasPath = arg.slice(14);
+        }
+        else if (arg === "--canvas") {
+            canvasName = args[++i];
+        }
+        else if (arg.startsWith("--canvas=")) {
+            canvasName = arg.slice(9);
+        }
+        else if (arg === "--canvases-dir") {
+            canvasesDir = args[++i];
+        }
+        else if (arg.startsWith("--canvases-dir=")) {
+            canvasesDir = arg.slice(15);
+        }
+        else if (!arg.startsWith("-")) {
+            if (!dagPath)
+                dagPath = arg;
+            else
+                throw new Error(`unexpected positional argument: ${arg}`);
+        }
+        else {
+            throw new Error(`unknown run-dag flag: ${arg}`);
+        }
+    }
+    if (!dagPath) {
+        throw new Error("run-dag requires --dag <path>");
+    }
+    return {
+        dagPath: path.resolve(dagPath),
+        cwd: path.resolve(cwd ?? defaultCwd ?? process.cwd()),
+        initOnly,
+        dryRun,
+        maxConcurrent,
+        runId,
+        noCursor,
+        canvasPath,
+        canvasName,
+        canvasesDir,
+    };
+}
+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 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 runRunDag(repoRoot, rawArgs) {
+    const parsed = parseRunDagArgs(rawArgs, repoRoot);
+    const spec = await loadDagSpecFromFile(parsed.dagPath);
+    if (parsed.noCursor) {
+        const rawTaskExecutors = await loadRawTaskExecutorMap(parsed.dagPath);
+        assertNoCursorTasks(spec, rawTaskExecutors);
+    }
+    assertValidDagSpec(spec);
+    const resolvedCanvasPath = resolveCanvasPath({
+        canvasPath: parsed.canvasPath,
+        canvasName: parsed.canvasName,
+        canvasesDir: parsed.canvasesDir,
+        cwd: parsed.cwd,
+    });
+    const canvas = resolvedCanvasPath
+        ? createDagCanvasObserver({ canvasPath: resolvedCanvasPath, spec })
+        : undefined;
+    if (parsed.dryRun) {
+        const summary = await runDag(spec, {
+            cwd: parsed.cwd,
+            dryRun: true,
+            runId: parsed.runId,
+            observer: canvas?.observer,
+        });
+        const canvasError = await flushCanvasSafely(canvas);
+        console.log(JSON.stringify({
+            mode: "dry-run",
+            title: spec.title,
+            taskCount: spec.tasks.length,
+            ranks: summary.ranks,
+            runId: summary.runId,
+            runDir: summary.runDir,
+            ...(resolvedCanvasPath ? { canvasPath: resolvedCanvasPath } : {}),
+            ...(canvasError ? { canvasError } : {}),
+        }, null, 2));
+        return;
+    }
+    const maxConcurrent = parsed.maxConcurrent;
+    const summary = await runDag(spec, {
+        cwd: parsed.cwd,
+        initOnly: parsed.initOnly,
+        dryRun: false,
+        maxConcurrent,
+        runId: parsed.runId,
+        observer: canvas?.observer,
+    });
+    const canvasError = await flushCanvasSafely(canvas);
+    const payload = resolvedCanvasPath
+        ? {
+            ...summary,
+            canvasPath: resolvedCanvasPath,
+            ...(canvasError ? { canvasError } : {}),
+        }
+        : summary;
+    console.log(JSON.stringify(payload, null, 2));
+}

package/dist/commands/spine.js

@@ -0,0 +1,38 @@
+import { formatSpineAuditJson, formatSpineAuditMarkdown, runSpineAudit, } from "../governance/spine-audit.js";
+export function parseSpineArgs(args) {
+    const [command, taskId, ...rest] = args;
+    if (command !== "audit" || !taskId) {
+        throw new Error("usage: spine audit <task-id> [--json|--markdown]");
+    }
+    let json = false;
+    let markdown = false;
+    for (const arg of rest) {
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--markdown") {
+            markdown = true;
+            continue;
+        }
+        throw new Error(`unknown spine audit argument: ${arg}`);
+    }
+    if (!json && !markdown)
+        json = true;
+    return { command, taskId, json, markdown };
+}
+export async function runSpine(repoRoot, args) {
+    const parsed = parseSpineArgs(args);
+    const audit = await runSpineAudit(repoRoot, parsed.taskId);
+    if (!audit.ok) {
+        process.exitCode = 1;
+    }
+    if (parsed.json) {
+        process.stdout.write(formatSpineAuditJson(audit));
+    }
+    if (parsed.markdown) {
+        if (parsed.json)
+            process.stdout.write("\n");
+        process.stdout.write(formatSpineAuditMarkdown(audit));
+    }
+}

package/dist/commands/stats.js

@@ -0,0 +1,84 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+function percentile(values, p) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const index = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, index)];
+}
+function formatMs(ms) {
+    if (ms >= 60_000)
+        return `${(ms / 60_000).toFixed(1)} min`;
+    return `${(ms / 1_000).toFixed(1)}s`;
+}
+export async function runStats(repoRoot) {
+    const tasksDir = path.join(repoRoot, '.harness', 'tasks');
+    const stepRecords = {};
+    let taskDirs = [];
+    try {
+        const entries = await readdir(tasksDir, { withFileTypes: true });
+        taskDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        console.log('no task directories found');
+        return;
+    }
+    for (const taskId of taskDirs) {
+        const jsonlPath = path.join(tasksDir, taskId, 'logs', 'executor.jsonl');
+        try {
+            const content = await readFile(jsonlPath, 'utf-8');
+            for (const line of content.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const record = JSON.parse(trimmed);
+                    if (typeof record.step === 'string' && typeof record.durationMs === 'number') {
+                        const step = record.step;
+                        if (!stepRecords[step])
+                            stepRecords[step] = [];
+                        stepRecords[step].push({
+                            durationMs: record.durationMs,
+                            ok: Boolean(record.ok),
+                            step,
+                            timedOut: Boolean(record.timedOut),
+                        });
+                    }
+                }
+                catch {
+                    // skip unparsable lines
+                }
+            }
+        }
+        catch {
+            // skip missing executor.jsonl
+        }
+    }
+    const stepOrder = ['analyze', 'plan', 'spec', 'implement', 'verify', 'retrospective'];
+    let totalRecords = 0;
+    let totalTimedOut = 0;
+    for (const step of stepOrder) {
+        const records = stepRecords[step] ?? [];
+        if (records.length === 0)
+            continue;
+        totalRecords += records.length;
+        const durations = records.map((r) => r.durationMs);
+        const timedOutCount = records.filter((r) => r.timedOut).length;
+        totalTimedOut += timedOutCount;
+        console.log(`${step} (${records.length} runs)`);
+        console.log(`  count  : ${records.length}`);
+        console.log(`  min    : ${formatMs(Math.min(...durations))}`);
+        console.log(`  P50    : ${formatMs(percentile(durations, 50))}`);
+        console.log(`  P95    : ${formatMs(percentile(durations, 95))}`);
+        console.log(`  P99    : ${formatMs(percentile(durations, 99))}`);
+        console.log(`  max    : ${formatMs(Math.max(...durations))}`);
+        if (timedOutCount > 0)
+            console.log(`  timedOut: ${timedOutCount}`);
+        console.log('');
+    }
+    console.log(`${'='.repeat(40)}`);
+    console.log(`total runs: ${totalRecords}`);
+    if (totalTimedOut > 0)
+        console.log(`total timed out: ${totalTimedOut}`);
+}

package/dist/commands/status.js

@@ -0,0 +1,56 @@
+import { getTaskDir, getTaskPaths, getTaskStatus, loadTaskConfig, refreshSourceState, } from '../task/runtime.js';
+import { getArtifactPath } from '../shared/artifacts-core.js';
+import { buildTaskReadModel } from '../task/read-model.js';
+export async function runStatus(repoRoot, taskId) {
+    await refreshSourceState(repoRoot, taskId);
+    const state = await getTaskStatus(repoRoot, taskId);
+    const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    const taskDir = getTaskDir(repoRoot, taskId);
+    const taskPaths = getTaskPaths(repoRoot, taskId);
+    const readModel = await buildTaskReadModel(repoRoot, taskId);
+    console.log(JSON.stringify({
+        taskId,
+        taskDir,
+        taskRoot: taskDir,
+        sourceOfTruth: 'task',
+        artifactPaths: {
+            taskConfig: taskPaths.taskConfigPath,
+            workflowState: taskPaths.statePath,
+            sourceDir: taskPaths.sourceDir,
+            artifactsDir: `${taskDir}/artifacts`,
+            analysis: getArtifactPath(taskDir, 'analyze'),
+            plan: getArtifactPath(taskDir, 'plan'),
+            modifyLog: getArtifactPath(taskDir, 'implement'),
+            verifyResult: getArtifactPath(taskDir, 'verify'),
+            retrospective: getArtifactPath(taskDir, 'retrospective'),
+        },
+        runRefs: {
+            oneShotRuns: readModel.runRefs.oneShotRuns,
+            dagRuns: readModel.runRefs.dagRuns,
+        },
+        readModel,
+        actionContext: {
+            mode: 'dag',
+            allowedEditRoots: taskConfig.allowedPaths,
+            forbiddenPaths: taskConfig.forbiddenPaths,
+            constraints: taskConfig.hardConstraints,
+            requiresPromotion: readModel.promotion.required && !readModel.promotion.ready,
+        },
+        currentStep: state.currentStep,
+        status: state.status,
+        complexity: taskConfig.complexity,
+        maxFixLoops: taskConfig.maxFixLoops,
+        verifyEnv: taskConfig.verifyEnv ?? 'clean',
+        maxGoalContinuationsPerRun: taskConfig.maxGoalContinuationsPerRun ?? 5,
+        goal: state.goal,
+        sourceState: state.sourceState,
+        completedSteps: state.completedSteps,
+        decisionLogSize: state.decisionLog.length,
+        artifacts: state.artifacts,
+        nextActions: [
+            readModel.nextAction.command,
+            `npm run dev -- instructions dag-draft --task ${taskId} --json`,
+        ],
+        nextSuggestedCommand: readModel.nextAction.command,
+    }, null, 2));
+}

package/dist/commands/study-init.js

@@ -0,0 +1,192 @@
+/**
+ * Feature-study task initialization (compatibility-only).
+ * Creates taskKind=feature-study tasks for external reference analysis.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildReferenceIndex, parseReferenceDocArg, parseReferenceRepoArg } from '../shared/reference-context.js';
+import { createTask, getTaskPaths, loadTaskConfig } from '../task/runtime.js';
+function parseStudyInitArgs(args) {
+    const referenceRepos = [];
+    const referenceDocs = [];
+    const referenceGlobs = [];
+    let title;
+    let targetRepoLabel = 'aimax';
+    let storageModel = 'json-dir-markdown';
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--reference-repo') {
+            const value = args[i + 1];
+            if (!value)
+                throw new Error('usage: study init <task-id> --reference-repo name:/absolute/path');
+            referenceRepos.push(parseReferenceRepoArg(value));
+            i += 1;
+            continue;
+        }
+        if (arg === '--reference-doc') {
+            const value = args[i + 1];
+            if (!value)
+                throw new Error('usage: study init <task-id> --reference-doc [/path | name:/path]');
+            referenceDocs.push(parseReferenceDocArg(value));
+            i += 1;
+            continue;
+        }
+        if (arg === '--reference-glob') {
+            const value = args[i + 1];
+            if (!value)
+                throw new Error('usage: study init <task-id> --reference-glob <glob>');
+            referenceGlobs.push(value);
+            i += 1;
+            continue;
+        }
+        if (arg === '--target-repo') {
+            const value = args[i + 1];
+            if (!value)
+                throw new Error('usage: study init <task-id> --target-repo <label>');
+            targetRepoLabel = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--storage-model') {
+            const value = args[i + 1];
+            if (!value)
+                throw new Error('usage: study init <task-id> --storage-model json-dir-markdown');
+            storageModel = value;
+            i += 1;
+            continue;
+        }
+        positional.push(arg);
+    }
+    const [taskId, ...titleParts] = positional;
+    if (!taskId) {
+        throw new Error('usage: study init <task-id> [title] [--reference-repo name:/path] [--reference-doc path] [--reference-glob glob]');
+    }
+    if (titleParts.length > 0) {
+        title = titleParts.join(' ');
+    }
+    if (referenceGlobs.length > 0) {
+        for (const repo of referenceRepos) {
+            repo.focusGlobs = [...new Set([...(repo.focusGlobs ?? []), ...referenceGlobs])];
+        }
+    }
+    return {
+        taskId,
+        title,
+        referenceRepos,
+        referenceDocs,
+        referenceGlobs,
+        targetRepoLabel,
+        storageModel,
+    };
+}
+export async function runStudyInit(repoRoot, args) {
+    const options = parseStudyInitArgs(args);
+    await createTask(repoRoot, options.taskId, options.title ?? options.taskId);
+    const paths = getTaskPaths(repoRoot, options.taskId);
+    const taskConfig = await loadTaskConfig(repoRoot, options.taskId);
+    const nextConfig = {
+        ...taskConfig,
+        taskKind: 'feature-study',
+        contextProfile: 'slim',
+        complexity: 'large',
+        referenceRepos: options.referenceRepos,
+        referenceDocs: options.referenceDocs,
+        hardConstraints: [
+            `目标仓库: ${options.targetRepoLabel}`,
+            `存储模型: ${options.storageModel}（禁止引入 SQLite 作为 goal 状态主存储）`,
+            '必须先完成参考特性分析，再输出可落地的轻量实现计划',
+        ],
+        notes: 'feature-study task created by study init',
+    };
+    delete nextConfig.flow;
+    await writeFile(paths.taskConfigPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf-8');
+    await mkdir(paths.sourceDir, { recursive: true });
+    await writeFile(path.join(paths.sourceDir, '需求.md'), renderRequirementTemplate(options), 'utf-8');
+    await writeFile(path.join(paths.sourceDir, '执行约束.md'), renderConstraintTemplate(options), 'utf-8');
+    await writeFile(path.join(paths.sourceDir, '参考说明.md'), renderReferenceNotesTemplate(options), 'utf-8');
+    let indexed = false;
+    if (options.referenceRepos.length > 0 || options.referenceDocs.length > 0) {
+        await buildReferenceIndex(repoRoot, options.taskId, nextConfig);
+        indexed = true;
+    }
+    console.log(JSON.stringify({
+        taskId: options.taskId,
+        taskDir: paths.taskDir,
+        taskKind: 'feature-study',
+        indexed,
+        referenceRepos: options.referenceRepos.map((repo) => repo.name),
+        referenceDocs: options.referenceDocs.map((doc) => doc.name ?? doc.path),
+        next: [
+            'edit source/需求.md and source/执行约束.md',
+            indexed
+                ? `npm run dev -- dag run-task ${options.taskId} --profile auto --strict-models`
+                : `npm run dev -- reference index ${options.taskId}; npm run dev -- dag run-task ${options.taskId} --profile auto --strict-models`,
+        ],
+    }, null, 2));
+}
+function renderRequirementTemplate(options) {
+    return [
+        '# 需求',
+        '',
+        '## 背景',
+        '',
+        '- 参考外部代码库中的既有特性，分析其设计与实现原理',
+        '- 在目标仓库中以更轻量的方式落地等价能力',
+        '',
+        '## 目标',
+        '',
+        '- [ ] 完成参考特性分析（架构、状态机、数据流、边界）',
+        `- [ ] 在 ${options.targetRepoLabel} 设计 ${options.storageModel} 存储与状态管理方案`,
+        '- [ ] 输出可执行的实现计划并通过 verify',
+        '',
+        '## 验收标准',
+        '',
+        '- 分析报告能定位参考实现的关键模块与调用链',
+        '- 实现计划明确目录/JSON/Markdown 文件布局，不依赖 SQLite',
+        '- 实现后具备最小可用的 set/get/pause/resume/clear（或等价能力）',
+        '',
+    ].join('\n');
+}
+function renderConstraintTemplate(options) {
+    return [
+        '# 执行约束',
+        '',
+        '## 目标仓库',
+        '',
+        `- ${options.targetRepoLabel}`,
+        '',
+        '## 存储约束',
+        '',
+        `- 必须使用 ${options.storageModel}`,
+        '- 禁止把 SQLite 作为 thread/task goal 的主存储',
+        '- 状态应可通过目录 + JSON 文件恢复',
+        '',
+        '## 范围',
+        '',
+        '- 优先最小可用闭环，不做过度抽象',
+        '- 参考代码只读，不在参考仓库内提交改动',
+        '',
+    ].join('\n');
+}
+function renderReferenceNotesTemplate(options) {
+    const repos = options.referenceRepos.map((repo) => `- ${repo.name}: \`${repo.path}\``).join('\n') || '- （未配置）';
+    const docs = options.referenceDocs.map((doc) => `- ${doc.name ?? path.basename(doc.path)}: \`${doc.path}\``).join('\n') || '- （未配置）';
+    return [
+        '# 参考说明',
+        '',
+        '## 参考仓库',
+        '',
+        repos,
+        '',
+        '## 参考文档',
+        '',
+        docs,
+        '',
+        '## 索引',
+        '',
+        '- 运行 `reference index <task-id>` 会生成 `source/references/index.json`',
+        '- analyze/plan 步骤会自动附带索引中的参考文件',
+        '',
+    ].join('\n');
+}