@netnodeag/kraftwerk 0.2.0 → 0.3.1

package/inspector/lib/runs.ts

@@ -0,0 +1,313 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * 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.
+ */
+
+export const OUTPUT_DIR = process.env.KRAFTWERK_OUTPUT
+  ? path.resolve(process.env.KRAFTWERK_OUTPUT)
+  : path.resolve(process.cwd(), "../../agent-playground/output");
+
+/** A run with no trace update for this long and no summary counts as aborted. */
+const STALE_MS = 15 * 60 * 1000;
+
+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[];
+}
+
+type TraceEvent = Record<string, any> & { ts: string; event: string };
+
+async function readTrace(runDir: string): Promise<TraceEvent[]> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(path.join(runDir, "trace.jsonl"), "utf8");
+  } catch {
+    return [];
+  }
+  const events: TraceEvent[] = [];
+  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: TraceEvent[]) {
+  const runStart = events.find((e) => e.event === "run_start");
+  const summary = events.find((e) => e.event === "run_summary");
+
+  const phases: PhaseView[] = [];
+  const byName = new Map<string, PhaseView>();
+  for (const e of events) {
+    if (e.event === "phase_start") {
+      const p: PhaseView = {
+        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<string, GateView>();
+    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: any[] | undefined = runStart?.steps;
+  const steps: string[] | undefined = 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: RunStatus;
+  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: string,
+  a: ReturnType<typeof analyse>
+): Promise<ReturnType<typeof analyse>> {
+  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: string): string {
+  const parts = p.split("/");
+  return parts.length > 2 ? parts.slice(-2).join("/") : p;
+}
+
+export async function listRuns(): Promise<RunListItem[]> {
+  let entries: string[];
+  try {
+    entries = (await fs.readdir(OUTPUT_DIR)).filter((e) => e.startsWith("run-"));
+  } catch {
+    return [];
+  }
+  const items = await Promise.all(
+    entries.map(async (id): Promise<RunListItem | null> => {
+      const runDir = path.join(OUTPUT_DIR, 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) as RunListItem[]).sort((a, b) => b.id.localeCompare(a.id));
+}
+
+export function safeRunDir(id: string): string {
+  if (!/^run-[0-9-]+$/.test(id)) throw new Error("invalid run id");
+  return path.join(OUTPUT_DIR, id);
+}
+
+export async function getRun(id: string): Promise<RunDetail | null> {
+  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: FileView[] = [];
+  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: string,
+  name: string
+): Promise<{ absPath: string; size: number } | null> {
+  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/inspector/lib/workflows.ts

@@ -0,0 +1,240 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { OUTPUT_DIR } from "./runs";
+
+/**
+ * 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.
+ */
+
+/** The consumer project root is the parent of the output dir. */
+export const PROJECT_ROOT = path.dirname(OUTPUT_DIR);
+
+async function workflowsRoot(): Promise<string | undefined> {
+  for (const candidate of ["src/workflows", "workflows"]) {
+    const p = path.join(PROJECT_ROOT, candidate);
+    const st = await fs.stat(p).catch(() => null);
+    if (st?.isDirectory()) return p;
+  }
+  return undefined;
+}
+
+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;
+}
+
+function gateLabel(g: any): string {
+  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: unknown,
+  baseDir: string | null
+): Promise<{ text?: string; sourceRef?: string }> {
+  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: string, prefix = ""): Promise<string[]> {
+  const out: string[] = [];
+  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();
+}
+
+interface Located {
+  slug: string;
+  yamlPath: string;
+  baseDir: string | null;
+}
+
+async function locate(): Promise<Located[]> {
+  const root = await workflowsRoot();
+  if (!root) return [];
+  const found: Located[] = [];
+  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: Located): Promise<any> {
+  const text = await fs.readFile(l.yamlPath, "utf8");
+  return parseYaml(text);
+}
+
+export async function listWorkflows(): Promise<{ root?: string; workflows: WorkflowSummary[] }> {
+  const root = await workflowsRoot();
+  const located = await locate();
+  const workflows = await Promise.all(
+    located.map(async (l): Promise<WorkflowSummary> => {
+      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 as Error).message };
+      }
+    })
+  );
+  return { root, workflows };
+}
+
+export async function getWorkflow(slug: string): Promise<WorkflowDetail | null> {
+  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: any;
+  try {
+    raw = await parseRaw(l);
+  } catch (err) {
+    return {
+      slug: l.slug,
+      dir: path.dirname(l.yamlPath),
+      agents: [],
+      steps: [],
+      files: [],
+      error: (err as Error).message,
+    };
+  }
+
+  const agents: AgentInfo[] = [];
+  for (const [id, a] of Object.entries<any>(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: StepInfo[] = [];
+  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)],
+  };
+}

package/inspector/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;