agent-world 0.13.0 → 0.15.0

package/dist/server/api.js

@@ -5,12 +5,29 @@
  * Supports world/agent/chat management with optimized serialization and error handling.
  *
  * Changes:
+ * - 2026-03-12: World status now keeps the current chat in `queuedChatIds` while a durable `queued`/`sending`
+ *   message_queue row still exists, preventing false-idle status during post-response queue cleanup.
+ * - 2026-03-12: Trailing comma cleanup in WorldUpdateSchema; tool_permission is stored in world.variables env key — no dedicated API schema field needed.
+ * - 2026-03-06: Removed runtime `world.currentChatId` fallback from message send routes; chat-scoped sends now require explicit `chatId`.
+ * - 2026-03-06: Added `/tool-artifact` for stable, restorable adopted-tool preview URLs limited to approved world working directories and registered skill roots.
+ * - 2026-03-06: Hardened `POST /worlds/:worldName/hitl/respond` for restart-safe validation: when the runtime pending map lacks the request entry but it exists in persisted messages, trigger `activateChatWithSnapshot` to seed the runtime map and return an actionable error.
+ * - 2026-03-10: Queue-backed message ingress is now user-only; non-user API senders use explicit immediate dispatch instead of the mixed queue helper.
+ * - 2026-03-04: Added queue metadata fields to non-streaming `/messages` success responses (`queueMessageId`, `queueStatus`, `queueRetryCount`) to expose queue terminal/error state.
+ * - 2026-02-27: Hardened non-streaming `/messages` event collection with chat-scoped filtering to prevent cross-chat response contamination.
+ * - 2026-02-24: Added `hitlPrompts` payload to `POST /worlds/:worldName/setChat/:chatId` responses so web chat switches can render replayed pending HITL prompts.
+ * - 2026-03-11: Added restoreChat(suppressAutoResume: true) before subscribeWorld in streaming edit path
+ *   to sync agent memory from storage, matching Electron editMessageInChat flow and fixing stale-runtime
+ *   cause of edit-success hang after world delete+recreate in e2e tests.
+ * - 2026-03-11: Added restoreChat before subscribeWorld in handleStreamingChat and handleNonStreamingChat
+ *   send-message paths to match Electron sendChatMessage pattern and prevent stale-agent hangs.
+ * - 2026-02-21: Removed temporary server-side folder-picker endpoint in favor of web File API based selection.
  * - 2026-02-20: Enforced options-only HITL response endpoint `POST /worlds/:worldName/hitl/respond` (`optionId` required).
  * - 2026-02-14: Added HITL option response endpoint `POST /worlds/:worldName/hitl/respond` for web/CLI approval submissions.
  * - 2026-02-13: Added core-managed message edit endpoint `PUT /worlds/:worldName/messages/:messageId`
  *   - Delegates edit/remove/resubmit flow to `core.editUserMessage` for cross-client consistency
  *   - Streams edit-resubmission follow-up events over SSE by default (`stream: true`)
  *   - Keeps DELETE endpoint focused on removal-only behavior
+ * - 2026-02-21: Extended non-streaming timeout refresh to include shell assistant-stream SSE activity (`start`/`chunk`/`end` with `toolName='shell_cmd'`) in addition to legacy `tool-stream`.
  * - 2026-02-11: Extended non-streaming timeout on tool-stream events to prevent premature timeout during long-running tools
  * - Standardized world-scoped routes to use validateWorld middleware to load and attach worldCtx/world
  * - Removed ad-hoc world loading and undefined getWorldOrError usage; handlers now use (req as any).worldCtx and (req as any).world
@@ -47,12 +64,18 @@
  * - 2026-02-08: Removed legacy manual intervention endpoint and related server handling
  */
 import express from 'express';
+import { promises as fs } from 'fs';
+import * as path from 'path';
 import { z } from 'zod';
 import { createSSEHandler } from './sse-handler.js';
-import { createWorld, listWorlds, createCategoryLogger, publishMessage, enableStreaming, disableStreaming, 
+import { createWorld, listWorlds, createCategoryLogger, enqueueAndProcessUserTurn, dispatchImmediateChatMessage, enableStreaming, disableStreaming, 
 // core managers (function-based)
-getWorld, updateWorld, deleteWorld, createAgent, getAgent, updateAgent, deleteAgent, listChats, newChat, restoreChat, deleteChat as deleteChatCore, clearAgentMemory, listAgents as listAgentsCore, getMemory as coreGetMemory, exportWorldToMarkdown, removeMessagesFrom, editUserMessage, stopMessageProcessing, submitWorldHitlResponse, EventType } from '../core/index.js';
+getWorld, updateWorld, deleteWorld, createAgent, getAgent, updateAgent, deleteAgent, listChats, newChat, activateChatWithSnapshot, restoreChat, deleteChat as deleteChatCore, clearAgentMemory, listAgents as listAgentsCore, getMemory as coreGetMemory, exportWorldToMarkdown, removeMessagesFrom, editUserMessage, stopMessageProcessing, submitWorldHitlResponse, listPendingHitlPromptEventsFromMessages, getQueueMessages, getActiveProcessingChatIds, getActiveAgentNames, EventType } from '../core/index.js';
 import { subscribeWorld } from '../core/index.js';
+// Opik integration: optional tracer attach for API-managed world subscriptions.
+import { attachOptionalOpikTracer } from '../core/optional-tracers/opik-runtime.js';
+import { getSkillSourcePath, getSkills } from '../core/skill-registry.js';
+import { getDefaultWorkingDirectory, getEnvValueFromText, toKebabCase } from '../core/utils.js';
 import { listMCPServers, restartMCPServer, getMCPSystemHealth, getMCPRegistryStats } from '../core/mcp-server-registry.js';
 // Function-specific loggers for granular debugging control
 const loggerWorld = createCategoryLogger('api.world');
@@ -62,6 +85,21 @@ const loggerStream = createCategoryLogger('api.stream');
 const loggerValidation = createCategoryLogger('api.validation');
 const loggerMcp = createCategoryLogger('api.mcp');
 const loggerExport = createCategoryLogger('api.export');
+function isUserSender(sender) {
+    const normalized = String(sender || '').trim().toLowerCase();
+    return normalized === 'human' || normalized === 'world' || normalized.startsWith('user');
+}
+async function hasPendingCurrentChatQueueMessage(world) {
+    const currentChatId = String(world.currentChatId || '').trim();
+    if (!currentChatId) {
+        return false;
+    }
+    const queuedMessages = await getQueueMessages(world.id, currentChatId);
+    return queuedMessages.some((entry) => {
+        const status = String(entry?.status || '').trim().toLowerCase();
+        return status === 'queued' || status === 'sending';
+    });
+}
 const DEFAULT_WORLD_NAME = 'Default World';
 // World context factory - eliminates repetitive worldId passing
 function createWorldContext(worldId) {
@@ -97,6 +135,8 @@ function serializeWorld(world) {
         currentChatId: world.currentChatId || null,
         mcpConfig: world.mcpConfig || null,
         variables: typeof world.variables === 'string' ? world.variables : '',
+        uiMode: world.uiMode || 'chat',
+        dashboardZones: world.dashboardZones || [],
         agents: Array.from(world.agents.values()).map(serializeAgent),
         chats: Array.from(world.chats.values()).map(serializeChat)
     };
@@ -132,8 +172,77 @@ function sendError(res, status, message, code, details) {
         error.details = details;
     res.status(status).json(error);
 }
-function toKebabCase(name) {
-    return name.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+function isPathWithinRoot(rootPath, candidatePath) {
+    const normalizedRoot = normalizeResolvedPath(rootPath);
+    const normalizedCandidate = normalizeResolvedPath(candidatePath);
+    return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}/`);
+}
+function normalizeResolvedPath(targetPath) {
+    return path.resolve(targetPath).replace(/\\/g, '/').replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+}
+async function getRegisteredSkillRoots() {
+    const skillRoots = await Promise.all(getSkills()
+        .map((skill) => getSkillSourcePath(skill.skill_id))
+        .filter((skillPath) => typeof skillPath === 'string' && skillPath.trim().length > 0)
+        .map(async (skillPath) => {
+        try {
+            return normalizeResolvedPath(path.dirname(await fs.realpath(path.resolve(skillPath))));
+        }
+        catch {
+            return null;
+        }
+    }));
+    return [...new Set(skillRoots.filter((skillRoot) => typeof skillRoot === 'string' && skillRoot.length > 0))];
+}
+async function resolveWorldArtifactRoot(worldId) {
+    if (!worldId) {
+        return null;
+    }
+    const world = await getWorld(toKebabCase(worldId));
+    if (!world) {
+        return null;
+    }
+    const lexicalRoot = path.resolve(getEnvValueFromText(typeof world.variables === 'string' ? world.variables : '', 'working_directory') || getDefaultWorkingDirectory());
+    try {
+        return normalizeResolvedPath(await fs.realpath(lexicalRoot));
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveToolArtifactPath(requestedPath, worldId) {
+    const normalizedPath = String(requestedPath || '').trim();
+    if (!normalizedPath) {
+        return null;
+    }
+    const worldRoot = await resolveWorldArtifactRoot(worldId);
+    const skillRoots = await getRegisteredSkillRoots();
+    const uniqueRoots = [...new Set([
+            ...(worldRoot ? [worldRoot] : []),
+            ...skillRoots,
+        ].map((root) => normalizeResolvedPath(root)))];
+    if (uniqueRoots.length === 0) {
+        return null;
+    }
+    const candidatePaths = path.isAbsolute(normalizedPath)
+        ? [normalizeResolvedPath(normalizedPath)]
+        : uniqueRoots.map((root) => normalizeResolvedPath(path.resolve(root, normalizedPath)));
+    for (const candidatePath of candidatePaths) {
+        try {
+            const realCandidatePath = normalizeResolvedPath(await fs.realpath(candidatePath));
+            if (!uniqueRoots.some((root) => isPathWithinRoot(root, realCandidatePath))) {
+                continue;
+            }
+            const stat = await fs.stat(realCandidatePath);
+            if (stat.isFile()) {
+                return realCandidatePath;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
 }
 async function isAgentNameUnique(worldCtx, agentName, excludeAgent) {
     const normalizedAgentName = toKebabCase(agentName);
@@ -183,7 +292,7 @@ const WorldUpdateSchema = z.object({
     chatLLMProvider: z.enum(['openai', 'anthropic', 'azure', 'google', 'xai', 'openai-compatible', 'ollama']).nullable().optional(),
     chatLLMModel: z.string().nullable().optional(),
     mcpConfig: z.string().nullable().optional(),
-    variables: z.string().nullable().optional()
+    variables: z.string().nullable().optional(),
 });
 const AgentCreateSchema = z.object({
     name: z.string().min(1).max(100),
@@ -201,7 +310,7 @@ const ChatMessageSchema = z.object({
     message: z.string().min(1),
     sender: z.string().default("human"),
     stream: z.boolean().optional().default(true),
-    chatId: z.string().min(1).optional(),
+    chatId: z.string().min(1),
     messages: z.array(z.any()).optional()
 });
 const MessageEditSchema = z.object({
@@ -217,6 +326,10 @@ const HitlResponseSchema = z.object({
     optionId: z.string().min(1),
     chatId: z.string().nullable().optional()
 });
+const ToolArtifactQuerySchema = z.object({
+    path: z.string().min(1),
+    worldId: z.string().min(1).optional(),
+});
 const AgentUpdateSchema = z.object({
     name: z.string().min(1).max(100).optional(),
     type: z.string().optional(),
@@ -230,6 +343,19 @@ const AgentUpdateSchema = z.object({
     clearMemory: z.boolean().optional()
 });
 const router = express.Router();
+router.get('/tool-artifact', async (req, res) => {
+    const validation = ToolArtifactQuerySchema.safeParse(req.query);
+    if (!validation.success) {
+        sendError(res, 400, 'Invalid tool artifact request', 'VALIDATION_ERROR', validation.error.issues);
+        return;
+    }
+    const resolvedPath = await resolveToolArtifactPath(validation.data.path, validation.data.worldId);
+    if (!resolvedPath) {
+        sendError(res, 404, 'Tool artifact not found', 'TOOL_ARTIFACT_NOT_FOUND');
+        return;
+    }
+    res.sendFile(resolvedPath);
+});
 // World Routes
 router.get('/worlds', async (req, res) => {
     try {
@@ -268,6 +394,33 @@ router.get('/worlds/:worldName', validateWorld, async (req, res) => {
         sendError(res, 500, 'Internal server error', 'INTERNAL_ERROR');
     }
 });
+router.get('/worlds/:worldName/status', validateWorld, async (req, res) => {
+    try {
+        const world = req.world;
+        const includeCurrentChatQueue = await hasPendingCurrentChatQueueMessage(world);
+        const activeChatIds = [...getActiveProcessingChatIds(world)];
+        const queuedChatIds = [
+            ...new Set([
+                ...(world._queuedChatIds ?? []),
+                ...(includeCurrentChatQueue && world.currentChatId ? [world.currentChatId] : []),
+            ]),
+        ];
+        const activeAgentNames = getActiveAgentNames(world);
+        res.json({
+            worldId: world.id,
+            isProcessing: world.isProcessing ?? false,
+            activeChatIds,
+            queuedChatIds,
+            activeAgentNames,
+            queueDepth: queuedChatIds.length,
+            sendingCount: activeChatIds.length,
+        });
+    }
+    catch (error) {
+        loggerWorld.error('Error getting world status', { error: error instanceof Error ? error.message : error, worldName: req.params.worldName });
+        sendError(res, 500, 'Internal server error', 'INTERNAL_ERROR');
+    }
+});
 router.post('/worlds', async (req, res) => {
     try {
         const validation = WorldCreateSchema.safeParse(req.body);
@@ -551,8 +704,28 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
     disableStreaming();
     let subscription = null;
     let listeners = new Map();
+    const normalizedChatId = typeof chatId === 'string' ? chatId.trim() : '';
+    const scopedChatId = normalizedChatId.length > 0 ? normalizedChatId : null;
+    const isChatEventInScope = (eventChatId, includeUnscopedWhenScoped = false) => {
+        if (!scopedChatId) {
+            return true;
+        }
+        if (eventChatId === undefined || eventChatId === null) {
+            return includeUnscopedWhenScoped;
+        }
+        return String(eventChatId).trim() === scopedChatId;
+    };
     try {
+        // Sync agent memory from storage before subscribing, mirroring the Electron sendChatMessage pattern.
+        // Prevents stale-runtime agents (e.g. after agent add/delete with a live runtime) from silently
+        // dropping the message with no response-start event.
+        if (chatId) {
+            await restoreChat(worldName, chatId);
+        }
         let responseContent = '';
+        let queuedMessageId = null;
+        let queuedStatus = null;
+        let queuedRetryCount = null;
         let isComplete = false;
         let hasError = false;
         let errorMessage = '';
@@ -566,7 +739,7 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
                     reject(new Error(errorMessage));
                 }
             }, 60000); // Longer timeout as fallback since we rely on events
-            // Helper to reset the fallback timeout (called when tool-stream data arrives)
+            // Helper to reset the fallback timeout when long-running shell stream activity arrives.
             const resetTimeout = () => {
                 clearTimeout(timeoutTimer);
                 timeoutTimer = setTimeout(() => {
@@ -579,7 +752,7 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
                 }, 60000);
             };
             // Subscribe with minimal client (no forwarding callbacks)
-            subscribeWorld(worldName, { isOpen: true }).then(sub => {
+            subscribeWorld(worldName, { isOpen: true }).then(async (sub) => {
                 if (!sub) {
                     hasError = true;
                     errorMessage = 'Failed to subscribe to world';
@@ -588,8 +761,12 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
                 }
                 subscription = sub;
                 const world = subscription.world;
+                await attachOptionalOpikTracer(world, { source: 'server' });
                 // Listen to world activity events to detect when all processing is complete
                 const worldActivityListener = (eventData) => {
+                    if (!isChatEventInScope(eventData?.chatId, true)) {
+                        return;
+                    }
                     if (eventData.type === 'response-start') {
                         awaitingIdle = true;
                         loggerChat.debug('Non-streaming: world processing started', {
@@ -608,6 +785,9 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
                 };
                 // Collect message events for response
                 const messageListener = (eventData) => {
+                    if (!isChatEventInScope(eventData?.chatId, false)) {
+                        return;
+                    }
                     responseContent = JSON.stringify({ type: 'message', data: eventData });
                 };
                 // Listen to activity events for completion detection
@@ -616,16 +796,33 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
                 // Listen to message events for response content
                 world.eventEmitter.on(EventType.MESSAGE, messageListener);
                 listeners.set(EventType.MESSAGE, messageListener);
-                // Listen to SSE events to extend timeout on tool-stream data
+                // Listen to SSE events to extend timeout on shell stream activity.
                 const sseListener = (eventData) => {
-                    if (eventData.type === 'tool-stream') {
+                    if (!isChatEventInScope(eventData?.chatId, false)) {
+                        return;
+                    }
+                    const isLegacyToolStream = eventData.type === 'tool-stream';
+                    const isShellAssistantStream = eventData.toolName === 'shell_cmd' &&
+                        (eventData.type === 'start' || eventData.type === 'chunk' || eventData.type === 'end');
+                    if (isLegacyToolStream || isShellAssistantStream) {
                         resetTimeout();
                     }
                 };
                 world.eventEmitter.on(EventType.SSE, sseListener);
                 listeners.set(EventType.SSE, sseListener);
-                // Publish message
-                publishMessage(world, message, sender, chatId);
+                if (isUserSender(sender)) {
+                    // Queue-backed user ingress: enqueue then trigger event-driven processing.
+                    const queued = await enqueueAndProcessUserTurn(world.id, chatId, message, sender, world);
+                    queuedMessageId = queued?.messageId || null;
+                    queuedStatus = queued?.status || null;
+                    queuedRetryCount = typeof queued?.retryCount === 'number' ? queued.retryCount : null;
+                }
+                else {
+                    const dispatched = await dispatchImmediateChatMessage(world.id, chatId, message, sender, world);
+                    queuedMessageId = dispatched?.messageId || null;
+                    queuedStatus = null;
+                    queuedRetryCount = null;
+                }
             }).catch(error => {
                 hasError = true;
                 errorMessage = `Failed to connect to world: ${error instanceof Error ? error.message : error}`;
@@ -642,7 +839,10 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
             message: 'Message processed successfully',
             data: {
                 content: responseContent || 'No response received',
-                timestamp: new Date().toISOString()
+                timestamp: new Date().toISOString(),
+                queueMessageId: queuedMessageId,
+                queueStatus: queuedStatus,
+                queueRetryCount: queuedRetryCount
             }
         });
     }
@@ -680,6 +880,12 @@ async function handleNonStreamingChat(res, worldName, message, sender, chatId) {
  * @returns Promise that resolves when stream is complete
  */
 async function handleStreamingChat(req, res, worldName, message, sender, chatId) {
+    // Sync agent memory from storage before subscribing, mirroring the Electron sendChatMessage pattern.
+    // Prevents stale-runtime agents (e.g. after agent add/delete with a live runtime) from silently
+    // dropping the message with no response-start event.
+    if (chatId) {
+        await restoreChat(worldName, chatId);
+    }
     // Subscribe to world to get the world instance
     const subscription = await subscribeWorld(worldName, { isOpen: true });
     if (!subscription) {
@@ -690,8 +896,10 @@ async function handleStreamingChat(req, res, worldName, message, sender, chatId)
         return;
     }
     const world = subscription.world;
+    await attachOptionalOpikTracer(world, { source: 'server' });
     // Create SSE handler - automatically sets up headers, listeners, and cleanup
     const sseHandler = createSSEHandler(req, res, world, 'chat', chatId);
+    await sseHandler.ready;
     // Clean up subscription when the HTTP response closes/finishes to prevent stale world
     // instances from accumulating in activeSubscribedWorlds.
     let subscriptionCleanedUp = false;
@@ -705,8 +913,12 @@ async function handleStreamingChat(req, res, worldName, message, sender, chatId)
     res.on('finish', cleanupSubscription);
     res.on('close', cleanupSubscription);
     try {
-        // Publish message - events will be automatically streamed
-        publishMessage(world, message, sender, chatId);
+        if (isUserSender(sender)) {
+            await enqueueAndProcessUserTurn(world.id, chatId, message, sender, world);
+        }
+        else {
+            await dispatchImmediateChatMessage(world.id, chatId, message, sender, world);
+        }
     }
     catch (error) {
         sseHandler.sendSSE({
@@ -798,6 +1010,10 @@ router.put('/worlds/:worldName/messages/:messageId', validateWorld, async (req,
             });
             return;
         }
+        // Sync agent memory from storage before subscribing so a stale runtime
+        // (e.g. after a world delete+recreate) picks up the fresh agent list.
+        // Mirrors the Electron editMessageInChat flow: restoreChat → ensureWorldSubscribed.
+        await restoreChat(worldCtx.id, chatId, { suppressAutoResume: true });
         const subscription = await subscribeWorld(worldCtx.id, { isOpen: true });
         if (!subscription?.world) {
             res.setHeader('Content-Type', 'text/event-stream');
@@ -807,7 +1023,9 @@ router.put('/worlds/:worldName/messages/:messageId', validateWorld, async (req,
             res.end();
             return;
         }
+        await attachOptionalOpikTracer(subscription.world, { source: 'server' });
         const sseHandler = createSSEHandler(req, res, subscription.world, 'edit', chatId);
+        await sseHandler.ready;
         let subscriptionCleanedUp = false;
         const cleanupSubscription = () => {
             if (subscriptionCleanedUp) {
@@ -942,6 +1160,26 @@ router.post('/worlds/:worldName/hitl/respond', validateWorld, async (req, res) =
             optionId,
             ...(chatId !== undefined ? { chatId } : {}),
         });
+        // Restart-safe fallback: if the runtime pending map lacks the entry (e.g. server
+        // restarted before /setChat was called) but the request exists in persisted messages,
+        // trigger chat activation to seed the pending map via the tool-call resume path.
+        // The caller should retry /hitl/respond after receiving the HITL SSE event.
+        if (!result.accepted && result.reason?.includes('No pending HITL request') && chatId) {
+            const memory = await coreGetMemory(worldCtx.id, chatId);
+            if (Array.isArray(memory)) {
+                const surviving = listPendingHitlPromptEventsFromMessages(memory, chatId);
+                const inMessages = surviving.some((item) => item.prompt.requestId === requestId);
+                if (inMessages) {
+                    // Trigger restore/resume asynchronously to repopulate the pending map.
+                    void activateChatWithSnapshot(worldCtx.id, chatId).catch(() => undefined);
+                    res.json({
+                        accepted: false,
+                        reason: `HITL request '${requestId}' is pending in chat messages but the chat is not yet activated on this server. Call POST /worlds/${req.params.worldName}/setChat/${chatId} to activate, then retry this request.`,
+                    });
+                    return;
+                }
+            }
+        }
         res.json(result);
     }
     catch (error) {
@@ -1040,18 +1278,22 @@ router.post('/worlds/:worldName/setChat/:chatId', validateWorld, async (req, res
             sendError(res, 404, 'World not found', 'WORLD_NOT_FOUND');
             return;
         }
-        const updatedWorld = await worldCtx.setChat(chatId);
-        if (!updatedWorld) {
+        const activated = await activateChatWithSnapshot(worldCtx.id, chatId);
+        if (!activated) {
             res.json({
                 world: serializeWorld(currentWorld),
                 chatId: currentWorld.currentChatId,
+                hitlPrompts: [],
                 success: false
             });
             return;
         }
+        const updatedWorld = activated.world;
+        const pendingHitlPrompts = activated.hitlPrompts;
         res.json({
             world: serializeWorld(updatedWorld),
-            chatId: updatedWorld.currentChatId,
+            chatId: activated.chatId,
+            hitlPrompts: pendingHitlPrompts,
             success: true
         });
     }

package/dist/server/error-response.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Server Error Response Mapping
+ *
+ * Purpose:
+ * - Convert runtime/server errors into stable, user-meaningful HTTP responses.
+ *
+ * Features:
+ * - Specific mappings for oversized request payloads and invalid JSON bodies.
+ * - Readonly SQLite detection with actionable error messaging.
+ * - Safe fallback for unknown internal errors.
+ *
+ * Implementation Notes:
+ * - JSON parse mapping is intentionally strict to body-parser parse errors only,
+ *   so unrelated `SyntaxError`s in route logic are not mislabeled as request-body issues.
+ *
+ * Changes:
+ * - 2026-02-26: Tightened invalid JSON detection to avoid misclassifying generic runtime SyntaxErrors.
+ * - 2026-02-26: Initial extraction from `server/index.ts` for reusable, testable global error mapping.
+ */
+export type ErrorResponsePayload = {
+    error: string;
+    code: string;
+};
+export declare function getErrorResponse(error: unknown): {
+    status: number;
+    payload: ErrorResponsePayload;
+};

package/dist/server/error-response.js

@@ -0,0 +1,77 @@
+/**
+ * Server Error Response Mapping
+ *
+ * Purpose:
+ * - Convert runtime/server errors into stable, user-meaningful HTTP responses.
+ *
+ * Features:
+ * - Specific mappings for oversized request payloads and invalid JSON bodies.
+ * - Readonly SQLite detection with actionable error messaging.
+ * - Safe fallback for unknown internal errors.
+ *
+ * Implementation Notes:
+ * - JSON parse mapping is intentionally strict to body-parser parse errors only,
+ *   so unrelated `SyntaxError`s in route logic are not mislabeled as request-body issues.
+ *
+ * Changes:
+ * - 2026-02-26: Tightened invalid JSON detection to avoid misclassifying generic runtime SyntaxErrors.
+ * - 2026-02-26: Initial extraction from `server/index.ts` for reusable, testable global error mapping.
+ */
+function isEntityTooLargeError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return candidate.type === 'entity.too.large' || candidate.status === 413 || candidate.statusCode === 413;
+}
+function isJsonParseError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    const isBodyParserParseType = candidate.type === 'entity.parse.failed';
+    const isBodyParserSyntaxError = error instanceof SyntaxError
+        && (candidate.status === 400 || candidate.statusCode === 400)
+        && 'body' in candidate;
+    return isBodyParserParseType || isBodyParserSyntaxError;
+}
+function isReadonlySqliteError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return candidate.code === 'SQLITE_READONLY' || String(candidate.message || '').includes('SQLITE_READONLY');
+}
+export function getErrorResponse(error) {
+    if (isEntityTooLargeError(error)) {
+        return {
+            status: 413,
+            payload: {
+                error: 'Request payload too large. Try submitting a smaller update payload.',
+                code: 'PAYLOAD_TOO_LARGE'
+            }
+        };
+    }
+    if (isJsonParseError(error)) {
+        return {
+            status: 400,
+            payload: {
+                error: 'Invalid JSON body. Please check request formatting.',
+                code: 'INVALID_JSON_BODY'
+            }
+        };
+    }
+    if (isReadonlySqliteError(error)) {
+        return {
+            status: 503,
+            payload: {
+                error: 'Database is read-only. Check database file permissions and retry.',
+                code: 'DATABASE_READONLY'
+            }
+        };
+    }
+    return {
+        status: 500,
+        payload: {
+            error: 'Server failed to process the request.',
+            code: 'INTERNAL_ERROR'
+        }
+    };
+}

package/dist/server/index.d.ts

@@ -15,15 +15,16 @@
  * Endpoints: /health + API routes from ./api.ts
  *
  * Recent Changes:
+ * - 2026-02-26: Added specific global API error mapping for oversized JSON payloads, invalid JSON bodies, and readonly database errors to avoid generic INTERNAL_ERROR responses.
  * - 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';
+export { getErrorResponse } from './error-response.js';
 type StartWebServerOptions = {
     openBrowser?: boolean;
     registerProcessHandlers?: boolean;
 };
 export declare function startWebServer(port?: number, host?: string, options?: StartWebServerOptions): Promise<Server>;
-export {};

package/dist/server/index.js

@@ -15,6 +15,7 @@
  * Endpoints: /health + API routes from ./api.ts
  *
  * Recent Changes:
+ * - 2026-02-26: Added specific global API error mapping for oversized JSON payloads, invalid JSON bodies, and readonly database errors to avoid generic INTERNAL_ERROR responses.
  * - 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
@@ -32,11 +33,13 @@ import path from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import apiRouter from './api.js';
 import { initializeMCPRegistry, shutdownAllMCPServers } from '../core/mcp-server-registry.js';
+import { getErrorResponse } from './error-response.js';
+export { getErrorResponse } from './error-response.js';
 // ES modules setup
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Configuration
-const PORT = Number(process.env.PORT) || 0;
+const PORT = Number(process.env.PORT) || 3000;
 const HOST = process.env.HOST || '127.0.0.1';
 // Create server logger after logger auto-initialization
 const serverLogger = createCategoryLogger('server');
@@ -117,7 +120,8 @@ app.get('*', (req, res) => {
 // Error handling middleware
 app.use((error, req, res, next) => {
     console.error('Unhandled error:', error);
-    res.status(500).json({ error: 'Internal server error', code: 'INTERNAL_ERROR' });
+    const { status, payload } = getErrorResponse(error);
+    res.status(status).json(payload);
 });
 // 404 handler
 app.use((req, res) => {

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

@@ -29,8 +29,14 @@
  * ```
  *
  * 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
@@ -38,6 +44,10 @@
 import { Request, Response } from 'express';
 import { World } from '../core/index.js';
 export interface SSEHandler {
+    /**
+     * Resolves once synthesis has finished and live listeners are attached.
+     */
+    ready: Promise<void>;
     /**
      * Send a Server-Sent Event to the client
      * @param data - Data object to send (will be JSON stringified)