channels.tools 0.1.0 → 0.1.1

package/package.json

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