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

package/dist/cli.js

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

package/dist/mcp.js

@@ -2,14 +2,34 @@ import {
   __test_clearRooms,
   __test_dispatch,
   __test_setRoom,
+  _clearRoomsForTest,
+  _registerRoomForTest,
+  dispatchTool,
+  performAddComment,
+  performAddSuggestion,
+  performAgentStatus,
+  performDone,
+  performReplyComment,
+  performReplySuggestion,
+  performResolveThread,
   startMcpHttpServer,
   startMcpServer,
   teardownAllRooms
-} from "./chunk-A5KBJAJW.js";
+} from "./chunk-EJUJPBX2.js";
 export {
   __test_clearRooms,
   __test_dispatch,
   __test_setRoom,
+  _clearRoomsForTest,
+  _registerRoomForTest,
+  dispatchTool,
+  performAddComment,
+  performAddSuggestion,
+  performAgentStatus,
+  performDone,
+  performReplyComment,
+  performReplySuggestion,
+  performResolveThread,
   startMcpHttpServer,
   startMcpServer,
   teardownAllRooms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composer-app/mcp",
-  "version": "0.0.1-beta.5",
+  "version": "0.0.1-beta.7",
   "description": "Composer MCP",
   "license": "MIT",
   "author": "Josh Philpott",
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "skill"
+    "skill",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "mcp",

package/skill/SKILL.md

@@ -36,14 +36,13 @@ 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 `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.
+   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 the subagent spawn leaves the room attached but
-silent; saying "I'm monitoring" without spawning the loop is a lie,
-every mention gets missed.
+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:
 
@@ -65,63 +64,16 @@ 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 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.
+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 30 seconds). **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 in-doc action, then execute `requiredNextToolCall` — which
+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.
 
@@ -130,8 +82,9 @@ 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 exit (per exit rule 1
-  above). Do not paraphrase — users recognize the line across sessions.
+  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:
 
@@ -142,11 +95,13 @@ On `mention`, the event contains everything you need to act in one turn:
   threadKind: "comment" | "suggestion",
   threadText: "...",           // the exact message that triggered you
   replyId?: "...",             // present when it's a reply on an existing thread
-  reason: "direct_mention" | "active_thread",
+  reason: "direct_mention" | "active_thread" | "solo_room",
   anchoredText?: "...",        // the doc text the thread is anchored to
   headingId?: "...",           // the section's headingId (use with write tools)
   headingText?: "...",
-  sectionMarkdown?: "..."      // full containing section as markdown
+  sectionMarkdown?: "...",     // full containing section as markdown
+  invokerUserId?: "...",       // userId of whoever triggered you (use in mentions[])
+  invokerName?: "..."          // their display name (use in @mention literal)
 }
 ```
 
@@ -155,6 +110,38 @@ 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.
 
+**Ack first, then do the work.** On every `mention` event you intend to act
+on, post a brief ack reply FIRST — before reading the full doc, before
+drafting a suggestion. This is the "I heard you, I'm on it" signal; without
+it the user stares at a silent sidebar while you think.
+
+- Call `composer_reply_comment` (or `composer_reply_suggestion`) with
+  `state: "thinking"` and `mentions: [event.invokerUserId]`. For a brand-new
+  thread response use `composer_add_comment` / `composer_add_suggestion`
+  with the same `state` + `mentions` shape.
+- Body: `@<invokerName> — on it` or equivalent terse phrasing (≤ 24 chars).
+  "On it.", "Looking.", "Checking.". No preamble, no promise of structure.
+- Read `invokerUserId` and `invokerName` directly from the event payload
+  above — do NOT try to reconstruct them from `threadText` or from an
+  awareness lookup. They're the authoritative values the server resolved.
+- **Skip the ack** for empty thank-yous or conversational dead-ends you
+  wouldn't reply to at all (see `reason` gates below) — the ack is a
+  signal of intent to act, not a reflex.
+- **Skip the ack** when this mention is a yes-variant confirmation inside
+  an ask-then-auto-suggest round-trip (see §"Auto-suggest when the user
+  confirms a concrete proposal"): if the mention fired as `active_thread`
+  AND your own prior reply on this thread was a concrete yes/no
+  counter-proposal AND the human's message is a yes-variant, drop the
+  suggestion directly via `composer_add_suggestion` with
+  `fromThreadId: event.threadId`. The "I heard you" signal was already
+  delivered in the prior ack; a second ack here is noise. Only the
+  initial substantive-work mention gets an ack.
+
+Once the ack is posted, drive state with `composer_agent_status` as you
+work (see §"Progress status" below). On completion, rewrite the ack to
+its final form in the same call that transitions to `ready` — do not
+post a duplicate pointer reply.
+
 **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
@@ -180,13 +167,19 @@ need to catch up on what's already been said.
       drafts they're jotting down).
   When in doubt, reply — the user can always ignore you.
 
+**When you skip a mention, call `composer_done({ roomId, threadId })`.**
+The instant a mention is dequeued via `composer_next_event`, the server
+publishes a `thinking…` indicator on that thread so the user sees you
+picked it up — there's no flicker waiting for your first
+`composer_agent_status` call. If you reply, the `state: "ready"`
+transition clears the indicator on its own. If you skip without
+replying, nothing else clears it and the user's avatar pulses forever.
+`composer_done` is idempotent — safe to call even if the indicator was
+already cleared.
+
 ### 4. Act
-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.
+Triggers: direct requests like "add a summary to section 2".
+Action: already attached; call the write tools and report back concisely.
 
 ## Tools
 
@@ -200,13 +193,25 @@ Read tools:
 
 Write tools:
 - `composer_add_comment` — NEW comment on any span in the doc. Use when
-  raising something outside the current thread's anchor.
+  raising something outside the current thread's anchor. Accepts an
+  optional `state` ("thinking" on an ack) so the first-ever reply on a
+  thread can be the ack.
 - `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.
+  existing thread. Accept an optional `state` field for the ack-first
+  flow; post with `state: "thinking"` and the invoker in `mentions[]`.
+- `composer_agent_status` — drive state transitions (`thinking →
+  working → replying → ready`) and rewrite the final ack body on the
+  reply/comment/suggestion you own. See §"Progress status".
+- `composer_done` — clear the live indicator on a thread you decided
+  NOT to reply to. Required when you skip a mention (off-topic chatter,
+  self-mention, conversational dead-end), because the indicator is
+  published optimistically the moment a mention is dequeued. Replying
+  with `state: "ready"` clears it on its own — only call `composer_done`
+  for the skip case.
 - `composer_resolve_thread` — mark resolved.
 
 There is no "just edit" tool in v1. All text changes go through suggestions
@@ -220,11 +225,18 @@ a chat window. Long replies get unwieldy fast. Rules:
 - Answer in 1–3 sentences. Prefer one.
 - Reply directly to the question asked — no preamble ("Great question!"),
   no restating the ask, no trailing summary of what you just did.
-- **If you post a suggestion in response to the thread, the suggestion IS
-  your reply. Do not also post a comment reply.** The suggestion renders
-  as a Replace/With card in the sidebar already; a pointer comment ("see
-  the suggestion") just duplicates what the user can already see.
-  Silent suggestion-only responses are correct and expected.
+- **When the substantive answer is a standalone artifact, that artifact
+  IS the reply.** A "standalone artifact" means a suggestion, a cross-span
+  comment on a different anchor, or a separate document link. In that
+  case do NOT post a duplicate pointer comment — instead, rewrite your
+  existing ack in place to a thin pointer (`"Posted a suggestion below."`,
+  `"Added a comment in Section 3."`, `"See doc <link>."`) and set
+  `state: "ready"` on the same call. The suggestion / cross-span comment
+  renders as its own card; a pointer reply just duplicates what the user
+  can already see.
+- **When the substantive answer IS a reply with text**, rewrite the ack
+  to that text and clear the state (or set `state: "ready"`) in the same
+  `composer_agent_status` call. Do not post a separate follow-up reply.
 - If the answer genuinely needs structure (a list of 4+ items, code, a
   table) and a suggestion isn't the right shape, post it as a suggestion
   in the doc body instead of as a comment reply.
@@ -349,8 +361,10 @@ Two turns, not three:
 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).
+   and the concrete replacement. **Skip the ack in this case** — the
+   prior reply already delivered the "I heard you" signal, and the
+   suggestion card IS your answer. Do NOT also post a comment reply
+   (see §"Keep comment text terse" and the ack-skip rule in §"Monitor").
 
 If the user says no / picks a different value / redirects, follow their
 lead — do not post the original proposal anyway.
@@ -360,6 +374,108 @@ 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.
 
+### Progress status
+
+Once the ack is posted, drive the owning reply through a small state
+machine using `composer_agent_status`. The UI animates state changes
+on the reply card; the user sees progress instead of a silent pause.
+
+```
+composer_agent_status({
+  roomId,
+  threadId,
+  replyId?,             // identifies which reply you own; omit for thread-head
+  state,                // "thinking" | "working" | "replying" | "ready"
+  text?,                // rewrite the reply body (only meaningful on "ready")
+  note?,                // short human-readable progress line
+  kind?                 // "comment" | "suggestion" — disambiguates head records
+})
+```
+
+State machine: **`thinking → working → replying → ready`**.
+
+- `thinking` — initial ack, set by the reply/add tool that posted it.
+- `working` — you're doing substantive work (reading the doc, computing,
+  drafting). Set this whenever you expect a gap.
+- `replying` — you're about to write the final text. Optional, brief.
+- `ready` — done. Call with `text: "<final ack body>"` to rewrite the
+  ack in place atomically; the awareness heartbeat for this entry is
+  pruned in the same call.
+
+**Minimum-visible rule.** The UI collapses state changes that happen
+faster than 400 ms, so don't worry about being too fast. DO worry about
+being SILENT for more than ~2 seconds without calling
+`composer_agent_status({ state: "working" })` — silence is the failure
+mode. If you're about to do something slow (fetch the full doc, compute
+a non-trivial diff, call another tool), transition to `working` first.
+
+Use `note` to surface human-readable progress where it helps — e.g.
+`note: "Reading section 3…"`, `note: "Drafting suggestion…"`,
+`note: "Checking cross-references…"`. Short sentence fragments; the
+user reads them at a glance.
+
+On completion, one call does everything:
+
+```
+composer_agent_status({
+  roomId, threadId, replyId,
+  state: "ready",
+  text: "Posted a suggestion below."
+})
+```
+
+This rewrites the ack body and prunes the awareness heartbeat
+atomically. Do NOT post a separate reply to say "done" — the rewrite
+IS the final reply.
+
+### Worked example — ack-then-suggestion flow
+
+A mention arrives; the user asked you to tighten a sentence in Section 3.
+The full round-trip is four tool calls:
+
+```
+// 1. Mention arrives via composer_next_event:
+//    { kind: "mention", threadId: "t_abc", invokerUserId: "u_jess",
+//      invokerName: "Jess", reason: "direct_mention", ... }
+
+// 2. Ack first — posts the "on it" reply with a thinking indicator.
+const { replyId } = composer_reply_comment({
+  roomId,
+  threadId: "t_abc",
+  text: "@Jess — on it",
+  mentions: ["u_jess"],
+  state: "thinking",
+});
+
+// 3. Transition to working before any slow step.
+composer_agent_status({
+  roomId,
+  threadId: "t_abc",
+  replyId,
+  state: "working",
+  note: "Reading section 3…",
+});
+
+// 4. Do the work and post the substantive artifact.
+composer_add_suggestion({
+  roomId,
+  fromThreadId: "t_abc",
+  replacementText: "…",
+});
+
+// 5. Rewrite the ack to a thin pointer and mark ready atomically.
+composer_agent_status({
+  roomId,
+  threadId: "t_abc",
+  replyId,
+  state: "ready",
+  text: "Posted a suggestion below.",
+});
+```
+
+No extra pointer reply. No "done" message. The rewrite + suggestion
+card together are the complete response.
+
 ## Anchors
 
 Write tools take: