@tea-agent/loop-agent 0.1.0

package/dist/executors/shell-executor.js

@@ -0,0 +1,300 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { truncateOutput } from "./cursor-executor.js";
+import { expandShellPreset, buildVerdictGateShellCommand } from "./shell-presets.js";
+import { pathsChangedDuringRun, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
+import { buildShellProcessEnv } from "./shell-verification.js";
+const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
+const SUMMARY_STDOUT_MAX = 4_000;
+const SUMMARY_STDERR_MAX = 2_000;
+const NODE_STDOUT_MAX = 12_000;
+const NODE_STDERR_MAX = 8_000;
+function resolveBashExecutable() {
+    if (process.env.LOOP_AGENT_BASH)
+        return process.env.LOOP_AGENT_BASH;
+    if (process.platform !== "win32")
+        return "bash";
+    const candidates = [
+        process.env.GIT_BASH,
+        process.env.ProgramFiles
+            ? path.join(process.env.ProgramFiles, "Git", "bin", "bash.exe")
+            : undefined,
+        process.env["ProgramFiles(x86)"]
+            ? path.join(process.env["ProgramFiles(x86)"], "Git", "bin", "bash.exe")
+            : undefined,
+        process.env.LocalAppData
+            ? path.join(process.env.LocalAppData, "Programs", "Git", "bin", "bash.exe")
+            : undefined,
+    ];
+    return candidates.find((candidate) => candidate && existsSync(candidate)) ?? "bash";
+}
+function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+export function resolveShellCwd(root, requestedCwd) {
+    const resolved = requestedCwd ? path.resolve(root, requestedCwd) : root;
+    if (!isWithinRoot(root, resolved)) {
+        throw new Error(`shell cwd must stay within DAG cwd: ${requestedCwd}`);
+    }
+    return resolved;
+}
+/** Preset commands first, then explicit shell.commands, then verdictGate (deterministic ordering). */
+export function resolveShellCommands(shell) {
+    const fromPreset = shell.preset ? expandShellPreset(shell.preset) : [];
+    const explicit = (shell.commands ?? []).filter((command) => command.trim().length > 0);
+    const fromVerdictGate = shell.verdictGate
+        ? [buildVerdictGateShellCommand(shell.verdictGate)]
+        : [];
+    return [...fromPreset, ...explicit, ...fromVerdictGate];
+}
+async function readGitStatusPorcelain(cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
+            cwd,
+            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 status failed: ${stderr.trim() || stdout.trim()}`));
+        });
+    });
+}
+export async function executeShellCommand(input) {
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        const injectedEnv = input.dagRunMeta
+            ? {
+                HARNESS_DAG_RUN_DIR: input.dagRunMeta.runDir,
+                HARNESS_DAG_RUN_ID: input.dagRunMeta.runId,
+            }
+            : undefined;
+        const child = spawn(resolveBashExecutable(), ["-lc", input.command], {
+            cwd: input.cwd,
+            env: buildShellProcessEnv(input.envAllowlist, injectedEnv),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        let timeoutHandle;
+        let sigkillHandle;
+        function finish(result) {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            resolve({
+                command: input.command,
+                cwd: input.cwd,
+                durationMs: Date.now() - startedAt,
+                stdout,
+                stderr,
+                timedOut,
+                ...result,
+            });
+        }
+        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", (error) => {
+            stderr += stderr ? `\n${error.message}` : error.message;
+            finish({
+                exitCode: null,
+                failureCategory: "spawn-error",
+                ok: false,
+            });
+        });
+        child.on("close", (code) => {
+            finish({
+                exitCode: code,
+                failureCategory: timedOut
+                    ? "timeout"
+                    : code === 0
+                        ? "success"
+                        : "nonzero-exit",
+                ok: code === 0 && !timedOut,
+            });
+        });
+        if (input.timeoutMs > 0) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+                sigkillHandle = setTimeout(() => {
+                    if (child.exitCode === null) {
+                        child.kill("SIGKILL");
+                    }
+                }, 5_000);
+            }, input.timeoutMs);
+        }
+    });
+}
+function summarizeCommandResults(results) {
+    const stdout = results
+        .map((result) => [`$ ${result.command}`, result.stdout.trim()].filter(Boolean).join("\n"))
+        .join("\n\n");
+    const stderr = results
+        .filter((result) => result.stderr.trim().length > 0)
+        .map((result) => [`$ ${result.command}`, result.stderr.trim()].join("\n"))
+        .join("\n\n");
+    return {
+        stdout: truncateOutput(stdout, NODE_STDOUT_MAX).text,
+        stderr: truncateOutput(stderr, NODE_STDERR_MAX).text,
+    };
+}
+export function buildShellResultSummaryMarkdown(input) {
+    const lines = [
+        "# Shell execution summary",
+        "",
+        "## Run metadata",
+        "",
+        "| Field | Value |",
+        "|-------|-------|",
+        `| dagRunId | ${input.runId} |`,
+        `| dagNodeId | ${input.nodeId} |`,
+        `| cwd | ${input.rootCwd} |`,
+        `| commandCount | ${input.results.length} |`,
+        "",
+        "## Commands",
+        "",
+        "| # | ok | exitCode | failureCategory | durationMs | cwd | command |",
+        "|---|----|----------|-----------------|------------|-----|---------|",
+    ];
+    input.results.forEach((result, index) => {
+        lines.push(`| ${index + 1} | ${result.ok} | ${result.exitCode ?? "null"} | ${result.failureCategory} | ${result.durationMs} | ${result.cwd} | ${result.command.replace(/\|/g, "\\|")} |`);
+    });
+    if (input.writeGuardViolations && input.writeGuardViolations.length > 0) {
+        lines.push("", "## Write guard violations", "");
+        for (const violation of input.writeGuardViolations) {
+            lines.push(`- ${violation}`);
+        }
+    }
+    for (const [index, result] of input.results.entries()) {
+        const stdout = truncateOutput(result.stdout, SUMMARY_STDOUT_MAX);
+        const stderr = truncateOutput(result.stderr, SUMMARY_STDERR_MAX);
+        lines.push("", `## Command ${index + 1}: ${result.command}`, "", "### stdout", "", "```text", stdout.text, "```");
+        if (stdout.truncated)
+            lines.push("", "_(stdout truncated)_");
+        if (stderr.text.trim()) {
+            lines.push("", "### stderr", "", "```text", stderr.text, "```");
+            if (stderr.truncated)
+                lines.push("", "_(stderr truncated)_");
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function runShellWriteGuard(input) {
+    const afterStatus = await readGitStatusPorcelain(input.rootCwd);
+    const beforeSnapshot = snapshotGitStatusPorcelain(input.beforeStatus);
+    const afterSnapshot = snapshotGitStatusPorcelain(afterStatus);
+    const changedPaths = pathsChangedDuringRun(beforeSnapshot, afterSnapshot);
+    return validateShellWriteGuard({
+        changedPaths,
+        writePolicy: input.task.writePolicy,
+        writeSet: input.task.writeSet,
+        allowedPaths: input.task.allowedPaths,
+        forbiddenPaths: input.task.forbiddenPaths,
+    });
+}
+export async function executeDagShellNode(input, meta) {
+    const shell = input.task.shell;
+    const commands = shell ? resolveShellCommands(shell) : [];
+    if (!shell || commands.length === 0) {
+        throw new Error(`shell task ${input.task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`);
+    }
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    const timeoutMs = shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+    const results = [];
+    const started = Date.now();
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        // Non-git cwd: skip write guard (documented limitation).
+        beforeStatus = undefined;
+    }
+    for (const command of commands) {
+        const result = await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs,
+            envAllowlist: shell.envAllowlist,
+            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+        });
+        results.push(result);
+        if (!result.ok)
+            break;
+    }
+    let writeGuardViolations = [];
+    let writeGuardOk = true;
+    if (beforeStatus !== undefined) {
+        try {
+            const guard = await runShellWriteGuard({
+                rootCwd: input.cwd,
+                task: input.task,
+                beforeStatus,
+            });
+            writeGuardOk = guard.ok;
+            writeGuardViolations = guard.violations;
+        }
+        catch {
+            writeGuardOk = false;
+            writeGuardViolations = ["write guard failed: git status unavailable"];
+        }
+    }
+    const commandsOk = results.every((result) => result.ok);
+    const ok = commandsOk && writeGuardOk;
+    const firstFailure = results.find((result) => !result.ok);
+    const nodeDir = path.join(meta.runDir, input.task.id);
+    await mkdir(nodeDir, { recursive: true });
+    await writeFile(path.join(nodeDir, "result.summary.md"), buildShellResultSummaryMarkdown({
+        nodeId: input.task.id,
+        runId: meta.runId,
+        rootCwd: input.cwd,
+        results,
+        writeGuardViolations: writeGuardOk ? undefined : writeGuardViolations,
+    }), "utf-8");
+    const aggregate = summarizeCommandResults(results);
+    const stderrParts = [aggregate.stderr];
+    if (!writeGuardOk) {
+        stderrParts.push(`write guard failed: ${writeGuardViolations.join(", ")}`);
+    }
+    return {
+        ok,
+        stdout: aggregate.stdout,
+        stderr: stderrParts.filter(Boolean).join("\n\n"),
+        failureCategory: !commandsOk
+            ? (firstFailure?.failureCategory ?? "nonzero-exit")
+            : !writeGuardOk
+                ? "write-guard"
+                : "success",
+        durationMs: Date.now() - started,
+    };
+}

package/dist/executors/shell-presets.js

@@ -0,0 +1,47 @@
+/** Preset command lists run before explicit `shell.commands` (deterministic ordering). */
+export const DAG_SHELL_PRESETS = {
+    "loop-agent-standard-verify": [
+        "npm run lint",
+        "npm run typecheck",
+        "npx vitest run test/dag-shell-executor.test.ts test/dag-validate.test.ts test/dag-runner.test.ts --reporter=dot",
+    ],
+};
+export function expandShellPreset(preset) {
+    return [...DAG_SHELL_PRESETS[preset]];
+}
+function escapeShellSingleQuoted(value) {
+    return value.replace(/'/g, "'\\''");
+}
+const VERDICT_GATE_NODE_PARSER_FIRST_NON_EMPTY = 'node -e \'const fs=require("fs"); const raw=JSON.parse(fs.readFileSync(process.argv[1], "utf8")); const text=raw.assistantText ?? raw.stdout ?? ""; const line=String(text).split(/\\r?\\n/).find((value) => value.trim().length > 0) ?? ""; process.stdout.write(line);\' "${FILE}" || true';
+const VERDICT_GATE_NODE_PARSER_FIRST_VERDICT_LINE = 'node -e \'const fs=require("fs"); const raw=JSON.parse(fs.readFileSync(process.argv[1], "utf8")); const text=raw.assistantText ?? raw.stdout ?? ""; const normalize=(value) => { const trimmed=String(value).trim(); const emphasized=trimmed.match(/^\\*{1,3}\\s*(VERDICT:[^*]+?)\\s*\\*{1,3}$/); return (emphasized ? emphasized[1] : trimmed).trim(); }; const line=String(text).split(/\\r?\\n/).map(normalize).find((value) => /^VERDICT:/.test(value)) ?? ""; process.stdout.write(line);\' "${FILE}" || true';
+function verdictGateNodeParser(lineMode) {
+    return lineMode === "first-verdict-line"
+        ? VERDICT_GATE_NODE_PARSER_FIRST_VERDICT_LINE
+        : VERDICT_GATE_NODE_PARSER_FIRST_NON_EMPTY;
+}
+/**
+ * Build a single shell command that reads `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`
+ * (injected by the shell executor from runtime meta), parses a single candidate
+ * verdict line from `assistantText ?? stdout`, and accepts only exact verdict values.
+ * Modes:
+ * - first-non-empty: first non-empty line
+ * - first-verdict-line: first line matching /^VERDICT:/ after trim and optional whole-line Markdown emphasis normalization
+ *
+ * Must stay one command so `shell.commands[]` process isolation cannot drop state variables.
+ */
+export function buildVerdictGateShellCommand(gate) {
+    const gateLabel = gate.label ?? `${gate.fromNodeId} verdict`;
+    const jsonFile = `${gate.fromNodeId}.json`;
+    const lineMode = gate.lineMode ?? "first-non-empty";
+    const parser = verdictGateNodeParser(lineMode);
+    const preamble = `test -n "\${HARNESS_DAG_RUN_DIR:-}" || { echo "missing HARNESS_DAG_RUN_DIR for ${gateLabel} gate" >&2; exit 1; }; FILE="\${HARNESS_DAG_RUN_DIR}/${jsonFile}"; test -f "\${FILE}" || { echo "missing ${gateLabel} JSON output: \${FILE}" >&2; exit 1; }; FIRST=$(${parser})`;
+    const blockedMessage = `${gateLabel} gate blocked: \${FIRST:-missing VERDICT line}`;
+    if (gate.accept.length === 1) {
+        const expected = escapeShellSingleQuoted(gate.accept[0]);
+        return `${preamble}; test "\${FIRST}" = '${expected}' || { echo "${blockedMessage}" >&2; exit 1; }`;
+    }
+    const acceptPattern = gate.accept
+        .map((value) => `'${escapeShellSingleQuoted(value)}'`)
+        .join("|");
+    return `${preamble}; case "\${FIRST}" in ${acceptPattern}) exit 0 ;; *) echo "${blockedMessage}" >&2; exit 1 ;; esac`;
+}

package/dist/executors/shell-verification.js

@@ -0,0 +1,251 @@
+import { spawn } from "node:child_process";
+export const DEFAULT_VERIFY_TIMEOUT_MS = 1_800_000;
+const VERIFY_ENV_ALLOWLIST = [
+    "HOME",
+    "PATH",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "CI",
+    "NODE_OPTIONS",
+    "NODE_PATH",
+    "PNPM_HOME",
+    "COREPACK_ENABLE",
+    "COREPACK_ENABLE_AUTO_PIN",
+    "COREPACK_HOME",
+];
+export function buildVerifyProcessEnv(mode = "clean") {
+    if (mode === "inherit") {
+        return { ...process.env };
+    }
+    const env = { CI: "true" };
+    for (const key of VERIFY_ENV_ALLOWLIST) {
+        const value = process.env[key];
+        if (value !== undefined && value !== "") {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+/** Clean verify env plus explicitly allowlisted host variables (no broad passthrough). */
+export function buildShellProcessEnv(envAllowlist, injected) {
+    const env = buildVerifyProcessEnv("clean");
+    if (envAllowlist) {
+        for (const key of envAllowlist) {
+            const value = process.env[key];
+            if (value !== undefined) {
+                env[key] = value;
+            }
+        }
+    }
+    if (injected) {
+        for (const [key, value] of Object.entries(injected)) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+export function extractLastFailureCategory(verifyReportText) {
+    const categoryLine = verifyReportText.match(/- category:\s*([a-z0-9-]+)/i);
+    if (categoryLine?.[1])
+        return categoryLine[1].toLowerCase();
+    const kindLine = verifyReportText.match(/:\s*(environment-failure|governance-failure|typecheck-failure|test-failure|verify-failure|timeout)/i);
+    return kindLine?.[1]?.toLowerCase();
+}
+export function renderVerifyReport(results) {
+    const passed = results.filter((result) => result.ok);
+    const failed = results.filter((result) => !result.ok);
+    const commandBlock = results
+        .map((result) => result.args.join(" "))
+        .join("\n");
+    const passedList = passed.length > 0
+        ? passed.map((result) => `- ${result.label}`).join("\n")
+        : "- 无";
+    const failedList = failed.length > 0
+        ? failed
+            .map((result) => `- ${result.label}${result.timedOut ? " (TIMEOUT)" : ""}`)
+            .join("\n")
+        : "- 无";
+    const failureKinds = failed.length > 0
+        ? failed
+            .map((result) => `- ${result.label}: ${result.failureCategory ?? "unknown"}${result.attempts > 1 ? ` (attempts=${result.attempts})` : ""}`)
+            .join("\n")
+        : "- 无";
+    const failureSummary = failed.length > 0
+        ? failed
+            .map((result) => `- ${result.label}${result.timedOut ? " [TIMEOUT]" : ""}: ${summarize(result.stderr || result.stdout)}`)
+            .join("\n")
+        : "- 无";
+    const commandDetails = results
+        .map((result) => [
+        `### ${result.label}`,
+        `- command: \`${result.args.join(" ")}\``,
+        `- cwd: \`${result.cwd}\``,
+        `- exitCode: ${result.exitCode ?? "null"}`,
+        `- attempts: ${result.attempts}`,
+        `- category: ${result.failureCategory ?? (result.ok ? "success" : "unknown")}`,
+        `- durationMs: ${result.durationMs}`,
+    ].join("\n"))
+        .join("\n\n");
+    const nextStep = failed.length > 0
+        ? "- [ ] 进入修复子循环\n- [ ] 需要人工判断失败原因是否由环境导致"
+        : "- [x] 无需继续修复\n- [ ] 可进入 retrospective";
+    return [
+        "# 验证结果",
+        "",
+        "## 1. 执行的命令",
+        "```bash",
+        commandBlock,
+        "```",
+        "",
+        "## 2. 通过项",
+        passedList,
+        "",
+        "## 3. 失败项",
+        failedList,
+        "",
+        "## 4. 失败摘要",
+        failureSummary,
+        "",
+        "## 5. 失败分类",
+        failureKinds,
+        "",
+        "## 6. 命令详情",
+        commandDetails,
+        "",
+        "## 7. 下一步建议",
+        nextStep,
+        "",
+    ].join("\n");
+}
+export async function executeCommand(command, defaultTimeoutMs = DEFAULT_VERIFY_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const [binary, ...args] = command.args;
+        const timeoutMs = command.timeoutMs ?? defaultTimeoutMs;
+        const startedAt = Date.now();
+        const child = spawn(binary, args, {
+            cwd: command.cwd,
+            env: command.env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let timeoutHandle;
+        let sigkillHandle;
+        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", (error) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            resolve({
+                ...command,
+                attempts: 1,
+                durationMs: Date.now() - startedAt,
+                exitCode: code,
+                failureCategory: classifyVerifyCommandFailure(command, code, timedOut, stderr, stdout),
+                ok: code === 0,
+                stderr,
+                stdout,
+                timedOut,
+            });
+        });
+        if (timeoutMs > 0) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+                sigkillHandle = setTimeout(() => {
+                    if (child.exitCode === null) {
+                        child.kill("SIGKILL");
+                    }
+                }, 5_000);
+            }, timeoutMs);
+        }
+    });
+}
+export async function executeVerifyCommands(commands, defaultTimeoutMs, options) {
+    if (options.mode === "parallel") {
+        return Promise.all(commands.map((command) => executeCommandWithRetry(command, defaultTimeoutMs, options.retryCount)));
+    }
+    const results = [];
+    for (const command of commands) {
+        const result = await executeCommandWithRetry(command, defaultTimeoutMs, options.retryCount);
+        results.push(result);
+        if (options.failFast && !result.ok) {
+            break;
+        }
+    }
+    return results;
+}
+async function executeCommandWithRetry(command, defaultTimeoutMs, retryCount) {
+    let lastResult = await executeCommand(command, defaultTimeoutMs);
+    let attempts = 1;
+    while (!lastResult.ok && attempts <= retryCount) {
+        attempts += 1;
+        lastResult = await executeCommand(command, defaultTimeoutMs);
+    }
+    return {
+        ...lastResult,
+        attempts,
+    };
+}
+export function summarizeVerifyFailure(results) {
+    const firstFailure = results.find((result) => !result.ok);
+    if (!firstFailure)
+        return "success";
+    return firstFailure.failureCategory ?? "verify-failure";
+}
+function classifyVerifyCommandFailure(command, exitCode, timedOut, stderr, stdout) {
+    if (timedOut)
+        return "timeout";
+    if (exitCode === 0)
+        return "success";
+    const joined = `${command.label} ${command.args.join(" ")} ${stderr} ${stdout}`.toLowerCase();
+    if (joined.includes("check-repo") || joined.includes("governance"))
+        return "governance-failure";
+    if (/pnpm.*configured to use|corepack invoked pnpm|packagemanager|cannot find pnpm|enoent.*pnpm/.test(joined)) {
+        return "environment-failure";
+    }
+    if (joined.includes("typecheck") || joined.includes("tsc"))
+        return "typecheck-failure";
+    if (joined.includes("test"))
+        return "test-failure";
+    if (/not found|enoent/.test(joined))
+        return "environment-failure";
+    return "verify-failure";
+}
+function summarize(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 240) || "no output captured";
+}
+export function resolveVerifyPreset(preset, taskConfig) {
+    if (!preset || preset === "auto") {
+        if (taskConfig.complexity === "small")
+            return "quick";
+        if (taskConfig.complexity === "large")
+            return "full";
+        return "standard";
+    }
+    return preset;
+}