@hasna/conversations 0.2.1 → 0.2.3

package/bin/mcp.js

@@ -6,39 +6,60 @@ var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
-var __moduleCache = /* @__PURE__ */ new WeakMap;
 var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
     return entry;
   entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
   __moduleCache.set(from, entry);
   return entry;
 };
+var __moduleCache;
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -28879,12 +28900,64 @@ function getMessageById(id) {
   const row = db2.prepare("SELECT * FROM messages WHERE id = ?").get(id);
   return row ? parseMessage(row) : null;
 }
+function markReadByIds(ids) {
+  const db2 = getDb();
+  if (ids.length === 0)
+    return 0;
+  const placeholders = ids.map(() => "?").join(", ");
+  const stmt = db2.prepare(`UPDATE messages SET read_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE id IN (${placeholders}) AND read_at IS NULL`);
+  const result = stmt.run(...ids);
+  return result.changes;
+}
 function markAllRead(agent) {
   const db2 = getDb();
   const stmt = db2.prepare(`UPDATE messages SET read_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE to_agent = ? AND read_at IS NULL`);
   const result = stmt.run(agent);
   return result.changes;
 }
+function readDigest(opts = {}) {
+  const db2 = getDb();
+  const countConditions = ["read_at IS NULL"];
+  const countParams = [];
+  if (opts.space) {
+    countConditions.push("space = ?");
+    countParams.push(opts.space);
+  }
+  if (opts.session_id) {
+    countConditions.push("session_id = ?");
+    countParams.push(opts.session_id);
+  }
+  if (opts.to) {
+    countConditions.push("to_agent = ?");
+    countParams.push(opts.to);
+  }
+  if (opts.since) {
+    countConditions.push("created_at > ?");
+    countParams.push(opts.since);
+  }
+  if (opts.project_id) {
+    countConditions.push("project_id = ?");
+    countParams.push(opts.project_id);
+  }
+  const countWhere = `WHERE ${countConditions.join(" AND ")}`;
+  const totalUnread = db2.prepare(`SELECT COUNT(*) as n FROM messages ${countWhere}`).get(...countParams).n;
+  const messages = readMessages({ ...opts, unread_only: opts.unread_only ?? true });
+  if (messages.length > 0) {
+    markReadByIds(messages.map((m) => m.id));
+  }
+  const digest = messages.map((m) => ({
+    id: m.id,
+    from: m.from_agent,
+    created_at: m.created_at,
+    preview: m.content.slice(0, 100) + (m.content.length > 100 ? "\u2026" : ""),
+    priority: m.priority,
+    has_attachments: Array.isArray(m.attachments) && m.attachments.length > 0,
+    space: m.space,
+    to: m.to_agent,
+    unread: !m.read_at
+  }));
+  return { messages: digest, total_unread: totalUnread, shown: digest.length };
+}
 function escapeCsvField(value) {
   if (value === null || value === undefined)
     return "";
@@ -29068,6 +29141,39 @@ function searchMessages(opts) {
     return { ...msg, snippet: null, relevance_score: 0 };
   });
 }
+function listUnreadCounts(agent) {
+  const db2 = getDb();
+  if (agent) {
+    const rows2 = db2.prepare(`
+      SELECT
+        space,
+        COUNT(CASE WHEN read_at IS NULL AND (to_agent = ? OR to_agent IS NULL OR to_agent = '') THEN 1 END) AS unread_count,
+        MAX(created_at) AS latest_message_at
+      FROM messages
+      WHERE space IN (
+        SELECT DISTINCT space FROM space_members WHERE agent = ?
+        UNION
+        SELECT DISTINCT space FROM messages WHERE to_agent = ? AND space IS NOT NULL
+      )
+      GROUP BY space
+      HAVING COUNT(*) > 0
+      ORDER BY unread_count DESC, latest_message_at DESC
+    `).all(agent, agent, agent);
+    return rows2;
+  }
+  const rows = db2.prepare(`
+    SELECT
+      space,
+      COUNT(CASE WHEN read_at IS NULL THEN 1 END) AS unread_count,
+      MAX(created_at) AS latest_message_at
+    FROM messages
+    WHERE space IS NOT NULL
+    GROUP BY space
+    HAVING COUNT(*) > 0
+    ORDER BY unread_count DESC, latest_message_at DESC
+  `).all();
+  return rows;
+}
 
 // src/lib/sessions.ts
 init_db();
@@ -30050,10 +30156,12 @@ function getReactionSummary(messageId) {
 // src/lib/locks.ts
 init_db();
 var DEFAULT_LOCK_EXPIRY_MS = 5 * 60 * 1000;
+var STALE_HEARTBEAT_SECONDS = 30 * 60;
 function acquireLock(resourceType, resourceId, agentId, lockType = "advisory", expiryMs = DEFAULT_LOCK_EXPIRY_MS) {
   const db2 = getDb();
   return db2.transaction(() => {
     cleanExpiredLocks();
+    releaseStaleAgentLocks();
     const existing = db2.prepare(`
       SELECT * FROM resource_locks
       WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
@@ -30080,6 +30188,55 @@ function acquireLock(resourceType, resourceId, agentId, lockType = "advisory", e
     return { acquired: true, lock };
   }).immediate();
 }
+function bulkAcquireLock(resources, agentId) {
+  const db2 = getDb();
+  return db2.transaction(() => {
+    cleanExpiredLocks();
+    releaseStaleAgentLocks();
+    const acquired = [];
+    for (const { resource_type, resource_id, lock_type = "advisory", expiry_ms = DEFAULT_LOCK_EXPIRY_MS } of resources) {
+      const existing = db2.prepare(`
+        SELECT * FROM resource_locks
+        WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+      `).get(resource_type, resource_id, lock_type);
+      if (existing && existing.agent_id !== agentId) {
+        throw { _bulkConflict: true, resource_type, resource_id, held_by: existing.agent_id };
+      }
+      const expiresAt = new Date(Date.now() + expiry_ms).toISOString().slice(0, -1);
+      if (existing) {
+        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, resource_type, resource_id, lock_type);
+      } else {
+        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(resource_type, resource_id, agentId, lock_type, expiresAt);
+      }
+      const lock = db2.prepare(`
+        SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+      `).get(resource_type, resource_id, lock_type);
+      acquired.push(lock);
+    }
+    return { acquired: true, locks: acquired };
+  }).immediate();
+}
+function tryBulkAcquireLock(resources, agentId) {
+  try {
+    return bulkAcquireLock(resources, agentId);
+  } catch (err) {
+    const e = err;
+    if (e?._bulkConflict) {
+      return {
+        acquired: false,
+        locks: [],
+        blocked_by: { resource_type: e.resource_type, resource_id: e.resource_id, held_by: e.held_by }
+      };
+    }
+    throw err;
+  }
+}
 function releaseLock(resourceType, resourceId, agentId) {
   const db2 = getDb();
   const result = db2.prepare(`
@@ -30091,6 +30248,7 @@ function releaseLock(resourceType, resourceId, agentId) {
 function checkLock(resourceType, resourceId) {
   const db2 = getDb();
   cleanExpiredLocks();
+  releaseStaleAgentLocks();
   return db2.prepare(`
     SELECT * FROM resource_locks
     WHERE resource_type = ? AND resource_id = ?
@@ -30098,6 +30256,17 @@ function checkLock(resourceType, resourceId) {
     LIMIT 1
   `).get(resourceType, resourceId);
 }
+function releaseStaleAgentLocks() {
+  const db2 = getDb();
+  const result = db2.prepare(`
+    DELETE FROM resource_locks
+    WHERE LOWER(agent_id) IN (
+      SELECT LOWER(agent) FROM agent_presence
+      WHERE last_seen_at < strftime('%Y-%m-%dT%H:%M:%f', 'now', '-${STALE_HEARTBEAT_SECONDS} seconds')
+    )
+  `).run();
+  return result.changes;
+}
 function cleanExpiredLocks() {
   const db2 = getDb();
   const result = db2.prepare(`
@@ -30108,6 +30277,7 @@ function cleanExpiredLocks() {
 function listLocks(opts) {
   const db2 = getDb();
   cleanExpiredLocks();
+  releaseStaleAgentLocks();
   let query = "SELECT * FROM resource_locks WHERE 1=1";
   const params = [];
   if (opts?.resource_type) {
@@ -30121,6 +30291,31 @@ function listLocks(opts) {
   query += " ORDER BY locked_at ASC";
   return db2.prepare(query).all(...params);
 }
+function listLocksEnriched(opts) {
+  const locks = listLocks(opts);
+  const db2 = getDb();
+  const nowMs = Date.now();
+  return locks.map((lock) => {
+    const lockedMs = new Date(lock.locked_at + "Z").getTime();
+    const expiresMs = new Date(lock.expires_at + "Z").getTime();
+    const presenceRow = db2.prepare(`
+      SELECT role, status, last_seen_at, project_id FROM agent_presence WHERE LOWER(agent) = LOWER(?)
+    `).get(lock.agent_id);
+    const agent = presenceRow ? {
+      role: presenceRow.role ?? null,
+      status: presenceRow.status ?? null,
+      online: presenceRow.last_seen_at ? nowMs - new Date(presenceRow.last_seen_at + "Z").getTime() < 60000 : false,
+      last_seen_at: presenceRow.last_seen_at ?? null,
+      project_id: presenceRow.project_id ?? null
+    } : null;
+    return {
+      ...lock,
+      locked_seconds_ago: Math.round((nowMs - lockedMs) / 1000),
+      expires_in_seconds: Math.round((expiresMs - nowMs) / 1000),
+      agent
+    };
+  });
+}
 
 // src/lib/hot.ts
 init_db();
@@ -30605,7 +30800,7 @@ function getGraphStats() {
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.2.1",
+  version: "0.2.3",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -30735,7 +30930,8 @@ server.registerTool("read_messages", {
     project_id: exports_external.string().optional(),
     since: exports_external.string().optional(),
     limit: exports_external.coerce.number().optional(),
-    unread_only: exports_external.coerce.boolean().optional()
+    unread_only: exports_external.coerce.boolean().optional(),
+    mark_read: exports_external.coerce.boolean().optional()
   }
 }, async (args) => {
   const agent = resolveIdentity(args.from);
@@ -30743,6 +30939,9 @@ server.registerTool("read_messages", {
     ...args,
     project_id: args.project_id ?? resolveProjectId(undefined, agent)
   });
+  if (args.mark_read !== false && messages.length > 0) {
+    markReadByIds(messages.map((m) => m.id));
+  }
   return {
     content: [{ type: "text", text: JSON.stringify(messages) }]
   };
@@ -30901,6 +31100,17 @@ server.registerTool("list_spaces", {
     content: [{ type: "text", text: JSON.stringify(spaces) }]
   };
 });
+server.registerTool("list_unread_counts", {
+  description: "Get unread message counts per space without fetching message content. Use this at session start to triage which spaces need attention before calling read_messages.",
+  inputSchema: {
+    agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts.")
+  }
+}, async (args) => {
+  const counts = listUnreadCounts(args.agent);
+  return {
+    content: [{ type: "text", text: JSON.stringify(counts) }]
+  };
+});
 server.registerTool("send_to_space", {
   description: "Post a message to a space.",
   inputSchema: {
@@ -30938,15 +31148,36 @@ server.registerTool("read_space", {
   inputSchema: {
     space: exports_external.string(),
     since: exports_external.string().optional(),
-    limit: exports_external.coerce.number().optional()
+    limit: exports_external.coerce.number().optional(),
+    mark_read: exports_external.coerce.boolean().optional()
   }
 }, async (args) => {
-  const { space, since, limit } = args;
+  const { space, since, limit, mark_read } = args;
   const messages = readMessages({ space, since, limit });
+  if (mark_read !== false && messages.length > 0) {
+    markReadByIds(messages.map((m) => m.id));
+  }
   return {
     content: [{ type: "text", text: JSON.stringify(messages) }]
   };
 });
+server.registerTool("read_digest", {
+  description: "Lightweight unread message digest \u2014 returns preview-only summaries, auto-marks as read. Use instead of read_messages on busy spaces to avoid token overflow.",
+  inputSchema: {
+    space: exports_external.string().optional(),
+    session_id: exports_external.string().optional(),
+    to: exports_external.string().optional(),
+    since: exports_external.string().optional(),
+    limit: exports_external.coerce.number().optional(),
+    project_id: exports_external.string().optional()
+  }
+}, async (args) => {
+  const { space, session_id, to, since, limit, project_id } = args;
+  const result = readDigest({ space, session_id, to, since, limit, project_id });
+  return {
+    content: [{ type: "text", text: JSON.stringify(result) }]
+  };
+});
 server.registerTool("join_space", {
   description: "Join a space as a member.",
   inputSchema: {
@@ -31479,18 +31710,29 @@ server.registerTool("get_reaction_summary", {
   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.",
+  description: "Acquire an advisory or exclusive lock on a resource. Returns conflict info if another agent holds the lock. On conflict, auto-DMs the holding agent.",
   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()
+    from: exports_external.string().optional(),
+    auto_dm: exports_external.coerce.boolean().optional()
   }
 }, async (args) => {
-  const { resource_type, resource_id, lock_type, expiry_ms, from: fromParam } = args;
+  const { resource_type, resource_id, lock_type, expiry_ms, from: fromParam, auto_dm } = args;
   const agent = resolveIdentity(fromParam);
   const result = acquireLock(resource_type, resource_id, agent, lock_type ?? "advisory", expiry_ms);
+  if (!result.acquired && result.held_by && auto_dm !== false) {
+    try {
+      sendMessage({
+        from: agent,
+        to: result.held_by,
+        content: `Lock conflict: I (@${agent}) tried to acquire ${lock_type ?? "advisory"} lock on \`${resource_type}/${resource_id}\` but you hold it. If you no longer need it, release it with \`release_lock\`.`,
+        priority: "high"
+      });
+    } catch {}
+  }
   return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
 server.registerTool("release_lock", {
@@ -31517,15 +31759,50 @@ server.registerTool("check_lock", {
   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.",
+  description: "List all active (non-expired) locks enriched with agent presence details (status, online, last_seen_at) and time context (locked_seconds_ago, expires_in_seconds). 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 });
+  const locks = listLocksEnriched({ resource_type: args.resource_type, agent_id: args.agent_id });
   return { content: [{ type: "text", text: JSON.stringify(locks) }] };
 });
+server.registerTool("bulk_acquire_lock", {
+  description: "Atomically acquire multiple locks at once. All-or-nothing: if any lock is held by another agent, none are acquired. Returns blocked_by info on conflict.",
+  inputSchema: {
+    resources: exports_external.array(exports_external.object({
+      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(),
+    auto_dm: exports_external.coerce.boolean().optional()
+  }
+}, async (args) => {
+  const agent = resolveIdentity(args.from);
+  const result = tryBulkAcquireLock(args.resources, agent);
+  if (!result.acquired && result.blocked_by && args.auto_dm !== false) {
+    try {
+      sendMessage({
+        from: agent,
+        to: result.blocked_by.held_by,
+        content: `Bulk lock conflict: I (@${agent}) tried to atomically acquire ${args.resources.length} locks but you hold \`${result.blocked_by.resource_type}/${result.blocked_by.resource_id}\`. Release it when done.`,
+        priority: "high"
+      });
+    } catch {}
+  }
+  return { content: [{ type: "text", text: JSON.stringify(result) }] };
+});
+server.registerTool("clean_expired_locks", {
+  description: "Clean up expired locks and auto-release locks held by agents whose heartbeat has been stale for >30 minutes. Returns counts of removed locks.",
+  inputSchema: {}
+}, async () => {
+  const stale = releaseStaleAgentLocks();
+  const expired = cleanExpiredLocks();
+  return { content: [{ type: "text", text: JSON.stringify({ released_stale_agent: stale, released_expired: expired, total: stale + expired }) }] };
+});
 server.registerTool("get_thread_replies", {
   description: "Get all replies in a thread for a given parent message ID.",
   inputSchema: {
@@ -31709,6 +31986,7 @@ server.registerTool("search_tools", {
   const all = [
     "send_message",
     "read_messages",
+    "read_digest",
     "list_sessions",
     "reply",
     "mark_read",
@@ -31747,9 +32025,11 @@ server.registerTool("search_tools", {
     "get_reactions",
     "get_reaction_summary",
     "acquire_lock",
+    "bulk_acquire_lock",
     "release_lock",
     "check_lock",
     "list_locks",
+    "clean_expired_locks",
     "get_thread_replies",
     "set_focus",
     "get_focus",
@@ -31775,16 +32055,18 @@ server.registerTool("describe_tools", {
 }, async ({ names }) => {
   const descriptions = {
     send_message: "Send DM to agent. Required: to, content. Optional: from?, priority?(low|normal|high|urgent), blocking?",
-    read_messages: "Read messages with filters. Optional: session_id?, from?, to?, space?, since?(ISO), limit?, unread_only?",
+    read_messages: "Read messages with filters. Optional: session_id?, from?, to?, space?, since?(ISO), limit?, unread_only?, mark_read?(default true \u2014 auto-marks returned messages as read, pass false to peek without consuming)",
+    read_digest: "Lightweight unread digest \u2014 preview only (no full bodies), auto-marks read, never overflows tokens. Returns { messages, total_unread, shown }. Optional: space?, session_id?, to?, since?(ISO), limit?, project_id?",
     list_sessions: "List all DM sessions. Optional: agent?(filter by participant)",
     reply: "Reply to a message in same session. Required: message_id, content. Optional: from?",
     mark_read: "Mark messages as read. Optional: from?, ids?(array), all?(bool \u2014 mark all unread)",
     search_messages: "Full-text search messages. Required: query. Optional: space?, from?, to?, limit?",
     export_messages: "Export messages as JSON or CSV. Optional: space?, session_id?, from?, since?, until?, format?(json|csv)",
     create_space: "Create space and auto-join. Required: name. Optional: from?, description?, parent_id?(max 3 levels), project_id?",
+    list_unread_counts: "Get unread message counts per space (no content). Ideal for session start triage. Optional: agent?(filter to agent's spaces)",
     list_spaces: "List spaces with member/message counts. Optional: project_id?, parent_id?(use 'null' for top-level), include_archived?",
     send_to_space: "Post message to space. Required: space, content. Optional: from?, priority?(low|normal|high|urgent), blocking?",
-    read_space: "Read messages in a space. Required: space. Optional: since?(ISO), limit?",
+    read_space: "Read messages in a space. Required: space. Optional: since?(ISO), limit?, mark_read?(default true \u2014 auto-marks returned messages as read)",
     join_space: "Join a space. Required: space. Optional: from?",
     leave_space: "Leave a space. Required: space. Optional: from?",
     update_space: "Update space fields. Required: name. Optional: description?, parent_id?(use 'null' to remove), project_id?(use 'null' to remove)",
@@ -31813,10 +32095,12 @@ server.registerTool("describe_tools", {
     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?",
+    acquire_lock: "Acquire advisory/exclusive lock on a resource. On conflict, auto-DMs the holding agent. Required: resource_type, resource_id. Optional: lock_type?(advisory|exclusive), expiry_ms?, from?, auto_dm?(default true)",
+    bulk_acquire_lock: "Atomically acquire multiple locks (all-or-nothing). Required: resources[]{resource_type,resource_id,lock_type?,expiry_ms?}. Optional: from?, auto_dm?(default true). Returns blocked_by on conflict.",
     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?",
+    list_locks: "List active locks enriched with agent presence + time context. Optional: resource_type?, agent_id?",
+    clean_expired_locks: "Release expired locks + locks held by agents with stale heartbeat (>30 min). Returns {released_stale_agent, released_expired, total}",
     get_thread_replies: "Get all replies in a thread. Required: message_id. Optional: limit?",
     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?",

package/dist/index.d.ts

@@ -21,8 +21,8 @@ export { addReaction, removeReaction, getReactions, getReactionSummary, } from "
 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";
-export type { ResourceLock } from "./lib/locks.js";
+export { acquireLock, tryBulkAcquireLock, releaseLock, checkLock, cleanExpiredLocks, releaseStaleAgentLocks, listLocks, listLocksEnriched, } from "./lib/locks.js";
+export type { ResourceLock, EnrichedLock, BulkLockRequest, BulkAcquireResult } from "./lib/locks.js";
 export { computeHotness, listHotSessions, } from "./lib/hot.js";
 export type { HotSession, HotSessionsOptions } from "./lib/hot.js";
 export { extractTopics, getSpaceTopics, getSessionTopics, getTrendingTopics, } from "./lib/topics.js";