@netnodeag/kraftwerk 0.4.1 → 0.7.0

package/dist/cli/kraftwerk.js

@@ -11,15 +11,17 @@ import { loadWorkflow, missingEnv } from "../yaml.js";
 import { renderCreateBrief } from "./create-brief.js";
 import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
+import { registerKnowledgeCommands } from "./knowledge.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
 /**
  * kraftwerk — the kraftwerk CLI.
  *
- *   kraftwerk init                    scaffold kraftwerk.yml + workflows/ + example
+ *   kraftwerk init                    scaffold kraftwerk.yml + kraftwerk-data/ (workflow, agent, knowledge)
  *   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 knowledge ...           Context & Knowledge: OKF bundles (list/get/put/verify/...)
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
@@ -127,7 +129,7 @@ program
     .option("--from <source>", "Workflows from a git remote: github:org/repo[@ref] or git URL")
     .option("--sandbox", "Run inside the Docker sandbox container (image: kraftwerk-runner)")
     .option("--ssh", "Forward the SSH agent + known_hosts into the sandbox (only with --sandbox)")
-    .option("--run-id <id>", "Pin the run folder name (output/<id>), e.g. for external triggers")
+    .option("--run-id <id>", "Pin the run folder name (output/runs/<id>), e.g. for external triggers")
     .action(async (name, requestParts, opts) => {
     const machine = !!opts.json;
     const fail = (code, message) => {
@@ -170,8 +172,10 @@ program
     }
     if (opts.sandbox) {
         const { runSandboxed } = await import("../runner/docker.js");
+        const { resolveProject } = await import("../config.js");
         const handle = await runSandboxed({
             projectRoot: baseDir,
+            outputDir: opts.from ? undefined : (await resolveProject(baseDir)).outputDir,
             workflowPath: entry.path,
             workflowName: workflow.name,
             request,
@@ -182,17 +186,14 @@ program
         console.log(chalk.dim(`sandbox ${handle.containerName} → ${handle.runDir}`));
         process.exit(await handle.finished);
     }
-    if (opts.runId) {
-        process.env.KRAFTWERK_RUN_DIR = path.resolve("output", opts.runId);
-    }
-    else if (!process.env.KRAFTWERK_RUN_DIR) {
+    if (opts.runId || !process.env.KRAFTWERK_RUN_DIR) {
         // Root the run dir explicitly: at the project's output dir (honors
         // kraftwerk.yml `output:` and works from subdirs); for remote runs at
         // the caller's cwd — never inside the clone cache.
-        const { runStamp } = await import("../workflow.js");
+        const { newRunId, runDirFor } = await import("../workflow.js");
         const { resolveProject } = await import("../config.js");
         const outBase = opts.from ? path.resolve("output") : (await resolveProject(baseDir)).outputDir;
-        process.env.KRAFTWERK_RUN_DIR = path.join(outBase, `run-${runStamp()}`);
+        process.env.KRAFTWERK_RUN_DIR = runDirFor(outBase, opts.runId ?? newRunId(workflow.name));
     }
     // Machine/quiet mode: workflow narration must not pollute stdout — the
     // engine logs via console.log, so reroute it for the duration of the run.
@@ -223,7 +224,7 @@ program
 });
 program
     .command("init")
-    .description("Scaffold the project: kraftwerk.yml, workflows/ with an example, .gitignore")
+    .description("Scaffold the project: kraftwerk.yml, kraftwerk-data/ (example workflow, agent max, demo knowledge), .gitignore")
     .action(async () => {
     await runInit(process.cwd());
 });
@@ -246,11 +247,12 @@ runs
 runs
     .command("show")
     .description("Show one run in detail: phases, gates, cost")
-    .argument("<runId>", "Folder name under output/, see `kraftwerk runs`")
+    .argument("<runId>", "Folder name under output/runs/, see `kraftwerk runs`")
     .option("--json", "Machine-readable output (all trace events)")
     .action(async (runId, opts) => {
     await showRun(process.cwd(), runId, opts);
 });
+registerKnowledgeCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/runs.js

@@ -4,6 +4,7 @@ import chalk from "chalk";
 import Table from "cli-table3";
 import { resolveProject } from "../config.js";
 import { fmtDuration, fmtTokens } from "../stats.js";
+import { runDirFor } from "../workflow.js";
 async function readRun(dir) {
     const tracePath = path.join(dir, "trace.jsonl");
     const raw = await readFile(tracePath, "utf8").catch(() => null);
@@ -37,12 +38,18 @@ async function readRun(dir) {
 }
 async function collectRuns(cwd) {
     const { outputDir } = await resolveProject(cwd);
-    const entries = await readdir(outputDir, { withFileTypes: true }).catch(() => []);
+    // New runs live under <output>/runs/; legacy run-* folders sit at the root.
+    const dirs = [
+        ...(await readdir(path.join(outputDir, "runs"), { withFileTypes: true }).catch(() => []))
+            .filter((e) => e.isDirectory())
+            .map((e) => path.join(outputDir, "runs", e.name)),
+        ...(await readdir(outputDir, { withFileTypes: true }).catch(() => []))
+            .filter((e) => e.isDirectory() && e.name.startsWith("run-"))
+            .map((e) => path.join(outputDir, e.name)),
+    ];
     const runs = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const info = await readRun(path.join(outputDir, entry.name));
+    for (const dir of dirs) {
+        const info = await readRun(dir);
         if (info)
             runs.push(info);
     }
@@ -83,7 +90,7 @@ export async function listRuns(cwd, opts = {}) {
 }
 export async function showRun(cwd, id, opts = {}) {
     const { outputDir } = await resolveProject(cwd);
-    const dir = path.join(outputDir, id);
+    const dir = runDirFor(outputDir, id);
     if (!(await stat(dir).catch(() => null))) {
         console.error(chalk.red(`Run "${id}" not found under ${outputDir}.`));
         process.exit(2);

package/dist/cli/ui.js

@@ -42,11 +42,10 @@ function ensureBuilt() {
 }
 export async function runUi(cwd, opts) {
     const staticDir = ensureBuilt();
-    const outputDir = opts.output
-        ? path.resolve(cwd, opts.output)
-        : (await resolveProject(cwd)).outputDir;
+    const project = await resolveProject(cwd);
+    const outputDir = opts.output ? path.resolve(cwd, opts.output) : project.outputDir;
     const port = Number(opts.port ?? "1981");
-    await startInspector({ outputDir, staticDir, port });
+    await startInspector({ outputDir, staticDir, port, projectRoot: project.root });
     console.log(`${chalk.green("✔")} Inspector: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));
 }

package/dist/config.d.ts

@@ -9,17 +9,26 @@
  *
  * All fields are optional — a valid kraftwerk.yml may be empty:
  *
+ *   name: my-project           # display name (inspector header, "environment")
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
+ *   knowledge: knowledge       # OKF knowledge-bundle root, relative to the file
+ *   agents: agents             # team agent-definition root, relative to the file
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
 export declare const CONFIG_FILENAMES: string[];
 export interface ProjectConfig {
+    /** Display name of the project ("environment"), shown in the inspector header. */
+    name?: string;
     /** Workflows root relative to the project root. */
     workflows?: string;
     /** Run-artifact directory relative to the project root. Default: output */
     output?: string;
+    /** OKF knowledge-bundle root relative to the project root. Default: knowledge */
+    knowledge?: string;
+    /** Team agent-definition root relative to the project root. Default: agents */
+    agents?: string;
 }
 export interface Project {
     /** Absolute project root the CLI operates on. */

package/dist/config.js

@@ -12,8 +12,11 @@ import { parse } from "yaml";
  *
  * All fields are optional — a valid kraftwerk.yml may be empty:
  *
+ *   name: my-project           # display name (inspector header, "environment")
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
+ *   knowledge: knowledge       # OKF knowledge-bundle root, relative to the file
+ *   agents: agents             # team agent-definition root, relative to the file
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -81,10 +84,10 @@ async function loadConfig(configPath) {
     if (raw === null || raw === undefined)
         return {};
     if (typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error(`${path.basename(configPath)}: expected a mapping (workflows, output)`);
+        throw new Error(`${path.basename(configPath)}: expected a mapping (name, workflows, output, knowledge, agents)`);
     }
     const config = raw;
-    const known = ["workflows", "output"];
+    const known = ["name", "workflows", "output", "knowledge", "agents"];
     for (const key of Object.keys(config)) {
         if (!known.includes(key)) {
             throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);

package/dist/gates.d.ts

@@ -14,5 +14,12 @@ export interface Gate {
 export declare const fileNonEmpty: (file: string) => Gate;
 /** No {{...}} template slots may survive a fill step. */
 export declare const slotsFilled: (file: string) => Gate;
+/**
+ * Workflow-specific validation as a bash script: exit 0 = passed, non-zero =
+ * failed and everything the script printed becomes the failure message — so
+ * precise per-violation output turns directly into a precise correction
+ * prompt. The script runs in the run directory (env: RUN_DIR).
+ */
+export declare const checkScript: (script: string, label: string) => Gate;
 /** Fixed template parts chosen by code must survive byte-identically. */
 export declare const containsText: (file: string, needle: string, label: string) => Gate;

package/dist/gates.js

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 export const fileNonEmpty = (file) => ({
@@ -22,6 +23,32 @@ export const slotsFilled = (file) => ({
             : null;
     },
 });
+/**
+ * Workflow-specific validation as a bash script: exit 0 = passed, non-zero =
+ * failed and everything the script printed becomes the failure message — so
+ * precise per-violation output turns directly into a precise correction
+ * prompt. The script runs in the run directory (env: RUN_DIR).
+ */
+export const checkScript = (script, label) => ({
+    name: `check(${label})`,
+    async check(runDir) {
+        const result = await new Promise((resolve, reject) => {
+            const child = spawn("bash", ["-c", script], {
+                cwd: runDir,
+                env: { ...process.env, RUN_DIR: runDir },
+            });
+            let output = "";
+            child.stdout.on("data", (chunk) => (output += String(chunk)));
+            child.stderr.on("data", (chunk) => (output += String(chunk)));
+            child.on("error", reject);
+            child.on("close", (code) => resolve({ code: code ?? 1, output }));
+        });
+        if (result.code === 0)
+            return null;
+        const tail = result.output.trim().split("\n").slice(-12).join("\n");
+        return tail || `check script failed with exit code ${result.code}`;
+    },
+});
 /** Fixed template parts chosen by code must survive byte-identically. */
 export const containsText = (file, needle, label) => ({
     name: `contains(${file}, ${label})`,

package/dist/harnesses/claude.js

@@ -8,7 +8,6 @@ function invokeClaude(inv) {
     ];
     const args = [
         "-p",
-        "--chrome",
         "--output-format", "stream-json",
         "--verbose",
         "--model", inv.model,

package/dist/inspector/chat/acp.d.ts

@@ -1,2 +1,2 @@
-import type { BackendHooks, ChatBackend } from "./backend.js";
-export declare function startAcpBackend(agent: "claude" | "codex", cwd: string, hooks: BackendHooks): Promise<ChatBackend>;
+import type { BackendHooks, BackendTuning, ChatBackend } from "./backend.js";
+export declare function startAcpBackend(agent: "claude" | "codex", cwd: string, hooks: BackendHooks, tuning?: BackendTuning): Promise<ChatBackend>;

package/dist/inspector/chat/acp.js

@@ -15,15 +15,42 @@ const ADAPTERS = {
     claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
     codex: "@agentclientprotocol/codex-acp/dist/index.js",
 };
+/** Effort tier -> Claude thinking budget (the adapter reads MAX_THINKING_TOKENS). */
+const CLAUDE_THINKING_BUDGET = {
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+    xhigh: 32000,
+    max: 63999,
+};
+/**
+ * Model/effort overrides ride on adapter-specific channels: the claude
+ * adapter takes the model via session `_meta.claudeCode.options` and the
+ * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
+ * the session config it hands to `codex app-server`.
+ */
+function tuningEnv(agent, tuning) {
+    const env = { ...process.env };
+    if (agent === "claude" && tuning.effort && CLAUDE_THINKING_BUDGET[tuning.effort]) {
+        env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[tuning.effort]);
+    }
+    if (agent === "codex" && (tuning.model || tuning.effort)) {
+        env.CODEX_CONFIG = JSON.stringify({
+            ...(tuning.model ? { model: tuning.model } : {}),
+            ...(tuning.effort ? { model_reasoning_effort: tuning.effort } : {}),
+        });
+    }
+    return env;
+}
 function contentText(content) {
     return content.type === "text" ? content.text : "";
 }
-export async function startAcpBackend(agent, cwd, hooks) {
+export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
     const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
     const child = spawn(process.execPath, [entry], {
         cwd,
         stdio: ["pipe", "pipe", "pipe"],
-        env: process.env,
+        env: tuningEnv(agent, tuning),
     });
     let stderr = "";
     child.stderr.on("data", (c) => {
@@ -91,7 +118,21 @@ export async function startAcpBackend(agent, cwd, hooks) {
         clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
         clientInfo: { name: "kraftwerk-inspector", version: "1.0.0" },
     });
-    const session = await conn.newSession({ cwd, mcpServers: [] });
+    // Claude-only session options ride on _meta.claudeCode.options (the
+    // adapter spreads them into the Agent SDK options): model override,
+    // skill allowlist (undefined = all discovered skills), extra work dirs.
+    const claudeOptions = {
+        ...(tuning.model ? { model: tuning.model } : {}),
+        ...(tuning.skills ? { skills: tuning.skills } : {}),
+        ...(tuning.addDirs?.length ? { additionalDirectories: tuning.addDirs } : {}),
+    };
+    const session = await conn.newSession({
+        cwd,
+        mcpServers: [],
+        ...(agent === "claude" && Object.keys(claudeOptions).length
+            ? { _meta: { claudeCode: { options: claudeOptions } } }
+            : {}),
+    });
     const sessionId = session.sessionId;
     return {
         async prompt(text) {

package/dist/inspector/chat/backend.d.ts

@@ -18,6 +18,20 @@ export interface BackendHooks {
         kind?: string;
     }>): Promise<string | null>;
 }
+/**
+ * Optional per-chat model/effort overrides (from a team member definition).
+ * Each backend maps them onto whatever its agent actually supports.
+ */
+export interface BackendTuning {
+    model?: string;
+    effort?: string;
+    /** claude: restrict native skill discovery to these names (undefined = all). */
+    skills?: string[];
+    /** pi: skill folders to load explicitly via --skill. */
+    skillDirs?: string[];
+    /** claude: extra directories the session may work in (e.g. project root for run chats). */
+    addDirs?: string[];
+}
 export interface ChatBackend {
     /** Send one user message; resolves with the stop reason at turn end. */
     prompt(text: string): Promise<string>;

package/dist/inspector/chat/pi.d.ts

@@ -0,0 +1,2 @@
+import type { BackendHooks, BackendTuning, ChatBackend } from "./backend.js";
+export declare function startPiBackend(cwd: string, hooks: BackendHooks, tuning?: BackendTuning): ChatBackend;

package/dist/inspector/chat/pi.js

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+const clip = (raw) => {
+    const oneLine = String(raw ?? "").replace(/\s+/g, " ").trim();
+    return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
+};
+export function startPiBackend(cwd, hooks, tuning = {}) {
+    const sessionId = randomUUID();
+    let child = null;
+    let cancelled = false;
+    const tuningArgs = [
+        ...(tuning.model ? ["--model", tuning.model] : []),
+        ...(tuning.effort ? ["--thinking", tuning.effort] : []),
+        ...(tuning.skillDirs ?? []).flatMap((dir) => ["--skill", dir]),
+    ];
+    return {
+        prompt(text) {
+            cancelled = false;
+            return new Promise((resolve, reject) => {
+                const proc = spawn("pi", ["-p", "--mode", "json", "--session-id", sessionId, ...tuningArgs], {
+                    cwd,
+                    stdio: ["pipe", "pipe", "pipe"],
+                    env: process.env,
+                });
+                child = proc;
+                proc.stdin.write(text);
+                proc.stdin.end();
+                let sawAssistant = false;
+                let failure;
+                let stderr = "";
+                let buffer = "";
+                let toolSeq = 0;
+                const handleLine = (line) => {
+                    if (!line.trim())
+                        return;
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch {
+                        return; // non-JSON noise on stdout
+                    }
+                    if (event.type === "tool_execution_start" && event.toolName) {
+                        const a = event.args ?? {};
+                        const target = clip(a.path ?? a.file_path ?? a.command ?? a.pattern ?? "");
+                        hooks.emit({
+                            type: "tool_call",
+                            callId: `pi-${sessionId}-${toolSeq++}`,
+                            title: target ? `${event.toolName} ${target}` : event.toolName,
+                            status: "completed",
+                        });
+                    }
+                    if (event.type === "message_end" && event.message?.role === "assistant") {
+                        sawAssistant = true;
+                        for (const block of event.message.content ?? []) {
+                            if (block?.type === "text" && block.text?.trim()) {
+                                hooks.emit({ type: "text", text: block.text });
+                            }
+                            if (block?.type === "thinking" && block.text?.trim()) {
+                                hooks.emit({ type: "thought", text: block.text });
+                            }
+                        }
+                    }
+                    if (event.type === "error") {
+                        failure = typeof event.error === "string" ? event.error : line;
+                    }
+                    // API failures don't exit non-zero: they ride on turn_end as
+                    // stopReason "error" with an empty assistant message.
+                    if (event.type === "turn_end" && event.message?.stopReason === "error") {
+                        failure = clip(event.message.errorMessage ?? "unknown pi error");
+                    }
+                };
+                proc.stdout.on("data", (chunk) => {
+                    buffer += chunk.toString("utf8");
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    lines.forEach(handleLine);
+                });
+                proc.stderr.on("data", (chunk) => {
+                    stderr += chunk.toString("utf8");
+                });
+                proc.on("error", (err) => reject(new Error(`could not spawn pi: ${err.message}`)));
+                proc.on("close", (code) => {
+                    child = null;
+                    handleLine(buffer);
+                    if (cancelled)
+                        return resolve("cancelled");
+                    if (failure || code !== 0 || !sawAssistant) {
+                        reject(new Error(`pi failed (exit ${code})` +
+                            (failure ? `: ${failure}` : "") +
+                            (stderr.trim() ? `\nstderr: ${stderr.trim().slice(-1000)}` : "")));
+                        return;
+                    }
+                    resolve("end_turn");
+                });
+            });
+        },
+        cancel() {
+            cancelled = true;
+            child?.kill("SIGTERM");
+        },
+        dispose() {
+            child?.kill("SIGTERM");
+        },
+    };
+}

package/dist/inspector/chat/sessions.d.ts

@@ -0,0 +1,33 @@
+import type { ChatAgentId, ChatMeta, ChatScope, StoredChatEvent } from "./types.js";
+export declare function createChat(opts: {
+    agent: ChatAgentId;
+    scope: ChatScope;
+    /** Preset title (e.g. routine runs); otherwise the first message names the chat. */
+    title?: string;
+}): Promise<ChatMeta>;
+export declare function listChats(): Promise<Array<ChatMeta & {
+    busy: boolean;
+}>>;
+export declare function getChat(id: string): Promise<{
+    meta: ChatMeta;
+    events: StoredChatEvent[];
+    busy: boolean;
+} | null>;
+export declare function postMessage(id: string, text: string): Promise<{
+    error?: string;
+}>;
+export declare function resolvePermission(id: string, requestId: string, optionId: string | null): Promise<{
+    error?: string;
+}>;
+/** Delete a chat: kill its backend, drop the live state, remove its folder. */
+export declare function deleteChat(id: string): Promise<{
+    error?: string;
+}>;
+export declare function cancelChat(id: string): Promise<{
+    error?: string;
+}>;
+/**
+ * SSE subscription: replays events after `afterSeq`, then streams new ones.
+ * Returns an unsubscribe function.
+ */
+export declare function subscribeChat(id: string, afterSeq: number, fn: (ev: StoredChatEvent) => void): Promise<(() => void) | null>;