channels.tools 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# channels.tools
+
+Channels for the [pi](https://pi.dev) coding agent. Connect **channel
+servers** — small processes that push events from the outside world into a
+live session — and the session becomes reachable: a push **wakes it when
+idle** and **queues, coalesced, when it's mid-turn**. Each server's tools are
+registered so the agent can act on what arrived.
+
+Mail buses, code-review watchers, CI, file watchers, webhooks — anything that
+can speak the (simple) protocol below can drive an agent session.
+
+Site: [channels.tools](https://channels.tools)
+
+## Install
+
+```bash
+pi install npm:channels.tools
+```
+
+## Configure
+
+`~/.pi/agent/channels.json` (global) or `<project>/.pi/channels.json`
+(project wins on name collision). Nothing connects until one of these files
+exists:
+
+```json
+{ "channelServers": {
+    "file":  { "command": "node", "args": ["examples/file-channel.js", "inbox.txt"] },
+    "my-bus": { "command": "mybus", "args": ["channel"], "env": {}, "cwd": "." }
+} }
+```
+
+Real-world servers: [muster](https://muster.tools) (`muster channel`, a
+multi-agent mail bus) and galley (`galley channel`, document review) both
+speak this protocol.
+
+## Behavior
+
+- An event arriving while the session is idle starts a turn immediately
+  (delivered as a steer with the server's event payload).
+- Events arriving mid-turn are buffered and delivered coalesced once the turn
+  settles (pi's `agent_settled`, not `agent_end`) — a running turn is never
+  interrupted.
+- Each server's tools are registered under their own names, so instructions a
+  server hands the agent stay literally true.
+- `AGENT_SESSION_ID` is exported before any server spawns; servers can read
+  it at startup to scope themselves to this session.
+- A server that crashes is retried with backoff; its tools re-register on
+  reconnect. A misbehaving or non-conforming process is killed and logged.
+
+## The protocol (`claude/channel` convention)
+
+A channel server is a subprocess speaking **newline-delimited JSON-RPC 2.0
+over stdio** (no `Content-Length` framing). Originating as an experimental
+Claude Code convention, hence the capability name.
+
+1. **Handshake** — client sends `initialize`; the server's result must
+   declare `capabilities.experimental["claude/channel"]` and may include an
+   `instructions` string (injected as guidance) and `tools` (see below).
+   Servers not declaring the capability are rejected.
+2. **Events** — the server pushes `notifications/claude/channel` with a
+   `params` payload: freeform text plus optional `meta` attributes
+   (`count`, `thread_id`, `from`, …). Multiple notifications may be
+   coalesced by the client; servers that pre-coalesce should say how many
+   events one push represents in `meta.count`.
+3. **Tools** — servers may expose tools (name, description, JSON-schema
+   input). The client registers them with pi and proxies invocations via
+   `tools/call`.
+4. **Shutdown** — SIGTERM on session end (SIGKILL after a grace period).
+
+The reference server in [`examples/file-channel.js`](examples/file-channel.js)
+implements the whole convention in ~60 dependency-free lines: append a line
+to a watched file and an idle pi session wakes with it.
+
+```bash
+node examples/file-channel.js --demo   # prints the wire exchange, no pi needed
+```
+
+## Test
+
+```bash
+npm test                        # unit, no binaries needed
+node --test test/live.test.ts   # integration; skips servers not installed
+```

package/examples/file-channel.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Reference channel server for the claude/channel convention.
+//
+// Watches a file; every line appended to it is pushed into the connected pi
+// session as a channel event. Declares one tool (file_channel_status) so the
+// tool-proxy path is exercised too.
+//
+//   node file-channel.js <path>     run as a channel server (pi spawns this)
+//   node file-channel.js --demo     print the wire exchange, no pi needed
+//
+// Wire format: newline-delimited JSON-RPC 2.0 over stdio.
+
+import { openSync, readSync, fstatSync, watchFile, closeSync } from "node:fs";
+
+const NOTIFICATION = "notifications/claude/channel";
+const CAPABILITY = "claude/channel";
+
+const arg = process.argv[2];
+if (!arg || arg === "--help") {
+  console.error("usage: file-channel.js <path-to-watch> | --demo");
+  process.exit(2);
+}
+
+if (arg === "--demo") {
+  const show = (dir, msg) => console.log(`${dir} ${JSON.stringify(msg)}`);
+  show("<-", { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "channels.tools", version: "0.1.0" } } });
+  show("->", { jsonrpc: "2.0", id: 1, result: { capabilities: { experimental: { [CAPABILITY]: {} } }, instructions: "Lines appended to the watched file arrive as channel events." } });
+  show("<-", { jsonrpc: "2.0", method: "notifications/initialized" });
+  show("<-", { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+  show("->", { jsonrpc: "2.0", id: 2, result: { tools: [{ name: "file_channel_status", description: "Report the watched path and lines delivered.", inputSchema: { type: "object", properties: {} } }] } });
+  show("->", { jsonrpc: "2.0", method: NOTIFICATION, params: { content: "new line appended: hello", meta: { count: 1, source_path: "inbox.txt" } } });
+  process.exit(0);
+}
+
+const watchedPath = arg;
+let delivered = 0;
+let offset = 0;
+
+function send(msg) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`);
+}
+
+function drainNewLines() {
+  let fd;
+  try {
+    fd = openSync(watchedPath, "r");
+  } catch {
+    return; // file may not exist yet; watchFile fires again when it does
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size < offset) offset = 0; // truncated: start over
+    if (size === offset) return;
+    const buf = Buffer.alloc(size - offset);
+    readSync(fd, buf, 0, buf.length, offset);
+    offset = size;
+    const lines = buf.toString("utf-8").split("\n").filter((l) => l.trim() !== "");
+    if (lines.length === 0) return;
+    delivered += lines.length;
+    send({
+      method: NOTIFICATION,
+      params: {
+        content: lines.join("\n"),
+        meta: { count: lines.length, source_path: watchedPath },
+      },
+    });
+  } finally {
+    closeSync(fd);
+  }
+}
+
+let buffered = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+  buffered += chunk;
+  let nl;
+  while ((nl = buffered.indexOf("\n")) >= 0) {
+    const line = buffered.slice(0, nl);
+    buffered = buffered.slice(nl + 1);
+    if (line.trim() === "") continue;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    handle(msg);
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+
+function handle(msg) {
+  if (msg.method === "initialize") {
+    send({
+      id: msg.id,
+      result: {
+        protocolVersion: "2025-06-18",
+        capabilities: { experimental: { [CAPABILITY]: {} } },
+        serverInfo: { name: "file-channel", version: "0.1.0" },
+        instructions:
+          `Lines appended to ${watchedPath} arrive as channel events. ` +
+          "Call file_channel_status to see what has been delivered.",
+      },
+    });
+    // Start from the file's current end: only NEW lines become events.
+    try {
+      const fd = openSync(watchedPath, "r");
+      offset = fstatSync(fd).size;
+      closeSync(fd);
+    } catch {
+      offset = 0;
+    }
+    watchFile(watchedPath, { interval: 500 }, drainNewLines);
+    return;
+  }
+  if (msg.method === "tools/list") {
+    send({
+      id: msg.id,
+      result: {
+        tools: [
+          {
+            name: "file_channel_status",
+            description: "Report the watched path and how many lines have been delivered.",
+            inputSchema: { type: "object", properties: {} },
+          },
+        ],
+      },
+    });
+    return;
+  }
+  if (msg.method === "tools/call") {
+    const name = msg.params?.name;
+    if (name === "file_channel_status") {
+      send({
+        id: msg.id,
+        result: {
+          content: [{ type: "text", text: `watching ${watchedPath}; ${delivered} line(s) delivered` }],
+        },
+      });
+    } else {
+      send({ id: msg.id, error: { code: -32601, message: `unknown tool: ${name}` } });
+    }
+    return;
+  }
+  if (msg.id !== undefined) {
+    // Unknown request: answer rather than dangle the client's promise.
+    send({ id: msg.id, error: { code: -32601, message: `unknown method: ${msg.method}` } });
+  }
+}
+
+process.on("SIGTERM", () => process.exit(0));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "channels.tools",
+  "version": "0.1.0",
+  "description": "Channels for the pi coding agent: connect channel servers that push events into a live session — wake it when idle, queue when busy — and proxy their tools. A client for the claude/channel convention.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://channels.tools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schuettc/pi-extensions.git",
+    "directory": "packages/channels.tools"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "channels",
+    "claude-channel",
+    "agent-wake",
+    "event-driven"
+  ],
+  "files": [
+    "src",
+    "examples",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --experimental-strip-types --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.6.0"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,136 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { PassThrough } from "node:stream";
+import { JsonRpcClient } from "./client.ts";
+
+function pair() {
+  const stdin = new PassThrough();   // what the client writes
+  const stdout = new PassThrough();  // what the client reads
+  const client = new JsonRpcClient({ stdin, stdout });
+  return { client, stdin, stdout };
+}
+
+function nextLine(stream: PassThrough): Promise<Record<string, unknown>> {
+  return new Promise((resolve) => {
+    let buf = "";
+    stream.on("data", (chunk: Buffer) => {
+      buf += chunk.toString("utf-8");
+      const nl = buf.indexOf("\n");
+      if (nl >= 0) resolve(JSON.parse(buf.slice(0, nl)));
+    });
+  });
+}
+
+test("request writes a framed JSON-RPC call and resolves on the matching id", async () => {
+  const { client, stdin, stdout } = pair();
+  const pending = client.request("initialize", { protocolVersion: "2025-06-18" });
+  const sent = await nextLine(stdin);
+  assert.equal(sent.jsonrpc, "2.0");
+  assert.equal(sent.method, "initialize");
+  assert.deepEqual(sent.params, { protocolVersion: "2025-06-18" });
+  stdout.write(JSON.stringify({ jsonrpc: "2.0", id: sent.id, result: { ok: true } }) + "\n");
+  assert.deepEqual(await pending, { ok: true });
+});
+
+test("a JSON-RPC error response rejects", async () => {
+  const { client, stdin, stdout } = pair();
+  const pending = client.request("tools/call");
+  const sent = await nextLine(stdin);
+  stdout.write(JSON.stringify({ jsonrpc: "2.0", id: sent.id, error: { code: -32601, message: "no such tool" } }) + "\n");
+  await assert.rejects(pending, /no such tool/);
+});
+
+test("notifications reach the handler and carry method and params", async () => {
+  const { client, stdout } = pair();
+  const seen: Array<{ method: string; params: unknown }> = [];
+  client.onNotification((method, params) => seen.push({ method, params }));
+  stdout.write(JSON.stringify({
+    jsonrpc: "2.0",
+    method: "notifications/claude/channel",
+    params: { content: "hello", meta: { intent: "fyi" } },
+  }) + "\n");
+  await new Promise((r) => setImmediate(r));
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0].method, "notifications/claude/channel");
+  assert.deepEqual(seen[0].params, { content: "hello", meta: { intent: "fyi" } });
+});
+
+test("a message split across chunk boundaries is reassembled", async () => {
+  const { client, stdout } = pair();
+  const seen: string[] = [];
+  client.onNotification((method) => seen.push(method));
+  stdout.write('{"jsonrpc":"2.0","meth');
+  stdout.write('od":"notifications/x"}\n');
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(seen, ["notifications/x"]);
+});
+
+test("two messages in one chunk are both delivered", async () => {
+  const { client, stdout } = pair();
+  const seen: string[] = [];
+  client.onNotification((method) => seen.push(method));
+  stdout.write('{"jsonrpc":"2.0","method":"a"}\n{"jsonrpc":"2.0","method":"b"}\n');
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(seen, ["a", "b"]);
+});
+
+test("an unparseable line is skipped without killing the stream", async () => {
+  const { client, stdout } = pair();
+  const seen: string[] = [];
+  client.onNotification((method) => seen.push(method));
+  stdout.write('not json\n{"jsonrpc":"2.0","method":"after"}\n');
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(seen, ["after"]);
+});
+
+test("close rejects every in-flight request", async () => {
+  const { client, stdin } = pair();
+  const pending = client.request("initialize");
+  await nextLine(stdin);
+  client.close();
+  await assert.rejects(pending, /closed/);
+});
+
+test("a notification carrying \"id\": null is dispatched, not dropped (F8)", async () => {
+  const { client, stdout } = pair();
+  const seen: Array<{ method: string; params: unknown }> = [];
+  client.onNotification((method, params) => seen.push({ method, params }));
+  stdout.write(JSON.stringify({
+    jsonrpc: "1.0",
+    id: null,
+    method: "notifications/claude/channel",
+    params: { content: "mail", meta: {} },
+  }) + "\n");
+  await new Promise((r) => setImmediate(r));
+  assert.equal(seen.length, 1, "an id:null notification must not be silently dropped");
+  assert.equal(seen[0].method, "notifications/claude/channel");
+});
+
+// Race the pending request against a short timer rather than awaiting it
+// directly: pre-fix, an aborted signal is never honored and the request
+// never settles, so a direct assert.rejects() would hang instead of failing.
+async function raceAbort(pending: Promise<unknown>): Promise<"resolved" | "rejected" | "pending"> {
+  return Promise.race([
+    pending.then(() => "resolved" as const, () => "rejected" as const),
+    new Promise<"pending">((r) => setTimeout(() => r("pending"), 300)),
+  ]);
+}
+
+test("aborting the signal after send rejects the pending request and stops the timer (F6)", async () => {
+  const { client, stdin } = pair();
+  const controller = new AbortController();
+  const pending = client.request("tools/call", { name: "x" }, 30_000, controller.signal);
+  await nextLine(stdin);
+  controller.abort();
+  assert.equal(await raceAbort(pending), "rejected");
+  await assert.rejects(pending, /aborted/);
+});
+
+test("an already-aborted signal rejects immediately without sending (F6)", async () => {
+  const { client } = pair();
+  const controller = new AbortController();
+  controller.abort();
+  const pending = client.request("tools/call", {}, 30_000, controller.signal);
+  assert.equal(await raceAbort(pending), "rejected");
+  await assert.rejects(pending, /aborted/);
+});

package/src/client.ts

@@ -0,0 +1,124 @@
+import type { Readable, Writable } from "node:stream";
+
+type NotificationHandler = (method: string, params: unknown) => void;
+type Pending = {
+  resolve: (v: unknown) => void;
+  reject: (e: Error) => void;
+  timer?: NodeJS.Timeout;
+  // Removes the abort listener registered for this request, if any. Called
+  // on every settlement path (response, timeout, close) so an aborted-later
+  // signal never fires into a request that already finished.
+  cleanup?: () => void;
+};
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class JsonRpcClient {
+  private streams: { stdin: Writable; stdout: Readable };
+  private nextId = 1;
+  private pending = new Map<number, Pending>();
+  private handlers: NotificationHandler[] = [];
+  private buffer = "";
+  private closed = false;
+
+  constructor(streams: { stdin: Writable; stdout: Readable }) {
+    this.streams = streams;
+    this.streams.stdout.on("data", (chunk: Buffer) => this.onData(chunk));
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer += chunk.toString("utf-8");
+    let nl = this.buffer.indexOf("\n");
+    while (nl >= 0) {
+      const line = this.buffer.slice(0, nl).trim();
+      this.buffer = this.buffer.slice(nl + 1);
+      if (line !== "") this.dispatch(line);
+      nl = this.buffer.indexOf("\n");
+    }
+  }
+
+  private dispatch(line: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      // A server that writes a stray line must not take the channel down.
+      return;
+    }
+    // A JSON-RPC 1.0-flavored notification carries "id": null rather than
+    // omitting id entirely. Requiring strict `undefined` here silently drops
+    // that shape — a notification is mail, so this is the silent-mail-loss
+    // failure class.
+    if (typeof msg.method === "string" && (msg.id === undefined || msg.id === null)) {
+      for (const h of this.handlers) h(msg.method, msg.params);
+      return;
+    }
+    if (typeof msg.id !== "number") return;
+    const entry = this.pending.get(msg.id);
+    if (!entry) return;
+    this.pending.delete(msg.id);
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.cleanup?.();
+    const err = msg.error as { message?: string } | undefined;
+    if (err) entry.reject(new Error(err.message ?? "JSON-RPC error"));
+    else entry.resolve(msg.result);
+  }
+
+  // `signal` threads pi's own abort signal (from `execute(id, params, signal,
+  // …)`) through to the pending request so an aborted turn rejects the call
+  // immediately instead of waiting out the full timeout with nothing to show
+  // for it.
+  request(method: string, params?: unknown, timeoutMs = DEFAULT_TIMEOUT_MS, signal?: AbortSignal): Promise<unknown> {
+    if (this.closed) return Promise.reject(new Error("channel client is closed"));
+    if (signal?.aborted) return Promise.reject(new Error(`aborted before send: ${method}`));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const entry = this.pending.get(id);
+        this.pending.delete(id);
+        entry?.cleanup?.();
+        reject(new Error(`timed out after ${timeoutMs}ms: ${method}`));
+      }, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+
+      let cleanup: (() => void) | undefined;
+      if (signal) {
+        const onAbort = () => {
+          if (!this.pending.has(id)) return;
+          this.pending.delete(id);
+          clearTimeout(timer);
+          reject(new Error(`aborted: ${method}`));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        cleanup = () => signal.removeEventListener("abort", onAbort);
+      }
+
+      this.pending.set(id, { resolve, reject, timer, ...(cleanup ? { cleanup } : {}) });
+      this.write({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) });
+    });
+  }
+
+  notify(method: string, params?: unknown): void {
+    if (this.closed) return;
+    this.write({ jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) });
+  }
+
+  onNotification(handler: NotificationHandler): void {
+    this.handlers.push(handler);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const [, entry] of this.pending) {
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.cleanup?.();
+      entry.reject(new Error("channel client is closed"));
+    }
+    this.pending.clear();
+  }
+
+  private write(msg: unknown): void {
+    this.streams.stdin.write(JSON.stringify(msg) + "\n");
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,72 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadChannelConfig } from "./config.ts";
+
+function scratch(): string {
+  return mkdtempSync(join(tmpdir(), "pi-channels-config-"));
+}
+
+test("returns empty when no config files exist", () => {
+  const home = scratch();
+  const cwd = scratch();
+  assert.deepEqual(loadChannelConfig({ home, cwd }), {});
+});
+
+test("reads the global config", () => {
+  const home = scratch();
+  const cwd = scratch();
+  mkdirSync(join(home, ".pi", "agent"), { recursive: true });
+  writeFileSync(
+    join(home, ".pi", "agent", "channels.json"),
+    JSON.stringify({ channelServers: { "muster-channel": { command: "muster", args: ["channel"] } } }),
+  );
+  assert.deepEqual(loadChannelConfig({ home, cwd }), {
+    "muster-channel": { command: "muster", args: ["channel"] },
+  });
+});
+
+test("project config overrides global by name and adds new names", () => {
+  const home = scratch();
+  const cwd = scratch();
+  mkdirSync(join(home, ".pi", "agent"), { recursive: true });
+  writeFileSync(
+    join(home, ".pi", "agent", "channels.json"),
+    JSON.stringify({ channelServers: { galley: { command: "galley", args: ["channel"] } } }),
+  );
+  mkdirSync(join(cwd, ".pi"), { recursive: true });
+  writeFileSync(
+    join(cwd, ".pi", "channels.json"),
+    JSON.stringify({
+      channelServers: {
+        galley: { command: "galley", args: ["channel", "--scope", "."] },
+        "muster-channel": { command: "muster", args: ["channel"] },
+      },
+    }),
+  );
+  assert.deepEqual(loadChannelConfig({ home, cwd }), {
+    galley: { command: "galley", args: ["channel", "--scope", "."] },
+    "muster-channel": { command: "muster", args: ["channel"] },
+  });
+});
+
+test("malformed JSON is skipped, not thrown", () => {
+  const home = scratch();
+  const cwd = scratch();
+  mkdirSync(join(home, ".pi", "agent"), { recursive: true });
+  writeFileSync(join(home, ".pi", "agent", "channels.json"), "{ not json");
+  assert.deepEqual(loadChannelConfig({ home, cwd }), {});
+});
+
+test("entries without a command string are rejected", () => {
+  const home = scratch();
+  const cwd = scratch();
+  mkdirSync(join(home, ".pi", "agent"), { recursive: true });
+  writeFileSync(
+    join(home, ".pi", "agent", "channels.json"),
+    JSON.stringify({ channelServers: { broken: { args: ["x"] }, ok: { command: "muster" } } }),
+  );
+  assert.deepEqual(loadChannelConfig({ home, cwd }), { ok: { command: "muster" } });
+});

package/src/config.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type ChannelServerDef = {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+};
+
+function readServers(path: string): Record<string, ChannelServerDef> {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return {};
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // A malformed file must not take the session down; the connection
+    // layer surfaces "no channels configured" instead.
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null) return {};
+  const servers = (parsed as { channelServers?: unknown }).channelServers;
+  if (typeof servers !== "object" || servers === null) return {};
+
+  const out: Record<string, ChannelServerDef> = {};
+  for (const [name, value] of Object.entries(servers as Record<string, unknown>)) {
+    if (typeof value !== "object" || value === null) continue;
+    const def = value as Partial<ChannelServerDef>;
+    if (typeof def.command !== "string" || def.command === "") continue;
+    out[name] = { command: def.command, ...(def.args ? { args: def.args } : {}),
+      ...(def.env ? { env: def.env } : {}), ...(def.cwd ? { cwd: def.cwd } : {}) };
+  }
+  return out;
+}
+
+export function loadChannelConfig(opts: { home: string; cwd: string }): Record<string, ChannelServerDef> {
+  const global = readServers(join(opts.home, ".pi", "agent", "channels.json"));
+  const project = readServers(join(opts.cwd, ".pi", "channels.json"));
+  return { ...global, ...project };
+}