agent-world 0.13.0 → 0.15.0

package/dist/server/sse-handler.js

@@ -29,16 +29,23 @@
  * ```
  *
  * Created: 2025-11-10 - Extracted from api.ts for reusability
+ * Updated: 2026-03-01 - Skip synthesis for 'edit' context to prevent duplicate "From human" messages after message edits.
+ * Updated: 2026-03-11 - Exposed a readiness promise so chat/edit dispatch waits until SSE listeners are attached, preventing the web client from missing the initial user-message echo.
+ * Updated: 2026-03-11 - Replaced optional-call resolution of the readiness promise with an explicit helper to satisfy
+ *   strict TypeScript control-flow analysis in the build config.
+ * Updated: 2026-02-27 - Scoped realtime log forwarding by world/chat to prevent cross-chat log leakage in chat-scoped streams.
+ * Updated: 2026-02-26 - Added realtime log-stream forwarding (`type: 'log'`) to SSE clients to align web error visibility with Electron.
  * Updated: 2026-02-20 - Removed stale legacy event-channel SSE forwarding from this handler.
- * Updated: 2026-02-20 - Keep `hitl-option-request` system events bypassing strict chat scope filtering so HITL prompts are always delivered.
+ * Updated: 2026-02-21 - Refresh fallback timeout on shell assistant-stream SSE activity (`start`/`chunk`/`end` + `toolName='shell_cmd'`) as well as legacy `tool-stream`.
  * 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';
+import { addLogStreamCallback, createCategoryLogger, EventType, getMemory, listPendingHitlPromptEventsFromMessages } from '../core/index.js';
 const loggerStream = createCategoryLogger('api.stream');
 // Timeout constants for streaming (fallback only)
 const STREAM_TIMEOUT_NO_EVENTS_MS = 15000;
+const STREAM_IDLE_CLOSE_DELAY_MS = 2000;
 /**
  * Create and configure an SSE handler for streaming world events
  *
@@ -56,6 +63,7 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.setHeader('Access-Control-Allow-Headers', 'Cache-Control');
     let timeoutTimer;
+    let idleCloseTimer;
     let hasReceivedEvents = false;
     let isResponseEnded = false;
     let lastEventTime = Date.now();
@@ -90,6 +98,10 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
             clearTimeout(timeoutTimer);
             timeoutTimer = undefined;
         }
+        if (idleCloseTimer) {
+            clearTimeout(idleCloseTimer);
+            idleCloseTimer = undefined;
+        }
         loggerStream.debug(`[${context}] Ending SSE response. Stats: events=${hasReceivedEvents}, awaitingWorldIdle=${awaitingWorldIdle}`);
         try {
             if (!res.destroyed) {
@@ -124,21 +136,22 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
         const normalizedEventChatId = eventChatId === null ? null : String(eventChatId);
         return normalizedEventChatId === normalizedScopedChatId;
     };
-    const isHitlRequestEvent = (eventData) => {
-        if (!eventData)
-            return false;
-        const content = eventData.content;
-        if (content && typeof content === 'object') {
-            const eventType = String(content.eventType || '').trim();
-            return eventType === 'hitl-option-request';
-        }
-        if (typeof content === 'string') {
-            const eventType = content.trim();
-            return eventType === 'hitl-option-request';
-        }
-        return false;
+    // Track already-sent ids to avoid double-emitting synthesized -> live events
+    const sentMessageIds = new Set();
+    const sentToolCallIds = new Set();
+    let resolveReady = null;
+    const ready = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    const markReady = () => {
+        if (!resolveReady) {
+            return;
+        }
+        const resolve = resolveReady;
+        resolveReady = null;
+        resolve();
     };
-    // Attach direct listeners to world.eventEmitter
+    // Attach direct listeners to world.eventEmitter (defined inside attach to allow synth-before-attach)
     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);
@@ -161,6 +174,10 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
         }
         // Handle world activity events for stream completion
         if (eventData?.type === 'response-start') {
+            if (idleCloseTimer) {
+                clearTimeout(idleCloseTimer);
+                idleCloseTimer = undefined;
+            }
             awaitingWorldIdle = true;
             loggerStream.debug(`[${context}] World processing started`, {
                 activityId: eventData.activityId,
@@ -171,20 +188,24 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
             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);
+            awaitingWorldIdle = false;
+            if (idleCloseTimer) {
+                clearTimeout(idleCloseTimer);
+            }
+            idleCloseTimer = setTimeout(() => {
+                // If no new response-start arrived during the grace window,
+                // treat this idle as final and close the stream.
+                if (!awaitingWorldIdle) {
+                    endResponse();
+                }
+            }, STREAM_IDLE_CLOSE_DELAY_MS);
             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;
@@ -201,39 +222,177 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
             replyToMessageId: eventData.replyToMessageId,
             createdAt: eventData.timestamp || new Date().toISOString(),
             role: eventData.role,
-            tool_calls: eventData.tool_calls
+            tool_calls: eventData.tool_calls,
+            tool_call_id: eventData.tool_call_id
         };
         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') {
+        // Extend fallback timeout for long-running shell stream activity.
+        const isLegacyToolStream = eventData.type === 'tool-stream';
+        const isShellAssistantStream = eventData.toolName === 'shell_cmd' &&
+            (eventData.type === 'start' || eventData.type === 'chunk' || eventData.type === 'end');
+        if (isLegacyToolStream || isShellAssistantStream) {
             startTimeoutFallback();
         }
         sendSSE({ type: EventType.SSE, data: eventData });
     };
-    world.eventEmitter.on(EventType.SSE, sseListener);
-    listeners.set(EventType.SSE, sseListener);
     const systemListener = (eventData) => {
-        const isHitlRequest = isHitlRequestEvent(eventData);
-        if (!isHitlRequest && !isChatEventInScope(eventData?.chatId, true)) {
+        if (!isChatEventInScope(eventData?.chatId, false)) {
             return;
         }
         sendSSE({ type: EventType.SYSTEM, data: eventData });
     };
-    world.eventEmitter.on(EventType.SYSTEM, systemListener);
-    listeners.set(EventType.SYSTEM, systemListener);
+    // Mirror Electron's global log forwarding pattern:
+    // stream backend logger events as SSE `type: 'log'` payloads during the active request.
+    const logListener = (logEvent) => {
+        const logData = logEvent?.data && typeof logEvent.data === 'object' ? logEvent.data : null;
+        const logWorldId = (typeof logEvent?.worldId === 'string' && logEvent.worldId.trim()) ? logEvent.worldId.trim()
+            : (typeof logData?.worldId === 'string' && String(logData.worldId).trim())
+                ? String(logData.worldId).trim()
+                : undefined;
+        if (logWorldId && logWorldId !== world.id) {
+            return;
+        }
+        const logChatId = (typeof logEvent?.chatId === 'string' && logEvent.chatId.trim()) ? logEvent.chatId.trim()
+            : (logEvent?.chatId === null ? null
+                : (typeof logData?.chatId === 'string' && logData.chatId.trim()) ? logData.chatId.trim()
+                    : (logData?.chatId === null ? null : undefined));
+        if (!isChatEventInScope(logChatId, false)) {
+            return;
+        }
+        sendSSE({
+            type: EventType.SSE,
+            data: {
+                type: 'log',
+                chatId: logChatId,
+                messageId: logEvent?.messageId || `log-${Date.now()}`,
+                logEvent: {
+                    level: logEvent?.level || 'info',
+                    category: logEvent?.category || 'unknown',
+                    message: logEvent?.message || '',
+                    timestamp: logEvent?.timestamp || new Date().toISOString(),
+                    data: logData ?? null,
+                    messageId: logEvent?.messageId || `log-${Date.now()}`,
+                    chatId: logChatId
+                }
+            }
+        });
+    };
+    let unsubscribeLogStream = null;
+    // NOTE: listeners are attached after an initial synthesis step below to avoid race
+    // where core resume emits events before the client has subscribed.
+    async function attachListeners() {
+        world.eventEmitter.on(EventType.WORLD, worldListener);
+        listeners.set(EventType.WORLD, worldListener);
+        world.eventEmitter.on(EventType.MESSAGE, messageListener);
+        listeners.set(EventType.MESSAGE, messageListener);
+        world.eventEmitter.on(EventType.SSE, sseListener);
+        listeners.set(EventType.SSE, sseListener);
+        world.eventEmitter.on(EventType.SYSTEM, systemListener);
+        listeners.set(EventType.SYSTEM, systemListener);
+        unsubscribeLogStream = addLogStreamCallback(logListener);
+    }
+    // Synthesis: use persisted memory as the source of truth to restore UI state
+    (async () => {
+        try {
+            // Skip synthesis for edit operations: the edit flow removes old messages and immediately
+            // publishes a fresh user message via publishMessage, so synthesizing the pre-edit last
+            // user message would cause a duplicate "From human" message in the UI.
+            if (context === 'edit') {
+                return;
+            }
+            if (!normalizedScopedChatId) {
+                return;
+            }
+            // Try to read canonical chat memory using public core helper
+            const memory = await getMemory(world.id, normalizedScopedChatId);
+            if (Array.isArray(memory) && memory.length > 0) {
+                // Send the most recent user message if the last message is a user message
+                const lastMessage = memory[memory.length - 1];
+                if (lastMessage && lastMessage.messageId) {
+                    // Mark as sent to avoid double-emitting when live listeners arrive
+                    sentMessageIds.add(String(lastMessage.messageId));
+                    if (lastMessage.role === 'user') {
+                        const messageData = {
+                            type: 'message',
+                            sender: lastMessage.sender,
+                            content: lastMessage.content,
+                            messageId: lastMessage.messageId,
+                            chatId: lastMessage.chatId,
+                            replyToMessageId: lastMessage.replyToMessageId,
+                            createdAt: lastMessage.createdAt || new Date().toISOString(),
+                            role: lastMessage.role,
+                            tool_calls: lastMessage.tool_calls
+                        };
+                        sendSSE({ type: EventType.MESSAGE, data: messageData });
+                    }
+                    else if (lastMessage.role === 'assistant' && Array.isArray(lastMessage.tool_calls) && lastMessage.tool_calls.length > 0) {
+                        // Detect unresolved tool calls by scanning persisted memory for completed tool messages
+                        const completedToolCallIds = new Set();
+                        for (const m of memory) {
+                            if (m.role === 'tool' && typeof m.tool_call_id === 'string') {
+                                completedToolCallIds.add(String(m.tool_call_id));
+                            }
+                        }
+                        for (const tc of lastMessage.tool_calls) {
+                            const toolCallId = String(tc?.id || '').trim();
+                            const toolName = String(tc?.function?.name || '').trim();
+                            if (!toolCallId || completedToolCallIds.has(toolCallId))
+                                continue;
+                            // Synthesize a tool-start event so the UI can show pending work / HITL
+                            sentToolCallIds.add(toolCallId);
+                            sendSSE({
+                                type: EventType.SSE,
+                                data: {
+                                    type: 'tool-start',
+                                    messageId: toolCallId,
+                                    agentName: lastMessage.agentId || undefined,
+                                    chatId: lastMessage.chatId,
+                                    toolExecution: {
+                                        toolName,
+                                        toolCallId,
+                                        input: tc?.function?.arguments || {}
+                                    }
+                                }
+                            });
+                        }
+                    }
+                    // Also synthesize any pending HITL prompts derived from memory
+                    try {
+                        const pendingHitl = listPendingHitlPromptEventsFromMessages(memory || [], normalizedScopedChatId === undefined ? null : normalizedScopedChatId);
+                        for (const h of pendingHitl) {
+                            sendSSE({ type: EventType.SYSTEM, data: h });
+                        }
+                    }
+                    catch (hitlErr) {
+                        loggerStream.debug(`[${context}] failed to synthesize HITL prompts:`, hitlErr);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            loggerStream.debug(`[${context}] failed to synthesize persisted state:`, error);
+        }
+        finally {
+            // Attach live listeners after synthesis to avoid race where resume emits before client subscribed
+            attachListeners();
+            markReady();
+        }
+    })();
     // Cleanup function to remove all listeners
     const cleanupListeners = () => {
         for (const [eventType, listener] of listeners.entries()) {
             world.eventEmitter.removeListener(eventType, listener);
         }
         listeners.clear();
+        if (unsubscribeLogStream) {
+            unsubscribeLogStream();
+            unsubscribeLogStream = null;
+        }
     };
     // Handle client disconnect
     req.on('close', () => {
@@ -244,6 +403,7 @@ export function createSSEHandler(req, res, world, context = 'sse', scopedChatId)
     // Start the fallback timeout
     startTimeoutFallback();
     return {
+        ready,
         sendSSE,
         endResponse,
         isEnded: () => isResponseEnded

package/migrations/0015_add_message_queue.sql

@@ -0,0 +1,36 @@
+-- Migration: Create message_queue table for user message queue feature
+-- Version: 15
+-- Date: 2026-03-01
+--
+-- Creates a dedicated message_queue table to persist user messages that are
+-- queued for sequential processing. A separate table (rather than an
+-- agent_memory status column) is used to avoid the agent_id FK constraint
+-- on agent_memory, since queued messages are not yet associated with a
+-- specific agent.
+--
+-- Status lifecycle:
+--   queued    -> sending -> (row deleted when processed successfully)
+--   queued    -> cancelled  (when user stops/clears queue)
+--   sending   -> queued     (startup recovery: interrupted sessions reset)
+--   sending   -> error      (after max retries exhausted)
+
+CREATE TABLE IF NOT EXISTS message_queue (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  world_id TEXT NOT NULL,
+  chat_id TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  content TEXT NOT NULL,
+  sender TEXT NOT NULL DEFAULT 'human',
+  status TEXT NOT NULL DEFAULT 'queued',
+  retry_count INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (world_id) REFERENCES worlds(id) ON DELETE CASCADE,
+  FOREIGN KEY (chat_id) REFERENCES world_chats(id) ON DELETE CASCADE
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_message_queue_message_id
+  ON message_queue(message_id);
+
+CREATE INDEX IF NOT EXISTS idx_message_queue_chat
+  ON message_queue(world_id, chat_id, status);

package/migrations/0016_add_world_heartbeat.sql

@@ -0,0 +1,13 @@
+-- Migration: Add world heartbeat configuration fields
+-- Version: 16
+-- Date: 2026-03-04
+--
+-- Adds persisted world heartbeat controls used by Electron main runtime.
+-- Fields:
+--   heartbeat_enabled  - whether heartbeat scheduling is enabled
+--   heartbeat_interval - cron expression (product policy: strict 5-field)
+--   heartbeat_prompt   - message content published on each tick
+
+ALTER TABLE worlds ADD COLUMN heartbeat_enabled INTEGER DEFAULT 0;
+ALTER TABLE worlds ADD COLUMN heartbeat_interval TEXT;
+ALTER TABLE worlds ADD COLUMN heartbeat_prompt TEXT;

package/migrations/0017_add_title_provenance.sql

@@ -0,0 +1,7 @@
+-- Migration: Add title_provenance column to world_chats
+-- Purpose: Track whether a chat title was set by default, auto-generated, or manually assigned.
+-- Notes:
+--   - DEFAULT 'default' ensures existing rows are treated as legacy (favor-preserve) per REQ-11.
+--   - Valid values: 'default' (untitled/legacy), 'auto' (auto-generated), 'manual' (user-renamed).
+ALTER TABLE world_chats
+ADD COLUMN title_provenance TEXT DEFAULT 'default';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-world",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -17,7 +17,8 @@
   "type": "module",
   "workspaces": [
     "core",
-    "web"
+    "web",
+    "packages/opik"
   ],
   "bin": {
     "agent-world": "bin/agent-world.js",
@@ -25,6 +26,7 @@
     "agent-world-server": "bin/agent-world-server.js"
   },
   "scripts": {
+    "install:all": "npm install && npm install --prefix electron",
     "dev": "npm run web:dev",
     "dev:reset": "for p in 3000 8080; do pids=$(lsof -tiTCP:$p -sTCP:LISTEN 2>/dev/null || true); if [ -n \"$pids\" ]; then kill $pids; fi; done",
     "web:dev": "npm-run-all --parallel server:watch web:vite:wait",
@@ -35,25 +37,39 @@
     "web:start": "npm run build && npm run server:start",
     "cli:start": "npm run build && node dist/cli/index.js",
     "electron:start": "npm run build:core && npm run start --prefix electron",
-    "build": "npm run build --workspace=core && tsc --project tsconfig.build.json && npm run build --workspace=web",
+    "electron:main:build": "npm run main:build --prefix electron",
+    "electron:renderer:build": "npm run renderer:build --prefix electron",
+    "build": "npm run build --workspace=core && npm run build --workspace=packages/opik && tsc --project tsconfig.build.json && npm run build --workspace=web && npm run main:build --prefix electron",
     "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 && npm run main:build --prefix electron",
+    "check": "tsc --noEmit --project tsconfig.build.json && npm run check --workspace=core && npm run check --workspace=web && npm run check --prefix electron",
     "server:dev": "npx tsx server/index.ts",
     "server:watch": "npx tsx --watch server/index.ts",
     "server:start": "node dist/server/index.js",
     "web:vite": "npm run dev --workspace=web",
+    "web:vite:e2e": "vite dev --config web/vite.config.js --host 127.0.0.1 --port 8080 --strictPort",
     "web:vite:wait": "wait-on tcp:127.0.0.1:3000 && npm run web:vite",
+    "web:e2e:serve": "node tests/web-e2e/support/start-web-servers.mjs",
     "electron:vite": "npm run dev --prefix electron",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
+    "coverage:scorecard": "node scripts/coverage-scorecard.mjs",
+    "test:coverage:gate": "npm run test:coverage && npm run coverage:scorecard",
     "test:db": "npx tsx tests/db/migration-tests.ts",
     "test:e2e": "npx tsx tests/e2e/test-agent-response-rules.ts",
     "test:e2e:interactive": "npx tsx tests/e2e/test-agent-response-rules.ts -i",
+    "test:web:e2e:run": "playwright test --config playwright.web.config.ts",
+    "test:web:e2e": "npm run test:web:e2e:run",
+    "test:electron:e2e:run": "playwright test --config playwright.electron.config.ts",
+    "test:electron:e2e": "npm-run-all --sequential build:core electron:main:build electron:renderer:build test:electron:e2e:run",
     "integration": "vitest run --config vitest.integration.config.ts",
-    "pkill": "pkill -f tsx"
+    "ci:test": "npm run test:coverage:gate && npm run integration",
+    "pkill": "pkill -f tsx",
+    "opik:eval": "npx tsx tests/opik/eval-robustness.ts",
+    "opik:storage-export-world": "npx tsx scripts/opik-export-world-storage.ts",
+    "test:integration": "npm run integration"
   },
   "description": "World-mediated agent management system with clean API surface",
   "keywords": [
@@ -71,23 +87,28 @@
     "@google/generative-ai": "^0.24.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.5.0",
+    "commander": "^14.0.0",
     "cors": "^2.8.5",
     "dotenv": "^17.2.3",
     "enquirer": "^2.4.1",
-    "express": "^4.22.1",
     "events": "^3.3.0",
+    "express": "^4.22.1",
     "fast-glob": "^3.3.3",
     "nanoid": "^5.1.5",
     "open": "^11.0.0",
-    "openai": "^6.15.0",
-    "commander": "^14.0.0",
+    "node-cron": "^4.2.1",
+    "openai": "^6.25.0",
     "pino": "^10.0.0",
     "pino-pretty": "^13.1.3",
     "sqlite3": "^5.1.7",
-    "zod": "^4.2.1",
-    "tsx": "^4.21.0"
+    "turndown": "^7.2.0",
+    "turndown-plugin-gfm": "^1.0.2",
+    "tsx": "^4.21.0",
+    "zod": "^4.2.1"
   },
   "devDependencies": {
+    "@types/node-cron": "^3.0.11",
+    "@playwright/test": "^1.54.2",
     "@tailwindcss/postcss": "^4.1.18",
     "@types/cors": "^2.8.19",
     "@types/express": "^4.17.25",