@ryanfw/prompt-orchestration-pipeline 1.3.1 → 1.3.2

package/src/core/agent-step.ts

@@ -1,15 +1,33 @@
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { chmodSync, existsSync } from "node:fs";
+import { cp, mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
 import { createTaskFileIO, generateLogName } from "./file-io.ts";
 import { LogEvent, LogFileExtension } from "../config/log-events.ts";
 import { run } from "../harness/index.ts";
 import { startMcpIoServer } from "../harness/mcp-io-server.ts";
 import type { McpIoServerHandle } from "../harness/mcp-io-server.ts";
 import type { AgentEntryConfig, AgentStepResult } from "./agent-types.ts";
-import type { RunOptions, HarnessRun, HarnessEvent } from "../harness/index.ts";
+import type {
+  RunOptions,
+  HarnessRun,
+  HarnessEvent,
+  HarnessName,
+  McpServerConfig,
+  RunResult,
+} from "../harness/index.ts";
 import type { TaskFileIO } from "./file-io.ts";
 
+type EnvSnapshot = Record<string, string | undefined>;
+let compatibilityEnvQueue: Promise<void> = Promise.resolve();
+
+interface HarnessCompatibility {
+  mcpServers?: McpServerConfig[];
+  env?: Record<string, string>;
+  cleanup?: () => Promise<void>;
+}
+
 function gitSync(args: string[], cwd: string): { exitCode: number; stdout: string; stderr: string } {
   const result = Bun.spawnSync(["git", ...args], {
     cwd,
@@ -62,6 +80,200 @@ async function captureDiff(io: TaskFileIO, cwd: string): Promise<boolean> {
   }
 }
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? value as Record<string, unknown> : null;
+}
+
+function expandHome(path: string): string {
+  return path.startsWith("~/") ? join(process.env.HOME ?? "", path.slice(2)) : path;
+}
+
+function findExecutable(name: string, candidateDirs: string[]): string | null {
+  const pathEntries = (process.env.PATH ?? "").split(":").filter(Boolean);
+  for (const dir of [...pathEntries, ...candidateDirs.map(expandHome)]) {
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function existingBinOverride(harness: HarnessName): string | undefined {
+  const upper = harness.toUpperCase();
+  return process.env[`LLM_ADAPTER_${upper}_BIN`] ?? process.env[`POP_${upper}_BIN`];
+}
+
+function snapshotEnv(keys: string[]): EnvSnapshot {
+  return Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+}
+
+function applyEnv(values: Record<string, string>): EnvSnapshot {
+  const previous = snapshotEnv(Object.keys(values));
+  for (const [key, value] of Object.entries(values)) {
+    process.env[key] = value;
+  }
+  return previous;
+}
+
+function restoreEnv(previous: EnvSnapshot): void {
+  for (const [key, value] of Object.entries(previous)) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+}
+
+async function withCompatibilityEnv<T>(
+  compatibility: HarnessCompatibility,
+  runWithEnv: () => Promise<T>,
+): Promise<T> {
+  if (!compatibility.env) {
+    try {
+      return await runWithEnv();
+    } finally {
+      await compatibility.cleanup?.();
+    }
+  }
+
+  const previousTurn = compatibilityEnvQueue;
+  let releaseTurn!: () => void;
+  compatibilityEnvQueue = new Promise<void>((resolve) => {
+    releaseTurn = resolve;
+  });
+  await previousTurn;
+
+  const previousEnv = applyEnv(compatibility.env);
+  try {
+    return await runWithEnv();
+  } finally {
+    restoreEnv(previousEnv);
+    try {
+      await compatibility.cleanup?.();
+    } finally {
+      releaseTurn();
+    }
+  }
+}
+
+function defaultOpencodeConfigDir(): string {
+  return join(process.env.HOME ?? homedir(), ".config", "opencode");
+}
+
+function opencodeConfigDir(): string {
+  return process.env.OPENCODE_CONFIG_DIR ?? defaultOpencodeConfigDir();
+}
+
+async function readJsonObject(path: string): Promise<Record<string, unknown>> {
+  if (!existsSync(path)) return {};
+  const parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
+  return asRecord(parsed) ?? {};
+}
+
+function codexConfigValue(key: string, value: string): string {
+  return `${key}=${JSON.stringify(value)}`;
+}
+
+async function prepareHarnessCompatibility(
+  harness: HarnessName,
+  mcpHandle: McpIoServerHandle | undefined,
+): Promise<HarnessCompatibility> {
+  if (!mcpHandle) return {};
+
+  const mcpServer: McpServerConfig = {
+    name: "popio",
+    url: mcpHandle.connection.url,
+    headers: { Authorization: `Bearer ${mcpHandle.connection.token}` },
+  };
+
+  if (harness === "claude") {
+    return { mcpServers: [mcpServer] };
+  }
+
+  if (harness === "opencode") {
+    const configDir = await mkdtemp(join(tmpdir(), "opencode-mcp-"));
+    const sourceConfigDir = opencodeConfigDir();
+    if (existsSync(sourceConfigDir)) {
+      await cp(sourceConfigDir, configDir, { recursive: true, force: true });
+    }
+    const configPath = join(configDir, "opencode.json");
+    const existingConfig = await readJsonObject(configPath);
+    const existingMcp = asRecord(existingConfig["mcp"]) ?? {};
+    await writeFile(
+      configPath,
+      JSON.stringify({
+        ...existingConfig,
+        mcp: {
+          ...existingMcp,
+          popio: {
+            type: "remote",
+            url: mcpHandle.connection.url,
+            headers: { Authorization: `Bearer ${mcpHandle.connection.token}` },
+            enabled: true,
+          },
+        },
+      }, null, 2),
+    );
+    return {
+      env: { OPENCODE_CONFIG_DIR: configDir },
+      cleanup: async () => {
+        await rm(configDir, { recursive: true, force: true });
+      },
+    };
+  }
+
+  if (harness === "codex") {
+    const wrapperDir = await mkdtemp(join(tmpdir(), "codex-mcp-"));
+    const wrapperPath = join(wrapperDir, "codex");
+    const realBin =
+      existingBinOverride("codex") ??
+      findExecutable("codex", ["/opt/homebrew/bin", "~/.local/bin"]) ??
+      "codex";
+    await writeFile(
+      wrapperPath,
+      [
+        "#!/bin/sh",
+        'exec "$POP_REAL_CODEX_BIN" "$@" \\',
+        '  -c "$POP_MCP_URL_CONFIG" \\',
+        '  -c \'mcp_servers.popio.bearer_token_env_var="POP_MCP_TOKEN"\'',
+        "",
+      ].join("\n"),
+    );
+    chmodSync(wrapperPath, 0o700);
+    return {
+      env: {
+        LLM_ADAPTER_CODEX_BIN: wrapperPath,
+        POP_REAL_CODEX_BIN: realBin,
+        POP_MCP_URL_CONFIG: codexConfigValue("mcp_servers.popio.url", mcpHandle.connection.url),
+        POP_MCP_TOKEN: mcpHandle.connection.token,
+      },
+      cleanup: async () => {
+        await rm(wrapperDir, { recursive: true, force: true });
+      },
+    };
+  }
+
+  return {};
+}
+
+function costFromRaw(raw: unknown): number | undefined {
+  const record = asRecord(raw);
+  if (!record) return undefined;
+  if (typeof record["total_cost_usd"] === "number") return record["total_cost_usd"];
+  if (typeof record["costUsd"] === "number") return record["costUsd"];
+  const info = asRecord(record["info"]);
+  if (typeof info?.["costUsd"] === "number") return info["costUsd"];
+  return undefined;
+}
+
+function extractCostUsd(events: HarnessEvent[]): number | undefined {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const cost = costFromRaw(events[i]!.raw);
+    if (cost !== undefined) return cost;
+  }
+  return undefined;
+}
+
 /** Dependency seam shared by the agent runners (injected in tests). */
 interface AgentRunDeps {
   run?: typeof run;
@@ -86,6 +298,8 @@ export async function executeAgent(
   const _run = deps?.run ?? run;
   const _startMcpIoServer = deps?.startMcpIoServer ?? startMcpIoServer;
   const { io, entry } = args;
+  const observedEvents: HarnessEvent[] = [];
+  let completedResult: RunResult | undefined;
 
   const cwd = entry.cwd ?? io.getTaskDir();
   // The harness spawns with this cwd before any artifact is written, so the task
@@ -115,30 +329,30 @@ export async function executeAgent(
       LogEvent.DEBUG,
       LogFileExtension.TEXT,
     );
-
+    const compatibility = await prepareHarnessCompatibility(entry.harness, mcpHandle);
     const options: RunOptions = {
       harness: entry.harness,
       prompt,
       cwd,
       model: entry.model,
-      mcpServers: mcpHandle
-        ? [{
-            name: "popio",
-            url: mcpHandle.connection.url,
-            headers: { Authorization: `Bearer ${mcpHandle.connection.token}` },
-          }]
-        : undefined,
+      ...(compatibility.mcpServers ? { mcpServers: compatibility.mcpServers } : {}),
       timeoutMs: entry.timeoutMs,
+      ...(entry.idleTimeoutMs !== undefined ? { idleTimeoutMs: entry.idleTimeoutMs } : {}),
       permissionMode: "bypass",
       onEvent: (event: HarnessEvent) => {
+        observedEvents.push(event);
         void io.writeLog(logName, JSON.stringify(event.raw) + "\n", {
           mode: "append",
         });
       },
     };
 
-    const harnessRun: HarnessRun = _run(options);
-    const result = await harnessRun.result;
+    const result = await withCompatibilityEnv(compatibility, async () => {
+      const harnessRun: HarnessRun = _run(options);
+      const harnessResult = await harnessRun.result;
+      completedResult = harnessResult;
+      return harnessResult;
+    });
 
     await io.writeArtifact("agent-result.md", result.finalMessage);
 
@@ -157,7 +371,7 @@ export async function executeAgent(
       finalMessage: result.finalMessage,
       artifactsWritten: allArtifacts,
       usage: result.usage,
-      costUsd: result.costUsd,
+      costUsd: result.costUsd ?? extractCostUsd(observedEvents),
       sessionId: result.sessionId,
     };
   } catch (err) {
@@ -170,6 +384,9 @@ export async function executeAgent(
       ok: false,
       finalMessage: "",
       artifactsWritten: allArtifacts,
+      usage: completedResult?.usage,
+      costUsd: completedResult?.costUsd ?? extractCostUsd(observedEvents),
+      sessionId: completedResult?.sessionId,
       error: err instanceof Error ? err.message : String(err),
     };
   } finally {

package/src/core/agent-types.ts

@@ -13,6 +13,7 @@ export interface AgentEntryConfig {
   cwd?: string;
   io?: boolean;
   timeoutMs?: number;
+  idleTimeoutMs?: number;
   captureDiff?: boolean;
 }
 
@@ -48,6 +49,8 @@ export interface TaskAgentOptions {
   io?: boolean;
   /** Overall wall-clock cap in milliseconds. */
   timeoutMs?: number;
+  /** No-output cap in milliseconds. Defaults to the adapter's idle timeout. */
+  idleTimeoutMs?: number;
   /** Capture a git diff of the working tree as an `agent.patch` artifact. */
   captureDiff?: boolean;
 }

package/src/core/file-io.ts

@@ -1,9 +1,10 @@
 import { mkdir, rename, appendFile } from "node:fs/promises";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, appendFileSync, renameSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
 import { Database } from "bun:sqlite";
 import { LogFileExtension, isValidLogEvent, isValidLogFileExtension } from "../config/log-events";
-import { writeJobStatus } from "./status-writer";
+import { writeJobStatus, flushJobStatus } from "./status-writer";
+import { createJobLogger } from "./logger";
 import { executeBatch, validateBatchOptions } from "./batch-runner";
 import type { BatchOptions, BatchResult } from "./batch-runner";
 
@@ -169,34 +170,6 @@ export async function trackFile(
   });
 }
 
-/**
- * @internal Synchronous status writer for writeLogSync and getDB.
- * Reads tasks-status.json, applies updater, writes back as pretty-printed JSON.
- * Falls back to a minimal default snapshot on missing or invalid JSON.
- * No temp-file-rename, no async queue participation.
- */
-export function writeJobStatusSync(
-  jobDir: string,
-  updater: (snapshot: Record<string, unknown>) => void,
-): void {
-  const statusPath = join(jobDir, "tasks-status.json");
-  let snapshot: Record<string, unknown>;
-  try {
-    const raw = readFileSync(statusPath, "utf-8");
-    snapshot = JSON.parse(raw) as Record<string, unknown>;
-  } catch {
-    snapshot = {
-      id: basename(jobDir),
-      state: "pending",
-      tasks: {},
-      files: { artifacts: [], logs: [], tmp: [] },
-    };
-  }
-  updater(snapshot);
-  mkdirSync(jobDir, { recursive: true });
-  writeFileSync(statusPath, JSON.stringify(snapshot, null, 2));
-}
-
 export function createTaskFileIO(config: TaskFileIOConfig): TaskFileIO {
   const { workDir, taskName, statusPath, getStage } = config;
   const trackTaskFilesEnabled = config.trackTaskFiles ?? true;
@@ -234,28 +207,8 @@ export function createTaskFileIO(config: TaskFileIOConfig): TaskFileIO {
     const db = new Database(dbPath);
     db.exec("PRAGMA journal_mode = WAL;");
 
-    writeJobStatusSync(jobDir, (snapshot: Record<string, unknown>) => {
-      const files = (snapshot["files"] ?? {}) as FilesRecord;
-      snapshot["files"] = files;
-      const artifactsList = (files.artifacts ?? []) as string[];
-      files.artifacts = artifactsList;
-      if (!artifactsList.includes("run.db")) {
-        artifactsList.push("run.db");
-      }
-
-      if (trackTaskFilesEnabled) {
-        const tasks = (snapshot["tasks"] ?? {}) as Record<string, TaskRecord>;
-        snapshot["tasks"] = tasks;
-        const task = (tasks[taskName] ?? {}) as TaskRecord;
-        tasks[taskName] = task;
-        const taskFiles = (task.files ?? {}) as FilesRecord;
-        task.files = taskFiles;
-        const taskArtifactsList = (taskFiles.artifacts ?? []) as string[];
-        taskFiles.artifacts = taskArtifactsList;
-        if (!taskArtifactsList.includes("run.db")) {
-          taskArtifactsList.push("run.db");
-        }
-      }
+    void trackFile(jobDir, "artifacts", "run.db", taskName, trackTaskFilesEnabled).catch((err) => {
+      createJobLogger("file-io", basename(jobDir)).warn("getDB: manifest tracking failed", err);
     });
 
     return db;
@@ -314,28 +267,8 @@ export function createTaskFileIO(config: TaskFileIOConfig): TaskFileIO {
         renameSync(tmpPath, filePath);
       }
 
-      writeJobStatusSync(jobDir, (snapshot: Record<string, unknown>) => {
-        const files = (snapshot["files"] ?? {}) as FilesRecord;
-        snapshot["files"] = files;
-        const logsList = (files.logs ?? []) as string[];
-        files.logs = logsList;
-        if (!logsList.includes(name)) {
-          logsList.push(name);
-        }
-
-        if (trackTaskFilesEnabled) {
-          const tasks = (snapshot["tasks"] ?? {}) as Record<string, TaskRecord>;
-          snapshot["tasks"] = tasks;
-          const task = (tasks[taskName] ?? {}) as TaskRecord;
-          tasks[taskName] = task;
-          const taskFiles = (task.files ?? {}) as FilesRecord;
-          task.files = taskFiles;
-          const taskLogsList = (taskFiles.logs ?? []) as string[];
-          taskFiles.logs = taskLogsList;
-          if (!taskLogsList.includes(name)) {
-            taskLogsList.push(name);
-          }
-        }
+      void trackFile(jobDir, "logs", name, taskName, trackTaskFilesEnabled).catch((err) => {
+        createJobLogger("file-io", basename(jobDir)).warn("writeLogSync: manifest tracking failed", err);
       });
     },
 
@@ -348,6 +281,7 @@ export function createTaskFileIO(config: TaskFileIOConfig): TaskFileIO {
         return await executeBatch(db, options);
       } finally {
         db.close();
+        await flushJobStatus(jobDir);
       }
     },
   };

package/src/core/pipeline-runner.ts

@@ -5,7 +5,7 @@ import { unlinkSync } from "node:fs";
 import { getConfig, getPipelineConfig } from "./config";
 import { validatePipelineOrThrow } from "./validation";
 import { loadFreshModule } from "./module-loader";
-import { atomicWrite, writeJobStatus, type GateInfo } from "./status-writer";
+import { atomicWrite, writeJobStatus, flushJobStatus, StatusCorruptError, type GateInfo } from "./status-writer";
 import { decideTransition } from "./lifecycle-policy";
 import { runPipeline } from "./task-runner";
 import type { AuditLogEntry, PipelineResult } from "./task-runner";
@@ -672,8 +672,14 @@ export async function runPipelineJob(jobId: string): Promise<void> {
   while (true) {
     const pipeline = await loadPipeline(config.pipelineJsonPath);
     const pipelineTasks = normalizePipelineTasks(pipeline);
-    const statusText = await Bun.file(config.statusPath).text();
-    const status = JSON.parse(statusText) as { tasks: Record<string, { state?: string }> };
+    let status: { tasks: Record<string, { state?: string }> };
+    try {
+      const statusText = await Bun.file(config.statusPath).text();
+      status = JSON.parse(statusText) as { tasks: Record<string, { state?: string }> };
+    } catch (parseErr: unknown) {
+      if (parseErr instanceof SyntaxError) throw new StatusCorruptError(config.statusPath, { cause: parseErr });
+      throw parseErr;
+    }
 
     let selectedEntry: PipelineTaskEntry | null = null;
     let selectedTaskState: TaskStateValue = TaskState.PENDING;
@@ -1092,6 +1098,49 @@ export async function runPipelineJob(jobId: string): Promise<void> {
   }
   await releaseJobSlotBestEffort(dataDir, jobId);
   } catch (err) {
+    if (err instanceof StatusCorruptError) {
+      console.error(`Status corruption detected for job "${jobId}": ${err.statusPath} — refusing to overwrite`);
+      if (workDir !== undefined) {
+        try {
+          const failureIO = createTaskFileIO({
+            workDir,
+            taskName: "orchestrator",
+            trackTaskFiles: false,
+            getStage: () => "runPipelineJob",
+            statusPath: join(workDir, "tasks-status.json"),
+          });
+          const failureLogName = generateLogName(
+            "orchestrator",
+            "runPipelineJob",
+            LogEvent.FAILURE_DETAILS,
+            LogFileExtension.JSON,
+          );
+          await failureIO.writeLog(
+            failureLogName,
+            JSON.stringify({
+              type: "status_corrupt",
+              jobId,
+              statusPath: err.statusPath,
+              message: err.message,
+            }, null, 2),
+          );
+        } catch {
+          // Do not mask the original error if log-write fails
+        }
+        try {
+          await cleanupPidFile(workDir);
+        } catch {
+          // Do not mask the original failure if PID cleanup fails
+        }
+      }
+      if (dataDir !== undefined) {
+        await releaseJobSlotBestEffort(dataDir, jobId);
+      }
+      process.exitCode = 1;
+      setTimeout(() => process.exit(1), 5000).unref();
+      process.exit(1);
+      return;
+    }
     const normalized = normalizeError(err);
     console.error(normalized.message);
     if (workDir !== undefined) {
@@ -1171,6 +1220,8 @@ export async function completeJob(
   // Create complete/ directory if needed
   await mkdir(config.completeDir, { recursive: true });
 
+  await flushJobStatus(config.workDir);
+
   // Move job directory from current/ to complete/
   await rename(config.workDir, destDir);
 

package/src/core/status-writer.ts

@@ -1,5 +1,5 @@
-import { rename, unlink, mkdir } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { rename, unlink, mkdir, open } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { createJobLogger } from "./logger";
 import type { NormalizedError } from "./pipeline-runner";
 
@@ -71,6 +71,19 @@ export interface UploadArtifact {
   content: string;
 }
 
+export class StatusCorruptError extends Error {
+  readonly statusPath: string;
+  constructor(statusPath: string, options?: { cause?: unknown }) {
+    super(
+      `tasks-status.json is corrupt (unparseable) at ${statusPath}; refusing to overwrite — ` +
+      `repair the file or delete it to let a fresh status be created`,
+      options,
+    );
+    this.name = "StatusCorruptError";
+    this.statusPath = statusPath;
+  }
+}
+
 export const STATUS_FILENAME = "tasks-status.json";
 
 function clearResetTaskMetadata(task: TaskEntry): void {
@@ -150,13 +163,40 @@ export async function atomicWrite(filePath: string, content: string): Promise<vo
   const tmp = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
   try {
     await Bun.write(tmp, content);
+    const fh = await open(tmp, "r+");
+    try { await fh.sync(); } finally { await fh.close(); }
     await rename(tmp, filePath);
+    const dirFh = await open(dirname(filePath), "r");
+    try { await dirFh.sync(); } finally { await dirFh.close(); }
   } catch (err) {
     await unlink(tmp).catch(() => {});
     throw err;
   }
 }
 
+async function readSnapshotForUpdate(statusPath: string, jobDir: string): Promise<unknown> {
+  try {
+    const text = await Bun.file(statusPath).text();
+    return JSON.parse(text);
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return createDefaultStatus(jobDir);
+    if (err instanceof SyntaxError) throw new StatusCorruptError(statusPath, { cause: err });
+    throw err;
+  }
+}
+
+export async function flushJobStatus(jobDir: string): Promise<void> {
+  const pending = writeQueues.get(jobDir);
+  if (pending) {
+    try {
+      await pending;
+    } catch {
+      // drain only
+    }
+  }
+}
+
 const writeQueues = new Map<string, Promise<StatusSnapshot>>();
 
 export async function readJobStatus(jobDir: string): Promise<StatusSnapshot | null> {
@@ -195,18 +235,7 @@ export function updateTaskStatus(jobDir: string, taskId: string, taskUpdateFn: T
   return next;
 
   async function runTaskWrite(): Promise<StatusSnapshot> {
-    let raw: unknown;
-    try {
-      const text = await Bun.file(statusPath).text();
-      raw = JSON.parse(text);
-    } catch (err: unknown) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === "ENOENT" || err instanceof SyntaxError) {
-        raw = createDefaultStatus(jobDir);
-      } else {
-        throw err;
-      }
-    }
+    const raw = await readSnapshotForUpdate(statusPath, jobDir);
 
     const snapshot = validateStatusSnapshot(raw, jobDir);
 
@@ -361,18 +390,7 @@ export function writeJobStatus(jobDir: string, updateFn: StatusUpdateFn): Promis
   return next;
 
   async function runWrite(): Promise<StatusSnapshot> {
-    let raw: unknown;
-    try {
-      const text = await Bun.file(statusPath).text();
-      raw = JSON.parse(text);
-    } catch (err: unknown) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === "ENOENT" || err instanceof SyntaxError) {
-        raw = createDefaultStatus(jobDir);
-      } else {
-        throw err;
-      }
-    }
+    const raw = await readSnapshotForUpdate(statusPath, jobDir);
 
     let snapshot = validateStatusSnapshot(raw, jobDir);
 

package/src/core/task-runner.ts

@@ -19,7 +19,7 @@ import { TaskState } from "../config/statuses";
 import { LogEvent, LogFileExtension } from "../config/log-events";
 // LLMClient: src/llm/index.ts exports HighLevelLLM (no LLMClient type exists there).
 import type { HighLevelLLM } from "../providers/types";
-import type { TaskAgentOptions, TaskAgentRunner } from "./agent-types";
+import type { AgentStepResult, TaskAgentOptions, TaskAgentRunner } from "./agent-types";
 
 /** Opaque alias — the LLM client passed into execution contexts. */
 export type LLMClient = HighLevelLLM;
@@ -254,6 +254,21 @@ export function deriveModelKeyAndTokens(metric: Record<string, unknown>): TokenU
   return [modelKey, inputTokens, outputTokens, cost];
 }
 
+function deriveAgentUsageTuple(options: TaskAgentOptions, result: AgentStepResult): TokenUsageTuple | null {
+  const costUsd =
+    typeof result.costUsd === "number" && Number.isFinite(result.costUsd)
+      ? result.costUsd
+      : undefined;
+  if (!result.usage && costUsd === undefined) return null;
+
+  return [
+    `${options.harness}:${options.model ?? "default"}`,
+    result.usage?.inputTokens ?? 0,
+    result.usage?.outputTokens ?? 0,
+    costUsd ?? 0,
+  ];
+}
+
 // ─── Safe clone ─────────────────────────────────────────────────────────────
 
 function safeClone<T>(value: T): T {
@@ -525,8 +540,11 @@ export async function runPipeline(
     };
     llmMetrics.push(record);
 
-    // Append token usage to status file, serialized via promise queue
     const tuple = deriveModelKeyAndTokens(metric);
+    enqueueTokenUsage(tuple);
+  };
+
+  const enqueueTokenUsage = (tuple: TokenUsageTuple) => {
     tokenWriteQueue = tokenWriteQueue.then(async () => {
       await writeJobStatus(jobDir, (snapshot: StatusSnapshot) => {
         const tasks = snapshot.tasks;
@@ -569,10 +587,16 @@ export async function runPipeline(
   // 9b. Build the CLI-agent harness runner injected into stages. It reuses the
   // task's own `io`, so an agent reads and writes the same artifacts the task
   // sees. A caller may override it (tests/custom hosts).
-  const runAgent: TaskAgentRunner =
+  const runAgentCore: TaskAgentRunner =
     initialContext.runAgent ??
     ((options: TaskAgentOptions) =>
       executeAgent({ io, entry: { ...options, name: taskName } }));
+  const runAgent: TaskAgentRunner = async (options: TaskAgentOptions) => {
+    const result = await runAgentCore(options);
+    const tuple = deriveAgentUsageTuple(options, result);
+    if (tuple) enqueueTokenUsage(tuple);
+    return result;
+  };
 
   // 10. Build execution context
   const pipelineTasks = initialContext.pipelineTasks ?? initialContext.meta?.pipelineTasks;