@tea-agent/loop-agent 0.5.0 → 0.6.0

package/dist/task/source-references.js

@@ -0,0 +1,221 @@
+/**
+ * Deterministic source reference materialization for task harnesses.
+ *
+ * Keeps user-authored PRD / reference docs as immutable copies under
+ * source/references/, separate from the derived source/需求.md contract.
+ */
+import { createHash } from "node:crypto";
+import { access, copyFile, mkdir, readdir, readFile, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { getTaskPaths, loadTaskConfig } from "./runtime.js";
+import { writeTaskConfig } from "../infrastructure/harness/task-store.js";
+export const SOURCE_REFERENCE_DIRECTORY = "references";
+export const SOURCE_MANIFEST_FILE = "source-manifest.json";
+function toPosixRelative(from, to) {
+    return path.relative(from, to).split(path.sep).join("/");
+}
+function slugifyName(value) {
+    const trimmed = value.trim().toLowerCase();
+    const slug = trimmed
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return slug || "requirement";
+}
+function ensureUniqueReferenceName(existing, baseName, extension) {
+    const used = new Set(existing);
+    const candidate = `${baseName}${extension}`;
+    if (!used.has(candidate))
+        return candidate;
+    let index = 2;
+    while (used.has(`${baseName}-${index}${extension}`)) {
+        index += 1;
+    }
+    return `${baseName}-${index}${extension}`;
+}
+export function getSourceManifestPath(sourceDir) {
+    return path.join(sourceDir, SOURCE_MANIFEST_FILE);
+}
+export async function readSourceManifest(sourceDir) {
+    try {
+        const raw = await readFile(getSourceManifestPath(sourceDir), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function writeSourceManifest(sourceDir, manifest) {
+    await writeFile(getSourceManifestPath(sourceDir), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+}
+export async function hashFile(filePath) {
+    const content = await readFile(filePath);
+    return {
+        sha256: createHash("sha256").update(content).digest("hex"),
+        bytes: content.byteLength,
+        content,
+    };
+}
+/**
+ * Copy task.json.referenceDocs into source/references/ without rewriting content.
+ * Existing same-basename files are left untouched (immutable once present).
+ */
+export async function materializeTaskReferenceDocs(input) {
+    const paths = getTaskPaths(input.repoRoot, input.taskId);
+    const taskConfig = input.taskConfig ?? (await loadTaskConfig(input.repoRoot, input.taskId));
+    const docs = taskConfig.referenceDocs ?? [];
+    if (docs.length === 0)
+        return [];
+    const referenceDir = path.join(paths.sourceDir, SOURCE_REFERENCE_DIRECTORY);
+    await mkdir(referenceDir, { recursive: true });
+    const materialized = [];
+    for (const doc of docs) {
+        const absoluteSource = path.isAbsolute(doc.path)
+            ? doc.path
+            : path.resolve(input.repoRoot, doc.path);
+        await assertReadableFile(absoluteSource, `referenceDocs entry "${doc.name ?? doc.path}"`);
+        const extension = path.extname(absoluteSource) || ".md";
+        const baseName = slugifyName(doc.name ?? path.basename(absoluteSource, extension));
+        const targetName = `${baseName}${extension}`;
+        const targetPath = path.join(referenceDir, targetName);
+        try {
+            await access(targetPath);
+            // Keep existing materialized copy immutable.
+        }
+        catch {
+            await copyFile(absoluteSource, targetPath);
+        }
+        materialized.push(targetPath);
+    }
+    return materialized;
+}
+export async function importPrdDocument(input) {
+    const now = input.now ?? new Date();
+    const paths = getTaskPaths(input.repoRoot, input.taskId);
+    await assertTaskExists(paths.taskConfigPath, input.taskId);
+    const absoluteSource = path.isAbsolute(input.filePath)
+        ? input.filePath
+        : path.resolve(input.repoRoot, input.filePath);
+    await assertReadableFile(absoluteSource, "PRD file");
+    const hash = await hashFile(absoluteSource);
+    const extension = path.extname(absoluteSource) || ".md";
+    const requestedName = slugifyName(input.name ?? "requirement");
+    const role = input.role ?? "requirement";
+    const referenceDir = path.join(paths.sourceDir, SOURCE_REFERENCE_DIRECTORY);
+    await mkdir(referenceDir, { recursive: true });
+    const existingManifest = await readSourceManifest(paths.sourceDir);
+    const existingNames = new Set((existingManifest?.documents ?? []).map((doc) => path.basename(doc.materializedPath)));
+    // Also avoid clobbering non-manifest files in references/.
+    try {
+        for (const entry of await readdir(referenceDir)) {
+            existingNames.add(entry);
+        }
+    }
+    catch {
+        // directory may be empty / just created
+    }
+    // Prefer stable name "requirement.md" when free; otherwise suffix.
+    const preferredName = `${requestedName}${extension}`;
+    const targetFileName = existingNames.has(preferredName)
+        ? // If the same content is already there, reuse; else unique name.
+            (await sameHashIfExists(path.join(referenceDir, preferredName), hash.sha256))
+                ? preferredName
+                : ensureUniqueReferenceName(existingNames, requestedName, extension)
+        : preferredName;
+    const targetPath = path.join(referenceDir, targetFileName);
+    if (!(await fileExists(targetPath))) {
+        await writeFile(targetPath, hash.content);
+    }
+    const importedAt = now.toISOString();
+    const sourcePathForRecord = path.isAbsolute(input.filePath)
+        ? toPosixRelative(input.repoRoot, absoluteSource)
+        : input.filePath.split(path.sep).join("/");
+    const materializedRelativePath = `${SOURCE_REFERENCE_DIRECTORY}/${targetFileName}`;
+    const document = {
+        role,
+        name: requestedName,
+        sourcePath: sourcePathForRecord,
+        materializedPath: materializedRelativePath,
+        sha256: hash.sha256,
+        bytes: hash.bytes,
+        importedAt,
+    };
+    const documents = [...(existingManifest?.documents ?? [])].filter((entry) => entry.materializedPath !== materializedRelativePath);
+    documents.push(document);
+    documents.sort((left, right) => left.materializedPath.localeCompare(right.materializedPath));
+    const manifest = {
+        schemaVersion: 1,
+        taskId: input.taskId,
+        updatedAt: importedAt,
+        documents,
+    };
+    await writeSourceManifest(paths.sourceDir, manifest);
+    const taskConfig = await loadTaskConfig(input.repoRoot, input.taskId);
+    const referenceDocs = [...(taskConfig.referenceDocs ?? [])];
+    const alreadyListed = referenceDocs.some((doc) => {
+        const absolute = path.isAbsolute(doc.path)
+            ? doc.path
+            : path.resolve(input.repoRoot, doc.path);
+        return absolute === absoluteSource;
+    });
+    if (!alreadyListed) {
+        referenceDocs.push({
+            name: requestedName,
+            path: sourcePathForRecord,
+        });
+        await writeTaskConfig(input.repoRoot, input.taskId, {
+            ...taskConfig,
+            referenceDocs,
+        });
+    }
+    return {
+        taskId: input.taskId,
+        sourcePath: sourcePathForRecord,
+        materializedAbsolutePath: targetPath,
+        materializedRelativePath,
+        sha256: hash.sha256,
+        bytes: hash.bytes,
+        manifestPath: getSourceManifestPath(paths.sourceDir),
+        referenceDocs: alreadyListed ? referenceDocs : [...referenceDocs],
+    };
+}
+async function sameHashIfExists(filePath, sha256) {
+    try {
+        const existing = await hashFile(filePath);
+        return existing.sha256 === sha256;
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertTaskExists(taskConfigPath, taskId) {
+    try {
+        await access(taskConfigPath);
+    }
+    catch {
+        throw new Error(`task not found: ${taskId} (expected ${taskConfigPath}). Run new-task first.`);
+    }
+}
+async function assertReadableFile(filePath, label) {
+    try {
+        await access(filePath);
+    }
+    catch {
+        throw new Error(`${label} is not readable: ${filePath}`);
+    }
+}

package/dist/worker/cli.js

@@ -9,6 +9,11 @@ import { resolveLoopAgentProfile } from "./profile-mapping.js";
 import { writeMorningReport } from "./report/morning-report.js";
 import { buildBatchRunId, runReadyTasks } from "./runner/run-ready.js";
 import { createProgressReporter } from "./progress-reporter.js";
+import { createCompositeProgressReporter } from "./observability/progress-composite.js";
+import { createRoutedWorkerEventStore } from "./observability/event-store.js";
+import { buildGlobalSnapshot } from "./observability/read-model.js";
+import { createObserveServer } from "./observe/server.js";
+import { prepareTaskPoolRetry } from "./pool/run-store.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
 export function buildAgentWorkerProgram() {
@@ -21,6 +26,7 @@ export function buildAgentWorkerProgram() {
     const task = program.command("task").description("TaskSpec utilities");
     const batch = program.command("batch").description("Task Pool batch utilities");
     const report = program.command("report").description("Task Pool reporting utilities");
+    const observe = program.command("observe").description("Observe UI server and snapshot utilities");
     task
         .command("validate")
         .argument("<task-yaml>", "TaskSpec YAML file")
@@ -43,6 +49,20 @@ export function buildAgentWorkerProgram() {
         const result = resolveLoopAgentProfile(parsed);
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     });
+    task
+        .command("retry")
+        .argument("<task-id>", "Failed Task Pool task to requeue")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--reason <reason>", "Why the failure is safe to retry")
+        .description("Explicitly requeue a failed task; the next run-ready uses a new workerRunId")
+        .action(async (taskId, options) => {
+        const result = await prepareTaskPoolRetry({
+            repoRoot: path.resolve(options.repo),
+            taskId,
+            ...(options.reason ? { reason: options.reason } : {}),
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    });
     batch
         .command("run-ready")
         .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
@@ -62,7 +82,18 @@ export function buildAgentWorkerProgram() {
             loopAgentBin: options.loopAgentBin,
             artifactRoot: path.join(repoRoot, ".task-pool", "artifacts", batchRunId),
         });
-        const progress = createProgressReporter({ quiet: options.quiet ?? false });
+        let progress;
+        try {
+            const eventStore = createRoutedWorkerEventStore(repoRoot);
+            progress = createCompositeProgressReporter({
+                quiet: options.quiet ?? false,
+                eventStore,
+                context: { batchRunId },
+            });
+        }
+        catch {
+            progress = createProgressReporter({ quiet: options.quiet ?? false });
+        }
         const result = await runReadyTasks({
             repoRoot,
             featureDir: path.resolve(options.featureDir),
@@ -80,6 +111,36 @@ export function buildAgentWorkerProgram() {
         if (result.status !== "completed")
             process.exitCode = 1;
     });
+    observe
+        .command("serve")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--port <port>", "HTTP port", "8787")
+        .option("--host <host>", "Bind host", "127.0.0.1")
+        .description("Start read-only observe HTTP server")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const server = await createObserveServer({
+            repoRoot,
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+        });
+        process.stdout.write(`${server.url}\n`);
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    });
+    observe
+        .command("snapshot")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit JSON (default)")
+        .description("Print GlobalSnapshot JSON to stdout")
+        .action(async (options) => {
+        const snapshot = await buildGlobalSnapshot({ repoRoot: path.resolve(options.repo) });
+        process.stdout.write(`${JSON.stringify(snapshot)}\n`);
+    });
     report
         .command("morning")
         .requiredOption("--repo <repo-root>", "Target repo root")

package/dist/worker/loop-agent/loop-agent-client.js

@@ -1,13 +1,16 @@
 import { spawn } from "node:child_process";
+import { appendFileSync, writeFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parseCommandJson } from "./parse-json.js";
 export const DEFAULT_WORKER_COMMAND_TIMEOUT_MS = 120_000;
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
 export class LoopAgentClient {
     loopAgentBin;
     baseArgs;
     artifactRoot;
     defaultTimeoutMs;
+    heartbeatIntervalMs;
     env;
     constructor(options) {
         this.loopAgentBin = options.loopAgentBin;
@@ -15,6 +18,8 @@ export class LoopAgentClient {
         this.artifactRoot = options.artifactRoot;
         this.defaultTimeoutMs =
             options.defaultTimeoutMs ?? DEFAULT_WORKER_COMMAND_TIMEOUT_MS;
+        this.heartbeatIntervalMs =
+            options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
         this.env = options.env;
     }
     async run(args, options) {
@@ -27,12 +32,23 @@ export class LoopAgentClient {
         const startedAt = Date.now();
         const artifactDir = path.join(this.artifactRoot, sanitizeName(options.artifactName));
         await mkdir(artifactDir, { recursive: true });
+        const stdoutPath = path.join(artifactDir, "stdout.txt");
+        const stderrPath = path.join(artifactDir, "stderr.txt");
+        const resultPath = path.join(artifactDir, "result.json");
         const { stdout, stderr, exitCode, timedOut } = await spawnCommand({
             command,
             args: commandArgs,
             cwd: options.cwd,
             timeoutMs: options.timeoutMs ?? this.defaultTimeoutMs,
             env: { ...process.env, ...this.env, ...options.env },
+            stdoutPath,
+            stderrPath,
+            resultPath,
+            heartbeatIntervalMs: this.heartbeatIntervalMs,
+            onSpawn: options.onSpawn,
+            onStdout: options.onStdout,
+            onStderr: options.onStderr,
+            onHeartbeat: options.onHeartbeat,
         });
         const result = {
             ok: exitCode === 0 && !timedOut,
@@ -46,9 +62,9 @@ export class LoopAgentClient {
             timedOut,
             artifacts: {
                 dir: artifactDir,
-                stdoutPath: path.join(artifactDir, "stdout.txt"),
-                stderrPath: path.join(artifactDir, "stderr.txt"),
-                resultPath: path.join(artifactDir, "result.json"),
+                stdoutPath,
+                stderrPath,
+                resultPath,
             },
         };
         if (options.expectJson) {
@@ -69,12 +85,30 @@ export class LoopAgentClient {
 }
 function spawnCommand(input) {
     return new Promise((resolve, reject) => {
+        const startedAtMs = Date.now();
+        const startedAt = new Date(startedAtMs).toISOString();
         const child = spawn(input.command, input.args, {
             cwd: input.cwd,
             env: input.env,
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
         });
+        try {
+            writeFileSync(input.stdoutPath, "", "utf-8");
+            writeFileSync(input.stderrPath, "", "utf-8");
+        }
+        catch {
+            // best-effort: degrade to in-memory buffer only
+        }
+        invokeSpawnCallback(input.onSpawn, {
+            pid: child.pid,
+            startedAt,
+            artifactRefs: {
+                stdoutPath: input.stdoutPath,
+                stderrPath: input.stderrPath,
+                resultPath: input.resultPath,
+            },
+        });
         let stdout = "";
         let stderr = "";
         let timedOut = false;
@@ -82,24 +116,82 @@ function spawnCommand(input) {
             timedOut = true;
             child.kill("SIGTERM");
         }, input.timeoutMs);
+        let heartbeatTimer;
+        if (input.heartbeatIntervalMs > 0) {
+            heartbeatTimer = setInterval(() => {
+                invokeHeartbeatCallback(input.onHeartbeat, startedAtMs);
+            }, input.heartbeatIntervalMs);
+        }
+        const clearTimers = () => {
+            clearTimeout(timeout);
+            if (heartbeatTimer !== undefined) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = undefined;
+            }
+        };
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         child.stdout.on("data", (chunk) => {
             stdout += chunk;
+            appendChunkBestEffort(input.stdoutPath, chunk);
+            invokeChunkCallback(input.onStdout, chunk);
         });
         child.stderr.on("data", (chunk) => {
             stderr += chunk;
+            appendChunkBestEffort(input.stderrPath, chunk);
+            invokeChunkCallback(input.onStderr, chunk);
         });
         child.on("error", (error) => {
-            clearTimeout(timeout);
+            clearTimers();
             reject(error);
         });
         child.on("close", (exitCode) => {
-            clearTimeout(timeout);
+            clearTimers();
             resolve({ stdout, stderr, exitCode, timedOut });
         });
     });
 }
+function appendChunkBestEffort(filePath, chunk) {
+    try {
+        appendFileSync(filePath, chunk, "utf-8");
+    }
+    catch {
+        // best-effort: degrade to in-memory buffer only
+    }
+}
+function invokeSpawnCallback(callback, info) {
+    if (!callback) {
+        return;
+    }
+    try {
+        callback(info);
+    }
+    catch (error) {
+        process.stderr.write(`LoopAgentClient onSpawn callback error: ${String(error)}\n`);
+    }
+}
+function invokeChunkCallback(callback, chunk) {
+    if (!callback) {
+        return;
+    }
+    try {
+        callback(chunk);
+    }
+    catch (error) {
+        process.stderr.write(`LoopAgentClient output callback error: ${String(error)}\n`);
+    }
+}
+function invokeHeartbeatCallback(callback, startedAtMs) {
+    if (!callback) {
+        return;
+    }
+    try {
+        callback({ at: new Date().toISOString(), elapsedMs: Date.now() - startedAtMs });
+    }
+    catch (error) {
+        process.stderr.write(`LoopAgentClient onHeartbeat callback error: ${String(error)}\n`);
+    }
+}
 function sanitizeName(name) {
     return name.replace(/[^a-zA-Z0-9._-]+/g, "-");
 }