@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/commands/promote-run.js

@@ -0,0 +1,29 @@
+import { promoteRunEvidence } from '../records/promotion.js';
+export function parsePromoteRunArgs(args) {
+    const [taskId, ...rest] = args;
+    if (!taskId)
+        throw new Error('usage: promote-run <task-id> --run-id <run-id>');
+    let runId;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === '--run-id') {
+            runId = rest[++i];
+            if (!runId)
+                throw new Error('promote-run --run-id requires a value');
+            continue;
+        }
+        if (arg.startsWith('--run-id=')) {
+            runId = arg.slice('--run-id='.length);
+            continue;
+        }
+        throw new Error(`unknown promote-run flag: ${arg}`);
+    }
+    if (!runId)
+        throw new Error('usage: promote-run <task-id> --run-id <run-id>');
+    return { taskId, runId };
+}
+export async function runPromoteRun(repoRoot, args) {
+    const parsed = parsePromoteRunArgs(args);
+    const result = await promoteRunEvidence(repoRoot, parsed.taskId, parsed.runId);
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/commands/reference-index.js

@@ -0,0 +1,16 @@
+/** Feature-study reference index command (compatibility-only). */
+import { buildReferenceIndex } from '../shared/reference-context.js';
+import { loadTaskConfig } from '../task/runtime.js';
+export async function runReferenceIndex(repoRoot, taskId) {
+    const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    const index = await buildReferenceIndex(repoRoot, taskId, taskConfig);
+    const fileCount = index.repos.reduce((sum, repo) => sum + repo.files.length, 0);
+    console.log(JSON.stringify({
+        taskId,
+        manifestPath: `${repoRoot}/.harness/tasks/${taskId}/source/references/index.json`,
+        repoCount: index.repos.length,
+        indexedFileCount: fileCount,
+        docCount: index.docs.length,
+        truncatedRepos: index.repos.filter((repo) => repo.truncated).map((repo) => repo.name),
+    }, null, 2));
+}

package/dist/commands/run-dag-progress.js

@@ -0,0 +1,123 @@
+export const DEFAULT_RUN_DAG_PROGRESS_INTERVAL_MS = 30_000;
+/**
+ * Contract floor for periodic progress output. Values below this are rejected
+ * at CLI parse time (aligned with `dag execute`'s parseProgressIntervalMs).
+ * Lives here (not src/application/dag/args.ts) because task-advance shares it
+ * and src/application/dag/args.ts is outside the task-advance write boundary.
+ */
+export const MIN_RUN_DAG_PROGRESS_INTERVAL_MS = 1_000;
+/** Validate a progress interval; throws with the dag execute error contract. */
+export function validateRunDagProgressIntervalMs(value) {
+    if (!Number.isInteger(value) || value < MIN_RUN_DAG_PROGRESS_INTERVAL_MS) {
+        throw new Error("progress-interval-ms must be an integer >= 1000");
+    }
+    return value;
+}
+function formatDuration(durationMs) {
+    const totalSeconds = Math.max(0, Math.floor(durationMs / 1_000));
+    const hours = Math.floor(totalSeconds / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0)
+        return `${hours}h${String(minutes).padStart(2, "0")}m`;
+    if (minutes > 0)
+        return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+    return `${seconds}s`;
+}
+function countStatuses(state) {
+    const counts = { finished: 0, running: 0, pending: 0, error: 0, skipped: 0 };
+    for (const node of Object.values(state.nodes)) {
+        if (node.status === "FINISHED")
+            counts.finished += 1;
+        else if (node.status === "RUNNING")
+            counts.running += 1;
+        else if (node.status === "ERROR")
+            counts.error += 1;
+        else if (node.status === "SKIPPED")
+            counts.skipped += 1;
+        else
+            counts.pending += 1;
+    }
+    return `finished=${counts.finished} running=${counts.running} pending=${counts.pending} error=${counts.error} skipped=${counts.skipped}`;
+}
+function nodeElapsedMs(node, now) {
+    const startedAt = node.startedAt ? Date.parse(node.startedAt) : Number.NaN;
+    return Number.isFinite(startedAt) ? Math.max(0, now - startedAt) : 0;
+}
+function activeNodeSummary(state, now) {
+    const running = Object.values(state.nodes).filter((node) => node.status === "RUNNING");
+    if (running.length === 0)
+        return "nodes=none";
+    return running
+        .map((node) => {
+        const details = [
+            `${node.id}(${formatDuration(nodeElapsedMs(node, now))}`,
+            node.livenessStatus ? `liveness=${node.livenessStatus}` : undefined,
+            node.currentAttempt ? `attempt=${node.currentAttempt}` : undefined,
+        ]
+            .filter(Boolean)
+            .join(" ");
+        return `${details})`;
+    })
+        .join(",");
+}
+/**
+ * Human-readable CLI progress written to stderr. The final run-dag JSON remains
+ * the only stdout payload, so machine callers can continue parsing stdout.
+ */
+export function createRunDagProgressObserver(options = {}) {
+    const intervalMs = options.intervalMs ?? DEFAULT_RUN_DAG_PROGRESS_INTERVAL_MS;
+    const write = options.write ?? ((text) => process.stderr.write(text));
+    const now = options.now ?? Date.now;
+    let latestState;
+    let timer;
+    const emit = (message) => {
+        try {
+            write(`[dag execute] ${message}\n`);
+        }
+        catch {
+            // Progress is a derived CLI view and must never decide DAG execution.
+        }
+    };
+    const stop = () => {
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+    };
+    const start = () => {
+        if (timer || intervalMs <= 0)
+            return;
+        timer = setInterval(() => {
+            if (!latestState)
+                return;
+            emit(`heartbeat run=${latestState.runId} ${countStatuses(latestState)} ${activeNodeSummary(latestState, now())}`);
+        }, intervalMs);
+        timer.unref?.();
+    };
+    const observer = {
+        onRunStart: (state) => {
+            latestState = state;
+            emit(`started run=${state.runId} nodes=${Object.keys(state.nodes).length} title=${JSON.stringify(state.title)}`);
+            start();
+        },
+        onNodeStart: (nodeId, state) => {
+            latestState = state;
+            const node = state.nodes[nodeId];
+            emit(`node-started run=${state.runId} node=${nodeId} executor=${node?.executor ?? "unknown"} ${countStatuses(state)}`);
+        },
+        onNodeOutput: (_nodeId, _chunk, state) => {
+            latestState = state;
+        },
+        onNodeFinish: (nodeId, state) => {
+            latestState = state;
+            const node = state.nodes[nodeId];
+            emit(`node-finished run=${state.runId} node=${nodeId} status=${node?.status ?? "unknown"} duration=${formatDuration(node?.durationMs ?? 0)} ${countStatuses(state)}`);
+        },
+        onRunFinish: (state) => {
+            latestState = state;
+            stop();
+            emit(`finished run=${state.runId} status=${state.status} ${countStatuses(state)}`);
+        },
+    };
+    return { observer, dispose: stop };
+}

package/dist/commands/run-dag.js

@@ -0,0 +1,22 @@
+import { parseRunDagArgs } from "../application/dag/args.js";
+import { runDagUseCase } from "../application/dag/run-dag.js";
+import { createRunDagProgressObserver } from "./run-dag-progress.js";
+export { parseRunDagArgs };
+export async function runRunDag(repoRoot, rawArgs) {
+    const parsed = parseRunDagArgs(rawArgs, repoRoot);
+    const { quiet, progressIntervalMs, ...runInput } = parsed;
+    const progress = quiet || parsed.dryRun || parsed.initOnly
+        ? undefined
+        : createRunDagProgressObserver({ intervalMs: progressIntervalMs });
+    try {
+        const result = await runDagUseCase({
+            repoRoot,
+            ...runInput,
+            observer: progress?.observer,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    finally {
+        progress?.dispose();
+    }
+}

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,113 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { buildContextUsageReport, formatContextUsageReportHuman, parseStatsContextArgs, } from "../application/context-usage/skill-resolution-stats.js";
+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`;
+}
+async function runLegacyStepStats(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}`);
+}
+async function runContextStats(repoRoot, args) {
+    const parsed = parseStatsContextArgs(args);
+    const report = await buildContextUsageReport(repoRoot, { last: parsed.last });
+    if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        console.log(formatContextUsageReportHuman(report));
+    }
+    if (!report.ok)
+        process.exitCode = 1;
+}
+/**
+ * `stats` — legacy step-duration histogram (default, no subcommand).
+ * `stats context [--last N] [--json]` — skill-resolution / outcome telemetry.
+ */
+export async function runStats(repoRoot, args = []) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === undefined) {
+        await runLegacyStepStats(repoRoot);
+        return;
+    }
+    if (subcommand === "context") {
+        await runContextStats(repoRoot, rest);
+        return;
+    }
+    throw new Error(`unknown stats subcommand: ${subcommand}\nusage: stats | stats context [--last <n>] [--json]`);
+}

package/dist/commands/status.js

@@ -0,0 +1,57 @@
+import { getTaskDir, getTaskPaths, getTaskStatus, loadTaskConfig, } from "../task/runtime.js";
+import { getArtifactPath } from "../shared/artifacts-core.js";
+import { buildTaskReadModel } from "../task/read-model.js";
+export async function runStatus(repoRoot, taskId) {
+    // Read-only: do not refresh/repair/migrate. Mutations belong to task advance.
+    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,
+        // Prefer task advance/status; keep single next action (no parallel command arrays).
+        next: {
+            kind: "advance-or-status",
+            command: readModel.nextAction.command,
+            reason: readModel.nextAction.reason,
+        },
+    }, 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 -- task advance ${options.taskId} --profile auto --json`
+                : `npm run dev -- reference index ${options.taskId}; npm run dev -- task advance ${options.taskId} --profile auto --json`,
+        ],
+    }, 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');
+}