@netnodeag/kraftwerk 0.4.1 → 0.6.0

package/dist/inspector/routines.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Routines: per-team-member scheduled prompts — "message your agent every
+ * weekday at 9". Definitions live next to the member (git-tracked):
+ *
+ *   agents/<slug>/routines.yml    # list of { id, name, schedule, prompt, enabled }
+ *
+ * Runtime state (last run / last session / errors) is run-state, not
+ * config, so it lives in <output>/routines-state.json. The scheduler is a
+ * plain interval inside the inspector server: each due routine opens a new
+ * session (chat) for the member and posts the prompt — the run shows up in
+ * the member's sessions sidebar like any conversation. Schedules use
+ * standard 5-field cron in the server's local time.
+ */
+export interface Routine {
+    id: string;
+    name: string;
+    /** 5-field cron (min hour dom month dow) or @hourly/@daily/@weekly/@monthly. */
+    schedule: string;
+    prompt: string;
+    enabled: boolean;
+}
+export interface RoutineStatus extends Routine {
+    nextRunAt?: string;
+    lastRunAt?: string;
+    lastChatId?: string;
+    lastError?: string;
+}
+interface CronSpec {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    domStar: boolean;
+    dowStar: boolean;
+}
+export declare function parseCron(expr: string): CronSpec;
+/** Next matching instant after `from`, scanning up to 60 days; undefined if none. */
+export declare function nextRun(schedule: string, from?: Date): string | undefined;
+export declare function listRoutines(slug: string): Promise<Routine[]>;
+export interface SaveRoutineInput {
+    id?: string;
+    name: string;
+    schedule: string;
+    prompt: string;
+    enabled?: boolean;
+}
+export declare function saveRoutine(slug: string, input: SaveRoutineInput): Promise<Routine>;
+export declare function deleteRoutine(slug: string, id: string): Promise<void>;
+export declare function routineStatuses(slug: string): Promise<RoutineStatus[]>;
+export declare function runRoutineNow(slug: string, id: string): Promise<{
+    chatId: string;
+}>;
+/** Start the in-process scheduler; safe to call more than once. */
+export declare function startRoutineScheduler(): void;
+export {};

package/dist/inspector/routines.js

@@ -0,0 +1,266 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { getOutputDir } from "./context.js";
+import { getMember, listMembers, safeMemberSlug, teamRoot } from "./team.js";
+import { createChat, postMessage } from "./chat/sessions.js";
+/* ---------- cron ---------- */
+const ALIASES = {
+    "@hourly": "0 * * * *",
+    "@daily": "0 0 * * *",
+    "@weekly": "0 0 * * 0",
+    "@monthly": "0 0 1 * *",
+};
+function parseField(spec, min, max, label) {
+    const out = new Set();
+    for (const part of spec.split(",")) {
+        const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+        if (!m)
+            throw new Error(`invalid ${label} field "${part}"`);
+        const step = m[2] ? Number(m[2]) : 1;
+        if (step < 1)
+            throw new Error(`invalid step in ${label} field`);
+        let lo = min;
+        let hi = max;
+        if (m[1] !== "*") {
+            const [a, b] = m[1].split("-").map(Number);
+            lo = a;
+            hi = b ?? (m[2] ? max : a); // "a/n" means a..max stepped; bare "a" is exact
+        }
+        if (lo < min || hi > max || lo > hi)
+            throw new Error(`${label} field out of range (${min}-${max})`);
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+export function parseCron(expr) {
+    const fields = (ALIASES[expr.trim()] ?? expr.trim()).split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error("schedule must be 5 cron fields (min hour dom month dow) or an @alias");
+    }
+    const spec = {
+        minute: parseField(fields[0], 0, 59, "minute"),
+        hour: parseField(fields[1], 0, 23, "hour"),
+        dom: parseField(fields[2], 1, 31, "day-of-month"),
+        month: parseField(fields[3], 1, 12, "month"),
+        dow: new Set(
+        // 7 is an alias for Sunday (0)
+        [...parseField(fields[4], 0, 7, "day-of-week")].map((v) => (v === 7 ? 0 : v))),
+        domStar: fields[2] === "*",
+        dowStar: fields[4] === "*",
+    };
+    return spec;
+}
+function cronMatches(spec, d) {
+    if (!spec.minute.has(d.getMinutes()))
+        return false;
+    if (!spec.hour.has(d.getHours()))
+        return false;
+    if (!spec.month.has(d.getMonth() + 1))
+        return false;
+    const domOk = spec.dom.has(d.getDate());
+    const dowOk = spec.dow.has(d.getDay());
+    // Standard cron rule: if both day fields are restricted, either may match.
+    if (!spec.domStar && !spec.dowStar)
+        return domOk || dowOk;
+    return domOk && dowOk;
+}
+/** Next matching instant after `from`, scanning up to 60 days; undefined if none. */
+export function nextRun(schedule, from = new Date()) {
+    let spec;
+    try {
+        spec = parseCron(schedule);
+    }
+    catch {
+        return undefined;
+    }
+    const d = new Date(from);
+    d.setSeconds(0, 0);
+    for (let i = 0; i < 60 * 24 * 60; i++) {
+        d.setMinutes(d.getMinutes() + 1);
+        if (cronMatches(spec, d))
+            return d.toISOString();
+    }
+    return undefined;
+}
+/* ---------- definition CRUD (agents/<slug>/routines.yml) ---------- */
+async function routinesFile(slug) {
+    return path.join(await teamRoot(), safeMemberSlug(slug), "routines.yml");
+}
+function normalizeRoutine(raw) {
+    const id = String(raw.id ?? "").trim();
+    if (!id)
+        return null;
+    return {
+        id,
+        name: String(raw.name ?? id),
+        schedule: String(raw.schedule ?? ""),
+        prompt: String(raw.prompt ?? ""),
+        enabled: raw.enabled !== false,
+    };
+}
+export async function listRoutines(slug) {
+    let raw;
+    try {
+        raw = parse(await fs.readFile(await routinesFile(slug), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((r) => normalizeRoutine((r ?? {})))
+        .filter(Boolean);
+}
+async function writeRoutines(slug, routines) {
+    await fs.writeFile(await routinesFile(slug), stringify(routines));
+}
+export async function saveRoutine(slug, input) {
+    const name = input.name?.trim();
+    if (!name)
+        throw new Error("name is required");
+    if (!input.prompt?.trim())
+        throw new Error("prompt is required");
+    parseCron(input.schedule); // throws with a useful message on a bad schedule
+    const id = input.id?.trim() ||
+        name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 48);
+    if (!id)
+        throw new Error("name must contain at least one letter or digit");
+    const routine = {
+        id,
+        name,
+        schedule: input.schedule.trim(),
+        prompt: input.prompt,
+        enabled: input.enabled !== false,
+    };
+    const routines = await listRoutines(slug);
+    const i = routines.findIndex((r) => r.id === id);
+    if (i >= 0)
+        routines[i] = routine;
+    else
+        routines.push(routine);
+    await writeRoutines(slug, routines);
+    return routine;
+}
+export async function deleteRoutine(slug, id) {
+    const routines = await listRoutines(slug);
+    await writeRoutines(slug, routines.filter((r) => r.id !== id));
+}
+const stateFile = () => path.join(getOutputDir(), "routines-state.json");
+async function readState() {
+    try {
+        return JSON.parse(await fs.readFile(stateFile(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+async function writeState(state) {
+    await fs.mkdir(getOutputDir(), { recursive: true });
+    await fs.writeFile(stateFile(), JSON.stringify(state, null, 2));
+}
+export async function routineStatuses(slug) {
+    const [routines, state] = await Promise.all([listRoutines(slug), readState()]);
+    return routines.map((r) => {
+        const s = state[`${slug}/${r.id}`] ?? {};
+        return {
+            ...r,
+            ...(r.enabled ? { nextRunAt: nextRun(r.schedule) } : {}),
+            ...(s.lastRunAt ? { lastRunAt: s.lastRunAt } : {}),
+            ...(s.lastChatId ? { lastChatId: s.lastChatId } : {}),
+            ...(s.lastError ? { lastError: s.lastError } : {}),
+        };
+    });
+}
+/* ---------- firing ---------- */
+/** Open a fresh session for the member and post the routine's prompt. */
+async function fireRoutine(slug, routine) {
+    const member = await getMember(slug);
+    if (!member)
+        throw new Error(`team agent "${slug}" not found`);
+    const meta = await createChat({
+        agent: member.harness,
+        scope: { kind: "team", member: slug, routine: routine.id },
+        title: `⏰ ${routine.name}`,
+    });
+    const { error } = await postMessage(meta.id, routine.prompt);
+    if (error)
+        throw new Error(error);
+    return meta.id;
+}
+export async function runRoutineNow(slug, id) {
+    const routine = (await listRoutines(slug)).find((r) => r.id === id);
+    if (!routine)
+        throw new Error("routine not found");
+    const state = await readState();
+    const key = `${slug}/${id}`;
+    try {
+        const chatId = await fireRoutine(slug, routine);
+        state[key] = { ...state[key], lastRunAt: new Date().toISOString(), lastChatId: chatId };
+        delete state[key].lastError;
+        await writeState(state);
+        return { chatId };
+    }
+    catch (err) {
+        state[key] = { ...state[key], lastError: err.message };
+        await writeState(state);
+        throw err;
+    }
+}
+/* ---------- scheduler ---------- */
+let timer = null;
+async function tick() {
+    const now = new Date();
+    const p = (n) => String(n).padStart(2, "0");
+    const minuteKey = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}T${p(now.getHours())}:${p(now.getMinutes())}`;
+    let members;
+    try {
+        members = await listMembers();
+    }
+    catch {
+        return;
+    }
+    const state = await readState();
+    let dirty = false;
+    for (const m of members) {
+        for (const r of await listRoutines(m.slug).catch(() => [])) {
+            if (!r.enabled)
+                continue;
+            let due = false;
+            try {
+                due = cronMatches(parseCron(r.schedule), now);
+            }
+            catch {
+                continue; // invalid schedule — surfaced by validation on save, skip here
+            }
+            const key = `${m.slug}/${r.id}`;
+            if (!due || state[key]?.lastMinute === minuteKey)
+                continue;
+            state[key] = { ...state[key], lastMinute: minuteKey };
+            dirty = true;
+            try {
+                const chatId = await fireRoutine(m.slug, r);
+                state[key] = { ...state[key], lastRunAt: now.toISOString(), lastChatId: chatId };
+                delete state[key].lastError;
+            }
+            catch (err) {
+                state[key] = { ...state[key], lastError: err.message };
+            }
+        }
+    }
+    if (dirty)
+        await writeState(state);
+}
+/** Start the in-process scheduler; safe to call more than once. */
+export function startRoutineScheduler() {
+    if (timer)
+        return;
+    timer = setInterval(() => void tick().catch(() => { }), 20_000);
+    timer.unref?.();
+}

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>;