kojee-mcp 0.5.11 → 0.5.13

package/README.md

@@ -240,6 +240,30 @@ Run bare (no `--token`) and the proxy uses **paired** credentials from
 | **openclaw** | **native channel plugin** (not MCP) | OpenClaw's own routing/sessions wake the agent on each Tandem event |
 | **hermes** | **native channel plugin** (sidecar daemon + webhook) | Hermes gateway wakes the agent like a Telegram DM |
 
+## Wake-delivery architecture (`src/delivery/`)
+
+Wake delivery is **pluggable, one module per runtime** behind a single interface, so **adding a runtime = write one `src/delivery/<runtime>.ts` + a line in the registry** — no edits to the SSE consume loop.
+
+```ts
+// src/delivery/types.ts
+interface WakeDelivery {
+  readonly name: string;
+  start(ctx: WakeDeliveryContext): Promise<StartedDelivery>; // open log / bind port / build sinks + stream
+  deliver(event: TandemEvent): Promise<void>;                // per-event fan-out; each sink isolated, never throws into consumeSse
+  stop(): Promise<void>;                                      // idempotent teardown
+  health?(): DeliveryHealth;                                  // surfaced by `kojee-mcp doctor`
+}
+// ctx = { instanceKey, runtime, eventLogDir, config, log } — framework-provided
+```
+
+- **Framework** — `types.ts` (interface), `registry.ts` (`runtime → WakeDelivery`, reproducing the channels / webhook-only / none gating); `index.ts` builds the runtime's delivery from the registry and `consumeSse` calls `deliver()` generically (cursor-tracking + wake-filter run first).
+- **Shared primitives** — `lib/event-log.ts` (Monitor substrate), `lib/webhook-sink.ts` (HMAC-signed POST), `lib/channel.ts` (CC channel render), `lib/fanout.ts` (the per-event sink fan-out).
+- **Per-runtime modules** — `claude-code.ts` (channel + event-log/Monitor), `hermes.ts` (HTTP webhook), `codex.ts` (webhook delegate; the Codex Stop-hook stays a CLI subcommand, **not** a sink), `openclaw.ts` (host-supplied sentinel — OpenClaw runs the proxy in-process and injects its own `WakeDelivery` via `kojee-mcp/lib`).
+
+**Session-faithful wake path.** The event log is keyed on a **stable instance key** (the Claude Code `session_id`, read from the parent env; else `KOJEE_INSTANCE`, else a project-dir hash). Because that key is stable across a window restart / crash / `--resume` (the pid is not), a persistent **Monitor keeps tailing a live log across a restart** instead of being stranded on a dead one. A startup **reaper** removes dead proxies' logs + discovery files (never a live sibling's — liveness-gated), and `kojee-mcp doctor` warns on a stale Monitor or a sibling proxy holding the webhook env. *(Degraded mode: where no session id is readable — e.g. Windows — set `KOJEE_INSTANCE=<unique-per-window>` so concurrent windows in one project dir don't share an event log.)*
+
+**Adding a runtime:** implement `WakeDelivery` in `src/delivery/<runtime>.ts` (compose the `lib/` primitives), register it in `src/delivery/registry.ts`, done.
+
 ## Native gateway runtimes (OpenClaw + Hermes)
 
 On OpenClaw and Hermes, Tandem is a **native channel** — peer to Telegram/Discord

package/dist/ancestry-ONFBQEP5.js

@@ -0,0 +1,8 @@
+import {
+  deriveDiscoveryKey,
+  findClaudeAncestorPid
+} from "./chunk-VHKPWUX7.js";
+export {
+  deriveDiscoveryKey,
+  findClaudeAncestorPid
+};

package/dist/{chunk-LDZXU3DW.js → chunk-2OLXXOT3.js}

@@ -62,6 +62,7 @@ function translateHttpError(status, errorCode, trigger) {
   return null;
 }
 var TANDEM_ERROR_MESSAGES = {
+  [-32001]: () => "You aren't an active member of that Tandem (the seat may have been reaped). Run tandem_join to reactivate it, then retry.",
   [-32003]: () => "This Tandem is hardened to owner-only membership; you can't join.",
   [-32004]: () => "You aren't a member of that Tandem. Use tandem_join(join_link) first.",
   [-32006]: (data) => {

package/dist/{codex-stop-hook-SWA53ECG.js → chunk-35XBRG3V.js}

@@ -63,10 +63,11 @@ async function runCodexStopHook() {
   process.stdout.write(out);
 }
 var CODEX_PEEK_BUDGET_MS = CODEX_PEEK_MS;
+
 export {
-  CODEX_PEEK_BUDGET_MS,
-  codexPendingMarkerPath,
   decideCodexStopHook,
+  codexPendingMarkerPath,
   defaultPeekPending,
-  runCodexStopHook
+  runCodexStopHook,
+  CODEX_PEEK_BUDGET_MS
 };

package/dist/chunk-3H3TL34J.js

@@ -0,0 +1,401 @@
+import {
+  claudeCodeAdapter
+} from "./chunk-XXFVWP6H.js";
+import {
+  GatewayClient,
+  applyStableSessionId
+} from "./chunk-IMOEZ4NJ.js";
+import {
+  AuthModule
+} from "./chunk-JXMVZEQ7.js";
+import {
+  secureDir,
+  secureFile
+} from "./chunk-BLEGIR35.js";
+import {
+  createMcpServer,
+  startMcpServer
+} from "./chunk-CM3EKMDD.js";
+import {
+  findClaudeAncestorPid
+} from "./chunk-VHKPWUX7.js";
+import {
+  parseTandemsConfig
+} from "./chunk-YKW54DKF.js";
+
+// src/index.ts
+import fs2 from "fs";
+import os2 from "os";
+import path2 from "path";
+
+// src/tool-registry.ts
+var ToolRegistry = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  gateway;
+  /** Flat map: tool name → full tool definition */
+  tools = /* @__PURE__ */ new Map();
+  /**
+   * Fetch all tools with full schemas from the gateway in a single RPC call.
+   */
+  async discoverTools() {
+    console.error("[tools] Fetching tools with full schemas from gateway...");
+    const result = await this.gateway.sendRpc("tools/list", {
+      include_schema: true
+    });
+    const maybeError = result;
+    if (maybeError.isError) {
+      const msg = maybeError.content?.[0]?.text ?? "unknown error";
+      throw new Error(`Gateway rejected tools/list: ${msg}`);
+    }
+    const toolList = result?.tools;
+    if (!toolList || !Array.isArray(toolList)) {
+      console.error("[tools] No tools returned from gateway");
+      return;
+    }
+    for (const tool of toolList) {
+      if (this.tools.has(tool.name)) {
+        console.error(`[tools] Warning: duplicate tool name "${tool.name}" \u2014 overwriting`);
+      }
+      this.tools.set(tool.name, tool);
+    }
+    console.error(`[tools] Registered ${this.tools.size} tools from gateway`);
+  }
+  /**
+   * Return all registered tools for the MCP ListTools response.
+   */
+  getAllTools() {
+    return Array.from(this.tools.values());
+  }
+  /**
+   * Call a tool through the gateway.
+   */
+  async callTool(name, args) {
+    if (!this.tools.has(name)) {
+      const available = Array.from(this.tools.keys()).slice(0, 10).join(", ");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Tool '${name}' not found. Some available tools: ${available}${this.tools.size > 10 ? ", ..." : ""}`
+          }
+        ],
+        isError: true
+      };
+    }
+    return this.gateway.sendRpc("tools/call", {
+      name,
+      arguments: args
+    });
+  }
+  /** Total number of registered tools. */
+  get toolCount() {
+    return this.tools.size;
+  }
+};
+
+// src/runtime/detect.ts
+import psList from "ps-list";
+async function detectRuntime(env = process.env) {
+  if (env["KOJEE_RUNTIME"] === "claude-code") return "claude-code";
+  if (env["KOJEE_RUNTIME"] === "codex") return "codex";
+  if (env["CLAUDE_CODE_SESSION_ID"]) return "claude-code";
+  const ancestor = await detectRuntimeFromAncestry();
+  if (ancestor) return ancestor;
+  return "unknown";
+}
+async function detectRuntimeFromAncestry() {
+  try {
+    const processes = await psList();
+    const byPid = new Map(processes.map((p) => [p.pid, p]));
+    let pid = process.ppid;
+    for (let depth = 0; depth < 5 && pid && pid > 1; depth++) {
+      const row = byPid.get(pid);
+      if (!row) return null;
+      const haystack = `${row.name} ${row.cmd ?? ""}`;
+      if (/(^|\/|\\)claude(\.app|\.exe)?(\/|$|\s|\\)/i.test(haystack) || /Claude Helper/i.test(haystack)) {
+        return "claude-code";
+      }
+      if (/(^|\/|\\)codex(\.exe)?(\/|$|\s|\\)/i.test(haystack)) {
+        return "codex";
+      }
+      pid = row.ppid;
+    }
+  } catch {
+  }
+  return null;
+}
+
+// src/adapters/codex.ts
+var codexAdapter = {
+  runtime: "codex",
+  supportsChannels: false,
+  // Codex has NO Claude-style channel injection
+  formatTandemEvent() {
+    throw new Error(
+      "codexAdapter.formatTandemEvent() is unreachable \u2014 Codex has no channel injection; server.ts gates this on supportsChannels. Codex receives events via the webhook sink + a model-chosen bounded tandem_listen."
+    );
+  }
+};
+
+// src/adapters/unknown.ts
+var unknownAdapter = {
+  runtime: "unknown",
+  supportsChannels: false,
+  formatTandemEvent() {
+    throw new Error(
+      "unknownAdapter.formatTandemEvent() is unreachable \u2014 caller should gate on supportsChannels"
+    );
+  }
+};
+
+// src/tandem/room-memory.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+function defaultKojeeDir() {
+  return path.join(os.homedir(), ".kojee");
+}
+function seatedRoomsPath(key, dir = defaultKojeeDir()) {
+  return path.join(dir, `seated-rooms-cc-${key}.json`);
+}
+function readSeatedRooms(key, dir = defaultKojeeDir()) {
+  let raw;
+  try {
+    raw = fs.readFileSync(seatedRoomsPath(key, dir), "utf8");
+  } catch {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed.rooms) ? parsed.rooms.filter((r) => typeof r === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function hasSeatedRoomsFile(key, dir = defaultKojeeDir()) {
+  return fs.existsSync(seatedRoomsPath(key, dir));
+}
+function seedSeatedRooms(key, rooms, dir = defaultKojeeDir()) {
+  writeSeatedRooms(key, [...new Set(rooms)], dir);
+}
+function writeSeatedRooms(key, rooms, dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  secureDir(dir);
+  const filePath = seatedRoomsPath(key, dir);
+  const body = { schema: 1, rooms, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  fs.writeFileSync(filePath, JSON.stringify(body, null, 2), { mode: 384 });
+  secureFile(filePath);
+}
+function addSeatedRoom(key, tandemId, dir = defaultKojeeDir()) {
+  const rooms = readSeatedRooms(key, dir);
+  if (rooms.includes(tandemId)) return;
+  writeSeatedRooms(key, [...rooms, tandemId], dir);
+}
+function removeSeatedRoom(key, tandemId, dir = defaultKojeeDir()) {
+  const rooms = readSeatedRooms(key, dir);
+  if (!rooms.includes(tandemId)) return;
+  writeSeatedRooms(key, rooms.filter((r) => r !== tandemId), dir);
+}
+
+// src/index.ts
+var DEFAULT_KEYSTORE_PATH = path2.join(os2.homedir(), ".kojee", "keypair.json");
+function isDPoPEnrollmentError(err) {
+  const msg = String(err?.message ?? err ?? "").toLowerCase();
+  if (msg.includes("invalid or expired") && msg.includes("token")) return false;
+  if (msg.includes("generate a new")) return false;
+  return msg.includes("401") || msg.includes("authentication failed") || msg.includes("dpop") || msg.includes("key enrollment") || msg.includes("kid");
+}
+async function selectAdapter() {
+  const runtime = await detectRuntime();
+  if (runtime === "claude-code") return claudeCodeAdapter;
+  if (runtime === "codex") return codexAdapter;
+  return unknownAdapter;
+}
+async function listTandemIds(gateway) {
+  const result = await gateway.sendRpc("tools/call", { name: "tandem_list", arguments: {} });
+  const maybeErr = result;
+  if (maybeErr.isError) return null;
+  const text = maybeErr.content?.[0]?.text;
+  try {
+    const parsed = text ? JSON.parse(text) : {};
+    const list = Array.isArray(parsed.tandems) ? parsed.tandems : Array.isArray(parsed) ? parsed : null;
+    if (!Array.isArray(list)) return [];
+    return list.map((t) => {
+      if (typeof t === "string") return t;
+      const obj = t;
+      if (obj?.my_membership?.is_member !== true) return void 0;
+      return obj?.tandem_id ?? obj?.id;
+    }).filter((id) => typeof id === "string" && id.length > 0);
+  } catch {
+    return null;
+  }
+}
+async function startProxy(config) {
+  const keystorePath = config.keystorePath || DEFAULT_KEYSTORE_PATH;
+  const adapter = await selectAdapter();
+  console.error(`[kojee-mcp] Starting proxy for ${config.url} (runtime=${adapter.runtime})`);
+  const ccPid = await findClaudeAncestorPid();
+  const { instanceKey } = await applyStableSessionId(config.token, { ccPid });
+  const { registry, gateway } = await enrollAndDiscover(config, keystorePath);
+  console.error(
+    `[kojee-mcp] Ready \u2014 ${registry.toolCount} tools available from ${config.url}`
+  );
+  const roomMemory = {
+    hasMemory: () => hasSeatedRoomsFile(instanceKey),
+    read: () => readSeatedRooms(instanceKey),
+    seed: (rooms) => seedSeatedRooms(instanceKey, rooms)
+  };
+  const recordRooms = parseTandemsConfig(process.env["KOJEE_TANDEMS"]).mode === "auto-local";
+  if (instanceKey.startsWith("wd-")) {
+    console.error(
+      "[kojee-mcp] degraded per-window fidelity: no per-window session id \u2014 two concurrent windows in the same project dir share ONE seat" + (recordRooms ? " and one room-memory file" : "") + ". Set KOJEE_INSTANCE=<unique-per-window> to keep them distinct."
+    );
+  }
+  let activeStreamHandle = null;
+  const { createJoinReconnectScheduler } = await import("./reconnect-scheduler-ARV6JIWK.js");
+  const joinReconnect = createJoinReconnectScheduler({
+    // BOOT-RACE (Bug B): report whether the stream handle was actually ready.
+    // `false` ⇒ activeStreamHandle is still null (tandem_join fired before the
+    // stream was set up) → the scheduler queues the reconnect and flushes it on
+    // notifyReady() once the handle is assigned (see below), instead of silently
+    // dropping it as the old `activeStreamHandle?.reconnect()` no-op did.
+    reconnect: () => {
+      if (!activeStreamHandle) return false;
+      activeStreamHandle.reconnect();
+      return true;
+    }
+  });
+  const onTandemJoin = (tandemId) => {
+    joinReconnect.requestReconnect();
+    if (recordRooms && tandemId) addSeatedRoom(instanceKey, tandemId);
+  };
+  const onTandemLeave = (tandemId) => {
+    if (recordRooms && tandemId) removeSeatedRoom(instanceKey, tandemId);
+  };
+  const teardownSteps = [];
+  let shuttingDown = false;
+  function shutdown(reason) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    activeStreamHandle?.();
+    for (const step of teardownSteps) {
+      try {
+        const maybe = step();
+        if (maybe && typeof maybe.catch === "function") {
+          maybe.catch((err) => {
+            console.error("[kojee-mcp] async shutdown step failed:", err?.message ?? err);
+          });
+        }
+      } catch (err) {
+        console.error("[kojee-mcp] shutdown step failed:", err?.message ?? err);
+      }
+    }
+    console.error(`[kojee-mcp] shutting down (${reason}), exiting`);
+    process.exit(0);
+  }
+  const { ensureJoinTandems } = await import("./ensure-join-5Y5IJ7HN.js");
+  await ensureJoinTandems({
+    gateway,
+    env: process.env["KOJEE_TANDEMS"],
+    listTandems: () => listTandemIds(gateway),
+    roomMemory,
+    onJoined: () => joinReconnect.requestReconnect()
+  });
+  let tandemMembershipCount = -1;
+  try {
+    const bootIds = await listTandemIds(gateway);
+    tandemMembershipCount = bootIds === null ? -1 : bootIds.length;
+  } catch (err) {
+    console.error("[kojee-mcp] tandem_list probe failed:", err.message);
+  }
+  console.error(`[kojee-mcp] Tandem memberships: ${tandemMembershipCount === -1 ? "unknown" : tandemMembershipCount}`);
+  let server;
+  const { selectDelivery } = await import("./registry-TGALQP6M.js");
+  const delivery = selectDelivery(adapter.runtime, {
+    supportsChannels: adapter.supportsChannels
+  });
+  if (delivery) {
+    const started = await delivery.start({
+      instanceKey,
+      runtime: adapter.runtime,
+      adapter,
+      config,
+      registry,
+      gateway,
+      ccPid,
+      tandemMembershipCount,
+      listTandemIds: () => listTandemIds(gateway),
+      toolCallHooks: { onTandemJoin, onTandemLeave },
+      onStreamReady: (handle) => {
+        activeStreamHandle = handle;
+        joinReconnect.notifyReady();
+      },
+      log: (line) => console.error(line)
+    });
+    server = started.server;
+    if (started.exitCleanup) {
+      const exitCleanup = started.exitCleanup;
+      process.on("exit", () => exitCleanup());
+    }
+    for (const step of started.teardown) teardownSteps.push(step);
+  } else {
+    server = createMcpServer(registry, adapter, tandemMembershipCount);
+  }
+  process.stdin.on("end", () => shutdown("stdin end"));
+  process.stdin.on("close", () => shutdown("stdin close"));
+  process.on("SIGHUP", () => shutdown("SIGHUP"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  if (ccPid !== null) {
+    const { createParentWatchdog } = await import("./parent-watchdog-TLU355FB.js");
+    const watchdog = createParentWatchdog({
+      ccPid,
+      onParentGone: () => shutdown("parent (Claude Code) gone")
+    });
+    watchdog.start();
+    teardownSteps.push(() => watchdog.stop());
+  } else {
+    console.error(
+      "[kojee-mcp] no Claude Code ancestor found \u2014 parent-liveness watchdog NOT armed (stdin/signal handlers still cover clean exits)"
+    );
+  }
+  await startMcpServer(server);
+}
+async function enrollAndDiscover(config, keystorePath, isRetry = false) {
+  const auth = new AuthModule(config.token, config.url, keystorePath);
+  const keyPair = await auth.ensureEnrolled();
+  const sessionId = GatewayClient.deriveSessionId(config.token);
+  console.error(`[kojee-mcp] Session: ${sessionId}`);
+  const gateway = new GatewayClient(
+    config.url,
+    config.token,
+    keyPair.privateKey,
+    keyPair.kid,
+    sessionId
+  );
+  const registry = new ToolRegistry(gateway);
+  try {
+    await registry.discoverTools();
+    return { registry, gateway };
+  } catch (err) {
+    if (isRetry || !isDPoPEnrollmentError(err)) {
+      throw err;
+    }
+    console.error(
+      "[kojee-mcp] Auth failed, attempting recovery with fresh enrollment..."
+    );
+    try {
+      if (fs2.existsSync(keystorePath)) fs2.unlinkSync(keystorePath);
+    } catch (unlinkErr) {
+      console.error("[kojee-mcp] Could not remove stale keystore:", unlinkErr);
+    }
+    return enrollAndDiscover(config, keystorePath, true);
+  }
+}
+
+export {
+  listTandemIds,
+  startProxy
+};

package/dist/{chunk-MKDMAAMN.js → chunk-74XFVX6Z.js}

@@ -1,13 +1,14 @@
 import {
-  MCP_SESSION_ID,
-  createDPoPProof
-} from "./chunk-2MIISF2W.js";
+  createDPoPProof,
+  getSessionId
+} from "./chunk-NR4Y54OL.js";
 
 // src/tandem/event-stream.ts
 var STALE_FLOOR_MS = 9e4;
 var STALE_INTERVAL_MULTIPLIER = 3;
 var STALE_CHECK_INTERVAL_MS = 5e3;
 var UNARMED_FALLBACK_MS = 12 * 6e4;
+var UNDICI_DEFAULT_BODY_TIMEOUT_MS = 3e5;
 function createAdaptiveWatchdog(options = {}) {
   const floorMs = options.floorMs ?? STALE_FLOOR_MS;
   const multiplier = options.multiplier ?? STALE_INTERVAL_MULTIPLIER;
@@ -179,7 +180,7 @@ async function openStream(opts, controller, sinceValue) {
     headers: {
       Authorization: `DPoP ${opts.token}`,
       DPoP: proof,
-      "Mcp-Session-Id": MCP_SESSION_ID,
+      "Mcp-Session-Id": getSessionId(),
       Accept: "text/event-stream"
     },
     signal: controller.signal
@@ -232,6 +233,14 @@ async function consumeSse(body, opts, controller, state, onCursor) {
             const parsed = normalizeBackendEvent(raw, evt.event);
             onCursor(parsed.tandem_id, parsed.cursor);
             if (parsed.wake === false) continue;
+            if (opts.delivery) {
+              try {
+                await opts.delivery.deliver(parsed);
+              } catch (err) {
+                console.error("[event-stream] delivery.deliver failed:", err);
+              }
+              continue;
+            }
             opts.queue?.push(parsed);
             if (opts.eventLog) {
               try {
@@ -398,8 +407,11 @@ function normalizeBackendEvent(raw, sseEventType) {
 }
 
 export {
+  UNDICI_DEFAULT_BODY_TIMEOUT_MS,
   createAdaptiveWatchdog,
+  createBackoffController,
   startEventStream,
+  serializeCursorMap,
   sanitizeDisplayname,
   normalizeBackendEvent
 };

package/dist/chunk-CM3EKMDD.js

@@ -0,0 +1,116 @@
+import {
+  buildCatchUpNote,
+  buildMonitorSpawn,
+  buildReplyRecipe
+} from "./chunk-X672ZN7V.js";
+import {
+  translateToolCallResult
+} from "./chunk-2OLXXOT3.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/version.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var FALLBACK_VERSION = "0.0.0-unknown";
+function resolveVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const parsed = JSON.parse(
+      fs.readFileSync(path.join(here, "..", "package.json"), "utf8")
+    );
+    return typeof parsed?.version === "string" && parsed.version ? parsed.version : FALLBACK_VERSION;
+  } catch (err) {
+    process.stderr.write(
+      `kojee-mcp: could not resolve version from package.json, falling back to ${FALLBACK_VERSION}: ${String(err)}
+`
+    );
+    return FALLBACK_VERSION;
+  }
+}
+var VERSION = resolveVersion();
+
+// src/server.ts
+function buildChannelInstructions(_tandemMembershipCount, eventLogPath) {
+  const intro = `Tandem events are delivered to you in three ways depending on which is active in your Claude Code session:
+
+(1) If channel notifications are available, you'll see them as \`<channel source="kojee-mcp" ...>\` tags in your context. Each tag carries tandem_id, message_id, from_principal, kind, severity. To respond: ${buildReplyRecipe()}.
+
+`;
+  const monitorSection = `(2) For sustained wake-from-idle WITHOUT channel notifications, the proxy writes one event line per Tandem message to ${eventLogPath}. At the start of every session, spawn ONE Monitor task: ${buildMonitorSpawn(eventLogPath)}. Each appended line will arrive as a separate wake notification, and carries msg=<id> and cursor=<n>. To respond: ${buildReplyRecipe()}. ${buildCatchUpNote()} (\`kojee-mcp tail\` is a portable line-streamer shipped with this proxy \u2014 works on macOS, Linux, and Windows. It follows BOTH the messages log above and a status sibling; status/heartbeat telemetry never wakes you \u2014 only real messages do.)
+
+`;
+  const listenSection = "(3) If you want to BLOCK until any single reply lands (rather than receive a stream of events), call tandem_listen(tandem_id, since=cursor, timeout_ms=N) instead.";
+  const advice = "\n\nPrefer (2) at session start \u2014 it's the default no-allowlist wake mechanism. (1) supplements it when channels are enabled; (3) is for one-shot blocking waits.";
+  return intro + monitorSection + listenSection + advice;
+}
+function tandemIdArg(args) {
+  return typeof args["tandem_id"] === "string" ? args["tandem_id"] : null;
+}
+async function executeToolCall(registry, name, args, hooks) {
+  const rawResult = await registry.callTool(name, args);
+  const result = translateToolCallResult(rawResult);
+  if (!result.isError) {
+    if (name === "tandem_join") {
+      try {
+        hooks?.onTandemJoin?.(tandemIdArg(args));
+      } catch (err) {
+        console.error("[mcp] onTandemJoin hook failed:", err?.message ?? String(err));
+      }
+    } else if (name === "tandem_leave") {
+      try {
+        hooks?.onTandemLeave?.(tandemIdArg(args));
+      } catch (err) {
+        console.error("[mcp] onTandemLeave hook failed:", err?.message ?? String(err));
+      }
+    }
+  }
+  return result;
+}
+function createMcpServer(registry, adapter, tandemMembershipCount = -1, eventLogPath, hooks) {
+  const capabilities = { tools: {} };
+  if (adapter.supportsChannels) {
+    capabilities.experimental = { "claude/channel": {} };
+  }
+  const server = new Server(
+    { name: "kojee-mcp", version: VERSION },
+    {
+      capabilities,
+      ...adapter.supportsChannels ? { instructions: buildChannelInstructions(tandemMembershipCount, eventLogPath ?? "") } : {}
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = registry.getAllTools().map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }));
+    return { tools };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = await executeToolCall(registry, name, args ?? {}, hooks);
+    return { content: result.content, isError: result.isError };
+  });
+  return server;
+}
+async function startMcpServer(server) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[mcp] Server started on stdio transport");
+}
+
+export {
+  VERSION,
+  buildChannelInstructions,
+  executeToolCall,
+  createMcpServer,
+  startMcpServer
+};