@netnodeag/kraftwerk 0.4.1 → 0.6.0

package/README.md

@@ -56,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 knowledge                     # Context & Knowledge: OKF bundles (list/get/put/verify/search/...)
 kraftwerk ui                            # inspector web UI on http://localhost:1981; --port, --output
 kraftwerk doctor                        # preflight: harness CLIs, docker, workflows, declared env vars
 kraftwerk validate                      # all discovered — schema + semantics + files, exit 1 on failure
@@ -69,8 +70,10 @@ kraftwerk runner ps / stop <run-id>     # see / stop running sandbox containers
 ### Project config — kraftwerk.yml
 
 Optional, at the project root (also the root marker for the walk-up); all
-fields optional: `workflows:` (workflows root) and `output:` (run-artifact
-directory, default `output/`).
+fields optional: `workflows:` (workflows root), `output:` (run-artifact
+directory, default `output/`), `knowledge:` (OKF knowledge-bundle root,
+default `knowledge/`), and `agents:` (team agent-definition root, default
+`agents/`).
 
 ### Triggering from CI / cron / webhooks
 
@@ -116,6 +119,141 @@ agent (Claude Code, Codex): it prints a self-contained brief — schema
 example, gates, harness rules, verify ladder — that the agent follows to
 author the workflow folder and validate/smoke it with this CLI.
 
+### Inspector on a server — deploy starter
+
+The repo root ships [`deploy-starter/`](../deploy-starter/): copy it
+into your consumer repo as `deploy/` and it builds a small image (this
+package from npm + the claude/codex/pi CLIs) that serves `kraftwerk ui`
+for that repo, bind-mounted at `/work`. `compose.yml` is localhost-only
+(SSH tunnel); `compose.traefik.yml` layers traefik routing + mandatory
+basic-auth on top — the UI has no authentication of its own and its chat
+runs coding agents against the mounted repo. Agent logins made inside
+the container persist in the `agent-home` volume. This is a different
+image from the `kraftwerk-runner` sandbox (`runner/Dockerfile`) used by
+`run --sandbox`.
+
+## Team — persistent agents
+
+The inspector's "team" screen turns chat agents into persistent teammates.
+A team member is one folder under the project's `agents/` root:
+
+```
+agents/max/
+  agent.yml     # name, emoji, description, harness, model, effort, workflows
+  system.md     # the member's system prompt (its role)
+```
+
+```yaml
+# agents/max/agent.yml
+name: Max
+emoji: 🛠️
+description: Runs and explains this project's workflows
+harness: claude        # claude | codex | pi — which chat backend runs it
+model: sonnet          # optional; harness default when omitted
+effort: medium         # optional: low | medium | high | xhigh | max
+workflows: [tagline, website-check]
+knowledge: [customer-support]   # OKF bundles the member consults & maintains
+```
+
+Sessions with a member are ordinary chats scoped `{ kind: "team", member }`,
+listed per member in a second sidebar. On the first message the member gets
+its role plus its connected workflows and knowledge bundles injected as
+context — including how to run workflows
+(`KRAFTWERK_YES=1 npx kraftwerk run <workflow> "<request>"`) and how to read
+and write knowledge through `kraftwerk knowledge` (writes stamped with the
+member's own actor, `<slug>/<harness>`), so it triggers its own workflows
+when a request matches and keeps its bundles current. Model/effort ride on
+backend-specific channels: the claude adapter takes the model via ACP session
+options and the thinking budget via `MAX_THINKING_TOKENS`; codex gets a
+`CODEX_CONFIG` env override (`model`, `model_reasoning_effort`); pi gets
+`--model`/`--thinking` flags. Members are created and edited in the UI (or by
+editing the files — the definition is read fresh for each new session).
+
+### Routines — scheduled prompts
+
+A member can have routines: cron-scheduled prompts, like standing orders for
+an employee. Definitions live next to the member in
+`agents/<slug>/routines.yml` (git-tracked); run state (last run, last
+session, errors) lives in `<output>/routines-state.json`.
+
+```yaml
+# agents/max/routines.yml
+- id: morning-check
+  name: Morning check
+  schedule: "0 9 * * 1-5"   # 5-field cron (server local time) or @hourly/@daily/@weekly/@monthly
+  prompt: |
+    Run the website-check workflow for https://example.com and summarize
+    anything that regressed since the last run.
+  enabled: true
+```
+
+The inspector server runs the scheduler in-process (no external cron): every
+due routine opens a fresh session for the member, posts the prompt, and the
+run shows up in the sessions sidebar titled "⏰ <name>". Routine sessions run
+unattended, so tool-permission requests are auto-approved (the
+request/approval pair stays in the thread as an audit trail) — treat routine
+prompts with the same trust as `KRAFTWERK_YES=1` workflow runs. Manage
+routines on the member page: create/edit/delete, toggle enabled, "run now",
+and jump to the last run's session. Missed schedules while the server is
+down are skipped, not replayed.
+
+## Context & Knowledge — OKF bundles
+
+Alongside runs and chats, a project can keep curated knowledge as
+[OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles (Open Knowledge Format): directories of markdown files with YAML
+frontmatter under `knowledge/`, one concept per file. Human-readable,
+agent-parseable, diffable in git — and self-describing: frontmatter
+carries provenance (`sources`, `generated`), trust (`verified`), and
+lifecycle (`status`, `stale_after`).
+
+```
+knowledge/
+  customer-support/        # one bundle per subdirectory
+    index.md               # derived directory listing (regenerated on every write)
+    log.md                 # chronological update history (appended on every write)
+    playbooks/refunds.md   # a concept: YAML frontmatter + markdown body
+```
+
+The `kraftwerk knowledge` CLI is the enforced write path — `put` stamps
+`generated: { by, at }` with the writing actor, appends the bundle log,
+and regenerates the derived `index.md`, so an agent-maintained corpus
+stays trustable:
+
+```bash
+kraftwerk knowledge init customer-support               # new bundle
+kraftwerk knowledge put customer-support/playbooks/refunds \
+  --file refunds.md --actor helpdesk-agent/claude-sonnet-5
+kraftwerk knowledge list customer-support               # concepts + trust tier
+kraftwerk knowledge get customer-support/playbooks/refunds   # raw markdown; --json parsed
+kraftwerk knowledge search "refund"                     # full-text across bundles
+kraftwerk knowledge verify customer-support/playbooks/refunds --by human:user
+kraftwerk knowledge validate                            # OKF conformance + warnings
+kraftwerk knowledge fsck --fix                          # heal out-of-band edits (reindex)
+```
+
+Actors follow the OKF convention: `<producer>/<version>` for agents,
+`human:<id>` for people, `process:<id>` for automation. Consumers derive
+a **trust tier** per concept: no `verified` ⇒ unverified, verified by
+non-human actors ⇒ machine-confirmed, verified by a `human:` actor ⇒
+human-reviewed. The inspector's **Context & Knowledge** screen shows
+bundles, concepts with trust/status/staleness badges, sources, and the
+bundle log — the ✓ verify button records a `human:user` verification, and
+"curate in chat" opens a knowledge-scoped chat whose agent knows the OKF
+essentials and writes through the CLI.
+
+Workflows read and write knowledge through the same CLI via a
+[CLI grant](#cli-grants) — the trust model stays intact because every
+agent write is stamped with its actor:
+
+```yaml
+clis:
+  npx kraftwerk knowledge: "OKF knowledge base. Read: `list`, `get <bundle>/<path>`, `search <text>`. Write: `put <bundle>/<path> --file <tmp.md> --actor triager/gpt-5.6`. Frontmatter needs `type:`; never edit index.md/log.md by hand."
+agents:
+  triager:
+    clis: [npx kraftwerk knowledge]
+```
+
 ## The agent — four axes
 
 ```ts
@@ -241,9 +379,32 @@ npm start -- validate <path>                   # runCli consumers (TS registry)
 ```
 
 Gates: `file_non_empty: <file>`, `slots_filled: <file>`,
-`contains: {file, text, label?}`. Living examples:
+`contains: {file, text, label?}`, and `check: <script>` (or
+`check: {run, label?}`) — a bash validation script executed in the run
+directory; exit 0 passes, non-zero fails and everything the script printed
+becomes the failure message, verbatim in the correction prompt. Single-line
+values reference a file inside the workflow folder, like `run:`.
+
+Steps take an optional `if:` — deterministic preconditions in the same
+forms as gates, evaluated against the run directory just before the step.
+Any unmet precondition SKIPS the step (traced as `phase_skipped`, run
+continues) — the way to avoid spawning an agent when a previous script
+found nothing to do:
+
+```yaml
+  - name: triage tickets
+    agent: triager
+    if:
+      - file_non_empty: todo.json    # written by the fetch step only when work exists
+    prompt: prompts/triage.md
+    gates:
+      - check: scripts/validate-triage.sh
+```
+
+Living examples:
 [`../agent-playground/src/workflows/tagline/`](../agent-playground/src/workflows/tagline/)
-and [`../agent-playground/src/workflows/pitch/`](../agent-playground/src/workflows/pitch/).
+and [`../agent-playground/src/workflows/pitch/`](../agent-playground/src/workflows/pitch/);
+`check`/`if` in [`../agent-playground/src/workflows/helpdesk-check/`](../agent-playground/src/workflows/helpdesk-check/).
 v1 is deliberately linear — approval loops, AGENTS.md-style context files
 and skills stay on the roadmap; anything non-linear is a TS workflow.
 

package/dist/cli/doctor.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { resolveProject } from "../config.js";
@@ -13,6 +14,31 @@ const ICONS = {
 function report(level, label, detail) {
     console.log(`${ICONS[level]} ${label}${detail ? chalk.dim(` — ${detail}`) : ""}`);
 }
+/** True if a < b for plain x.y.z versions (prerelease tags ignored). */
+function semverLt(a, b) {
+    const pa = a.split("-")[0].split(".").map(Number);
+    const pb = b.split("-")[0].split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) < (pb[i] ?? 0);
+    }
+    return false;
+}
+/** Latest published version from the npm registry, or undefined if unreachable. */
+async function latestNpmVersion(name) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        return data.version;
+    }
+    catch {
+        return undefined;
+    }
+}
 function cliVersion(command) {
     const r = spawnSync(command, ["--version"], { encoding: "utf8", timeout: 10_000 });
     if (r.status !== 0)
@@ -29,6 +55,18 @@ export async function runDoctor(cwd) {
         report("fail", `node ${process.versions.node}`, "kraftwerk needs node >= 20");
         failures++;
     }
+    // kraftwerk version vs npm.
+    const pkg = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+    const latest = await latestNpmVersion(pkg.name);
+    if (!latest) {
+        report("info", `kraftwerk ${pkg.version}`, "could not reach npm registry to check for updates");
+    }
+    else if (semverLt(pkg.version, latest)) {
+        report("warn", `kraftwerk ${pkg.version}`, `${latest} available — npm i -g ${pkg.name}@latest`);
+    }
+    else {
+        report("ok", `kraftwerk ${pkg.version}`, latest === pkg.version ? "latest on npm" : `ahead of npm (latest: ${latest})`);
+    }
     // Project.
     const project = await resolveProject(cwd);
     report("info", `Project root: ${project.root}`, project.configPath ? path.basename(project.configPath) : "no kraftwerk.yml (fallback: workflows folder or .git)");

package/dist/cli/knowledge.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerKnowledgeCommands(program: Command): void;

package/dist/cli/knowledge.js

@@ -0,0 +1,213 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import { resolveProject } from "../config.js";
+import { fsck, getConcept, initBundle, knowledgeRoot, listBundles, listConcepts, searchKnowledge, validateBundle, verifyConcept, writeConcept, } from "../okf.js";
+/**
+ * `kraftwerk knowledge` — the CLI surface over OKF bundles (Context &
+ * Knowledge). This is the enforced write path: `put` stamps provenance
+ * (`generated: { by, at }`), appends the bundle log, and regenerates
+ * index.md; direct file edits are healed by `fsck --fix`.
+ *
+ * Agents identify via --actor (or KRAFTWERK_ACTOR); the OKF convention is
+ * `<producer>/<version>` for agents, `human:<id>` for people,
+ * `process:<id>` for automation. Humans default to `human:user`.
+ */
+const DEFAULT_ACTOR = "human:user";
+const actorOf = (opts) => opts.actor?.trim() || process.env.KRAFTWERK_ACTOR?.trim() || DEFAULT_ACTOR;
+async function root() {
+    const project = await resolveProject(process.cwd());
+    return knowledgeRoot(project.root, project.config.knowledge);
+}
+/** Split "bundle/path/to/concept" into its bundle and concept id. */
+function splitRef(ref) {
+    const clean = ref.replace(/^\/+/, "");
+    const slash = clean.indexOf("/");
+    if (slash <= 0 || slash === clean.length - 1) {
+        throw new Error(`expected <bundle>/<concept-path>, got "${ref}"`);
+    }
+    return { bundle: clean.slice(0, slash), id: clean.slice(slash + 1) };
+}
+const tierColor = (tier) => tier === "human-reviewed"
+    ? chalk.green(tier)
+    : tier === "machine-confirmed"
+        ? chalk.cyan(tier)
+        : chalk.dim(tier);
+function conceptLine(c) {
+    const flags = [
+        c.status !== "stable" ? chalk.yellow(c.status) : "",
+        c.stale ? chalk.red("stale") : "",
+        c.error ? chalk.red("invalid") : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return (`  ${chalk.cyan(c.id.padEnd(32))} ${(c.type ?? "?").padEnd(22)} ` +
+        `${tierColor(c.trustTier).padEnd(18)} ${flags}`);
+}
+function printIssues(issues) {
+    for (const i of issues) {
+        const mark = i.level === "error" ? chalk.red("✖") : chalk.yellow("⚠");
+        console.log(`${mark} ${i.bundle}/${i.file}: ${i.message}`);
+    }
+}
+async function readStdin() {
+    let data = "";
+    for await (const chunk of process.stdin)
+        data += chunk;
+    return data;
+}
+export function registerKnowledgeCommands(program) {
+    const knowledge = program
+        .command("knowledge")
+        .description("Context & Knowledge: OKF bundles under knowledge/ (read, write, verify)");
+    knowledge
+        .command("list", { isDefault: true })
+        .description("List bundles, or the concepts of one bundle")
+        .argument("[bundle]", "Bundle name (a directory under knowledge/)")
+        .option("--json", "Machine-readable output")
+        .action(async (bundle, opts) => {
+        const kroot = await root();
+        if (!bundle) {
+            const bundles = await listBundles(kroot);
+            if (opts.json)
+                return void console.log(JSON.stringify({ root: kroot, bundles }, null, 2));
+            if (bundles.length === 0) {
+                console.log(chalk.yellow(`No knowledge bundles in ${kroot} — create one with \`kraftwerk knowledge init <name>\`.`));
+                return;
+            }
+            for (const b of bundles) {
+                console.log(`${chalk.cyan(b.name.padEnd(24))} ${String(b.concepts).padStart(3)} concepts` +
+                    chalk.dim(`${b.okfVersion ? `  okf ${b.okfVersion}` : ""}${b.updatedAt ? `  updated ${b.updatedAt.slice(0, 10)}` : ""}`));
+            }
+            return;
+        }
+        const concepts = await listConcepts(kroot, bundle);
+        if (opts.json)
+            return void console.log(JSON.stringify({ bundle, concepts }, null, 2));
+        if (concepts.length === 0) {
+            console.log(chalk.yellow(`Bundle "${bundle}" has no concepts.`));
+            return;
+        }
+        console.log(chalk.bold(`  ${"concept".padEnd(32)} ${"type".padEnd(22)} trust`));
+        for (const c of concepts)
+            console.log(conceptLine(c));
+    });
+    knowledge
+        .command("get")
+        .description("Print one concept (raw markdown; --json adds parsed frontmatter + trust)")
+        .argument("<ref>", "<bundle>/<concept-path>, e.g. finance/metrics/revenue")
+        .option("--json", "Machine-readable output")
+        .action(async (ref, opts) => {
+        const { bundle, id } = splitRef(ref);
+        const concept = await getConcept(await root(), bundle, id);
+        if (!concept) {
+            console.error(chalk.red(`Concept ${ref} not found.`));
+            process.exit(2);
+        }
+        if (opts.json) {
+            const { raw, ...rest } = concept;
+            console.log(JSON.stringify(rest, null, 2));
+        }
+        else {
+            process.stdout.write(concept.raw);
+        }
+    });
+    knowledge
+        .command("put")
+        .description("Write a concept from stdin or --file (stamps generated.by/at, logs, reindexes)")
+        .argument("<ref>", "<bundle>/<concept-path>")
+        .option("--file <path>", "Read the concept markdown from a file instead of stdin")
+        .option("--actor <actor>", `Who writes: <producer>/<version>, human:<id>, process:<id> (default: ${DEFAULT_ACTOR})`)
+        .action(async (ref, opts) => {
+        const { bundle, id } = splitRef(ref);
+        const content = opts.file ? await readFile(path.resolve(opts.file), "utf8") : await readStdin();
+        if (!content.trim()) {
+            console.error(chalk.red("No content (pipe markdown on stdin or pass --file)."));
+            process.exit(2);
+        }
+        try {
+            const result = await writeConcept(await root(), bundle, id, content, actorOf(opts));
+            console.log(`${chalk.green("✔")} ${result.created ? "created" : "updated"} ${chalk.cyan(`${bundle}/${result.concept.id}`)} ` +
+                chalk.dim(`(${result.concept.type}, by ${actorOf(opts)})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    knowledge
+        .command("verify")
+        .description("Record a verification event on a concept (raises its trust tier)")
+        .argument("<ref>", "<bundle>/<concept-path>")
+        .option("--by <actor>", `Verifier actor (default: ${DEFAULT_ACTOR})`)
+        .action(async (ref, opts) => {
+        const { bundle, id } = splitRef(ref);
+        const actor = opts.by?.trim() || process.env.KRAFTWERK_ACTOR?.trim() || DEFAULT_ACTOR;
+        try {
+            const concept = await verifyConcept(await root(), bundle, id, actor);
+            console.log(`${chalk.green("✔")} ${ref} verified by ${actor} → ${tierColor(concept.trustTier)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    knowledge
+        .command("search")
+        .description("Full-text search across bundles")
+        .argument("<query>", "Search text (case-insensitive substring)")
+        .option("--bundle <name>", "Restrict to one bundle")
+        .option("--json", "Machine-readable output")
+        .action(async (query, opts) => {
+        const hits = await searchKnowledge(await root(), query, opts.bundle);
+        if (opts.json)
+            return void console.log(JSON.stringify({ query, hits }, null, 2));
+        if (hits.length === 0)
+            return void console.log(chalk.dim("No matches."));
+        for (const h of hits) {
+            console.log(`${chalk.cyan(`${h.bundle}/${h.id}`)} ${chalk.dim(`(${h.type ?? "?"})`)}\n  ${h.snippet}`);
+        }
+    });
+    knowledge
+        .command("init")
+        .description("Create an empty bundle (index.md + log.md)")
+        .argument("<bundle>", "Bundle name")
+        .action(async (bundle) => {
+        try {
+            const dir = await initBundle(await root(), bundle);
+            console.log(`${chalk.green("✔")} bundle ${chalk.cyan(bundle)} created at ${dir}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    knowledge
+        .command("validate")
+        .description("OKF conformance check (errors) + provenance/staleness warnings")
+        .argument("[bundle]", "Bundle name; without it: all bundles")
+        .action(async (bundle) => {
+        const kroot = await root();
+        const bundles = bundle ? [bundle] : (await listBundles(kroot)).map((b) => b.name);
+        let errors = 0;
+        for (const b of bundles) {
+            const issues = await validateBundle(kroot, b);
+            printIssues(issues);
+            errors += issues.filter((i) => i.level === "error").length;
+        }
+        if (errors === 0)
+            console.log(chalk.green(`✔ ${bundles.length} bundle(s) conformant`));
+        process.exit(errors > 0 ? 1 : 0);
+    });
+    knowledge
+        .command("fsck")
+        .description("Validate all bundles; --fix regenerates every derived index.md")
+        .option("--fix", "Regenerate index.md files (heals out-of-band writes)")
+        .action(async (opts) => {
+        const issues = await fsck(await root(), !!opts.fix);
+        printIssues(issues);
+        if (opts.fix)
+            console.log(chalk.green("✔ indexes regenerated"));
+        process.exit(issues.some((i) => i.level === "error") ? 1 : 0);
+    });
+}

package/dist/cli/kraftwerk.js

@@ -11,6 +11,7 @@ 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";
 /**
@@ -20,6 +21,7 @@ import { runUi } from "./ui.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 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
@@ -251,6 +253,7 @@ runs
     .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/config.d.ts

@@ -11,6 +11,8 @@
  *
  *   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";
@@ -20,6 +22,10 @@ export interface ProjectConfig {
     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

@@ -14,6 +14,8 @@ import { parse } from "yaml";
  *
  *   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 +83,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 (workflows, output, knowledge)`);
     }
     const config = raw;
-    const known = ["workflows", "output"];
+    const known = ["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/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,13 @@ 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: [] });
+    const session = await conn.newSession({
+        cwd,
+        mcpServers: [],
+        ...(agent === "claude" && tuning.model
+            ? { _meta: { claudeCode: { options: { model: tuning.model } } } }
+            : {}),
+    });
     const sessionId = session.sessionId;
     return {
         async prompt(text) {