@ryanfw/prompt-orchestration-pipeline 1.3.0 → 1.3.2

package/README.md

@@ -50,6 +50,7 @@ Switch models globally or per-task without rewriting your logic.
     *   **Moonshot** (Kimi)
     *   **Zhipu** (GLM-4)
     *   **Claude Code** (CLI integration)
+*   **CLI Agents**: Tasks can also drive tool-using CLI coding agents (Claude, Codex, OpenCode) via the injected `runAgent()` helper — for file-aware, multi-turn work alongside single LLM calls. See the [Task Development Guide](docs/pop-task-guide.md#agent-api).
 
 ---
 

package/docs/pop-task-guide.md

@@ -192,6 +192,50 @@ const response = await llm.deepseek.chat({
 
 ---
 
+## Agent API
+
+Available via the `runAgent` function passed to stages. It runs a CLI coding
+agent (the harness adapter) from inside a standard JavaScript task — the same
+machinery behind pipeline `agent:` entries, but callable mid-task with a prompt
+you build programmatically from upstream data.
+
+```js
+export const inference = async ({ runAgent, io, data, flags }) => {
+  const result = await runAgent({
+    harness: "claude",        // "claude" | "codex" | "opencode"
+    prompt: "Read 'context.md', then write a summary to 'summary.md'.",
+    // model?: string         // optional, passed through to the CLI
+    // io?: boolean           // default true: bridge POP read/write artifacts
+    // timeoutMs?: number     // optional wall-clock cap
+    // idleTimeoutMs?: number // optional no-output cap
+    // captureDiff?: boolean  // capture a git diff as 'agent.patch'
+  });
+
+  if (!result.ok) {
+    throw new Error(`Agent failed: ${result.error}`);
+  }
+
+  // result: { ok, finalMessage, artifactsWritten, usage?, costUsd?, sessionId? }
+  const summary = await io.readArtifact("summary.md");
+  return { output: { summary }, flags };
+};
+```
+
+By default (`io` is `true`) the agent shares the task's file I/O: it can call the
+`read_artifact` / `write_artifact` tools to read and write the same artifacts the
+task sees, and its `agent-result.md` is written automatically. Token usage and
+cost flow into the job status like any other LLM call.
+
+**`runAgent` vs `llm`**: use `llm.<provider>.chat()` for a single request/response
+LLM call; use `runAgent()` when you need a tool-using CLI agent that reads and
+writes files over multiple turns.
+
+**`runAgent` vs an `agent:` pipeline entry**: an `agent:` entry takes a static
+prompt from `pipeline.json`. `runAgent()` lets a JavaScript task compose the
+prompt from seed/stage data and post-process the result in later stages.
+
+---
+
 ## Validation API
 
 Available via `validators` object in stages that need schema validation.
@@ -320,6 +364,7 @@ Each stage receives:
 {
   io,                    // File I/O (may be null)
   llm,                   // LLM client
+  runAgent,              // Run a CLI agent harness (see Agent API)
   validators,            // { validateWithSchema }
   flags,                 // Control flags
   meta: { taskName, workDir, jobId },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
   "main": "src/ui/server/index.ts",
@@ -64,7 +64,6 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-markdown": "^10.1.0",
-    "react-mentions": "^4.4.10",
     "react-router-dom": "^7.9.4",
     "react-syntax-highlighter": "^15.6.1",
     "rehype-highlight": "^7.0.2",
@@ -72,7 +71,8 @@
     "tslib": "^2.8.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "^1.17.4",
-    "zod": "^3.25.0"
+    "zod": "^3.25.0",
+    "local-llm-cli-adapter": "github:ryan-mahoney/local-llm-cli-adapter#2ea1aa2d8e8dbe43eb845eb4730b08a02618f476"
   },
   "devDependencies": {
     "@eslint/js": "^9.37.0",

package/src/core/__tests__/agent-step.test.ts

@@ -1,15 +1,15 @@
 import { describe, it, expect, mock, beforeEach, afterEach } from "bun:test";
-import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { WriteOptions, TaskFileIO } from "../file-io.ts";
 import type { McpIoServerHandle } from "../../harness/mcp-io-server.ts";
 import type {
-  HarnessRunOptions,
-  HarnessRunResult,
+  RunResult,
+  HarnessRun,
   HarnessEvent,
-} from "../../harness/types.ts";
-import { runAgentStep } from "../agent-step.ts";
+} from "../../harness/index.ts";
+import { runAgentStep, executeAgent } from "../agent-step.ts";
 import { createTaskFileIO } from "../file-io.ts";
 
 function createFakeIO(): TaskFileIO & { calls: string[] } {
@@ -53,10 +53,11 @@ function createFakeIO(): TaskFileIO & { calls: string[] } {
 
 function createFakeMcpHandle(
   artifacts: string[] = [],
+  connection = { url: "http://127.0.0.1:9999/mcp", token: "fake-token" },
 ): McpIoServerHandle & { closeSpy: ReturnType<typeof mock> } {
   const closeSpy = mock(async () => {});
   return {
-    connection: { url: "http://127.0.0.1:9999/mcp", token: "fake-token" },
+    connection,
     artifactsWritten() {
       return [...artifacts];
     },
@@ -84,26 +85,53 @@ function makeArgs(overrides?: {
   };
 }
 
-function makeSuccessResult(overrides?: Partial<HarnessRunResult>): HarnessRunResult {
+function makeFakeHarnessRun(result: RunResult | Error): HarnessRun {
+  const resolved =
+    result instanceof Error
+      ? Promise.reject(result)
+      : Promise.resolve(result);
+  return {
+    result: resolved,
+    sessionId: Promise.resolve("sess-1"),
+    abort() {},
+  };
+}
+
+function makeSuccessResult(overrides?: Partial<RunResult>): RunResult {
   return {
     finalMessage: "task complete",
-    events: [],
     exitCode: 0,
     usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
-    costUsd: 0.12,
     sessionId: "sess-1",
     ...overrides,
   };
 }
 
-function makeDeps(result: HarnessRunResult | Error) {
-  const runHarnessTask = mock(async (_opts: HarnessRunOptions) => {
-    if (result instanceof Error) throw result;
-    return result;
+function deferred<T>(): { promise: Promise<T>; resolve: (value: T) => void; reject: (err: unknown) => void } {
+  let resolve!: (value: T) => void;
+  let reject!: (err: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
   });
+  return { promise, resolve, reject };
+}
+
+async function waitFor(predicate: () => boolean, message: string): Promise<void> {
+  const deadline = Date.now() + 1_000;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error(message);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  }
+}
+
+function makeDeps(result: RunResult | Error) {
+  const run = mock(() => makeFakeHarnessRun(result));
   const startMcpIoServer = mock(async () => createFakeMcpHandle());
   const createTaskFileIO = mock(() => createFakeIO());
-  return { runHarnessTask, startMcpIoServer, createTaskFileIO };
+  return { run, startMcpIoServer, createTaskFileIO };
 }
 
 function gitSync(args: string[], cwd: string): string {
@@ -119,13 +147,335 @@ function makeCaptureDeps(workDir: string) {
     statusPath: join(workDir, "tasks-status.json"),
   });
   return {
-    runHarnessTask: mock(async () => makeSuccessResult()),
+    run: mock(() => makeFakeHarnessRun(makeSuccessResult())),
     startMcpIoServer: mock(async () => createFakeMcpHandle()),
     createTaskFileIO: mock(() => io),
     io,
   };
 }
 
+describe("executeAgent", () => {
+  it("runs against a provided io and returns ok:true with merged artifacts", async () => {
+    const io = createFakeIO();
+    const run = mock(() => makeFakeHarnessRun(makeSuccessResult()));
+    const startMcpIoServer = mock(async () => createFakeMcpHandle(["explainer.md"]));
+
+    const result = await executeAgent(
+      { io, entry: { name: "agent-explainer", harness: "claude", prompt: "do it" } },
+      { run, startMcpIoServer },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.finalMessage).toBe("task complete");
+    expect(result.artifactsWritten).toContain("explainer.md");
+    expect(result.artifactsWritten).toContain("agent-result.md");
+    expect(io.calls).toContain("writeArtifact:agent-result.md");
+    expect(startMcpIoServer).toHaveBeenCalled();
+  });
+
+  it("returns ok:false when the harness run rejects", async () => {
+    const io = createFakeIO();
+    const run = mock(() => makeFakeHarnessRun(new Error("spawn failed")));
+    const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+    const result = await executeAgent(
+      { io, entry: { name: "agent-explainer", harness: "codex", prompt: "do it" } },
+      { run, startMcpIoServer },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe("spawn failed");
+  });
+
+  it("skips the MCP server when io is false", async () => {
+    const io = createFakeIO();
+    const run = mock(() => makeFakeHarnessRun(makeSuccessResult()));
+    const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+    await executeAgent(
+      { io, entry: { name: "a", harness: "opencode", prompt: "p", io: false } },
+      { run, startMcpIoServer },
+    );
+
+    expect(startMcpIoServer).not.toHaveBeenCalled();
+  });
+
+  it("passes adapter-native MCP servers for claude", async () => {
+    const io = createFakeIO();
+    let capturedMcpServers: unknown;
+    const run = mock((opts: { mcpServers?: unknown }) => {
+      capturedMcpServers = opts.mcpServers;
+      return makeFakeHarnessRun(makeSuccessResult());
+    });
+    const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+    await executeAgent(
+      { io, entry: { name: "a", harness: "claude", prompt: "p" } },
+      { run, startMcpIoServer },
+    );
+
+    expect(capturedMcpServers).toEqual([{
+      name: "popio",
+      url: "http://127.0.0.1:9999/mcp",
+      headers: { Authorization: "Bearer fake-token" },
+    }]);
+  });
+
+  it("bridges MCP for codex through a temporary binary wrapper", async () => {
+    const io = createFakeIO();
+    const previousPopBin = process.env.POP_CODEX_BIN;
+    const previousAdapterBin = process.env.LLM_ADAPTER_CODEX_BIN;
+    const previousRealBin = process.env.POP_REAL_CODEX_BIN;
+    const previousMcpUrlConfig = process.env.POP_MCP_URL_CONFIG;
+    const previousMcpToken = process.env.POP_MCP_TOKEN;
+    let wrapperPath = "";
+    let capturedMcpServers: unknown;
+    try {
+      process.env.POP_CODEX_BIN = "/custom/codex";
+      delete process.env.LLM_ADAPTER_CODEX_BIN;
+      delete process.env.POP_REAL_CODEX_BIN;
+      delete process.env.POP_MCP_URL_CONFIG;
+      delete process.env.POP_MCP_TOKEN;
+      const run = mock((opts: { mcpServers?: unknown; onEvent?: (event: HarnessEvent) => void }) => {
+        capturedMcpServers = opts.mcpServers;
+        wrapperPath = process.env.LLM_ADAPTER_CODEX_BIN ?? "";
+        expect(wrapperPath).toContain("codex-mcp-");
+        expect(readFileSync(wrapperPath, "utf8")).toContain("POP_MCP_URL_CONFIG");
+        expect(process.env.POP_REAL_CODEX_BIN).toBe("/custom/codex");
+        expect(process.env.POP_MCP_URL_CONFIG).toBe(
+          'mcp_servers.popio.url="http://127.0.0.1:9999/mcp"',
+        );
+        expect(process.env.POP_MCP_TOKEN).toBe("fake-token");
+        opts.onEvent?.({
+          harness: "codex",
+          seq: 0,
+          at: Date.now(),
+          raw: { type: "result", total_cost_usd: 0.42 },
+          type: "raw",
+        });
+        return makeFakeHarnessRun(makeSuccessResult());
+      });
+      const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+      const result = await executeAgent(
+        { io, entry: { name: "a", harness: "codex", prompt: "p" } },
+        { run, startMcpIoServer },
+      );
+
+      expect(capturedMcpServers).toBeUndefined();
+      expect(result.costUsd).toBe(0.42);
+      expect(process.env.LLM_ADAPTER_CODEX_BIN).toBeUndefined();
+      expect(process.env.POP_REAL_CODEX_BIN).toBeUndefined();
+      expect(process.env.POP_MCP_URL_CONFIG).toBeUndefined();
+      expect(process.env.POP_MCP_TOKEN).toBeUndefined();
+      expect(existsSync(wrapperPath)).toBe(false);
+    } finally {
+      if (previousPopBin === undefined) {
+        delete process.env.POP_CODEX_BIN;
+      } else {
+        process.env.POP_CODEX_BIN = previousPopBin;
+      }
+      if (previousAdapterBin === undefined) {
+        delete process.env.LLM_ADAPTER_CODEX_BIN;
+      } else {
+        process.env.LLM_ADAPTER_CODEX_BIN = previousAdapterBin;
+      }
+      if (previousRealBin === undefined) {
+        delete process.env.POP_REAL_CODEX_BIN;
+      } else {
+        process.env.POP_REAL_CODEX_BIN = previousRealBin;
+      }
+      if (previousMcpUrlConfig === undefined) {
+        delete process.env.POP_MCP_URL_CONFIG;
+      } else {
+        process.env.POP_MCP_URL_CONFIG = previousMcpUrlConfig;
+      }
+      if (previousMcpToken === undefined) {
+        delete process.env.POP_MCP_TOKEN;
+      } else {
+        process.env.POP_MCP_TOKEN = previousMcpToken;
+      }
+    }
+  });
+
+  it("serializes env-backed MCP compatibility for concurrent codex runs", async () => {
+    const previousPopBin = process.env.POP_CODEX_BIN;
+    const previousAdapterBin = process.env.LLM_ADAPTER_CODEX_BIN;
+    const previousRealBin = process.env.POP_REAL_CODEX_BIN;
+    const previousMcpUrlConfig = process.env.POP_MCP_URL_CONFIG;
+    const previousMcpToken = process.env.POP_MCP_TOKEN;
+    const firstRunResult = deferred<RunResult>();
+    const secondRunResult = deferred<RunResult>();
+    const observedTokens: Array<string | undefined> = [];
+    let runCount = 0;
+    let startCount = 0;
+    try {
+      process.env.POP_CODEX_BIN = "/custom/codex";
+      delete process.env.LLM_ADAPTER_CODEX_BIN;
+      delete process.env.POP_REAL_CODEX_BIN;
+      delete process.env.POP_MCP_URL_CONFIG;
+      delete process.env.POP_MCP_TOKEN;
+      const run = mock(() => {
+        runCount += 1;
+        observedTokens.push(process.env.POP_MCP_TOKEN);
+        return {
+          result: runCount === 1 ? firstRunResult.promise : secondRunResult.promise,
+          sessionId: Promise.resolve(`sess-${runCount}`),
+          abort() {},
+        };
+      });
+      const startMcpIoServer = mock(async () => {
+        startCount += 1;
+        return createFakeMcpHandle([], {
+          url: `http://127.0.0.1:999${startCount}/mcp`,
+          token: `token-${startCount}`,
+        });
+      });
+
+      const first = executeAgent(
+        { io: createFakeIO(), entry: { name: "a", harness: "codex", prompt: "p" } },
+        { run, startMcpIoServer },
+      );
+      const second = executeAgent(
+        { io: createFakeIO(), entry: { name: "b", harness: "codex", prompt: "p" } },
+        { run, startMcpIoServer },
+      );
+
+      await waitFor(() => runCount === 1, "first codex run did not start");
+      expect(runCount).toBe(1);
+      expect(observedTokens).toHaveLength(1);
+      const firstObservedToken = observedTokens[0];
+      if (firstObservedToken === undefined) {
+        throw new Error("first codex run did not receive an MCP token");
+      }
+      expect(["token-1", "token-2"]).toContain(firstObservedToken);
+
+      firstRunResult.resolve(makeSuccessResult({ finalMessage: "run-1" }));
+      await waitFor(() => runCount === 2, "second codex run did not start");
+      expect(runCount).toBe(2);
+      expect(new Set(observedTokens)).toEqual(new Set(["token-1", "token-2"]));
+
+      secondRunResult.resolve(makeSuccessResult({ finalMessage: "run-2" }));
+      const results = await Promise.all([first, second]);
+      expect(new Set(results.map((r) => r.finalMessage))).toEqual(new Set(["run-1", "run-2"]));
+      expect(process.env.POP_MCP_TOKEN).toBeUndefined();
+      expect(process.env.POP_MCP_URL_CONFIG).toBeUndefined();
+    } finally {
+      firstRunResult.resolve(makeSuccessResult());
+      secondRunResult.resolve(makeSuccessResult());
+      if (previousPopBin === undefined) {
+        delete process.env.POP_CODEX_BIN;
+      } else {
+        process.env.POP_CODEX_BIN = previousPopBin;
+      }
+      if (previousAdapterBin === undefined) {
+        delete process.env.LLM_ADAPTER_CODEX_BIN;
+      } else {
+        process.env.LLM_ADAPTER_CODEX_BIN = previousAdapterBin;
+      }
+      if (previousRealBin === undefined) {
+        delete process.env.POP_REAL_CODEX_BIN;
+      } else {
+        process.env.POP_REAL_CODEX_BIN = previousRealBin;
+      }
+      if (previousMcpUrlConfig === undefined) {
+        delete process.env.POP_MCP_URL_CONFIG;
+      } else {
+        process.env.POP_MCP_URL_CONFIG = previousMcpUrlConfig;
+      }
+      if (previousMcpToken === undefined) {
+        delete process.env.POP_MCP_TOKEN;
+      } else {
+        process.env.POP_MCP_TOKEN = previousMcpToken;
+      }
+    }
+  });
+
+  it("bridges MCP for opencode through OPENCODE_CONFIG_DIR and extracts raw cost", async () => {
+    const io = createFakeIO();
+    const previousConfigDir = process.env.OPENCODE_CONFIG_DIR;
+    const sourceConfigDir = mkdtempSync(join(tmpdir(), "opencode-existing-"));
+    let configDir = "";
+    let capturedMcpServers: unknown;
+    try {
+      writeFileSync(
+        join(sourceConfigDir, "opencode.json"),
+        JSON.stringify({
+          provider: "kept",
+          mcp: {
+            existing: { type: "local", command: ["tool"] },
+          },
+        }),
+      );
+      process.env.OPENCODE_CONFIG_DIR = sourceConfigDir;
+      const run = mock((opts: { mcpServers?: unknown; onEvent?: (event: HarnessEvent) => void }) => {
+        capturedMcpServers = opts.mcpServers;
+        configDir = process.env.OPENCODE_CONFIG_DIR ?? "";
+        const config = JSON.parse(readFileSync(join(configDir, "opencode.json"), "utf8")) as Record<string, unknown>;
+        expect(config).toMatchObject({
+          provider: "kept",
+          mcp: {
+            existing: { type: "local", command: ["tool"] },
+            popio: {
+              type: "remote",
+              url: "http://127.0.0.1:9999/mcp",
+              headers: { Authorization: "Bearer fake-token" },
+              enabled: true,
+            },
+          },
+        });
+        opts.onEvent?.({
+          harness: "opencode",
+          seq: 0,
+          at: Date.now(),
+          raw: { type: "result", info: { costUsd: 0.13 } },
+          type: "raw",
+        });
+        return makeFakeHarnessRun(makeSuccessResult());
+      });
+      const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+      const result = await executeAgent(
+        { io, entry: { name: "a", harness: "opencode", prompt: "p" } },
+        { run, startMcpIoServer },
+      );
+
+      expect(capturedMcpServers).toBeUndefined();
+      expect(result.costUsd).toBe(0.13);
+      expect(process.env.OPENCODE_CONFIG_DIR).toBe(sourceConfigDir);
+      expect(existsSync(configDir)).toBe(false);
+    } finally {
+      rmSync(sourceConfigDir, { recursive: true, force: true });
+      if (previousConfigDir === undefined) {
+        delete process.env.OPENCODE_CONFIG_DIR;
+      } else {
+        process.env.OPENCODE_CONFIG_DIR = previousConfigDir;
+      }
+    }
+  });
+
+  it("preserves usage and cost when artifact writes fail after the harness run", async () => {
+    const io = createFakeIO();
+    io.writeArtifact = async () => {
+      throw new Error("disk full");
+    };
+    const run = mock(() => makeFakeHarnessRun(makeSuccessResult({ costUsd: 0.21 })));
+    const startMcpIoServer = mock(async () => createFakeMcpHandle(["agent-output.md"]));
+
+    const result = await executeAgent(
+      { io, entry: { name: "a", harness: "claude", prompt: "p" } },
+      { run, startMcpIoServer },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe("disk full");
+    expect(result.usage).toEqual({ inputTokens: 100, outputTokens: 50, totalTokens: 150 });
+    expect(result.costUsd).toBe(0.21);
+    expect(result.sessionId).toBe("sess-1");
+    expect(result.artifactsWritten).toContain("agent-output.md");
+  });
+});
+
 describe("runAgentStep", () => {
   it("success writes event log and agent-result.md and returns ok:true with usage/cost", async () => {
     const deps = makeDeps(makeSuccessResult());
@@ -135,7 +485,7 @@ describe("runAgentStep", () => {
     expect(result.ok).toBe(true);
     expect(result.finalMessage).toBe("task complete");
     expect(result.usage).toEqual({ inputTokens: 100, outputTokens: 50, totalTokens: 150 });
-    expect(result.costUsd).toBe(0.12);
+    expect(result.costUsd).toBeUndefined();
     expect(result.sessionId).toBe("sess-1");
     expect(result.artifactsWritten).toContain("agent-result.md");
     expect(deps.startMcpIoServer).toHaveBeenCalled();
@@ -150,18 +500,18 @@ describe("runAgentStep", () => {
     });
 
     const events: HarnessEvent[] = [
-      { type: "text", raw: { text: "hello" }, text: "hello" },
-      { type: "result", raw: { message: "done" } },
+      { harness: "claude", seq: 0, at: Date.now(), raw: { text: "hello" }, type: "assistant_message", text: "hello" },
+      { harness: "claude", seq: 1, at: Date.now(), raw: { message: "done" }, type: "run_completed", result: makeSuccessResult() },
     ];
-    const runHarnessTask = mock(async (opts: HarnessRunOptions) => {
+    const run = mock((opts: { onEvent?: (event: HarnessEvent) => void }) => {
       for (const event of events) {
         opts.onEvent?.(event);
       }
-      return makeSuccessResult();
+      return makeFakeHarnessRun(makeSuccessResult());
     });
     const startMcpIoServer = mock(async () => createFakeMcpHandle());
 
-    await runAgentStep(makeArgs(), { runHarnessTask, startMcpIoServer, createTaskFileIO });
+    await runAgentStep(makeArgs(), { run, startMcpIoServer, createTaskFileIO });
 
     const logCalls = capturedIO!.calls.filter((c) => c.startsWith("writeLog:"));
     expect(logCalls).toHaveLength(2);
@@ -177,15 +527,15 @@ describe("runAgentStep", () => {
     });
 
     let capturedPrompt: string | undefined;
-    const runHarnessTask = mock(async (opts: HarnessRunOptions) => {
+    const run = mock((opts: { prompt: string }) => {
       capturedPrompt = opts.prompt;
-      return makeSuccessResult();
+      return makeFakeHarnessRun(makeSuccessResult());
     });
     const startMcpIoServer = mock(async () => createFakeMcpHandle());
 
     const result = await runAgentStep(
       makeArgs({ entry: { prompt: undefined, promptFrom: "my-prompt.md" } }),
-      { runHarnessTask, startMcpIoServer, createTaskFileIO },
+      { run, startMcpIoServer, createTaskFileIO },
     );
 
     expect(result.ok).toBe(true);
@@ -197,9 +547,7 @@ describe("runAgentStep", () => {
     const mcpHandle = createFakeMcpHandle();
     const createTaskFileIO = mock(() => createFakeIO());
     const deps = {
-      runHarnessTask: mock(async () => {
-        throw new Error("boom");
-      }),
+      run: mock(() => makeFakeHarnessRun(new Error("boom"))),
       startMcpIoServer: mock(async () => mcpHandle),
       createTaskFileIO,
     };
@@ -216,7 +564,7 @@ describe("runAgentStep", () => {
     const mcpHandle = createFakeMcpHandle();
     const createTaskFileIO = mock(() => createFakeIO());
     const deps = {
-      runHarnessTask: mock(async () => makeSuccessResult()),
+      run: mock(() => makeFakeHarnessRun(makeSuccessResult())),
       startMcpIoServer: mock(async () => mcpHandle),
       createTaskFileIO,
     };
@@ -229,9 +577,7 @@ describe("runAgentStep", () => {
     const mcpHandle = createFakeMcpHandle();
     const createTaskFileIO = mock(() => createFakeIO());
     const deps = {
-      runHarnessTask: mock(async () => {
-        throw new Error("fail");
-      }),
+      run: mock(() => makeFakeHarnessRun(new Error("fail"))),
       startMcpIoServer: mock(async () => mcpHandle),
       createTaskFileIO,
     };
@@ -243,22 +589,43 @@ describe("runAgentStep", () => {
   it("MCP server is closed on timeout path", async () => {
     const mcpHandle = createFakeMcpHandle();
     const createTaskFileIO = mock(() => createFakeIO());
+    let capturedTimeoutMs: number | undefined;
+    let capturedIdleTimeoutMs: number | undefined;
     const deps = {
-      runHarnessTask: mock(async () => {
-        throw new Error('Harness "claude" timed out after 100ms');
+      run: mock((opts) => {
+        capturedTimeoutMs = opts.timeoutMs;
+        capturedIdleTimeoutMs = opts.idleTimeoutMs;
+        return makeFakeHarnessRun(new Error('Harness "claude" timed out after 100ms'));
       }),
       startMcpIoServer: mock(async () => mcpHandle),
       createTaskFileIO,
     };
 
     await runAgentStep(makeArgs({ entry: { timeoutMs: 100 } }), deps);
+    expect(capturedTimeoutMs).toBe(100);
+    expect(capturedIdleTimeoutMs).toBeUndefined();
     expect(mcpHandle.closeSpy).toHaveBeenCalled();
   });
 
+  it("passes an explicit idle timeout through to the adapter", async () => {
+    let capturedIdleTimeoutMs: number | undefined;
+    const deps = {
+      run: mock((opts) => {
+        capturedIdleTimeoutMs = opts.idleTimeoutMs;
+        return makeFakeHarnessRun(makeSuccessResult());
+      }),
+      startMcpIoServer: mock(async () => createFakeMcpHandle()),
+      createTaskFileIO: mock(() => createFakeIO()),
+    };
+
+    await runAgentStep(makeArgs({ entry: { idleTimeoutMs: 250 } }), deps);
+    expect(capturedIdleTimeoutMs).toBe(250);
+  });
+
   it("does not start MCP server when io is false", async () => {
     const createTaskFileIO = mock(() => createFakeIO());
     const deps = {
-      runHarnessTask: mock(async () => makeSuccessResult()),
+      run: mock(() => makeFakeHarnessRun(makeSuccessResult())),
       startMcpIoServer: mock(async () => createFakeMcpHandle()),
       createTaskFileIO,
     };
@@ -284,7 +651,7 @@ describe("runAgentStep", () => {
     const mcpHandle = createFakeMcpHandle(["custom-artifact.md", "agent-result.md"]);
     const createTaskFileIO = mock(() => createFakeIO());
     const deps = {
-      runHarnessTask: mock(async () => makeSuccessResult()),
+      run: mock(() => makeFakeHarnessRun(makeSuccessResult())),
       startMcpIoServer: mock(async () => mcpHandle),
       createTaskFileIO,
     };