agent-world 0.11.1 → 0.12.0

package/dist/server/index.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Web Server - Express.js HTTP Server with REST API and SSE
+ *
+ * Features:
+ * - Express server with CORS, static files, and modular API routing
+ * - Environment-based LLM provider configuration
+ * - Category-based logging with configurable levels
+ * - Health check endpoint and proper error handling
+ * - Environment Variables: Automatically loads .env file for API keys and configuration
+ * - Controlled startup behavior for direct execution vs imported usage
+ * - Optional browser auto-open and process signal handler registration
+ *
+ * Configuration: AGENT_WORLD_DATA_PATH, LOG_LEVEL, LLM provider keys
+ * Endpoints: /health + API routes from ./api.ts
+ *
+ * Recent Changes:
+ * - 2026-02-08: Fixed auto-run detection to only trigger on direct execution
+ * - 2026-02-08: Made browser auto-open configurable via AGENT_WORLD_AUTO_OPEN env var
+ * - 2026-02-08: Prevented duplicate process signal handler registration using WeakSet
+ * - 2026-02-08: Added shutdown guard to prevent race conditions during graceful shutdown
+ */
+import { Server } from 'http';
+type StartWebServerOptions = {
+    openBrowser?: boolean;
+    registerProcessHandlers?: boolean;
+};
+export declare function startWebServer(port?: number, host?: string, options?: StartWebServerOptions): Promise<Server>;
+export {};

package/dist/server/sse-handler.d.ts

@@ -0,0 +1,62 @@
+/**
+ * SSE Event Handler - Reusable Server-Sent Events Logic
+ *
+ * Purpose: Centralized SSE streaming logic for world events
+ *
+ * Features:
+ * - Sets up SSE response headers and connection
+ * - Wires world event listeners (MESSAGE, SSE, SYSTEM, WORLD)
+ * - Handles world activity state tracking (response-start, idle)
+ * - Forwards tool events (tool-start, tool-result, tool-error, tool-progress) as SSE events
+ * - Automatic stream completion when world becomes idle
+ * - Timeout fallback (60s) if world never becomes idle
+ * - Proper cleanup on client disconnect or stream end
+ *
+ * Event Routing:
+ * - 'world' channel carries both WorldActivityEvent and WorldToolEvent types
+ * - WorldActivityEvent (response-start, idle, response-end) → manages stream lifecycle
+ * - WorldToolEvent (tool-start, tool-result, tool-error, tool-progress) → forwarded as SSE events
+ *
+ * Usage:
+ * ```typescript
+ * const handler = createSSEHandler(req, res, world, 'chat');
+ *
+ * // Publish your event (message, tool result, etc.)
+ * publishMessage(world, message, sender);
+ *
+ * // Optional: Send custom event
+ * handler.sendSSE({ type: 'custom', data: {...} });
+ * ```
+ *
+ * Created: 2025-11-10 - Extracted from api.ts for reusability
+ * Updated: 2026-02-11 - Extended fallback timeout on tool-stream events to prevent premature timeout
+ * Updated: 2026-02-08 - Removed manual tool-intervention SSE commentary and kept generic tool_call forwarding
+ * Updated: 2025-11-10 - Added tool event forwarding to SSE channel
+ */
+import { Request, Response } from 'express';
+import { World } from '../core/index.js';
+export interface SSEHandler {
+    /**
+     * Send a Server-Sent Event to the client
+     * @param data - Data object to send (will be JSON stringified)
+     */
+    sendSSE: (data: any) => void;
+    /**
+     * Manually end the SSE response
+     */
+    endResponse: () => void;
+    /**
+     * Check if the response has ended
+     */
+    isEnded: () => boolean;
+}
+/**
+ * Create and configure an SSE handler for streaming world events
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param world - World instance to listen to
+ * @param context - Context label for logging (e.g., 'chat', 'tool-result')
+ * @returns SSEHandler interface with sendSSE, endResponse, and isEnded methods
+ */
+export declare function createSSEHandler(req: Request, res: Response, world: World, context?: string, scopedChatId?: string | null): SSEHandler;

package/dist/server/sse-handler.js

@@ -0,0 +1,234 @@
+/**
+ * SSE Event Handler - Reusable Server-Sent Events Logic
+ *
+ * Purpose: Centralized SSE streaming logic for world events
+ *
+ * Features:
+ * - Sets up SSE response headers and connection
+ * - Wires world event listeners (MESSAGE, SSE, SYSTEM, WORLD)
+ * - Handles world activity state tracking (response-start, idle)
+ * - Forwards tool events (tool-start, tool-result, tool-error, tool-progress) as SSE events
+ * - Automatic stream completion when world becomes idle
+ * - Timeout fallback (60s) if world never becomes idle
+ * - Proper cleanup on client disconnect or stream end
+ *
+ * Event Routing:
+ * - 'world' channel carries both WorldActivityEvent and WorldToolEvent types
+ * - WorldActivityEvent (response-start, idle, response-end) → manages stream lifecycle
+ * - WorldToolEvent (tool-start, tool-result, tool-error, tool-progress) → forwarded as SSE events
+ *
+ * Usage:
+ * ```typescript
+ * const handler = createSSEHandler(req, res, world, 'chat');
+ *
+ * // Publish your event (message, tool result, etc.)
+ * publishMessage(world, message, sender);
+ *
+ * // Optional: Send custom event
+ * handler.sendSSE({ type: 'custom', data: {...} });
+ * ```
+ *
+ * Created: 2025-11-10 - Extracted from api.ts for reusability
+ * Updated: 2026-02-11 - Extended fallback timeout on tool-stream events to prevent premature timeout
+ * Updated: 2026-02-08 - Removed manual tool-intervention SSE commentary and kept generic tool_call forwarding
+ * Updated: 2025-11-10 - Added tool event forwarding to SSE channel
+ */
+import { createCategoryLogger, EventType } from '../core/index.js';
+const loggerStream = createCategoryLogger('api.stream');
+// Timeout constants for streaming (fallback only)
+const STREAM_TIMEOUT_NO_EVENTS_MS = 15000;
+/**
+ * Create and configure an SSE handler for streaming world events
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param world - World instance to listen to
+ * @param context - Context label for logging (e.g., 'chat', 'tool-result')
+ * @returns SSEHandler interface with sendSSE, endResponse, and isEnded methods
+ */
+export function createSSEHandler(req, res, world, context = 'sse', scopedChatId) {
+    // Set SSE headers
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Headers', 'Cache-Control');
+    let timeoutTimer;
+    let hasReceivedEvents = false;
+    let isResponseEnded = false;
+    let lastEventTime = Date.now();
+    let awaitingWorldIdle = false;
+    const startTimeoutFallback = () => {
+        if (timeoutTimer)
+            clearTimeout(timeoutTimer);
+        if (isResponseEnded)
+            return;
+        // Fallback timeout - only used if world never becomes idle
+        timeoutTimer = setTimeout(() => {
+            if (!isResponseEnded) {
+                const timeSinceLastEvent = Date.now() - lastEventTime;
+                loggerStream.debug(`[${context}] Streaming timeout fallback triggered: timeSinceLastEvent=${timeSinceLastEvent}ms, awaitingWorldIdle=${awaitingWorldIdle}`);
+                if (!hasReceivedEvents && timeSinceLastEvent >= STREAM_TIMEOUT_NO_EVENTS_MS) {
+                    loggerStream.debug(`[${context}] Ending stream: no events received within ${STREAM_TIMEOUT_NO_EVENTS_MS}ms`);
+                    endResponse();
+                }
+                else if (timeSinceLastEvent >= 60000) {
+                    // 60 second absolute timeout as fallback
+                    loggerStream.debug(`[${context}] Ending stream: absolute timeout (60s) reached`);
+                    endResponse();
+                }
+            }
+        }, 60000);
+    };
+    const endResponse = () => {
+        if (isResponseEnded)
+            return;
+        isResponseEnded = true;
+        if (timeoutTimer) {
+            clearTimeout(timeoutTimer);
+            timeoutTimer = undefined;
+        }
+        loggerStream.debug(`[${context}] Ending SSE response. Stats: events=${hasReceivedEvents}, awaitingWorldIdle=${awaitingWorldIdle}`);
+        try {
+            if (!res.destroyed) {
+                res.end();
+            }
+        }
+        catch (error) {
+            loggerStream.debug(`[${context}] Error ending response (likely already closed):`, error);
+        }
+    };
+    const sendSSE = (data) => {
+        if (isResponseEnded || res.destroyed)
+            return;
+        try {
+            const jsonData = typeof data === 'string' ? data : JSON.stringify(data);
+            res.write(`data: ${jsonData}\n\n`);
+            hasReceivedEvents = true;
+            lastEventTime = Date.now();
+        }
+        catch (error) {
+            loggerStream.debug(`[${context}] Error writing SSE data:`, error);
+            endResponse();
+        }
+    };
+    const listeners = new Map();
+    const normalizedScopedChatId = scopedChatId === undefined ? undefined : (scopedChatId === null ? null : String(scopedChatId));
+    const isChatEventInScope = (eventChatId, includeUnscopedWhenScoped = false) => {
+        if (normalizedScopedChatId === undefined)
+            return true;
+        if (eventChatId === undefined)
+            return includeUnscopedWhenScoped;
+        const normalizedEventChatId = eventChatId === null ? null : String(eventChatId);
+        return normalizedEventChatId === normalizedScopedChatId;
+    };
+    // Attach direct listeners to world.eventEmitter
+    const worldListener = (eventData) => {
+        // Check if this is a tool event (tool-start, tool-result, tool-error, tool-progress)
+        const isToolEvent = eventData?.type && ['tool-start', 'tool-result', 'tool-error', 'tool-progress'].includes(eventData.type);
+        if (isToolEvent) {
+            if (!isChatEventInScope(eventData?.chatId, false)) {
+                return;
+            }
+            // Forward tool events as SSE events for frontend consumption
+            sendSSE({
+                type: EventType.SSE,
+                data: {
+                    type: eventData.type,
+                    messageId: eventData.messageId,
+                    agentName: eventData.agentName,
+                    toolExecution: eventData.toolExecution,
+                    chatId: eventData.chatId
+                }
+            });
+            return;
+        }
+        // Handle world activity events for stream completion
+        if (eventData?.type === 'response-start') {
+            awaitingWorldIdle = true;
+            loggerStream.debug(`[${context}] World processing started`, {
+                activityId: eventData.activityId,
+                source: eventData.source
+            });
+        }
+        else if (eventData?.type === 'idle' && awaitingWorldIdle) {
+            loggerStream.debug(`[${context}] World idle detected, ending stream`, {
+                activityId: eventData.activityId
+            });
+            // Stream all pending events, then end
+            sendSSE({ type: EventType.WORLD, data: eventData });
+            // Give a small delay for any final events to be sent
+            setTimeout(() => {
+                endResponse();
+            }, 500);
+            return;
+        }
+        if (isChatEventInScope(eventData?.chatId, true)) {
+            sendSSE({ type: EventType.WORLD, data: eventData });
+        }
+    };
+    world.eventEmitter.on(EventType.WORLD, worldListener);
+    listeners.set(EventType.WORLD, worldListener);
+    const messageListener = (eventData) => {
+        if (!isChatEventInScope(eventData?.chatId, false)) {
+            return;
+        }
+        // Enhance message event data with structured format
+        // CRITICAL: replyToMessageId must be included for frontend threading display
+        // Include tool_calls to preserve complete assistant tool-call context on the client.
+        const messageData = {
+            type: 'message',
+            sender: eventData.sender,
+            content: eventData.content,
+            messageId: eventData.messageId,
+            chatId: eventData.chatId,
+            replyToMessageId: eventData.replyToMessageId,
+            createdAt: eventData.timestamp || new Date().toISOString(),
+            role: eventData.role,
+            tool_calls: eventData.tool_calls
+        };
+        sendSSE({ type: EventType.MESSAGE, data: messageData });
+    };
+    world.eventEmitter.on(EventType.MESSAGE, messageListener);
+    listeners.set(EventType.MESSAGE, messageListener);
+    const sseListener = (eventData) => {
+        if (!isChatEventInScope(eventData?.chatId, false)) {
+            return;
+        }
+        // Extend fallback timeout when tool-stream data arrives (keeps long-running tools alive)
+        if (eventData.type === 'tool-stream') {
+            startTimeoutFallback();
+        }
+        sendSSE({ type: EventType.SSE, data: eventData });
+    };
+    world.eventEmitter.on(EventType.SSE, sseListener);
+    listeners.set(EventType.SSE, sseListener);
+    const systemListener = (eventData) => {
+        if (!isChatEventInScope(eventData?.chatId, true)) {
+            return;
+        }
+        sendSSE({ type: EventType.SYSTEM, data: eventData });
+    };
+    world.eventEmitter.on(EventType.SYSTEM, systemListener);
+    listeners.set(EventType.SYSTEM, systemListener);
+    // Cleanup function to remove all listeners
+    const cleanupListeners = () => {
+        for (const [eventType, listener] of listeners.entries()) {
+            world.eventEmitter.removeListener(eventType, listener);
+        }
+        listeners.clear();
+    };
+    // Handle client disconnect
+    req.on('close', () => {
+        loggerStream.debug(`[${context}] Client disconnected, cleaning up`);
+        cleanupListeners();
+        endResponse();
+    });
+    // Start the fallback timeout
+    startTimeoutFallback();
+    return {
+        sendSSE,
+        endResponse,
+        isEnded: () => isResponseEnded
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-world",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -20,7 +20,7 @@
     "web"
   ],
   "bin": {
-    "agent-world": "scripts/launch-electron.js",
+    "agent-world": "dist/server/index.js",
     "agent-world-cli": "dist/cli/index.js",
     "agent-world-server": "dist/server/index.js"
   },
@@ -38,7 +38,7 @@
     "build": "npm run build --workspace=core && tsc --project tsconfig.build.json && npm run build --workspace=web",
     "build:core": "npm run build --workspace=core",
     "build:core:watch": "npm run build --workspace=core -- --watch --preserveWatchOutput",
-    "check": "tsc --noEmit --project tsconfig.build.json && npm run check --workspace=core && npm run check --workspace=web",
+    "check": "tsc --noEmit --project tsconfig.build.json && npm run check --workspace=core && npm run check --workspace=web && npm run main:build --prefix electron",
     "server:dev": "npx tsx server/index.ts",
     "server:watch": "npx tsx --watch server/index.ts",
     "server:start": "node dist/server/index.js",
@@ -67,11 +67,23 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@google/generative-ai": "^0.24.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.5.0",
     "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
     "enquirer": "^2.4.1",
     "express": "^4.22.1",
+    "events": "^3.3.0",
+    "fast-glob": "^3.3.3",
+    "nanoid": "^5.1.5",
     "open": "^11.0.0",
+    "openai": "^6.15.0",
+    "pino": "^10.0.0",
+    "pino-pretty": "^13.1.3",
+    "sqlite3": "^5.1.7",
+    "zod": "^4.2.1",
     "tsx": "^4.21.0"
   },
   "devDependencies": {

package/scripts/launch-electron.js

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Launch Electron App - Simple launcher for agent-world desktop app
- * 
- * Purpose:
- * - Launch the Electron desktop app when running `agent-world` command
- * - Ensures necessary builds exist before launching
- * 
- * Features:
- * - Checks for core build
- * - Launches Electron app
- * - Provides helpful error messages if builds are missing
- * 
- * Implementation Notes:
- * - Used as bin entry point in package.json
- * - Replaces CLI as default when running `agent-world` command
- */
-
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-import fs from 'node:fs';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const projectRoot = path.resolve(__dirname, '..');
-
-// Check if core build exists
-const coreIndexPath = path.join(projectRoot, 'dist', 'core', 'index.js');
-if (!fs.existsSync(coreIndexPath)) {
-  console.error('Error: Core build not found. Please run: npm run build');
-  process.exit(1);
-}
-
-// Check if electron directory exists
-const electronPath = path.join(projectRoot, 'electron');
-if (!fs.existsSync(electronPath)) {
-  console.error('Error: Electron app not found.');
-  process.exit(1);
-}
-
-// Launch Electron app
-const electronMainPath = path.join(electronPath, 'main.js');
-const electronProcess = spawn('npx', ['electron', electronMainPath], {
-  cwd: projectRoot,
-  stdio: 'inherit',
-  env: { ...process.env }
-});
-
-electronProcess.on('error', (error) => {
-  console.error('Failed to launch Electron app:', error);
-  process.exit(1);
-});
-
-electronProcess.on('exit', (code) => {
-  process.exit(code || 0);
-});