@netnodeag/kraftwerk 0.2.0

package/dist/runner/docker.d.ts

@@ -0,0 +1,38 @@
+export interface SandboxOptions {
+    /** Consumer project root (where output/ lives). */
+    projectRoot: string;
+    /** Workflow folder (folder mode) or .yml file path. */
+    workflowPath: string;
+    /** Workflow name as declared in the YAML (used for `kraftwerk run <name>`). */
+    workflowName: string;
+    request: string;
+    /** Pre-chosen run id (run-...); generated when omitted. */
+    runId?: string;
+    /** Forward the host SSH agent + known_hosts into the container. */
+    ssh?: boolean;
+    /** "attach": inherit stdio, await completion (CLI). "detach": stdio to runner.log, survives the parent (web trigger). */
+    mode: "attach" | "detach";
+    memory?: string;
+    cpus?: string;
+}
+export interface SandboxHandle {
+    runId: string;
+    runDir: string;
+    containerName: string;
+    /** Resolves with the docker exit code (attach mode only awaits it). */
+    finished: Promise<number>;
+}
+export declare function dockerAvailable(): string | null;
+export declare function imageExists(): boolean;
+/** Build (or rebuild) the kraftwerk-runner image. Streams docker output. */
+export declare function buildImage(): Promise<void>;
+export declare function runSandboxed(opts: SandboxOptions): Promise<SandboxHandle>;
+/** Running kraftwerk sandbox containers: [{ runId, workflow, container, status }]. */
+export declare function listSandboxes(): Array<{
+    runId: string;
+    workflow: string;
+    container: string;
+    status: string;
+}>;
+/** Stop a sandboxed run by run id. Returns false when no such container. */
+export declare function stopSandbox(runId: string): boolean;

package/dist/runner/docker.js

@@ -0,0 +1,166 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdir, writeFile, readFile, open } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runStamp } from "../workflow.js";
+/**
+ * Docker sandbox runner: one container per workflow run.
+ *
+ * The container gets
+ *   - the workflow folder, mounted read-only at /work/src/workflows/<name>
+ *   - the host run directory, bind-mounted at /work/output/<run-id> — so
+ *     trace.jsonl and all artifacts land on the host LIVE while the run
+ *     executes (no copy-back step needed; the inspector polls as usual)
+ *   - env vars from <project>/runner.env (if present) plus pass-through of
+ *     ANTHROPIC_API_KEY / OPENAI_API_KEY from the host environment
+ *   - optionally the host SSH agent socket + known_hosts (`ssh: true`)
+ *
+ * Inside, plain `kraftwerk run --yes` executes; KRAFTWERK_RUN_DIR pins the
+ * run directory to the mount. Container name kw-<run-id> and label
+ * kraftwerk.run make runs discoverable and cancellable (`docker stop`).
+ */
+const IMAGE = "kraftwerk-runner";
+const ENV_FILE = "runner.env";
+const PASSTHROUGH_ENV = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+/** Framework package root (contains runner/Dockerfile). */
+const frameworkDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export function dockerAvailable() {
+    const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
+        encoding: "utf8",
+        timeout: 10_000,
+    });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.trim() || "unknown";
+}
+export function imageExists() {
+    return spawnSync("docker", ["image", "inspect", IMAGE], { stdio: "ignore" }).status === 0;
+}
+/** Build (or rebuild) the kraftwerk-runner image. Streams docker output. */
+export async function buildImage() {
+    if (!existsSync(path.join(frameworkDir, "dist"))) {
+        throw new Error("dist/ missing — run `npm run build` in the framework checkout first, then build the image.");
+    }
+    const dockerfile = path.join(frameworkDir, "runner", "Dockerfile");
+    await new Promise((resolve, reject) => {
+        const child = spawn("docker", ["build", "-t", IMAGE, "-f", dockerfile, frameworkDir], { stdio: "inherit" });
+        child.on("error", reject);
+        child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`docker build failed (exit ${code})`)));
+    });
+}
+export async function runSandboxed(opts) {
+    if (!dockerAvailable()) {
+        throw new Error("Docker daemon not reachable — is Docker running?");
+    }
+    if (!imageExists()) {
+        throw new Error(`Image "${IMAGE}" not found — run \`kraftwerk runner build\` first.`);
+    }
+    const runId = opts.runId ?? `run-${runStamp()}`;
+    const runDir = path.join(opts.projectRoot, "output", runId);
+    await mkdir(runDir, { recursive: true });
+    const containerName = `kw-${runId}`;
+    // Folder mode and single-file mode both mount under src/workflows/ so
+    // the in-container discovery finds exactly this one workflow.
+    const wfAbs = path.resolve(opts.workflowPath);
+    const wfTarget = `/work/src/workflows/${path.basename(wfAbs)}`;
+    const args = [
+        "run", "--rm",
+        "--name", containerName,
+        "--label", `kraftwerk.run=${runId}`,
+        "--label", `kraftwerk.workflow=${opts.workflowName}`,
+        "--memory", opts.memory ?? "2g",
+        "--cpus", opts.cpus ?? "2",
+        "-v", `${wfAbs}:${wfTarget}:ro`,
+        "-v", `${runDir}:/work/output/${runId}`,
+        "-e", `KRAFTWERK_RUN_DIR=/work/output/${runId}`,
+    ];
+    const envFile = path.join(opts.projectRoot, ENV_FILE);
+    if (existsSync(envFile))
+        args.push("--env-file", envFile);
+    for (const key of PASSTHROUGH_ENV) {
+        if (process.env[key])
+            args.push("-e", key);
+    }
+    if (opts.ssh) {
+        // Docker Desktop (macOS) exposes the host agent at a magic path; on
+        // Linux the socket path can be mounted directly.
+        const sock = os.platform() === "darwin" ? "/run/host-services/ssh-auth.sock" : process.env.SSH_AUTH_SOCK;
+        if (sock) {
+            args.push("-v", `${os.platform() === "darwin" ? "/run/host-services/ssh-auth.sock" : sock}:/ssh-agent.sock`, "-e", "SSH_AUTH_SOCK=/ssh-agent.sock");
+        }
+        const knownHosts = path.join(os.homedir(), ".ssh", "known_hosts");
+        if (existsSync(knownHosts)) {
+            args.push("-v", `${knownHosts}:/root/.ssh/known_hosts:ro`);
+        }
+    }
+    args.push(IMAGE, "kraftwerk", "run", "--yes", opts.workflowName, opts.request);
+    await writeFile(path.join(runDir, "runner.json"), JSON.stringify({
+        container: containerName,
+        image: IMAGE,
+        workflow: opts.workflowName,
+        request: opts.request,
+        ssh: !!opts.ssh,
+        startedAt: new Date().toISOString(),
+    }, null, 2) + "\n");
+    let exited;
+    if (opts.mode === "attach") {
+        const child = spawn("docker", args, { stdio: "inherit" });
+        exited = new Promise((resolve, reject) => {
+            child.on("error", reject);
+            child.on("close", (code) => resolve(code ?? 1));
+        });
+    }
+    else {
+        // Detached: docker client keeps running after the parent (e.g. the
+        // inspector dev server) exits; all output goes to runner.log.
+        const log = await open(path.join(runDir, "runner.log"), "a");
+        const child = spawn("docker", args, {
+            detached: true,
+            stdio: ["ignore", log.fd, log.fd],
+        });
+        exited = new Promise((resolve) => {
+            child.on("close", (code) => resolve(code ?? 1));
+            child.on("error", () => resolve(1));
+        });
+        child.unref();
+        await log.close();
+    }
+    // Record the outcome before anyone (e.g. the CLI's process.exit) can act
+    // on the resolved exit code. Best effort only in detach mode — the parent
+    // may be gone; trace.jsonl still tells the story.
+    const finished = exited.then(async (code) => {
+        try {
+            const p = path.join(runDir, "runner.json");
+            const meta = JSON.parse(await readFile(p, "utf8"));
+            meta.exitCode = code;
+            meta.finishedAt = new Date().toISOString();
+            await writeFile(p, JSON.stringify(meta, null, 2) + "\n");
+        }
+        catch {
+            /* ignore */
+        }
+        return code;
+    });
+    return { runId, runDir, containerName, finished };
+}
+/** Running kraftwerk sandbox containers: [{ runId, workflow, container, status }]. */
+export function listSandboxes() {
+    const r = spawnSync("docker", ["ps", "--filter", "label=kraftwerk.run", "--format",
+        '{{.Label "kraftwerk.run"}}\t{{.Label "kraftwerk.workflow"}}\t{{.Names}}\t{{.Status}}'], { encoding: "utf8" });
+    if (r.status !== 0)
+        return [];
+    return r.stdout
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [runId, workflow, container, status] = line.split("\t");
+        return { runId, workflow, container, status };
+    });
+}
+/** Stop a sandboxed run by run id. Returns false when no such container. */
+export function stopSandbox(runId) {
+    return spawnSync("docker", ["stop", `kw-${runId}`], { stdio: "ignore", timeout: 30_000 }).status === 0;
+}

package/dist/stats.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-phase resource accounting: wall-clock time, token usage, cost.
+ * Collected by Run, persisted to trace.jsonl, rendered as the run summary.
+ */
+export interface PhaseStats {
+    phase: string;
+    kind: "agent" | "code" | "script";
+    /** Agent id, for agent phases. */
+    agent?: string;
+    /** Harness id, for agent phases. */
+    harness?: string;
+    /** Model id, for agent phases. */
+    model?: string;
+    effort?: string;
+    /** 1 + number of correction rounds. */
+    attempts: number;
+    /** Wall-clock time of the whole phase, corrections included. */
+    durationMs: number;
+    /** Fresh input tokens (uncached), summed over attempts. */
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+}
+export interface RunTotals {
+    durationMs: number;
+    in: number;
+    out: number;
+    costUsd: number;
+}
+/** Everything the API processed as input: fresh + cache read + cache creation. */
+export declare const totalIn: (s: {
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}) => number;
+export declare const fmtTokens: (n: number) => string;
+export declare const fmtDuration: (ms: number) => string;
+/** One-line phase result, appended to the ✔ log line. */
+export declare function phaseStatsLine(stats: PhaseStats, numTurns?: number): string;
+/** Render the end-of-run table; returns the printable lines plus totals. */
+export declare function summaryTable(stats: PhaseStats[]): {
+    lines: string[];
+    total: RunTotals;
+};

package/dist/stats.js

@@ -0,0 +1,65 @@
+/**
+ * Per-phase resource accounting: wall-clock time, token usage, cost.
+ * Collected by Run, persisted to trace.jsonl, rendered as the run summary.
+ */
+/** Everything the API processed as input: fresh + cache read + cache creation. */
+export const totalIn = (s) => s.inputTokens + s.cacheReadTokens + s.cacheCreationTokens;
+export const fmtTokens = (n) => n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+export const fmtDuration = (ms) => {
+    const s = Math.round(ms / 1000);
+    return s >= 60 ? `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s` : `${s}s`;
+};
+/** One-line phase result, appended to the ✔ log line. */
+export function phaseStatsLine(stats, numTurns) {
+    return [
+        numTurns !== undefined ? `${numTurns} turns` : "",
+        fmtDuration(stats.durationMs),
+        `${fmtTokens(totalIn(stats))} in / ${fmtTokens(stats.outputTokens)} out`,
+        `$${stats.costUsd.toFixed(4)}`,
+    ]
+        .filter(Boolean)
+        .join(" | ");
+}
+/** Render the end-of-run table; returns the printable lines plus totals. */
+export function summaryTable(stats) {
+    const rows = stats.map((s) => {
+        // Prefix the harness only when it is not the default claude runtime.
+        const modelName = s.harness && s.harness !== "claude" ? `${s.harness}:${s.model}` : s.model;
+        return {
+            phase: s.phase,
+            agent: s.kind === "agent" ? s.agent ?? "" : `(${s.kind})`,
+            model: modelName ? (s.effort ? `${modelName} (${s.effort})` : modelName) : "",
+            attempts: String(s.attempts),
+            time: fmtDuration(s.durationMs),
+            tokens: s.kind === "agent" ? `${fmtTokens(totalIn(s))} / ${fmtTokens(s.outputTokens)}` : "",
+            cost: s.kind === "agent" ? `$${s.costUsd.toFixed(4)}` : "",
+        };
+    });
+    const total = stats.reduce((acc, s) => ({
+        durationMs: acc.durationMs + s.durationMs,
+        in: acc.in + totalIn(s),
+        out: acc.out + s.outputTokens,
+        costUsd: acc.costUsd + s.costUsd,
+    }), { durationMs: 0, in: 0, out: 0, costUsd: 0 });
+    rows.push({
+        phase: "total",
+        agent: "",
+        model: "",
+        attempts: "",
+        time: fmtDuration(total.durationMs),
+        tokens: `${fmtTokens(total.in)} / ${fmtTokens(total.out)}`,
+        cost: `$${total.costUsd.toFixed(4)}`,
+    });
+    const header = { phase: "phase", agent: "agent", model: "model", attempts: "att", time: "time", tokens: "tokens in/out", cost: "cost" };
+    const cols = ["phase", "agent", "model", "attempts", "time", "tokens", "cost"];
+    const width = (c) => Math.max(header[c].length, ...rows.map((r) => r[c].length));
+    const line = (r) => "  " + cols.map((c) => r[c].padEnd(width(c))).join("  ");
+    return {
+        lines: [
+            line(header),
+            "  " + cols.map((c) => "-".repeat(width(c))).join("  "),
+            ...rows.map(line),
+        ],
+        total,
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate workflow files/folders without executing them: runs the full
+ * loader (JSON Schema + semantic checks + referenced files). Returns the
+ * number of failures. Used by the `validate` CLI subcommand
+ * (`npm start -- validate <path> ...`) and runnable standalone
+ * (`npm run validate -- <path> ...` in the framework).
+ */
+export declare function validateWorkflows(paths: string[]): Promise<number>;

package/dist/validate.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { loadWorkflow } from "./yaml.js";
+/**
+ * Validate workflow files/folders without executing them: runs the full
+ * loader (JSON Schema + semantic checks + referenced files). Returns the
+ * number of failures. Used by the `validate` CLI subcommand
+ * (`npm start -- validate <path> ...`) and runnable standalone
+ * (`npm run validate -- <path> ...` in the framework).
+ */
+export async function validateWorkflows(paths) {
+    let failures = 0;
+    for (const p of paths) {
+        try {
+            const workflow = await loadWorkflow(p);
+            console.log(`✔ ${p}: OK — workflow "${workflow.name}" (${workflow.description})`);
+        }
+        catch (err) {
+            failures += 1;
+            console.error(`✖ ${p}: ${err.message}`);
+        }
+    }
+    return failures;
+}
+// Standalone entry: tsx src/validate.ts <path> [<path> ...]
+if (process.argv[1] && import.meta.filename === path.resolve(process.argv[1])) {
+    const paths = process.argv.slice(2);
+    if (paths.length === 0) {
+        console.error("Usage: npm run validate -- <workflow.yml | workflow-folder> ...");
+        process.exit(1);
+    }
+    const failures = await validateWorkflows(paths);
+    process.exit(failures > 0 ? 1 : 0);
+}

package/dist/workflow.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The contract between the CLI registry and a concrete workflow (ADW).
+ * A workflow owns its run directory, roster, prompts, and gates; the
+ * framework only provides the phase runner and the CLI dispatch.
+ */
+import type { PhaseStats, RunTotals } from "./stats.js";
+export interface WorkflowRunOptions {
+    request: string;
+    autoApprove: boolean;
+    verbose: boolean;
+}
+/** Machine-readable outcome of a run (also what `run --json` prints). */
+export interface RunResult {
+    runDir: string;
+    phases: PhaseStats[];
+    total: RunTotals;
+}
+export interface WorkflowDefinition {
+    name: string;
+    description: string;
+    run(opts: WorkflowRunOptions): Promise<RunResult | void>;
+}
+/** Local-time run-folder stamp: "2026-08-13-1432-07" (sortable, no colons). */
+export declare function runStamp(date?: Date): string;

package/dist/workflow.js

@@ -0,0 +1,11 @@
+/**
+ * The contract between the CLI registry and a concrete workflow (ADW).
+ * A workflow owns its run directory, roster, prompts, and gates; the
+ * framework only provides the phase runner and the CLI dispatch.
+ */
+/** Local-time run-folder stamp: "2026-08-13-1432-07" (sortable, no colons). */
+export function runStamp(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `-${pad(date.getHours())}${pad(date.getMinutes())}-${pad(date.getSeconds())}`);
+}

package/dist/yaml.d.ts

@@ -0,0 +1,21 @@
+import type { AgentDefinition } from "./agent.js";
+import { type RunResult, type WorkflowDefinition } from "./workflow.js";
+/** A YAML-loaded workflow additionally exposes its roster/steps (for the CLI). */
+export interface LoadedWorkflow extends WorkflowDefinition {
+    readonly meta: {
+        agents: AgentDefinition[];
+        steps: string[];
+        /** Environment variables the workflow declares under `requires:`. */
+        requires: string[];
+    };
+    run(opts: Parameters<WorkflowDefinition["run"]>[0]): Promise<RunResult>;
+}
+/** Names from `requires:` that are missing/empty in the current environment. */
+export declare const missingEnv: (requires: string[]) => string[];
+/**
+ * Load a workflow from a folder (`<dir>/workflow.yml` + referenced files)
+ * or from a single `.yml`/`.yaml` file (everything inline).
+ */
+export declare function loadWorkflow(givenPath: string): Promise<LoadedWorkflow>;
+/** Back-compat alias for the single-file entry point. */
+export declare const loadWorkflowYaml: typeof loadWorkflow;