@netnodeag/kraftwerk 0.2.0 → 0.3.1

package/README.md

@@ -22,6 +22,12 @@ npx @netnodeag/kraftwerk init      # scaffold kraftwerk.yml + workflows/ + examp
 npx @netnodeag/kraftwerk run hello "Was ist kraftwerk?"
 ```
 
+Your own workflows are just more folders under `workflows/` — a
+`workflow.yml` plus prompt files, discovered automatically (see
+[YAML workflows](#yaml-workflows)). Or let a coding agent build one:
+`npx @netnodeag/kraftwerk create "<what it should do>"` prints a
+self-contained brief that Claude Code / Codex follows end to end.
+
 For a local checkout / programmatic consumer (TS workflows, custom gates,
 approval loops), add the dependency (the `kraftwerk` alias keeps imports
 short):
@@ -50,6 +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 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
@@ -333,7 +340,8 @@ 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) — no
-`src/`, examples, or inspector. Check with `npm pack --dry-run` before a
+(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.

package/dist/cli/kraftwerk.js

@@ -12,6 +12,7 @@ import { renderCreateBrief } from "./create-brief.js";
 import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { listRuns, showRun } from "./runs.js";
+import { runUi } from "./ui.js";
 /**
  * kraftwerk — the kraftwerk CLI.
  *
@@ -19,6 +20,7 @@ import { listRuns, showRun } from "./runs.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 doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -249,6 +251,14 @@ runs
     .action(async (runId, opts) => {
     await showRun(process.cwd(), runId, opts);
 });
+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("--output <dir>", "Output directory to inspect (default: the project's output dir)")
+    .action(async (opts) => {
+    await runUi(process.cwd(), opts);
+});
 const runner = program
     .command("runner")
     .description("Manage the Docker sandbox runner (build the image, see/stop running runs)");

package/dist/cli/ui.d.ts

@@ -0,0 +1,4 @@
+export declare function runUi(cwd: string, opts: {
+    port?: string;
+    output?: string;
+}): Promise<void>;

package/dist/cli/ui.js

@@ -0,0 +1,75 @@
+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 chalk from "chalk";
+import { resolveProject } from "../config.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.
+ */
+/** 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.
+ */
+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");
+            },
+        });
+    }
+    return dest;
+}
+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 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);
+        }
+    }
+    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/inspector/README.md

@@ -0,0 +1,67 @@
+# kraftwerk inspector
+
+Web UI to look into the `output/` folder of a kraftwerk consumer project:
+all runs at a glance, live phase timelines while a run executes, and every
+file per run with inline preview (HTML reports render in place, text tails
+live, images display).
+
+## Run
+
+```bash
+kraftwerk ui       # from any consumer project — installs deps on first launch,
+                   # points at the project's output dir; --port, --output
+```
+
+Or directly from a checkout:
+
+```bash
+cd inspector
+npm install
+npm run dev        # http://localhost:4499
+```
+
+By default it inspects `../../agent-playground/output` (the playground next
+to this repo). Point it anywhere else with:
+
+```bash
+KRAFTWERK_OUTPUT=/path/to/your-project/output npm run dev
+```
+
+## What it shows
+
+- **Run index** — every `run-*` folder: workflow, request, status lamp
+  (ok / running / failed / aborted), phase progress, duration, cost.
+  Running runs tick live.
+- **Run detail** — the phase timeline parsed from `trace.jsonl`: agent +
+  model chips, attempts, duration, token and cost figures, gate results
+  (including failure messages), envelope summaries, and for the running
+  phase the last tool activity. Steps that have not started yet appear as
+  pending — the `run_start` trace event declares them.
+- **Files** — all files of the run dir with size; click to view. `.html`
+  renders in a sandboxed iframe (reports look like reports), images render
+  inline, everything else is text with live tail while the run is active.
+- **Workflows** — browses `src/workflows/` (or `workflows/`) of the same
+  project: every workflow as a card, and per workflow a visualization of
+  how it is built — agent cards (model, tools, persona) with identity
+  colors, the step pipeline in order with each step's resolved prompt or
+  script (file references are inlined), the gates per step, the workflow
+  folder contents, and links to recent runs of that workflow. Broken
+  YAML still shows up, flagged with its parse error.
+
+- **Trigger runs** — every workflow page has a "trigger run" panel: enter a
+  request and launch. Default is the **Docker sandbox** (one
+  `kraftwerk-runner` container per run, workflow mounted read-only, run dir
+  bind-mounted back into `output/` so the live timeline works unchanged;
+  build the image once with `kraftwerk runner build`). Optional: forward
+  the SSH agent, or run locally instead. Sandboxed runs show a "sandbox"
+  chip and a stop button while running (`docker stop` under the hood).
+  Env vars for sandboxed runs go into `<project>/runner.env`.
+
+Realtime is plain polling (1.5 s while something runs, 6 s otherwise) —
+no daemon, no socket, works on a plain filesystem.
+
+## Requirements
+
+Traces written by kraftwerk ≥ the `run_start` event carry workflow
+name, request, and the declared step list; older traces still render, only
+without those labels.

package/inspector/app/api/runs/[id]/file/route.ts

@@ -0,0 +1,56 @@
+import { promises as fs } from "node:fs";
+import { NextResponse } from "next/server";
+import { readRunFile } from "@/lib/runs";
+
+export const dynamic = "force-dynamic";
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".pdf": "application/pdf",
+  ".json": "application/json; charset=utf-8",
+};
+
+/** Text preview payloads are capped; the tail matters most for logs. */
+const MAX_TEXT = 400_000;
+
+export async function GET(req: Request, ctx: { params: Promise<{ id: string }> }) {
+  const { id } = await ctx.params;
+  const url = new URL(req.url);
+  const name = url.searchParams.get("name") ?? "";
+  const raw = url.searchParams.get("raw") === "1";
+
+  let file;
+  try {
+    file = await readRunFile(id, name);
+  } catch {
+    return NextResponse.json({ error: "invalid request" }, { status: 400 });
+  }
+  if (!file) return NextResponse.json({ error: "not found" }, { status: 404 });
+
+  const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+
+  if (raw) {
+    const buf = await fs.readFile(file.absPath);
+    return new NextResponse(new Uint8Array(buf), {
+      headers: {
+        "content-type": TYPES[ext] ?? "text/plain; charset=utf-8",
+        "cache-control": "no-store",
+      },
+    });
+  }
+
+  const buf = await fs.readFile(file.absPath);
+  let text = buf.toString("utf8");
+  let truncated = false;
+  if (text.length > MAX_TEXT) {
+    text = text.slice(-MAX_TEXT);
+    truncated = true;
+  }
+  return NextResponse.json({ name, size: file.size, truncated, content: text });
+}

package/inspector/app/api/runs/[id]/route.ts

@@ -0,0 +1,15 @@
+import { NextResponse } from "next/server";
+import { getRun } from "@/lib/runs";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(_req: Request, ctx: { params: Promise<{ id: string }> }) {
+  const { id } = await ctx.params;
+  try {
+    const run = await getRun(id);
+    if (!run) return NextResponse.json({ error: "not found" }, { status: 404 });
+    return NextResponse.json(run);
+  } catch {
+    return NextResponse.json({ error: "invalid run id" }, { status: 400 });
+  }
+}

package/inspector/app/api/runs/[id]/stop/route.ts

@@ -0,0 +1,15 @@
+import { NextResponse } from "next/server";
+import { stopRun } from "@/lib/runner";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(_req: Request, ctx: { params: Promise<{ id: string }> }) {
+  const { id } = await ctx.params;
+  const stopped = stopRun(id);
+  return stopped
+    ? NextResponse.json({ stopped: true })
+    : NextResponse.json(
+        { error: "no running sandbox container for this run (local runs cannot be stopped here)" },
+        { status: 404 }
+      );
+}

package/inspector/app/api/runs/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from "next/server";
+import { listRuns, OUTPUT_DIR } from "@/lib/runs";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const runs = await listRuns();
+  return NextResponse.json({ outputDir: OUTPUT_DIR, runs });
+}

package/inspector/app/api/workflows/[slug]/route.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from "next/server";
+import { getWorkflow } from "@/lib/workflows";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(_req: Request, ctx: { params: Promise<{ slug: string }> }) {
+  const { slug } = await ctx.params;
+  const wf = await getWorkflow(slug);
+  if (!wf) return NextResponse.json({ error: "not found" }, { status: 404 });
+  return NextResponse.json(wf);
+}

package/inspector/app/api/workflows/[slug]/run/route.ts

@@ -0,0 +1,37 @@
+import { NextResponse } from "next/server";
+import { getWorkflow } from "@/lib/workflows";
+import { triggerRun, dockerStatus } from "@/lib/runner";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return NextResponse.json(dockerStatus());
+}
+
+export async function POST(req: Request, ctx: { params: Promise<{ slug: string }> }) {
+  const { slug } = await ctx.params;
+  const wf = await getWorkflow(decodeURIComponent(slug));
+  if (!wf || wf.error || !wf.name) {
+    return NextResponse.json({ error: "workflow not found or broken" }, { status: 404 });
+  }
+  let body: { request?: string; sandbox?: boolean; ssh?: boolean };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "invalid JSON body" }, { status: 400 });
+  }
+  const request = (body.request ?? "").trim();
+  if (!request) return NextResponse.json({ error: "request text is required" }, { status: 400 });
+
+  try {
+    const { runId } = triggerRun({
+      workflowName: wf.name,
+      request,
+      sandbox: body.sandbox ?? true,
+      ssh: !!body.ssh,
+    });
+    return NextResponse.json({ runId });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 503 });
+  }
+}

package/inspector/app/api/workflows/route.ts

@@ -0,0 +1,8 @@
+import { NextResponse } from "next/server";
+import { listWorkflows } from "@/lib/workflows";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return NextResponse.json(await listWorkflows());
+}