@band-ai/sdk 0.1.6 → 0.1.10

package/dist/runtime.cjs

@@ -38,6 +38,7 @@ __export(runtime_exports, {
   HUB_ROOM_SYSTEM_PROMPT: () => HUB_ROOM_SYSTEM_PROMPT,
   HistoryProvider: () => HistoryProvider,
   MCP_TOOL_PREFIX: () => MCP_TOOL_PREFIX,
+  MEMORY_SECTION: () => MEMORY_SECTION,
   MEMORY_TOOL_NAMES: () => MEMORY_TOOL_NAMES,
   MessageRetryTracker: () => MessageRetryTracker,
   ParticipantTracker: () => ParticipantTracker,
@@ -1172,6 +1173,108 @@ var DEFAULT_AGENT_TOOLS_CAPABILITIES = {
   memory: true
 };
 
+// src/contracts/memory.ts
+var SENSORY_MEMORY_TYPES = [
+  "iconic",
+  // Visual input
+  "echoic",
+  // Auditory input
+  "haptic"
+  // Tactile input
+];
+var COGNITIVE_MEMORY_TYPES = [
+  "episodic",
+  // Events that occurred
+  "semantic",
+  // Facts, preferences, learned knowledge
+  "procedural"
+  // How to perform tasks
+];
+function namedValues(values) {
+  return Object.fromEntries(values.map((value) => [value, value]));
+}
+var MEMORY_SYSTEM_TYPES = {
+  sensory: SENSORY_MEMORY_TYPES,
+  // Brief sensory inputs
+  working: COGNITIVE_MEMORY_TYPES,
+  // Short-term session context
+  long_term: COGNITIVE_MEMORY_TYPES
+  // Persistent cross-conversation memory
+};
+var MEMORY_SYSTEMS = Object.keys(MEMORY_SYSTEM_TYPES);
+var MEMORY_TYPES = [
+  ...SENSORY_MEMORY_TYPES,
+  ...COGNITIVE_MEMORY_TYPES
+];
+var MEMORY_SEGMENTS = [
+  "user",
+  // User preferences or profile info
+  "agent",
+  // Facts or events about agents/entities
+  "tool",
+  // Tool usage or task procedures
+  "guideline"
+  // Behavioral rules or policies
+];
+var MEMORY_STORE_SCOPES = [
+  "subject",
+  // About one person/agent; requires subject_id
+  "organization"
+  // Shared org-wide
+];
+var MEMORY_LIST_SCOPES = [
+  "subject",
+  // Subject-scoped memories only
+  "organization",
+  // Organization-scoped memories only
+  "all"
+  // Both scopes (no scope filter)
+];
+var MEMORY_STATUSES = [
+  "active",
+  // Normal, visible memories
+  "superseded",
+  // Outdated; soft-deleted via thenvoi_supersede_memory
+  "archived",
+  // Hidden but preserved via thenvoi_archive_memory
+  "all"
+  // Any status (no filter)
+];
+var MEMORY_SYSTEM = namedValues(MEMORY_SYSTEMS);
+var MEMORY_TYPE = namedValues(MEMORY_TYPES);
+var MEMORY_SEGMENT = namedValues(MEMORY_SEGMENTS);
+var MEMORY_STORE_SCOPE = namedValues(MEMORY_STORE_SCOPES);
+function isMemorySystem(value) {
+  return MEMORY_SYSTEMS.includes(value);
+}
+function isMemoryType(value) {
+  return MEMORY_TYPES.includes(value);
+}
+function isMemoryTypeForSystem(system, type) {
+  return MEMORY_SYSTEM_TYPES[system].includes(type);
+}
+function isMemorySegment(value) {
+  return MEMORY_SEGMENTS.includes(value);
+}
+function isMemoryStoreScope(value) {
+  return MEMORY_STORE_SCOPES.includes(value);
+}
+function isMemoryListScope(value) {
+  return MEMORY_LIST_SCOPES.includes(value);
+}
+function isMemoryStatus(value) {
+  return MEMORY_STATUSES.includes(value);
+}
+function expectedList(values) {
+  return values.join(", ");
+}
+function expectedMemoryTypesForSystem(system) {
+  return expectedList(MEMORY_SYSTEM_TYPES[system]);
+}
+function memoryTypeForSystemError(system) {
+  return `type must be one of: ${expectedMemoryTypesForSystem(system)} for system "${system}"`;
+}
+
 // src/runtime/tools/schemas.ts
 var TOOL_MODELS = {
   thenvoi_send_message: {
@@ -1359,29 +1462,22 @@ var TOOL_MODELS = {
       },
       scope: {
         type: "string",
-        enum: ["subject", "organization", "all"],
+        enum: [...MEMORY_LIST_SCOPES],
         description: "Filter by scope."
       },
       system: {
         type: "string",
-        enum: ["sensory", "working", "long_term"],
+        enum: [...MEMORY_SYSTEMS],
         description: "Filter by memory system."
       },
       type: {
         type: "string",
-        enum: [
-          "iconic",
-          "echoic",
-          "haptic",
-          "episodic",
-          "semantic",
-          "procedural"
-        ],
+        enum: [...MEMORY_TYPES],
         description: "Filter by memory type."
       },
       segment: {
         type: "string",
-        enum: ["user", "agent", "tool", "guideline"],
+        enum: [...MEMORY_SEGMENTS],
         description: "Filter by segment."
       },
       content_query: {
@@ -1396,7 +1492,7 @@ var TOOL_MODELS = {
       },
       status: {
         type: "string",
-        enum: ["active", "superseded", "archived", "all"],
+        enum: [...MEMORY_STATUSES],
         description: "Filter by status."
       }
     },
@@ -1411,24 +1507,17 @@ var TOOL_MODELS = {
       },
       system: {
         type: "string",
-        enum: ["sensory", "working", "long_term"],
+        enum: [...MEMORY_SYSTEMS],
         description: "Memory system tier."
       },
       type: {
         type: "string",
-        enum: [
-          "iconic",
-          "echoic",
-          "haptic",
-          "episodic",
-          "semantic",
-          "procedural"
-        ],
+        enum: [...MEMORY_TYPES],
         description: "Memory type (must be valid for selected system)."
       },
       segment: {
         type: "string",
-        enum: ["user", "agent", "tool", "guideline"],
+        enum: [...MEMORY_SEGMENTS],
         description: "Logical segment."
       },
       thought: {
@@ -1437,7 +1526,7 @@ var TOOL_MODELS = {
       },
       scope: {
         type: "string",
-        enum: ["subject", "organization"],
+        enum: [...MEMORY_STORE_SCOPES],
         description: "Visibility scope."
       },
       subject_id: {
@@ -1547,40 +1636,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;
@@ -2158,6 +2213,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 } : {},
@@ -2179,13 +2237,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,
@@ -2265,8 +2331,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;
   }
@@ -2276,7 +2342,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;
   }
@@ -2286,7 +2352,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;
   }
@@ -2296,7 +2362,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;
   }
@@ -2306,7 +2372,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;
   }
@@ -2315,8 +2381,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;
   }
@@ -2324,24 +2390,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;
@@ -2381,17 +2429,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) {
@@ -2471,7 +2521,7 @@ function replaceUuidMentions(content, participants) {
     const participantId = participant.id;
     const handle = participant.handle;
     if (typeof participantId === "string" && typeof handle === "string") {
-      next = next.replaceAll(`@[[${participantId}]]`, `@${handle}`);
+      next = next.replaceAll(`@[[${participantId}]]`, ensureHandlePrefix(handle) ?? "");
     }
   }
   return next;
@@ -2503,7 +2553,9 @@ function buildParticipantsMessage(participants) {
     const participantType = String(participant.type ?? "Unknown");
     const participantName = String(participant.name ?? "Unknown");
     const participantHandle = String(participant.handle ?? "Unknown");
-    lines.push(`- @${participantHandle} \u2014 ${participantName} (${participantType})`);
+    lines.push(
+      `- ${ensureHandlePrefix(participantHandle) ?? ""} \u2014 ${participantName} (${participantType})`
+    );
   }
   lines.push("");
   lines.push(
@@ -2982,7 +3034,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;
@@ -3002,7 +3054,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);
@@ -3038,7 +3091,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;
       }
@@ -3201,13 +3260,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);
@@ -3244,6 +3303,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 assertNever2(value) {
   throw new Error(`Unhandled platform event: ${JSON.stringify(value)}`);
 }
@@ -4185,55 +4261,241 @@ var payloadSchemas = {
 
 // src/platform/streaming/PhoenixChannelsTransport.ts
 var import_phoenix = require("phoenix");
+
+// src/platform/streaming/disconnectReason.ts
+var import_zod2 = require("zod");
+var UPGRADE_CODES = [
+  "invalid_on_conflict",
+  "connection_conflict",
+  "too_many_requests",
+  "tracking_failed"
+];
+var UPGRADE_REASONS = {
+  invalid_on_conflict: {
+    status: 400,
+    message: "Invalid websocket conflict policy.",
+    retryable: false
+  },
+  connection_conflict: {
+    status: 409,
+    message: "Websocket connection conflict.",
+    retryable: false
+  },
+  too_many_requests: {
+    status: 429,
+    message: "Too many websocket connection attempts.",
+    retryable: true
+  },
+  tracking_failed: {
+    status: 503,
+    message: "Websocket connection tracking failed.",
+    retryable: true
+  }
+};
+var upgradeErrorSchema = import_zod2.z.object({
+  status: import_zod2.z.number(),
+  body: import_zod2.z.preprocess(
+    (body) => {
+      if (typeof body !== "string") {
+        return body;
+      }
+      try {
+        return JSON.parse(body);
+      } catch {
+        return null;
+      }
+    },
+    import_zod2.z.object({
+      error: import_zod2.z.object({
+        code: import_zod2.z.enum(UPGRADE_CODES),
+        message: import_zod2.z.string().optional(),
+        retry_after: import_zod2.z.number().nullable().optional(),
+        request_id: import_zod2.z.string().nullable().optional()
+      })
+    })
+  ),
+  headers: import_zod2.z.record(import_zod2.z.unknown()).optional()
+});
+var WebSocketDisconnectError = class extends Error {
+  reason;
+  constructor(reason) {
+    super(reason.message);
+    this.name = "WebSocketDisconnectError";
+    this.reason = reason;
+  }
+};
+function parseSupersedeDisconnectReason(payload) {
+  if (typeof payload.reason !== "string" || typeof payload.message !== "string") {
+    return null;
+  }
+  return {
+    source: "agent_control",
+    code: payload.reason,
+    message: payload.message,
+    retryable: false,
+    retryAfter: typeof payload.retry_after === "number" ? payload.retry_after : null,
+    targetSocketId: typeof payload.target_socket_id === "string" ? payload.target_socket_id : null,
+    correlationId: typeof payload.correlation_id === "string" ? payload.correlation_id : null
+  };
+}
+function parseUpgradeDisconnectReason(event) {
+  const parsed = upgradeErrorSchema.safeParse(event);
+  if (!parsed.success) {
+    return null;
+  }
+  const { status, body, headers } = parsed.data;
+  const {
+    code,
+    message,
+    retry_after: retryAfter,
+    request_id: requestId
+  } = body.error;
+  const reason = UPGRADE_REASONS[code];
+  if (status !== reason.status) {
+    return null;
+  }
+  return {
+    source: "upgrade",
+    status: reason.status,
+    code,
+    message: message ?? reason.message,
+    retryable: reason.retryable,
+    retryAfter: retryAfter ?? retryAfterFromHeaders(headers),
+    requestId: requestId ?? null
+  };
+}
+function genericCloseReason(event) {
+  return {
+    source: "websocket_close",
+    code: "websocket.closed",
+    message: "Phoenix socket closed without a platform disconnect reason.",
+    retryable: true,
+    closeCode: typeof event?.code === "number" ? event.code : null,
+    closeReason: typeof event?.reason === "string" && event.reason.length > 0 ? event.reason : null
+  };
+}
+function retryAfterFromHeaders(headers) {
+  const value = headers?.["retry-after"] ?? headers?.["Retry-After"];
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const seconds = Number(value);
+    return Number.isFinite(seconds) ? seconds : null;
+  }
+  return null;
+}
+
+// src/platform/streaming/nodeWebSocketFactory.ts
 var import_ws = require("ws");
+function createNodeWebSocketFactory(headers) {
+  const Constructor = import_ws.WebSocket;
+  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 import_phoenix.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;
     }
@@ -4257,15 +4519,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;
@@ -4301,7 +4578,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) {
@@ -4329,19 +4609,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;
@@ -4349,20 +4737,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 import_ws.WebSocket;
+    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;
@@ -4384,6 +4795,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,
@@ -4410,6 +4827,8 @@ var ThenvoiLink = class {
   eventQueue = [];
   waiters = [];
   connected = false;
+  lastDisconnectReason = null;
+  terminalDisconnectError = null;
   constructor(options) {
     this.agentId = options.agentId;
     this.apiKey = options.apiKey;
@@ -4431,17 +4850,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() {
@@ -4455,8 +4892,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) {
@@ -4481,32 +4933,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}`, {
@@ -4528,6 +4990,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;
     }
@@ -4535,19 +5000,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;
         }
@@ -4555,8 +5020,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);
@@ -4568,7 +5042,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 };
       }
@@ -4650,7 +5127,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);
   }
@@ -4827,7 +5306,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) {
@@ -5104,16 +5584,15 @@ var RoomPresence = class {
   }
 };
 
-// src/runtime/prompts.ts
-var BASE_INSTRUCTIONS = `
+// src/runtime/prompts/base.ts
+var ENVIRONMENT_SECTION = `
 ## Environment
 
 Multi-participant chat. Messages show sender: [Name]: content.
 Messages prefixed with [System]: are platform updates (participant changes, contact updates, etc.) \u2014 not messages from users.
 Use \`thenvoi_send_message(content, mentions)\` to respond. Plain text output is not delivered.
-Mentions use handles: @<username> for users, @<username>/<agent-name> for agents.
-
-## CRITICAL: Delegate When You Cannot Help Directly
+Mentions use handles: @<username> for users, @<username>/<agent-name> for agents.`;
+var MULTI_AGENT_RULES_SECTION = `## CRITICAL: Delegate When You Cannot Help Directly
 
 You have NO internet access and NO real-time data. When asked about weather, news, stock prices,
 or any current information you cannot answer directly:
@@ -5139,14 +5618,12 @@ Only remove agents if the user explicitly requests it.
 When someone asks you to get information from another agent:
 1. Ask the other agent for the information
 2. When you receive the response, IMMEDIATELY relay it back to the ORIGINAL REQUESTER
-3. Do NOT just thank the helper agent - the requester is waiting for their answer!
-
-## IMPORTANT: Always Share Your Thinking
+3. Do NOT just thank the helper agent - the requester is waiting for their answer!`;
+var THINKING_SECTION = `## IMPORTANT: Always Share Your Thinking
 
 You MUST call \`thenvoi_send_event(content, message_type="thought")\` BEFORE every action.
-This is required so users can see your reasoning process.
-
-## Examples
+This is required so users can see your reasoning process.`;
+var EXAMPLES_SECTION = `## Examples
 
 ### Simple question - answer directly
 [John Doe]: What's 2+2?
@@ -5179,8 +5656,73 @@ This is required so users can see your reasoning process.
 
 [Weather Agent]: London is 8\xB0C and rainy.
 -> thenvoi_send_event("Got London weather. Relaying to John Doe.", message_type="thought")
--> thenvoi_send_message("London is 8\xB0C and rainy.", mentions=["@john"])
-`;
+-> thenvoi_send_message("London is 8\xB0C and rainy.", mentions=["@john"])`;
+var BASE_INSTRUCTIONS = [
+  ENVIRONMENT_SECTION,
+  MULTI_AGENT_RULES_SECTION,
+  THINKING_SECTION,
+  EXAMPLES_SECTION
+].join("\n\n") + "\n";
+
+// src/runtime/prompts/memory.ts
+var MEMORY_INTRO = `## Memory Tools
+
+You have access to memory tools for storing and retrieving information
+across conversations. Use \`thenvoi_store_memory\` to persist important
+information and \`thenvoi_list_memories\` / \`thenvoi_get_memory\` to recall it.
+Use \`thenvoi_supersede_memory\` to mark outdated memories and
+\`thenvoi_archive_memory\` to hide memories that should be preserved.`;
+function longTermPattern(label, type, segment, scope) {
+  return {
+    label,
+    system: MEMORY_SYSTEM.long_term,
+    type,
+    segment,
+    scope
+  };
+}
+var COMMON_MEMORY_PATTERNS = [
+  longTermPattern("Facts learned about a specific agent/entity", MEMORY_TYPE.semantic, MEMORY_SEGMENT.agent, MEMORY_STORE_SCOPE.subject),
+  longTermPattern("Events involving a specific person/agent", MEMORY_TYPE.episodic, MEMORY_SEGMENT.agent, MEMORY_STORE_SCOPE.subject),
+  longTermPattern("A user's preferences or profile info", MEMORY_TYPE.semantic, MEMORY_SEGMENT.user, MEMORY_STORE_SCOPE.subject),
+  longTermPattern("Org-wide knowledge or how to perform a task", MEMORY_TYPE.procedural, MEMORY_SEGMENT.tool, MEMORY_STORE_SCOPE.organization)
+];
+function renderMemoryPattern(pattern) {
+  return `- ${pattern.label}: \`system="${pattern.system}"\`, \`type="${pattern.type}"\`, \`segment="${pattern.segment}"\`, \`scope="${pattern.scope}"\``;
+}
+var MEMORY_COMMON_PATTERNS = [
+  "Common patterns:",
+  ...COMMON_MEMORY_PATTERNS.map(renderMemoryPattern)
+].join("\n");
+var MEMORY_SCOPE_GUIDANCE = `Prefer \`scope="${MEMORY_STORE_SCOPE.subject}"\` whenever the memory is about a specific person or agent, so it
+stays attached to that subject rather than leaking org-wide. Storing with \`scope="${MEMORY_STORE_SCOPE.subject}"\` requires a
+real \`subject_id\` UUID, so resolve it first via \`thenvoi_lookup_peers\` or the participant list.
+Reserve \`scope="${MEMORY_STORE_SCOPE.organization}"\` for knowledge that is genuinely shared across the whole organization and
+is not about any one subject.`;
+function quoteChoices(values) {
+  return values.map((value) => `\`"${value}"\``).join(" | ");
+}
+function memoryTypeLines() {
+  return Object.entries(MEMORY_SYSTEM_TYPES).map(([system, types]) => `  - ${system}: ${quoteChoices(types)}`).join("\n");
+}
+function buildMemorySection() {
+  const storeMemoryProps = TOOL_MODELS.thenvoi_store_memory.properties;
+  const systems = storeMemoryProps.system.enum;
+  const segments = storeMemoryProps.segment.enum;
+  const scopes = storeMemoryProps.scope.enum;
+  const fieldRules = `When calling \`thenvoi_store_memory\`, the \`system\`, \`type\`, \`segment\`, and \`scope\` fields
+must use these exact values (case-sensitive):
+
+- **system**: ${quoteChoices(systems)}
+- **type** (must match the chosen system):
+${memoryTypeLines()}
+- **segment**: ${quoteChoices(segments)}
+- **scope**: ${quoteChoices(scopes)}`;
+  return [MEMORY_INTRO, fieldRules, MEMORY_COMMON_PATTERNS, MEMORY_SCOPE_GUIDANCE].join("\n\n");
+}
+var MEMORY_SECTION = buildMemorySection();
+
+// src/runtime/prompts/templates.ts
 var TEMPLATES = {
   default: `You are {agent_name}, {agent_description}.
 
@@ -5199,7 +5741,13 @@ ${customSection}`.trim();
   }
   const template = options?.template ?? "default";
   const templateString = TEMPLATES[template] ?? TEMPLATES.default;
-  return templateString.replaceAll("{agent_name}", agentName).replaceAll("{agent_description}", agentDescription).replaceAll("{custom_section}", customSection);
+  const parts = [
+    templateString.replaceAll("{agent_name}", agentName).replaceAll("{agent_description}", agentDescription).replaceAll("{custom_section}", customSection)
+  ];
+  if (options?.capabilities?.memory) {
+    parts.push(MEMORY_SECTION);
+  }
+  return parts.join("\n\n");
 }
 
 // src/runtime/participantTracker.ts
@@ -5336,6 +5884,7 @@ async function runWithGracefulShutdown(agent, options) {
   HUB_ROOM_SYSTEM_PROMPT,
   HistoryProvider,
   MCP_TOOL_PREFIX,
+  MEMORY_SECTION,
   MEMORY_TOOL_NAMES,
   MessageRetryTracker,
   ParticipantTracker,