@workflow-manager/runner 0.4.0 → 0.5.0

package/README.md

@@ -5,7 +5,7 @@
 The core ideas:
 
 - **Workflow definitions.** A workflow is a list of steps with stable keys, objectives, and `dependsOn` edges (the engine topologically orders them). Each step is one of three kinds: `task` (delegated to an agent), `approval` (a human checkpoint), or `system`. Steps can carry retry policies, timeouts, and validation rules (`human`, `external`, or `none`).
-- **Agent adapters.** Each task step picks an adapter that does the actual work: `pi-agent` (the default — drives the `pi` coding agent CLI with a built prompt plus `input.json`/`output.json` envelopes), `claude-code` (pipes a built prompt into the `claude` CLI), `opencode`, `codex` (not yet implemented, mock-routed), and `mock` (deterministic simulator for tests/authoring). Steps can declare skills, MCP endpoints, system prompts, and a model under `taskSpec.init`, which get injected into the agent's prompt or input file.
+- **Agent adapters.** Each task step picks an adapter that does the actual work: `pi-agent` (the default — drives the `pi` coding agent CLI with a built prompt plus `input.json`/`output.json` envelopes), `acp` (connects to any [Agent Client Protocol](https://agentclientprotocol.com) agent over JSON-RPC/stdio), and `mock` (deterministic simulator for tests/authoring). The `claude-code`, `opencode`, and `codex` keys are ACP presets — their original bespoke executors are deprecated behind `taskSpec.payload.legacyExecutor`. Steps can declare skills, MCP endpoints, system prompts, and a model under `taskSpec.init`, which get injected into the agent's prompt, input file, or ACP session.
 - **The envelope protocol.** Every step execution returns a structured result: an execution status (`SUCCESS`, `FAILED`, `QA_REJECTED`, `YIELD_EXTERNAL`) plus a QA routing action (`PROCEED`, `RETRY_CURRENT`, `ROLLBACK_PREVIOUS`, `RESTART_ALL`). That's what lets the engine retry a step, roll back to the previous one, or restart the whole run based on what the agent reported.
 - **Human-in-the-loop control.** While a run is active, wfm starts a local HTTP attach API (token-protected, with SSE event streaming), so a waiting step can be resolved either in the terminal prompt or from another shell with `wfm approve` / `wfm resume` / `wfm cancel`.
 - **A registry.** `wfm publish` / `pull` / `search` / `auth` talk to a Supabase-backed remote registry (the `apps/remote-registry` web app in this repo) for sharing workflows, with skills bundled and SHA-256 verified. Runs also emit opt-in telemetry there.

package/dist/acpExecutor.d.ts

@@ -0,0 +1,16 @@
+import type { InputEnvelope, OutputEnvelope, StepDefinition, StepExecutionHooks, WorkflowDefinition } from "./types.js";
+interface ResolvedAcpCommand {
+    command: string;
+    args: string[];
+}
+export declare function normalizeTimeout(value: unknown, fallbackMs?: number): number;
+/**
+ * Resolves which ACP agent command to launch for a step. Precedence:
+ * payload.acpCommand → WFM_ACP_COMMAND env → preset for payload.acpAgent → preset
+ * for the adapter key (claude-code / opencode). Returns null when nothing resolves
+ * (e.g. bare `acp` or `codex` without configuration), which keeps the step on mock.
+ */
+export declare function resolveAcpCommand(step: StepDefinition, env: NodeJS.ProcessEnv): ResolvedAcpCommand | null;
+export declare function shouldUseRealAcp(step: StepDefinition): boolean;
+export declare function executeAcpStep(step: StepDefinition, input: InputEnvelope, attempt: number, workflow?: WorkflowDefinition, workflowFilePath?: string, hooks?: StepExecutionHooks): Promise<OutputEnvelope>;
+export {};

package/dist/acpExecutor.js

@@ -0,0 +1,311 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ClientSideConnection, PROTOCOL_VERSION, ndJsonStream, } from "@zed-industries/agent-client-protocol";
+import { resolveTaskAdapter } from "./adapters.js";
+import { resolveSkill } from "./skillResolver.js";
+// Best-effort presets so claude-code / opencode / a named agent route through ACP
+// without explicit commands. All are overridable via payload.acpCommand or WFM_ACP_COMMAND.
+const ACP_COMMAND_PRESETS = {
+    "claude-code": { command: "claude-code-acp", args: [] },
+    opencode: { command: "opencode", args: ["acp"] },
+    gemini: { command: "gemini", args: ["--experimental-acp"] },
+};
+const READ_ONLY_TOOL_KINDS = new Set(["read", "search", "fetch", "think"]);
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+// node:stream's Writable.toWeb / Readable.toWeb are not implemented in Bun, so we
+// bridge the child process stdio to Web streams ourselves (portable across runtimes).
+function writableToWeb(writable) {
+    return new WritableStream({
+        write(chunk) {
+            return new Promise((resolve, reject) => {
+                writable.write(chunk, (err) => (err ? reject(err) : resolve()));
+            });
+        },
+        close() {
+            return new Promise((resolve) => writable.end(() => resolve()));
+        },
+        abort() {
+            writable.destroy();
+        },
+    });
+}
+function readableToWeb(readable) {
+    return new ReadableStream({
+        start(controller) {
+            readable.on("data", (chunk) => {
+                controller.enqueue(typeof chunk === "string" ? new TextEncoder().encode(chunk) : Uint8Array.from(chunk));
+            });
+            readable.on("end", () => {
+                try {
+                    controller.close();
+                }
+                catch {
+                    // already closed
+                }
+            });
+            readable.on("error", (err) => controller.error(err));
+        },
+        cancel() {
+            readable.destroy();
+        },
+    });
+}
+export function normalizeTimeout(value, fallbackMs = 600000) {
+    const timeout = Number(value ?? fallbackMs);
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        return fallbackMs;
+    return Math.floor(timeout);
+}
+function stringArg(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/**
+ * Resolves which ACP agent command to launch for a step. Precedence:
+ * payload.acpCommand → WFM_ACP_COMMAND env → preset for payload.acpAgent → preset
+ * for the adapter key (claude-code / opencode). Returns null when nothing resolves
+ * (e.g. bare `acp` or `codex` without configuration), which keeps the step on mock.
+ */
+export function resolveAcpCommand(step, env) {
+    const payload = asRecord(step.taskSpec?.payload);
+    const payloadArgs = Array.isArray(payload.acpArgs) ? payload.acpArgs.map((arg) => String(arg)) : [];
+    const explicit = stringArg(payload.acpCommand) ?? stringArg(env.WFM_ACP_COMMAND);
+    if (explicit) {
+        return { command: explicit, args: payloadArgs };
+    }
+    const presetKey = stringArg(payload.acpAgent) ?? resolveTaskAdapter(step.taskSpec?.adapterKey);
+    const preset = ACP_COMMAND_PRESETS[presetKey];
+    if (preset) {
+        return { command: preset.command, args: payloadArgs.length > 0 ? payloadArgs : [...preset.args] };
+    }
+    return null;
+}
+export function shouldUseRealAcp(step) {
+    const payload = asRecord(step.taskSpec?.payload);
+    return payload.useRealAdapter === true && resolveAcpCommand(step, process.env) !== null;
+}
+function permissionPolicy(step) {
+    const value = asRecord(step.taskSpec?.payload).acpPermissions;
+    return value === "deny" || value === "reads-only" ? value : "allow";
+}
+function decidePermission(req, policy) {
+    const allow = req.options.find((option) => option.kind === "allow_once") ??
+        req.options.find((option) => option.kind === "allow_always");
+    const reject = req.options.find((option) => option.kind === "reject_once") ??
+        req.options.find((option) => option.kind === "reject_always");
+    let chooseAllow;
+    if (policy === "allow") {
+        chooseAllow = true;
+    }
+    else if (policy === "deny") {
+        chooseAllow = false;
+    }
+    else {
+        const kind = req.toolCall.kind ?? undefined;
+        chooseAllow = kind ? READ_ONLY_TOOL_KINDS.has(kind) : false;
+    }
+    const chosen = chooseAllow ? (allow ?? req.options[0]) : reject;
+    if (!chosen) {
+        return { outcome: { outcome: "cancelled" } };
+    }
+    return { outcome: { outcome: "selected", optionId: chosen.optionId } };
+}
+function buildMcpServers(endpoints) {
+    const servers = [];
+    const skipped = [];
+    for (const endpoint of endpoints) {
+        if (/^https?:\/\//i.test(endpoint)) {
+            servers.push({ type: "http", name: endpoint, url: endpoint, headers: [] });
+        }
+        else {
+            skipped.push(endpoint);
+        }
+    }
+    return { servers, skipped };
+}
+function composePrompt(step, input, workflow, workflowFilePath) {
+    const payload = asRecord(step.taskSpec?.payload);
+    if (typeof payload.prompt === "string" && payload.prompt.trim()) {
+        return payload.prompt;
+    }
+    const parts = [];
+    const systemPrompts = input.priming_configuration.system_prompts;
+    if (systemPrompts.length > 0) {
+        parts.push(systemPrompts.join("\n"));
+    }
+    const skills = input.priming_configuration.required_skills;
+    if (skills.length > 0) {
+        const unresolved = [];
+        for (const name of skills) {
+            const resolved = workflow && workflowFilePath ? resolveSkill(name, workflow, workflowFilePath) : null;
+            if (resolved) {
+                parts.push(resolved.content);
+            }
+            else {
+                unresolved.push(name);
+            }
+        }
+        if (unresolved.length > 0) {
+            parts.push(`Apply the following skills: ${unresolved.join(", ")}`);
+        }
+    }
+    const globalState = input.global_context.global_state;
+    const inputLines = Object.entries(globalState)
+        .filter(([, value]) => typeof value === "string" || typeof value === "number")
+        .map(([key, value]) => `${key}: ${String(value).replace(/[\n\r]/g, " ")}`);
+    if (inputLines.length > 0) {
+        parts.push(`Input:\n${inputLines.join("\n")}`);
+    }
+    parts.push(input.step_context.step_objective);
+    const previous = input.step_context.previous_output;
+    if (Object.keys(previous).length > 0) {
+        parts.push(`Previous step output:\n${JSON.stringify(previous, null, 2)}`);
+    }
+    const context = input.priming_configuration.context;
+    if (typeof context === "string" && context.trim()) {
+        parts.push(`Context:\n${context}`);
+    }
+    else if (context && typeof context === "object") {
+        const serialized = JSON.stringify(context, null, 2);
+        if (serialized !== "{}") {
+            parts.push(`Context:\n${serialized}`);
+        }
+    }
+    return parts.join("\n\n");
+}
+function mapStopReason(stopReason) {
+    switch (stopReason) {
+        case "end_turn":
+            return { status: "SUCCESS", action: "PROCEED", reason: "" };
+        case "refusal":
+            return { status: "QA_REJECTED", action: "RETRY_CURRENT", reason: "agent refused the turn" };
+        case "max_tokens":
+            return { status: "FAILED", action: "RETRY_CURRENT", reason: "agent stopped at max tokens" };
+        case "max_turn_requests":
+            return { status: "FAILED", action: "RETRY_CURRENT", reason: "agent stopped at max turn requests" };
+        case "cancelled":
+            return { status: "FAILED", action: "PROCEED", reason: "turn cancelled" };
+        default:
+            return { status: "FAILED", action: "PROCEED", reason: `unknown stop reason: ${stopReason}` };
+    }
+}
+export function executeAcpStep(step, input, attempt, workflow, workflowFilePath, hooks) {
+    const startedAt = Date.now();
+    const adapter = resolveTaskAdapter(step.taskSpec?.adapterKey);
+    const payload = asRecord(step.taskSpec?.payload);
+    const timeoutMs = normalizeTimeout(payload.timeoutMs);
+    const resolved = resolveAcpCommand(step, process.env);
+    const makeResult = (status, reason, extra = {}, action = "PROCEED") => ({
+        step_id: step.key,
+        execution_status: status,
+        qa_routing: { action, feedback_reason: reason },
+        mutated_payload: {
+            stepKey: step.key,
+            attempt,
+            adapter,
+            command: resolved?.command,
+            args: resolved?.args,
+            ...extra,
+        },
+        metadata: {
+            execution_time_ms: Date.now() - startedAt,
+            external_intervention_required: false,
+        },
+    });
+    if (!resolved) {
+        return Promise.resolve(makeResult("FAILED", "no ACP agent command could be resolved for this step"));
+    }
+    const cwd = stringArg(payload.cwd) ?? (workflowFilePath ? path.dirname(path.resolve(workflowFilePath)) : process.cwd());
+    const policy = permissionPolicy(step);
+    const { servers: mcpServers, skipped } = buildMcpServers(input.priming_configuration.mcp_endpoints);
+    if (skipped.length > 0) {
+        hooks?.onStderr?.(`[acp] ignoring non-http MCP endpoints (need structured config): ${skipped.join(", ")}\n`);
+    }
+    let child;
+    try {
+        child = spawn(resolved.command, resolved.args, { stdio: ["pipe", "pipe", "pipe"], cwd, env: process.env });
+    }
+    catch (err) {
+        return Promise.resolve(makeResult("FAILED", `failed to spawn ${resolved.command}: ${err.message}`));
+    }
+    hooks?.onStarted?.({ command: resolved.command, args: resolved.args, cwd, timeoutMs });
+    child.stderr?.setEncoding("utf-8");
+    child.stderr?.on("data", (chunk) => hooks?.onStderr?.(chunk));
+    // A ChildProcess "error" (e.g. ENOENT for a missing agent binary) is emitted
+    // asynchronously and would crash the process if unhandled.
+    const childError = new Promise((_resolve, reject) => {
+        child.on("error", (err) => reject(new Error(`agent process error: ${err.message}`)));
+    });
+    let agentText = "";
+    let sessionId;
+    let timer;
+    const client = {
+        async sessionUpdate(params) {
+            const update = params.update;
+            if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text") {
+                agentText += update.content.text;
+                hooks?.onStdout?.(update.content.text);
+            }
+            else if (update.sessionUpdate === "tool_call") {
+                hooks?.onStdout?.(`\n[acp tool] ${update.title}\n`);
+            }
+        },
+        async requestPermission(params) {
+            return decidePermission(params, policy);
+        },
+        async readTextFile(params) {
+            return { content: fs.readFileSync(params.path, "utf-8") };
+        },
+        async writeTextFile(params) {
+            fs.mkdirSync(path.dirname(params.path), { recursive: true });
+            fs.writeFileSync(params.path, params.content, "utf-8");
+            return {};
+        },
+    };
+    let conn;
+    try {
+        const stream = ndJsonStream(writableToWeb(child.stdin), readableToWeb(child.stdout));
+        conn = new ClientSideConnection(() => client, stream);
+    }
+    catch (err) {
+        child.kill("SIGKILL");
+        return Promise.resolve(makeResult("FAILED", `failed to open ACP connection: ${err.message}`));
+    }
+    const runTurn = async () => {
+        await conn.initialize({
+            protocolVersion: PROTOCOL_VERSION,
+            clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: false },
+        });
+        const authMethod = stringArg(payload.acpAuthMethod) ?? stringArg(process.env.WFM_ACP_AUTH_METHOD);
+        if (authMethod) {
+            await conn.authenticate({ methodId: authMethod });
+        }
+        const session = await conn.newSession({ cwd, mcpServers });
+        sessionId = session.sessionId;
+        const prompt = [{ type: "text", text: composePrompt(step, input, workflow, workflowFilePath) }];
+        const response = await conn.prompt({ sessionId: session.sessionId, prompt });
+        const mapped = mapStopReason(response.stopReason);
+        return makeResult(mapped.status, mapped.reason, { stopReason: response.stopReason, output: agentText.trim() }, mapped.action);
+    };
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            if (sessionId) {
+                conn.cancel({ sessionId }).catch(() => undefined);
+            }
+            resolve(makeResult("FAILED", `timed out after ${timeoutMs}ms`, { stopReason: "timeout", output: agentText.trim() }));
+        }, timeoutMs);
+    });
+    return Promise.race([runTurn(), timeout, childError])
+        .catch((err) => makeResult("FAILED", `ACP turn failed: ${err.message}`, { output: agentText.trim() }))
+        .then((result) => {
+        hooks?.onFinished?.({ executionStatus: result.execution_status });
+        return result;
+    })
+        .finally(() => {
+        if (timer)
+            clearTimeout(timer);
+        child.kill("SIGTERM");
+    });
+}

package/dist/adapters.js

@@ -5,6 +5,7 @@ export const SUPPORTED_ADAPTERS = [
     "opencode",
     "codex",
     "claude-code",
+    "acp",
 ];
 export function resolveTaskAdapter(adapter) {
     return adapter ?? DEFAULT_TASK_ADAPTER;

package/dist/engine.js

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
+import { executeAcpStep, shouldUseRealAcp } from "./acpExecutor.js";
 import { resolveTaskAdapter } from "./adapters.js";
 import { EventLog } from "./events.js";
 import { executeClaudeCodeStep, shouldUseRealClaudeCode } from "./claudeCodeExecutor.js";
 import { executeMockStep } from "./mockExecutor.js";
 import { executeOpencodeStep, shouldUseRealOpencode } from "./opencodeExecutor.js";
 import { executePiAgentStep } from "./piAgentExecutor.js";
-import { validateRuntimeRequirements } from "./runtimePreflight.js";
+import { adapterMockFallbackReason, validateRuntimeRequirements } from "./runtimePreflight.js";
 function nodeType(step) {
     if (step.kind === "approval")
         return "HUMAN";
@@ -296,12 +297,25 @@ async function executeStep(step, input, attempt, workflow, workflowFilePath, hoo
     if (adapterKey === "pi-agent") {
         return executePiAgentStep(step, input, attempt, workflow, workflowFilePath, hooks);
     }
-    if (adapterKey === "opencode" && shouldUseRealOpencode(step)) {
+    // Legacy escape hatch: the bespoke claude-code / opencode subprocess executors are
+    // deprecated in favor of ACP, but stay reachable via payload.legacyExecutor so existing
+    // real-integration users are not stranded.
+    const legacyExecutor = step.taskSpec?.payload?.legacyExecutor === true;
+    if (legacyExecutor && adapterKey === "opencode" && shouldUseRealOpencode(step)) {
         return executeOpencodeStep(step, input, attempt, hooks);
     }
-    if (adapterKey === "claude-code" && shouldUseRealClaudeCode(step)) {
+    if (legacyExecutor && adapterKey === "claude-code" && shouldUseRealClaudeCode(step)) {
         return executeClaudeCodeStep(step, input, attempt, workflow, workflowFilePath, hooks);
     }
+    // All non-pi agents run through ACP.
+    const acpRoutable = adapterKey === "acp" || adapterKey === "claude-code" || adapterKey === "opencode" || adapterKey === "codex";
+    if (acpRoutable && shouldUseRealAcp(step)) {
+        return executeAcpStep(step, input, attempt, workflow, workflowFilePath, hooks);
+    }
+    const fallbackReason = adapterMockFallbackReason(step);
+    if (fallbackReason) {
+        hooks?.onStderr?.(`[wfm] ${step.key}: ${fallbackReason}\n`);
+    }
     return executeMockStep(step, input, attempt, hooks);
 }
 export async function runWorkflow(definition, options) {

package/dist/index.js

@@ -14,7 +14,7 @@ import { MAN_PAGE_SOURCE } from "./manPage.js";
 import { promptForApprovalDecision, runWorkflow } from "./engine.js";
 import { cmdAuth, cmdPublish, cmdPull, cmdRemoteInfo, cmdSearch } from "./remote/commands.js";
 import { emitRunTelemetryBestEffort } from "./remote/telemetry.js";
-import { adapterImplementationStatuses, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
+import { adapterImplementationStatuses, adapterMockFallbackWarnings, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
 function cliDisplayName() {
     const invokedAs = path.basename(process.argv[1] ?? "");
     if (invokedAs === "workflow-manager" || invokedAs === "wfm") {
@@ -159,6 +159,18 @@ const WORKFLOW_SCAFFOLD_JSON = {
                 payload: { mockResult: "success" },
             },
         },
+        {
+            key: "acp_review",
+            kind: "task",
+            objective: "Example ACP step: set useRealAdapter + acpAgent to run a real agent; mocks otherwise",
+            dependsOn: ["hardening"],
+            validation: { mode: "none", required: false, autoConfirm: true },
+            taskSpec: {
+                adapterKey: "acp",
+                init: { systemPrompts: ["Review the implementation"] },
+                payload: { mockResult: "success" },
+            },
+        },
     ],
 };
 const WORKFLOW_SCAFFOLD_MARKDOWN = `---
@@ -244,6 +256,20 @@ steps:
         systemPrompts: [Prioritize correctness and readability]
       payload:
         mockResult: success
+  - key: acp_review
+    kind: task
+    objective: "Example ACP step: set useRealAdapter + acpAgent to run a real agent; mocks otherwise"
+    dependsOn: [hardening]
+    validation:
+      mode: none
+      required: false
+      autoConfirm: true
+    taskSpec:
+      adapterKey: acp
+      init:
+        systemPrompts: [Review the implementation]
+      payload:
+        mockResult: success
 ---
 
 # Workflow Notes
@@ -486,12 +512,14 @@ function cmdDoctor(args) {
     let workflow = null;
     let workflowErrors = [];
     let runtimeErrors = [];
+    let adapterWarnings = [];
     if (workflowPath) {
         try {
             workflow = parseWorkflowFile(path.resolve(workflowPath));
             workflowErrors = validateWorkflow(workflow);
             if (workflowErrors.length === 0) {
                 runtimeErrors = validateRuntimeRequirements(workflow);
+                adapterWarnings = adapterMockFallbackWarnings(workflow);
             }
         }
         catch (err) {
@@ -515,6 +543,7 @@ function cmdDoctor(args) {
                     title: workflow.title,
                     errors: workflowErrors,
                     runtimeErrors,
+                    adapterWarnings,
                 }
                 : null,
             baselineErrors,
@@ -548,6 +577,12 @@ function cmdDoctor(args) {
         else {
             console.log("- OK workflow schema and runtime requirements");
         }
+        if (adapterWarnings.length > 0) {
+            console.log("\nAdapter warnings:");
+            for (const warning of adapterWarnings) {
+                console.log(`- ${warning.stepKey}: ${warning.message}`);
+            }
+        }
     }
     return exitCode;
 }
@@ -629,6 +664,9 @@ async function cmdRun(filePath) {
             });
             return 1;
         }
+        for (const warning of adapterMockFallbackWarnings(workflow)) {
+            process.stderr.write(`⚠ ${warning.stepKey}: ${warning.message}\n`);
+        }
         const objective = getFlag("--objective");
         const inputRaw = getFlag("--input");
         let input = {};

package/dist/runtimePreflight.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterKey, WorkflowDefinition } from "./types.js";
+import type { AdapterKey, StepDefinition, WorkflowDefinition } from "./types.js";
 export interface RuntimeDoctorCheck {
     key: string;
     label: string;
@@ -13,4 +13,19 @@ export interface AdapterImplementationStatus {
 }
 export declare function validateRuntimeRequirements(definition: WorkflowDefinition, env?: NodeJS.ProcessEnv): string[];
 export declare function runtimeDoctorChecks(env?: NodeJS.ProcessEnv): RuntimeDoctorCheck[];
+export interface AdapterMockFallbackWarning {
+    stepKey: string;
+    adapter: AdapterKey;
+    message: string;
+}
+/**
+ * Detects a step that explicitly selects a non-pi adapter whose real execution
+ * path is not enabled, so the engine will route it to the mock executor. Non-pi
+ * agents run through ACP, which needs `useRealAdapter: true` plus a resolvable
+ * agent command. Returns a message explaining the gap, or null when the step
+ * will run as the user expects (default pi-agent, an enabled ACP/legacy path, or
+ * an intentional mock selection).
+ */
+export declare function adapterMockFallbackReason(step: StepDefinition): string | null;
+export declare function adapterMockFallbackWarnings(definition: WorkflowDefinition): AdapterMockFallbackWarning[];
 export declare function adapterImplementationStatuses(): AdapterImplementationStatus[];

package/dist/runtimePreflight.js

@@ -1,9 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveAcpCommand, shouldUseRealAcp } from "./acpExecutor.js";
 import { resolveTaskAdapter } from "./adapters.js";
 import { shouldUseRealClaudeCode } from "./claudeCodeExecutor.js";
 import { shouldUseRealOpencode } from "./opencodeExecutor.js";
 import { DEFAULT_PI_COMMAND } from "./piAgentExecutor.js";
+const ACP_ROUTABLE_ADAPTERS = new Set(["acp", "claude-code", "opencode", "codex"]);
+function legacyExecutorEnabled(step) {
+    return asRecord(step.taskSpec?.payload).legacyExecutor === true;
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -98,12 +103,23 @@ function runtimeRequirement(step, env) {
         // explicitly declared env vars are enforced for pi steps.
         return { stepKey: step.key, adapter, command: piAgentCommand(step, env), envVars: explicitRequiredEnv(step) };
     }
-    if (adapter === "opencode" && shouldUseRealOpencode(step)) {
+    const legacy = legacyExecutorEnabled(step);
+    if (legacy && adapter === "opencode" && shouldUseRealOpencode(step)) {
         return { stepKey: step.key, adapter, command: "opencode", envVars };
     }
-    if (adapter === "claude-code" && shouldUseRealClaudeCode(step)) {
+    if (legacy && adapter === "claude-code" && shouldUseRealClaudeCode(step)) {
         return { stepKey: step.key, adapter, command: "claude", envVars };
     }
+    if (shouldUseRealAcp(step)) {
+        // ACP agents manage their own credentials (like pi), so only explicitly declared
+        // env vars are enforced; the resolved agent command must exist on the host.
+        return {
+            stepKey: step.key,
+            adapter,
+            command: resolveAcpCommand(step, env)?.command,
+            envVars: explicitRequiredEnv(step),
+        };
+    }
     if (envVars.length > 0 && adapter !== "mock") {
         return { stepKey: step.key, adapter, envVars };
     }
@@ -149,15 +165,74 @@ function envCheck(key, label, envVar, env) {
 }
 export function runtimeDoctorChecks(env = process.env) {
     const piAgentStep = { key: "pi-agent", kind: "task", taskSpec: {} };
+    const acpCommand = env.WFM_ACP_COMMAND?.trim();
+    const acpCheck = acpCommand
+        ? commandCheck("acp", "ACP agent command", acpCommand, false, env)
+        : {
+            key: "acp",
+            label: "ACP agent command",
+            status: "info",
+            required: false,
+            detail: "configured per step (payload.acpCommand / acpAgent) or via WFM_ACP_COMMAND",
+        };
     return [
         commandCheck("pi-agent", "Pi command", piAgentCommand(piAgentStep, env), true, env),
-        commandCheck("opencode", "OpenCode command", "opencode", false, env),
-        commandCheck("claude", "Claude Code command", "claude", false, env),
+        acpCheck,
+        commandCheck("opencode", "OpenCode command (legacy)", "opencode", false, env),
+        commandCheck("claude", "Claude Code command (legacy)", "claude", false, env),
         envCheck("openrouter-key", "OpenRouter API key", "OPENROUTER_API_KEY", env),
         envCheck("openai-key", "OpenAI API key", "OPENAI_API_KEY", env),
         envCheck("anthropic-key", "Anthropic API key", "ANTHROPIC_API_KEY", env),
     ];
 }
+/**
+ * Detects a step that explicitly selects a non-pi adapter whose real execution
+ * path is not enabled, so the engine will route it to the mock executor. Non-pi
+ * agents run through ACP, which needs `useRealAdapter: true` plus a resolvable
+ * agent command. Returns a message explaining the gap, or null when the step
+ * will run as the user expects (default pi-agent, an enabled ACP/legacy path, or
+ * an intentional mock selection).
+ */
+export function adapterMockFallbackReason(step) {
+    if (step.kind !== "task" || !step.taskSpec?.adapterKey) {
+        return null;
+    }
+    const adapter = resolveTaskAdapter(step.taskSpec.adapterKey);
+    if (!ACP_ROUTABLE_ADAPTERS.has(adapter)) {
+        return null;
+    }
+    const legacy = legacyExecutorEnabled(step);
+    if (legacy && adapter === "opencode" && shouldUseRealOpencode(step)) {
+        return null;
+    }
+    if (legacy && adapter === "claude-code" && shouldUseRealClaudeCode(step)) {
+        return null;
+    }
+    if (shouldUseRealAcp(step)) {
+        return null;
+    }
+    if (asRecord(step.taskSpec?.payload).useRealAdapter === true) {
+        // The user opted into a real run but no ACP agent command could be resolved.
+        return `adapterKey '${adapter}' has useRealAdapter set, but no ACP agent command could be resolved, so the step runs as a mock. Set taskSpec.payload.acpCommand or acpAgent (or WFM_ACP_COMMAND) to run it through ACP.`;
+    }
+    if (resolveAcpCommand(step, process.env) !== null) {
+        // A concrete agent is named (a preset like claude-code/opencode, or an explicit
+        // command) but useRealAdapter is off, so the step still mocks.
+        return `adapterKey '${adapter}' is set, but useRealAdapter is not enabled, so the step runs as a mock. Set taskSpec.payload.useRealAdapter: true to run it through ACP.`;
+    }
+    // Bare acp/codex with no agent configured is treated as an intentional mock.
+    return null;
+}
+export function adapterMockFallbackWarnings(definition) {
+    const warnings = [];
+    for (const step of definition.steps) {
+        const message = adapterMockFallbackReason(step);
+        if (message) {
+            warnings.push({ stepKey: step.key, adapter: resolveTaskAdapter(step.taskSpec?.adapterKey), message });
+        }
+    }
+    return warnings;
+}
 export function adapterImplementationStatuses() {
     return [
         {
@@ -165,6 +240,11 @@ export function adapterImplementationStatuses() {
             status: "real",
             detail: "default host-backed adapter driving the pi coding agent CLI",
         },
+        {
+            adapter: "acp",
+            status: "real",
+            detail: "Agent Client Protocol adapter; runs any ACP agent (via acpCommand/acpAgent) when useRealAdapter is true",
+        },
         {
             adapter: "mock",
             status: "mock",
@@ -173,17 +253,17 @@ export function adapterImplementationStatuses() {
         {
             adapter: "opencode",
             status: "partial",
-            detail: "mock-routed by default; real host smoke path only when useRealAdapter and opencodeSmokeTest are true",
+            detail: "routed through ACP when useRealAdapter is true; bespoke executor deprecated (payload.legacyExecutor)",
         },
         {
             adapter: "codex",
-            status: "mock",
-            detail: "currently mock-routed; real Codex executor is not implemented yet",
+            status: "partial",
+            detail: "routed through ACP when useRealAdapter and an acpCommand/acpAgent are set; otherwise mock",
         },
         {
             adapter: "claude-code",
             status: "partial",
-            detail: "mock-routed by default; real host CLI path only when useRealAdapter is true",
+            detail: "routed through ACP when useRealAdapter is true; bespoke executor deprecated (payload.legacyExecutor)",
         },
     ];
 }

package/dist/types.d.ts

@@ -5,7 +5,7 @@ export type NodeType = "AGENT" | "HUMAN" | "SYSTEM";
 export type ExecutionStatus = "SUCCESS" | "QA_REJECTED" | "YIELD_EXTERNAL" | "FAILED";
 export type QaAction = "PROCEED" | "RETRY_CURRENT" | "ROLLBACK_PREVIOUS" | "RESTART_ALL";
 export type ValidationMode = "none" | "human" | "external";
-export type AdapterKey = "pi-agent" | "mock" | "opencode" | "codex" | "claude-code";
+export type AdapterKey = "pi-agent" | "mock" | "opencode" | "codex" | "claude-code" | "acp";
 export interface RetryPolicy {
     maxAttempts?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-manager/runner",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes",
   "repository": {
     "type": "git",
@@ -33,8 +33,8 @@
     "lint:fix": "biome lint --write --error-on-warnings",
     "lint:staged": "lint-staged --relative --concurrent false",
     "man": "man ./man/wfm.1",
-    "test:unit": "bun test tests/parser.test.ts tests/engine.test.ts tests/runtimePreflight.test.ts tests/mockExecutor.test.ts tests/opencodeExecutor.test.ts tests/claudeCodeExecutor.test.ts tests/piAgentExecutor.test.ts tests/skillResolver.test.ts tests/publish-bundle.test.ts tests/remote.test.ts tests/installer.test.ts tests/run-telemetry.test.ts tests/runnerApi.test.ts tests/runnerCli.test.ts tests/supabase-functions.test.ts tests/supabase-ops.test.ts tests/remote-registry-app.test.ts",
-    "test:release": "bun test tests/parser.test.ts tests/engine.test.ts tests/runtimePreflight.test.ts tests/mockExecutor.test.ts tests/opencodeExecutor.test.ts tests/claudeCodeExecutor.test.ts tests/piAgentExecutor.test.ts tests/skillResolver.test.ts tests/publish-bundle.test.ts tests/remote.test.ts tests/run-telemetry.test.ts tests/runnerApi.test.ts tests/runnerCli.test.ts tests/supabase-functions.test.ts tests/supabase-ops.test.ts tests/remote-registry-app.test.ts tests/story-workflow.e2e.test.ts tests/opencode-real.e2e.test.ts",
+    "test:unit": "bun test tests/parser.test.ts tests/engine.test.ts tests/runtimePreflight.test.ts tests/mockExecutor.test.ts tests/opencodeExecutor.test.ts tests/claudeCodeExecutor.test.ts tests/acpExecutor.test.ts tests/piAgentExecutor.test.ts tests/skillResolver.test.ts tests/publish-bundle.test.ts tests/remote.test.ts tests/installer.test.ts tests/run-telemetry.test.ts tests/runnerApi.test.ts tests/runnerCli.test.ts tests/supabase-functions.test.ts tests/supabase-ops.test.ts tests/remote-registry-app.test.ts",
+    "test:release": "bun test tests/parser.test.ts tests/engine.test.ts tests/runtimePreflight.test.ts tests/mockExecutor.test.ts tests/opencodeExecutor.test.ts tests/claudeCodeExecutor.test.ts tests/acpExecutor.test.ts tests/piAgentExecutor.test.ts tests/skillResolver.test.ts tests/publish-bundle.test.ts tests/remote.test.ts tests/run-telemetry.test.ts tests/runnerApi.test.ts tests/runnerCli.test.ts tests/supabase-functions.test.ts tests/supabase-ops.test.ts tests/remote-registry-app.test.ts tests/story-workflow.e2e.test.ts tests/opencode-real.e2e.test.ts",
     "test:e2e": "bun test tests/story-workflow.e2e.test.ts tests/opencode-real.e2e.test.ts",
     "test:e2e:real": "WORKFLOW_MANAGER_REAL_OPENCODE=1 bun test tests/opencode-real.e2e.test.ts",
     "test": "bun test",
@@ -72,6 +72,7 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@zed-industries/agent-client-protocol": "^0.4.5",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {

package/skills/workflow-manager-cli/SKILL.md

@@ -62,9 +62,10 @@ Adapters (set per step via `taskSpec.adapterKey`; omit for the default):
 | Adapter | Kind | Notes |
 | --- | --- | --- |
 | `pi-agent` | real (default) | Drives the host `pi` coding agent CLI in print mode. `pi` must be on `PATH`; its auth lives in `~/.pi`, not env vars. |
-| `opencode` | real (opt-in) | Requires the `opencode` CLI on `PATH`. |
-| `claude-code` | real (opt-in) | Requires the `claude` CLI on `PATH`. |
-| `codex` | mock-routed | Deterministic simulation. |
+| `acp` | real (opt-in) | Connects to any Agent Client Protocol agent over JSON-RPC/stdio. Needs `payload.useRealAdapter: true` and an agent via `payload.acpCommand`/`acpArgs`, `payload.acpAgent` preset, or `WFM_ACP_COMMAND`. Permissions via `payload.acpPermissions` (`allow`/`deny`/`reads-only`). |
+| `claude-code` | real (opt-in) | ACP preset (`claude-code-acp`). Routes through `acp` when `useRealAdapter` is true. Legacy `claude` CLI path via `payload.legacyExecutor: true`. |
+| `opencode` | real (opt-in) | ACP preset (`opencode acp`). Routes through `acp` when `useRealAdapter` is true. Legacy `opencode` CLI path via `payload.legacyExecutor: true`. |
+| `codex` | mock / opt-in | Mock by default; routes through `acp` when `useRealAdapter` and an `acpCommand`/`acpAgent` are set. |
 | `mock` | mock | Deterministic simulation for tests and examples. |
 
 Provider API keys are inferred from `taskSpec.init.model` and checked by `wfm doctor` / run preflight: