@abraca/mcp 1.6.0 → 1.8.1

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/resources/agent-guide.ts

@@ -1,7 +1,7 @@
 /**
  * Static resource: AI agent guide for working with Abracadabra documents.
  */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 const AGENT_GUIDE = `# Abracadabra AI Agent Guide
 
@@ -47,24 +47,38 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 
 ## Page Types Reference
 
+### Core Types (always available)
+
 | Type | Children Are | Grandchildren Are | Depth | Key Meta on Children |
 |------|-------------|-------------------|-------|---------------------|
 | **doc** | Sub-documents | Sub-sub-documents | ∞ | — |
 | **kanban** | Columns | Cards | 2 | color, icon on cards |
 | **table** | Columns | Cells (positional rows) | 2 | — |
-| **calendar** | Events | — | 1 | datetimeStart, datetimeEnd, allDay, color |
+| **calendar** | Events | — | 1 | datetimeStart, datetimeEnd, allDay, color, icon |
 | **timeline** | Epics | Tasks | 2 | dateStart, dateEnd, taskProgress, color |
 | **checklist** | Tasks | Sub-tasks | ∞ | checked, priority, dateEnd |
 | **outline** | Items | Sub-items | ∞ | — |
-| **mindmap** | Central nodes | Branches | ∞ | mmX, mmY |
 | **graph** | Nodes | — | 1 | graphX, graphY, graphPinned, color |
-| **gallery** | Items | — | 1 | geoLat, geoLng, datetimeStart, tags |
+| **gallery** | Items | — | 1 | geoLat, geoLng, datetimeStart, tags, rating, icon, color |
 | **map** | Markers/Lines | Points (for lines) | 2 | geoType, geoLat, geoLng, icon, color |
-| **dashboard** | Items | — | 1 | deskX, deskY, deskMode |
-| **spatial** | Objects | Sub-parts | ∞ | spShape, spX/Y/Z, spColor, spOpacity |
-| **media** | Tracks | — | 1 | tags |
-| **slides** | Slides | — | 1 | — |
-| **whiteboard** | Objects | — | 1 | wbX, wbY, wbW, wbH |
+| **slides** | Slides | Sub-slides | 2 | slidesTransition, color |
+| **dashboard** | Items | — | 1 | deskX, deskY, deskZ, deskMode |
+| **chart** | Data points | Data points | 2 | number (value), color, tags |
+| **sheets** | Columns | Cells | 2 | formula, bold, italic, textColor, bgColor, align |
+| **overview** | Pages | — | 1 | — |
+| **call** | — (no children) | — | 0 | — |
+
+Alias: \`desktop\` → \`dashboard\`.
+
+### Plugin Types (require plugin enabled on the server)
+
+| Type | Plugin | Children Are | Grandchildren Are | Depth | Key Meta on Children |
+|------|--------|-------------|-------------------|-------|---------------------|
+| **spatial** | spatial | Objects | Sub-parts | ∞ | spShape, spX/Y/Z, spRX/RY/RZ, spSX/SY/SZ, color, spOpacity |
+| **media** | media | Tracks | — | ∞ | tags |
+| **coder** | coder | Files/Folders | — | ∞ | fileType, entry |
+
+> Spatial uses the universal \`color\` key for object color — there is no \`spColor\`.
 
 ---
 
@@ -137,18 +151,65 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 4. Modes: \`"icon"\` (small), \`"widget-sm"\` (240×180), \`"widget-lg"\` (400×320)
 5. Grid uses 80px cells
 
-**Spatial (3D scene):**
+**Spatial (3D scene)** *(requires spatial plugin):*
 1. \`create_document(parentId, "3D Scene", "spatial")\`
 2. Create objects: \`create_document(sceneId, "Red Cube")\`
-3. Set 3D properties: \`update_metadata(objId, { spShape: "box", spColor: "#ef4444", spX: 0, spY: 1, spZ: 0, spSX: 2, spSY: 2, spSZ: 2 })\`
-4. Shapes: \`"box"\`, \`"sphere"\`, \`"cylinder"\`, \`"cone"\`, \`"plane"\`, \`"torus"\`, \`"glb"\` (uploaded 3D model)
+3. Set 3D properties: \`update_metadata(objId, { spShape: "box", color: "#ef4444", spX: 0, spY: 1, spZ: 0, spSX: 2, spSY: 2, spSZ: 2 })\`
+4. Shapes: \`"box"\`, \`"sphere"\`, \`"cylinder"\`, \`"cone"\`, \`"plane"\`, \`"torus"\`, \`"glb"\` (uploaded 3D model — set \`spModelUploadId\` and \`spModelDocId\`)
 5. Rotation (degrees): \`spRX\`, \`spRY\`, \`spRZ\`. Scale: \`spSX\`, \`spSY\`, \`spSZ\` (default 1). Opacity: \`spOpacity\` (0–100)
+6. Use the universal \`color\` key — **never \`spColor\`**
 
 **Outline (nested items):**
 1. \`create_document(parentId, "Meeting Notes", "outline")\`
 2. Create items: \`create_document(outlineId, "Agenda Item 1")\`
 3. Create sub-items (unlimited depth): \`create_document(itemId, "Sub-point")\`
 
+**Slides (presentation with two-axis nav):**
+1. \`create_document(parentId, "Q1 Review", "slides")\`
+2. Create slides as direct children: \`create_document(deckId, "Intro")\`
+3. Create sub-slides (vertical navigation) as grandchildren: \`create_document(slideId, "Deep dive")\`
+4. Per-slide transition: \`update_metadata(slideId, { slidesTransition: "fade", color: "#6366f1" })\`
+5. Deck-level theme: \`update_metadata(deckId, { slidesTheme: "dark" })\`
+
+**Chart (data viz — manual or aggregation):**
+1. \`create_document(parentId, "Sales", "chart")\`
+2. Configure: \`update_metadata(chartId, { chartType: "bar", chartMetric: "value", chartShowLegend: true, chartLimit: 10 })\`
+3. Modes:
+   - **Manual data points**: create children with \`number\` (value) and optional \`tags\`/\`color\`
+     \`create_document(chartId, "Q1")\` then \`update_metadata(dpId, { number: 42500, color: "#6366f1" })\`
+   - **Aggregation**: set \`chartMetric\` to \`"type"\`/\`"tag"\`/\`"status"\`/\`"priority"\`/\`"activity"\`/\`"completion"\` and point the chart at a subtree — it aggregates the descendants' meta automatically
+4. Chart types: \`"bar"\`, \`"stacked bar"\`, \`"line"\`, \`"donut"\`, \`"treemap"\`
+5. Color schemes: \`"default"\`, \`"warm"\`, \`"cool"\`, \`"mono"\`
+
+**Sheets (spreadsheet with formulas):**
+1. \`create_document(parentId, "Budget", "sheets")\`
+2. Create columns: \`create_document(sheetId, "A")\`, \`create_document(sheetId, "B")\`
+3. Create cells under columns (positional rows, like \`table\`)
+4. Formulas on cells: \`update_metadata(cellId, { formula: "=A1+B1" })\`
+5. Cell formatting: \`update_metadata(cellId, { bold: true, bgColor: "#fef3c7", align: "right" })\`
+6. Deck config: \`update_metadata(sheetId, { sheetsDefaultColWidth: 120, sheetsDefaultRowHeight: 28, sheetsShowGridlines: true, sheetsFreezeRows: 1, sheetsFreezeCols: 1 })\`
+
+**Overview (space home):**
+1. \`create_document(parentId, "Home", "overview")\`
+2. No children required — renders activity, people, stats from the surrounding space
+3. Children (if any) show as linked pages
+
+**Call (video room):**
+1. \`create_document(parentId, "Daily Standup", "call")\`
+2. Video rooms have **no children** — do not add documents underneath
+
+**Coder (multi-file collaborative editor)** *(requires coder plugin):*
+1. \`create_document(parentId, "My App", "coder")\`
+2. Create files/folders: \`create_document(projectId, "App.vue")\`, \`create_document(projectId, "src")\`
+3. Set file type: \`update_metadata(fileId, { fileType: "vue", entry: true })\`
+4. \`fileType\` options: \`"vue"\`, \`"ts"\`, \`"js"\`, \`"css"\`, \`"json"\`, \`"folder"\`
+5. Mark the entry file with \`entry: true\` — the renderer uses it as the preview root
+
+**Media (audio/video playlist)** *(requires media plugin):*
+1. \`create_document(parentId, "Focus Mix", "media")\`
+2. Create tracks: \`create_document(playlistId, "Track 1")\` — attach audio/video file via upload tool
+3. Playlist config: \`update_metadata(playlistId, { mediaRepeat: "all", mediaShuffle: false })\`
+
 ---
 
 ## Document References
@@ -223,22 +284,55 @@ In the **graph** page type, document references (embeds and links) create visibl
 |-----|------|-----------|--------|
 | \`kanbanColumnWidth\` | string | kanban | "narrow", "default", "wide" |
 | \`galleryColumns\` | number | gallery | 1–6 |
-| \`galleryAspect\` | string | gallery | "square", "4:3", "16:9" |
+| \`galleryAspect\` | string | gallery | "square", "4:3", "3:2", "16:9", "free" |
+| \`galleryCardStyle\` | string | gallery | "default", "compact", "detailed" |
+| \`galleryShowLabels\` | boolean | gallery | show item labels |
+| \`gallerySortBy\` | string | gallery | "manual", "date", "name", "rating" |
 | \`calendarView\` | string | calendar | "month", "week", "day" |
 | \`calendarWeekStart\` | string | calendar | "sun", "mon" |
+| \`calendarShowWeekNumbers\` | boolean | calendar | — |
 | \`tableMode\` | string | table | "hierarchy", "flat" |
+| \`tableSortKey\` | string | table | meta key to sort by |
+| \`tableSortDir\` | string | table | "asc", "desc" |
+| \`timelineZoom\` | string | timeline | "week", "month", "quarter" |
+| \`timelinePixelsPerDay\` | number | timeline | zoom granularity |
+| \`timelineCenterDate\` | string | timeline | ISO date to center view |
+| \`checklistFilter\` | string | checklist | "all", "active", "completed" |
+| \`checklistSort\` | string | checklist | "manual", "priority", "due" |
+| \`mapShowLabels\` | boolean | map | — |
+| \`graphSpacing\` | string | graph | "compact", "default", "spacious" |
+| \`graphShowLabels\` | boolean | graph | — |
+| \`graphEdgeThickness\` | string | graph | "thin", "normal", "thick" |
 | \`showRefEdges\` | boolean | graph | show doc-reference edges |
-
-### Spatial 3D Keys (for spatial children)
+| \`mmSpacing\` | string | mindmap-layout | spacing between branches |
+| \`spatialGridVisible\` | boolean | spatial | show ground grid |
+| \`slidesTheme\` | string | slides | "dark", "light" |
+| \`chartType\` | string | chart | "bar", "stacked bar", "line", "donut", "treemap" |
+| \`chartMetric\` | string | chart | "value", "type", "tag", "status", "priority", "activity", "completion" |
+| \`chartColorScheme\` | string | chart | "default", "warm", "cool", "mono" |
+| \`chartLimit\` | number | chart | 3–30 (max items) |
+| \`chartShowLegend\` | boolean | chart | — |
+| \`chartShowValues\` | boolean | chart | — |
+| \`sheetsDefaultColWidth\` | number | sheets | 40–500 |
+| \`sheetsDefaultRowHeight\` | number | sheets | 20–100 |
+| \`sheetsShowGridlines\` | boolean | sheets | — |
+| \`sheetsFreezeRows\` | number | sheets | frozen rows count |
+| \`sheetsFreezeCols\` | number | sheets | frozen cols count |
+| \`mediaRepeat\` | string | media | "off", "all", "one" (plugin) |
+| \`mediaShuffle\` | boolean | media | plugin |
+
+### Spatial 3D Keys (for spatial children — requires spatial plugin)
 
 | Key | Type | Default | Meaning |
 |-----|------|---------|---------|
 | \`spShape\` | string | — | "box", "sphere", "cylinder", "cone", "plane", "torus", "glb" |
-| \`spColor\` | string | — | CSS color |
+| \`color\` | string | — | CSS color — universal key, **not** \`spColor\` |
 | \`spOpacity\` | number | 100 | 0–100 |
 | \`spX\`, \`spY\`, \`spZ\` | number | 0 | Position |
 | \`spRX\`, \`spRY\`, \`spRZ\` | number | 0 | Rotation (degrees) |
 | \`spSX\`, \`spSY\`, \`spSZ\` | number | 1 | Scale |
+| \`spModelUploadId\` | string | — | GLB upload ID (when \`spShape: "glb"\`) |
+| \`spModelDocId\` | string | — | Doc ID that owns the GLB upload |
 
 ### Dashboard Keys (for dashboard children)
 
@@ -248,6 +342,28 @@ In the **graph** page type, document references (embeds and links) create visibl
 | \`deskZ\` | number | Z-index (layering) |
 | \`deskMode\` | string | "icon", "widget-sm" (240×180), "widget-lg" (400×320) |
 
+### Sheets Cell Formatting (per-cell meta)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`formula\` | string | Cell formula (e.g. "=A1+B1") |
+| \`bold\` | boolean | — |
+| \`italic\` | boolean | — |
+| \`textColor\` | string | CSS color |
+| \`bgColor\` | string | CSS color |
+| \`align\` | string | "left", "center", "right" |
+
+### Coder Keys (for coder children — plugin)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`fileType\` | string | "vue", "ts", "js", "css", "json", "folder" |
+| \`entry\` | boolean | Mark this file as the preview entry point |
+
+### Discovering What Metadata Applies
+
+Use the \`list_page_types\` tool to enumerate all known page types and their declared \`metaSchema\` (fields that apply to children/descendants) and \`defaultMetaFields\` (renderer config fields on the page itself). It's the authoritative list of what meta keys make sense for any given page type.
+
 ---
 
 ## Content Structure
@@ -330,8 +446,11 @@ Always clear fields when done by setting them to \`null\`.
 | **Outline** | \`outline:editing\` | nodeId | Editing an outline node |
 | **Gallery** | \`gallery:focused\` | itemId | Item hovered/selected |
 | **Timeline** | \`timeline:focused\` | taskId | Task selected |
-| **Mindmap** | \`mindmap:focused\` | nodeId | Node selected/edited |
 | **Graph** | \`graph:focused\` | nodeId | Node hovered/selected |
+| **Slides** | \`slides:current\` | slideId | Slide being presented |
+| **Spatial** | \`spatial:selected\`, \`spatial:camera\` | objectId / camera state | plugin |
+| **Media** | \`media:playing\`, \`media:position\` | trackId / 0–1 | plugin |
+| **Coder** | \`coder:activeFile\` | fileId | plugin |
 | **Map** | \`map:focused\` | markerId | Marker hovered/selected |
 | **Doc** | \`doc:scroll\` | 0–1 number | Scroll position in document |
 
@@ -414,22 +533,25 @@ Always check and traverse the \`children\` array returned by \`read_document\`.*
 - Create top-level documents without first confirming the correct hub doc ID
 - Rename or write content to the space hub document itself
 - Set \`type\` on child items (cards, cells, events) — only set type on the parent page
-`
+`;
 
 export function registerAgentGuide(mcp: McpServer) {
   mcp.resource(
-    'agent-guide',
-    'abracadabra://agent-guide',
+    "agent-guide",
+    "abracadabra://agent-guide",
     {
-      description: 'Comprehensive guide for AI agents working with Abracadabra documents. Covers page types, tree operations, metadata, content structure, and best practices.',
-      mimeType: 'text/markdown',
+      description:
+        "Comprehensive guide for AI agents working with Abracadabra documents. Covers page types, tree operations, metadata, content structure, and best practices.",
+      mimeType: "text/markdown",
     },
     async () => ({
-      contents: [{
-        uri: 'abracadabra://agent-guide',
-        text: AGENT_GUIDE,
-        mimeType: 'text/markdown',
-      }],
-    })
-  )
+      contents: [
+        {
+          uri: "abracadabra://agent-guide",
+          text: AGENT_GUIDE,
+          mimeType: "text/markdown",
+        },
+      ],
+    }),
+  );
 }

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)
@@ -249,6 +277,19 @@ export class AbracadabraMCPServer {
     return this._activeConnection?.doc.getMap('doc-trash') ?? null
   }
 
+  /** Get plugin names enabled in the active space via space-plugins Y.Map. */
+  getEnabledPluginNames(): string[] {
+    const doc = this._activeConnection?.doc
+    if (!doc) return []
+    const pluginsMap = doc.getMap('space-plugins')
+    const names: string[] = []
+    pluginsMap.forEach((value: any, key: string) => {
+      const entry = value?.toJSON ? value.toJSON() : value
+      if (entry?.enabled) names.push(key)
+    })
+    return names
+  }
+
   /**
    * Get or create a child provider for a given document ID.
    * Caches providers and waits for sync before returning.
@@ -346,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
@@ -363,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,
@@ -433,14 +478,44 @@ 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) {
@@ -452,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',
@@ -505,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()
@@ -540,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])
+    }
   }
 
   /**
@@ -581,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