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

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

@@ -3833,7 +3833,9 @@ function getElementText(el) {
   let out = "";
   for (const child of el.toArray()) {
     if (child instanceof Y2.XmlText) {
-      out += child.toString();
+      for (const op of child.toDelta()) {
+        if (typeof op.insert === "string") out += op.insert;
+      }
     } else if (isXmlElement(child)) {
       out += getElementText(child);
     }
@@ -3879,6 +3881,31 @@ function getOutline(doc) {
   });
   return outline;
 }
+function getSectionBlockRange(doc, headingId) {
+  const blocks = topLevelBlocks(doc);
+  let startIndex = -1;
+  let startLevel = 0;
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    if (block.nodeName !== "heading") continue;
+    const id = makeHeadingId(getElementText(block), i);
+    if (id === headingId) {
+      startIndex = i;
+      startLevel = getHeadingLevel(block);
+      break;
+    }
+  }
+  if (startIndex === -1) return null;
+  let endIndex = blocks.length;
+  for (let i = startIndex + 1; i < blocks.length; i++) {
+    const block = blocks[i];
+    if (block.nodeName === "heading" && getHeadingLevel(block) <= startLevel) {
+      endIndex = i;
+      break;
+    }
+  }
+  return { start: startIndex, end: endIndex };
+}
 function getSection(doc, headingId) {
   const blocks = topLevelBlocks(doc);
   let startIndex = -1;
@@ -3922,17 +3949,33 @@ import * as Y3 from "yjs";
 function buildFlatMap(fragment) {
   let flat = "";
   const map = [];
+  const blockFlatStarts = [];
   const walk = (node) => {
     if (node instanceof Y3.XmlText) {
-      const text = node.toString();
-      for (let i = 0; i < text.length; i++) {
-        map.push({
-          xmlText: node,
-          offsetInText: i,
-          flatIndex: flat.length + i
-        });
+      let localOffset = 0;
+      for (const op of node.toDelta()) {
+        const value = op.insert;
+        if (typeof value === "string") {
+          const base = flat.length;
+          for (let i = 0; i < value.length; i++) {
+            map.push({
+              xmlText: node,
+              offsetInText: localOffset + i,
+              flatIndex: base + i
+            });
+          }
+          flat += value;
+          localOffset += value.length;
+        } else if (value !== void 0) {
+          map.push({
+            xmlText: node,
+            offsetInText: localOffset,
+            flatIndex: flat.length
+          });
+          flat += "\uFFFC";
+          localOffset += 1;
+        }
       }
-      flat += text;
       return;
     }
     for (const child of node.toArray()) {
@@ -3943,6 +3986,7 @@ function buildFlatMap(fragment) {
   };
   const topLevel = fragment.toArray();
   topLevel.forEach((node, idx) => {
+    blockFlatStarts.push(flat.length);
     if (node instanceof Y3.XmlText || node instanceof Y3.XmlElement) {
       walk(node);
     }
@@ -3950,7 +3994,7 @@ function buildFlatMap(fragment) {
       flat += "\n";
     }
   });
-  return { flat, map };
+  return { flat, map, blockFlatStarts };
 }
 function findNthOccurrence(flat, needle, n) {
   if (needle.length === 0) return null;
@@ -4068,11 +4112,23 @@ function resolveServerAnchor(doc, spec) {
     return { ok: false, error: "text_not_found", currentSectionText };
   }
   const fragment = doc.getXmlFragment("default");
-  const { flat, map } = buildFlatMap(fragment);
-  const flatStart = findNthOccurrence(flat, spec.textToFind, occurrence);
-  if (flatStart === null) {
+  const { flat, map, blockFlatStarts } = buildFlatMap(fragment);
+  const range = getSectionBlockRange(doc, spec.headingId);
+  if (!range) {
+    return {
+      ok: false,
+      error: "section_not_found",
+      currentSectionText
+    };
+  }
+  const sectionFlatStart = blockFlatStarts[range.start] ?? 0;
+  const sectionFlatEnd = range.end < blockFlatStarts.length ? blockFlatStarts[range.end] : flat.length;
+  const sectionFlat = flat.slice(sectionFlatStart, sectionFlatEnd);
+  const sectionRelStart = findNthOccurrence(sectionFlat, spec.textToFind, occurrence);
+  if (sectionRelStart === null) {
     return { ok: false, error: "text_not_found", currentSectionText };
   }
+  const flatStart = sectionFlatStart + sectionRelStart;
   const flatEnd = flatStart + spec.textToFind.length;
   const startEntry = lookupFlatIndex(map, flatStart);
   if (!startEntry) {
@@ -4116,16 +4172,29 @@ var RoomState = class {
   /**
    * Threads the agent has already written to (created a comment, added a
    * suggestion, or replied). Once a thread is "active", subsequent remote
-   * replies on it are surfaced to the model even if they don't say
-   * `@agent` — the conversation is already in progress, and requiring a
+   * replies on it are surfaced to the model even if they don't name the
+   * agent — the conversation is already in progress, and requiring a
    * re-mention every turn is bad UX.
    */
   activeThreads = /* @__PURE__ */ new Set();
+  /**
+   * Timestamp (ms since epoch) of the most recent non-local transaction on
+   * this doc. Initialized to construction time so a freshly-attached room
+   * with an idle user bails out after the first full timeout window rather
+   * than looking "fresh" forever. Bumped by `attachRemoteActivityTracker`
+   * on every remote edit, comment, suggestion, or activity-feed write.
+   */
+  _lastRemoteActivityAt = Date.now();
   constructor(opts) {
     this.roomId = opts.roomId;
     this.actingAs = opts.actingAs;
     this.identity = opts.identity;
     this.watchMentions();
+    attachRemoteActivityTracker(this.doc, {
+      onActivity: (at) => {
+        this._lastRemoteActivityAt = at;
+      }
+    });
     this.provider = new YProvider(opts.serverHost, opts.roomId, this.doc, {
       party: "composer-room",
       connect: true,
@@ -4225,12 +4294,16 @@ var RoomState = class {
   }
   /**
    * Mark a thread as active so subsequent remote replies on it surface as
-   * mentions even without an explicit `@agent`. Called by MCP write-tool
-   * handlers right after the agent creates or replies on a thread.
+   * mentions even without an explicit mention of this agent. Called by MCP
+   * write-tool handlers right after the agent creates or replies on a thread.
    */
   markThreadActive(threadId) {
     this.activeThreads.add(threadId);
   }
+  /** Timestamp (ms) of the most recent non-local transaction on this doc. */
+  get lastRemoteActivityAt() {
+    return this._lastRemoteActivityAt;
+  }
   enqueue(ev) {
     const waiter = this.waiters.shift();
     if (waiter) waiter(ev);
@@ -4241,20 +4314,60 @@ var RoomState = class {
       enqueue: (ev) => this.enqueue(ev),
       seen: this.seen,
       activeThreads: this.activeThreads,
-      identityUserId: this.identity.userId
+      identityUserId: this.identity.userId,
+      actingAs: this.actingAs,
+      getSoloHumanAuthorId: () => this.computeSoloHumanAuthorId()
     });
   }
+  /**
+   * Read the provider's awareness map and decide whether the room is "solo"
+   * right now — exactly one agent (us) and exactly one human. Returns the
+   * sole human's `userId` in that case, else `undefined`. Any other shape
+   * (multiple humans, multiple agents, empty, no `user` payload) returns
+   * `undefined` so the observer stays silent unless the gate passes.
+   */
+  computeSoloHumanAuthorId() {
+    const states = this.provider.awareness.getStates();
+    let humanCount = 0;
+    let agentCount = 0;
+    let soloHuman;
+    for (const state of states.values()) {
+      const user = state?.user;
+      if (!user || typeof user.userId !== "string") continue;
+      if (user.isAgent) {
+        agentCount++;
+      } else {
+        humanCount++;
+        soloHuman = user.userId;
+      }
+    }
+    if (humanCount !== 1 || agentCount !== 1) return void 0;
+    return soloHuman;
+  }
 };
-var AGENT_MENTION_RE = /@agent/i;
-var hasAgentMention = (text) => AGENT_MENTION_RE.test(text);
+function buildActingAsMatcher(actingAs) {
+  if (!actingAs) return () => false;
+  const escaped = actingAs.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`@${escaped}(?![\\w])`, "i");
+  return (text) => re.test(text);
+}
+function checkMentionsSidecar(mentions, identityUserId) {
+  if (!Array.isArray(mentions) || mentions.length === 0) return "absent";
+  if (identityUserId && mentions.includes(identityUserId)) return "hit";
+  return "miss";
+}
+var ANY_AT_MENTION_RE = /@\w/;
 function attachMentionObserver(doc, opts) {
   const seen = opts.seen ?? /* @__PURE__ */ new Set();
   const activeThreads = opts.activeThreads ?? /* @__PURE__ */ new Set();
   const enqueue = opts.enqueue;
   const identityUserId = opts.identityUserId;
+  const hasActingAsMention = buildActingAsMatcher(opts.actingAs);
+  const getSoloHumanAuthorId = opts.getSoloHumanAuthorId ?? (() => void 0);
   const scan = (kind, threadId, entry, isLocal) => {
     if (!entry || typeof entry !== "object") return;
     const record = entry;
+    const bodyAuthorUserId = typeof record.authorUserId === "string" ? record.authorUserId : void 0;
     const replies = Array.isArray(record.replies) ? record.replies : [];
     let lastAgentIdx = -1;
     if (identityUserId !== void 0) {
@@ -4268,7 +4381,9 @@ function attachMentionObserver(doc, opts) {
     }
     const bodyAnswered = lastAgentIdx >= 0;
     const body = typeof record.text === "string" ? record.text : typeof record.replacementText === "string" ? record.replacementText : "";
-    if (hasAgentMention(body) && !seen.has(threadId)) {
+    const bodySidecar = checkMentionsSidecar(record.mentions, identityUserId);
+    const bodyHit = bodySidecar === "hit" || bodySidecar === "absent" && hasActingAsMention(body);
+    if (bodyHit && !seen.has(threadId)) {
       seen.add(threadId);
       if (!isLocal && !bodyAnswered) {
         enqueue({
@@ -4280,6 +4395,19 @@ function attachMentionObserver(doc, opts) {
           ...resolveAnchoredContext(doc, record.anchorFrom, record.anchorTo)
         });
       }
+    } else if (!seen.has(threadId) && !isLocal && !bodyAnswered && bodySidecar !== "miss" && !ANY_AT_MENTION_RE.test(body)) {
+      const soloHuman = getSoloHumanAuthorId();
+      if (soloHuman && bodyAuthorUserId === soloHuman) {
+        seen.add(threadId);
+        enqueue({
+          kind: "mention",
+          threadId,
+          threadKind: kind,
+          threadText: body,
+          reason: "solo_room",
+          ...resolveAnchoredContext(doc, record.anchorFrom, record.anchorTo)
+        });
+      }
     }
     for (let i = 0; i < replies.length; i++) {
       const r = replies[i];
@@ -4292,16 +4420,25 @@ function attachMentionObserver(doc, opts) {
       seen.add(key);
       if (isLocal) continue;
       if (i <= lastAgentIdx) continue;
-      const isDirect = hasAgentMention(reply.text);
+      const replySidecar = checkMentionsSidecar(reply.mentions, identityUserId);
+      const isDirect = replySidecar === "hit" || replySidecar === "absent" && hasActingAsMention(reply.text);
       const inActiveThread = activeThreads.has(threadId);
-      if (!isDirect && !inActiveThread) continue;
+      let reason = isDirect ? "direct_mention" : inActiveThread ? "active_thread" : null;
+      if (!reason) {
+        const replyAuthor = typeof reply.authorUserId === "string" ? reply.authorUserId : void 0;
+        const soloHuman = getSoloHumanAuthorId();
+        if (replySidecar !== "miss" && !ANY_AT_MENTION_RE.test(reply.text) && soloHuman && replyAuthor === soloHuman) {
+          reason = "solo_room";
+        }
+      }
+      if (!reason) continue;
       enqueue({
         kind: "mention",
         threadId,
         threadKind: kind,
         threadText: reply.text,
         replyId: reply.id,
-        reason: isDirect ? "direct_mention" : "active_thread",
+        reason,
         ...resolveAnchoredContext(doc, record.anchorFrom, record.anchorTo)
       });
     }
@@ -4320,6 +4457,12 @@ function attachMentionObserver(doc, opts) {
 function hashState(doc) {
   return Buffer.from(Y4.encodeStateVector(doc)).toString("base64");
 }
+function attachRemoteActivityTracker(doc, opts) {
+  const now = opts.now ?? (() => Date.now());
+  doc.on("afterTransaction", (tr) => {
+    if (!tr.local) opts.onActivity(now());
+  });
+}
 
 // src/identity.ts
 import * as fs from "fs/promises";
@@ -4352,7 +4495,9 @@ function pickColor() {
 function isValidIdentity(value) {
   if (typeof value !== "object" || value === null) return false;
   const v = value;
-  return typeof v.userId === "string" && typeof v.color === "string";
+  if (typeof v.userId !== "string" || typeof v.color !== "string") return false;
+  if (v.name !== void 0 && typeof v.name !== "string") return false;
+  return true;
 }
 async function loadOrCreateIdentity(dir) {
   const filePath = path.join(dir, FILE_NAME);
@@ -4360,18 +4505,16 @@ async function loadOrCreateIdentity(dir) {
     const raw = await fs.readFile(filePath, "utf8");
     const parsed = JSON.parse(raw);
     if (isValidIdentity(parsed)) {
-      if (isPaletteColor(parsed.color)) {
-        return { userId: parsed.userId, color: parsed.color };
-      }
-      const migrated = {
+      const base = {
         userId: parsed.userId,
-        color: pickColor()
+        color: isPaletteColor(parsed.color) ? parsed.color : pickColor(),
+        ...parsed.name ? { name: parsed.name } : {}
       };
-      await fs.mkdir(dir, { recursive: true });
-      await fs.writeFile(filePath, JSON.stringify(migrated, null, 2), {
-        mode: FILE_MODE
-      });
-      return migrated;
+      if (base.color === parsed.color) {
+        return base;
+      }
+      await saveIdentity(dir, base);
+      return base;
     }
   } catch (err) {
     const code = err.code;
@@ -4382,11 +4525,15 @@ async function loadOrCreateIdentity(dir) {
     userId: nanoid2(),
     color: pickColor()
   };
+  await saveIdentity(dir, identity);
+  return identity;
+}
+async function saveIdentity(dir, identity) {
+  const filePath = path.join(dir, FILE_NAME);
   await fs.mkdir(dir, { recursive: true });
   await fs.writeFile(filePath, JSON.stringify(identity, null, 2), {
     mode: FILE_MODE
   });
-  return identity;
 }
 
 // src/mdToFragment.ts
@@ -4464,6 +4611,30 @@ async function getIdentity() {
   }
   return identityCache;
 }
+async function resolveActingAs(actingAsArg) {
+  const identity = await getIdentity();
+  if (identity.name) return { actingAs: identity.name, isFirstRun: false };
+  if (!actingAsArg) {
+    throw new Error(
+      [
+        "First Composer room on this machine \u2014 you need a persistent name before proceeding. STOP and ask the user what to call you.",
+        "",
+        "Offer ONE suggested default they can accept with a tap:",
+        `  - If you know the user's first name from conversation context, suggest "<FirstName>'s Agent" (e.g. "Josh's Agent").`,
+        "  - Otherwise pick something playful from outside the model-family space (e.g. Monty, Gerty, Rosie, Otto, Pip). Do NOT suggest Claude / Gemini / GPT / Sonnet / Opus / Haiku / other model names.",
+        "",
+        `Phrase it like: "I'll go by <suggested name> in Composer docs \u2014 sound good, or pick your own?"`,
+        "",
+        "Retry with their answer as `actingAs`. It persists to ~/.composer/user.json and is reused for every future room on this machine, so only ask once."
+      ].join("\n")
+    );
+  }
+  const next = { ...identity, name: actingAsArg };
+  await saveIdentity(COMPOSER_DIR2, next);
+  identityCache = next;
+  log("agent name persisted", { name: actingAsArg, userId: identity.userId });
+  return { actingAs: actingAsArg, isFirstRun: true };
+}
 function getOrError(roomId) {
   const state = rooms.get(roomId);
   if (!state) throw new Error(`not attached to room: ${roomId}`);
@@ -4482,7 +4653,7 @@ function parseRoomIdFromUrl(url) {
 var TOOL_DEFS = [
   {
     name: "composer_create_room",
-    description: "Create a new Composer room. Returns { roomId, browserUrl, snapshot }. Seed the doc by passing either `seedMarkdownPath` (absolute path to a markdown file on disk \u2014 preferred when the markdown already lives in a file, avoids streaming the content through the model) OR `seedMarkdown` (inline string, for content you generated in-turn). Pass exactly one. The seed file is read once at creation and never written back \u2014 edits in Composer stay in the room.",
+    description: "Create a new Composer room. Returns { roomId, browserUrl, snapshot, actingAs, step1_sayToUser, step2_callTool }. EXECUTE step1 AND step2 IN ORDER before ending your turn: first output `step1_sayToUser` (it contains the browserUrl \u2014 the user needs that link or they can't open the doc), then call the tool named in `step2_callTool`. Skipping step2 means your agent is silent in the room; skipping step1 means the user has no way in. Seed the doc by passing either `seedMarkdownPath` (absolute path to a markdown file on disk \u2014 preferred when the markdown already lives in a file, avoids streaming the content through the model) OR `seedMarkdown` (inline string, for content you generated in-turn). Pass exactly one. The seed file is read once at creation and never written back \u2014 edits in Composer stay in the room.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4497,22 +4668,24 @@ var TOOL_DEFS = [
         },
         actingAs: {
           type: "string",
-          description: `Agent display name for this room, e.g. "Josh's Agent".`
+          description: 'Your display name in the doc. FIRST-RUN FLOW: if you haven\'t saved a name yet, do NOT guess \u2014 call without `actingAs`, the MCP returns an error that instructs you to ask the user. Ask them ("what should I be called in Composer?") and retry with their answer. The name persists to ~/.composer/user.json. OPTIONAL on subsequent calls \u2014 the stored name wins and any value here is ignored.'
         }
-      },
-      required: ["actingAs"]
+      }
     }
   },
   {
     name: "composer_join_room",
-    description: "Join an existing Composer room by browser URL. Returns the attach snapshot.",
+    description: "Join an existing Composer room by browser URL. Returns { roomId, browserUrl, snapshot, actingAs, step1_sayToUser, step2_callTool }. EXECUTE step1 AND step2 IN ORDER before ending your turn: first output `step1_sayToUser` (it contains the browserUrl so the user can confirm which doc you joined), then call the tool named in `step2_callTool`. Skipping step2 means your agent is silent in the room; skipping step1 leaves the user guessing which doc you landed in.",
     inputSchema: {
       type: "object",
       properties: {
         url: { type: "string" },
-        actingAs: { type: "string" }
+        actingAs: {
+          type: "string",
+          description: "Your display name in the doc. FIRST-RUN FLOW: if you haven't saved a name yet, call without `actingAs`, get the error, ASK THE USER what to be called, then retry with their answer. Persists to ~/.composer/user.json. OPTIONAL on subsequent calls \u2014 the stored name wins."
+        }
       },
-      required: ["url", "actingAs"]
+      required: ["url"]
     }
   },
   {
@@ -4526,12 +4699,12 @@ var TOOL_DEFS = [
   },
   {
     name: "composer_next_event",
-    description: "Block until a remote @agent mention arrives or the timeout elapses.",
+    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`.",
     inputSchema: {
       type: "object",
       properties: {
         roomId: { type: "string" },
-        timeoutSec: { type: "number", default: 300 }
+        timeoutSec: { type: "number", default: 600 }
       },
       required: ["roomId"]
     }
@@ -4557,9 +4730,21 @@ var TOOL_DEFS = [
       required: ["roomId"]
     }
   },
+  {
+    name: "composer_get_thread",
+    description: "Read the full state of a comment or suggestion thread by id. Returns the body (or replacementText), every reply (with author, text, timestamp, optional mentions sidecar), the thread's anchored text, and the containing section as markdown. Use when `composer_next_event` surfaces an event and you need history: the event only gives you the triggering message, so call this to catch up on everything said before you were tagged.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        roomId: { type: "string" },
+        threadId: { type: "string" }
+      },
+      required: ["roomId", "threadId"]
+    }
+  },
   {
     name: "composer_add_comment",
-    description: "Post a comment anchored to a text span. Anchor is { headingId, textToFind, occurrence? }. Returns { id } on success or an isError result if the anchor cannot be resolved.",
+    description: "Post a new top-level comment anchored to a text span anywhere in the doc. Anchor is { headingId, textToFind, occurrence? }. Use this to flag something the user didn't ask about \u2014 cross-referencing related sections, raising a concern elsewhere in the doc, or seeding a thread on a new span. Use `composer_reply_comment` instead when continuing an existing thread. Returns { id } on success or an isError result if the anchor cannot be resolved.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4593,7 +4778,7 @@ var TOOL_DEFS = [
   },
   {
     name: "composer_add_suggestion",
-    description: "Post a text replacement suggestion. When responding to a thread, default to passing fromThreadId \u2014 the suggestion inherits the source thread's exact stored anchor, which is the right span whenever the user's request is scoped to what they selected (the common case). Supply an `anchor` instead when the user's request explicitly targets a different span (e.g. they highlight one word but ask to rewrite the whole paragraph), or for proactive suggestions with no source thread. Pick one: supplying both is rejected. Returns { id } on success or an isError result if the anchor cannot be resolved.",
+    description: "Post a text replacement suggestion. A suggestion can target ANY span anywhere in the doc \u2014 not just the span of the thread that triggered you. Pick exactly one of:\n  - `fromThreadId` \u2014 inherit the source thread's exact stored anchor. Right when the user's request is scoped to what they selected (the common case: 'rewrite this', 'make this shorter').\n  - `anchor` \u2014 specify a span yourself via `{ headingId, textToFind, occurrence? }`. Use this when the user's request targets different text ('also update the intro', 'the bullet list in Section 3 is stale') OR for proactive suggestions with no source thread.\n**Anchor = what gets deleted.** Your `textToFind` is literally cut when the user accepts and `replacementText` is inserted in its place. Anchor the whole unit you're changing (full sentence including terminal punctuation; full list item text; full paragraph), match your replacementText's shape (inline for mid-paragraph edits, full markdown block for block replacements), end replacement at the same boundary as the anchor, and include any formatting you want preserved in the replacement itself \u2014 the anchor's bold / link / heading level is gone on accept. A too-narrow or mid-token anchor leaves broken spacing or smashed-together words. See SKILL.md 'Pick the right span' for the full rubric.\n**Ripple coverage is your responsibility.** If the change requires edits nearby or elsewhere (enumeration counts, cross-references, subject/verb agreement, restated facts), call this tool MULTIPLE times in the same turn \u2014 one suggestion per span \u2014 so accepting leaves the doc correct. If you're unsure whether ripples exist elsewhere in the doc, call `composer_get_full_doc` first. Returns { id } on success or an isError result if the anchor cannot be resolved.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4688,9 +4873,25 @@ function asAnchor(value) {
   }
   return { headingId, textToFind, occurrence };
 }
+function buildMonitorHandoff(roomId, browserUrl, actingAs, opts) {
+  const mention = `@${actingAs}`;
+  const step1_sayToUser = opts.isFirstRun ? `${browserUrl}
+
+First time using Composer? Here's how it works: I'm monitoring this doc right here in your terminal. Reach me anytime by tagging ${mention} in any comment or reply \u2014 I'll answer right in the thread, and I can also post suggestions you accept or reject inline.` : `${browserUrl}
+
+I'm monitoring this doc from the terminal \u2014 tag me with ${mention} in any comment and I'll reply right there.`;
+  return {
+    step1_sayToUser,
+    step2_callTool: {
+      tool: "composer_next_event",
+      args: { roomId },
+      why: "MANDATORY and STRICTLY AFTER step 1. First output `step1_sayToUser` to the user \u2014 they need the URL to open the doc \u2014 THEN call this tool. The room is attached but NOT being watched until you enter the composer_next_event loop. Two failure modes to avoid: (a) outputting 'I'm monitoring' without calling this tool = silent agent; (b) calling this tool without first outputting the URL = user has no way in."
+    }
+  };
+}
 async function handleCreateRoom(args) {
   const a = asObject(args);
-  const actingAs = asString(a.actingAs, "actingAs");
+  const actingAsArg = asOptionalString(a.actingAs, "actingAs");
   const seedMarkdownInline = asOptionalString(a.seedMarkdown, "seedMarkdown");
   const seedMarkdownPath = asOptionalString(
     a.seedMarkdownPath,
@@ -4716,8 +4917,10 @@ async function handleCreateRoom(args) {
       return errorResult(`failed to read seedMarkdownPath: ${message}`);
     }
   }
+  const { actingAs, isFirstRun } = await resolveActingAs(actingAsArg);
   const identity = await getIdentity();
   const roomId = nanoid3(10);
+  const browserUrl = browserUrlFor(roomId);
   const state = new RoomState({
     roomId,
     serverHost: SERVER_HOST,
@@ -4729,22 +4932,42 @@ async function handleCreateRoom(args) {
     writeMarkdownToFragment(state.doc.getXmlFragment("default"), seedMarkdown);
   }
   rooms.set(roomId, state);
+  log(`composer room created \u2192 ${browserUrl}`, { roomId, actingAs });
   return okResult({
     roomId,
-    browserUrl: browserUrlFor(roomId),
-    snapshot: state.snapshot()
+    browserUrl,
+    actingAs,
+    snapshot: state.snapshot(),
+    ...buildMonitorHandoff(roomId, browserUrl, actingAs, { isFirstRun })
   });
 }
 async function handleJoinRoom(args) {
   const a = asObject(args);
   const url = asString(a.url, "url");
-  const actingAs = asString(a.actingAs, "actingAs");
+  const actingAsArg = asOptionalString(a.actingAs, "actingAs");
   const roomId = parseRoomIdFromUrl(url);
-  const identity = await getIdentity();
+  const browserUrl = browserUrlFor(roomId);
   const existing = rooms.get(roomId);
   if (existing) {
-    return okResult({ roomId, snapshot: existing.snapshot() });
+    log(`composer room rejoined \u2192 ${browserUrl}`, {
+      roomId,
+      actingAs: existing.actingAs
+    });
+    return okResult({
+      roomId,
+      browserUrl,
+      actingAs: existing.actingAs,
+      snapshot: existing.snapshot(),
+      // Rejoining a room already attached in this process is never a
+      // first-run situation — we already wrote a name to disk at least
+      // once in this process lifetime to have created `existing`.
+      ...buildMonitorHandoff(roomId, browserUrl, existing.actingAs, {
+        isFirstRun: false
+      })
+    });
   }
+  const { actingAs, isFirstRun } = await resolveActingAs(actingAsArg);
+  const identity = await getIdentity();
   const state = new RoomState({
     roomId,
     serverHost: SERVER_HOST,
@@ -4753,7 +4976,14 @@ async function handleJoinRoom(args) {
   });
   await state.waitForInitialSync();
   rooms.set(roomId, state);
-  return okResult({ roomId, snapshot: state.snapshot() });
+  log(`composer room joined \u2192 ${browserUrl}`, { roomId, actingAs });
+  return okResult({
+    roomId,
+    browserUrl,
+    actingAs,
+    snapshot: state.snapshot(),
+    ...buildMonitorHandoff(roomId, browserUrl, actingAs, { isFirstRun })
+  });
 }
 function handleAttachRoom(args) {
   const a = asObject(args);
@@ -4761,13 +4991,46 @@ function handleAttachRoom(args) {
   const state = getOrError(roomId);
   return okResult({ roomId, snapshot: state.snapshot() });
 }
+var ACTIVITY_WINDOW_MS = 10 * 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) {
   const a = asObject(args);
   const roomId = asString(a.roomId, "roomId");
-  const timeoutSec = typeof a.timeoutSec === "number" && Number.isFinite(a.timeoutSec) ? a.timeoutSec : 300;
+  const timeoutSec = typeof a.timeoutSec === "number" && Number.isFinite(a.timeoutSec) ? a.timeoutSec : 600;
   const state = getOrError(roomId);
   const event = await state.nextEvent(timeoutSec * 1e3);
-  return okResult(event);
+  if (event.kind === "mention") {
+    return okResult({
+      ...event,
+      requiredNextToolCall: {
+        tool: "composer_next_event",
+        args: { roomId },
+        why: "MANDATORY \u2014 call this immediately after you've posted your reply / suggestion / resolve. The monitor loop is always-on; ending your turn without this call drops you out of the room and the user will think you stopped listening."
+      }
+    });
+  }
+  const msSinceActivity = Date.now() - state.lastRemoteActivityAt;
+  const recentActivity = msSinceActivity < ACTIVITY_WINDOW_MS;
+  const minutesSince = Math.max(1, Math.round(msSinceActivity / 6e4));
+  if (recentActivity) {
+    return okResult({
+      kind: "timeout",
+      recentActivity: true,
+      secondsSinceActivity: Math.round(msSinceActivity / 1e3),
+      requiredNextToolCall: {
+        tool: "composer_next_event",
+        args: { roomId },
+        why: `MANDATORY \u2014 call this immediately. The user was active in the doc ~${minutesSince} minute${minutesSince === 1 ? "" : "s"} ago; do NOT exit the monitor loop.`
+      }
+    });
+  }
+  return okResult({
+    kind: "timeout",
+    recentActivity: false,
+    secondsSinceActivity: Math.round(msSinceActivity / 1e3),
+    userMessage: LEAVE_MESSAGE,
+    instruction: `Say \`userMessage\` EXACTLY as written \u2014 do not paraphrase the goodbye. Then stop calling composer_next_event until the user asks you to rejoin. No requiredNextToolCall field: the loop is intentionally over.`
+  });
 }
 function handleGetSection(args) {
   const a = asObject(args);
@@ -4783,6 +5046,55 @@ function handleGetFullDoc(args) {
   const state = getOrError(roomId);
   return okResult({ markdown: serializeDocAsMarkdown(state.doc) });
 }
+function handleGetThread(args) {
+  const a = asObject(args);
+  const roomId = asString(a.roomId, "roomId");
+  const threadId = asString(a.threadId, "threadId");
+  const state = getOrError(roomId);
+  const commentRaw = state.doc.getMap("comments").get(threadId);
+  const suggestionRaw = state.doc.getMap("suggestions").get(threadId);
+  const raw = commentRaw ?? suggestionRaw;
+  if (!raw) {
+    return errorResult(`thread not found: ${threadId}`);
+  }
+  const kind = commentRaw ? "comment" : "suggestion";
+  const anchoredContext = resolveAnchoredContext(
+    state.doc,
+    raw.anchorFrom,
+    raw.anchorTo
+  );
+  const replies = Array.isArray(raw.replies) ? raw.replies : [];
+  const shapedReplies = replies.filter(
+    (r) => !!r && typeof r === "object" && typeof r.id === "string" && typeof r.text === "string"
+  ).map((r) => ({
+    id: r.id,
+    text: r.text,
+    authorName: typeof r.authorName === "string" ? r.authorName : void 0,
+    authorUserId: typeof r.authorUserId === "string" ? r.authorUserId : void 0,
+    authorIsAgent: typeof r.authorIsAgent === "boolean" ? r.authorIsAgent : void 0,
+    mentions: Array.isArray(r.mentions) ? r.mentions.filter((m) => typeof m === "string") : void 0,
+    createdAt: typeof r.createdAt === "number" ? r.createdAt : void 0
+  }));
+  return okResult({
+    threadId,
+    kind,
+    body: typeof raw.text === "string" ? raw.text : void 0,
+    replacementText: kind === "suggestion" && typeof raw.replacementText === "string" ? raw.replacementText : void 0,
+    originalText: kind === "suggestion" && typeof raw.originalText === "string" ? raw.originalText : void 0,
+    authorName: typeof raw.authorName === "string" ? raw.authorName : void 0,
+    authorUserId: typeof raw.authorUserId === "string" ? raw.authorUserId : void 0,
+    authorIsAgent: typeof raw.authorIsAgent === "boolean" ? raw.authorIsAgent : void 0,
+    createdAt: typeof raw.createdAt === "number" ? raw.createdAt : void 0,
+    resolved: kind === "comment" && typeof raw.resolved === "boolean" ? raw.resolved : void 0,
+    status: kind === "suggestion" && (raw.status === "pending" || raw.status === "accepted" || raw.status === "rejected") ? raw.status : void 0,
+    mentions: Array.isArray(raw.mentions) ? raw.mentions.filter((m) => typeof m === "string") : void 0,
+    anchoredText: anchoredContext.anchoredText,
+    headingId: anchoredContext.headingId,
+    headingText: anchoredContext.headingText,
+    sectionMarkdown: anchoredContext.sectionMarkdown,
+    replies: shapedReplies
+  });
+}
 function handleAddComment(args) {
   const a = asObject(args);
   const roomId = asString(a.roomId, "roomId");
@@ -4958,6 +5270,8 @@ async function dispatchTool(name, args) {
       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":

package/dist/cli.js

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

package/dist/mcp.js

@@ -1,7 +1,7 @@
 import {
   startMcpHttpServer,
   startMcpServer
-} from "./chunk-VVYEIOFH.js";
+} from "./chunk-UVXQZ2TN.js";
 export {
   startMcpHttpServer,
   startMcpServer

package/package.json

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

package/skill/SKILL.md

@@ -12,8 +12,37 @@ to create, join, monitor, or act in a Composer doc.
 
 ### 1. Create
 Triggers: "send this markdown to Composer", "make a Composer doc with this".
-Action: call `composer_create_room({ name, actingAs: "<user's name>'s Agent", ... })`.
-Return the `browserUrl`. You are already attached; enter monitor mode.
+Action: call `composer_create_room({ ... })`.
+
+**First run only — ask the user what to call you.** If you have no saved
+name on this machine, the MCP returns an error instructing you to stop
+and ask. Offer one suggested default they can accept with a tap:
+
+- If you know the user's first name, suggest `"<FirstName>'s Agent"`
+  (e.g. `"Josh's Agent"`).
+- Otherwise suggest something playful that isn't a model family — `Monty`,
+  `Gerty`, `Rosie`, `Otto`, `Pip`. Do **not** suggest Claude, Gemini,
+  Sonnet, Opus, Haiku, GPT, or any other model name.
+
+Phrase it like: *"I'll go by Monty in Composer docs — sound good, or pick
+your own?"* Retry the tool call with their answer as `actingAs`. It
+persists to `~/.composer/user.json` and is reused forever.
+
+**On success** (first run or any subsequent run), the return gives you
+two ordered steps — the field names encode the order:
+
+1. `step1_sayToUser` — output this FIRST. It always starts with the
+   `browserUrl` because the user needs the link to open the doc; it
+   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.
+
+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.
 
 **Seeding — prefer a file path when one exists.** Pick exactly one:
 
@@ -32,15 +61,30 @@ to sync changes back.
 
 ### 2. Join
 Triggers: a share prompt with a Composer URL, "/composer join <url>".
-Action: extract the URL and the acting-as name from the prompt. Call
-`composer_join_room({ url, actingAs })`. Announce the doc outline and enter
-monitor mode.
+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, timeoutSec: 300 })` in a loop.
-On `timeout`: loop again up to ~30 minutes, then ask the user if they want
-to keep watching.
+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.
+
+On `mention`: handle the event (reply / suggestion / resolve as needed),
+output any user-facing text, then execute `requiredNextToolCall` — which
+is another `composer_next_event` call. Do not pause for the user to
+acknowledge. The doc is the conversation.
+
+On `timeout`: check `recentActivity`.
+- `recentActivity: true` → the return includes `requiredNextToolCall`.
+  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.
 
 On `mention`, the event contains everything you need to act in one turn:
 
@@ -64,22 +108,54 @@ or `composer_add_comment` — no extra `composer_get_section` call is needed in
 the common case. Reach for `sectionMarkdown` to understand surrounding context
 before replying or suggesting.
 
-**Important:** `reason: "active_thread"` means the user replied on a thread
-the agent has already participated in — no explicit `@agent` was required.
-Decide whether to respond based on content, not just the trigger; if the
-reply is plainly addressed to another person, or is a thank-you that doesn't
-need an answer, it's fine to leave it alone (don't emit an empty reply just
-to acknowledge). If it clearly asks you something, answer it.
+**The event only carries the triggering message.** If the thread already has
+replies (from the user, or from another agent), call `composer_get_thread({
+roomId, threadId })` before replying. The return has every reply with author
+and timestamp — essential when the user tagged you mid-conversation and you
+need to catch up on what's already been said.
+
+**`reason` is your main filter:**
+
+- `"direct_mention"` — sidecar or text explicitly tagged you. Always
+  reply (unless the content is purely a thank-you that doesn't need an
+  answer — never emit empty acknowledgements).
+- `"active_thread"` — a plain reply on a thread you're already in. Reply
+  if the content invites one; skip if it's plainly addressed to another
+  person, is a thank-you, or is otherwise a conversational dead-end.
+- `"solo_room"` — you're alone with one human who didn't tag anyone.
+  **Default to a helpful reply** — they almost certainly want your
+  input. Skip only when the text reads like:
+    - a **note-to-self** ("TODO: fix this later", "remember to check
+      the date"),
+    - a bare **acknowledgement** ("k", "got it", "done"),
+    - a stage direction / aside ("ugh", "hmm"),
+    - or anything that visibly isn't pointed at you (quoted text,
+      drafts they're jotting down).
+  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.
 
-## Write tools
-
-- `composer_add_comment` — comment anchored to text.
-- `composer_add_suggestion` — propose a text replacement (lands as pending).
-- `composer_reply_comment` / `composer_reply_suggestion` — reply on a thread.
+## Tools
+
+Read tools:
+- `composer_get_full_doc` — entire doc as markdown.
+- `composer_get_section` — one section by `headingId`.
+- `composer_get_thread` — full state of a thread (all replies, anchor,
+  containing section). Call this when `composer_next_event` surfaces a
+  mention on a thread that already has history — the event gives you
+  only the triggering message.
+
+Write tools:
+- `composer_add_comment` — NEW comment on any span in the doc. Use when
+  raising something outside the current thread's anchor.
+- `composer_add_suggestion` — propose a text replacement (lands as
+  pending). Can target any span — `fromThreadId` inherits the source
+  thread's anchor; `anchor` specifies a span elsewhere. Call it multiple
+  times in a turn to suggest in several spots.
+- `composer_reply_comment` / `composer_reply_suggestion` — reply on an
+  existing thread.
 - `composer_resolve_thread` — mark resolved.
 
 There is no "just edit" tool in v1. All text changes go through suggestions
@@ -135,6 +211,104 @@ Picking a broader `textToFind` than the user asked for (the whole sentence
 when they highlighted a phrase, the whole paragraph when they asked about
 one clause) is the main failure mode. When in doubt, default to path 1.
 
+### Cross-span: reply and suggest anywhere in the doc
+
+A comment/reply thread is anchored to *one* span, but your response is
+not confined to that span. When the user's question (or your own
+judgment) points elsewhere:
+
+- **Suggest a change to different text.** Call `composer_add_suggestion`
+  with `anchor: { headingId, textToFind }` pointing at the target. You
+  can post multiple suggestions in one turn — e.g., the user says "the
+  flour amount is off and so is the bake time" → two suggestions, each
+  anchored to its own span.
+- **Open a new thread elsewhere.** Call `composer_add_comment` with
+  its own anchor. Useful for cross-references ("see also the
+  conclusion") or raising something the user didn't ask about but
+  should see.
+- **Still reply on the original thread too** if the user's question
+  deserves a direct answer — but only when the reply says something
+  the suggestion/new-comment doesn't already convey. Don't post
+  "see my suggestion"; the card IS the answer.
+
+Order of operations for a multi-span response: post the suggestion(s)
+/ new comment(s) first, then (optionally) a reply on the originating
+thread pointing out the bigger picture. That way the originating
+thread's reply can reference what you just did.
+
+### Suggest completely — accepting must leave the doc correct
+
+Goal: the user clicks Accept and is done. They should never have to
+hunt down downstream edits you forgot.
+
+**Load enough context before you suggest.** The event gives you
+`sectionMarkdown` for the containing section — usually enough for
+wording changes. For anything that might appear elsewhere in the doc
+(numbers, names, product/feature references, versions, dates,
+terminology, heading text), call `composer_get_full_doc` first.
+One extra read is much cheaper than shipping a broken doc.
+
+**Scan for ripples before posting.** Common ones:
+
+- **Counts and enumerations.** "The three examples below" / "three
+  things to remember" — if you add or remove an item, update the
+  count and any ordinal words ("first", "finally").
+- **Cross-references.** "As in section 2", "see the conclusion",
+  "per step 3 above". If your edit moves or renames the target,
+  update the reference too.
+- **Restated facts.** Recipes reference an ingredient twice; release
+  notes cite a version in both intro and body; specs quote a number
+  in a heading and a paragraph. One fact, multiple spans — cover
+  all of them.
+- **Subject/verb and pronoun agreement.** "X and Y are" → trim to
+  just X → "X is". Changing from plural to singular ripples.
+- **Neighboring flow.** Rewriting sentence 2 can break sentence 3
+  ("This is why..."). Fix the continuation.
+- **Heading changes.** If you change heading text, any prose that
+  says "see the Intro section" may need updating.
+
+**Post every ripple as its own suggestion, in the same turn.** Don't
+leave the user to hunt for companion edits. The tool accepts one
+anchor per call — call it multiple times. Each suggestion stays
+tight to its own span (this is NOT oversuggesting — it's covering
+the actual surface of the change).
+
+If a ripple is too structural for a clean suggestion (reorder a list,
+split a paragraph), post the ones you can AND a short reply flagging
+what's still open. The user shouldn't be surprised.
+
+**When in doubt about the scope of a ripple, fetch the full doc.**
+Don't guess.
+
+### Auto-suggest when the user confirms a concrete proposal
+
+When a user flags something qualitative ("this is too much flour", "this
+sentence is clunky", "this number feels off"), lead with a **concrete
+counter-proposal framed as a question** — then, if they confirm, post
+the suggestion immediately without waiting for a second "yes, go ahead".
+
+Two turns, not three:
+
+1. **Turn 1 (propose).** Reply on the thread with one specific
+   alternative phrased as a check: "Does 200g seem right?", "How about
+   'gently fold' instead of 'stir'?", "Would 45 minutes read better than
+   90?". Pick a real number / phrase — not "would you like me to
+   suggest a different amount?" (that's a question about your behavior,
+   not a proposal).
+2. **Turn 2 (commit on confirmation).** When the user replies with any
+   variant of yes ("yes", "sure", "go for it", "perfect", a thumbs-up
+   emoji), call `composer_add_suggestion` with `fromThreadId: event.threadId`
+   and the concrete replacement. Do NOT also post a comment reply — the
+   suggestion card IS your reply (see "Keep comment text terse" above).
+
+If the user says no / picks a different value / redirects, follow their
+lead — do not post the original proposal anyway.
+
+If you can't name a concrete alternative (e.g. the thread is too
+abstract to guess a number), ask a clarifying question instead. Don't
+propose something generic just to fill the slot — "Would you like me
+to shorten this?" is worthless without a target length.
+
 ## Anchors
 
 Write tools take:
@@ -143,9 +317,40 @@ Write tools take:
 { headingId: "intro-0", textToFind: "the exact words to anchor on", occurrence?: 1 }
 ```
 
-If you get `text_not_found`, the error message includes the current section
-text. Re-plan against the fresh text and retry. Never retry with stale
-content.
+### Pick the right span — anchor = what gets deleted
+
+Your `textToFind` is literally cut out when the user accepts; your
+`replacementText` is inserted in its place. So:
+
+- **Anchor the whole unit you're changing.** Replacing a sentence →
+  include the terminal punctuation (`.`, `?`, `!`). Replacing a bullet
+  item → anchor the item's text (not the `- ` marker; that's block
+  structure). Replacing a paragraph → anchor the whole paragraph.
+- **Include any trailing punctuation you're changing.** Converting a
+  statement to a question? End the anchor at the `.` and end the
+  replacement with `?`. Don't anchor "the statement" alone and
+  replace with "the question?" — you'll end up with `the question?.`.
+- **Match your `replacementText`'s shape to the anchor's shape.** Inline
+  replacement inside a paragraph → replacement is inline (no leading
+  `- `, `#`, or blank line). Replacing a full list → replacement is a
+  full markdown list. Single-paragraph markdown is unwrapped to inline
+  on accept; multi-block markdown is inserted as blocks.
+- **Formatting is part of your replacement, not the anchor.** If the
+  original had `**bold**` or a link, the anchor's formatting is gone
+  on accept — your replacement must include the markdown syntax for
+  any formatting you want preserved.
+- **Anchor at token boundaries, not mid-word.** `textToFind: "istrat"`
+  to hit the middle of "administration" is fragile. Use whole words
+  or sentence boundaries. Use `occurrence` when the same phrase
+  appears multiple times.
+- **Mind the whitespace.** By default, do not include leading or
+  trailing whitespace in the anchor, and end `replacementText` at the
+  same boundary. If you include a trailing space in the anchor,
+  include one in the replacement too; otherwise words smash together.
+
+If you get `text_not_found`, the error message includes the current
+section text. Re-plan against the fresh text and retry. Never retry
+with stale content.
 
 ## Discoverability