@netnodeag/kraftwerk 0.4.0 → 0.6.0

package/dist/inspector/chat/store.js

@@ -0,0 +1,69 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getOutputDir } from "../context.js";
+/**
+ * Chats live on disk under <output>/chats/<chat-id>/ as meta.json plus an
+ * append-only events.jsonl — inspectable with plain tools and durable
+ * across server restarts, like run folders.
+ */
+const chatsDir = () => path.join(getOutputDir(), "chats");
+export function safeChatDir(id) {
+    if (!/^chat-[0-9a-z-]+$/.test(id))
+        throw new Error("invalid chat id");
+    return path.join(chatsDir(), id);
+}
+export function newChatId() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, "0");
+    const stamp = `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}` +
+        `-${p(d.getHours())}${p(d.getMinutes())}-${p(d.getSeconds())}`;
+    return `chat-${stamp}-${Math.random().toString(36).slice(2, 6)}`;
+}
+export async function writeMeta(meta) {
+    const dir = safeChatDir(meta.id);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "meta.json"), JSON.stringify(meta, null, 2));
+}
+export async function readMeta(id) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(safeChatDir(id), "meta.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function appendEvent(id, ev) {
+    await fs.appendFile(path.join(safeChatDir(id), "events.jsonl"), JSON.stringify(ev) + "\n");
+}
+export async function readEvents(id) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(safeChatDir(id), "events.jsonl"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            /* partially written last line */
+        }
+    }
+    return events;
+}
+export async function listChatMetas() {
+    let entries;
+    try {
+        entries = (await fs.readdir(chatsDir())).filter((e) => e.startsWith("chat-"));
+    }
+    catch {
+        return [];
+    }
+    const metas = await Promise.all(entries.map(readMeta));
+    return metas.filter(Boolean).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}

package/dist/inspector/chat/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Chat data model shared across the chat backend modules. Every chat is a
+ * folder under <output>/chats/ holding meta.json plus events.jsonl — the
+ * same files-on-disk philosophy as runs. Events are the single source of
+ * truth: the UI replays them to render the thread, and the SSE stream just
+ * appends live ones.
+ */
+export type ChatAgentId = "claude" | "codex" | "pi";
+export type ChatScope = {
+    kind: "general";
+} | {
+    kind: "kraftwerk";
+} | {
+    kind: "run";
+    runId: string;
+} | {
+    kind: "knowledge";
+    bundle?: string;
+} | {
+    kind: "team";
+    member: string;
+    routine?: string;
+};
+export interface ChatMeta {
+    id: string;
+    agent: ChatAgentId;
+    title: string;
+    cwd: string;
+    scope: ChatScope;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One thread event; `seq` orders them and drives SSE resume (?after=seq). */
+export type ChatEvent = {
+    type: "user_message";
+    text: string;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "thought";
+    text: string;
+} | {
+    type: "tool_call";
+    callId: string;
+    title: string;
+    kind?: string;
+    status?: string;
+} | {
+    type: "tool_update";
+    callId: string;
+    title?: string;
+    status?: string;
+} | {
+    type: "permission_request";
+    requestId: string;
+    title: string;
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind?: string;
+    }>;
+} | {
+    type: "permission_resolved";
+    requestId: string;
+    optionId: string | null;
+} | {
+    type: "turn_end";
+    stopReason: string;
+} | {
+    type: "error";
+    message: string;
+};
+export type StoredChatEvent = ChatEvent & {
+    seq: number;
+    ts: string;
+};

package/dist/inspector/chat/types.js

@@ -0,0 +1,8 @@
+/**
+ * Chat data model shared across the chat backend modules. Every chat is a
+ * folder under <output>/chats/ holding meta.json plus events.jsonl — the
+ * same files-on-disk philosophy as runs. Events are the single source of
+ * truth: the UI replays them to render the thread, and the SSE stream just
+ * appends live ones.
+ */
+export {};

package/dist/inspector/knowledge.d.ts

@@ -0,0 +1,24 @@
+import { type BundleInfo, type ConceptDetail, type ConceptInfo } from "../okf.js";
+/**
+ * Context & Knowledge for the inspector: a thin API layer over the OKF
+ * core (src/okf.ts). Writes from the UI are stamped as `human:user` — the
+ * browser user is the human in the loop; agents write through the CLI (or
+ * chat) with their own actor.
+ */
+export declare const UI_ACTOR = "human:user";
+export interface KnowledgeIndex {
+    root: string;
+    bundles: BundleInfo[];
+}
+export interface BundleDetail {
+    name: string;
+    concepts: ConceptInfo[];
+    /** Raw log.md, if the bundle keeps one. */
+    log?: string;
+}
+export declare function knowledgeIndex(): Promise<KnowledgeIndex>;
+export declare function createBundle(name: string): Promise<BundleInfo>;
+export declare function bundleDetail(name: string): Promise<BundleDetail | null>;
+export declare function conceptDetail(bundle: string, id: string): Promise<ConceptDetail | null>;
+export declare function putConcept(bundle: string, id: string, content: string): Promise<ConceptDetail>;
+export declare function verifyFromUi(bundle: string, id: string): Promise<ConceptDetail>;

package/dist/inspector/knowledge.js

@@ -0,0 +1,41 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveProject } from "../config.js";
+import { getConcept, initBundle, knowledgeRoot, listBundles, listConcepts, safeBundleName, verifyConcept, writeConcept, } from "../okf.js";
+import { getProjectRoot } from "./context.js";
+/**
+ * Context & Knowledge for the inspector: a thin API layer over the OKF
+ * core (src/okf.ts). Writes from the UI are stamped as `human:user` — the
+ * browser user is the human in the loop; agents write through the CLI (or
+ * chat) with their own actor.
+ */
+export const UI_ACTOR = "human:user";
+async function root() {
+    const project = await resolveProject(getProjectRoot());
+    return knowledgeRoot(project.root, project.config.knowledge);
+}
+export async function knowledgeIndex() {
+    const kroot = await root();
+    return { root: kroot, bundles: await listBundles(kroot) };
+}
+export async function createBundle(name) {
+    await initBundle(await root(), name);
+    return { name, concepts: 0 };
+}
+export async function bundleDetail(name) {
+    const kroot = await root();
+    const dir = path.join(kroot, safeBundleName(name));
+    if (!(await fs.stat(dir).catch(() => null)))
+        return null;
+    const log = await fs.readFile(path.join(dir, "log.md"), "utf8").catch(() => undefined);
+    return { name, concepts: await listConcepts(kroot, name), log };
+}
+export async function conceptDetail(bundle, id) {
+    return getConcept(await root(), bundle, id);
+}
+export async function putConcept(bundle, id, content) {
+    return (await writeConcept(await root(), bundle, id, content, UI_ACTOR)).concept;
+}
+export async function verifyFromUi(bundle, id) {
+    return verifyConcept(await root(), bundle, id, UI_ACTOR);
+}

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?.();
+}