agent-world 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yiyi Sun
+
+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,236 @@
+# Agent World
+
+*Build AI agent teams with just words—no coding required.*
+
+## Why Agent World?
+
+Traditional AI frameworks force you to write hundreds of lines of code just to make agents talk to each other. Agent World lets you create intelligent agent teams using nothing but plain natural language.
+
+Audio introduction: [Listen here](https://yysun.github.io/agent-world)
+
+**Other frameworks:**
+- Install SDKs → write code → handle loops → deploy containers
+- Learn Python/TypeScript before "Hello, world"
+
+**Agent World:**
+- Write prompts → for multiple agents → communicating in a shared world
+```text
+You are @moderator. When someone says "start debate", 
+ask for a topic, then tag @pro and @con to argue.
+```
+Paste that prompt. Agents come alive instantly.
+
+![GitHub](docs/Screenshot-agents.png)
+
+## Why It Works
+
+- ✅ No Code Required - Agents are defined entirely in natural language
+- ✅ Natural Communication - Agents understand context and conversations
+- ✅ Built-in Rules for Messages - Turn limits to prevent loops
+- ✅ Multiple AI Providers - Use different models for different agents
+- ✅ Modern Web Interface - React + Next.js frontend with real-time chat
+
+## What You Can Build
+
+- Debate Club
+```text
+@moderator: Manages rounds, keeps time
+@pro: Argues for the topic  
+@con: Argues against the topic
+```
+
+- Editorial Pipeline
+```text
+@planner: Assigns articles
+@author: Writes drafts
+@editor: Reviews and edits
+@publisher: Formats and publishes
+```
+
+- Game Master
+```text
+@gm: Runs the game, manages state
+@player1, @player2: Take turns
+@assistant: Helps with rules
+```
+
+- Social Simulation
+```text
+@alice: Friendly neighbor
+@bob: Practical problem-solver  
+@charlie: Creative dreamer
+```
+
+- Customer Support
+```text
+@triage: Categorizes requests
+@specialist: Handles technical issues
+@manager: Escalates complaints
+```
+
+## How Agents Communicate
+
+Each Agent World has a collection of agents that can communicate through a shared event system. Agents follow simple rules:
+
+### Message Rules
+
+| Message Type | Example | Who Responds |
+|--------------|---------|--------------|
+| **Human message** | `Hello everyone!` | All active agents |
+| **Direct mention** | `@alice Can you help?` | Only @alice |
+| **Paragraph mention** | `Please review this:\n@alice` | Only @alice |
+| **Mid-text mention** | `I think @alice should help` | Nobody (saved to memory) |
+
+### Agent Behavior
+
+**Agents always respond to:**
+- Human messages (unless mentioned agents exist)
+- Direct @mentions at paragraph start
+- System messages
+
+**Agents never respond to:**
+- Their own messages
+- Other agents (unless @mentioned), but will save message to memory
+- Mid-text mentions (will save message to memory)
+
+**Turn limits prevent loops:**
+- Default: 5 responses per conversation thread
+- Agents automatically pass control back to humans
+- Configurable per world
+
+
+## Installation & Setup
+
+### Prerequisites
+- Node.js 20+ 
+- An API key for your preferred LLM provider
+
+### Quick Start
+
+**Option 1: CLI Interface**
+```bash
+npx agent-world
+```
+
+**Option 2: Web Interface**
+```bash
+npx agent-world --server
+```
+
+## Project Structure (npm workspaces)
+
+This project uses npm workspaces with two main packages:
+
+- **`core/`** - Reusable agent management library
+  - World-mediated agent management system
+  - Event-driven architecture
+  - LLM provider abstraction
+  - Cross-platform compatibility (Node.js/Browser)
+
+- **`next/`** - Next.js web application
+  - React frontend with Tailwind CSS
+  - API routes for CRUD operations
+  - Real-time chat with streaming support
+  - Modern, minimalistic UI
+
+### Cross-workspace imports
+```typescript
+// In next/ workspace
+import { createWorld, listAgents, publishMessage } from '@agent-world/core';
+```
+
+### Web Interface Features
+
+The Next.js workspace provides a modern web interface with:
+
+- **Home Page**: World selector and creator with clean card-based UI
+- **World Page**: Chat interface with agent management sidebar
+  - Real-time messaging with agents
+  - Toggle between streaming and non-streaming modes
+  - Agent creation with custom system prompts
+  - Responsive design with Tailwind CSS
+
+### API Endpoints
+
+The Next.js workspace exposes REST APIs for integration:
+
+```
+GET    /api/worlds                     # List all worlds
+POST   /api/worlds                     # Create new world
+GET    /api/worlds/:id                 # Get world details
+PUT    /api/worlds/:id                 # Update world
+DELETE /api/worlds/:id                 # Delete world
+
+GET    /api/worlds/:id/agents          # List agents in world
+POST   /api/worlds/:id/agents          # Create new agent
+GET    /api/worlds/:id/agents/:agentId # Get agent details
+PUT    /api/worlds/:id/agents/:agentId # Update agent
+DELETE /api/worlds/:id/agents/:agentId # Delete agent
+
+POST   /api/worlds/:id/chat            # Send message (streaming/non-streaming)
+```
+
+### Environment Setup
+
+Export your API keys as environment variables 
+
+```bash
+# Required if Choose one or more
+export OPENAI_API_KEY="your-key-here"
+export ANTHROPIC_API_KEY="your-key-here"  
+export GOOGLE_API_KEY="your-key-here"
+
+# Default: For local models
+export OLLAMA_BASE_URL="http://localhost:11434"
+```
+
+Or create a `.env` file in your working directory with:
+
+```env
+OPENAI_API_KEY=your-key-here
+ANTHROPIC_API_KEY=your-key-here
+GOOGLE_API_KEY=your-key-here
+OLLAMA_BASE_URL=http://localhost:11434
+```
+
+### World Database Setup
+
+The worlds are stored in the SQLite database under the `~/agent-world` directory. You can change the database path by setting the environment variable `AGENT_WORLD_SQLITE_DATABASE`.
+
+Or, you can change the storage type to file-based by setting the environment variable `AGENT_WORLD_STORAGE_TYPE` to `file`. And set the `AGENT_WORLD_DATA_PATH` to your desired directory.
+
+```bash
+# Use file storage
+export AGENT_WORLD_STORAGE_TYPE=file
+export AGENT_WORLD_DATA_PATH=./data/worlds
+```
+
+## Learn More
+
+- **[Building Agents with Just Words](docs/Building%20Agents%20with%20Just%20Words.md)** - Complete guide with examples
+
+
+## Future Plans
+
+- **Long Run Worlds** - Worlds can run for days or weeks, with agents evolving over time
+- **Dynamic Worlds** - Worlds can provide real-time data to agents, e.g. date and time
+- **Tools / MCP Support** - Worlds can have tools for agents to use, like search or code execution
+- **Agent Learning** - Agents will evolve based on interactions
+- **Agent Replication** - Agents can create new agents
+
+## Contributing
+
+Agent World thrives on community examples and improvements:
+
+1. **Share your agent teams** - Submit interesting prompt combinations
+2. **Report bugs** - Help us improve the core system  
+3. **Suggest features** - What would make agents more useful?
+4. **Write docs** - Help others learn faster
+
+## License
+
+MIT License - Build amazing things and share them with the world!
+
+Copyright © 2025 Yiyi Sun
+
+

package/dist/cli/index.js

@@ -0,0 +1,660 @@
+#!/usr/bin/env node
+// Load environment variables from .env file
+import dotenv from 'dotenv';
+dotenv.config();
+/**
+ * Agent World CLI Entry Point - Dual-Mode Console Interface
+ *
+ * Provides pipeline and interactive modes with unified subscription system,
+ * real-time streaming, and comprehensive world management.
+ *
+ * FEATURES:
+ * - Pipeline Mode: Execute commands and exit with timer-based cleanup
+ * - Interactive Mode: Real-time console interface with streaming responses
+ * - Unified Subscription: Both modes use subscribeWorld for consistent event handling
+ * - World Management: Auto-discovery and interactive selection
+ * - Real-time Streaming: Live agent responses via stream.ts module
+ * - Color Helpers: Consistent styling with simplified color functions
+ * - Timer Management: Smart prompt restoration and exit handling
+ * - Debug Logging: Configurable log levels using core logger module
+ * - Environment Variables: Automatically loads .env file for API keys and configuration
+ *
+ * ARCHITECTURE:
+ * - Uses commander.js for argument parsing and mode detection
+ * - Uses subscribeWorld for all world management in both modes
+ * - Implements ClientConnection interface for console-based event handling
+ * - Uses readline for interactive input with proper cleanup
+ * - Delegates streaming display to stream.ts module for real-time chunk accumulation
+ * - Uses core logger for structured debug logging with configurable levels
+ *
+ * USAGE:
+ * Pipeline: cli --root /data/worlds --world myworld --command "/clear agent1"
+ * Pipeline: cli --root /data/worlds --world myworld "Hello, world!"
+ * Pipeline: echo "Hello, world!" | cli --root /data/worlds --world myworld
+ * Interactive: cli --root /data/worlds --world myworld
+ * Debug Mode: cli --root /data/worlds --world myworld --logLevel debug
+ */
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { program } from 'commander';
+import readline from 'readline';
+import { listWorlds, subscribeWorld, createCategoryLogger, LLMProvider, initializeLogger, enableStreaming, disableStreaming } from '../core/index.js';
+import { processCLIInput } from './commands.js';
+import { createStreamingState, handleWorldEventWithStreaming } from './stream.js';
+import { configureLLMProvider } from '../core/llm-config.js';
+// Initialize logger system with default configuration: all categories at 'error' level
+initializeLogger({
+    globalLevel: 'error',
+    categoryLevels: {
+        cli: 'error',
+        core: 'error',
+        events: 'error',
+        llm: 'error'
+    }
+});
+// Create CLI category logger after initialization
+const logger = createCategoryLogger('cli');
+function setupPromptTimer(globalState, rl, callback, delay = 2000) {
+    clearPromptTimer(globalState);
+    globalState.promptTimer = setTimeout(callback, delay);
+}
+function clearPromptTimer(globalState) {
+    if (globalState.promptTimer) {
+        clearTimeout(globalState.promptTimer);
+        globalState.promptTimer = undefined;
+    }
+}
+function createGlobalState() {
+    return {};
+}
+// Color helpers - consolidated styling API
+const red = (text) => `\x1b[31m${text}\x1b[0m`;
+const green = (text) => `\x1b[32m${text}\x1b[0m`;
+const yellow = (text) => `\x1b[33m${text}\x1b[0m`;
+const blue = (text) => `\x1b[34m${text}\x1b[0m`;
+const magenta = (text) => `\x1b[35m${text}\x1b[0m`;
+const cyan = (text) => `\x1b[36m${text}\x1b[0m`;
+const gray = (text) => `\x1b[90m${text}\x1b[0m`;
+const bold = (text) => `\x1b[1m${text}\x1b[0m`;
+const boldRed = (text) => `\x1b[1m\x1b[31m${text}\x1b[0m`;
+const boldGreen = (text) => `\x1b[1m\x1b[32m${text}\x1b[0m`;
+const boldYellow = (text) => `\x1b[1m\x1b[33m${text}\x1b[0m`;
+const boldBlue = (text) => `\x1b[1m\x1b[34m${text}\x1b[0m`;
+const boldMagenta = (text) => `\x1b[1m\x1b[35m${text}\x1b[0m`;
+const boldCyan = (text) => `\x1b[1m\x1b[36m${text}\x1b[0m`;
+const success = (text) => `${boldGreen('✓')} ${text}`;
+const error = (text) => `${boldRed('✗')} ${text}`;
+const bullet = (text) => `${gray('•')} ${text}`;
+// Logger configuration
+async function configureLogger(logLevel) {
+    // Use the centralized logger configuration from core
+    const level = (logLevel || 'error');
+    // Reinitialize logger with new configuration
+    initializeLogger({
+        globalLevel: level,
+        categoryLevels: {
+            cli: 'error', // Always keep CLI at error level
+            core: level, // Core modules use global level
+            events: 'error', // Keep events at error level (too verbose)
+            llm: level, // LLM module uses global level
+        }
+    });
+    // Only log the debug message if we're actually at debug level for global
+    if (level === 'debug' || level === 'trace') {
+        logger.debug(`Global log level set to: ${level}, CLI log level: error`);
+    }
+}
+// LLM Provider configuration from environment variables
+function configureLLMProvidersFromEnv() {
+    // OpenAI
+    if (process.env.OPENAI_API_KEY) {
+        configureLLMProvider(LLMProvider.OPENAI, {
+            apiKey: process.env.OPENAI_API_KEY
+        });
+        logger.debug('Configured OpenAI provider from environment');
+    }
+    // Anthropic
+    if (process.env.ANTHROPIC_API_KEY) {
+        configureLLMProvider(LLMProvider.ANTHROPIC, {
+            apiKey: process.env.ANTHROPIC_API_KEY
+        });
+        logger.debug('Configured Anthropic provider from environment');
+    }
+    // Google
+    if (process.env.GOOGLE_API_KEY) {
+        configureLLMProvider(LLMProvider.GOOGLE, {
+            apiKey: process.env.GOOGLE_API_KEY
+        });
+        logger.debug('Configured Google provider from environment');
+    }
+    // Azure
+    if (process.env.AZURE_OPENAI_API_KEY && process.env.AZURE_ENDPOINT && process.env.AZURE_DEPLOYMENT) {
+        configureLLMProvider(LLMProvider.AZURE, {
+            apiKey: process.env.AZURE_OPENAI_API_KEY,
+            endpoint: process.env.AZURE_ENDPOINT,
+            deployment: process.env.AZURE_DEPLOYMENT,
+            apiVersion: process.env.AZURE_API_VERSION || '2023-12-01-preview'
+        });
+        logger.debug('Configured Azure provider from environment');
+    }
+    // XAI
+    if (process.env.XAI_API_KEY) {
+        configureLLMProvider(LLMProvider.XAI, {
+            apiKey: process.env.XAI_API_KEY
+        });
+        logger.debug('Configured XAI provider from environment');
+    }
+    // OpenAI Compatible
+    if (process.env.OPENAI_COMPATIBLE_API_KEY && process.env.OPENAI_COMPATIBLE_BASE_URL) {
+        configureLLMProvider(LLMProvider.OPENAI_COMPATIBLE, {
+            apiKey: process.env.OPENAI_COMPATIBLE_API_KEY,
+            baseUrl: process.env.OPENAI_COMPATIBLE_BASE_URL
+        });
+        logger.debug('Configured OpenAI-Compatible provider from environment');
+    }
+    // Ollama
+    if (process.env.OLLAMA_BASE_URL) {
+        configureLLMProvider(LLMProvider.OLLAMA, {
+            baseUrl: process.env.OLLAMA_BASE_URL
+        });
+        logger.debug('Configured Ollama provider from environment');
+    }
+    else {
+        // Configure Ollama with default URL if not specified
+        configureLLMProvider(LLMProvider.OLLAMA, {
+            baseUrl: 'http://localhost:11434/api'
+        });
+        logger.debug('Configured Ollama provider with default URL');
+    }
+}
+const AGENT_WORLD_DATA_PATH = process.env.AGENT_WORLD_DATA_PATH || './data/worlds';
+const DEFAULT_ROOT_PATH = path.join(process.cwd(), AGENT_WORLD_DATA_PATH);
+// Pipeline mode execution with timer-based cleanup
+async function runPipelineMode(options, messageFromArgs) {
+    const rootPath = options.root || DEFAULT_ROOT_PATH;
+    disableStreaming();
+    try {
+        let world = null;
+        let worldSubscription = null;
+        let timeoutId = null;
+        const pipelineClient = {
+            isOpen: true,
+            onWorldEvent: (eventType, eventData) => {
+                if (eventData.content && eventData.content.includes('Success message sent'))
+                    return;
+                if ((eventType === 'system' || eventType === 'world') && eventData.message) {
+                    console.log(`${boldRed('● system:')} ${eventData.message}`);
+                }
+                if (eventType === 'sse' && eventData.content) {
+                    setupExitTimer(5000);
+                }
+                if (eventType === 'message' && eventData.content) {
+                    console.log(`${boldGreen('● ' + (eventData.sender || 'agent') + ':')} ${eventData.content}`);
+                    setupExitTimer(3000);
+                }
+            },
+            onError: (error) => {
+                console.log(red(`Error: ${error}`));
+            }
+        };
+        const setupExitTimer = (delay = 2000) => {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => {
+                if (worldSubscription)
+                    worldSubscription.unsubscribe();
+                process.exit(0);
+            }, delay);
+        };
+        if (options.world) {
+            worldSubscription = await subscribeWorld(options.world, rootPath, pipelineClient);
+            if (!worldSubscription) {
+                console.error(boldRed(`Error: World '${options.world}' not found`));
+                process.exit(1);
+            }
+            world = worldSubscription.world;
+        }
+        // Execute command from --command option
+        if (options.command) {
+            if (!options.command.startsWith('/') && !world) {
+                console.error(boldRed('Error: World must be specified to send user messages'));
+                process.exit(1);
+            }
+            const result = await processCLIInput(options.command, world, rootPath, 'HUMAN');
+            console.log(JSON.stringify(result, null, 2));
+            // Only set timer if sending message to world (not for commands)
+            if (!options.command.startsWith('/') && world) {
+                setupExitTimer();
+            }
+            else {
+                // For commands, exit immediately after processing
+                if (worldSubscription)
+                    worldSubscription.unsubscribe();
+                process.exit(result.success ? 0 : 1);
+            }
+            if (!result.success) {
+                setTimeout(() => process.exit(1), 100);
+                return;
+            }
+        }
+        // Execute message from args
+        if (messageFromArgs) {
+            if (!world) {
+                console.error(boldRed('Error: World must be specified to send user messages'));
+                process.exit(1);
+            }
+            const result = await processCLIInput(messageFromArgs, world, rootPath, 'HUMAN');
+            console.log(JSON.stringify(result, null, 2));
+            // Set timer with longer delay for message processing (always needed for messages)
+            setupExitTimer(8000);
+            if (!result.success) {
+                setTimeout(() => process.exit(1), 100);
+                return;
+            }
+        }
+        // Handle stdin input
+        if (!process.stdin.isTTY) {
+            let input = '';
+            process.stdin.setEncoding('utf8');
+            for await (const chunk of process.stdin)
+                input += chunk;
+            if (input.trim()) {
+                if (!world) {
+                    console.error(boldRed('Error: World must be specified to send user messages'));
+                    process.exit(1);
+                }
+                const result = await processCLIInput(input.trim(), world, rootPath, 'HUMAN');
+                console.log(JSON.stringify(result, null, 2));
+                // Set timer with longer delay for message processing (always needed for stdin messages)
+                setupExitTimer(8000);
+                if (!result.success) {
+                    setTimeout(() => process.exit(1), 100);
+                    return;
+                }
+                return;
+            }
+        }
+        if (!options.command && !messageFromArgs) {
+            program.help();
+        }
+    }
+    catch (error) {
+        console.error(boldRed('Error:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+function cleanupWorldSubscription(worldState) {
+    if (worldState?.subscription) {
+        worldState.subscription.unsubscribe();
+    }
+}
+// World subscription handler
+async function handleSubscribe(rootPath, worldName, streaming, globalState, rl) {
+    const cliClient = {
+        isOpen: true,
+        onWorldEvent: (eventType, eventData) => {
+            handleWorldEvent(eventType, eventData, streaming, globalState, rl);
+        },
+        onError: (error) => {
+            console.log(red(`Error: ${error}`));
+        }
+    };
+    const subscription = await subscribeWorld(worldName, rootPath, cliClient);
+    if (!subscription)
+        throw new Error('Failed to load world');
+    return { subscription, world: subscription.world };
+}
+// Handle world events with streaming support
+function handleWorldEvent(eventType, eventData, streaming, globalState, rl) {
+    if (handleWorldEventWithStreaming(eventType, eventData, streaming)) {
+        return;
+    }
+    if (eventData.content && eventData.content.includes('Success message sent'))
+        return;
+    if ((eventType === 'system' || eventType === 'world') && eventData.message) {
+        console.log(`\n${boldRed('● system:')} ${eventData.message}`);
+    }
+}
+// World discovery and selection
+async function getAvailableWorldNames(rootPath) {
+    try {
+        const worldInfos = await listWorlds(rootPath);
+        return worldInfos.map(info => info.id);
+    }
+    catch (error) {
+        console.error('Error listing worlds:', error);
+        return [];
+    }
+}
+async function selectWorld(rootPath, rl) {
+    const worlds = await getAvailableWorldNames(rootPath);
+    if (worlds.length === 0) {
+        console.log(boldRed(`No worlds found in ${rootPath}`));
+        return null;
+    }
+    if (worlds.length === 1) {
+        console.log(`${boldGreen('Auto-selecting the only available world:')} ${cyan(worlds[0])}`);
+        return worlds[0];
+    }
+    console.log(`\n${boldMagenta('Available worlds:')}`);
+    console.log(`  ${yellow('0.')} ${cyan('Exit')}`);
+    worlds.forEach((world, index) => {
+        console.log(`  ${yellow(`${index + 1}.`)} ${cyan(world)}`);
+    });
+    return new Promise((resolve) => {
+        function askForSelection() {
+            rl.question(`\n${boldMagenta('Select a world (number or name), or 0 to exit:')} `, (answer) => {
+                const trimmed = answer.trim();
+                const num = parseInt(trimmed);
+                if (num === 0) {
+                    resolve(null);
+                    return;
+                }
+                if (!isNaN(num) && num >= 1 && num <= worlds.length) {
+                    resolve(worlds[num - 1]);
+                    return;
+                }
+                const found = worlds.find(world => world.toLowerCase() === trimmed.toLowerCase() ||
+                    world.toLowerCase().includes(trimmed.toLowerCase()));
+                if (found) {
+                    resolve(found);
+                    return;
+                }
+                console.log(boldRed('Invalid selection. Please try again.'));
+                askForSelection();
+            });
+        }
+        askForSelection();
+    });
+}
+// Interactive mode: console-based interface
+async function runInteractiveMode(options) {
+    const rootPath = options.root || DEFAULT_ROOT_PATH;
+    enableStreaming();
+    const globalState = createGlobalState();
+    const streaming = createStreamingState();
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: '> '
+    });
+    // Set up streaming callbacks
+    streaming.wait = (delay) => {
+        setupPromptTimer(globalState, rl, () => {
+            if (streaming.isActive) {
+                console.log(`\n${gray('Streaming appears stalled - waiting for user input...')}`);
+                streaming.isActive = false;
+                streaming.content = '';
+                streaming.sender = undefined;
+                streaming.messageId = undefined;
+                rl.prompt();
+            }
+            else {
+                rl.prompt();
+            }
+        }, delay);
+    };
+    streaming.stopWait = () => {
+        clearPromptTimer(globalState);
+    };
+    console.log(boldCyan('Agent World CLI (Interactive Mode)'));
+    console.log(cyan('===================================='));
+    let worldState = null;
+    let currentWorldName = '';
+    let isExiting = false;
+    try {
+        // Load initial world or prompt for selection
+        if (options.world) {
+            logger.debug(`Loading world: ${options.world}`);
+            try {
+                worldState = await handleSubscribe(rootPath, options.world, streaming, globalState, rl);
+                currentWorldName = options.world;
+                console.log(success(`Connected to world: ${currentWorldName}`));
+                if (worldState?.world) {
+                    console.log(`${gray('Agents:')} ${yellow(String(worldState.world.agents?.size || 0))} ${gray('| Turn Limit:')} ${yellow(String(worldState.world.turnLimit || 'N/A'))}`);
+                }
+            }
+            catch (err) {
+                console.error(error(`Error loading world: ${err instanceof Error ? err.message : 'Unknown error'}`));
+                process.exit(1);
+            }
+        }
+        else {
+            console.log(`\n${boldBlue('Discovering available worlds...')}`);
+            const selectedWorld = await selectWorld(rootPath, rl);
+            if (!selectedWorld) {
+                console.log(error('No world selected. Exiting.'));
+                rl.close();
+                return;
+            }
+            logger.debug(`Loading world: ${selectedWorld}`);
+            try {
+                worldState = await handleSubscribe(rootPath, selectedWorld, streaming, globalState, rl);
+                currentWorldName = selectedWorld;
+                console.log(success(`Connected to world: ${currentWorldName}`));
+                if (worldState?.world) {
+                    console.log(`${gray('Agents:')} ${yellow(String(worldState.world.agents?.size || 0))} ${gray('| Turn Limit:')} ${yellow(String(worldState.world.turnLimit || 'N/A'))}`);
+                }
+            }
+            catch (err) {
+                console.error(error(`Error loading world: ${err instanceof Error ? err.message : 'Unknown error'}`));
+                rl.close();
+                return;
+            }
+        }
+        // Show usage tips
+        console.log(`\n${gray('Tips:')}`);
+        console.log(`  ${bullet(gray('Type commands like:'))} ${cyan('/clear agent1')}, ${cyan('/clear all')}, ${cyan('/add MyAgent')}`);
+        console.log(`  ${bullet(gray('Use'))} ${cyan('/select')} ${gray('to choose a different world')}`);
+        console.log(`  ${bullet(gray('Type messages to send to agents'))}`);
+        console.log(`  ${bullet(gray('Use'))} ${cyan('/quit')} ${gray('or')} ${cyan('/exit')} ${gray('to exit, or press')} ${boldYellow('Ctrl+C')}`);
+        console.log(`  ${bullet(gray('Use'))} ${cyan('--logLevel debug')} ${gray('to see detailed debug messages')}`);
+        console.log('');
+        rl.prompt();
+        rl.on('line', async (input) => {
+            const trimmedInput = input.trim();
+            if (!trimmedInput) {
+                rl.prompt();
+                return;
+            }
+            console.log(`\n${boldYellow('● you:')} ${trimmedInput}`);
+            try {
+                const result = await processCLIInput(trimmedInput, worldState?.world || null, rootPath, 'HUMAN');
+                // Handle exit commands
+                if (result.data?.exit) {
+                    if (isExiting)
+                        return; // Prevent duplicate exit handling
+                    isExiting = true;
+                    // Clear any existing timers immediately
+                    if (streaming.stopWait) {
+                        streaming.stopWait();
+                    }
+                    console.log(`\n${boldCyan('Goodbye!')}`);
+                    if (worldState) {
+                        cleanupWorldSubscription(worldState);
+                    }
+                    rl.close();
+                    return;
+                }
+                // Handle world selection command
+                if (result.data?.selectWorld) {
+                    console.log(`\n${boldBlue('Discovering available worlds...')}`);
+                    const selectedWorld = await selectWorld(rootPath, rl);
+                    if (!selectedWorld) {
+                        console.log(error('No world selected.'));
+                        rl.prompt();
+                        return;
+                    }
+                    logger.debug(`Loading world: ${selectedWorld}`);
+                    try {
+                        // Clean up existing world subscription first
+                        if (worldState) {
+                            logger.debug('Cleaning up previous world subscription...');
+                            cleanupWorldSubscription(worldState);
+                            worldState = null;
+                            // Small delay to ensure cleanup is complete
+                            await new Promise(resolve => setTimeout(resolve, 100));
+                        }
+                        // Subscribe to the new world
+                        logger.debug(`Subscribing to world: ${selectedWorld}...`);
+                        worldState = await handleSubscribe(rootPath, selectedWorld, streaming, globalState, rl);
+                        currentWorldName = selectedWorld;
+                        console.log(success(`Connected to world: ${currentWorldName}`));
+                        if (worldState?.world) {
+                            console.log(`${gray('Agents:')} ${yellow(String(worldState.world.agents?.size || 0))} ${gray('| Turn Limit:')} ${yellow(String(worldState.world.turnLimit || 'N/A'))}`);
+                        }
+                    }
+                    catch (err) {
+                        console.error(error(`Error loading world: ${err instanceof Error ? err.message : 'Unknown error'}`));
+                    }
+                    // Show prompt immediately after world selection
+                    rl.prompt();
+                    return;
+                }
+                if (result.success === false) {
+                    console.log(error(`Error: ${result.error || result.message || 'Command failed'}`));
+                }
+                else if (result.message &&
+                    !result.message.includes('Success message sent') &&
+                    !result.message.includes('Message sent to world')) {
+                    console.log(success(result.message));
+                }
+                if (result.data && !(result.data.sender === 'HUMAN')) {
+                    console.log(`${boldMagenta('Data:')} ${JSON.stringify(result.data, null, 2)}`);
+                }
+                // Refresh world if needed
+                if (result.refreshWorld && currentWorldName && worldState) {
+                    try {
+                        console.log(boldBlue('Refreshing world state...'));
+                        // Use the subscription's refresh method to properly destroy old world and create new
+                        const refreshedWorld = await worldState.subscription.refresh(rootPath);
+                        worldState.world = refreshedWorld;
+                        console.log(success('World state refreshed'));
+                    }
+                    catch (err) {
+                        console.error(error(`Error refreshing world: ${err instanceof Error ? err.message : 'Unknown error'}`));
+                    }
+                }
+            }
+            catch (err) {
+                console.error(error(`Command error: ${err instanceof Error ? err.message : 'Unknown error'}`));
+            }
+            // Set timer based on input type: commands get short delay, messages get longer delay
+            const isCommand = trimmedInput.startsWith('/');
+            const isExitCommand = trimmedInput.toLowerCase() === '/exit' || trimmedInput.toLowerCase() === '/quit';
+            const isSelectCommand = trimmedInput.toLowerCase() === '/select';
+            if (isExitCommand) {
+                // For exit commands, don't set any timer - exit should be immediate
+                return;
+            }
+            else if (isSelectCommand) {
+                // For select command, prompt is already shown in the handler
+                return;
+            }
+            else if (isCommand) {
+                // For other commands, show prompt immediately
+                rl.prompt();
+            }
+            else if (streaming.wait) {
+                // For messages, wait for potential agent responses
+                streaming.wait(5000);
+            }
+        });
+        rl.on('close', () => {
+            if (isExiting)
+                return; // Prevent duplicate cleanup
+            isExiting = true;
+            console.log(`\n${boldCyan('Goodbye!')}`);
+            if (worldState) {
+                if (streaming.stopWait) {
+                    streaming.stopWait();
+                }
+                cleanupWorldSubscription(worldState);
+            }
+            process.exit(0);
+        });
+        rl.on('SIGINT', () => {
+            if (isExiting)
+                return; // Prevent duplicate cleanup
+            isExiting = true;
+            console.log(`\n${boldCyan('Goodbye!')}`);
+            if (worldState) {
+                if (streaming.stopWait) {
+                    streaming.stopWait();
+                }
+                cleanupWorldSubscription(worldState);
+            }
+            rl.close();
+        });
+    }
+    catch (err) {
+        console.error(boldRed('Error starting interactive mode:'), err instanceof Error ? err.message : err);
+        rl.close();
+        process.exit(1);
+    }
+}
+// Main CLI entry point
+async function main() {
+    // Configure LLM providers from environment variables at startup
+    configureLLMProvidersFromEnv();
+    program
+        .name('cli')
+        .description('Agent World CLI')
+        .version('1.0.0')
+        .option('-r, --root <path>', 'Root path for worlds data', DEFAULT_ROOT_PATH)
+        .option('-w, --world <name>', 'World name to connect to')
+        .option('-c, --command <cmd>', 'Command to execute in pipeline mode')
+        .option('-l, --logLevel <level>', 'Set log level (trace, debug, info, warn, error)', 'error')
+        .option('-s, --server', 'Launch the server before running CLI')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .parse();
+    const options = program.opts();
+    // If --server is specified, launch the server first
+    if (options.server) {
+        const { spawnSync } = await import('child_process');
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const serverPath = path.resolve(__dirname, '../server/index.js');
+        const serverProcess = spawnSync('node', [serverPath], {
+            stdio: 'inherit',
+            cwd: path.dirname(serverPath),
+            env: process.env
+        });
+        if (serverProcess.error) {
+            console.error(boldRed('Failed to launch server:'), serverProcess.error);
+            process.exit(1);
+        }
+        // If server exits, exit CLI as well
+        process.exit(serverProcess.status || 0);
+    }
+    // Configure logger - set global level first, then CLI-specific level
+    await configureLogger(options.logLevel);
+    const args = program.args;
+    const messageFromArgs = args.length > 0 ? args.join(' ') : null;
+    const isPipelineMode = !!(options.command ||
+        messageFromArgs ||
+        !process.stdin.isTTY);
+    if (isPipelineMode) {
+        await runPipelineMode(options, messageFromArgs);
+    }
+    else {
+        await runInteractiveMode(options);
+    }
+}
+// Global error handling
+function setupErrorHandlers() {
+    process.on('unhandledRejection', (error) => {
+        console.error(boldRed('Unhandled rejection:'), error);
+        process.exit(1);
+    });
+    process.on('uncaughtException', (error) => {
+        console.error(boldRed('Uncaught exception:'), error);
+        process.exit(1);
+    });
+}
+setupErrorHandlers();
+main().catch((error) => {
+    console.error(boldRed('CLI error:'), error);
+    process.exit(1);
+});

package/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent World - Main Package Entry Point
+ *
+ * Features:
+ * - World-centric agent management system
+ * - LLM provider abstraction layer
+ * - Event-driven architecture
+ * - TypeScript-native execution
+ * - Command-line and server interfaces
+ *
+ * This module re-exports the core functionality of Agent World for npm package usage.
+ */
+
+// Re-export all core functionality
+export * from './core/index';
+
+// Package information
+export const PACKAGE_INFO = {
+  name: 'agent-world',
+  version: '0.3.0',
+  description: 'A agent management system for building AI agent teams with just words.',
+} as const;

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "agent-world",
+  "version": "0.4.0",
+  "main": "index.ts",
+  "type": "module",
+  "workspaces": [
+    "core",
+    "next"
+  ],
+  "bin": {
+    "agent-world": "dist/cli/index.js"
+  },
+  "scripts": {
+    "prestart": "npm run build",
+    "start": "node dist/server/index.js",
+    "cli": "npx tsx cli/index.ts",
+    "server": "npx tsx server/index.ts",
+    "dev-web": "concurrently \"npm run server\" \"cd web && npm run dev\"",
+    "test": "jest --config jest.config.js",
+    "check": "tsc --noEmit",
+    "build": "tsc && cd web && npm run build",
+    "pkill": "pkill -f tsx",
+    "dev": "cd next && npm run dev"
+  },
+  "description": "World-mediated agent management system with clean API surface",
+  "keywords": [
+    "agents",
+    "ai",
+    "llm",
+    "world",
+    "typescript",
+    "api"
+  ],
+  "author": "",
+  "license": "ISC",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.2.12",
+    "@ai-sdk/azure": "^1.3.23",
+    "@ai-sdk/google": "^1.2.19",
+    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/openai-compatible": "^0.2.14",
+    "@ai-sdk/xai": "^1.2.16",
+    "@types/terminal-kit": "^2.5.7",
+    "ai": "^4.3.16",
+    "chalk": "^4.1.2",
+    "cors": "^2.8.5",
+    "dotenv": "^16.5.0",
+    "events": "^3.3.0",
+    "express": "^4.21.2",
+    "ollama-ai-provider": "^1.2.0",
+    "open": "^10.2.0",
+    "pino": "^9.7.0",
+    "pino-pretty": "^13.0.0",
+    "sqlite3": "^5.1.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.3",
+    "uuid": "^11.1.0",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/chalk": "^0.4.31",
+    "@types/cors": "^2.8.14",
+    "@types/express": "^4.17.23",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.9",
+    "@types/pino": "^7.0.4",
+    "@types/sqlite3": "^3.1.11",
+    "@types/tmp": "^0.2.0",
+    "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.18.1",
+    "commander": "^14.0.0",
+    "concurrently": "^9.1.2",
+    "esbuild": "^0.21.5",
+    "jest": "^29.5.0",
+    "nodemon": "^3.1.10",
+    "tmp": "^0.2.0",
+    "ts-jest": "^29.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}