@netnodeag/kraftwerk 0.4.1 → 0.7.0

package/dist/inspector/server.js

@@ -1,10 +1,16 @@
 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, 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.
  * Serves the prebuilt SPA (inspector/dist) plus the JSON/file API the
@@ -31,6 +37,9 @@ const MIME = {
 /** Text preview payloads are capped; the tail matters most for logs. */
 const MAX_TEXT = 400_000;
 function json(res, body, status = 200) {
+    // A late error on an SSE response must not try to write headers again.
+    if (res.headersSent)
+        return void res.end();
     res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
     res.end(JSON.stringify(body));
 }
@@ -46,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 });
+    }
     // GET /api/runs
     if (seg.length === 2 && seg[1] === "runs" && method === "GET") {
         return json(res, { outputDir: getOutputDir(), runs: await listRuns() });
@@ -140,6 +169,284 @@ async function handleApi(req, res, url) {
             }
         }
     }
+    // GET/POST /api/knowledge — bundle index / create a bundle
+    if (seg.length === 2 && seg[1] === "knowledge") {
+        if (method === "GET")
+            return json(res, await knowledgeIndex());
+        if (method === "POST") {
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                return json(res, { error: "invalid JSON body" }, 400);
+            }
+            try {
+                return json(res, await createBundle(String(body.name ?? "").trim()));
+            }
+            catch (err) {
+                return json(res, { error: err.message }, 400);
+            }
+        }
+    }
+    // GET /api/knowledge/:bundle — concepts + log
+    if (seg.length === 3 && seg[1] === "knowledge" && method === "GET") {
+        try {
+            const detail = await bundleDetail(decodeURIComponent(seg[2]));
+            return detail ? json(res, detail) : json(res, { error: "not found" }, 404);
+        }
+        catch {
+            return json(res, { error: "invalid bundle name" }, 400);
+        }
+    }
+    // GET/POST /api/knowledge/:bundle/concept?id=... — read / write one concept
+    if (seg.length === 4 && seg[1] === "knowledge" && seg[3] === "concept") {
+        const bundle = decodeURIComponent(seg[2]);
+        if (method === "GET") {
+            const id = url.searchParams.get("id") ?? "";
+            try {
+                const concept = await conceptDetail(bundle, id);
+                return concept ? json(res, concept) : json(res, { error: "not found" }, 404);
+            }
+            catch (err) {
+                return json(res, { error: err.message }, 400);
+            }
+        }
+        if (method === "POST") {
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                return json(res, { error: "invalid JSON body" }, 400);
+            }
+            if (!body.id || !body.content?.trim()) {
+                return json(res, { error: "id and content are required" }, 400);
+            }
+            try {
+                return json(res, await putConcept(bundle, body.id, body.content));
+            }
+            catch (err) {
+                return json(res, { error: err.message }, 400);
+            }
+        }
+    }
+    // POST /api/knowledge/:bundle/verify — human verification from the UI
+    if (seg.length === 4 && seg[1] === "knowledge" && seg[3] === "verify" && method === "POST") {
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch {
+            return json(res, { error: "invalid JSON body" }, 400);
+        }
+        if (!body.id)
+            return json(res, { error: "id is required" }, 400);
+        try {
+            return json(res, await verifyFromUi(decodeURIComponent(seg[2]), body.id));
+        }
+        catch (err) {
+            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") {
+            return json(res, { root: await teamRoot(), members: await listMembers() });
+        }
+        if (method === "POST") {
+            try {
+                const body = JSON.parse(await readBody(req));
+                return json(res, await saveMember({ ...body, slug: undefined }));
+            }
+            catch (err) {
+                return json(res, { error: err.message }, 400);
+            }
+        }
+    }
+    // GET/POST /api/team/:slug/routines — list (with run state) / upsert
+    if (seg.length === 4 && seg[1] === "team" && seg[3] === "routines") {
+        const slug = decodeURIComponent(seg[2]);
+        try {
+            if (method === "GET")
+                return json(res, { routines: await routineStatuses(slug) });
+            if (method === "POST") {
+                const body = JSON.parse(await readBody(req));
+                return json(res, await saveRoutine(slug, body));
+            }
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // DELETE /api/team/:slug/routines/:id | POST /api/team/:slug/routines/:id/run
+    if (seg.length >= 5 && seg[1] === "team" && seg[3] === "routines") {
+        const slug = decodeURIComponent(seg[2]);
+        const id = decodeURIComponent(seg[4]);
+        try {
+            if (seg.length === 5 && method === "DELETE") {
+                await deleteRoutine(slug, id);
+                return json(res, { ok: true });
+            }
+            if (seg.length === 6 && seg[5] === "run" && method === "POST") {
+                return json(res, await runRoutineNow(slug, id));
+            }
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // GET/PUT/DELETE /api/team/:slug
+    if (seg.length === 3 && seg[1] === "team") {
+        const slug = decodeURIComponent(seg[2]);
+        try {
+            if (method === "GET") {
+                const member = await getMember(slug);
+                return member ? json(res, member) : json(res, { error: "not found" }, 404);
+            }
+            if (method === "PUT") {
+                const body = JSON.parse(await readBody(req));
+                return json(res, await saveMember({ ...body, slug }));
+            }
+            if (method === "DELETE") {
+                await deleteMember(slug);
+                return json(res, { ok: true });
+            }
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // GET/POST /api/chats
+    if (seg.length === 2 && seg[1] === "chats") {
+        if (method === "GET")
+            return json(res, { chats: await listChats() });
+        if (method === "POST") {
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                return json(res, { error: "invalid JSON body" }, 400);
+            }
+            let agent = body.agent;
+            let scope;
+            if (body.scope?.kind === "team" && body.scope.member) {
+                // Team sessions run on the member's configured harness.
+                const member = await getMember(body.scope.member).catch(() => null);
+                if (!member)
+                    return json(res, { error: "team agent not found" }, 404);
+                scope = { kind: "team", member: member.slug };
+                agent = member.harness;
+            }
+            else if (body.scope?.kind === "run" && body.scope.runId) {
+                scope = { kind: "run", runId: body.scope.runId };
+            }
+            else if (body.scope?.kind === "kraftwerk") {
+                scope = { kind: "kraftwerk" };
+            }
+            else if (body.scope?.kind === "knowledge") {
+                scope = { kind: "knowledge", ...(body.scope.bundle ? { bundle: body.scope.bundle } : {}) };
+            }
+            else {
+                scope = { kind: "general" };
+            }
+            if (!["claude", "codex", "pi"].includes(agent)) {
+                return json(res, { error: "agent must be claude, codex, or pi" }, 400);
+            }
+            try {
+                return json(res, await createChat({ agent, scope }));
+            }
+            catch (err) {
+                return json(res, { error: err.message }, 400);
+            }
+        }
+    }
+    // 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 {
+            const chat = await getChat(seg[2]);
+            return chat ? json(res, chat) : json(res, { error: "not found" }, 404);
+        }
+        catch {
+            return json(res, { error: "invalid chat id" }, 400);
+        }
+    }
+    // GET /api/chats/:id/events?after=N — SSE stream of thread events.
+    if (seg.length === 4 && seg[1] === "chats" && seg[3] === "events" && method === "GET") {
+        const afterSeq = Number(url.searchParams.get("after") ?? "0") || 0;
+        const send = (ev) => {
+            res.write(`id: ${ev.seq}\ndata: ${JSON.stringify(ev)}\n\n`);
+        };
+        let unsubscribe = null;
+        try {
+            res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-store",
+                connection: "keep-alive",
+            });
+            unsubscribe = await subscribeChat(seg[2], afterSeq, send);
+        }
+        catch {
+            return void res.end();
+        }
+        if (!unsubscribe)
+            return void res.end();
+        const heartbeat = setInterval(() => res.write(":hb\n\n"), 25_000);
+        req.on("close", () => {
+            clearInterval(heartbeat);
+            unsubscribe?.();
+        });
+        return;
+    }
+    // POST /api/chats/:id/{message,permission,cancel}
+    if (seg.length === 4 && seg[1] === "chats" && method === "POST") {
+        let body = {};
+        try {
+            const raw = await readBody(req);
+            if (raw)
+                body = JSON.parse(raw);
+        }
+        catch {
+            return json(res, { error: "invalid JSON body" }, 400);
+        }
+        try {
+            let result;
+            if (seg[3] === "message") {
+                const text = String(body.text ?? "").trim();
+                if (!text)
+                    return json(res, { error: "text is required" }, 400);
+                result = await postMessage(seg[2], text);
+            }
+            else if (seg[3] === "permission") {
+                result = await resolvePermission(seg[2], String(body.requestId ?? ""), body.optionId == null ? null : String(body.optionId));
+            }
+            else if (seg[3] === "cancel") {
+                result = await cancelChat(seg[2]);
+            }
+            else {
+                return json(res, { error: "not found" }, 404);
+            }
+            return result.error ? json(res, result, 409) : json(res, { ok: true });
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
     json(res, { error: "not found" }, 404);
 }
 async function serveStatic(res, staticDir, pathname) {
@@ -167,6 +474,9 @@ 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 {
             const url = new URL(req.url ?? "/", "http://localhost");

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

@@ -0,0 +1,57 @@
+import type { ChatAgentId } from "./chat/types.js";
+/**
+ * Team: persistent agent teammates, defined on the filesystem. Each member
+ * is one folder under the project's agents/ root:
+ *
+ *   agents/<slug>/agent.yml    # name, emoji, harness, model, effort, workflows
+ *   agents/<slug>/system.md    # the member's system prompt / role description
+ *
+ * Definitions are git-tracked project config (like workflows/), not run
+ * state — sessions with a member are ordinary chats scoped to it.
+ */
+export declare const HARNESSES: ChatAgentId[];
+export declare const EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export interface TeamMember {
+    slug: string;
+    name: string;
+    emoji: string;
+    description?: string;
+    harness: ChatAgentId;
+    model?: string;
+    effort?: string;
+    /** Workflow slugs this member knows about and may run. */
+    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. */
+    system: string;
+}
+export declare function teamRoot(): Promise<string>;
+export declare function safeMemberSlug(slug: string): string;
+/** Derive a slug from a display name: "Max Müller" -> "max-mueller"-ish. */
+export declare function slugFromName(name: string): string;
+export declare function listMembers(): Promise<TeamMember[]>;
+export declare function getMember(slug: string): Promise<TeamMemberDetail | null>;
+export interface SaveMemberInput {
+    slug?: string;
+    name: string;
+    emoji?: string;
+    description?: string;
+    harness: string;
+    model?: string;
+    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>;
+export declare function deleteMember(slug: string): Promise<void>;

package/dist/inspector/team.js

@@ -0,0 +1,121 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { resolveProject } from "../config.js";
+import { getProjectRoot } from "./context.js";
+/**
+ * Team: persistent agent teammates, defined on the filesystem. Each member
+ * is one folder under the project's agents/ root:
+ *
+ *   agents/<slug>/agent.yml    # name, emoji, harness, model, effort, workflows
+ *   agents/<slug>/system.md    # the member's system prompt / role description
+ *
+ * Definitions are git-tracked project config (like workflows/), not run
+ * state — sessions with a member are ordinary chats scoped to it.
+ */
+export const HARNESSES = ["claude", "codex", "pi"];
+export const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+export async function teamRoot() {
+    const project = await resolveProject(getProjectRoot());
+    return path.resolve(project.root, project.config.agents ?? "agents");
+}
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+export function safeMemberSlug(slug) {
+    if (!SLUG_RE.test(slug))
+        throw new Error(`invalid agent slug "${slug}"`);
+    return slug;
+}
+/** Derive a slug from a display name: "Max Müller" -> "max-mueller"-ish. */
+export function slugFromName(name) {
+    const slug = name
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    if (!SLUG_RE.test(slug))
+        throw new Error("name must contain at least one letter or digit");
+    return slug;
+}
+function normalize(slug, raw) {
+    const harness = String(raw.harness ?? "claude");
+    return {
+        slug,
+        name: String(raw.name ?? slug),
+        emoji: String(raw.emoji ?? "🤖"),
+        ...(raw.description ? { description: String(raw.description) } : {}),
+        harness: HARNESSES.includes(harness) ? harness : "claude",
+        ...(raw.model ? { model: String(raw.model) } : {}),
+        ...(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() {
+    const root = await teamRoot();
+    let entries;
+    try {
+        entries = (await fs.readdir(root, { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && SLUG_RE.test(e.name))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const members = await Promise.all(entries.map(async (slug) => {
+        try {
+            const raw = parse(await fs.readFile(path.join(root, slug, "agent.yml"), "utf8"));
+            return normalize(slug, (raw ?? {}));
+        }
+        catch {
+            return null;
+        }
+    }));
+    return members.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function getMember(slug) {
+    const dir = path.join(await teamRoot(), safeMemberSlug(slug));
+    let raw;
+    try {
+        raw = parse(await fs.readFile(path.join(dir, "agent.yml"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const system = await fs.readFile(path.join(dir, "system.md"), "utf8").catch(() => "");
+    return { ...normalize(slug, (raw ?? {})), system: system.trim() };
+}
+export async function saveMember(input) {
+    const name = input.name?.trim();
+    if (!name)
+        throw new Error("name is required");
+    if (!HARNESSES.includes(input.harness)) {
+        throw new Error(`harness must be one of: ${HARNESSES.join(", ")}`);
+    }
+    if (input.effort && !EFFORTS.includes(input.effort)) {
+        throw new Error(`effort must be one of: ${EFFORTS.join(", ")}`);
+    }
+    const slug = input.slug ? safeMemberSlug(input.slug) : slugFromName(name);
+    const dir = path.join(await teamRoot(), slug);
+    await fs.mkdir(dir, { recursive: true });
+    const yml = {
+        name,
+        emoji: input.emoji?.trim() || "🤖",
+        ...(input.description?.trim() ? { description: input.description.trim() } : {}),
+        harness: input.harness,
+        ...(input.model?.trim() ? { model: input.model.trim() } : {}),
+        ...(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");
+    return (await getMember(slug));
+}
+export async function deleteMember(slug) {
+    const dir = path.join(await teamRoot(), safeMemberSlug(slug));
+    await fs.rm(dir, { recursive: true, force: true });
+}