@elizaos/server 1.6.2-alpha.16 → 1.6.2-alpha.18

package/dist/index.d.ts

@@ -21,17 +21,21 @@ export declare function resolvePgliteDir(dir?: string, fallbackDir?: string): st
  */
 export type ServerMiddleware = (req: express.Request, res: express.Response, next: express.NextFunction) => void;
 /**
- * Interface for defining server configuration options.
- * @typedef {Object} ServerOptions
- * @property {ServerMiddleware[]} [middlewares] - Optional array of server middlewares.
- * @property {string} [dataDir] - Optional directory for storing server data.
- * @property {string} [postgresUrl] - Optional URL for connecting to a PostgreSQL database.
+ * Interface for defining server configuration.
+ * Used for unified server initialization and startup.
  */
-export interface ServerOptions {
+export interface ServerConfig {
     middlewares?: ServerMiddleware[];
     dataDir?: string;
     postgresUrl?: string;
     clientPath?: string;
+    port?: number;
+    agents?: Array<{
+        character: Character;
+        plugins?: (Plugin | string)[];
+        init?: (runtime: IAgentRuntime) => Promise<void>;
+    }>;
+    isTestMode?: boolean;
 }
 /**
  * Determines if the web UI should be enabled based on environment variables.
@@ -57,12 +61,15 @@ export declare class AgentServer {
     jsonToCharacter: (character: unknown) => Promise<Character>;
     /**
      * Start multiple agents in batch (true parallel)
-     * @param characters - Array of character configurations
-     * @param plugins - Optional plugins to load
+     * @param agents - Array of agent configurations (character + optional plugins/init)
      * @param options - Optional configuration (e.g., isTestMode for test dependencies)
      * @returns Array of started agent runtimes
      */
-    startAgents(characters: Character[], plugins?: (Plugin | string)[], options?: {
+    startAgents(agents: Array<{
+        character: Character;
+        plugins?: (Plugin | string)[];
+        init?: (runtime: IAgentRuntime) => Promise<void>;
+    }>, options?: {
         isTestMode?: boolean;
     }): Promise<IAgentRuntime[]>;
     /**
@@ -88,18 +95,20 @@ export declare class AgentServer {
      */
     constructor();
     /**
-     * Initializes the database and server.
+     * Initializes the database and server (internal use only).
      *
-     * @param {ServerOptions} [options] - Optional server options.
+     * @param {ServerConfig} [config] - Optional server configuration.
      * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     * @private
      */
-    initialize(options?: ServerOptions): Promise<void>;
+    private initialize;
     private ensureDefaultServer;
     /**
-     * Initializes the server with the provided options.
+     * Initializes the server with the provided configuration.
      *
-     * @param {ServerOptions} [options] - Optional server options.
+     * @param {ServerConfig} [config] - Optional server configuration.
      * @returns {Promise<void>} - A promise that resolves once the server is initialized.
+     * @private
      */
     private initializeServer;
     /**
@@ -125,13 +134,33 @@ export declare class AgentServer {
      */
     registerMiddleware(middleware: ServerMiddleware): void;
     /**
-     * Starts the server on the specified port.
+     * Starts the server with unified configuration.
+     * Handles initialization, port resolution, and optional agent startup.
      *
-     * @param {number} port - The port number on which the server should listen.
+     * @param {ServerConfig} config - Server configuration including port, agents, and infrastructure options.
      * @returns {Promise<void>} A promise that resolves when the server is listening.
-     * @throws {Error} If the port is invalid or if there is an error while starting the server.
+     * @throws {Error} If there is an error during initialization or startup.
      */
-    start(port: number): Promise<void>;
+    start(config?: ServerConfig): Promise<void>;
+    /**
+     * Resolves and finds an available port.
+     * - If port is provided (number): validates and returns it (strict - fails if unavailable)
+     * - If port is undefined: finds next available port starting from env/default (auto-discovery)
+     */
+    private resolveAndFindPort;
+    /**
+     * Finds an available port starting from the requested port.
+     * Tries incrementing ports up to maxAttempts.
+     */
+    private findAvailablePort;
+    /**
+     * Checks if a port is available by attempting to bind to it.
+     */
+    private isPortAvailable;
+    /**
+     * Starts the HTTP server on the specified port.
+     */
+    private startHttpServer;
     /**
      * Stops the server if it is running. Closes the server connection,
      * stops the database connection, and logs a success message.

package/dist/index.js

@@ -23620,6 +23620,7 @@ var helmet = Object.assign(function helmet2(options = {}) {
 import * as fs6 from "node:fs";
 import http4 from "node:http";
 import os3 from "node:os";
+import net3 from "node:net";
 import path8, { basename as basename2, dirname as dirname3, extname, join as join4 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -23825,7 +23826,7 @@ function createAgentCrudRouter(elizaOS, serverInstance) {
           try {
             await serverInstance?.unregisterAgent(agentId);
             const { enabled, status: status2, createdAt, updatedAt, ...characterData } = updatedAgent;
-            const runtimes = await serverInstance?.startAgents([characterData]);
+            const runtimes = await serverInstance?.startAgents([{ character: characterData }]);
             if (!runtimes || runtimes.length === 0) {
               throw new Error("Failed to restart agent after configuration change");
             }
@@ -23834,7 +23835,7 @@ function createAgentCrudRouter(elizaOS, serverInstance) {
             logger.error({ error: restartError, agentId }, `[AGENT UPDATE] Failed to restart agent ${agentId}, attempting to restore previous state`);
             try {
               const { enabled, status: status2, createdAt, updatedAt, ...previousCharacterData } = currentAgent;
-              await serverInstance?.startAgents([previousCharacterData]);
+              await serverInstance?.startAgents([{ character: previousCharacterData }]);
               logger.warn(`[AGENT UPDATE] Restored agent ${agentId} to previous state`);
             } catch (restoreError) {
               logger.error({ error: restoreError, agentId }, `[AGENT UPDATE] Failed to restore agent ${agentId} - agent may be in broken state`);
@@ -23956,7 +23957,7 @@ import { validateUuid as validateUuid2, logger as logger2 } from "@elizaos/core"
 import express2 from "express";
 function createAgentLifecycleRouter(elizaOS, serverInstance) {
   const router = express2.Router();
-  const db = serverInstance?.database;
+  const db = serverInstance.database;
   router.post("/:agentId/start", async (req, res) => {
     const agentId = validateUuid2(req.params.agentId);
     if (!agentId) {
@@ -23980,7 +23981,7 @@ function createAgentLifecycleRouter(elizaOS, serverInstance) {
           status: "active"
         });
       }
-      await serverInstance?.startAgents([agent]);
+      await serverInstance.startAgents([{ character: agent }]);
       const runtime = elizaOS.getAgent(agentId);
       if (!runtime) {
         throw new Error("Failed to start agent");
@@ -28855,7 +28856,7 @@ import express30 from "express";
 // package.json
 var package_default = {
   name: "@elizaos/server",
-  version: "1.6.2-alpha.16",
+  version: "1.6.2-alpha.18",
   description: "ElizaOS Server - Core server infrastructure for ElizaOS agents",
   publishConfig: {
     access: "public",
@@ -45942,16 +45943,21 @@ class AgentServer {
   database;
   loadCharacterTryPath;
   jsonToCharacter;
-  async startAgents(characters, plugins = [], options) {
+  async startAgents(agents, options) {
     if (!this.elizaOS) {
       throw new Error("Server not properly initialized");
     }
-    const agentConfigs = characters.map((character) => {
-      character.id ??= stringToUuid2(character.name);
-      const allPlugins = [...character.plugins || [], ...plugins, sqlPlugin];
+    const agentConfigs = agents.map((agent) => {
+      agent.character.id ??= stringToUuid2(agent.character.name);
+      const allPlugins = [
+        ...agent.character.plugins || [],
+        ...agent.plugins || [],
+        sqlPlugin
+      ];
       return {
-        character: encryptedCharacter(character),
-        plugins: allPlugins
+        character: encryptedCharacter(agent.character),
+        plugins: allPlugins,
+        init: agent.init
       };
     });
     const agentIds = await this.elizaOS.addAgents(agentConfigs, options);
@@ -46009,14 +46015,14 @@ class AgentServer {
       throw error2;
     }
   }
-  async initialize(options) {
+  async initialize(config3) {
     if (this.isInitialized) {
       logger30.warn("AgentServer is already initialized, skipping initialization");
       return;
     }
     try {
       logger30.debug("Initializing AgentServer (async operations)...");
-      const agentDataDir = resolvePgliteDir(options?.dataDir);
+      const agentDataDir = resolvePgliteDir(config3?.dataDir);
       logger30.info(`[INIT] Database Dir for SQL plugin: ${agentDataDir}`);
       const dbDir = path8.dirname(agentDataDir);
       if (!fs6.existsSync(dbDir)) {
@@ -46026,7 +46032,7 @@ class AgentServer {
       const tempServerAgentId = "00000000-0000-0000-0000-000000000000";
       this.database = createDatabaseAdapter({
         dataDir: agentDataDir,
-        postgresUrl: options?.postgresUrl
+        postgresUrl: config3?.postgresUrl
       }, tempServerAgentId);
       await this.database.init();
       logger30.success("Database initialized for server operations");
@@ -46052,7 +46058,7 @@ class AgentServer {
       this.elizaOS = new ElizaOS2;
       this.elizaOS.enableEditableMode();
       logger30.success("[INIT] ElizaOS initialized");
-      await this.initializeServer(options);
+      await this.initializeServer(config3);
       await new Promise((resolve2) => setTimeout(resolve2, 250));
       this.isInitialized = true;
     } catch (error2) {
@@ -46114,10 +46120,10 @@ class AgentServer {
       throw error2;
     }
   }
-  async initializeServer(options) {
+  async initializeServer(config3) {
     try {
-      if (options?.clientPath) {
-        this.clientPath = options.clientPath;
+      if (config3?.clientPath) {
+        this.clientPath = config3.clientPath;
       }
       this.app = express33();
       const DEFAULT_SENTRY_DSN = "https://c20e2d51b66c14a783b0689d536f7e5c@o4509349865259008.ingest.us.sentry.io/4509352524120064";
@@ -46187,9 +46193,9 @@ class AgentServer {
         referrerPolicy: { policy: "no-referrer-when-downgrade" },
         xssFilter: true
       }));
-      if (options?.middlewares) {
+      if (config3?.middlewares) {
         logger30.debug("Applying custom middlewares...");
-        for (const middleware2 of options.middlewares) {
+        for (const middleware2 of config3.middlewares) {
           this.app.use(middleware2);
         }
       }
@@ -46279,10 +46285,10 @@ class AgentServer {
           return;
         }
         const absolutePath = path8.resolve(filePath);
-        const options2 = {
+        const options = {
           dotfiles: "deny"
         };
-        res.sendFile(absolutePath, options2, (err) => {
+        res.sendFile(absolutePath, options, (err) => {
           if (err) {
             const ext2 = extname(filename).toLowerCase();
             const mimeType = ext2 === ".png" ? "image/png" : ext2 === ".jpg" || ext2 === ".jpeg" ? "image/jpeg" : "application/octet-stream";
@@ -46631,12 +46637,73 @@ class AgentServer {
   registerMiddleware(middleware2) {
     this.app.use(middleware2);
   }
-  start(port) {
+  async start(config3) {
+    if (!this.isInitialized) {
+      await this.initialize(config3);
+    }
+    if (!config3?.isTestMode) {
+      const port = await this.resolveAndFindPort(config3?.port);
+      await this.startHttpServer(port);
+    }
+    if (config3?.agents && config3.agents.length > 0) {
+      await this.startAgents(config3.agents, { isTestMode: config3.isTestMode });
+      logger30.info(`Started ${config3.agents.length} agents`);
+    }
+  }
+  async resolveAndFindPort(port) {
+    if (port !== undefined) {
+      if (typeof port !== "number" || port < 1 || port > 65535) {
+        throw new Error(`Invalid port number: ${port}. Must be between 1 and 65535.`);
+      }
+      return port;
+    }
+    let requestedPort = 3000;
+    const envPort = process.env.SERVER_PORT;
+    if (envPort) {
+      const parsed = parseInt(envPort, 10);
+      if (!isNaN(parsed) && parsed >= 1 && parsed <= 65535) {
+        requestedPort = parsed;
+      } else {
+        logger30.warn(`Invalid SERVER_PORT "${envPort}", falling back to 3000`);
+      }
+    }
+    return await this.findAvailablePort(requestedPort);
+  }
+  async findAvailablePort(startPort, maxAttempts = 10) {
+    for (let attempt = 0;attempt < maxAttempts; attempt++) {
+      const port = startPort + attempt;
+      if (port > 65535) {
+        throw new Error(`Could not find available port (exceeded max port 65535, tried up to ${port - 1})`);
+      }
+      if (await this.isPortAvailable(port)) {
+        if (attempt > 0) {
+          logger30.info(`Port ${startPort} is in use, using port ${port} instead`);
+        }
+        return port;
+      }
+    }
+    throw new Error(`Could not find available port after ${maxAttempts} attempts starting from ${startPort}`);
+  }
+  async isPortAvailable(port) {
+    return new Promise((resolve2) => {
+      const server = net3.createServer();
+      server.once("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+          resolve2(false);
+        } else {
+          resolve2(false);
+        }
+      });
+      server.once("listening", () => {
+        server.close();
+        resolve2(true);
+      });
+      server.listen(port);
+    });
+  }
+  startHttpServer(port) {
     return new Promise((resolve2, reject) => {
       try {
-        if (!port || typeof port !== "number") {
-          throw new Error(`Invalid port number: ${port}`);
-        }
         logger30.debug(`Starting server on port ${port}...`);
         logger30.debug(`Current agents count: ${this.elizaOS?.getAgents().length || 0}`);
         logger30.debug(`Environment: ${"development"}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/server",
-  "version": "1.6.2-alpha.16",
+  "version": "1.6.2-alpha.18",
   "description": "ElizaOS Server - Core server infrastructure for ElizaOS agents",
   "publishConfig": {
     "access": "public",
@@ -44,7 +44,7 @@
     "dev": "bun run build.ts --watch"
   },
   "devDependencies": {
-    "@elizaos/client": "1.6.2-alpha.16",
+    "@elizaos/client": "1.6.2-alpha.18",
     "@types/node": "^24.0.1",
     "prettier": "3.6.2",
     "tsx": "4.20.6",
@@ -52,10 +52,10 @@
     "which": "^5.0.0",
     "ws": "^8.18.0"
   },
-  "gitHead": "ae35960ef5fc17aebdc30b73c8fa57b5fff4e34e",
+  "gitHead": "6d6022cc97a0b1ce0909bfe8a7be10392677a416",
   "dependencies": {
-    "@elizaos/core": "1.6.2-alpha.16",
-    "@elizaos/plugin-sql": "1.6.2-alpha.16",
+    "@elizaos/core": "1.6.2-alpha.18",
+    "@elizaos/plugin-sql": "1.6.2-alpha.18",
     "@sentry/node": "^10.16.0",
     "@types/express": "^5.0.2",
     "@types/helmet": "^4.0.0",