@netnodeag/kraftwerk 0.4.0 → 0.4.1

package/README.md

@@ -56,7 +56,7 @@ kraftwerk list                          # table: workflows, steps, agents (with
 kraftwerk run tagline "https://..."     # run; --yes, --verbose
 kraftwerk run                           # interactive: pick workflow, type the request
 kraftwerk runs                          # past runs from output/*/trace.jsonl; runs show <id> for detail
-kraftwerk ui                            # inspector web UI on http://localhost:4499; --port, --output
+kraftwerk ui                            # inspector web UI on http://localhost:1981; --port, --output
 kraftwerk doctor                        # preflight: harness CLIs, docker, workflows, declared env vars
 kraftwerk validate                      # all discovered — schema + semantics + files, exit 1 on failure
 kraftwerk validate src/workflows/pitch  # specific paths

package/dist/cli/kraftwerk.js

@@ -20,7 +20,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk list                    discover + list workflows (--json, --from)
  *   kraftwerk run [workflow] [text]   run one (prompts interactively if omitted)
  *   kraftwerk runs [show <id>]        inspect past runs from their traces
- *   kraftwerk ui                      start the inspector web UI (localhost:4499)
+ *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -254,7 +254,7 @@ runs
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")
-    .option("--port <port>", "Port for the web UI", "4499")
+    .option("--port <port>", "Port for the web UI", "1981")
     .option("--output <dir>", "Output directory to inspect (default: the project's output dir)")
     .action(async (opts) => {
     await runUi(process.cwd(), opts);

package/dist/cli/ui.js

@@ -45,7 +45,7 @@ export async function runUi(cwd, opts) {
     const outputDir = opts.output
         ? path.resolve(cwd, opts.output)
         : (await resolveProject(cwd)).outputDir;
-    const port = Number(opts.port ?? "4499");
+    const port = Number(opts.port ?? "1981");
     await startInspector({ outputDir, staticDir, port });
     console.log(`${chalk.green("✔")} Inspector: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));

package/dist/inspector/chat/acp.d.ts

@@ -0,0 +1,2 @@
+import type { BackendHooks, ChatBackend } from "./backend.js";
+export declare function startAcpBackend(agent: "claude" | "codex", cwd: string, hooks: BackendHooks): Promise<ChatBackend>;

package/dist/inspector/chat/acp.js

@@ -0,0 +1,122 @@
+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";
+/**
+ * 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.
+ */
+const ADAPTERS = {
+    claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
+    codex: "@agentclientprotocol/codex-acp/dist/index.js",
+};
+function contentText(content) {
+    return content.type === "text" ? content.text : "";
+}
+export async function startAcpBackend(agent, cwd, hooks) {
+    const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
+    const child = spawn(process.execPath, [entry], {
+        cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+        env: process.env,
+    });
+    let stderr = "";
+    child.stderr.on("data", (c) => {
+        stderr += c.toString("utf8");
+        if (stderr.length > 20_000)
+            stderr = stderr.slice(-20_000);
+    });
+    let dead = false;
+    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;
+            switch (u.sessionUpdate) {
+                case "agent_message_chunk": {
+                    const text = contentText(u.content);
+                    if (text)
+                        hooks.emit({ type: "text", text });
+                    break;
+                }
+                case "agent_thought_chunk": {
+                    const text = contentText(u.content);
+                    if (text)
+                        hooks.emit({ type: "thought", text });
+                    break;
+                }
+                case "tool_call":
+                    hooks.emit({
+                        type: "tool_call",
+                        callId: u.toolCallId,
+                        title: u.title,
+                        kind: u.kind ?? undefined,
+                        status: u.status ?? undefined,
+                    });
+                    break;
+                case "tool_call_update":
+                    hooks.emit({
+                        type: "tool_update",
+                        callId: u.toolCallId,
+                        title: u.title ?? undefined,
+                        status: u.status ?? undefined,
+                    });
+                    break;
+                // plans, mode/config updates etc. carry no thread content — skip.
+            }
+        },
+        async requestPermission(params) {
+            const optionId = await hooks.askPermission(params.toolCall.title ?? params.toolCall.toolCallId, params.options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })));
+            return optionId
+                ? { outcome: { outcome: "selected", optionId } }
+                : { 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 session = await conn.newSession({ cwd, mcpServers: [] });
+    const sessionId = session.sessionId;
+    return {
+        async prompt(text) {
+            if (dead)
+                throw new Error(`${agent} agent process is gone — start a new chat`);
+            try {
+                const res = await conn.prompt({
+                    sessionId,
+                    prompt: [{ type: "text", text }],
+                });
+                return res.stopReason;
+            }
+            catch (err) {
+                if (err instanceof RequestError)
+                    throw new Error(`${agent} agent: ${err.message}`);
+                throw err;
+            }
+        },
+        cancel() {
+            if (!dead)
+                void conn.cancel({ sessionId }).catch(() => { });
+        },
+        dispose() {
+            if (!dead)
+                child.kill("SIGTERM");
+        },
+    };
+}

package/dist/inspector/chat/backend.d.ts

@@ -0,0 +1,28 @@
+import type { ChatEvent } from "./types.js";
+/**
+ * A chat backend is one live agent conversation: prompt() runs a full turn
+ * (resolves when the agent finishes), streaming intermediate activity
+ * through the hooks. ACP agents (claude, codex) keep a subprocess alive for
+ * the whole chat; pi respawns per message and resumes via --session-id.
+ */
+export interface BackendHooks {
+    /** Stream a thread event (text chunk, tool call, ...) to the session. */
+    emit(ev: ChatEvent): void;
+    /**
+     * Surface a permission request to the user; resolves with the chosen
+     * optionId, or null when the user (or a cancel) dismissed it.
+     */
+    askPermission(title: string, options: Array<{
+        optionId: string;
+        name: string;
+        kind?: string;
+    }>): Promise<string | null>;
+}
+export interface ChatBackend {
+    /** Send one user message; resolves with the stop reason at turn end. */
+    prompt(text: string): Promise<string>;
+    /** Interrupt the current turn (the running prompt() still resolves). */
+    cancel(): void;
+    /** Kill the agent subprocess, if any. */
+    dispose(): void;
+}

package/dist/inspector/chat/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/inspector/chat/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Chat data model shared across the chat backend modules. Every chat is a
+ * folder under <output>/chats/ holding meta.json plus events.jsonl — the
+ * same files-on-disk philosophy as runs. Events are the single source of
+ * truth: the UI replays them to render the thread, and the SSE stream just
+ * appends live ones.
+ */
+export type ChatAgentId = "claude" | "codex" | "pi";
+export type ChatScope = {
+    kind: "general";
+} | {
+    kind: "kraftwerk";
+} | {
+    kind: "run";
+    runId: string;
+};
+export interface ChatMeta {
+    id: string;
+    agent: ChatAgentId;
+    title: string;
+    cwd: string;
+    scope: ChatScope;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One thread event; `seq` orders them and drives SSE resume (?after=seq). */
+export type ChatEvent = {
+    type: "user_message";
+    text: string;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "thought";
+    text: string;
+} | {
+    type: "tool_call";
+    callId: string;
+    title: string;
+    kind?: string;
+    status?: string;
+} | {
+    type: "tool_update";
+    callId: string;
+    title?: string;
+    status?: string;
+} | {
+    type: "permission_request";
+    requestId: string;
+    title: string;
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind?: string;
+    }>;
+} | {
+    type: "permission_resolved";
+    requestId: string;
+    optionId: string | null;
+} | {
+    type: "turn_end";
+    stopReason: string;
+} | {
+    type: "error";
+    message: string;
+};
+export type StoredChatEvent = ChatEvent & {
+    seq: number;
+    ts: string;
+};

package/dist/inspector/chat/types.js

@@ -0,0 +1,8 @@
+/**
+ * Chat data model shared across the chat backend modules. Every chat is a
+ * folder under <output>/chats/ holding meta.json plus events.jsonl — the
+ * same files-on-disk philosophy as runs. Events are the single source of
+ * truth: the UI replays them to render the thread, and the SSE stream just
+ * appends live ones.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Deterministic workflow-as-code framework: agents (persona + model + tools + harness) run in bounded phases on headless CLI harnesses (claude -p, codex exec, pi); code owns the control flow, envelopes + gates judge the results",
   "keywords": [
     "agents",
@@ -55,6 +55,9 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "^0.70.0",
+    "@agentclientprotocol/codex-acp": "^1.6.2",
+    "@agentclientprotocol/sdk": "^1.4.0",
     "@inquirer/prompts": "^8.5.2",
     "ajv": "^8.20.0",
     "chalk": "^6.0.0",