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

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to `@composer-app/mcp` are documented in this file.
+
+This project uses pre-release semver under the `0.0.x-beta.N` track; each
+release bumps the `beta.N` counter regardless of additive / breaking
+distinction until the package graduates to `0.1.0`.
+
+## 0.0.1-beta.7 — 2026-04-29
+
+Polish on the COM-26 ack/state work shipped in `0.0.1-beta.6` (which was
+never published to npm). Adds an explicit "skip" signal and fixes the
+top-bar avatar pulsing forever after a reply finished.
+
+### Added
+
+- **New tool: `composer_done`.** Explicit signal for the skip path —
+  off-topic chatter, self-mention, or any case where the agent decides
+  not to reply. Accepts `{ roomId, threadId, replyId? }`. Clears the
+  thread-head `agentWork` placeholder published by
+  `RoomState.onEventDelivered` when `composer_next_event` dequeued the
+  mention; optionally also clears a per-reply entry. Idempotent.
+  SKILL.md tells the agent to call it whenever it skips.
+
+### Fixed
+
+- **Top-bar PresenceBar avatar kept pulsing forever after a reply.**
+  `composer_next_event` publishes a thread-head
+  `agentWork(threadId, undefined, "thinking")` placeholder when it
+  dequeues a mention; the agent's ack reply then publishes a
+  reply-scoped entry. The `composer_agent_status({state: "ready"})`
+  handler cleared the reply-scoped entry but not the thread-head
+  placeholder, and `useAgentActivityByUser`'s max-severity reduction
+  kept the avatar pulsing.
+  - `performAgentStatus` ready branch now clears both
+    `(threadId, replyId)` and `(threadId, undefined)`.
+  - `performReplyComment` and `performReplySuggestion` also clear the
+    thread-head placeholder when posted with `state: "ready"` directly,
+    as defense in depth for callers that skip the state machine.
+
+## 0.0.1-beta.6 — 2026-04-28
+
+Agent acknowledgment + live state indicators (COM-26). Layered onto the
+socket-driven presence model from 0.0.1-beta.5 (PR #24); the awareness
+heartbeat is no longer used — `agentWork` updates ride on the natural
+tool-call cadence instead.
+
+### Added
+
+- **New tool: `composer_agent_status`.** Lets the agent advance an
+  in-flight ack's state without re-sending text, and atomically rewrite
+  the ack at completion. Accepts `{ roomId, threadId, replyId?, state,
+  text?, note?, kind? }`. `kind` defaults to `"comment"`; set
+  `"suggestion"` to target a thread-head agent-authored suggestion. Omit
+  `replyId` to update a thread-head record directly; pass it to update a
+  reply inside the parent thread. Returns `{ id }` for thread-head
+  updates and `{ replyId }` for reply updates.
+- **Optional `state` argument on `composer_reply_comment`,
+  `composer_reply_suggestion`, `composer_add_comment`, and
+  `composer_add_suggestion`.** Allowed values: `"thinking" | "working" |
+  "replying" | "ready"`. Absent = existing behavior (legacy callers
+  unaffected).
+- **`invokerUserId` and `invokerName` on the `mention` event payload.**
+  Resolved server-side from the triggering reply's or thread's
+  `authorUserId` / `authorName`. For `solo_room`, this is the sole human
+  in awareness. Lets the model post an ack that `@-mentions` the invoker
+  back without a round-trip lookup.
+- **Decision 9 filter on the mention observer.** `attachMentionObserver`
+  now skips `active_thread` and `solo_room` emissions when the
+  triggering reply has `authorIsAgent === true`. Direct `direct_mention`
+  triggers still fire cross-agent (explicit `@<otherAgent>` is
+  legitimate). Prevents multi-agent ping-pong amplification on every
+  state transition.
+- **Truth-ordering + self-heal in `composer_agent_status`.** On `ready`
+  transitions the awareness `agentWork` entry is pruned BEFORE the CRDT
+  write, so a mid-op crash leaves at worst an ephemeral anomaly rather
+  than a stuck persisted state. Every `composer_agent_status` handler
+  call self-heals stale `agentWork` entries whose target record is
+  already `ready`.
+
+### Host-side SKILL.md
+
+- **Ack-first behavior** — the model is now instructed to post a brief
+  ack reply (`state: "thinking"` with the invoker in the `mentions[]`
+  sidecar) before any substantive work on every mention it decides to
+  act on. The ack body is ≤ 24 chars — e.g., `@<invokerName> — on it`.
+- **Generalized "standalone artifact IS the reply" rule.** The old
+  "suggestion IS the reply; do not also post a comment reply" guidance
+  is superseded by a rule covering any standalone artifact (suggestion,
+  cross-span comment on a different anchor, separate document). The ack
+  gets rewritten to a thin pointer on completion; no duplicate pointer
+  comment is posted.
+- **Progress status section** documents `composer_agent_status`, the
+  `thinking → working → replying → ready` state machine, the UI's 400 ms
+  minimum-visible collapse window, and the 2-second silence ceiling
+  before a progress call is expected.
+- **Worked example** added showing the full ack-then-suggestion flow
+  end to end.
+- **Ask-then-auto-suggest reconciliation.** On a yes-variant
+  confirmation inside an active ask-then-suggest round-trip, the agent
+  skips the ack — the prior reply already delivered the "I heard you"
+  signal, and the suggestion is the immediate answer.
+
+### Changed
+
+- **`addReply` and `addSuggestionReply` on the web side** now accept an
+  optional `{ silent?: boolean }` opts bag (propagated to
+  `emitActivity`). The MCP does not call these directly, but the
+  `composer_agent_status` handler passes `silent: true` internally for
+  every non-`ready` transition so the activity feed doesn't spam on
+  every `thinking → working → replying` flip. Default is
+  `silent: false` — existing callers unaffected.
+
+### Infrastructure
+
+- **New `mcp/vitest.config.ts`** so `npm -w @composer-app/mcp run test`
+  no longer picks up the root `vitest.config.ts`'s `projects` list and
+  crashes. Fixes followup #3 for the mcp workspace.
+
+### Backward compatibility
+
+All additions are strictly additive:
+
+- Older clients that don't know the `state` field ignore it on read; the
+  ack reply's literal text still renders legibly with no indicator.
+- Older models running a pre-ack-first SKILL.md continue to work — they
+  just don't call `composer_agent_status` and go straight from `thinking`
+  (if they use the new `state` arg) or a plain reply (if they don't) to
+  the final answer.
+- Existing tool handlers preserve their v1 return shapes (`{id}` /
+  `{replyId}`); new fields are additive.
+- The `mention` event payload's new `invokerUserId` / `invokerName`
+  fields are optional — older consumers that don't read them are
+  unaffected.
+
+### Rollback
+
+Revert `0.0.1-beta.4` to `0.0.1-beta.3`. Browser clients rendering
+`state`-bearing records posted before rollback fall through the
+unknown-state branch and render the record's literal text — no crash, no
+broken layout.
+
+## 0.0.1-beta.3 and earlier
+
+Unreleased baseline. See git log for commit-level history.

package/README.md

@@ -0,0 +1,160 @@
+# @composer-app/mcp
+
+MCP server for [Composer](https://usecomposer.app) — a realtime
+collaborative markdown editor with first-class agent support.
+
+The MCP server runs locally under an MCP-capable coding CLI (Claude Code
+today; Codex / OpenCode adapters are follow-up work) and connects to a
+Composer room as a standard Yjs peer. It exposes a small, typed tool
+surface the model uses to read the doc, react to mentions, post
+comments, and suggest edits — all through the same CRDT path humans use.
+
+## Install / setup
+
+```bash
+npx @composer-app/mcp@latest setup
+```
+
+Writes `~/.composer/user.json` (persistent machine identity +
+self-chosen display name), registers `composer-mcp` with your coding
+CLI, and installs the host-side SKILL prompt at
+`~/.claude/skills/composer/SKILL.md`.
+
+Restart your CLI once setup completes.
+
+## Tools
+
+### Read
+
+- **`composer_attach_room`** — attach to an existing room by ID and
+  return a snapshot (full doc markdown, outline, version).
+- **`composer_get_full_doc`** — fetch the current doc as markdown.
+- **`composer_get_section`** — fetch a single section by `headingId`.
+- **`composer_get_thread`** — fetch a thread's body + every reply +
+  anchored text + containing section markdown (for catch-up on
+  conversations the model was tagged into mid-flight).
+- **`composer_next_event`** — block for up to `timeoutSec` (default
+  600 s) waiting for a remote event. Returns `mention` or `timeout`.
+
+The `mention` event carries the triggering text, the anchored doc
+range, the containing section as markdown, and (new in 0.0.1-beta.4)
+**`invokerUserId` + `invokerName`** — so the model can `@mention` the
+invoker back without a client-side lookup. The `reason` field is one
+of: `"direct_mention"`, `"active_thread"`, or `"solo_room"`.
+
+### Write
+
+- **`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.
+- **`composer_resolve_thread`** — mark a thread resolved.
+- **`composer_agent_status`** (new in 0.0.1-beta.4) — advance an
+  in-flight ack's state, and atomically rewrite the ack's text on
+  completion. See [Progress status](#progress-status) below.
+
+### Create / join rooms
+
+- **`composer_create_room`** — create a new doc, optionally seeded from
+  a markdown file or inline string. Returns the browser URL so the
+  invoking human can open it.
+- **`composer_join_room`** — attach to an existing room by browser URL.
+
+## Agent reply states
+
+Every agent-authored reply, comment, or suggestion can carry an
+optional `state` field (new in 0.0.1-beta.4):
+
+| State | Meaning | UI |
+|---|---|---|
+| `thinking` | Ack posted, no tool use yet | Violet status dot + name-row shimmer |
+| `working` | Agent is using tools | Blue dot + indeterminate bar under row |
+| `replying` | Final response is being assembled / streamed | Teal dot + blinking caret |
+| `ready` | Terminal; record holds the final content (or a pointer to a standalone artifact) | Neutral grey dot (no indicator) |
+
+The UI also derives a `stalled` view when the agent's awareness
+presence drops while a non-`ready` state persists for > 60 s (4× the
+MCP's 15 s heartbeat) — amber dot with a slower pulse and an inline
+"Retry" affordance.
+
+Legacy records and older browsers ignore the `state` field and render
+the literal reply text — no crash, no broken layout.
+
+## Progress status
+
+The model drives state transitions through the `composer_agent_status`
+tool. The canonical lifecycle:
+
+```text
+# Mention arrives
+composer_next_event() → { kind: "mention", threadId, invokerUserId, invokerName, ... }
+
+# 1. Acknowledge first
+composer_reply_comment({
+  roomId, threadId,
+  text: "@<invokerName> — on it",
+  mentions: [invokerUserId],
+  state: "thinking",
+})  // → { replyId }
+
+# 2. Advance state as you work (optional but recommended for >2 s spans)
+composer_agent_status({
+  roomId, threadId, replyId,
+  state: "working",
+  note: "reading section 3…",
+})
+
+# 3. Land the substantive answer
+composer_add_suggestion({ roomId, fromThreadId: threadId, replacementText: "…" })
+
+# 4. Atomically rewrite the ack to a pointer + mark ready
+composer_agent_status({
+  roomId, threadId, replyId,
+  state: "ready",
+  text: "Posted a suggestion below.",
+})
+```
+
+Key invariants:
+
+- **Prune awareness before writing `ready` to the CRDT.** The handler
+  enforces this internally; a mid-op crash leaves at worst an ephemeral
+  anomaly, never a stuck persisted state masked by a stale heartbeat.
+- **Self-heal on handler entry.** Every call prunes awareness entries
+  whose target record is already `ready`. Idempotent; converges on
+  retries.
+- **Silent intermediate transitions.** Non-`ready` state flips pass
+  `silent: true` to the activity-feed path, so the feed only sees the
+  initial ack and the final `ready` rewrite.
+
+See [`skill/SKILL.md`](./skill/SKILL.md) — shipped with the package and
+installed into your CLI's skill directory by `setup` — for the full
+host-side behavior contract (when to ack vs skip, when suggestion IS
+the reply, ask-then-auto-suggest reconciliation, multi-agent etiquette).
+
+## Environment
+
+The MCP reads two env vars (set by `setup` when registering with your
+CLI):
+
+- `COMPOSER_SERVER_HOST` — the Composer server host (e.g.,
+  `usecomposer.app` or `localhost:5173` for local dev).
+- `COMPOSER_APP_BASE` — the base URL of the Composer web app (e.g.,
+  `https://usecomposer.app` or `http://localhost:5173`).
+
+Identity is stored at `~/.composer/user.json` with mode `0600`.
+Delete the file to reset; setup will prompt for a new name on next run.
+
+## Development
+
+```bash
+cd mcp
+npm run typecheck   # tsc --noEmit -p .
+npm run build       # tsup → dist/cli.js + dist/mcp.js
+npm run test        # vitest run (uses mcp/vitest.config.ts; 131 tests as of 0.0.1-beta.4)
+```
+
+## License
+
+MIT