channels.tools 0.1.1 → 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.1",
+  "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",