@netnodeag/kraftwerk 0.40.0 → 0.41.0

package/dist/inspector/chat/sessions.js

@@ -12,8 +12,31 @@ import { startAcpBackend } from "./acp.js";
 import { startPiBackend } from "./pi.js";
 import { UNATTENDED_PERMISSION_TIMEOUT_MS, declineOption, unattendedTimeoutLabel } from "./permissions.js";
 import { chatHref, dismissKey, pushNotification } from "../notifications.js";
+import { getChannel, mentionTargets } from "../channels.js";
 import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
+const MAIN = "main";
 const states = new Map();
+const newSeat = (key, harness) => ({
+    key,
+    harness,
+    backend: null,
+    busy: false,
+    needsContext: true,
+    seenSeq: 0,
+    wake: null,
+});
+/** The one seat of an ordinary (non-channel) chat. */
+function mainSeat(state) {
+    let seat = state.seats.get(MAIN);
+    if (!seat) {
+        seat = newSeat(MAIN, state.meta.agent);
+        state.seats.set(MAIN, seat);
+    }
+    return seat;
+}
+const isBusy = (state) => [...state.seats.values()].some((s) => s.busy);
+/** The event author for a seat: channel members sign their events, the lone agent of a chat does not. */
+const seatAuthor = (seat) => (seat.key === MAIN ? undefined : { kind: "agent", slug: seat.key });
 /** Routine-fired sessions: nobody is expected to be watching live. */
 const isUnattended = (scope) => scope.kind === "agent" && !!scope.routine;
 /** Diagnose handle for a failed routine session (only called for unattended agent scopes). */
@@ -25,6 +48,8 @@ function routineRef(meta) {
 }
 /** How the bell names a chat: its title ("⏰ Morning digest"), else the agent, else "chat". */
 function chatLabel(meta) {
+    if (meta.scope.kind === "channel")
+        return `#${meta.scope.slug}`;
     if (meta.title)
         return meta.title;
     return meta.scope.kind === "agent" ? meta.scope.slug : "chat";
@@ -49,10 +74,14 @@ function lastEventText(state, afterSeq, type) {
     const paras = text.split(/\n{2,}/).filter((p) => p.trim());
     return paras.slice(-2).join("\n\n");
 }
-/** Kill a chat's agent subprocess; the next message spawns a fresh one. */
+function dropSeat(seat) {
+    seat.backend?.dispose();
+    seat.backend = null;
+}
+/** Kill a chat's agent subprocess(es); the next message spawns fresh ones. */
 function dropBackend(state) {
-    state.backend?.dispose();
-    state.backend = null;
+    for (const seat of state.seats.values())
+        dropSeat(seat);
 }
 // Idle reaper: a finished chat must not keep its agent subprocess alive
 // forever (one ACP adapter + one harness binary per chat adds up fast —
@@ -64,7 +93,8 @@ const IDLE_BACKEND_MS = 15 * 60_000;
 const reaper = setInterval(() => {
     const cutoff = Date.now() - IDLE_BACKEND_MS;
     for (const state of states.values()) {
-        if (state.backend && !state.busy && Date.parse(state.meta.updatedAt) < cutoff) {
+        const live = [...state.seats.values()].some((s) => s.backend);
+        if (live && !isBusy(state) && Date.parse(state.meta.updatedAt) < cutoff) {
             dropBackend(state);
         }
     }
@@ -86,20 +116,19 @@ async function loadState(id) {
         meta,
         events: await readEvents(id),
         subscribers: new Set(),
-        backend: null,
-        busy: false,
+        seats: new Map(),
         pendingPermissions: new Map(),
         writeChain: Promise.resolve(),
-        needsContext: true,
     };
     // Two racing loads: keep whichever registered first.
     return states.get(id) ?? (states.set(id, state), state);
 }
-function emit(state, ev) {
+function emit(state, ev, from) {
     const stored = {
         ...ev,
         seq: (state.events[state.events.length - 1]?.seq ?? 0) + 1,
         ts: new Date().toISOString(),
+        ...(from ? { from } : {}),
     };
     state.events.push(stored);
     state.meta.updatedAt = stored.ts;
@@ -393,25 +422,57 @@ const RENDERING_BLOCK = `## Chat rendering\n` +
     `with ![alt](/api/runs/<run-id>/file?name=picture.png&raw=1), or link any artifact the same way. ` +
     `Prefer these relative /api/... URLs over file paths when showing results: they render directly ` +
     `in this chat and keep working wherever the inspector is reachable.`;
-async function scopeContext(meta) {
-    const { scope, agent } = meta;
+async function scopeContext(meta, seat) {
+    // A channel seat is the member agent in its own right: persona, skills and
+    // repositories as in its direct sessions, plus the channel rules.
+    const scope = meta.scope.kind === "channel" ? { kind: "agent", slug: seat.key } : meta.scope;
+    const agent = seat.harness;
     // The repositories block reads every clone from git, so it runs alongside
     // the rest instead of adding its spawns to the first prompt's latency.
-    const [base, repos, vibe, skills] = await Promise.all([
+    const [base, repos, vibe, skills, channel] = await Promise.all([
         baseScopeContext(scope, agent),
         scope.kind === "agent" || scope.kind === "kraftwerk" ? reposContext() : Promise.resolve(""),
         meta.vibeable ? vibeableContext(meta.vibeable, meta.cwd) : Promise.resolve(""),
         availableSkills(scope),
+        meta.scope.kind === "channel" ? channelContext(meta.scope.slug, seat.key) : Promise.resolve(""),
     ]);
-    return [base, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+    return [base, channel, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+}
+/** The channel block a member agent gets once per process: who is here, how turns work, how to hand over. */
+async function channelContext(slug, self) {
+    const channel = await getChannel(slug).catch(() => null);
+    if (!channel)
+        return `You sit in channel #${slug}, but its definition under channels/ is missing. Tell the humans.`;
+    const agents = await listAgents().catch(() => []);
+    const others = channel.members
+        .filter((m) => m !== self)
+        .map((m) => {
+        const a = agents.find((x) => x.slug === m);
+        return `- @${m}${a ? ` — ${a.emoji} ${a.name}${a.description ? `: ${a.description}` : ""}` : ""}`;
+    })
+        .join("\n");
+    return (`## Channel #${channel.slug} — ${channel.name}\n` +
+        (channel.purpose ? `Purpose: ${channel.purpose}\n` : "") +
+        `This is a group conversation, like a Slack channel: humans and several agents share one transcript. ` +
+        `You are @${self}. Other agents here:\n${others || "(none — you are the only agent)"}\n\n` +
+        `How it works: each time you are woken you receive the messages posted since your last turn, each prefixed ` +
+        `with its author ("[Lukas]:" is a human, "[@slug]:" an agent). Reply as yourself, to the channel — everyone reads it. ` +
+        `You are woken when a message @mentions you` +
+        (channel.responder === self ? `, and for every message that mentions nobody (you are the channel's responder)` : "") +
+        `. To hand a task to another agent, @mention them in your reply and say what you need; they are woken with your ` +
+        `message. Do not mention an agent just to be polite — every mention starts a turn, and handovers are limited to ` +
+        `${channel.maxHops} per human message. Do not repeat what others already said; add your part. Keep replies short ` +
+        `unless the task needs detail; a long result is better as a file in the project than as a wall of text.`);
 }
 /* ---------- backend lifecycle ---------- */
 /** Agent sessions carry the agent's model/effort; resolved live so edits apply to new backends. */
-async function backendTuning(meta) {
-    const { scope, agent } = meta;
+async function backendTuning(meta, seat) {
+    const { scope } = meta;
+    const agent = seat.harness;
     const tuning = {};
-    if (scope.kind === "agent") {
-        const def = await getAgent(scope.slug).catch(() => null);
+    const agentSlug = scope.kind === "agent" ? scope.slug : scope.kind === "channel" ? seat.key : undefined;
+    if (agentSlug) {
+        const def = await getAgent(agentSlug).catch(() => null);
         if (def?.model)
             tuning.model = def.model;
         if (def?.effort)
@@ -436,11 +497,12 @@ async function backendTuning(meta) {
     }
     return tuning;
 }
-async function ensureBackend(state) {
-    if (state.backend)
-        return state.backend;
+async function ensureBackend(state, seat) {
+    if (seat.backend)
+        return seat.backend;
+    const me = seatAuthor(seat);
     const hooks = {
-        emit: (ev) => void emit(state, ev),
+        emit: (ev) => void emit(state, ev, me),
         askPermission: (title, options) => {
             // The harness already judged this call worth asking about, so the
             // question always goes to a human — routine sessions included. The
@@ -456,16 +518,16 @@ async function ensureBackend(state) {
                     if (deadline)
                         clearTimeout(deadline);
                     state.pendingPermissions.delete(requestId);
-                    emit(state, { type: "permission_resolved", requestId, optionId });
+                    emit(state, { type: "permission_resolved", requestId, optionId }, me);
                     void dismissKey(notifyKey);
                     resolve(optionId);
                 });
-                emit(state, { type: "permission_request", requestId, title, options });
+                emit(state, { type: "permission_request", requestId, title, options }, me);
                 // The bell: a question is waiting. Answered -> the item goes away again.
                 void pushNotification({
                     kind: "approval",
                     key: notifyKey,
-                    title: `${chatLabel(state.meta)} needs approval`,
+                    title: `${chatLabel(state.meta)}${me?.kind === "agent" ? ` · @${me.slug}` : ""} needs approval`,
                     body: title,
                     href: chatHref(state.meta),
                 });
@@ -485,17 +547,17 @@ async function ensureBackend(state) {
             });
         },
     };
-    const { agent } = state.meta;
+    const agent = seat.harness;
     const cwd = await effectiveCwd(state.meta);
-    const tuning = await backendTuning(state.meta);
-    state.backend =
+    const tuning = await backendTuning(state.meta, seat);
+    seat.backend =
         agent === "pi"
             ? startPiBackend(cwd, hooks, tuning)
             : await startAcpBackend(agent, cwd, hooks, tuning);
     // Fresh process = fresh context window: re-send scope context with the
     // next prompt (matters for chats resumed after an inspector restart).
-    state.needsContext = true;
-    return state.backend;
+    seat.needsContext = true;
+    return seat.backend;
 }
 /* ---------- public API (used by server.ts) ---------- */
 /** Where a chat's agent runs when no vibeable is open: the run folder for run chats, else the project root. */
@@ -529,11 +591,9 @@ export async function createChat(opts) {
         meta,
         events: [],
         subscribers: new Set(),
-        backend: null,
-        busy: false,
+        seats: new Map(),
         pendingPermissions: new Map(),
         writeChain: Promise.resolve(),
-        needsContext: true,
     });
     return meta;
 }
@@ -545,7 +605,7 @@ 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,
+        busy: states.has(m.id) ? isBusy(states.get(m.id)) : false,
         awaitingApproval: chatAwaitingApproval(m.id),
     }));
 }
@@ -553,15 +613,18 @@ export async function getChat(id) {
     const state = await loadState(id);
     if (!state)
         return null;
-    return { meta: state.meta, events: state.events, busy: state.busy };
+    return { meta: state.meta, events: state.events, busy: isBusy(state) };
 }
-export async function postMessage(id, text) {
+export async function postMessage(id, text, opts = {}) {
     const state = await loadState(id);
     if (!state)
         return { error: "not found" };
-    if (state.busy)
+    if (state.meta.scope.kind === "channel")
+        return postChannelMessage(state, state.meta.scope.slug, text, opts.from);
+    const seat = mainSeat(state);
+    if (seat.busy)
         return { error: "agent is still working — wait for the turn to finish" };
-    state.busy = true;
+    seat.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);
@@ -572,9 +635,9 @@ export async function postMessage(id, text) {
     // and the browser follows along on the SSE stream.
     void (async () => {
         try {
-            const backend = await ensureBackend(state);
-            const context = state.needsContext ? await scopeContext(state.meta) : "";
-            state.needsContext = false;
+            const backend = await ensureBackend(state, seat);
+            const context = seat.needsContext ? await scopeContext(state.meta, seat) : "";
+            seat.needsContext = false;
             // "/<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);
@@ -612,12 +675,183 @@ export async function postMessage(id, text) {
             dropBackend(state);
         }
         finally {
-            state.busy = false;
+            seat.busy = false;
             void writeMeta(state.meta).catch(() => { });
         }
     })();
     return {};
 }
+/* ---------- channels ---------- */
+/**
+ * A human posts to a channel: the message is signed with their name and the
+ * agents it wakes (mentions, else the responder) each run a turn — in
+ * parallel, never blocking the humans, who can keep posting. An agent that
+ * is still busy is woken again when its turn ends, so nothing is lost.
+ */
+async function postChannelMessage(state, slug, text, from) {
+    const channel = await getChannel(slug).catch(() => null);
+    if (!channel)
+        return { error: `channel "${slug}" has no definition under channels/` };
+    const name = (from ?? "").replace(/\s+/g, " ").trim().slice(0, 40) || "you";
+    emit(state, { type: "user_message", text }, { kind: "human", name });
+    void writeMeta(state.meta).catch(() => { });
+    for (const target of mentionTargets(text, channel))
+        void wakeSeat(state, channel, target, 0);
+    return {};
+}
+/** Wake a member agent: run a turn now, or mark it to run again when its current turn ends. */
+async function wakeSeat(state, channel, slug, hops) {
+    const def = await getAgent(slug).catch(() => null);
+    if (!def) {
+        emit(state, { type: "error", message: `@${slug} is in the channel but has no agent definition under agents/` });
+        return;
+    }
+    let seat = state.seats.get(slug);
+    if (!seat) {
+        seat = newSeat(slug, def.harness);
+        state.seats.set(slug, seat);
+    }
+    if (seat.busy) {
+        seat.wake = { hops: Math.min(hops, seat.wake?.hops ?? hops) };
+        return;
+    }
+    await runSeatTurn(state, channel, seat, hops);
+}
+/**
+ * The transcript a seat has not seen yet, as the agent reads it: humans by
+ * name, other agents by @slug (their streamed text merged per turn), own
+ * messages and machinery (tools, permissions, thoughts) left out.
+ */
+function transcriptSince(state, afterSeq, beforeSeq, self) {
+    const lines = [];
+    let open = null;
+    const flush = () => {
+        if (open && open.text.trim())
+            lines.push(`[@${open.slug}]: ${open.text.trim()}`);
+        open = null;
+    };
+    for (const e of state.events) {
+        if (e.seq <= afterSeq || e.seq >= beforeSeq)
+            continue;
+        if (e.type === "user_message") {
+            flush();
+            lines.push(`[${e.from?.kind === "human" ? e.from.name : "human"}]: ${e.text}`);
+        }
+        else if (e.type === "text" && e.from?.kind === "agent" && e.from.slug !== self) {
+            if (open && open.slug !== e.from.slug)
+                flush();
+            open = open ?? { slug: e.from.slug, text: "" };
+            open.text += e.text;
+        }
+        else if (e.type === "turn_end" && open && e.from?.kind === "agent" && e.from.slug === open.slug) {
+            flush();
+        }
+    }
+    flush();
+    return lines.join("\n\n");
+}
+/** What one agent said during a turn (its streamed text after `afterSeq`). */
+function seatTextSince(state, afterSeq, slug) {
+    return state.events
+        .filter((e) => e.seq > afterSeq && e.type === "text" && e.from?.kind === "agent" && e.from.slug === slug)
+        .map((e) => e.text)
+        .join("");
+}
+async function runSeatTurn(state, channel, seat, hops) {
+    seat.busy = true;
+    const me = { kind: "agent", slug: seat.key };
+    const start = emit(state, { type: "turn_start" }, me).seq;
+    try {
+        const backend = await ensureBackend(state, seat);
+        const context = seat.needsContext ? await scopeContext(state.meta, seat) : "";
+        seat.needsContext = false;
+        const delta = transcriptSince(state, seat.seenSeq, start, seat.key);
+        seat.seenSeq = start;
+        if (!delta && !context) {
+            emit(state, { type: "turn_end", stopReason: "nothing_new" }, me);
+            return;
+        }
+        const prompt = (context ? `<context>\n${context}\n</context>\n\n` : "") +
+            (delta ? `New messages in #${channel.slug}:\n\n${delta}` : `You joined #${channel.slug}. Nothing addressed to you yet — reply with one short line saying you are here.`);
+        const stopReason = await backend.prompt(prompt);
+        emit(state, { type: "turn_end", stopReason }, me);
+        // Handover: agents this one @mentioned get its message, within the hop budget.
+        const said = seatTextSince(state, start, seat.key);
+        const next = mentionTargets(said, channel, seat.key);
+        if (next.length > 0 && hops >= channel.maxHops) {
+            emit(state, {
+                type: "error",
+                message: `handover limit reached (${channel.maxHops} per human message) — @mention ${next.map((n) => `@${n}`).join(", ")} yourself to continue`,
+            });
+        }
+        else {
+            for (const target of next)
+                void wakeSeat(state, channel, target, hops + 1);
+        }
+    }
+    catch (err) {
+        emit(state, { type: "error", message: err.message }, me);
+        dropSeat(seat);
+    }
+    finally {
+        seat.busy = false;
+        void writeMeta(state.meta).catch(() => { });
+        if (seat.wake) {
+            const { hops: again } = seat.wake;
+            seat.wake = null;
+            void runSeatTurn(state, channel, seat, again);
+        }
+    }
+}
+/** The chat that holds a channel's transcript; created on first use. */
+export async function ensureChannelChat(channel) {
+    const metas = await listChatMetas();
+    const existing = metas.find((m) => m.scope.kind === "channel" && m.scope.slug === channel.slug);
+    if (existing)
+        return states.get(existing.id)?.meta ?? existing;
+    return createChat({ agent: "claude", scope: { kind: "channel", slug: channel.slug }, title: channel.name });
+}
+/**
+ * "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 async function convertChatToChannel(chatId, channel) {
+    const state = await loadState(chatId);
+    if (!state)
+        return { error: "chat not found" };
+    const scope = state.meta.scope;
+    if (scope.kind !== "agent")
+        return { error: "only an agent session can become a channel" };
+    if (!channel.members.includes(scope.slug))
+        return { error: `the channel must include @${scope.slug}` };
+    if (isBusy(state))
+        return { error: "agent is still working — wait for the turn to finish" };
+    const main = state.seats.get(MAIN);
+    state.seats.delete(MAIN);
+    const seat = main ?? newSeat(scope.slug, state.meta.agent);
+    seat.key = scope.slug;
+    seat.needsContext = true;
+    seat.seenSeq = state.events[state.events.length - 1]?.seq ?? 0;
+    state.seats.set(scope.slug, seat);
+    state.meta.scope = { kind: "channel", slug: channel.slug };
+    state.meta.title = channel.name;
+    state.meta.updatedAt = new Date().toISOString();
+    await writeMeta(state.meta);
+    return { meta: state.meta };
+}
+/** Members left the channel: their processes go, the transcript stays. */
+export async function dropChannelSeats(chatId, keep) {
+    const state = states.get(chatId);
+    if (!state)
+        return;
+    for (const [key, seat] of state.seats) {
+        if (!keep.includes(key)) {
+            dropSeat(seat);
+            state.seats.delete(key);
+        }
+    }
+}
 /**
  * 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
@@ -629,7 +863,7 @@ export async function setChatVibeable(id, slug) {
     if (!state)
         return { error: "not found", status: 404 };
     const busyError = { error: "agent is still working — wait for the turn to finish", status: 409 };
-    if (state.busy)
+    if (isBusy(state))
         return busyError;
     let dir = null;
     if (slug) {
@@ -644,7 +878,7 @@ export async function setChatVibeable(id, slug) {
     // A message may have started a turn during the await above; its backend
     // was spawned in the old cwd, so refuse rather than relabel it. From here
     // on nothing yields until cwd, vibeable and backend agree.
-    if (state.busy)
+    if (isBusy(state))
         return busyError;
     if (slug && dir) {
         state.meta.vibeable = slug;
@@ -656,7 +890,8 @@ export async function setChatVibeable(id, slug) {
     }
     state.meta.updatedAt = new Date().toISOString();
     dropBackend(state);
-    state.needsContext = true;
+    for (const seat of state.seats.values())
+        seat.needsContext = true;
     await writeMeta(state.meta);
     return { meta: state.meta };
 }
@@ -688,7 +923,8 @@ export async function cancelChat(id) {
         return { error: "not found" };
     for (const resolve of state.pendingPermissions.values())
         resolve(null);
-    state.backend?.cancel();
+    for (const seat of state.seats.values())
+        seat.backend?.cancel();
     return {};
 }
 /**

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

@@ -20,6 +20,19 @@ export type ChatScope = {
     kind: "agent";
     slug: string;
     routine?: string;
+}
+/** A channel: several agents (and humans) share one transcript; see channels.ts. */
+ | {
+    kind: "channel";
+    slug: string;
+};
+/** Who produced an event. Absent on single-agent chats (the one human, the one agent). */
+export type Author = {
+    kind: "human";
+    name: string;
+} | {
+    kind: "agent";
+    slug: string;
 };
 export interface ChatMeta {
     id: string;
@@ -66,6 +79,10 @@ export type ChatEvent = {
     type: "permission_resolved";
     requestId: string;
     optionId: string | null;
+}
+/** Channels: an agent starts working on the messages it was shown (pairs with turn_end by the same author). */
+ | {
+    type: "turn_start";
 } | {
     type: "turn_end";
     stopReason: string;
@@ -76,4 +93,5 @@ export type ChatEvent = {
 export type StoredChatEvent = ChatEvent & {
     seq: number;
     ts: string;
+    from?: Author;
 };

package/dist/inspector/notifications.js

@@ -38,6 +38,8 @@ export function clipBody(text) {
 }
 /** Inspector route for a chat — mirrors chatHref in the UI. */
 export function chatHref(meta) {
+    if (meta.scope.kind === "channel")
+        return `/channels/${meta.scope.slug}`;
     return meta.scope.kind === "agent" ? `/agents/${meta.scope.slug}/chat/${meta.id}` : `/agents/chats/${meta.id}`;
 }
 export async function pushNotification(input) {

package/dist/inspector/server.js

@@ -8,7 +8,8 @@ import { listWorkflows, getWorkflow } from "./workflows.js";
 import { dockerStatus, triggerRun, stopRun } from "./runner.js";
 import { clearNotifications, listNotifications, markNotificationsRead } from "./notifications.js";
 import { startDiagnosis } from "./diagnose.js";
-import { cancelChat, createChat, deleteChat, disposeAllBackends, getChat, listChats, postMessage, resolvePermission, setChatVibeable, subscribeChat, } from "./chat/sessions.js";
+import { deleteChannel, getChannel, listChannels, saveChannel, channelsRoot } from "./channels.js";
+import { cancelChat, createChat, deleteChat, disposeAllBackends, getChat, listChats, postMessage, resolvePermission, setChatVibeable, subscribeChat, convertChatToChannel, dropChannelSeats, ensureChannelChat } from "./chat/sessions.js";
 import { bundleDetail, conceptDetail, createBundle, knowledgeIndex, putConcept, verifyFromUi, } from "./knowledge.js";
 import { deleteAgent, getAgent, listAgents, saveAgent, setAgentArchived, agentsRoot, } from "./agents.js";
 import { deleteAgentSkill, getSkill, listAgentSkills, listSkills, readSkill, saveAgentSkill, skillsRoot, } from "./skills.js";
@@ -190,6 +191,76 @@ async function handleApi(req, res, url) {
     if (method !== "GET" && method !== "HEAD" && !sameOrigin(req)) {
         return json(res, { error: "cross-origin request refused" }, 403);
     }
+    // Channels — shared transcripts with several agents (channels/<slug>/channel.yml + one chat).
+    // GET /api/channels | POST /api/channels {name, purpose?, members, responder?}
+    // POST /api/channels/from-chat {chatId, name, members, ...} — an agent session becomes a channel
+    // GET/PUT/DELETE /api/channels/:slug
+    if (seg.length >= 2 && seg[1] === "channels") {
+        const view = async (c) => {
+            const meta = await ensureChannelChat(c);
+            const live = (await listChats()).find((x) => x.id === meta.id);
+            return { ...c, chatId: meta.id, busy: live?.busy ?? false, awaitingApproval: live?.awaitingApproval ?? false, updatedAt: meta.updatedAt };
+        };
+        let body = {};
+        if (method === "POST" || method === "PUT") {
+            try {
+                const raw = await readBody(req);
+                if (raw)
+                    body = JSON.parse(raw);
+            }
+            catch {
+                return json(res, { error: "invalid JSON body" }, 400);
+            }
+        }
+        try {
+            if (seg.length === 2 && method === "GET") {
+                const channels = await listChannels();
+                return json(res, { root: await channelsRoot(), channels: await Promise.all(channels.map(view)) });
+            }
+            if (seg.length === 2 && method === "POST") {
+                const { chatId: _c, slug: _s, ...input } = body;
+                return json(res, await view(await saveChannel(input)));
+            }
+            if (seg.length === 3 && seg[2] === "from-chat" && method === "POST") {
+                const { chatId, slug: _s, ...input } = body;
+                if (!chatId)
+                    return json(res, { error: "chatId is required" }, 400);
+                const channel = await saveChannel(input);
+                const converted = await convertChatToChannel(chatId, channel);
+                if (converted.error) {
+                    await deleteChannel(channel.slug).catch(() => { });
+                    return json(res, { error: converted.error }, 409);
+                }
+                return json(res, await view(channel));
+            }
+            if (seg.length === 3) {
+                const slug = decodeURIComponent(seg[2]);
+                const channel = await getChannel(slug);
+                if (!channel)
+                    return json(res, { error: "channel not found" }, 404);
+                if (method === "GET")
+                    return json(res, await view(channel));
+                if (method === "PUT") {
+                    const { chatId: _c, slug: _s, ...input } = body;
+                    const saved = await saveChannel({ ...input, slug });
+                    const meta = await ensureChannelChat(saved);
+                    await dropChannelSeats(meta.id, saved.members);
+                    return json(res, await view(saved));
+                }
+                if (method === "DELETE") {
+                    const meta = (await listChats()).find((c) => c.scope.kind === "channel" && c.scope.slug === slug);
+                    if (meta)
+                        await deleteChat(meta.id);
+                    await deleteChannel(slug);
+                    return json(res, { ok: true });
+                }
+            }
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+        return json(res, { error: "not found" }, 404);
+    }
     // GET /api/notifications — the bell: attention items, newest first, plus unread count.
     // POST /api/notifications/read {ids?: string[]} — mark some (or all) read.
     // DELETE /api/notifications — clear the list.
@@ -914,7 +985,8 @@ async function handleApi(req, res, url) {
                 const text = String(body.text ?? "").trim();
                 if (!text)
                     return json(res, { error: "text is required" }, 400);
-                result = await postMessage(seg[2], text);
+                // Channels: the poster's display name signs the message.
+                result = await postMessage(seg[2], text, { from: typeof body.from === "string" ? body.from : undefined });
             }
             else if (seg[3] === "permission") {
                 result = await resolvePermission(seg[2], String(body.requestId ?? ""), body.optionId == null ? null : String(body.optionId));