@hasna/conversations 0.1.32 → 0.1.33

package/README.md

@@ -10,10 +10,18 @@ Real-time messaging for AI agents on the same machine. Send direct messages betw
 - **Sessions** -- derived automatically from messages, no manual session management
 - **Priorities** -- four levels: `low`, `normal`, `high`, `urgent`
 - **Read tracking** -- per-message read receipts with bulk mark-read support
+- **Message threading** -- `reply_to` field links replies to parent messages; `getThreadReplies()` fetches full threads
+- **Emoji reactions** -- add/remove emoji reactions on any message; `getReactionSummary()` aggregates counts
+- **Message pinning** -- pin important messages per space or session
+- **Agent presence** -- heartbeat, online/offline status, 30-min conflict detection for concurrent sessions
+- **Resource locks** -- advisory and exclusive locks with configurable TTL for coordination
+- **Focus mode** -- scope an agent session to a project; all read tools auto-filter by project
+- **Webhooks** -- async POST notifications to Slack/Discord/email on DM, blocker, space, or @mention
 - **200ms polling** -- near-instant message delivery via indexed SQLite queries
-- **Three surfaces** -- CLI, MCP server (16 tools), and TypeScript library
+- **Three surfaces** -- CLI, MCP server (37 tools), and TypeScript library
 - **Interactive TUI** -- Ink-based terminal UI for browsing sessions and chatting
 - **Web dashboard** -- built-in HTTP dashboard for browser-based monitoring
+- **Health check** -- `conversations doctor` validates setup and catches common issues
 - **Self-updating** -- `conversations update` checks npm and installs the latest version
 
 ## Installation
@@ -337,6 +345,140 @@ const spaceMessages = useSpaceMessages("deployments");
 - **Sessions derived from messages** -- no separate sessions table
 - **Agent identity resolution**: explicit `--from` flag > `CONVERSATIONS_AGENT_ID` env var > `"user"` fallback
 
+## Emoji Reactions
+
+Add emoji reactions to any message. Reactions are aggregated by emoji with agent lists.
+
+```bash
+# Add a reaction
+conversations react 42 👍
+
+# Remove a reaction
+conversations unreact 42 👍
+
+# Show reaction counts for a message
+conversations reactions 42
+
+# TypeScript library
+import { addReaction, removeReaction, getReactionSummary } from "@hasna/conversations";
+
+addReaction(42, "codex", "✅");
+const summary = getReactionSummary(42);
+// [{ emoji: "✅", count: 1, agents: ["codex"] }]
+```
+
+## Message Threading
+
+Replies link to a parent message via `reply_to`. Use `getThreadReplies()` to fetch all replies.
+
+```bash
+# Reply to message #42 (CLI)
+conversations reply --to 42 "Got it!"
+
+# MCP tool
+{ "tool": "reply", "message_id": 42, "content": "Got it!" }
+{ "tool": "get_thread_replies", "message_id": 42 }
+```
+
+```typescript
+import { readMessages, getThreadReplies } from "@hasna/conversations";
+
+const replies = getThreadReplies(42);
+```
+
+## Agent Presence
+
+Agents announce their presence via heartbeat. The system detects duplicate sessions (30-min conflict window) and supports graceful takeover of stale sessions.
+
+```bash
+# Register agent (with conflict detection)
+conversations agents list
+conversations agents list --online
+
+# MCP tools
+{ "tool": "register_agent", "name": "codex", "session_id": "sess-abc123", "role": "agent" }
+{ "tool": "heartbeat", "from": "codex", "status": "working on auth module" }
+{ "tool": "list_agents" }
+```
+
+```typescript
+import { registerAgent, heartbeat, listAgents, isAgentConflict } from "@hasna/conversations";
+
+const result = registerAgent("codex", "sess-abc123", "agent");
+if (isAgentConflict(result)) {
+  console.log(`Conflict: ${result.existing_session_id} active since ${result.last_seen_at}`);
+}
+```
+
+## Resource Locks
+
+Coordinate concurrent agent access with advisory or exclusive locks. Locks expire automatically (default 5 minutes).
+
+```typescript
+import { acquireLock, releaseLock, checkLock } from "@hasna/conversations";
+
+// Advisory lock (multiple readers allowed, writers coordinate)
+const result = acquireLock("space", "deployments", "codex", "advisory");
+if (!result.acquired) {
+  console.log(`Locked by ${result.held_by}`);
+}
+
+// Exclusive lock (only one writer)
+acquireLock("pinned_message", "42", "codex", "exclusive", 60_000); // 1 min TTL
+releaseLock("pinned_message", "42", "codex");
+```
+
+```bash
+# MCP tools
+{ "tool": "acquire_lock", "resource_type": "space", "resource_id": "deployments", "lock_type": "advisory" }
+{ "tool": "check_lock", "resource_type": "space", "resource_id": "deployments" }
+{ "tool": "release_lock", "resource_type": "space", "resource_id": "deployments" }
+{ "tool": "list_locks" }
+```
+
+## Focus Mode
+
+Scope an agent session to a project. All read-heavy MCP tools auto-filter to the focused project.
+
+```bash
+# MCP tools
+{ "tool": "set_focus", "project_id": "proj-abc123", "from": "codex" }
+{ "tool": "get_focus", "from": "codex" }
+{ "tool": "unfocus", "from": "codex" }
+```
+
+Priority: explicit `project_id` param > session focus > `register_agent` project > no filter.
+
+## Webhooks
+
+Get notified on Slack, Discord, or any HTTP endpoint when messages arrive.
+
+Create `~/.conversations/config.json`:
+
+```json
+{
+  "webhooks": [
+    {
+      "url": "https://hooks.slack.com/services/...",
+      "events": ["dm", "blocker", "space", "mention"],
+      "agent": "andrei"
+    }
+  ]
+}
+```
+
+Event types: `dm` (direct messages), `blocker` (blocking messages), `space` (space messages), `mention` (@name matches).
+
+Webhooks fire asynchronously — they never slow down message delivery. Failed deliveries are silently ignored.
+
+## Health Check
+
+```bash
+conversations doctor
+```
+
+Checks: database accessibility, WAL mode, MCP binary on PATH, npm version, webhook config validity.
+
 ## CLI Commands
 
 | Command | Description |
@@ -345,9 +487,19 @@ const spaceMessages = useSpaceMessages("deployments");
 | `conversations send` | Send a direct message |
 | `conversations read` | Read messages with filters |
 | `conversations reply` | Reply to a message by ID |
+| `conversations search <query>` | Full-text search across messages |
+| `conversations since <duration>` | Activity feed since 30m/2h/1d ago |
+| `conversations context` | Session boot context for agents |
 | `conversations sessions` | List conversation sessions |
 | `conversations mark-read` | Mark messages as read |
+| `conversations pin <id>` | Pin a message |
+| `conversations unpin <id>` | Unpin a message |
+| `conversations pinned` | List pinned messages |
+| `conversations react <id> <emoji>` | Add emoji reaction |
+| `conversations unreact <id> <emoji>` | Remove emoji reaction |
+| `conversations reactions <id>` | Show reaction summary |
 | `conversations status` | Show database stats |
+| `conversations doctor` | Health check |
 | `conversations update` | Check for and install updates |
 | `conversations space create` | Create a new space |
 | `conversations space list` | List all spaces |
@@ -361,6 +513,7 @@ const spaceMessages = useSpaceMessages("deployments");
 | `conversations project get` | Get project details |
 | `conversations project update` | Update a project |
 | `conversations project delete` | Delete a project |
+| `conversations agents list` | List agents with presence |
 | `conversations mcp` | Start MCP server on stdio |
 | `conversations dashboard` | Start web dashboard |
 

package/bin/index.js

@@ -2498,6 +2498,11 @@ function getUnreadBlockers(agent) {
   `).all(agent, agent);
   return rows.map(parseMessage);
 }
+function getThreadReplies(messageId) {
+  const db2 = getDb();
+  const rows = db2.prepare("SELECT * FROM messages WHERE reply_to = ? ORDER BY created_at ASC, id ASC").all(messageId);
+  return rows.map(parseMessage);
+}
 function searchMessages(opts) {
   const db2 = getDb();
   const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
@@ -3478,6 +3483,48 @@ var init_presence = __esm(() => {
   CONFLICT_THRESHOLD_SECONDS = 30 * 60;
 });
 
+// src/lib/reactions.ts
+function addReaction(messageId, agent, emoji) {
+  const db2 = getDb();
+  const stmt = db2.prepare(`
+    INSERT INTO reactions (message_id, agent, emoji)
+    VALUES (?, ?, ?)
+    ON CONFLICT (message_id, agent, emoji) DO UPDATE SET agent = agent
+    RETURNING *
+  `);
+  const row = stmt.get(messageId, agent, emoji);
+  return row;
+}
+function removeReaction(messageId, agent, emoji) {
+  const db2 = getDb();
+  const stmt = db2.prepare("DELETE FROM reactions WHERE message_id = ? AND agent = ? AND emoji = ?");
+  const result = stmt.run(messageId, agent, emoji);
+  return result.changes > 0;
+}
+function getReactions(messageId) {
+  const db2 = getDb();
+  const rows = db2.prepare("SELECT * FROM reactions WHERE message_id = ? ORDER BY created_at ASC, id ASC").all(messageId);
+  return rows;
+}
+function getReactionSummary(messageId) {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT emoji, GROUP_CONCAT(agent) as agents, COUNT(*) as count
+    FROM reactions
+    WHERE message_id = ?
+    GROUP BY emoji
+    ORDER BY count DESC, MIN(created_at) ASC
+  `).all(messageId);
+  return rows.map((row) => ({
+    emoji: row.emoji,
+    count: row.count,
+    agents: row.agents.split(",")
+  }));
+}
+var init_reactions = __esm(() => {
+  init_db();
+});
+
 // src/lib/terminal-markdown.ts
 var exports_terminal_markdown = {};
 __export(exports_terminal_markdown, {
@@ -3622,7 +3669,7 @@ var init_poll = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/conversations",
-    version: "0.1.32",
+    version: "0.1.33",
     description: "Real-time CLI messaging for AI agents",
     type: "module",
     bin: {
@@ -32566,6 +32613,84 @@ var init_stdio2 = __esm(() => {
   init_stdio();
 });
 
+// src/lib/locks.ts
+function acquireLock(resourceType, resourceId, agentId, lockType = "advisory", expiryMs = DEFAULT_LOCK_EXPIRY_MS) {
+  const db2 = getDb();
+  return db2.transaction(() => {
+    cleanExpiredLocks();
+    const existing = db2.prepare(`
+      SELECT * FROM resource_locks
+      WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+    `).get(resourceType, resourceId, lockType);
+    if (existing) {
+      if (existing.agent_id !== agentId) {
+        return { acquired: false, lock: null, held_by: existing.agent_id };
+      }
+      const expiresAt = new Date(Date.now() + expiryMs).toISOString().replace("T", "T").replace("Z", "");
+      db2.prepare(`
+        UPDATE resource_locks SET expires_at = ?, locked_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
+        WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+      `).run(expiresAt, resourceType, resourceId, lockType);
+    } else {
+      const expiresAt = new Date(Date.now() + expiryMs).toISOString().slice(0, -1);
+      db2.prepare(`
+        INSERT INTO resource_locks (resource_type, resource_id, agent_id, lock_type, locked_at, expires_at)
+        VALUES (?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'), ?)
+      `).run(resourceType, resourceId, agentId, lockType, expiresAt);
+    }
+    const lock = db2.prepare(`
+      SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+    `).get(resourceType, resourceId, lockType);
+    return { acquired: true, lock };
+  }).immediate();
+}
+function releaseLock(resourceType, resourceId, agentId) {
+  const db2 = getDb();
+  const result = db2.prepare(`
+    DELETE FROM resource_locks
+    WHERE resource_type = ? AND resource_id = ? AND agent_id = ?
+  `).run(resourceType, resourceId, agentId);
+  return result.changes > 0;
+}
+function checkLock(resourceType, resourceId) {
+  const db2 = getDb();
+  cleanExpiredLocks();
+  return db2.prepare(`
+    SELECT * FROM resource_locks
+    WHERE resource_type = ? AND resource_id = ?
+    ORDER BY locked_at ASC
+    LIMIT 1
+  `).get(resourceType, resourceId);
+}
+function cleanExpiredLocks() {
+  const db2 = getDb();
+  const result = db2.prepare(`
+    DELETE FROM resource_locks WHERE expires_at < strftime('%Y-%m-%dT%H:%M:%f', 'now')
+  `).run();
+  return result.changes;
+}
+function listLocks(opts) {
+  const db2 = getDb();
+  cleanExpiredLocks();
+  let query = "SELECT * FROM resource_locks WHERE 1=1";
+  const params = [];
+  if (opts?.resource_type) {
+    query += " AND resource_type = ?";
+    params.push(opts.resource_type);
+  }
+  if (opts?.agent_id) {
+    query += " AND agent_id = ?";
+    params.push(opts.agent_id);
+  }
+  query += " ORDER BY locked_at ASC";
+  return db2.prepare(query).all(...params);
+}
+var DEFAULT_LOCK_EXPIRY_MS;
+var init_locks = __esm(() => {
+  init_db();
+  DEFAULT_LOCK_EXPIRY_MS = 5 * 60 * 1000;
+});
+
 // src/mcp/index.ts
 var exports_mcp = {};
 __export(exports_mcp, {
@@ -32599,6 +32724,8 @@ var init_mcp2 = __esm(() => {
   init_projects();
   init_identity();
   init_presence();
+  init_reactions();
+  init_locks();
   import__package = __toESM(require_package(), 1);
   server = new McpServer({
     name: "conversations",
@@ -33239,6 +33366,107 @@ var init_mcp2 = __esm(() => {
       content: [{ type: "text", text: JSON.stringify(messages) }]
     };
   });
+  server.registerTool("add_reaction", {
+    description: "Add an emoji reaction to a message.",
+    inputSchema: {
+      message_id: exports_external.coerce.number(),
+      emoji: exports_external.string(),
+      from: exports_external.string().optional()
+    }
+  }, async (args) => {
+    const { message_id, emoji: emoji3, from: fromParam } = args;
+    const agent = resolveIdentity(fromParam);
+    const reaction = addReaction(message_id, agent, emoji3);
+    return { content: [{ type: "text", text: JSON.stringify(reaction) }] };
+  });
+  server.registerTool("remove_reaction", {
+    description: "Remove an emoji reaction from a message.",
+    inputSchema: {
+      message_id: exports_external.coerce.number(),
+      emoji: exports_external.string(),
+      from: exports_external.string().optional()
+    }
+  }, async (args) => {
+    const { message_id, emoji: emoji3, from: fromParam } = args;
+    const agent = resolveIdentity(fromParam);
+    const removed = removeReaction(message_id, agent, emoji3);
+    return { content: [{ type: "text", text: JSON.stringify({ removed }) }] };
+  });
+  server.registerTool("get_reactions", {
+    description: "Get all reactions for a message.",
+    inputSchema: {
+      message_id: exports_external.coerce.number()
+    }
+  }, async (args) => {
+    const reactions = getReactions(args.message_id);
+    return { content: [{ type: "text", text: JSON.stringify(reactions) }] };
+  });
+  server.registerTool("get_reaction_summary", {
+    description: "Get emoji reaction counts and agent lists for a message.",
+    inputSchema: {
+      message_id: exports_external.coerce.number()
+    }
+  }, async (args) => {
+    const summary = getReactionSummary(args.message_id);
+    return { content: [{ type: "text", text: JSON.stringify(summary) }] };
+  });
+  server.registerTool("acquire_lock", {
+    description: "Acquire an advisory or exclusive lock on a resource. Returns conflict info if another agent holds the lock.",
+    inputSchema: {
+      resource_type: exports_external.string(),
+      resource_id: exports_external.string(),
+      lock_type: exports_external.enum(["advisory", "exclusive"]).optional(),
+      expiry_ms: exports_external.coerce.number().optional(),
+      from: exports_external.string().optional()
+    }
+  }, async (args) => {
+    const { resource_type, resource_id, lock_type, expiry_ms, from: fromParam } = args;
+    const agent = resolveIdentity(fromParam);
+    const result = acquireLock(resource_type, resource_id, agent, lock_type ?? "advisory", expiry_ms);
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
+  server.registerTool("release_lock", {
+    description: "Release a lock held by the agent on a resource.",
+    inputSchema: {
+      resource_type: exports_external.string(),
+      resource_id: exports_external.string(),
+      from: exports_external.string().optional()
+    }
+  }, async (args) => {
+    const { resource_type, resource_id, from: fromParam } = args;
+    const agent = resolveIdentity(fromParam);
+    const released = releaseLock(resource_type, resource_id, agent);
+    return { content: [{ type: "text", text: JSON.stringify({ released }) }] };
+  });
+  server.registerTool("check_lock", {
+    description: "Check if a resource is currently locked and who holds it.",
+    inputSchema: {
+      resource_type: exports_external.string(),
+      resource_id: exports_external.string()
+    }
+  }, async (args) => {
+    const lock = checkLock(args.resource_type, args.resource_id);
+    return { content: [{ type: "text", text: JSON.stringify(lock ?? { locked: false }) }] };
+  });
+  server.registerTool("list_locks", {
+    description: "List all active (non-expired) locks. Filter by resource_type or agent.",
+    inputSchema: {
+      resource_type: exports_external.string().optional(),
+      agent_id: exports_external.string().optional()
+    }
+  }, async (args) => {
+    const locks = listLocks({ resource_type: args.resource_type, agent_id: args.agent_id });
+    return { content: [{ type: "text", text: JSON.stringify(locks) }] };
+  });
+  server.registerTool("get_thread_replies", {
+    description: "Get all replies in a thread for a given parent message ID.",
+    inputSchema: {
+      message_id: exports_external.coerce.number()
+    }
+  }, async (args) => {
+    const replies = getThreadReplies(args.message_id);
+    return { content: [{ type: "text", text: JSON.stringify(replies) }] };
+  });
   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.",
     inputSchema: {
@@ -33437,6 +33665,15 @@ var init_mcp2 = __esm(() => {
       "pin_message",
       "unpin_message",
       "get_pinned_messages",
+      "add_reaction",
+      "remove_reaction",
+      "get_reactions",
+      "get_reaction_summary",
+      "acquire_lock",
+      "release_lock",
+      "check_lock",
+      "list_locks",
+      "get_thread_replies",
       "set_focus",
       "get_focus",
       "unfocus",
@@ -33486,6 +33723,15 @@ var init_mcp2 = __esm(() => {
       pin_message: "Pin a message. Required: id",
       unpin_message: "Unpin a message. Required: id",
       get_pinned_messages: "Get pinned messages. Optional: space?, session_id?, limit?",
+      add_reaction: "Add emoji reaction to a message. Required: message_id, emoji. Optional: from?",
+      remove_reaction: "Remove emoji reaction from a message. Required: message_id, emoji. Optional: from?",
+      get_reactions: "Get all reactions for a message. Required: message_id",
+      get_reaction_summary: "Get emoji counts + agent lists for a message. Required: message_id",
+      acquire_lock: "Acquire advisory/exclusive lock on a resource. Required: resource_type, resource_id. Optional: lock_type?(advisory|exclusive), expiry_ms?, from?",
+      release_lock: "Release lock held by agent. Required: resource_type, resource_id. Optional: from?",
+      check_lock: "Check if resource is locked and who holds it. Required: resource_type, resource_id",
+      list_locks: "List active locks. Optional: resource_type?, agent_id?",
+      get_thread_replies: "Get all replies in a thread. 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?",
@@ -33944,6 +34190,23 @@ function startDashboardServer(port = 0, host) {
         const agents = listAgents({ online_only: onlineOnly });
         return jsonResponse(applyFields(agents, url2.searchParams.get("fields")));
       }
+      if (path === "/api/reactions" && req.method === "GET") {
+        const messageIdStr = url2.searchParams.get("message_id");
+        if (!messageIdStr)
+          return jsonResponse({ error: "message_id required" }, 400);
+        const messageId = parseInt(messageIdStr);
+        if (isNaN(messageId))
+          return jsonResponse({ error: "message_id must be a number" }, 400);
+        const summary = url2.searchParams.get("summary") === "true";
+        const result = summary ? getReactionSummary(messageId) : getReactions(messageId);
+        return jsonResponse(result);
+      }
+      if (path === "/api/locks" && req.method === "GET") {
+        const resource_type = url2.searchParams.get("resource_type") ?? undefined;
+        const agent_id = url2.searchParams.get("agent_id") ?? undefined;
+        const locks = listLocks({ resource_type, agent_id });
+        return jsonResponse(locks);
+      }
       if (path === "/api/version" && req.method === "GET") {
         try {
           const pkg2 = await Promise.resolve().then(() => __toESM(require_package(), 1));
@@ -34024,6 +34287,8 @@ var init_serve = __esm(() => {
   init_projects();
   init_db();
   init_presence();
+  init_reactions();
+  init_locks();
   isDirectRun2 = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("serve.ts") || process.argv[1]?.endsWith("serve.js");
   if (isDirectRun2) {
     const port = normalizePort(process.env.PORT, 0);
@@ -34055,6 +34320,7 @@ init_projects();
 init_db();
 init_identity();
 init_presence();
+init_reactions();
 init_terminal_markdown();
 import chalk3 from "chalk";
 import { render } from "ink";
@@ -35120,6 +35386,87 @@ program2.command("search").description("Search messages by content").argument("<
   }
   closeDb();
 });
+program2.command("since").description("Show all activity (DMs + spaces) since a duration ago").argument("<duration>", "Duration: e.g. 30m, 2h, 1d").option("--json", "Output as JSON").action((duration3, opts) => {
+  const match = duration3.match(/^(\d+)([mhd])$/);
+  if (!match) {
+    console.error(chalk3.red(`Invalid duration "${duration3}". Use format: 30m, 2h, 1d`));
+    process.exit(1);
+  }
+  const value = parseInt(match[1]);
+  const unit = match[2];
+  const msMap = { m: 60000, h: 3600000, d: 86400000 };
+  const since = new Date(Date.now() - value * msMap[unit]).toISOString().replace("T", "T").slice(0, 23);
+  const messages = readMessages({ since, order: "asc", limit: 200 });
+  if (opts.json) {
+    console.log(JSON.stringify(messages, null, 2));
+  } else {
+    if (messages.length === 0) {
+      console.log(chalk3.dim(`No activity in the last ${duration3}.`));
+    } else {
+      console.log(chalk3.bold(`Activity since ${duration3} ago (${messages.length} message(s)):
+`));
+      for (const msg of messages) {
+        const time3 = chalk3.dim(msg.created_at.slice(11, 19));
+        const from = chalk3.cyan(msg.from_agent);
+        const where = msg.space ? chalk3.magenta(`#${msg.space}`) : chalk3.yellow(`\u2192 ${msg.to_agent}`);
+        const priority = msg.priority !== "normal" ? chalk3.red(` [${msg.priority}]`) : "";
+        const unread = !msg.read_at ? chalk3.green(" \u2022") : "";
+        const content = renderContent(msg.content);
+        console.log(`${time3} ${from} ${where}${priority}${unread}`);
+        console.log(`       ${content}
+`);
+      }
+    }
+  }
+  closeDb();
+});
+program2.command("context").description("One-shot session boot context for agents: online agents, unread DMs, spaces, recent activity").option("--json", "Output as JSON").action((opts) => {
+  const agent = resolveIdentity();
+  heartbeat(agent);
+  const db2 = getDb();
+  const onlineAgents = listAgents({ online_only: true });
+  const unreadDMs = readMessages({ to: agent, unread_only: true, limit: 5 });
+  const mySpaces = db2.prepare(`
+      SELECT s.name, s.description,
+        (SELECT COUNT(*) FROM messages m WHERE m.space = s.name AND m.read_at IS NULL) as unread
+      FROM spaces s
+      JOIN space_members sm ON sm.space = s.name
+      WHERE sm.agent = ?
+      ORDER BY s.name
+    `).all(agent);
+  const recentDMs = readMessages({ to: agent, limit: 3 });
+  const context = { agent, online_agents: onlineAgents, unread_dms: unreadDMs, spaces: mySpaces, recent_dms: recentDMs };
+  if (opts.json) {
+    console.log(JSON.stringify(context, null, 2));
+  } else {
+    console.log(chalk3.bold(`Context for ${chalk3.cyan(agent)}
+`));
+    if (onlineAgents.length > 0) {
+      const names = onlineAgents.map((a) => chalk3.green(a.agent)).join(", ");
+      console.log(`${chalk3.bold("Online agents:")} ${names}`);
+    } else {
+      console.log(`${chalk3.bold("Online agents:")} ${chalk3.dim("none")}`);
+    }
+    if (unreadDMs.length > 0) {
+      console.log(`${chalk3.bold("Unread DMs:")} ${chalk3.yellow(unreadDMs.length + " message(s)")}`);
+      for (const msg of unreadDMs.slice(0, 3)) {
+        console.log(`  ${chalk3.dim(msg.created_at.slice(11, 16))} ${chalk3.cyan(msg.from_agent)}: ${msg.content.slice(0, 80)}`);
+      }
+    } else {
+      console.log(`${chalk3.bold("Unread DMs:")} ${chalk3.dim("none")}`);
+    }
+    if (mySpaces.length > 0) {
+      console.log(`${chalk3.bold("My spaces:")}`);
+      for (const sp of mySpaces) {
+        const unread = sp.unread > 0 ? chalk3.yellow(` (${sp.unread} unread)`) : "";
+        console.log(`  ${chalk3.magenta("#" + sp.name)}${unread}`);
+      }
+    } else {
+      console.log(`${chalk3.bold("My spaces:")} ${chalk3.dim("none")}`);
+    }
+  }
+  closeDb();
+});
 program2.command("sessions").description("List conversation sessions").option("--agent <id>", "Filter sessions involving this agent").option("--json", "Output as JSON").action((opts) => {
   const sessions = listSessions(opts.agent);
   if (opts.json) {
@@ -35234,6 +35581,79 @@ program2.command("status").description("Show database stats").option("--json", "
   }
   closeDb();
 });
+program2.command("doctor").description("Check conversations setup and health").option("--json", "Output as JSON").action(async (opts) => {
+  const checks4 = [];
+  try {
+    const db2 = getDb();
+    db2.prepare("SELECT 1").get();
+    const dbPath = getDbPath();
+    checks4.push({ name: "Database", ok: true, message: `OK \u2014 ${dbPath}` });
+  } catch (e) {
+    checks4.push({ name: "Database", ok: false, message: `Cannot open DB: ${e.message}` });
+  }
+  try {
+    const db2 = getDb();
+    const mode = db2.prepare("PRAGMA journal_mode").get();
+    const isWal = mode.journal_mode === "wal";
+    checks4.push({ name: "WAL mode", ok: isWal, message: isWal ? "OK \u2014 WAL mode enabled" : `WARNING \u2014 journal_mode is ${mode.journal_mode}` });
+  } catch {
+    checks4.push({ name: "WAL mode", ok: false, message: "Could not check WAL mode" });
+  }
+  try {
+    const proc = Bun.spawn(["which", "conversations-mcp"], { stdout: "pipe", stderr: "pipe" });
+    const exit = await proc.exited;
+    const path = await new Response(proc.stdout).text();
+    checks4.push({ name: "MCP binary", ok: exit === 0, message: exit === 0 ? `OK \u2014 ${path.trim()}` : "conversations-mcp not found in PATH \u2014 run: bun install -g @hasna/conversations" });
+  } catch {
+    checks4.push({ name: "MCP binary", ok: false, message: "Could not check MCP binary" });
+  }
+  try {
+    const current = import__package2.default.version;
+    const res = await fetch("https://registry.npmjs.org/@hasna/conversations/latest");
+    const data = await res.json();
+    const latest = data.version;
+    const upToDate = current === latest;
+    checks4.push({ name: "npm version", ok: upToDate, message: upToDate ? `OK \u2014 v${current} (latest)` : `Update available: v${current} \u2192 v${latest} \u2014 run: bun install -g @hasna/conversations@latest` });
+  } catch {
+    checks4.push({ name: "npm version", ok: true, message: "Could not check npm registry (offline?)" });
+  }
+  const { homedir: homedir5 } = await import("os");
+  const { existsSync: existsSync2 } = await import("fs");
+  const { join: join6 } = await import("path");
+  const configPath = process.env.CONVERSATIONS_CONFIG_PATH ?? join6(homedir5(), ".conversations", "config.json");
+  if (existsSync2(configPath)) {
+    try {
+      const { readFileSync: readFileSync3 } = await import("fs");
+      JSON.parse(readFileSync3(configPath, "utf8"));
+      checks4.push({ name: "Webhook config", ok: true, message: `OK \u2014 ${configPath}` });
+    } catch (e) {
+      checks4.push({ name: "Webhook config", ok: false, message: `Invalid JSON at ${configPath}: ${e.message}` });
+    }
+  } else {
+    checks4.push({ name: "Webhook config", ok: true, message: "No webhook config (optional)" });
+  }
+  closeDb();
+  const allOk = checks4.every((c) => c.ok);
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: allOk, checks: checks4 }, null, 2));
+  } else {
+    console.log(chalk3.bold(`Conversations Doctor
+`));
+    for (const check2 of checks4) {
+      const icon = check2.ok ? chalk3.green("\u2713") : chalk3.red("\u2717");
+      const label = chalk3.bold(check2.name.padEnd(16));
+      console.log(`  ${icon}  ${label}  ${check2.message}`);
+    }
+    console.log();
+    if (allOk) {
+      console.log(chalk3.green("All checks passed."));
+    } else {
+      const failed = checks4.filter((c) => !c.ok).length;
+      console.log(chalk3.red(`${failed} check(s) failed.`));
+      process.exit(1);
+    }
+  }
+});
 program2.command("update").description("Check for and install updates").option("--check", "Only check for updates, don't install").option("--json", "Output as JSON").action(async (opts) => {
   const pkg3 = await Promise.resolve().then(() => __toESM(require_package(), 1));
   const current = pkg3.version;
@@ -35760,6 +36180,64 @@ program2.command("unpin").description("Unpin a message").argument("<id>", "Messa
   }
   closeDb();
 });
+program2.command("pinned").description("List pinned messages").option("--space <name>", "Filter by space").option("--session <id>", "Filter by session ID").option("--limit <n>", "Max results", parseInt).option("--json", "Output as JSON").action((opts) => {
+  const messages = getPinnedMessages({ space: opts.space, session_id: opts.session, limit: opts.limit });
+  if (opts.json) {
+    console.log(JSON.stringify(messages, null, 2));
+  } else {
+    if (messages.length === 0) {
+      console.log(chalk3.dim("No pinned messages."));
+    } else {
+      console.log(chalk3.dim(`${messages.length} pinned message(s):
+`));
+      for (const msg of messages) {
+        const time3 = chalk3.dim(msg.created_at.slice(11, 19));
+        const from = chalk3.cyan(msg.from_agent);
+        const where = msg.space ? chalk3.magenta(`#${msg.space}`) : chalk3.yellow(msg.to_agent);
+        console.log(`${chalk3.yellow("\uD83D\uDCCC")} [#${msg.id}] ${time3} ${from} \u2192 ${where}: ${msg.content}`);
+      }
+    }
+  }
+  closeDb();
+});
+program2.command("react").description("Add an emoji reaction to a message").argument("<id>", "Message ID", parseInt).argument("<emoji>", "Emoji to react with").option("--from <agent>", "Agent identity override").option("--json", "Output as JSON").action((id, emoji3, opts) => {
+  const agent = resolveIdentity(opts.from);
+  const reaction = addReaction(id, agent, emoji3);
+  if (opts.json) {
+    console.log(JSON.stringify(reaction, null, 2));
+  } else {
+    console.log(chalk3.green(`${emoji3} reaction added to message #${id}`));
+  }
+  closeDb();
+});
+program2.command("unreact").description("Remove an emoji reaction from a message").argument("<id>", "Message ID", parseInt).argument("<emoji>", "Emoji to remove").option("--from <agent>", "Agent identity override").option("--json", "Output as JSON").action((id, emoji3, opts) => {
+  const agent = resolveIdentity(opts.from);
+  const removed = removeReaction(id, agent, emoji3);
+  if (opts.json) {
+    console.log(JSON.stringify({ removed }, null, 2));
+  } else {
+    if (removed) {
+      console.log(chalk3.green(`${emoji3} reaction removed from message #${id}`));
+    } else {
+      console.log(chalk3.dim(`No ${emoji3} reaction found on message #${id}`));
+    }
+  }
+  closeDb();
+});
+program2.command("reactions").description("Show emoji reactions on a message").argument("<id>", "Message ID", parseInt).option("--json", "Output as JSON").action((id, opts) => {
+  const summary = getReactionSummary(id);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    if (summary.length === 0) {
+      console.log(chalk3.dim(`No reactions on message #${id}`));
+    } else {
+      const parts = summary.map((r) => `${r.emoji} ${r.count}`).join("  ");
+      console.log(`Message #${id}: ${parts}`);
+    }
+  }
+  closeDb();
+});
 var agents = program2.command("agents").description("Manage agents");
 agents.command("list").description("List all agents with their presence status").option("--online", "Only show online agents").option("--json", "Output as JSON").action((opts) => {
   const agent = resolveIdentity();

package/bin/mcp.js

@@ -28939,6 +28939,11 @@ function getUnreadBlockers(agent) {
   `).all(agent, agent);
   return rows.map(parseMessage);
 }
+function getThreadReplies(messageId) {
+  const db2 = getDb();
+  const rows = db2.prepare("SELECT * FROM messages WHERE reply_to = ? ORDER BY created_at ASC, id ASC").all(messageId);
+  return rows.map(parseMessage);
+}
 function searchMessages(opts) {
   const db2 = getDb();
   const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
@@ -29898,10 +29903,125 @@ function renameAgent(oldName, newName) {
   db2.prepare("UPDATE agent_presence SET agent = ? WHERE LOWER(agent) = ?").run(normalizedNew, normalizedOld);
   return true;
 }
+
+// src/lib/reactions.ts
+init_db();
+function addReaction(messageId, agent, emoji3) {
+  const db2 = getDb();
+  const stmt = db2.prepare(`
+    INSERT INTO reactions (message_id, agent, emoji)
+    VALUES (?, ?, ?)
+    ON CONFLICT (message_id, agent, emoji) DO UPDATE SET agent = agent
+    RETURNING *
+  `);
+  const row = stmt.get(messageId, agent, emoji3);
+  return row;
+}
+function removeReaction(messageId, agent, emoji3) {
+  const db2 = getDb();
+  const stmt = db2.prepare("DELETE FROM reactions WHERE message_id = ? AND agent = ? AND emoji = ?");
+  const result = stmt.run(messageId, agent, emoji3);
+  return result.changes > 0;
+}
+function getReactions(messageId) {
+  const db2 = getDb();
+  const rows = db2.prepare("SELECT * FROM reactions WHERE message_id = ? ORDER BY created_at ASC, id ASC").all(messageId);
+  return rows;
+}
+function getReactionSummary(messageId) {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT emoji, GROUP_CONCAT(agent) as agents, COUNT(*) as count
+    FROM reactions
+    WHERE message_id = ?
+    GROUP BY emoji
+    ORDER BY count DESC, MIN(created_at) ASC
+  `).all(messageId);
+  return rows.map((row) => ({
+    emoji: row.emoji,
+    count: row.count,
+    agents: row.agents.split(",")
+  }));
+}
+
+// src/lib/locks.ts
+init_db();
+var DEFAULT_LOCK_EXPIRY_MS = 5 * 60 * 1000;
+function acquireLock(resourceType, resourceId, agentId, lockType = "advisory", expiryMs = DEFAULT_LOCK_EXPIRY_MS) {
+  const db2 = getDb();
+  return db2.transaction(() => {
+    cleanExpiredLocks();
+    const existing = db2.prepare(`
+      SELECT * FROM resource_locks
+      WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+    `).get(resourceType, resourceId, lockType);
+    if (existing) {
+      if (existing.agent_id !== agentId) {
+        return { acquired: false, lock: null, held_by: existing.agent_id };
+      }
+      const expiresAt = new Date(Date.now() + expiryMs).toISOString().replace("T", "T").replace("Z", "");
+      db2.prepare(`
+        UPDATE resource_locks SET expires_at = ?, locked_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
+        WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+      `).run(expiresAt, resourceType, resourceId, lockType);
+    } else {
+      const expiresAt = new Date(Date.now() + expiryMs).toISOString().slice(0, -1);
+      db2.prepare(`
+        INSERT INTO resource_locks (resource_type, resource_id, agent_id, lock_type, locked_at, expires_at)
+        VALUES (?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'), ?)
+      `).run(resourceType, resourceId, agentId, lockType, expiresAt);
+    }
+    const lock = db2.prepare(`
+      SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+    `).get(resourceType, resourceId, lockType);
+    return { acquired: true, lock };
+  }).immediate();
+}
+function releaseLock(resourceType, resourceId, agentId) {
+  const db2 = getDb();
+  const result = db2.prepare(`
+    DELETE FROM resource_locks
+    WHERE resource_type = ? AND resource_id = ? AND agent_id = ?
+  `).run(resourceType, resourceId, agentId);
+  return result.changes > 0;
+}
+function checkLock(resourceType, resourceId) {
+  const db2 = getDb();
+  cleanExpiredLocks();
+  return db2.prepare(`
+    SELECT * FROM resource_locks
+    WHERE resource_type = ? AND resource_id = ?
+    ORDER BY locked_at ASC
+    LIMIT 1
+  `).get(resourceType, resourceId);
+}
+function cleanExpiredLocks() {
+  const db2 = getDb();
+  const result = db2.prepare(`
+    DELETE FROM resource_locks WHERE expires_at < strftime('%Y-%m-%dT%H:%M:%f', 'now')
+  `).run();
+  return result.changes;
+}
+function listLocks(opts) {
+  const db2 = getDb();
+  cleanExpiredLocks();
+  let query = "SELECT * FROM resource_locks WHERE 1=1";
+  const params = [];
+  if (opts?.resource_type) {
+    query += " AND resource_type = ?";
+    params.push(opts.resource_type);
+  }
+  if (opts?.agent_id) {
+    query += " AND agent_id = ?";
+    params.push(opts.agent_id);
+  }
+  query += " ORDER BY locked_at ASC";
+  return db2.prepare(query).all(...params);
+}
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.1.32",
+  version: "0.1.33",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -30630,6 +30750,107 @@ server.registerTool("get_pinned_messages", {
     content: [{ type: "text", text: JSON.stringify(messages) }]
   };
 });
+server.registerTool("add_reaction", {
+  description: "Add an emoji reaction to a message.",
+  inputSchema: {
+    message_id: exports_external.coerce.number(),
+    emoji: exports_external.string(),
+    from: exports_external.string().optional()
+  }
+}, async (args) => {
+  const { message_id, emoji: emoji3, from: fromParam } = args;
+  const agent = resolveIdentity(fromParam);
+  const reaction = addReaction(message_id, agent, emoji3);
+  return { content: [{ type: "text", text: JSON.stringify(reaction) }] };
+});
+server.registerTool("remove_reaction", {
+  description: "Remove an emoji reaction from a message.",
+  inputSchema: {
+    message_id: exports_external.coerce.number(),
+    emoji: exports_external.string(),
+    from: exports_external.string().optional()
+  }
+}, async (args) => {
+  const { message_id, emoji: emoji3, from: fromParam } = args;
+  const agent = resolveIdentity(fromParam);
+  const removed = removeReaction(message_id, agent, emoji3);
+  return { content: [{ type: "text", text: JSON.stringify({ removed }) }] };
+});
+server.registerTool("get_reactions", {
+  description: "Get all reactions for a message.",
+  inputSchema: {
+    message_id: exports_external.coerce.number()
+  }
+}, async (args) => {
+  const reactions = getReactions(args.message_id);
+  return { content: [{ type: "text", text: JSON.stringify(reactions) }] };
+});
+server.registerTool("get_reaction_summary", {
+  description: "Get emoji reaction counts and agent lists for a message.",
+  inputSchema: {
+    message_id: exports_external.coerce.number()
+  }
+}, async (args) => {
+  const summary = getReactionSummary(args.message_id);
+  return { content: [{ type: "text", text: JSON.stringify(summary) }] };
+});
+server.registerTool("acquire_lock", {
+  description: "Acquire an advisory or exclusive lock on a resource. Returns conflict info if another agent holds the lock.",
+  inputSchema: {
+    resource_type: exports_external.string(),
+    resource_id: exports_external.string(),
+    lock_type: exports_external.enum(["advisory", "exclusive"]).optional(),
+    expiry_ms: exports_external.coerce.number().optional(),
+    from: exports_external.string().optional()
+  }
+}, async (args) => {
+  const { resource_type, resource_id, lock_type, expiry_ms, from: fromParam } = args;
+  const agent = resolveIdentity(fromParam);
+  const result = acquireLock(resource_type, resource_id, agent, lock_type ?? "advisory", expiry_ms);
+  return { content: [{ type: "text", text: JSON.stringify(result) }] };
+});
+server.registerTool("release_lock", {
+  description: "Release a lock held by the agent on a resource.",
+  inputSchema: {
+    resource_type: exports_external.string(),
+    resource_id: exports_external.string(),
+    from: exports_external.string().optional()
+  }
+}, async (args) => {
+  const { resource_type, resource_id, from: fromParam } = args;
+  const agent = resolveIdentity(fromParam);
+  const released = releaseLock(resource_type, resource_id, agent);
+  return { content: [{ type: "text", text: JSON.stringify({ released }) }] };
+});
+server.registerTool("check_lock", {
+  description: "Check if a resource is currently locked and who holds it.",
+  inputSchema: {
+    resource_type: exports_external.string(),
+    resource_id: exports_external.string()
+  }
+}, async (args) => {
+  const lock = checkLock(args.resource_type, args.resource_id);
+  return { content: [{ type: "text", text: JSON.stringify(lock ?? { locked: false }) }] };
+});
+server.registerTool("list_locks", {
+  description: "List all active (non-expired) locks. Filter by resource_type or agent.",
+  inputSchema: {
+    resource_type: exports_external.string().optional(),
+    agent_id: exports_external.string().optional()
+  }
+}, async (args) => {
+  const locks = listLocks({ resource_type: args.resource_type, agent_id: args.agent_id });
+  return { content: [{ type: "text", text: JSON.stringify(locks) }] };
+});
+server.registerTool("get_thread_replies", {
+  description: "Get all replies in a thread for a given parent message ID.",
+  inputSchema: {
+    message_id: exports_external.coerce.number()
+  }
+}, async (args) => {
+  const replies = getThreadReplies(args.message_id);
+  return { content: [{ type: "text", text: JSON.stringify(replies) }] };
+});
 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.",
   inputSchema: {
@@ -30828,6 +31049,15 @@ server.registerTool("search_tools", {
     "pin_message",
     "unpin_message",
     "get_pinned_messages",
+    "add_reaction",
+    "remove_reaction",
+    "get_reactions",
+    "get_reaction_summary",
+    "acquire_lock",
+    "release_lock",
+    "check_lock",
+    "list_locks",
+    "get_thread_replies",
     "set_focus",
     "get_focus",
     "unfocus",
@@ -30877,6 +31107,15 @@ server.registerTool("describe_tools", {
     pin_message: "Pin a message. Required: id",
     unpin_message: "Unpin a message. Required: id",
     get_pinned_messages: "Get pinned messages. Optional: space?, session_id?, limit?",
+    add_reaction: "Add emoji reaction to a message. Required: message_id, emoji. Optional: from?",
+    remove_reaction: "Remove emoji reaction from a message. Required: message_id, emoji. Optional: from?",
+    get_reactions: "Get all reactions for a message. Required: message_id",
+    get_reaction_summary: "Get emoji counts + agent lists for a message. Required: message_id",
+    acquire_lock: "Acquire advisory/exclusive lock on a resource. Required: resource_type, resource_id. Optional: lock_type?(advisory|exclusive), expiry_ms?, from?",
+    release_lock: "Release lock held by agent. Required: resource_type, resource_id. Optional: from?",
+    check_lock: "Check if resource is locked and who holds it. Required: resource_type, resource_id",
+    list_locks: "List active locks. Optional: resource_type?, agent_id?",
+    get_thread_replies: "Get all replies in a thread. 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.d.ts

@@ -14,9 +14,10 @@ export { listSessions, getSession, } from "./lib/sessions.js";
 export { createSpace, updateSpace, archiveSpace, unarchiveSpace, listSpaces, getSpace, joinSpace, leaveSpace, getSpaceMembers, isSpaceMember, getSpaceDepth, } from "./lib/spaces.js";
 export { createProject, listProjects, getProject, getProjectByName, updateProject, deleteProject, } from "./lib/projects.js";
 export { getDb, getDbPath, closeDb, } from "./lib/db.js";
-export { startPolling, useSpaceMessages, } from "./lib/poll.js";
+export { startPolling, useMessages, useSpaceMessages, } from "./lib/poll.js";
 export { resolveIdentity, requireIdentity, } from "./lib/identity.js";
 export { addReaction, removeReaction, getReactions, getReactionSummary, } from "./lib/reactions.js";
+export type { ReactionSummary } from "./lib/reactions.js";
 export { fireWebhooks, } from "./lib/webhooks.js";
 export { heartbeat, registerAgent, isAgentConflict, getPresence, listAgents, removePresence, renameAgent, } from "./lib/presence.js";
 export { acquireLock, releaseLock, checkLock, cleanExpiredLocks, listLocks, } from "./lib/locks.js";

package/dist/index.js

@@ -2983,6 +2983,22 @@ function startPolling(opts) {
     }
   };
 }
+function useMessages(sessionId, agent) {
+  const [messages, setMessages] = import_react.useState([]);
+  import_react.useEffect(() => {
+    const existing = readMessages({ session_id: sessionId });
+    setMessages(existing);
+    const { stop } = startPolling({
+      session_id: sessionId,
+      interval_ms: 200,
+      on_messages: (newMessages) => {
+        setMessages((prev) => [...prev, ...newMessages]);
+      }
+    });
+    return stop;
+  }, [sessionId, agent]);
+  return messages;
+}
 function useSpaceMessages(spaceName) {
   const [messages, setMessages] = import_react.useState([]);
   import_react.useEffect(() => {
@@ -3656,6 +3672,7 @@ function listLocks(opts) {
 }
 export {
   useSpaceMessages,
+  useMessages,
   updateSpace,
   updateProject,
   unpinMessage,

package/package.json

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