@netnodeag/kraftwerk 0.18.0 → 0.20.0

package/README.md

@@ -205,14 +205,20 @@ editing the files — the definition is read fresh for each new session).
 
 Chats — general ones and team sessions — can use skills: Claude-style
 instruction packages, one folder per skill with a `SKILL.md` (YAML
-frontmatter `name` + `description`, then the instructions). Two roots are
-discovered, with a project skill shadowing a same-named user skill:
+frontmatter `name` + `description`, then the instructions). Discovered
+roots, each shadowing same-named skills in the roots below it:
 
 ```
-<project>/.claude/skills/<name>/SKILL.md   # git-tracked, per project
-~/.claude/skills/<name>/SKILL.md           # personal, per user
+<project>/agents/<slug>/skills/<name>/SKILL.md   # private to that one team agent
+<project>/<skills root>/<name>/SKILL.md          # workspace, git-tracked (kraftwerk.yml `skills`, default skills/)
+<project>/.claude/skills/<name>/SKILL.md         # git-tracked, per project
+~/.claude/skills/<name>/SKILL.md                 # personal, per user
 ```
 
+Agent skills are visible only to that agent's sessions and always apply —
+a member's `skills:` allowlist narrows the shared roots only. They're
+managed in the agent profile ("own skills") or by editing the files.
+
 Every chat lists its visible skills as context ("## Your skills"), so the
 agent reaches for one when the request matches. Typing `/` in the composer
 opens an autocomplete over them; sending `/<name> <args>` expands the

package/dist/cli/kraftwerk.js

@@ -12,6 +12,7 @@ import { renderCreateBrief } from "./create-brief.js";
 import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
+import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
 /**
@@ -22,6 +23,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk run [workflow] [text]   run one (prompts interactively if omitted)
  *   kraftwerk runs [show <id>]        inspect past runs from their traces
  *   kraftwerk knowledge ...           Context & Knowledge: OKF bundles (list/get/put/verify/...)
+ *   kraftwerk routines ...            per-agent scheduled prompts (list/add/remove/enable/run)
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
@@ -253,6 +255,7 @@ runs
     await showRun(process.cwd(), runId, opts);
 });
 registerKnowledgeCommands(program);
+registerRoutineCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/routines.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerRoutineCommands(program: Command): void;

package/dist/cli/routines.js

@@ -0,0 +1,177 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import { resolveProject } from "../config.js";
+import { setOutputDir, setProjectRoot } from "../inspector/context.js";
+import { deleteRoutine, listRoutines, routineStatuses, saveRoutine, } from "../inspector/routines.js";
+import { getMember, listMembers } from "../inspector/team.js";
+/**
+ * `kraftwerk routines` — CLI surface over per-agent scheduled prompts
+ * (agents/<slug>/routines.yml). Definition CRUD works directly on the
+ * files; `run` fires through the running inspector server, because the
+ * session (chat) and the scheduler live there.
+ */
+/** Point the inspector context at this project so team/routine paths resolve. */
+async function initContext() {
+    const project = await resolveProject(process.cwd());
+    setProjectRoot(project.root);
+    setOutputDir(project.outputDir);
+    return { port: project.config.port ?? 1981 };
+}
+async function requireMember(slug) {
+    if (!(await getMember(slug))) {
+        console.error(chalk.red(`Agent "${slug}" not found (expected agents/${slug}/agent.yml).`));
+        process.exit(2);
+    }
+}
+async function readStdin() {
+    let data = "";
+    for await (const chunk of process.stdin)
+        data += chunk;
+    return data;
+}
+/** ISO timestamp → local "YYYY-MM-DD HH:mm" (schedules are server-local time). */
+const fmtTime = (iso) => {
+    if (!iso)
+        return "—";
+    const d = new Date(iso);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+};
+function routineLine(r) {
+    const state = r.enabled ? chalk.green("on ") : chalk.dim("off");
+    const flags = r.lastError ? ` ${chalk.red(`error: ${r.lastError}`)}` : "";
+    return (`  ${chalk.cyan(r.id.padEnd(24))} ${state} ${r.schedule.padEnd(14)} ` +
+        chalk.dim(`next ${fmtTime(r.nextRunAt).padEnd(17)} last ${fmtTime(r.lastRunAt)}`) +
+        flags);
+}
+export function registerRoutineCommands(program) {
+    const routines = program
+        .command("routines")
+        .description("Per-agent scheduled prompts (agents/<slug>/routines.yml): list, add, run, ...");
+    routines
+        .command("list", { isDefault: true })
+        .description("List routines — all agents, or one agent with schedule state")
+        .argument("[agent]", "Agent slug (folder under agents/)")
+        .option("--json", "Machine-readable output")
+        .action(async (agent, opts) => {
+        await initContext();
+        const slugs = agent ? [agent] : (await listMembers()).map((m) => m.slug);
+        if (agent)
+            await requireMember(agent);
+        const all = {};
+        for (const slug of slugs)
+            all[slug] = await routineStatuses(slug);
+        if (opts.json)
+            return void console.log(JSON.stringify(all, null, 2));
+        let any = false;
+        for (const [slug, rs] of Object.entries(all)) {
+            if (rs.length === 0)
+                continue;
+            any = true;
+            console.log(chalk.bold(slug));
+            for (const r of rs)
+                console.log(routineLine(r));
+        }
+        if (!any) {
+            console.log(chalk.yellow("No routines yet — add one with `kraftwerk routines add <agent> --name ... --schedule ... --prompt ...`."));
+        }
+    });
+    routines
+        .command("add")
+        .description("Create or update a routine (same id = update)")
+        .argument("<agent>", "Agent slug")
+        .requiredOption("--name <name>", 'Display name, e.g. "Morning triage"')
+        .requiredOption("--schedule <cron>", '5-field cron ("0 9 * * 1-5") or @hourly/@daily/@weekly/@monthly')
+        .option("--prompt <text>", "The prompt to post (or pipe it on stdin / use --file)")
+        .option("--file <path>", "Read the prompt from a file")
+        .option("--id <id>", "Routine id (default: derived from the name)")
+        .option("--disabled", "Create it switched off")
+        .action(async (agent, opts) => {
+        await initContext();
+        await requireMember(agent);
+        const prompt = opts.prompt ??
+            (opts.file ? await readFile(path.resolve(opts.file), "utf8") : process.stdin.isTTY ? "" : await readStdin());
+        if (!prompt.trim()) {
+            console.error(chalk.red("No prompt (--prompt, --file, or pipe it on stdin)."));
+            process.exit(2);
+        }
+        try {
+            const existing = new Set((await listRoutines(agent)).map((r) => r.id));
+            const routine = await saveRoutine(agent, {
+                ...(opts.id ? { id: opts.id } : {}),
+                name: opts.name,
+                schedule: opts.schedule,
+                prompt,
+                enabled: !opts.disabled,
+            });
+            const verb = existing.has(routine.id) ? "updated" : "created";
+            console.log(`${chalk.green("✔")} ${verb} ${chalk.cyan(`${agent}/${routine.id}`)} ` +
+                chalk.dim(`(${routine.schedule}${routine.enabled ? "" : ", disabled"})`));
+            if (routine.enabled) {
+                console.log(chalk.dim("  fires from the inspector server — make sure `kraftwerk ui` is running."));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    routines
+        .command("remove")
+        .description("Delete a routine")
+        .argument("<agent>", "Agent slug")
+        .argument("<id>", "Routine id (see `kraftwerk routines <agent>`)")
+        .action(async (agent, id) => {
+        await initContext();
+        await requireMember(agent);
+        if (!(await listRoutines(agent)).some((r) => r.id === id)) {
+            console.error(chalk.red(`Routine "${agent}/${id}" not found.`));
+            process.exit(2);
+        }
+        await deleteRoutine(agent, id);
+        console.log(`${chalk.green("✔")} removed ${chalk.cyan(`${agent}/${id}`)}`);
+    });
+    for (const [verb, enabled] of [["enable", true], ["disable", false]]) {
+        routines
+            .command(verb)
+            .description(`${verb === "enable" ? "Enable" : "Disable"} a routine`)
+            .argument("<agent>", "Agent slug")
+            .argument("<id>", "Routine id")
+            .action(async (agent, id) => {
+            await initContext();
+            const routine = (await listRoutines(agent)).find((r) => r.id === id);
+            if (!routine) {
+                console.error(chalk.red(`Routine "${agent}/${id}" not found.`));
+                process.exit(2);
+            }
+            await saveRoutine(agent, { ...routine, enabled });
+            console.log(`${chalk.green("✔")} ${chalk.cyan(`${agent}/${id}`)} ${verb}d`);
+        });
+    }
+    routines
+        .command("run")
+        .description("Fire a routine now (opens a session via the running `kraftwerk ui` server)")
+        .argument("<agent>", "Agent slug")
+        .argument("<id>", "Routine id")
+        .option("--port <port>", "Inspector port (default: kraftwerk.yml `port`, else 1981)")
+        .action(async (agent, id, opts) => {
+        const { port } = await initContext();
+        const p = opts.port ? Number(opts.port) : port;
+        const url = `http://localhost:${p}/api/team/${encodeURIComponent(agent)}/routines/${encodeURIComponent(id)}/run`;
+        let body;
+        try {
+            body = (await (await fetch(url, { method: "POST" })).json());
+        }
+        catch {
+            console.error(chalk.red(`Inspector not reachable on localhost:${p} — routines fire through the server; start it with \`kraftwerk ui\`.`));
+            process.exit(2);
+        }
+        if (body.error || !body.chatId) {
+            console.error(chalk.red(body.error ?? "run failed"));
+            process.exit(2);
+        }
+        console.log(`${chalk.green("✔")} ${chalk.cyan(`${agent}/${id}`)} fired → session ${body.chatId}\n` +
+            chalk.dim(`  http://localhost:${p}/#/agents/${encodeURIComponent(agent)}/chat/${body.chatId}`));
+    });
+}

package/dist/inspector/chat/sessions.js

@@ -74,18 +74,20 @@ function emit(state, ev) {
 /* ---------- skills ---------- */
 /**
  * Skills visible to a chat: every discovered skill (workspace skills root
- * + .claude/skills roots), narrowed by the team member's allowlist when the chat
- * is a team session (absent allowlist = all, empty = none).
+ * + .claude/skills roots, plus the member's own agents/<slug>/skills for team
+ * sessions), narrowed by the team member's allowlist when the chat is a team
+ * session (absent allowlist = all, empty = none). The agent's own skills
+ * always apply — the allowlist narrows shared skills only.
  */
 async function availableSkills(scope) {
-    const all = await listSkills().catch(() => []);
-    if (scope.kind !== "team" || all.length === 0)
+    const all = await listSkills(scope.kind === "team" ? scope.member : undefined).catch(() => []);
+    if (scope.kind !== "team")
         return all;
     const member = await getMember(scope.member).catch(() => null);
     if (!member || member.skills === undefined)
         return all;
     const allowed = new Set(member.skills.map((n) => n.toLowerCase()));
-    return all.filter((s) => allowed.has(s.name.toLowerCase()));
+    return all.filter((s) => s.source === "agent" || allowed.has(s.name.toLowerCase()));
 }
 /** "## Your skills" context block (empty when no skills are visible). */
 function skillsBlock(skills) {

package/dist/inspector/server.js

@@ -9,7 +9,7 @@ import { dockerStatus, triggerRun, stopRun } from "./runner.js";
 import { cancelChat, createChat, deleteChat, disposeAllBackends, 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 { getSkill, listSkills, skillsRoot } from "./skills.js";
+import { deleteAgentSkill, getSkill, listAgentSkills, listSkills, readSkill, saveAgentSkill, skillsRoot, } from "./skills.js";
 import { deleteRoutine, routineStatuses, runRoutineNow, saveRoutine, startRoutineScheduler, } from "./routines.js";
 /**
  * The inspector server: a plain node:http server with no dependencies.
@@ -279,6 +279,41 @@ async function handleApi(req, res, url) {
             }
         }
     }
+    // GET/POST /api/team/:slug/skills — the agent's own skills / create or update one
+    if (seg.length === 4 && seg[1] === "team" && seg[3] === "skills") {
+        const slug = decodeURIComponent(seg[2]);
+        try {
+            if (method === "GET")
+                return json(res, { skills: await listAgentSkills(slug) });
+            if (method === "POST") {
+                const body = JSON.parse(await readBody(req));
+                return json(res, await saveAgentSkill(slug, String(body.name ?? ""), String(body.content ?? "")));
+            }
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // GET/DELETE /api/team/:slug/skills/:name — one agent skill with content / delete
+    if (seg.length === 5 && seg[1] === "team" && seg[3] === "skills") {
+        const slug = decodeURIComponent(seg[2]);
+        const name = decodeURIComponent(seg[4]);
+        try {
+            if (method === "GET") {
+                const skill = (await listAgentSkills(slug)).find((s) => s.name.toLowerCase() === name.toLowerCase());
+                if (!skill)
+                    return json(res, { error: "not found" }, 404);
+                return json(res, { ...skill, content: await readSkill(skill) });
+            }
+            if (method === "DELETE") {
+                await deleteAgentSkill(slug, name);
+                return json(res, { ok: true });
+            }
+        }
+        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]);

package/dist/inspector/skills.d.ts

@@ -12,6 +12,14 @@
  * shadows a same-named project skill, which shadows a same-named global
  * skill. Skills are surfaced to every chat as context (and expanded on
  * /<name> invocation), so they work identically on claude, codex, and pi.
+ *
+ * On top of the shared roots, each team agent can carry private skills in
+ *
+ *   agents/<slug>/skills/<name>/SKILL.md            (agent, git-tracked)
+ *
+ * Agent skills are visible only to that agent's sessions, always apply
+ * (the member's allowlist narrows shared skills only), and shadow
+ * same-named shared skills.
  */
 export interface SkillInfo {
     /** Frontmatter `name`, falling back to the folder name. */
@@ -21,8 +29,10 @@ export interface SkillInfo {
     path: string;
     /** Absolute path to the skill folder (for harnesses that take a dir). */
     dir: string;
-    /** workspace = kraftwerk skills root; project = .claude/skills; user = ~/.claude/skills. */
-    source: "workspace" | "project" | "user";
+    /** workspace = kraftwerk skills root; project = .claude/skills; user = ~/.claude/skills; agent = agents/<slug>/skills. */
+    source: "workspace" | "project" | "user" | "agent";
+    /** For source "agent": the owning member's slug. */
+    agent?: string;
 }
 export interface SkillDetail extends SkillInfo {
     /** Full SKILL.md contents. */
@@ -32,8 +42,21 @@ export interface SkillDetail extends SkillInfo {
 }
 /** Absolute workspace skills root (kraftwerk.yml `skills`, default skills/). */
 export declare function skillsRoot(): Promise<string>;
-/** All discovered skills; workspace shadows project shadows user (global). */
-export declare function listSkills(): Promise<SkillInfo[]>;
+/** The private skills root of one team agent: agents/<slug>/skills. */
+export declare function agentSkillsRoot(slug: string): Promise<string>;
+/** One agent's private skills (agents/<slug>/skills/<name>/SKILL.md). */
+export declare function listAgentSkills(slug: string): Promise<SkillInfo[]>;
+/**
+ * All discovered skills; agent (when a member is given) shadows workspace
+ * shadows project shadows user (global).
+ */
+export declare function listSkills(member?: string): Promise<SkillInfo[]>;
+/** Create or update one agent skill; writes agents/<slug>/skills/<name>/SKILL.md. */
+export declare function saveAgentSkill(slug: string, name: string, content: string): Promise<SkillInfo & {
+    content: string;
+}>;
+/** Delete one agent skill (removes its folder). */
+export declare function deleteAgentSkill(slug: string, name: string): Promise<void>;
 /** Read a skill's SKILL.md contents (empty string when unreadable). */
 export declare function readSkill(skill: SkillInfo): Promise<string>;
 /** One skill by name (post-shadowing), with SKILL.md content + bundled files. */

package/dist/inspector/skills.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { parse } from "yaml";
 import { resolveProject } from "../config.js";
 import { getProjectRoot } from "./context.js";
+import { safeMemberSlug, teamRoot } from "./team.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);
@@ -57,16 +58,29 @@ async function scanRoot(root, source) {
     }));
     return skills.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
 }
-/** All discovered skills; workspace shadows project shadows user (global). */
-export async function listSkills() {
-    const [workspace, project, user] = await Promise.all([
+/** The private skills root of one team agent: agents/<slug>/skills. */
+export async function agentSkillsRoot(slug) {
+    return path.join(await teamRoot(), safeMemberSlug(slug), "skills");
+}
+/** One agent's private skills (agents/<slug>/skills/<name>/SKILL.md). */
+export async function listAgentSkills(slug) {
+    const skills = await scanRoot(await agentSkillsRoot(slug), "agent");
+    return skills.map((s) => ({ ...s, agent: slug }));
+}
+/**
+ * All discovered skills; agent (when a member is given) shadows workspace
+ * shadows project shadows user (global).
+ */
+export async function listSkills(member) {
+    const [agent, workspace, project, user] = await Promise.all([
+        member ? listAgentSkills(member).catch(() => []) : [],
         skillsRoot().then((root) => scanRoot(root, "workspace")),
         scanRoot(path.join(getProjectRoot(), ".claude", "skills"), "project"),
         scanRoot(path.join(os.homedir(), ".claude", "skills"), "user"),
     ]);
-    const out = [...workspace];
+    const out = [...agent];
     const seen = new Set(out.map((s) => s.name.toLowerCase()));
-    for (const s of [...project, ...user]) {
+    for (const s of [...workspace, ...project, ...user]) {
         if (seen.has(s.name.toLowerCase()))
             continue;
         seen.add(s.name.toLowerCase());
@@ -74,6 +88,37 @@ export async function listSkills() {
     }
     return out;
 }
+/** Create or update one agent skill; writes agents/<slug>/skills/<name>/SKILL.md. */
+export async function saveAgentSkill(slug, name, content) {
+    const n = name.trim().toLowerCase();
+    if (!NAME_RE.test(n)) {
+        throw new Error("skill name must be letters, digits, - or _ (e.g. report-html)");
+    }
+    if (!content.trim())
+        throw new Error("content (SKILL.md) is required");
+    const dir = path.join(await agentSkillsRoot(slug), n);
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, "SKILL.md");
+    await fs.writeFile(file, content.endsWith("\n") ? content : content + "\n");
+    const fm = frontmatter(content);
+    const display = String(fm.name ?? n).trim() || n;
+    return {
+        name: NAME_RE.test(display) ? display : n,
+        description: String(fm.description ?? "").trim(),
+        path: file,
+        dir,
+        source: "agent",
+        agent: slug,
+        content,
+    };
+}
+/** Delete one agent skill (removes its folder). */
+export async function deleteAgentSkill(slug, name) {
+    const skill = (await listAgentSkills(slug)).find((s) => s.name.toLowerCase() === name.toLowerCase());
+    if (!skill)
+        throw new Error(`skill "${name}" not found`);
+    await fs.rm(skill.dir, { recursive: true, force: true });
+}
 /** Read a skill's SKILL.md contents (empty string when unreadable). */
 export function readSkill(skill) {
     return fs.readFile(skill.path, "utf8").catch(() => "");