@netnodeag/kraftwerk 0.4.0 → 0.6.0

package/dist/inspector/server.js

@@ -5,6 +5,10 @@ import { setOutputDir, getOutputDir } from "./context.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 { bundleDetail, conceptDetail, createBundle, knowledgeIndex, putConcept, verifyFromUi, } from "./knowledge.js";
+import { deleteMember, getMember, listMembers, saveMember, teamRoot, } from "./team.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 +35,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));
 }
@@ -140,6 +147,270 @@ 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/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);
+            }
+        }
+    }
+    // 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 +438,7 @@ 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);
+    startRoutineScheduler();
     const server = http.createServer(async (req, res) => {
         try {
             const url = new URL(req.url ?? "/", "http://localhost");

package/dist/inspector/team.d.ts

@@ -0,0 +1,50 @@
+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[];
+}
+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[];
+    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,119 @@
+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) : [],
+    };
+}
+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),
+    };
+    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 });
+}

package/dist/okf.d.ts

@@ -0,0 +1,118 @@
+/**
+ * OKF (Open Knowledge Format) core — kraftwerk's "Context & Knowledge"
+ * feature. Implements OKF v0.2 (github.com/GoogleCloudPlatform/knowledge-catalog):
+ * a knowledge bundle is a directory of markdown files with YAML frontmatter,
+ * one concept per file, plus the reserved index.md / log.md.
+ *
+ * Layout: <project>/knowledge/<bundle>/**\/*.md — each direct subdirectory of
+ * the knowledge root is one bundle (the unit of distribution). The root is
+ * configurable via `knowledge:` in kraftwerk.yml.
+ *
+ * Design decisions:
+ * - Writes go through writeConcept()/verifyConcept() so provenance is
+ *   enforced: every put stamps `generated: { by, at }`, appends to the
+ *   bundle's log.md, and regenerates index.md. Frontmatter edits use the
+ *   yaml Document API, so unknown keys and comments survive round-trips
+ *   (spec §4.1 requires preserving unknown keys).
+ * - index.md is fully derived from concept frontmatter — regeneration is
+ *   idempotent, so concurrent writers and out-of-band edits self-heal on
+ *   the next regen (or via fsck --fix).
+ * - Consumers are permissive per spec §11: unknown types, missing optional
+ *   families, and broken links never reject a concept.
+ */
+export declare const DEFAULT_KNOWLEDGE_DIR = "knowledge";
+export declare const OKF_VERSION = "0.2";
+export type TrustTier = "unverified" | "machine-confirmed" | "human-reviewed";
+export type ConceptStatus = "draft" | "stable" | "deprecated";
+export interface VerifiedEntry {
+    by?: string;
+    at?: string;
+}
+export interface SourceEntry {
+    id?: string;
+    resource?: string;
+    title?: string;
+    author?: string;
+    usage_count?: number;
+    last_modified?: string;
+}
+export interface ConceptInfo {
+    /** Concept ID: path within the bundle, `.md` stripped (spec §2). */
+    id: string;
+    bundle: string;
+    type?: string;
+    title: string;
+    description?: string;
+    tags: string[];
+    status: ConceptStatus;
+    trustTier: TrustTier;
+    staleAfter?: string;
+    stale: boolean;
+    generated?: {
+        by?: string;
+        at?: string;
+    };
+    verified: VerifiedEntry[];
+    /** Frontmatter problem (missing block, bad YAML, missing type). */
+    error?: string;
+}
+export interface ConceptDetail extends ConceptInfo {
+    frontmatter: Record<string, unknown> | null;
+    body: string;
+    raw: string;
+    sources: SourceEntry[];
+}
+export interface BundleInfo {
+    name: string;
+    concepts: number;
+    /** Latest generated.at / verified.at across concepts, for sorting. */
+    updatedAt?: string;
+    okfVersion?: string;
+}
+export interface ValidationIssue {
+    bundle: string;
+    file: string;
+    level: "error" | "warning";
+    message: string;
+}
+export declare function knowledgeRoot(projectRoot: string, configured?: string): string;
+export declare function safeBundleName(name: string): string;
+/** Normalize a concept id: strip .md, forbid escapes and absolute paths. */
+export declare function safeConceptId(id: string): string;
+export declare function conceptFile(root: string, bundle: string, id: string): string;
+export declare function trustTier(verified: VerifiedEntry[]): TrustTier;
+export declare function listBundles(root: string): Promise<BundleInfo[]>;
+export declare function listConcepts(root: string, bundle: string): Promise<ConceptInfo[]>;
+export declare function getConcept(root: string, bundle: string, id: string): Promise<ConceptDetail | null>;
+export interface WriteResult {
+    file: string;
+    created: boolean;
+    concept: ConceptDetail;
+}
+/**
+ * The enforced write path: validates, stamps provenance, appends the
+ * bundle log, and regenerates index.md.
+ */
+export declare function writeConcept(root: string, bundle: string, id: string, content: string, actor: string): Promise<WriteResult>;
+/** Append a verification event (`verified: [{ by, at }]`) to a concept. */
+export declare function verifyConcept(root: string, bundle: string, id: string, actor: string): Promise<ConceptDetail>;
+/**
+ * Derived, idempotent bundle-root index.md (§8): one section per top-level
+ * subdirectory plus a root section, entries pulled from frontmatter.
+ */
+export declare function regenerateIndex(root: string, bundle: string): Promise<void>;
+/** Prepend an entry under today's date heading in the bundle's log.md (§9). */
+export declare function appendLog(root: string, bundle: string, entry: string): Promise<void>;
+export declare function initBundle(root: string, bundle: string): Promise<string>;
+/** Conformance per §11 plus advisory warnings (missing provenance, stale). */
+export declare function validateBundle(root: string, bundle: string): Promise<ValidationIssue[]>;
+export interface SearchHit {
+    bundle: string;
+    id: string;
+    title: string;
+    type?: string;
+    snippet: string;
+}
+export declare function searchKnowledge(root: string, query: string, bundle?: string): Promise<SearchHit[]>;
+/** Re-derive every bundle index; returns all validation issues found. */
+export declare function fsck(root: string, fix: boolean): Promise<ValidationIssue[]>;