@tea-agent/loop-agent 0.4.0 → 0.6.0

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, "-");
 }

package/dist/worker/materialize/harness-task-materializer.js

@@ -1,4 +1,5 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
 import { writeTaskConfig, writeTaskArtifactFile } from "../../infrastructure/harness/task-store.js";
@@ -51,7 +52,25 @@ export async function materializeTaskSpec(options) {
         taskYamlPath: path.join(paths.sourceDir, "task.yaml"),
     };
     await mkdir(paths.sourceDir, { recursive: true });
-    await writeFile(sourcePaths.requirementPath, renderRequirementMarkdown(options.taskSpec), "utf-8");
+    const referencePaths = await materializeSourceDocs({
+        taskSpec: options.taskSpec,
+        taskSpecPath: options.taskSpecPath,
+        sourceDir: paths.sourceDir,
+    });
+    const sourceDocTrace = await buildSourceDocTrace({
+        taskSpec: options.taskSpec,
+        taskSpecPath: options.taskSpecPath,
+        referencePaths,
+    });
+    const acceptanceSummaries = await buildAcceptanceSummaries({
+        taskSpec: options.taskSpec,
+        taskSpecPath: options.taskSpecPath,
+        referencePaths,
+    });
+    await writeFile(sourcePaths.requirementPath, renderRequirementMarkdown(options.taskSpec, {
+        sourceDocTrace,
+        acceptanceSummaries,
+    }), "utf-8");
     await writeFile(sourcePaths.constraintsPath, renderConstraintsMarkdown(options.taskSpec), "utf-8");
     await writeFile(sourcePaths.taskYamlPath, YAML.stringify(options.taskSpec), "utf-8");
     const profileMapping = resolveLoopAgentProfile(options.taskSpec);
@@ -62,11 +81,31 @@ export async function materializeTaskSpec(options) {
         featureId: options.taskSpec.feature_id,
         loopAgentProfile: profileMapping.loopAgentProfile,
         taskConfigPath: paths.taskConfigPath,
-        source: sourcePaths,
+        source: {
+            ...sourcePaths,
+            // Reference copies make the upstream requirement/design/test cases concrete.
+            referencePaths,
+        },
     };
     await writeTaskArtifactFile(options.repoRoot, harnessTaskId, "materialize-manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
     return manifest;
 }
+async function materializeSourceDocs(input) {
+    const referenceDir = path.join(input.sourceDir, "references");
+    const taskSpecDir = path.dirname(path.resolve(input.taskSpecPath));
+    const referencePaths = {};
+    await mkdir(referenceDir, { recursive: true });
+    for (const [key, relativePath] of Object.entries(input.taskSpec.source_docs)) {
+        if (!relativePath)
+            continue;
+        const sourcePath = path.resolve(taskSpecDir, relativePath);
+        const extension = path.extname(sourcePath) || ".md";
+        const targetPath = path.join(referenceDir, `${key}${extension}`);
+        await copyFile(sourcePath, targetPath);
+        referencePaths[key] = targetPath;
+    }
+    return referencePaths;
+}
 export function buildHarnessTaskId(taskSpec, now) {
     const date = now.toISOString().slice(0, 10);
     const slug = slugify(`${taskSpec.id}-${taskSpec.title}`);
@@ -81,10 +120,15 @@ function slugify(value) {
         .replace(/^-+|-+$/g, "")
         .replace(/-{2,}/g, "-");
 }
-function renderRequirementMarkdown(taskSpec) {
+/** Exported for unit tests: derived contract must point back to immutable references. */
+export function renderRequirementMarkdown(taskSpec, options = {}) {
     const lines = [
         `# ${taskSpec.title}`,
         "",
+        "> Derived execution contract from TaskSpec.",
+        "> Authoritative sources: `source/references/*` (immutable copies of TaskSpec source_docs).",
+        "> On conflict, prefer `source/references/*` over this file. Do not invent missing acceptance text.",
+        "",
         `TaskSpec business id: ${taskSpec.id}`,
         `Feature id: ${taskSpec.feature_id}`,
         `Task type: ${taskSpec.type}`,
@@ -104,10 +148,123 @@ function renderRequirementMarkdown(taskSpec) {
     if (taskSpec.scope.open_questions.length > 0) {
         lines.push("## Open Questions", "", ...bulletLines(taskSpec.scope.open_questions), "");
     }
-    lines.push("## Acceptance References", "", ...bulletLines(taskSpec.acceptance_refs), "");
+    const acceptanceLines = options.acceptanceSummaries && options.acceptanceSummaries.length > 0
+        ? options.acceptanceSummaries.map((entry) => `- ${entry.id}: ${entry.summary}`)
+        : bulletLines(taskSpec.acceptance_refs);
+    lines.push("## Acceptance References", "", ...acceptanceLines, "");
+    if (options.sourceDocTrace && options.sourceDocTrace.length > 0) {
+        lines.push("## Source Docs / Traceability", "", ...options.sourceDocTrace.map((entry) => `- ${entry.key}: ${entry.materializedPath} (from ${entry.sourcePath}; sha256=${entry.sha256.slice(0, 12)}…)`), "");
+    }
+    else {
+        lines.push("## Source Docs / Traceability", "", ...bulletLines(Object.entries(taskSpec.source_docs).map(([key, value]) => `${key}: source/references/${key}.* ← ${value}`)), "");
+    }
     lines.push("## Required Outputs", "", ...bulletLines(taskSpec.outputs.required), "");
     return `${lines.join("\n").trimEnd()}\n`;
 }
+async function buildSourceDocTrace(input) {
+    const entries = [];
+    for (const [key, relativePath] of Object.entries(input.taskSpec.source_docs)) {
+        if (!relativePath)
+            continue;
+        const materializedAbsolute = input.referencePaths[key];
+        if (!materializedAbsolute)
+            continue;
+        const content = await readFile(materializedAbsolute);
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        const extension = path.extname(materializedAbsolute) || ".md";
+        entries.push({
+            key,
+            sourcePath: relativePath.split(path.sep).join("/"),
+            materializedPath: `references/${key}${extension}`,
+            sha256,
+        });
+    }
+    entries.sort((left, right) => left.key.localeCompare(right.key));
+    return entries;
+}
+async function buildAcceptanceSummaries(input) {
+    const acceptanceAbsolute = input.referencePaths.acceptance ??
+        path.resolve(path.dirname(path.resolve(input.taskSpecPath)), input.taskSpec.source_docs.acceptance);
+    let raw = "";
+    try {
+        raw = await readFile(acceptanceAbsolute, "utf-8");
+    }
+    catch {
+        return input.taskSpec.acceptance_refs.map((id) => ({
+            id,
+            summary: "(acceptance source unreadable; see source/references/acceptance.*)",
+        }));
+    }
+    const byId = indexAcceptanceItems(raw);
+    return input.taskSpec.acceptance_refs.map((id) => ({
+        id,
+        summary: byId.get(id) ??
+            "(no summary found in acceptance source; re-read source/references/acceptance.*)",
+    }));
+}
+/** Pull short human summaries for acceptance IDs from YAML or Markdown sources. */
+export function indexAcceptanceItems(raw) {
+    const map = new Map();
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return map;
+    // YAML AcceptanceSpec: { acceptance: [ { id, title, then, ... } ] }
+    try {
+        const parsed = YAML.parse(trimmed);
+        const items = extractAcceptanceArray(parsed);
+        for (const item of items) {
+            if (!item || typeof item !== "object")
+                continue;
+            const record = item;
+            const id = typeof record.id === "string" ? record.id : undefined;
+            if (!id)
+                continue;
+            const title = typeof record.title === "string" ? record.title.trim() : "";
+            const then = typeof record.then === "string" ? record.then.trim() : "";
+            const given = typeof record.given === "string" ? record.given.trim() : "";
+            const when = typeof record.when === "string" ? record.when.trim() : "";
+            const parts = [
+                title,
+                then ? `then: ${then}` : "",
+                !then && given ? `given: ${given}` : "",
+                !then && when ? `when: ${when}` : "",
+            ].filter(Boolean);
+            map.set(id, compactSummary(parts.join(" — ") || id));
+        }
+        if (map.size > 0)
+            return map;
+    }
+    catch {
+        // fall through to markdown heuristics
+    }
+    // Markdown / free text: lines like "AC-BE-001: ..." or "- AC-BE-001 ..."
+    for (const line of trimmed.split("\n")) {
+        const match = line.match(/(?:^|\s)((?:AC|REQ)[-A-Z0-9]+)\s*[:：\-–—]\s*(.+)$/i);
+        if (!match)
+            continue;
+        const id = match[1];
+        const summary = compactSummary(match[2]);
+        if (!map.has(id))
+            map.set(id, summary);
+    }
+    return map;
+}
+function extractAcceptanceArray(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    const root = parsed;
+    if (Array.isArray(root.acceptance))
+        return root.acceptance;
+    if (Array.isArray(parsed))
+        return parsed;
+    return [];
+}
+function compactSummary(value, maxChars = 180) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxChars)
+        return normalized;
+    return `${normalized.slice(0, maxChars - 1)}…`;
+}
 function renderConstraintsMarkdown(taskSpec) {
     const lines = [
         `# Execution Constraints for ${taskSpec.id}`,

package/dist/worker/observability/event-store.js

@@ -0,0 +1,82 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+function writeDiagnostic(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[worker-event-store] ${context}: ${message}\n`);
+}
+function serializeEvent(event) {
+    return `${JSON.stringify(event)}\n`;
+}
+/** Identifiers used as event-store path segments must not alter the route. */
+export function isSafeObservabilityIdentifier(value) {
+    return value !== "." && value !== ".." && !/[\\/\0]/.test(value);
+}
+export function createWorkerEventStore(jsonlPath) {
+    return {
+        async append(event) {
+            try {
+                await mkdir(path.dirname(jsonlPath), { recursive: true });
+                await appendFile(jsonlPath, serializeEvent(event), "utf-8");
+            }
+            catch (error) {
+                writeDiagnostic(`append failed (${jsonlPath})`, error);
+            }
+        },
+        async appendMany(events) {
+            for (const event of events) {
+                await this.append(event);
+            }
+        },
+        appendSyncSafe(event) {
+            try {
+                mkdirSync(path.dirname(jsonlPath), { recursive: true });
+                appendFileSync(jsonlPath, serializeEvent(event), "utf-8");
+            }
+            catch (error) {
+                writeDiagnostic(`appendSyncSafe failed (${jsonlPath})`, error);
+            }
+        },
+        path() {
+            return jsonlPath;
+        },
+    };
+}
+export function createRoutedWorkerEventStore(repoRoot) {
+    const observabilityRoot = path.join(path.resolve(repoRoot), ".task-pool", "observability");
+    const globalStore = createWorkerEventStore(path.join(observabilityRoot, "events.jsonl"));
+    let queue = Promise.resolve();
+    function storesFor(event) {
+        const stores = [globalStore];
+        if (event.batchRunId && isSafeObservabilityIdentifier(event.batchRunId)) {
+            stores.push(createWorkerEventStore(path.join(observabilityRoot, "batches", event.batchRunId, "events.jsonl")));
+        }
+        if (event.workerRunId && isSafeObservabilityIdentifier(event.workerRunId)) {
+            stores.push(createWorkerEventStore(path.join(observabilityRoot, "runs", event.workerRunId, "events.jsonl")));
+        }
+        return stores;
+    }
+    const store = {
+        append(event) {
+            const write = queue.then(async () => {
+                await Promise.all(storesFor(event).map((target) => target.append(event)));
+            });
+            queue = write.catch(() => { });
+            return write;
+        },
+        async appendMany(events) {
+            for (const event of events) {
+                await store.append(event);
+            }
+        },
+        appendSyncSafe(event) {
+            for (const target of storesFor(event)) {
+                target.appendSyncSafe(event);
+            }
+        },
+        path() {
+            return globalStore.path();
+        },
+    };
+    return store;
+}

package/dist/worker/observability/events.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
+const WORKER_EVENT_SOURCES = new Set([
+    "worker",
+    "loop-agent-command",
+    "dag",
+    "shell",
+    "artifact",
+    "observe",
+]);
+const WORKER_EVENT_TYPES = new Set([
+    "batch.started",
+    "batch.finished",
+    "readyQueue.computed",
+    "task.queued",
+    "task.started",
+    "task.finished",
+    "task.reused",
+    "step.started",
+    "step.heartbeat",
+    "step.output",
+    "step.finished",
+    "command.started",
+    "command.output",
+    "command.heartbeat",
+    "command.finished",
+    "dag.run.started",
+    "dag.node.started",
+    "dag.node.output",
+    "dag.node.finished",
+    "dag.run.finished",
+    "artifact.written",
+    "failure.routed",
+    "state.updated",
+]);
+export function createWorkerEvent(input, options) {
+    const now = options?.now ?? (() => new Date());
+    const randomUuid = options?.randomUuid ?? randomUUID;
+    return {
+        ...input,
+        schemaVersion: 1,
+        id: input.id ?? randomUuid(),
+        at: input.at ?? now().toISOString(),
+        spanId: input.spanId ?? randomUuid(),
+    };
+}
+export function parseWorkerEventLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return undefined;
+        }
+        return isWorkerEvent(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isWorkerEvent(value) {
+    const event = value;
+    return (event.schemaVersion === 1 &&
+        typeof event.id === "string" &&
+        event.id.length > 0 &&
+        typeof event.at === "string" &&
+        !Number.isNaN(Date.parse(event.at)) &&
+        typeof event.spanId === "string" &&
+        event.spanId.length > 0 &&
+        typeof event.source === "string" &&
+        WORKER_EVENT_SOURCES.has(event.source) &&
+        typeof event.type === "string" &&
+        WORKER_EVENT_TYPES.has(event.type) &&
+        typeof event.label === "string");
+}
+export function truncatePreview(text, maxBytes = 4096) {
+    return truncateUtf8Preview(text, maxBytes);
+}
+export function redactForPreview(text) {
+    return redactSecrets(text);
+}

package/dist/worker/observability/progress-composite.js

@@ -0,0 +1,33 @@
+import { createProgressReporter, } from "../progress-reporter.js";
+import { createWorkerEvent } from "./events.js";
+export function createCompositeProgressReporter(options) {
+    const textReporter = createProgressReporter({
+        quiet: options.quiet,
+        now: options.now,
+        isTty: options.isTty,
+        sink: options.sink,
+    });
+    const eventStore = options.eventStore;
+    const context = options.context ?? {};
+    const now = options.now ?? (() => new Date());
+    return {
+        ...textReporter,
+        async event(input) {
+            if (!eventStore)
+                return;
+            try {
+                const event = createWorkerEvent({
+                    ...input,
+                    batchRunId: input.batchRunId ?? context.batchRunId,
+                    workerRunId: input.workerRunId ?? context.workerRunId,
+                    taskId: input.taskId ?? context.taskId,
+                }, { now });
+                await eventStore.append(event);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`[progress-composite] event append failed: ${message}\n`);
+            }
+        },
+    };
+}