@hasna/conversations 0.2.14 → 0.2.16

package/bin/hook.js

@@ -255,6 +255,16 @@ 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_read_receipts (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent TEXT NOT NULL,
+      read_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (message_id, agent)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_message ON message_read_receipts(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_agent ON message_read_receipts(agent)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS message_mentions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,

package/bin/index.js

@@ -2120,6 +2120,16 @@ 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_read_receipts (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent TEXT NOT NULL,
+      read_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (message_id, agent)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_message ON message_read_receipts(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_agent ON message_read_receipts(agent)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS message_mentions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -2814,6 +2824,33 @@ function markUnreadByIds(ids) {
   const result = db2.prepare(`UPDATE messages SET read_at = NULL WHERE id IN (${placeholders})`).run(...ids);
   return result.changes;
 }
+function recordReadReceipt(messageId, agent) {
+  const db2 = getDb();
+  db2.prepare(`INSERT OR REPLACE INTO message_read_receipts (message_id, agent, read_at)
+     VALUES (?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'))`).run(messageId, agent.toLowerCase());
+}
+function recordReadReceiptsBatch(messageIds, agent) {
+  if (!messageIds.length || !agent)
+    return;
+  const db2 = getDb();
+  const stmt = db2.prepare(`INSERT OR REPLACE INTO message_read_receipts (message_id, agent, read_at)
+     VALUES (?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'))`);
+  for (const id of messageIds) {
+    stmt.run(id, agent.toLowerCase());
+  }
+}
+function getReadReceipts(messageId) {
+  const db2 = getDb();
+  return db2.prepare("SELECT * FROM message_read_receipts WHERE message_id = ? ORDER BY read_at ASC").all(messageId);
+}
+function getMessageReadStatus(messageId, space) {
+  const db2 = getDb();
+  const receipts = getReadReceipts(messageId);
+  const readers = new Set(receipts.map((r) => r.agent));
+  const members = db2.prepare("SELECT agent FROM space_members WHERE space = ?").all(space);
+  const unread_by = members.map((m) => m.agent).filter((a) => !readers.has(a));
+  return { receipts, unread_by };
+}
 var init_messages = __esm(() => {
   init_db();
   init_webhooks();
@@ -4453,7 +4490,7 @@ var init_poll = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/conversations",
-    version: "0.2.14",
+    version: "0.2.16",
     description: "Real-time CLI messaging for AI agents",
     type: "module",
     bin: {
@@ -33914,6 +33951,55 @@ var init_mcp2 = __esm(() => {
       content: [{ type: "text", text: JSON.stringify(spaces) }]
     };
   });
+  server.registerTool("read_receipts", {
+    description: "Get per-agent read receipts for a message. Shows who has read it and (for space messages) who hasn't.",
+    inputSchema: {
+      message_id: exports_external.coerce.number(),
+      space: exports_external.string().optional().describe("Space name \u2014 if provided, also returns list of members who haven't read yet")
+    }
+  }, async (args) => {
+    const receipts = getReadReceipts(args.message_id);
+    if (args.space) {
+      const status = getMessageReadStatus(args.message_id, args.space);
+      return { content: [{ type: "text", text: JSON.stringify(status) }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ receipts, count: receipts.length }) }] };
+  });
+  server.registerTool("mark_read_receipt", {
+    description: "Manually record that an agent has read a specific message.",
+    inputSchema: {
+      message_id: exports_external.coerce.number(),
+      agent: exports_external.string()
+    }
+  }, async (args) => {
+    recordReadReceipt(args.message_id, args.agent);
+    return { content: [{ type: "text", text: `\u2713 Marked message #${args.message_id} as read by ${args.agent}` }] };
+  });
+  server.registerTool("broadcast", {
+    description: "Send the same message to multiple spaces at once. Useful for status updates, bug reports, or announcements that need to go to several spaces.",
+    inputSchema: {
+      spaces: exports_external.array(exports_external.string()).describe("List of space names to send to"),
+      content: exports_external.string().describe("Message content"),
+      from: exports_external.string().optional().describe("Sender agent name"),
+      priority: exports_external.enum(["low", "normal", "high", "urgent"]).optional()
+    }
+  }, async (args) => {
+    const { spaces, content, from: fromParam, priority } = args;
+    const from = resolveIdentity(fromParam);
+    const results = [];
+    const errors4 = [];
+    for (const space of spaces) {
+      try {
+        const msg = sendMessage({ from, to: space, content, space, priority });
+        results.push({ space, id: msg.id });
+      } catch (e) {
+        errors4.push(`${space}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify({ sent: results, errors: errors4, total: results.length }) }]
+    };
+  });
   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: {
@@ -33990,6 +34076,7 @@ var init_mcp2 = __esm(() => {
     description: "Read messages from a space.",
     inputSchema: {
       space: exports_external.string(),
+      from: exports_external.string().optional().describe("Agent reading the space \u2014 used for per-agent read receipts"),
       since: exports_external.string().optional(),
       limit: exports_external.coerce.number().optional(),
       mark_read: exports_external.coerce.boolean().optional(),
@@ -33999,11 +34086,15 @@ var init_mcp2 = __esm(() => {
       latest: exports_external.coerce.number().optional().describe("Return the N most recent messages, newest first")
     }
   }, async (args) => {
-    const { space, since, limit, mark_read, max_content_length, threads_only, include_reply_counts, latest } = args;
+    const { space, from: fromParam, since, limit, mark_read, max_content_length, threads_only, include_reply_counts, latest } = args;
     const messages = readMessages({ space, since, limit, max_content_length, threads_only, include_reply_counts, latest });
     if (mark_read !== false && messages.length > 0) {
       markReadByIds(messages.map((m) => m.id));
     }
+    if (fromParam && messages.length > 0) {
+      const agent = resolveIdentity(fromParam);
+      recordReadReceiptsBatch(messages.map((m) => m.id), agent);
+    }
     return {
       content: [{ type: "text", text: JSON.stringify(messages) }]
     };

package/bin/mcp.js

@@ -6752,6 +6752,16 @@ 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_read_receipts (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent TEXT NOT NULL,
+      read_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (message_id, agent)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_message ON message_read_receipts(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_agent ON message_read_receipts(agent)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS message_mentions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -29317,6 +29327,33 @@ function markUnreadByIds(ids) {
   const result = db2.prepare(`UPDATE messages SET read_at = NULL WHERE id IN (${placeholders})`).run(...ids);
   return result.changes;
 }
+function recordReadReceipt(messageId, agent) {
+  const db2 = getDb();
+  db2.prepare(`INSERT OR REPLACE INTO message_read_receipts (message_id, agent, read_at)
+     VALUES (?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'))`).run(messageId, agent.toLowerCase());
+}
+function recordReadReceiptsBatch(messageIds, agent) {
+  if (!messageIds.length || !agent)
+    return;
+  const db2 = getDb();
+  const stmt = db2.prepare(`INSERT OR REPLACE INTO message_read_receipts (message_id, agent, read_at)
+     VALUES (?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'))`);
+  for (const id of messageIds) {
+    stmt.run(id, agent.toLowerCase());
+  }
+}
+function getReadReceipts(messageId) {
+  const db2 = getDb();
+  return db2.prepare("SELECT * FROM message_read_receipts WHERE message_id = ? ORDER BY read_at ASC").all(messageId);
+}
+function getMessageReadStatus(messageId, space) {
+  const db2 = getDb();
+  const receipts = getReadReceipts(messageId);
+  const readers = new Set(receipts.map((r) => r.agent));
+  const members = db2.prepare("SELECT agent FROM space_members WHERE space = ?").all(space);
+  const unread_by = members.map((m) => m.agent).filter((a) => !readers.has(a));
+  return { receipts, unread_by };
+}
 
 // src/lib/sessions.ts
 init_db();
@@ -30943,7 +30980,7 @@ function getGraphStats() {
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.2.14",
+  version: "0.2.16",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -31283,6 +31320,55 @@ server.registerTool("list_spaces", {
     content: [{ type: "text", text: JSON.stringify(spaces) }]
   };
 });
+server.registerTool("read_receipts", {
+  description: "Get per-agent read receipts for a message. Shows who has read it and (for space messages) who hasn't.",
+  inputSchema: {
+    message_id: exports_external.coerce.number(),
+    space: exports_external.string().optional().describe("Space name \u2014 if provided, also returns list of members who haven't read yet")
+  }
+}, async (args) => {
+  const receipts = getReadReceipts(args.message_id);
+  if (args.space) {
+    const status = getMessageReadStatus(args.message_id, args.space);
+    return { content: [{ type: "text", text: JSON.stringify(status) }] };
+  }
+  return { content: [{ type: "text", text: JSON.stringify({ receipts, count: receipts.length }) }] };
+});
+server.registerTool("mark_read_receipt", {
+  description: "Manually record that an agent has read a specific message.",
+  inputSchema: {
+    message_id: exports_external.coerce.number(),
+    agent: exports_external.string()
+  }
+}, async (args) => {
+  recordReadReceipt(args.message_id, args.agent);
+  return { content: [{ type: "text", text: `\u2713 Marked message #${args.message_id} as read by ${args.agent}` }] };
+});
+server.registerTool("broadcast", {
+  description: "Send the same message to multiple spaces at once. Useful for status updates, bug reports, or announcements that need to go to several spaces.",
+  inputSchema: {
+    spaces: exports_external.array(exports_external.string()).describe("List of space names to send to"),
+    content: exports_external.string().describe("Message content"),
+    from: exports_external.string().optional().describe("Sender agent name"),
+    priority: exports_external.enum(["low", "normal", "high", "urgent"]).optional()
+  }
+}, async (args) => {
+  const { spaces, content, from: fromParam, priority } = args;
+  const from = resolveIdentity(fromParam);
+  const results = [];
+  const errors3 = [];
+  for (const space of spaces) {
+    try {
+      const msg = sendMessage({ from, to: space, content, space, priority });
+      results.push({ space, id: msg.id });
+    } catch (e) {
+      errors3.push(`${space}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify({ sent: results, errors: errors3, total: results.length }) }]
+  };
+});
 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: {
@@ -31359,6 +31445,7 @@ server.registerTool("read_space", {
   description: "Read messages from a space.",
   inputSchema: {
     space: exports_external.string(),
+    from: exports_external.string().optional().describe("Agent reading the space \u2014 used for per-agent read receipts"),
     since: exports_external.string().optional(),
     limit: exports_external.coerce.number().optional(),
     mark_read: exports_external.coerce.boolean().optional(),
@@ -31368,11 +31455,15 @@ server.registerTool("read_space", {
     latest: exports_external.coerce.number().optional().describe("Return the N most recent messages, newest first")
   }
 }, async (args) => {
-  const { space, since, limit, mark_read, max_content_length, threads_only, include_reply_counts, latest } = args;
+  const { space, from: fromParam, since, limit, mark_read, max_content_length, threads_only, include_reply_counts, latest } = args;
   const messages = readMessages({ space, since, limit, max_content_length, threads_only, include_reply_counts, latest });
   if (mark_read !== false && messages.length > 0) {
     markReadByIds(messages.map((m) => m.id));
   }
+  if (fromParam && messages.length > 0) {
+    const agent = resolveIdentity(fromParam);
+    recordReadReceiptsBatch(messages.map((m) => m.id), agent);
+  }
   return {
     content: [{ type: "text", text: JSON.stringify(messages) }]
   };

package/dist/index.js

@@ -279,6 +279,16 @@ 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_read_receipts (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent TEXT NOT NULL,
+      read_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (message_id, agent)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_message ON message_read_receipts(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_read_receipts_agent ON message_read_receipts(agent)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS message_mentions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,

package/dist/lib/messages.d.ts

@@ -92,3 +92,19 @@ export declare function markMentionsRead(agent: string, space?: string): number;
 export declare function markUnread(messageId: number): number;
 /** Mark multiple messages as unread. */
 export declare function markUnreadByIds(ids: number[]): number;
+export interface ReadReceipt {
+    message_id: number;
+    agent: string;
+    read_at: string;
+}
+/** Record that an agent has read a specific message. */
+export declare function recordReadReceipt(messageId: number, agent: string): void;
+/** Record read receipts for all messages in a batch. */
+export declare function recordReadReceiptsBatch(messageIds: number[], agent: string): void;
+/** Get all read receipts for a specific message. */
+export declare function getReadReceipts(messageId: number): ReadReceipt[];
+/** Get read status summary for a space message: who has read it and who hasn't. */
+export declare function getMessageReadStatus(messageId: number, space: string): {
+    receipts: ReadReceipt[];
+    unread_by: string[];
+};

package/package.json

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