agent-world 0.13.0 → 0.15.0

package/dist/core/managers.js

@@ -8,25 +8,41 @@
  * - Automatic ID normalization to kebab-case for consistency
  * - Environment-aware storage operations through storage-factory
  * - Agent message management with automatic agentId assignment
- * - Message ID migration for user message edit feature
- * - User message editing with removal and resubmission
- * - Error logging for message edit operations
+ *
+ * Queue management, message editing, and storage initialization are handled by
+ * dedicated sub-modules (queue-manager.ts, message-edit-manager.ts, storage-init.ts)
+ * whose public APIs are re-exported here for backward compatibility.
  *
  * API: World (create/get/update/delete/list), Agent (create/get/update/delete/list/updateMemory/clearMemory),
- * Chat (newChat/listChats/deleteChat/restoreChat), Migration (migrateMessageIds),
- * MessageEdit (removeMessagesFrom/editUserMessage/logEditError/getEditErrors)
+ * Chat (newChat/listChats/deleteChat/restoreChat),
+ * re-exports: migrateMessageIds, removeMessagesFrom, editUserMessage, logEditError, getEditErrors,
+ *             addToQueue, enqueueAndProcessUserTurn, dispatchImmediateChatMessage, getQueueMessages,
+ *             pauseChatQueue, resumeChatQueue, stopChatQueue, clearChatQueue, retryQueueMessage,
+ *             recoverQueueSendingMessages
  *
  * Implementation Details:
  * - Ensures all agent messages include agentId for proper export functionality
  * - Compatible with both SQLite and memory storage backends
  * - Automatic agent identification for message source tracking
- * - Idempotent message ID migration supporting both file and SQL storage
- * - Comprehensive error tracking for partial failures
- * - Error log persistence with 100-entry retention policy
  *
  * Recent Changes:
- * - 2026-02-20: Added `claimAgentCreationSlot` to allow `create_agent` tool to hold the TOCTOU slot before showing approval dialog, preventing duplicate-approval race conditions.
- * - 2026-02-20: Added `createAgent` option `allowWhileWorldProcessing` so approval-gated in-flight tool calls can create agents without disabling default processing guards.
+ * - 2026-03-11: Synchronized active runtime world metadata during `updateWorld` so live chats pick up
+ *   updated `variables`/`working_directory` and other top-level config without requiring a runtime refresh.
+ * - 2026-03-10: Renamed queue-backed ingress to `enqueueAndProcessUserTurn` and split non-user immediate dispatch into `dispatchImmediateChatMessage`.
+ * - 2026-03-10: Removed restore-time user-last resend from persisted chat memory; queue-owned rows are now the only automatic resume authority.
+ * - 2026-03-10: Added `restoreChat(..., { suppressAutoResume: true })` support for edit/delete mutation flows so failed last-turn messages are not replayed before mutation.
+ * - 2026-03-09: God-module decomposition — extracted queue management (queue-manager.ts),
+ *   message edit/migration logic (message-edit-manager.ts), and storage singleton +
+ *   identifier resolution (storage-init.ts) into focused sub-modules. managers.ts reduced
+ *   from 2928 → 1300 lines; all public exports preserved via re-exports.
+ * - 2026-03-09: Added `activateChatResources` helper to consolidate the resource-reactivation
+ *   sequence (memory sync, skill approvals, HITL replay, queue resume) shared between the
+ *   two branches of `restoreChat`.
+ * - 2026-03-09: Added SSE terminal-state guard in `triggerPendingLastMessageResume` to prevent
+ *   infinite auto-resume loops when the last SSE event is already terminal.
+ * - 2026-03-06: Moved chat-selection runtime control flow onto explicit/persisted chat helpers.
+ * - 2026-03-06: Removed runtime `world.currentChatId` fallback from exported chat-memory helpers.
+ * - 2026-02-20: Added `claimAgentCreationSlot` / `allowWhileWorldProcessing` for approval-gated tool calls.
  * - 2026-02-16: Added `branchChatFromMessage` to create a new chat branched from an assistant message and copy source-chat history up to the target message.
  * - 2026-02-14: Updated `editUserMessage` to be fully core-managed for clear+resend behavior without client-side subscription refresh logic.
  *   - Edit resubmission now prefers active subscribed world runtimes.
@@ -68,43 +84,123 @@
  *   - logEditError/getEditErrors: Error persistence in edit-errors.json
  *
  * Note: Export functionality has been moved to core/export.ts
- */ // Core module imports
-import { createCategoryLogger, initializeLogger } from './logger.js';
+ */
+// Core module imports
+import { createCategoryLogger } from './logger.js';
 import { EventEmitter } from 'events';
-import { createStorageWithWrappers } from './storage/storage-factory.js';
 import * as utils from './utils.js';
-import { nanoid } from 'nanoid';
-import * as fs from 'fs';
-import * as path from 'path';
-import { getWorldDir } from './storage/world-storage.js';
-import { getDefaultRootPath } from './storage/storage-factory.js';
-import { NEW_CHAT_TITLE, isDefaultChatTitle } from './chat-constants.js';
-import { hasActiveChatMessageProcessing, stopMessageProcessing } from './message-processing-control.js';
-// Initialize logger and storage
+import { NEW_CHAT_TITLE, isDefaultChatTitle, TITLE_PROVENANCE_MANUAL } from './chat-constants.js';
+import { hasActiveChatMessageProcessing } from './message-processing-control.js';
+import { replayPendingHitlRequests, listPendingHitlPromptEventsFromMessages } from './hitl.js';
+import { clearChatSkillApprovals, reconstructSkillApprovalsFromMessages } from './load-skill-tool.js';
+import { resumePendingToolCallsForChat } from './events/memory-manager.js';
+import { stopWorldRuntimesByWorldId } from './world-registry.js';
+import { storageWrappers, ensureInitialization, getResolvedWorldId, getResolvedAgentId, } from './storage-init.js';
+import { triggerPendingQueueResume, autoPauseQueueForChat, clearQueuePauseForChat, } from './queue-manager.js';
+import { syncRuntimeAgentMemoryFromStorage, migrateMessageIds, } from './message-edit-manager.js';
+// Per-module state
 const logger = createCategoryLogger('core.managers');
-let storageWrappers = null;
-let moduleInitialization = null;
-async function initializeModules() {
-    if (storageWrappers) {
-        return; // Already initialized
+const loggerRestore = createCategoryLogger('chat.restore');
+const loggerRestoreResume = createCategoryLogger('chat.restore.resume');
+const inFlightToolResumeKeys = new Set();
+function triggerPendingToolCallResume(world, chatId, targetAssistantMessageId) {
+    if (!chatId) {
+        return;
     }
-    try {
-        initializeLogger();
-        storageWrappers = await createStorageWithWrappers();
+    if (hasActiveChatMessageProcessing(world.id, chatId)) {
+        return;
     }
-    catch (error) {
-        // Log error but don't throw - allows tests to proceed with mocked storage
-        logger.error('Failed to initialize storage', { error: error instanceof Error ? error.message : error });
-        throw error;
+    const resumeKey = `${world.id}:${chatId}`;
+    if (inFlightToolResumeKeys.has(resumeKey)) {
+        return;
+    }
+    inFlightToolResumeKeys.add(resumeKey);
+    void (async () => {
+        try {
+            const resumedCount = await resumePendingToolCallsForChat(world, chatId, targetAssistantMessageId);
+            loggerRestoreResume.debug('Attempted pending tool-call resume after chat restore', {
+                worldId: world.id,
+                chatId,
+                targetAssistantMessageId: targetAssistantMessageId || null,
+                resumedCount,
+            });
+            if (resumedCount > 0) {
+                loggerRestoreResume.debug('Resumed pending persisted tool calls after chat restore', {
+                    worldId: world.id,
+                    chatId,
+                    targetAssistantMessageId,
+                    resumedCount,
+                });
+            }
+        }
+        catch (error) {
+            loggerRestoreResume.warn('Failed to resume pending persisted tool calls after chat restore', {
+                worldId: world.id,
+                chatId,
+                targetAssistantMessageId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            inFlightToolResumeKeys.delete(resumeKey);
+        }
+    })();
+}
+function hasPendingToolCallsOnLastAssistantMessage(lastMessage, chatMemory) {
+    if (lastMessage.role !== 'assistant' || !Array.isArray(lastMessage.tool_calls) || lastMessage.tool_calls.length === 0) {
+        return false;
+    }
+    const completedToolCallIds = new Set();
+    for (const message of chatMemory) {
+        if (message.role !== 'tool' || typeof message.tool_call_id !== 'string') {
+            continue;
+        }
+        const toolCallId = message.tool_call_id.trim();
+        if (toolCallId) {
+            completedToolCallIds.add(toolCallId);
+        }
+    }
+    for (const toolCall of lastMessage.tool_calls) {
+        const toolCallId = String(toolCall?.id || '').trim();
+        if (!toolCallId) {
+            continue;
+        }
+        if (!completedToolCallIds.has(toolCallId)) {
+            return true;
+        }
     }
+    return false;
 }
-function ensureInitialization() {
-    if (!moduleInitialization) {
-        moduleInitialization = initializeModules();
+function triggerPendingToolCallResumeFromLastMessage(world, chatId) {
+    if (!chatId) {
+        return;
     }
-    return moduleInitialization;
+    void (async () => {
+        try {
+            const chatMemory = await storageWrappers.getMemory(world.id, chatId);
+            if (!chatMemory || chatMemory.length === 0) {
+                return;
+            }
+            const lastMessage = chatMemory[chatMemory.length - 1];
+            if (!hasPendingToolCallsOnLastAssistantMessage(lastMessage, chatMemory)) {
+                return;
+            }
+            loggerRestoreResume.debug('Detected pending tool-call-last message during chat-restore inspection', {
+                worldId: world.id,
+                chatId,
+                messageId: lastMessage.messageId || null,
+            });
+            triggerPendingToolCallResume(world, chatId, lastMessage.messageId);
+        }
+        catch (error) {
+            loggerRestoreResume.warn('Failed to inspect last message for pending tool-call resume during chat restore', {
+                worldId: world.id,
+                chatId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    })();
 }
-const NEW_CHAT_CONFIG = { REUSABLE_CHAT_TITLE: NEW_CHAT_TITLE };
 // TOCTOU guard: prevents two concurrent createAgent calls from both passing the
 // `agentExists` check before either write lands. Maps worldId → Set<agentId>.
 const pendingAgentCreates = new Map();
@@ -142,137 +238,6 @@ export async function claimAgentCreationSlot(worldId, agentName) {
         },
     };
 }
-function extractGeneratedChatTitleFromSystemPayload(payload) {
-    if (!payload || typeof payload !== 'object')
-        return null;
-    if (payload.eventType !== 'chat-title-updated')
-        return null;
-    const title = typeof payload.title === 'string' ? payload.title.trim() : '';
-    return title || null;
-}
-async function resetAutoGeneratedChatTitleForEditResubmission(world, chatId) {
-    const chat = world.chats.get(chatId) ?? await storageWrappers.loadChatData(world.id, chatId);
-    if (!chat)
-        return;
-    const currentTitle = String(chat.name || '').trim();
-    if (!currentTitle || isDefaultChatTitle(currentTitle)) {
-        return;
-    }
-    const eventStorage = world.eventStorage;
-    if (!eventStorage) {
-        return;
-    }
-    let latestGeneratedTitle = null;
-    try {
-        const systemEvents = await eventStorage.getEventsByWorldAndChat(world.id, chatId, {
-            types: ['system'],
-            order: 'desc',
-            limit: 25
-        });
-        for (const event of systemEvents) {
-            const generatedTitle = extractGeneratedChatTitleFromSystemPayload(event?.payload);
-            if (generatedTitle) {
-                latestGeneratedTitle = generatedTitle;
-                break;
-            }
-        }
-    }
-    catch (error) {
-        logger.debug('Skipping auto-title reset because system events could not be queried', {
-            worldId: world.id,
-            chatId,
-            error: error instanceof Error ? error.message : String(error)
-        });
-        return;
-    }
-    if (!latestGeneratedTitle || latestGeneratedTitle !== currentTitle) {
-        return;
-    }
-    let resetSucceeded = false;
-    if (typeof storageWrappers.updateChatNameIfCurrent === 'function') {
-        resetSucceeded = await storageWrappers.updateChatNameIfCurrent(world.id, chatId, currentTitle, NEW_CHAT_TITLE);
-    }
-    else {
-        const updated = await storageWrappers.updateChatData(world.id, chatId, { name: NEW_CHAT_TITLE });
-        resetSucceeded = !!updated;
-    }
-    if (!resetSucceeded) {
-        return;
-    }
-    const runtimeChat = world.chats.get(chatId);
-    if (runtimeChat) {
-        runtimeChat.name = NEW_CHAT_TITLE;
-    }
-}
-async function syncRuntimeAgentMemoryFromStorage(world, worldId) {
-    if (!world?.agents || world.agents.size === 0)
-        return;
-    for (const runtimeAgent of world.agents.values()) {
-        const persistedAgent = await storageWrappers.loadAgent(worldId, runtimeAgent.id);
-        runtimeAgent.memory = Array.isArray(persistedAgent?.memory)
-            ? [...persistedAgent.memory]
-            : [];
-    }
-}
-/**
- * Resolve a world identifier to the persisted world ID.
- * Accepts either world ID or world name and supports historical rename drift.
- */
-async function resolveWorldIdentifier(worldIdOrName) {
-    const normalizedInput = utils.toKebabCase(worldIdOrName);
-    if (!normalizedInput)
-        return null;
-    // Fast path: direct normalized ID lookup
-    const directWorld = await storageWrappers.loadWorld(normalizedInput);
-    if (directWorld?.id) {
-        return directWorld.id;
-    }
-    // Fallback: scan worlds and match by normalized ID or normalized name
-    const worlds = await storageWrappers.listWorlds();
-    const matched = worlds.find((world) => {
-        const storedId = String(world.id || '');
-        const storedName = String(world.name || '');
-        return (storedId === worldIdOrName ||
-            storedName === worldIdOrName ||
-            utils.toKebabCase(storedId) === normalizedInput ||
-            utils.toKebabCase(storedName) === normalizedInput);
-    });
-    return matched?.id || null;
-}
-async function getResolvedWorldId(worldIdOrName) {
-    const resolved = await resolveWorldIdentifier(worldIdOrName);
-    return resolved || utils.toKebabCase(worldIdOrName);
-}
-/**
- * Resolve an agent identifier to the persisted agent ID within a world.
- * Accepts either agent ID or agent name and supports historical rename drift.
- */
-async function resolveAgentIdentifier(worldIdOrName, agentIdOrName) {
-    const resolvedWorldId = await getResolvedWorldId(worldIdOrName);
-    const normalizedInput = utils.toKebabCase(agentIdOrName);
-    if (!normalizedInput)
-        return null;
-    // Fast path: direct normalized ID lookup
-    const directAgent = await storageWrappers.loadAgent(resolvedWorldId, normalizedInput);
-    if (directAgent?.id) {
-        return directAgent.id;
-    }
-    // Fallback: scan agents and match by normalized ID or normalized name
-    const agents = await storageWrappers.listAgents(resolvedWorldId);
-    const matched = agents.find((agent) => {
-        const storedId = String(agent.id || '');
-        const storedName = String(agent.name || '');
-        return (storedId === agentIdOrName ||
-            storedName === agentIdOrName ||
-            utils.toKebabCase(storedId) === normalizedInput ||
-            utils.toKebabCase(storedName) === normalizedInput);
-    });
-    return matched?.id || null;
-}
-async function getResolvedAgentId(worldIdOrName, agentIdOrName) {
-    const resolved = await resolveAgentIdentifier(worldIdOrName, agentIdOrName);
-    return resolved || utils.toKebabCase(agentIdOrName);
-}
 /**
  * Create new world with configuration and automatically create a new chat
  */
@@ -293,6 +258,9 @@ export async function createWorld(params) {
         chatLLMModel: params.chatLLMModel,
         mcpConfig: params.mcpConfig,
         variables: params.variables,
+        heartbeatEnabled: params.heartbeatEnabled === true,
+        heartbeatInterval: params.heartbeatInterval ? String(params.heartbeatInterval).trim() : null,
+        heartbeatPrompt: params.heartbeatPrompt ? String(params.heartbeatPrompt) : null,
         createdAt: new Date(),
         lastUpdated: new Date(),
         totalAgents: 0,
@@ -337,8 +305,59 @@ export async function updateWorld(worldId, updates) {
         lastUpdated: new Date()
     };
     await storageWrappers.saveWorld(updatedData);
+    const { getActiveSubscribedWorlds } = await import('./subscription.js');
+    const activeRuntimeWorlds = getActiveSubscribedWorlds(resolvedWorldId);
+    if (activeRuntimeWorlds.length > 0) {
+        const shouldSyncCurrentChatId = normalizedUpdates.currentChatId !== undefined;
+        for (const activeRuntimeWorld of activeRuntimeWorlds) {
+            syncActiveRuntimeWorldMetadata(activeRuntimeWorld, updatedData);
+            if (shouldSyncCurrentChatId) {
+                activeRuntimeWorld.currentChatId = updatedData.currentChatId ?? null;
+            }
+        }
+        return activeRuntimeWorlds[0] ?? null;
+    }
     return getWorld(resolvedWorldId);
 }
+function syncActiveRuntimeWorldMetadata(targetWorld, persistedWorld) {
+    targetWorld.name = persistedWorld.name;
+    targetWorld.description = persistedWorld.description;
+    targetWorld.turnLimit = persistedWorld.turnLimit;
+    targetWorld.mainAgent = persistedWorld.mainAgent ?? null;
+    targetWorld.chatLLMProvider = persistedWorld.chatLLMProvider;
+    targetWorld.chatLLMModel = persistedWorld.chatLLMModel;
+    targetWorld.mcpConfig = persistedWorld.mcpConfig ?? null;
+    targetWorld.variables = persistedWorld.variables;
+    targetWorld.uiMode = persistedWorld.uiMode;
+    targetWorld.dashboardZones = persistedWorld.dashboardZones;
+    targetWorld.heartbeatEnabled = persistedWorld.heartbeatEnabled === true;
+    targetWorld.heartbeatInterval = persistedWorld.heartbeatInterval ?? null;
+    targetWorld.heartbeatPrompt = persistedWorld.heartbeatPrompt ?? null;
+    targetWorld.lastUpdated = persistedWorld.lastUpdated;
+}
+async function getPersistedCurrentChatId(worldId) {
+    const resolvedWorldId = await getResolvedWorldId(worldId);
+    const worldData = await storageWrappers.loadWorld(resolvedWorldId);
+    const chatId = String(worldData?.currentChatId || '').trim();
+    return chatId || null;
+}
+async function setPersistedCurrentChatId(worldId, chatId) {
+    const resolvedWorldId = await getResolvedWorldId(worldId);
+    const worldData = await storageWrappers.loadWorld(resolvedWorldId);
+    if (!worldData) {
+        return;
+    }
+    const normalizedChatId = String(chatId || '').trim() || null;
+    const existingChatId = String(worldData.currentChatId || '').trim() || null;
+    if (existingChatId === normalizedChatId) {
+        return;
+    }
+    await storageWrappers.saveWorld({
+        ...worldData,
+        currentChatId: normalizedChatId,
+        lastUpdated: new Date(),
+    });
+}
 /**
  * Set the raw .env-style variables text for a world
  */
@@ -391,7 +410,11 @@ export async function deleteWorld(worldId) {
     if (worldData?._activityListenerCleanup) {
         worldData._activityListenerCleanup();
     }
-    return await storageWrappers.deleteWorld(resolvedWorldId);
+    const result = await storageWrappers.deleteWorld(resolvedWorldId);
+    // Stop any active runtime so subsequent subscriptions get a fresh world
+    // instead of reusing state from the deleted incarnation.
+    await stopWorldRuntimesByWorldId(resolvedWorldId);
+    return result;
 }
 /**
  * Get all world IDs and basic information
@@ -455,6 +478,8 @@ export async function getWorld(worldId) {
         world._eventPersistenceCleanup = setupEventPersistence(world);
         world._activityListenerCleanup = setupWorldActivityListener(world);
     }
+    // Initialize queued chat set; per-chat seeding deferred to explicit queue operations
+    world._queuedChatIds = new Set();
     return world;
 }
 /**
@@ -705,7 +730,7 @@ async function createChat(worldId, params) {
     const chatData = {
         id: chatId,
         worldId,
-        name: NEW_CHAT_CONFIG.REUSABLE_CHAT_TITLE,
+        name: NEW_CHAT_TITLE,
         description: params.description,
         createdAt: now,
         updatedAt: now,
@@ -730,7 +755,8 @@ export async function newChat(worldId) {
     if (existingChat) {
         const messages = await storageWrappers.getMemory(resolvedWorldId, existingChat.id);
         if (messages.length === 0) {
-            return await updateWorld(resolvedWorldId, { currentChatId: existingChat.id });
+            await setPersistedCurrentChatId(resolvedWorldId, existingChat.id);
+            return await getWorld(resolvedWorldId);
         }
         // If chat has messages, fall through to create a new one
     }
@@ -738,7 +764,8 @@ export async function newChat(worldId) {
         name: NEW_CHAT_TITLE,
         captureChat: false
     });
-    return await updateWorld(resolvedWorldId, { currentChatId: chatData.id });
+    await setPersistedCurrentChatId(resolvedWorldId, chatData.id);
+    return await getWorld(resolvedWorldId);
 }
 /**
  * Create a branched chat from a source chat up to (and including) the provided message.
@@ -795,13 +822,10 @@ export async function branchChatFromMessage(worldId, sourceChatId, messageId) {
     };
     const cutoffTimestamp = toEpochMillis(targetMessage?.createdAt);
     const updatedWorld = await newChat(resolvedWorldId);
-    if (!updatedWorld || !updatedWorld.currentChatId) {
+    const newChatId = await getPersistedCurrentChatId(resolvedWorldId);
+    if (!updatedWorld || !newChatId) {
         throw new Error('Failed to create branch chat.');
     }
-    const newChatId = String(updatedWorld.currentChatId || '').trim();
-    if (!newChatId) {
-        throw new Error('Failed to resolve new chat ID for branch.');
-    }
     let copiedMessageCount = 0;
     const agents = await listAgents(resolvedWorldId);
     try {
@@ -868,6 +892,11 @@ export async function listChats(worldId) {
 export async function updateChat(worldId, chatId, updates) {
     await ensureInitialization();
     const resolvedWorldId = await getResolvedWorldId(worldId);
+    // When the caller explicitly sets a name, treat it as a manual title so the
+    // auto-title scheduler will not overwrite it.
+    if (typeof updates.name === 'string' && updates.name.trim().length > 0) {
+        updates = { ...updates, titleProvenance: TITLE_PROVENANCE_MANUAL };
+    }
     const chat = await storageWrappers.updateChatData(resolvedWorldId, chatId, updates);
     if (!chat) {
         return null;
@@ -888,12 +917,10 @@ export async function deleteChat(worldId, chatId) {
     // First, delete all agent memory items associated with this chat
     const deletedMemoryCount = await storageWrappers.deleteMemoryByChatId(resolvedWorldId, chatId);
     logger.debug('Deleted memory items for chat', { worldId, resolvedWorldId, chatId, deletedMemoryCount });
-    // Get the world to check if this was the current chat
+    const persistedCurrentChatId = await getPersistedCurrentChatId(resolvedWorldId);
+    // Get the world to update in-memory chat cache only
     const world = await getWorld(resolvedWorldId);
-    let shouldSetNewCurrentChat = false;
-    if (world && world.currentChatId === chatId) {
-        shouldSetNewCurrentChat = true;
-    }
+    const shouldSetNewCurrentChat = persistedCurrentChatId === chatId;
     // Then delete the chat itself
     const chatDeleted = await storageWrappers.deleteChatData(resolvedWorldId, chatId);
     // Remove from world's in-memory chat map
@@ -906,7 +933,7 @@ export async function deleteChat(worldId, chatId) {
         if (remainingChats.length > 0) {
             // Set the most recently updated chat as current
             const latestChat = remainingChats.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())[0];
-            await updateWorld(resolvedWorldId, { currentChatId: latestChat.id });
+            await setPersistedCurrentChatId(resolvedWorldId, latestChat.id);
         }
         else {
             // No chats left, create a new one
@@ -916,14 +943,64 @@ export async function deleteChat(worldId, chatId) {
     }
     return chatDeleted;
 }
-export async function restoreChat(worldId, chatId) {
+async function activateChatResources(world, resolvedWorldId, chatId, options) {
+    await syncRuntimeAgentMemoryFromStorage(world, resolvedWorldId);
+    loggerRestore.debug('Restore chat memory sync complete', { worldId: world.id, chatId });
+    const memoryForApprovals = await storageWrappers.getMemory(resolvedWorldId, chatId);
+    clearChatSkillApprovals(resolvedWorldId, chatId);
+    reconstructSkillApprovalsFromMessages(resolvedWorldId, chatId, Array.isArray(memoryForApprovals) ? memoryForApprovals : []);
+    const { getActiveSubscribedWorld } = await import('./subscription.js');
+    const runtimeWorld = getActiveSubscribedWorld(resolvedWorldId, chatId) || world;
+    const replayedHitlPromptCount = replayPendingHitlRequests(runtimeWorld, chatId);
+    loggerRestore.debug('Restore chat pending HITL replay triggered', { worldId: world.id, chatId });
+    if (options?.suppressAutoResume === true) {
+        loggerRestore.debug('Restore chat auto-resume suppressed for mutation flow', {
+            worldId: world.id,
+            chatId,
+        });
+        return;
+    }
+    if (replayedHitlPromptCount > 0) {
+        loggerRestore.debug('Restore chat auto-resume skipped because chat is awaiting HITL input', {
+            worldId: world.id,
+            chatId,
+            replayedHitlPromptCount,
+        });
+        return;
+    }
+    triggerPendingToolCallResumeFromLastMessage(runtimeWorld, chatId);
+    clearQueuePauseForChat(runtimeWorld.id, chatId);
+    triggerPendingQueueResume(runtimeWorld, chatId, { recoverStaleSending: true });
+}
+export async function restoreChat(worldId, chatId, options) {
     await ensureInitialization();
     const resolvedWorldId = await getResolvedWorldId(worldId);
+    const restoreStartedAt = Date.now();
+    loggerRestore.debug('Restore chat started', {
+        worldId: resolvedWorldId,
+        requestedChatId: chatId,
+    });
     let world = await getWorld(resolvedWorldId);
+    const persistedCurrentChatId = await getPersistedCurrentChatId(resolvedWorldId);
     if (!world) {
+        loggerRestore.debug('Restore chat aborted: world missing', {
+            worldId: resolvedWorldId,
+            requestedChatId: chatId,
+        });
         return null;
     }
-    if (world.currentChatId === chatId) {
+    if (persistedCurrentChatId === chatId) {
+        loggerRestore.debug('Restore chat detected already-current chat', {
+            worldId: world.id,
+            chatId,
+            action: 'sync-memory+resume',
+        });
+        await activateChatResources(world, resolvedWorldId, chatId, options);
+        loggerRestore.debug('Restore chat resume inspection triggered', {
+            worldId: world.id,
+            chatId,
+            elapsedMs: Date.now() - restoreStartedAt,
+        });
         return world;
     }
     const runtimeChatExists = world.chats.has(chatId);
@@ -931,13 +1008,81 @@ export async function restoreChat(worldId, chatId) {
         ? true
         : !!(await storageWrappers.loadChatData(resolvedWorldId, chatId));
     if (!persistedChatExists) {
+        loggerRestore.debug('Restore chat aborted: chat missing', {
+            worldId: resolvedWorldId,
+            requestedChatId: chatId,
+            runtimeChatExists,
+        });
         return null;
     }
-    world = await updateWorld(resolvedWorldId, {
-        currentChatId: chatId
+    // Auto-pause the old chat's queue when switching away (FR-8 safety)
+    const previousChatId = persistedCurrentChatId;
+    if (previousChatId && previousChatId !== chatId) {
+        autoPauseQueueForChat(resolvedWorldId, previousChatId);
+        loggerRestore.debug('Auto-paused queue for previous chat on switch', {
+            worldId: resolvedWorldId,
+            previousChatId,
+            newChatId: chatId,
+        });
+    }
+    loggerRestore.debug('Restore chat switching current chat', {
+        worldId: resolvedWorldId,
+        fromChatId: previousChatId,
+        toChatId: chatId,
+    });
+    await setPersistedCurrentChatId(resolvedWorldId, chatId);
+    world = await getWorld(resolvedWorldId);
+    if (world) {
+        await activateChatResources(world, resolvedWorldId, chatId, options);
+        loggerRestore.debug('Restore chat resume inspection triggered', {
+            worldId: world.id,
+            chatId,
+            elapsedMs: Date.now() - restoreStartedAt,
+        });
+    }
+    else {
+        loggerRestore.warn('Restore chat update-world returned null', {
+            worldId: resolvedWorldId,
+            requestedChatId: chatId,
+            elapsedMs: Date.now() - restoreStartedAt,
+        });
+    }
+    loggerRestore.debug('Restore chat completed', {
+        worldId: resolvedWorldId,
+        requestedChatId: chatId,
+        restoredCurrentChatId: await getPersistedCurrentChatId(resolvedWorldId),
+        elapsedMs: Date.now() - restoreStartedAt,
     });
     return world;
 }
+export async function activateChatWithSnapshot(worldId, chatId) {
+    const world = await restoreChat(worldId, chatId);
+    if (!world) {
+        return null;
+    }
+    const resolvedChatId = String(chatId || '').trim();
+    if (!resolvedChatId) {
+        return null;
+    }
+    const memory = await storageWrappers.getMemory(world.id, resolvedChatId);
+    const safeMemory = Array.isArray(memory) ? memory : [];
+    // Message-authoritative: pending HITL state is derived from persisted messages only.
+    // Runtime pending map serves transport/notification purposes; the snapshot always uses
+    // messages as the single source of truth (AD-1, AD-4).
+    const hitlPrompts = listPendingHitlPromptEventsFromMessages(safeMemory, resolvedChatId);
+    loggerRestore.debug('Activate chat snapshot assembled', {
+        worldId: world.id,
+        chatId: resolvedChatId,
+        memoryCount: safeMemory.length,
+        hitlPromptCount: hitlPrompts.length,
+    });
+    return {
+        world,
+        chatId: resolvedChatId,
+        memory: safeMemory,
+        hitlPrompts,
+    };
+}
 export async function getMemory(worldId, chatId) {
     await ensureInitialization();
     const resolvedWorldId = await getResolvedWorldId(worldId);
@@ -945,7 +1090,10 @@ export async function getMemory(worldId, chatId) {
     if (!world) {
         return null;
     }
-    const resolvedChatId = chatId || world.currentChatId;
+    const resolvedChatId = String(chatId || '').trim();
+    if (!resolvedChatId) {
+        throw new Error('getMemory: chatId is required.');
+    }
     const memory = await storageWrappers.getMemory(resolvedWorldId, resolvedChatId);
     // Auto-repair legacy memories so downstream clients can rely on messageId without UI fallbacks.
     if (memory.some(message => !message.messageId)) {
@@ -958,316 +1106,6 @@ export async function getMemory(worldId, chatId) {
     }
     return memory;
 }
-/**
- * Migrate messages to include messageId for user message edit feature
- * Automatically detects storage type and handles both file and SQL storage
- * Idempotent - safe to run multiple times
- *
- * @param worldId - World ID to migrate messages for
- * @returns Number of messages migrated
- */
-export async function migrateMessageIds(worldId) {
-    await ensureInitialization();
-    const resolvedWorldId = await getResolvedWorldId(worldId);
-    let totalMigrated = 0;
-    const world = await getWorld(resolvedWorldId);
-    if (!world) {
-        throw new Error(`World '${worldId}' not found`);
-    }
-    // Get all agents in the world
-    const agents = await listAgents(resolvedWorldId);
-    // Get all chats for the world
-    const chats = await storageWrappers.listChats(resolvedWorldId);
-    // Migrate messages for each chat
-    for (const chat of chats) {
-        const chatId = chat.id;
-        // Get all memory for this chat
-        const memory = await storageWrappers.getMemory(resolvedWorldId, chatId);
-        if (!memory || memory.length === 0) {
-            continue;
-        }
-        // Check which messages need messageId
-        let needsMigration = false;
-        const updatedMemory = [];
-        for (const message of memory) {
-            if (!message.messageId) {
-                needsMigration = true;
-                updatedMemory.push({
-                    ...message,
-                    messageId: nanoid(10)
-                });
-                totalMigrated++;
-            }
-            else {
-                updatedMemory.push(message);
-            }
-        }
-        // If any messages were updated, save the entire memory back
-        if (needsMigration) {
-            // For each agent, update their memory with the migrated messages
-            for (const agent of agents) {
-                const agentMessages = updatedMemory.filter(m => m.agentId === agent.id);
-                if (agentMessages.length > 0) {
-                    await storageWrappers.saveAgentMemory(resolvedWorldId, agent.id, agentMessages);
-                }
-            }
-        }
-    }
-    logger.info(`Migrated ${totalMigrated} messages with messageId for world '${resolvedWorldId}'`);
-    return totalMigrated;
-}
-/**
- * Remove a message and all subsequent messages from all agents in a world
- * Used for user message editing feature
- *
- * @param worldId - World ID
- * @param messageId - ID of the message to remove (and all after it)
- * @param chatId - Chat ID to filter messages
- * @returns RemovalResult with per-agent removal details
- */
-export async function removeMessagesFrom(worldId, messageId, chatId) {
-    await ensureInitialization();
-    const resolvedWorldId = await getResolvedWorldId(worldId);
-    const world = await getWorld(resolvedWorldId);
-    if (!world) {
-        throw new Error(`World '${worldId}' not found`);
-    }
-    // Get all agents
-    const agents = await listAgents(resolvedWorldId);
-    // Track results per agent
-    const processedAgents = [];
-    const failedAgents = [];
-    let messagesRemovedTotal = 0;
-    let foundTargetInAnyAgent = false;
-    let targetTimestampValue = null;
-    const loadedAgentsById = new Map();
-    const toTimestamp = (value) => {
-        if (value instanceof Date) {
-            return value.getTime();
-        }
-        if (value) {
-            const parsed = new Date(value).getTime();
-            if (Number.isFinite(parsed)) {
-                return parsed;
-            }
-        }
-        return Date.now();
-    };
-    // First pass: load each agent and discover the deletion cutoff timestamp
-    for (const agent of agents) {
-        try {
-            const fullAgent = await storageWrappers.loadAgent(resolvedWorldId, agent.id);
-            if (!fullAgent || !fullAgent.memory || fullAgent.memory.length === 0) {
-                continue;
-            }
-            loadedAgentsById.set(agent.id, fullAgent);
-            // Find the target message in this chat for global cutoff derivation
-            const targetMsg = fullAgent.memory.find(m => m.messageId === messageId && m.chatId === chatId);
-            if (targetMsg) {
-                foundTargetInAnyAgent = true;
-                const candidateTimestamp = toTimestamp(targetMsg.createdAt);
-                if (targetTimestampValue === null || candidateTimestamp < targetTimestampValue) {
-                    targetTimestampValue = candidateTimestamp;
-                }
-            }
-        }
-        catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            failedAgents.push({
-                agentId: agent.id,
-                error: errorMsg
-            });
-        }
-    }
-    if (!foundTargetInAnyAgent || targetTimestampValue === null) {
-        const notFoundFailures = agents.length > 0
-            ? [
-                ...failedAgents,
-                { agentId: 'all', error: `Message with ID '${messageId}' not found in chat '${chatId}'` }
-            ]
-            : failedAgents;
-        return {
-            success: false,
-            messageId,
-            totalAgents: agents.length,
-            processedAgents,
-            failedAgents: notFoundFailures,
-            messagesRemovedTotal,
-            requiresRetry: false,
-            resubmissionStatus: 'skipped',
-            newMessageId: undefined
-        };
-    }
-    // Second pass: apply cutoff to all agents in the target chat
-    for (const agent of agents) {
-        if (failedAgents.some(entry => entry.agentId === agent.id)) {
-            continue;
-        }
-        const fullAgent = loadedAgentsById.get(agent.id);
-        if (!fullAgent || !Array.isArray(fullAgent.memory) || fullAgent.memory.length === 0) {
-            processedAgents.push(agent.id);
-            continue;
-        }
-        try {
-            const messagesToKeep = fullAgent.memory.filter(m => {
-                if (m.chatId !== chatId) {
-                    return true;
-                }
-                const msgTimestamp = toTimestamp(m.createdAt);
-                return msgTimestamp < targetTimestampValue;
-            });
-            const removedCount = fullAgent.memory.length - messagesToKeep.length;
-            if (removedCount === 0) {
-                processedAgents.push(agent.id);
-                continue;
-            }
-            await storageWrappers.saveAgentMemory(resolvedWorldId, agent.id, messagesToKeep);
-            messagesRemovedTotal += removedCount;
-            processedAgents.push(agent.id);
-        }
-        catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            failedAgents.push({
-                agentId: agent.id,
-                error: errorMsg
-            });
-        }
-    }
-    logger.info('Message removal completed', {
-        messageId,
-        success: failedAgents.length === 0,
-        totalAgents: agents.length,
-        processedAgents: processedAgents.length,
-        failedAgents: failedAgents.length,
-        messagesRemovedTotal
-    });
-    return {
-        success: failedAgents.length === 0,
-        messageId,
-        totalAgents: agents.length,
-        processedAgents,
-        failedAgents,
-        messagesRemovedTotal,
-        requiresRetry: failedAgents.length > 0,
-        resubmissionStatus: 'skipped', // Will be updated by editUserMessage
-        newMessageId: undefined
-    };
-}
-/**
- * Edit a user message by removing it and all subsequent messages, then resubmitting with new content
- * Combines removal and resubmission in a single operation with comprehensive error tracking
- *
- * @param worldId - World ID
- * @param messageId - ID of the message to edit
- * @param newContent - New message content
- * @param chatId - Chat ID for the message
- * @returns RemovalResult with removal and resubmission details
- */
-export async function editUserMessage(worldId, messageId, newContent, chatId, targetWorld) {
-    await ensureInitialization();
-    const resolvedWorldId = await getResolvedWorldId(worldId);
-    const { getActiveSubscribedWorld } = await import('./subscription.js');
-    const activeSubscribedWorld = targetWorld || getActiveSubscribedWorld(resolvedWorldId);
-    const world = activeSubscribedWorld || await getWorld(resolvedWorldId);
-    if (!world) {
-        throw new Error(`World '${worldId}' not found`);
-    }
-    if (hasActiveChatMessageProcessing(resolvedWorldId, chatId)) {
-        stopMessageProcessing(resolvedWorldId, chatId);
-    }
-    // Step 1: Remove the message and all subsequent messages
-    const removalResult = await removeMessagesFrom(resolvedWorldId, messageId, chatId);
-    if (!removalResult.success) {
-        return removalResult;
-    }
-    await syncRuntimeAgentMemoryFromStorage(activeSubscribedWorld || world, resolvedWorldId);
-    // Step 2: Reset auto-generated chat title so post-resubmission title generation can run again.
-    await resetAutoGeneratedChatTitleForEditResubmission(world, chatId);
-    const worldForResubmission = activeSubscribedWorld || world;
-    if (!activeSubscribedWorld) {
-        const { subscribeAgentToMessages, subscribeWorldToMessages } = await import('./events/index.js');
-        for (const agent of worldForResubmission.agents.values()) {
-            subscribeAgentToMessages(worldForResubmission, agent);
-        }
-        subscribeWorldToMessages(worldForResubmission);
-    }
-    // Step 3: Attempt resubmission using publishMessage directly
-    try {
-        const { publishMessage } = await import('./events/index.js');
-        const messageEvent = publishMessage(worldForResubmission, newContent, 'human', chatId);
-        logger.info(`Resubmitted edited message to world '${resolvedWorldId}' with new messageId '${messageEvent.messageId}'`);
-        return {
-            ...removalResult,
-            resubmissionStatus: 'success',
-            newMessageId: messageEvent.messageId
-        };
-    }
-    catch (error) {
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        logger.error(`Failed to resubmit message to world '${resolvedWorldId}': ${errorMsg}`);
-        return {
-            ...removalResult,
-            resubmissionStatus: 'failed',
-            resubmissionError: errorMsg
-        };
-    }
-}
-/**
- * Log an error from a message edit operation for troubleshooting and retry
- * Stores errors in data/worlds/{worldName}/edit-errors.json
- * Keeps only the last 100 errors
- *
- * @param worldId - World ID
- * @param errorLog - EditErrorLog to persist
- */
-export async function logEditError(worldId, errorLog) {
-    await ensureInitialization();
-    const resolvedWorldId = await getResolvedWorldId(worldId);
-    const rootPath = getDefaultRootPath();
-    const worldDir = getWorldDir(rootPath, resolvedWorldId);
-    const errorsFile = path.join(worldDir, 'edit-errors.json');
-    try {
-        // Read existing errors
-        let errors = [];
-        if (fs.existsSync(errorsFile)) {
-            const data = fs.readFileSync(errorsFile, 'utf-8');
-            errors = JSON.parse(data);
-        }
-        // Add new error
-        errors.push(errorLog);
-        // Keep only last 100 errors
-        if (errors.length > 100) {
-            errors = errors.slice(-100);
-        }
-        // Write back to file
-        fs.writeFileSync(errorsFile, JSON.stringify(errors, null, 2), 'utf-8');
-        logger.debug(`Logged edit error for world '${resolvedWorldId}'`);
-    }
-    catch (error) {
-        logger.error(`Failed to log edit error for world '${resolvedWorldId}': ${error instanceof Error ? error.message : error}`);
-    }
-}
-/**
- * Get edit error logs for a world
- *
- * @param worldId - World ID
- * @returns Array of EditErrorLog entries
- */
-export async function getEditErrors(worldId) {
-    await ensureInitialization();
-    const resolvedWorldId = await getResolvedWorldId(worldId);
-    const rootPath = getDefaultRootPath();
-    const worldDir = getWorldDir(rootPath, resolvedWorldId);
-    const errorsFile = path.join(worldDir, 'edit-errors.json');
-    try {
-        if (!fs.existsSync(errorsFile)) {
-            return [];
-        }
-        const data = fs.readFileSync(errorsFile, 'utf-8');
-        return JSON.parse(data);
-    }
-    catch (error) {
-        logger.error(`Failed to read edit errors for world '${resolvedWorldId}': ${error instanceof Error ? error.message : error}`);
-        return [];
-    }
-}
+// Re-exports from extracted modules
+export { migrateMessageIds, removeMessagesFrom, editUserMessage, logEditError, getEditErrors } from './message-edit-manager.js';
+export { addToQueue, recoverQueueSendingMessages, enqueueAndProcessUserTurn, dispatchImmediateChatMessage, getQueueMessages, removeFromQueue, pauseChatQueue, resumeChatQueue, stopChatQueue, clearChatQueue, retryQueueMessage } from './queue-manager.js';