@netnodeag/kraftwerk 0.4.1 → 0.7.0

package/dist/inspector/chat/sessions.js

@@ -0,0 +1,407 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { getOutputDir, getProjectRoot } from "../context.js";
+import { knowledgeIndex } from "../knowledge.js";
+import { getRun, listRuns, safeRunDir } from "../runs.js";
+import { listSkills, readSkill } from "../skills.js";
+import { listWorkflows } from "../workflows.js";
+import { getMember } from "../team.js";
+import { startAcpBackend } from "./acp.js";
+import { startPiBackend } from "./pi.js";
+import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
+const states = new Map();
+async function loadState(id) {
+    const existing = states.get(id);
+    if (existing)
+        return existing;
+    const meta = await readMeta(id);
+    if (!meta)
+        return null;
+    const state = {
+        meta,
+        events: await readEvents(id),
+        subscribers: new Set(),
+        backend: null,
+        busy: false,
+        pendingPermissions: new Map(),
+        writeChain: Promise.resolve(),
+    };
+    // Two racing loads: keep whichever registered first.
+    return states.get(id) ?? (states.set(id, state), state);
+}
+function emit(state, ev) {
+    const stored = {
+        ...ev,
+        seq: (state.events[state.events.length - 1]?.seq ?? 0) + 1,
+        ts: new Date().toISOString(),
+    };
+    state.events.push(stored);
+    state.meta.updatedAt = stored.ts;
+    state.writeChain = state.writeChain
+        .then(() => appendEvent(state.meta.id, stored))
+        .catch(() => { });
+    for (const fn of state.subscribers)
+        fn(stored);
+    return stored;
+}
+/* ---------- skills ---------- */
+/**
+ * Skills visible to a chat: every discovered skill (project + user
+ * .claude/skills), narrowed by the team member's allowlist when the chat
+ * is a team session (absent allowlist = all, empty = none).
+ */
+async function availableSkills(scope) {
+    const all = await listSkills().catch(() => []);
+    if (scope.kind !== "team" || all.length === 0)
+        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()));
+}
+/** "## Your skills" context block (empty when no skills are visible). */
+function skillsBlock(skills) {
+    if (skills.length === 0)
+        return "";
+    const lines = skills
+        .map((s) => `- /${s.name}${s.description ? `: ${s.description}` : ""} — ${s.path}`)
+        .join("\n");
+    return (`## Your skills\nSkills are reusable instruction packages (a SKILL.md per skill). When the ` +
+        `user's request matches one, read its SKILL.md file and follow the instructions in it. The user ` +
+        `can also invoke one explicitly by starting a message with /<skill-name>.\n${lines}`);
+}
+/**
+ * Explicit skill invocation: a message starting with /<skill-name> is
+ * expanded into the skill's SKILL.md instructions (the stored user_message
+ * keeps the original "/name args" text). Unknown names pass through as-is.
+ */
+async function expandSkillInvocation(scope, text) {
+    const m = /^\/([A-Za-z0-9][\w-]*)[ \t]*([\s\S]*)$/.exec(text);
+    if (!m)
+        return text;
+    const skills = await availableSkills(scope);
+    const skill = skills.find((s) => s.name.toLowerCase() === m[1].toLowerCase());
+    if (!skill)
+        return text;
+    const body = await readSkill(skill);
+    if (!body.trim())
+        return text;
+    const args = m[2].trim();
+    return (`The user invoked the skill "${skill.name}" (${skill.path}). Follow the skill's instructions:\n\n` +
+        `<skill name="${skill.name}">\n${body.trim()}\n</skill>\n\n` +
+        `Arguments the user passed to the skill: ${args || "(none)"}`);
+}
+/* ---------- scope context ---------- */
+/** "## Your knowledge" block for a team member's connected OKF bundles. */
+async function teamKnowledgeContext(member) {
+    if (member.knowledge.length === 0)
+        return "";
+    const { bundles } = await knowledgeIndex().catch(() => ({ bundles: [] }));
+    const lines = member.knowledge
+        .map((name) => {
+        const b = bundles.find((x) => x.name === name);
+        return b
+            ? `- ${b.name} (${b.concepts} concepts${b.updatedAt ? `, updated ${b.updatedAt.slice(0, 10)}` : ""})`
+            : `- ${name} (not found in knowledge/ — tell the user if you need it)`;
+    })
+        .join("\n");
+    return (`## Your knowledge\nThese OKF knowledge bundles (markdown + YAML frontmatter under knowledge/) are ` +
+        `part of your job. Consult them before answering questions in their domain, and keep them current ` +
+        `when you learn something durable:\n${lines}\n\n` +
+        `Read with \`npx kraftwerk knowledge list <bundle>\`, \`get <bundle>/<path>\`, \`search <text>\`. ` +
+        `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor ${member.slug}/${member.harness}\` ` +
+        `(write the markdown to a temp file first; the CLI stamps provenance and maintains index.md/log.md). ` +
+        `Never hand-edit index.md or log.md, and never add \`verified\` yourself — verification is the human's ` +
+        `click in the UI.\n\n`);
+}
+/** Base context per scope; scopeContext() appends the shared skills block. */
+async function baseScopeContext(scope, agent) {
+    if (scope.kind === "team") {
+        const member = await getMember(scope.member).catch(() => null);
+        if (!member) {
+            return `You were opened as team agent "${scope.member}", but its definition under agents/ is missing. Tell the user and ask them to recreate it.`;
+        }
+        const { workflows } = await listWorkflows().catch(() => ({ workflows: [] }));
+        const connected = workflows.filter((w) => member.workflows.includes(w.slug));
+        const missing = member.workflows.filter((slug) => !connected.some((w) => w.slug === slug));
+        const wfLines = connected
+            .map((w) => `- ${w.slug}: ${w.description ?? w.name ?? ""} (${w.steps} steps)`)
+            .join("\n");
+        return (`You are ${member.emoji} ${member.name}, a persistent agent teammate on this project's team ` +
+            `(defined in agents/${member.slug}/). The user works with you like with a colleague: every session ` +
+            `is a conversation with the same ${member.name}, so keep this role consistently. You are an AI agent, ` +
+            `not a human — never pretend otherwise, but do own your role.\n\n` +
+            `## Your role\n${member.system || "(no system prompt written yet — ask the user what your job should be)"}\n\n` +
+            (member.workflows.length > 0
+                ? `## Your workflows\nThese kraftwerk workflows are part of your job. When the user's request matches one, ` +
+                    `run it yourself instead of doing the work by hand:\n${wfLines || "(none found)"}\n` +
+                    (missing.length > 0
+                        ? `(configured but not found in this project: ${missing.join(", ")})\n`
+                        : "") +
+                    `\nRun a workflow with:\n` +
+                    `  KRAFTWERK_YES=1 npx kraftwerk run <workflow> "<request>"\n` +
+                    `The command blocks until the run finishes; artifacts land in output/runs/*/ — tell the user the ` +
+                    `run id and summarize the result. Confirm with the user before starting a long or expensive run ` +
+                    `unless they clearly asked for it.\n\n`
+                : "") +
+            (await teamKnowledgeContext(member)) +
+            `The working directory is the project root. Stay within your role; if a request is clearly outside it, ` +
+            `say so and suggest which teammate or tool fits better.` +
+            (scope.routine
+                ? `\n\nThis session was started automatically by your scheduled routine "${scope.routine}" — ` +
+                    `nobody may be watching live. Complete the task autonomously (tool permissions are ` +
+                    `auto-approved) and end with a clear, self-contained summary of what you did and found.`
+                : ""));
+    }
+    if (scope.kind === "knowledge") {
+        const { root, bundles } = await knowledgeIndex().catch(() => ({ root: "", bundles: [] }));
+        const bundleLines = bundles
+            .map((b) => `- ${b.name} (${b.concepts} concepts${b.updatedAt ? `, updated ${b.updatedAt.slice(0, 10)}` : ""})`)
+            .join("\n");
+        return (`You are the knowledge curator inside the kraftwerk inspector ("Context & Knowledge"). ` +
+            `This project keeps knowledge as OKF v0.2 bundles (Open Knowledge Format): directories of markdown ` +
+            `files with YAML frontmatter under ${root || "knowledge/"}. Each direct subdirectory is one bundle; each .md file ` +
+            `(except the reserved index.md and log.md) is one concept.\n\n` +
+            `Existing bundles:\n${bundleLines || "(none yet)"}\n` +
+            (scope.bundle ? `\nThe user wants to work on the "${scope.bundle}" bundle.\n` : "") +
+            `\nOKF essentials:\n` +
+            `- Frontmatter needs exactly one required key: \`type\` (free-form, e.g. Playbook, Metric, Reference, API Endpoint). ` +
+            `Recommended: title, description, tags, resource (canonical URI of the described asset).\n` +
+            `- Provenance/trust families (all optional): \`sources\` (list of { id, resource, title, author, usage_count, last_modified }), ` +
+            `\`generated: { by, at }\`, \`verified: [{ by, at }]\`, \`status\` (draft|stable|deprecated), \`stale_after\` (ISO datetime).\n` +
+            `- Actors: \`<producer>/<version>\` for agents, \`human:<id>\` for people, \`process:<id>\` for automation.\n` +
+            `- Concepts cross-link with normal markdown links, bundle-absolute (\`/path/concept.md\`) preferred. ` +
+            `Per-claim attribution uses markdown footnotes whose label is a \`sources[].id\`.\n` +
+            `- Favor structural markdown (headings, tables, lists) over prose.\n\n` +
+            `ALWAYS write through the kraftwerk CLI so provenance is stamped and the bundle log/index stay maintained:\n` +
+            `- \`npx kraftwerk knowledge init <bundle>\` — new bundle\n` +
+            `- \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor kraftwerk-chat/${agent}\` — create/update a concept ` +
+            `(write the markdown to a temp file first; the CLI stamps generated.by/at, appends log.md, regenerates index.md)\n` +
+            `- \`npx kraftwerk knowledge list [bundle]\`, \`get <bundle>/<path>\`, \`search <text>\`, \`validate\`\n` +
+            `Do not hand-edit index.md or log.md (derived/maintained), and do not add \`verified\` yourself — ` +
+            `verification is the human's click in the UI. Ask the user what knowledge to capture, then author concise, well-typed concepts.`);
+    }
+    if (scope.kind === "kraftwerk") {
+        const [{ workflows }, runs] = await Promise.all([listWorkflows(), listRuns()]);
+        const wfLines = workflows
+            .map((w) => `- ${w.name ?? w.slug}: ${w.description ?? ""} (${w.steps} steps, ${w.agents} agents)`)
+            .join("\n");
+        const runLines = runs
+            .slice(0, 10)
+            .map((r) => `- ${r.id} — ${r.workflow ?? "?"} [${r.status}] ${r.request ?? ""}`.trim())
+            .join("\n");
+        return (`You are the assistant inside the kraftwerk inspector, a UI for a workflow-as-code agent framework. ` +
+            `The consumer project root is ${getProjectRoot()}; run outputs live in ${getOutputDir()} (one folder per run under runs/, each with a trace.jsonl and working files).\n\n` +
+            `Workflows in this project:\n${wfLines || "(none)"}\n\nRecent runs:\n${runLines || "(none)"}\n\n` +
+            `Answer questions about workflows and runs by reading these files. Do not modify run outputs unless asked.`);
+    }
+    if (scope.kind === "run") {
+        const run = await getRun(scope.runId);
+        if (!run)
+            return `The user wants to discuss kraftwerk run ${scope.runId}, but it was not found.`;
+        const phases = run.phases
+            .map((p) => `- ${p.phase} [${p.status}]${p.summary ? `: ${p.summary}` : ""}`)
+            .join("\n");
+        const files = run.files.map((f) => `- ${f.name} (${f.size} bytes)`).join("\n");
+        return (`You are the assistant for one kraftwerk workflow run. Your working directory is the run's output folder.\n\n` +
+            `Run ${run.id} — workflow "${run.workflow ?? "?"}", status ${run.status}.\n` +
+            `Request: ${run.request ?? "(none)"}\n\nPhases:\n${phases || "(none)"}\n\nFiles in this folder:\n${files || "(none)"}\n\n` +
+            `trace.jsonl holds the full event log. Read files as needed to answer; do not modify the run's artifacts unless asked.`);
+    }
+    return "";
+}
+async function scopeContext(scope, agent) {
+    const [base, skills] = await Promise.all([
+        baseScopeContext(scope, agent),
+        availableSkills(scope),
+    ]);
+    const block = skillsBlock(skills);
+    if (!block)
+        return base;
+    return base ? `${base}\n\n${block}` : block;
+}
+/* ---------- backend lifecycle ---------- */
+/** Team chats carry the member's model/effort; resolved live so edits apply to new backends. */
+async function backendTuning(scope, agent) {
+    const tuning = {};
+    if (scope.kind === "team") {
+        const member = await getMember(scope.member).catch(() => null);
+        if (member?.model)
+            tuning.model = member.model;
+        if (member?.effort)
+            tuning.effort = member.effort;
+        // Claude discovers skills natively; a defined allowlist narrows that.
+        if (agent === "claude" && member?.skills)
+            tuning.skills = member.skills;
+    }
+    // Run chats live in the run folder — grant claude the project root so
+    // project-level skills and files stay reachable.
+    if (scope.kind === "run" && agent === "claude")
+        tuning.addDirs = [getProjectRoot()];
+    // pi loads skills only when told: hand it every visible skill folder.
+    if (agent === "pi") {
+        const skills = await availableSkills(scope);
+        if (skills.length > 0)
+            tuning.skillDirs = skills.map((s) => s.dir);
+    }
+    return tuning;
+}
+async function ensureBackend(state) {
+    if (state.backend)
+        return state.backend;
+    const hooks = {
+        emit: (ev) => void emit(state, ev),
+        askPermission: (title, options) => {
+            // Routine-triggered sessions run unattended: auto-approve, but keep
+            // the request/resolution pair in the thread as an audit trail.
+            const scope = state.meta.scope;
+            if (scope.kind === "team" && scope.routine) {
+                const allow = options.find((o) => o.kind?.startsWith("allow")) ?? options[0];
+                const requestId = randomUUID();
+                emit(state, { type: "permission_request", requestId, title, options });
+                emit(state, { type: "permission_resolved", requestId, optionId: allow?.optionId ?? null });
+                return Promise.resolve(allow?.optionId ?? null);
+            }
+            return new Promise((resolve) => {
+                const requestId = randomUUID();
+                state.pendingPermissions.set(requestId, (optionId) => {
+                    state.pendingPermissions.delete(requestId);
+                    emit(state, { type: "permission_resolved", requestId, optionId });
+                    resolve(optionId);
+                });
+                emit(state, { type: "permission_request", requestId, title, options });
+            });
+        },
+    };
+    const { agent, cwd } = state.meta;
+    const tuning = await backendTuning(state.meta.scope, agent);
+    state.backend =
+        agent === "pi"
+            ? startPiBackend(cwd, hooks, tuning)
+            : await startAcpBackend(agent, cwd, hooks, tuning);
+    return state.backend;
+}
+/* ---------- public API (used by server.ts) ---------- */
+export async function createChat(opts) {
+    const cwd = opts.scope.kind === "run" ? safeRunDir(opts.scope.runId) : getProjectRoot();
+    const now = new Date().toISOString();
+    const meta = {
+        id: newChatId(),
+        agent: opts.agent,
+        title: opts.title ?? "",
+        cwd,
+        scope: opts.scope,
+        createdAt: now,
+        updatedAt: now,
+    };
+    await writeMeta(meta);
+    states.set(meta.id, {
+        meta,
+        events: [],
+        subscribers: new Set(),
+        backend: null,
+        busy: false,
+        pendingPermissions: new Map(),
+        writeChain: Promise.resolve(),
+    });
+    return meta;
+}
+export async function listChats() {
+    const metas = await listChatMetas();
+    return metas.map((m) => ({
+        ...(states.get(m.id)?.meta ?? m),
+        busy: states.get(m.id)?.busy ?? false,
+    }));
+}
+export async function getChat(id) {
+    const state = await loadState(id);
+    if (!state)
+        return null;
+    return { meta: state.meta, events: state.events, busy: state.busy };
+}
+export async function postMessage(id, text) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    if (state.busy)
+        return { error: "agent is still working — wait for the turn to finish" };
+    state.busy = true;
+    const isFirst = !state.events.some((e) => e.type === "user_message");
+    if (isFirst && !state.meta.title) {
+        state.meta.title = text.replace(/\s+/g, " ").trim().slice(0, 80);
+        void writeMeta(state.meta).catch(() => { });
+    }
+    emit(state, { type: "user_message", text });
+    // The turn runs in the background; the HTTP request returns immediately
+    // and the browser follows along on the SSE stream.
+    void (async () => {
+        try {
+            const backend = await ensureBackend(state);
+            const context = isFirst ? await scopeContext(state.meta.scope, state.meta.agent) : "";
+            // "/<skill> args" expands to the skill's instructions for the agent;
+            // the thread keeps the short form the user typed.
+            const body = await expandSkillInvocation(state.meta.scope, text);
+            const promptText = context ? `<context>\n${context}\n</context>\n\n${body}` : body;
+            const stopReason = await backend.prompt(promptText);
+            emit(state, { type: "turn_end", stopReason });
+        }
+        catch (err) {
+            emit(state, { type: "error", message: err.message });
+            // A failed turn may mean a dead subprocess; drop it so the next
+            // message spawns a fresh agent (thread history stays on disk).
+            state.backend?.dispose();
+            state.backend = null;
+        }
+        finally {
+            state.busy = false;
+            void writeMeta(state.meta).catch(() => { });
+        }
+    })();
+    return {};
+}
+export async function resolvePermission(id, requestId, optionId) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    const resolve = state.pendingPermissions.get(requestId);
+    if (!resolve)
+        return { error: "no such pending permission request" };
+    resolve(optionId);
+    return {};
+}
+/** Delete a chat: kill its backend, drop the live state, remove its folder. */
+export async function deleteChat(id) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    for (const resolve of state.pendingPermissions.values())
+        resolve(null);
+    state.backend?.dispose();
+    states.delete(id);
+    await fs.rm(safeChatDir(id), { recursive: true, force: true });
+    return {};
+}
+export async function cancelChat(id) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    for (const resolve of state.pendingPermissions.values())
+        resolve(null);
+    state.backend?.cancel();
+    return {};
+}
+/**
+ * SSE subscription: replays events after `afterSeq`, then streams new ones.
+ * Returns an unsubscribe function.
+ */
+export async function subscribeChat(id, afterSeq, fn) {
+    const state = await loadState(id);
+    if (!state)
+        return null;
+    for (const ev of state.events)
+        if (ev.seq > afterSeq)
+            fn(ev);
+    state.subscribers.add(fn);
+    return () => state.subscribers.delete(fn);
+}

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

@@ -0,0 +1,8 @@
+import type { ChatMeta, StoredChatEvent } from "./types.js";
+export declare function safeChatDir(id: string): string;
+export declare function newChatId(): string;
+export declare function writeMeta(meta: ChatMeta): Promise<void>;
+export declare function readMeta(id: string): Promise<ChatMeta | null>;
+export declare function appendEvent(id: string, ev: StoredChatEvent): Promise<void>;
+export declare function readEvents(id: string): Promise<StoredChatEvent[]>;
+export declare function listChatMetas(): Promise<ChatMeta[]>;

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

@@ -13,6 +13,13 @@ export type ChatScope = {
 } | {
     kind: "run";
     runId: string;
+} | {
+    kind: "knowledge";
+    bundle?: string;
+} | {
+    kind: "team";
+    member: string;
+    routine?: string;
 };
 export interface ChatMeta {
     id: string;

package/dist/inspector/context.d.ts

@@ -1,5 +1,10 @@
 export declare function setOutputDir(dir: string): void;
-/** Absolute output directory (one run-* folder per run). */
+export declare function setProjectRoot(dir: string): void;
+/** Absolute output directory (runs/ + chats/ live inside). */
 export declare function getOutputDir(): string;
-/** The consumer project root is the parent of the output dir. */
+/**
+ * The consumer project root. Set explicitly at startup; falls back to the
+ * parent of the output dir (wrong for nested output dirs like
+ * kraftwerk-data/output — always pass projectRoot when known).
+ */
 export declare function getProjectRoot(): string;

package/dist/inspector/context.js

@@ -4,16 +4,24 @@ import path from "node:path";
  * Set once by startInspector() before any request is served.
  */
 let outputDir = "";
+let projectRoot = "";
 export function setOutputDir(dir) {
     outputDir = path.resolve(dir);
 }
-/** Absolute output directory (one run-* folder per run). */
+export function setProjectRoot(dir) {
+    projectRoot = path.resolve(dir);
+}
+/** Absolute output directory (runs/ + chats/ live inside). */
 export function getOutputDir() {
     if (!outputDir)
         throw new Error("inspector context not initialized");
     return outputDir;
 }
-/** The consumer project root is the parent of the output dir. */
+/**
+ * The consumer project root. Set explicitly at startup; falls back to the
+ * parent of the output dir (wrong for nested output dirs like
+ * kraftwerk-data/output — always pass projectRoot when known).
+ */
 export function getProjectRoot() {
-    return path.dirname(getOutputDir());
+    return projectRoot || path.dirname(getOutputDir());
 }

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