@netnodeag/kraftwerk 0.41.0 → 0.42.0

package/README.md

@@ -583,6 +583,31 @@ Prerequisites per harness:
   models reuse the Claude subscription OAuth, other vendors need their key in
   the env (check with `pi auth check --provider deepseek`).
 
+### Agent protocol
+
+Phases can also run over the [Agent Client Protocol](https://agentclientprotocol.com)
+— the same adapters the inspector's chats use (`claude-agent-acp`,
+`codex-acp`), bundled with kraftwerk, so nothing needs to be on the PATH.
+Set `protocol: acp` at the top of a workflow (every agent) or on one agent;
+`runs-on` still picks the harness (pi has no adapter). The adapter process
+stays alive for the whole run, so phases on one harness share a session
+like `--resume` does on the CLI. Persona and workspace context travel inside
+each phase prompt. On claude the agent's `tools`, CLI grants and MCP servers
+become the session's allowlist (settings sources off) and the session is
+switched to `acceptEdits`; codex runs in its workspace-write mode. A permission request the harness
+still raises is declined — nobody watches a workflow run, and kraftwerk
+never answers for a human. A programmatic `Run` ends its adapters with
+`disposeAcpSessions(runDir)` (the YAML runner does this itself).
+
+```yaml
+name: tagline
+protocol: acp          # all agents over ACP; per agent: protocol: cli | acp
+agents:
+  writer:
+    runs-on: claude    # or codex
+    model: sonnet
+```
+
 ## YAML workflows
 
 Linear workflows can be pure config, GitHub-Actions-flavored with `steps`,

package/dist/acp.d.ts

@@ -0,0 +1,43 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { ClientSideConnection, type Client, type McpServer } from "@agentclientprotocol/sdk";
+import type { McpServerConfig } from "./harness.js";
+/**
+ * Agent Client Protocol plumbing shared by the inspector's chats and the
+ * workflow ACP harness: the adapter packages (bundled with kraftwerk, so no
+ * CLI on the PATH is needed), model/effort tuning, and spawning one adapter
+ * as a subprocess speaking ACP over its stdio.
+ *
+ * Auth rides on the local CLI logins (Claude Code / Codex) via the
+ * inherited environment — same story as the CLI harnesses.
+ */
+export type AcpAgent = "claude" | "codex";
+/**
+ * Model/effort overrides ride on adapter-specific channels: the claude
+ * adapter takes the model via session `_meta.claudeCode.options` and the
+ * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
+ * the session config it hands to `codex app-server`.
+ */
+export declare function adapterEnv(agent: AcpAgent, tuning: {
+    model?: string;
+    effort?: string;
+}): NodeJS.ProcessEnv;
+/** Kraftwerk's MCP config (stdio or url) -> the protocol's session mcpServers entries. */
+export declare function acpMcpServers(servers?: Record<string, McpServerConfig>): McpServer[];
+export interface AcpProcess {
+    child: ChildProcessWithoutNullStreams;
+    conn: ClientSideConnection;
+}
+/**
+ * Spawn the adapter for `agent` in `cwd`, wire the ACP connection to
+ * `client`, and run the initialize handshake. Process failures reach the
+ * caller through the callbacks (a failed spawn is otherwise an unhandled
+ * 'error' event that takes the host process down).
+ */
+export declare function connectAcp(agent: AcpAgent, opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    client: Client;
+    clientName: string;
+    onError(err: Error): void;
+    onClose(code: number | null, stderr: string): void;
+}): Promise<AcpProcess>;

package/dist/acp.js

@@ -0,0 +1,76 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+const ADAPTERS = {
+    claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
+    codex: "@agentclientprotocol/codex-acp/dist/index.js",
+};
+/** Effort tier -> Claude thinking budget (the adapter reads MAX_THINKING_TOKENS). */
+const CLAUDE_THINKING_BUDGET = {
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+    xhigh: 32000,
+    max: 63999,
+};
+/**
+ * Model/effort overrides ride on adapter-specific channels: the claude
+ * adapter takes the model via session `_meta.claudeCode.options` and the
+ * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
+ * the session config it hands to `codex app-server`.
+ */
+export function adapterEnv(agent, tuning) {
+    const env = { ...process.env };
+    if (agent === "claude" && tuning.effort && CLAUDE_THINKING_BUDGET[tuning.effort]) {
+        env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[tuning.effort]);
+    }
+    if (agent === "codex" && (tuning.model || tuning.effort)) {
+        env.CODEX_CONFIG = JSON.stringify({
+            ...(tuning.model ? { model: tuning.model } : {}),
+            ...(tuning.effort ? { model_reasoning_effort: tuning.effort } : {}),
+        });
+    }
+    return env;
+}
+/** Kraftwerk's MCP config (stdio or url) -> the protocol's session mcpServers entries. */
+export function acpMcpServers(servers = {}) {
+    return Object.entries(servers).map(([name, cfg]) => "url" in cfg
+        ? { type: "http", name, url: cfg.url, headers: [] }
+        : {
+            name,
+            command: cfg.command,
+            args: cfg.args ?? [],
+            env: Object.entries(cfg.env ?? {}).map(([n, value]) => ({ name: n, value })),
+        });
+}
+/**
+ * Spawn the adapter for `agent` in `cwd`, wire the ACP connection to
+ * `client`, and run the initialize handshake. Process failures reach the
+ * caller through the callbacks (a failed spawn is otherwise an unhandled
+ * 'error' event that takes the host process down).
+ */
+export async function connectAcp(agent, opts) {
+    const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
+    const child = spawn(process.execPath, [entry], {
+        cwd: opts.cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+        env: opts.env,
+    });
+    let stderr = "";
+    child.stderr.on("data", (c) => {
+        stderr += c.toString("utf8");
+        if (stderr.length > 20_000)
+            stderr = stderr.slice(-20_000);
+    });
+    child.on("error", opts.onError);
+    child.on("close", (code) => opts.onClose(code, stderr.trim()));
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+    const conn = new ClientSideConnection(() => opts.client, stream);
+    await conn.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+        clientInfo: { name: opts.clientName, version: "1.0.0" },
+    });
+    return { child, conn };
+}

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessId, McpServerConfig } from "./harness.js";
+import type { AgentProtocol, HarnessId, McpServerConfig } from "./harness.js";
 /**
  * An agent is exactly four things:
  *
@@ -45,5 +45,7 @@ export interface AgentDefinition {
     mcp?: Record<string, McpServerConfig>;
     /** Which runtime executes this agent. Default: "claude". */
     harness?: HarnessId;
+    /** How that runtime is driven: headless CLI (default) or the Agent Client Protocol. */
+    protocol?: AgentProtocol;
 }
 export declare function defineAgent(agent: AgentDefinition): AgentDefinition;

package/dist/cli/doctor.js

@@ -137,11 +137,19 @@ export async function runDoctor(cwd) {
         }
     }
     // Harnesses: hard requirement only if a discovered workflow runs on them.
+    // Over the agent protocol the bundled adapters bring their own runtime.
     const needed = new Set();
+    let acp = false;
     for (const e of found) {
-        for (const a of e.workflow?.meta.agents ?? [])
-            needed.add(a.harness ?? "claude");
+        for (const a of e.workflow?.meta.agents ?? []) {
+            if (a.protocol === "acp")
+                acp = true;
+            else
+                needed.add(a.harness ?? "claude");
+        }
     }
+    if (acp)
+        report("ok", "agent protocol adapters", "claude-agent-acp + codex-acp bundled with kraftwerk");
     for (const harness of ["claude", "codex", "pi"]) {
         const version = cliVersion(harness);
         const isNeeded = needed.has(harness);

package/dist/cli/kraftwerk.js

@@ -62,7 +62,10 @@ const program = new Command()
     .version(pkg.version);
 const agentLabel = (workflow) => workflow.meta.agents
     .map((a) => {
-    const harness = a.harness && a.harness !== "claude" ? `${a.harness}:` : "";
+    const where = [a.harness && a.harness !== "claude" ? a.harness : "", a.protocol === "acp" ? "acp" : ""]
+        .filter(Boolean)
+        .join("/");
+    const harness = where ? `${where}:` : "";
     const effort = a.effort ? `, ${a.effort}` : "";
     return `${a.id} ${chalk.dim(`(${harness}${a.model}${effort})`)}`;
 })
@@ -88,6 +91,7 @@ program
                 id: a.id,
                 model: a.model,
                 harness: a.harness ?? "claude",
+                protocol: a.protocol ?? "cli",
             })),
             error: e.error,
         })), null, 2));
@@ -166,13 +170,15 @@ program
         })),
     });
     const workflow = entry.workflow;
+    // A workflow whose steps never read ${{ request }} runs without one.
     let request = (requestParts ?? []).join(" ").trim();
-    if (!request && machine)
-        fail(2, "No request given (--json is non-interactive).");
-    if (!request)
+    if (!request && workflow.meta.usesRequest) {
+        if (machine)
+            fail(2, "No request given (--json is non-interactive).");
         request = (await input({ message: "Request (topic, URL, ...):" })).trim();
-    if (!request)
-        fail(2, "No request given.");
+        if (!request)
+            fail(2, "No request given.");
+    }
     const missing = missingEnv(workflow.meta.requires);
     if (missing.length > 0) {
         fail(2, `Workflow "${workflow.name}" needs environment variables that are missing: ${missing.join(", ")}`);

package/dist/harness.d.ts

@@ -12,6 +12,12 @@
  * run directory (the workspace-context contract).
  */
 export type HarnessId = "claude" | "codex" | "pi";
+/**
+ * How the harness is driven: `cli` spawns the headless CLI per phase
+ * (claude -p, codex exec, pi); `acp` keeps one Agent Client Protocol
+ * adapter alive for the run (see harnesses/acp.ts). pi has no adapter.
+ */
+export type AgentProtocol = "cli" | "acp";
 /**
  * One MCP server an agent may use: either a local stdio server (spawned by
  * the harness, e.g. `node multiply-server.ts`) or a remote streamable-HTTP

package/dist/harnesses/acp.d.ts

@@ -0,0 +1,20 @@
+import type { AgentInvocation, Harness, HarnessId } from "../harness.js";
+/** Claude Agent SDK options for a phase session: the CLI harness's flags, as session meta. */
+export declare function claudeSessionOptions(inv: Pick<AgentInvocation, "model" | "tools" | "clis" | "mcpServers">): Record<string, unknown>;
+/**
+ * What a tool call touched, from its input (path, url, command) or its
+ * first location. Undefined when the adapter has not said yet — a title
+ * alone may be a placeholder.
+ */
+export declare function toolTarget(u: {
+    rawInput?: Record<string, unknown>;
+    locations?: Array<{
+        path?: string;
+    }>;
+}): string | undefined;
+/**
+ * Stop the adapter processes of one run (its run directory), or of every
+ * run in this process when no directory is given.
+ */
+export declare function disposeAcpSessions(cwd?: string): void;
+export declare function acpHarness(id: HarnessId): Harness;

package/dist/harnesses/acp.js

@@ -0,0 +1,195 @@
+import { RequestError, } from "@agentclientprotocol/sdk";
+import { acpMcpServers, adapterEnv, connectAcp } from "../acp.js";
+import { declineOption, unattendedMode } from "../inspector/chat/permissions.js";
+const live = new Map();
+// The run process is the adapters' only owner: never leave one behind.
+process.once("exit", () => disposeAcpSessions());
+/** Claude Agent SDK options for a phase session: the CLI harness's flags, as session meta. */
+export function claudeSessionOptions(inv) {
+    return {
+        model: inv.model,
+        // Keep the run hermetic: no user/project settings, hooks, or CLAUDE.md.
+        settingSources: [],
+        allowedTools: [
+            ...inv.tools,
+            ...(inv.clis ?? []).map((name) => `Bash(${name}:*)`),
+            ...Object.keys(inv.mcpServers ?? {}).map((name) => `mcp__${name}`),
+        ],
+    };
+}
+/**
+ * What a tool call touched, from its input (path, url, command) or its
+ * first location. Undefined when the adapter has not said yet — a title
+ * alone may be a placeholder.
+ */
+export function toolTarget(u) {
+    const input = u.rawInput ?? {};
+    const raw = input.file_path ?? input.url ?? input.path ?? input.command ?? u.locations?.[0]?.path;
+    if (raw == null)
+        return undefined;
+    const target = String(raw).replace(/\s+/g, " ").trim();
+    return target.length > 160 ? `${target.slice(0, 160)}…` : target;
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+async function open(agent, inv) {
+    let ended;
+    const closed = new Promise((r) => (ended = r));
+    const state = {
+        agent,
+        cwd: inv.cwd,
+        sessionId: "",
+        dead: false,
+        closed,
+        turn: null,
+        cost: 0,
+    };
+    const end = (why) => {
+        state.dead = true;
+        state.exit ??= why;
+        ended(state.exit);
+    };
+    const client = {
+        sessionUpdate(params) {
+            const u = params.update;
+            const turn = state.turn;
+            if (u.sessionUpdate === "agent_message_chunk" && u.content?.type === "text" && turn) {
+                turn.text += u.content.text ?? "";
+            }
+            else if (u.sessionUpdate === "tool_call" && turn) {
+                const kind = u.kind ?? "tool";
+                const target = toolTarget(u);
+                if (target)
+                    turn.onToolUse?.(kind, target);
+                else
+                    turn.pending.set(u.toolCallId ?? "", { kind, title: String(u.title ?? "") });
+            }
+            else if (u.sessionUpdate === "tool_call_update" && turn?.pending.has(u.toolCallId ?? "")) {
+                const target = toolTarget(u);
+                if (target) {
+                    turn.onToolUse?.(turn.pending.get(u.toolCallId ?? "").kind, target);
+                    turn.pending.delete(u.toolCallId ?? "");
+                }
+            }
+            else if (u.sessionUpdate === "usage_update" && typeof u.cost?.amount === "number") {
+                state.cost = u.cost.amount;
+            }
+        },
+        async requestPermission(params) {
+            // The harness judged this worth asking; a workflow run has nobody to ask.
+            const optionId = declineOption(params.options);
+            console.log(`  ⛔ ${params.toolCall.title ?? params.toolCall.toolCallId} — permission declined (unattended run)`);
+            return optionId ? { outcome: { outcome: "selected", optionId } } : { outcome: { outcome: "cancelled" } };
+        },
+    };
+    const { child, conn } = await connectAcp(agent, {
+        cwd: inv.cwd,
+        env: adapterEnv(agent, { model: inv.model, effort: inv.effort }),
+        client,
+        clientName: "kraftwerk",
+        onError: (err) => end(`could not start the ${agent} adapter: ${err.message}`),
+        onClose: (code, stderr) => end(`${agent} adapter exited (code ${code})${stderr ? `: ${stderr.slice(-500)}` : ""}`),
+    });
+    state.child = child;
+    state.conn = conn;
+    try {
+        const session = await conn.newSession({
+            cwd: inv.cwd,
+            mcpServers: acpMcpServers(inv.mcpServers),
+            ...(agent === "claude" ? { _meta: { claudeCode: { options: claudeSessionOptions(inv) } } } : {}),
+        });
+        state.sessionId = session.sessionId;
+        const modeId = unattendedMode(agent, session.modes?.currentModeId);
+        if (modeId) {
+            await conn.setSessionMode({ sessionId: session.sessionId, modeId }).catch((err) => {
+                console.log(`  ⚠ could not select the ${modeId} mode (${err.message}) — the ${agent} default applies`);
+            });
+        }
+    }
+    catch (err) {
+        // A refused session leaves the adapter running; it must not outlive the failure.
+        if (!state.dead)
+            child.kill("SIGTERM");
+        throw await failure(state, agent, err);
+    }
+    live.set(state.sessionId, state);
+    return state;
+}
+/**
+ * The error to surface for a failed request. When the adapter died, the
+ * SDK rejects on stdout EOF before the process 'close' event carries the
+ * stderr tail — give that a moment and prefer it, it names the real cause.
+ */
+async function failure(state, agent, err) {
+    const closing = /connection closed|closed/i.test(err.message ?? "");
+    if (state.dead || closing)
+        await Promise.race([state.closed, wait(1000)]);
+    if (state.exit)
+        return new Error(state.exit);
+    if (err instanceof RequestError)
+        return new Error(`${agent} (acp): ${err.message}`);
+    return err;
+}
+async function invoke(agent, inv) {
+    let s = inv.resume ? live.get(inv.resume) : undefined;
+    if (s?.dead) {
+        live.delete(s.sessionId);
+        s = undefined;
+    }
+    s ??= await open(agent, inv);
+    const turn = { text: "", onToolUse: inv.onToolUse, pending: new Map() };
+    s.turn = turn;
+    const prevCost = s.cost;
+    const started = Date.now();
+    // No per-prompt system prompt over ACP: carry persona + context in the prompt.
+    const prompt = `# Role and workspace context for this phase\n\n${inv.systemPrompt}\n\n` + `# Task\n\n${inv.prompt}`;
+    let res;
+    try {
+        res = await s.conn.prompt({ sessionId: s.sessionId, prompt: [{ type: "text", text: prompt }] });
+    }
+    catch (err) {
+        s.turn = null;
+        throw await failure(s, agent, err);
+    }
+    s.turn = null;
+    // Calls the adapter never named (no update carried a target) still count.
+    for (const p of turn.pending.values())
+        inv.onToolUse?.(p.kind, p.title);
+    if (res.stopReason !== "end_turn")
+        throw new Error(`${agent} (acp) stopped with ${res.stopReason}`);
+    if (inv.onText && turn.text.trim())
+        inv.onText(turn.text.trim());
+    const result = {
+        sessionId: s.sessionId,
+        text: turn.text,
+        durationMs: Date.now() - started,
+    };
+    if (res.usage) {
+        result.usage = {
+            inputTokens: res.usage.inputTokens,
+            outputTokens: res.usage.outputTokens,
+            cacheReadTokens: res.usage.cachedReadTokens ?? 0,
+            cacheCreationTokens: res.usage.cachedWriteTokens ?? 0,
+        };
+    }
+    if (s.cost > prevCost)
+        result.costUsd = s.cost - prevCost;
+    return result;
+}
+/**
+ * Stop the adapter processes of one run (its run directory), or of every
+ * run in this process when no directory is given.
+ */
+export function disposeAcpSessions(cwd) {
+    for (const [id, s] of live) {
+        if (cwd && s.cwd !== cwd)
+            continue;
+        if (!s.dead)
+            s.child.kill("SIGTERM");
+        live.delete(id);
+    }
+}
+export function acpHarness(id) {
+    if (id === "pi")
+        throw new Error('runs-on "pi" has no agent-protocol adapter — use claude or codex, or protocol: cli');
+    return { id, invoke: (inv) => invoke(id, inv) };
+}

package/dist/harnesses/registry.d.ts

@@ -1,2 +1,2 @@
-import type { Harness, HarnessId } from "../harness.js";
-export declare function harnessFor(id?: HarnessId): Harness;
+import type { AgentProtocol, Harness, HarnessId } from "../harness.js";
+export declare function harnessFor(id?: HarnessId, protocol?: AgentProtocol): Harness;

package/dist/harnesses/registry.js

@@ -1,16 +1,21 @@
+import { acpHarness } from "./acp.js";
 import { claudeHarness } from "./claude.js";
 import { codexHarness } from "./codex.js";
 import { piHarness } from "./pi.js";
 /**
- * Maps an agent's `harness` field to the adapter that runs it.
- * Default is claude — an agent without a harness runs on `claude -p`.
+ * Maps an agent's `harness` (+ `protocol`) to the adapter that runs it.
+ * Default is claude over the CLI — an agent without a harness runs on
+ * `claude -p`; `protocol: acp` drives the same harness over the Agent
+ * Client Protocol instead.
  */
 const HARNESSES = {
     claude: claudeHarness,
     codex: codexHarness,
     pi: piHarness,
 };
-export function harnessFor(id = "claude") {
+export function harnessFor(id = "claude", protocol = "cli") {
+    if (protocol === "acp")
+        return acpHarness(id);
     const harness = HARNESSES[id];
     if (!harness) {
         throw new Error(`harness "${id}" is not registered (available: ${Object.keys(HARNESSES).join(", ")})`);

package/dist/index.d.ts

@@ -10,6 +10,7 @@
 export { defineAgent, type AgentDefinition, type EffortLevel } from "./agent.js";
 export { type AgentInvocation, type AgentResult, type Harness, type HarnessId, type McpServerConfig, type TokenUsage, } from "./harness.js";
 export { harnessFor } from "./harnesses/registry.js";
+export { disposeAcpSessions } from "./harnesses/acp.js";
 export { Run, type RunOptions } from "./run.js";
 export { correctionPrompt, envelopeContract, parseEnvelope, type Envelope, } from "./envelope.js";
 export { containsText, fileNonEmpty, slotsFilled, type Gate } from "./gates.js";

package/dist/index.js

@@ -9,6 +9,7 @@
  */
 export { defineAgent } from "./agent.js";
 export { harnessFor } from "./harnesses/registry.js";
+export { disposeAcpSessions } from "./harnesses/acp.js";
 export { Run } from "./run.js";
 export { correctionPrompt, envelopeContract, parseEnvelope, } from "./envelope.js";
 export { containsText, fileNonEmpty, slotsFilled } from "./gates.js";

package/dist/inspector/chat/acp.js

@@ -1,80 +1,18 @@
-import { spawn } from "node:child_process";
-import { Readable, Writable } from "node:stream";
-import { fileURLToPath } from "node:url";
-import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
+import { RequestError } from "@agentclientprotocol/sdk";
+import { adapterEnv, connectAcp } from "../../acp.js";
 import { unattendedMode } from "./permissions.js";
 /**
  * ACP-backed chat: spawn an adapter (claude-agent-acp / codex-acp) as a
  * subprocess, speak Agent Client Protocol over its stdio, and translate
  * session/update notifications into chat events. One subprocess lives for
- * the whole chat; the ACP session id carries the conversation.
- *
- * Auth rides on the local CLI logins (Claude Code / Codex) via the
- * inherited environment — same story as the kraftwerk harnesses.
+ * the whole chat; the ACP session id carries the conversation. The
+ * adapter plumbing is shared with the workflow ACP harness (src/acp.ts).
  */
-const ADAPTERS = {
-    claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
-    codex: "@agentclientprotocol/codex-acp/dist/index.js",
-};
-/** Effort tier -> Claude thinking budget (the adapter reads MAX_THINKING_TOKENS). */
-const CLAUDE_THINKING_BUDGET = {
-    low: 2048,
-    medium: 8192,
-    high: 16384,
-    xhigh: 32000,
-    max: 63999,
-};
-/**
- * Model/effort overrides ride on adapter-specific channels: the claude
- * adapter takes the model via session `_meta.claudeCode.options` and the
- * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
- * the session config it hands to `codex app-server`.
- */
-function tuningEnv(agent, tuning) {
-    const env = { ...process.env };
-    if (agent === "claude" && tuning.effort && CLAUDE_THINKING_BUDGET[tuning.effort]) {
-        env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[tuning.effort]);
-    }
-    if (agent === "codex" && (tuning.model || tuning.effort)) {
-        env.CODEX_CONFIG = JSON.stringify({
-            ...(tuning.model ? { model: tuning.model } : {}),
-            ...(tuning.effort ? { model_reasoning_effort: tuning.effort } : {}),
-        });
-    }
-    return env;
-}
 function contentText(content) {
     return content.type === "text" ? content.text : "";
 }
 export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
-    const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
-    const child = spawn(process.execPath, [entry], {
-        cwd,
-        stdio: ["pipe", "pipe", "pipe"],
-        env: tuningEnv(agent, tuning),
-    });
-    let stderr = "";
-    child.stderr.on("data", (c) => {
-        stderr += c.toString("utf8");
-        if (stderr.length > 20_000)
-            stderr = stderr.slice(-20_000);
-    });
     let dead = false;
-    // Without a listener a failed spawn (cwd gone, node missing) is an
-    // unhandled 'error' event that takes the whole inspector down.
-    child.on("error", (err) => {
-        dead = true;
-        hooks.emit({ type: "error", message: `could not start the ${agent} agent: ${err.message}` });
-    });
-    child.on("close", (code) => {
-        dead = true;
-        if (code !== 0 && code !== null) {
-            hooks.emit({
-                type: "error",
-                message: `${agent} agent exited (code ${code})${stderr.trim() ? `: ${stderr.trim().slice(-500)}` : ""}`,
-            });
-        }
-    });
     const client = {
         sessionUpdate(params) {
             const u = params.update;
@@ -118,12 +56,24 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
                 : { outcome: { outcome: "cancelled" } };
         },
     };
-    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
-    const conn = new ClientSideConnection(() => client, stream);
-    await conn.initialize({
-        protocolVersion: PROTOCOL_VERSION,
-        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
-        clientInfo: { name: "kraftwerk-inspector", version: "1.0.0" },
+    const { child, conn } = await connectAcp(agent, {
+        cwd,
+        env: adapterEnv(agent, tuning),
+        client,
+        clientName: "kraftwerk-inspector",
+        onError: (err) => {
+            dead = true;
+            hooks.emit({ type: "error", message: `could not start the ${agent} agent: ${err.message}` });
+        },
+        onClose: (code, stderr) => {
+            dead = true;
+            if (code !== 0 && code !== null) {
+                hooks.emit({
+                    type: "error",
+                    message: `${agent} agent exited (code ${code})${stderr ? `: ${stderr.slice(-500)}` : ""}`,
+                });
+            }
+        },
     });
     // Claude-only session options ride on _meta.claudeCode.options (the
     // adapter spreads them into the Agent SDK options): model override,

package/dist/inspector/runs.d.ts

@@ -10,6 +10,7 @@ export interface PhaseView {
     agent?: string;
     model?: string;
     harness?: string;
+    protocol?: string;
     status: "running" | "ok" | "failed" | "blocked" | "pending";
     attempts: number;
     startedAt?: string;

package/dist/inspector/runs.js

@@ -42,6 +42,7 @@ function analyse(events) {
                 agent: e.agent,
                 model: e.model,
                 harness: e.harness,
+                protocol: e.protocol === "acp" ? "acp" : undefined,
                 status: "running",
                 attempts: 0,
                 startedAt: e.ts,

package/dist/inspector/server.js

@@ -645,8 +645,8 @@ async function handleApi(req, res, url) {
                 return json(res, { error: "invalid JSON body" }, 400);
             }
             const request = (body.request ?? "").trim();
-            if (!request)
-                return json(res, { error: "request text is required" }, 400);
+            if (!request && wf.usesRequest)
+                return json(res, { error: "this workflow needs a request" }, 400);
             try {
                 const { runId } = triggerRun({
                     workflowName: wf.name,