@band-ai/sdk 0.2.1 → 0.3.0

package/dist/runtime.cjs

@@ -41,10 +41,11 @@ __export(runtime_exports, {
   MCP_TOOL_PREFIX: () => MCP_TOOL_PREFIX,
   MEMORY_SECTION: () => MEMORY_SECTION,
   MEMORY_TOOL_NAMES: () => MEMORY_TOOL_NAMES,
-  ParticipantRoster: () => import_band_sdk_core3.ParticipantRoster,
+  ParticipantRoster: () => import_band_sdk_core4.ParticipantRoster,
   PlatformRuntime: () => PlatformRuntime,
-  RetryTracker: () => import_band_sdk_core3.RetryTracker,
+  RetryTracker: () => import_band_sdk_core4.RetryTracker,
   RoomPresence: () => RoomPresence,
+  RoomRoster: () => import_band_sdk_core4.RoomRoster,
   SYNTHETIC_CONTACT_EVENTS_SENDER_ID: () => SYNTHETIC_CONTACT_EVENTS_SENDER_ID,
   SYNTHETIC_CONTACT_EVENTS_SENDER_NAME: () => SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
   SYNTHETIC_SENDER_TYPE: () => SYNTHETIC_SENDER_TYPE,
@@ -58,6 +59,7 @@ __export(runtime_exports, {
   getToolDescription: () => getToolDescription,
   isChatEventType: () => isChatEventType,
   mcpToolNames: () => mcpToolNames,
+  mentionSubjectsFromMetadata: () => mentionSubjectsFromMetadata,
   renderSystemPrompt: () => renderSystemPrompt,
   replaceUuidMentions: () => replaceUuidMentions,
   runWithGracefulShutdown: () => runWithGracefulShutdown
@@ -138,6 +140,26 @@ var RuntimeStateError = class extends BandSdkError {
 function isMetadataMap(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function mentionSubjectsFromMetadata(metadata) {
+  const mentions = metadata?.mentions;
+  if (!Array.isArray(mentions)) {
+    return [];
+  }
+  const subjects = [];
+  for (const mention of mentions) {
+    if (!isMetadataMap(mention) || typeof mention.id !== "string") {
+      continue;
+    }
+    const label = [mention.handle, mention.username, mention.name].find(
+      (value) => typeof value === "string" && value.trim().length > 0
+    );
+    if (label === void 0) {
+      continue;
+    }
+    subjects.push({ id: mention.id, handle: label });
+  }
+  return subjects;
+}
 function replaceUuidMentions(content, participants) {
   if (!content || participants.length === 0) {
     return content;
@@ -1234,6 +1256,13 @@ function isToolExecutorError(value) {
   const candidate = value;
   return candidate.ok === false && typeof candidate.errorType === "string" && TOOL_EXECUTOR_ERROR_TYPES.includes(candidate.errorType) && typeof candidate.toolName === "string" && typeof candidate.message === "string" && typeof candidate.legacyMessage === "string";
 }
+function isStructuredToolFailure(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const payload = value;
+  return payload.ok === false && typeof payload.message === "string";
+}
 var DEFAULT_AGENT_TOOLS_CAPABILITIES = {
   peers: true,
   contacts: true,
@@ -1711,10 +1740,12 @@ var AgentTools = class {
   roster;
   adapterTools;
   toolHandlers;
+  logger;
   constructor(options) {
     this.roomId = options.roomId;
     this.rest = options.rest;
     this.roster = options.roster ?? new import_band_sdk_core.ParticipantRoster();
+    this.logger = options.logger ?? new NoopLogger();
     this.capabilities = {
       ...DEFAULT_AGENT_TOOLS_CAPABILITIES,
       ...options.capabilities
@@ -1744,14 +1775,23 @@ var AgentTools = class {
   }
   async sendEvent(content, messageType, metadata) {
     assertChatEventType(messageType);
-    return this.rest.createChatEvent(
-      this.roomId,
-      {
-        content,
-        messageType,
-        metadata
+    try {
+      return await this.rest.createChatEvent(
+        this.roomId,
+        {
+          content,
+          messageType,
+          metadata
+        }
+      );
+    } catch (error) {
+      try {
+        this.logger.warn("chat event send failed", { roomId: this.roomId, messageType, error });
+      } catch {
       }
-    );
+      const message = error instanceof Error ? error.message : String(error);
+      return { ok: false, status: "failed", message };
+    }
   }
   async createChatroom(taskId) {
     const room = await this.rest.createChat(taskId, DEFAULT_REQUEST_OPTIONS);
@@ -1854,7 +1894,16 @@ var AgentTools = class {
       });
     }
     try {
-      return await handler(arguments_);
+      const result = await handler(arguments_);
+      if (toolName === "band_send_event" && isStructuredToolFailure(result) && !isToolExecutorError(result)) {
+        return createToolExecutorError({
+          errorType: "ToolExecutionError",
+          toolName,
+          message: result.message,
+          legacyMessage: `Error executing ${toolName}: ${result.message}`
+        });
+      }
+      return result;
     } catch (error) {
       if (isToolExecutorError(error)) {
         return error;
@@ -2555,7 +2604,8 @@ var ExecutionContext = class {
       roomId: this.roomId,
       rest: this.link.rest,
       roster: this.roster,
-      capabilities: this.link.capabilities
+      capabilities: this.link.capabilities,
+      logger: options.logger ?? new NoopLogger()
     });
     this.adapterTools = this.tools.getAdapterTools();
   }
@@ -2803,70 +2853,278 @@ var ExecutionContext = class {
   }
 };
 
+// src/runtime/rooms/RoomPresence.ts
+var import_band_sdk_core3 = require("@band-ai/band-sdk-core");
+
 // src/runtime/rooms/subscriptions.ts
-function hasRoomId(roomId) {
-  return typeof roomId === "string" && roomId.length > 0;
+async function hydrateExistingRooms(options) {
+  try {
+    const rooms = await options.link.listAllChats(void 0, options.requestOptions);
+    for (const room of rooms) {
+      const roomId = typeof room.id === "string" ? room.id : null;
+      if (!roomId) {
+        continue;
+      }
+      if (options.roomFilter && !options.roomFilter(room)) {
+        continue;
+      }
+      await options.onRoom(roomId, room);
+    }
+  } catch (error) {
+    if (error instanceof UnsupportedFeatureError) {
+      return;
+    }
+    if (options.onError) {
+      await options.onError(error);
+      return;
+    }
+    throw error;
+  }
 }
-async function trackRoomJoin(options) {
-  if (!hasRoomId(options.roomId)) {
-    return false;
+
+// src/runtime/rooms/RoomPresence.ts
+var RoomPresence = class {
+  roster = new import_band_sdk_core3.RoomRoster();
+  onRoomJoined = null;
+  onRoomLeft = null;
+  onRoomEvent = null;
+  onContactEvent = null;
+  link;
+  roomFilter;
+  autoSubscribeExistingRooms;
+  logger;
+  eventController = null;
+  eventTask = null;
+  contactsSubscribed = false;
+  lifecycle = Promise.resolve();
+  admissionInFlight = /* @__PURE__ */ new Map();
+  // Read once by `admitRoomOrThrow` right after a failed admission; a
+  // subsequent successful subscribe clears it so a caller never attributes
+  // today's failure to a stale reason from an earlier attempt.
+  lastSubscribeError = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.link = options.link;
+    this.roomFilter = options.roomFilter;
+    this.autoSubscribeExistingRooms = options.autoSubscribeExistingRooms ?? true;
+    this.logger = options.logger ?? new NoopLogger();
   }
-  if (options.roomFilter && !options.roomFilter(options.payload)) {
-    return false;
+  async start() {
+    return this.serialize(() => this.startBody());
   }
-  if (options.trackedRooms.has(options.roomId)) {
-    return false;
+  async stop() {
+    return this.serialize(() => this.stopBody());
   }
-  await options.link.subscribeRoom(options.roomId);
-  options.trackedRooms.add(options.roomId);
-  if (options.onJoined) {
-    await options.onJoined(options.roomId, options.payload);
+  async [Symbol.asyncDispose]() {
+    await this.stop();
   }
-  return true;
-}
-async function trackRoomLeave(options) {
-  if (!hasRoomId(options.roomId) || !options.trackedRooms.has(options.roomId)) {
-    return false;
+  abortEventLoop() {
+    this.eventController?.abort();
   }
-  await options.link.unsubscribeRoom(options.roomId);
-  options.trackedRooms.delete(options.roomId);
-  if (options.onLeft) {
-    await options.onLeft(options.roomId);
+  async waitUntilStopped() {
+    await this.eventTask;
   }
-  return true;
-}
-async function hydrateTrackedRooms(options) {
-  const pageSize = options.pageSize ?? 100;
-  const maxPages = options.maxPages ?? 100;
-  try {
-    const rooms = await options.link.listAllChats(
-      { pageSize, maxPages },
-      options.requestOptions
+  async admitRoom(roomId, payload, notify = true) {
+    const ticket = this.roster.beginRoomAdmission(roomId, true);
+    const admitted = ticket === void 0 ? await this.awaitInFlightAdmission(roomId) : await this.performAdmission(roomId, ticket);
+    if (admitted && notify) {
+      await this.onRoomJoined?.(roomId, payload);
+    }
+    return admitted;
+  }
+  /** Admit a room for a caller that needs to know *why* a failed subscribe happened, not just that it did. */
+  async admitRoomOrThrow(roomId) {
+    if (!await this.admitRoom(roomId, {}, false)) {
+      throw new TransportError(`Failed to subscribe to room ${roomId}`, this.lastSubscribeError.get(roomId));
+    }
+  }
+  async awaitInFlightAdmission(roomId) {
+    const inFlight = this.admissionInFlight.get(roomId);
+    return inFlight ? await inFlight : this.roster.roomMembership(roomId) === "admitted";
+  }
+  async performAdmission(roomId, ticket) {
+    const admission = this.completeAdmission(roomId, ticket);
+    this.admissionInFlight.set(roomId, admission);
+    try {
+      return await admission;
+    } finally {
+      if (this.admissionInFlight.get(roomId) === admission) {
+        this.admissionInFlight.delete(roomId);
+      }
+    }
+  }
+  async completeAdmission(roomId, ticket) {
+    let succeeded = false;
+    let admitted = false;
+    let subscribeError;
+    try {
+      await this.link.subscribeRoom(roomId);
+      succeeded = true;
+    } catch (error) {
+      this.logger.warn("RoomPresence failed to subscribe room", { roomId, error });
+      subscribeError = error;
+    } finally {
+      admitted = this.roster.recordRoomAdmission(roomId, ticket, succeeded);
+    }
+    const roomIsAdmitted = admitted || this.roster.roomMembership(roomId) === "admitted";
+    if (succeeded && !admitted && !roomIsAdmitted) {
+      this.logger.debug("RoomPresence admission ticket went stale", { roomId });
+      await this.unsubscribeRoom(roomId);
+    }
+    if (roomIsAdmitted) {
+      this.lastSubscribeError.delete(roomId);
+    } else if (subscribeError !== void 0) {
+      this.lastSubscribeError.set(roomId, subscribeError);
+    }
+    return roomIsAdmitted;
+  }
+  async serialize(body) {
+    const run = this.lifecycle.then(body, body);
+    this.lifecycle = run.then(
+      () => void 0,
+      () => void 0
     );
-    for (const room of rooms) {
-      await trackRoomJoin({
-        link: options.link,
-        roomId: typeof room.id === "string" ? room.id : null,
-        payload: room,
-        trackedRooms: options.trackedRooms,
-        roomFilter: options.roomFilter,
-        onJoined: options.onJoined
+    return run;
+  }
+  async startBody() {
+    if (this.eventTask) {
+      throw new RuntimeStateError("RoomPresence is already started");
+    }
+    if (!this.link.isConnected()) {
+      await this.link.connect();
+    }
+    const contactsReady = this.subscribeContacts();
+    try {
+      await this.link.subscribeAgentRooms();
+    } catch (error) {
+      this.logger.warn("RoomPresence failed to subscribe agent_rooms channel, continuing without it", {
+        error
       });
     }
-  } catch (error) {
-    if (error instanceof UnsupportedFeatureError) {
+    if (this.autoSubscribeExistingRooms) {
+      await this.subscribeExistingRooms();
+    }
+    await contactsReady;
+    this.eventController = new AbortController();
+    this.eventTask = this.consumeEvents(this.eventController.signal);
+  }
+  async subscribeContacts() {
+    if (!this.link.capabilities.contacts) {
       return;
     }
-    if (options.onError) {
-      await options.onError(error);
+    try {
+      await this.link.subscribeAgentContacts();
+      this.contactsSubscribed = true;
+    } catch (error) {
+      this.logger.warn("RoomPresence failed to subscribe agent_contacts channel, continuing without it", {
+        error
+      });
+    }
+  }
+  async stopBody() {
+    this.abortEventLoop();
+    await this.eventTask?.catch(() => void 0);
+    this.eventTask = null;
+    this.eventController = null;
+    if (this.contactsSubscribed) {
+      try {
+        await this.link.unsubscribeAgentContacts();
+      } catch (error) {
+        this.logger.warn("RoomPresence failed to unsubscribe agent_contacts channel", { error });
+      } finally {
+        this.contactsSubscribed = false;
+      }
+    }
+    const roomIds = this.roster.trackedRoomIds();
+    this.roster.clear();
+    this.lastSubscribeError.clear();
+    await Promise.all(
+      roomIds.map(async (roomId) => {
+        await this.unsubscribeRoom(roomId);
+        await this.onRoomLeft?.(roomId);
+      })
+    );
+  }
+  async consumeEvents(signal) {
+    while (!signal.aborted) {
+      const event = await this.link.nextEvent(signal);
+      if (!event) {
+        return;
+      }
+      switch (event.type) {
+        case "room_added":
+          await this.handleRoomAdded(event.roomId, event.payload);
+          break;
+        case "room_removed":
+        case "room_deleted":
+          await this.handleRoomRemoved(event.roomId);
+          break;
+        case "contact_request_received":
+        case "contact_request_updated":
+        case "contact_added":
+        case "contact_removed":
+          await this.onContactEvent?.(event);
+          break;
+        case "message_created":
+        case "participant_added":
+        case "participant_removed":
+          if (event.roomId && this.roster.roomMembership(event.roomId) === "admitted") {
+            await this.onRoomEvent?.(event.roomId, event);
+          }
+          break;
+        default:
+          assertNever2(event);
+      }
+    }
+  }
+  async handleRoomAdded(roomId, payload) {
+    if (!roomId) {
       return;
     }
-    throw error;
+    if (this.roomFilter && !this.roomFilter(payload)) {
+      return;
+    }
+    await this.admitRoom(roomId, payload);
+  }
+  async handleRoomRemoved(roomId) {
+    if (!roomId) {
+      return;
+    }
+    await this.unsubscribeRoom(roomId);
+    this.lastSubscribeError.delete(roomId);
+    if (!this.roster.recordRoomRemoved(roomId)) {
+      this.logger.debug("RoomPresence ignoring removal for untracked room", { roomId });
+      return;
+    }
+    await this.onRoomLeft?.(roomId);
+  }
+  async unsubscribeRoom(roomId) {
+    try {
+      await this.link.unsubscribeRoom(roomId);
+    } catch (error) {
+      this.logger.warn("RoomPresence failed to unsubscribe room", { roomId, error });
+    }
   }
+  async subscribeExistingRooms() {
+    await hydrateExistingRooms({
+      link: this.link,
+      roomFilter: this.roomFilter,
+      requestOptions: DEFAULT_REQUEST_OPTIONS,
+      onRoom: async (roomId, payload) => {
+        await this.admitRoom(roomId, payload);
+      },
+      onError: (error) => {
+        this.logger.warn("RoomPresence failed to subscribe existing rooms", { error });
+      }
+    });
+  }
+};
+function assertNever2(value) {
+  throw new Error(`Unhandled platform event: ${JSON.stringify(value)}`);
 }
 
 // src/runtime/rooms/AgentRuntime.ts
 var AgentRuntime = class {
+  presence;
   link;
   agentId;
   onExecute;
@@ -2877,19 +3135,14 @@ var AgentRuntime = class {
   onParticipantAdded;
   onParticipantRemoved;
   onError;
-  roomFilter;
   contextFactory;
   sessionConfig;
-  autoSubscribeExistingRooms;
-  subscribedRooms = /* @__PURE__ */ new Set();
   contexts = /* @__PURE__ */ new Map();
   executions = /* @__PURE__ */ new Map();
   executionWatchers = /* @__PURE__ */ new Map();
   logger;
   running = false;
   stopping = false;
-  stopController = new AbortController();
-  consumeTask = null;
   fatalError = null;
   constructor(options) {
     this.link = options.link;
@@ -2903,7 +3156,6 @@ var AgentRuntime = class {
     this.onContactEvent = options.onContactEvent;
     this.onParticipantAdded = options.onParticipantAdded;
     this.onParticipantRemoved = options.onParticipantRemoved;
-    this.roomFilter = options.roomFilter;
     this.contextFactory = options.contextFactory;
     this.sessionConfig = {
       enableContextCache: options.sessionConfig?.enableContextCache ?? true,
@@ -2912,7 +3164,48 @@ var AgentRuntime = class {
       maxMessageRetries: options.sessionConfig?.maxMessageRetries ?? 1,
       enableContextHydration: options.sessionConfig?.enableContextHydration ?? true
     };
-    this.autoSubscribeExistingRooms = options.agentConfig?.autoSubscribeExistingRooms ?? false;
+    this.presence = new RoomPresence({
+      link: this.link,
+      roomFilter: options.roomFilter,
+      autoSubscribeExistingRooms: options.agentConfig?.autoSubscribeExistingRooms ?? false,
+      logger: this.logger
+    });
+    this.presence.onRoomJoined = async (roomId, payload) => {
+      this.getOrCreateExecution(roomId);
+      await this.onRoomJoined?.(roomId, payload);
+    };
+    this.presence.onRoomLeft = async (roomId) => {
+      await this.teardownExecution(roomId);
+      await this.onRoomLeft?.(roomId);
+    };
+    this.presence.onRoomEvent = async (roomId, event) => {
+      switch (event.type) {
+        case "participant_added": {
+          const context = this.getOrCreateContext(roomId);
+          const participant = {
+            id: event.payload.id,
+            name: event.payload.name,
+            type: event.payload.type,
+            handle: event.payload.handle
+          };
+          context.addParticipant(participant);
+          await this.onParticipantAdded?.(roomId, participant);
+          return;
+        }
+        case "participant_removed": {
+          const context = this.getOrCreateContext(roomId);
+          context.removeParticipant(event.payload.id);
+          await this.onParticipantRemoved?.(roomId, event.payload.id);
+          return;
+        }
+        case "message_created":
+          await this.getOrCreateExecution(roomId).enqueue(event);
+          return;
+        default:
+          assertNever3(event);
+      }
+    };
+    this.presence.onContactEvent = this.onContactEvent ?? null;
   }
   async start() {
     if (this.running) {
@@ -2921,45 +3214,17 @@ var AgentRuntime = class {
     this.running = true;
     this.stopping = false;
     this.fatalError = null;
-    if (!this.stopController.signal.aborted) {
-      this.stopController.abort();
-    }
-    this.stopController = new AbortController();
     try {
-      await this.link.connect();
+      await this.presence.start();
     } catch (error) {
       await this.handleStartFailure();
       throw error;
     }
-    try {
-      await this.link.subscribeAgentRooms();
-    } catch {
-      this.logger.warn("AgentRuntime failed to subscribe agent_rooms channel, continuing without it");
-    }
-    try {
-      await this.subscribeExistingRooms();
-    } catch (error) {
-      await this.handleStartFailure();
-      throw error;
-    }
-    this.consumeTask = this.consumeLoop(this.stopController.signal);
-    if (!this.link.capabilities.contacts) {
-      return;
-    }
-    try {
-      await this.link.subscribeAgentContacts();
-    } catch {
-      this.logger.warn("AgentRuntime failed to subscribe agent_contacts channel, continuing without it");
-    }
+    void this.presence.waitUntilStopped().catch((error) => this.failRuntime(error, syntheticRuntimeFailureEvent(this.agentId)));
   }
   async handleStartFailure() {
     this.running = false;
     this.stopping = false;
-    this.stopController.abort();
-    if (this.consumeTask) {
-      await this.consumeTask;
-      this.consumeTask = null;
-    }
     await this.link.disconnect();
   }
   async stop(timeoutMs) {
@@ -2968,34 +3233,25 @@ var AgentRuntime = class {
     }
     this.stopping = true;
     this.running = false;
-    this.stopController.abort();
-    if (this.consumeTask) {
-      await this.consumeTask;
-      this.consumeTask = null;
-    }
-    const deadline = timeoutMs === void 0 ? void 0 : Date.now() + timeoutMs;
+    this.presence.abortEventLoop();
+    await this.presence.waitUntilStopped().catch(() => void 0);
     let graceful = true;
-    for (const execution of this.executions.values()) {
-      const remaining = deadline === void 0 ? void 0 : Math.max(0, deadline - Date.now());
-      const stopped = await execution.stop(remaining);
-      if (!stopped) {
-        graceful = false;
-      }
-    }
-    for (const roomId of [...this.subscribedRooms]) {
-      const remaining = deadline === void 0 ? void 0 : Math.max(0, deadline - Date.now());
-      await this.leaveTrackedRoom(roomId, remaining);
-    }
+    await Promise.all(
+      [...this.executions].map(async ([roomId, execution]) => {
+        const stopped = await execution.stop(timeoutMs);
+        if (!stopped) {
+          graceful = false;
+        }
+        this.executions.delete(roomId);
+      })
+    );
+    await this.presence.stop();
     for (const roomId of [...this.contexts.keys()]) {
       await this.onSessionCleanup(roomId);
     }
-    this.subscribedRooms.clear();
     this.contexts.clear();
     this.executions.clear();
     this.executionWatchers.clear();
-    if (this.link.capabilities.contacts) {
-      await this.link.unsubscribeAgentContacts();
-    }
     await this.link.disconnect();
     if (this.fatalError) {
       throw this.fatalError instanceof Error ? this.fatalError : new Error(String(this.fatalError));
@@ -3006,11 +3262,7 @@ var AgentRuntime = class {
     return this.contexts.get(roomId);
   }
   async waitUntilStopped() {
-    if (this.consumeTask) {
-      await this.consumeTask;
-    } else {
-      await this.link.runForever(this.stopController.signal);
-    }
+    await this.presence.waitUntilStopped().catch(() => void 0);
     if (this.fatalError) {
       throw this.fatalError instanceof Error ? this.fatalError : new Error(String(this.fatalError));
     }
@@ -3018,97 +3270,19 @@ var AgentRuntime = class {
   getContexts() {
     return [...this.contexts.values()];
   }
-  async consumeLoop(signal) {
-    while (!signal.aborted) {
-      let event;
-      try {
-        event = await this.link.nextEvent(signal);
-      } catch (error) {
-        await this.failRuntime(error, syntheticRuntimeFailureEvent(this.agentId));
-        return;
-      }
-      if (!event) {
-        return;
-      }
-      try {
-        await this.handleEvent(event);
-      } catch (error) {
-        await this.failRuntime(error, event);
-        return;
-      }
-    }
-  }
-  async handleEvent(event) {
-    switch (event.type) {
-      case "room_added":
-        await trackRoomJoin({
-          link: this.link,
-          roomId: event.roomId,
-          payload: event.payload,
-          trackedRooms: this.subscribedRooms,
-          roomFilter: this.roomFilter,
-          onJoined: async (roomId) => {
-            this.getOrCreateExecution(roomId);
-            await this.onRoomJoined?.(roomId, event.payload);
-          }
-        });
-        return;
-      case "room_removed":
-      case "room_deleted":
-        if (event.roomId) {
-          await this.onRoomLeft?.(event.roomId);
-          await this.leaveTrackedRoom(event.roomId);
-        }
-        return;
-      case "participant_added":
-        if (event.roomId) {
-          const context = this.getOrCreateContext(event.roomId);
-          const participant = {
-            id: event.payload.id,
-            name: event.payload.name,
-            type: event.payload.type,
-            handle: event.payload.handle
-          };
-          context.addParticipant(participant);
-          await this.onParticipantAdded?.(event.roomId, participant);
-        }
-        return;
-      case "participant_removed":
-        if (event.roomId) {
-          const context = this.getOrCreateContext(event.roomId);
-          context.removeParticipant(event.payload.id);
-          await this.onParticipantRemoved?.(event.roomId, event.payload.id);
-        }
-        return;
-      case "contact_request_received":
-      case "contact_request_updated":
-      case "contact_added":
-      case "contact_removed":
-        await this.onContactEvent?.(event);
-        return;
-      case "message_created":
-        if (!event.roomId) {
-          return;
-        }
-        await this.getOrCreateExecution(event.roomId).enqueue(event);
-        return;
-    }
-    return assertNever2(event);
-  }
   async enqueueEvent(roomId, event) {
     await this.getOrCreateExecution(roomId).enqueue(event);
   }
   async bootstrapRoomMessage(roomId, message) {
-    await this.link.subscribeRoom(roomId);
-    this.subscribedRooms.add(roomId);
+    await this.presence.admitRoomOrThrow(roomId);
     await this.getOrCreateExecution(roomId).bootstrapMessage(message);
   }
   async resetRoomSession(roomId, timeoutMs) {
+    return this.teardownExecution(roomId, timeoutMs);
+  }
+  async teardownExecution(roomId, timeoutMs) {
     const execution = this.executions.get(roomId);
-    let graceful = true;
-    if (execution) {
-      graceful = await execution.stop(timeoutMs);
-    }
+    const graceful = execution ? await execution.stop(timeoutMs) : true;
     this.executions.delete(roomId);
     this.contexts.delete(roomId);
     await this.onSessionCleanup(roomId);
@@ -3164,44 +3338,13 @@ var AgentRuntime = class {
       maxMessageRetries: this.sessionConfig.maxMessageRetries,
       enableContextCache: this.sessionConfig.enableContextCache,
       contextCacheTtlSeconds: this.sessionConfig.contextCacheTtlSeconds,
-      enableContextHydration: this.sessionConfig.enableContextHydration
+      enableContextHydration: this.sessionConfig.enableContextHydration,
+      logger: this.logger
     };
     const context = this.contextFactory ? this.contextFactory(roomId, defaults) : new ExecutionContext(defaults);
     this.contexts.set(roomId, context);
     return context;
   }
-  async subscribeExistingRooms() {
-    if (!this.autoSubscribeExistingRooms) {
-      return;
-    }
-    await hydrateTrackedRooms({
-      link: this.link,
-      trackedRooms: this.subscribedRooms,
-      roomFilter: this.roomFilter,
-      onJoined: async (roomId, payload) => {
-        this.getOrCreateExecution(roomId);
-        await this.onRoomJoined?.(roomId, payload);
-      },
-      onError: async (error) => {
-        this.logger.warn("AgentRuntime failed to subscribe existing rooms", {
-          error
-        });
-      }
-    });
-  }
-  async leaveTrackedRoom(roomId, timeoutMs) {
-    await trackRoomLeave({
-      link: this.link,
-      roomId,
-      trackedRooms: this.subscribedRooms,
-      onLeft: async (leftRoomId) => {
-        await this.executions.get(leftRoomId)?.stop(timeoutMs);
-        this.contexts.delete(leftRoomId);
-        this.executions.delete(leftRoomId);
-        await this.onSessionCleanup(leftRoomId);
-      }
-    });
-  }
   async failRuntime(error, event) {
     if (!this.fatalError) {
       this.fatalError = error;
@@ -3213,9 +3356,7 @@ var AgentRuntime = class {
       });
       this.notifyOnError(error, event);
     }
-    if (!this.stopController.signal.aborted) {
-      this.stopController.abort();
-    }
+    this.presence.abortEventLoop();
   }
   notifyOnError(error, event) {
     if (!this.onError) {
@@ -3232,6 +3373,9 @@ var AgentRuntime = class {
     }
   }
 };
+function assertNever3(value) {
+  throw new Error(`Unhandled room event: ${JSON.stringify(value)}`);
+}
 function syntheticRuntimeFailureEvent(agentId) {
   return {
     type: "message_created",
@@ -3249,9 +3393,6 @@ function syntheticRuntimeFailureEvent(agentId) {
     }
   };
 }
-function assertNever2(value) {
-  throw new Error(`Unhandled platform event: ${JSON.stringify(value)}`);
-}
 
 // src/client/rest/pagination.ts
 var DEFAULT_PAGE_SIZE = 100;
@@ -5293,6 +5434,9 @@ var PlatformRuntime = class {
     this.stopping = false;
     return graceful;
   }
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
   async runForever() {
     if (!this.runtime) {
       throw new RuntimeStateError("Runtime not started");
@@ -5343,129 +5487,8 @@ var PlatformRuntime = class {
   }
 };
 
-// src/runtime/rooms/RoomPresence.ts
-var RoomPresence = class {
-  rooms = /* @__PURE__ */ new Set();
-  onRoomJoined = null;
-  onRoomLeft = null;
-  onRoomEvent = null;
-  onContactEvent = null;
-  link;
-  roomFilter;
-  autoSubscribeExistingRooms;
-  logger;
-  eventController = null;
-  eventTask = null;
-  contactsSubscribed = false;
-  constructor(options) {
-    this.link = options.link;
-    this.roomFilter = options.roomFilter;
-    this.autoSubscribeExistingRooms = options.autoSubscribeExistingRooms ?? true;
-    this.logger = options.logger ?? new NoopLogger();
-  }
-  async start() {
-    if (this.eventTask) {
-      return;
-    }
-    if (!this.link.isConnected()) {
-      await this.link.connect();
-    }
-    try {
-      await this.link.subscribeAgentRooms();
-    } catch {
-    }
-    if (this.autoSubscribeExistingRooms) {
-      await this.subscribeExistingRooms();
-    }
-    if (this.link.capabilities.contacts) {
-      await this.link.subscribeAgentContacts();
-      this.contactsSubscribed = true;
-    }
-    this.eventController = new AbortController();
-    this.eventTask = this.consumeEvents(this.eventController.signal);
-  }
-  async stop() {
-    this.eventController?.abort();
-    await this.eventTask;
-    this.eventTask = null;
-    this.eventController = null;
-    if (this.contactsSubscribed) {
-      await this.link.unsubscribeAgentContacts();
-      this.contactsSubscribed = false;
-    }
-    for (const roomId of [...this.rooms]) {
-      await trackRoomLeave({
-        link: this.link,
-        roomId,
-        trackedRooms: this.rooms,
-        onLeft: this.onRoomLeft ?? void 0
-      });
-    }
-  }
-  async consumeEvents(signal) {
-    while (!signal.aborted) {
-      const event = await this.link.nextEvent(signal);
-      if (!event) {
-        return;
-      }
-      switch (event.type) {
-        case "room_added":
-          await this.handleRoomAdded(event.roomId, event.payload);
-          break;
-        case "room_removed":
-        case "room_deleted":
-          await this.handleRoomRemoved(event.roomId);
-          break;
-        case "contact_request_received":
-        case "contact_request_updated":
-        case "contact_added":
-        case "contact_removed":
-          await this.onContactEvent?.(event);
-          break;
-        default:
-          if (event.roomId && this.rooms.has(event.roomId)) {
-            await this.onRoomEvent?.(event.roomId, event);
-          }
-          break;
-      }
-    }
-  }
-  async handleRoomAdded(roomId, payload) {
-    await trackRoomJoin({
-      link: this.link,
-      roomId,
-      payload,
-      trackedRooms: this.rooms,
-      roomFilter: this.roomFilter,
-      onJoined: this.onRoomJoined ?? void 0
-    });
-  }
-  async handleRoomRemoved(roomId) {
-    await trackRoomLeave({
-      link: this.link,
-      roomId,
-      trackedRooms: this.rooms,
-      onLeft: this.onRoomLeft ?? void 0
-    });
-  }
-  async subscribeExistingRooms() {
-    await hydrateTrackedRooms({
-      link: this.link,
-      trackedRooms: this.rooms,
-      requestOptions: DEFAULT_REQUEST_OPTIONS,
-      roomFilter: this.roomFilter,
-      onJoined: this.onRoomJoined ?? void 0,
-      onError: async (error) => {
-        this.logger.warn("RoomPresence failed to subscribe existing rooms", {
-          error
-        });
-      }
-    });
-  }
-};
-
 // src/runtime/index.ts
-var import_band_sdk_core3 = require("@band-ai/band-sdk-core");
+var import_band_sdk_core4 = require("@band-ai/band-sdk-core");
 
 // src/runtime/prompts/base.ts
 var ENVIRONMENT_SECTION = `
@@ -5719,6 +5742,7 @@ async function runWithGracefulShutdown(agent, options) {
   PlatformRuntime,
   RetryTracker,
   RoomPresence,
+  RoomRoster,
   SYNTHETIC_CONTACT_EVENTS_SENDER_ID,
   SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
   SYNTHETIC_SENDER_TYPE,
@@ -5732,6 +5756,7 @@ async function runWithGracefulShutdown(agent, options) {
   getToolDescription,
   isChatEventType,
   mcpToolNames,
+  mentionSubjectsFromMetadata,
   renderSystemPrompt,
   replaceUuidMentions,
   runWithGracefulShutdown