@openparachute/agent 0.1.2 → 0.2.0

package/src/bridge.ts

@@ -0,0 +1,417 @@
+#!/usr/bin/env bun
+/**
+ * parachute-agent bridge — a stdio MCP server that Claude Code spawns.
+ *
+ * Connects to the parachute-agent daemon via SSE for inbound messages
+ * and proxies outbound tool calls (reply, react, edit, download) to the
+ * daemon's HTTP API. This is the only file Claude Code interacts with.
+ *
+ * The bridge is stateless and lightweight — safe to spawn in multiple
+ * sessions simultaneously because it never touches the Telegram API.
+ * The daemon handles all platform communication.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { agentEnv } from "./env-compat.ts";
+
+const DAEMON_URL = agentEnv("URL") ?? "http://127.0.0.1:1941";
+
+// Hub-issued JWT (aud: "agent", scopes agent:read + agent:write) the
+// session presents to the daemon on every request. Minted by launch-session.sh
+// via `parachute auth mint-token` and passed through .mcp.json. Read via the
+// PARACHUTE_AGENT_TOKEN → legacy PARACHUTE_CHANNEL_TOKEN fallback (rename
+// back-compat). When unset, the bridge sends no Authorization header — back-compat
+// for an unguarded/dev daemon (a daemon with auth on will then 401, surfaced below).
+const TOKEN = agentEnv("TOKEN");
+
+/** Headers for an outbound daemon request, adding the bearer when a token is set. */
+function daemonHeaders(extra: Record<string, string> = {}): Record<string, string> {
+  return TOKEN ? { ...extra, authorization: `Bearer ${TOKEN}` } : { ...extra };
+}
+
+// The named channel this bridge subscribes to. Defaults to "telegram" for
+// backwards-compat with single-bot installs. The daemon routes inbound on this
+// channel only to bridges subscribed to it, and every outbound tool call below
+// carries this channel so the daemon dispatches to the right transport.
+const CHANNEL = process.env.PARACHUTE_CHANNEL_NAME ?? "telegram";
+
+// ---------------------------------------------------------------------------
+// MCP server setup
+// ---------------------------------------------------------------------------
+
+const mcp = new Server(
+  { name: "parachute-agent", version: "0.1.0" },
+  {
+    capabilities: {
+      experimental: {
+        "claude/agent": {},
+        "claude/agent/permission": {},
+      },
+      tools: {},
+    },
+    instructions: [
+      "You are connected to a live chat channel. A human is messaging you through it.",
+      "",
+      "CRITICAL — HOW THE HUMAN SEES YOU: they read ONLY what you send via the `reply` tool. Your normal assistant/transcript text is INVISIBLE to them. So for EVERY message that arrives on this channel you MUST call the `reply` tool to answer — even a one-word reply. Never answer only in your transcript: if you don't call `reply`, the human sees nothing at all.",
+      "",
+      'Inbound messages arrive as <channel source="parachute-agent" ...> with metadata attributes describing the sender. Treat each as a chat message from the human and respond by calling the reply tool — the daemon routes it back out the same channel. Pass back any addressing fields the inbound tag carried (e.g. chat_id) if present; omit them otherwise. Use reply_to (message_id) to thread a specific message; omit it for normal responses.',
+      "",
+      "If the tag has an image_path attribute, Read that file — it is an attachment the sender sent.",
+      "If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path.",
+      "",
+      "Use react to add emoji reactions. Use edit_message for interim progress updates (edits do not push notifications — send a new reply when a long task completes so the user's device pings).",
+      "",
+      'reply accepts file paths (files: ["/abs/path.png"]) for attachments.',
+    ].join("\n"),
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Permission relay — receive permission_request from CC, forward to daemon
+// ---------------------------------------------------------------------------
+
+// The permission-request notification. The Zod schema does the runtime validation;
+// the params shape is hand-typed below. WHY the cast: the MCP SDK's
+// `setNotificationHandler<T>` computes `SchemaOutput<T>` over the schema, which trips
+// TS2589 ("type instantiation is excessively deep") on this nested inline Zod object —
+// a known SDK/Zod inference limit, NOT a runtime problem (the schema validates fine and
+// bun runs it). Passing the schema as the SDK's loose first-arg constraint sidesteps the
+// deep inference; the handler reads `params` via the explicit `PermissionNotifParams`.
+const PermissionNotifSchema = z.object({
+  method: z.literal("notifications/claude/agent/permission_request"),
+  params: z.object({
+    request_id: z.string(),
+    tool_name: z.string(),
+    description: z.string(),
+    input_preview: z.string(),
+  }),
+});
+// Derived from the schema so the two can't drift (plain z.infer of this shallow
+// schema is fine — the TS2589 depth blowup is in the SDK's SchemaOutput<T> on the
+// setNotificationHandler generic path, not in a basic type alias).
+type PermissionNotifParams = z.infer<typeof PermissionNotifSchema>["params"];
+
+mcp.setNotificationHandler(
+  PermissionNotifSchema as unknown as Parameters<typeof mcp.setNotificationHandler>[0],
+  async (notification) => {
+    const { params } = notification as { params: PermissionNotifParams };
+    try {
+      await fetch(`${DAEMON_URL}/api/permission`, {
+        method: "POST",
+        headers: daemonHeaders({ "content-type": "application/json" }),
+        body: JSON.stringify({ channel: CHANNEL, ...params }),
+      });
+    } catch (err) {
+      process.stderr.write(`parachute-agent bridge: failed to relay permission request: ${err}\n`);
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Tools — match the official plugin's tool surface
+// ---------------------------------------------------------------------------
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "reply",
+      description: "Send a message back through the channel to the sender. Supports text, file attachments, and quote-reply threading. The daemon routes it out whichever transport the channel uses.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          text: { type: "string", description: "Message text (optional if files provided)" },
+          reply_to: { type: "string", description: "Message ID to quote-reply (optional)" },
+          files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Absolute file paths to attach (optional)",
+          },
+          chat_id: {
+            type: "string",
+            description:
+              "Addressing field some transports need (e.g. a Telegram chat ID). Include it ONLY if the inbound message tag carried one; omit it otherwise (e.g. for a web/UI channel).",
+          },
+        },
+        required: [],
+      },
+    },
+    {
+      name: "react",
+      description: "Add an emoji reaction to a message, on transports that support reactions (e.g. Telegram's fixed emoji whitelist 👍 👎 ❤ 🔥 👀). Not all channels support this.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          message_id: { type: "string", description: "Message ID to react to" },
+          emoji: { type: "string", description: "Emoji reaction" },
+          chat_id: { type: "string", description: "Addressing field for transports that need it (e.g. Telegram chat ID); omit otherwise." },
+        },
+        required: ["message_id", "emoji"],
+      },
+    },
+    {
+      name: "edit_message",
+      description: "Edit a message you previously sent. Useful for progress updates. On most transports edits don't push a notification.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          message_id: { type: "string", description: "Message ID to edit" },
+          text: { type: "string", description: "New text" },
+          chat_id: { type: "string", description: "Addressing field for transports that need it (e.g. Telegram chat ID); omit otherwise." },
+        },
+        required: ["message_id", "text"],
+      },
+    },
+    {
+      name: "download_attachment",
+      description: "Download a Telegram file attachment by file_id. Returns the local path.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          file_id: { type: "string", description: "Telegram file_id from the attachment_file_id attribute" },
+        },
+        required: ["file_id"],
+      },
+    },
+  ],
+}));
+
+mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const args = req.params.arguments as Record<string, unknown>;
+  // Every outbound call carries the channel so the daemon dispatches to the
+  // right transport. Tool args (chat_id, text, …) ride alongside.
+  const body = { channel: CHANNEL, ...args };
+
+  switch (req.params.name) {
+    case "reply": {
+      const res = await fetch(`${DAEMON_URL}/api/reply`, {
+        method: "POST",
+        headers: daemonHeaders({ "content-type": "application/json" }),
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const err = await res.text();
+        return { content: [{ type: "text", text: `reply failed: ${err}` }], isError: true };
+      }
+      const data = (await res.json()) as { sent: string[] };
+      const ids = data.sent;
+      const parts = ids.length === 1 ? `(id: ${ids[0]})` : `(ids: ${ids.join(", ")})`;
+      return { content: [{ type: "text", text: `sent ${ids.length} part${ids.length > 1 ? "s" : ""} ${parts}` }] };
+    }
+
+    case "react": {
+      const res = await fetch(`${DAEMON_URL}/api/react`, {
+        method: "POST",
+        headers: daemonHeaders({ "content-type": "application/json" }),
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const err = await res.text();
+        return { content: [{ type: "text", text: `react failed: ${err}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: "reacted" }] };
+    }
+
+    case "edit_message": {
+      const res = await fetch(`${DAEMON_URL}/api/edit`, {
+        method: "POST",
+        headers: daemonHeaders({ "content-type": "application/json" }),
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const err = await res.text();
+        return { content: [{ type: "text", text: `edit failed: ${err}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: "edited" }] };
+    }
+
+    case "download_attachment": {
+      const res = await fetch(`${DAEMON_URL}/api/download`, {
+        method: "POST",
+        headers: daemonHeaders({ "content-type": "application/json" }),
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const err = await res.text();
+        return { content: [{ type: "text", text: `download failed: ${err}` }], isError: true };
+      }
+      const data = (await res.json()) as { path: string };
+      return { content: [{ type: "text", text: data.path }] };
+    }
+
+    default:
+      return { content: [{ type: "text", text: `unknown tool: ${req.params.name}` }], isError: true };
+  }
+});
+
+// ---------------------------------------------------------------------------
+// SSE connection to daemon — forward inbound messages as MCP notifications
+// ---------------------------------------------------------------------------
+
+async function connectToEvents(): Promise<void> {
+  while (true) {
+    try {
+      const res = await fetch(`${DAEMON_URL}/events?channel=${encodeURIComponent(CHANNEL)}`, {
+        headers: daemonHeaders(),
+      });
+      if (res.status === 401 || res.status === 403) {
+        // The daemon has auth on and rejected our token (or we sent none).
+        // Surface the operator-facing cause clearly before the reconnect loop
+        // retries — otherwise this looks like a generic connectivity failure.
+        process.stderr.write(
+          `parachute-agent bridge: daemon rejected the channel connection (HTTP ${res.status}). ` +
+            (TOKEN
+              ? "The PARACHUTE_AGENT_TOKEN is invalid/expired or lacks agent:read — re-mint it " +
+                "(parachute auth mint-token --scope \"agent:read agent:write\") and relaunch the session.\n"
+              : "No PARACHUTE_AGENT_TOKEN was provided but the daemon requires one — relaunch the " +
+                "session via launch-session.sh so it mints + passes a hub token.\n"),
+        );
+        throw new Error(`SSE connect rejected: ${res.status}`);
+      }
+      if (!res.ok || !res.body) {
+        throw new Error(`SSE connect failed: ${res.status}`);
+      }
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+
+        let currentEvent = "";
+        let currentData = "";
+
+        for (const line of lines) {
+          if (line.startsWith("event: ")) {
+            currentEvent = line.slice(7);
+          } else if (line.startsWith("data: ")) {
+            currentData += line.slice(6);
+          } else if (line === "") {
+            // End of event
+            if (currentEvent === "message" && currentData) {
+              try {
+                const parsed = JSON.parse(currentData) as {
+                  content: string;
+                  meta: Record<string, string>;
+                  source: string;
+                };
+                await mcp.notification({
+                  method: "notifications/claude/agent",
+                  params: {
+                    content: parsed.content,
+                    meta: { source: "parachute-agent", ...parsed.meta },
+                  },
+                });
+              } catch (err) {
+                process.stderr.write(`parachute-agent bridge: failed to parse/forward event: ${err}\n`);
+              }
+            } else if (currentEvent === "permission_verdict" && currentData) {
+              try {
+                const parsed = JSON.parse(currentData) as {
+                  request_id: string;
+                  behavior: string;
+                };
+                await mcp.notification({
+                  method: "notifications/claude/agent/permission",
+                  params: {
+                    request_id: parsed.request_id,
+                    behavior: parsed.behavior,
+                  },
+                });
+              } catch (err) {
+                process.stderr.write(`parachute-agent bridge: failed to forward permission verdict: ${err}\n`);
+              }
+            }
+            currentEvent = "";
+            currentData = "";
+          }
+        }
+      }
+    } catch (err) {
+      process.stderr.write(`parachute-agent bridge: SSE error, reconnecting in 3s: ${err}\n`);
+    }
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Missing-subscription warning
+//
+// If Claude Code attaches to this bridge but didn't opt into the
+// experimental `claude/agent` capability (e.g. forgot
+// `--dangerously-load-development-channels=server:<name>`), the MCP tools
+// register fine but every inbound notification the bridge emits is silently
+// dropped. That looks identical to a working setup until a message arrives
+// and nothing lands in the session.
+//
+// Signals, in priority order:
+//   1. On `oninitialized`, read `getClientCapabilities().experimental` — the
+//      canonical MCP hook. If `claude/agent` is missing, warn.
+//   2. If no initialize ever arrives (bridge is running but no client
+//      connected), warn after a grace period so `bun src/bridge.ts` invoked
+//      standalone tells you so.
+//
+// The warning doesn't exit — outbound tool calls still work in degraded mode.
+// Gated on NODE_ENV !== "test" so tests can import this module silently.
+// ---------------------------------------------------------------------------
+
+const SUBSCRIPTION_WARN_MS = 15_000;
+const IS_TEST = process.env.NODE_ENV === "test";
+
+let initReceived = false;
+const warnIfNoInit = setTimeout(() => {
+  if (initReceived || IS_TEST) return;
+  process.stderr.write(
+    "parachute-agent bridge: no MCP initialize received after 15s — " +
+    "the bridge is running but no client has connected.\n",
+  );
+}, SUBSCRIPTION_WARN_MS);
+if (typeof warnIfNoInit.unref === "function") warnIfNoInit.unref();
+
+mcp.oninitialized = () => {
+  initReceived = true;
+  clearTimeout(warnIfNoInit);
+  if (IS_TEST) return;
+  // The MCP SDK dispatches `notifications/initialized` and the preceding
+  // `initialize` request as separate microtasks; the notification's sync
+  // handler can fire before the request handler populates client
+  // capabilities. Defer the check to a later tick so `_clientCapabilities`
+  // is populated by the time we inspect it.
+  setTimeout(() => {
+    const caps = mcp.getClientCapabilities();
+    const hasAgent = caps?.experimental?.["claude/agent"] !== undefined;
+    if (!hasAgent) {
+      process.stderr.write(
+        [
+          "parachute-agent bridge: WARNING — client did not advertise claude/agent support.",
+          "  Inbound Telegram messages will not reach this session.",
+          "  Did you launch Claude Code with:",
+          "      --dangerously-load-development-channels=server:parachute-agent",
+          "  (See https://github.com/ParachuteComputer/parachute-agent/issues/8)",
+          "",
+        ].join("\n"),
+      );
+    }
+  }, 0);
+};
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+await mcp.connect(new StdioServerTransport());
+process.stderr.write(`parachute-agent bridge: connected to Claude Code (channel="${CHANNEL}"), connecting to daemon...\n`);
+
+// Start SSE listener (runs forever, reconnects on failure)
+connectToEvents();

package/src/channel-backend-wiring.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Tests for the ATTACHED-backend daemon wiring (design 2026-06-18-attached-backend.md,
+ * phases 1-2) — the two load-bearing seams:
+ *
+ *   1. The DAEMON ROUTING FORK (`contextFor`): an inbound for a `backend:attached`
+ *      agent must NOT enqueue to the ProgrammaticAgentRegistry (no `claude -p`) and
+ *      lands as a durable queue note; an inbound for a programmatic agent still
+ *      enqueues as before (no regression).
+ *   2. The CHANNEL MCP SURFACE (`dispatchChannelTool`): pending / next-message /
+ *      reply / release dispatch to the AttachedQueueRegistry; the outbound from `reply`
+ *      goes through the channel transport's reply (the `#agent/message/outbound` path —
+ *      loop-safe).
+ *
+ * Fakes throughout — no real vault / hub / tmux.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { contextFor } from "./daemon.ts";
+import { ClientRegistry } from "./routing.ts";
+import { DeliveryState } from "./delivery-state.ts";
+import {
+  ProgrammaticAgentRegistry,
+  type WriteOutbound,
+} from "./backends/registry.ts";
+import {
+  AttachedQueueRegistry,
+  type AttachedQueueStore,
+} from "./backends/attached-queue.ts";
+import { dispatchChannelTool } from "./mcp-http.ts";
+import { SCOPE_READ, SCOPE_WRITE } from "./auth.ts";
+import type { AgentBackend, AgentHandle, AgentStatus, DeliverResult } from "./backends/types.ts";
+import type { AgentSpec } from "./sandbox/types.ts";
+import type { InboundQueueNote, InboundStatus } from "./transports/vault.ts";
+
+// --- fakes -----------------------------------------------------------------
+
+/** A programmatic backend whose `deliver` (the `claude -p` turn) records calls. */
+class FakeProgrammaticBackend implements AgentBackend {
+  readonly kind = "programmatic";
+  readonly delivered: string[] = [];
+  async start(spec: AgentSpec): Promise<AgentHandle> {
+    return { backend: this.kind, channel: spec.channels[0] as string, name: spec.name, spec };
+  }
+  async deliver(_handle: AgentHandle, message: string): Promise<DeliverResult> {
+    this.delivered.push(message);
+    return { ok: true, reply: `auto:${message}` };
+  }
+  async stop(): Promise<void> {}
+  async status(): Promise<AgentStatus> {
+    return { live: true };
+  }
+}
+
+function noopWriteOutbound(): WriteOutbound {
+  return async () => {};
+}
+
+/** A fake attached-queue store: in-memory notes + recorded outbound. */
+class FakeStore implements AttachedQueueStore {
+  readonly notes = new Map<string, InboundQueueNote>();
+  readonly outbound: Array<{ text: string; inReplyTo?: string }> = [];
+  add(n: InboundQueueNote): void {
+    this.notes.set(n.id, n);
+  }
+  async listInboundQueue(): Promise<InboundQueueNote[]> {
+    return [...this.notes.values()].map((n) => ({ ...n })).sort((a, b) => (a.ts < b.ts ? -1 : 1));
+  }
+  async setInboundStatus(id: string, status: InboundStatus, claimedAt?: string | null): Promise<void> {
+    const n = this.notes.get(id)!;
+    n.status = status;
+    if (claimedAt === null) delete n.claimedAt;
+    else if (claimedAt !== undefined) n.claimedAt = claimedAt;
+  }
+  async reply(args: { text: string; inReplyTo?: string }): Promise<{ sent: string[] }> {
+    this.outbound.push({ text: args.text, ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}) });
+    return { sent: ["out-1"] };
+  }
+}
+
+const channelSpec = (name: string, systemPrompt?: string): AgentSpec => ({
+  name,
+  channels: [name],
+  backend: "attached",
+  ...(systemPrompt ? { systemPrompt } : {}),
+});
+
+// --- 1. the daemon routing fork --------------------------------------------
+
+describe("daemon routing fork (contextFor) — attached vs programmatic", () => {
+  test("an attached-backend inbound does NOT enqueue to the programmatic worker", async () => {
+    const backend = new FakeProgrammaticBackend();
+    const programmatic = new ProgrammaticAgentRegistry({ backend, writeOutbound: noopWriteOutbound() });
+    const attachedQueue = new AttachedQueueRegistry();
+    const store = new FakeStore();
+    // Register an ATTACHED agent for "laptop" (its queue store is the fake).
+    attachedQueue.register(channelSpec("laptop"), store);
+
+    const registry = new ClientRegistry();
+    const ctx = contextFor(registry, "laptop", new DeliveryState(), programmatic, attachedQueue);
+    // Simulate the vault trigger delivering an inbound for the channel.
+    ctx.emit({
+      channel: "laptop",
+      content: "handle this when you're around",
+      meta: { note_id: "note-1", ts: "2026-06-18T10:00:00Z" },
+      source: "vault",
+    });
+
+    // THE ASSERTION: the programmatic worker was NOT invoked (no `claude -p` turn).
+    expect(backend.delivered).toEqual([]);
+    // And the durable note is the queue item — it's pending (the trigger creates it as
+    // status:pending; emit doesn't mutate it). The note already lives in the vault; the
+    // channel registry reads it on the next pull.
+    store.add({ id: "note-1", text: "handle this when you're around", sender: "operator", ts: "2026-06-18T10:00:00Z", status: "pending" });
+    const view = await attachedQueue.pending("laptop");
+    expect(view.count).toBe(1);
+  });
+
+  test("a programmatic inbound STILL enqueues to the worker (no regression)", async () => {
+    const backend = new FakeProgrammaticBackend();
+    const programmatic = new ProgrammaticAgentRegistry({ backend, writeOutbound: noopWriteOutbound() });
+    await programmatic.register({ name: "eng", channels: ["eng"], backend: "programmatic" });
+    const attachedQueue = new AttachedQueueRegistry(); // no attached agent for "eng".
+
+    const registry = new ClientRegistry();
+    const ctx = contextFor(registry, "eng", new DeliveryState(), programmatic, attachedQueue);
+    ctx.emit({ channel: "eng", content: "do a task", meta: { note_id: "n-eng" }, source: "vault" });
+
+    // The serial worker drains async — wait for the turn to run.
+    for (let i = 0; i < 200 && backend.delivered.length === 0; i++) {
+      await new Promise<void>((r) => setTimeout(r, 1));
+    }
+    expect(backend.delivered).toEqual(["do a task"]); // the programmatic path is untouched.
+  });
+
+  test("the channel fork is checked FIRST — a name in BOTH registries routes to channel", async () => {
+    // Defense-in-depth: even if a programmatic agent somehow shares the channel, the
+    // channel check short-circuits (the fork is explicit + first), so no `claude -p`.
+    const backend = new FakeProgrammaticBackend();
+    const programmatic = new ProgrammaticAgentRegistry({ backend, writeOutbound: noopWriteOutbound() });
+    await programmatic.register({ name: "dual", channels: ["dual"], backend: "programmatic" });
+    const attachedQueue = new AttachedQueueRegistry();
+    attachedQueue.register(channelSpec("dual"), new FakeStore());
+
+    const ctx = contextFor(new ClientRegistry(), "dual", new DeliveryState(), programmatic, attachedQueue);
+    ctx.emit({ channel: "dual", content: "x", meta: {}, source: "vault" });
+    await new Promise<void>((r) => setTimeout(r, 10));
+    expect(backend.delivered).toEqual([]); // channel won the fork.
+  });
+});
+
+// --- 2. the channel MCP surface --------------------------------------------
+
+const RW = [SCOPE_READ, SCOPE_WRITE];
+
+function parse(result: { content: Array<{ type: "text"; text: string }> }): unknown {
+  return JSON.parse(result.content[0]!.text);
+}
+
+describe("channel MCP surface (dispatchChannelTool)", () => {
+  test("pending → { count, items }", async () => {
+    const reg = new AttachedQueueRegistry();
+    const store = new FakeStore();
+    store.add({ id: "a", text: "hi", sender: "operator", ts: "2026-06-18T10:00:00Z", status: "pending" });
+    reg.register(channelSpec("laptop"), store);
+
+    const r = await dispatchChannelTool("laptop", reg, RW, "pending", {});
+    expect(r.isError).toBeUndefined();
+    expect(parse(r)).toEqual({ count: 1, items: [{ id: "a", preview: "hi" }] });
+  });
+
+  test("next-message claims + returns id/text/inReplyTo/systemPrompt", async () => {
+    const reg = new AttachedQueueRegistry();
+    const store = new FakeStore();
+    store.add({ id: "a", text: "the question", sender: "operator", ts: "2026-06-18T10:00:00Z", status: "pending" });
+    reg.register(channelSpec("laptop", "You are laptop."), store);
+
+    const r = await dispatchChannelTool("laptop", reg, RW, "next-message", {});
+    const claimed = parse(r) as { id: string; text: string; inReplyTo: string; systemPrompt: string };
+    expect(claimed.id).toBe("a");
+    expect(claimed.text).toBe("the question");
+    expect(claimed.inReplyTo).toBe("a");
+    expect(claimed.systemPrompt).toBe("You are laptop.");
+    expect(store.notes.get("a")!.status).toBe("in-flight");
+  });
+
+  test("next-message returns a null-message sentinel when the queue is empty", async () => {
+    const reg = new AttachedQueueRegistry();
+    reg.register(channelSpec("laptop"), new FakeStore());
+    const r = await dispatchChannelTool("laptop", reg, RW, "next-message", {});
+    expect(parse(r)).toEqual({ message: null, note: "no pending messages" });
+  });
+
+  test("reply writes the outbound (loop-safe path) + marks handled", async () => {
+    const reg = new AttachedQueueRegistry();
+    const store = new FakeStore();
+    store.add({ id: "a", text: "q", sender: "operator", ts: "2026-06-18T10:00:00Z", status: "in-flight", claimedAt: "2026-06-18T10:01:00Z" });
+    reg.register(channelSpec("laptop"), store);
+
+    const r = await dispatchChannelTool("laptop", reg, RW, "reply", { inReplyTo: "a", text: "the answer" });
+    expect(r.isError).toBeUndefined();
+    // The outbound went through the channel transport's reply seam — which writes a
+    // `#agent/message/outbound` note (loop-safe; the inbound trigger never fires on it).
+    expect(store.outbound).toEqual([{ text: "the answer", inReplyTo: "a" }]);
+    expect(store.notes.get("a")!.status).toBe("handled");
+  });
+
+  test("release un-claims back to pending", async () => {
+    const reg = new AttachedQueueRegistry();
+    const store = new FakeStore();
+    store.add({ id: "a", text: "q", sender: "operator", ts: "t", status: "in-flight", claimedAt: "2026-06-18T10:00:00Z" });
+    reg.register(channelSpec("laptop"), store);
+
+    const r = await dispatchChannelTool("laptop", reg, RW, "release", { id: "a" });
+    expect(r.isError).toBeUndefined();
+    expect(store.notes.get("a")!.status).toBe("pending");
+  });
+
+  test("write tools require agent:write; a read-only token is refused", async () => {
+    const reg = new AttachedQueueRegistry();
+    reg.register(channelSpec("laptop"), new FakeStore());
+    for (const tool of ["next-message", "reply", "release"]) {
+      const r = await dispatchChannelTool("laptop", reg, [SCOPE_READ], tool, { id: "a", text: "x" });
+      expect(r.isError).toBe(true);
+      expect(r.content[0]!.text).toContain(SCOPE_WRITE);
+    }
+    // pending is read-only — works with a read token.
+    const ok = await dispatchChannelTool("laptop", reg, [SCOPE_READ], "pending", {});
+    expect(ok.isError).toBeUndefined();
+  });
+
+  test("a non-attached channel gates cleanly (tool error, not a crash)", async () => {
+    const reg = new AttachedQueueRegistry(); // nothing registered.
+    const r = await dispatchChannelTool("nope", reg, RW, "pending", {});
+    expect(r.isError).toBe(true);
+    expect(r.content[0]!.text).toContain("no attached-backend agent");
+  });
+});