@band-ai/sdk 0.1.4 → 0.1.10

package/dist/{chunk-I5EZG52P.js → chunk-FP237EAG.js}

@@ -4,15 +4,37 @@ import {
   SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
   SYNTHETIC_SENDER_TYPE,
   buildParticipantsMessage
-} from "./chunk-INA6YZTZ.js";
+} from "./chunk-RDM4TE4B.js";
 import {
   CHAT_EVENT_TYPES,
   CHAT_TOOL_NAMES,
+  MEMORY_LIST_SCOPES,
+  MEMORY_SEGMENTS,
+  MEMORY_STATUSES,
+  MEMORY_STORE_SCOPES,
+  MEMORY_SYSTEMS,
   MEMORY_TOOL_NAMES,
+  MEMORY_TYPES,
   TOOL_MODELS,
   assertChatEventType,
-  getToolDescription
-} from "./chunk-GVEQ3RAH.js";
+  expectedList,
+  expectedMemoryTypesForSystem,
+  getToolDescription,
+  isMemoryListScope,
+  isMemorySegment,
+  isMemoryStatus,
+  isMemoryStoreScope,
+  isMemorySystem,
+  isMemoryType,
+  isMemoryTypeForSystem,
+  memoryTypeForSystemError
+} from "./chunk-MLROFDKR.js";
+import {
+  WebSocketDisconnectError,
+  genericCloseReason,
+  parseSupersedeDisconnectReason,
+  parseUpgradeDisconnectReason
+} from "./chunk-US226AS4.js";
 import {
   DEFAULT_REQUEST_OPTIONS,
   FernRestAdapter,
@@ -143,55 +165,117 @@ var payloadSchemas = {
 
 // src/platform/streaming/PhoenixChannelsTransport.ts
 import { Socket } from "phoenix";
+
+// src/platform/streaming/nodeWebSocketFactory.ts
 import { WebSocket as NodeWebSocket } from "ws";
+function createNodeWebSocketFactory(headers) {
+  const Constructor = NodeWebSocket;
+  class ThenvoiNodeWebSocket {
+    constructor(address, protocols) {
+      const socket = new Constructor(address, protocols, headers ? { headers } : void 0);
+      socket.once("unexpected-response", (request, response) => {
+        void emitUpgradeError(socket, request, response);
+      });
+      return socket;
+    }
+  }
+  return ThenvoiNodeWebSocket;
+}
+async function emitUpgradeError(websocket, request, response) {
+  const body = await readResponseBody(response);
+  const error = new Error(
+    `Unexpected server response: ${response.statusCode ?? "unknown"}`
+  );
+  error.status = response.statusCode;
+  error.body = body;
+  error.headers = response.headers;
+  request.destroy();
+  websocket.emit("error", error);
+  websocket.emit("close", 1006, Buffer.alloc(0));
+}
+async function readResponseBody(response) {
+  const chunks = [];
+  for await (const chunk of response) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// src/platform/streaming/PhoenixChannelsTransport.ts
 var PhoenixChannelsTransport = class {
   socket;
+  agentId;
   channels = /* @__PURE__ */ new Map();
   channelRefs = /* @__PURE__ */ new Map();
   pendingJoins = /* @__PURE__ */ new Map();
   logger;
+  onTerminalDisconnect;
   onHandlerError;
   connected = false;
   connectPromise = null;
   connectResolve = null;
+  connectReject = null;
+  lastDisconnectReason = null;
+  terminalDisconnectError = null;
+  runForeverWaiters = /* @__PURE__ */ new Set();
+  stoppingReconnect = false;
+  suppressNextCloseReason = false;
   constructor(options) {
     this.logger = options.logger ?? new NoopLogger();
+    this.agentId = options.agentId;
+    this.onTerminalDisconnect = options.onTerminalDisconnect;
     let wsUrl = options.wsUrl;
     if (wsUrl.endsWith("/websocket")) {
       wsUrl = wsUrl.slice(0, -"/websocket".length);
     }
+    const reconnectAfterMs = options.reconnectAfterMs ?? ((tries) => [1e3, 2e3, 5e3, 1e4, 3e4][tries - 1] ?? 3e4);
     this.socket = new Socket(wsUrl, {
       params: {
-        api_key: options.apiKey,
-        agent_id: options.agentId
+        agent_id: options.agentId,
+        ...options.conflictPolicy ? { on_conflict: options.conflictPolicy } : {}
       },
       heartbeatIntervalMs: options.heartbeatIntervalMs,
-      reconnectAfterMs: options.reconnectAfterMs ?? ((tries) => [1e3, 2e3, 5e3, 1e4, 3e4][tries - 1] ?? 3e4),
-      transport: options.websocketFactory ?? resolveWebSocketFactory()
+      reconnectAfterMs: (tries) => {
+        if (this.terminalDisconnectError) {
+          return Number.POSITIVE_INFINITY;
+        }
+        return reconnectAfterMs(tries);
+      },
+      transport: options.websocketFactory ?? resolveWebSocketFactory(options.apiKey)
     });
     this.socket.onOpen(() => {
-      this.connected = true;
-      this.connectResolve?.();
-      this.connectResolve = null;
-      this.logger.info("Phoenix socket opened", {
-        channels: getSocketChannelCount(this.socket)
-      });
+      void this.handleOpen();
     });
     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.recordSocketClose(event);
     });
     this.socket.onError((event) => {
+      const errorEvent = unwrapErrorEvent(event);
+      const upgradeReason = parseUpgradeDisconnectReason(errorEvent);
+      if (upgradeReason) {
+        if (upgradeReason.retryable) {
+          this.lastDisconnectReason = upgradeReason;
+          this.connectReject?.(new WebSocketDisconnectError(upgradeReason));
+          this.stopReconnectIfNoChannels({ suppressCloseReason: true });
+        } else {
+          this.recordTerminalDisconnect(upgradeReason);
+        }
+        this.logger.warn("Phoenix socket upgrade failed", {
+          reason: upgradeReason
+        });
+        return;
+      }
+      this.connectReject?.(
+        new TransportError("Phoenix socket connection failed", errorEvent)
+      );
+      this.stopReconnectIfNoChannels({ suppressCloseReason: true });
       this.logger.warn("Phoenix socket error", { event });
     });
   }
   async connect() {
+    if (this.terminalDisconnectError) {
+      throw this.terminalDisconnectError;
+    }
     if (this.connected) {
       return;
     }
@@ -215,15 +299,30 @@ var PhoenixChannelsTransport = class {
     await this.connectPromise;
   }
   async disconnect() {
-    for (const topic of this.channels.keys()) {
-      await this.leave(topic);
-    }
+    const results = await Promise.allSettled(
+      [...this.channels.keys()].map((topic) => this.leave(topic))
+    );
     this.socket.disconnect();
     this.connected = false;
+    const failures = [];
+    for (const result of results) {
+      if (result.status === "rejected") {
+        failures.push(result.reason);
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        "Failed to leave one or more Phoenix topics during disconnect"
+      );
+    }
   }
   isConnected() {
     return this.connected;
   }
+  getDisconnectReason() {
+    return this.lastDisconnectReason;
+  }
   async join(topic, handlers) {
     if (this.channels.has(topic)) {
       return;
@@ -259,7 +358,10 @@ var PhoenixChannelsTransport = class {
         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}`)));
+        ).receive(
+          "timeout",
+          () => reject(new TransportError(`Timeout joining topic ${topic}`))
+        );
       });
     } catch (error) {
       for (const [event, ref] of refs) {
@@ -287,19 +389,127 @@ var PhoenixChannelsTransport = class {
       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}`)));
+      ).receive(
+        "timeout",
+        () => reject(new TransportError(`Timeout leaving topic ${topic}`))
+      );
     });
     this.channels.delete(topic);
     this.logger.debug("Left topic", { topic });
   }
   async runForever(signal) {
+    if (this.terminalDisconnectError) {
+      throw this.terminalDisconnectError;
+    }
     if (signal.aborted) {
       return;
     }
-    await new Promise((resolve) => {
-      signal.addEventListener("abort", () => resolve(), { once: true });
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const abortController = new AbortController();
+      const waiter = {
+        reject: (error) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          this.runForeverWaiters.delete(waiter);
+          abortController.abort();
+          reject(error);
+        }
+      };
+      this.runForeverWaiters.add(waiter);
+      signal.addEventListener(
+        "abort",
+        () => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          this.runForeverWaiters.delete(waiter);
+          resolve();
+        },
+        { once: true, signal: abortController.signal }
+      );
+    });
+  }
+  async handleOpen() {
+    try {
+      await this.subscribeAgentControl();
+    } catch (error) {
+      this.connected = false;
+      this.socket.disconnect();
+      this.connectReject?.(
+        error instanceof Error ? error : new TransportError(String(error))
+      );
+      this.logger.warn("Failed to join mandatory agent_control channel", {
+        error
+      });
+      return;
+    }
+    this.connected = true;
+    this.connectResolve?.();
+    this.connectResolve = null;
+    this.connectReject = null;
+    this.logger.info("Phoenix socket opened", {
+      channels: getSocketChannelCount(this.socket)
     });
   }
+  stopReconnectIfNoChannels(options = {}) {
+    if (this.stoppingReconnect || getSocketChannelCount(this.socket) !== 0) {
+      return;
+    }
+    this.suppressNextCloseReason = options.suppressCloseReason ?? false;
+    this.stoppingReconnect = true;
+    this.socket.disconnect();
+    this.stoppingReconnect = false;
+  }
+  async subscribeAgentControl() {
+    if (!this.agentId) {
+      return;
+    }
+    await this.join(`agent_control:${this.agentId}`, {
+      supersede: (payload) => {
+        const reason = parseSupersedeDisconnectReason(payload);
+        if (!reason) {
+          this.logger.warn("Invalid agent_control supersede payload", {
+            payload
+          });
+          return;
+        }
+        this.recordTerminalDisconnect(reason);
+      }
+    });
+  }
+  recordSocketClose(event) {
+    this.connected = false;
+    const suppressCloseReason = this.suppressNextCloseReason;
+    this.suppressNextCloseReason = false;
+    this.stopReconnectIfNoChannels();
+    if (!suppressCloseReason && !this.terminalDisconnectError && !this.lastDisconnectReason) {
+      this.lastDisconnectReason = genericCloseReason(event);
+    }
+    this.logger.info("Phoenix socket closed", {
+      code: event?.code ?? null,
+      reason: event?.reason ?? null,
+      platformReason: this.lastDisconnectReason
+    });
+  }
+  recordTerminalDisconnect(reason) {
+    if (this.terminalDisconnectError) {
+      return;
+    }
+    const error = new WebSocketDisconnectError(reason);
+    this.lastDisconnectReason = reason;
+    this.terminalDisconnectError = error;
+    this.onTerminalDisconnect?.(reason);
+    this.connectReject?.(error);
+    for (const waiter of this.runForeverWaiters) {
+      waiter.reject(error);
+    }
+    this.runForeverWaiters.clear();
+    this.socket.disconnect();
+  }
   async waitForConnection(timeoutMs = 1e4) {
     if (this.connected) {
       return;
@@ -307,20 +517,43 @@ var PhoenixChannelsTransport = class {
     await new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         this.connectResolve = null;
-        reject(new TransportError("Timed out waiting for Phoenix socket connection"));
+        this.connectReject = null;
+        reject(
+          new TransportError("Timed out waiting for Phoenix socket connection")
+        );
       }, timeoutMs);
       this.connectResolve = () => {
         clearTimeout(timeout);
+        this.connectReject = null;
         resolve();
       };
+      this.connectReject = (error) => {
+        clearTimeout(timeout);
+        this.connectResolve = null;
+        this.connectReject = null;
+        reject(
+          error instanceof Error ? error : new TransportError(String(error))
+        );
+      };
     });
   }
 };
-function resolveWebSocketFactory() {
+function resolveWebSocketFactory(apiKey) {
   if (typeof process !== "undefined" && process.versions?.node) {
-    return NodeWebSocket;
+    return createNodeWebSocketFactory({ "x-api-key": apiKey });
+  }
+  throw new TransportError(
+    "Phoenix WebSocket API-key auth requires a WebSocket transport that can set handshake headers."
+  );
+}
+function unwrapErrorEvent(event) {
+  if (!isErrorEvent(event)) {
+    return event;
   }
-  return WebSocket;
+  return event.error;
+}
+function isErrorEvent(event) {
+  return typeof event === "object" && event !== null && "error" in event;
 }
 function removeSocketChannel(socket, channel) {
   const candidate = socket;
@@ -342,6 +575,12 @@ function deriveDefaultRestUrl(wsUrl) {
   const protocol = parsed.protocol === "ws:" ? "http:" : "https:";
   return `${protocol}//${parsed.host}`;
 }
+function roomTopics(roomId) {
+  return {
+    chat: `chat_room:${roomId}`,
+    participants: `room_participants:${roomId}`
+  };
+}
 function toPlatformMessage(roomId, message) {
   return {
     id: message.id,
@@ -368,6 +607,8 @@ var ThenvoiLink = class {
   eventQueue = [];
   waiters = [];
   connected = false;
+  lastDisconnectReason = null;
+  terminalDisconnectError = null;
   constructor(options) {
     this.agentId = options.agentId;
     this.apiKey = options.apiKey;
@@ -389,17 +630,35 @@ var ThenvoiLink = class {
       wsUrl: this.wsUrl,
       apiKey: this.apiKey,
       agentId: this.agentId,
-      logger: this.logger
+      logger: this.logger,
+      conflictPolicy: options.conflictPolicy,
+      onTerminalDisconnect: (reason) => {
+        this.recordDisconnectReason(reason);
+      }
     });
   }
   isConnected() {
     return this.connected;
   }
+  getDisconnectReason() {
+    return this.lastDisconnectReason;
+  }
   async connect() {
     if (this.connected) {
       return;
     }
-    await this.transport.connect();
+    try {
+      await this.transport.connect();
+    } catch (error) {
+      if (error instanceof WebSocketDisconnectError) {
+        if (error.reason.retryable) {
+          this.lastDisconnectReason = error.reason;
+        } else {
+          this.recordDisconnectError(error);
+        }
+      }
+      throw error;
+    }
     this.connected = true;
   }
   async disconnect() {
@@ -413,8 +672,23 @@ var ThenvoiLink = class {
     this.connected = false;
   }
   async runForever(signal) {
+    if (this.terminalDisconnectError) {
+      throw this.terminalDisconnectError;
+    }
     await this.transport.runForever(signal);
   }
+  recordDisconnectReason(reason) {
+    this.recordDisconnectError(new WebSocketDisconnectError(reason));
+  }
+  recordDisconnectError(error) {
+    this.connected = false;
+    this.lastDisconnectReason = error.reason;
+    this.terminalDisconnectError = error;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      waiter?.reject(error);
+    }
+  }
   queueEvent(event) {
     const waiter = this.waiters.shift();
     if (waiter) {
@@ -439,32 +713,42 @@ var ThenvoiLink = class {
     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);
-      }
-    });
+    await this.joinRoomTopics(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}`);
+    const topics = roomTopics(roomId);
+    await this.transport.leave(topics.chat);
+    await this.transport.leave(topics.participants);
     this.subscribedRooms.delete(roomId);
   }
+  async joinRoomTopics(roomId) {
+    const topics = roomTopics(roomId);
+    await this.transport.join(topics.chat, {
+      message_created: (payload) => {
+        this.emit("message_created", payload, roomId);
+      }
+    });
+    try {
+      await this.transport.join(topics.participants, {
+        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);
+        }
+      });
+    } catch (error) {
+      await this.transport.leave(topics.chat);
+      throw error;
+    }
+  }
   async subscribeAgentContacts() {
     assertCapability(this.capabilities, "contacts", "Contacts streaming");
     await this.transport.join(`agent_contacts:${this.agentId}`, {
@@ -486,6 +770,9 @@ var ThenvoiLink = class {
     await this.transport.leave(`agent_contacts:${this.agentId}`);
   }
   async nextEvent(signal) {
+    if (this.terminalDisconnectError) {
+      throw this.terminalDisconnectError;
+    }
     if (signal?.aborted) {
       return null;
     }
@@ -493,19 +780,19 @@ var ThenvoiLink = class {
     if (queued) {
       return queued;
     }
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       let settled = false;
       const onAbort = () => {
         const index = this.waiters.indexOf(waiter);
         if (index >= 0) {
           this.waiters.splice(index, 1);
         }
-        finalize(null);
+        finalizeResolve(null);
       };
       const cleanup = () => {
         signal?.removeEventListener("abort", onAbort);
       };
-      const finalize = (event) => {
+      const finalizeResolve = (event) => {
         if (settled) {
           return;
         }
@@ -513,8 +800,17 @@ var ThenvoiLink = class {
         cleanup();
         resolve(event);
       };
+      const finalizeReject = (error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        reject(error);
+      };
       const waiter = {
-        resolve: finalize,
+        resolve: finalizeResolve,
+        reject: finalizeReject,
         cleanup
       };
       this.waiters.push(waiter);
@@ -526,7 +822,10 @@ var ThenvoiLink = class {
       next: async () => {
         const value = await this.nextEvent();
         if (value === null) {
-          return { done: true, value: void 0 };
+          return {
+            done: true,
+            value: void 0
+          };
         }
         return { done: false, value };
       }
@@ -608,7 +907,9 @@ var ThenvoiLink = class {
   }
   async listChats(request, requestOptions) {
     if (!this.rest.listChats) {
-      throw new UnsupportedFeatureError("Chat listing is not available in current REST adapter");
+      throw new UnsupportedFeatureError(
+        "Chat listing is not available in current REST adapter"
+      );
     }
     return this.rest.listChats(request, requestOptions);
   }
@@ -968,40 +1269,6 @@ var CONTACT_REQUEST_ACTIONS = /* @__PURE__ */ new Set([
   "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;
@@ -1579,6 +1846,9 @@ var AgentTools = class {
     const status = this.normalizeOptionalMemoryStatus(arguments_.status);
     const subjectId = this.normalizeOptionalString(arguments_.subject_id);
     const contentQuery = this.normalizeOptionalString(arguments_.content_query);
+    if (system && type && !isMemoryTypeForSystem(system, type)) {
+      throw new ValidationError(memoryTypeForSystemError(system));
+    }
     return {
       ...subjectId ? { subject_id: subjectId } : {},
       ...scope ? { scope } : {},
@@ -1600,13 +1870,21 @@ var AgentTools = class {
     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");
+      throw new ValidationError(`system must be one of: ${expectedList(MEMORY_SYSTEMS)}`);
     }
     if (!type) {
-      throw new ValidationError("type must be one of: iconic, echoic, haptic, episodic, semantic, procedural");
+      throw new ValidationError(`type must be one of: ${expectedList(MEMORY_TYPES)}`);
+    }
+    if (!isMemoryTypeForSystem(system, type)) {
+      throw new ValidationError(memoryTypeForSystemError(system));
     }
     if (!segment) {
-      throw new ValidationError("segment must be one of: user, agent, tool, guideline");
+      throw new ValidationError(`segment must be one of: ${expectedList(MEMORY_SEGMENTS)}`);
+    }
+    if (scope === "subject" && !subjectId) {
+      throw new ValidationError(
+        'scope="subject" requires a subject_id (the UUID of the person or agent the memory is about). If you do not have a concrete subject UUID, retry with scope="organization" and omit subject_id. Do not invent a UUID.'
+      );
     }
     return {
       content,
@@ -1686,8 +1964,8 @@ var AgentTools = class {
     if (!normalized) {
       return void 0;
     }
-    if (!isListMemoryScope(normalized)) {
-      throw new ValidationError("scope must be one of: subject, organization, all");
+    if (!isMemoryListScope(normalized)) {
+      throw new ValidationError(`scope must be one of: ${expectedList(MEMORY_LIST_SCOPES)}`);
     }
     return normalized;
   }
@@ -1697,7 +1975,7 @@ var AgentTools = class {
       return void 0;
     }
     if (!isMemorySystem(normalized)) {
-      throw new ValidationError("system must be one of: sensory, working, long_term");
+      throw new ValidationError(`system must be one of: ${expectedList(MEMORY_SYSTEMS)}`);
     }
     return normalized;
   }
@@ -1707,7 +1985,7 @@ var AgentTools = class {
       return void 0;
     }
     if (!isMemoryType(normalized)) {
-      throw new ValidationError("type must be one of: iconic, echoic, haptic, episodic, semantic, procedural");
+      throw new ValidationError(`type must be one of: ${expectedList(MEMORY_TYPES)}`);
     }
     return normalized;
   }
@@ -1717,7 +1995,7 @@ var AgentTools = class {
       return void 0;
     }
     if (!isMemorySegment(normalized)) {
-      throw new ValidationError("segment must be one of: user, agent, tool, guideline");
+      throw new ValidationError(`segment must be one of: ${expectedList(MEMORY_SEGMENTS)}`);
     }
     return normalized;
   }
@@ -1727,7 +2005,7 @@ var AgentTools = class {
       return void 0;
     }
     if (!isMemoryStatus(normalized)) {
-      throw new ValidationError("status must be one of: active, superseded, archived, all");
+      throw new ValidationError(`status must be one of: ${expectedList(MEMORY_STATUSES)}`);
     }
     return normalized;
   }
@@ -1736,8 +2014,8 @@ var AgentTools = class {
     if (!normalized) {
       return void 0;
     }
-    if (!isStoreMemoryScope(normalized)) {
-      throw new ValidationError("scope must be one of: subject, organization");
+    if (!isMemoryStoreScope(normalized)) {
+      throw new ValidationError(`scope must be one of: ${expectedList(MEMORY_STORE_SCOPES)}`);
     }
     return normalized;
   }
@@ -1745,24 +2023,6 @@ var AgentTools = class {
 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;
@@ -1802,17 +2062,19 @@ function validateToolArgs(toolName, args) {
     }
   }
   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.system === "string" && !isMemorySystem(args.system)) {
+      errors.push(`system: Invalid value '${args.system}'. Expected one of: ${expectedList(MEMORY_SYSTEMS)}`);
     }
-    if (typeof args.type === "string" && !validTypes.includes(args.type)) {
-      errors.push(`type: Invalid value '${args.type}'. Expected one of: ${validTypes.join(", ")}`);
+    if (typeof args.type === "string" && !isMemoryType(args.type)) {
+      errors.push(`type: Invalid value '${args.type}'. Expected one of: ${expectedList(MEMORY_TYPES)}`);
     }
-    if (typeof args.segment === "string" && !validSegments.includes(args.segment)) {
-      errors.push(`segment: Invalid value '${args.segment}'. Expected one of: ${validSegments.join(", ")}`);
+    if (typeof args.system === "string" && isMemorySystem(args.system) && typeof args.type === "string" && isMemoryType(args.type) && !isMemoryTypeForSystem(args.system, args.type)) {
+      errors.push(
+        `type: Invalid value '${args.type}' for system '${args.system}'. Expected one of: ${expectedMemoryTypesForSystem(args.system)}`
+      );
+    }
+    if (typeof args.segment === "string" && !isMemorySegment(args.segment)) {
+      errors.push(`segment: Invalid value '${args.segment}'. Expected one of: ${expectedList(MEMORY_SEGMENTS)}`);
     }
   }
   if (errors.length > 0) {
@@ -2349,7 +2611,7 @@ var AgentRuntime = class {
     await this.link.disconnect();
   }
   async stop(timeoutMs) {
-    if (!this.running || this.stopping) {
+    if (this.stopping || !this.running && !this.fatalError) {
       return true;
     }
     this.stopping = true;
@@ -2369,7 +2631,8 @@ var AgentRuntime = class {
       }
     }
     for (const roomId of [...this.subscribedRooms]) {
-      await this.leaveTrackedRoom(roomId);
+      const remaining = deadline === void 0 ? void 0 : Math.max(0, deadline - Date.now());
+      await this.leaveTrackedRoom(roomId, remaining);
     }
     for (const roomId of [...this.contexts.keys()]) {
       await this.onSessionCleanup(roomId);
@@ -2405,7 +2668,13 @@ var AgentRuntime = class {
   }
   async consumeLoop(signal) {
     while (!signal.aborted) {
-      const event = await this.link.nextEvent(signal);
+      let event;
+      try {
+        event = await this.link.nextEvent(signal);
+      } catch (error) {
+        await this.failRuntime(error, syntheticRuntimeFailureEvent(this.agentId));
+        return;
+      }
       if (!event) {
         return;
       }
@@ -2568,13 +2837,13 @@ var AgentRuntime = class {
       }
     });
   }
-  async leaveTrackedRoom(roomId) {
+  async leaveTrackedRoom(roomId, timeoutMs) {
     await trackRoomLeave({
       link: this.link,
       roomId,
       trackedRooms: this.subscribedRooms,
       onLeft: async (leftRoomId) => {
-        await this.executions.get(leftRoomId)?.stop();
+        await this.executions.get(leftRoomId)?.stop(timeoutMs);
         this.contexts.delete(leftRoomId);
         this.executions.delete(leftRoomId);
         await this.onSessionCleanup(leftRoomId);
@@ -2611,6 +2880,23 @@ var AgentRuntime = class {
     }
   }
 };
+function syntheticRuntimeFailureEvent(agentId) {
+  return {
+    type: "message_created",
+    roomId: null,
+    payload: {
+      id: "runtime-failed",
+      content: "",
+      sender_id: 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()
+    }
+  };
+}
 function assertNever(value) {
   throw new Error(`Unhandled platform event: ${JSON.stringify(value)}`);
 }
@@ -3453,7 +3739,8 @@ var PlatformRuntime = class {
         agentId: this._agentId,
         apiKey: this._apiKey,
         wsUrl: this._wsUrl,
-        restUrl: this._restUrl
+        restUrl: this._restUrl,
+        logger: this.logger
       });
     }
     if (this.configuredIdentity) {
@@ -3670,6 +3957,7 @@ async function runWithGracefulShutdown(agent, options) {
 }
 
 export {
+  deriveDefaultRestUrl,
   ThenvoiLink,
   Execution,
   AgentTools,