@netnodeag/kraftwerk 0.3.1 → 0.4.1

package/dist/inspector/runs.js

@@ -0,0 +1,240 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getOutputDir } from "./context.js";
+/**
+ * Filesystem + trace.jsonl reading for the inspector. The output directory
+ * holds one folder per run (run-YYYY-MM-DD-HHMM-SS); every run folder has a
+ * trace.jsonl written by the framework plus the run's working files.
+ */
+/** A run with no trace update for this long and no summary counts as aborted. */
+const STALE_MS = 15 * 60 * 1000;
+async function readTrace(runDir) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(runDir, "trace.jsonl"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            /* partially written last line of a live run */
+        }
+    }
+    return events;
+}
+function analyse(events) {
+    const runStart = events.find((e) => e.event === "run_start");
+    const summary = events.find((e) => e.event === "run_summary");
+    const phases = [];
+    const byName = new Map();
+    for (const e of events) {
+        if (e.event === "phase_start") {
+            const p = {
+                phase: e.phase,
+                kind: e.kind === "script" ? "script" : "agent",
+                agent: e.agent,
+                model: e.model,
+                harness: e.harness,
+                status: "running",
+                attempts: 0,
+                startedAt: e.ts,
+                gates: [],
+            };
+            phases.push(p);
+            byName.set(e.phase, p);
+            continue;
+        }
+        const p = byName.get(e.phase);
+        if (!p)
+            continue;
+        switch (e.event) {
+            case "tool_use":
+                p.lastActivity = `${e.tool} ${e.target ? shortenPath(e.target) : ""}`.trim();
+                break;
+            case "agent_result":
+                p.attempts = (e.attempt ?? 0) + 1;
+                break;
+            case "script_result":
+                p.attempts += 1;
+                p.stdout = e.stdout || undefined;
+                p.stderr = e.stderr || undefined;
+                break;
+            case "envelope":
+                p.summary = e.envelope?.summary;
+                break;
+            case "gate_result":
+                p.gates.push({ gate: e.gate, passed: e.passed, failure: e.failure ?? null });
+                break;
+            case "phase_end":
+                p.status = e.status === "ok" ? "ok" : e.status === "blocked" ? "blocked" : "failed";
+                p.endedAt = e.ts;
+                if (e.stats) {
+                    p.durationMs = e.stats.durationMs;
+                    p.costUsd = e.stats.costUsd;
+                    p.tokensIn =
+                        (e.stats.inputTokens ?? 0) +
+                            (e.stats.cacheReadTokens ?? 0) +
+                            (e.stats.cacheCreationTokens ?? 0);
+                    p.tokensOut = e.stats.outputTokens ?? 0;
+                    p.attempts = e.stats.attempts ?? p.attempts;
+                }
+                break;
+        }
+    }
+    // Only keep the last attempt's gate results per gate name.
+    for (const p of phases) {
+        const last = new Map();
+        for (const g of p.gates)
+            last.set(g.gate, g);
+        p.gates = [...last.values()];
+    }
+    // Steps declared at run_start that have not started yet are pending.
+    // run_start.steps is either string[] (older traces) or {name, kind, agent, model}[].
+    const rawSteps = runStart?.steps;
+    const steps = rawSteps?.map((s) => (typeof s === "string" ? s : s.name));
+    if (rawSteps) {
+        for (const s of rawSteps) {
+            const name = typeof s === "string" ? s : s.name;
+            if (!byName.has(name)) {
+                phases.push({
+                    phase: name,
+                    kind: typeof s === "string" ? "script" : s.kind,
+                    agent: typeof s === "string" ? undefined : s.agent,
+                    model: typeof s === "string" ? undefined : s.model,
+                    status: "pending",
+                    attempts: 0,
+                    gates: [],
+                });
+            }
+        }
+    }
+    const failed = phases.some((p) => p.status === "failed" || p.status === "blocked");
+    const lastTs = events.length ? events[events.length - 1].ts : undefined;
+    let status;
+    if (summary)
+        status = failed ? "failed" : "ok";
+    else if (failed)
+        status = "failed";
+    else if (lastTs && Date.now() - Date.parse(lastTs) > STALE_MS)
+        status = "aborted";
+    else
+        status = "running";
+    return { runStart, summary, phases, steps, status, lastTs };
+}
+/**
+ * Sandboxed runs write runner.json (exit code recorded when the container
+ * ends). If the trace looks "running" but the container already exited —
+ * e.g. it crashed before any phase_end — trust the exit code instead of
+ * waiting for the 15-minute stale timeout.
+ */
+async function applyRunnerVerdict(runDir, a) {
+    if (a.status !== "running")
+        return a;
+    try {
+        const meta = JSON.parse(await fs.readFile(path.join(runDir, "runner.json"), "utf8"));
+        if (meta.exitCode != null) {
+            a.status = meta.exitCode === 0 ? "ok" : "failed";
+            if (meta.exitCode !== 0) {
+                for (const p of a.phases)
+                    if (p.status === "running")
+                        p.status = "failed";
+            }
+        }
+    }
+    catch {
+        /* no runner.json (local run) or unreadable — keep trace-based status */
+    }
+    return a;
+}
+function shortenPath(p) {
+    const parts = p.split("/");
+    return parts.length > 2 ? parts.slice(-2).join("/") : p;
+}
+export async function listRuns() {
+    let entries;
+    try {
+        entries = (await fs.readdir(getOutputDir())).filter((e) => e.startsWith("run-"));
+    }
+    catch {
+        return [];
+    }
+    const items = await Promise.all(entries.map(async (id) => {
+        const runDir = path.join(getOutputDir(), id);
+        const st = await fs.stat(runDir).catch(() => null);
+        if (!st?.isDirectory())
+            return null;
+        const events = await readTrace(runDir);
+        const { runStart, summary, phases, steps, status, lastTs } = await applyRunnerVerdict(runDir, analyse(events));
+        const done = phases.filter((p) => p.status === "ok").length;
+        const current = phases.find((p) => p.status === "running")?.phase;
+        return {
+            id,
+            workflow: runStart?.workflow,
+            request: runStart?.request,
+            status,
+            startedAt: events[0]?.ts,
+            updatedAt: lastTs ?? st.mtime.toISOString(),
+            phasesDone: done,
+            phasesTotal: steps?.length ?? (summary ? phases.length : undefined),
+            currentPhase: current,
+            durationMs: summary?.total?.durationMs,
+            costUsd: summary?.total?.costUsd,
+        };
+    }));
+    return items.filter(Boolean).sort((a, b) => b.id.localeCompare(a.id));
+}
+export function safeRunDir(id) {
+    if (!/^run-[0-9-]+$/.test(id))
+        throw new Error("invalid run id");
+    return path.join(getOutputDir(), id);
+}
+export async function getRun(id) {
+    const runDir = safeRunDir(id);
+    const st = await fs.stat(runDir).catch(() => null);
+    if (!st?.isDirectory())
+        return null;
+    const events = await readTrace(runDir);
+    const { runStart, summary, phases, steps, status, lastTs } = await applyRunnerVerdict(runDir, analyse(events));
+    const names = await fs.readdir(runDir);
+    const files = [];
+    for (const name of names) {
+        const fst = await fs.stat(path.join(runDir, name)).catch(() => null);
+        if (fst?.isFile())
+            files.push({ name, size: fst.size, mtime: fst.mtime.toISOString() });
+    }
+    files.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        id,
+        workflow: runStart?.workflow,
+        description: runStart?.description,
+        request: runStart?.request,
+        status,
+        startedAt: events[0]?.ts,
+        updatedAt: lastTs ?? st.mtime.toISOString(),
+        phasesDone: phases.filter((p) => p.status === "ok").length,
+        phasesTotal: steps?.length ?? (summary ? phases.length : undefined),
+        currentPhase: phases.find((p) => p.status === "running")?.phase,
+        durationMs: summary?.total?.durationMs,
+        costUsd: summary?.total?.costUsd,
+        steps,
+        phases,
+        files,
+    };
+}
+export async function readRunFile(id, name) {
+    const runDir = safeRunDir(id);
+    const absPath = path.resolve(runDir, name);
+    if (absPath !== path.join(runDir, path.basename(name)))
+        throw new Error("invalid file name");
+    const st = await fs.stat(absPath).catch(() => null);
+    if (!st?.isFile())
+        return null;
+    return { absPath, size: st.size };
+}

package/dist/inspector/server.d.ts

@@ -0,0 +1,8 @@
+import http from "node:http";
+export interface InspectorOptions {
+    outputDir: string;
+    staticDir: string;
+    port: number;
+}
+/** Start the server; resolves once it listens. Runs until the process ends. */
+export declare function startInspector(opts: InspectorOptions): Promise<http.Server>;

package/dist/inspector/server.js

@@ -0,0 +1,186 @@
+import { promises as fs } from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { setOutputDir, getOutputDir } from "./context.js";
+import { listRuns, getRun, readRunFile } from "./runs.js";
+import { listWorkflows, getWorkflow } from "./workflows.js";
+import { dockerStatus, triggerRun, stopRun } from "./runner.js";
+/**
+ * The inspector server: a plain node:http server with no dependencies.
+ * Serves the prebuilt SPA (inspector/dist) plus the JSON/file API the
+ * frontend polls. Realtime is polling — no daemon, no socket, works on a
+ * plain filesystem.
+ */
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".pdf": "application/pdf",
+    ".json": "application/json; charset=utf-8",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+};
+/** Text preview payloads are capped; the tail matters most for logs. */
+const MAX_TEXT = 400_000;
+function json(res, body, status = 200) {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", (c) => {
+            data += c;
+            if (data.length > 1_000_000)
+                reject(new Error("body too large"));
+        });
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}
+async function handleApi(req, res, url) {
+    const seg = url.pathname.split("/").filter(Boolean); // ["api", ...]
+    const method = req.method ?? "GET";
+    // GET /api/runs
+    if (seg.length === 2 && seg[1] === "runs" && method === "GET") {
+        return json(res, { outputDir: getOutputDir(), runs: await listRuns() });
+    }
+    // GET /api/runs/:id
+    if (seg.length === 3 && seg[1] === "runs" && method === "GET") {
+        try {
+            const run = await getRun(seg[2]);
+            return run ? json(res, run) : json(res, { error: "not found" }, 404);
+        }
+        catch {
+            return json(res, { error: "invalid run id" }, 400);
+        }
+    }
+    // GET /api/runs/:id/file?name=...&raw=1
+    if (seg.length === 4 && seg[1] === "runs" && seg[3] === "file" && method === "GET") {
+        const name = url.searchParams.get("name") ?? "";
+        const raw = url.searchParams.get("raw") === "1";
+        let file;
+        try {
+            file = await readRunFile(seg[2], name);
+        }
+        catch {
+            return json(res, { error: "invalid request" }, 400);
+        }
+        if (!file)
+            return json(res, { error: "not found" }, 404);
+        const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+        const buf = await fs.readFile(file.absPath);
+        if (raw) {
+            res.writeHead(200, {
+                "content-type": MIME[ext] ?? "text/plain; charset=utf-8",
+                "cache-control": "no-store",
+            });
+            return void res.end(buf);
+        }
+        let text = buf.toString("utf8");
+        let truncated = false;
+        if (text.length > MAX_TEXT) {
+            text = text.slice(-MAX_TEXT);
+            truncated = true;
+        }
+        return json(res, { name, size: file.size, truncated, content: text });
+    }
+    // POST /api/runs/:id/stop
+    if (seg.length === 4 && seg[1] === "runs" && seg[3] === "stop" && method === "POST") {
+        return stopRun(seg[2])
+            ? json(res, { stopped: true })
+            : json(res, { error: "no running sandbox container for this run (local runs cannot be stopped here)" }, 404);
+    }
+    // GET /api/workflows
+    if (seg.length === 2 && seg[1] === "workflows" && method === "GET") {
+        return json(res, await listWorkflows());
+    }
+    // GET /api/workflows/:slug
+    if (seg.length === 3 && seg[1] === "workflows" && method === "GET") {
+        const wf = await getWorkflow(decodeURIComponent(seg[2]));
+        return wf ? json(res, wf) : json(res, { error: "not found" }, 404);
+    }
+    // GET/POST /api/workflows/:slug/run
+    if (seg.length === 4 && seg[1] === "workflows" && seg[3] === "run") {
+        if (method === "GET")
+            return json(res, dockerStatus());
+        if (method === "POST") {
+            const wf = await getWorkflow(decodeURIComponent(seg[2]));
+            if (!wf || wf.error || !wf.name)
+                return json(res, { error: "workflow not found or broken" }, 404);
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                return json(res, { error: "invalid JSON body" }, 400);
+            }
+            const request = (body.request ?? "").trim();
+            if (!request)
+                return json(res, { error: "request text is required" }, 400);
+            try {
+                const { runId } = triggerRun({
+                    workflowName: wf.name,
+                    request,
+                    sandbox: body.sandbox ?? true,
+                    ssh: !!body.ssh,
+                });
+                return json(res, { runId });
+            }
+            catch (err) {
+                return json(res, { error: err.message }, 503);
+            }
+        }
+    }
+    json(res, { error: "not found" }, 404);
+}
+async function serveStatic(res, staticDir, pathname) {
+    // SPA: unknown paths fall back to index.html (routing is client-side).
+    const rel = pathname === "/" ? "index.html" : pathname.slice(1);
+    let abs = path.resolve(staticDir, rel);
+    if (!abs.startsWith(path.resolve(staticDir) + path.sep) && abs !== path.resolve(staticDir)) {
+        return json(res, { error: "not found" }, 404);
+    }
+    let buf = await fs.readFile(abs).catch(() => null);
+    if (buf === null) {
+        abs = path.join(staticDir, "index.html");
+        buf = await fs.readFile(abs).catch(() => null);
+    }
+    if (buf === null)
+        return json(res, { error: "inspector assets missing" }, 500);
+    const ext = path.extname(abs).toLowerCase();
+    res.writeHead(200, {
+        "content-type": MIME[ext] ?? "application/octet-stream",
+        // Vite emits content-hashed asset names; index.html must stay fresh.
+        "cache-control": abs.endsWith("index.html") ? "no-store" : "public, max-age=31536000, immutable",
+    });
+    res.end(buf);
+}
+/** Start the server; resolves once it listens. Runs until the process ends. */
+export function startInspector(opts) {
+    setOutputDir(opts.outputDir);
+    const server = http.createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (url.pathname.startsWith("/api/"))
+                await handleApi(req, res, url);
+            else
+                await serveStatic(res, opts.staticDir, url.pathname);
+        }
+        catch (err) {
+            json(res, { error: err.message }, 500);
+        }
+    });
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, () => resolve(server));
+    });
+}

package/dist/inspector/workflows.d.ts

@@ -0,0 +1,45 @@
+export interface AgentInfo {
+    id: string;
+    name?: string;
+    model?: string;
+    harness?: string;
+    effort?: string;
+    tools: string[];
+    persona?: string;
+}
+export interface StepInfo {
+    name: string;
+    kind: "agent" | "script";
+    agent?: string;
+    /** Resolved prompt text (agent steps). */
+    prompt?: string;
+    /** The file reference as written in the yml, if the value was a file ref. */
+    sourceRef?: string;
+    /** Resolved script text (script steps). */
+    script?: string;
+    gates: string[];
+}
+export interface WorkflowSummary {
+    slug: string;
+    name?: string;
+    description?: string;
+    agents: number;
+    steps: number;
+    error?: string;
+}
+export interface WorkflowDetail {
+    slug: string;
+    dir: string;
+    name?: string;
+    description?: string;
+    workspace?: string;
+    agents: AgentInfo[];
+    steps: StepInfo[];
+    files: string[];
+    error?: string;
+}
+export declare function listWorkflows(): Promise<{
+    root?: string;
+    workflows: WorkflowSummary[];
+}>;
+export declare function getWorkflow(slug: string): Promise<WorkflowDetail | null>;

package/dist/inspector/workflows.js

@@ -0,0 +1,186 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { getProjectRoot } from "./context.js";
+/**
+ * Workflow discovery + parsing for the inspector. Mirrors the kraftwerk CLI
+ * conventions (src/workflows/ or workflows/ under the project root, folder
+ * mode with workflow.yml or single .yml files) but parses the YAML raw, so
+ * even a workflow the framework would reject still renders — with its error.
+ */
+async function workflowsRoot() {
+    for (const candidate of ["src/workflows", "workflows"]) {
+        const p = path.join(getProjectRoot(), candidate);
+        const st = await fs.stat(p).catch(() => null);
+        if (st?.isDirectory())
+            return p;
+    }
+    return undefined;
+}
+function gateLabel(g) {
+    if (g == null)
+        return "?";
+    if (typeof g.file_non_empty === "string")
+        return `file_non_empty(${g.file_non_empty})`;
+    if (typeof g.slots_filled === "string")
+        return `slots_filled(${g.slots_filled})`;
+    if (g.contains)
+        return `contains(${g.contains.file}, ${g.contains.label ?? g.contains.text})`;
+    return JSON.stringify(g);
+}
+/** Folder mode: a single-line value references a file inside the folder. */
+async function resolveText(value, baseDir) {
+    if (typeof value !== "string")
+        return {};
+    const line = value.trim();
+    if (!baseDir || line.includes("\n"))
+        return { text: line };
+    const candidate = path.resolve(baseDir, line);
+    if (!candidate.startsWith(path.resolve(baseDir) + path.sep))
+        return { text: line };
+    const content = await fs.readFile(candidate, "utf8").catch(() => null);
+    if (content !== null)
+        return { text: content.trim(), sourceRef: line };
+    return { text: line };
+}
+async function listDirFiles(dir, prefix = "") {
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+        if (e.name.startsWith("."))
+            continue;
+        if (e.isDirectory()) {
+            out.push(...(await listDirFiles(path.join(dir, e.name), `${prefix}${e.name}/`)));
+        }
+        else {
+            out.push(`${prefix}${e.name}`);
+        }
+    }
+    return out.sort();
+}
+async function locate() {
+    const root = await workflowsRoot();
+    if (!root)
+        return [];
+    const found = [];
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            for (const f of ["workflow.yml", "workflow.yaml"]) {
+                const st = await fs.stat(path.join(entryPath, f)).catch(() => null);
+                if (st?.isFile()) {
+                    found.push({ slug: entry.name, yamlPath: path.join(entryPath, f), baseDir: entryPath });
+                    break;
+                }
+            }
+        }
+        else if (/\.ya?ml$/.test(entry.name)) {
+            found.push({ slug: entry.name.replace(/\.ya?ml$/, ""), yamlPath: entryPath, baseDir: null });
+        }
+    }
+    return found.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+async function parseRaw(l) {
+    const text = await fs.readFile(l.yamlPath, "utf8");
+    return parseYaml(text);
+}
+export async function listWorkflows() {
+    const root = await workflowsRoot();
+    const located = await locate();
+    const workflows = await Promise.all(located.map(async (l) => {
+        try {
+            const raw = await parseRaw(l);
+            return {
+                slug: l.slug,
+                name: raw?.name,
+                description: raw?.description,
+                agents: Object.keys(raw?.agents ?? {}).length,
+                steps: (raw?.steps ?? []).length,
+            };
+        }
+        catch (err) {
+            return { slug: l.slug, agents: 0, steps: 0, error: err.message };
+        }
+    }));
+    return { root, workflows };
+}
+export async function getWorkflow(slug) {
+    const located = await locate();
+    const l = located.find((x) => x.slug === slug) ??
+        // Fallback: match by workflow name (run traces carry the name, not the slug).
+        (await (async () => {
+            for (const x of located) {
+                try {
+                    if ((await parseRaw(x))?.name === slug)
+                        return x;
+                }
+                catch { }
+            }
+            return undefined;
+        })());
+    if (!l)
+        return null;
+    let raw;
+    try {
+        raw = await parseRaw(l);
+    }
+    catch (err) {
+        return {
+            slug: l.slug,
+            dir: path.dirname(l.yamlPath),
+            agents: [],
+            steps: [],
+            files: [],
+            error: err.message,
+        };
+    }
+    const agents = [];
+    for (const [id, a] of Object.entries(raw?.agents ?? {})) {
+        const persona = await resolveText(a?.persona, l.baseDir);
+        agents.push({
+            id,
+            name: a?.name,
+            model: a?.model,
+            harness: a?.harness,
+            effort: a?.effort,
+            tools: a?.tools ?? [],
+            persona: persona.text,
+        });
+    }
+    const steps = [];
+    for (const s of raw?.steps ?? []) {
+        const gates = (s?.gates ?? []).map(gateLabel);
+        if (s?.run !== undefined) {
+            const script = await resolveText(s.run, l.baseDir);
+            steps.push({
+                name: s.name,
+                kind: "script",
+                script: script.text,
+                sourceRef: script.sourceRef,
+                gates,
+            });
+        }
+        else {
+            const prompt = await resolveText(s?.prompt, l.baseDir);
+            steps.push({
+                name: s?.name,
+                kind: "agent",
+                agent: s?.agent,
+                prompt: prompt.text,
+                sourceRef: prompt.sourceRef,
+                gates,
+            });
+        }
+    }
+    const workspace = await resolveText(raw?.workspace, l.baseDir);
+    return {
+        slug: l.slug,
+        dir: path.dirname(l.yamlPath),
+        name: raw?.name,
+        description: raw?.description,
+        workspace: workspace.text,
+        agents,
+        steps,
+        files: l.baseDir ? await listDirFiles(l.baseDir) : [path.basename(l.yamlPath)],
+    };
+}