channels.tools 0.1.0

package/src/index.ts

@@ -0,0 +1,215 @@
+import { homedir } from "node:os";
+import { loadChannelConfig } from "./config.ts";
+import type { ChannelServerDef } from "./config.ts";
+import { ConnectionManager } from "./connection.ts";
+import type { Connection } from "./connection.ts";
+import { createWake } from "./wake.ts";
+import { applyIdentity } from "./identity.ts";
+import { normalizeSchema, resolveToolNames, toTextContent } from "./tools.ts";
+
+type Deps = {
+  env?: NodeJS.ProcessEnv;
+  loadConfig?: (cwd: string) => Record<string, ChannelServerDef>;
+  onBeforeSpawn?: () => void;
+  // Test seams only: override the ConnectionManager's retry backoff so tests
+  // can exercise the retry path without waiting out the real 30s/5min timers.
+  retryBaseMs?: number;
+  retryMaxMs?: number;
+};
+
+export function createExtension(pi: any, deps: Deps = {}): void {
+  const env = deps.env ?? process.env;
+  const loadConfig = deps.loadConfig ?? ((cwd: string) => loadChannelConfig({ home: homedir(), cwd }));
+
+  const manager = new ConnectionManager({
+    onEvent: (event) => wake.onEvent(event),
+    onStatus: (status) => uiSetStatus(status),
+    log: (message) => log(message),
+    // A channel that connects via retry — 30s+ after session_start already
+    // ran registerTools() once — is otherwise never brought back into the
+    // tool lifecycle: its instructions get injected and its events wake the
+    // agent, but the tools it just told the agent to call were never
+    // registered. registerTools() is idempotent (it clears and rebuilds
+    // registeredNames every call), so re-running it here is safe.
+    onConnected: (connections) => {
+      try {
+        registerTools(connections);
+      } catch (error) {
+        log(`re-registering tools after a retry reconnect failed: ${String(error)}`);
+      }
+    },
+    ...(deps.retryBaseMs !== undefined ? { retryBaseMs: deps.retryBaseMs } : {}),
+    ...(deps.retryMaxMs !== undefined ? { retryMaxMs: deps.retryMaxMs } : {}),
+  });
+
+  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
+      // 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" });
+    },
+    log: (message) => log(message),
+  });
+
+  let ui: { setStatus?: (key: string, value?: string) => void } | undefined;
+  const registeredNames = new Set<string>();
+
+  function uiSetStatus(status: string): void {
+    ui?.setStatus?.("channels", status === "" ? undefined : status);
+  }
+
+  function log(message: string): void {
+    process.stderr.write(`[channels] ${message}\n`);
+  }
+
+  function registerTools(connections: Connection[]): void {
+    const builtins = (pi.getAllTools?.() ?? []).map((t: { name: string }) => t.name);
+    const { resolved, dropped } = resolveToolNames(
+      connections.map((c) => ({ name: c.name, tools: c.tools })),
+      builtins,
+    );
+    // A dropped tool is uncallable and invisible; say so rather than letting
+    // the agent wonder why a documented tool does not exist.
+    for (const drop of dropped) {
+      log(`channel ${drop.server}: tool "${drop.original}" not registered — ${drop.reason}`);
+    }
+
+    // session_start also fires for reload/resume/fork, each time with a
+    // freshly reconnected `connections` array — the previous connectAll()
+    // already closed the old children and clients. Re-registering
+    // unconditionally (rather than skipping names already seen) replaces
+    // each tool's `execute` closure so it captures the new connection;
+    // skipping would leave the tool calling a client that is already
+    // closed, failing silently on every future invocation.
+    const stillPresent = new Set(resolved.map((e) => e.registered));
+    // pi.unregisterTool does not exist in the installed pi 0.84.2 (verified
+    // against its docs/ and dist/) — the optional call below is a permanent
+    // no-op today, kept only for a future pi version that adds it. The
+    // fallback that actually works now: drop the stale names from the
+    // active set, computed from getActiveTools() minus what is stale, so a
+    // resume never leaves a tool pointing at a closed client. Both calls are
+    // guarded; nothing here may throw into session_start.
+    const stillStale: string[] = [];
+    for (const name of registeredNames) {
+      if (stillPresent.has(name)) continue;
+      let handled = false;
+      try {
+        handled = Boolean(pi.unregisterTool?.(name));
+      } catch (error) {
+        log(`failed to unregister stale tool "${name}": ${String(error)}`);
+      }
+      if (!handled) stillStale.push(name);
+    }
+    if (stillStale.length > 0) {
+      try {
+        const active: string[] = pi.getActiveTools?.() ?? [];
+        pi.setActiveTools?.(active.filter((name: string) => !stillStale.includes(name)));
+      } catch (error) {
+        log(`failed to drop stale tools from the active set: ${String(error)}`);
+      }
+    }
+    registeredNames.clear();
+
+    for (const entry of resolved) {
+      // entry.server always names a connection from `connections` — it was
+      // built from `connections.map(...)` above.
+      const conn = connections.find((c) => c.name === entry.server)!;
+      const def = conn.tools.find((t) => t.name === entry.original);
+      registeredNames.add(entry.registered);
+      pi.registerTool({
+        name: entry.registered,
+        label: entry.original,
+        description: def?.description ?? `Tool from the ${entry.server} channel`,
+        // Plain JSON Schema: pi's toolWireSchema and validateToolArguments
+        // treat it as such, and it keeps this module free of typebox.
+        parameters: normalizeSchema(def?.inputSchema),
+        // pi's documented signature is execute(toolCallId, params, signal,
+        // onUpdate, ctx). Threading `signal` through to the JSON-RPC request
+        // means an aborted turn rejects the pending call immediately instead
+        // of leaving it pending for the full 30s timeout.
+        async execute(_id: string, params: unknown, signal?: AbortSignal) {
+          // pi only honors a thrown error as tool failure (it sets
+          // isError: true on the reported result); returning any
+          // error-shaped value — nested or not — is inert and the agent
+          // reads it as a clean success.
+          let result: unknown;
+          try {
+            result = await conn.client.request(
+              "tools/call",
+              { name: entry.original, arguments: params ?? {} },
+              undefined,
+              signal,
+            );
+          } catch (error) {
+            throw new Error(`channel tool "${entry.original}" on ${entry.server} failed: ${String(error)}`);
+          }
+          const mapped = toTextContent(result);
+          if (mapped.isError) {
+            const text = mapped.content.map((c) => c.text).join("\n");
+            throw new Error(`channel tool "${entry.original}" on ${entry.server} reported an error: ${text}`);
+          }
+          return { content: mapped.content, details: { server: entry.server } };
+        },
+      });
+    }
+  }
+
+  pi.on("session_start", async (_event: unknown, ctx: any) => {
+    ui = ctx.ui;
+    wake.onSessionStart();
+
+    // The whole body runs under try/finally so wake.onReady() always fires,
+    // even if something in between throws (most plausibly pi.registerTool
+    // rejecting a schema shaped by an external, out-of-our-control server).
+    // onReady() is the only thing that opens the mail gate; skipping it on
+    // an unhandled error would silently swallow every channel event for the
+    // rest of the session's lifetime.
+    try {
+      // Ordering is load-bearing: servers may read AGENT_SESSION_ID at
+      // their own startup to scope what they attach to. Set it late and
+      // such a channel comes up blind while the connection still looks
+      // healthy.
+      applyIdentity(ctx.sessionManager?.getSessionId?.(), env);
+      deps.onBeforeSpawn?.();
+
+      const defs = loadConfig(ctx.cwd ?? process.cwd());
+      await manager.connectAll(defs);
+      // manager.connections(), NOT the array connectAll returned: a retry that
+      // reconnected while a sibling was still handshaking has already
+      // registered its tools via onConnected, and connectAll's array cannot
+      // contain that server. Registering from the narrower array treats those
+      // tools as stale and drops them — leaving a live channel whose
+      // instructions are injected and whose events wake the agent, with no
+      // tools and no further retry scheduled. connections() is a superset in
+      // every other case.
+      registerTools(manager.connections());
+    } catch (error) {
+      log(`session_start failed: ${String(error)}`);
+    } finally {
+      // The gate opens when session_start completes — never on first
+      // settle, since agent_settled only fires after an agent run.
+      wake.onReady();
+    }
+  });
+
+  pi.on("before_agent_start", async (event: { systemPrompt?: string }) => {
+    const blocks = manager
+      .connections()
+      .filter((c) => typeof c.instructions === "string" && c.instructions !== "")
+      .map((c) => `<channel-instructions source="${c.name}">\n${c.instructions}\n</channel-instructions>`);
+    if (blocks.length === 0) return undefined;
+    return { systemPrompt: `${event.systemPrompt ?? ""}\n\n${blocks.join("\n\n")}` };
+  });
+
+  pi.on("agent_start", () => wake.onAgentStart());
+  pi.on("agent_settled", () => wake.onAgentSettled());
+  pi.on("session_shutdown", async () => { await manager.closeAll(); });
+}
+
+export default function (pi: any): void {
+  createExtension(pi);
+}

package/src/tools.test.ts

@@ -0,0 +1,109 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { normalizeSchema, resolveToolNames, toTextContent } from "./tools.ts";
+
+test("normalizeSchema strips $schema and additionalProperties", () => {
+  const out = normalizeSchema({
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "object",
+    properties: { doc: { type: "string" } },
+    additionalProperties: false,
+  });
+  assert.deepEqual(out, { type: "object", properties: { doc: { type: "string" } } });
+});
+
+test("normalizeSchema substitutes an empty object schema for junk", () => {
+  assert.deepEqual(normalizeSchema(undefined), { type: "object", properties: {} });
+  assert.deepEqual(normalizeSchema(null), { type: "object", properties: {} });
+  assert.deepEqual(normalizeSchema("nonsense"), { type: "object", properties: {} });
+  assert.deepEqual(normalizeSchema([1, 2]), { type: "object", properties: {} });
+});
+
+test("tool names are registered unprefixed so server instructions stay true", () => {
+  const { resolved, dropped } = resolveToolNames(
+    [{ name: "muster-channel", tools: [{ name: "muster_channel_status" }] }],
+    ["bash", "read"],
+  );
+  assert.deepEqual(resolved, [
+    { server: "muster-channel", original: "muster_channel_status", registered: "muster_channel_status" },
+  ]);
+  assert.deepEqual(dropped, []);
+});
+
+test("a collision with a builtin is prefixed with the server name", () => {
+  const { resolved } = resolveToolNames([{ name: "galley", tools: [{ name: "read" }] }], ["bash", "read"]);
+  assert.equal(resolved[0].registered, "galley_read");
+  assert.equal(resolved[0].original, "read");
+});
+
+test("a collision between two servers prefixes only the later one", () => {
+  const { resolved } = resolveToolNames(
+    [
+      { name: "alpha", tools: [{ name: "status" }] },
+      { name: "beta", tools: [{ name: "status" }] },
+    ],
+    [],
+  );
+  assert.equal(resolved[0].registered, "status");
+  assert.equal(resolved[1].registered, "beta_status");
+});
+
+test("server names are sanitized before prefixing", () => {
+  const { resolved } = resolveToolNames([{ name: "muster-channel", tools: [{ name: "read" }] }], ["read"]);
+  assert.equal(resolved[0].registered, "muster_channel_read");
+});
+
+test("a tool whose prefixed name still collides with a builtin is dropped with a reason naming the builtin", () => {
+  const { resolved, dropped } = resolveToolNames(
+    [{ name: "galley", tools: [{ name: "read" }] }],
+    ["read", "galley_read"],
+  );
+  assert.deepEqual(resolved, []);
+  assert.equal(dropped.length, 1);
+  assert.equal(dropped[0].server, "galley");
+  assert.equal(dropped[0].original, "read");
+  assert.match(dropped[0].reason, /builtin/);
+});
+
+test("a tool whose prefixed name collides with another server's registered tool is dropped with a reason naming a cross-server collision, not a builtin", () => {
+  // No builtins at all: gamma takes the bare name "x", beta gets prefixed to
+  // "beta_x" and registers it, then a second beta tool also named "x" tries
+  // the same bare-then-prefixed path and finds "beta_x" already taken by its
+  // own server's earlier tool — a collision with zero builtins involved.
+  const { resolved, dropped } = resolveToolNames(
+    [
+      { name: "gamma", tools: [{ name: "x" }] },
+      { name: "beta", tools: [{ name: "x" }, { name: "x" }] },
+    ],
+    [],
+  );
+  assert.equal(resolved.length, 2);
+  assert.equal(dropped.length, 1);
+  assert.equal(dropped[0].server, "beta");
+  assert.equal(dropped[0].original, "x");
+  assert.match(dropped[0].reason, /another server/);
+  assert.doesNotMatch(dropped[0].reason, /builtin/);
+});
+
+test("toTextContent maps MCP text blocks through", () => {
+  const out = toTextContent({ content: [{ type: "text", text: "hello" }] });
+  assert.deepEqual(out.content, [{ type: "text", text: "hello" }]);
+  assert.equal(out.isError, false);
+});
+
+test("toTextContent honors isError", () => {
+  const out = toTextContent({ content: [{ type: "text", text: "boom" }], isError: true });
+  assert.equal(out.isError, true);
+});
+
+test("toTextContent renders non-text blocks as a readable placeholder", () => {
+  const out = toTextContent({ content: [{ type: "image", data: "…", mimeType: "image/png" }] });
+  assert.equal(out.content.length, 1);
+  assert.match(out.content[0].text, /image/);
+});
+
+test("toTextContent survives a result with no content", () => {
+  const out = toTextContent({});
+  assert.equal(out.content.length, 1);
+  assert.equal(out.isError, false);
+});

package/src/tools.ts

@@ -0,0 +1,66 @@
+import type { McpToolDef } from "./connection.ts";
+
+export function normalizeSchema(schema: unknown): Record<string, unknown> {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    return { type: "object", properties: {} };
+  }
+  // $schema and additionalProperties are stripped because pi's validator
+  // treats the object as a typebox schema; real servers ship
+  // additionalProperties:false, which is the case this guards.
+  const { $schema: _s, additionalProperties: _a, ...rest } = schema as Record<string, unknown>;
+  return rest;
+}
+
+export function resolveToolNames(
+  connections: Array<{ name: string; tools: McpToolDef[] }>,
+  builtins: string[],
+): {
+  resolved: Array<{ server: string; original: string; registered: string }>;
+  dropped: Array<{ server: string; original: string; reason: string }>;
+} {
+  const builtinSet = new Set(builtins);
+  const taken = new Set(builtins);
+  const resolved: Array<{ server: string; original: string; registered: string }> = [];
+  const dropped: Array<{ server: string; original: string; reason: string }> = [];
+  for (const conn of connections) {
+    for (const tool of conn.tools) {
+      // Unprefixed by default: channel servers already self-namespace, and
+      // their instructions name these tools literally. Prefix only on a real
+      // clash, so at most one server's documentation is ever wrong.
+      let registered = tool.name;
+      if (taken.has(registered)) registered = `${conn.name.replace(/[^A-Za-z0-9_]/g, "_")}_${tool.name}`;
+      if (taken.has(registered)) {
+        // Attribute the drop to whatever the *final* (possibly prefixed) name
+        // actually collided with — builtins never change, but `taken` grows
+        // as servers are processed, so this must be checked against the
+        // original builtin set, not the flag from the unprefixed check above.
+        const reason = builtinSet.has(registered)
+          ? `prefixed name "${registered}" still collides with a builtin tool`
+          : `prefixed name "${registered}" collides with another server's registered tool`;
+        dropped.push({ server: conn.name, original: tool.name, reason });
+        continue;
+      }
+      taken.add(registered);
+      resolved.push({ server: conn.name, original: tool.name, registered });
+    }
+  }
+  return { resolved, dropped };
+}
+
+export function toTextContent(result: unknown): {
+  content: Array<{ type: "text"; text: string }>;
+  isError: boolean;
+} {
+  const r = (typeof result === "object" && result !== null ? result : {}) as {
+    content?: unknown;
+    isError?: unknown;
+  };
+  const blocks = Array.isArray(r.content) ? r.content : [];
+  const content = blocks.map((block) => {
+    const b = (typeof block === "object" && block !== null ? block : {}) as Record<string, unknown>;
+    if (b.type === "text" && typeof b.text === "string") return { type: "text" as const, text: b.text };
+    return { type: "text" as const, text: `[${String(b.type ?? "unknown")} content omitted]` };
+  });
+  if (content.length === 0) content.push({ type: "text" as const, text: "(no content)" });
+  return { content, isError: r.isError === true };
+}

package/src/wake.test.ts

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createWake } from "./wake.ts";
+import type { ChannelEvent } from "./envelope.ts";
+
+function harness() {
+  const delivered: string[] = [];
+  const wake = createWake({ deliver: (text) => delivered.push(text) });
+  wake.onSessionStart();
+  wake.onReady();
+  return { wake, delivered };
+}
+
+const ev = (source: string, content: string, meta: Record<string, string> = {}): ChannelEvent =>
+  ({ source, content, meta });
+
+test("an event while idle delivers immediately", () => {
+  const { wake, delivered } = harness();
+  wake.onEvent(ev("muster-channel", "mail arrived"));
+  assert.equal(delivered.length, 1);
+  assert.match(delivered[0], /mail arrived/);
+});
+
+test("an event mid-turn is buffered, not delivered", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();
+  wake.onEvent(ev("muster-channel", "mail arrived"));
+  assert.equal(delivered.length, 0);
+  assert.equal(wake.pendingCount(), 1);
+});
+
+test("settling flushes the buffer coalesced into one delivery per source", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();
+  wake.onEvent(ev("muster-channel", "one"));
+  wake.onEvent(ev("muster-channel", "two"));
+  wake.onAgentSettled();
+  assert.equal(delivered.length, 1);
+  assert.match(delivered[0], /one/);
+  assert.match(delivered[0], /two/);
+  assert.equal(wake.pendingCount(), 0);
+});
+
+test("events from different sources flush as separate deliveries", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();
+  wake.onEvent(ev("muster-channel", "mail"));
+  wake.onEvent(ev("galley", "revise"));
+  wake.onAgentSettled();
+  assert.equal(delivered.length, 2);
+  assert.match(delivered[0], /source="muster-channel"/);
+  assert.match(delivered[1], /source="galley"/);
+});
+
+test("settling with an empty buffer delivers nothing", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();
+  wake.onAgentSettled();
+  assert.equal(delivered.length, 0);
+});
+
+test("mail arriving before ready is buffered and released once ready", () => {
+  const delivered: string[] = [];
+  const wake = createWake({ deliver: (text) => delivered.push(text) });
+  wake.onSessionStart();
+  wake.onEvent(ev("muster-channel", "early mail"));
+  assert.equal(delivered.length, 0, "must not deliver into a half-built session");
+  wake.onReady();
+  assert.equal(delivered.length, 1);
+  assert.match(delivered[0], /early mail/);
+});
+
+test("a turn started by the operator also buffers", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();          // not triggered by us
+  wake.onEvent(ev("muster-channel", "mail"));
+  assert.equal(delivered.length, 0);
+});
+
+test("session_start clears the buffer and closes the gate again", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();
+  wake.onEvent(ev("muster-channel", "stale"));
+  wake.onSessionStart();
+  assert.equal(wake.pendingCount(), 0);
+  wake.onEvent(ev("muster-channel", "after resume"));
+  assert.equal(delivered.length, 0, "gate is closed until ready");
+  wake.onReady();
+  assert.equal(delivered.length, 1);
+  assert.doesNotMatch(delivered[0], /stale/);
+});
+
+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);
+    },
+    log: (m) => logs.push(m),
+  });
+  wake.onSessionStart();
+  wake.onReady();
+  wake.onAgentStart();
+  wake.onEvent(ev("bad", "one"));
+  wake.onEvent(ev("good", "two"));
+  wake.onAgentSettled();
+  assert.equal(delivered.length, 1, "the good source's batch must still be delivered");
+  assert.match(delivered[0], /source="good"/);
+  assert.ok(logs.some((l) => /bad/.test(l)), `expected a log naming the failed source, got: ${logs.join(" | ")}`);
+});
+
+test("delivery order across sources follows first arrival", () => {
+  const { wake, delivered } = harness();
+  wake.onAgentStart();
+  wake.onEvent(ev("galley", "first"));
+  wake.onEvent(ev("muster-channel", "second"));
+  wake.onAgentSettled();
+  assert.match(delivered[0], /source="galley"/);
+});

package/src/wake.ts

@@ -0,0 +1,76 @@
+import { renderBatch } from "./envelope.ts";
+import type { ChannelEvent } from "./envelope.ts";
+
+export type Wake = {
+  onEvent(event: ChannelEvent): void;
+  onAgentStart(): void;
+  onAgentSettled(): void;
+  onSessionStart(): void;
+  onReady(): void;
+  pendingCount(): number;
+};
+
+export function createWake(opts: { deliver: (text: string) => 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;
+  let ready = false;
+
+  function pendingCount(): number {
+    let n = 0;
+    for (const [, events] of buffer) n += events.length;
+    return n;
+  }
+
+  function flush(): void {
+    if (buffer.size === 0) return;
+    const batches = buffer;
+    buffer = new Map();
+    for (const [source, events] of batches) {
+      if (events.length === 0) continue;
+      try {
+        opts.deliver(renderBatch(source, events));
+      } catch (error) {
+        // This runs synchronously inside the OS stream callback chain
+        // (stdout 'data' -> dispatch -> onEvent -> flush -> deliver ->
+        // pi.sendUserMessage). A throw here must not escape: uncaught, it kills
+        // the pi process from inside an EventEmitter callback. And because
+        // `buffer` was already swapped out above, one bad delivery must not
+        // stop the loop — the next source's events would otherwise be
+        // discarded along with it, which is exactly the silent-mail-loss
+        // failure this component exists to prevent.
+        opts.log?.(`delivery to ${source} failed: ${String(error)}`);
+      }
+    }
+  }
+
+  return {
+    onEvent(event) {
+      const events = buffer.get(event.source) ?? [];
+      events.push(event);
+      buffer.set(event.source, events);
+      // The gate must be open AND no turn running. `ready` is set when
+      // session_start finishes, never on first settle: agent_settled only
+      // fires after an agent run, so a session whose first event is inbound
+      // mail would otherwise never settle and never deliver.
+      if (ready && !busy) flush();
+    },
+    onAgentStart() {
+      busy = true;
+    },
+    onAgentSettled() {
+      busy = false;
+      if (ready) flush();
+    },
+    onSessionStart() {
+      busy = false;
+      ready = false;
+      buffer = new Map();
+    },
+    onReady() {
+      ready = true;
+      if (!busy) flush();
+    },
+    pendingCount,
+  };
+}