@netnodeag/kraftwerk 0.4.1 → 0.7.0

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/runner.d.ts

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

package/dist/inspector/runner.js

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

package/dist/inspector/runs.d.ts

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

package/dist/inspector/runs.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { getOutputDir } from "./context.js";
 /**
  * Filesystem + trace.jsonl reading for the inspector. The output directory
- * holds one folder per run (run-YYYY-MM-DD-HHMM-SS); every run folder has a
+ * holds one folder per run (runs/<stamp>-<workflow>, legacy run-* at the root);
  * trace.jsonl written by the framework plus the run's working files.
  */
 /** A run with no trace update for this long and no summary counts as aborted. */
@@ -158,15 +158,14 @@ function shortenPath(p) {
     return parts.length > 2 ? parts.slice(-2).join("/") : p;
 }
 export async function listRuns() {
-    let entries;
-    try {
-        entries = (await fs.readdir(getOutputDir())).filter((e) => e.startsWith("run-"));
-    }
-    catch {
-        return [];
-    }
+    // New runs live under <output>/runs/; legacy run-* folders sit at the root.
+    const current = (await fs.readdir(path.join(getOutputDir(), "runs")).catch(() => []))
+        .filter((e) => RUN_ID_RE.test(e) && !e.startsWith("run-"));
+    const legacy = (await fs.readdir(getOutputDir()).catch(() => []))
+        .filter((e) => e.startsWith("run-") && RUN_ID_RE.test(e));
+    const entries = [...current, ...legacy];
     const items = await Promise.all(entries.map(async (id) => {
-        const runDir = path.join(getOutputDir(), id);
+        const runDir = safeRunDir(id);
         const st = await fs.stat(runDir).catch(() => null);
         if (!st?.isDirectory())
             return null;
@@ -188,12 +187,18 @@ export async function listRuns() {
             costUsd: summary?.total?.costUsd,
         };
     }));
-    return items.filter(Boolean).sort((a, b) => b.id.localeCompare(a.id));
+    // Newest first; strip the legacy "run-" prefix so both id styles compare by stamp.
+    const stampOf = (r) => r.id.replace(/^run-/, "");
+    return items.filter(Boolean).sort((a, b) => stampOf(b).localeCompare(stampOf(a)));
 }
+/** "2026-08-25-1432-07-hello" (runs/ subdir) or legacy "run-…" (output root). */
+export const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function safeRunDir(id) {
-    if (!/^run-[0-9-]+$/.test(id))
+    if (!RUN_ID_RE.test(id))
         throw new Error("invalid run id");
-    return path.join(getOutputDir(), id);
+    return id.startsWith("run-")
+        ? path.join(getOutputDir(), id)
+        : path.join(getOutputDir(), "runs", id);
 }
 export async function getRun(id) {
     const runDir = safeRunDir(id);

package/dist/inspector/server.d.ts

@@ -3,6 +3,8 @@ export interface InspectorOptions {
     outputDir: string;
     staticDir: string;
     port: number;
+    /** Consumer project root; defaults to the parent of outputDir. */
+    projectRoot?: string;
 }
 /** Start the server; resolves once it listens. Runs until the process ends. */
 export declare function startInspector(opts: InspectorOptions): Promise<http.Server>;