@netnodeag/kraftwerk 0.41.0 → 0.42.1

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/chat/sessions.js

@@ -333,7 +333,7 @@ async function baseScopeContext(scope, agent) {
         const bundleLines = bundles
             .map((b) => `- ${b.name} (${b.concepts} concepts${b.updatedAt ? `, updated ${b.updatedAt.slice(0, 10)}` : ""})`)
             .join("\n");
-        return (`You are the knowledge curator inside the kraftwerk inspector ("Context & Knowledge"). ` +
+        return (`You are the knowledge curator inside the kraftwerk inspector ("Knowledge"). ` +
             `This project keeps knowledge as OKF v0.2 bundles (Open Knowledge Format): directories of markdown ` +
             `files with YAML frontmatter under ${root || "knowledge/"}. Each direct subdirectory is one bundle; each .md file ` +
             `(except the reserved index.md and log.md) is one concept.\n\n` +

package/dist/inspector/knowledge.d.ts

@@ -1,6 +1,6 @@
 import { type BundleInfo, type ConceptDetail, type ConceptInfo } from "../okf.js";
 /**
- * Context & Knowledge for the inspector: a thin API layer over the OKF
+ * Knowledge for the inspector: a thin API layer over the OKF
  * core (src/okf.ts). Writes from the UI are stamped as `human:user` — the
  * browser user is the human in the loop; agents write through the CLI (or
  * chat) with their own actor.

package/dist/inspector/knowledge.js

@@ -4,7 +4,7 @@ import { resolveProject } from "../config.js";
 import { getConcept, initBundle, knowledgeRoot, listBundles, listConcepts, safeBundleName, verifyConcept, writeConcept, } from "../okf.js";
 import { getProjectRoot } from "./context.js";
 /**
- * Context & Knowledge for the inspector: a thin API layer over the OKF
+ * Knowledge for the inspector: a thin API layer over the OKF
  * core (src/okf.ts). Writes from the UI are stamped as `human:user` — the
  * browser user is the human in the loop; agents write through the CLI (or
  * chat) with their own actor.

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,

package/dist/inspector/workflows.d.ts

@@ -3,6 +3,7 @@ export interface AgentInfo {
     name?: string;
     model?: string;
     harness?: string;
+    protocol?: string;
     effort?: string;
     tools: string[];
     persona?: string;
@@ -25,6 +26,8 @@ export interface WorkflowSummary {
     description?: string;
     agents: number;
     steps: number;
+    /** False when no step reads `${{ request }}` — the ▶ button runs it straight away. */
+    usesRequest: boolean;
     error?: string;
 }
 export interface WorkflowDetail {
@@ -36,6 +39,7 @@ export interface WorkflowDetail {
     agents: AgentInfo[];
     steps: StepInfo[];
     files: string[];
+    usesRequest: boolean;
     error?: string;
 }
 export declare function listWorkflows(): Promise<{

package/dist/inspector/workflows.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { resolveProject } from "../config.js";
+import { referencesRequest } from "../yaml.js";
 import { getProjectRoot } from "./context.js";
 /**
  * Workflow discovery + parsing for the inspector. Uses the same root
@@ -80,6 +81,16 @@ async function parseRaw(l) {
     const text = await fs.readFile(l.yamlPath, "utf8");
     return parseYaml(text);
 }
+/** Does any step read the request (prompt or script, inline or via a file in the folder)? */
+async function stepsUseRequest(raw, baseDir) {
+    for (const s of raw?.steps ?? []) {
+        const script = s?.run !== undefined;
+        const { text } = await resolveText(script ? s.run : s?.prompt, baseDir);
+        if (text && referencesRequest(text, script ? "script" : "agent"))
+            return true;
+    }
+    return false;
+}
 export async function listWorkflows() {
     const root = await workflowsRoot();
     const located = await locate();
@@ -92,10 +103,11 @@ export async function listWorkflows() {
                 description: raw?.description,
                 agents: Object.keys(raw?.agents ?? {}).length,
                 steps: (raw?.steps ?? []).length,
+                usesRequest: await stepsUseRequest(raw, l.baseDir),
             };
         }
         catch (err) {
-            return { slug: l.slug, agents: 0, steps: 0, error: err.message };
+            return { slug: l.slug, agents: 0, steps: 0, usesRequest: true, error: err.message };
         }
     }));
     return { root, workflows };
@@ -127,6 +139,7 @@ export async function getWorkflow(slug) {
             agents: [],
             steps: [],
             files: [],
+            usesRequest: true,
             error: err.message,
         };
     }
@@ -138,6 +151,7 @@ export async function getWorkflow(slug) {
             name: a?.name,
             model: a?.model,
             harness: a?.harness,
+            protocol: a?.protocol ?? raw?.protocol,
             effort: a?.effort,
             tools: a?.tools ?? [],
             persona: persona.text,
@@ -178,5 +192,6 @@ export async function getWorkflow(slug) {
         agents,
         steps,
         files: l.baseDir ? await listDirFiles(l.baseDir) : [path.basename(l.yamlPath)],
+        usesRequest: await stepsUseRequest(raw, l.baseDir),
     };
 }

package/dist/okf.d.ts

@@ -1,5 +1,5 @@
 /**
- * OKF (Open Knowledge Format) core — kraftwerk's "Context & Knowledge"
+ * OKF (Open Knowledge Format) core — kraftwerk's "Knowledge"
  * feature. Implements OKF v0.2 (github.com/GoogleCloudPlatform/knowledge-catalog):
  * a knowledge bundle is a directory of markdown files with YAML frontmatter,
  * one concept per file, plus the reserved index.md / log.md.

package/dist/okf.js

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, parseDocument } from "yaml";
 /**
- * OKF (Open Knowledge Format) core — kraftwerk's "Context & Knowledge"
+ * OKF (Open Knowledge Format) core — kraftwerk's "Knowledge"
  * feature. Implements OKF v0.2 (github.com/GoogleCloudPlatform/knowledge-catalog):
  * a knowledge bundle is a directory of markdown files with YAML frontmatter,
  * one concept per file, plus the reserved index.md / log.md.

package/dist/run.d.ts

@@ -30,6 +30,7 @@ export interface RunOptions {
     maxGateRetries?: number;
 }
 export declare class Run {
+    /** Session per harness AND protocol: a CLI session id means nothing to the ACP adapter and vice versa. */
     private readonly sessions;
     /** Per-phase stats in execution order; repeated phases appear once per execution. */
     readonly stats: PhaseStats[];

package/dist/run.js

@@ -5,6 +5,7 @@ import { harnessFor } from "./harnesses/registry.js";
 import { correctionPrompt, parseEnvelope } from "./envelope.js";
 import { fmtDuration, phaseStatsLine, summaryTable } from "./stats.js";
 export class Run {
+    /** Session per harness AND protocol: a CLI session id means nothing to the ACP adapter and vice versa. */
     sessions = new Map();
     /** Per-phase stats in execution order; repeated phases appear once per execution. */
     stats = [];
@@ -23,7 +24,8 @@ export class Run {
     }
     async agentPhase(params) {
         const { agent } = params;
-        const harness = harnessFor(agent.harness);
+        const harness = harnessFor(agent.harness, agent.protocol);
+        const sessionKey = `${harness.id}/${agent.protocol ?? "cli"}`;
         const modelName = harness.id === "claude" ? agent.model : `${harness.id}:${agent.model}`;
         const modelLabel = agent.effort ? `${modelName}, effort ${agent.effort}` : modelName;
         console.log(`\n▸ Phase "${params.name}" — ${agent.name} [${agent.id}] (${modelLabel})`);
@@ -32,17 +34,19 @@ export class Run {
             kind: "agent",
             agent: agent.id,
             harness: harness.id,
+            protocol: agent.protocol ?? "cli",
             model: agent.model,
             effort: agent.effort ?? null,
             clis: agent.clis ? Object.keys(agent.clis) : [],
             mcp: agent.mcp ? Object.keys(agent.mcp) : [],
-            resume: this.sessions.get(harness.id) ?? null,
+            resume: this.sessions.get(sessionKey) ?? null,
         });
         const phaseStats = {
             phase: params.name,
             kind: "agent",
             agent: agent.id,
             harness: harness.id,
+            ...(agent.protocol === "acp" ? { protocol: "acp" } : {}),
             model: agent.model,
             effort: agent.effort,
             attempts: 0,
@@ -74,7 +78,7 @@ export class Run {
                 tools: agent.tools,
                 clis: cliEntries.map(([name]) => name),
                 mcpServers: agent.mcp,
-                resume: this.sessions.get(harness.id),
+                resume: this.sessions.get(sessionKey),
                 onToolUse: (tool, target) => {
                     console.log(`  ⚙ ${tool} ${target}`.trimEnd());
                     void this.trace("tool_use", { phase: params.name, attempt, tool, target });
@@ -82,7 +86,7 @@ export class Run {
                 onText: this.verbose ? (text) => console.log(`  💬 ${text}`) : undefined,
             });
             if (result.sessionId)
-                this.sessions.set(harness.id, result.sessionId);
+                this.sessions.set(sessionKey, result.sessionId);
             phaseStats.attempts = attempt + 1;
             phaseStats.durationMs = Date.now() - started;
             phaseStats.costUsd += result.costUsd ?? 0;

package/dist/stats.d.ts

@@ -9,6 +9,8 @@ export interface PhaseStats {
     agent?: string;
     /** Harness id, for agent phases. */
     harness?: string;
+    /** "acp" when the phase ran over the Agent Client Protocol (absent = CLI). */
+    protocol?: string;
     /** Model id, for agent phases. */
     model?: string;
     effort?: string;

package/dist/yaml.d.ts

@@ -7,9 +7,21 @@ export interface LoadedWorkflow extends WorkflowDefinition {
         steps: string[];
         /** Environment variables the workflow declares under `requires:`. */
         requires: string[];
+        /** False when no step reads `${{ request }}` — such a workflow runs without a request. */
+        usesRequest: boolean;
     };
     run(opts: Parameters<WorkflowDefinition["run"]>[0]): Promise<RunResult>;
 }
+/**
+ * Does a prompt or script read the request? Prompts through `${{ request }}`;
+ * scripts through that or the REQUEST env var — matched as the bare word,
+ * because a script may read it from bash (`$REQUEST`), Python
+ * (`os.environ.get("REQUEST")`) or anything else. A mention in a comment
+ * counts too: better one dialog too many than a run without its input.
+ * A workflow whose steps never read it runs without one (`kraftwerk run
+ * <name>`, the ▶ in the UI) — the request is an argument, not a ritual.
+ */
+export declare const referencesRequest: (text: string, kind: "agent" | "script") => boolean;
 /** Names from `requires:` that are missing/empty in the current environment. */
 export declare const missingEnv: (requires: string[]) => string[];
 /**

package/dist/yaml.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { Ajv } from "ajv";
 import { parse } from "yaml";
+import { disposeAcpSessions } from "./harnesses/acp.js";
 import { envelopeContract } from "./envelope.js";
 import { checkScript, containsText, fileNonEmpty, slotsFilled } from "./gates.js";
 import { Run } from "./run.js";
@@ -77,6 +78,16 @@ function formatAjvErrors(errors, file) {
     const cliHint = errors.some((e) => e.instancePath.startsWith("/clis")) ? `\n${CLI_HINT}` : "";
     return `${file}: schema validation failed\n${lines.map((l) => `  - ${l}`).join("\n")}${gateHint}${stepHint}${mcpHint}${cliHint}`;
 }
+/**
+ * Does a prompt or script read the request? Prompts through `${{ request }}`;
+ * scripts through that or the REQUEST env var — matched as the bare word,
+ * because a script may read it from bash (`$REQUEST`), Python
+ * (`os.environ.get("REQUEST")`) or anything else. A mention in a comment
+ * counts too: better one dialog too many than a run without its input.
+ * A workflow whose steps never read it runs without one (`kraftwerk run
+ * <name>`, the ▶ in the UI) — the request is an argument, not a ritual.
+ */
+export const referencesRequest = (text, kind) => /\$\{\{\s*request\s*\}\}/.test(text) || (kind === "script" && /\bREQUEST\b/.test(text));
 /** Names from `requires:` that are missing/empty in the current environment. */
 export const missingEnv = (requires) => requires.filter((name) => !process.env[name]);
 /**
@@ -176,8 +187,15 @@ export async function loadWorkflow(givenPath) {
     // CLIs available to agents: command prefix -> one-line usage hint (may be
     // empty). Purely declarative; agents opt in below.
     const cliDefs = new Map(Object.entries(raw.clis ?? {}).map(([name, hint]) => [name, String(hint ?? "")]));
+    // `protocol: acp` drives a harness over the Agent Client Protocol instead
+    // of its CLI — workflow-wide, or per agent. pi has no adapter.
+    const protocolDefault = raw.protocol ?? "cli";
     const agents = new Map();
     for (const [id, a] of Object.entries(raw.agents ?? {})) {
+        const protocol = a.protocol ?? protocolDefault;
+        if (protocol === "acp" && a["runs-on"] === "pi") {
+            fail(`agents.${id}: runs-on "pi" has no agent-protocol adapter — use claude or codex, or protocol: cli`);
+        }
         const mcp = {};
         for (const serverName of (a.mcp ?? [])) {
             const def = mcpDefs.get(serverName);
@@ -206,6 +224,7 @@ export async function loadWorkflow(givenPath) {
             tools: a.tools,
             persona: await resolveText(a.persona, `agents.${id}.persona`),
             harness: a["runs-on"],
+            ...(protocol === "acp" ? { protocol } : {}),
             ...(Object.keys(clis).length > 0 ? { clis } : {}),
             ...(Object.keys(mcp).length > 0 ? { mcp } : {}),
         });
@@ -255,6 +274,7 @@ export async function loadWorkflow(givenPath) {
             agents: [...agents.values()],
             steps: steps.map((s) => s.name),
             requires,
+            usesRequest: steps.some((s) => referencesRequest(s.kind === "script" ? s.script : s.prompt, s.kind)),
         },
         async run({ request, verbose }) {
             const missing = missingEnv(requires);
@@ -286,48 +306,53 @@ export async function loadWorkflow(givenPath) {
                     ? { name: s.name, kind: "script" }
                     : { name: s.name, kind: "agent", agent: s.agent.id, model: s.agent.model }),
             });
-            for (const step of steps) {
-                // `if:` preconditions — deterministic checks on run-dir files. Any
-                // unmet precondition SKIPS the step (the run continues); this is how
-                // a workflow avoids spawning an agent when there is nothing to do.
-                if (step.preconditions.length > 0) {
-                    const unmet = [];
-                    for (const pre of step.preconditions) {
-                        const failure = await pre.check(runDir);
-                        if (failure)
-                            unmet.push(`${pre.name}: ${failure}`);
+            try {
+                for (const step of steps) {
+                    // `if:` preconditions — deterministic checks on run-dir files. Any
+                    // unmet precondition SKIPS the step (the run continues); this is how
+                    // a workflow avoids spawning an agent when there is nothing to do.
+                    if (step.preconditions.length > 0) {
+                        const unmet = [];
+                        for (const pre of step.preconditions) {
+                            const failure = await pre.check(runDir);
+                            if (failure)
+                                unmet.push(`${pre.name}: ${failure}`);
+                        }
+                        if (unmet.length > 0) {
+                            console.log(`\n▸ Phase "${step.name}" — skipped (if: not met)`);
+                            for (const reason of unmet)
+                                console.log(`  ↷ ${reason}`);
+                            await run.trace("phase_skipped", { phase: step.name, unmet });
+                            continue;
+                        }
                     }
-                    if (unmet.length > 0) {
-                        console.log(`\n▸ Phase "${step.name}" — skipped (if: not met)`);
-                        for (const reason of unmet)
-                            console.log(`  ↷ ${reason}`);
-                        await run.trace("phase_skipped", { phase: step.name, unmet });
+                    if (step.kind === "script") {
+                        await run.scriptPhase({
+                            name: step.name,
+                            script: step.script.replace(/\$\{\{\s*request\s*\}\}/g, request),
+                            gates: step.gates,
+                            env: {
+                                REQUEST: request,
+                                ...(baseDir ? { WORKFLOW_DIR: path.resolve(baseDir) } : {}),
+                            },
+                        });
                         continue;
                     }
-                }
-                if (step.kind === "script") {
-                    await run.scriptPhase({
+                    const prompt = step.prompt
+                        .replace(/\$\{\{\s*request\s*\}\}/g, request)
+                        .replace(/\$\{\{\s*agent\s*\}\}/g, step.agent.id);
+                    await run.agentPhase({
                         name: step.name,
-                        script: step.script.replace(/\$\{\{\s*request\s*\}\}/g, request),
+                        agent: step.agent,
+                        prompt: `${prompt}\n\n${envelopeContract(step.name)}`,
                         gates: step.gates,
-                        env: {
-                            REQUEST: request,
-                            ...(baseDir ? { WORKFLOW_DIR: path.resolve(baseDir) } : {}),
-                        },
                     });
-                    continue;
                 }
-                const prompt = step.prompt
-                    .replace(/\$\{\{\s*request\s*\}\}/g, request)
-                    .replace(/\$\{\{\s*agent\s*\}\}/g, step.agent.id);
-                await run.agentPhase({
-                    name: step.name,
-                    agent: step.agent,
-                    prompt: `${prompt}\n\n${envelopeContract(step.name)}`,
-                    gates: step.gates,
-                });
+                await run.printSummary();
+            }
+            finally {
+                disposeAcpSessions(runDir);
             }
-            await run.printSummary();
             console.log(`\nArtifacts: ${runDir}`);
             return { runDir, phases: run.stats, total: summaryTable(run.stats).total };
         },