@netnodeag/kraftwerk 0.3.1 → 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
@@ -340,8 +340,10 @@ npm publish         # runs npm run build first via prepublishOnly
 ```
 
 The tarball is whitelisted via `files`: `bin/`, `dist/`, `runner/`
-(Dockerfile for sandboxed runs), `schema/` (workflow JSON schema), and the
-inspector sources (for `kraftwerk ui`; its deps install on first launch) —
-no `src/` or examples. Check with `npm pack --dry-run` before a
-release. Runtime deps stay regular `dependencies`; `tsx` and `typescript`
-are dev-only, so consumers install neither.
+(Dockerfile for sandboxed runs), `schema/` (workflow JSON schema), and
+`inspector/dist/` (the prebuilt web UI for `kraftwerk ui` — built by
+`prepublishOnly`, served by the dependency-free server compiled into
+`dist/inspector/`) — no `src/` or examples. Check with `npm pack
+--dry-run` before a release. Runtime deps stay regular `dependencies`;
+`tsx`, `typescript`, and the inspector's Vite/React toolchain are
+dev-only, so consumers install none of them.

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

@@ -1,75 +1,52 @@
 import { existsSync } from "node:fs";
-import { cp, readFile } from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import chalk from "chalk";
 import { resolveProject } from "../config.js";
+import { startInspector } from "../inspector/server.js";
 /**
- * `kraftwerk ui` — start the inspector web UI (Next.js app shipped in the
- * package under inspector/) pointed at the current project's output dir.
- * First launch installs the inspector's dependencies; the server then runs
- * in the foreground until Ctrl-C.
+ * `kraftwerk ui` — start the inspector web UI pointed at the current
+ * project's output dir. The server is dependency-free node:http (part of
+ * this package); the frontend is a prebuilt Vite bundle shipped in
+ * inspector/dist. Nothing to install at runtime — the server starts
+ * instantly and runs in the foreground until Ctrl-C.
  */
 /** Package root is two levels up from this file (src/cli/ or dist/cli/). */
 const packageRoot = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../..");
-const inNodeModules = (p) => p.split(path.sep).includes("node_modules");
 /**
- * The inspector cannot run in place from an installed package: Next.js
- * excludes everything under node_modules/ from compilation, so its .ts/.tsx
- * sources would be served raw. Installed copies are materialized (sources
- * only) into ~/.cache/kraftwerk/inspector-<version>/ and run from there;
- * dev checkouts run in place.
+ * Published packages ship inspector/dist. A dev checkout builds it on
+ * first use (and after frontend edits: `npm run build` in inspector/).
  */
-async function materializeInspector() {
-    const src = path.join(packageRoot(), "inspector");
-    if (!inNodeModules(src))
-        return src;
-    const pkg = JSON.parse(await readFile(path.join(packageRoot(), "package.json"), "utf8"));
-    const dest = path.join(os.homedir(), ".cache", "kraftwerk", `inspector-${pkg.version}`);
-    if (!existsSync(path.join(dest, "package.json"))) {
-        await cp(src, dest, {
-            recursive: true,
-            filter: (s) => {
-                const parts = path.relative(src, s).split(path.sep);
-                return !parts.includes("node_modules") && !parts.includes(".next");
-            },
-        });
+function ensureBuilt() {
+    const inspector = path.join(packageRoot(), "inspector");
+    const dist = path.join(inspector, "dist");
+    if (existsSync(path.join(dist, "index.html")))
+        return dist;
+    if (!existsSync(path.join(inspector, "src"))) {
+        console.error(chalk.red(`Inspector assets missing at ${dist} — broken install?`));
+        process.exit(1);
     }
-    return dest;
+    console.log(chalk.dim("Building the inspector frontend (first use in this checkout) ..."));
+    for (const args of [
+        ...(existsSync(path.join(inspector, "node_modules")) ? [] : [["install", "--no-fund", "--no-audit"]]),
+        ["run", "build"],
+    ]) {
+        const r = spawnSync("npm", args, { cwd: inspector, stdio: "inherit" });
+        if (r.status !== 0) {
+            console.error(chalk.red(`npm ${args.join(" ")} failed in inspector/.`));
+            process.exit(1);
+        }
+    }
+    return dist;
 }
 export async function runUi(cwd, opts) {
-    if (!existsSync(path.join(packageRoot(), "inspector", "package.json"))) {
-        console.error(chalk.red(`Inspector not found at ${path.join(packageRoot(), "inspector")} — broken install?`));
-        process.exit(1);
-    }
-    const dir = await materializeInspector();
+    const staticDir = ensureBuilt();
     const outputDir = opts.output
         ? path.resolve(cwd, opts.output)
         : (await resolveProject(cwd)).outputDir;
-    const port = opts.port ?? "4499";
-    if (!existsSync(path.join(dir, "node_modules"))) {
-        console.log(chalk.dim("First launch — installing inspector dependencies ..."));
-        const install = spawnSync("npm", ["install", "--no-fund", "--no-audit"], {
-            cwd: dir,
-            stdio: "inherit",
-        });
-        if (install.status !== 0) {
-            console.error(chalk.red("npm install failed in the inspector directory."));
-            process.exit(1);
-        }
-    }
+    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})`));
-    const nextBin = path.join(dir, "node_modules", "next", "dist", "bin", "next");
-    const child = spawn(process.execPath, [nextBin, "dev", "-p", port], {
-        cwd: dir,
-        stdio: "inherit",
-        env: { ...process.env, KRAFTWERK_OUTPUT: outputDir },
-    });
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-        process.on(signal, () => child.kill(signal));
-    }
-    child.on("exit", (code) => process.exit(code ?? 0));
 }

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/dist/inspector/context.d.ts

@@ -0,0 +1,5 @@
+export declare function setOutputDir(dir: string): void;
+/** Absolute output directory (one run-* folder per run). */
+export declare function getOutputDir(): string;
+/** The consumer project root is the parent of the output dir. */
+export declare function getProjectRoot(): string;

package/dist/inspector/context.js

@@ -0,0 +1,19 @@
+import path from "node:path";
+/**
+ * Server-side context for the inspector: which consumer project it looks at.
+ * Set once by startInspector() before any request is served.
+ */
+let outputDir = "";
+export function setOutputDir(dir) {
+    outputDir = path.resolve(dir);
+}
+/** Absolute output directory (one run-* folder per run). */
+export function getOutputDir() {
+    if (!outputDir)
+        throw new Error("inspector context not initialized");
+    return outputDir;
+}
+/** The consumer project root is the parent of the output dir. */
+export function getProjectRoot() {
+    return path.dirname(getOutputDir());
+}

package/dist/inspector/runner.d.ts

@@ -0,0 +1,13 @@
+export declare function dockerStatus(): {
+    available: boolean;
+    image: boolean;
+};
+export declare function triggerRun(opts: {
+    workflowName: string;
+    request: string;
+    sandbox: boolean;
+    ssh: boolean;
+}): {
+    runId: string;
+};
+export declare function stopRun(runId: string): boolean;

package/dist/inspector/runner.js

@@ -0,0 +1,66 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, openSync, closeSync } from "node:fs";
+import path from "node:path";
+import { getProjectRoot } from "./context.js";
+/**
+ * Workflow trigger for the web UI. The inspector stays decoupled from the
+ * framework runtime: it shells out to `npx kraftwerk run` in the consumer
+ * project, detached, with a pre-chosen --run-id so the browser can jump to
+ * /runs/<id> immediately and watch the (already polling) live timeline.
+ *
+ * Sandbox mode adds --sandbox: one Docker container per run, workflow
+ * mounted read-only, run dir bind-mounted back into output/ (see
+ * kraftwerk/src/runner/docker.ts).
+ */
+function stamp(d = new Date()) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}-${p(d.getSeconds())}`;
+}
+export function dockerStatus() {
+    const daemon = spawnSync("docker", ["version", "--format", "ok"], {
+        stdio: "ignore",
+        timeout: 8000,
+    });
+    if (daemon.status !== 0)
+        return { available: false, image: false };
+    const image = spawnSync("docker", ["image", "inspect", "kraftwerk-runner"], {
+        stdio: "ignore",
+        timeout: 8000,
+    });
+    return { available: true, image: image.status === 0 };
+}
+export function triggerRun(opts) {
+    if (opts.sandbox) {
+        const docker = dockerStatus();
+        if (!docker.available)
+            throw new Error("Docker daemon not reachable — start Docker first.");
+        if (!docker.image)
+            throw new Error('Image "kraftwerk-runner" missing — run `kraftwerk runner build`.');
+    }
+    const runId = `run-${stamp()}`;
+    // Matches the CLI's --run-id resolution: output/<id> under the project root.
+    const runDir = path.join(getProjectRoot(), "output", runId);
+    mkdirSync(runDir, { recursive: true });
+    const log = openSync(path.join(runDir, "trigger.log"), "a");
+    const args = ["kraftwerk", "run", "--yes", "--run-id", runId];
+    if (opts.sandbox)
+        args.push("--sandbox");
+    if (opts.ssh)
+        args.push("--ssh");
+    args.push(opts.workflowName, opts.request);
+    const child = spawn("npx", args, {
+        cwd: getProjectRoot(),
+        detached: true,
+        stdio: ["ignore", log, log],
+        env: { ...process.env, FORCE_COLOR: "0" },
+    });
+    child.unref();
+    closeSync(log);
+    return { runId };
+}
+export function stopRun(runId) {
+    // Sandboxed runs run in container kw-<runId>; docker stop ends them.
+    if (!/^run-[0-9-]+$/.test(runId))
+        return false;
+    return (spawnSync("docker", ["stop", `kw-${runId}`], { stdio: "ignore", timeout: 30_000 }).status === 0);
+}

package/dist/inspector/runs.d.ts

@@ -0,0 +1,57 @@
+export type RunStatus = "running" | "ok" | "failed" | "aborted";
+export interface GateView {
+    gate: string;
+    passed: boolean;
+    failure: string | null;
+}
+export interface PhaseView {
+    phase: string;
+    kind: "agent" | "script";
+    agent?: string;
+    model?: string;
+    harness?: string;
+    status: "running" | "ok" | "failed" | "blocked" | "pending";
+    attempts: number;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    gates: GateView[];
+    summary?: string;
+    lastActivity?: string;
+    stdout?: string;
+    stderr?: string;
+}
+export interface FileView {
+    name: string;
+    size: number;
+    mtime: string;
+}
+export interface RunListItem {
+    id: string;
+    workflow?: string;
+    request?: string;
+    status: RunStatus;
+    startedAt?: string;
+    updatedAt: string;
+    phasesDone: number;
+    phasesTotal?: number;
+    currentPhase?: string;
+    durationMs?: number;
+    costUsd?: number;
+}
+export interface RunDetail extends RunListItem {
+    description?: string;
+    steps?: string[];
+    phases: PhaseView[];
+    files: FileView[];
+}
+export declare function listRuns(): Promise<RunListItem[]>;
+export declare function safeRunDir(id: string): string;
+export declare function getRun(id: string): Promise<RunDetail | null>;
+export declare function readRunFile(id: string, name: string): Promise<{
+    absPath: string;
+    size: number;
+} | null>;