@abraca/mcp 1.8.0 → 1.9.1

package/dist/index.d.ts

@@ -3,12 +3,23 @@ import { AbracadabraClient, AbracadabraProvider, ServerInfo, SpaceMeta } from "@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region packages/mcp/src/server.d.ts
+/**
+ * Controls when the agent reacts to incoming chat:
+ * - `all`          — respond to every message in every visible channel (legacy)
+ * - `mention`      — group chats require `@<alias>`; DMs always respond
+ * - `task`         — ignore chat entirely; only respond to ai:task awareness events
+ * - `mention+task` — group chats require mention OR ai:task; DMs always respond (default)
+ */
+type TriggerMode = 'all' | 'mention' | 'task' | 'mention+task';
 interface MCPServerConfig {
   url: string;
   agentName?: string;
   agentColor?: string;
   inviteCode?: string;
   keyFile?: string;
+  triggerMode?: TriggerMode;
+  /** Aliases matched in `@<alias>` tokens. Defaults to `[agentName]`. */
+  mentionAliases?: string[];
 }
 declare class AbracadabraMCPServer {
   readonly config: MCPServerConfig;
@@ -28,9 +39,14 @@ declare class AbracadabraMCPServer {
   private _typingInterval;
   private _lastChatChannel;
   private _signFn;
+  /** Rolling buffer of the last N tool calls in the current turn, surfaced via awareness. */
+  private _toolHistory;
+  private static readonly TOOL_HISTORY_MAX;
   constructor(config: MCPServerConfig);
   get agentName(): string;
   get agentColor(): string;
+  get triggerMode(): TriggerMode;
+  get mentionAliases(): string[];
   get serverInfo(): ServerInfo | null;
   get rootDocId(): string | null;
   get spaces(): SpaceMeta[];
@@ -86,12 +102,25 @@ declare class AbracadabraMCPServer {
    *   dashboard only shows it in the relevant chat. Defaults to `_lastChatChannel`.
    */
   setAutoStatus(status: string | null, docId?: string, statusContext?: string | null): void;
+  /**
+   * Start a new agent turn. Mints a fresh UUID and writes it to awareness so
+   * the dashboard can gate the incantation on "there is an active turn",
+   * decoupled from the (racier) status field. Called from chat arrival and
+   * ai:task dispatch right before `setAutoStatus('thinking')`.
+   */
+  private _beginTurn;
   /** Re-send typing indicator every 2s so dashboard keeps showing it (expires at 3s). */
   private _startTypingInterval;
   private _stopTypingInterval;
   /**
    * Broadcast which tool the agent is currently executing.
-   * Dashboard renders this as a ChatTool indicator.
+   *
+   * Renders as a ChatTool pill on the dashboard. On non-null calls, the tool
+   * is also appended to `toolHistory` (capped at TOOL_HISTORY_MAX) and written
+   * to awareness so the dashboard's inline trace can show the turn's recent
+   * activity. Tools do NOT clear (`setActiveToolCall(null)`) on completion —
+   * the pill stays until the next tool replaces it or `setAutoStatus(null)`
+   * flushes the turn. This keeps pills visible long enough to see.
    */
   setActiveToolCall(toolCall: {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/mcp",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "MCP server for Abracadabra — AI agent collaboration on CRDT documents",
   "license": "MIT",
   "type": "module",

package/src/converters/markdownToYjs.ts

@@ -164,6 +164,10 @@ export function parseFrontmatter(markdown: string): FrontmatterResult {
 interface InlineToken {
   text: string
   attrs?: Record<string, unknown>
+  /** If set, emit an inline Y.XmlElement with this nodeName instead of text+marks. */
+  node?: string
+  /** Attributes for the inline node (when node is set). */
+  nodeAttrs?: Record<string, string>
 }
 
 function parseInline(text: string): InlineToken[] {
@@ -190,10 +194,9 @@ function parseInline(text: string): InlineToken[] {
       const kbdProps = parseMdcProps(`{${match[4]}}`)
       tokens.push({ text: kbdProps['value'] || '', attrs: { kbd: { value: kbdProps['value'] || '' } } })
     } else if (match[5] !== undefined) {
-      // Inline wikilink [[docId]] or [[docId|label]] → link to /doc/docId
-      const docId = match[5]
-      const displayText = match[6] ?? docId
-      tokens.push({ text: displayText!, attrs: { link: { href: `/doc/${docId}` } } })
+      // Inline wikilink [[docId]] or [[docId|label]] → inline docLink node
+      // (the label is derived from the tree at render time; legacy label is dropped)
+      tokens.push({ text: '', node: 'docLink', nodeAttrs: { docId: match[5]! } })
     } else if (match[7] !== undefined) {
       tokens.push({ text: match[7], attrs: { strike: true } })
     } else if (match[8] !== undefined) {
@@ -213,7 +216,7 @@ function parseInline(text: string): InlineToken[] {
   if (lastIndex < stripped.length) {
     tokens.push({ text: stripped.slice(lastIndex) })
   }
-  return tokens.filter(t => t.text.length > 0)
+  return tokens.filter(t => t.node || t.text.length > 0)
 }
 
 // ── Block-level parser ───────────────────────────────────────────────────────
@@ -247,7 +250,7 @@ type Block =
   | { type: 'field'; name: string; fieldType: string; required: boolean; innerBlocks: Block[] }
   | { type: 'fieldGroup'; fields: Block[] }
   | { type: 'image'; src: string; alt: string; width?: string; height?: string }
-  | { type: 'docEmbed'; docId: string }
+  | { type: 'docEmbed'; docId: string; seamless?: boolean }
   | { type: 'svgEmbed'; svg: string; title: string }
 
 function parseTableRow(line: string): string[] {
@@ -382,9 +385,11 @@ function parseBlocks(markdown: string): Block[] {
       continue
     }
 
-    const docEmbedMatch = line.match(/^!\[\[([^\]|]+?)(?:\|[^\]]*?)?\]\]\s*$/)
+    const docEmbedMatch = line.match(/^!\[\[([^\]|]+?)(?:\|[^\]]*?)?\]\](\{[^}]*\})?\s*$/)
     if (docEmbedMatch) {
-      blocks.push({ type: 'docEmbed', docId: docEmbedMatch[1]! })
+      const props = parseMdcProps(docEmbedMatch[2])
+      const seamless = 'seamless' in props || props['seamless'] === 'true' || /\{[^}]*\bseamless\b[^}]*\}/.test(docEmbedMatch[2] ?? '')
+      blocks.push({ type: 'docEmbed', docId: docEmbedMatch[1]!, seamless: seamless || undefined })
       i++
       continue
     }
@@ -600,17 +605,28 @@ function parseBlocks(markdown: string): Block[] {
 // ── Y.js content population ──────────────────────────────────────────────────
 
 function fillTextInto(el: Y.XmlElement, tokens: InlineToken[]): void {
-  const filtered = tokens.filter(t => t.text.length > 0)
+  const filtered = tokens.filter(t => t.node || t.text.length > 0)
   if (!filtered.length) return
 
-  const xtNodes = filtered.map(() => new Y.XmlText())
-  el.insert(0, xtNodes)
+  const children: (Y.XmlText | Y.XmlElement)[] = filtered.map((tok) => {
+    if (tok.node) {
+      const xe = new Y.XmlElement(tok.node)
+      if (tok.nodeAttrs) {
+        for (const [k, v] of Object.entries(tok.nodeAttrs)) xe.setAttribute(k, v)
+      }
+      return xe
+    }
+    return new Y.XmlText()
+  })
+  el.insert(0, children)
 
   filtered.forEach((tok, i) => {
+    if (tok.node) return
+    const xt = children[i] as Y.XmlText
     if (tok.attrs) {
-      xtNodes[i]!.insert(0, tok.text, tok.attrs as Record<string, boolean | object>)
+      xt.insert(0, tok.text, tok.attrs as Record<string, boolean | object>)
     } else {
-      xtNodes[i]!.insert(0, tok.text)
+      xt.insert(0, tok.text)
     }
   })
 }
@@ -837,6 +853,7 @@ function fillBlock(el: Y.XmlElement, block: Block): void {
     }
     case 'docEmbed': {
       el.setAttribute('docId', block.docId)
+      if (block.seamless) el.setAttribute('seamless', 'true')
       break
     }
     case 'svgEmbed': {

package/src/converters/yjsToMarkdown.ts

@@ -38,6 +38,12 @@ function elementTextContent(el: Y.XmlElement | Y.XmlFragment): string {
     if (child instanceof Y.XmlText) {
       parts.push(xmlTextToMarkdown(child))
     } else if (child instanceof Y.XmlElement) {
+      // Inline nodes that carry meaning at the inline level.
+      if (child.nodeName === 'docLink') {
+        const docId = child.getAttribute('docId')
+        if (docId) parts.push(`[[${docId}]]`)
+        continue
+      }
       parts.push(elementTextContent(child))
     }
   }
@@ -97,7 +103,10 @@ function serializeElement(el: Y.XmlElement, indent = ''): string {
 
     case 'docEmbed': {
       const docId = el.getAttribute('docId')
-      return docId ? `![[${docId}]]` : ''
+      if (!docId) return ''
+      const seamlessAttr = el.getAttribute('seamless')
+      const seamless = seamlessAttr === true || seamlessAttr === 'true'
+      return seamless ? `![[${docId}]]{seamless}` : `![[${docId}]]`
     }
 
     case 'svgEmbed': {

package/src/hook-bridge.ts

@@ -149,6 +149,9 @@ export class HookBridge {
   private routeEvent(payload: Record<string, any>): void {
     const event = payload.hook_event_name
     switch (event) {
+      case 'UserPromptSubmit':
+        this.onUserPromptSubmit()
+        break
       case 'PreToolUse':
         this.onPreToolUse(payload)
         break
@@ -159,7 +162,7 @@ export class HookBridge {
         this.onSubagentStart(payload)
         break
       case 'SubagentStop':
-        this.onSubagentStop(payload)
+        this.onSubagentStop()
         break
       case 'Stop':
         this.onStop()
@@ -167,6 +170,12 @@ export class HookBridge {
     }
   }
 
+  /** New user turn — reset any lingering status/tool state from the previous turn. */
+  private onUserPromptSubmit(): void {
+    this.server.setAutoStatus(null)
+    this.server.setActiveToolCall(null)
+  }
+
   private onPreToolUse(payload: Record<string, any>): void {
     const toolName: string = payload.tool_name ?? ''
     // Skip Abracadabra MCP tools — they set awareness themselves
@@ -184,10 +193,10 @@ export class HookBridge {
     const toolName: string = payload.tool_name ?? ''
     if (toolName.startsWith('mcp__abracadabra__')) return
 
-    // Don't clear activeToolCall — let it persist until the next PreToolUse
-    // replaces it or Stop clears everything. This prevents the status from
-    // flashing and vanishing between consecutive tool calls.
-    this.server.setAutoStatus('thinking')
+    // Don't touch status — let the short auto-clear timer handle idle
+    // detection, or the next PreToolUse / Stop / UserPromptSubmit override it.
+    // Don't clear activeToolCall either: the pill stays until the next tool
+    // replaces it or the turn ends, preventing flashes between tool calls.
   }
 
   private onSubagentStart(payload: Record<string, any>): void {
@@ -196,9 +205,10 @@ export class HookBridge {
     this.server.setAutoStatus('thinking')
   }
 
-  private onSubagentStop(_payload: Record<string, any>): void {
-    // Don't clear — let it persist until the next action or Stop
-    this.server.setAutoStatus('thinking')
+  private onSubagentStop(): void {
+    // No-op — the parent agent continues working; the next Pre/PostToolUse or
+    // Stop will update state. Previously this reset status to 'thinking',
+    // which kept the auto-clear timer resetting forever.
   }
 
   private onStop(): void {

package/src/index.ts

@@ -3,15 +3,23 @@
  * Abracadabra MCP Server — entry point.
  *
  * Environment variables:
- *   ABRA_URL         (required) — Server URL (e.g. http://localhost:1234)
+ *   ABRA_URL                    (required) — Server URL (e.g. http://localhost:1234)
  *   ABRA_AGENT_NAME             — Display name (default: "AI Assistant")
  *   ABRA_AGENT_COLOR            — HSL color for presence (default: "hsl(270, 80%, 60%)")
  *   ABRA_INVITE_CODE            — Invite code for first-run registration (grants role)
  *   ABRA_KEY_FILE               — Path to Ed25519 key file (default: ~/.abracadabra/agent.key)
+ *   ABRA_AGENT_TRIGGER_MODE     — When to respond in group chats:
+ *                                   all          → every message (legacy)
+ *                                   mention      → only when @<alias> is used
+ *                                   task         → only ai:task awareness events
+ *                                   mention+task → mention OR ai:task (default)
+ *                                 DMs always trigger regardless of mode.
+ *   ABRA_AGENT_MENTION_ALIASES  — Comma-separated aliases for @mentions
+ *                                 (default: [ABRA_AGENT_NAME])
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { AbracadabraMCPServer } from './server.ts'
+import { AbracadabraMCPServer, type TriggerMode } from './server.ts'
 import { registerTreeTools } from './tools/tree.ts'
 import { registerContentTools } from './tools/content.ts'
 import { registerMetaTools } from './tools/meta.ts'
@@ -33,6 +41,21 @@ async function main() {
     process.exit(1)
   }
 
+  // Parse trigger mode (defaults to mention+task)
+  const rawMode = (process.env.ABRA_AGENT_TRIGGER_MODE ?? 'mention+task').trim().toLowerCase()
+  const validModes: TriggerMode[] = ['all', 'mention', 'task', 'mention+task']
+  const triggerMode = (validModes as string[]).includes(rawMode)
+    ? (rawMode as TriggerMode)
+    : 'mention+task'
+  if (rawMode && !(validModes as string[]).includes(rawMode)) {
+    console.error(`[abracadabra-mcp] Invalid ABRA_AGENT_TRIGGER_MODE="${rawMode}", falling back to "mention+task"`)
+  }
+
+  const aliasEnv = process.env.ABRA_AGENT_MENTION_ALIASES
+  const mentionAliases: string[] | undefined = aliasEnv
+    ? aliasEnv.split(',').map((a: string) => a.trim()).filter((a: string) => a.length > 0)
+    : undefined
+
   // Create the Abracadabra connection manager
   const server = new AbracadabraMCPServer({
     url,
@@ -40,8 +63,12 @@ async function main() {
     agentColor: process.env.ABRA_AGENT_COLOR,
     inviteCode: process.env.ABRA_INVITE_CODE,
     keyFile: process.env.ABRA_KEY_FILE,
+    triggerMode,
+    mentionAliases,
   })
 
+  console.error(`[abracadabra-mcp] Trigger mode: ${triggerMode}; aliases: ${server.mentionAliases.join(', ')}`)
+
   // Create MCP server with channel capability
   const mcp = new McpServer(
     { name: 'abracadabra', version: '1.0.0' },

package/src/mentions.ts

@@ -0,0 +1,42 @@
+/**
+ * Mention parsing for chat messages.
+ *
+ * Recognizes `@alias` tokens (case-insensitive, word-boundary) so the agent
+ * can decide whether a group-chat message is directed at it.
+ */
+
+/** Escape regex metacharacters in an alias string. */
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Build a regex that matches `@<alias>` for any of the given aliases.
+ * Requires a non-word char (or start) before `@` and a word boundary after the alias
+ * so `@Claude` matches but `email@claudesomething` does not.
+ */
+function buildMentionRegex(aliases: string[]): RegExp | null {
+  const cleaned = aliases.map(a => a.trim()).filter(a => a.length > 0)
+  if (cleaned.length === 0) return null
+  const alt = cleaned.map(escapeRegex).join('|')
+  return new RegExp(`(?:^|[^\\w@])@(?:${alt})\\b`, 'i')
+}
+
+/** Returns true if `text` contains `@alias` for any alias (case-insensitive). */
+export function containsMention(text: string, aliases: string[]): boolean {
+  const re = buildMentionRegex(aliases)
+  if (!re) return false
+  return re.test(text)
+}
+
+/**
+ * Remove `@alias` tokens from the text. Leaves surrounding whitespace tidy so
+ * the cleaned prompt reads naturally (e.g. `"@Claude help"` → `"help"`).
+ */
+export function stripMention(text: string, aliases: string[]): string {
+  const cleaned = aliases.map(a => a.trim()).filter(a => a.length > 0)
+  if (cleaned.length === 0) return text
+  const alt = cleaned.map(escapeRegex).join('|')
+  const re = new RegExp(`(^|\\s)@(?:${alt})\\b[,:]?\\s*`, 'gi')
+  return text.replace(re, (_m, lead) => (lead ? ' ' : '')).replace(/\s{2,}/g, ' ').trim()
+}

package/src/server.ts

@@ -12,6 +12,16 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { waitForSync } from './utils.ts'
 import { loadOrCreateKeypair, signChallenge } from './crypto.ts'
+import { containsMention, stripMention } from './mentions.ts'
+
+/**
+ * Controls when the agent reacts to incoming chat:
+ * - `all`          — respond to every message in every visible channel (legacy)
+ * - `mention`      — group chats require `@<alias>`; DMs always respond
+ * - `task`         — ignore chat entirely; only respond to ai:task awareness events
+ * - `mention+task` — group chats require mention OR ai:task; DMs always respond (default)
+ */
+export type TriggerMode = 'all' | 'mention' | 'task' | 'mention+task'
 
 export interface MCPServerConfig {
   url: string
@@ -19,6 +29,9 @@ export interface MCPServerConfig {
   agentColor?: string
   inviteCode?: string
   keyFile?: string
+  triggerMode?: TriggerMode
+  /** Aliases matched in `@<alias>` tokens. Defaults to `[agentName]`. */
+  mentionAliases?: string[]
 }
 
 interface SpaceConnection {
@@ -52,6 +65,9 @@ export class AbracadabraMCPServer {
   private _typingInterval: ReturnType<typeof setInterval> | null = null
   private _lastChatChannel: string | null = null
   private _signFn: ((challenge: string) => Promise<string>) | null = null
+  /** Rolling buffer of the last N tool calls in the current turn, surfaced via awareness. */
+  private _toolHistory: Array<{ tool: string; target?: string; ts: number; channel: string | null }> = []
+  private static readonly TOOL_HISTORY_MAX = 20
 
   constructor(config: MCPServerConfig) {
     this.config = config
@@ -69,6 +85,16 @@ export class AbracadabraMCPServer {
     return this.config.agentColor || 'hsl(270, 80%, 60%)'
   }
 
+  get triggerMode(): TriggerMode {
+    return this.config.triggerMode ?? 'mention+task'
+  }
+
+  get mentionAliases(): string[] {
+    const explicit = this.config.mentionAliases?.filter(a => a.trim().length > 0)
+    if (explicit && explicit.length > 0) return explicit
+    return [this.agentName]
+  }
+
   get serverInfo(): ServerInfo | null {
     return this._serverInfo
   }
@@ -121,7 +147,7 @@ export class AbracadabraMCPServer {
         throw err
       }
     }
-    console.error(`[abracadabra-mcp] Authenticated as ${this.agentName} (${keypair.publicKeyB64.slice(0, 12)}...)`)
+    console.error(`[abracadabra-mcp] Authenticated as ${this.agentName} (pubkey=${keypair.publicKeyB64})`)
 
     // Step 3: Discover server info
     this._serverInfo = await this.client.serverInfo()
@@ -209,6 +235,8 @@ export class AbracadabraMCPServer {
     provider.awareness.setLocalStateField('status', null)
     provider.awareness.setLocalStateField('activeToolCall', null)
     provider.awareness.setLocalStateField('statusContext', null)
+    provider.awareness.setLocalStateField('turnId', null)
+    provider.awareness.setLocalStateField('toolHistory', [])
 
     const conn: SpaceConnection = { doc, provider, docId }
     this._spaceConnections.set(docId, conn)
@@ -359,6 +387,9 @@ export class AbracadabraMCPServer {
   private _observeRootAwareness(provider: AbracadabraProvider): void {
     const selfId = provider.awareness.clientID
     provider.awareness.on('change', () => {
+      // Strict `mention` mode ignores ai:task awareness; every other mode honors it.
+      if (this.triggerMode === 'mention') return
+
       const states = provider.awareness.getStates()
       for (const [clientId, state] of states) {
         if (clientId === selfId) continue
@@ -376,6 +407,7 @@ export class AbracadabraMCPServer {
           : 'Unknown'
 
         console.error(`[abracadabra-mcp] Handling ai:task id=${id} from ${senderName}: ${text.slice(0, 80)}`)
+        this._beginTurn()
         this.setAutoStatus('thinking')
         this._dispatchAiTask({
           id,
@@ -446,15 +478,45 @@ export class AbracadabraMCPServer {
 
       const channel = data.channel as string | undefined
       const docId = channel?.startsWith('group:') ? channel.slice(6) : ''
+      const isDM = channel?.startsWith('dm:') ?? false
+      const isGroup = channel?.startsWith('group:') ?? false
 
       // Only process DMs where the agent is a participant
-      if (channel?.startsWith('dm:')) {
-        const parts = channel.split(':')
+      if (isDM) {
+        const parts = channel!.split(':')
         if (parts.length === 3 && parts[1] !== this._userId && parts[2] !== this._userId) {
+          console.error(
+            `[abracadabra-mcp] Dropping DM: agent _userId=${this._userId} not in channel parts=[${parts[1]}, ${parts[2]}] — channel='${channel}'. ` +
+            `The dashboard's awareness likely points at a stale Claude identity.`,
+          )
           return
         }
       }
 
+      // ── Trigger mode gate ─────────────────────────────────────────────
+      // DMs always dispatch (implicit summon). Groups obey the trigger mode.
+      const mode = this.triggerMode
+      const content = typeof data.content === 'string' ? data.content : ''
+      let dispatchContent = content
+
+      if (isGroup) {
+        if (mode === 'task') {
+          // Chat never triggers in task-only mode
+          return
+        }
+        if (mode === 'mention' || mode === 'mention+task') {
+          const aliases = this.mentionAliases
+          if (!containsMention(content, aliases)) {
+            console.error(`[abracadabra-mcp] skipped message on ${channel} — no @mention for ${aliases.join('|')}`)
+            return
+          }
+          // Strip the mention so Claude sees a clean prompt
+          dispatchContent = stripMention(content, aliases) || content
+        }
+        // mode === 'all' falls through unchanged
+      }
+      // ──────────────────────────────────────────────────────────────────
+
       // Auto-mark channel as read so sender sees a read receipt
       if (channel) {
         const rootProvider = this._activeConnection?.provider
@@ -465,19 +527,22 @@ export class AbracadabraMCPServer {
             timestamp: Math.floor(Date.now() / 1000),
           }))
         }
-        // Send immediate typing indicator and start periodic re-sends
+        // Remember the channel so setAutoStatus can scope statusContext to it.
+        // NOTE: no typing indicator here — "thinking" status + tool pills are
+        // the correct signal while Claude is working; typing is reserved for
+        // the actual send_chat_message burst below.
         this._lastChatChannel = channel
-        this.sendTypingIndicator(channel)
-        this._startTypingInterval(channel)
       }
 
-      // Set status to "thinking" so dashboard shows AI is processing
+      // Mint a fresh turn id so the dashboard ties its incantation + tool
+      // trace to THIS turn, and set status to "thinking".
+      this._beginTurn()
       this.setAutoStatus('thinking')
 
       await this._serverRef.notification({
         method: 'notifications/claude/channel',
         params: {
-          content: data.content ?? '',
+          content: dispatchContent,
           instructions: `You MUST use send_chat_message with channel="${channel ?? ''}" for ALL responses — both progress updates and final answers. The user CANNOT see plain text output; they only see messages sent via send_chat_message. When doing multi-step work, send brief status updates via send_chat_message (e.g. "Looking into that..." or "Found it, writing up results...") so the user knows you're working. Never output plain text as a substitute for send_chat_message.`,
           meta: {
             source: 'abracadabra',
@@ -518,23 +583,47 @@ export class AbracadabraMCPServer {
     const context = status ? (statusContext !== undefined ? statusContext : this._lastChatChannel) : null
     provider.awareness.setLocalStateField('statusContext', context ?? null)
 
-    // When clearing status, also stop typing interval
+    // When clearing status this is the authoritative end-of-turn signal:
+    // drop the tool pill, the turn id, and the running tool history so the
+    // dashboard's incantation + activity trace all collapse in lockstep.
     if (!status) {
       this._stopTypingInterval()
+      provider.awareness.setLocalStateField('activeToolCall', null)
+      provider.awareness.setLocalStateField('turnId', null)
+      this._toolHistory = []
+      provider.awareness.setLocalStateField('toolHistory', [])
     }
 
-    // Auto-clear status after 30s of no updates (generous timeout so status
-    // persists visibly between consecutive tool calls instead of flickering)
+    // Auto-clear status after 10s of no updates. Short enough that a real
+    // idle is noticed quickly; long enough that normal inter-tool gaps
+    // (PostToolUse → next PreToolUse) don't flicker.
     if (status) {
       this._statusClearTimer = setTimeout(() => {
         provider.awareness.setLocalStateField('status', null)
         provider.awareness.setLocalStateField('activeToolCall', null)
         provider.awareness.setLocalStateField('statusContext', null)
+        provider.awareness.setLocalStateField('turnId', null)
+        this._toolHistory = []
+        provider.awareness.setLocalStateField('toolHistory', [])
         this._stopTypingInterval()
-      }, 30_000)
+      }, 10_000)
     }
   }
 
+  /**
+   * Start a new agent turn. Mints a fresh UUID and writes it to awareness so
+   * the dashboard can gate the incantation on "there is an active turn",
+   * decoupled from the (racier) status field. Called from chat arrival and
+   * ai:task dispatch right before `setAutoStatus('thinking')`.
+   */
+  private _beginTurn(): void {
+    const provider = this._activeConnection?.provider
+    if (!provider) return
+    this._toolHistory = []
+    provider.awareness.setLocalStateField('toolHistory', [])
+    provider.awareness.setLocalStateField('turnId', crypto.randomUUID())
+  }
+
   /** Re-send typing indicator every 2s so dashboard keeps showing it (expires at 3s). */
   private _startTypingInterval(channel: string): void {
     this._stopTypingInterval()
@@ -553,10 +642,30 @@ export class AbracadabraMCPServer {
 
   /**
    * Broadcast which tool the agent is currently executing.
-   * Dashboard renders this as a ChatTool indicator.
+   *
+   * Renders as a ChatTool pill on the dashboard. On non-null calls, the tool
+   * is also appended to `toolHistory` (capped at TOOL_HISTORY_MAX) and written
+   * to awareness so the dashboard's inline trace can show the turn's recent
+   * activity. Tools do NOT clear (`setActiveToolCall(null)`) on completion —
+   * the pill stays until the next tool replaces it or `setAutoStatus(null)`
+   * flushes the turn. This keeps pills visible long enough to see.
    */
   setActiveToolCall(toolCall: { name: string; target?: string } | null): void {
-    this._activeConnection?.provider?.awareness.setLocalStateField('activeToolCall', toolCall)
+    const provider = this._activeConnection?.provider
+    if (!provider) return
+    provider.awareness.setLocalStateField('activeToolCall', toolCall)
+    if (toolCall) {
+      this._toolHistory.push({
+        tool: toolCall.name,
+        target: toolCall.target,
+        ts: Date.now(),
+        channel: this._lastChatChannel,
+      })
+      if (this._toolHistory.length > AbracadabraMCPServer.TOOL_HISTORY_MAX) {
+        this._toolHistory.splice(0, this._toolHistory.length - AbracadabraMCPServer.TOOL_HISTORY_MAX)
+      }
+      provider.awareness.setLocalStateField('toolHistory', [...this._toolHistory])
+    }
   }
 
   /**
@@ -594,8 +703,11 @@ export class AbracadabraMCPServer {
       conn.provider.awareness.setLocalStateField('status', null)
       conn.provider.awareness.setLocalStateField('activeToolCall', null)
       conn.provider.awareness.setLocalStateField('statusContext', null)
+      conn.provider.awareness.setLocalStateField('turnId', null)
+      conn.provider.awareness.setLocalStateField('toolHistory', [])
       conn.provider.destroy()
     }
+    this._toolHistory = []
     this._spaceConnections.clear()
     this._activeConnection = null
 

package/src/tools/awareness.ts

@@ -38,6 +38,7 @@ export function registerAwarenessTools(mcp: McpServer, server: AbracadabraMCPSer
       fields: z.record(z.string(), z.unknown()).describe('Key-value pairs to set on the child document\'s awareness state. Use namespaced keys like "kanban:hovering", "table:editing", "slides:viewing", "outline:editing", "calendar:focused", "gallery:focused", "timeline:focused", "graph:focused", "map:focused", "doc:scroll". Set a key to null to clear it.'),
     },
     async ({ docId, fields }) => {
+      server.setActiveToolCall({ name: 'set_doc_awareness', target: docId })
       try {
         const provider = await server.getChildProvider(docId)
         for (const [key, value] of Object.entries(fields)) {
@@ -58,6 +59,7 @@ export function registerAwarenessTools(mcp: McpServer, server: AbracadabraMCPSer
     'Check the "AI Inbox" document for pending instructions from humans. Returns the inbox content and any pending task sub-documents. Create the inbox as a doc called "AI Inbox" under the hub doc if it does not exist yet. Note: channel-based watching via watch_chat is preferred for real-time use.',
     {},
     async () => {
+      server.setActiveToolCall({ name: 'poll_inbox' })
       try {
         const treeMap = server.getTreeMap()
         const rootDocId = server.rootDocId
@@ -124,6 +126,7 @@ export function registerAwarenessTools(mcp: McpServer, server: AbracadabraMCPSer
       docId: z.string().optional().describe('If provided, list users connected to this specific document. Otherwise lists users from root awareness.'),
     },
     async ({ docId }) => {
+      server.setActiveToolCall({ name: 'list_connected_users', target: docId })
       try {
         let awareness
         if (docId) {