@hasna/conversations 0.2.4 → 0.2.6

package/bin/hook.js

@@ -252,6 +252,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`

package/bin/index.js

@@ -2117,6 +2117,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -2330,6 +2344,12 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  if (opts.space) {
+    const mentions = parseMentions(opts.content);
+    if (mentions.length > 0) {
+      processMentions(message.id, opts.from, opts.space, mentions, db2);
+    }
+  }
   fireWebhooks(message);
   return message;
 }
@@ -2368,11 +2388,24 @@ function readMessages(opts = {}) {
   if (opts.unread_only) {
     conditions.push("read_at IS NULL");
   }
+  if (opts.threads_only) {
+    conditions.push("reply_to IS NULL");
+  }
+  if (opts.mentions_only) {
+    conditions.push(`id IN (SELECT message_id FROM message_mentions WHERE mentioned_agent = ?)`);
+    params.push(opts.mentions_only.toLowerCase());
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const resolvedLimit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
   const order = opts.order?.toLowerCase() === "desc" ? "DESC" : "ASC";
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at ${order}, id ${order} LIMIT ${resolvedLimit}`).all(...params);
   let messages = rows.map(parseMessage);
+  if (opts.include_reply_counts && messages.length > 0) {
+    const db22 = getDb();
+    const counts = db22.prepare(`SELECT reply_to, COUNT(*) as c FROM messages WHERE reply_to IN (${messages.map(() => "?").join(",")}) GROUP BY reply_to`).all(...messages.map((m) => m.id));
+    const countMap = new Map(counts.map((r) => [r.reply_to, r.c]));
+    messages = messages.map((m) => ({ ...m, reply_count: countMap.get(m.id) ?? 0 }));
+  }
   if (opts.max_content_length && opts.max_content_length > 0) {
     messages = messages.map((m) => {
       if (m.content.length > opts.max_content_length) {
@@ -2685,6 +2718,73 @@ function listUnreadCounts(agent) {
   `).all();
   return rows;
 }
+function parseMentions(content) {
+  const matches = content.match(/@([a-zA-Z0-9_-]+)/g) ?? [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+async function processMentions(messageId, fromAgent, space, mentionedAgents, db2) {
+  const stmt = db2.prepare("INSERT INTO message_mentions (message_id, mentioned_agent, from_agent, space) VALUES (?, ?, ?, ?)");
+  for (const agent of mentionedAgents) {
+    try {
+      stmt.run(messageId, agent, fromAgent, space);
+      if (agent !== fromAgent.toLowerCase()) {
+        sendMessage({
+          from: fromAgent,
+          to: agent,
+          content: `You were mentioned in #${space} by ${fromAgent} (message #${messageId})`,
+          metadata: { type: "mention_notification", source_message_id: messageId, space }
+        });
+      }
+    } catch {}
+  }
+}
+function listUnreadCountsWithMentions(agent) {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      space,
+      COUNT(CASE WHEN read_at IS NULL AND (to_agent = ? OR to_agent IS NULL OR to_agent = '') THEN 1 END) AS unread_count,
+      (SELECT COUNT(*) FROM message_mentions mm WHERE mm.space = m.space AND mm.mentioned_agent = ? AND mm.notified_at IS NULL) AS mention_count,
+      MAX(created_at) AS latest_message_at
+    FROM messages m
+    WHERE space IN (
+      SELECT DISTINCT space FROM space_members WHERE agent = ?
+      UNION
+      SELECT DISTINCT space FROM messages WHERE to_agent = ? AND space IS NOT NULL
+    )
+    GROUP BY space
+    HAVING COUNT(*) > 0
+    ORDER BY mention_count DESC, unread_count DESC, latest_message_at DESC
+  `).all(agent, agent, agent, agent);
+  return rows;
+}
+function getMessagesForAgent(agent, opts) {
+  const db2 = getDb();
+  const conditions = ["mm.mentioned_agent = ?"];
+  const params = [agent.toLowerCase()];
+  if (opts?.space) {
+    conditions.push("m.space = ?");
+    params.push(opts.space);
+  }
+  if (opts?.unread_only) {
+    conditions.push("mm.notified_at IS NULL");
+  }
+  const limit = opts?.limit ?? 50;
+  const rows = db2.prepare(`SELECT m.*, mm.id AS mention_id FROM messages m
+     JOIN message_mentions mm ON mm.message_id = m.id
+     WHERE ${conditions.join(" AND ")}
+     ORDER BY m.created_at DESC LIMIT ${limit}`).all(...params);
+  return rows.map(({ mention_id, ...row }) => ({ message: parseMessage(row), mention_id }));
+}
+function markMentionsRead(agent, space) {
+  const db2 = getDb();
+  if (space) {
+    const result2 = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND space = ? AND notified_at IS NULL").run(agent, space);
+    return result2.changes;
+  }
+  const result = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND notified_at IS NULL").run(agent);
+  return result.changes;
+}
 var init_messages = __esm(() => {
   init_db();
   init_webhooks();
@@ -4324,7 +4424,7 @@ var init_poll = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/conversations",
-    version: "0.2.4",
+    version: "0.2.6",
     description: "Real-time CLI messaging for AI agents",
     type: "module",
     bin: {
@@ -33577,7 +33677,10 @@ var init_mcp2 = __esm(() => {
       limit: exports_external.coerce.number().optional(),
       unread_only: exports_external.coerce.boolean().optional(),
       mark_read: exports_external.coerce.boolean().optional(),
-      max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)")
+      max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)"),
+      threads_only: exports_external.coerce.boolean().optional().describe("Only return root messages (reply_to IS NULL) \u2014 hides thread replies"),
+      include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message (adds one extra query)"),
+      mentions_only: exports_external.string().optional().describe("Only return messages that @mention this agent")
     }
   }, async (args) => {
     const agent = resolveIdentity(args.from);
@@ -33605,7 +33708,7 @@ var init_mcp2 = __esm(() => {
     };
   });
   server.registerTool("reply", {
-    description: "Reply to a message by ID.",
+    description: "Reply to a specific message, creating a thread. Sets reply_to so it can be retrieved with get_thread_replies.",
     inputSchema: {
       message_id: exports_external.coerce.number(),
       content: exports_external.string(),
@@ -33622,13 +33725,13 @@ var init_mcp2 = __esm(() => {
     }
     const from = resolveIdentity(fromParam);
     const space = original.space || (original.session_id?.startsWith("space:") ? original.session_id.slice(6) : undefined);
-    const to = space ? space : original.from_agent === from ? original.to_agent : original.from_agent;
     const msg = sendMessage({
       from,
-      to,
+      to: space ?? (original.from_agent === from ? original.to_agent : original.from_agent),
       content,
       session_id: original.session_id,
-      space
+      space,
+      reply_to: message_id
     });
     return {
       content: [{ type: "text", text: JSON.stringify(msg) }]
@@ -33749,13 +33852,42 @@ var init_mcp2 = __esm(() => {
   server.registerTool("list_unread_counts", {
     description: "Get unread message counts per space without fetching message content. Use this at session start to triage which spaces need attention before calling read_messages.",
     inputSchema: {
-      agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts.")
+      agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts."),
+      include_mentions: exports_external.coerce.boolean().optional().describe("Include mention_count per space (requires agent)")
     }
   }, async (args) => {
+    if (args.agent && args.include_mentions) {
+      const counts2 = listUnreadCountsWithMentions(args.agent);
+      return { content: [{ type: "text", text: JSON.stringify(counts2) }] };
+    }
     const counts = listUnreadCounts(args.agent);
-    return {
-      content: [{ type: "text", text: JSON.stringify(counts) }]
-    };
+    return { content: [{ type: "text", text: JSON.stringify(counts) }] };
+  });
+  server.registerTool("get_mentions", {
+    description: "Get messages that @mention a specific agent. Useful for catching up on missed pings.",
+    inputSchema: {
+      agent: exports_external.string().describe("Agent name to find mentions for"),
+      space: exports_external.string().optional().describe("Filter to a specific space"),
+      unread_only: exports_external.coerce.boolean().optional().describe("Only unread (not yet notified) mentions (default: true)"),
+      limit: exports_external.coerce.number().optional().describe("Max results (default: 50)")
+    }
+  }, async (args) => {
+    const results = getMessagesForAgent(args.agent, {
+      space: args.space,
+      unread_only: args.unread_only ?? true,
+      limit: args.limit
+    });
+    return { content: [{ type: "text", text: JSON.stringify({ mentions: results, count: results.length }) }] };
+  });
+  server.registerTool("mark_mentions_read", {
+    description: "Mark @mentions as seen for an agent. Clears unread mention counts.",
+    inputSchema: {
+      agent: exports_external.string().describe("Agent name"),
+      space: exports_external.string().optional().describe("Clear only mentions in this space")
+    }
+  }, async (args) => {
+    const cleared = markMentionsRead(args.agent, args.space);
+    return { content: [{ type: "text", text: JSON.stringify({ cleared }) }] };
   });
   server.registerTool("send_to_space", {
     description: "Post a message to a space.",
@@ -33796,11 +33928,13 @@ var init_mcp2 = __esm(() => {
       since: exports_external.string().optional(),
       limit: exports_external.coerce.number().optional(),
       mark_read: exports_external.coerce.boolean().optional(),
-      max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)")
+      max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)"),
+      threads_only: exports_external.coerce.boolean().optional().describe("Only return root messages (hides thread replies)"),
+      include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message")
     }
   }, async (args) => {
-    const { space, since, limit, mark_read, max_content_length } = args;
-    const messages = readMessages({ space, since, limit, max_content_length });
+    const { space, since, limit, mark_read, max_content_length, threads_only, include_reply_counts } = args;
+    const messages = readMessages({ space, since, limit, max_content_length, threads_only, include_reply_counts });
     if (mark_read !== false && messages.length > 0) {
       markReadByIds(messages.map((m) => m.id));
     }
@@ -34451,13 +34585,30 @@ var init_mcp2 = __esm(() => {
     return { content: [{ type: "text", text: JSON.stringify({ released_stale_agent: stale, released_expired: expired, total: stale + expired }) }] };
   });
   server.registerTool("get_thread_replies", {
-    description: "Get all replies in a thread for a given parent message ID.",
+    description: "Get all replies in a thread for a given parent message ID. Also accessible as read_thread.",
     inputSchema: {
-      message_id: exports_external.coerce.number()
+      message_id: exports_external.coerce.number(),
+      limit: exports_external.coerce.number().optional()
+    }
+  }, async (args) => {
+    let replies = getThreadReplies(args.message_id);
+    if (args.limit)
+      replies = replies.slice(0, args.limit);
+    const parent = getMessageById(args.message_id);
+    return { content: [{ type: "text", text: JSON.stringify({ parent, replies, reply_count: replies.length }) }] };
+  });
+  server.registerTool("read_thread", {
+    description: "Alias for get_thread_replies. Read all replies to a specific message, forming a thread view.",
+    inputSchema: {
+      message_id: exports_external.coerce.number(),
+      limit: exports_external.coerce.number().optional()
     }
   }, async (args) => {
-    const replies = getThreadReplies(args.message_id);
-    return { content: [{ type: "text", text: JSON.stringify(replies) }] };
+    let replies = getThreadReplies(args.message_id);
+    if (args.limit)
+      replies = replies.slice(0, args.limit);
+    const parent = getMessageById(args.message_id);
+    return { content: [{ type: "text", text: JSON.stringify({ parent, replies, reply_count: replies.length }) }] };
   });
   server.registerTool("set_focus", {
     description: "Set agent focus to a project. All read-heavy tools will default to this project scope. Stores in MCP session memory AND updates agent_presence.project_id in DB.",
@@ -34705,7 +34856,7 @@ var init_mcp2 = __esm(() => {
       read_messages: "Read messages with filters. Optional: session_id?, from?, to?, space?, since?(ISO), limit?, unread_only?, mark_read?(default true \u2014 auto-marks returned messages as read, pass false to peek without consuming)",
       read_digest: "Lightweight unread digest \u2014 preview only (no full bodies), auto-marks read, never overflows tokens. Returns { messages, total_unread, shown }. Optional: space?, session_id?, to?, since?(ISO), limit?, project_id?",
       list_sessions: "List all DM sessions. Optional: agent?(filter by participant)",
-      reply: "Reply to a message in same session. Required: message_id, content. Optional: from?",
+      reply: "Reply to a specific message, creating a thread (sets reply_to). Use read_thread to retrieve. Required: message_id, content. Optional: from?",
       mark_read: "Mark messages as read. Optional: from?, ids?(array), all?(bool \u2014 mark all unread)",
       search_messages: "Full-text search messages. Required: query. Optional: space?, from?, to?, limit?",
       export_messages: "Export messages as JSON or CSV. Optional: space?, session_id?, from?, since?, until?, format?(json|csv)",
@@ -34749,6 +34900,7 @@ var init_mcp2 = __esm(() => {
       list_locks: "List active locks enriched with agent presence + time context. Optional: resource_type?, agent_id?",
       clean_expired_locks: "Release expired locks + locks held by agents with stale heartbeat (>30 min). Returns {released_stale_agent, released_expired, total}",
       get_thread_replies: "Get all replies in a thread. Required: message_id. Optional: limit?",
+      read_thread: "Alias for get_thread_replies. Required: message_id. Optional: limit?",
       set_focus: "Set agent focus to a project. All read tools default to this scope. Required: project_id. Optional: from?",
       get_focus: "Get current focus: session focus, DB project_id, effective project_id. Optional: from?",
       unfocus: "Clear agent focus (session + DB). Optional: from?",

package/bin/mcp.js

@@ -6749,6 +6749,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -28839,6 +28853,12 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  if (opts.space) {
+    const mentions = parseMentions(opts.content);
+    if (mentions.length > 0) {
+      processMentions(message.id, opts.from, opts.space, mentions, db2);
+    }
+  }
   fireWebhooks(message);
   return message;
 }
@@ -28877,11 +28897,24 @@ function readMessages(opts = {}) {
   if (opts.unread_only) {
     conditions.push("read_at IS NULL");
   }
+  if (opts.threads_only) {
+    conditions.push("reply_to IS NULL");
+  }
+  if (opts.mentions_only) {
+    conditions.push(`id IN (SELECT message_id FROM message_mentions WHERE mentioned_agent = ?)`);
+    params.push(opts.mentions_only.toLowerCase());
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const resolvedLimit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
   const order = opts.order?.toLowerCase() === "desc" ? "DESC" : "ASC";
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at ${order}, id ${order} LIMIT ${resolvedLimit}`).all(...params);
   let messages = rows.map(parseMessage);
+  if (opts.include_reply_counts && messages.length > 0) {
+    const db22 = getDb();
+    const counts = db22.prepare(`SELECT reply_to, COUNT(*) as c FROM messages WHERE reply_to IN (${messages.map(() => "?").join(",")}) GROUP BY reply_to`).all(...messages.map((m) => m.id));
+    const countMap = new Map(counts.map((r) => [r.reply_to, r.c]));
+    messages = messages.map((m) => ({ ...m, reply_count: countMap.get(m.id) ?? 0 }));
+  }
   if (opts.max_content_length && opts.max_content_length > 0) {
     messages = messages.map((m) => {
       if (m.content.length > opts.max_content_length) {
@@ -29182,6 +29215,73 @@ function listUnreadCounts(agent) {
   `).all();
   return rows;
 }
+function parseMentions(content) {
+  const matches = content.match(/@([a-zA-Z0-9_-]+)/g) ?? [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+async function processMentions(messageId, fromAgent, space, mentionedAgents, db2) {
+  const stmt = db2.prepare("INSERT INTO message_mentions (message_id, mentioned_agent, from_agent, space) VALUES (?, ?, ?, ?)");
+  for (const agent of mentionedAgents) {
+    try {
+      stmt.run(messageId, agent, fromAgent, space);
+      if (agent !== fromAgent.toLowerCase()) {
+        sendMessage({
+          from: fromAgent,
+          to: agent,
+          content: `You were mentioned in #${space} by ${fromAgent} (message #${messageId})`,
+          metadata: { type: "mention_notification", source_message_id: messageId, space }
+        });
+      }
+    } catch {}
+  }
+}
+function listUnreadCountsWithMentions(agent) {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      space,
+      COUNT(CASE WHEN read_at IS NULL AND (to_agent = ? OR to_agent IS NULL OR to_agent = '') THEN 1 END) AS unread_count,
+      (SELECT COUNT(*) FROM message_mentions mm WHERE mm.space = m.space AND mm.mentioned_agent = ? AND mm.notified_at IS NULL) AS mention_count,
+      MAX(created_at) AS latest_message_at
+    FROM messages m
+    WHERE space IN (
+      SELECT DISTINCT space FROM space_members WHERE agent = ?
+      UNION
+      SELECT DISTINCT space FROM messages WHERE to_agent = ? AND space IS NOT NULL
+    )
+    GROUP BY space
+    HAVING COUNT(*) > 0
+    ORDER BY mention_count DESC, unread_count DESC, latest_message_at DESC
+  `).all(agent, agent, agent, agent);
+  return rows;
+}
+function getMessagesForAgent(agent, opts) {
+  const db2 = getDb();
+  const conditions = ["mm.mentioned_agent = ?"];
+  const params = [agent.toLowerCase()];
+  if (opts?.space) {
+    conditions.push("m.space = ?");
+    params.push(opts.space);
+  }
+  if (opts?.unread_only) {
+    conditions.push("mm.notified_at IS NULL");
+  }
+  const limit = opts?.limit ?? 50;
+  const rows = db2.prepare(`SELECT m.*, mm.id AS mention_id FROM messages m
+     JOIN message_mentions mm ON mm.message_id = m.id
+     WHERE ${conditions.join(" AND ")}
+     ORDER BY m.created_at DESC LIMIT ${limit}`).all(...params);
+  return rows.map(({ mention_id, ...row }) => ({ message: parseMessage(row), mention_id }));
+}
+function markMentionsRead(agent, space) {
+  const db2 = getDb();
+  if (space) {
+    const result2 = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND space = ? AND notified_at IS NULL").run(agent, space);
+    return result2.changes;
+  }
+  const result = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND notified_at IS NULL").run(agent);
+  return result.changes;
+}
 
 // src/lib/sessions.ts
 init_db();
@@ -30808,7 +30908,7 @@ function getGraphStats() {
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.2.4",
+  version: "0.2.6",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -30940,7 +31040,10 @@ server.registerTool("read_messages", {
     limit: exports_external.coerce.number().optional(),
     unread_only: exports_external.coerce.boolean().optional(),
     mark_read: exports_external.coerce.boolean().optional(),
-    max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)")
+    max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)"),
+    threads_only: exports_external.coerce.boolean().optional().describe("Only return root messages (reply_to IS NULL) \u2014 hides thread replies"),
+    include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message (adds one extra query)"),
+    mentions_only: exports_external.string().optional().describe("Only return messages that @mention this agent")
   }
 }, async (args) => {
   const agent = resolveIdentity(args.from);
@@ -30968,7 +31071,7 @@ server.registerTool("list_sessions", {
   };
 });
 server.registerTool("reply", {
-  description: "Reply to a message by ID.",
+  description: "Reply to a specific message, creating a thread. Sets reply_to so it can be retrieved with get_thread_replies.",
   inputSchema: {
     message_id: exports_external.coerce.number(),
     content: exports_external.string(),
@@ -30985,13 +31088,13 @@ server.registerTool("reply", {
   }
   const from = resolveIdentity(fromParam);
   const space = original.space || (original.session_id?.startsWith("space:") ? original.session_id.slice(6) : undefined);
-  const to = space ? space : original.from_agent === from ? original.to_agent : original.from_agent;
   const msg = sendMessage({
     from,
-    to,
+    to: space ?? (original.from_agent === from ? original.to_agent : original.from_agent),
     content,
     session_id: original.session_id,
-    space
+    space,
+    reply_to: message_id
   });
   return {
     content: [{ type: "text", text: JSON.stringify(msg) }]
@@ -31112,13 +31215,42 @@ server.registerTool("list_spaces", {
 server.registerTool("list_unread_counts", {
   description: "Get unread message counts per space without fetching message content. Use this at session start to triage which spaces need attention before calling read_messages.",
   inputSchema: {
-    agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts.")
+    agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts."),
+    include_mentions: exports_external.coerce.boolean().optional().describe("Include mention_count per space (requires agent)")
   }
 }, async (args) => {
+  if (args.agent && args.include_mentions) {
+    const counts2 = listUnreadCountsWithMentions(args.agent);
+    return { content: [{ type: "text", text: JSON.stringify(counts2) }] };
+  }
   const counts = listUnreadCounts(args.agent);
-  return {
-    content: [{ type: "text", text: JSON.stringify(counts) }]
-  };
+  return { content: [{ type: "text", text: JSON.stringify(counts) }] };
+});
+server.registerTool("get_mentions", {
+  description: "Get messages that @mention a specific agent. Useful for catching up on missed pings.",
+  inputSchema: {
+    agent: exports_external.string().describe("Agent name to find mentions for"),
+    space: exports_external.string().optional().describe("Filter to a specific space"),
+    unread_only: exports_external.coerce.boolean().optional().describe("Only unread (not yet notified) mentions (default: true)"),
+    limit: exports_external.coerce.number().optional().describe("Max results (default: 50)")
+  }
+}, async (args) => {
+  const results = getMessagesForAgent(args.agent, {
+    space: args.space,
+    unread_only: args.unread_only ?? true,
+    limit: args.limit
+  });
+  return { content: [{ type: "text", text: JSON.stringify({ mentions: results, count: results.length }) }] };
+});
+server.registerTool("mark_mentions_read", {
+  description: "Mark @mentions as seen for an agent. Clears unread mention counts.",
+  inputSchema: {
+    agent: exports_external.string().describe("Agent name"),
+    space: exports_external.string().optional().describe("Clear only mentions in this space")
+  }
+}, async (args) => {
+  const cleared = markMentionsRead(args.agent, args.space);
+  return { content: [{ type: "text", text: JSON.stringify({ cleared }) }] };
 });
 server.registerTool("send_to_space", {
   description: "Post a message to a space.",
@@ -31159,11 +31291,13 @@ server.registerTool("read_space", {
     since: exports_external.string().optional(),
     limit: exports_external.coerce.number().optional(),
     mark_read: exports_external.coerce.boolean().optional(),
-    max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)")
+    max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)"),
+    threads_only: exports_external.coerce.boolean().optional().describe("Only return root messages (hides thread replies)"),
+    include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message")
   }
 }, async (args) => {
-  const { space, since, limit, mark_read, max_content_length } = args;
-  const messages = readMessages({ space, since, limit, max_content_length });
+  const { space, since, limit, mark_read, max_content_length, threads_only, include_reply_counts } = args;
+  const messages = readMessages({ space, since, limit, max_content_length, threads_only, include_reply_counts });
   if (mark_read !== false && messages.length > 0) {
     markReadByIds(messages.map((m) => m.id));
   }
@@ -31814,13 +31948,30 @@ server.registerTool("clean_expired_locks", {
   return { content: [{ type: "text", text: JSON.stringify({ released_stale_agent: stale, released_expired: expired, total: stale + expired }) }] };
 });
 server.registerTool("get_thread_replies", {
-  description: "Get all replies in a thread for a given parent message ID.",
+  description: "Get all replies in a thread for a given parent message ID. Also accessible as read_thread.",
   inputSchema: {
-    message_id: exports_external.coerce.number()
+    message_id: exports_external.coerce.number(),
+    limit: exports_external.coerce.number().optional()
+  }
+}, async (args) => {
+  let replies = getThreadReplies(args.message_id);
+  if (args.limit)
+    replies = replies.slice(0, args.limit);
+  const parent = getMessageById(args.message_id);
+  return { content: [{ type: "text", text: JSON.stringify({ parent, replies, reply_count: replies.length }) }] };
+});
+server.registerTool("read_thread", {
+  description: "Alias for get_thread_replies. Read all replies to a specific message, forming a thread view.",
+  inputSchema: {
+    message_id: exports_external.coerce.number(),
+    limit: exports_external.coerce.number().optional()
   }
 }, async (args) => {
-  const replies = getThreadReplies(args.message_id);
-  return { content: [{ type: "text", text: JSON.stringify(replies) }] };
+  let replies = getThreadReplies(args.message_id);
+  if (args.limit)
+    replies = replies.slice(0, args.limit);
+  const parent = getMessageById(args.message_id);
+  return { content: [{ type: "text", text: JSON.stringify({ parent, replies, reply_count: replies.length }) }] };
 });
 server.registerTool("set_focus", {
   description: "Set agent focus to a project. All read-heavy tools will default to this project scope. Stores in MCP session memory AND updates agent_presence.project_id in DB.",
@@ -32068,7 +32219,7 @@ server.registerTool("describe_tools", {
     read_messages: "Read messages with filters. Optional: session_id?, from?, to?, space?, since?(ISO), limit?, unread_only?, mark_read?(default true \u2014 auto-marks returned messages as read, pass false to peek without consuming)",
     read_digest: "Lightweight unread digest \u2014 preview only (no full bodies), auto-marks read, never overflows tokens. Returns { messages, total_unread, shown }. Optional: space?, session_id?, to?, since?(ISO), limit?, project_id?",
     list_sessions: "List all DM sessions. Optional: agent?(filter by participant)",
-    reply: "Reply to a message in same session. Required: message_id, content. Optional: from?",
+    reply: "Reply to a specific message, creating a thread (sets reply_to). Use read_thread to retrieve. Required: message_id, content. Optional: from?",
     mark_read: "Mark messages as read. Optional: from?, ids?(array), all?(bool \u2014 mark all unread)",
     search_messages: "Full-text search messages. Required: query. Optional: space?, from?, to?, limit?",
     export_messages: "Export messages as JSON or CSV. Optional: space?, session_id?, from?, since?, until?, format?(json|csv)",
@@ -32112,6 +32263,7 @@ server.registerTool("describe_tools", {
     list_locks: "List active locks enriched with agent presence + time context. Optional: resource_type?, agent_id?",
     clean_expired_locks: "Release expired locks + locks held by agents with stale heartbeat (>30 min). Returns {released_stale_agent, released_expired, total}",
     get_thread_replies: "Get all replies in a thread. Required: message_id. Optional: limit?",
+    read_thread: "Alias for get_thread_replies. Required: message_id. Optional: limit?",
     set_focus: "Set agent focus to a project. All read tools default to this scope. Required: project_id. Optional: from?",
     get_focus: "Get current focus: session focus, DB project_id, effective project_id. Optional: from?",
     unfocus: "Clear agent focus (session + DB). Optional: from?",

package/dist/index.js

@@ -276,6 +276,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -2304,6 +2318,12 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  if (opts.space) {
+    const mentions = parseMentions(opts.content);
+    if (mentions.length > 0) {
+      processMentions(message.id, opts.from, opts.space, mentions, db2);
+    }
+  }
   fireWebhooks(message);
   return message;
 }
@@ -2342,11 +2362,24 @@ function readMessages(opts = {}) {
   if (opts.unread_only) {
     conditions.push("read_at IS NULL");
   }
+  if (opts.threads_only) {
+    conditions.push("reply_to IS NULL");
+  }
+  if (opts.mentions_only) {
+    conditions.push(`id IN (SELECT message_id FROM message_mentions WHERE mentioned_agent = ?)`);
+    params.push(opts.mentions_only.toLowerCase());
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const resolvedLimit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
   const order = opts.order?.toLowerCase() === "desc" ? "DESC" : "ASC";
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at ${order}, id ${order} LIMIT ${resolvedLimit}`).all(...params);
   let messages = rows.map(parseMessage);
+  if (opts.include_reply_counts && messages.length > 0) {
+    const db22 = getDb();
+    const counts = db22.prepare(`SELECT reply_to, COUNT(*) as c FROM messages WHERE reply_to IN (${messages.map(() => "?").join(",")}) GROUP BY reply_to`).all(...messages.map((m) => m.id));
+    const countMap = new Map(counts.map((r) => [r.reply_to, r.c]));
+    messages = messages.map((m) => ({ ...m, reply_count: countMap.get(m.id) ?? 0 }));
+  }
   if (opts.max_content_length && opts.max_content_length > 0) {
     messages = messages.map((m) => {
       if (m.content.length > opts.max_content_length) {
@@ -2574,6 +2607,26 @@ function searchMessages(opts) {
     return { ...msg, snippet: null, relevance_score: 0 };
   });
 }
+function parseMentions(content) {
+  const matches = content.match(/@([a-zA-Z0-9_-]+)/g) ?? [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+async function processMentions(messageId, fromAgent, space, mentionedAgents, db2) {
+  const stmt = db2.prepare("INSERT INTO message_mentions (message_id, mentioned_agent, from_agent, space) VALUES (?, ?, ?, ?)");
+  for (const agent of mentionedAgents) {
+    try {
+      stmt.run(messageId, agent, fromAgent, space);
+      if (agent !== fromAgent.toLowerCase()) {
+        sendMessage({
+          from: fromAgent,
+          to: agent,
+          content: `You were mentioned in #${space} by ${fromAgent} (message #${messageId})`,
+          metadata: { type: "mention_notification", source_message_id: messageId, space }
+        });
+      }
+    } catch {}
+  }
+}
 // src/lib/sessions.ts
 init_db();
 function listSessions(agent) {

package/dist/lib/messages.d.ts

@@ -67,3 +67,24 @@ export interface UnreadCount {
  * If agent is omitted, returns counts for all spaces.
  */
 export declare function listUnreadCounts(agent?: string): UnreadCount[];
+/** Extract @agentname mentions from message content. Returns unique agent names (lowercase). */
+export declare function parseMentions(content: string): string[];
+export interface MentionCount {
+    space: string;
+    unread_count: number;
+    mention_count: number;
+    latest_message_at: string | null;
+}
+/** Get unread counts AND mention counts per space for an agent. */
+export declare function listUnreadCountsWithMentions(agent: string): MentionCount[];
+/** Get messages that mention a specific agent. */
+export declare function getMessagesForAgent(agent: string, opts?: {
+    space?: string;
+    unread_only?: boolean;
+    limit?: number;
+}): Array<{
+    message: Message;
+    mention_id: number;
+}>;
+/** Mark mentions as notified (agent has seen them). */
+export declare function markMentionsRead(agent: string, space?: string): number;

package/dist/types.d.ts

@@ -19,6 +19,7 @@ export interface Message {
     blocking: boolean;
     attachments: Attachment[] | null;
     reply_to: number | null;
+    reply_count?: number;
     truncated?: boolean;
 }
 export interface Reaction {
@@ -108,6 +109,9 @@ export interface ReadMessagesOptions {
     order?: "asc" | "desc";
     compact?: boolean;
     max_content_length?: number;
+    threads_only?: boolean;
+    include_reply_counts?: boolean;
+    mentions_only?: string;
 }
 export interface SearchMessagesOptions {
     query: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/conversations",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Real-time CLI messaging for AI agents",
   "type": "module",
   "bin": {