@netnodeag/kraftwerk 0.39.1 → 0.41.0

package/README.md

@@ -385,13 +385,81 @@ session, errors) lives in `<output>/routines-state.json`.
 The inspector server runs the scheduler in-process, so there is no external
 cron to set up. Every due routine opens a fresh session for the agent, posts
 the prompt, and shows up in the sessions sidebar titled "⏰ <name>". Routine
-sessions run unattended, so tool-permission requests are auto-approved, with
-the request and approval pair left in the thread as an audit trail. Give
-routine prompts the same trust you would give a `KRAFTWERK_YES=1` workflow
-run. Manage routines on the agent page, where you can create, edit and
+sessions run unattended in the harness's own permission mode — your
+configured claude default (`auto` or `acceptEdits`; plain `default` is lifted
+to `acceptEdits`, `bypassPermissions` is never used) or codex's sandboxed
+`agent` preset (never full access). Edits inside the project need no
+approval, and the harness keeps deciding what still needs a human — shell
+commands, network, files outside the project. Kraftwerk never answers those for you.
+The question waits in the thread, the routine row and the agent card show
+"needs approval", and you allow or deny when you look; "allow always" is
+remembered by the harness so the same routine stops asking. A request nobody
+answers within 30 minutes is declined and the routine ends with a summary of
+what it could not do.
+
+The bell in the top bar collects what happened while you were away: a
+session waiting for approval, a routine that finished (with the first lines
+of its summary) or failed, a workflow run started from the inspector that
+ended. The unread count sits on the bell and in front of the tab title, so a
+background tab reads "(2) …"; click an item to jump there. Failure items
+carry a "diagnose" button: it opens a chat where the failure is best
+understood — the run folder for a failed workflow run, a fresh session of the
+same agent for a routine that died mid-run, the kraftwerk-aware chat for a
+routine that could not start — and sends a first message that names the
+failure, points at the evidence (trace, logs, the failed session's events)
+and asks for root cause, fix and how to re-run. Allow browser
+notifications once (the bell offers it) and each new item also shows as a
+system notification while any inspector tab is open. Items live in
+`output/notifications.json`; `GET /api/notifications` lists them,
+`POST /api/notifications/read` marks them, `DELETE /api/notifications` clears.
+
+Manage routines on the agent page, where you can create, edit and
 delete them, toggle enabled, hit "run now", and jump to the last run's
 session. Schedules missed while the server is down are skipped, not replayed.
 
+## Channels
+
+A channel is one conversation shared by several agents and humans — a Slack
+channel where the coworkers are agents. The definition is git-tracked with
+the workspace, the transcript is a chat like any other:
+
+```
+channels/<slug>/channel.yml     # name, purpose, members, responder, maxHops
+output/chats/<chat-id>/         # the transcript (scope { kind: channel })
+```
+
+```yaml
+name: Website relaunch
+purpose: ship the new site by March
+members: [researcher, writer, dev-ops]   # agent slugs
+responder: researcher                    # answers when nobody is @mentioned (optional)
+maxHops: 3                               # agent-to-agent handovers per human message
+```
+
+Every member agent has its own seat in the channel: its own process, its
+own persona, skills, model and permissions, exactly as in a direct session.
+What it receives is not the whole transcript each time but the messages
+since its last turn, each prefixed with the author (`[Lukas]:` a human,
+`[@writer]:` an agent). Who answers:
+
+- `@mention` an agent and it wakes; several mentions run in parallel and
+  their replies stream in as separate posts.
+- No mention: the channel's responder answers, or nobody if none is set.
+- Agents hand over by mentioning each other; `maxHops` bounds the chain
+  per human message so two agents never talk forever.
+- Humans are never blocked. An agent that is busy when mentioned again runs
+  once more when its turn ends, with everything it missed.
+- Permission questions from any agent show as cards in the channel and in
+  the bell; anyone present can answer.
+
+Create channels on the channels screen, or from an existing agent session
+with **add coworker**: the session becomes the channel's transcript, the
+agent keeps its process and memory, and the agents you pick join. Your
+messages carry the name set in the composer ("posting as"), stored per
+browser. API: `GET/POST /api/channels`, `GET/PUT/DELETE /api/channels/:slug`,
+`POST /api/channels/from-chat {chatId, name, members}`; messages go through
+the chat endpoint with `from` for the poster's name.
+
 ## Context & Knowledge
 
 Alongside runs and chats, a project can keep curated knowledge as

package/dist/config.d.ts

@@ -42,6 +42,13 @@ export declare const CONFIG_FILENAMES: string[];
  * skills) plus kraftwerk.yml itself. Commit and push stay manual; the
  * interval only fetches, and pulls when `autosync` allows it.
  */
+/**
+ * A remote or branch name kraftwerk will hand to git as a positional
+ * argument. Git reads a leading dash as an option ("--upload-pack=<cmd>"
+ * runs a command), so such values are refused wherever they enter — config
+ * load, settings API — and the git calls add --end-of-options as well.
+ */
+export declare function isSafeGitName(value: string): boolean;
 export interface GitConfig {
     /** false keeps the block but turns the feature off. Default: true. */
     enabled?: boolean;

package/dist/config.js

@@ -41,6 +41,21 @@ export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk
 export const CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/kraftwerk.schema.json";
 export const CONFIG_FILENAMES = ["kraftwerk.yml", "kraftwerk.yaml"];
 const WORKFLOW_ROOT_CANDIDATES = ["src/workflows", "workflows"];
+/**
+ * Git sync for the workspace. The synced paths are not configurable: they
+ * are the roots this file already declares (workflows, knowledge, agents,
+ * skills) plus kraftwerk.yml itself. Commit and push stay manual; the
+ * interval only fetches, and pulls when `autosync` allows it.
+ */
+/**
+ * A remote or branch name kraftwerk will hand to git as a positional
+ * argument. Git reads a leading dash as an option ("--upload-pack=<cmd>"
+ * runs a command), so such values are refused wherever they enter — config
+ * load, settings API — and the git calls add --end-of-options as well.
+ */
+export function isSafeGitName(value) {
+    return value.length > 0 && !value.startsWith("-") && !/[\s\x00-\x1f]/.test(value);
+}
 /** Where clones land when `repos.root` is not set. */
 export const REPOS_DEFAULT_ROOT = "repos";
 /**
@@ -240,6 +255,9 @@ function validateGit(configPath, value) {
         if (g[key] !== undefined && (typeof g[key] !== "string" || !g[key].trim())) {
             throw new Error(`${file}: git.${key} must be a non-empty string`);
         }
+        if (typeof g[key] === "string" && !isSafeGitName(g[key].trim())) {
+            throw new Error(`${file}: git.${key} must be a plain name (no leading "-", no whitespace)`);
+        }
     }
     if (g.interval !== undefined && (typeof g.interval !== "number" || !Number.isInteger(g.interval) || g.interval < 0)) {
         throw new Error(`${file}: git.interval must be a whole number of seconds (0 disables the timer)`);

package/dist/inspector/channels.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Channels: one transcript shared by several agents and humans — a Slack
+ * channel where the coworkers are agents. The definition is git-tracked
+ * with the workspace so the whole team sees the same channels:
+ *
+ *   channels/<slug>/channel.yml   # name, purpose, members (agent slugs), responder, maxHops
+ *
+ * The transcript itself is a chat (scope { kind: "channel", slug }) under
+ * <output>/chats/, run-state like every other chat. sessions.ts gives each
+ * member agent its own seat (process) in that chat and routes messages:
+ * an @mention wakes that agent, no mention wakes the channel's responder,
+ * an agent mentioning another hands over — bounded by maxHops per human
+ * message so two agents never talk forever.
+ */
+export interface Channel {
+    slug: string;
+    name: string;
+    purpose?: string;
+    /** Agent slugs that sit in the channel. */
+    members: string[];
+    /** Who answers a message that mentions nobody; absent = nobody does. */
+    responder?: string;
+    /** Agent-to-agent handovers allowed per human message. */
+    maxHops: number;
+}
+export declare const DEFAULT_MAX_HOPS = 3;
+export declare function channelsRoot(): Promise<string>;
+export declare function safeChannelSlug(slug: string): string;
+export declare function listChannels(): Promise<Channel[]>;
+export declare function getChannel(slug: string): Promise<Channel | null>;
+export interface SaveChannelInput {
+    slug?: string;
+    name?: string;
+    purpose?: string;
+    members?: string[];
+    /** Agent slug, or "" / null to clear. */
+    responder?: string | null;
+    maxHops?: number;
+}
+/** Create (no slug: derived from the name) or update a channel definition. */
+export declare function saveChannel(input: SaveChannelInput): Promise<Channel>;
+export declare function deleteChannel(slug: string): Promise<void>;
+/**
+ * Who a channel message wakes. @mentions of members win (in text order, each
+ * once); a message that mentions nobody goes to the responder, or to nobody.
+ * `self` (the author, when an agent) never wakes itself.
+ */
+export declare function mentionTargets(text: string, channel: Pick<Channel, "members" | "responder">, self?: string): string[];

package/dist/inspector/channels.js

@@ -0,0 +1,130 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { getProjectRoot } from "./context.js";
+import { resolveProject } from "../config.js";
+import { listAgents, safeAgentSlug, slugFromName } from "./agents.js";
+export const DEFAULT_MAX_HOPS = 3;
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+export async function channelsRoot() {
+    const project = await resolveProject(getProjectRoot());
+    return path.resolve(project.root, "channels");
+}
+export function safeChannelSlug(slug) {
+    if (!SLUG_RE.test(slug))
+        throw new Error(`invalid channel slug "${slug}"`);
+    return slug;
+}
+function normalize(slug, raw) {
+    const members = Array.isArray(raw.members) ? [...new Set(raw.members.map(String))] : [];
+    const responder = typeof raw.responder === "string" && members.includes(raw.responder) ? raw.responder : undefined;
+    const hops = typeof raw.maxHops === "number" && Number.isInteger(raw.maxHops) && raw.maxHops >= 0 ? raw.maxHops : DEFAULT_MAX_HOPS;
+    return {
+        slug,
+        name: String(raw.name ?? slug),
+        ...(raw.purpose ? { purpose: String(raw.purpose) } : {}),
+        members,
+        ...(responder ? { responder } : {}),
+        maxHops: hops,
+    };
+}
+export async function listChannels() {
+    const root = await channelsRoot();
+    let entries;
+    try {
+        entries = (await fs.readdir(root, { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && SLUG_RE.test(e.name))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const channels = await Promise.all(entries.map((slug) => getChannel(slug)));
+    return channels.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function getChannel(slug) {
+    const file = path.join(await channelsRoot(), safeChannelSlug(slug), "channel.yml");
+    try {
+        const raw = parse(await fs.readFile(file, "utf8"));
+        return normalize(slug, (raw ?? {}));
+    }
+    catch {
+        return null;
+    }
+}
+/** Members must be existing, non-archived agents; returns them in the order given. */
+async function checkMembers(slugs) {
+    const agents = await listAgents();
+    return slugs.map((slug) => {
+        const a = agents.find((m) => m.slug === safeAgentSlug(slug));
+        if (!a)
+            throw new Error(`agent "${slug}" not found`);
+        if (a.archived)
+            throw new Error(`agent "${slug}" is archived`);
+        return a;
+    });
+}
+/** Create (no slug: derived from the name) or update a channel definition. */
+export async function saveChannel(input) {
+    const existing = input.slug ? await getChannel(safeChannelSlug(input.slug)) : null;
+    const name = (input.name ?? existing?.name ?? "").trim();
+    if (!name)
+        throw new Error("name is required");
+    const slug = input.slug ? safeChannelSlug(input.slug) : slugFromName(name);
+    if (!input.slug && (await getChannel(slug)))
+        throw new Error(`channel "${slug}" exists already`);
+    const members = input.members !== undefined ? [...new Set(input.members.map(String))] : existing?.members ?? [];
+    if (members.length === 0)
+        throw new Error("a channel needs at least one agent");
+    await checkMembers(members);
+    let responder = existing?.responder;
+    if (input.responder !== undefined)
+        responder = input.responder ? input.responder : undefined;
+    if (responder && !members.includes(responder))
+        responder = undefined;
+    const maxHops = input.maxHops !== undefined
+        ? Number.isInteger(input.maxHops) && input.maxHops >= 0
+            ? input.maxHops
+            : (() => {
+                throw new Error("maxHops must be a whole number");
+            })()
+        : existing?.maxHops ?? DEFAULT_MAX_HOPS;
+    const channel = {
+        slug,
+        name,
+        ...(input.purpose !== undefined
+            ? input.purpose.trim()
+                ? { purpose: input.purpose.trim() }
+                : {}
+            : existing?.purpose
+                ? { purpose: existing.purpose }
+                : {}),
+        members,
+        ...(responder ? { responder } : {}),
+        maxHops,
+    };
+    const dir = path.join(await channelsRoot(), slug);
+    await fs.mkdir(dir, { recursive: true });
+    const { slug: _s, ...body } = channel;
+    await fs.writeFile(path.join(dir, "channel.yml"), stringify(body));
+    return channel;
+}
+export async function deleteChannel(slug) {
+    await fs.rm(path.join(await channelsRoot(), safeChannelSlug(slug)), { recursive: true, force: true });
+}
+/**
+ * Who a channel message wakes. @mentions of members win (in text order, each
+ * once); a message that mentions nobody goes to the responder, or to nobody.
+ * `self` (the author, when an agent) never wakes itself.
+ */
+export function mentionTargets(text, channel, self) {
+    const out = [];
+    for (const m of text.matchAll(/(^|[^\w@])@([a-z0-9][a-z0-9-]*)/g)) {
+        const slug = m[2];
+        if (channel.members.includes(slug) && slug !== self && !out.includes(slug))
+            out.push(slug);
+    }
+    if (out.length === 0 && channel.responder && channel.responder !== self && !self)
+        return [channel.responder];
+    return out;
+}

package/dist/inspector/chat/acp.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
+import { unattendedMode } from "./permissions.js";
 /**
  * ACP-backed chat: spawn an adapter (claude-agent-acp / codex-acp) as a
  * subprocess, speak Agent Client Protocol over its stdio, and translate
@@ -143,6 +144,22 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
             : {}),
     });
     const sessionId = session.sessionId;
+    if (tuning.unattended) {
+        // Nobody is watching: keep the harness's configured mode unless it is
+        // one that never asks (see unattendedMode). The harness keeps deciding
+        // which calls reach a human; kraftwerk only rules out "never ask".
+        const modeId = unattendedMode(agent, session.modes?.currentModeId);
+        if (modeId) {
+            // A mode the adapter does not offer must not kill the session: the
+            // harness default applies, and the thread shows why.
+            await conn.setSessionMode({ sessionId, modeId }).catch((err) => {
+                hooks.emit({
+                    type: "error",
+                    message: `could not select the ${modeId} mode for this unattended session (${err.message}) — the ${agent} default applies`,
+                });
+            });
+        }
+    }
     return {
         async prompt(text) {
             if (dead)

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

@@ -31,6 +31,12 @@ export interface BackendTuning {
     skillDirs?: string[];
     /** claude: extra directories the session may work in (e.g. project root for run chats). */
     addDirs?: string[];
+    /**
+     * Nobody is watching this session live (routine runs). The backend selects
+     * the harness's own hands-off permission mode — the harness keeps deciding
+     * what still needs a human; kraftwerk never answers for one.
+     */
+    unattended?: boolean;
 }
 export interface ChatBackend {
     /** Send one user message; resolves with the stop reason at turn end. */

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

@@ -0,0 +1,36 @@
+/**
+ * Permission requests for sessions nobody is watching live (routine runs).
+ *
+ * The harness (claude / codex) decides which tool calls need a human; a
+ * request reaching kraftwerk means the harness already judged the action
+ * worth asking about. Kraftwerk never answers on the human's behalf — it
+ * holds the question in the thread, flags the session as waiting, and gives
+ * the human this long to look. When nobody does, the request is declined
+ * so the routine can end with a clear summary instead of hanging forever.
+ */
+export declare const UNATTENDED_PERMISSION_TIMEOUT_MS: number;
+export interface PermissionOption {
+    optionId: string;
+    name: string;
+    kind?: string;
+}
+/**
+ * The option that declines a request without ending the turn: the adapter's
+ * `reject_once` (ACP kinds are allow_once / allow_always / reject_once /
+ * reject_always). null cancels the tool call outright when no reject option
+ * is offered — never an "allow".
+ */
+export declare function declineOption(options: PermissionOption[]): string | null;
+/** Human-readable timeout for prompts and thread notes. */
+export declare function unattendedTimeoutLabel(ms?: number): string;
+/**
+ * Session mode for an unattended (routine) session, given the mode the
+ * harness opened with (its configured default). Returns the mode to switch
+ * to, or null to keep the current one. The harness stays the judge of what
+ * needs a human; this only rules out the two presets that never ask —
+ * claude bypassPermissions and codex agent-full-access — and lifts claude's
+ * plain "default" (ask for every edit) to acceptEdits so a routine can write
+ * inside the project without stalling. claude's "auto" mode (its own
+ * classifier decides) and acceptEdits are kept as they are.
+ */
+export declare function unattendedMode(agent: "claude" | "codex", current: string | undefined): string | null;

package/dist/inspector/chat/permissions.js

@@ -0,0 +1,42 @@
+/**
+ * Permission requests for sessions nobody is watching live (routine runs).
+ *
+ * The harness (claude / codex) decides which tool calls need a human; a
+ * request reaching kraftwerk means the harness already judged the action
+ * worth asking about. Kraftwerk never answers on the human's behalf — it
+ * holds the question in the thread, flags the session as waiting, and gives
+ * the human this long to look. When nobody does, the request is declined
+ * so the routine can end with a clear summary instead of hanging forever.
+ */
+export const UNATTENDED_PERMISSION_TIMEOUT_MS = 30 * 60_000;
+/**
+ * The option that declines a request without ending the turn: the adapter's
+ * `reject_once` (ACP kinds are allow_once / allow_always / reject_once /
+ * reject_always). null cancels the tool call outright when no reject option
+ * is offered — never an "allow".
+ */
+export function declineOption(options) {
+    const reject = options.find((o) => o.kind === "reject_once") ??
+        options.find((o) => o.kind?.startsWith("reject"));
+    return reject?.optionId ?? null;
+}
+/** Human-readable timeout for prompts and thread notes. */
+export function unattendedTimeoutLabel(ms = UNATTENDED_PERMISSION_TIMEOUT_MS) {
+    const min = Math.round(ms / 60_000);
+    return min === 1 ? "1 minute" : `${min} minutes`;
+}
+/**
+ * Session mode for an unattended (routine) session, given the mode the
+ * harness opened with (its configured default). Returns the mode to switch
+ * to, or null to keep the current one. The harness stays the judge of what
+ * needs a human; this only rules out the two presets that never ask —
+ * claude bypassPermissions and codex agent-full-access — and lifts claude's
+ * plain "default" (ask for every edit) to acceptEdits so a routine can write
+ * inside the project without stalling. claude's "auto" mode (its own
+ * classifier decides) and acceptEdits are kept as they are.
+ */
+export function unattendedMode(agent, current) {
+    if (agent === "codex")
+        return current === "agent-full-access" || !current ? "agent" : null;
+    return current === "auto" || current === "acceptEdits" ? null : "acceptEdits";
+}

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

@@ -1,4 +1,5 @@
 import type { ChatAgentId, ChatMeta, ChatScope, StoredChatEvent } from "./types.js";
+import { type Channel } from "../channels.js";
 /** Server shutdown: no agent subprocess may outlive the inspector. */
 export declare function disposeAllBackends(): void;
 /**
@@ -21,17 +22,35 @@ export declare function createChat(opts: {
     /** Preset title (e.g. routine runs); otherwise the first message names the chat. */
     title?: string;
 }): Promise<ChatMeta>;
+/** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
+export declare function chatAwaitingApproval(id: string): boolean;
 export declare function listChats(): Promise<Array<ChatMeta & {
     busy: boolean;
+    awaitingApproval: boolean;
 }>>;
 export declare function getChat(id: string): Promise<{
     meta: ChatMeta;
     events: StoredChatEvent[];
     busy: boolean;
 } | null>;
-export declare function postMessage(id: string, text: string): Promise<{
+export declare function postMessage(id: string, text: string, opts?: {
+    from?: string;
+}): Promise<{
     error?: string;
 }>;
+/** The chat that holds a channel's transcript; created on first use. */
+export declare function ensureChannelChat(channel: Channel): Promise<ChatMeta>;
+/**
+ * "Add a coworker" to an agent session: the chat becomes the channel's
+ * transcript. The agent keeps its process and memory — it has seen every
+ * message so far — and learns the channel rules with its next prompt.
+ */
+export declare function convertChatToChannel(chatId: string, channel: Channel): Promise<{
+    error?: string;
+    meta?: ChatMeta;
+}>;
+/** Members left the channel: their processes go, the transcript stays. */
+export declare function dropChannelSeats(chatId: string, keep: string[]): Promise<void>;
 /**
  * Open a vibeable in the chat (or close it with null). The agent's cwd
  * becomes the app folder, so the running subprocess is dropped and the next