channels.tools 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,15 @@
 # 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
+servers** — small local processes that push events into a live session — and
+the session becomes reachable by your other tools: 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.
+Mail buses, code-review servers, CI and file watchers — anything on your
+machine that can speak the (simple) protocol below can drive an agent
+session. Servers are subprocesses the session itself spawns from your config;
+nothing listens on a network.
 
 Site: [channels.tools](https://channels.tools)
 
@@ -51,8 +53,8 @@ speak this protocol.
 ## 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.
+over stdio** (no `Content-Length` framing). `claude/channel` is the
+convention's wire name.
 
 1. **Handshake** — client sends `initialize`; the server's result must
    declare `capabilities.experimental["claude/channel"]` and may include an
@@ -69,11 +71,13 @@ Claude Code convention, hence the capability name.
 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.
+implements the whole convention dependency-free (the server itself is ~60
+lines; the rest of the file is the demo): 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
+node examples/file-channel.js --demo          # narrated walkthrough, no pi needed
+node examples/file-channel.js --demo --wire   # the same exchange as raw wire frames
 ```
 
 ## Test

package/examples/file-channel.js

@@ -5,12 +5,14 @@
 // 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
+//   node file-channel.js <path>            run as a channel server (pi spawns this)
+//   node file-channel.js --demo            narrated walkthrough, no pi needed
+//   node file-channel.js --demo --wire     the same exchange as raw wire frames
 //
 // Wire format: newline-delimited JSON-RPC 2.0 over stdio.
 
 import { openSync, readSync, fstatSync, watchFile, closeSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
 
 const NOTIFICATION = "notifications/claude/channel";
 const CAPABILITY = "claude/channel";
@@ -22,13 +24,69 @@ if (!arg || arg === "--help") {
 }
 
 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" } } });
+  // One scripted exchange, printable two ways: --wire shows the literal
+  // ndjson frames; the default narrates the same frames as a story.
+  const frames = {
+    init: { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "channels.tools", version: "0.1.0" } } },
+    initResult: { jsonrpc: "2.0", id: 1, result: { capabilities: { experimental: { [CAPABILITY]: {} } }, instructions: "Lines appended to the watched file arrive as channel events." } },
+    initialized: { jsonrpc: "2.0", method: "notifications/initialized" },
+    toolsList: { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} },
+    toolsResult: { jsonrpc: "2.0", id: 2, result: { tools: [{ name: "file_channel_status", description: "Report the watched path and lines delivered.", inputSchema: { type: "object", properties: {} } }] } },
+    event1: { jsonrpc: "2.0", method: NOTIFICATION, params: { content: "deploy finished: api v2.4.1 is live", meta: { count: 1, source_path: "inbox.txt" } } },
+    event3: { jsonrpc: "2.0", method: NOTIFICATION, params: { content: "tests passed: 214/214\nreview approved: PR #87\nnew issue filed: login flake", meta: { count: 3, source_path: "inbox.txt" } } },
+  };
+
+  if (process.argv.includes("--wire")) {
+    for (const [name, frame] of Object.entries(frames)) {
+      const dir = frame.method === NOTIFICATION || frame.result ? "->" : "<-";
+      console.log(`${dir} ${JSON.stringify(frame)}`);
+      void name;
+    }
+    process.exit(0);
+  }
+
+  const tty = process.stdout.isTTY;
+  const paint = (code, s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
+  const dim = (s) => paint(2, s);
+  const cyan = (s) => paint(36, s);
+  const bold = (s) => paint(1, s);
+  const green = (s) => paint(32, s);
+  const rule = (title) => console.log(`\n${dim("──")} ${bold(title)} ${dim("─".repeat(Math.max(2, 56 - title.length)))}`);
+  const say = (s) => console.log(s);
+  const pause = () => (tty ? sleep(650) : Promise.resolve());
+
+  say(`${bold("file-channel")} ${dim("·")} a channel server: one file in, channel events out`);
+  say(dim("the same exchange as raw wire frames: --demo --wire"));
+
+  rule("1 · handshake — the session spawns this server");
+  await pause();
+  say(`  ${cyan("→")} initialize`);
+  say(`  ${cyan("←")} capabilities.experimental[${green('"claude/channel"')}] ${green("✓")}`);
+  say(`    ${dim("instructions:")} "Lines appended to the watched file arrive as channel events."`);
+  await pause();
+  say(`  ${cyan("→")} tools/list`);
+  say(`  ${cyan("←")} 1 tool: ${bold("file_channel_status")} ${dim("— registered with the agent, callable by name")}`);
+
+  rule("2 · something happens on your machine");
+  await pause();
+  say(`  ${dim("$")} echo ${green('"deploy finished: api v2.4.1 is live"')} >> inbox.txt`);
+  await pause();
+  say(`  ${cyan("←")} notifications/claude/channel  ${dim("(count 1, source inbox.txt)")}`);
+  say(`    ${bold("deploy finished: api v2.4.1 is live")}`);
+  say(`    ${dim("the session is idle — this push wakes it and starts a turn")}`);
+
+  rule("3 · three more land while the agent is busy");
+  await pause();
+  say(`  ${dim("$")} echo ... >> inbox.txt   ${dim("×3, mid-turn")}`);
+  await pause();
+  say(`  ${cyan("←")} notifications/claude/channel  ${dim("(count 3 — one push, coalesced)")}`);
+  for (const line of frames.event3.params.content.split("\n")) say(`    ${bold(line)}`);
+  say(`    ${dim("buffered while the turn ran; delivered together when it settled")}`);
+
+  rule("try it live");
+  say(`  add to ${cyan("~/.pi/agent/channels.json")}:`);
+  say(`    { "channelServers": { "file": { "command": "node", "args": ["${dim("/path/to/")}file-channel.js", "inbox.txt"] } } }`);
+  say(`  then, with the session idle:  ${dim("$")} echo hi >> inbox.txt   ${dim("— and watch it wake")}\n`);
   process.exit(0);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "channels.tools",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",

package/src/envelope.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { splitGuidance, renderBatch, strictestIntent } from "./envelope.ts";
+import { splitGuidance, renderBatch, renderSummary, strictestIntent } from "./envelope.ts";
 
 test("splitGuidance separates on the first --- sentinel", () => {
   const r = splitGuidance("line one\n\n---\nGUIDANCE HERE");
@@ -130,3 +130,29 @@ test("events without a server count fall back to counting notifications", () =>
   ]);
   assert.match(out, /count="2"/);
 });
+
+test("renderSummary takes each event's first body line and drops the guidance", () => {
+  const out = renderSummary("muster-channel", [
+    { source: "muster-channel", content: 'muster: reply on thread #1 "x"\n\n---\ncall get_thread 1', meta: {} },
+    { source: "muster-channel", content: 'muster: fyi on thread #2 "y"\n\n---\nread only', meta: {} },
+  ]);
+  assert.equal(out, 'muster: reply on thread #1 "x"\nmuster: fyi on thread #2 "y"');
+});
+
+test("renderSummary dedupes identical lines and caps at five with a remainder", () => {
+  const events = Array.from({ length: 8 }, (_, i) => ({
+    source: "s",
+    content: `line ${i}`,
+    meta: {},
+  }));
+  events.push({ source: "s", content: "line 0", meta: {} });
+  const out = renderSummary("s", events);
+  const lines = out.split("\n");
+  assert.equal(lines.length, 6);
+  assert.equal(lines[5], "…and 3 more");
+});
+
+test("renderSummary falls back to naming the source when no event has a body", () => {
+  const out = renderSummary("galley", [{ source: "galley", content: "\n\n---\nguidance only", meta: {} }]);
+  assert.equal(out, "[galley] new channel activity");
+});

package/src/envelope.ts

@@ -43,6 +43,25 @@ function escapeAttr(value: string): string {
     .replace(/"/g, """);
 }
 
+// renderSummary is the VISIBLE half of a delivery: one short line per event
+// (the first body line, which channel servers author as their own compact
+// summary), deduplicated, capped at five. It is what the operator reads in
+// the transcript, and what the model acts on in the rare race where the
+// envelope's nextTurn queue drains only at a later prompt — so it must be
+// able to stand alone, not just decorate.
+export function renderSummary(source: string, events: ChannelEvent[]): string {
+  const lines: string[] = [];
+  for (const event of events) {
+    const { body } = splitGuidance(event.content);
+    const first = body.split("\n").find((line) => line.trim() !== "");
+    if (first !== undefined && !lines.includes(first)) lines.push(first);
+  }
+  if (lines.length === 0) return `[${source}] new channel activity`;
+  const shown = lines.slice(0, 5);
+  if (lines.length > shown.length) shown.push(`…and ${lines.length - shown.length} more`);
+  return shown.join("\n");
+}
+
 export function renderBatch(source: string, events: ChannelEvent[]): string {
   const bodies: string[] = [];
   const guidance: string[] = [];

package/src/index.test.ts

@@ -15,6 +15,7 @@ type ToolDef = { name: string; execute(id: string, params: unknown): Promise<unk
 function fakePi() {
   const handlers = new Map<string, Handler[]>();
   const sent: Array<{ msg: unknown; opts: unknown }> = [];
+  const customs: Array<{ msg: unknown; opts: unknown }> = [];
   const registered: string[] = [];
   const unregistered: string[] = [];
   const tools = new Map<string, ToolDef>();
@@ -26,6 +27,7 @@ function fakePi() {
       handlers.set(event, list);
     },
     sendUserMessage(content: unknown, opts: unknown) { sent.push({ msg: content, opts }); },
+    sendMessage(message: unknown, opts: unknown) { customs.push({ msg: message, opts }); },
     registerTool(def: ToolDef) { registered.push(def.name); tools.set(def.name, def); },
     unregisterTool(name: string) { unregistered.push(name); tools.delete(name); },
     getAllTools() { return [{ name: "bash" }, { name: "read" }]; },
@@ -43,7 +45,7 @@ function fakePi() {
     for (const h of handlers.get(event) ?? []) out.push(await h(payload, ctx));
     return out;
   }
-  return { pi, ctx, fire, sent, registered, unregistered, tools, statuses };
+  return { pi, ctx, fire, sent, customs, registered, unregistered, tools, statuses };
 }
 
 test("session_start sets AGENT_SESSION_ID before any server is spawned", async () => {
@@ -63,19 +65,29 @@ test("session_start sets AGENT_SESSION_ID before any server is spawned", async (
   await fire("session_shutdown");
 });
 
-test("an inbound event while idle is delivered as a user message through the full prompt pipeline", async () => {
-  const { pi, fire, sent } = fakePi();
+test("an inbound event delivers a hidden envelope plus a visible summary line", async () => {
+  const { pi, fire, sent, customs } = fakePi();
   createExtension(pi as never, {
     env: {},
     loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE], env: { FAKE_PUSH_AFTER_MS: "50" } } }),
   });
   await fire("session_start", { reason: "startup" });
   await new Promise((r) => setTimeout(r, 500));
+  // The envelope rides a hidden custom message queued for the next turn —
+  // pi injects the nextTurn queue before before_agent_start fires.
+  assert.equal(customs.length, 1);
+  const custom = customs[0].msg as { customType: string; content: string; display: boolean };
+  assert.equal(custom.customType, "channel-envelope");
+  assert.equal(custom.display, false);
+  assert.match(custom.content, /<channel source="fake"/);
+  assert.equal((customs[0].opts as { deliverAs?: string }).deliverAs, "nextTurn");
+  // The visible user message is the short summary — no raw XML — and it is
+  // what triggers the turn through the full prompt pipeline.
   assert.equal(sent.length, 1);
   const opts = sent[0].opts as { deliverAs?: string };
   assert.equal(opts.deliverAs, "steer");
   const text = sent[0].msg as string;
-  assert.match(text, /<channel source="fake"/);
+  assert.doesNotMatch(text, /<channel/);
   await fire("session_shutdown");
 });
 

package/src/index.ts

@@ -43,14 +43,29 @@ export function createExtension(pi: any, deps: Deps = {}): void {
   });
 
   const wake = createWake({
-    deliver: (text) => {
-      // sendUserMessage, not sendMessage({triggerTurn}): the custom-message
-      // trigger path starts the turn without emitting before_agent_start
-      // (pi core skips it), so extensions that assemble or capture the system
+    deliver: ({ envelope, summary }) => {
+      // Two-part delivery so the transcript shows a short readable line
+      // instead of the raw XML envelope, while the model still receives the
+      // envelope verbatim (pi serializes custom messages to the LLM as user
+      // content; display:false only hides them from the TUI).
+      //
+      // Why not one custom message with triggerTurn: that path starts the
+      // turn without emitting before_agent_start (verified against pi
+      // 0.84.3 dist), so extensions that assemble or capture the system
       // prompt there never see the turn — a bridge provider can hard-fail a
-      // session whose first turn is a channel wake. sendUserMessage runs the
-      // full prompt pipeline when idle and queues a steer while streaming.
-      pi.sendUserMessage(text, { deliverAs: "steer" });
+      // session whose first turn is a channel wake. Instead the envelope is
+      // queued deliverAs:"nextTurn" and the turn is triggered by the
+      // summary via sendUserMessage: prompt() drains the nextTurn queue
+      // into that same turn BEFORE emitting before_agent_start. Wake only
+      // delivers while the agent is settled; if a turn starts in the narrow
+      // race window, the summary steers into it and the envelope waits for
+      // the next prompt — degraded (the summary stands alone by design),
+      // never lost.
+      pi.sendMessage(
+        { customType: "channel-envelope", content: envelope, display: false },
+        { deliverAs: "nextTurn" },
+      );
+      pi.sendUserMessage(summary, { deliverAs: "steer" });
     },
     log: (message) => log(message),
   });

package/src/wake.test.ts

@@ -5,7 +5,7 @@ import type { ChannelEvent } from "./envelope.ts";
 
 function harness() {
   const delivered: string[] = [];
-  const wake = createWake({ deliver: (text) => delivered.push(text) });
+  const wake = createWake({ deliver: (d) => delivered.push(d.envelope) });
   wake.onSessionStart();
   wake.onReady();
   return { wake, delivered };
@@ -61,7 +61,7 @@ test("settling with an empty buffer delivers nothing", () => {
 
 test("mail arriving before ready is buffered and released once ready", () => {
   const delivered: string[] = [];
-  const wake = createWake({ deliver: (text) => delivered.push(text) });
+  const wake = createWake({ deliver: (d) => delivered.push(d.envelope) });
   wake.onSessionStart();
   wake.onEvent(ev("muster-channel", "early mail"));
   assert.equal(delivered.length, 0, "must not deliver into a half-built session");
@@ -94,9 +94,9 @@ test("a throwing deliver for one source still delivers the other (F2)", () => {
   const delivered: string[] = [];
   const logs: string[] = [];
   const wake = createWake({
-    deliver: (text) => {
-      if (text.includes('source="bad"')) throw new Error("boom: deliver exploded");
-      delivered.push(text);
+    deliver: (d) => {
+      if (d.envelope.includes('source="bad"')) throw new Error("boom: deliver exploded");
+      delivered.push(d.envelope);
     },
     log: (m) => logs.push(m),
   });

package/src/wake.ts

@@ -1,6 +1,13 @@
-import { renderBatch } from "./envelope.ts";
+import { renderBatch, renderSummary } from "./envelope.ts";
 import type { ChannelEvent } from "./envelope.ts";
 
+export type Delivery = {
+  // The model-facing XML envelope — full bodies, guidance, meta attributes.
+  envelope: string;
+  // The human-facing short form — what the transcript shows.
+  summary: string;
+};
+
 export type Wake = {
   onEvent(event: ChannelEvent): void;
   onAgentStart(): void;
@@ -10,7 +17,7 @@ export type Wake = {
   pendingCount(): number;
 };
 
-export function createWake(opts: { deliver: (text: string) => void; log?: (message: string) => void }): Wake {
+export function createWake(opts: { deliver: (delivery: Delivery) => void; log?: (message: string) => void }): Wake {
   // Insertion order of this Map is the delivery order across sources.
   let buffer = new Map<string, ChannelEvent[]>();
   let busy = false;
@@ -29,7 +36,7 @@ export function createWake(opts: { deliver: (text: string) => void; log?: (messa
     for (const [source, events] of batches) {
       if (events.length === 0) continue;
       try {
-        opts.deliver(renderBatch(source, events));
+        opts.deliver({ envelope: renderBatch(source, events), summary: renderSummary(source, events) });
       } catch (error) {
         // This runs synchronously inside the OS stream callback chain
         // (stdout 'data' -> dispatch -> onEvent -> flush -> deliver ->