@hasna/conversations 0.1.28 → 0.1.30

package/bin/hook.js

@@ -118,12 +118,27 @@ function getDb() {
       agent TEXT PRIMARY KEY,
       session_id TEXT,
       role TEXT NOT NULL DEFAULT 'agent',
+      project_id TEXT,
       status TEXT NOT NULL DEFAULT 'online',
       last_seen_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       metadata TEXT
     )
   `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      resource_type TEXT NOT NULL,
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'advisory',
+      locked_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      expires_at TEXT NOT NULL,
+      UNIQUE(resource_type, resource_id, lock_type)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_resource ON resource_locks(resource_type, resource_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_agent ON resource_locks(agent_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_expires ON resource_locks(expires_at)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS reactions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -219,6 +234,9 @@ function getDb() {
     db.exec("ALTER TABLE agent_presence ADD COLUMN created_at TEXT NOT NULL DEFAULT ''");
     db.exec("UPDATE agent_presence SET created_at = last_seen_at WHERE created_at = ''");
   }
+  if (!presenceColNames.includes("project_id")) {
+    db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
+  }
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`

package/bin/index.js

@@ -1972,12 +1972,27 @@ function getDb() {
       agent TEXT PRIMARY KEY,
       session_id TEXT,
       role TEXT NOT NULL DEFAULT 'agent',
+      project_id TEXT,
       status TEXT NOT NULL DEFAULT 'online',
       last_seen_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       metadata TEXT
     )
   `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      resource_type TEXT NOT NULL,
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'advisory',
+      locked_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      expires_at TEXT NOT NULL,
+      UNIQUE(resource_type, resource_id, lock_type)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_resource ON resource_locks(resource_type, resource_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_agent ON resource_locks(agent_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_expires ON resource_locks(expires_at)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS reactions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -2073,6 +2088,9 @@ function getDb() {
     db.exec("ALTER TABLE agent_presence ADD COLUMN created_at TEXT NOT NULL DEFAULT ''");
     db.exec("UPDATE agent_presence SET created_at = last_seen_at WHERE created_at = ''");
   }
+  if (!presenceColNames.includes("project_id")) {
+    db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
+  }
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -3339,6 +3357,7 @@ function parsePresence(row) {
     agent: row.agent,
     session_id: row.session_id ?? null,
     role: row.role || "agent",
+    project_id: row.project_id ?? null,
     status: row.status,
     last_seen_at: lastSeenAt,
     created_at: row.created_at || lastSeenAt,
@@ -3351,43 +3370,46 @@ function isActiveSession(lastSeenAt) {
   const nowMs = Date.now();
   return nowMs - lastSeenMs < CONFLICT_THRESHOLD_SECONDS * 1000;
 }
-function registerAgent(name, sessionId, role) {
+function registerAgent(name, sessionId, role, projectId) {
   const db2 = getDb();
   const normalizedName = name.trim().toLowerCase();
-  const existing = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-  if (existing) {
-    const lastSeenAt = existing.last_seen_at;
-    const existingSessionId = existing.session_id;
-    if (isActiveSession(lastSeenAt) && existingSessionId && existingSessionId !== sessionId) {
-      return {
-        conflict: true,
-        error: "agent_conflict",
-        message: `Agent "${normalizedName}" is already active (last seen: ${lastSeenAt}). Wait 30 minutes or use force takeover.`,
-        existing_id: existing.id,
-        existing_name: normalizedName,
-        existing_session_id: existingSessionId,
-        last_seen_at: lastSeenAt,
-        session_hint: existingSessionId ? existingSessionId.slice(0, 8) : null,
-        working_dir: null
-      };
-    }
-    const tookOver = existingSessionId !== sessionId;
+  const result = db2.transaction(() => {
+    const existing = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+    if (existing) {
+      const lastSeenAt = existing.last_seen_at;
+      const existingSessionId = existing.session_id;
+      if (isActiveSession(lastSeenAt) && existingSessionId && existingSessionId !== sessionId) {
+        return {
+          conflict: true,
+          error: "agent_conflict",
+          message: `Agent "${normalizedName}" is already active (last seen: ${lastSeenAt}). Wait 30 minutes or use force takeover.`,
+          existing_id: existing.id,
+          existing_name: normalizedName,
+          existing_session_id: existingSessionId,
+          last_seen_at: lastSeenAt,
+          session_hint: existingSessionId ? existingSessionId.slice(0, 8) : null,
+          working_dir: null
+        };
+      }
+      const tookOver = existingSessionId !== sessionId;
+      db2.prepare(`
+        UPDATE agent_presence
+        SET session_id = ?, role = ?, project_id = ?, last_seen_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
+        WHERE agent = ?
+      `).run(sessionId, role || existing.role || "agent", projectId ?? existing.project_id ?? null, normalizedName);
+      const updated = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+      return { agent: parsePresence(updated), created: false, took_over: tookOver };
+    }
+    const id = crypto.randomUUID().slice(0, 8);
+    const resolvedRole = role || "agent";
     db2.prepare(`
-      UPDATE agent_presence
-      SET session_id = ?, role = ?, last_seen_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
-      WHERE agent = ?
-    `).run(sessionId, role || existing.role || "agent", normalizedName);
-    const updated = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-    return { agent: parsePresence(updated), created: false, took_over: tookOver };
-  }
-  const id = crypto.randomUUID().slice(0, 8);
-  const resolvedRole = role || "agent";
-  db2.prepare(`
-    INSERT INTO agent_presence (id, agent, session_id, role, status, last_seen_at, created_at)
-    VALUES (?, ?, ?, ?, 'online', strftime('%Y-%m-%dT%H:%M:%f', 'now'), strftime('%Y-%m-%dT%H:%M:%f', 'now'))
-  `).run(id, normalizedName, sessionId, resolvedRole);
-  const created = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-  return { agent: parsePresence(created), created: true, took_over: false };
+      INSERT INTO agent_presence (id, agent, session_id, role, project_id, status, last_seen_at, created_at)
+      VALUES (?, ?, ?, ?, ?, 'online', strftime('%Y-%m-%dT%H:%M:%f', 'now'), strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    `).run(id, normalizedName, sessionId, resolvedRole, projectId ?? null);
+    const created = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+    return { agent: parsePresence(created), created: true, took_over: false };
+  }).immediate();
+  return result;
 }
 function heartbeat(agent, status, metadata, sessionId) {
   const db2 = getDb();
@@ -3591,7 +3613,7 @@ var init_poll = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/conversations",
-    version: "0.1.28",
+    version: "0.1.30",
     description: "Real-time CLI messaging for AI agents",
     type: "module",
     bin: {
@@ -33189,15 +33211,16 @@ var init_mcp2 = __esm(() => {
     };
   });
   server.registerTool("register_agent", {
-    description: "Register an agent with conflict detection. Returns AgentConflictError if another active session exists (active = heartbeat within last 30 min).",
+    description: "Register an agent with conflict detection. Returns AgentConflictError if another active session exists (active = heartbeat within last 30 min). Optional project_id locks agent to a project for the session.",
     inputSchema: {
       name: exports_external.string(),
       session_id: exports_external.string(),
-      role: exports_external.string().optional()
+      role: exports_external.string().optional(),
+      project_id: exports_external.string().optional()
     }
   }, async (args) => {
-    const { name, session_id, role } = args;
-    const result = registerAgent(name, session_id, role);
+    const { name, session_id, role, project_id } = args;
+    const result = registerAgent(name, session_id, role, project_id);
     return {
       content: [{ type: "text", text: JSON.stringify(result) }]
     };

package/bin/mcp.js

@@ -6604,12 +6604,27 @@ function getDb() {
       agent TEXT PRIMARY KEY,
       session_id TEXT,
       role TEXT NOT NULL DEFAULT 'agent',
+      project_id TEXT,
       status TEXT NOT NULL DEFAULT 'online',
       last_seen_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       metadata TEXT
     )
   `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      resource_type TEXT NOT NULL,
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'advisory',
+      locked_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      expires_at TEXT NOT NULL,
+      UNIQUE(resource_type, resource_id, lock_type)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_resource ON resource_locks(resource_type, resource_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_agent ON resource_locks(agent_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_expires ON resource_locks(expires_at)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS reactions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -6705,6 +6720,9 @@ function getDb() {
     db.exec("ALTER TABLE agent_presence ADD COLUMN created_at TEXT NOT NULL DEFAULT ''");
     db.exec("UPDATE agent_presence SET created_at = last_seen_at WHERE created_at = ''");
   }
+  if (!presenceColNames.includes("project_id")) {
+    db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
+  }
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -29765,6 +29783,7 @@ function parsePresence(row) {
     agent: row.agent,
     session_id: row.session_id ?? null,
     role: row.role || "agent",
+    project_id: row.project_id ?? null,
     status: row.status,
     last_seen_at: lastSeenAt,
     created_at: row.created_at || lastSeenAt,
@@ -29777,43 +29796,46 @@ function isActiveSession(lastSeenAt) {
   const nowMs = Date.now();
   return nowMs - lastSeenMs < CONFLICT_THRESHOLD_SECONDS * 1000;
 }
-function registerAgent(name, sessionId, role) {
+function registerAgent(name, sessionId, role, projectId) {
   const db2 = getDb();
   const normalizedName = name.trim().toLowerCase();
-  const existing = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-  if (existing) {
-    const lastSeenAt = existing.last_seen_at;
-    const existingSessionId = existing.session_id;
-    if (isActiveSession(lastSeenAt) && existingSessionId && existingSessionId !== sessionId) {
-      return {
-        conflict: true,
-        error: "agent_conflict",
-        message: `Agent "${normalizedName}" is already active (last seen: ${lastSeenAt}). Wait 30 minutes or use force takeover.`,
-        existing_id: existing.id,
-        existing_name: normalizedName,
-        existing_session_id: existingSessionId,
-        last_seen_at: lastSeenAt,
-        session_hint: existingSessionId ? existingSessionId.slice(0, 8) : null,
-        working_dir: null
-      };
-    }
-    const tookOver = existingSessionId !== sessionId;
+  const result = db2.transaction(() => {
+    const existing = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+    if (existing) {
+      const lastSeenAt = existing.last_seen_at;
+      const existingSessionId = existing.session_id;
+      if (isActiveSession(lastSeenAt) && existingSessionId && existingSessionId !== sessionId) {
+        return {
+          conflict: true,
+          error: "agent_conflict",
+          message: `Agent "${normalizedName}" is already active (last seen: ${lastSeenAt}). Wait 30 minutes or use force takeover.`,
+          existing_id: existing.id,
+          existing_name: normalizedName,
+          existing_session_id: existingSessionId,
+          last_seen_at: lastSeenAt,
+          session_hint: existingSessionId ? existingSessionId.slice(0, 8) : null,
+          working_dir: null
+        };
+      }
+      const tookOver = existingSessionId !== sessionId;
+      db2.prepare(`
+        UPDATE agent_presence
+        SET session_id = ?, role = ?, project_id = ?, last_seen_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
+        WHERE agent = ?
+      `).run(sessionId, role || existing.role || "agent", projectId ?? existing.project_id ?? null, normalizedName);
+      const updated = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+      return { agent: parsePresence(updated), created: false, took_over: tookOver };
+    }
+    const id = crypto.randomUUID().slice(0, 8);
+    const resolvedRole = role || "agent";
     db2.prepare(`
-      UPDATE agent_presence
-      SET session_id = ?, role = ?, last_seen_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
-      WHERE agent = ?
-    `).run(sessionId, role || existing.role || "agent", normalizedName);
-    const updated = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-    return { agent: parsePresence(updated), created: false, took_over: tookOver };
-  }
-  const id = crypto.randomUUID().slice(0, 8);
-  const resolvedRole = role || "agent";
-  db2.prepare(`
-    INSERT INTO agent_presence (id, agent, session_id, role, status, last_seen_at, created_at)
-    VALUES (?, ?, ?, ?, 'online', strftime('%Y-%m-%dT%H:%M:%f', 'now'), strftime('%Y-%m-%dT%H:%M:%f', 'now'))
-  `).run(id, normalizedName, sessionId, resolvedRole);
-  const created = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-  return { agent: parsePresence(created), created: true, took_over: false };
+      INSERT INTO agent_presence (id, agent, session_id, role, project_id, status, last_seen_at, created_at)
+      VALUES (?, ?, ?, ?, ?, 'online', strftime('%Y-%m-%dT%H:%M:%f', 'now'), strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    `).run(id, normalizedName, sessionId, resolvedRole, projectId ?? null);
+    const created = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+    return { agent: parsePresence(created), created: true, took_over: false };
+  }).immediate();
+  return result;
 }
 function heartbeat(agent, status, metadata, sessionId) {
   const db2 = getDb();
@@ -29864,7 +29886,7 @@ function renameAgent(oldName, newName) {
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.1.28",
+  version: "0.1.30",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -30574,15 +30596,16 @@ server.registerTool("get_pinned_messages", {
   };
 });
 server.registerTool("register_agent", {
-  description: "Register an agent with conflict detection. Returns AgentConflictError if another active session exists (active = heartbeat within last 30 min).",
+  description: "Register an agent with conflict detection. Returns AgentConflictError if another active session exists (active = heartbeat within last 30 min). Optional project_id locks agent to a project for the session.",
   inputSchema: {
     name: exports_external.string(),
     session_id: exports_external.string(),
-    role: exports_external.string().optional()
+    role: exports_external.string().optional(),
+    project_id: exports_external.string().optional()
   }
 }, async (args) => {
-  const { name, session_id, role } = args;
-  const result = registerAgent(name, session_id, role);
+  const { name, session_id, role, project_id } = args;
+  const result = registerAgent(name, session_id, role, project_id);
   return {
     content: [{ type: "text", text: JSON.stringify(result) }]
   };

package/dist/index.d.ts

@@ -19,4 +19,6 @@ export { resolveIdentity, requireIdentity, } from "./lib/identity.js";
 export { addReaction, removeReaction, getReactions, getReactionSummary, } 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 type { Message, Session, Space, SpaceInfo, SpaceMember, Project, ProjectInfo, Priority, SendMessageOptions, ReadMessagesOptions, SearchMessagesOptions, AgentPresence, AgentConflictError, RegisterAgentResult, Reaction, Attachment, } from "./types.js";

package/dist/index.js

@@ -131,12 +131,27 @@ function getDb() {
       agent TEXT PRIMARY KEY,
       session_id TEXT,
       role TEXT NOT NULL DEFAULT 'agent',
+      project_id TEXT,
       status TEXT NOT NULL DEFAULT 'online',
       last_seen_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
       metadata TEXT
     )
   `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      resource_type TEXT NOT NULL,
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'advisory',
+      locked_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      expires_at TEXT NOT NULL,
+      UNIQUE(resource_type, resource_id, lock_type)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_resource ON resource_locks(resource_type, resource_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_agent ON resource_locks(agent_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_locks_expires ON resource_locks(expires_at)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS reactions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -232,6 +247,9 @@ function getDb() {
     db.exec("ALTER TABLE agent_presence ADD COLUMN created_at TEXT NOT NULL DEFAULT ''");
     db.exec("UPDATE agent_presence SET created_at = last_seen_at WHERE created_at = ''");
   }
+  if (!presenceColNames.includes("project_id")) {
+    db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
+  }
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -3444,6 +3462,7 @@ function parsePresence(row) {
     agent: row.agent,
     session_id: row.session_id ?? null,
     role: row.role || "agent",
+    project_id: row.project_id ?? null,
     status: row.status,
     last_seen_at: lastSeenAt,
     created_at: row.created_at || lastSeenAt,
@@ -3459,43 +3478,46 @@ function isActiveSession(lastSeenAt) {
 function isAgentConflict(result) {
   return result.conflict === true;
 }
-function registerAgent(name, sessionId, role) {
+function registerAgent(name, sessionId, role, projectId) {
   const db2 = getDb();
   const normalizedName = name.trim().toLowerCase();
-  const existing = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-  if (existing) {
-    const lastSeenAt = existing.last_seen_at;
-    const existingSessionId = existing.session_id;
-    if (isActiveSession(lastSeenAt) && existingSessionId && existingSessionId !== sessionId) {
-      return {
-        conflict: true,
-        error: "agent_conflict",
-        message: `Agent "${normalizedName}" is already active (last seen: ${lastSeenAt}). Wait 30 minutes or use force takeover.`,
-        existing_id: existing.id,
-        existing_name: normalizedName,
-        existing_session_id: existingSessionId,
-        last_seen_at: lastSeenAt,
-        session_hint: existingSessionId ? existingSessionId.slice(0, 8) : null,
-        working_dir: null
-      };
+  const result = db2.transaction(() => {
+    const existing = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+    if (existing) {
+      const lastSeenAt = existing.last_seen_at;
+      const existingSessionId = existing.session_id;
+      if (isActiveSession(lastSeenAt) && existingSessionId && existingSessionId !== sessionId) {
+        return {
+          conflict: true,
+          error: "agent_conflict",
+          message: `Agent "${normalizedName}" is already active (last seen: ${lastSeenAt}). Wait 30 minutes or use force takeover.`,
+          existing_id: existing.id,
+          existing_name: normalizedName,
+          existing_session_id: existingSessionId,
+          last_seen_at: lastSeenAt,
+          session_hint: existingSessionId ? existingSessionId.slice(0, 8) : null,
+          working_dir: null
+        };
+      }
+      const tookOver = existingSessionId !== sessionId;
+      db2.prepare(`
+        UPDATE agent_presence
+        SET session_id = ?, role = ?, project_id = ?, last_seen_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
+        WHERE agent = ?
+      `).run(sessionId, role || existing.role || "agent", projectId ?? existing.project_id ?? null, normalizedName);
+      const updated = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+      return { agent: parsePresence(updated), created: false, took_over: tookOver };
     }
-    const tookOver = existingSessionId !== sessionId;
+    const id = crypto.randomUUID().slice(0, 8);
+    const resolvedRole = role || "agent";
     db2.prepare(`
-      UPDATE agent_presence
-      SET session_id = ?, role = ?, last_seen_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
-      WHERE agent = ?
-    `).run(sessionId, role || existing.role || "agent", normalizedName);
-    const updated = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-    return { agent: parsePresence(updated), created: false, took_over: tookOver };
-  }
-  const id = crypto.randomUUID().slice(0, 8);
-  const resolvedRole = role || "agent";
-  db2.prepare(`
-    INSERT INTO agent_presence (id, agent, session_id, role, status, last_seen_at, created_at)
-    VALUES (?, ?, ?, ?, 'online', strftime('%Y-%m-%dT%H:%M:%f', 'now'), strftime('%Y-%m-%dT%H:%M:%f', 'now'))
-  `).run(id, normalizedName, sessionId, resolvedRole);
-  const created = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
-  return { agent: parsePresence(created), created: true, took_over: false };
+      INSERT INTO agent_presence (id, agent, session_id, role, project_id, status, last_seen_at, created_at)
+      VALUES (?, ?, ?, ?, ?, 'online', strftime('%Y-%m-%dT%H:%M:%f', 'now'), strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    `).run(id, normalizedName, sessionId, resolvedRole, projectId ?? null);
+    const created = db2.prepare("SELECT * FROM agent_presence WHERE agent = ?").get(normalizedName);
+    return { agent: parsePresence(created), created: true, took_over: false };
+  }).immediate();
+  return result;
 }
 function heartbeat(agent, status, metadata, sessionId) {
   const db2 = getDb();
@@ -3549,6 +3571,80 @@ function renameAgent(oldName, newName) {
   db2.prepare("UPDATE agent_presence SET agent = ? WHERE LOWER(agent) = ?").run(normalizedNew, normalizedOld);
   return true;
 }
+// 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);
+}
 export {
   useSpaceMessages,
   updateSpace,
@@ -3563,6 +3659,7 @@ export {
   renameAgent,
   removeReaction,
   removePresence,
+  releaseLock,
   registerAgent,
   readMessages,
   pinMessage,
@@ -3573,6 +3670,7 @@ export {
   listSpaces,
   listSessions,
   listProjects,
+  listLocks,
   listAgents,
   leaveSpace,
   joinSpace,
@@ -3602,6 +3700,9 @@ export {
   createSpace,
   createProject,
   closeDb,
+  cleanExpiredLocks,
+  checkLock,
   archiveSpace,
-  addReaction
+  addReaction,
+  acquireLock
 };

package/dist/lib/locks.d.ts

@@ -0,0 +1,20 @@
+export interface ResourceLock {
+    resource_type: string;
+    resource_id: string;
+    agent_id: string;
+    lock_type: "advisory" | "exclusive";
+    locked_at: string;
+    expires_at: string;
+}
+export declare function acquireLock(resourceType: string, resourceId: string, agentId: string, lockType?: "advisory" | "exclusive", expiryMs?: number): {
+    acquired: boolean;
+    lock: ResourceLock | null;
+    held_by?: string;
+};
+export declare function releaseLock(resourceType: string, resourceId: string, agentId: string): boolean;
+export declare function checkLock(resourceType: string, resourceId: string): ResourceLock | null;
+export declare function cleanExpiredLocks(): number;
+export declare function listLocks(opts?: {
+    resource_type?: string;
+    agent_id?: string;
+}): ResourceLock[];

package/dist/lib/locks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/presence.d.ts

@@ -1,6 +1,6 @@
 import type { AgentPresence, AgentConflictError, RegisterAgentResult } from "../types.js";
 export declare function isAgentConflict(result: RegisterAgentResult | AgentConflictError): result is AgentConflictError;
-export declare function registerAgent(name: string, sessionId: string, role?: string): RegisterAgentResult | AgentConflictError;
+export declare function registerAgent(name: string, sessionId: string, role?: string, projectId?: string): RegisterAgentResult | AgentConflictError;
 export declare function heartbeat(agent: string, status?: string, metadata?: Record<string, unknown>, sessionId?: string): void;
 export declare function getPresence(agent: string): AgentPresence | null;
 export declare function listAgents(opts?: {

package/dist/types.d.ts

@@ -116,6 +116,7 @@ export interface AgentPresence {
     agent: string;
     session_id: string | null;
     role: string;
+    project_id: string | null;
     status: string;
     last_seen_at: string;
     created_at: string;

package/package.json

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