@band-ai/sdk 0.1.2

package/dist/chunk-6AJA2OPC.js

@@ -0,0 +1,3682 @@
+import {
+  HistoryProvider,
+  SYNTHETIC_CONTACT_EVENTS_SENDER_ID,
+  SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
+  SYNTHETIC_SENDER_TYPE,
+  buildParticipantsMessage
+} from "./chunk-INA6YZTZ.js";
+import {
+  CHAT_EVENT_TYPES,
+  CHAT_TOOL_NAMES,
+  MEMORY_TOOL_NAMES,
+  TOOL_MODELS,
+  assertChatEventType,
+  getToolDescription
+} from "./chunk-GVEQ3RAH.js";
+import {
+  DEFAULT_REQUEST_OPTIONS,
+  FernRestAdapter,
+  fetchPaginated
+} from "./chunk-SG4WLD2H.js";
+import {
+  DEFAULT_AGENT_TOOLS_CAPABILITIES,
+  createToolExecutorError,
+  isToolExecutorError
+} from "./chunk-3BKAC4OZ.js";
+import {
+  NoopLogger
+} from "./chunk-OD2G5LFQ.js";
+import {
+  RuntimeStateError,
+  TransportError,
+  UnsupportedFeatureError,
+  ValidationError
+} from "./chunk-YR3BOQNW.js";
+
+// src/contracts/capabilities.ts
+var CAPABILITY_LABELS = {
+  peers: "Peer lookup",
+  contacts: "Contacts",
+  memory: "Memory"
+};
+function assertCapability(capabilities, capability, label = CAPABILITY_LABELS[capability]) {
+  if (!capabilities[capability]) {
+    throw new UnsupportedFeatureError(`${label} is disabled by runtime capabilities`);
+  }
+}
+
+// src/platform/streaming/payloadSchemas.ts
+import { z } from "zod";
+var mentionSchema = z.object({
+  id: z.string(),
+  handle: z.string().nullish(),
+  name: z.string().nullish(),
+  username: z.string().nullish()
+}).passthrough();
+var messageMetadataSchema = z.object({
+  mentions: z.array(mentionSchema).nullish()
+}).passthrough();
+var messageCreatedPayloadSchema = z.object({
+  id: z.string(),
+  content: z.string(),
+  message_type: z.string(),
+  metadata: messageMetadataSchema.nullish(),
+  sender_id: z.string(),
+  sender_type: z.string(),
+  sender_name: z.string().nullish(),
+  chat_room_id: z.string().nullish(),
+  inserted_at: z.string(),
+  updated_at: z.string()
+}).passthrough();
+var roomOwnerSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string()
+}).passthrough();
+var roomAddedPayloadSchema = z.object({
+  id: z.string(),
+  title: z.string().nullish(),
+  task_id: z.string().nullish(),
+  inserted_at: z.string().nullish(),
+  updated_at: z.string().nullish(),
+  owner: roomOwnerSchema.nullish(),
+  status: z.string().nullish(),
+  type: z.string().nullish(),
+  created_at: z.string().nullish(),
+  participant_role: z.string().nullish()
+}).passthrough();
+var roomRemovedPayloadSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  type: z.string(),
+  title: z.string(),
+  removed_at: z.string()
+}).passthrough();
+var participantAddedPayloadSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  handle: z.string().nullish()
+}).passthrough();
+var participantRemovedPayloadSchema = z.object({
+  id: z.string()
+}).passthrough();
+var roomDeletedPayloadSchema = z.object({
+  id: z.string()
+}).passthrough();
+var contactRequestReceivedPayloadSchema = z.object({
+  id: z.string(),
+  from_handle: z.string(),
+  from_name: z.string(),
+  message: z.string().nullish(),
+  status: z.string(),
+  inserted_at: z.string()
+}).passthrough();
+var contactRequestUpdatedPayloadSchema = z.object({
+  id: z.string(),
+  status: z.string()
+}).passthrough();
+var contactAddedPayloadSchema = z.object({
+  id: z.string(),
+  handle: z.string(),
+  name: z.string(),
+  type: z.string(),
+  description: z.string().nullish(),
+  is_external: z.boolean().nullish(),
+  inserted_at: z.string()
+}).passthrough();
+var contactRemovedPayloadSchema = z.object({
+  id: z.string()
+}).passthrough();
+var payloadSchemas = {
+  message_created: messageCreatedPayloadSchema,
+  room_added: roomAddedPayloadSchema,
+  room_removed: roomRemovedPayloadSchema,
+  participant_added: participantAddedPayloadSchema,
+  participant_removed: participantRemovedPayloadSchema,
+  room_deleted: roomDeletedPayloadSchema,
+  contact_request_received: contactRequestReceivedPayloadSchema,
+  contact_request_updated: contactRequestUpdatedPayloadSchema,
+  contact_added: contactAddedPayloadSchema,
+  contact_removed: contactRemovedPayloadSchema
+};
+
+// src/platform/streaming/PhoenixChannelsTransport.ts
+import { Socket } from "phoenix";
+import { WebSocket as NodeWebSocket } from "ws";
+var PhoenixChannelsTransport = class {
+  socket;
+  channels = /* @__PURE__ */ new Map();
+  channelRefs = /* @__PURE__ */ new Map();
+  pendingJoins = /* @__PURE__ */ new Map();
+  logger;
+  onHandlerError;
+  connected = false;
+  connectPromise = null;
+  connectResolve = null;
+  constructor(options) {
+    this.logger = options.logger ?? new NoopLogger();
+    let wsUrl = options.wsUrl;
+    if (wsUrl.endsWith("/websocket")) {
+      wsUrl = wsUrl.slice(0, -"/websocket".length);
+    }
+    this.socket = new Socket(wsUrl, {
+      params: {
+        api_key: options.apiKey,
+        agent_id: options.agentId
+      },
+      heartbeatIntervalMs: options.heartbeatIntervalMs,
+      reconnectAfterMs: options.reconnectAfterMs ?? ((tries) => [1e3, 2e3, 5e3, 1e4, 3e4][tries - 1] ?? 3e4),
+      transport: options.websocketFactory ?? resolveWebSocketFactory()
+    });
+    this.socket.onOpen(() => {
+      this.connected = true;
+      this.connectResolve?.();
+      this.connectResolve = null;
+      this.logger.info("Phoenix socket opened", {
+        channels: getSocketChannelCount(this.socket)
+      });
+    });
+    this.socket.onClose((event) => {
+      this.connected = false;
+      if (getSocketChannelCount(this.socket) === 0) {
+        this.socket.disconnect();
+      }
+      this.logger.info("Phoenix socket closed", {
+        code: event?.code ?? null,
+        reason: event?.reason ?? null
+      });
+    });
+    this.socket.onError((event) => {
+      this.logger.warn("Phoenix socket error", { event });
+    });
+  }
+  async connect() {
+    if (this.connected) {
+      return;
+    }
+    if (!this.connectPromise) {
+      this.socket.connect();
+      const pending = this.waitForConnection();
+      this.connectPromise = pending;
+      void pending.then(
+        () => {
+          if (this.connectPromise === pending) {
+            this.connectPromise = null;
+          }
+        },
+        () => {
+          if (this.connectPromise === pending) {
+            this.connectPromise = null;
+          }
+        }
+      );
+    }
+    await this.connectPromise;
+  }
+  async disconnect() {
+    for (const topic of this.channels.keys()) {
+      await this.leave(topic);
+    }
+    this.socket.disconnect();
+    this.connected = false;
+  }
+  isConnected() {
+    return this.connected;
+  }
+  async join(topic, handlers) {
+    if (this.channels.has(topic)) {
+      return;
+    }
+    const pendingJoin = this.pendingJoins.get(topic);
+    if (pendingJoin) {
+      return pendingJoin;
+    }
+    const joinPromise = this.doJoin(topic, handlers).finally(() => {
+      this.pendingJoins.delete(topic);
+    });
+    this.pendingJoins.set(topic, joinPromise);
+    return joinPromise;
+  }
+  async doJoin(topic, handlers) {
+    const channel = this.socket.channel(topic, {});
+    const refs = [];
+    for (const [event, handler] of Object.entries(handlers)) {
+      const ref = channel.on(event, (payload) => {
+        Promise.resolve(handler(payload)).catch((error) => {
+          this.logger.error("Unhandled topic handler error", {
+            topic,
+            event,
+            error
+          });
+          this.onHandlerError?.(error);
+        });
+      });
+      refs.push([event, ref]);
+    }
+    try {
+      await new Promise((resolve, reject) => {
+        channel.join().receive("ok", () => resolve()).receive(
+          "error",
+          (error) => reject(new TransportError(`Failed to join topic ${topic}`, error))
+        ).receive("timeout", () => reject(new TransportError(`Timeout joining topic ${topic}`)));
+      });
+    } catch (error) {
+      for (const [event, ref] of refs) {
+        channel.off(event, ref);
+      }
+      channel.leave();
+      removeSocketChannel(this.socket, channel);
+      throw error;
+    }
+    this.channels.set(topic, channel);
+    this.channelRefs.set(topic, refs);
+    this.logger.debug("Joined topic", { topic });
+  }
+  async leave(topic) {
+    const channel = this.channels.get(topic);
+    if (!channel) {
+      return;
+    }
+    const refs = this.channelRefs.get(topic) ?? [];
+    for (const [event, ref] of refs) {
+      channel.off(event, ref);
+    }
+    this.channelRefs.delete(topic);
+    await new Promise((resolve, reject) => {
+      channel.leave().receive("ok", () => resolve()).receive(
+        "error",
+        (error) => reject(new TransportError(`Failed to leave topic ${topic}`, error))
+      ).receive("timeout", () => reject(new TransportError(`Timeout leaving topic ${topic}`)));
+    });
+    this.channels.delete(topic);
+    this.logger.debug("Left topic", { topic });
+  }
+  async runForever(signal) {
+    if (signal.aborted) {
+      return;
+    }
+    await new Promise((resolve) => {
+      signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+  }
+  async waitForConnection(timeoutMs = 1e4) {
+    if (this.connected) {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.connectResolve = null;
+        reject(new TransportError("Timed out waiting for Phoenix socket connection"));
+      }, timeoutMs);
+      this.connectResolve = () => {
+        clearTimeout(timeout);
+        resolve();
+      };
+    });
+  }
+};
+function resolveWebSocketFactory() {
+  if (typeof process !== "undefined" && process.versions?.node) {
+    return NodeWebSocket;
+  }
+  return WebSocket;
+}
+function removeSocketChannel(socket, channel) {
+  const candidate = socket;
+  candidate.remove?.(channel);
+}
+function getSocketChannelCount(socket) {
+  const candidate = socket;
+  if (!Array.isArray(candidate.channels)) {
+    return "unknown";
+  }
+  return candidate.channels.length;
+}
+
+// src/platform/ThenvoiLink.ts
+import { ThenvoiClient } from "@thenvoi/rest-client";
+var DEFAULT_WS_URL = "wss://app.thenvoi.com/api/v1/socket";
+function deriveDefaultRestUrl(wsUrl) {
+  const parsed = new URL(wsUrl);
+  const protocol = parsed.protocol === "ws:" ? "http:" : "https:";
+  return `${protocol}//${parsed.host}`;
+}
+function toPlatformMessage(roomId, message) {
+  return {
+    id: message.id,
+    roomId,
+    content: message.content,
+    senderId: message.sender_id,
+    senderType: message.sender_type,
+    senderName: message.sender_name ?? null,
+    messageType: message.message_type,
+    metadata: message.metadata ?? {},
+    createdAt: new Date(message.inserted_at)
+  };
+}
+var ThenvoiLink = class {
+  agentId;
+  apiKey;
+  wsUrl;
+  restUrl;
+  rest;
+  capabilities;
+  logger;
+  transport;
+  subscribedRooms = /* @__PURE__ */ new Set();
+  eventQueue = [];
+  waiters = [];
+  connected = false;
+  constructor(options) {
+    this.agentId = options.agentId;
+    this.apiKey = options.apiKey;
+    this.wsUrl = options.wsUrl ?? DEFAULT_WS_URL;
+    this.restUrl = options.restUrl ?? deriveDefaultRestUrl(this.wsUrl);
+    this.logger = options.logger ?? new NoopLogger();
+    this.capabilities = {
+      ...DEFAULT_AGENT_TOOLS_CAPABILITIES,
+      ...options.capabilities
+    };
+    const restApi = options.restApi ?? new FernRestAdapter(
+      new ThenvoiClient({
+        apiKey: this.apiKey,
+        baseUrl: this.restUrl
+      })
+    );
+    this.rest = restApi;
+    this.transport = options.transport ?? new PhoenixChannelsTransport({
+      wsUrl: this.wsUrl,
+      apiKey: this.apiKey,
+      agentId: this.agentId,
+      logger: this.logger
+    });
+  }
+  isConnected() {
+    return this.connected;
+  }
+  async connect() {
+    if (this.connected) {
+      return;
+    }
+    await this.transport.connect();
+    this.connected = true;
+  }
+  async disconnect() {
+    if (!this.connected) {
+      return;
+    }
+    await Promise.allSettled(
+      [...this.subscribedRooms].map((roomId) => this.unsubscribeRoom(roomId))
+    );
+    await this.transport.disconnect();
+    this.connected = false;
+  }
+  async runForever(signal) {
+    await this.transport.runForever(signal);
+  }
+  queueEvent(event) {
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter.resolve(event);
+      return;
+    }
+    this.eventQueue.push(event);
+  }
+  async subscribeAgentRooms() {
+    await this.transport.join(`agent_rooms:${this.agentId}`, {
+      room_added: (payload) => {
+        const roomId = typeof payload.id === "string" ? payload.id : "";
+        this.emit("room_added", payload, roomId);
+      },
+      room_removed: (payload) => {
+        const roomId = typeof payload.id === "string" ? payload.id : "";
+        this.emit("room_removed", payload, roomId);
+      }
+    });
+  }
+  async subscribeRoom(roomId) {
+    if (this.subscribedRooms.has(roomId)) {
+      return;
+    }
+    await this.transport.join(`chat_room:${roomId}`, {
+      message_created: (payload) => {
+        this.emit("message_created", payload, roomId);
+      }
+    });
+    await this.transport.join(`room_participants:${roomId}`, {
+      participant_added: (payload) => {
+        this.emit("participant_added", payload, roomId);
+      },
+      participant_removed: (payload) => {
+        this.emit("participant_removed", payload, roomId);
+      },
+      room_deleted: (payload) => {
+        this.emit("room_deleted", payload, roomId);
+      }
+    });
+    this.subscribedRooms.add(roomId);
+  }
+  async unsubscribeRoom(roomId) {
+    if (!this.subscribedRooms.has(roomId)) {
+      return;
+    }
+    await this.transport.leave(`chat_room:${roomId}`);
+    await this.transport.leave(`room_participants:${roomId}`);
+    this.subscribedRooms.delete(roomId);
+  }
+  async subscribeAgentContacts() {
+    assertCapability(this.capabilities, "contacts", "Contacts streaming");
+    await this.transport.join(`agent_contacts:${this.agentId}`, {
+      contact_request_received: (payload) => {
+        this.emit("contact_request_received", payload, null);
+      },
+      contact_request_updated: (payload) => {
+        this.emit("contact_request_updated", payload, null);
+      },
+      contact_added: (payload) => {
+        this.emit("contact_added", payload, null);
+      },
+      contact_removed: (payload) => {
+        this.emit("contact_removed", payload, null);
+      }
+    });
+  }
+  async unsubscribeAgentContacts() {
+    await this.transport.leave(`agent_contacts:${this.agentId}`);
+  }
+  async nextEvent(signal) {
+    if (signal?.aborted) {
+      return null;
+    }
+    const queued = this.eventQueue.shift();
+    if (queued) {
+      return queued;
+    }
+    return new Promise((resolve) => {
+      let settled = false;
+      const onAbort = () => {
+        const index = this.waiters.indexOf(waiter);
+        if (index >= 0) {
+          this.waiters.splice(index, 1);
+        }
+        finalize(null);
+      };
+      const cleanup = () => {
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const finalize = (event) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve(event);
+      };
+      const waiter = {
+        resolve: finalize,
+        cleanup
+      };
+      this.waiters.push(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const value = await this.nextEvent();
+        if (value === null) {
+          return { done: true, value: void 0 };
+        }
+        return { done: false, value };
+      }
+    };
+  }
+  async markProcessing(roomId, messageId, options) {
+    await this.markMessageStatus(
+      "markProcessing",
+      {
+        roomId,
+        messageId
+      },
+      () => this.rest.markMessageProcessing(roomId, messageId),
+      options
+    );
+  }
+  async markProcessed(roomId, messageId, options) {
+    await this.markMessageStatus(
+      "markProcessed",
+      {
+        roomId,
+        messageId
+      },
+      () => this.rest.markMessageProcessed(roomId, messageId),
+      options
+    );
+  }
+  async markFailed(roomId, messageId, error, options) {
+    const normalizedError = error.trim() || "Unknown error";
+    await this.markMessageStatus(
+      "markFailed",
+      {
+        roomId,
+        messageId,
+        error: normalizedError
+      },
+      () => this.rest.markMessageFailed(roomId, messageId, normalizedError),
+      options
+    );
+  }
+  async markMessageStatus(operation, context, mark, options) {
+    try {
+      await mark();
+    } catch (error) {
+      if (!options?.bestEffort) {
+        throw error;
+      }
+      this.logger.warn(`${operation} failed (best-effort)`, {
+        ...context,
+        error
+      });
+    }
+  }
+  async getNextMessage(roomId) {
+    if (!this.rest.getNextMessage) {
+      throw new UnsupportedFeatureError("Message queue access is not available in current REST adapter");
+    }
+    const message = await this.rest.getNextMessage({ chatId: roomId });
+    return message ? toPlatformMessage(roomId, message) : null;
+  }
+  async getStaleProcessingMessages(roomId) {
+    if (!this.rest.listMessages) {
+      return [];
+    }
+    const response = await this.rest.listMessages({
+      chatId: roomId,
+      page: 1,
+      pageSize: 50,
+      status: "processing"
+    });
+    return response.data.map((msg) => toPlatformMessage(roomId, msg));
+  }
+  async listChats(request, requestOptions) {
+    if (!this.rest.listChats) {
+      throw new UnsupportedFeatureError("Chat listing is not available in current REST adapter");
+    }
+    return this.rest.listChats(request, requestOptions);
+  }
+  async listAllChats(options, requestOptions) {
+    return fetchPaginated({
+      fetchPage: ({ page, pageSize }) => this.listChats({ page, pageSize }, requestOptions),
+      pageSize: options?.pageSize,
+      maxPages: options?.maxPages,
+      strategy: options?.strategy,
+      metadataValidation: options?.metadataValidation
+    });
+  }
+  emit(eventType, payload, roomId) {
+    const schema = payloadSchemas[eventType];
+    const parsed = schema.safeParse(payload);
+    if (!parsed.success) {
+      this.logger.warn(`Invalid ${eventType} payload, dropping event`, {
+        error: parsed.error.message,
+        roomId
+      });
+      return;
+    }
+    this.queueEvent({
+      type: eventType,
+      roomId,
+      payload: parsed.data,
+      raw: payload
+    });
+  }
+};
+
+// src/runtime/Execution.ts
+function toMessageEvent(message) {
+  const insertedAt = message.createdAt.toISOString();
+  return {
+    type: "message_created",
+    roomId: message.roomId,
+    payload: {
+      id: message.id,
+      content: message.content,
+      sender_id: message.senderId,
+      sender_type: message.senderType,
+      sender_name: message.senderName ?? null,
+      message_type: message.messageType,
+      metadata: message.metadata,
+      inserted_at: insertedAt,
+      updated_at: insertedAt
+    }
+  };
+}
+var Execution = class {
+  roomId;
+  link;
+  context;
+  retryTracker;
+  onExecute;
+  onFailure;
+  logger;
+  eventQueue = [];
+  waiters = [];
+  idleWaiters = /* @__PURE__ */ new Set();
+  drainedWsMessageIds = /* @__PURE__ */ new Set();
+  syncProcessedIds = /* @__PURE__ */ new Set();
+  processTask;
+  firstWsMessageId = null;
+  syncComplete = false;
+  running = true;
+  inFlight = 0;
+  constructor(options) {
+    this.roomId = options.roomId;
+    this.link = options.link;
+    this.context = options.context;
+    this.retryTracker = this.context.getRetryTracker();
+    this.onExecute = options.onExecute;
+    this.onFailure = options.onFailure;
+    this.logger = options.logger ?? new NoopLogger();
+    this.processTask = this.processLoop();
+  }
+  enqueue(event) {
+    if (event.type === "message_created" && !this.syncComplete && this.firstWsMessageId === null) {
+      this.firstWsMessageId = event.payload.id;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter(event);
+    } else {
+      this.eventQueue.push(event);
+    }
+    return Promise.resolve();
+  }
+  async bootstrapMessage(message) {
+    this.syncProcessedIds.add(message.id);
+    await this.executeSyncMessage(toMessageEvent(message), message.id);
+  }
+  isIdle() {
+    return this.syncComplete && this.inFlight === 0 && this.eventQueue.length === 0;
+  }
+  async waitForIdle(timeoutMs) {
+    if (this.isIdle()) {
+      return true;
+    }
+    return new Promise((resolve) => {
+      let settled = false;
+      let timeoutHandle = null;
+      const idleWaiter = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        this.idleWaiters.delete(idleWaiter);
+        if (timeoutHandle !== null) {
+          clearTimeout(timeoutHandle);
+        }
+        resolve(true);
+      };
+      this.idleWaiters.add(idleWaiter);
+      if (timeoutMs === void 0) {
+        return;
+      }
+      timeoutHandle = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        this.idleWaiters.delete(idleWaiter);
+        resolve(false);
+      }, timeoutMs);
+    });
+  }
+  async stop(timeoutMs) {
+    const graceful = await this.waitForIdle(timeoutMs);
+    this.running = false;
+    this.resolveEventWaiters(null);
+    if (graceful || timeoutMs === void 0) {
+      await this.processTask;
+    }
+    return graceful;
+  }
+  async waitUntilStopped() {
+    await this.processTask;
+  }
+  async processLoop() {
+    await this.recoverStaleProcessingMessages();
+    await this.synchronizeWithNext();
+    while (this.running) {
+      const event = await this.nextQueuedEvent();
+      if (!event) {
+        return;
+      }
+      if (event.type === "message_created" && this.drainedWsMessageIds.has(event.payload.id)) {
+        this.drainedWsMessageIds.delete(event.payload.id);
+        this.notifyIfIdle();
+        continue;
+      }
+      await this.executeEvent(event);
+    }
+  }
+  async recoverStaleProcessingMessages() {
+    let staleMessages;
+    try {
+      staleMessages = await this.link.getStaleProcessingMessages(this.roomId);
+    } catch {
+      this.logger.warn("Failed to fetch stale processing messages, skipping recovery", {
+        roomId: this.roomId
+      });
+      return;
+    }
+    if (staleMessages.length === 0) {
+      return;
+    }
+    this.logger.info("Recovering stale processing messages", {
+      roomId: this.roomId,
+      count: staleMessages.length
+    });
+    for (const message of staleMessages) {
+      if (!this.running) {
+        break;
+      }
+      if (this.retryTracker.isPermanentlyFailed(message.id)) {
+        this.logger.warn("Skipping permanently failed stale message", {
+          roomId: this.roomId,
+          messageId: message.id
+        });
+        continue;
+      }
+      await this.executeSyncMessage(toMessageEvent(message), message.id);
+      this.syncProcessedIds.add(message.id);
+    }
+  }
+  async synchronizeWithNext() {
+    while (this.running) {
+      const nextMessage = await this.link.getNextMessage(this.roomId);
+      if (!nextMessage) {
+        break;
+      }
+      if (this.syncProcessedIds.has(nextMessage.id)) {
+        const isSyncPoint2 = this.firstWsMessageId !== null && nextMessage.id === this.firstWsMessageId;
+        if (isSyncPoint2) {
+          this.drainedWsMessageIds.add(nextMessage.id);
+          this.firstWsMessageId = null;
+          break;
+        }
+        continue;
+      }
+      if (this.retryTracker.isPermanentlyFailed(nextMessage.id)) {
+        this.logger.warn("Skipping permanently failed message during sync", {
+          roomId: this.roomId,
+          messageId: nextMessage.id
+        });
+        await this.markMessageFailed(nextMessage.id, "Message permanently failed after max retries");
+        const isSyncPoint2 = this.firstWsMessageId !== null && nextMessage.id === this.firstWsMessageId;
+        if (isSyncPoint2) {
+          this.drainedWsMessageIds.add(nextMessage.id);
+          this.firstWsMessageId = null;
+          break;
+        }
+        continue;
+      }
+      const isSyncPoint = this.firstWsMessageId !== null && nextMessage.id === this.firstWsMessageId;
+      await this.executeSyncMessage(toMessageEvent(nextMessage), nextMessage.id);
+      this.syncProcessedIds.add(nextMessage.id);
+      if (isSyncPoint) {
+        this.drainedWsMessageIds.add(nextMessage.id);
+        this.firstWsMessageId = null;
+        break;
+      }
+    }
+    this.syncProcessedIds.clear();
+    this.syncComplete = true;
+    this.notifyIfIdle();
+  }
+  async executeSyncMessage(event, messageId) {
+    const [, exceeded] = this.retryTracker.recordAttempt(messageId);
+    if (exceeded) {
+      this.logger.error("Message exceeded max retries during sync, marking permanently failed", {
+        roomId: this.roomId,
+        messageId,
+        maxRetries: this.retryTracker.maxRetries
+      });
+      await this.markMessageFailed(messageId, "Message permanently failed after max retries");
+      return;
+    }
+    this.inFlight += 1;
+    this.context.setState("processing");
+    try {
+      await this.onExecute(this.context, event);
+      this.retryTracker.markSuccess(messageId);
+    } catch (error) {
+      const label = error instanceof Error ? error.message : String(error);
+      this.logger.error("Sync message execution failed", {
+        roomId: this.roomId,
+        messageId,
+        error: label
+      });
+    } finally {
+      this.inFlight -= 1;
+      this.context.setState("idle");
+    }
+  }
+  async executeEvent(event) {
+    this.inFlight += 1;
+    this.context.setState("processing");
+    try {
+      await this.onExecute(this.context, event);
+    } catch (error) {
+      if (this.onFailure) {
+        await this.onFailure(error, event);
+      } else {
+        this.logger.error("Execution queue task failed", {
+          roomId: this.roomId,
+          eventType: event.type,
+          error
+        });
+      }
+      this.running = false;
+      this.eventQueue.splice(0, this.eventQueue.length);
+      this.resolveEventWaiters(null);
+      throw error;
+    } finally {
+      this.inFlight -= 1;
+      this.context.setState("idle");
+      this.notifyIfIdle();
+    }
+  }
+  async nextQueuedEvent() {
+    const queued = this.eventQueue.shift();
+    if (queued) {
+      return queued;
+    }
+    if (!this.running) {
+      return null;
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+  notifyIfIdle() {
+    if (!this.isIdle()) {
+      return;
+    }
+    const waiters = [...this.idleWaiters];
+    this.idleWaiters.clear();
+    for (const waiter of waiters) {
+      waiter();
+    }
+  }
+  resolveEventWaiters(event) {
+    const waiters = this.waiters.splice(0, this.waiters.length);
+    for (const waiter of waiters) {
+      waiter(event);
+    }
+  }
+  async markMessageFailed(messageId, error) {
+    try {
+      await this.link.markFailed(this.roomId, messageId, error, { bestEffort: true });
+    } catch {
+      this.logger.warn("Failed to mark message as failed on server", {
+        roomId: this.roomId,
+        messageId
+      });
+    }
+  }
+};
+
+// src/runtime/tools/AgentTools.ts
+var REQUIRED_ADAPTER_TOOL_METHODS = [
+  "sendMessage",
+  "sendEvent",
+  "addParticipant",
+  "removeParticipant",
+  "getParticipants",
+  "createChatroom",
+  "getToolSchemas",
+  "getAnthropicToolSchemas",
+  "getOpenAIToolSchemas",
+  "executeToolCall"
+];
+var OPTIONAL_ADAPTER_TOOL_METHODS = {
+  peers: ["lookupPeers"],
+  contacts: [
+    "listContacts",
+    "addContact",
+    "removeContact",
+    "listContactRequests",
+    "respondContactRequest"
+  ],
+  memory: [
+    "listMemories",
+    "storeMemory",
+    "getMemory",
+    "supersedeMemory",
+    "archiveMemory"
+  ]
+};
+var CONTACT_REQUEST_ACTIONS = /* @__PURE__ */ new Set([
+  "approve",
+  "reject",
+  "cancel"
+]);
+var MEMORY_SYSTEMS = /* @__PURE__ */ new Set([
+  "sensory",
+  "working",
+  "long_term"
+]);
+var MEMORY_TYPES = /* @__PURE__ */ new Set([
+  "iconic",
+  "echoic",
+  "haptic",
+  "episodic",
+  "semantic",
+  "procedural"
+]);
+var MEMORY_SEGMENTS = /* @__PURE__ */ new Set([
+  "user",
+  "agent",
+  "tool",
+  "guideline"
+]);
+var LIST_MEMORY_SCOPES = /* @__PURE__ */ new Set([
+  "subject",
+  "organization",
+  "all"
+]);
+var LIST_MEMORY_STATUSES = /* @__PURE__ */ new Set([
+  "active",
+  "superseded",
+  "archived",
+  "all"
+]);
+var MEMORY_SCOPES = /* @__PURE__ */ new Set([
+  "subject",
+  "organization"
+]);
+var AgentTools = class {
+  roomId;
+  capabilities;
+  rest;
+  participants;
+  adapterTools;
+  toolHandlers;
+  constructor(options) {
+    this.roomId = options.roomId;
+    this.rest = options.rest;
+    this.participants = options.participants ?? [];
+    this.capabilities = {
+      ...DEFAULT_AGENT_TOOLS_CAPABILITIES,
+      ...options.capabilities
+    };
+    this.toolHandlers = this.buildToolHandlers();
+    this.adapterTools = this.buildAdapterTools();
+  }
+  getAdapterTools() {
+    return this.adapterTools;
+  }
+  async sendMessage(content, mentions = []) {
+    if (mentions.length > 0 && typeof mentions[0] === "string" && this.participants.length === 0) {
+      await this.syncParticipants();
+    }
+    const resolvedMentions = this.resolveMentions(mentions);
+    return this.rest.createChatMessage(
+      this.roomId,
+      {
+        content,
+        mentions: resolvedMentions
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async sendEvent(content, messageType, metadata) {
+    assertChatEventType(messageType);
+    return this.rest.createChatEvent(
+      this.roomId,
+      {
+        content,
+        messageType,
+        metadata
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async createChatroom(taskId) {
+    const room = await this.rest.createChat(taskId, DEFAULT_REQUEST_OPTIONS);
+    return room.id;
+  }
+  async addParticipant(name, role = "member") {
+    const existing = await this.syncParticipants();
+    const alreadyInRoom = existing.find(
+      (participant) => String(participant.name ?? "").toLowerCase() === name.toLowerCase()
+    );
+    if (alreadyInRoom) {
+      return {
+        ...alreadyInRoom,
+        status: "already_in_room"
+      };
+    }
+    const peer = await this.lookupPeerByName(name);
+    if (!peer?.id) {
+      throw new UnsupportedFeatureError(
+        `Participant '${name}' not found. lookupPeers requires peer endpoint availability.`
+      );
+    }
+    await this.rest.addChatParticipant(
+      this.roomId,
+      {
+        participantId: String(peer.id),
+        role
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+    const participantRecord = {
+      id: String(peer.id),
+      name,
+      role,
+      type: String(peer.type ?? "Agent"),
+      handle: typeof peer.handle === "string" ? peer.handle : null
+    };
+    this.participants.push(participantRecord);
+    return {
+      ...participantRecord,
+      status: "added"
+    };
+  }
+  async removeParticipant(name) {
+    const participants = await this.syncParticipants();
+    const participant = participants.find(
+      (entry) => String(entry.name ?? "").toLowerCase() === name.toLowerCase()
+    );
+    if (!participant?.id) {
+      throw new ValidationError(`Participant '${name}' not found in room`);
+    }
+    await this.rest.removeChatParticipant(this.roomId, String(participant.id), DEFAULT_REQUEST_OPTIONS);
+    this.replaceParticipants(this.participants.filter((entry) => entry.id !== participant.id));
+    return {
+      id: participant.id,
+      name,
+      status: "removed"
+    };
+  }
+  async lookupPeers(page = 1, pageSize = 50) {
+    assertCapability(this.capabilities, "peers");
+    if (!this.rest.listPeers) {
+      throw new UnsupportedFeatureError(
+        "Peer listing is not available in current REST adapter"
+      );
+    }
+    return this.rest.listPeers(
+      {
+        page,
+        pageSize,
+        notInChat: this.roomId
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async getParticipants() {
+    return this.fetchParticipants();
+  }
+  async fetchParticipants() {
+    const participants = await this.rest.listChatParticipants(this.roomId, DEFAULT_REQUEST_OPTIONS);
+    return participants.map((participant) => ({
+      id: participant.id,
+      name: participant.name,
+      type: participant.type,
+      handle: participant.handle ?? null
+    }));
+  }
+  async syncParticipants() {
+    const participants = await this.fetchParticipants();
+    this.replaceParticipants(participants);
+    return [...this.participants];
+  }
+  async executeToolCall(toolName, arguments_) {
+    const validationError = validateToolArgs(toolName, arguments_);
+    if (validationError) {
+      return validationError;
+    }
+    const handler = this.toolHandlers[toolName];
+    if (!handler) {
+      return createToolExecutorError({
+        errorType: "ToolNotFoundError",
+        toolName,
+        message: `Tool '${toolName}' is not registered`,
+        legacyMessage: `Unknown tool: ${toolName}`
+      });
+    }
+    try {
+      return await handler(arguments_);
+    } catch (error) {
+      if (isToolExecutorError(error)) {
+        return error;
+      }
+      if (error instanceof ValidationError) {
+        return createToolExecutorError({
+          errorType: "ToolArgumentsValidationError",
+          toolName,
+          message: error.message,
+          legacyMessage: `Invalid arguments for ${toolName}: ${error.message}`
+        });
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      return createToolExecutorError({
+        errorType: "ToolExecutionError",
+        toolName,
+        message,
+        legacyMessage: `Error executing ${toolName}: ${message}`
+      });
+    }
+  }
+  getToolSchemas(format, options) {
+    const includeMemory = options?.includeMemory ?? false;
+    const tools = Object.entries(TOOL_MODELS).filter(([name]) => {
+      if (MEMORY_TOOL_NAMES.has(name)) {
+        return includeMemory && this.capabilities.memory;
+      }
+      if (!CHAT_TOOL_NAMES.has(name) && !this.capabilities.contacts) {
+        return false;
+      }
+      if (name === "thenvoi_lookup_peers" && !this.capabilities.peers) {
+        return false;
+      }
+      return true;
+    }).map(([name, model]) => {
+      if (format === "anthropic") {
+        return {
+          name,
+          description: getToolDescription(name),
+          input_schema: {
+            type: "object",
+            properties: model.properties,
+            required: model.required
+          }
+        };
+      }
+      return {
+        type: "function",
+        function: {
+          name,
+          description: getToolDescription(name),
+          parameters: {
+            type: "object",
+            properties: model.properties,
+            required: model.required
+          }
+        }
+      };
+    });
+    return tools;
+  }
+  getAnthropicToolSchemas(options) {
+    return this.getToolSchemas("anthropic", options);
+  }
+  getOpenAIToolSchemas(options) {
+    return this.getToolSchemas("openai", options);
+  }
+  async listContacts(request = {}) {
+    assertCapability(this.capabilities, "contacts");
+    if (!this.rest.listContacts) {
+      throw new UnsupportedFeatureError("Contact listing is not available in current REST adapter");
+    }
+    const page = request.page ?? 1;
+    const pageSize = request.pageSize ?? 50;
+    return this.rest.listContacts(
+      {
+        page,
+        pageSize
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async addContact(request) {
+    assertCapability(this.capabilities, "contacts");
+    if (!this.rest.addContact) {
+      throw new UnsupportedFeatureError("Contact creation is not available in current REST adapter");
+    }
+    const normalizedHandle = request.handle.trim();
+    if (normalizedHandle.length === 0) {
+      throw new ValidationError("handle is required");
+    }
+    return this.rest.addContact(
+      {
+        handle: normalizedHandle,
+        ...request.message ? { message: request.message } : {}
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async removeContact(request) {
+    assertCapability(this.capabilities, "contacts");
+    if (!this.rest.removeContact) {
+      throw new UnsupportedFeatureError("Contact removal is not available in current REST adapter");
+    }
+    if (request.target === "handle") {
+      const handle = request.handle.trim();
+      if (handle.length === 0) {
+        throw new ValidationError("handle is required");
+      }
+      return this.rest.removeContact(
+        {
+          target: "handle",
+          handle
+        },
+        DEFAULT_REQUEST_OPTIONS
+      );
+    }
+    const contactId = request.contactId.trim();
+    if (contactId.length === 0) {
+      throw new ValidationError("contactId is required");
+    }
+    return this.rest.removeContact(
+      {
+        target: "contactId",
+        contactId
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async listContactRequests(request = {}) {
+    assertCapability(this.capabilities, "contacts");
+    if (!this.rest.listContactRequests) {
+      throw new UnsupportedFeatureError("Contact request listing is not available in current REST adapter");
+    }
+    const page = request.page ?? 1;
+    const pageSize = request.pageSize ?? 50;
+    const sentStatus = request.sentStatus ?? "pending";
+    return this.rest.listContactRequests(
+      {
+        page,
+        pageSize,
+        sentStatus
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async respondContactRequest(request) {
+    assertCapability(this.capabilities, "contacts");
+    if (!this.rest.respondContactRequest) {
+      throw new UnsupportedFeatureError("Contact request responses are not available in current REST adapter");
+    }
+    if (request.target === "handle") {
+      const handle = request.handle.trim();
+      if (handle.length === 0) {
+        throw new ValidationError("handle is required");
+      }
+      return this.rest.respondContactRequest(
+        {
+          action: request.action,
+          target: "handle",
+          handle
+        },
+        DEFAULT_REQUEST_OPTIONS
+      );
+    }
+    const requestId = request.requestId.trim();
+    if (requestId.length === 0) {
+      throw new ValidationError("requestId is required");
+    }
+    return this.rest.respondContactRequest(
+      {
+        action: request.action,
+        target: "requestId",
+        requestId
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async listMemories(args = {}) {
+    assertCapability(this.capabilities, "memory");
+    if (!this.rest.listMemories) {
+      throw new UnsupportedFeatureError("Memory listing is not available in current REST adapter");
+    }
+    return this.rest.listMemories(args, DEFAULT_REQUEST_OPTIONS);
+  }
+  async storeMemory(args) {
+    assertCapability(this.capabilities, "memory");
+    if (!this.rest.storeMemory) {
+      throw new UnsupportedFeatureError("Memory creation is not available in current REST adapter");
+    }
+    return this.rest.storeMemory(args, DEFAULT_REQUEST_OPTIONS);
+  }
+  async getMemory(memoryId) {
+    assertCapability(this.capabilities, "memory");
+    if (!this.rest.getMemory) {
+      throw new UnsupportedFeatureError("Memory lookup is not available in current REST adapter");
+    }
+    const normalizedMemoryId = memoryId.trim();
+    if (normalizedMemoryId.length === 0) {
+      throw new ValidationError("memoryId is required");
+    }
+    return this.rest.getMemory(normalizedMemoryId, DEFAULT_REQUEST_OPTIONS);
+  }
+  async supersedeMemory(memoryId) {
+    assertCapability(this.capabilities, "memory");
+    if (!this.rest.supersedeMemory) {
+      throw new UnsupportedFeatureError("Memory supersede is not available in current REST adapter");
+    }
+    const normalizedMemoryId = memoryId.trim();
+    if (normalizedMemoryId.length === 0) {
+      throw new ValidationError("memoryId is required");
+    }
+    return this.rest.supersedeMemory(normalizedMemoryId, DEFAULT_REQUEST_OPTIONS);
+  }
+  async archiveMemory(memoryId) {
+    assertCapability(this.capabilities, "memory");
+    if (!this.rest.archiveMemory) {
+      throw new UnsupportedFeatureError("Memory archive is not available in current REST adapter");
+    }
+    const normalizedMemoryId = memoryId.trim();
+    if (normalizedMemoryId.length === 0) {
+      throw new ValidationError("memoryId is required");
+    }
+    return this.rest.archiveMemory(normalizedMemoryId, DEFAULT_REQUEST_OPTIONS);
+  }
+  resolveMentions(mentions) {
+    if (mentions.length === 0) {
+      return [];
+    }
+    if (typeof mentions[0] !== "string") {
+      return mentions.filter(
+        (entry) => typeof entry === "object" && entry !== null && "id" in entry
+      );
+    }
+    const stringMentions = mentions.filter((entry) => typeof entry === "string");
+    const participantsByHandle = /* @__PURE__ */ new Map();
+    const participantsById = /* @__PURE__ */ new Map();
+    const participantsByName = /* @__PURE__ */ new Map();
+    for (const participant of this.participants) {
+      const ref = {
+        id: String(participant.id),
+        handle: typeof participant.handle === "string" ? participant.handle : void 0
+      };
+      participantsById.set(ref.id, ref);
+      const handle = participant.handle;
+      if (typeof handle === "string") {
+        participantsByHandle.set(this.normalizeMentionHandle(handle), ref);
+      }
+      const name = participant.name;
+      if (typeof name === "string" && name.trim().length > 0) {
+        participantsByName.set(name.trim().toLowerCase(), ref);
+      }
+    }
+    return stringMentions.map((mention) => {
+      const byId = participantsById.get(mention);
+      if (byId) {
+        return byId;
+      }
+      const normalized = this.normalizeMentionHandle(mention);
+      const found = participantsByHandle.get(normalized);
+      if (found) {
+        return found;
+      }
+      const byName = participantsByName.get(mention.trim().toLowerCase());
+      if (byName) {
+        return byName;
+      }
+      throw new ValidationError(`Mention '${mention}' not found in participants`);
+    });
+  }
+  async lookupPeerByName(name) {
+    const target = name.trim().toLowerCase();
+    const pageSize = 100;
+    const maxPages = 25;
+    for (let page = 1; page <= maxPages; page += 1) {
+      const peers = await this.lookupPeers(page, pageSize);
+      const items = peers.data ?? [];
+      const match = items.find((peer) => String(peer.name ?? "").toLowerCase() === target);
+      if (match) {
+        return match;
+      }
+      const totalPages = peers.metadata?.totalPages;
+      if (typeof totalPages === "number" && totalPages > 0 && page >= totalPages) {
+        break;
+      }
+      if ((typeof totalPages !== "number" || totalPages <= 0) && items.length < pageSize) {
+        break;
+      }
+    }
+    return null;
+  }
+  normalizeMentionHandle(handle) {
+    return handle.trim().replace(/^@+/, "").toLowerCase();
+  }
+  replaceParticipants(participants) {
+    this.participants.splice(0, this.participants.length, ...participants);
+  }
+  buildAdapterTools() {
+    const tools = {
+      capabilities: this.capabilities
+    };
+    for (const methodName of REQUIRED_ADAPTER_TOOL_METHODS) {
+      tools[methodName] = this.bindAdapterToolMethod(methodName);
+    }
+    for (const [capabilityKey, methodNames] of Object.entries(OPTIONAL_ADAPTER_TOOL_METHODS)) {
+      if (!this.capabilities[capabilityKey]) {
+        continue;
+      }
+      for (const methodName of methodNames) {
+        tools[methodName] = this.bindAdapterToolMethod(methodName);
+      }
+    }
+    return Object.freeze(tools);
+  }
+  bindAdapterToolMethod(methodName) {
+    const method = this[methodName];
+    return method.bind(this);
+  }
+  buildToolHandlers() {
+    return {
+      ...this.buildMessagingToolHandlers(),
+      ...this.buildContactToolHandlers(),
+      ...this.buildMemoryToolHandlers()
+    };
+  }
+  buildMessagingToolHandlers() {
+    return {
+      thenvoi_send_message: async (arguments_) => this.sendMessage(
+        String(arguments_.content ?? ""),
+        this.normalizeMentionInput(arguments_.mentions)
+      ),
+      thenvoi_send_event: async (arguments_) => this.sendEvent(
+        String(arguments_.content ?? ""),
+        String(arguments_.message_type ?? "task"),
+        this.normalizeOptionalMetadata(arguments_.metadata)
+      ),
+      thenvoi_add_participant: async (arguments_) => this.addParticipant(String(arguments_.name ?? ""), String(arguments_.role ?? "member")),
+      thenvoi_remove_participant: async (arguments_) => this.removeParticipant(String(arguments_.name ?? "")),
+      thenvoi_lookup_peers: async (arguments_) => this.lookupPeers(
+        coercePositiveInt(arguments_.page, 1),
+        coercePositiveInt(arguments_.page_size, 50)
+      ),
+      thenvoi_get_participants: async () => this.getParticipants(),
+      thenvoi_create_chatroom: async (arguments_) => this.createChatroom(this.normalizeOptionalString(arguments_.task_id))
+    };
+  }
+  buildContactToolHandlers() {
+    return {
+      thenvoi_list_contacts: async (arguments_) => this.listContacts({
+        page: coercePositiveInt(arguments_.page, 1),
+        pageSize: coercePositiveInt(arguments_.page_size, 50)
+      }),
+      thenvoi_add_contact: async (arguments_) => this.addContact({
+        handle: String(arguments_.handle ?? ""),
+        ...typeof arguments_.message === "string" ? { message: arguments_.message } : {}
+      }),
+      thenvoi_remove_contact: async (arguments_) => this.removeContact(this.toRemoveContactArgs(arguments_)),
+      thenvoi_list_contact_requests: async (arguments_) => this.listContactRequests({
+        page: coercePositiveInt(arguments_.page, 1),
+        pageSize: coercePositiveInt(arguments_.page_size, 50),
+        sentStatus: String(arguments_.sent_status ?? "pending")
+      }),
+      thenvoi_respond_contact_request: async (arguments_) => this.respondContactRequest(this.toRespondContactRequestArgs(arguments_))
+    };
+  }
+  buildMemoryToolHandlers() {
+    return {
+      thenvoi_list_memories: async (arguments_) => this.listMemories(this.toListMemoriesArgs(arguments_)),
+      thenvoi_store_memory: async (arguments_) => this.storeMemory(this.toStoreMemoryArgs(arguments_)),
+      thenvoi_get_memory: async (arguments_) => this.getMemory(String(arguments_.memory_id ?? "")),
+      thenvoi_supersede_memory: async (arguments_) => this.supersedeMemory(String(arguments_.memory_id ?? "")),
+      thenvoi_archive_memory: async (arguments_) => this.archiveMemory(String(arguments_.memory_id ?? ""))
+    };
+  }
+  toRemoveContactArgs(arguments_) {
+    const handle = this.normalizeOptionalString(arguments_.handle);
+    const contactId = this.normalizeOptionalString(arguments_.contact_id);
+    if (handle && contactId || !handle && !contactId) {
+      throw new ValidationError("Provide exactly one of handle or contact_id");
+    }
+    if (handle) {
+      return {
+        target: "handle",
+        handle
+      };
+    }
+    return {
+      target: "contactId",
+      contactId
+    };
+  }
+  toRespondContactRequestArgs(arguments_) {
+    const actionValue = this.normalizeOptionalString(arguments_.action);
+    if (!actionValue || !isContactRequestAction(actionValue)) {
+      throw new ValidationError("action must be one of: approve, reject, cancel");
+    }
+    const handle = this.normalizeOptionalString(arguments_.handle);
+    const requestId = this.normalizeOptionalString(arguments_.request_id);
+    if (handle && requestId || !handle && !requestId) {
+      throw new ValidationError("Provide exactly one of handle or request_id");
+    }
+    if (handle) {
+      return {
+        action: actionValue,
+        target: "handle",
+        handle
+      };
+    }
+    return {
+      action: actionValue,
+      target: "requestId",
+      requestId
+    };
+  }
+  toListMemoriesArgs(arguments_) {
+    const pageSize = this.normalizeOptionalNumber(arguments_.page_size);
+    const scope = this.normalizeOptionalMemoryScope(arguments_.scope);
+    const system = this.normalizeOptionalMemorySystem(arguments_.system);
+    const type = this.normalizeOptionalMemoryType(arguments_.type);
+    const segment = this.normalizeOptionalMemorySegment(arguments_.segment);
+    const status = this.normalizeOptionalMemoryStatus(arguments_.status);
+    const subjectId = this.normalizeOptionalString(arguments_.subject_id);
+    const contentQuery = this.normalizeOptionalString(arguments_.content_query);
+    return {
+      ...subjectId ? { subject_id: subjectId } : {},
+      ...scope ? { scope } : {},
+      ...system ? { system } : {},
+      ...type ? { type } : {},
+      ...segment ? { segment } : {},
+      ...contentQuery ? { content_query: contentQuery } : {},
+      ...typeof pageSize === "number" ? { page_size: pageSize } : {},
+      ...status ? { status } : {}
+    };
+  }
+  toStoreMemoryArgs(arguments_) {
+    const content = this.normalizeRequiredString(arguments_.content, "content");
+    const thought = this.normalizeRequiredString(arguments_.thought, "thought");
+    const system = this.normalizeOptionalMemorySystem(arguments_.system);
+    const type = this.normalizeOptionalMemoryType(arguments_.type);
+    const segment = this.normalizeOptionalMemorySegment(arguments_.segment);
+    const scope = this.normalizeOptionalStoreMemoryScope(arguments_.scope);
+    const subjectId = this.normalizeOptionalString(arguments_.subject_id);
+    const metadata = this.normalizeOptionalMetadata(arguments_.metadata);
+    if (!system) {
+      throw new ValidationError("system must be one of: sensory, working, long_term");
+    }
+    if (!type) {
+      throw new ValidationError("type must be one of: iconic, echoic, haptic, episodic, semantic, procedural");
+    }
+    if (!segment) {
+      throw new ValidationError("segment must be one of: user, agent, tool, guideline");
+    }
+    return {
+      content,
+      thought,
+      system,
+      type,
+      segment,
+      ...scope ? { scope } : {},
+      ...subjectId ? { subject_id: subjectId } : {},
+      ...metadata ? { metadata } : {}
+    };
+  }
+  normalizeOptionalString(value) {
+    if (typeof value !== "string") {
+      return void 0;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : void 0;
+  }
+  normalizeRequiredString(value, fieldName) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      throw new ValidationError(`${fieldName} is required`);
+    }
+    return normalized;
+  }
+  normalizeOptionalNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "string") {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+    return void 0;
+  }
+  normalizeOptionalMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return void 0;
+    }
+    return value;
+  }
+  normalizeMentionInput(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+      return [];
+    }
+    if (typeof value[0] === "string") {
+      return value.filter((entry) => typeof entry === "string");
+    }
+    const mentions = [];
+    for (const entry of value) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        continue;
+      }
+      const mention = entry;
+      if (typeof mention.id !== "string") {
+        continue;
+      }
+      const normalized = { id: mention.id };
+      if (typeof mention.handle === "string") {
+        normalized.handle = mention.handle;
+      }
+      if (typeof mention.name === "string") {
+        normalized.name = mention.name;
+      }
+      if (typeof mention.username === "string") {
+        normalized.username = mention.username;
+      }
+      mentions.push(normalized);
+    }
+    return mentions;
+  }
+  normalizeOptionalMemoryScope(value) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      return void 0;
+    }
+    if (!isListMemoryScope(normalized)) {
+      throw new ValidationError("scope must be one of: subject, organization, all");
+    }
+    return normalized;
+  }
+  normalizeOptionalMemorySystem(value) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      return void 0;
+    }
+    if (!isMemorySystem(normalized)) {
+      throw new ValidationError("system must be one of: sensory, working, long_term");
+    }
+    return normalized;
+  }
+  normalizeOptionalMemoryType(value) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      return void 0;
+    }
+    if (!isMemoryType(normalized)) {
+      throw new ValidationError("type must be one of: iconic, echoic, haptic, episodic, semantic, procedural");
+    }
+    return normalized;
+  }
+  normalizeOptionalMemorySegment(value) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      return void 0;
+    }
+    if (!isMemorySegment(normalized)) {
+      throw new ValidationError("segment must be one of: user, agent, tool, guideline");
+    }
+    return normalized;
+  }
+  normalizeOptionalMemoryStatus(value) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      return void 0;
+    }
+    if (!isMemoryStatus(normalized)) {
+      throw new ValidationError("status must be one of: active, superseded, archived, all");
+    }
+    return normalized;
+  }
+  normalizeOptionalStoreMemoryScope(value) {
+    const normalized = this.normalizeOptionalString(value);
+    if (!normalized) {
+      return void 0;
+    }
+    if (!isStoreMemoryScope(normalized)) {
+      throw new ValidationError("scope must be one of: subject, organization");
+    }
+    return normalized;
+  }
+};
+function isContactRequestAction(value) {
+  return CONTACT_REQUEST_ACTIONS.has(value);
+}
+function isMemorySystem(value) {
+  return MEMORY_SYSTEMS.has(value);
+}
+function isMemoryType(value) {
+  return MEMORY_TYPES.has(value);
+}
+function isMemorySegment(value) {
+  return MEMORY_SEGMENTS.has(value);
+}
+function isStoreMemoryScope(value) {
+  return MEMORY_SCOPES.has(value);
+}
+function isListMemoryScope(value) {
+  return LIST_MEMORY_SCOPES.has(value);
+}
+function isMemoryStatus(value) {
+  return LIST_MEMORY_STATUSES.has(value);
+}
+function coercePositiveInt(value, fallback) {
+  const num = Number(value ?? fallback);
+  return Number.isFinite(num) && num >= 1 ? Math.floor(num) : fallback;
+}
+function validateToolArgs(toolName, args) {
+  const errors = [];
+  const model = TOOL_MODELS[toolName];
+  if (!model) {
+    return null;
+  }
+  for (const field of model.required) {
+    if (args[field] === void 0 || args[field] === null) {
+      errors.push(`${field}: Field required`);
+    }
+  }
+  if (toolName === "thenvoi_send_message") {
+    const mentions = args.mentions;
+    if (Array.isArray(mentions) && mentions.length === 0) {
+      errors.push("mentions: At least one mention is required");
+    }
+  }
+  if (toolName === "thenvoi_send_event") {
+    const messageType = args.message_type;
+    if (typeof messageType === "string" && !CHAT_EVENT_TYPES.includes(messageType)) {
+      errors.push(
+        `message_type: Invalid value '${messageType}'. Expected one of: ${[...CHAT_EVENT_TYPES].join(", ")}`
+      );
+    }
+  }
+  if (toolName === "thenvoi_respond_contact_request") {
+    const action = args.action;
+    const validActions = ["approve", "reject", "cancel"];
+    if (typeof action === "string" && !validActions.includes(action)) {
+      errors.push(
+        `action: Invalid value '${action}'. Expected one of: ${validActions.join(", ")}`
+      );
+    }
+  }
+  if (toolName === "thenvoi_store_memory") {
+    const validSystems = ["sensory", "working", "long_term"];
+    const validTypes = ["iconic", "echoic", "haptic", "episodic", "semantic", "procedural"];
+    const validSegments = ["user", "agent", "tool", "guideline"];
+    if (typeof args.system === "string" && !validSystems.includes(args.system)) {
+      errors.push(`system: Invalid value '${args.system}'. Expected one of: ${validSystems.join(", ")}`);
+    }
+    if (typeof args.type === "string" && !validTypes.includes(args.type)) {
+      errors.push(`type: Invalid value '${args.type}'. Expected one of: ${validTypes.join(", ")}`);
+    }
+    if (typeof args.segment === "string" && !validSegments.includes(args.segment)) {
+      errors.push(`segment: Invalid value '${args.segment}'. Expected one of: ${validSegments.join(", ")}`);
+    }
+  }
+  if (errors.length > 0) {
+    const message = `Invalid arguments for ${toolName}: ${errors.join("; ")}`;
+    return createToolExecutorError({
+      errorType: "ToolArgumentsValidationError",
+      toolName,
+      message,
+      legacyMessage: message,
+      details: { validationErrors: errors }
+    });
+  }
+  return null;
+}
+
+// src/runtime/retryTracker.ts
+var DEFAULT_MAX_TRACKED = 1e4;
+var MessageRetryTracker = class {
+  maxRetriesValue;
+  maxTracked;
+  attempts = /* @__PURE__ */ new Map();
+  failed = /* @__PURE__ */ new Set();
+  constructor(maxRetries = 1, maxTracked = DEFAULT_MAX_TRACKED) {
+    this.maxRetriesValue = maxRetries;
+    this.maxTracked = maxTracked;
+  }
+  get maxRetries() {
+    return this.maxRetriesValue;
+  }
+  isPermanentlyFailed(messageId) {
+    return this.failed.has(messageId);
+  }
+  recordAttempt(messageId) {
+    const attempts = (this.attempts.get(messageId) ?? 0) + 1;
+    this.attempts.set(messageId, attempts);
+    const exceeded = attempts > this.maxRetriesValue;
+    if (exceeded) {
+      this.evictSetIfNeeded(this.failed);
+      this.failed.add(messageId);
+    }
+    this.evictMapIfNeeded(this.attempts);
+    return [attempts, exceeded];
+  }
+  markSuccess(messageId) {
+    this.attempts.delete(messageId);
+  }
+  markPermanentlyFailed(messageId) {
+    this.evictSetIfNeeded(this.failed);
+    this.failed.add(messageId);
+  }
+  evictMapIfNeeded(map) {
+    while (map.size >= this.maxTracked) {
+      const first = map.keys().next();
+      if (first.done) break;
+      map.delete(first.value);
+    }
+  }
+  evictSetIfNeeded(set) {
+    while (set.size >= this.maxTracked) {
+      const first = set.values().next();
+      if (first.done) break;
+      set.delete(first.value);
+    }
+  }
+};
+
+// src/runtime/ExecutionContext.ts
+var DEDUP_CACHE_MAX = 500;
+var ExecutionContext = class {
+  roomId;
+  link;
+  maxContextMessages;
+  enableContextCache;
+  contextCacheTtlMs;
+  enableContextHydration;
+  history = [];
+  messageIds = /* @__PURE__ */ new Set();
+  dedupCache = /* @__PURE__ */ new Map();
+  participants = [];
+  tools;
+  adapterTools;
+  participantsMessage = null;
+  lastSentParticipantIds = null;
+  contactsMessage = null;
+  contextCache = null;
+  contextCacheExpiresAt = 0;
+  _state = "starting";
+  retryTrackerInstance;
+  _llmInitialized = false;
+  _pendingSystemMessages = [];
+  constructor(options) {
+    this.roomId = options.roomId;
+    this.link = options.link;
+    this.maxContextMessages = options.maxContextMessages;
+    this.enableContextCache = options.enableContextCache ?? true;
+    this.contextCacheTtlMs = Math.max(0, (options.contextCacheTtlSeconds ?? 300) * 1e3);
+    this.enableContextHydration = options.enableContextHydration ?? true;
+    this.retryTrackerInstance = new MessageRetryTracker(options.maxMessageRetries ?? 1);
+    this.tools = new AgentTools({
+      roomId: this.roomId,
+      rest: this.link.rest,
+      participants: this.participants,
+      capabilities: this.link.capabilities
+    });
+    this.adapterTools = this.tools.getAdapterTools();
+  }
+  get state() {
+    return this._state;
+  }
+  setState(state) {
+    this._state = state;
+  }
+  getRetryTracker() {
+    return this.retryTrackerInstance;
+  }
+  get isLlmInitialized() {
+    return this._llmInitialized;
+  }
+  markLlmInitialized() {
+    this._llmInitialized = true;
+  }
+  injectSystemMessage(message) {
+    this._pendingSystemMessages.push(message);
+  }
+  consumeSystemMessages() {
+    const copy = [...this._pendingSystemMessages];
+    this._pendingSystemMessages.length = 0;
+    return copy;
+  }
+  getTools() {
+    return this.adapterTools;
+  }
+  hasMessage(messageId) {
+    return this.messageIds.has(messageId) || this.dedupCache.has(messageId);
+  }
+  recordMessage(message) {
+    if (this.hasMessage(message.id)) {
+      return;
+    }
+    this.trackDedup(message.id);
+    this.history.push(message);
+    if (this.history.length > this.maxContextMessages) {
+      this.history.splice(0, this.history.length - this.maxContextMessages);
+    }
+    this.rebuildMessageIds();
+    if (this.contextCache) {
+      this.contextCache.messages.push(this.toHistoryEntry(message));
+      if (this.contextCache.messages.length > this.maxContextMessages) {
+        this.contextCache.messages.splice(0, this.contextCache.messages.length - this.maxContextMessages);
+      }
+      this.contextCache.hydratedAt = /* @__PURE__ */ new Date();
+      this.contextCacheExpiresAt = this.nextCacheExpiry();
+    }
+  }
+  getRawHistory() {
+    return this.history.map((entry) => ({
+      id: entry.id,
+      room_id: entry.roomId,
+      content: entry.content,
+      sender_id: entry.senderId,
+      sender_type: entry.senderType,
+      sender_name: entry.senderName,
+      message_type: entry.messageType,
+      metadata: entry.metadata,
+      created_at: entry.createdAt.toISOString(),
+      role: entry.senderType === "User" ? "user" : "assistant"
+    }));
+  }
+  setParticipants(participants) {
+    this.replaceParticipants(participants);
+    this.updateCachedParticipants();
+  }
+  addParticipant(participant) {
+    const existingIndex = this.participants.findIndex((entry) => entry.id === participant.id);
+    if (existingIndex >= 0) {
+      this.participants.splice(existingIndex, 1);
+    }
+    this.participants.push(participant);
+    const name = String(participant.name ?? "unknown");
+    this.participantsMessage = `${name} joined the room.`;
+    this.updateCachedParticipants();
+  }
+  removeParticipant(participantId) {
+    const removed = this.participants.find((entry) => String(entry.id) === participantId);
+    const next = this.participants.filter((entry) => String(entry.id) !== participantId);
+    this.replaceParticipants(next);
+    if (removed) {
+      this.participantsMessage = `${String(removed.name ?? participantId)} left the room.`;
+    }
+    this.updateCachedParticipants();
+  }
+  setContactsMessage(message) {
+    this.contactsMessage = message;
+  }
+  consumeParticipantsMessage() {
+    const currentIds = new Set(this.participants.map((p) => String(p.id)));
+    let changed = !this.lastSentParticipantIds || currentIds.size !== this.lastSentParticipantIds.size;
+    if (!changed) {
+      for (const id of currentIds) {
+        if (!this.lastSentParticipantIds.has(id)) {
+          changed = true;
+          break;
+        }
+      }
+    }
+    if (!changed && !this.participantsMessage) {
+      return null;
+    }
+    const parts = [];
+    if (this.participantsMessage) {
+      parts.push(this.participantsMessage);
+      this.participantsMessage = null;
+    }
+    if (changed) {
+      const asRecords = this.participants.map((p) => ({
+        id: p.id,
+        name: p.name,
+        type: p.type,
+        handle: p.handle ?? null
+      }));
+      parts.push(buildParticipantsMessage(asRecords));
+    }
+    this.lastSentParticipantIds = currentIds;
+    return parts.length > 0 ? parts.join("\n") : null;
+  }
+  consumeContactsMessage() {
+    const value = this.contactsMessage;
+    this.contactsMessage = null;
+    return value;
+  }
+  async getHydratedHistory(excludeMessageId) {
+    if (!this.enableContextHydration || !this.link.rest.getChatContext) {
+      return this.getRawHistory().filter((entry) => entry.id !== excludeMessageId);
+    }
+    try {
+      const context = await this.hydrateContext();
+      return context.messages.filter((entry) => entry.id !== excludeMessageId);
+    } catch (error) {
+      if (error instanceof UnsupportedFeatureError) {
+        return this.getRawHistory().filter((entry) => entry.id !== excludeMessageId);
+      }
+      throw error;
+    }
+  }
+  async hydrateContext(forceRefresh = false) {
+    if (!this.enableContextHydration || !this.link.rest.getChatContext) {
+      return this.buildLocalContext();
+    }
+    if (!forceRefresh && this.enableContextCache && this.contextCache && !this.isCacheExpired()) {
+      return this.contextCache;
+    }
+    try {
+      const participants = await this.loadParticipants();
+      const messages = await this.loadHydratedMessages();
+      const context = {
+        roomId: this.roomId,
+        messages,
+        participants,
+        hydratedAt: /* @__PURE__ */ new Date()
+      };
+      this.contextCache = context;
+      this.contextCacheExpiresAt = this.nextCacheExpiry();
+      return context;
+    } catch (error) {
+      if (!(error instanceof UnsupportedFeatureError)) {
+        throw error;
+      }
+      const fallback = this.buildLocalContext();
+      this.contextCache = fallback;
+      this.contextCacheExpiresAt = this.nextCacheExpiry();
+      return fallback;
+    }
+  }
+  replaceParticipants(participants) {
+    this.participants.splice(0, this.participants.length, ...participants);
+  }
+  buildLocalContext() {
+    return {
+      roomId: this.roomId,
+      messages: this.getRawHistory(),
+      participants: [...this.participants],
+      hydratedAt: /* @__PURE__ */ new Date()
+    };
+  }
+  async loadParticipants() {
+    const participants = await this.link.rest.listChatParticipants(this.roomId, DEFAULT_REQUEST_OPTIONS);
+    const normalized = participants.map((participant) => ({
+      id: participant.id,
+      name: participant.name,
+      type: participant.type,
+      handle: participant.handle ?? null
+    }));
+    this.replaceParticipants(normalized);
+    return [...this.participants];
+  }
+  async loadHydratedMessages() {
+    const messages = [];
+    const pageSize = Math.min(Math.max(this.maxContextMessages, 1), 100);
+    const maxPages = 100;
+    for (let page = 1; page <= maxPages; page += 1) {
+      const response = await this.link.rest.getChatContext?.(
+        {
+          chatId: this.roomId,
+          page,
+          pageSize
+        },
+        DEFAULT_REQUEST_OPTIONS
+      );
+      const items = response?.data ?? [];
+      messages.push(...items.map((item) => ({
+        id: item.id,
+        room_id: this.roomId,
+        content: item.content,
+        sender_id: item.sender_id,
+        sender_type: item.sender_type,
+        sender_name: item.sender_name ?? null,
+        message_type: item.message_type,
+        metadata: item.metadata ?? {},
+        created_at: item.inserted_at,
+        role: item.sender_type === "User" ? "user" : "assistant"
+      })));
+      const totalPages = response?.metadata?.totalPages;
+      if (typeof totalPages === "number" && totalPages > 0 && page >= totalPages) {
+        break;
+      }
+      if ((typeof totalPages !== "number" || totalPages <= 0) && items.length < pageSize) {
+        break;
+      }
+    }
+    return messages.slice(-this.maxContextMessages);
+  }
+  updateCachedParticipants() {
+    if (!this.contextCache) {
+      return;
+    }
+    this.contextCache.participants = [...this.participants];
+    this.contextCache.hydratedAt = /* @__PURE__ */ new Date();
+    this.contextCacheExpiresAt = this.nextCacheExpiry();
+  }
+  isCacheExpired() {
+    return this.contextCacheExpiresAt > 0 && Date.now() >= this.contextCacheExpiresAt;
+  }
+  nextCacheExpiry() {
+    if (!this.enableContextCache || this.contextCacheTtlMs === 0) {
+      return 0;
+    }
+    return Date.now() + this.contextCacheTtlMs;
+  }
+  toHistoryEntry(message) {
+    return {
+      id: message.id,
+      room_id: message.roomId,
+      content: message.content,
+      sender_id: message.senderId,
+      sender_type: message.senderType,
+      sender_name: message.senderName,
+      message_type: message.messageType,
+      metadata: message.metadata,
+      created_at: message.createdAt.toISOString(),
+      role: message.senderType === "User" ? "user" : "assistant"
+    };
+  }
+  rebuildMessageIds() {
+    this.messageIds = new Set(this.history.map((entry) => entry.id));
+  }
+  trackDedup(messageId) {
+    this.dedupCache.set(messageId, true);
+    if (this.dedupCache.size > DEDUP_CACHE_MAX) {
+      const first = this.dedupCache.keys().next();
+      if (!first.done) {
+        this.dedupCache.delete(first.value);
+      }
+    }
+  }
+};
+
+// src/runtime/rooms/subscriptions.ts
+function hasRoomId(roomId) {
+  return typeof roomId === "string" && roomId.length > 0;
+}
+async function trackRoomJoin(options) {
+  if (!hasRoomId(options.roomId)) {
+    return false;
+  }
+  if (options.roomFilter && !options.roomFilter(options.payload)) {
+    return false;
+  }
+  if (options.trackedRooms.has(options.roomId)) {
+    return false;
+  }
+  await options.link.subscribeRoom(options.roomId);
+  options.trackedRooms.add(options.roomId);
+  if (options.onJoined) {
+    await options.onJoined(options.roomId, options.payload);
+  }
+  return true;
+}
+async function trackRoomLeave(options) {
+  if (!hasRoomId(options.roomId) || !options.trackedRooms.has(options.roomId)) {
+    return false;
+  }
+  await options.link.unsubscribeRoom(options.roomId);
+  options.trackedRooms.delete(options.roomId);
+  if (options.onLeft) {
+    await options.onLeft(options.roomId);
+  }
+  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
+    );
+    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
+      });
+    }
+  } catch (error) {
+    if (error instanceof UnsupportedFeatureError) {
+      return;
+    }
+    if (options.onError) {
+      await options.onError(error);
+      return;
+    }
+    throw error;
+  }
+}
+
+// src/runtime/rooms/AgentRuntime.ts
+var AgentRuntime = class {
+  link;
+  agentId;
+  onExecute;
+  onSessionCleanup;
+  onRoomJoined;
+  onRoomLeft;
+  onContactEvent;
+  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;
+    this.agentId = options.agentId;
+    this.onExecute = options.onExecute;
+    this.onSessionCleanup = options.onSessionCleanup ?? (async () => void 0);
+    this.onRoomJoined = options.onRoomJoined;
+    this.onRoomLeft = options.onRoomLeft;
+    this.onError = options.onError;
+    this.logger = options.logger ?? new NoopLogger();
+    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,
+      contextCacheTtlSeconds: options.sessionConfig?.contextCacheTtlSeconds ?? 300,
+      maxContextMessages: options.sessionConfig?.maxContextMessages ?? 100,
+      maxMessageRetries: options.sessionConfig?.maxMessageRetries ?? 1,
+      enableContextHydration: options.sessionConfig?.enableContextHydration ?? true
+    };
+    this.autoSubscribeExistingRooms = options.agentConfig?.autoSubscribeExistingRooms ?? false;
+  }
+  async start() {
+    if (this.running) {
+      return;
+    }
+    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();
+    } 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");
+    }
+  }
+  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) {
+    if (!this.running || this.stopping) {
+      return true;
+    }
+    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;
+    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]) {
+      await this.leaveTrackedRoom(roomId);
+    }
+    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));
+    }
+    return graceful;
+  }
+  getContext(roomId) {
+    return this.contexts.get(roomId);
+  }
+  async waitUntilStopped() {
+    if (this.consumeTask) {
+      await this.consumeTask;
+    } else {
+      await this.link.runForever(this.stopController.signal);
+    }
+    if (this.fatalError) {
+      throw this.fatalError instanceof Error ? this.fatalError : new Error(String(this.fatalError));
+    }
+  }
+  getContexts() {
+    return [...this.contexts.values()];
+  }
+  async consumeLoop(signal) {
+    while (!signal.aborted) {
+      const event = await this.link.nextEvent(signal);
+      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 assertNever(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.getOrCreateExecution(roomId).bootstrapMessage(message);
+  }
+  async resetRoomSession(roomId, timeoutMs) {
+    const execution = this.executions.get(roomId);
+    let graceful = true;
+    if (execution) {
+      graceful = await execution.stop(timeoutMs);
+    }
+    this.executions.delete(roomId);
+    this.contexts.delete(roomId);
+    await this.onSessionCleanup(roomId);
+    return graceful;
+  }
+  getOrCreateExecution(roomId) {
+    const existing = this.executions.get(roomId);
+    if (existing) {
+      return existing;
+    }
+    const execution = new Execution({
+      roomId,
+      link: this.link,
+      context: this.getOrCreateContext(roomId),
+      onExecute: this.onExecute,
+      onFailure: async (error, event) => {
+        await this.failRuntime(error, event);
+      },
+      logger: this.logger
+    });
+    this.executions.set(roomId, execution);
+    const watcher = execution.waitUntilStopped().catch(async (error) => {
+      await this.failRuntime(error, {
+        type: "message_created",
+        roomId,
+        payload: {
+          id: "execution-failed",
+          content: "",
+          sender_id: this.agentId,
+          sender_type: "Agent",
+          sender_name: null,
+          message_type: "text",
+          metadata: {},
+          inserted_at: (/* @__PURE__ */ new Date(0)).toISOString(),
+          updated_at: (/* @__PURE__ */ new Date(0)).toISOString()
+        }
+      });
+    }).finally(() => {
+      this.executionWatchers.delete(roomId);
+    });
+    this.executionWatchers.set(roomId, watcher);
+    return execution;
+  }
+  getOrCreateContext(roomId) {
+    const existing = this.contexts.get(roomId);
+    if (existing) {
+      return existing;
+    }
+    const defaults = {
+      roomId,
+      link: this.link,
+      maxContextMessages: this.sessionConfig.maxContextMessages,
+      maxMessageRetries: this.sessionConfig.maxMessageRetries,
+      enableContextCache: this.sessionConfig.enableContextCache,
+      contextCacheTtlSeconds: this.sessionConfig.contextCacheTtlSeconds,
+      enableContextHydration: this.sessionConfig.enableContextHydration
+    };
+    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) {
+    await trackRoomLeave({
+      link: this.link,
+      roomId,
+      trackedRooms: this.subscribedRooms,
+      onLeft: async (leftRoomId) => {
+        await this.executions.get(leftRoomId)?.stop();
+        this.contexts.delete(leftRoomId);
+        this.executions.delete(leftRoomId);
+        await this.onSessionCleanup(leftRoomId);
+      }
+    });
+  }
+  async failRuntime(error, event) {
+    if (!this.fatalError) {
+      this.fatalError = error;
+      this.running = false;
+      this.logger.error("Fatal runtime error handling platform event", {
+        eventType: event.type,
+        roomId: event.roomId,
+        error
+      });
+      this.notifyOnError(error, event);
+    }
+    if (!this.stopController.signal.aborted) {
+      this.stopController.abort();
+    }
+  }
+  notifyOnError(error, event) {
+    if (!this.onError) {
+      return;
+    }
+    try {
+      this.onError(error, event);
+    } catch (observerError) {
+      this.logger.error("Error in runtime onError callback", {
+        eventType: event.type,
+        roomId: event.roomId,
+        error: observerError
+      });
+    }
+  }
+};
+function assertNever(value) {
+  throw new Error(`Unhandled platform event: ${JSON.stringify(value)}`);
+}
+
+// src/runtime/preprocessing/DefaultPreprocessor.ts
+function toPlatformMessage2(roomId, payload) {
+  return {
+    id: payload.id,
+    roomId,
+    content: payload.content,
+    senderId: payload.sender_id,
+    senderType: payload.sender_type,
+    senderName: payload.sender_name ?? null,
+    messageType: payload.message_type,
+    metadata: payload.metadata ?? {},
+    createdAt: new Date(payload.inserted_at)
+  };
+}
+var DefaultPreprocessor = class {
+  async process(context, event, agentId) {
+    if (event.type !== "message_created" || !event.roomId) {
+      return null;
+    }
+    const message = toPlatformMessage2(event.roomId, event.payload);
+    if (message.senderId === agentId) {
+      return null;
+    }
+    if (context.hasMessage(message.id)) {
+      return null;
+    }
+    const isSessionBootstrap = !context.isLlmInitialized;
+    if (isSessionBootstrap) {
+      context.markLlmInitialized();
+    }
+    context.recordMessage(message);
+    const systemMessages = context.consumeSystemMessages();
+    let contactsMessage;
+    if (systemMessages.length > 0) {
+      contactsMessage = systemMessages.join("\n");
+    } else {
+      contactsMessage = context.consumeContactsMessage();
+    }
+    const history = isSessionBootstrap ? await context.getHydratedHistory(message.id) : context.getRawHistory();
+    return {
+      message,
+      tools: context.getTools(),
+      history: new HistoryProvider(history),
+      participantsMessage: context.consumeParticipantsMessage(),
+      contactsMessage,
+      isSessionBootstrap,
+      roomId: context.roomId
+    };
+  }
+};
+
+// src/runtime/tools/ContactToolsImpl.ts
+var ContactToolsImpl = class {
+  rest;
+  constructor(rest) {
+    this.rest = rest;
+  }
+  async listContacts(request = {}) {
+    if (!this.rest.listContacts) {
+      throw new UnsupportedFeatureError("Contact listing is not available in current REST adapter");
+    }
+    return this.rest.listContacts(
+      {
+        page: request.page ?? 1,
+        pageSize: request.pageSize ?? 50
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async addContact(request) {
+    if (!this.rest.addContact) {
+      throw new UnsupportedFeatureError("Contact creation is not available in current REST adapter");
+    }
+    const normalizedHandle = request.handle.trim();
+    if (normalizedHandle.length === 0) {
+      throw new ValidationError("handle is required");
+    }
+    return this.rest.addContact(
+      {
+        handle: normalizedHandle,
+        ...request.message ? { message: request.message } : {}
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async removeContact(request) {
+    if (!this.rest.removeContact) {
+      throw new UnsupportedFeatureError("Contact removal is not available in current REST adapter");
+    }
+    if (request.target === "handle") {
+      const handle = request.handle.trim();
+      if (handle.length === 0) {
+        throw new ValidationError("handle is required");
+      }
+      return this.rest.removeContact(
+        { target: "handle", handle },
+        DEFAULT_REQUEST_OPTIONS
+      );
+    }
+    const contactId = request.contactId.trim();
+    if (contactId.length === 0) {
+      throw new ValidationError("contactId is required");
+    }
+    return this.rest.removeContact(
+      { target: "contactId", contactId },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async listContactRequests(request = {}) {
+    if (!this.rest.listContactRequests) {
+      throw new UnsupportedFeatureError("Contact request listing is not available in current REST adapter");
+    }
+    return this.rest.listContactRequests(
+      {
+        page: request.page ?? 1,
+        pageSize: request.pageSize ?? 50,
+        sentStatus: request.sentStatus ?? "pending"
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async respondContactRequest(request) {
+    if (!this.rest.respondContactRequest) {
+      throw new UnsupportedFeatureError("Contact request responses are not available in current REST adapter");
+    }
+    if (request.target === "handle") {
+      const handle = request.handle.trim();
+      if (handle.length === 0) {
+        throw new ValidationError("handle is required");
+      }
+      return this.rest.respondContactRequest(
+        { action: request.action, target: "handle", handle },
+        DEFAULT_REQUEST_OPTIONS
+      );
+    }
+    const requestId = request.requestId.trim();
+    if (requestId.length === 0) {
+      throw new ValidationError("requestId is required");
+    }
+    return this.rest.respondContactRequest(
+      { action: request.action, target: "requestId", requestId },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+};
+
+// src/runtime/tools/ContactCallbackTools.ts
+function toParticipantRecord(participant) {
+  return {
+    id: participant.id,
+    name: participant.name,
+    type: participant.type,
+    handle: participant.handle ?? null
+  };
+}
+function normalizePage(value, fallback) {
+  return Number.isInteger(value) && value && value > 0 ? value : fallback;
+}
+function requireRoomId(roomId, methodName) {
+  if (roomId) {
+    return roomId;
+  }
+  throw new UnsupportedFeatureError(`${methodName} is unavailable for contact callbacks without a room context`);
+}
+var ContactCallbackTools = class {
+  capabilities;
+  rest;
+  roomId;
+  contactTools;
+  constructor(rest, roomId) {
+    this.rest = rest;
+    this.roomId = roomId;
+    const hasContactMethods = Boolean(
+      rest.listContacts || rest.addContact || rest.removeContact || rest.listContactRequests || rest.respondContactRequest
+    );
+    this.contactTools = hasContactMethods ? new ContactToolsImpl(rest) : null;
+    this.capabilities = Object.freeze({
+      peers: Boolean(rest.listPeers),
+      contacts: hasContactMethods,
+      memory: Boolean(
+        rest.listMemories || rest.storeMemory || rest.getMemory || rest.supersedeMemory || rest.archiveMemory
+      )
+    });
+  }
+  async sendMessage(content, mentions) {
+    const roomId = requireRoomId(this.roomId, "sendMessage");
+    if (!this.rest.createChatMessage) {
+      throw new UnsupportedFeatureError("Message sending is not available in current REST adapter");
+    }
+    if (Array.isArray(mentions) && mentions.some((mention) => typeof mention === "string")) {
+      throw new UnsupportedFeatureError("sendMessage string mentions are unavailable for contact callbacks");
+    }
+    const normalizedMentions = mentions && mentions.every((mention) => typeof mention !== "string") ? mentions : void 0;
+    return this.rest.createChatMessage(
+      roomId,
+      {
+        content,
+        ...normalizedMentions ? { mentions: normalizedMentions } : {}
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async sendEvent(content, messageType, metadata) {
+    const roomId = requireRoomId(this.roomId, "sendEvent");
+    if (!this.rest.createChatEvent) {
+      throw new UnsupportedFeatureError("Event sending is not available in current REST adapter");
+    }
+    return this.rest.createChatEvent(
+      roomId,
+      {
+        content,
+        messageType,
+        ...metadata ? { metadata } : {}
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  async addParticipant() {
+    throw new UnsupportedFeatureError("addParticipant is unavailable for contact callbacks");
+  }
+  async removeParticipant() {
+    throw new UnsupportedFeatureError("removeParticipant is unavailable for contact callbacks");
+  }
+  async getParticipants() {
+    const roomId = requireRoomId(this.roomId, "getParticipants");
+    if (!this.rest.listChatParticipants) {
+      throw new UnsupportedFeatureError("Participant listing is not available in current REST adapter");
+    }
+    return (await this.rest.listChatParticipants(roomId, DEFAULT_REQUEST_OPTIONS)).map(toParticipantRecord);
+  }
+  async createChatroom(taskId) {
+    const chat = await this.rest.createChat(taskId, DEFAULT_REQUEST_OPTIONS);
+    return chat.id;
+  }
+  async lookupPeers(page = 1, pageSize = 50) {
+    if (!this.rest.listPeers) {
+      throw new UnsupportedFeatureError("Peer lookup is not available in current REST adapter");
+    }
+    return this.rest.listPeers(
+      {
+        page: normalizePage(page, 1),
+        pageSize: normalizePage(pageSize, 50),
+        notInChat: this.roomId ?? ""
+      },
+      DEFAULT_REQUEST_OPTIONS
+    );
+  }
+  getToolSchemas() {
+    return [];
+  }
+  getAnthropicToolSchemas() {
+    return [];
+  }
+  getOpenAIToolSchemas() {
+    return [];
+  }
+  async listContacts(request = {}) {
+    if (!this.contactTools) {
+      throw new UnsupportedFeatureError("Contact listing is not available in current REST adapter");
+    }
+    return this.contactTools.listContacts(request);
+  }
+  async addContact(request) {
+    if (!this.contactTools) {
+      throw new UnsupportedFeatureError("Contact creation is not available in current REST adapter");
+    }
+    return this.contactTools.addContact(request);
+  }
+  async removeContact(request) {
+    if (!this.contactTools) {
+      throw new UnsupportedFeatureError("Contact removal is not available in current REST adapter");
+    }
+    return this.contactTools.removeContact(request);
+  }
+  async listContactRequests(request = {}) {
+    if (!this.contactTools) {
+      throw new UnsupportedFeatureError("Contact request listing is not available in current REST adapter");
+    }
+    return this.contactTools.listContactRequests(request);
+  }
+  async respondContactRequest(request) {
+    if (!this.contactTools) {
+      throw new UnsupportedFeatureError("Contact request responses are not available in current REST adapter");
+    }
+    return this.contactTools.respondContactRequest(request);
+  }
+  async listMemories(args = {}) {
+    if (!this.rest.listMemories) {
+      throw new UnsupportedFeatureError("Memory listing is not available in current REST adapter");
+    }
+    return this.rest.listMemories(args, DEFAULT_REQUEST_OPTIONS);
+  }
+  async storeMemory(args) {
+    if (!this.rest.storeMemory) {
+      throw new UnsupportedFeatureError("Memory storage is not available in current REST adapter");
+    }
+    return this.rest.storeMemory(args, DEFAULT_REQUEST_OPTIONS);
+  }
+  async getMemory(memoryId) {
+    if (!this.rest.getMemory) {
+      throw new UnsupportedFeatureError("Memory lookup is not available in current REST adapter");
+    }
+    return this.rest.getMemory(memoryId, DEFAULT_REQUEST_OPTIONS);
+  }
+  async supersedeMemory(memoryId) {
+    if (!this.rest.supersedeMemory) {
+      throw new UnsupportedFeatureError("Memory supersede is not available in current REST adapter");
+    }
+    return this.rest.supersedeMemory(memoryId, DEFAULT_REQUEST_OPTIONS);
+  }
+  async archiveMemory(memoryId) {
+    if (!this.rest.archiveMemory) {
+      throw new UnsupportedFeatureError("Memory archival is not available in current REST adapter");
+    }
+    return this.rest.archiveMemory(memoryId, DEFAULT_REQUEST_OPTIONS);
+  }
+  async executeToolCall(toolName, toolArgs) {
+    switch (toolName) {
+      case "thenvoi_send_message":
+        return this.sendMessage(
+          String(toolArgs.content ?? ""),
+          toolArgs.mentions
+        );
+      case "thenvoi_send_event":
+        return this.sendEvent(
+          String(toolArgs.content ?? ""),
+          String(toolArgs.message_type ?? "task"),
+          toolArgs.metadata
+        );
+      case "thenvoi_get_participants":
+        return this.getParticipants();
+      case "thenvoi_create_chatroom":
+        return this.createChatroom(typeof toolArgs.task_id === "string" ? toolArgs.task_id : void 0);
+      case "thenvoi_lookup_peers":
+        return this.lookupPeers(
+          typeof toolArgs.page === "number" ? toolArgs.page : void 0,
+          typeof toolArgs.page_size === "number" ? toolArgs.page_size : void 0
+        );
+      case "thenvoi_list_contacts":
+        return this.listContacts({
+          page: typeof toolArgs.page === "number" ? toolArgs.page : void 0,
+          pageSize: typeof toolArgs.page_size === "number" ? toolArgs.page_size : void 0
+        });
+      case "thenvoi_add_contact":
+        return this.addContact({
+          handle: String(toolArgs.handle ?? ""),
+          ...typeof toolArgs.message === "string" ? { message: toolArgs.message } : {}
+        });
+      case "thenvoi_remove_contact":
+        if (typeof toolArgs.contact_id === "string") {
+          return this.removeContact({ target: "contactId", contactId: toolArgs.contact_id });
+        }
+        return this.removeContact({ target: "handle", handle: String(toolArgs.handle ?? "") });
+      case "thenvoi_list_contact_requests":
+        return this.listContactRequests({
+          page: typeof toolArgs.page === "number" ? toolArgs.page : void 0,
+          pageSize: typeof toolArgs.page_size === "number" ? toolArgs.page_size : void 0,
+          sentStatus: typeof toolArgs.sent_status === "string" ? toolArgs.sent_status : void 0
+        });
+      case "thenvoi_respond_contact_request":
+        if (typeof toolArgs.request_id === "string") {
+          return this.respondContactRequest({
+            action: String(toolArgs.action ?? "approve"),
+            target: "requestId",
+            requestId: toolArgs.request_id
+          });
+        }
+        return this.respondContactRequest({
+          action: String(toolArgs.action ?? "approve"),
+          target: "handle",
+          handle: String(toolArgs.handle ?? "")
+        });
+      case "thenvoi_list_memories":
+        return this.listMemories(toolArgs);
+      case "thenvoi_store_memory":
+        return this.storeMemory(toolArgs);
+      case "thenvoi_get_memory":
+        return this.getMemory(String(toolArgs.memory_id ?? ""));
+      case "thenvoi_supersede_memory":
+        return this.supersedeMemory(String(toolArgs.memory_id ?? ""));
+      case "thenvoi_archive_memory":
+        return this.archiveMemory(String(toolArgs.memory_id ?? ""));
+      default:
+        throw new UnsupportedFeatureError(`Unsupported tool call for contact callback: ${toolName}`);
+    }
+  }
+};
+
+// src/runtime/ContactEventHandler.ts
+var LRU_MAX_SIZE = 1e3;
+var HUB_ROOM_SYSTEM_PROMPT = `## OVERRIDE: Contact Management Mode
+
+This is your CONTACTS HUB - a dedicated room for managing contact requests.
+
+**IMPORTANT: Do NOT delegate or add participants here.** You handle contact events DIRECTLY using the contact tools below. Do NOT call thenvoi_lookup_peers() or thenvoi_add_participant() in this room.
+
+## Your Role
+
+1. **Review incoming contact requests** - When you see a [Contact Request] message, evaluate it
+2. **Take action** - Use the contact tools to respond:
+   - \`thenvoi_respond_contact_request(action="approve", request_id="...")\` to accept
+   - \`thenvoi_respond_contact_request(action="reject", request_id="...")\` to decline
+3. **Report your decision** - Send a thought event explaining what you did
+
+## Example
+
+[Contact Events]: [Contact Request] Alice (@alice) wants to connect.
+Request ID: abc-123
+
+Your response:
+1. thenvoi_send_event("Received contact request from Alice. Approving.", message_type="thought")
+2. thenvoi_respond_contact_request(action="approve", request_id="abc-123")
+3. thenvoi_send_event("Approved contact request from Alice (@alice)", message_type="thought")
+
+## Contact Tools (use these, NOT participant tools)
+- \`thenvoi_respond_contact_request(action, request_id)\` - Approve/reject requests
+- \`thenvoi_list_contact_requests()\` - List pending requests
+- \`thenvoi_list_contacts()\` - List current contacts`;
+var ContactEventHandlerError = class extends Error {
+  retryable;
+  stage;
+  eventType;
+  constructor(input) {
+    super(`Contact event ${input.eventType} failed during ${input.stage}`, { cause: input.cause });
+    this.name = "ContactEventHandlerError";
+    this.retryable = input.retryable;
+    this.stage = input.stage;
+    this.eventType = input.eventType;
+  }
+};
+var ContactEventHandler = class {
+  config;
+  rest;
+  logger;
+  onBroadcast;
+  onHubEvent;
+  onHubInit;
+  dedup = /* @__PURE__ */ new Set();
+  dedupOrder = [];
+  syntheticIdCounter = 0;
+  requestCache = /* @__PURE__ */ new Map();
+  hubRoomId = null;
+  hubRoomInitPromise = null;
+  constructor(options) {
+    this.config = options.config;
+    this.rest = options.rest;
+    this.logger = options.logger ?? new NoopLogger();
+    this.onBroadcast = options.onBroadcast;
+    this.onHubEvent = options.onHubEvent;
+    this.onHubInit = options.onHubInit;
+  }
+  async handle(event, tools) {
+    const strategy = this.config.strategy ?? "disabled";
+    const hasBroadcast = this.config.broadcastChanges && this.onBroadcast;
+    if (strategy === "disabled" && !hasBroadcast) {
+      return;
+    }
+    const dedupKey = this.buildDedupKey(event);
+    if (this.dedup.has(dedupKey)) {
+      this.logger.debug("Duplicate contact event skipped", { key: dedupKey });
+      return;
+    }
+    this.recordDedup(dedupKey);
+    try {
+      if (event.type === "contact_request_received") {
+        this.cacheRequestInfo(event.payload.id, {
+          fromHandle: event.payload.from_handle,
+          fromName: event.payload.from_name,
+          message: event.payload.message ?? null
+        });
+      }
+      if (hasBroadcast) {
+        const broadcastMsg = this.formatBroadcast(event);
+        if (broadcastMsg) {
+          this.onBroadcast(broadcastMsg);
+        }
+      }
+      if (strategy === "disabled") {
+        return;
+      }
+      if (strategy === "callback") {
+        await this.handleCallback(event, tools);
+      } else if (strategy === "hub_room") {
+        await this.handleHubRoom(event);
+      }
+    } catch (error) {
+      this.rollbackDedup(dedupKey);
+      throw error;
+    }
+  }
+  async handleCallback(event, tools) {
+    const callback = this.config.onEvent;
+    if (!callback) {
+      this.logger.warn("Contact event callback strategy configured but no onEvent callback provided");
+      return;
+    }
+    const callbackTools = tools ?? new ContactCallbackTools(this.rest, event.roomId);
+    try {
+      await callback(event, callbackTools);
+    } catch (error) {
+      const failure = this.buildHandlerError(event, "callback", error, false);
+      this.logFailure(event, failure.stage, failure.retryable, error);
+      throw failure;
+    }
+  }
+  async handleHubRoom(event) {
+    const hubTaskId = this.config.hubTaskId;
+    if (!hubTaskId) {
+      this.logger.warn("hub_room strategy requires hubTaskId");
+      return;
+    }
+    if (!this.hubRoomId) {
+      if (!this.hubRoomInitPromise) {
+        this.hubRoomInitPromise = this.initHubRoom(hubTaskId);
+      }
+      try {
+        this.hubRoomId = await this.hubRoomInitPromise;
+      } catch (error) {
+        this.hubRoomInitPromise = null;
+        const failure = this.buildHandlerError(event, "hub_room_init", error, true);
+        this.logFailure(event, failure.stage, failure.retryable, error);
+        throw failure;
+      }
+    }
+    const formattedMessage = await this.formatEventMessage(event);
+    let persistFailure = null;
+    try {
+      await this.rest.createChatEvent(this.hubRoomId, {
+        content: formattedMessage,
+        messageType: "contact_event",
+        metadata: { contactEventType: event.type, payload: event.payload }
+      });
+    } catch (error) {
+      persistFailure = this.buildHandlerError(event, "hub_room_persist", error, true);
+      this.logFailure(event, persistFailure.stage, persistFailure.retryable, error);
+    }
+    let dispatchFailure = null;
+    if (this.onHubEvent) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const syntheticEvent = {
+        type: "message_created",
+        roomId: this.hubRoomId,
+        payload: {
+          id: `contact-evt-${Date.now()}-${this.syntheticIdCounter++}`,
+          content: formattedMessage,
+          message_type: "contact_event",
+          sender_id: SYNTHETIC_CONTACT_EVENTS_SENDER_ID,
+          sender_type: SYNTHETIC_SENDER_TYPE,
+          sender_name: SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
+          inserted_at: now,
+          updated_at: now
+        }
+      };
+      try {
+        await this.onHubEvent(this.hubRoomId, syntheticEvent);
+      } catch (error) {
+        dispatchFailure = this.buildHandlerError(event, "hub_room_dispatch", error, true);
+        this.logFailure(event, dispatchFailure.stage, dispatchFailure.retryable, error);
+      }
+    }
+    if (persistFailure) {
+      throw persistFailure;
+    }
+    if (dispatchFailure) {
+      throw dispatchFailure;
+    }
+  }
+  async initHubRoom(hubTaskId) {
+    const result = await this.rest.createChat(hubTaskId);
+    this.logger.info("Hub room created for contact events", { roomId: result.id });
+    if (this.onHubInit) {
+      await this.onHubInit(result.id, HUB_ROOM_SYSTEM_PROMPT);
+    }
+    return result.id;
+  }
+  async formatEventMessage(event) {
+    switch (event.type) {
+      case "contact_request_received": {
+        const msg = event.payload.message ? `
+Message: "${event.payload.message}"` : "";
+        const handle = normalizeHandle(event.payload.from_handle);
+        return `[Contact Request] ${event.payload.from_name} (${handle}) wants to connect.${msg}
+Request ID: ${event.payload.id}`;
+      }
+      case "contact_request_updated": {
+        const info = await this.enrichUpdateEvent(event.payload.id);
+        if (info) {
+          const name = info.fromName ?? info.toName;
+          const rawHandle = info.fromHandle ?? info.toHandle ?? "";
+          const handle = normalizeHandle(rawHandle);
+          if (name) {
+            const direction = info.fromName ? "from" : "to";
+            return `[Contact Request Update] Request ${direction} ${name} (${handle}) status changed to: ${event.payload.status}
+Request ID: ${event.payload.id}`;
+          }
+        }
+        return `[Contact Request Update] Request ${event.payload.id} status changed to: ${event.payload.status}`;
+      }
+      case "contact_added": {
+        const handle = normalizeHandle(event.payload.handle);
+        return `[Contact Added] ${event.payload.name} (${handle}) is now a contact.
+Type: ${event.payload.type}, ID: ${event.payload.id}`;
+      }
+      case "contact_removed":
+        return `[Contact Removed] Contact ${event.payload.id} was removed.`;
+    }
+    return assertNever2(event);
+  }
+  formatBroadcast(event) {
+    switch (event.type) {
+      case "contact_added": {
+        const handle = normalizeHandle(event.payload.handle);
+        return `[Contacts]: ${handle} (${event.payload.name}) is now a contact`;
+      }
+      case "contact_removed":
+        return `[Contacts]: Contact ${event.payload.id} was removed`;
+      default:
+        return null;
+    }
+  }
+  async enrichUpdateEvent(requestId) {
+    const cached = this.requestCache.get(requestId);
+    if (cached) {
+      return cached;
+    }
+    this.logger.debug("Cache miss for request, fetching from API", { requestId });
+    return await this.fetchRequestDetails(requestId);
+  }
+  async fetchRequestDetails(requestId) {
+    if (!this.rest.listContactRequests) {
+      return null;
+    }
+    try {
+      const response = await this.rest.listContactRequests({ page: 1, pageSize: 100 });
+      for (const req of response.received ?? []) {
+        if (req.id === requestId) {
+          const info = {
+            fromHandle: req.from_handle,
+            fromName: req.from_name,
+            message: req.message ?? null
+          };
+          this.cacheRequestInfo(requestId, info);
+          this.logger.debug("Fetched request details from API (received)", { requestId });
+          return info;
+        }
+      }
+      for (const req of response.sent ?? []) {
+        if (req.id === requestId) {
+          const info = {
+            toHandle: req.to_handle,
+            toName: req.to_name,
+            message: req.message ?? null
+          };
+          this.cacheRequestInfo(requestId, info);
+          this.logger.debug("Fetched request details from API (sent)", { requestId });
+          return info;
+        }
+      }
+      this.logger.debug("Request not found in API", { requestId });
+      return null;
+    } catch (error) {
+      this.logger.warn("Failed to fetch request details from API", { requestId, error });
+      return null;
+    }
+  }
+  cacheRequestInfo(id, info) {
+    this.requestCache.set(id, info);
+    while (this.requestCache.size > LRU_MAX_SIZE) {
+      const first = this.requestCache.keys().next();
+      if (first.done) break;
+      this.requestCache.delete(first.value);
+    }
+  }
+  buildDedupKey(event) {
+    const id = event.payload.id;
+    if (event.type === "contact_request_updated") {
+      return `${event.type}:${id}:${event.payload.status}`;
+    }
+    return `${event.type}:${id}`;
+  }
+  recordDedup(key) {
+    this.dedup.add(key);
+    this.dedupOrder.push(key);
+    while (this.dedupOrder.length > LRU_MAX_SIZE) {
+      const evicted = this.dedupOrder.shift();
+      if (evicted) {
+        this.dedup.delete(evicted);
+      }
+    }
+  }
+  rollbackDedup(key) {
+    if (!this.dedup.delete(key)) {
+      return;
+    }
+    const index = this.dedupOrder.lastIndexOf(key);
+    if (index >= 0) {
+      this.dedupOrder.splice(index, 1);
+    }
+  }
+  buildHandlerError(event, stage, cause, defaultRetryable) {
+    return new ContactEventHandlerError({
+      eventType: event.type,
+      stage,
+      retryable: this.resolveRetryable(cause, defaultRetryable),
+      cause
+    });
+  }
+  resolveRetryable(error, defaultRetryable) {
+    if (typeof error === "object" && error !== null && "retryable" in error) {
+      return error.retryable === true;
+    }
+    return defaultRetryable;
+  }
+  logFailure(event, stage, retryable, error) {
+    this.logger.error("contact_event.failure", {
+      type: event.type,
+      stage,
+      retryable,
+      error: this.serializeError(error)
+    });
+  }
+  serializeError(error) {
+    if (error instanceof Error) {
+      const payload = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      };
+      if (typeof error.retryable !== "undefined") {
+        payload.retryable = error.retryable;
+      }
+      return payload;
+    }
+    return { message: String(error) };
+  }
+};
+function assertNever2(value) {
+  throw new Error(`Unhandled contact event: ${JSON.stringify(value)}`);
+}
+function normalizeHandle(handle) {
+  if (!handle) return "@unknown";
+  return handle.startsWith("@") ? handle : `@${handle}`;
+}
+
+// src/runtime/PlatformRuntime.ts
+var PlatformRuntime = class {
+  _agentId;
+  _apiKey;
+  _wsUrl;
+  _restUrl;
+  preprocessor;
+  sessionConfig;
+  contactConfig;
+  agentConfig;
+  linkOptions;
+  configuredIdentity;
+  logger;
+  _onParticipantAdded;
+  _onParticipantRemoved;
+  _roomFilter;
+  _contextFactory;
+  linkInstance;
+  initPromise = null;
+  runtime;
+  contactHandler;
+  activeAdapter;
+  stopping = false;
+  _agentName = "";
+  _agentDescription = "";
+  contactsSubscribed = false;
+  constructor(options) {
+    if (!options.agentId || options.agentId.trim() === "") {
+      throw new ValidationError(
+        "agentId is required and must be a non-empty string. Use loadAgentConfig() to load credentials from agent_config.yaml."
+      );
+    }
+    if (!options.apiKey || options.apiKey.trim() === "") {
+      throw new ValidationError(
+        "apiKey is required and must be a non-empty string. Use loadAgentConfig() to load credentials from agent_config.yaml."
+      );
+    }
+    this._agentId = options.agentId;
+    this._apiKey = options.apiKey;
+    this._wsUrl = options.wsUrl;
+    this._restUrl = options.restUrl;
+    this.linkInstance = options.link;
+    this.linkOptions = options.linkOptions;
+    this.preprocessor = options.preprocessor ?? new DefaultPreprocessor();
+    this.sessionConfig = options.sessionConfig;
+    this.contactConfig = options.contactConfig;
+    this.agentConfig = options.agentConfig;
+    this.logger = options.logger ?? new NoopLogger();
+    this.configuredIdentity = options.identity;
+    this._onParticipantAdded = options.onParticipantAdded;
+    this._onParticipantRemoved = options.onParticipantRemoved;
+    this._roomFilter = options.roomFilter;
+    this._contextFactory = options.contextFactory;
+  }
+  get link() {
+    if (!this.linkInstance) {
+      throw new RuntimeStateError("Runtime is not initialized");
+    }
+    return this.linkInstance;
+  }
+  get name() {
+    return this._agentName;
+  }
+  get agentId() {
+    return this._agentId;
+  }
+  get description() {
+    return this._agentDescription;
+  }
+  get contactConfiguration() {
+    return this.contactConfig;
+  }
+  get isContactsSubscribed() {
+    return this.contactsSubscribed;
+  }
+  async initialize() {
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+    this.initPromise = this.doInitialize();
+    try {
+      await this.initPromise;
+    } catch (error) {
+      this.initPromise = null;
+      throw error;
+    }
+  }
+  async doInitialize() {
+    if (!this.linkInstance) {
+      this.linkInstance = new ThenvoiLink({
+        ...this.linkOptions,
+        agentId: this._agentId,
+        apiKey: this._apiKey,
+        wsUrl: this._wsUrl,
+        restUrl: this._restUrl
+      });
+    }
+    if (this.configuredIdentity) {
+      this._agentName = this.configuredIdentity.name;
+      this._agentDescription = this.configuredIdentity.description ?? "";
+      return;
+    }
+    const me = await this.link.rest.getAgentMe();
+    this._agentName = me.name;
+    this._agentDescription = me.description ?? "";
+  }
+  async start(adapter) {
+    await this.initialize();
+    await adapter.onStarted(this._agentName, this._agentDescription);
+    this.activeAdapter = adapter;
+    try {
+      this.contactHandler = new ContactEventHandler({
+        config: this.contactConfig ?? { strategy: "disabled" },
+        rest: this.link.rest,
+        onBroadcast: (message) => {
+          const runtime = this.runtime;
+          if (!runtime) return;
+          for (const context of runtime.getContexts()) {
+            context.injectSystemMessage(message);
+          }
+        },
+        onHubEvent: async (roomId, event) => {
+          const runtime = this.runtime;
+          if (!runtime) return;
+          await runtime.enqueueEvent(roomId, event);
+        },
+        onHubInit: async (roomId, systemPrompt) => {
+          const runtime = this.runtime;
+          if (!runtime) return;
+          runtime.getOrCreateContext(roomId).injectSystemMessage(systemPrompt);
+        }
+      });
+      this.runtime = new AgentRuntime({
+        link: this.link,
+        agentId: this._agentId,
+        sessionConfig: this.sessionConfig,
+        agentConfig: this.agentConfig,
+        logger: this.logger,
+        onExecute: (context, event) => this.executeAdapter(context, event, adapter),
+        onSessionCleanup: (roomId) => adapter.onCleanup(roomId),
+        onContactEvent: (event) => this.handleContactEvent(event),
+        onParticipantAdded: this._onParticipantAdded,
+        onParticipantRemoved: this._onParticipantRemoved,
+        roomFilter: this._roomFilter,
+        contextFactory: this._contextFactory
+      });
+      await this.runtime.start();
+      this.contactsSubscribed = Boolean(this.link.capabilities.contacts);
+    } catch (error) {
+      try {
+        await this.stop();
+      } catch (stopError) {
+        throw new AggregateError(
+          [error, stopError],
+          "PlatformRuntime failed to start and cleanup also failed"
+        );
+      }
+      throw error;
+    }
+  }
+  async stop(timeoutMs) {
+    if (this.stopping) {
+      return true;
+    }
+    const runtime = this.runtime;
+    const adapter = this.activeAdapter;
+    if (!runtime && !adapter) {
+      return true;
+    }
+    this.stopping = true;
+    this.runtime = void 0;
+    this.contactHandler = void 0;
+    this.contactsSubscribed = false;
+    this.activeAdapter = void 0;
+    let graceful = true;
+    let runtimeError = null;
+    if (runtime) {
+      try {
+        graceful = await runtime.stop(timeoutMs);
+      } catch (error) {
+        runtimeError = error;
+      }
+    }
+    try {
+      await adapter?.onRuntimeStop?.();
+    } catch (error) {
+      if (runtimeError) {
+        throw new AggregateError(
+          [runtimeError, error],
+          "PlatformRuntime stop failed and adapter cleanup also failed"
+        );
+      }
+      throw error;
+    }
+    if (runtimeError) {
+      throw runtimeError instanceof Error ? runtimeError : new Error(String(runtimeError));
+    }
+    this.stopping = false;
+    return graceful;
+  }
+  async runForever() {
+    if (!this.runtime) {
+      throw new RuntimeStateError("Runtime not started");
+    }
+    await this.runtime.waitUntilStopped();
+  }
+  async bootstrapRoomMessage(roomId, message) {
+    if (!this.runtime) {
+      throw new RuntimeStateError("Runtime not started");
+    }
+    await this.runtime.bootstrapRoomMessage(roomId, message);
+  }
+  async resetRoomSession(roomId, timeoutMs) {
+    if (!this.runtime) {
+      throw new RuntimeStateError("Runtime not started");
+    }
+    return await this.runtime.resetRoomSession(roomId, timeoutMs);
+  }
+  async executeAdapter(context, event, adapter) {
+    const input = await this.preprocessor.process(context, event, this._agentId);
+    if (!input) {
+      return;
+    }
+    const messageId = String(input.message.id ?? "");
+    const roomId = input.roomId;
+    const isSynthetic = input.message.senderType === SYNTHETIC_SENDER_TYPE && input.message.senderId === SYNTHETIC_CONTACT_EVENTS_SENDER_ID;
+    const messageMarkOptions = { bestEffort: true };
+    if (messageId && !isSynthetic) {
+      await this.link.markProcessing(roomId, messageId, messageMarkOptions);
+    }
+    try {
+      await adapter.onEvent(input);
+      if (messageId && !isSynthetic) {
+        await this.link.markProcessed(roomId, messageId, messageMarkOptions);
+      }
+    } catch (error) {
+      const label = error instanceof Error ? error.message : String(error);
+      if (messageId && !isSynthetic) {
+        await this.link.markFailed(roomId, messageId, label, messageMarkOptions);
+      }
+      throw error;
+    }
+  }
+  async handleContactEvent(event) {
+    if (this.contactHandler) {
+      await this.contactHandler.handle(event);
+    }
+  }
+};
+
+// src/runtime/shutdown.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
+var GracefulShutdown = class {
+  agent;
+  timeoutMs;
+  onSignal;
+  handlers = /* @__PURE__ */ new Map();
+  shuttingDown = false;
+  constructor(agent, options) {
+    this.agent = agent;
+    this.timeoutMs = options?.timeoutMs === void 0 ? DEFAULT_SHUTDOWN_TIMEOUT_MS : options.timeoutMs;
+    this.onSignal = options?.onSignal;
+  }
+  registerSignals() {
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    for (const signal of signals) {
+      const handler = () => {
+        this.onSignal?.(signal);
+        void this.shutdown(signal);
+      };
+      process.on(signal, handler);
+      this.handlers.set(signal, handler);
+    }
+  }
+  unregisterSignals() {
+    for (const [signal, handler] of this.handlers.entries()) {
+      process.off(signal, handler);
+    }
+    this.handlers.clear();
+  }
+  async withSignals(fn) {
+    this.registerSignals();
+    try {
+      return await fn();
+    } finally {
+      this.unregisterSignals();
+    }
+  }
+  async shutdown(_signal) {
+    if (this.shuttingDown) {
+      process.exit(1);
+    }
+    this.shuttingDown = true;
+    try {
+      await this.agent.stop(this.timeoutMs);
+    } catch {
+      process.exit(1);
+    }
+  }
+};
+async function runWithGracefulShutdown(agent, options) {
+  const shutdown = new GracefulShutdown(agent, options);
+  await shutdown.withSignals(async () => {
+    await agent.run({
+      shutdownTimeoutMs: options?.timeoutMs === void 0 ? DEFAULT_SHUTDOWN_TIMEOUT_MS : options.timeoutMs,
+      signals: false
+    });
+  });
+}
+
+export {
+  ThenvoiLink,
+  Execution,
+  AgentTools,
+  MessageRetryTracker,
+  ExecutionContext,
+  trackRoomJoin,
+  trackRoomLeave,
+  hydrateTrackedRooms,
+  AgentRuntime,
+  DefaultPreprocessor,
+  ContactToolsImpl,
+  HUB_ROOM_SYSTEM_PROMPT,
+  ContactEventHandler,
+  PlatformRuntime,
+  GracefulShutdown,
+  runWithGracefulShutdown
+};