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

package/dist/cli.js

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

package/dist/mcp.js

@@ -1,8 +1,36 @@
 import {
+  __test_clearRooms,
+  __test_dispatch,
+  __test_setRoom,
+  _clearRoomsForTest,
+  _registerRoomForTest,
+  dispatchTool,
+  performAddComment,
+  performAddSuggestion,
+  performAgentStatus,
+  performDone,
+  performReplyComment,
+  performReplySuggestion,
+  performResolveThread,
   startMcpHttpServer,
-  startMcpServer
-} from "./chunk-UVXQZ2TN.js";
+  startMcpServer,
+  teardownAllRooms
+} from "./chunk-EJUJPBX2.js";
 export {
+  __test_clearRooms,
+  __test_dispatch,
+  __test_setRoom,
+  _clearRoomsForTest,
+  _registerRoomForTest,
+  dispatchTool,
+  performAddComment,
+  performAddSuggestion,
+  performAgentStatus,
+  performDone,
+  performReplyComment,
+  performReplySuggestion,
+  performResolveThread,
   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.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

@@ -69,7 +69,7 @@ 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
+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),
@@ -95,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)
 }
 ```
 
@@ -108,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
@@ -133,6 +167,16 @@ 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 like "add a summary to section 2".
 Action: already attached; call the write tools and report back concisely.
@@ -149,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
@@ -169,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.
@@ -298,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.
@@ -309,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: