@elizaos/server 1.4.2 → 1.4.4

package/dist/index.js

@@ -1398,13 +1398,13 @@ var InternalMessageBus = class extends EventTarget {
     if (eventHandlers.has(handler)) {
       return this;
     }
-    const wrappedHandler = (e) => {
+    const wrappedHandler = ((e) => {
       if (e instanceof CustomEvent) {
         handler(e.detail);
       } else {
         handler(void 0);
       }
-    };
+    });
     eventHandlers.set(handler, wrappedHandler);
     this.addEventListener(event, wrappedHandler);
     return this;
@@ -2855,92 +2855,518 @@ function v4(options, buf, offset) {
 }
 var v4_default = v4;
 
+// src/api/messaging/errors/SessionErrors.ts
+var SessionError = class extends Error {
+  code;
+  statusCode;
+  details;
+  timestamp;
+  constructor(code, message, statusCode = 500, details) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.timestamp = /* @__PURE__ */ new Date();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Convert error to JSON for API responses
+   */
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        timestamp: this.timestamp.toISOString(),
+        ...process.env.NODE_ENV === "development" && {
+          details: this.details,
+          stack: this.stack
+        }
+      }
+    };
+  }
+};
+var SessionNotFoundError = class extends SessionError {
+  constructor(sessionId, details) {
+    super("SESSION_NOT_FOUND", `Session with ID '${sessionId}' not found`, 404, details);
+  }
+};
+var SessionExpiredError = class extends SessionError {
+  constructor(sessionId, expiredAt, details) {
+    const message = expiredAt ? `Session '${sessionId}' expired at ${expiredAt.toISOString()}` : `Session '${sessionId}' has expired`;
+    super("SESSION_EXPIRED", message, 410, details);
+  }
+};
+var SessionCreationError = class extends SessionError {
+  constructor(reason, details) {
+    super("SESSION_CREATION_FAILED", `Failed to create session: ${reason}`, 500, details);
+  }
+};
+var AgentNotFoundError = class extends SessionError {
+  constructor(agentId, details) {
+    super("AGENT_NOT_FOUND", `Agent with ID '${agentId}' not found`, 404, details);
+  }
+};
+var ValidationError = class extends SessionError {
+  field;
+  value;
+  constructor(message, field, value, details) {
+    super("VALIDATION_ERROR", message, 400, details);
+    this.field = field;
+    this.value = value;
+  }
+};
+var InvalidUuidError = class extends ValidationError {
+  constructor(field, value) {
+    super(`Invalid UUID format for field '${field}'`, field, value, {
+      providedValue: value,
+      expectedFormat: "UUID v4"
+    });
+  }
+};
+var MissingFieldsError = class extends ValidationError {
+  constructor(fields) {
+    super(`Missing required fields: ${fields.join(", ")}`, void 0, void 0, {
+      missingFields: fields
+    });
+  }
+};
+var InvalidContentError = class extends ValidationError {
+  constructor(reason, content) {
+    super(`Invalid content: ${reason}`, "content", content, { reason });
+  }
+};
+var InvalidMetadataError = class extends ValidationError {
+  constructor(reason, metadata) {
+    super(`Invalid metadata: ${reason}`, "metadata", metadata, {
+      reason,
+      providedMetadata: metadata
+    });
+  }
+};
+var InvalidPaginationError = class extends ValidationError {
+  constructor(parameter, value, reason) {
+    super(`Invalid pagination parameter '${parameter}': ${reason}`, parameter, value, {
+      parameter,
+      value,
+      reason
+    });
+  }
+};
+var InvalidTimeoutConfigError = class extends ValidationError {
+  constructor(reason, config) {
+    super(`Invalid timeout configuration: ${reason}`, "timeoutConfig", config, {
+      reason,
+      providedConfig: config
+    });
+  }
+};
+var SessionRenewalError = class extends SessionError {
+  constructor(sessionId, reason, details) {
+    super("SESSION_RENEWAL_FAILED", `Cannot renew session '${sessionId}': ${reason}`, 400, details);
+  }
+};
+var MessageSendError = class extends SessionError {
+  constructor(sessionId, reason, details) {
+    super(
+      "MESSAGE_SEND_FAILED",
+      `Failed to send message in session '${sessionId}': ${reason}`,
+      500,
+      details
+    );
+  }
+};
+function createErrorHandler() {
+  return (err, _req, res, next) => {
+    if (res.headersSent) {
+      return next(err);
+    }
+    if (err instanceof SessionError) {
+      return res.status(err.statusCode).json(err.toJSON());
+    }
+    if (err.name === "ValidationError") {
+      return res.status(400).json({
+        error: {
+          code: "VALIDATION_ERROR",
+          message: err.message,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+    }
+    console.error("Unexpected error:", err);
+    return res.status(500).json({
+      error: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "An unexpected error occurred",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        ...process.env.NODE_ENV === "development" && {
+          details: err.message,
+          stack: err.stack
+        }
+      }
+    });
+  };
+}
+
 // src/api/messaging/sessions.ts
-var SESSION_TIMEOUT_MS = parseInt(process.env.SESSION_TIMEOUT_MINUTES || "30") * 60 * 1e3;
+function safeParseInt(value, fallback, min, max) {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed) || !isFinite(parsed)) {
+    logger13.warn(`[Sessions API] Invalid integer value: "${value}", using fallback: ${fallback}`);
+    return fallback;
+  }
+  let result = parsed;
+  if (min !== void 0 && result < min) {
+    logger13.warn(`[Sessions API] Value ${result} is below minimum ${min}, clamping to minimum`);
+    result = min;
+  }
+  if (max !== void 0 && result > max) {
+    logger13.warn(`[Sessions API] Value ${result} is above maximum ${max}, clamping to maximum`);
+    result = max;
+  }
+  return result;
+}
+var DEFAULT_TIMEOUT_MINUTES = safeParseInt(
+  process.env.SESSION_DEFAULT_TIMEOUT_MINUTES,
+  30,
+  1,
+  10080
+  // 7 days max
+);
+var MIN_TIMEOUT_MINUTES = safeParseInt(process.env.SESSION_MIN_TIMEOUT_MINUTES, 5, 1, 60);
+var MAX_TIMEOUT_MINUTES = safeParseInt(
+  process.env.SESSION_MAX_TIMEOUT_MINUTES,
+  1440,
+  // 24 hours
+  60,
+  10080
+  // 7 days max
+);
+var DEFAULT_MAX_DURATION_MINUTES = safeParseInt(
+  process.env.SESSION_MAX_DURATION_MINUTES,
+  720,
+  // 12 hours
+  60,
+  20160
+  // 14 days max
+);
+var DEFAULT_WARNING_THRESHOLD_MINUTES = safeParseInt(
+  process.env.SESSION_WARNING_THRESHOLD_MINUTES,
+  5,
+  1,
+  60
+);
+var CLEANUP_INTERVAL_MS = safeParseInt(process.env.SESSION_CLEANUP_INTERVAL_MINUTES, 5, 1, 60) * 60 * 1e3;
 var sessions = /* @__PURE__ */ new Map();
 var DEFAULT_SERVER_ID4 = "00000000-0000-0000-0000-000000000000";
+var agentTimeoutConfigs = /* @__PURE__ */ new Map();
+var activeCleanupIntervals = /* @__PURE__ */ new Set();
+var processHandlersRegistered = false;
+function isValidSession(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  const session = obj;
+  return typeof session.id === "string" && typeof session.agentId === "string" && typeof session.channelId === "string" && typeof session.userId === "string" && session.createdAt instanceof Date && session.lastActivity instanceof Date && session.expiresAt instanceof Date && typeof session.renewalCount === "number" && session.timeoutConfig !== void 0 && typeof session.timeoutConfig === "object";
+}
+function isCreateSessionRequest(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  const req = obj;
+  return typeof req.agentId === "string" && typeof req.userId === "string";
+}
+function isSendMessageRequest(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  const req = obj;
+  return typeof req.content === "string";
+}
+function isValidTimeoutConfig(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  const config = obj;
+  return (config.timeoutMinutes === void 0 || typeof config.timeoutMinutes === "number" || typeof config.timeoutMinutes === "string") && (config.autoRenew === void 0 || typeof config.autoRenew === "boolean") && (config.maxDurationMinutes === void 0 || typeof config.maxDurationMinutes === "number" || typeof config.maxDurationMinutes === "string") && (config.warningThresholdMinutes === void 0 || typeof config.warningThresholdMinutes === "number" || typeof config.warningThresholdMinutes === "string");
+}
 var MAX_CONTENT_LENGTH = 4e3;
 var MAX_METADATA_SIZE = 1024 * 10;
 var MAX_LIMIT = 100;
 var DEFAULT_LIMIT = 50;
+function getAgentTimeoutConfig(agent) {
+  if (agentTimeoutConfigs.has(agent.agentId)) {
+    return agentTimeoutConfigs.get(agent.agentId);
+  }
+  const timeoutSetting = agent.getSetting("SESSION_TIMEOUT_MINUTES");
+  const maxDurationSetting = agent.getSetting("SESSION_MAX_DURATION_MINUTES");
+  const warningThresholdSetting = agent.getSetting("SESSION_WARNING_THRESHOLD_MINUTES");
+  const agentConfig = {
+    timeoutMinutes: timeoutSetting ? safeParseInt(
+      String(timeoutSetting),
+      DEFAULT_TIMEOUT_MINUTES,
+      MIN_TIMEOUT_MINUTES,
+      MAX_TIMEOUT_MINUTES
+    ) : DEFAULT_TIMEOUT_MINUTES,
+    autoRenew: agent.getSetting("SESSION_AUTO_RENEW") ? agent.getSetting("SESSION_AUTO_RENEW") === "true" : true,
+    maxDurationMinutes: maxDurationSetting ? safeParseInt(
+      String(maxDurationSetting),
+      DEFAULT_MAX_DURATION_MINUTES,
+      MIN_TIMEOUT_MINUTES,
+      MAX_TIMEOUT_MINUTES * 2
+    ) : DEFAULT_MAX_DURATION_MINUTES,
+    warningThresholdMinutes: warningThresholdSetting ? safeParseInt(
+      String(warningThresholdSetting),
+      DEFAULT_WARNING_THRESHOLD_MINUTES,
+      1,
+      MAX_TIMEOUT_MINUTES
+    ) : DEFAULT_WARNING_THRESHOLD_MINUTES
+  };
+  agentTimeoutConfigs.set(agent.agentId, agentConfig);
+  return agentConfig;
+}
+function mergeTimeoutConfigs(sessionConfig, agentConfig) {
+  const merged = {
+    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
+    autoRenew: true,
+    maxDurationMinutes: DEFAULT_MAX_DURATION_MINUTES,
+    warningThresholdMinutes: DEFAULT_WARNING_THRESHOLD_MINUTES
+  };
+  if (agentConfig) {
+    Object.assign(merged, agentConfig);
+  }
+  if (sessionConfig) {
+    if (sessionConfig.timeoutMinutes !== void 0) {
+      const timeoutValue = Number(sessionConfig.timeoutMinutes);
+      if (isNaN(timeoutValue) || !isFinite(timeoutValue)) {
+        logger13.warn(
+          `[Sessions API] Invalid timeout minutes in session config: ${sessionConfig.timeoutMinutes}, using default`
+        );
+        merged.timeoutMinutes = DEFAULT_TIMEOUT_MINUTES;
+      } else {
+        const timeout = Math.max(MIN_TIMEOUT_MINUTES, Math.min(MAX_TIMEOUT_MINUTES, timeoutValue));
+        merged.timeoutMinutes = timeout;
+      }
+    }
+    if (sessionConfig.autoRenew !== void 0) {
+      merged.autoRenew = sessionConfig.autoRenew;
+    }
+    if (sessionConfig.maxDurationMinutes !== void 0) {
+      const maxDurationValue = Number(sessionConfig.maxDurationMinutes);
+      if (isNaN(maxDurationValue) || !isFinite(maxDurationValue)) {
+        logger13.warn(
+          `[Sessions API] Invalid max duration minutes in session config: ${sessionConfig.maxDurationMinutes}, using default`
+        );
+        merged.maxDurationMinutes = DEFAULT_MAX_DURATION_MINUTES;
+      } else {
+        merged.maxDurationMinutes = Math.max(
+          merged.timeoutMinutes,
+          Math.min(MAX_TIMEOUT_MINUTES * 2, maxDurationValue)
+        );
+      }
+    }
+    if (sessionConfig.warningThresholdMinutes !== void 0) {
+      const warningValue = Number(sessionConfig.warningThresholdMinutes);
+      if (isNaN(warningValue) || !isFinite(warningValue)) {
+        logger13.warn(
+          `[Sessions API] Invalid warning threshold minutes in session config: ${sessionConfig.warningThresholdMinutes}, using default`
+        );
+        merged.warningThresholdMinutes = DEFAULT_WARNING_THRESHOLD_MINUTES;
+      } else {
+        merged.warningThresholdMinutes = Math.max(1, warningValue);
+      }
+    }
+  }
+  return merged;
+}
+function calculateExpirationDate(createdAt, lastActivity, config, _renewalCount) {
+  const baseTime = config.autoRenew ? lastActivity : createdAt;
+  const timeoutMs = (config.timeoutMinutes || DEFAULT_TIMEOUT_MINUTES) * 60 * 1e3;
+  if (config.maxDurationMinutes) {
+    const maxDurationMs = config.maxDurationMinutes * 60 * 1e3;
+    const timeSinceCreation = Date.now() - createdAt.getTime();
+    if (timeSinceCreation + timeoutMs > maxDurationMs) {
+      return new Date(createdAt.getTime() + maxDurationMs);
+    }
+  }
+  return new Date(baseTime.getTime() + timeoutMs);
+}
+function shouldWarnAboutExpiration(session) {
+  if (session.warningState?.sent) {
+    return false;
+  }
+  const warningThresholdMs = (session.timeoutConfig.warningThresholdMinutes || DEFAULT_WARNING_THRESHOLD_MINUTES) * 60 * 1e3;
+  const timeRemaining = session.expiresAt.getTime() - Date.now();
+  return timeRemaining <= warningThresholdMs && timeRemaining > 0;
+}
+function renewSession(session) {
+  if (!session.timeoutConfig.autoRenew) {
+    return false;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const maxDurationMs = (session.timeoutConfig.maxDurationMinutes || DEFAULT_MAX_DURATION_MINUTES) * 60 * 1e3;
+  const timeSinceCreation = now.getTime() - session.createdAt.getTime();
+  if (timeSinceCreation >= maxDurationMs) {
+    return false;
+  }
+  session.lastActivity = now;
+  session.renewalCount++;
+  session.expiresAt = calculateExpirationDate(
+    session.createdAt,
+    session.lastActivity,
+    session.timeoutConfig,
+    session.renewalCount
+  );
+  session.warningState = void 0;
+  logger13.info(
+    `[Sessions API] Renewed session ${session.id}, renewal count: ${session.renewalCount}`
+  );
+  return true;
+}
+function createSessionInfoResponse(session) {
+  const now = Date.now();
+  const timeRemaining = Math.max(0, session.expiresAt.getTime() - now);
+  const warningThresholdMs = (session.timeoutConfig.warningThresholdMinutes || DEFAULT_WARNING_THRESHOLD_MINUTES) * 60 * 1e3;
+  return {
+    sessionId: session.id,
+    agentId: session.agentId,
+    userId: session.userId,
+    createdAt: session.createdAt,
+    lastActivity: session.lastActivity,
+    metadata: session.metadata,
+    expiresAt: session.expiresAt,
+    timeoutConfig: session.timeoutConfig,
+    renewalCount: session.renewalCount,
+    timeRemaining,
+    isNearExpiration: timeRemaining <= warningThresholdMs && timeRemaining > 0
+  };
+}
 function validateMetadata(metadata) {
   if (!metadata || typeof metadata !== "object") {
-    return true;
+    return;
   }
   const metadataStr = JSON.stringify(metadata);
   if (metadataStr.length > MAX_METADATA_SIZE) {
-    throw new Error(`Metadata exceeds maximum size of ${MAX_METADATA_SIZE} bytes`);
+    throw new InvalidMetadataError(
+      `Metadata exceeds maximum size of ${MAX_METADATA_SIZE} bytes`,
+      metadata
+    );
   }
-  return true;
 }
 function validateContent(content) {
   if (typeof content !== "string") {
-    throw new Error("Content must be a string");
+    throw new InvalidContentError("Content must be a string", content);
   }
   if (content.length === 0) {
-    throw new Error("Content cannot be empty");
+    throw new InvalidContentError("Content cannot be empty", content);
   }
   if (content.length > MAX_CONTENT_LENGTH) {
-    throw new Error(`Content exceeds maximum length of ${MAX_CONTENT_LENGTH} characters`);
+    throw new InvalidContentError(
+      `Content exceeds maximum length of ${MAX_CONTENT_LENGTH} characters`,
+      content
+    );
   }
   return true;
 }
-function errorResponse(res, status, message, details) {
-  logger13.error(`[Sessions API] Error: ${message}`, details);
-  return res.status(status).json({
-    error: message,
-    details: process.env.NODE_ENV === "development" ? details : void 0
-  });
+function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
 }
 function createSessionsRouter(agents, serverInstance) {
   const router = express12.Router();
   router.get("/sessions/health", (_req, res) => {
+    const now = Date.now();
+    let activeSessions = 0;
+    let expiringSoon = 0;
+    let invalidSessions = 0;
+    for (const session of sessions.values()) {
+      if (!isValidSession(session)) {
+        invalidSessions++;
+        continue;
+      }
+      if (session.expiresAt.getTime() > now) {
+        activeSessions++;
+        if (shouldWarnAboutExpiration(session)) {
+          expiringSoon++;
+        }
+      }
+    }
     const response = {
       status: "healthy",
-      activeSessions: sessions.size,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      activeSessions,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      expiringSoon,
+      ...invalidSessions > 0 && { invalidSessions },
+      uptime: process.uptime()
     };
     res.json(response);
   });
-  router.post("/sessions", async (req, res) => {
-    try {
+  router.post(
+    "/sessions",
+    asyncHandler(async (req, res) => {
       const body = req.body;
-      if (!body.agentId || !body.userId) {
-        return errorResponse(res, 400, "Missing required fields: agentId and userId");
+      if (!isCreateSessionRequest(body)) {
+        throw new MissingFieldsError(["agentId", "userId"]);
       }
-      if (!validateUuid13(body.agentId) || !validateUuid13(body.userId)) {
-        return errorResponse(res, 400, "Invalid UUID format for agentId or userId");
+      if (!validateUuid13(body.agentId)) {
+        throw new InvalidUuidError("agentId", body.agentId);
+      }
+      if (!validateUuid13(body.userId)) {
+        throw new InvalidUuidError("userId", body.userId);
       }
       const agent = agents.get(body.agentId);
       if (!agent) {
-        return errorResponse(res, 404, "Agent not found");
+        throw new AgentNotFoundError(body.agentId);
       }
-      if (body.metadata && !validateMetadata(body.metadata)) {
-        return errorResponse(res, 400, "Invalid metadata");
+      if (body.metadata) {
+        validateMetadata(body.metadata);
       }
+      const agentTimeoutConfig = getAgentTimeoutConfig(agent);
+      const finalTimeoutConfig = mergeTimeoutConfigs(body.timeoutConfig, agentTimeoutConfig);
+      logger13.info(
+        `[Sessions API] Creating session with timeout config: agentId=${body.agentId}, timeout=${finalTimeoutConfig.timeoutMinutes}, autoRenew=${finalTimeoutConfig.autoRenew}, maxDuration=${finalTimeoutConfig.maxDurationMinutes}`
+      );
       const sessionId = v4_default();
       const channelId = v4_default();
-      await serverInstance.createChannel({
-        id: channelId,
-        name: `session-${sessionId}`,
-        type: ChannelType3.DM,
-        messageServerId: DEFAULT_SERVER_ID4,
-        metadata: {
-          sessionId,
-          agentId: body.agentId,
-          userId: body.userId,
-          ...body.metadata || {}
-        }
-      });
-      await serverInstance.addParticipantsToChannel(channelId, [body.agentId]);
+      try {
+        await serverInstance.createChannel({
+          id: channelId,
+          name: `session-${sessionId}`,
+          type: ChannelType3.DM,
+          messageServerId: DEFAULT_SERVER_ID4,
+          metadata: {
+            sessionId,
+            agentId: body.agentId,
+            userId: body.userId,
+            timeoutConfig: finalTimeoutConfig,
+            ...body.metadata || {}
+          }
+        });
+        await serverInstance.addParticipantsToChannel(channelId, [body.agentId]);
+      } catch (error) {
+        throw new SessionCreationError("Failed to create channel or add participants", {
+          originalError: error instanceof Error ? error.message : String(error)
+        });
+      }
+      const now = /* @__PURE__ */ new Date();
       const session = {
         id: sessionId,
         agentId: body.agentId,
         channelId,
         userId: body.userId,
         metadata: body.metadata || {},
-        createdAt: /* @__PURE__ */ new Date(),
-        lastActivity: /* @__PURE__ */ new Date()
+        createdAt: now,
+        lastActivity: now,
+        expiresAt: calculateExpirationDate(now, now, finalTimeoutConfig, 0),
+        timeoutConfig: finalTimeoutConfig,
+        renewalCount: 0
       };
       sessions.set(sessionId, session);
       const response = {
@@ -2948,123 +3374,171 @@ function createSessionsRouter(agents, serverInstance) {
         agentId: session.agentId,
         userId: session.userId,
         createdAt: session.createdAt,
-        metadata: session.metadata
+        metadata: session.metadata,
+        expiresAt: session.expiresAt,
+        timeoutConfig: session.timeoutConfig
       };
       res.status(201).json(response);
-    } catch (error) {
-      errorResponse(
-        res,
-        500,
-        "Failed to create session",
-        error instanceof Error ? error.message : String(error)
-      );
-    }
-  });
-  router.get("/sessions/:sessionId", async (req, res) => {
-    const { sessionId } = req.params;
-    const session = sessions.get(sessionId);
-    if (!session) {
-      return errorResponse(res, 404, "Session not found");
-    }
-    const response = {
-      sessionId: session.id,
-      agentId: session.agentId,
-      userId: session.userId,
-      createdAt: session.createdAt,
-      lastActivity: session.lastActivity,
-      metadata: session.metadata
-    };
-    res.json(response);
-  });
-  router.post("/sessions/:sessionId/messages", async (req, res) => {
-    try {
+    })
+  );
+  router.get(
+    "/sessions/:sessionId",
+    asyncHandler(async (req, res) => {
+      const { sessionId } = req.params;
+      const session = sessions.get(sessionId);
+      if (!session || !isValidSession(session)) {
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (session.expiresAt.getTime() <= Date.now()) {
+        sessions.delete(sessionId);
+        throw new SessionExpiredError(sessionId, session.expiresAt);
+      }
+      const response = createSessionInfoResponse(session);
+      res.json(response);
+    })
+  );
+  router.post(
+    "/sessions/:sessionId/messages",
+    asyncHandler(async (req, res) => {
       const { sessionId } = req.params;
       const body = req.body;
+      if (!isSendMessageRequest(body)) {
+        throw new InvalidContentError("Invalid message request format", body);
+      }
       const session = sessions.get(sessionId);
       if (!session) {
-        return errorResponse(res, 404, "Session not found");
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (session.expiresAt.getTime() <= Date.now()) {
+        sessions.delete(sessionId);
+        throw new SessionExpiredError(sessionId, session.expiresAt);
+      }
+      validateContent(body.content);
+      if (body.metadata) {
+        validateMetadata(body.metadata);
+      }
+      const wasRenewed = renewSession(session);
+      if (!wasRenewed && session.timeoutConfig.autoRenew) {
+        const maxDurationMs = (session.timeoutConfig.maxDurationMinutes || DEFAULT_MAX_DURATION_MINUTES) * 60 * 1e3;
+        const timeSinceCreation = Date.now() - session.createdAt.getTime();
+        if (timeSinceCreation >= maxDurationMs) {
+          logger13.warn(`[Sessions API] Session ${sessionId} has reached maximum duration`);
+        }
+      } else if (!session.timeoutConfig.autoRenew) {
+        session.lastActivity = /* @__PURE__ */ new Date();
       }
+      if (shouldWarnAboutExpiration(session)) {
+        session.warningState = {
+          sent: true,
+          sentAt: /* @__PURE__ */ new Date()
+        };
+        logger13.info(`[Sessions API] Session ${sessionId} is near expiration, warning state set`);
+      }
+      let message;
       try {
-        validateContent(body.content);
+        message = await serverInstance.createMessage({
+          channelId: session.channelId,
+          authorId: session.userId,
+          content: body.content,
+          rawMessage: {
+            content: body.content,
+            attachments: body.attachments
+          },
+          sourceType: "user",
+          metadata: {
+            sessionId,
+            ...body.metadata || {}
+          }
+        });
       } catch (error) {
-        return errorResponse(res, 400, error instanceof Error ? error.message : String(error));
-      }
-      if (body.metadata && !validateMetadata(body.metadata)) {
-        return errorResponse(res, 400, "Invalid metadata");
+        throw new MessageSendError(sessionId, "Failed to create message in database", {
+          originalError: error instanceof Error ? error.message : String(error)
+        });
       }
-      session.lastActivity = /* @__PURE__ */ new Date();
-      const message = await serverInstance.createMessage({
-        channelId: session.channelId,
-        authorId: session.userId,
-        content: body.content,
-        rawMessage: {
-          content: body.content,
-          attachments: body.attachments
-        },
-        sourceType: "user",
-        metadata: {
-          sessionId,
-          ...body.metadata || {}
-        }
-      });
-      res.status(201).json({
+      const response = {
         id: message.id,
         content: message.content,
         authorId: message.authorId,
         createdAt: message.createdAt,
-        metadata: message.metadata
-      });
-    } catch (error) {
-      errorResponse(
-        res,
-        500,
-        "Failed to send message",
-        error instanceof Error ? error.message : String(error)
-      );
-    }
-  });
-  router.get("/sessions/:sessionId/messages", async (req, res) => {
-    try {
+        metadata: message.metadata,
+        sessionStatus: {
+          expiresAt: session.expiresAt,
+          renewalCount: session.renewalCount,
+          wasRenewed,
+          isNearExpiration: shouldWarnAboutExpiration(session)
+        }
+      };
+      res.status(201).json(response);
+    })
+  );
+  router.get(
+    "/sessions/:sessionId/messages",
+    asyncHandler(async (req, res) => {
       const { sessionId } = req.params;
-      const query = req.query;
+      const query = {
+        limit: req.query.limit,
+        before: req.query.before,
+        after: req.query.after
+      };
       const session = sessions.get(sessionId);
       if (!session) {
-        return errorResponse(res, 404, "Session not found");
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (session.expiresAt.getTime() <= Date.now()) {
+        sessions.delete(sessionId);
+        throw new SessionExpiredError(sessionId, session.expiresAt);
       }
       let messageLimit = DEFAULT_LIMIT;
       if (query.limit) {
-        const parsedLimit = parseInt(query.limit, 10);
-        if (isNaN(parsedLimit) || parsedLimit < 1) {
-          return errorResponse(res, 400, "Invalid limit parameter");
-        }
-        messageLimit = Math.min(parsedLimit, MAX_LIMIT);
+        const parsedLimit = safeParseInt(query.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+        messageLimit = parsedLimit;
       }
       let beforeDate;
       let afterDate;
       if (query.before) {
         const beforeTimestamp = parseInt(query.before, 10);
-        if (isNaN(beforeTimestamp)) {
-          return errorResponse(res, 400, "Invalid before parameter");
+        if (isNaN(beforeTimestamp) || !isFinite(beforeTimestamp)) {
+          throw new InvalidPaginationError("before", query.before, "Must be a valid timestamp");
         }
         beforeDate = new Date(beforeTimestamp);
+        if (isNaN(beforeDate.getTime())) {
+          throw new InvalidPaginationError("before", query.before, "Invalid date from timestamp");
+        }
       }
       if (query.after) {
         const afterTimestamp = parseInt(query.after, 10);
-        if (isNaN(afterTimestamp)) {
-          return errorResponse(res, 400, "Invalid after parameter");
+        if (isNaN(afterTimestamp) || !isFinite(afterTimestamp)) {
+          throw new InvalidPaginationError("after", query.after, "Must be a valid timestamp");
         }
         afterDate = new Date(afterTimestamp);
+        if (isNaN(afterDate.getTime())) {
+          throw new InvalidPaginationError("after", query.after, "Invalid date from timestamp");
+        }
       }
       let messages;
-      if (afterDate) {
-        messages = await serverInstance.getMessagesForChannel(
+      if (afterDate && beforeDate) {
+        const fetchLimit = Math.min(500, messageLimit * 10);
+        const allMessages = await serverInstance.getMessagesForChannel(
+          session.channelId,
+          fetchLimit,
+          beforeDate
+        );
+        messages = allMessages.filter((msg) => msg.createdAt > afterDate && msg.createdAt < beforeDate).slice(0, messageLimit);
+        if (allMessages.length === fetchLimit) {
+          logger13.debug(`[Sessions API] Range query hit limit of ${fetchLimit} messages`);
+        }
+      } else if (afterDate) {
+        const fetchLimit = Math.min(1e3, messageLimit * 20);
+        const recentMessages = await serverInstance.getMessagesForChannel(
           session.channelId,
-          messageLimit * 2,
-          // Get extra to ensure we have enough after filtering
-          void 0
-          // Don't use beforeDate for initial query
+          fetchLimit
         );
-        messages = messages.filter((msg) => msg.createdAt > afterDate).slice(0, messageLimit);
+        const newerMessages = recentMessages.filter((msg) => msg.createdAt > afterDate);
+        if (newerMessages.length > messageLimit) {
+          messages = newerMessages.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime()).slice(0, messageLimit).reverse();
+        } else {
+          messages = newerMessages;
+        }
       } else {
         messages = await serverInstance.getMessagesForChannel(
           session.channelId,
@@ -3075,7 +3549,10 @@ function createSessionsRouter(agents, serverInstance) {
       const simplifiedMessages = messages.map((msg) => {
         let rawMessage = {};
         try {
-          rawMessage = typeof msg.rawMessage === "string" ? JSON.parse(msg.rawMessage) : msg.rawMessage || {};
+          const parsedData = typeof msg.rawMessage === "string" ? JSON.parse(msg.rawMessage) : msg.rawMessage;
+          if (parsedData && typeof parsedData === "object") {
+            rawMessage = parsedData;
+          }
         } catch (error) {
           logger13.warn(
             `[Sessions API] Failed to parse rawMessage for message ${msg.id}`,
@@ -3095,68 +3572,208 @@ function createSessionsRouter(agents, serverInstance) {
           }
         };
       });
+      const oldestMessage = simplifiedMessages[simplifiedMessages.length - 1];
+      const newestMessage = simplifiedMessages[0];
       const response = {
         messages: simplifiedMessages,
         hasMore: messages.length === messageLimit
       };
+      if (simplifiedMessages.length > 0) {
+        response.cursors = {
+          before: oldestMessage?.createdAt.getTime(),
+          after: newestMessage?.createdAt.getTime()
+        };
+      }
       res.json(response);
-    } catch (error) {
-      errorResponse(
-        res,
-        500,
-        "Failed to fetch messages",
-        error instanceof Error ? error.message : String(error)
+    })
+  );
+  router.post(
+    "/sessions/:sessionId/renew",
+    asyncHandler(async (req, res) => {
+      const { sessionId } = req.params;
+      const session = sessions.get(sessionId);
+      if (!session) {
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (session.expiresAt.getTime() <= Date.now()) {
+        sessions.delete(sessionId);
+        throw new SessionExpiredError(sessionId, session.expiresAt);
+      }
+      const previousAutoRenew = session.timeoutConfig.autoRenew;
+      session.timeoutConfig.autoRenew = true;
+      const renewed = renewSession(session);
+      session.timeoutConfig.autoRenew = previousAutoRenew;
+      if (!renewed) {
+        throw new SessionRenewalError(sessionId, "Maximum duration reached", {
+          maxDuration: session.timeoutConfig.maxDurationMinutes,
+          createdAt: session.createdAt,
+          timeSinceCreation: Date.now() - session.createdAt.getTime()
+        });
+      }
+      const response = createSessionInfoResponse(session);
+      res.json(response);
+    })
+  );
+  router.patch(
+    "/sessions/:sessionId/timeout",
+    asyncHandler(async (req, res) => {
+      const { sessionId } = req.params;
+      const newConfig = req.body;
+      const session = sessions.get(sessionId);
+      if (!session) {
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (session.expiresAt.getTime() <= Date.now()) {
+        sessions.delete(sessionId);
+        throw new SessionExpiredError(sessionId, session.expiresAt);
+      }
+      if (!isValidTimeoutConfig(newConfig)) {
+        throw new InvalidTimeoutConfigError("Invalid timeout configuration format", newConfig);
+      }
+      if (newConfig.timeoutMinutes !== void 0) {
+        const timeoutValue = Number(newConfig.timeoutMinutes);
+        if (!isNaN(timeoutValue) && isFinite(timeoutValue)) {
+          if (timeoutValue < MIN_TIMEOUT_MINUTES || timeoutValue > MAX_TIMEOUT_MINUTES) {
+            throw new InvalidTimeoutConfigError(
+              `Timeout must be between ${MIN_TIMEOUT_MINUTES} and ${MAX_TIMEOUT_MINUTES} minutes`,
+              newConfig
+            );
+          }
+        }
+      }
+      const agent = agents.get(session.agentId);
+      const agentConfig = agent ? getAgentTimeoutConfig(agent) : void 0;
+      session.timeoutConfig = mergeTimeoutConfigs(newConfig, agentConfig);
+      session.expiresAt = calculateExpirationDate(
+        session.createdAt,
+        session.lastActivity,
+        session.timeoutConfig,
+        session.renewalCount
       );
-    }
-  });
-  router.delete("/sessions/:sessionId", async (req, res) => {
-    try {
+      logger13.info(
+        `[Sessions API] Updated timeout config for session ${sessionId}: timeout=${session.timeoutConfig.timeoutMinutes}, autoRenew=${session.timeoutConfig.autoRenew}, maxDuration=${session.timeoutConfig.maxDurationMinutes}`
+      );
+      const response = createSessionInfoResponse(session);
+      res.json(response);
+    })
+  );
+  router.post(
+    "/sessions/:sessionId/heartbeat",
+    asyncHandler(async (req, res) => {
+      const { sessionId } = req.params;
+      const session = sessions.get(sessionId);
+      if (!session || !isValidSession(session)) {
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (session.expiresAt.getTime() <= Date.now()) {
+        sessions.delete(sessionId);
+        throw new SessionExpiredError(sessionId, session.expiresAt);
+      }
+      session.lastActivity = /* @__PURE__ */ new Date();
+      if (session.timeoutConfig.autoRenew) {
+        const renewed = renewSession(session);
+        if (renewed) {
+          logger13.info(`[Sessions API] Session renewed via heartbeat: ${sessionId}`);
+        }
+      }
+      const response = createSessionInfoResponse(session);
+      logger13.debug(`[Sessions API] Heartbeat received for session: ${sessionId}`);
+      res.json(response);
+    })
+  );
+  router.delete(
+    "/sessions/:sessionId",
+    asyncHandler(async (req, res) => {
       const { sessionId } = req.params;
       const session = sessions.get(sessionId);
       if (!session) {
-        return errorResponse(res, 404, "Session not found");
+        throw new SessionNotFoundError(sessionId);
       }
       sessions.delete(sessionId);
-      res.json({ success: true });
-    } catch (error) {
-      errorResponse(
-        res,
-        500,
-        "Failed to delete session",
-        error instanceof Error ? error.message : String(error)
+      logger13.info(`[Sessions API] Deleted session ${sessionId}`);
+      res.json({
+        success: true,
+        message: `Session ${sessionId} deleted successfully`
+      });
+    })
+  );
+  router.get(
+    "/sessions",
+    asyncHandler(async (_req, res) => {
+      const now = Date.now();
+      const activeSessions = Array.from(sessions.values()).filter((session) => isValidSession(session) && session.expiresAt.getTime() > now).map((session) => createSessionInfoResponse(session));
+      res.json({
+        sessions: activeSessions,
+        total: activeSessions.length,
+        stats: {
+          totalSessions: sessions.size,
+          activeSessions: activeSessions.length,
+          expiredSessions: sessions.size - activeSessions.length
+        }
+      });
+    })
+  );
+  const cleanupInterval = setInterval(() => {
+    const now = /* @__PURE__ */ new Date();
+    let cleanedCount = 0;
+    let expiredCount = 0;
+    let warningCount = 0;
+    for (const [sessionId, session] of sessions.entries()) {
+      if (!isValidSession(session)) {
+        logger13.warn(`[Sessions API] Invalid session structure for ${sessionId}, removing`);
+        sessions.delete(sessionId);
+        cleanedCount++;
+        continue;
+      }
+      if (session.expiresAt.getTime() <= now.getTime()) {
+        sessions.delete(sessionId);
+        cleanedCount++;
+        expiredCount++;
+        logger13.info(`[Sessions API] Cleaned up expired session: ${sessionId}`);
+      } else if (shouldWarnAboutExpiration(session) && !session.warningState?.sent) {
+        session.warningState = {
+          sent: true,
+          sentAt: now
+        };
+        warningCount++;
+        logger13.info(`[Sessions API] Session ${sessionId} will expire soon`);
+      }
+    }
+    if (cleanedCount > 0 || warningCount > 0) {
+      logger13.info(
+        `[Sessions API] Cleanup cycle completed: ${cleanedCount} expired sessions removed, ${warningCount} warnings issued`
       );
     }
-  });
-  router.get("/sessions", async (_req, res) => {
-    const activeSessions = Array.from(sessions.values()).map((session) => ({
-      sessionId: session.id,
-      agentId: session.agentId,
-      userId: session.userId,
-      createdAt: session.createdAt,
-      lastActivity: session.lastActivity,
-      metadata: session.metadata
-    }));
-    res.json({
-      sessions: activeSessions,
-      total: activeSessions.length
-    });
-  });
-  const cleanupInterval = setInterval(
-    () => {
-      const now = /* @__PURE__ */ new Date();
-      for (const [sessionId, session] of sessions.entries()) {
-        if (now.getTime() - session.lastActivity.getTime() > SESSION_TIMEOUT_MS) {
-          sessions.delete(sessionId);
-          logger13.info(`[Sessions API] Cleaned up inactive session: ${sessionId}`);
-        }
+  }, CLEANUP_INTERVAL_MS);
+  activeCleanupIntervals.add(cleanupInterval);
+  const cleanup = () => {
+    if (activeCleanupIntervals.has(cleanupInterval)) {
+      clearInterval(cleanupInterval);
+      activeCleanupIntervals.delete(cleanupInterval);
+      logger13.info("[Sessions API] Cleanup interval cleared");
+    }
+  };
+  if (!processHandlersRegistered) {
+    processHandlersRegistered = true;
+    const globalCleanup = () => {
+      logger13.info("[Sessions API] Global cleanup initiated");
+      for (const interval of activeCleanupIntervals) {
+        clearInterval(interval);
+      }
+      activeCleanupIntervals.clear();
+      if (process.env.CLEAR_SESSIONS_ON_SHUTDOWN === "true") {
+        sessions.clear();
+        agentTimeoutConfigs.clear();
       }
-    },
-    5 * 60 * 1e3
-  );
-  process.on("SIGTERM", () => {
-    clearInterval(cleanupInterval);
-  });
-  return router;
+    };
+    process.once("SIGTERM", globalCleanup);
+    process.once("SIGINT", globalCleanup);
+    process.once("beforeExit", globalCleanup);
+  }
+  router.use(createErrorHandler());
+  const routerWithCleanup = router;
+  routerWithCleanup.cleanup = cleanup;
+  return routerWithCleanup;
 }
 
 // src/api/messaging/index.ts
@@ -4232,7 +4849,7 @@ import express29 from "express";
 // package.json
 var package_default = {
   name: "@elizaos/server",
-  version: "1.4.2",
+  version: "1.4.4",
   description: "ElizaOS Server - Core server infrastructure for ElizaOS agents",
   publishConfig: {
     access: "public",
@@ -4283,10 +4900,10 @@ var package_default = {
     which: "^4.0.0",
     ws: "^8.18.0"
   },
-  gitHead: "c4e30a38836ac4bed81c671239377685892ebdf5",
+  gitHead: "966e28250672a7a0c5f934defd995c51b94c4622",
   dependencies: {
-    "@elizaos/core": "workspace:*",
-    "@elizaos/plugin-sql": "workspace:*",
+    "@elizaos/core": "1.4.4",
+    "@elizaos/plugin-sql": "1.4.4",
     "@types/express": "^5.0.2",
     "@types/helmet": "^4.0.0",
     "@types/multer": "^1.4.13",
@@ -6175,7 +6792,7 @@ var AgentServer = class {
               connectSrc: ["'self'", "ws:", "wss:", "https:", "http:"],
               mediaSrc: ["'self'", "blob:", "data:"],
               objectSrc: ["'none'"],
-              frameSrc: ["'none'"],
+              frameSrc: [this.isWebUIEnabled ? "'self'" : "'none'"],
               baseUri: ["'self'"],
               formAction: ["'self'"]
               // upgrade-insecure-requests is added by helmet automatically