@tea-agent/loop-agent 0.1.0

package/dist/shared/artifacts-core.js

@@ -0,0 +1,88 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const ARTIFACTS_DIR = 'artifacts';
+const SPEC_ARTIFACT_STEPS = ['analyze', 'plan'];
+const DEFAULT_ARTIFACTS = {
+    '分析报告.md': '# 分析报告\n\n## 1. 任务目标\n\n## 2. 当前现状\n\n## 3. 受影响模块与文件\n\n## 4. 关键约束与不变式\n\n## 5. 硬约束摘要\n\n## 6. 允许修改范围 / 禁止修改范围\n\n## 7. 风险点\n\n## 8. 待确认问题\n',
+    '实现计划.md': '# 实现计划\n\n## 1. 修改目标\n\n## 2. 修改范围\n\n## 3. 允许修改文件 / 目录\n\n## 4. 明确不做的内容\n\n## 5. 关键决策\n\n## 6. 不变式\n\n## 7. 风险与回滚点\n\n## 8. 测试与验证方案\n\n## 9. 不在本次范围内的事项\n\n## 10. 待确认事项\n',
+    '修改记录.md': '# 修改记录\n\n## 1. 修改文件清单\n\n## 2. 关键改动说明\n',
+    '验证结果.md': '# 验证结果\n\n## 1. 执行的命令\n\n## 2. 通过项\n\n## 3. 失败项\n',
+    '复盘报告.md': '# 复盘报告\n\n## 1. 质量复盘\n\n## 2. 流程问题\n\n## 3. 下次建议\n',
+};
+const ARTIFACT_NAME_BY_STEP = {
+    analyze: '分析报告.md',
+    plan: '实现计划.md',
+    implement: '修改记录.md',
+    verify: '验证结果.md',
+    retrospective: '复盘报告.md',
+};
+export function getArtifactFileName(step) {
+    return ARTIFACT_NAME_BY_STEP[step];
+}
+export function getArtifactRelativePath(step) {
+    return `${ARTIFACTS_DIR}/${getArtifactFileName(step)}`;
+}
+/** Relative artifact path used in workflow evidence / executor records. */
+export function getArtifactEvidence(step) {
+    return getArtifactRelativePath(step);
+}
+export function getArtifactDisplayName(step) {
+    return getArtifactFileName(step);
+}
+export function formatSpecArtifactRelativePaths() {
+    return SPEC_ARTIFACT_STEPS.map((step) => getArtifactRelativePath(step)).join(' + ');
+}
+export function formatSpecArtifactDisplayNames() {
+    return SPEC_ARTIFACT_STEPS.map((step) => getArtifactDisplayName(step)).join(' + ');
+}
+const REQUIRED_HEADINGS = {
+    analyze: ['# 分析报告', '## 1. 任务目标'],
+    plan: ['# 实现计划', '## 1. 修改目标'],
+    implement: ['# 修改记录', '## 1. 修改文件清单'],
+    retrospective: ['# 复盘报告', '## 1. 质量复盘'],
+};
+export async function initializeArtifacts(taskDir) {
+    const artifactsDir = path.join(taskDir, 'artifacts');
+    await mkdir(artifactsDir, { recursive: true });
+    await Promise.all(Object.entries(DEFAULT_ARTIFACTS).map(([name, content]) => writeFile(path.join(artifactsDir, name), content, 'utf-8')));
+}
+export function getArtifactPath(taskDir, step) {
+    return path.join(taskDir, ARTIFACTS_DIR, getArtifactFileName(step));
+}
+export async function writeArtifactForStep(taskDir, step, content) {
+    await writeFile(getArtifactPath(taskDir, step), `${content.trim()}\n`, 'utf-8');
+}
+function normalizeArtifactContent(content) {
+    return content.replace(/\r/g, '').trim().replace(/\s+/g, ' ');
+}
+function isUnchangedNewTaskTemplate(step, content) {
+    const artifactName = ARTIFACT_NAME_BY_STEP[step];
+    const template = DEFAULT_ARTIFACTS[artifactName];
+    return normalizeArtifactContent(content) === normalizeArtifactContent(template);
+}
+function firstRequiredSectionIsEmpty(step, content) {
+    const [, firstSectionHeading] = REQUIRED_HEADINGS[step];
+    const headingIndex = content.indexOf(firstSectionHeading);
+    if (headingIndex < 0) {
+        return false;
+    }
+    const afterHeading = content.slice(headingIndex + firstSectionHeading.length);
+    const nextHeadingIndex = afterHeading.search(/^##\s/m);
+    const sectionBody = (nextHeadingIndex >= 0 ? afterHeading.slice(0, nextHeadingIndex) : afterHeading).trim();
+    return sectionBody.length === 0;
+}
+export function validateArtifactContent(step, content) {
+    const trimmed = content.trim();
+    if (!trimmed) {
+        return ['artifact content is empty'];
+    }
+    if (isUnchangedNewTaskTemplate(step, trimmed)) {
+        return ['artifact content matches unchanged new-task template'];
+    }
+    if (firstRequiredSectionIsEmpty(step, trimmed)) {
+        return ['artifact first required section has no substantive content'];
+    }
+    const missing = REQUIRED_HEADINGS[step]
+        .filter((heading) => !trimmed.includes(heading));
+    return missing.map((heading) => `missing required heading: ${heading}`);
+}

package/dist/shared/artifacts.js

@@ -0,0 +1,2 @@
+export * from "./artifacts-core.js";
+export * from "./copy-dir.js";

package/dist/shared/context-files.js

@@ -0,0 +1,32 @@
+const DEFAULT_MAX_FILES = {
+    slim: 10,
+    full: 24,
+};
+export function buildContextFiles(groups, taskConfig) {
+    const merged = groups.flat();
+    const deduped = uniqueKeepOrder(merged);
+    const maxFiles = resolveContextMaxFiles(taskConfig);
+    if (maxFiles <= 0 || deduped.length <= maxFiles) {
+        return deduped;
+    }
+    return deduped.slice(0, maxFiles);
+}
+function uniqueKeepOrder(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        result.push(item);
+    }
+    return result;
+}
+function resolveContextMaxFiles(taskConfig) {
+    if (taskConfig.contextMaxFiles > 0) {
+        return taskConfig.contextMaxFiles;
+    }
+    return taskConfig.contextProfile === 'slim'
+        ? DEFAULT_MAX_FILES.slim
+        : DEFAULT_MAX_FILES.full;
+}

package/dist/shared/context.js

@@ -0,0 +1,2 @@
+export * from "./context-files.js";
+export * from "./reference-context.js";

package/dist/shared/copy-dir.js

@@ -0,0 +1,17 @@
+import { copyFile, mkdir, readdir } from 'node:fs/promises';
+import path from 'node:path';
+/** Recursively copy a directory tree. Symlinks are followed. */
+export async function copyDir(src, dest) {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(srcPath, destPath);
+        }
+        else if (entry.isFile() || entry.isSymbolicLink()) {
+            await copyFile(srcPath, destPath);
+        }
+    }
+}

package/dist/shared/git-progress.js

@@ -0,0 +1,165 @@
+import { spawn } from 'node:child_process';
+export async function autoCommitVerifiedProgress(repoRoot, taskConfig) {
+    const statusOutput = await runGit(repoRoot, ['status', '--porcelain=v1', '--untracked-files=all']);
+    const entries = parseGitStatusPorcelain(statusOutput);
+    const changedPaths = Array.from(new Set(entries.map((entry) => entry.path)));
+    const stagedPaths = collectStagedPaths(entries);
+    const selectedPaths = selectAutoCommitPaths(changedPaths, taskConfig, stagedPaths);
+    const skippedPaths = changedPaths.filter((filePath) => !selectedPaths.includes(filePath));
+    const commitMessage = buildAutoCommitMessage(taskConfig);
+    if (selectedPaths.length === 0) {
+        return {
+            committed: false,
+            commitMessage,
+            selectedPaths,
+            skippedPaths,
+        };
+    }
+    await runGit(repoRoot, ['add', '--', ...selectedPaths]);
+    const stagedOutput = await runGit(repoRoot, ['diff', '--cached', '--name-only', '--', ...selectedPaths]);
+    const confirmedStagedPaths = stagedOutput
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (confirmedStagedPaths.length === 0) {
+        return {
+            committed: false,
+            commitMessage,
+            selectedPaths,
+            skippedPaths,
+        };
+    }
+    await runGit(repoRoot, ['commit', '--only', '-m', commitMessage, '--', ...selectedPaths]);
+    const commitHash = (await runGit(repoRoot, ['rev-parse', 'HEAD'])).trim();
+    return {
+        committed: true,
+        commitHash,
+        commitMessage,
+        selectedPaths,
+        skippedPaths,
+    };
+}
+export function parseGitStatusPorcelain(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter(Boolean)
+        .map((line) => {
+        const x = line[0] ?? ' ';
+        const y = line[1] ?? ' ';
+        const rawPath = line.slice(3);
+        const path = normalizeGitPath(rawPath);
+        return { path, x, y };
+    });
+}
+export function selectAutoCommitPaths(changedPaths, taskConfig, stagedPaths) {
+    const allowed = taskConfig.allowedPaths ?? [];
+    const forbidden = taskConfig.forbiddenPaths ?? [];
+    const hasAllowed = allowed.length > 0;
+    return changedPaths.filter((filePath) => {
+        const normalizedPath = normalizePath(filePath);
+        const forbiddenMatch = matchesAnyPattern(normalizedPath, forbidden);
+        if (forbiddenMatch)
+            return false;
+        // Already-staged paths are accepted as implicit authorisation by the
+        // implement step (e.g. `git mv` / `git rm` preformed before verify).
+        // forbiddenPaths still applies as a hard guard.
+        if (stagedPaths?.has(filePath))
+            return true;
+        const allowedMatch = hasAllowed
+            ? matchesAnyPattern(normalizedPath, allowed)
+            : !normalizedPath.startsWith('.harness/tasks/');
+        return allowedMatch;
+    });
+}
+/**
+ * Collect paths that were already staged (modified, added, deleted, renamed,
+ * or copied in the index) before auto-commit runs. Untracked files (`x === '?'`)
+ * are NOT staged; they require explicit allowedPaths approval.
+ */
+export function collectStagedPaths(entries) {
+    const staged = new Set();
+    for (const entry of entries) {
+        if (entry.x !== ' ' && entry.x !== '?') {
+            staged.add(entry.path);
+        }
+    }
+    return staged;
+}
+export function buildAutoCommitMessage(taskConfig) {
+    if (taskConfig.autoCommitMessage?.trim()) {
+        return taskConfig.autoCommitMessage.trim();
+    }
+    return `chore(task): save verified progress for ${taskConfig.taskId}`;
+}
+function matchesAnyPattern(filePath, patterns) {
+    return patterns.some((pattern) => pathMatchesPattern(filePath, pattern));
+}
+export function pathMatchesPattern(filePath, pattern) {
+    const normalizedPath = normalizePath(filePath);
+    let normalizedPattern = normalizePath(pattern);
+    if (normalizedPattern.endsWith('/')) {
+        normalizedPattern = normalizedPattern.slice(0, -1);
+    }
+    if (normalizedPattern.includes('*')) {
+        return globToRegExp(normalizedPattern).test(normalizedPath);
+    }
+    // Directory-style allowlist entries should match nested files too.
+    return normalizedPath === normalizedPattern || normalizedPath.startsWith(`${normalizedPattern}/`);
+}
+function globToRegExp(pattern) {
+    const normalized = normalizePath(pattern);
+    let regex = '^';
+    for (let i = 0; i < normalized.length; i += 1) {
+        const char = normalized[i];
+        const next = normalized[i + 1];
+        if (char === '*' && next === '*') {
+            regex += '.*';
+            i += 1;
+            continue;
+        }
+        if (char === '*') {
+            regex += '[^/]*';
+            continue;
+        }
+        regex += escapeRegExp(char);
+    }
+    regex += '$';
+    return new RegExp(regex);
+}
+function escapeRegExp(char) {
+    return /[\\^$.*+?()[\]{}|]/.test(char) ? `\\${char}` : char;
+}
+function normalizeGitPath(value) {
+    const target = value.includes(' -> ') ? value.split(' -> ').at(-1) ?? value : value;
+    return normalizePath(target);
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+async function runGit(repoRoot, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf-8');
+        child.stderr.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(stdout);
+                return;
+            }
+            reject(new Error(`git ${args.join(' ')} failed: ${(stderr || stdout).trim()}`));
+        });
+    });
+}

package/dist/shared/index.js

@@ -0,0 +1,5 @@
+export * from "./logger.js";
+export * from "./timeout.js";
+export * from "./context.js";
+export * from "./artifacts.js";
+export * from "./path-refs.js";

package/dist/shared/logger.js

@@ -0,0 +1,23 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+export async function appendWorkflowLog(taskDir, message) {
+    const logsDir = path.join(taskDir, 'logs');
+    await mkdir(logsDir, { recursive: true });
+    const line = `[${new Date().toISOString()}] ${message}\n`;
+    await appendFile(path.join(logsDir, 'workflow.log'), line, 'utf-8');
+}
+export async function appendExecutorRecord(taskDir, record) {
+    const logsDir = path.join(taskDir, 'logs');
+    await mkdir(logsDir, { recursive: true });
+    await appendFile(path.join(logsDir, 'executor.jsonl'), `${JSON.stringify(record)}\n`, 'utf-8');
+}
+export async function appendDecisionRecord(taskDir, record) {
+    const logsDir = path.join(taskDir, 'logs');
+    await mkdir(logsDir, { recursive: true });
+    await appendFile(path.join(logsDir, 'decisions.jsonl'), `${JSON.stringify(record)}\n`, 'utf-8');
+}
+export async function appendGoalEventRecord(taskDir, record) {
+    const logsDir = path.join(taskDir, 'logs');
+    await mkdir(logsDir, { recursive: true });
+    await appendFile(path.join(logsDir, 'goal-events.jsonl'), `${JSON.stringify(record)}\n`, 'utf-8');
+}

package/dist/shared/one-shot-prompt-args.js

@@ -0,0 +1,98 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export function createOneShotPromptParseAccum() {
+    return {
+        fromStdin: false,
+        positional: [],
+    };
+}
+export function parseOneShotCommonFlag(args, index, accum) {
+    const arg = args[index];
+    if (arg === "--stdin") {
+        accum.fromStdin = true;
+        return { kind: "consumed", nextIndex: index };
+    }
+    if (arg === "--file") {
+        const path = args[index + 1];
+        if (!path)
+            throw new Error("--file requires a path");
+        accum.fromFile = path;
+        return { kind: "consumed", nextIndex: index + 1 };
+    }
+    if (arg === "--cwd") {
+        const path = args[index + 1];
+        if (!path)
+            throw new Error("--cwd requires a path");
+        accum.cwd = path;
+        return { kind: "consumed", nextIndex: index + 1 };
+    }
+    if (arg === "--timeout") {
+        const val = args[index + 1];
+        if (!val)
+            throw new Error("--timeout requires a value in ms");
+        accum.timeoutMs = parsePositiveTimeoutMs(val);
+        return { kind: "consumed", nextIndex: index + 1 };
+    }
+    if (arg === "--help" || arg === "-h") {
+        return { kind: "help" };
+    }
+    if (!arg.startsWith("--")) {
+        accum.positional.push(arg);
+        return { kind: "consumed", nextIndex: index };
+    }
+    return { kind: "not-common" };
+}
+export function parsePositiveTimeoutMs(val) {
+    const timeoutMs = Number.parseInt(val, 10);
+    if (Number.isNaN(timeoutMs) || timeoutMs <= 0) {
+        throw new Error(`invalid timeout: ${val}`);
+    }
+    return timeoutMs;
+}
+export function resolveOneShotTask(accum, usage) {
+    let task = "";
+    if (accum.fromStdin) {
+        task = readFileSync(process.stdin.fd, "utf-8").trim();
+    }
+    else if (accum.fromFile) {
+        task = readFileSync(resolve(accum.fromFile), "utf-8").trim();
+    }
+    else if (accum.positional.length > 0) {
+        task = accum.positional.join(" ");
+    }
+    if (!task.trim()) {
+        throw formatNoTaskError(usage);
+    }
+    return task;
+}
+export function resolveOneShotCwd(cwd) {
+    return cwd ? resolve(cwd) : undefined;
+}
+export function formatUnknownFlagError(flag, usage) {
+    return new Error(`unknown flag: ${flag}\n${usage}`);
+}
+export function formatNoTaskError(usage) {
+    return new Error(`no task provided\n${usage}`);
+}
+export function printOneShotHelpAndExit(usage) {
+    console.log(usage);
+    process.exit(0);
+}
+export function handleStandaloneOneShotCommandError(err, printUsage) {
+    if (!(err instanceof Error)) {
+        throw err;
+    }
+    if (err.message.startsWith("no task provided")) {
+        printUsage();
+        process.exit(1);
+    }
+    if (err.message.startsWith("unknown flag")) {
+        process.stderr.write(`${err.message}\n`);
+        process.exit(1);
+    }
+    if (err.message.startsWith("usage:")) {
+        process.stderr.write(`${err.message}\n`);
+        process.exit(1);
+    }
+    throw err;
+}

package/dist/shared/path-refs.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+export function toPosixPath(value) {
+    return value.replace(/\\/g, "/");
+}
+export function repoRelativePath(repoRoot, filePath) {
+    const relative = path.relative(repoRoot, filePath) || ".";
+    return toPosixPath(relative);
+}
+export function referencePathJoin(...parts) {
+    return path.posix.join(...parts.map(toPosixPath));
+}
+export function resolveCliPath(value, cwd = process.cwd()) {
+    if (process.platform === "win32" && value.startsWith("/") && !value.startsWith("//")) {
+        return value;
+    }
+    return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+export function rewritePathPrefix(value, oldPrefix, newPrefix) {
+    const normalizedValue = toPosixPath(value);
+    const normalizedOld = toPosixPath(oldPrefix).replace(/\/+$/, "");
+    const normalizedNew = toPosixPath(newPrefix).replace(/\/+$/, "");
+    const toNewPrefixStyle = (rewritten) => value.includes("\\") || newPrefix.includes("\\")
+        ? rewritten.replace(/\//g, "\\")
+        : rewritten;
+    if (normalizedValue === normalizedOld)
+        return toNewPrefixStyle(normalizedNew);
+    if (normalizedValue.startsWith(`${normalizedOld}/`)) {
+        return toNewPrefixStyle(`${normalizedNew}${normalizedValue.slice(normalizedOld.length)}`);
+    }
+    return value;
+}

package/dist/shared/prompts.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isFeatureStudyTask } from './reference-context.js';
+export async function loadPrompt(repoRoot, step, taskConfig) {
+    const filename = resolvePromptFilename(step, taskConfig);
+    const promptPath = path.join(repoRoot, '.harness', 'prompts', filename);
+    try {
+        return await readFile(promptPath, 'utf-8');
+    }
+    catch {
+        if (filename !== `${step}.md`) {
+            return readFile(path.join(repoRoot, '.harness', 'prompts', `${step}.md`), 'utf-8');
+        }
+        throw new Error(`prompt not found: ${promptPath}`);
+    }
+}
+function resolvePromptFilename(step, taskConfig) {
+    if (!taskConfig || !isFeatureStudyTask(taskConfig)) {
+        return `${step}.md`;
+    }
+    if (step === 'analyze')
+        return 'feature-study-analyze.md';
+    if (step === 'plan')
+        return 'feature-study-plan.md';
+    return `${step}.md`;
+}