@composer-app/mcp 0.0.1-beta.4 → 0.0.1-beta.5

package/dist/{chunk-UVXQZ2TN.js → chunk-A5KBJAJW.js}

@@ -4185,6 +4185,14 @@ var RoomState = class {
    * on every remote edit, comment, suggestion, or activity-feed write.
    */
   _lastRemoteActivityAt = Date.now();
+  monitoringOn = false;
+  /**
+   * Set true when `composer_next_event`'s goodbye branch has fired. Tells
+   * `handleNextEvent` to refuse subsequent calls until the user explicitly
+   * re-engages (which happens via `composer_create_room` / `composer_join_room`,
+   * both of which build a fresh `RoomState` so this flag resets naturally).
+   */
+  goodbyeIssued = false;
   constructor(opts) {
     this.roomId = opts.roomId;
     this.actingAs = opts.actingAs;
@@ -4197,46 +4205,9 @@ var RoomState = class {
     });
     this.provider = new YProvider(opts.serverHost, opts.roomId, this.doc, {
       party: "composer-room",
-      connect: true,
+      connect: false,
       WebSocketPolyfill: WebSocket
     });
-    this.provider.awareness.setLocalStateField("user", {
-      name: opts.actingAs,
-      color: opts.identity.color,
-      userId: opts.identity.userId,
-      isAgent: true
-    });
-    this.installAwarenessHeartbeat();
-  }
-  /**
-   * Re-broadcast the MCP's awareness every 15s.
-   *
-   * y-partyserver's provider disables the y-protocols awareness
-   * `_checkInterval` (see `clearInterval(awareness._checkInterval)` in
-   * `y-partyserver/dist/provider/index.js`), so the MCP sends its awareness
-   * exactly once — on connect — and never heartbeats after that. Combined
-   * with Cloudflare Durable Object hibernation (which evicts the server's
-   * in-memory `document.awareness` Map on wake), this means a browser that
-   * connects more than ~60s after the MCP sees an empty awareness dump in
-   * `onConnect` and never learns the agent is there. The user's own
-   * awareness flows the other direction fine (they send on connect, server
-   * broadcasts to the MCP), which is why the failure is asymmetric.
-   *
-   * y-partyserver's provider listens to `awareness.on("change", ...)`, and
-   * y-protocols only fires `change` when the new state is deep-unequal to
-   * the previous one. Re-setting an identical state emits `update` but NOT
-   * `change`, so the provider never sends a wire frame. We bump a throwaway
-   * `_hb` field each tick to guarantee deep-inequality, forcing the change
-   * event and a broadcast. 15s is well under any realistic hibernation gap.
-   */
-  installAwarenessHeartbeat() {
-    const heartbeat = setInterval(() => {
-      const local = this.provider.awareness.getLocalState();
-      if (local !== null) {
-        this.provider.awareness.setLocalState({ ...local, _hb: Date.now() });
-      }
-    }, 15e3);
-    heartbeat.unref?.();
   }
   /**
    * Resolves when the provider has completed its first sync handshake.
@@ -4264,6 +4235,117 @@ var RoomState = class {
       this.provider.on("sync", onSync);
     });
   }
+  idleDisconnectTimer = null;
+  /**
+   * Open the WebSocket (if not already) and await the first sync handshake.
+   * Idempotent — no-op if already connected and synced. Call at the top of
+   * every tool handler that touches the doc. Cancels any pending idle
+   * disconnect because we're back in active use.
+   */
+  async ensureConnected(timeoutMs = 15e3) {
+    if (this.idleDisconnectTimer) {
+      clearTimeout(this.idleDisconnectTimer);
+      this.idleDisconnectTimer = null;
+    }
+    if (this.provider.wsconnected && this.provider.synced) return;
+    await this.provider.connect();
+    await this.waitForInitialSync(timeoutMs);
+  }
+  /**
+   * Arm a timer that turns monitoring off and closes the socket after `ms`
+   * of no further tool-handler activity. Cancelled by `ensureConnected`.
+   * Call at the end of every tool handler. Defaults to 30s — long enough
+   * to bridge a normal multi-step monitor turn (mention → reply →
+   * `composer_next_event` again), short enough that an abandoned monitor
+   * loop fades the avatar within the "within a minute" window the user
+   * requested.
+   *
+   * Both presence cleanup paths converge here: setMonitoring(false) clears
+   * our local awareness state, then disconnect() closes the socket which
+   * triggers y-partyserver's onClose → removeAwarenessStates. Either alone
+   * would suffice; doing both keeps local and server state consistent.
+   */
+  scheduleIdleDisconnect(ms = 3e4) {
+    if (this.idleDisconnectTimer) {
+      clearTimeout(this.idleDisconnectTimer);
+      this.idleDisconnectTimer = null;
+    }
+    if (!this.provider.wsconnected) return;
+    this.idleDisconnectTimer = setTimeout(() => {
+      this.idleDisconnectTimer = null;
+      this.setMonitoring(false);
+      this.provider.disconnect();
+    }, ms);
+    this.idleDisconnectTimer.unref?.();
+  }
+  /**
+   * Close the socket immediately. Available for explicit teardown
+   * (e.g., destroy()). Does not touch monitoring state — the socket close
+   * causes y-partyserver to broadcast the awareness removal, which is the
+   * visual signal peers care about.
+   */
+  disconnect() {
+    if (this.idleDisconnectTimer) {
+      clearTimeout(this.idleDisconnectTimer);
+      this.idleDisconnectTimer = null;
+    }
+    this.provider.disconnect();
+  }
+  /**
+   * Toggle whether the agent is visibly monitoring the room. Broadcast via
+   * the `user` awareness field — present ↔ avatar visible to peers. The
+   * socket must already be open (caller should have ensured this).
+   *
+   *   setMonitoring(true)  — called once on first composer_next_event entry.
+   *   setMonitoring(false) — called on the goodbye branch; clears awareness
+   *                          immediately so the avatar disappears as the
+   *                          farewell lands.
+   *
+   * Subsequent calls with the same value are no-ops.
+   */
+  setMonitoring(on) {
+    if (this.monitoringOn === on) return;
+    this.monitoringOn = on;
+    if (on) {
+      const current = this.provider.awareness.getLocalState() ?? {};
+      this.provider.awareness.setLocalState({
+        ...current,
+        user: {
+          name: this.actingAs,
+          color: this.identity.color,
+          userId: this.identity.userId,
+          isAgent: true
+        }
+      });
+    } else {
+      this.provider.awareness.setLocalState(null);
+    }
+  }
+  get isMonitoring() {
+    return this.monitoringOn;
+  }
+  /**
+   * Latch flipped by `composer_next_event`'s goodbye branch. Once set, the
+   * model is expected to stop calling `composer_next_event` until the user
+   * explicitly asks to rejoin — which builds a fresh RoomState, resetting
+   * the latch. The MCP refuses further next_event calls on this RoomState
+   * instead of silently re-entering the monitor loop.
+   */
+  markGoodbyeIssued() {
+    this.goodbyeIssued = true;
+  }
+  get hasIssuedGoodbye() {
+    return this.goodbyeIssued;
+  }
+  /**
+   * Read-only view of this client's local awareness state. Exposed for
+   * tests/diagnostics only — production code should not depend on this.
+   * Returns `null` when monitoring is off (local state cleared) or when
+   * the provider hasn't written any fields yet.
+   */
+  getLocalAwareness() {
+    return this.provider.awareness.getLocalState();
+  }
   snapshot() {
     return {
       fullDoc: serializeDocAsMarkdown(this.doc),
@@ -4272,23 +4354,38 @@ var RoomState = class {
       threadsBacklog: []
     };
   }
-  async nextEvent(timeoutMs) {
+  async nextEvent(timeoutMs, signal) {
     const pending = this.queue.shift();
     if (pending) return pending;
+    if (signal?.aborted) return { kind: "timeout" };
     return new Promise((resolve) => {
-      const timer = setTimeout(() => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
         const idx = this.waiters.indexOf(waiter);
         if (idx >= 0) this.waiters.splice(idx, 1);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
         resolve({ kind: "timeout" });
       }, timeoutMs);
+      const onAbort = () => {
+        cleanup();
+        resolve({ kind: "timeout" });
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
       const waiter = (ev) => {
-        clearTimeout(timer);
+        cleanup();
         resolve(ev);
       };
       this.waiters.push(waiter);
     });
   }
   destroy() {
+    if (this.idleDisconnectTimer) {
+      clearTimeout(this.idleDisconnectTimer);
+      this.idleDisconnectTimer = null;
+    }
     this.provider.destroy();
     this.doc.destroy();
   }
@@ -4605,6 +4702,18 @@ var SERVER_HOST = process.env.COMPOSER_SERVER_HOST ?? "usecomposer.app";
 var APP_BASE = process.env.COMPOSER_APP_BASE ?? "https://usecomposer.app";
 var rooms = /* @__PURE__ */ new Map();
 var identityCache = null;
+function teardownAllRooms() {
+  for (const [roomId, state] of rooms) {
+    try {
+      state.setMonitoring(false);
+      state.disconnect();
+      state.destroy();
+    } catch (err) {
+      logError(`teardown error for room ${roomId}`, err);
+    }
+  }
+  rooms.clear();
+}
 async function getIdentity() {
   if (!identityCache) {
     identityCache = await loadOrCreateIdentity(COMPOSER_DIR2);
@@ -4699,12 +4808,12 @@ var TOOL_DEFS = [
   },
   {
     name: "composer_next_event",
-    description: "Block for up to `timeoutSec` (default 600 / 10 min) waiting for a remote event. Returns `{ kind: 'mention' | 'timeout', ... }`. **The monitor loop is always-on** \u2014 every return carries a directive you must follow without waiting for user input. On `mention`, the `reason` is one of: `direct_mention` (sidecar or text named you \u2014 always reply), `active_thread` (plain reply on a thread you're already in \u2014 reply if the content invites one), or `solo_room` (you're alone with one human who didn't explicitly tag anyone \u2014 default to a helpful reply, but skip if the text reads like a note-to-self, acknowledgement, or aside). Handle the event, then execute the return's `requiredNextToolCall`. On `timeout`, `recentActivity` tells you whether to keep monitoring or exit with the goodbye line from `userMessage`.",
+    description: "Block for up to `timeoutSec` (default 30s) waiting for a remote event. Returns `{ kind: 'mention' | 'timeout', ... }`. **The monitor loop is always-on** \u2014 every return carries a directive you must follow without waiting for user input. On `mention`, the `reason` is one of: `direct_mention` (sidecar or text named you \u2014 always reply), `active_thread` (plain reply on a thread you're already in \u2014 reply if the content invites one), or `solo_room` (you're alone with one human who didn't explicitly tag anyone \u2014 default to a helpful reply, but skip if the text reads like a note-to-self, acknowledgement, or aside). Handle the event, then execute the return's `requiredNextToolCall`. On `timeout`, `recentActivity` tells you whether to keep monitoring or exit with the goodbye line from `userMessage`.",
     inputSchema: {
       type: "object",
       properties: {
         roomId: { type: "string" },
-        timeoutSec: { type: "number", default: 600 }
+        timeoutSec: { type: "number", default: 30 }
       },
       required: ["roomId"]
     }
@@ -4927,12 +5036,13 @@ async function handleCreateRoom(args) {
     actingAs,
     identity
   });
-  await state.waitForInitialSync();
+  await state.ensureConnected();
   if (seedMarkdown) {
     writeMarkdownToFragment(state.doc.getXmlFragment("default"), seedMarkdown);
   }
   rooms.set(roomId, state);
   log(`composer room created \u2192 ${browserUrl}`, { roomId, actingAs });
+  state.scheduleIdleDisconnect(3e4);
   return okResult({
     roomId,
     browserUrl,
@@ -4953,6 +5063,7 @@ async function handleJoinRoom(args) {
       roomId,
       actingAs: existing.actingAs
     });
+    existing.scheduleIdleDisconnect(3e4);
     return okResult({
       roomId,
       browserUrl,
@@ -4974,9 +5085,10 @@ async function handleJoinRoom(args) {
     actingAs,
     identity
   });
-  await state.waitForInitialSync();
+  await state.ensureConnected();
   rooms.set(roomId, state);
   log(`composer room joined \u2192 ${browserUrl}`, { roomId, actingAs });
+  state.scheduleIdleDisconnect(3e4);
   return okResult({
     roomId,
     browserUrl,
@@ -4991,14 +5103,41 @@ function handleAttachRoom(args) {
   const state = getOrError(roomId);
   return okResult({ roomId, snapshot: state.snapshot() });
 }
-var ACTIVITY_WINDOW_MS = 10 * 60 * 1e3;
+var ACTIVITY_WINDOW_MS = (() => {
+  const raw = process.env.COMPOSER_ACTIVITY_WINDOW_MS;
+  if (!raw) return 15 * 60 * 1e3;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 15 * 60 * 1e3;
+})();
 var LEAVE_MESSAGE = "I've left the document. You can ask me to rejoin anytime and I'll continue replying.";
-async function handleNextEvent(args) {
+async function handleNextEvent(args, signal) {
   const a = asObject(args);
   const roomId = asString(a.roomId, "roomId");
-  const timeoutSec = typeof a.timeoutSec === "number" && Number.isFinite(a.timeoutSec) ? a.timeoutSec : 600;
+  const timeoutSec = typeof a.timeoutSec === "number" && Number.isFinite(a.timeoutSec) ? a.timeoutSec : 30;
   const state = getOrError(roomId);
-  const event = await state.nextEvent(timeoutSec * 1e3);
+  if (state.hasIssuedGoodbye) {
+    return errorResult(
+      "Already said goodbye for this room. The user must explicitly ask you to rejoin (which will trigger a fresh `composer_join_room`). Do not call `composer_next_event` again on this roomId."
+    );
+  }
+  state.setMonitoring(true);
+  const onAbort = () => {
+    state.setMonitoring(false);
+    state.disconnect();
+  };
+  if (signal) {
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  }
+  let event;
+  try {
+    event = await state.nextEvent(timeoutSec * 1e3, signal);
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+  }
+  if (signal?.aborted) {
+    return okResult({ kind: "aborted" });
+  }
   if (event.kind === "mention") {
     return okResult({
       ...event,
@@ -5024,6 +5163,9 @@ async function handleNextEvent(args) {
       }
     });
   }
+  state.setMonitoring(false);
+  state.disconnect();
+  state.markGoodbyeIssued();
   return okResult({
     kind: "timeout",
     recentActivity: false,
@@ -5256,34 +5398,44 @@ function handleResolveThread(args) {
   comments.set(threadId, { ...existing, resolved: true });
   return okResult({ threadId, resolved: true });
 }
-async function dispatchTool(name, args) {
-  switch (name) {
-    case "composer_create_room":
-      return handleCreateRoom(args);
-    case "composer_join_room":
-      return handleJoinRoom(args);
-    case "composer_attach_room":
-      return handleAttachRoom(args);
-    case "composer_next_event":
-      return handleNextEvent(args);
-    case "composer_get_section":
-      return handleGetSection(args);
-    case "composer_get_full_doc":
-      return handleGetFullDoc(args);
-    case "composer_get_thread":
-      return handleGetThread(args);
-    case "composer_add_comment":
-      return handleAddComment(args);
-    case "composer_reply_comment":
-      return handleReplyComment(args);
-    case "composer_add_suggestion":
-      return handleAddSuggestion(args);
-    case "composer_reply_suggestion":
-      return handleReplySuggestion(args);
-    case "composer_resolve_thread":
-      return handleResolveThread(args);
-    default:
-      return errorResult(`unknown tool: ${name}`);
+async function dispatchTool(name, args, signal) {
+  const roomId = args && typeof args === "object" && "roomId" in args ? args.roomId : void 0;
+  const needsExistingRoom = name !== "composer_create_room" && name !== "composer_join_room";
+  const state = needsExistingRoom && typeof roomId === "string" ? rooms.get(roomId) : void 0;
+  if (state) {
+    await state.ensureConnected();
+  }
+  try {
+    switch (name) {
+      case "composer_create_room":
+        return await handleCreateRoom(args);
+      case "composer_join_room":
+        return await handleJoinRoom(args);
+      case "composer_attach_room":
+        return handleAttachRoom(args);
+      case "composer_next_event":
+        return await handleNextEvent(args, signal);
+      case "composer_get_section":
+        return handleGetSection(args);
+      case "composer_get_full_doc":
+        return handleGetFullDoc(args);
+      case "composer_get_thread":
+        return handleGetThread(args);
+      case "composer_add_comment":
+        return handleAddComment(args);
+      case "composer_reply_comment":
+        return handleReplyComment(args);
+      case "composer_add_suggestion":
+        return handleAddSuggestion(args);
+      case "composer_reply_suggestion":
+        return handleReplySuggestion(args);
+      case "composer_resolve_thread":
+        return handleResolveThread(args);
+      default:
+        return errorResult(`unknown tool: ${name}`);
+    }
+  } finally {
+    state?.scheduleIdleDisconnect(3e4);
   }
 }
 function buildServer() {
@@ -5294,13 +5446,13 @@ function buildServer() {
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOL_DEFS
   }));
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
     const { name, arguments: args } = req.params;
     const roomId = args && typeof args === "object" && "roomId" in args ? args.roomId : void 0;
     const started = Date.now();
     log(`tool ${name} call`, { roomId });
     try {
-      const result = await dispatchTool(name, args);
+      const result = await dispatchTool(name, args, extra.signal);
       const elapsedMs = Date.now() - started;
       if (result.isError) {
         const detail = result.content[0]?.text ?? "";
@@ -5327,7 +5479,7 @@ async function startMcpServer() {
   log("mcp server starting", {
     pid: process.pid,
     node: process.version,
-    build: "awareness-heartbeat-v1"
+    build: "socket-driven-v1"
   });
   const server = buildServer();
   const transport = new StdioServerTransport();
@@ -5339,6 +5491,28 @@ async function startMcpServer() {
     logFile: LOG_FILE_PATH,
     pid: process.pid
   });
+  installShutdownHandlers("stdio");
+}
+function installShutdownHandlers(transport) {
+  let shuttingDown = false;
+  const shutdown = (reason) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    log(`mcp shutdown \u2014 ${reason}`, { transport });
+    try {
+      teardownAllRooms();
+    } catch (err) {
+      logError("teardownAllRooms failed", err);
+    }
+    setTimeout(() => process.exit(0), 200).unref?.();
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGHUP", () => shutdown("SIGHUP"));
+  if (transport === "stdio") {
+    process.stdin.on("end", () => shutdown("stdin-end"));
+    process.stdin.on("close", () => shutdown("stdin-close"));
+  }
 }
 async function startMcpHttpServer(opts) {
   installCrashHandlers();
@@ -5346,7 +5520,7 @@ async function startMcpHttpServer(opts) {
     port: opts.port,
     pid: process.pid,
     node: process.version,
-    build: "awareness-heartbeat-v1"
+    build: "socket-driven-v1"
   });
   const server = buildServer();
   const transport = new StreamableHTTPServerTransport({
@@ -5392,18 +5566,30 @@ async function startMcpHttpServer(opts) {
   appBase=${APP_BASE}`
     );
   });
-  const shutdown = () => {
-    log("mcp http server shutting down");
+  installShutdownHandlers("http");
+  const closeServer = () => {
     httpServer.close(() => process.exit(0));
     setTimeout(() => process.exit(0), 500).unref();
   };
-  process.on("SIGTERM", shutdown);
-  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", closeServer);
+  process.on("SIGINT", closeServer);
+  process.on("SIGHUP", closeServer);
 }
+var __test_dispatch = dispatchTool;
+var __test_setRoom = (id, state) => {
+  rooms.set(id, state);
+};
+var __test_clearRooms = () => {
+  rooms.clear();
+};
 
 export {
   loadOrCreateIdentity,
   logError,
+  teardownAllRooms,
   startMcpServer,
-  startMcpHttpServer
+  startMcpHttpServer,
+  __test_dispatch,
+  __test_setRoom,
+  __test_clearRooms
 };

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   logError,
   startMcpHttpServer,
   startMcpServer
-} from "./chunk-UVXQZ2TN.js";
+} from "./chunk-A5KBJAJW.js";
 
 // src/setup.ts
 import * as fs from "fs/promises";

package/dist/mcp.js

@@ -1,8 +1,16 @@
 import {
+  __test_clearRooms,
+  __test_dispatch,
+  __test_setRoom,
   startMcpHttpServer,
-  startMcpServer
-} from "./chunk-UVXQZ2TN.js";
+  startMcpServer,
+  teardownAllRooms
+} from "./chunk-A5KBJAJW.js";
 export {
+  __test_clearRooms,
+  __test_dispatch,
+  __test_setRoom,
   startMcpHttpServer,
-  startMcpServer
+  startMcpServer,
+  teardownAllRooms
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composer-app/mcp",
-  "version": "0.0.1-beta.4",
+  "version": "0.0.1-beta.5",
   "description": "Composer MCP",
   "license": "MIT",
   "author": "Josh Philpott",

package/skill/SKILL.md

@@ -36,13 +36,14 @@ two ordered steps — the field names encode the order:
    also carries the `@<your-name>` tagging hint. Relay it; you can
    paraphrase lightly but do not drop the URL or the mention syntax.
 2. `step2_callTool` — a structured `{ tool, args, why }` directive for
-   the follow-up `composer_next_event` call. Execute it AFTER step 1,
-   before ending your turn.
+   the `composer_next_event` loop. **Do not run it inline.** Hand the
+   loop to a background subagent (see "Monitor — runs in a subagent"
+   below). End your turn once the subagent is spawned.
 
 Skipping step 1 leaves the user without the URL — they have no way into
-the doc. Skipping step 2 leaves the room attached but silent; saying
-"I'm monitoring" without making the call is a lie, the agent will miss
-every mention.
+the doc. Skipping the subagent spawn leaves the room attached but
+silent; saying "I'm monitoring" without spawning the loop is a lie,
+every mention gets missed.
 
 **Seeding — prefer a file path when one exists.** Pick exactly one:
 
@@ -64,16 +65,63 @@ Triggers: a share prompt with a Composer URL, "/composer join <url>".
 Action: extract the URL from the prompt and call `composer_join_room({ url })`.
 Same first-run rule as Create. On success, the return carries the same
 ordered pair: output `step1_sayToUser` first (confirms the URL the user
-just joined), then execute `step2_callTool`.
-
-### 3. Monitor
-Triggers: "watch this doc", or automatically after join/create.
-Action: call `composer_next_event({ roomId })` in a loop (default timeout
-is 10 minutes). **The loop is always-on.** Every return carries a
-structured directive — follow it without waiting for user input.
+just joined), then spawn the monitor subagent — same flow as Create
+(see "Monitor — runs in a subagent" below).
+
+### 3. Monitor — runs in a subagent
+
+Triggers: "watch this doc", or automatically after create/join.
+
+The monitor loop is delegated to a background subagent. Polling
+`composer_next_event` from the main thread fills the conversation
+context with idle-tick chatter and mention-handling that belongs in
+the doc, not the terminal. Spawn the subagent, end your turn, let the
+doc be the conversation.
+
+**How to spawn (Claude Code).** Use the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"` — short, identifies the room
+- `prompt`: the template below, with `{roomId}` and `{actingAs}` filled in
+
+Prompt template:
+
+> Invoke the composer skill, then run the monitor loop for room
+> `{roomId}` as `{actingAs}`. Your only job is the in-doc conversation:
+> call `composer_next_event({ roomId: "{roomId}" })` and follow each
+> return's `requiredNextToolCall` directive verbatim, looping until the
+> goodbye branch fires.
+>
+> All write tools (`composer_add_comment`, `composer_add_suggestion`,
+> `composer_reply_comment`, `composer_reply_suggestion`,
+> `composer_resolve_thread`) are yours to use as the skill describes.
+> The doc IS your conversation — do not narrate to the parent between
+> ticks.
+>
+> Exit and return when ANY of these happen:
+> 1. `composer_next_event` returns `kind: "timeout"` with
+>    `recentActivity: false` — say `userMessage` EXACTLY in the doc
+>    (it's the goodbye line), then exit.
+> 2. A request inside the doc clearly needs the parent terminal
+>    (a code change, a shell command, an external action the parent
+>    would do). Post a short reply: "I'll get on this in the terminal,"
+>    then exit with a one-sentence summary of the ask.
+> 3. An unrecoverable error (auth lost, room destroyed). Exit with
+>    the error.
+
+**Main thread after spawning.** Turn ends. Do **not** also call
+`composer_next_event` — two listeners on the same room means duplicated
+replies. If the user asks "what's happening in Composer?", check the
+subagent's status (`TaskList` / `TaskOutput`) rather than re-entering
+the loop yourself.
+
+**Inside the loop (what the subagent does).** Default timeout is 30
+seconds. Every return carries a structured directive — follow it
+without waiting for user input.
 
 On `mention`: handle the event (reply / suggestion / resolve as needed),
-output any user-facing text, then execute `requiredNextToolCall` — which
+output any in-doc action, then execute `requiredNextToolCall` — which
 is another `composer_next_event` call. Do not pause for the user to
 acknowledge. The doc is the conversation.
 
@@ -82,9 +130,8 @@ On `timeout`: check `recentActivity`.
   Execute it — the user is still working, just not tagging you.
 - `recentActivity: false` → the return includes `userMessage` and
   `instruction` but NO `requiredNextToolCall`. Say `userMessage`
-  EXACTLY ("I've left the document…") and stop calling
-  `composer_next_event` until the user asks you to rejoin. Do not
-  paraphrase — users recognize the line across sessions.
+  EXACTLY ("I've left the document…") and exit (per exit rule 1
+  above). Do not paraphrase — users recognize the line across sessions.
 
 On `mention`, the event contains everything you need to act in one turn:
 
@@ -134,8 +181,12 @@ need to catch up on what's already been said.
   When in doubt, reply — the user can always ignore you.
 
 ### 4. Act
-Triggers: direct requests like "add a summary to section 2".
-Action: already attached; call the write tools and report back concisely.
+Triggers: direct requests in the terminal like "add a summary to section 2".
+Action: the main thread is also attached to the room — call the write
+tools from here and report back concisely. Don't hand terminal directives
+to the monitor subagent; the subagent handles in-doc mentions, the main
+thread handles in-terminal asks. They share the same MCP, so writes from
+either show up in the doc.
 
 ## Tools