@netnodeag/kraftwerk 0.40.0 → 0.41.0

package/README.md

@@ -417,6 +417,49 @@ 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/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/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;
 /**
@@ -32,9 +33,24 @@ export declare function getChat(id: string): Promise<{
     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