@elizaos/server 1.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# @elizaos/server
+
+The server package provides the REST API and WebSocket server infrastructure for ElizaOS agents. It's the core runtime server that powers the ElizaOS CLI and can be embedded in other applications.
+
+## Overview
+
+`@elizaos/server` exports a complete agent server implementation including:
+
+- REST API endpoints for agent management and interaction
+- WebSocket support for real-time communication
+- Database integration with SQLite/PostgreSQL
+- Plugin system integration
+- Multi-agent runtime management
+- Built-in web UI serving
+
+This package is used internally by the ElizaOS CLI (`@elizaos/cli`) but can also be imported directly to create custom server implementations.
+
+## Installation
+
+```bash
+npm install @elizaos/server
+# or
+bun add @elizaos/server
+```
+
+## Usage
+
+### Basic Server Setup
+
+```typescript
+import { AgentServer } from '@elizaos/server';
+
+// Create and initialize server
+const server = new AgentServer();
+await server.initialize();
+
+// Start the server
+const port = 3000;
+server.start(port);
+
+// Server is now running at http://localhost:3000
+```
+
+### Advanced Configuration
+
+```typescript
+import { AgentServer, ServerOptions, ServerMiddleware } from '@elizaos/server';
+import { logger } from '@elizaos/core';
+
+// Custom middleware
+const customMiddleware: ServerMiddleware = (req, res, next) => {
+  logger.info(`${req.method} ${req.path}`);
+  next();
+};
+
+// Server configuration
+const serverOptions: ServerOptions = {
+  dataDir: './data/agents',
+  middlewares: [customMiddleware],
+  postgresUrl: process.env.DATABASE_URL, // Optional PostgreSQL
+};
+
+// Initialize server with options
+const server = new AgentServer();
+await server.initialize(serverOptions);
+
+// Register additional middleware
+server.registerMiddleware((req, res, next) => {
+  res.setHeader('X-Server', 'ElizaOS');
+  next();
+});
+
+// Start the server
+server.start(3000);
+```
+
+## API Endpoints
+
+### Agent Management
+
+- `GET /api/agents` - List all running agents
+- `GET /api/agents/:agentId` - Get specific agent details
+- `POST /api/agents` - Create new agent
+- `PUT /api/agents/:agentId` - Update agent configuration
+- `DELETE /api/agents/:agentId` - Stop and remove agent
+
+### Agent Interaction
+
+- `POST /api/agents/:agentId/message` - Send message to agent
+- `GET /api/agents/:agentId/history` - Get conversation history
+- `POST /api/agents/:agentId/action` - Trigger specific agent action
+
+### Memory & State
+
+- `GET /api/agents/:agentId/memory` - Get agent memory/knowledge
+- `POST /api/agents/:agentId/memory` - Add to agent memory
+- `DELETE /api/agents/:agentId/memory/:memoryId` - Remove memory
+
+### System
+
+- `GET /api/health` - Health check endpoint
+- `GET /api/version` - Get server version info
+
+## WebSocket Events
+
+Connect to `ws://localhost:3000/ws` for real-time communication:
+
+```javascript
+// Client-side WebSocket connection
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+// Send message
+ws.send(
+  JSON.stringify({
+    type: 'message',
+    agentId: 'agent-123',
+    content: 'Hello, agent!',
+  })
+);
+
+// Receive responses
+ws.on('message', (data) => {
+  const response = JSON.parse(data);
+  console.log('Agent response:', response);
+});
+```
+
+### WebSocket Message Types
+
+- `message` - Send/receive chat messages
+- `action` - Trigger agent actions
+- `status` - Agent status updates
+- `error` - Error notifications
+
+## Programmatic Usage
+
+### Embedding in Express App
+
+```typescript
+import express from 'express';
+import { AgentServer } from '@elizaos/server';
+
+const app = express();
+
+// Create ElizaOS server
+const elizaServer = new AgentServer();
+await elizaServer.initialize();
+
+// Mount ElizaOS APIs on your Express app
+// The server provides its own Express app instance
+app.use('/eliza', elizaServer.app);
+
+// Your custom routes
+app.get('/custom', (req, res) => {
+  res.json({ message: 'Custom endpoint' });
+});
+
+app.listen(3000);
+```
+
+### Programmatic Agent Management
+
+```typescript
+import { AgentServer } from '@elizaos/server';
+import { AgentRuntime, Character } from '@elizaos/core';
+
+// Initialize server
+const server = new AgentServer();
+await server.initialize();
+
+// Create and register agent runtime
+const character: Character = {
+  name: 'MyAgent',
+  // ... character configuration
+};
+
+// Note: Full AgentRuntime creation requires more setup
+// This is a simplified example
+const runtime = new AgentRuntime({
+  character,
+  database: server.database,
+  // ... other configuration
+});
+
+// Register agent with server
+await server.registerAgent(runtime);
+
+// Start server
+server.start(3000);
+```
+
+## Configuration
+
+### Environment Variables
+
+The server respects these environment variables:
+
+- `PORT` - Server port (default: 3000)
+- `HOST` - Server host (default: localhost)
+- `DATABASE_URL` - PostgreSQL connection string
+- `SQLITE_PATH` - Path to SQLite database file
+- `LOG_LEVEL` - Logging level (debug, info, warn, error)
+- `CORS_ORIGIN` - CORS allowed origins
+
+### Server Options
+
+```typescript
+interface ServerOptions {
+  port?: number;
+  host?: string;
+  agents?: string[] | Character[];
+  database?: DatabaseConfig;
+  plugins?: Plugin[];
+  cors?: CorsOptions;
+  staticDir?: string;
+  enableWebUI?: boolean;
+}
+```
+
+## Architecture
+
+The server package is structured as follows:
+
+```
+server/
+├── api/              # REST API route handlers
+│   ├── agents/       # Agent management endpoints
+│   ├── memory/       # Memory/knowledge endpoints
+│   └── system/       # System/health endpoints
+├── database/         # Database adapters and migrations
+├── services/         # Core services (runtime, storage)
+├── socketio/         # WebSocket implementation
+└── index.ts          # Main exports
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test suite
+npm test -- api/agents
+
+# Run with coverage
+npm test -- --coverage
+```
+
+### Building
+
+```bash
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run dev
+```
+
+## Examples
+
+See the `/examples` directory for complete examples:
+
+- Basic server setup
+- Multi-agent configuration
+- Custom plugin integration
+- Database configuration
+- WebSocket chat client
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+import { UUID, ChannelType, Character, DatabaseAdapter, IAgentRuntime } from '@elizaos/core';
+import express from 'express';
+import http from 'node:http';
+import { Server } from 'socket.io';
+
+interface MessageServer {
+    id: UUID;
+    name: string;
+    sourceType: string;
+    sourceId?: string;
+    metadata?: Record<string, any>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface MessageChannel {
+    id: UUID;
+    messageServerId: UUID;
+    name: string;
+    type: ChannelType;
+    sourceType?: string;
+    sourceId?: string;
+    topic?: string;
+    metadata?: Record<string, any>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CentralRootMessage {
+    id: UUID;
+    channelId: UUID;
+    authorId: UUID;
+    content: string;
+    rawMessage?: any;
+    inReplyToRootMessageId?: UUID;
+    sourceType?: string;
+    sourceId?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, any>;
+}
+interface MessageServiceStructure {
+    id: UUID;
+    channel_id: UUID;
+    server_id: UUID;
+    author_id: UUID;
+    author_display_name?: string;
+    content: string;
+    raw_message?: any;
+    source_id?: string;
+    source_type?: string;
+    in_reply_to_message_id?: UUID;
+    created_at: number;
+    metadata?: any;
+}
+
+/**
+ * Attempts to load a file from the given file path.
+ *
+ * @param {string} filePath - The path to the file to load.
+ * @returns {string | null} The contents of the file as a string, or null if an error occurred.
+ * @throws {Error} If an error occurs while loading the file.
+ */
+declare function tryLoadFile(filePath: string): string | null;
+/**
+ * Load characters from a specified URL and return them as an array of Character objects.
+ * @param {string} url - The URL from which to load character data.
+ * @returns {Promise<Character[]>} - A promise that resolves with an array of Character objects.
+ */
+declare function loadCharactersFromUrl(url: string): Promise<Character[]>;
+/**
+ * Converts a JSON object representing a character into a validated Character object with additional settings and secrets.
+ *
+ * @param {unknown} character - The input data representing a character.
+ * @returns {Promise<Character>} - A Promise that resolves to a validated Character object.
+ * @throws {Error} If character validation fails.
+ */
+declare function jsonToCharacter(character: unknown): Promise<Character>;
+/**
+ * Loads a character from the specified file path with safe JSON parsing and validation.
+ *
+ * @param {string} filePath - The path to the character file.
+ * @returns {Promise<Character>} A Promise that resolves to the validated Character object.
+ * @throws {Error} If the character file is not found, has invalid JSON, or fails validation.
+ */
+declare function loadCharacter(filePath: string): Promise<Character>;
+/**
+ * Asynchronously loads a character from the specified path.
+ * If the path is a URL, it loads the character from the URL.
+ * If the path is a local file path, it tries multiple possible locations and
+ * loads the character from the first valid location found.
+ *
+ * @param {string} characterPath - The path to load the character from.
+ * @returns {Promise<Character>} A Promise that resolves to the loaded character.
+ */
+declare function loadCharacterTryPath(characterPath: string): Promise<Character>;
+declare const hasValidRemoteUrls: () => boolean | "" | undefined;
+/**
+ * Load characters from local paths or remote URLs based on configuration.
+ * @param charactersArg - A comma-separated list of local file paths or remote URLs to load characters from.
+ * @returns A promise that resolves to an array of loaded characters.
+ */
+declare function loadCharacters(charactersArg: string): Promise<Character[]>;
+
+/**
+ * Expands a file path starting with `~` to the project directory.
+ *
+ * @param filepath - The path to expand.
+ * @returns The expanded path.
+ */
+declare function expandTildePath(filepath: string): string;
+declare function resolvePgliteDir(dir?: string, fallbackDir?: string): string;
+/**
+ * Represents a function that acts as a server middleware.
+ * @param {express.Request} req - The request object.
+ * @param {express.Response} res - The response object.
+ * @param {express.NextFunction} next - The next function to be called in the middleware chain.
+ * @returns {void}
+ */
+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 ServerOptions {
+    middlewares?: ServerMiddleware[];
+    dataDir?: string;
+    postgresUrl?: string;
+}
+/**
+ * Class representing an agent server.
+ */ /**
+* Represents an agent server which handles agents, database, and server functionalities.
+*/
+declare class AgentServer {
+    app: express.Application;
+    private agents;
+    server: http.Server;
+    socketIO: Server;
+    isInitialized: boolean;
+    database: DatabaseAdapter;
+    startAgent: (character: Character) => Promise<IAgentRuntime>;
+    stopAgent: (runtime: IAgentRuntime) => void;
+    loadCharacterTryPath: (characterPath: string) => Promise<Character>;
+    jsonToCharacter: (character: unknown) => Promise<Character>;
+    /**
+     * Constructor for AgentServer class.
+     *
+     * @constructor
+     */
+    constructor();
+    /**
+     * Initializes the database and server.
+     *
+     * @param {ServerOptions} [options] - Optional server options.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     */
+    initialize(options?: ServerOptions): Promise<void>;
+    private ensureDefaultServer;
+    /**
+     * Initializes the server with the provided options.
+     *
+     * @param {ServerOptions} [options] - Optional server options.
+     * @returns {Promise<void>} - A promise that resolves once the server is initialized.
+     */
+    private initializeServer;
+    /**
+     * Registers an agent with the provided runtime.
+     *
+     * @param {IAgentRuntime} runtime - The runtime object containing agent information.
+     * @throws {Error} if the runtime is null/undefined, if agentId is missing, if character configuration is missing,
+     * or if there are any errors during registration.
+     */
+    registerAgent(runtime: IAgentRuntime): Promise<void>;
+    /**
+     * Unregisters an agent from the system.
+     *
+     * @param {UUID} agentId - The unique identifier of the agent to unregister.
+     * @returns {void}
+     */
+    unregisterAgent(agentId: UUID): void;
+    /**
+     * Add middleware to the server's request handling pipeline
+     * @param {ServerMiddleware} middleware - The middleware function to be registered
+     */
+    registerMiddleware(middleware: ServerMiddleware): void;
+    /**
+     * Starts the server on the specified port.
+     *
+     * @param {number} port - The port number on which the server should listen.
+     * @throws {Error} If the port is invalid or if there is an error while starting the server.
+     */
+    start(port: number): void;
+    /**
+     * Stops the server if it is running. Closes the server connection,
+     * stops the database connection, and logs a success message.
+     */
+    stop(): Promise<void>;
+    createServer(data: Omit<MessageServer, 'id' | 'createdAt' | 'updatedAt'>): Promise<MessageServer>;
+    getServers(): Promise<MessageServer[]>;
+    getServerById(serverId: UUID): Promise<MessageServer | null>;
+    getServerBySourceType(sourceType: string): Promise<MessageServer | null>;
+    createChannel(data: Omit<MessageChannel, 'id' | 'createdAt' | 'updatedAt'> & {
+        id?: UUID;
+    }, participantIds?: UUID[]): Promise<MessageChannel>;
+    addParticipantsToChannel(channelId: UUID, userIds: UUID[]): Promise<void>;
+    getChannelsForServer(serverId: UUID): Promise<MessageChannel[]>;
+    getChannelDetails(channelId: UUID): Promise<MessageChannel | null>;
+    getChannelParticipants(channelId: UUID): Promise<UUID[]>;
+    deleteMessage(messageId: UUID): Promise<void>;
+    updateChannel(channelId: UUID, updates: {
+        name?: string;
+        participantCentralUserIds?: UUID[];
+        metadata?: any;
+    }): Promise<MessageChannel>;
+    deleteChannel(channelId: UUID): Promise<void>;
+    clearChannelMessages(channelId: UUID): Promise<void>;
+    findOrCreateCentralDmChannel(user1Id: UUID, user2Id: UUID, messageServerId: UUID): Promise<MessageChannel>;
+    createMessage(data: Omit<CentralRootMessage, 'id' | 'createdAt' | 'updatedAt'>): Promise<CentralRootMessage>;
+    getMessagesForChannel(channelId: UUID, limit?: number, beforeTimestamp?: Date): Promise<CentralRootMessage[]>;
+    removeParticipantFromChannel(): Promise<void>;
+    /**
+     * Add an agent to a server
+     * @param {UUID} serverId - The server ID
+     * @param {UUID} agentId - The agent ID to add
+     */
+    addAgentToServer(serverId: UUID, agentId: UUID): Promise<void>;
+    /**
+     * Remove an agent from a server
+     * @param {UUID} serverId - The server ID
+     * @param {UUID} agentId - The agent ID to remove
+     */
+    removeAgentFromServer(serverId: UUID, agentId: UUID): Promise<void>;
+    /**
+     * Get all agents associated with a server
+     * @param {UUID} serverId - The server ID
+     * @returns {Promise<UUID[]>} Array of agent IDs
+     */
+    getAgentsForServer(serverId: UUID): Promise<UUID[]>;
+    /**
+     * Get all servers an agent belongs to
+     * @param {UUID} agentId - The agent ID
+     * @returns {Promise<UUID[]>} Array of server IDs
+     */
+    getServersForAgent(agentId: UUID): Promise<UUID[]>;
+}
+
+export { AgentServer, type CentralRootMessage, type MessageChannel, type MessageServer, type MessageServiceStructure, type ServerMiddleware, type ServerOptions, expandTildePath, hasValidRemoteUrls, jsonToCharacter, loadCharacter, loadCharacterTryPath, loadCharacters, loadCharactersFromUrl, resolvePgliteDir, tryLoadFile };