@netnodeag/kraftwerk 0.6.0 → 0.8.0

package/dist/inspector/context.d.ts

@@ -1,5 +1,10 @@
 export declare function setOutputDir(dir: string): void;
-/** Absolute output directory (one run-* folder per run). */
+export declare function setProjectRoot(dir: string): void;
+/** Absolute output directory (runs/ + chats/ live inside). */
 export declare function getOutputDir(): string;
-/** The consumer project root is the parent of the output dir. */
+/**
+ * The consumer project root. Set explicitly at startup; falls back to the
+ * parent of the output dir (wrong for nested output dirs like
+ * kraftwerk-data/output — always pass projectRoot when known).
+ */
 export declare function getProjectRoot(): string;

package/dist/inspector/context.js

@@ -4,16 +4,24 @@ import path from "node:path";
  * Set once by startInspector() before any request is served.
  */
 let outputDir = "";
+let projectRoot = "";
 export function setOutputDir(dir) {
     outputDir = path.resolve(dir);
 }
-/** Absolute output directory (one run-* folder per run). */
+export function setProjectRoot(dir) {
+    projectRoot = path.resolve(dir);
+}
+/** Absolute output directory (runs/ + chats/ live inside). */
 export function getOutputDir() {
     if (!outputDir)
         throw new Error("inspector context not initialized");
     return outputDir;
 }
-/** The consumer project root is the parent of the output dir. */
+/**
+ * The consumer project root. Set explicitly at startup; falls back to the
+ * parent of the output dir (wrong for nested output dirs like
+ * kraftwerk-data/output — always pass projectRoot when known).
+ */
 export function getProjectRoot() {
-    return path.dirname(getOutputDir());
+    return projectRoot || path.dirname(getOutputDir());
 }

package/dist/inspector/runner.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Workflow trigger for the web UI. The inspector stays decoupled from the
+ * framework runtime: it shells out to `npx kraftwerk run` in the consumer
+ * project, detached, with a pre-chosen --run-id so the browser can jump to
+ * /runs/<id> immediately and watch the (already polling) live timeline.
+ *
+ * Sandbox mode adds --sandbox: one Docker container per run, workflow
+ * mounted read-only, run dir bind-mounted back into output/ (see
+ * kraftwerk/src/runner/docker.ts).
+ */
 export declare function dockerStatus(): {
     available: boolean;
     image: boolean;

package/dist/inspector/runner.js

@@ -2,6 +2,8 @@ import { spawn, spawnSync } from "node:child_process";
 import { mkdirSync, openSync, closeSync } from "node:fs";
 import path from "node:path";
 import { getProjectRoot } from "./context.js";
+import { RUN_ID_RE, safeRunDir } from "./runs.js";
+import { newRunId } from "../workflow.js";
 /**
  * Workflow trigger for the web UI. The inspector stays decoupled from the
  * framework runtime: it shells out to `npx kraftwerk run` in the consumer
@@ -12,10 +14,6 @@ import { getProjectRoot } from "./context.js";
  * mounted read-only, run dir bind-mounted back into output/ (see
  * kraftwerk/src/runner/docker.ts).
  */
-function stamp(d = new Date()) {
-    const p = (n) => String(n).padStart(2, "0");
-    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}-${p(d.getSeconds())}`;
-}
 export function dockerStatus() {
     const daemon = spawnSync("docker", ["version", "--format", "ok"], {
         stdio: "ignore",
@@ -37,9 +35,9 @@ export function triggerRun(opts) {
         if (!docker.image)
             throw new Error('Image "kraftwerk-runner" missing — run `kraftwerk runner build`.');
     }
-    const runId = `run-${stamp()}`;
-    // Matches the CLI's --run-id resolution: output/<id> under the project root.
-    const runDir = path.join(getProjectRoot(), "output", runId);
+    const runId = newRunId(opts.workflowName);
+    // Matches the CLI's --run-id resolution: <output dir>/runs/<id>.
+    const runDir = safeRunDir(runId);
     mkdirSync(runDir, { recursive: true });
     const log = openSync(path.join(runDir, "trigger.log"), "a");
     const args = ["kraftwerk", "run", "--yes", "--run-id", runId];
@@ -60,7 +58,7 @@ export function triggerRun(opts) {
 }
 export function stopRun(runId) {
     // Sandboxed runs run in container kw-<runId>; docker stop ends them.
-    if (!/^run-[0-9-]+$/.test(runId))
+    if (!RUN_ID_RE.test(runId))
         return false;
     return (spawnSync("docker", ["stop", `kw-${runId}`], { stdio: "ignore", timeout: 30_000 }).status === 0);
 }

package/dist/inspector/runs.d.ts

@@ -49,6 +49,8 @@ export interface RunDetail extends RunListItem {
     files: FileView[];
 }
 export declare function listRuns(): Promise<RunListItem[]>;
+/** "2026-08-25-1432-07-hello" (runs/ subdir) or legacy "run-…" (output root). */
+export declare const RUN_ID_RE: RegExp;
 export declare function safeRunDir(id: string): string;
 export declare function getRun(id: string): Promise<RunDetail | null>;
 export declare function readRunFile(id: string, name: string): Promise<{

package/dist/inspector/runs.js

@@ -3,7 +3,7 @@ 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
+ * holds one folder per run (runs/<stamp>-<workflow>, legacy run-* at the root);
  * 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. */
@@ -158,15 +158,14 @@ function shortenPath(p) {
     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 [];
-    }
+    // New runs live under <output>/runs/; legacy run-* folders sit at the root.
+    const current = (await fs.readdir(path.join(getOutputDir(), "runs")).catch(() => []))
+        .filter((e) => RUN_ID_RE.test(e) && !e.startsWith("run-"));
+    const legacy = (await fs.readdir(getOutputDir()).catch(() => []))
+        .filter((e) => e.startsWith("run-") && RUN_ID_RE.test(e));
+    const entries = [...current, ...legacy];
     const items = await Promise.all(entries.map(async (id) => {
-        const runDir = path.join(getOutputDir(), id);
+        const runDir = safeRunDir(id);
         const st = await fs.stat(runDir).catch(() => null);
         if (!st?.isDirectory())
             return null;
@@ -188,12 +187,18 @@ export async function listRuns() {
             costUsd: summary?.total?.costUsd,
         };
     }));
-    return items.filter(Boolean).sort((a, b) => b.id.localeCompare(a.id));
+    // Newest first; strip the legacy "run-" prefix so both id styles compare by stamp.
+    const stampOf = (r) => r.id.replace(/^run-/, "");
+    return items.filter(Boolean).sort((a, b) => stampOf(b).localeCompare(stampOf(a)));
 }
+/** "2026-08-25-1432-07-hello" (runs/ subdir) or legacy "run-…" (output root). */
+export const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function safeRunDir(id) {
-    if (!/^run-[0-9-]+$/.test(id))
+    if (!RUN_ID_RE.test(id))
         throw new Error("invalid run id");
-    return path.join(getOutputDir(), id);
+    return id.startsWith("run-")
+        ? path.join(getOutputDir(), id)
+        : path.join(getOutputDir(), "runs", id);
 }
 export async function getRun(id) {
     const runDir = safeRunDir(id);

package/dist/inspector/server.d.ts

@@ -3,6 +3,8 @@ export interface InspectorOptions {
     outputDir: string;
     staticDir: string;
     port: number;
+    /** Consumer project root; defaults to the parent of outputDir. */
+    projectRoot?: string;
 }
 /** 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

@@ -1,13 +1,15 @@
 import { promises as fs } from "node:fs";
 import http from "node:http";
 import path from "node:path";
-import { setOutputDir, getOutputDir } from "./context.js";
+import { setOutputDir, setProjectRoot, getOutputDir, getProjectRoot } from "./context.js";
+import { resolveProject } from "../config.js";
 import { listRuns, getRun, readRunFile } from "./runs.js";
 import { listWorkflows, getWorkflow } from "./workflows.js";
 import { dockerStatus, triggerRun, stopRun } from "./runner.js";
-import { cancelChat, createChat, getChat, listChats, postMessage, resolvePermission, subscribeChat, } from "./chat/sessions.js";
+import { cancelChat, createChat, deleteChat, getChat, listChats, postMessage, resolvePermission, subscribeChat, } from "./chat/sessions.js";
 import { bundleDetail, conceptDetail, createBundle, knowledgeIndex, putConcept, verifyFromUi, } from "./knowledge.js";
 import { deleteMember, getMember, listMembers, saveMember, teamRoot, } from "./team.js";
+import { listSkills } from "./skills.js";
 import { deleteRoutine, routineStatuses, runRoutineNow, saveRoutine, startRoutineScheduler, } from "./routines.js";
 /**
  * The inspector server: a plain node:http server with no dependencies.
@@ -53,9 +55,29 @@ function readBody(req) {
         req.on("error", reject);
     });
 }
+/** Package version, read once. Works from src/ (tsx) and dist/ alike. */
+let pkgVersion;
+async function getPkgVersion() {
+    if (pkgVersion === undefined) {
+        try {
+            const raw = await fs.readFile(new URL("../../package.json", import.meta.url), "utf8");
+            pkgVersion = JSON.parse(raw).version ?? "";
+        }
+        catch {
+            pkgVersion = "";
+        }
+    }
+    return pkgVersion;
+}
 async function handleApi(req, res, url) {
     const seg = url.pathname.split("/").filter(Boolean); // ["api", ...]
     const method = req.method ?? "GET";
+    // GET /api/meta — package version + project name ("environment") for the UI
+    if (seg.length === 2 && seg[1] === "meta" && method === "GET") {
+        const project = await resolveProject(getProjectRoot()).catch(() => null);
+        const projectName = project?.config.name ?? (project ? path.basename(project.root) : "");
+        return json(res, { version: await getPkgVersion(), projectName, projectIcon: project?.config.icon ?? "" });
+    }
     // GET /api/runs
     if (seg.length === 2 && seg[1] === "runs" && method === "GET") {
         return json(res, { outputDir: getOutputDir(), runs: await listRuns() });
@@ -227,6 +249,10 @@ async function handleApi(req, res, url) {
             return json(res, { error: err.message }, 400);
         }
     }
+    // GET /api/skills — discovered skills (project + user .claude/skills)
+    if (seg.length === 2 && seg[1] === "skills" && method === "GET") {
+        return json(res, { skills: await listSkills() });
+    }
     // GET/POST /api/team — member list / create a member
     if (seg.length === 2 && seg[1] === "team") {
         if (method === "GET") {
@@ -340,6 +366,16 @@ async function handleApi(req, res, url) {
             }
         }
     }
+    // DELETE /api/chats/:id
+    if (seg.length === 3 && seg[1] === "chats" && method === "DELETE") {
+        try {
+            const result = await deleteChat(seg[2]);
+            return json(res, result, result.error ? 404 : 200);
+        }
+        catch {
+            return json(res, { error: "invalid chat id" }, 400);
+        }
+    }
     // GET /api/chats/:id
     if (seg.length === 3 && seg[1] === "chats" && method === "GET") {
         try {
@@ -438,6 +474,8 @@ async function serveStatic(res, staticDir, pathname) {
 /** Start the server; resolves once it listens. Runs until the process ends. */
 export function startInspector(opts) {
     setOutputDir(opts.outputDir);
+    if (opts.projectRoot)
+        setProjectRoot(opts.projectRoot);
     startRoutineScheduler();
     const server = http.createServer(async (req, res) => {
         try {

package/dist/inspector/skills.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Skills: reusable instruction packages for chats, discovered from the
+ * Claude-style skill layout — one folder per skill holding a SKILL.md with
+ * YAML frontmatter (name, description). Two roots are scanned:
+ *
+ *   <projectRoot>/.claude/skills/<name>/SKILL.md   (git-tracked, per project)
+ *   ~/.claude/skills/<name>/SKILL.md               (personal, per user)
+ *
+ * A project skill shadows a user skill with the same name. Skills are
+ * surfaced to every chat as context (and expanded on /<name> invocation),
+ * so they work identically on claude, codex, and pi.
+ */
+export interface SkillInfo {
+    /** Frontmatter `name`, falling back to the folder name. */
+    name: string;
+    description: string;
+    /** Absolute path to the SKILL.md file. */
+    path: string;
+    /** Absolute path to the skill folder (for harnesses that take a dir). */
+    dir: string;
+    source: "project" | "user";
+}
+/** All discovered skills; a project skill shadows a same-named user skill. */
+export declare function listSkills(): Promise<SkillInfo[]>;
+/** Read a skill's SKILL.md contents (empty string when unreadable). */
+export declare function readSkill(skill: SkillInfo): Promise<string>;

package/dist/inspector/skills.js

@@ -0,0 +1,65 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse } from "yaml";
+import { getProjectRoot } from "./context.js";
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+function frontmatter(md) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/.exec(md);
+    if (!m)
+        return {};
+    try {
+        const parsed = parse(m[1]);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function scanRoot(root, source) {
+    let entries;
+    try {
+        entries = (await fs.readdir(root, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const skills = await Promise.all(entries.map(async (dirName) => {
+        const dir = path.join(root, dirName);
+        const file = path.join(dir, "SKILL.md");
+        let md;
+        try {
+            md = await fs.readFile(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+        const fm = frontmatter(md);
+        const name = String(fm.name ?? dirName).trim() || dirName;
+        if (!NAME_RE.test(name))
+            return null;
+        return {
+            name,
+            description: String(fm.description ?? "").trim(),
+            path: file,
+            dir,
+            source,
+        };
+    }));
+    return skills.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
+}
+/** All discovered skills; a project skill shadows a same-named user skill. */
+export async function listSkills() {
+    const [project, user] = await Promise.all([
+        scanRoot(path.join(getProjectRoot(), ".claude", "skills"), "project"),
+        scanRoot(path.join(os.homedir(), ".claude", "skills"), "user"),
+    ]);
+    const seen = new Set(project.map((s) => s.name.toLowerCase()));
+    return [...project, ...user.filter((s) => !seen.has(s.name.toLowerCase()))];
+}
+/** Read a skill's SKILL.md contents (empty string when unreadable). */
+export function readSkill(skill) {
+    return fs.readFile(skill.path, "utf8").catch(() => "");
+}

package/dist/inspector/team.d.ts

@@ -23,6 +23,11 @@ export interface TeamMember {
     workflows: string[];
     /** Knowledge bundles (OKF) this member works with. */
     knowledge: string[];
+    /**
+     * Skill allowlist (names from .claude/skills, project or user level).
+     * Absent = all discovered skills; empty list = no skills.
+     */
+    skills?: string[];
 }
 export interface TeamMemberDetail extends TeamMember {
     /** Contents of system.md — the member's system prompt. */
@@ -44,6 +49,8 @@ export interface SaveMemberInput {
     effort?: string;
     workflows?: string[];
     knowledge?: string[];
+    /** Omit for "all skills"; a list (possibly empty) restricts to those names. */
+    skills?: string[];
     system?: string;
 }
 export declare function saveMember(input: SaveMemberInput): Promise<TeamMemberDetail>;

package/dist/inspector/team.js

@@ -50,6 +50,7 @@ function normalize(slug, raw) {
         ...(raw.effort ? { effort: String(raw.effort) } : {}),
         workflows: Array.isArray(raw.workflows) ? raw.workflows.map(String) : [],
         knowledge: Array.isArray(raw.knowledge) ? raw.knowledge.map(String) : [],
+        ...(Array.isArray(raw.skills) ? { skills: raw.skills.map(String) } : {}),
     };
 }
 export async function listMembers() {
@@ -108,6 +109,7 @@ export async function saveMember(input) {
         ...(input.effort ? { effort: input.effort } : {}),
         workflows: (input.workflows ?? []).map(String),
         knowledge: (input.knowledge ?? []).map(String),
+        ...(input.skills ? { skills: input.skills.map(String) } : {}),
     };
     await fs.writeFile(path.join(dir, "agent.yml"), stringify(yml));
     await fs.writeFile(path.join(dir, "system.md"), (input.system ?? "").trim() + "\n");

package/dist/runner/docker.d.ts

@@ -1,12 +1,14 @@
 export interface SandboxOptions {
     /** Consumer project root (where output/ lives). */
     projectRoot: string;
+    /** Output directory; defaults to <projectRoot>/output (kraftwerk.yml `output:` may differ). */
+    outputDir?: 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. */
+    /** Pre-chosen run id; generated from workflow name + stamp when omitted. */
     runId?: string;
     /** Forward the host SSH agent + known_hosts into the container. */
     ssh?: boolean;

package/dist/runner/docker.js

@@ -4,7 +4,7 @@ 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";
+import { newRunId, runDirFor } from "../workflow.js";
 /**
  * Docker sandbox runner: one container per workflow run.
  *
@@ -57,8 +57,8 @@ export async function runSandboxed(opts) {
     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);
+    const runId = opts.runId ?? newRunId(opts.workflowName);
+    const runDir = runDirFor(opts.outputDir ?? 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
@@ -73,8 +73,8 @@ export async function runSandboxed(opts) {
         "--memory", opts.memory ?? "2g",
         "--cpus", opts.cpus ?? "2",
         "-v", `${wfAbs}:${wfTarget}:ro`,
-        "-v", `${runDir}:/work/output/${runId}`,
-        "-e", `KRAFTWERK_RUN_DIR=/work/output/${runId}`,
+        "-v", `${runDir}:/work/output/runs/${runId}`,
+        "-e", `KRAFTWERK_RUN_DIR=/work/output/runs/${runId}`,
     ];
     const envFile = path.join(opts.projectRoot, ENV_FILE);
     if (existsSync(envFile))

package/dist/workflow.d.ts

@@ -22,3 +22,10 @@ export interface WorkflowDefinition {
 }
 /** Local-time run-folder stamp: "2026-08-13-1432-07" (sortable, no colons). */
 export declare function runStamp(date?: Date): string;
+/** Run-folder name: "<stamp>-<workflow-slug>", e.g. "2026-08-25-1432-07-hello". */
+export declare function newRunId(workflowName: string, date?: Date): string;
+/**
+ * Where a run's folder lives: <output>/runs/<id>. Legacy ids ("run-<stamp>",
+ * pre-runs-subfolder) stay at the output root so old runs remain readable.
+ */
+export declare function runDirFor(outputDir: string, runId: string): string;

package/dist/workflow.js

@@ -3,9 +3,28 @@
  * A workflow owns its run directory, roster, prompts, and gates; the
  * framework only provides the phase runner and the CLI dispatch.
  */
+import path from "node:path";
 /** 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())}`);
 }
+/** Run-folder name: "<stamp>-<workflow-slug>", e.g. "2026-08-25-1432-07-hello". */
+export function newRunId(workflowName, date = new Date()) {
+    const slug = workflowName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40) || "workflow";
+    return `${runStamp(date)}-${slug}`;
+}
+/**
+ * Where a run's folder lives: <output>/runs/<id>. Legacy ids ("run-<stamp>",
+ * pre-runs-subfolder) stay at the output root so old runs remain readable.
+ */
+export function runDirFor(outputDir, runId) {
+    return runId.startsWith("run-")
+        ? path.join(outputDir, runId)
+        : path.join(outputDir, "runs", runId);
+}

package/dist/yaml.js

@@ -6,7 +6,7 @@ import { envelopeContract } from "./envelope.js";
 import { checkScript, containsText, fileNonEmpty, slotsFilled } from "./gates.js";
 import { Run } from "./run.js";
 import { summaryTable } from "./stats.js";
-import { runStamp } from "./workflow.js";
+import { newRunId } from "./workflow.js";
 /**
  * YAML-configured workflows (v1: a linear sequence of gated agent steps).
  * Vocabulary borrows from GitHub Actions: `steps`, `runs-on` (the harness),
@@ -266,7 +266,7 @@ export async function loadWorkflow(givenPath) {
             // the run directory upfront so it can mount/watch it by name.
             const runDir = process.env.KRAFTWERK_RUN_DIR
                 ? path.resolve(process.env.KRAFTWERK_RUN_DIR)
-                : path.resolve("output", `run-${runStamp()}`);
+                : path.resolve("output", "runs", newRunId(raw.name));
             await mkdir(runDir, { recursive: true });
             const run = new Run({
                 runDir,