tandem-editor 0.4.0 → 0.6.0

package/dist/cli/index.js

@@ -10,7 +10,7 @@ var __export = (target, all) => {
 };
 
 // src/shared/constants.ts
-var DEFAULT_MCP_PORT, MAX_FILE_SIZE, MAX_WS_PAYLOAD, IDLE_TIMEOUT, SESSION_MAX_AGE;
+var DEFAULT_MCP_PORT, MAX_FILE_SIZE, MAX_WS_PAYLOAD, IDLE_TIMEOUT, SESSION_MAX_AGE, CHANNEL_MAX_RETRIES, CHANNEL_RETRY_DELAY_MS;
 var init_constants = __esm({
   "src/shared/constants.ts"() {
     "use strict";
@@ -19,108 +19,22 @@ var init_constants = __esm({
     MAX_WS_PAYLOAD = 10 * 1024 * 1024;
     IDLE_TIMEOUT = 30 * 60 * 1e3;
     SESSION_MAX_AGE = 30 * 24 * 60 * 60 * 1e3;
+    CHANNEL_MAX_RETRIES = 5;
+    CHANNEL_RETRY_DELAY_MS = 2e3;
   }
 });
 
 // src/cli/skill-content.ts
-var SKILL_CONTENT;
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+var __dirname, SKILL_PATH, SKILL_CONTENT;
 var init_skill_content = __esm({
   "src/cli/skill-content.ts"() {
     "use strict";
-    SKILL_CONTENT = `---
-name: tandem
-description: >
-  Use when tandem_* MCP tools are available, the user asks about Tandem
-  document editing, or collaborative document review. Provides workflow
-  guidance, annotation strategy, and tool usage patterns for the Tandem
-  collaborative editor.
----
-
-# Tandem \u2014 Collaborative Document Editor
-
-Tandem lets you annotate and edit documents alongside the user in real time. The user sees your changes in a browser editor; you interact via the tandem_* MCP tool suite.
-
-## Hard Rules
-
-These prevent the most common failures. Follow them always.
-
-1. **Resolve before mutating.** Call \`tandem_resolveRange\` (or \`tandem_search\`) to get offsets before calling \`tandem_edit\`, \`tandem_highlight\`, \`tandem_comment\`, \`tandem_suggest\`, or \`tandem_flag\`. Never compute offsets by counting characters in previously-read text \u2014 they go stale when the user edits.
-2. **Pass \`textSnapshot\`.** Include the matched text as \`textSnapshot\` on mutations and annotations. If the text moved, the server returns \`RANGE_MOVED\` with relocated coordinates instead of corrupting the document.
-3. **Use \`tandem_getTextContent\`, not \`tandem_getContent\`.** \`getContent\` returns ProseMirror JSON and burns tokens. Use \`getTextContent({ section: "Section Name" })\` for targeted reads. The \`section\` parameter is case-insensitive.
-4. **\`tandem_edit\` cannot create paragraphs.** Newlines become literal characters. For multi-paragraph changes, use multiple \`tandem_edit\` calls or \`tandem_suggest\`.
-5. **\`.docx\` files are read-only.** Use annotations instead of \`tandem_edit\`. Offer \`tandem_convertToMarkdown\` if the user wants an editable copy.
-
-## Workflow
-
-Standard review sequence:
-
-1. \`tandem_status\` \u2014 check for already-open documents (sessions restore automatically)
-2. \`tandem_getOutline\` \u2014 understand document structure
-3. \`tandem_setStatus("Reviewing [section]...", { focusParagraph: N })\` \u2014 show progress (use \`index\` from outline)
-4. \`tandem_getTextContent({ section: "..." })\` \u2014 read one section at a time
-5. Annotate findings (see annotation guide below)
-6. \`tandem_checkInbox\` \u2014 check for user messages and actions
-7. Repeat steps 3-6 for each section
-8. \`tandem_save\` \u2014 persist edits to disk when done
-
-## Annotation Guide
-
-Choose the right type for each finding:
-
-- **\`tandem_highlight\`** \u2014 Visual marker with a short note. Colors: green (verified/good), red (problem), yellow (needs attention). Use when the finding is self-evident from the color and a brief note.
-- **\`tandem_comment\`** \u2014 Observation requiring explanation. Use when you need more than one sentence to convey reasoning.
-- **\`tandem_suggest\`** \u2014 Specific text replacement. **Prefer over comment when you can provide replacement text** \u2014 the user gets one-click accept/reject. Cannot create new paragraphs.
-- **\`tandem_flag\`** \u2014 Factual errors, compliance risks, missing required content. Signals a blocking issue the user must address before the document ships.
-
-**User-created types:** \`question\` annotation is created by users, not Claude. When you see a \`question\` in \`tandem_checkInbox\` or \`tandem_getAnnotations\`, respond with a \`tandem_comment\` on the same range or \`tandem_reply\` for conversational answers.
-
-## Collaboration Mode
-
-Check \`mode\` from \`tandem_status\` or \`tandem_checkInbox\` and adapt:
-
-- **Tandem** (\`"tandem"\`, default) \u2014 Full collaboration. Annotate freely and react to selections and document changes.
-- **Solo** (\`"solo"\`) \u2014 The user wants to write undisturbed. Only respond when the user sends a chat message. Do not proactively annotate or react to document activity.
-
-## Reacting to Document Events
-
-Selection events can reach you two ways. Over the real-time channel they arrive as notifications with \`meta.respond_via = "tandem_reply"\`. When polling via \`tandem_checkInbox\`, the current selection shows up under \`activity.selectedText\` (no \`meta\` field \u2014 that only exists on channel pushes). Either way, when the user holds a selection, briefly acknowledge what they highlighted via \`tandem_reply\` \u2014 don't annotate unless asked. Use \`tandem_reply\` for any document-context reaction (chat messages, selections, question annotations); reserve terminal output for non-document work the user explicitly requests. In Solo mode, hold reactions until the user sends a chat message.
-
-## Collaboration Etiquette
-
-- Check \`tandem_getActivity()\` before annotating near the user's cursor. If \`isTyping\` is true, wait for typing to stop before annotating that area.
-- Use \`tandem_setStatus\` to show what you're working on \u2014 the user sees it in the browser status bar.
-- **Call \`tandem_checkInbox\` every 2-3 tool calls**, not just at the end of a task. The real-time channel is often not connected; polling is the reliable path.
-- Reply to chat messages with \`tandem_reply\`, not annotations.
-
-## .docx Review Workflow
-
-1. \`tandem_open\` \u2014 opens in read-only mode (\`readOnly: true\`)
-2. \`tandem_getAnnotations({ author: "import" })\` \u2014 check for imported Word comments; read and act on them
-3. Annotate with findings (highlight, comment, suggest, flag)
-4. \`tandem_exportAnnotations\` \u2014 generate a review summary the user can share
-5. If the user wants editable text, offer \`tandem_convertToMarkdown\`
-
-## Error Recovery
-
-- **\`RANGE_MOVED\`** \u2014 Text shifted since you read it. The response includes \`resolvedFrom\`/\`resolvedTo\` \u2014 use those coordinates for your next call.
-- **\`RANGE_GONE\`** \u2014 The text was deleted. Re-read the section with \`tandem_getTextContent\` and re-assess.
-- **\`INVALID_RANGE\`** \u2014 You hit heading markup (e.g., \`## \`). Target text content only, not the heading prefix.
-- **\`FORMAT_ERROR\`** \u2014 Attempted \`tandem_edit\` on a read-only \`.docx\`. Use annotations instead.
-
-## Session Handoff
-
-When starting a new Claude session with Tandem already running:
-
-1. \`tandem_status()\` \u2014 check \`openDocuments\` array for restored sessions
-2. \`tandem_listDocuments()\` \u2014 see all open docs with details
-3. \`tandem_getOutline()\` \u2014 orient on the active document
-4. \`tandem_getAnnotations()\` \u2014 see what was already reviewed
-5. Continue where the previous session left off
-
-## Multi-Document
-
-When multiple documents are open, always pass \`documentId\` explicitly \u2014 omitting it targets the active document, which may have changed since your last call. Use \`tandem_listDocuments\` to see what's available. Cross-reference by reading both docs via \`tandem_getTextContent({ documentId: "..." })\` and annotating the relevant one.
-`;
+    __dirname = dirname(fileURLToPath(import.meta.url));
+    SKILL_PATH = resolve(__dirname, "../../skills/tandem/SKILL.md");
+    SKILL_CONTENT = readFileSync(SKILL_PATH, "utf-8");
   }
 });
 
@@ -131,26 +45,27 @@ __export(setup_exports, {
   buildMcpEntries: () => buildMcpEntries,
   detectTargets: () => detectTargets,
   installSkill: () => installSkill,
-  runSetup: () => runSetup
+  runSetup: () => runSetup,
+  validateChannelShimPrereq: () => validateChannelShimPrereq
 });
 import { randomUUID } from "crypto";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
 import { copyFile, mkdir, rename, unlink, writeFile } from "fs/promises";
 import { homedir } from "os";
-import { dirname, join, resolve } from "path";
-import { fileURLToPath } from "url";
-function buildMcpEntries(channelPath, nodeBinary = "node") {
-  return {
-    tandem: {
-      type: "http",
-      url: `${MCP_URL}/mcp`
-    },
-    "tandem-channel": {
-      command: nodeBinary,
+import { basename, dirname as dirname2, join, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function buildMcpEntries(channelPath, opts = {}) {
+  const entries = {
+    tandem: { type: "http", url: `${MCP_URL}/mcp` }
+  };
+  if (opts.withChannelShim) {
+    entries["tandem-channel"] = {
+      command: opts.nodeBinary ?? "node",
       args: [channelPath],
       env: { TANDEM_URL: MCP_URL }
-    }
-  };
+    };
+  }
+  return entries;
 }
 function detectTargets(opts = {}) {
   const home = opts.homeOverride ?? homedir();
@@ -181,7 +96,7 @@ function detectTargets(opts = {}) {
   return targets;
 }
 async function atomicWrite(content, dest) {
-  const tmp = join(dirname(dest), `.tandem-setup-${randomUUID()}.tmp`);
+  const tmp = join(dirname2(dest), `.tandem-setup-${randomUUID()}.tmp`);
   await writeFile(tmp, content, "utf-8");
   try {
     await rename(tmp, dest);
@@ -202,14 +117,23 @@ async function atomicWrite(content, dest) {
 async function applyConfig(configPath, entries) {
   let existing = {};
   try {
-    existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    existing = JSON.parse(readFileSync2(configPath, "utf-8"));
   } catch (err) {
     const code = err.code;
     if (code === "ENOENT") {
     } else if (err instanceof SyntaxError) {
-      console.error(
-        `  Warning: ${configPath} contains malformed JSON \u2014 replacing with fresh config`
-      );
+      const backupPath = `${configPath}.broken-${Date.now()}`;
+      try {
+        await copyFile(configPath, backupPath);
+        console.error(
+          `  Warning: ${configPath} contains malformed JSON \u2014 backed up to ${basename(backupPath)}, replacing with fresh config`
+        );
+      } catch (copyErr) {
+        console.error(
+          `  Warning: ${configPath} contains malformed JSON and backup failed (${copyErr instanceof Error ? copyErr.message : copyErr}) \u2014 refusing to overwrite. Fix the JSON manually and rerun 'tandem setup'.`
+        );
+        throw copyErr;
+      }
     } else {
       throw err;
     }
@@ -221,17 +145,27 @@ async function applyConfig(configPath, entries) {
       ...entries
     }
   };
-  await mkdir(dirname(configPath), { recursive: true });
+  await mkdir(dirname2(configPath), { recursive: true });
   await atomicWrite(JSON.stringify(updated, null, 2) + "\n", configPath);
 }
 async function installSkill(opts = {}) {
   const home = opts.homeOverride ?? homedir();
   const skillPath = join(home, ".claude", "skills", "tandem", "SKILL.md");
-  await mkdir(dirname(skillPath), { recursive: true });
+  await mkdir(dirname2(skillPath), { recursive: true });
   await atomicWrite(SKILL_CONTENT, skillPath);
 }
+function validateChannelShimPrereq(channelPath) {
+  return existsSync(channelPath);
+}
 async function runSetup(opts = {}) {
   console.error("\nTandem Setup\n");
+  if (opts.withChannelShim && !validateChannelShimPrereq(CHANNEL_DIST)) {
+    console.error(
+      `Error: --with-channel-shim requires dist/channel/index.js at ${CHANNEL_DIST}
+Run 'npm run build' first, or drop --with-channel-shim to use the plugin monitor.`
+    );
+    process.exit(1);
+  }
   console.error("Detecting Claude installations...");
   const targets = detectTargets({ force: opts.force });
   if (targets.length === 0) {
@@ -244,7 +178,7 @@ async function runSetup(opts = {}) {
     console.error(`  Found: ${t.label} (${t.configPath})`);
   }
   console.error("\nWriting MCP configuration...");
-  const entries = buildMcpEntries(CHANNEL_DIST);
+  const entries = buildMcpEntries(CHANNEL_DIST, { withChannelShim: opts.withChannelShim });
   let failures = 0;
   for (const t of targets) {
     try {
@@ -279,23 +213,656 @@ Setup partially complete (${failures} target(s) failed). Start Tandem with: tand
     );
   }
   if (failures < targets.length) {
+    const pluginManifest = join(PACKAGE_ROOT, ".claude-plugin", "plugin.json");
+    const devInstructions = existsSync(pluginManifest) ? `  Or for development, load directly from this package:
+
+    claude --plugin-dir ${PACKAGE_ROOT}
+
+` : `  (Development plugin dir not found at ${pluginManifest}; skipping local-plugin instructions.)
+
+`;
     console.error(
-      "\n\x1B[1mReal-time push notifications (optional):\x1B[0m\n  To receive chat messages and events instantly (instead of polling),\n  start Claude Code with the channel flag:\n\n    claude --dangerously-load-development-channels server:tandem-channel\n\n  Without this flag, Claude still works but relies on tandem_checkInbox polling.\n"
+      "\n\x1B[1mReal-time push notifications (recommended):\x1B[0m\n  Install the Tandem plugin for instant events (one-time):\n\n    claude plugin marketplace add bloknayrb/tandem\n    claude plugin install tandem@tandem-editor\n\n" + devInstructions + "  Without the plugin, Claude still works but relies on tandem_checkInbox polling.\n"
     );
   }
 }
-var __dirname, CHANNEL_DIST, MCP_URL;
+var __dirname2, PACKAGE_ROOT, CHANNEL_DIST, MCP_URL;
 var init_setup = __esm({
   "src/cli/setup.ts"() {
     "use strict";
     init_constants();
     init_skill_content();
-    __dirname = dirname(fileURLToPath(import.meta.url));
-    CHANNEL_DIST = resolve(__dirname, "../channel/index.js");
+    __dirname2 = dirname2(fileURLToPath2(import.meta.url));
+    PACKAGE_ROOT = resolve2(__dirname2, "../..");
+    CHANNEL_DIST = resolve2(PACKAGE_ROOT, "dist/channel/index.js");
     MCP_URL = `http://localhost:${DEFAULT_MCP_PORT}`;
   }
 });
 
+// src/shared/cli-runtime.ts
+function redirectConsoleToStderr() {
+  console.log = console.error;
+  console.warn = console.error;
+  console.info = console.error;
+}
+function resolveTandemUrl(override) {
+  const raw = override ?? process.env.TANDEM_URL ?? `http://localhost:${DEFAULT_MCP_PORT}`;
+  return raw.replace(/\/$/, "");
+}
+var init_cli_runtime = __esm({
+  "src/shared/cli-runtime.ts"() {
+    "use strict";
+    init_constants();
+  }
+});
+
+// src/cli/preflight.ts
+async function ensureTandemServer(opts = {}) {
+  const url = resolveTandemUrl(opts.url);
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${url}/health`, { signal: controller.signal });
+    if (!res.ok) {
+      fail(url, `health endpoint returned HTTP ${res.status}`);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(url, msg);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function fail(url, detail) {
+  process.stderr.write(
+    `[tandem] Tandem server not reachable at ${url} (${detail}).
+[tandem] Start the Tauri app or run \`tandem start\` on the host, then retry.
+`
+  );
+  process.exit(1);
+}
+var DEFAULT_TIMEOUT_MS;
+var init_preflight = __esm({
+  "src/cli/preflight.ts"() {
+    "use strict";
+    init_cli_runtime();
+    DEFAULT_TIMEOUT_MS = 2e3;
+  }
+});
+
+// src/cli/mcp-stdio.ts
+var mcp_stdio_exports = {};
+__export(mcp_stdio_exports, {
+  getRequestId: () => getRequestId,
+  runMcpStdio: () => runMcpStdio
+});
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function runMcpStdio() {
+  const baseUrl = resolveTandemUrl();
+  await ensureTandemServer({ url: baseUrl });
+  const http = new StreamableHTTPClientTransport(new URL(`${baseUrl}/mcp`));
+  const stdio = new StdioServerTransport();
+  let shuttingDown = false;
+  const shutdown = async (code = 0) => {
+    if (!shuttingDown) {
+      shuttingDown = true;
+      await http.close().catch(() => {
+      });
+      await stdio.close().catch(() => {
+      });
+    }
+    process.exit(code);
+  };
+  stdio.onmessage = (msg) => {
+    http.send(msg).catch((err) => {
+      const detail = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[tandem mcp-stdio] upstream send failed: ${detail}
+`);
+      const requestId = getRequestId(msg);
+      if (requestId !== void 0) {
+        const errorResponse = {
+          jsonrpc: "2.0",
+          id: requestId,
+          error: {
+            // -32000 is the implementation-defined server error range per
+            // JSON-RPC 2.0 §5.1 — the upstream being unreachable is an
+            // application-level condition, not a generic Internal Error.
+            code: -32e3,
+            message: "Tandem HTTP upstream unreachable",
+            data: { detail }
+          }
+        };
+        stdio.send(errorResponse).catch(() => {
+        });
+      }
+    });
+  };
+  http.onmessage = (msg) => {
+    stdio.send(msg).catch((err) => {
+      const detail = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[tandem mcp-stdio] stdio write failed: ${detail}
+`);
+    });
+  };
+  stdio.onerror = (err) => {
+    process.stderr.write(`[tandem mcp-stdio] stdio error: ${err.message}
+`);
+  };
+  http.onerror = (err) => {
+    process.stderr.write(`[tandem mcp-stdio] http error: ${err.message}
+`);
+  };
+  stdio.onclose = () => {
+    void shutdown(0);
+  };
+  http.onclose = () => {
+    void shutdown(0);
+  };
+  await stdio.start();
+  try {
+    await http.start();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[tandem mcp-stdio] upstream http start failed: ${detail}
+`);
+    await shutdown(1);
+  }
+}
+function getRequestId(msg) {
+  const m = msg;
+  if (typeof m.method !== "string") return void 0;
+  if (typeof m.id === "string" || typeof m.id === "number") return m.id;
+  return void 0;
+}
+var init_mcp_stdio = __esm({
+  "src/cli/mcp-stdio.ts"() {
+    "use strict";
+    init_cli_runtime();
+    init_preflight();
+    redirectConsoleToStderr();
+  }
+});
+
+// src/shared/utils.ts
+var init_utils = __esm({
+  "src/shared/utils.ts"() {
+    "use strict";
+  }
+});
+
+// src/server/events/types.ts
+function parseTandemEvent(raw) {
+  if (typeof raw !== "object" || raw === null || !("id" in raw) || typeof raw.id !== "string" || !("type" in raw) || !VALID_EVENT_TYPES.has(raw.type) || !("timestamp" in raw) || typeof raw.timestamp !== "number" || !("payload" in raw) || typeof raw.payload !== "object") {
+    return null;
+  }
+  return raw;
+}
+function formatEventContent(event) {
+  const doc = event.documentId ? ` [doc: ${event.documentId}]` : "";
+  switch (event.type) {
+    case "annotation:created": {
+      const { annotationType, content, textSnippet, hasSuggestedText, directedAt } = event.payload;
+      const snippet = textSnippet ? ` on "${textSnippet}"` : "";
+      const label = hasSuggestedText ? "replacement" : directedAt === "claude" ? "question for Claude" : annotationType;
+      return `User created ${label}${snippet}: ${content || "(no content)"}${doc}`;
+    }
+    case "annotation:accepted": {
+      const { annotationId, textSnippet } = event.payload;
+      return `User accepted annotation ${annotationId}${textSnippet ? ` ("${textSnippet}")` : ""}${doc}`;
+    }
+    case "annotation:dismissed": {
+      const { annotationId, textSnippet } = event.payload;
+      return `User dismissed annotation ${annotationId}${textSnippet ? ` ("${textSnippet}")` : ""}${doc}`;
+    }
+    case "annotation:reply": {
+      const { annotationId, replyAuthor, replyText, textSnippet } = event.payload;
+      const who = replyAuthor === "claude" ? "Claude" : "User";
+      const snippet = textSnippet ? ` (on "${textSnippet}")` : "";
+      return `${who} replied to annotation ${annotationId}${snippet}: ${replyText}${doc}`;
+    }
+    case "chat:message": {
+      const { text, replyTo, selection } = event.payload;
+      const reply = replyTo ? ` (replying to ${replyTo})` : "";
+      const sel = selection && selection.selectedText ? ` [selection: "${selection.selectedText}"${"from" in selection ? ` (${selection.from}-${selection.to})` : ""}]` : "";
+      return `User says${reply}: ${text}${sel}${doc}`;
+    }
+    case "document:opened": {
+      const { fileName, format } = event.payload;
+      return `User opened document: ${fileName} (${format})${doc}`;
+    }
+    case "document:closed": {
+      const { fileName } = event.payload;
+      return `User closed document: ${fileName}${doc}`;
+    }
+    case "document:switched": {
+      const { fileName } = event.payload;
+      return `User switched to document: ${fileName}${doc}`;
+    }
+    default: {
+      const _exhaustive = event;
+      return `Unknown event${doc}`;
+    }
+  }
+}
+function formatEventMeta(event) {
+  const meta = {
+    event_type: event.type
+  };
+  if (event.documentId) meta.document_id = event.documentId;
+  switch (event.type) {
+    case "annotation:created":
+    case "annotation:accepted":
+    case "annotation:dismissed":
+      meta.annotation_id = event.payload.annotationId;
+      break;
+    case "annotation:reply":
+      meta.annotation_id = event.payload.annotationId;
+      meta.reply_id = event.payload.replyId;
+      break;
+    case "chat:message":
+      meta.message_id = event.payload.messageId;
+      if (event.payload.selection?.selectedText) meta.has_selection = "true";
+      break;
+    case "document:opened":
+    case "document:closed":
+    case "document:switched":
+      break;
+    default: {
+      const _exhaustive = event;
+      break;
+    }
+  }
+  return meta;
+}
+var VALID_EVENT_TYPES;
+var init_types = __esm({
+  "src/server/events/types.ts"() {
+    "use strict";
+    init_utils();
+    VALID_EVENT_TYPES = /* @__PURE__ */ new Set([
+      "annotation:created",
+      "annotation:accepted",
+      "annotation:dismissed",
+      "annotation:reply",
+      "chat:message",
+      "document:opened",
+      "document:closed",
+      "document:switched"
+    ]);
+  }
+});
+
+// src/channel/event-bridge.ts
+async function startEventBridge(mcp, tandemUrl) {
+  let retries = 0;
+  let lastEventId;
+  while (retries < CHANNEL_MAX_RETRIES) {
+    try {
+      await connectAndStream(mcp, tandemUrl, lastEventId, (id) => {
+        lastEventId = id;
+        retries = 0;
+      });
+    } catch (err) {
+      retries++;
+      console.error(
+        `[Channel] SSE connection failed (${retries}/${CHANNEL_MAX_RETRIES}):`,
+        err instanceof Error ? err.message : err
+      );
+      if (retries >= CHANNEL_MAX_RETRIES) {
+        console.error("[Channel] SSE connection exhausted, reporting error and exiting");
+        try {
+          await fetch(`${tandemUrl}/api/channel-error`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              error: "CHANNEL_CONNECT_FAILED",
+              message: `Channel shim lost connection after ${CHANNEL_MAX_RETRIES} retries.`
+            })
+          });
+        } catch (reportErr) {
+          console.error(
+            "[Channel] Could not report failure to server:",
+            reportErr instanceof Error ? reportErr.message : reportErr
+          );
+        }
+        process.exit(1);
+      }
+      await new Promise((r) => setTimeout(r, CHANNEL_RETRY_DELAY_MS));
+    }
+  }
+}
+async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
+  const headers = { Accept: "text/event-stream" };
+  if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+  const res = await fetch(`${tandemUrl}/api/events`, { headers });
+  if (!res.ok) throw new Error(`SSE endpoint returned ${res.status}`);
+  if (!res.body) throw new Error("SSE endpoint returned no body");
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let awarenessTimer = null;
+  let clearAwarenessTimer = null;
+  let pendingAwareness = null;
+  const AWARENESS_CLEAR_MS = 3e3;
+  function clearAwareness(documentId) {
+    fetch(`${tandemUrl}/api/channel-awareness`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        documentId: documentId ?? null,
+        status: "idle",
+        active: false
+      })
+    }).catch(() => {
+    });
+  }
+  function flushAwareness() {
+    if (!pendingAwareness) return;
+    const event = pendingAwareness;
+    pendingAwareness = null;
+    fetch(`${tandemUrl}/api/channel-awareness`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        documentId: event.documentId,
+        status: `processing: ${event.type}`,
+        active: true
+      })
+    }).catch((err) => {
+      console.error("[Channel] Awareness update failed:", err instanceof Error ? err.message : err);
+    });
+    if (clearAwarenessTimer) clearTimeout(clearAwarenessTimer);
+    clearAwarenessTimer = setTimeout(() => clearAwareness(event.documentId), AWARENESS_CLEAR_MS);
+  }
+  function scheduleAwareness(event) {
+    pendingAwareness = event;
+    if (awarenessTimer) clearTimeout(awarenessTimer);
+    awarenessTimer = setTimeout(flushAwareness, AWARENESS_DEBOUNCE_MS);
+  }
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) throw new Error("SSE stream ended");
+    buffer += decoder.decode(value, { stream: true });
+    let boundary;
+    while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+      const frame = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+      if (frame.startsWith(":")) continue;
+      let eventId;
+      let data;
+      for (const line of frame.split("\n")) {
+        if (line.startsWith("id: ")) eventId = line.slice(4);
+        else if (line.startsWith("data: ")) data = line.slice(6);
+      }
+      if (!data) continue;
+      let event;
+      try {
+        event = parseTandemEvent(JSON.parse(data));
+      } catch {
+        console.error("[Channel] Malformed SSE event data (skipping):", data.slice(0, 200));
+        continue;
+      }
+      if (!event) {
+        console.error("[Channel] Received invalid SSE event, skipping");
+        continue;
+      }
+      if (event.type !== "chat:message") {
+        const mode = await getCachedMode(tandemUrl);
+        if (mode === "solo") {
+          console.error(`[Channel] Solo mode: suppressed ${event.type} event`);
+          if (eventId) onEventId(eventId);
+          continue;
+        }
+      }
+      if (eventId) onEventId(eventId);
+      try {
+        await mcp.notification({
+          method: "notifications/claude/channel",
+          params: {
+            content: formatEventContent(event),
+            meta: formatEventMeta(event)
+          }
+        });
+      } catch (err) {
+        console.error("[Channel] MCP notification failed (transport broken?):", err);
+        throw err;
+      }
+      scheduleAwareness(event);
+    }
+  }
+}
+async function getCachedMode(tandemUrl) {
+  const now = Date.now();
+  if (now - cachedModeAt < MODE_CACHE_TTL_MS) return cachedMode;
+  try {
+    const res = await fetch(`${tandemUrl}/api/mode`);
+    if (res.ok) {
+      const { mode } = await res.json();
+      cachedMode = mode;
+    } else {
+      console.error(`[Channel] Mode check returned ${res.status}, using cached: "${cachedMode}"`);
+    }
+    cachedModeAt = now;
+  } catch (err) {
+    console.error(
+      "[Channel] Mode check failed, delivering event (fail-open):",
+      err instanceof Error ? err.message : err
+    );
+    cachedModeAt = now;
+  }
+  return cachedMode;
+}
+var AWARENESS_DEBOUNCE_MS, MODE_CACHE_TTL_MS, cachedMode, cachedModeAt;
+var init_event_bridge = __esm({
+  "src/channel/event-bridge.ts"() {
+    "use strict";
+    init_types();
+    init_constants();
+    AWARENESS_DEBOUNCE_MS = 500;
+    MODE_CACHE_TTL_MS = 2e3;
+    cachedMode = "tandem";
+    cachedModeAt = 0;
+  }
+});
+
+// src/channel/run.ts
+import { createConnection } from "net";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+async function runChannel(opts = {}) {
+  redirectConsoleToStderr();
+  const tandemUrl = resolveTandemUrl();
+  const mcp = new Server(
+    { name: "tandem-channel", version: "0.1.0" },
+    {
+      capabilities: {
+        experimental: {
+          "claude/channel": {},
+          "claude/channel/permission": {}
+        },
+        tools: {}
+      },
+      instructions: [
+        'Events from Tandem arrive as <channel source="tandem-channel" event_type="..." document_id="...">.',
+        "These are real-time push notifications of user actions in the collaborative document editor.",
+        "Event types: annotation:created, annotation:accepted, annotation:dismissed, annotation:reply,",
+        "chat:message, document:opened, document:closed, document:switched.",
+        "Chat messages may include a 'selection' field with buffered selection context.",
+        "Use your tandem MCP tools (tandem_getTextContent, tandem_comment, tandem_highlight, etc.) to act on them.",
+        "Reply to chat messages using tandem_reply. Pass document_id from the tag attributes.",
+        "Do not reply to non-chat events \u2014 just act on them using tools.",
+        "If you haven't received channel notifications recently, call tandem_checkInbox as a fallback."
+      ].join(" ")
+    }
+  );
+  mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "tandem_reply",
+        description: "Reply to a chat message in Tandem",
+        inputSchema: {
+          type: "object",
+          properties: {
+            text: { type: "string", description: "The reply message" },
+            documentId: {
+              type: "string",
+              description: "Document ID from the channel event (optional)"
+            },
+            replyTo: {
+              type: "string",
+              description: "Message ID being replied to (optional)"
+            }
+          },
+          required: ["text"]
+        }
+      }
+    ]
+  }));
+  mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+    if (req.params.name === "tandem_reply") {
+      const args2 = req.params.arguments;
+      try {
+        const res = await fetch(`${tandemUrl}/api/channel-reply`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(args2)
+        });
+        let data;
+        try {
+          data = await res.json();
+        } catch {
+          data = { message: "Non-JSON response" };
+        }
+        if (!res.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Reply failed (${res.status}): ${JSON.stringify(data)}`
+              }
+            ],
+            isError: true
+          };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to send reply: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+    throw new Error(`Unknown tool: ${req.params.name}`);
+  });
+  const PermissionRequestSchema = z.object({
+    method: z.literal("notifications/claude/channel/permission_request"),
+    params: z.object({
+      request_id: z.string(),
+      tool_name: z.string(),
+      description: z.string(),
+      input_preview: z.string()
+    })
+  });
+  mcp.setNotificationHandler(PermissionRequestSchema, async ({ params }) => {
+    try {
+      const res = await fetch(`${tandemUrl}/api/channel-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          requestId: params.request_id,
+          toolName: params.tool_name,
+          description: params.description,
+          inputPreview: params.input_preview
+        })
+      });
+      if (!res.ok) {
+        console.error(
+          `[Channel] Permission relay got HTTP ${res.status} \u2014 browser may not see prompt`
+        );
+      }
+    } catch (err) {
+      console.error("[Channel] Failed to forward permission request:", err);
+    }
+  });
+  console.error(`[Channel] Tandem channel shim starting (server: ${tandemUrl})`);
+  if (!opts.skipReachabilityLog) {
+    const reachable = await checkServerReachable(tandemUrl);
+    if (!reachable) {
+      console.error(`[Channel] Cannot reach Tandem server at ${tandemUrl}`);
+      console.error("[Channel] Start it with: tandem start");
+    }
+  }
+  const transport = new StdioServerTransport2();
+  await mcp.connect(transport);
+  console.error("[Channel] Connected to Claude Code via stdio");
+  startEventBridge(mcp, tandemUrl).catch((err) => {
+    console.error("[Channel] Event bridge failed unexpectedly:", err);
+    process.exit(1);
+  });
+}
+async function checkServerReachable(url, timeoutMs = 2e3) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    console.error(
+      `[Channel] Invalid TANDEM_URL: "${url}" \u2014 expected format: http://localhost:3479`
+    );
+    return false;
+  }
+  const port = parseInt(parsed.port || String(DEFAULT_MCP_PORT), 10);
+  return new Promise((resolve4) => {
+    const socket = createConnection({ port, host: parsed.hostname }, () => {
+      socket.destroy();
+      resolve4(true);
+    });
+    socket.setTimeout(timeoutMs);
+    socket.on("timeout", () => {
+      socket.destroy();
+      resolve4(false);
+    });
+    socket.on("error", (err) => {
+      console.error(`[Channel] Server probe failed: ${err.message}`);
+      socket.destroy();
+      resolve4(false);
+    });
+  });
+}
+var init_run = __esm({
+  "src/channel/run.ts"() {
+    "use strict";
+    init_cli_runtime();
+    init_constants();
+    init_event_bridge();
+  }
+});
+
+// src/cli/channel.ts
+var channel_exports = {};
+__export(channel_exports, {
+  runChannelCli: () => runChannelCli
+});
+async function runChannelCli() {
+  await ensureTandemServer();
+  await runChannel({ skipReachabilityLog: true });
+}
+var init_channel = __esm({
+  "src/cli/channel.ts"() {
+    "use strict";
+    init_run();
+    init_preflight();
+  }
+});
+
 // src/cli/start.ts
 var start_exports = {};
 __export(start_exports, {
@@ -303,8 +870,8 @@ __export(start_exports, {
 });
 import { spawn } from "child_process";
 import { existsSync as existsSync2 } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname3, resolve as resolve3 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 function runStart() {
   if (!existsSync2(SERVER_DIST)) {
     console.error(`[Tandem] Server not found at ${SERVER_DIST}`);
@@ -327,27 +894,36 @@ function runStart() {
     process.once(sig, () => proc.kill());
   }
 }
-var __dirname2, SERVER_DIST;
+var __dirname3, SERVER_DIST;
 var init_start = __esm({
   "src/cli/start.ts"() {
     "use strict";
-    __dirname2 = dirname2(fileURLToPath2(import.meta.url));
-    SERVER_DIST = resolve2(__dirname2, "../server/index.js");
+    __dirname3 = dirname3(fileURLToPath3(import.meta.url));
+    SERVER_DIST = resolve3(__dirname3, "../server/index.js");
   }
 });
 
 // src/cli/index.ts
 import updateNotifier from "update-notifier";
-var version = true ? "0.4.0" : "0.0.0-dev";
-updateNotifier({ pkg: { name: "tandem-editor", version } }).notify();
+var version = true ? "0.6.0" : "0.0.0-dev";
 var args = process.argv.slice(2);
+var isStdioMode = args[0] === "mcp-stdio" || args[0] === "channel";
+if (!isStdioMode) {
+  updateNotifier({ pkg: { name: "tandem-editor", version } }).notify();
+}
 if (args.includes("--help") || args.includes("-h")) {
   console.log(`tandem v${version}
 
 Usage:
-  tandem                  Start Tandem server and open the browser
-  tandem setup            Register MCP tools with Claude Code / Claude Desktop
-  tandem setup --force    Register to default paths regardless of detection
+  tandem                            Start Tandem server and open the browser
+  tandem setup                      Register MCP tools with Claude Code / Claude Desktop
+  tandem setup --force              Register to default paths regardless of detection
+  tandem setup --with-channel-shim  Also register the stdio channel shim (legacy opt-in)
+  tandem mcp-stdio                  Run as a stdio MCP server proxying to local HTTP
+                                    (used by the plugin's Cowork bridge; requires
+                                    tandem server running on the host)
+  tandem channel                    Run the Tandem channel shim (stdio MCP)
+                                    (used by the plugin's tandem-channel entry)
   tandem --version
   tandem --help
 `);
@@ -360,7 +936,16 @@ if (args.includes("--version") || args.includes("-v")) {
 try {
   if (args[0] === "setup") {
     const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
-    await runSetup2({ force: args.includes("--force") });
+    await runSetup2({
+      force: args.includes("--force"),
+      withChannelShim: args.includes("--with-channel-shim")
+    });
+  } else if (args[0] === "mcp-stdio") {
+    const { runMcpStdio: runMcpStdio2 } = await Promise.resolve().then(() => (init_mcp_stdio(), mcp_stdio_exports));
+    await runMcpStdio2();
+  } else if (args[0] === "channel") {
+    const { runChannelCli: runChannelCli2 } = await Promise.resolve().then(() => (init_channel(), channel_exports));
+    await runChannelCli2();
   } else if (!args[0] || args[0] === "start") {
     const { runStart: runStart2 } = await Promise.resolve().then(() => (init_start(), start_exports));
     runStart2();