@hasna/conversations 0.1.18 → 0.1.20

package/bin/mcp.js

@@ -6677,6 +6677,43 @@ function getDb() {
   if (!colNames2.includes("attachments")) {
     db.exec("ALTER TABLE messages ADD COLUMN attachments TEXT");
   }
+  if (!colNames2.includes("reply_to")) {
+    db.exec("ALTER TABLE messages ADD COLUMN reply_to INTEGER REFERENCES messages(id)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_messages_reply_to ON messages(reply_to)");
+  }
+  const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
+  if (!ftsExists) {
+    db.exec(`
+      CREATE VIRTUAL TABLE messages_fts USING fts5(
+        content, from_agent, to_agent, space,
+        content_rowid='id', content='messages'
+      )
+    `);
+    db.exec(`
+      INSERT INTO messages_fts(rowid, content, from_agent, to_agent, space)
+      SELECT id, content, from_agent, to_agent, space FROM messages
+    `);
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages BEGIN
+        INSERT INTO messages_fts(rowid, content, from_agent, to_agent, space)
+        VALUES (new.id, new.content, new.from_agent, new.to_agent, new.space);
+      END
+    `);
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages BEGIN
+        INSERT INTO messages_fts(messages_fts, rowid, content, from_agent, to_agent, space)
+        VALUES ('delete', old.id, old.content, old.from_agent, old.to_agent, old.space);
+      END
+    `);
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE OF content ON messages BEGIN
+        INSERT INTO messages_fts(messages_fts, rowid, content, from_agent, to_agent, space)
+        VALUES ('delete', old.id, old.content, old.from_agent, old.to_agent, old.space);
+        INSERT INTO messages_fts(rowid, content, from_agent, to_agent, space)
+        VALUES (new.id, new.content, new.from_agent, new.to_agent, new.space);
+      END
+    `);
+  }
   return db;
 }
 function closeDb() {
@@ -28509,8 +28546,84 @@ class StdioServerTransport {
 init_db();
 import { randomUUID } from "crypto";
 import { mkdirSync as mkdirSync2, copyFileSync, statSync } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir3 } from "os";
+
+// src/lib/webhooks.ts
+import { readFileSync } from "fs";
 import { join as join2 } from "path";
 import { homedir as homedir2 } from "os";
+var cachedConfig = null;
+var configLoadedAt = 0;
+var CONFIG_CACHE_MS = 1e4;
+function getConfigPath() {
+  return process.env.CONVERSATIONS_CONFIG_PATH || join2(homedir2(), ".conversations", "config.json");
+}
+function loadConfig() {
+  const now = Date.now();
+  if (cachedConfig && now - configLoadedAt < CONFIG_CACHE_MS)
+    return cachedConfig;
+  try {
+    const raw = readFileSync(getConfigPath(), "utf-8");
+    cachedConfig = JSON.parse(raw);
+    configLoadedAt = now;
+    return cachedConfig;
+  } catch {
+    cachedConfig = {};
+    configLoadedAt = now;
+    return cachedConfig;
+  }
+}
+function matchesEvent(webhook, msg) {
+  for (const event of webhook.events) {
+    if (event === "dm" && !msg.space)
+      return true;
+    if (event === "blocker" && msg.blocking)
+      return true;
+    if (event === "space" && msg.space)
+      return true;
+    if (event === "mention" && webhook.agent && msg.content.includes(`@${webhook.agent}`))
+      return true;
+  }
+  return false;
+}
+function fireWebhooks(msg) {
+  const config2 = loadConfig();
+  if (!config2.webhooks || config2.webhooks.length === 0)
+    return;
+  for (const webhook of config2.webhooks) {
+    if (webhook.agent && msg.to_agent !== webhook.agent && !msg.space)
+      continue;
+    if (!matchesEvent(webhook, msg))
+      continue;
+    fetch(webhook.url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        id: msg.id,
+        from: msg.from_agent,
+        to: msg.to_agent,
+        space: msg.space,
+        content: msg.content,
+        priority: msg.priority,
+        blocking: msg.blocking,
+        created_at: msg.created_at
+      })
+    }).catch(() => {});
+  }
+}
+
+// src/lib/messages.ts
+function compactMessage(msg) {
+  const result = {};
+  for (const key of Object.keys(msg)) {
+    const val = msg[key];
+    if (val !== null && val !== undefined) {
+      result[key] = val;
+    }
+  }
+  return result;
+}
 function parseMessage(row) {
   let metadata = null;
   if (row.metadata) {
@@ -28532,13 +28645,14 @@ function parseMessage(row) {
     ...row,
     metadata,
     attachments,
-    blocking: !!row.blocking
+    blocking: !!row.blocking,
+    reply_to: row.reply_to || null
   };
 }
 function getAttachmentsDir() {
   if (process.env.CONVERSATIONS_ATTACHMENTS_DIR)
     return process.env.CONVERSATIONS_ATTACHMENTS_DIR;
-  return join2(homedir2(), ".conversations", "attachments");
+  return join3(homedir3(), ".conversations", "attachments");
 }
 function guessMimeType(name) {
   const ext = name.split(".").pop()?.toLowerCase();
@@ -28574,19 +28688,20 @@ function sendMessage(opts) {
   const metadata = opts.metadata ? JSON.stringify(opts.metadata) : null;
   const normalizedPriority = opts.priority === "low" || opts.priority === "normal" || opts.priority === "high" || opts.priority === "urgent" ? opts.priority : "normal";
   const blocking = opts.blocking ? 1 : 0;
+  const replyTo = opts.reply_to || null;
   const stmt = db2.prepare(`
-    INSERT INTO messages (session_id, from_agent, to_agent, space, content, priority, working_dir, repository, branch, metadata, blocking)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO messages (session_id, from_agent, to_agent, space, content, priority, working_dir, repository, branch, metadata, blocking, reply_to)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     RETURNING *
   `);
-  const row = stmt.get(sessionId, opts.from, opts.to, opts.space || null, opts.content, normalizedPriority, opts.working_dir || null, opts.repository || null, opts.branch || null, metadata, blocking);
+  const row = stmt.get(sessionId, opts.from, opts.to, opts.space || null, opts.content, normalizedPriority, opts.working_dir || null, opts.repository || null, opts.branch || null, metadata, blocking, replyTo);
   const message = parseMessage(row);
   if (opts.attachments && opts.attachments.length > 0) {
-    const attachmentsDir = join2(getAttachmentsDir(), String(message.id));
+    const attachmentsDir = join3(getAttachmentsDir(), String(message.id));
     mkdirSync2(attachmentsDir, { recursive: true });
     const attachmentInfos = [];
     for (const att of opts.attachments) {
-      const destPath = join2(attachmentsDir, att.name);
+      const destPath = join3(attachmentsDir, att.name);
       copyFileSync(att.source_path, destPath);
       const stat = statSync(destPath);
       attachmentInfos.push({
@@ -28600,6 +28715,7 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  fireWebhooks(message);
   return message;
 }
 function readMessages(opts = {}) {
@@ -28634,10 +28750,13 @@ function readMessages(opts = {}) {
     conditions.push("read_at IS NULL");
   }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-  const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? `LIMIT ${Math.floor(opts.limit)}` : "";
+  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}`).all(...params);
-  return rows.map(parseMessage);
+  const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at ${order}, id ${order} LIMIT ${resolvedLimit}`).all(...params);
+  const messages = rows.map(parseMessage);
+  if (opts.compact)
+    return messages.map(compactMessage);
+  return messages;
 }
 function markRead(ids, reader) {
   const db2 = getDb();
@@ -28771,6 +28890,33 @@ function getUnreadBlockers(agent) {
 }
 function searchMessages(opts) {
   const db2 = getDb();
+  const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
+  try {
+    const ftsConditions = [];
+    const ftsParams = [];
+    const words = opts.query.trim().split(/\s+/).filter(Boolean);
+    const ftsQuery = words.map((w) => `"${w.replace(/"/g, '""')}"`).join(" ");
+    ftsConditions.push("messages_fts MATCH ?");
+    ftsParams.push(ftsQuery);
+    let extraWhere = "";
+    if (opts.space) {
+      extraWhere += " AND m.space = ?";
+      ftsParams.push(opts.space);
+    }
+    if (opts.from) {
+      extraWhere += " AND m.from_agent = ?";
+      ftsParams.push(opts.from);
+    }
+    if (opts.to) {
+      extraWhere += " AND m.to_agent = ?";
+      ftsParams.push(opts.to);
+    }
+    const rows2 = db2.prepare(`SELECT m.* FROM messages m
+       JOIN messages_fts ON messages_fts.rowid = m.id
+       WHERE ${ftsConditions.join(" AND ")}${extraWhere}
+       ORDER BY m.created_at DESC, m.id DESC LIMIT ${limit}`).all(...ftsParams);
+    return rows2.map(parseMessage);
+  } catch {}
   const conditions = ["content LIKE ?"];
   const params = [`%${opts.query}%`];
   if (opts.space) {
@@ -28785,7 +28931,6 @@ function searchMessages(opts) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
-  const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 50;
   const where = `WHERE ${conditions.join(" AND ")}`;
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at DESC, id DESC LIMIT ${limit}`).all(...params);
   return rows.map(parseMessage);
@@ -29163,9 +29308,9 @@ function deleteProject(id) {
 }
 
 // src/lib/identity.ts
-import { readFileSync, writeFileSync, mkdirSync as mkdirSync3 } from "fs";
-import { join as join3, dirname as dirname2 } from "path";
-import { homedir as homedir3 } from "os";
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync as mkdirSync3 } from "fs";
+import { join as join4, dirname as dirname2 } from "path";
+import { homedir as homedir4 } from "os";
 
 // src/lib/names.ts
 var AGENT_NAMES = [
@@ -29517,7 +29662,7 @@ var AGENT_NAMES = [
 ];
 
 // src/lib/identity.ts
-var AGENT_ID_FILE = join3(homedir3(), ".conversations", "agent-id");
+var AGENT_ID_FILE = join4(homedir4(), ".conversations", "agent-id");
 var cachedAutoName = null;
 function isNameTaken(name) {
   try {
@@ -29533,7 +29678,7 @@ function getAutoName() {
   if (cachedAutoName)
     return cachedAutoName;
   try {
-    const name2 = readFileSync(AGENT_ID_FILE, "utf-8").trim();
+    const name2 = readFileSync2(AGENT_ID_FILE, "utf-8").trim();
     if (name2) {
       cachedAutoName = name2;
       return name2;
@@ -29632,7 +29777,7 @@ function renameAgent(oldName, newName) {
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.1.18",
+  version: "0.1.20",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -29716,9 +29861,9 @@ var server = new McpServer({
 });
 server.registerTool("send_message", {
   title: "Send Message",
-  description: "Send a direct message to another agent. Pass 'from' to identify yourself, or it falls back to CONVERSATIONS_AGENT_ID env var.",
+  description: "Send a direct message to another agent.",
   inputSchema: {
-    from: exports_external.string().optional().describe("Your agent ID (e.g. 'claude-1', 'assistant'). Falls back to CONVERSATIONS_AGENT_ID env var."),
+    from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     to: exports_external.string().describe("Recipient agent ID"),
     content: exports_external.string().describe("Message content"),
     session_id: exports_external.string().optional().describe("Session ID (auto-generated if omitted)"),
@@ -29727,7 +29872,7 @@ server.registerTool("send_message", {
     repository: exports_external.string().optional().describe("Repository context"),
     branch: exports_external.string().optional().describe("Branch context"),
     metadata: exports_external.string().optional().describe("JSON metadata string"),
-    blocking: exports_external.boolean().optional().describe("Send as a blocking message. Recipients must acknowledge before continuing.")
+    blocking: exports_external.boolean().optional().describe("Blocking message \u2014 recipients must acknowledge before continuing")
   }
 }, async ({ from: fromParam, to, content, session_id, priority, working_dir, repository, branch, metadata, blocking }) => {
   const from = resolveIdentity(fromParam);
@@ -29737,7 +29882,7 @@ server.registerTool("send_message", {
       parsedMetadata = JSON.parse(metadata);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid metadata JSON." }],
+        content: [{ type: "text", text: "invalid JSON" }],
         isError: true
       };
     }
@@ -29760,15 +29905,15 @@ server.registerTool("send_message", {
 });
 server.registerTool("read_messages", {
   title: "Read Messages",
-  description: "Read messages with optional filters. Returns messages sorted by time.",
+  description: "Read messages with filters, newest first.",
   inputSchema: {
     session_id: exports_external.string().optional().describe("Filter by session ID"),
-    from: exports_external.string().optional().describe("Filter by sender agent ID"),
-    to: exports_external.string().optional().describe("Filter by recipient agent ID"),
+    from: exports_external.string().optional().describe("Filter by sender"),
+    to: exports_external.string().optional().describe("Filter by recipient"),
     space: exports_external.string().optional().describe("Filter by space name"),
-    since: exports_external.string().optional().describe("Messages after this ISO timestamp"),
-    limit: exports_external.number().optional().describe("Max messages to return"),
-    unread_only: exports_external.boolean().optional().describe("Only return unread messages")
+    since: exports_external.string().optional().describe("ISO timestamp lower bound"),
+    limit: exports_external.number().optional().describe("Max messages to return (default 20)"),
+    unread_only: exports_external.boolean().optional().describe("Only unread messages")
   }
 }, async (opts) => {
   const messages = readMessages(opts);
@@ -29778,7 +29923,7 @@ server.registerTool("read_messages", {
 });
 server.registerTool("list_sessions", {
   title: "List Sessions",
-  description: "List conversation sessions, optionally filtered to a specific agent.",
+  description: "List sessions, optionally filtered by agent.",
   inputSchema: {
     agent: exports_external.string().optional().describe("Filter sessions involving this agent")
   }
@@ -29790,7 +29935,7 @@ server.registerTool("list_sessions", {
 });
 server.registerTool("reply", {
   title: "Reply to Message",
-  description: "Reply to a message by its ID. Automatically uses the same session and sends to the original sender.",
+  description: "Reply to a message (same session, original sender).",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     message_id: exports_external.number().describe("ID of the message to reply to"),
@@ -29822,7 +29967,7 @@ server.registerTool("reply", {
 });
 server.registerTool("mark_read", {
   title: "Mark Read",
-  description: "Mark message IDs as read for the current agent. Set 'all' to true to mark all unread messages as read.",
+  description: "Mark messages as read. Provide IDs or set 'all' to true.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     ids: exports_external.array(exports_external.number()).optional().describe("Message IDs to mark as read"),
@@ -29837,7 +29982,7 @@ server.registerTool("mark_read", {
     count = markRead(ids, agent);
   } else {
     return {
-      content: [{ type: "text", text: "Provide message IDs or set 'all' to true." }],
+      content: [{ type: "text", text: "provide ids or set all=true" }],
       isError: true
     };
   }
@@ -29847,13 +29992,13 @@ server.registerTool("mark_read", {
 });
 server.registerTool("search_messages", {
   title: "Search Messages",
-  description: "Full-text search across message content. Returns matching messages ordered by newest first.",
+  description: "Full-text search across message content, newest first.",
   inputSchema: {
-    query: exports_external.string().describe("Search query string"),
-    space: exports_external.string().optional().describe("Filter by space name"),
-    from: exports_external.string().optional().describe("Filter by sender agent ID"),
-    to: exports_external.string().optional().describe("Filter by recipient agent ID"),
-    limit: exports_external.number().optional().describe("Max results to return (default 50)")
+    query: exports_external.string().describe("Search query"),
+    space: exports_external.string().optional().describe("Filter by space"),
+    from: exports_external.string().optional().describe("Filter by sender"),
+    to: exports_external.string().optional().describe("Filter by recipient"),
+    limit: exports_external.number().optional().describe("Max results (default 20)")
   }
 }, async ({ query, space, from, to, limit }) => {
   const messages = searchMessages({ query, space, from, to, limit });
@@ -29865,11 +30010,11 @@ server.registerTool("export_messages", {
   title: "Export Messages",
   description: "Export messages as JSON or CSV with optional filters.",
   inputSchema: {
-    space: exports_external.string().optional().describe("Filter by space name"),
+    space: exports_external.string().optional().describe("Filter by space"),
     session_id: exports_external.string().optional().describe("Filter by session ID"),
-    from: exports_external.string().optional().describe("Filter by sender agent ID"),
-    since: exports_external.string().optional().describe("Messages after this ISO date"),
-    until: exports_external.string().optional().describe("Messages before this ISO date"),
+    from: exports_external.string().optional().describe("Filter by sender"),
+    since: exports_external.string().optional().describe("ISO date lower bound"),
+    until: exports_external.string().optional().describe("ISO date upper bound"),
     format: exports_external.enum(["json", "csv"]).optional().describe("Output format (default: json)")
   }
 }, async ({ space, session_id, from, since, until, format }) => {
@@ -29880,13 +30025,13 @@ server.registerTool("export_messages", {
 });
 server.registerTool("create_space", {
   title: "Create Space",
-  description: "Create a new space. The creator is auto-joined. Spaces can be nested (max 3 levels) and associated with a project.",
+  description: "Create a space. Auto-joined. Supports nesting and projects.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
-    name: exports_external.string().describe("Space name (e.g. 'deployments', 'code-review')"),
+    name: exports_external.string().describe("Space name"),
     description: exports_external.string().optional().describe("Space description"),
-    parent_id: exports_external.string().optional().describe("Parent space name for nesting (max 3 levels deep)"),
-    project_id: exports_external.string().optional().describe("Project ID to associate this space with")
+    parent_id: exports_external.string().optional().describe("Parent space name (max 3 levels deep)"),
+    project_id: exports_external.string().optional().describe("Project ID to associate with")
   }
 }, async ({ from: fromParam, name, description, parent_id, project_id }) => {
   const agent = resolveIdentity(fromParam);
@@ -29898,7 +30043,7 @@ server.registerTool("create_space", {
   } catch (e) {
     if (e.message?.includes("UNIQUE constraint")) {
       return {
-        content: [{ type: "text", text: `Space #${name} already exists` }],
+        content: [{ type: "text", text: `space "${name}" already exists` }],
         isError: true
       };
     }
@@ -29910,11 +30055,11 @@ server.registerTool("create_space", {
 });
 server.registerTool("list_spaces", {
   title: "List Spaces",
-  description: "List all available spaces with member and message counts. Can filter by project or parent. Archived spaces are excluded by default.",
+  description: "List spaces with member/message counts.",
   inputSchema: {
     project_id: exports_external.string().optional().describe("Filter by project ID"),
-    parent_id: exports_external.string().optional().describe("Filter by parent space name. Use 'null' for top-level only."),
-    include_archived: exports_external.boolean().optional().describe("Include archived spaces (default: false)")
+    parent_id: exports_external.string().optional().describe("Filter by parent space. Use 'null' for top-level only."),
+    include_archived: exports_external.boolean().optional().describe("Include archived spaces")
   }
 }, async ({ project_id, parent_id, include_archived }) => {
   const opts = {};
@@ -29940,14 +30085,14 @@ server.registerTool("send_to_space", {
     space: exports_external.string().describe("Space name"),
     content: exports_external.string().describe("Message content"),
     priority: exports_external.enum(["low", "normal", "high", "urgent"]).optional().describe("Message priority"),
-    blocking: exports_external.boolean().optional().describe("Send as a blocking message. All space members must acknowledge.")
+    blocking: exports_external.boolean().optional().describe("Blocking message \u2014 all space members must acknowledge")
   }
 }, async ({ from: fromParam, space, content, priority, blocking }) => {
   const from = resolveIdentity(fromParam);
   const sp = getSpace(space);
   if (!sp) {
     return {
-      content: [{ type: "text", text: `Space #${space} not found` }],
+      content: [{ type: "text", text: `space "${space}" not found` }],
       isError: true
     };
   }
@@ -29969,7 +30114,7 @@ server.registerTool("read_space", {
   description: "Read messages from a space.",
   inputSchema: {
     space: exports_external.string().describe("Space name"),
-    since: exports_external.string().optional().describe("Messages after this ISO timestamp"),
+    since: exports_external.string().optional().describe("ISO timestamp lower bound"),
     limit: exports_external.number().optional().describe("Max messages to return")
   }
 }, async ({ space, since, limit }) => {
@@ -29990,7 +30135,7 @@ server.registerTool("join_space", {
   const ok = joinSpace(space, agent);
   if (!ok) {
     return {
-      content: [{ type: "text", text: `Space #${space} not found` }],
+      content: [{ type: "text", text: `space "${space}" not found` }],
       isError: true
     };
   }
@@ -30014,12 +30159,12 @@ server.registerTool("leave_space", {
 });
 server.registerTool("update_space", {
   title: "Update Space",
-  description: "Update a space's description, parent, or project association.",
+  description: "Update a space's description, parent, or project.",
   inputSchema: {
-    name: exports_external.string().describe("Space name to update"),
+    name: exports_external.string().describe("Space name"),
     description: exports_external.string().optional().describe("New description"),
-    parent_id: exports_external.string().optional().describe("New parent space name (use 'null' to remove parent)"),
-    project_id: exports_external.string().optional().describe("New project ID (use 'null' to remove project)")
+    parent_id: exports_external.string().optional().describe("New parent space (use 'null' to remove)"),
+    project_id: exports_external.string().optional().describe("New project ID (use 'null' to remove)")
   }
 }, async ({ name, description, parent_id, project_id }) => {
   const updates = {};
@@ -30043,7 +30188,7 @@ server.registerTool("update_space", {
 });
 server.registerTool("archive_space", {
   title: "Archive Space",
-  description: "Archive a space. Archived spaces are hidden from list by default.",
+  description: "Archive a space. Hidden from list by default.",
   inputSchema: {
     name: exports_external.string().describe("Space name to archive")
   }
@@ -30081,16 +30226,16 @@ server.registerTool("unarchive_space", {
 });
 server.registerTool("create_project", {
   title: "Create Project",
-  description: "Create a new project. Projects organize spaces and provide context for agent collaboration.",
+  description: "Create a project for spaces and agent collaboration.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     name: exports_external.string().describe("Project name (unique)"),
     description: exports_external.string().optional().describe("Project description"),
-    path: exports_external.string().optional().describe("Absolute path to project on disk"),
+    path: exports_external.string().optional().describe("Absolute path on disk"),
     repository: exports_external.string().optional().describe("Repository URL"),
-    tags: exports_external.string().optional().describe(`JSON array of tags (e.g. '["backend", "api"]')`),
-    metadata: exports_external.string().optional().describe("JSON metadata string"),
-    settings: exports_external.string().optional().describe("JSON settings string")
+    tags: exports_external.string().optional().describe("JSON array of tags"),
+    metadata: exports_external.string().optional().describe("JSON metadata"),
+    settings: exports_external.string().optional().describe("JSON settings")
   }
 }, async ({ from: fromParam, name, description, path, repository, tags, metadata, settings }) => {
   const agent = resolveIdentity(fromParam);
@@ -30100,7 +30245,7 @@ server.registerTool("create_project", {
       parsedTags = JSON.parse(tags);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid tags JSON. Expected array of strings." }],
+        content: [{ type: "text", text: "invalid tags JSON (expected array)" }],
         isError: true
       };
     }
@@ -30111,7 +30256,7 @@ server.registerTool("create_project", {
       parsedMetadata = JSON.parse(metadata);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid metadata JSON." }],
+        content: [{ type: "text", text: "invalid JSON" }],
         isError: true
       };
     }
@@ -30122,7 +30267,7 @@ server.registerTool("create_project", {
       parsedSettings = JSON.parse(settings);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid settings JSON." }],
+        content: [{ type: "text", text: "invalid JSON" }],
         isError: true
       };
     }
@@ -30144,7 +30289,7 @@ server.registerTool("create_project", {
   } catch (e) {
     if (e.message?.includes("UNIQUE constraint")) {
       return {
-        content: [{ type: "text", text: `Project "${name}" already exists` }],
+        content: [{ type: "text", text: `project "${name}" already exists` }],
         isError: true
       };
     }
@@ -30158,7 +30303,7 @@ server.registerTool("list_projects", {
   title: "List Projects",
   description: "List all registered projects.",
   inputSchema: {
-    status: exports_external.enum(["active", "archived"]).optional().describe("Filter by project status")
+    status: exports_external.enum(["active", "archived"]).optional().describe("Filter by status")
   }
 }, async ({ status }) => {
   const projects = listProjects(status ? { status } : undefined);
@@ -30179,7 +30324,7 @@ server.registerTool("get_project", {
   }
   if (!project) {
     return {
-      content: [{ type: "text", text: `Project "${id}" not found` }],
+      content: [{ type: "text", text: `project "${id}" not found` }],
       isError: true
     };
   }
@@ -30192,14 +30337,14 @@ server.registerTool("update_project", {
   description: "Update a project's fields.",
   inputSchema: {
     id: exports_external.string().describe("Project ID (UUID)"),
-    name: exports_external.string().optional().describe("New project name"),
+    name: exports_external.string().optional().describe("New name"),
     description: exports_external.string().optional().describe("New description"),
     path: exports_external.string().optional().describe("New path"),
     status: exports_external.enum(["active", "archived"]).optional().describe("New status"),
     repository: exports_external.string().optional().describe("New repository URL"),
     tags: exports_external.string().optional().describe("JSON array of tags"),
-    metadata: exports_external.string().optional().describe("JSON metadata string"),
-    settings: exports_external.string().optional().describe("JSON settings string")
+    metadata: exports_external.string().optional().describe("JSON metadata"),
+    settings: exports_external.string().optional().describe("JSON settings")
   }
 }, async ({ id, name, description, path, status, repository, tags, metadata, settings }) => {
   const updates = {};
@@ -30218,7 +30363,7 @@ server.registerTool("update_project", {
       updates.tags = JSON.parse(tags);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid tags JSON." }],
+        content: [{ type: "text", text: "invalid tags JSON" }],
         isError: true
       };
     }
@@ -30228,7 +30373,7 @@ server.registerTool("update_project", {
       updates.metadata = JSON.parse(metadata);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid metadata JSON." }],
+        content: [{ type: "text", text: "invalid JSON" }],
         isError: true
       };
     }
@@ -30238,7 +30383,7 @@ server.registerTool("update_project", {
       updates.settings = JSON.parse(settings);
     } catch {
       return {
-        content: [{ type: "text", text: "Invalid settings JSON." }],
+        content: [{ type: "text", text: "invalid JSON" }],
         isError: true
       };
     }
@@ -30257,7 +30402,7 @@ server.registerTool("update_project", {
 });
 server.registerTool("delete_project", {
   title: "Delete Project",
-  description: "Delete a project permanently. Fails if spaces still reference it.",
+  description: "Delete a project permanently. Fails if spaces reference it.",
   inputSchema: {
     id: exports_external.string().describe("Project ID (UUID)")
   }
@@ -30266,7 +30411,7 @@ server.registerTool("delete_project", {
     const deleted = deleteProject(id);
     if (!deleted) {
       return {
-        content: [{ type: "text", text: `Project "${id}" not found` }],
+        content: [{ type: "text", text: `project "${id}" not found` }],
         isError: true
       };
     }
@@ -30282,7 +30427,7 @@ server.registerTool("delete_project", {
 });
 server.registerTool("delete_message", {
   title: "Delete Message",
-  description: "Delete a message. Only the sender can delete their own messages.",
+  description: "Delete a message. Sender only.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     id: exports_external.number().describe("Message ID to delete")
@@ -30292,7 +30437,7 @@ server.registerTool("delete_message", {
   const deleted = deleteMessage(id, agent);
   if (!deleted) {
     return {
-      content: [{ type: "text", text: `Message #${id} not found or not your message` }],
+      content: [{ type: "text", text: `not found or forbidden` }],
       isError: true
     };
   }
@@ -30302,7 +30447,7 @@ server.registerTool("delete_message", {
 });
 server.registerTool("edit_message", {
   title: "Edit Message",
-  description: "Edit a message's content. Only the sender can edit their own messages.",
+  description: "Edit a message's content. Sender only.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     id: exports_external.number().describe("Message ID to edit"),
@@ -30313,7 +30458,7 @@ server.registerTool("edit_message", {
   const msg = editMessage(id, agent, content);
   if (!msg) {
     return {
-      content: [{ type: "text", text: `Message #${id} not found or not your message` }],
+      content: [{ type: "text", text: `not found or forbidden` }],
       isError: true
     };
   }
@@ -30323,7 +30468,7 @@ server.registerTool("edit_message", {
 });
 server.registerTool("pin_message", {
   title: "Pin Message",
-  description: "Pin a message. Pinned messages can be retrieved with get_pinned_messages.",
+  description: "Pin a message in a space or session.",
   inputSchema: {
     id: exports_external.number().describe("Message ID to pin")
   }
@@ -30331,7 +30476,7 @@ server.registerTool("pin_message", {
   const msg = pinMessage(id);
   if (!msg) {
     return {
-      content: [{ type: "text", text: `Message #${id} not found` }],
+      content: [{ type: "text", text: `message #${id} not found` }],
       isError: true
     };
   }
@@ -30349,7 +30494,7 @@ server.registerTool("unpin_message", {
   const msg = unpinMessage(id);
   if (!msg) {
     return {
-      content: [{ type: "text", text: `Message #${id} not found` }],
+      content: [{ type: "text", text: `message #${id} not found` }],
       isError: true
     };
   }
@@ -30359,9 +30504,9 @@ server.registerTool("unpin_message", {
 });
 server.registerTool("get_pinned_messages", {
   title: "Get Pinned Messages",
-  description: "Retrieve pinned messages, optionally filtered by space or session.",
+  description: "Get pinned messages, filtered by space or session.",
   inputSchema: {
-    space: exports_external.string().optional().describe("Filter by space name"),
+    space: exports_external.string().optional().describe("Filter by space"),
     session_id: exports_external.string().optional().describe("Filter by session ID"),
     limit: exports_external.number().optional().describe("Max messages to return")
   }
@@ -30373,7 +30518,7 @@ server.registerTool("get_pinned_messages", {
 });
 server.registerTool("heartbeat", {
   title: "Heartbeat",
-  description: "Send a heartbeat to indicate agent is alive. Optionally set a status.",
+  description: "Send heartbeat. Optionally set agent status.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     status: exports_external.string().optional().describe("Agent status (e.g. 'online', 'busy', 'idle'). Defaults to 'online'.")
@@ -30387,9 +30532,9 @@ server.registerTool("heartbeat", {
 });
 server.registerTool("list_agents", {
   title: "List Agents",
-  description: "List all agents with their presence status. Returns agent name, status, last seen time, and whether they are online.",
+  description: "List agents with presence status.",
   inputSchema: {
-    online_only: exports_external.boolean().optional().describe("Only return agents that are currently online (seen within last 60 seconds)")
+    online_only: exports_external.boolean().optional().describe("Only return agents online within last 60s")
   }
 }, async ({ online_only }) => {
   const agents = listAgents({ online_only });
@@ -30399,7 +30544,7 @@ server.registerTool("list_agents", {
 });
 server.registerTool("get_blockers", {
   title: "Get Blockers",
-  description: "Check for unread blocking messages targeting you. Returns messages that must be acknowledged before continuing.",
+  description: "Check for unread blocking messages. Must acknowledge.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var.")
   }
@@ -30412,7 +30557,7 @@ server.registerTool("get_blockers", {
 });
 server.registerTool("remove_agent", {
   title: "Remove Agent",
-  description: "Remove an agent from the presence list. Only the agent itself should remove its own presence.",
+  description: "Remove an agent from the presence list.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     agent: exports_external.string().optional().describe("Agent to remove (defaults to yourself)")
@@ -30423,7 +30568,7 @@ server.registerTool("remove_agent", {
   const removed = removePresence(agent);
   if (!removed) {
     return {
-      content: [{ type: "text", text: `Agent "${agent}" not found` }],
+      content: [{ type: "text", text: `agent "${agent}" not found` }],
       isError: true
     };
   }
@@ -30433,7 +30578,7 @@ server.registerTool("remove_agent", {
 });
 server.registerTool("rename_agent", {
   title: "Rename Agent",
-  description: "Rename an agent in the presence list. By default renames yourself.",
+  description: "Rename an agent in the presence list.",
   inputSchema: {
     from: exports_external.string().optional().describe("Your current agent ID. Falls back to CONVERSATIONS_AGENT_ID env var."),
     new_name: exports_external.string().describe("The new name for the agent")
@@ -30443,7 +30588,7 @@ server.registerTool("rename_agent", {
   const newName = new_name.trim();
   if (!newName) {
     return {
-      content: [{ type: "text", text: "New name cannot be empty" }],
+      content: [{ type: "text", text: "new name cannot be empty" }],
       isError: true
     };
   }
@@ -30451,7 +30596,7 @@ server.registerTool("rename_agent", {
     const renamed = renameAgent(oldName, newName);
     if (!renamed) {
       return {
-        content: [{ type: "text", text: `Agent "${oldName}" not found in presence list` }],
+        content: [{ type: "text", text: `agent "${oldName}" not found` }],
         isError: true
       };
     }
@@ -30465,6 +30610,78 @@ server.registerTool("rename_agent", {
     };
   }
 });
+server.registerTool("search_tools", {
+  title: "Search Tools",
+  description: "List tool names, optionally filtered by keyword.",
+  inputSchema: {
+    query: exports_external.string().optional().describe("Keyword filter")
+  }
+}, async ({ query }) => {
+  const all = [
+    "send_message",
+    "read_messages",
+    "list_sessions",
+    "reply",
+    "mark_read",
+    "search_messages",
+    "export_messages",
+    "create_space",
+    "list_spaces",
+    "send_to_space",
+    "read_space",
+    "join_space",
+    "leave_space",
+    "update_space",
+    "archive_space",
+    "unarchive_space",
+    "create_project",
+    "list_projects",
+    "get_project",
+    "update_project",
+    "delete_project",
+    "delete_message",
+    "edit_message",
+    "pin_message",
+    "unpin_message",
+    "get_pinned_messages",
+    "heartbeat",
+    "list_agents",
+    "get_blockers",
+    "remove_agent",
+    "rename_agent",
+    "search_tools",
+    "describe_tools"
+  ];
+  const q = query?.toLowerCase();
+  const matches = q ? all.filter((n) => n.includes(q)) : all;
+  return { content: [{ type: "text", text: matches.join(", ") }] };
+});
+server.registerTool("describe_tools", {
+  title: "Describe Tools",
+  description: "Get descriptions for specific tools by name.",
+  inputSchema: {
+    names: exports_external.array(exports_external.string()).describe("Tool names from search_tools")
+  }
+}, async ({ names }) => {
+  const descriptions = {
+    send_message: "Send DM to agent. Params: to, content, from?, priority?",
+    read_messages: "Read messages. Params: space?, from?, to?, unread_only?, limit?",
+    list_sessions: "List sessions. Params: agent?",
+    reply: "Reply to message. Params: id, content, from?",
+    send_to_space: "Send message to space. Params: space, content, from?",
+    read_space: "Read space messages. Params: space, limit?, since?",
+    join_space: "Join a space. Params: space, from?",
+    create_space: "Create space. Params: name, description?, parent_id?",
+    list_spaces: "List spaces with counts. No required params.",
+    heartbeat: "Send heartbeat. Params: from?, status?",
+    list_agents: "List agents with presence. No required params.",
+    get_blockers: "Check for blocking messages. Params: name?",
+    search_messages: "Search messages. Params: query, space?, limit?"
+  };
+  const result = names.map((n) => `${n}: ${descriptions[n] || "See tool schema"}`).join(`
+`);
+  return { content: [{ type: "text", text: result }] };
+});
 async function startMcpServer() {
   const transport = new StdioServerTransport;
   await server.connect(transport);