@netnodeag/kraftwerk 0.40.0 → 0.42.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
@@ -540,6 +583,31 @@ Prerequisites per harness:
   models reuse the Claude subscription OAuth, other vendors need their key in
   the env (check with `pi auth check --provider deepseek`).
 
+### Agent protocol
+
+Phases can also run over the [Agent Client Protocol](https://agentclientprotocol.com)
+— the same adapters the inspector's chats use (`claude-agent-acp`,
+`codex-acp`), bundled with kraftwerk, so nothing needs to be on the PATH.
+Set `protocol: acp` at the top of a workflow (every agent) or on one agent;
+`runs-on` still picks the harness (pi has no adapter). The adapter process
+stays alive for the whole run, so phases on one harness share a session
+like `--resume` does on the CLI. Persona and workspace context travel inside
+each phase prompt. On claude the agent's `tools`, CLI grants and MCP servers
+become the session's allowlist (settings sources off) and the session is
+switched to `acceptEdits`; codex runs in its workspace-write mode. A permission request the harness
+still raises is declined — nobody watches a workflow run, and kraftwerk
+never answers for a human. A programmatic `Run` ends its adapters with
+`disposeAcpSessions(runDir)` (the YAML runner does this itself).
+
+```yaml
+name: tagline
+protocol: acp          # all agents over ACP; per agent: protocol: cli | acp
+agents:
+  writer:
+    runs-on: claude    # or codex
+    model: sonnet
+```
+
 ## YAML workflows
 
 Linear workflows can be pure config, GitHub-Actions-flavored with `steps`,

package/dist/acp.d.ts

@@ -0,0 +1,43 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { ClientSideConnection, type Client, type McpServer } from "@agentclientprotocol/sdk";
+import type { McpServerConfig } from "./harness.js";
+/**
+ * Agent Client Protocol plumbing shared by the inspector's chats and the
+ * workflow ACP harness: the adapter packages (bundled with kraftwerk, so no
+ * CLI on the PATH is needed), model/effort tuning, and spawning one adapter
+ * as a subprocess speaking ACP over its stdio.
+ *
+ * Auth rides on the local CLI logins (Claude Code / Codex) via the
+ * inherited environment — same story as the CLI harnesses.
+ */
+export type AcpAgent = "claude" | "codex";
+/**
+ * Model/effort overrides ride on adapter-specific channels: the claude
+ * adapter takes the model via session `_meta.claudeCode.options` and the
+ * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
+ * the session config it hands to `codex app-server`.
+ */
+export declare function adapterEnv(agent: AcpAgent, tuning: {
+    model?: string;
+    effort?: string;
+}): NodeJS.ProcessEnv;
+/** Kraftwerk's MCP config (stdio or url) -> the protocol's session mcpServers entries. */
+export declare function acpMcpServers(servers?: Record<string, McpServerConfig>): McpServer[];
+export interface AcpProcess {
+    child: ChildProcessWithoutNullStreams;
+    conn: ClientSideConnection;
+}
+/**
+ * Spawn the adapter for `agent` in `cwd`, wire the ACP connection to
+ * `client`, and run the initialize handshake. Process failures reach the
+ * caller through the callbacks (a failed spawn is otherwise an unhandled
+ * 'error' event that takes the host process down).
+ */
+export declare function connectAcp(agent: AcpAgent, opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    client: Client;
+    clientName: string;
+    onError(err: Error): void;
+    onClose(code: number | null, stderr: string): void;
+}): Promise<AcpProcess>;

package/dist/acp.js

@@ -0,0 +1,76 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+const ADAPTERS = {
+    claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
+    codex: "@agentclientprotocol/codex-acp/dist/index.js",
+};
+/** Effort tier -> Claude thinking budget (the adapter reads MAX_THINKING_TOKENS). */
+const CLAUDE_THINKING_BUDGET = {
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+    xhigh: 32000,
+    max: 63999,
+};
+/**
+ * Model/effort overrides ride on adapter-specific channels: the claude
+ * adapter takes the model via session `_meta.claudeCode.options` and the
+ * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
+ * the session config it hands to `codex app-server`.
+ */
+export function adapterEnv(agent, tuning) {
+    const env = { ...process.env };
+    if (agent === "claude" && tuning.effort && CLAUDE_THINKING_BUDGET[tuning.effort]) {
+        env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[tuning.effort]);
+    }
+    if (agent === "codex" && (tuning.model || tuning.effort)) {
+        env.CODEX_CONFIG = JSON.stringify({
+            ...(tuning.model ? { model: tuning.model } : {}),
+            ...(tuning.effort ? { model_reasoning_effort: tuning.effort } : {}),
+        });
+    }
+    return env;
+}
+/** Kraftwerk's MCP config (stdio or url) -> the protocol's session mcpServers entries. */
+export function acpMcpServers(servers = {}) {
+    return Object.entries(servers).map(([name, cfg]) => "url" in cfg
+        ? { type: "http", name, url: cfg.url, headers: [] }
+        : {
+            name,
+            command: cfg.command,
+            args: cfg.args ?? [],
+            env: Object.entries(cfg.env ?? {}).map(([n, value]) => ({ name: n, value })),
+        });
+}
+/**
+ * Spawn the adapter for `agent` in `cwd`, wire the ACP connection to
+ * `client`, and run the initialize handshake. Process failures reach the
+ * caller through the callbacks (a failed spawn is otherwise an unhandled
+ * 'error' event that takes the host process down).
+ */
+export async function connectAcp(agent, opts) {
+    const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
+    const child = spawn(process.execPath, [entry], {
+        cwd: opts.cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+        env: opts.env,
+    });
+    let stderr = "";
+    child.stderr.on("data", (c) => {
+        stderr += c.toString("utf8");
+        if (stderr.length > 20_000)
+            stderr = stderr.slice(-20_000);
+    });
+    child.on("error", opts.onError);
+    child.on("close", (code) => opts.onClose(code, stderr.trim()));
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+    const conn = new ClientSideConnection(() => opts.client, stream);
+    await conn.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+        clientInfo: { name: opts.clientName, version: "1.0.0" },
+    });
+    return { child, conn };
+}

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessId, McpServerConfig } from "./harness.js";
+import type { AgentProtocol, HarnessId, McpServerConfig } from "./harness.js";
 /**
  * An agent is exactly four things:
  *
@@ -45,5 +45,7 @@ export interface AgentDefinition {
     mcp?: Record<string, McpServerConfig>;
     /** Which runtime executes this agent. Default: "claude". */
     harness?: HarnessId;
+    /** How that runtime is driven: headless CLI (default) or the Agent Client Protocol. */
+    protocol?: AgentProtocol;
 }
 export declare function defineAgent(agent: AgentDefinition): AgentDefinition;

package/dist/cli/doctor.js

@@ -137,11 +137,19 @@ export async function runDoctor(cwd) {
         }
     }
     // Harnesses: hard requirement only if a discovered workflow runs on them.
+    // Over the agent protocol the bundled adapters bring their own runtime.
     const needed = new Set();
+    let acp = false;
     for (const e of found) {
-        for (const a of e.workflow?.meta.agents ?? [])
-            needed.add(a.harness ?? "claude");
+        for (const a of e.workflow?.meta.agents ?? []) {
+            if (a.protocol === "acp")
+                acp = true;
+            else
+                needed.add(a.harness ?? "claude");
+        }
     }
+    if (acp)
+        report("ok", "agent protocol adapters", "claude-agent-acp + codex-acp bundled with kraftwerk");
     for (const harness of ["claude", "codex", "pi"]) {
         const version = cliVersion(harness);
         const isNeeded = needed.has(harness);

package/dist/cli/kraftwerk.js

@@ -62,7 +62,10 @@ const program = new Command()
     .version(pkg.version);
 const agentLabel = (workflow) => workflow.meta.agents
     .map((a) => {
-    const harness = a.harness && a.harness !== "claude" ? `${a.harness}:` : "";
+    const where = [a.harness && a.harness !== "claude" ? a.harness : "", a.protocol === "acp" ? "acp" : ""]
+        .filter(Boolean)
+        .join("/");
+    const harness = where ? `${where}:` : "";
     const effort = a.effort ? `, ${a.effort}` : "";
     return `${a.id} ${chalk.dim(`(${harness}${a.model}${effort})`)}`;
 })
@@ -88,6 +91,7 @@ program
                 id: a.id,
                 model: a.model,
                 harness: a.harness ?? "claude",
+                protocol: a.protocol ?? "cli",
             })),
             error: e.error,
         })), null, 2));
@@ -166,13 +170,15 @@ program
         })),
     });
     const workflow = entry.workflow;
+    // A workflow whose steps never read ${{ request }} runs without one.
     let request = (requestParts ?? []).join(" ").trim();
-    if (!request && machine)
-        fail(2, "No request given (--json is non-interactive).");
-    if (!request)
+    if (!request && workflow.meta.usesRequest) {
+        if (machine)
+            fail(2, "No request given (--json is non-interactive).");
         request = (await input({ message: "Request (topic, URL, ...):" })).trim();
-    if (!request)
-        fail(2, "No request given.");
+        if (!request)
+            fail(2, "No request given.");
+    }
     const missing = missingEnv(workflow.meta.requires);
     if (missing.length > 0) {
         fail(2, `Workflow "${workflow.name}" needs environment variables that are missing: ${missing.join(", ")}`);

package/dist/harness.d.ts

@@ -12,6 +12,12 @@
  * run directory (the workspace-context contract).
  */
 export type HarnessId = "claude" | "codex" | "pi";
+/**
+ * How the harness is driven: `cli` spawns the headless CLI per phase
+ * (claude -p, codex exec, pi); `acp` keeps one Agent Client Protocol
+ * adapter alive for the run (see harnesses/acp.ts). pi has no adapter.
+ */
+export type AgentProtocol = "cli" | "acp";
 /**
  * One MCP server an agent may use: either a local stdio server (spawned by
  * the harness, e.g. `node multiply-server.ts`) or a remote streamable-HTTP

package/dist/harnesses/acp.d.ts

@@ -0,0 +1,20 @@
+import type { AgentInvocation, Harness, HarnessId } from "../harness.js";
+/** Claude Agent SDK options for a phase session: the CLI harness's flags, as session meta. */
+export declare function claudeSessionOptions(inv: Pick<AgentInvocation, "model" | "tools" | "clis" | "mcpServers">): Record<string, unknown>;
+/**
+ * What a tool call touched, from its input (path, url, command) or its
+ * first location. Undefined when the adapter has not said yet — a title
+ * alone may be a placeholder.
+ */
+export declare function toolTarget(u: {
+    rawInput?: Record<string, unknown>;
+    locations?: Array<{
+        path?: string;
+    }>;
+}): string | undefined;
+/**
+ * Stop the adapter processes of one run (its run directory), or of every
+ * run in this process when no directory is given.
+ */
+export declare function disposeAcpSessions(cwd?: string): void;
+export declare function acpHarness(id: HarnessId): Harness;

package/dist/harnesses/acp.js

@@ -0,0 +1,195 @@
+import { RequestError, } from "@agentclientprotocol/sdk";
+import { acpMcpServers, adapterEnv, connectAcp } from "../acp.js";
+import { declineOption, unattendedMode } from "../inspector/chat/permissions.js";
+const live = new Map();
+// The run process is the adapters' only owner: never leave one behind.
+process.once("exit", () => disposeAcpSessions());
+/** Claude Agent SDK options for a phase session: the CLI harness's flags, as session meta. */
+export function claudeSessionOptions(inv) {
+    return {
+        model: inv.model,
+        // Keep the run hermetic: no user/project settings, hooks, or CLAUDE.md.
+        settingSources: [],
+        allowedTools: [
+            ...inv.tools,
+            ...(inv.clis ?? []).map((name) => `Bash(${name}:*)`),
+            ...Object.keys(inv.mcpServers ?? {}).map((name) => `mcp__${name}`),
+        ],
+    };
+}
+/**
+ * What a tool call touched, from its input (path, url, command) or its
+ * first location. Undefined when the adapter has not said yet — a title
+ * alone may be a placeholder.
+ */
+export function toolTarget(u) {
+    const input = u.rawInput ?? {};
+    const raw = input.file_path ?? input.url ?? input.path ?? input.command ?? u.locations?.[0]?.path;
+    if (raw == null)
+        return undefined;
+    const target = String(raw).replace(/\s+/g, " ").trim();
+    return target.length > 160 ? `${target.slice(0, 160)}…` : target;
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+async function open(agent, inv) {
+    let ended;
+    const closed = new Promise((r) => (ended = r));
+    const state = {
+        agent,
+        cwd: inv.cwd,
+        sessionId: "",
+        dead: false,
+        closed,
+        turn: null,
+        cost: 0,
+    };
+    const end = (why) => {
+        state.dead = true;
+        state.exit ??= why;
+        ended(state.exit);
+    };
+    const client = {
+        sessionUpdate(params) {
+            const u = params.update;
+            const turn = state.turn;
+            if (u.sessionUpdate === "agent_message_chunk" && u.content?.type === "text" && turn) {
+                turn.text += u.content.text ?? "";
+            }
+            else if (u.sessionUpdate === "tool_call" && turn) {
+                const kind = u.kind ?? "tool";
+                const target = toolTarget(u);
+                if (target)
+                    turn.onToolUse?.(kind, target);
+                else
+                    turn.pending.set(u.toolCallId ?? "", { kind, title: String(u.title ?? "") });
+            }
+            else if (u.sessionUpdate === "tool_call_update" && turn?.pending.has(u.toolCallId ?? "")) {
+                const target = toolTarget(u);
+                if (target) {
+                    turn.onToolUse?.(turn.pending.get(u.toolCallId ?? "").kind, target);
+                    turn.pending.delete(u.toolCallId ?? "");
+                }
+            }
+            else if (u.sessionUpdate === "usage_update" && typeof u.cost?.amount === "number") {
+                state.cost = u.cost.amount;
+            }
+        },
+        async requestPermission(params) {
+            // The harness judged this worth asking; a workflow run has nobody to ask.
+            const optionId = declineOption(params.options);
+            console.log(`  ⛔ ${params.toolCall.title ?? params.toolCall.toolCallId} — permission declined (unattended run)`);
+            return optionId ? { outcome: { outcome: "selected", optionId } } : { outcome: { outcome: "cancelled" } };
+        },
+    };
+    const { child, conn } = await connectAcp(agent, {
+        cwd: inv.cwd,
+        env: adapterEnv(agent, { model: inv.model, effort: inv.effort }),
+        client,
+        clientName: "kraftwerk",
+        onError: (err) => end(`could not start the ${agent} adapter: ${err.message}`),
+        onClose: (code, stderr) => end(`${agent} adapter exited (code ${code})${stderr ? `: ${stderr.slice(-500)}` : ""}`),
+    });
+    state.child = child;
+    state.conn = conn;
+    try {
+        const session = await conn.newSession({
+            cwd: inv.cwd,
+            mcpServers: acpMcpServers(inv.mcpServers),
+            ...(agent === "claude" ? { _meta: { claudeCode: { options: claudeSessionOptions(inv) } } } : {}),
+        });
+        state.sessionId = session.sessionId;
+        const modeId = unattendedMode(agent, session.modes?.currentModeId);
+        if (modeId) {
+            await conn.setSessionMode({ sessionId: session.sessionId, modeId }).catch((err) => {
+                console.log(`  ⚠ could not select the ${modeId} mode (${err.message}) — the ${agent} default applies`);
+            });
+        }
+    }
+    catch (err) {
+        // A refused session leaves the adapter running; it must not outlive the failure.
+        if (!state.dead)
+            child.kill("SIGTERM");
+        throw await failure(state, agent, err);
+    }
+    live.set(state.sessionId, state);
+    return state;
+}
+/**
+ * The error to surface for a failed request. When the adapter died, the
+ * SDK rejects on stdout EOF before the process 'close' event carries the
+ * stderr tail — give that a moment and prefer it, it names the real cause.
+ */
+async function failure(state, agent, err) {
+    const closing = /connection closed|closed/i.test(err.message ?? "");
+    if (state.dead || closing)
+        await Promise.race([state.closed, wait(1000)]);
+    if (state.exit)
+        return new Error(state.exit);
+    if (err instanceof RequestError)
+        return new Error(`${agent} (acp): ${err.message}`);
+    return err;
+}
+async function invoke(agent, inv) {
+    let s = inv.resume ? live.get(inv.resume) : undefined;
+    if (s?.dead) {
+        live.delete(s.sessionId);
+        s = undefined;
+    }
+    s ??= await open(agent, inv);
+    const turn = { text: "", onToolUse: inv.onToolUse, pending: new Map() };
+    s.turn = turn;
+    const prevCost = s.cost;
+    const started = Date.now();
+    // No per-prompt system prompt over ACP: carry persona + context in the prompt.
+    const prompt = `# Role and workspace context for this phase\n\n${inv.systemPrompt}\n\n` + `# Task\n\n${inv.prompt}`;
+    let res;
+    try {
+        res = await s.conn.prompt({ sessionId: s.sessionId, prompt: [{ type: "text", text: prompt }] });
+    }
+    catch (err) {
+        s.turn = null;
+        throw await failure(s, agent, err);
+    }
+    s.turn = null;
+    // Calls the adapter never named (no update carried a target) still count.
+    for (const p of turn.pending.values())
+        inv.onToolUse?.(p.kind, p.title);
+    if (res.stopReason !== "end_turn")
+        throw new Error(`${agent} (acp) stopped with ${res.stopReason}`);
+    if (inv.onText && turn.text.trim())
+        inv.onText(turn.text.trim());
+    const result = {
+        sessionId: s.sessionId,
+        text: turn.text,
+        durationMs: Date.now() - started,
+    };
+    if (res.usage) {
+        result.usage = {
+            inputTokens: res.usage.inputTokens,
+            outputTokens: res.usage.outputTokens,
+            cacheReadTokens: res.usage.cachedReadTokens ?? 0,
+            cacheCreationTokens: res.usage.cachedWriteTokens ?? 0,
+        };
+    }
+    if (s.cost > prevCost)
+        result.costUsd = s.cost - prevCost;
+    return result;
+}
+/**
+ * Stop the adapter processes of one run (its run directory), or of every
+ * run in this process when no directory is given.
+ */
+export function disposeAcpSessions(cwd) {
+    for (const [id, s] of live) {
+        if (cwd && s.cwd !== cwd)
+            continue;
+        if (!s.dead)
+            s.child.kill("SIGTERM");
+        live.delete(id);
+    }
+}
+export function acpHarness(id) {
+    if (id === "pi")
+        throw new Error('runs-on "pi" has no agent-protocol adapter — use claude or codex, or protocol: cli');
+    return { id, invoke: (inv) => invoke(id, inv) };
+}

package/dist/harnesses/registry.d.ts

@@ -1,2 +1,2 @@
-import type { Harness, HarnessId } from "../harness.js";
-export declare function harnessFor(id?: HarnessId): Harness;
+import type { AgentProtocol, Harness, HarnessId } from "../harness.js";
+export declare function harnessFor(id?: HarnessId, protocol?: AgentProtocol): Harness;

package/dist/harnesses/registry.js

@@ -1,16 +1,21 @@
+import { acpHarness } from "./acp.js";
 import { claudeHarness } from "./claude.js";
 import { codexHarness } from "./codex.js";
 import { piHarness } from "./pi.js";
 /**
- * Maps an agent's `harness` field to the adapter that runs it.
- * Default is claude — an agent without a harness runs on `claude -p`.
+ * Maps an agent's `harness` (+ `protocol`) to the adapter that runs it.
+ * Default is claude over the CLI — an agent without a harness runs on
+ * `claude -p`; `protocol: acp` drives the same harness over the Agent
+ * Client Protocol instead.
  */
 const HARNESSES = {
     claude: claudeHarness,
     codex: codexHarness,
     pi: piHarness,
 };
-export function harnessFor(id = "claude") {
+export function harnessFor(id = "claude", protocol = "cli") {
+    if (protocol === "acp")
+        return acpHarness(id);
     const harness = HARNESSES[id];
     if (!harness) {
         throw new Error(`harness "${id}" is not registered (available: ${Object.keys(HARNESSES).join(", ")})`);

package/dist/index.d.ts

@@ -10,6 +10,7 @@
 export { defineAgent, type AgentDefinition, type EffortLevel } from "./agent.js";
 export { type AgentInvocation, type AgentResult, type Harness, type HarnessId, type McpServerConfig, type TokenUsage, } from "./harness.js";
 export { harnessFor } from "./harnesses/registry.js";
+export { disposeAcpSessions } from "./harnesses/acp.js";
 export { Run, type RunOptions } from "./run.js";
 export { correctionPrompt, envelopeContract, parseEnvelope, type Envelope, } from "./envelope.js";
 export { containsText, fileNonEmpty, slotsFilled, type Gate } from "./gates.js";

package/dist/index.js

@@ -9,6 +9,7 @@
  */
 export { defineAgent } from "./agent.js";
 export { harnessFor } from "./harnesses/registry.js";
+export { disposeAcpSessions } from "./harnesses/acp.js";
 export { Run } from "./run.js";
 export { correctionPrompt, envelopeContract, parseEnvelope, } from "./envelope.js";
 export { containsText, fileNonEmpty, slotsFilled } from "./gates.js";

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[];