diff --git a/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx b/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
new file mode 100644
index 0000000..57798a4
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
@@ -0,0 +1,198 @@
+/**
+ * Helper sub-components extracted from ChatPanel
+ *
+ * StageIndicator, ActionsTaken, CharacterAvatar, renderMessageContent
+ */
+
+import React, { useState, useEffect, useCallback, memo, useRef } from 'react';
+import { ChevronDown, ChevronRight } from 'lucide-react';
+import type { CharacterConfig } from '@/lib/characterManager';
+import { resolveEmotionMedia } from '@/lib/characterManager';
+import type { ModManager } from '@/lib/modManager';
+import styles from './index.module.scss';
+
+// ---------------------------------------------------------------------------
+// Render message content — formats (action text) as styled spans
+// ---------------------------------------------------------------------------
+
+export function renderMessageContent(content: string): React.ReactNode {
+  const parts = content.split(/(\([^)]+\))/g);
+  return parts.map((part, i) => {
+    if (/^\([^)]+\)$/.test(part)) {
+      return (
+        <span key={i} className={styles.emotion}>
+          {part}
+        </span>
+      );
+    }
+    return part;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Stage Indicator
+// ---------------------------------------------------------------------------
+
+export const StageIndicator: React.FC<{ modManager: ModManager | null }> = ({ modManager }) => {
+  if (!modManager) return null;
+
+  const total = modManager.stageCount;
+  const current = modManager.currentStageIndex;
+  const finished = modManager.isFinished;
+
+  return (
+    <div className={styles.stageIndicator}>
+      <span className={styles.stageText}>
+        Stage {finished ? total : current + 1}/{total}
+      </span>
+      <div className={styles.stageDots}>
+        {Array.from({ length: total }, (_, i) => (
+          <div
+            key={i}
+            className={`${styles.stageDot} ${
+              i < current || finished
+                ? styles.stageDotCompleted
+                : i === current
+                  ? styles.stageDotCurrent
+                  : ''
+            }`}
+          />
+        ))}
+      </div>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Actions Taken (collapsible)
+// ---------------------------------------------------------------------------
+
+export const ActionsTaken: React.FC<{ calls: string[] }> = ({ calls }) => {
+  const [open, setOpen] = useState(false);
+  if (calls.length === 0) return null;
+
+  return (
+    <div className={styles.actionsTaken}>
+      <button className={styles.actionsTakenToggle} onClick={() => setOpen(!open)}>
+        Actions taken
+        {open ? <ChevronDown size={12} /> : <ChevronRight size={12} />}
+      </button>
+      {open && (
+        <div className={styles.actionsTakenList}>
+          {calls.map((c, i) => (
+            <div key={i}>{c}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// CharacterAvatar – crossfade between emotion media without flashing
+// ---------------------------------------------------------------------------
+
+interface AvatarLayer {
+  url: string;
+  type: 'video' | 'image';
+  active: boolean;
+}
+
+export const CharacterAvatar: React.FC<{
+  character: CharacterConfig;
+  emotion?: string;
+  onEmotionEnd: () => void;
+}> = memo(({ character, emotion, onEmotionEnd }) => {
+  const isIdle = !emotion;
+  const media = resolveEmotionMedia(character, emotion || 'default');
+
+  const [layers, setLayers] = useState<AvatarLayer[]>(() =>
+    media ? [{ url: media.url, type: media.type, active: true }] : [],
+  );
+  const activeUrl = layers.find((l) => l.active)?.url;
+  const cleanupRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (cleanupRef.current) clearTimeout(cleanupRef.current);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!media) {
+      setLayers([]);
+      return;
+    }
+    if (media.url === activeUrl) return;
+    setLayers((prev) => {
+      // If the URL already exists (possibly inactive), reactivate it
+      const existing = prev.find((l) => l.url === media.url);
+      if (existing) {
+        // Cancel any pending cleanup that might remove this layer
+        if (cleanupRef.current) {
+          clearTimeout(cleanupRef.current);
+          cleanupRef.current = null;
+        }
+        return prev.map((l) => ({
+          ...l,
+          active: l.url === media.url,
+        }));
+      }
+      return [...prev, { url: media.url, type: media.type, active: false }];
+    });
+  }, [media?.url, activeUrl]);
+
+  const handleMediaReady = useCallback((readyUrl: string) => {
+    setLayers((prev) => {
+      const staleUrls = prev.filter((l) => l.url !== readyUrl).map((l) => l.url);
+      if (cleanupRef.current) clearTimeout(cleanupRef.current);
+      cleanupRef.current = setTimeout(() => {
+        setLayers((curr) => curr.filter((l) => !staleUrls.includes(l.url)));
+      }, 300);
+      return prev.map((l) => ({ ...l, active: l.url === readyUrl }));
+    });
+  }, []);
+
+  if (layers.length === 0) {
+    return <div className={styles.avatarPlaceholder}>{character.character_name.charAt(0)}</div>;
+  }
+
+  return (
+    <>
+      {layers.map((layer) => {
+        const layerStyle: React.CSSProperties = {
+          position: 'absolute',
+          inset: 0,
+          opacity: layer.active ? 1 : 0,
+          transition: 'opacity 0.25s ease-out',
+        };
+        if (layer.type === 'video') {
+          return (
+            <video
+              key={layer.url}
+              className={styles.avatarImage}
+              style={layerStyle}
+              src={layer.url}
+              autoPlay
+              loop={layer.active ? isIdle : false}
+              muted
+              playsInline
+              onCanPlay={!layer.active ? () => handleMediaReady(layer.url) : undefined}
+              onEnded={layer.active && !isIdle ? onEmotionEnd : undefined}
+            />
+          );
+        }
+        return (
+          <img
+            key={layer.url}
+            className={styles.avatarImage}
+            style={layerStyle}
+            src={layer.url}
+            alt={character.character_name}
+            onLoad={!layer.active ? () => handleMediaReady(layer.url) : undefined}
+          />
+        );
+      })}
+    </>
+  );
+});
diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
new file mode 100644
index 0000000..e41c4e9
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -0,0 +1,292 @@
+/**
+ * SettingsModal — LLM + Image Generation configuration
+ *
+ * Extracted from ChatPanel for maintainability.
+ */
+
+import React, { useState, useEffect } from 'react';
+import { Pencil, List } from 'lucide-react';
+import { PROVIDER_MODELS, getDefaultProviderConfig, type LLMProvider } from '@/lib/llmModels';
+import type { LLMConfig } from '@/lib/llmModels';
+import {
+  getDefaultImageGenConfig,
+  type ImageGenConfig,
+  type ImageGenProvider,
+} from '@/lib/imageGenClient';
+import styles from './index.module.scss';
+
+interface SettingsModalProps {
+  config: LLMConfig | null;
+  imageGenConfig: ImageGenConfig | null;
+  onSave: (_config: LLMConfig, _igConfig: ImageGenConfig | null) => void;
+  onClose: () => void;
+}
+
+const SettingsModal: React.FC<SettingsModalProps> = ({
+  config,
+  imageGenConfig,
+  onSave,
+  onClose,
+}) => {
+  // LLM settings
+  const [provider, setProvider] = useState<LLMProvider>(config?.provider || 'minimax');
+  const [apiKey, setApiKey] = useState(config?.apiKey || '');
+  const [baseUrl, setBaseUrl] = useState(
+    config?.baseUrl || getDefaultProviderConfig('minimax').baseUrl,
+  );
+  const [model, setModel] = useState(config?.model || getDefaultProviderConfig('minimax').model);
+  const [customHeaders, setCustomHeaders] = useState(config?.customHeaders || '');
+  const [manualModelMode, setManualModelMode] = useState(false);
+
+  const isPresetModel = PROVIDER_MODELS[provider]?.includes(model) ?? false;
+  const showDropdown = !manualModelMode && isPresetModel;
+
+  // Image gen settings
+  const [igProvider, setIgProvider] = useState<ImageGenProvider>(
+    imageGenConfig?.provider || 'gemini',
+  );
+  const [igApiKey, setIgApiKey] = useState(imageGenConfig?.apiKey || '');
+  const [igBaseUrl, setIgBaseUrl] = useState(
+    imageGenConfig?.baseUrl || getDefaultImageGenConfig('gemini').baseUrl,
+  );
+  const [igModel, setIgModel] = useState(
+    imageGenConfig?.model || getDefaultImageGenConfig('gemini').model,
+  );
+  const [igCustomHeaders, setIgCustomHeaders] = useState(imageGenConfig?.customHeaders || '');
+
+  // Sync local state when parent props change (e.g. async config load while modal is open)
+  useEffect(() => {
+    if (!config) return;
+    setProvider(config.provider);
+    setApiKey(config.apiKey);
+    setBaseUrl(config.baseUrl || getDefaultProviderConfig(config.provider).baseUrl);
+    setModel(config.model || getDefaultProviderConfig(config.provider).model);
+    setCustomHeaders(config.customHeaders || '');
+    setManualModelMode(false);
+  }, [config]);
+
+  useEffect(() => {
+    if (!imageGenConfig) return;
+    setIgProvider(imageGenConfig.provider);
+    setIgApiKey(imageGenConfig.apiKey);
+    setIgBaseUrl(
+      imageGenConfig.baseUrl || getDefaultImageGenConfig(imageGenConfig.provider).baseUrl,
+    );
+    setIgModel(imageGenConfig.model || getDefaultImageGenConfig(imageGenConfig.provider).model);
+    setIgCustomHeaders(imageGenConfig.customHeaders || '');
+  }, [imageGenConfig]);
+
+  const handleProviderChange = (p: LLMProvider) => {
+    setProvider(p);
+    const defaults = getDefaultProviderConfig(p);
+    setBaseUrl(defaults.baseUrl);
+    setModel(defaults.model);
+    setManualModelMode(false);
+  };
+
+  const handleModelChange = (newModel: string) => {
+    setModel(newModel);
+    setManualModelMode(false);
+  };
+
+  const handleIgProviderChange = (p: ImageGenProvider) => {
+    setIgProvider(p);
+    const defaults = getDefaultImageGenConfig(p);
+    setIgBaseUrl(defaults.baseUrl);
+    setIgModel(defaults.model);
+  };
+
+  return (
+    <div className={styles.overlay} data-testid="settings-overlay">
+      <div className={styles.settingsModal} data-testid="settings-modal">
+        <div className={styles.settingsTitle}>LLM Settings</div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Provider</label>
+          <select
+            className={styles.select}
+            value={provider}
+            onChange={(e) => handleProviderChange(e.target.value as LLMProvider)}
+          >
+            <option value="openai">OpenAI</option>
+            <option value="anthropic">Anthropic</option>
+            <option value="deepseek">DeepSeek</option>
+            <option value="llama.cpp">llama.cpp</option>
+            <option value="minimax">MiniMax</option>
+            <option value="z.ai">Z.ai</option>
+            <option value="kimi">Kimi</option>
+            <option value="openrouter">OpenRouter</option>
+          </select>
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>API Key</label>
+          <input
+            className={styles.fieldInput}
+            type="password"
+            value={apiKey}
+            onChange={(e) => setApiKey(e.target.value)}
+            placeholder="Optional for local servers"
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Base URL</label>
+          <input
+            className={styles.fieldInput}
+            value={baseUrl}
+            onChange={(e) => setBaseUrl(e.target.value)}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Model</label>
+          <div className={styles.modelSelectorWrapper}>
+            {showDropdown ? (
+              <>
+                <select
+                  className={styles.select}
+                  value={model}
+                  onChange={(e) => handleModelChange(e.target.value)}
+                >
+                  {PROVIDER_MODELS[provider]?.map((m) => (
+                    <option key={m} value={m}>
+                      {m}
+                    </option>
+                  ))}
+                </select>
+                <button
+                  type="button"
+                  onClick={() => setManualModelMode(true)}
+                  className={styles.manualToggleBtn}
+                  title="Enter custom model name"
+                >
+                  <Pencil size={14} />
+                </button>
+              </>
+            ) : (
+              <>
+                <input
+                  className={styles.fieldInput}
+                  value={model}
+                  onChange={(e) => setModel(e.target.value)}
+                  placeholder="e.g. gpt-4-turbo"
+                />
+                {isPresetModel && (
+                  <button
+                    type="button"
+                    onClick={() => setManualModelMode(false)}
+                    className={styles.manualToggleBtn}
+                    title="Back to model list"
+                  >
+                    <List size={14} />
+                  </button>
+                )}
+              </>
+            )}
+          </div>
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Custom Headers (one per line, Key: Value)</label>
+          <textarea
+            className={styles.fieldInput}
+            value={customHeaders}
+            onChange={(e) => setCustomHeaders(e.target.value)}
+            placeholder={'X-Custom-Header: value\nAnother-Header: value'}
+            rows={3}
+            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
+          />
+        </div>
+
+        <div className={styles.settingsDivider} />
+        <div className={styles.settingsTitle}>Image Generation</div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Provider</label>
+          <select
+            className={styles.select}
+            value={igProvider}
+            onChange={(e) => handleIgProviderChange(e.target.value as ImageGenProvider)}
+          >
+            <option value="openai">OpenAI</option>
+            <option value="gemini">Gemini</option>
+          </select>
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>API Key</label>
+          <input
+            className={styles.fieldInput}
+            type="password"
+            value={igApiKey}
+            onChange={(e) => setIgApiKey(e.target.value)}
+            placeholder="API Key..."
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Base URL</label>
+          <input
+            className={styles.fieldInput}
+            value={igBaseUrl}
+            onChange={(e) => setIgBaseUrl(e.target.value)}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Model</label>
+          <input
+            className={styles.fieldInput}
+            value={igModel}
+            onChange={(e) => setIgModel(e.target.value)}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Custom Headers</label>
+          <textarea
+            className={styles.fieldInput}
+            value={igCustomHeaders}
+            onChange={(e) => setIgCustomHeaders(e.target.value)}
+            placeholder={'X-Custom-Header: value'}
+            rows={2}
+            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
+          />
+        </div>
+
+        <div className={styles.settingsActions}>
+          <button className={styles.cancelBtn} onClick={onClose}>
+            Cancel
+          </button>
+          <button
+            className={styles.saveBtn}
+            onClick={() => {
+              const llmCfg: LLMConfig = {
+                provider,
+                apiKey,
+                baseUrl,
+                model,
+                ...(customHeaders.trim() ? { customHeaders } : {}),
+              };
+              const igCfg: ImageGenConfig | null = igApiKey.trim()
+                ? {
+                    provider: igProvider,
+                    apiKey: igApiKey,
+                    baseUrl: igBaseUrl,
+                    model: igModel,
+                    ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
+                  }
+                : null;
+              onSave(llmCfg, igCfg);
+            }}
+          >
+            Save
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default SettingsModal;
diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index 740488c..67e5502 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -1,57 +1,30 @@
-import React, { useState, useRef, useEffect, useCallback, memo } from 'react';
-import {
-  Settings,
-  Trash2,
-  RotateCcw,
-  Minus,
-  Maximize2,
-  ChevronDown,
-  ChevronRight,
-  Pencil,
-  List,
-} from 'lucide-react';
-import { chat, loadConfig, loadConfigSync, saveConfig, type ChatMessage } from '@/lib/llmClient';
-import {
-  PROVIDER_MODELS,
-  getDefaultProviderConfig,
-  type LLMConfig,
-  type LLMProvider,
-} from '@/lib/llmModels';
+/**
+ * ChatPanel — main chat interface
+ *
+ * This is the "thin shell" that wires state to UI.
+ * Core logic lives in:
+ *   - toolDefinitions.ts    (tool defs, system prompt builder)
+ *   - ChatSubComponents.tsx  (CharacterAvatar, StageIndicator, ActionsTaken)
+ *   - SettingsModal.tsx      (LLM + image gen config UI)
+ *   - useConversationEngine.ts (conversation loop + tool dispatch)
+ */
+
+import React, { useState, useRef, useEffect, useLayoutEffect, useCallback } from 'react';
+import { Settings, Trash2, RotateCcw, Minus, Maximize2 } from 'lucide-react';
+import { loadConfig, loadConfigSync, saveConfig, type ChatMessage } from '@/lib/llmClient';
+import type { LLMConfig } from '@/lib/llmModels';
 import {
   loadImageGenConfig,
   loadImageGenConfigSync,
   saveImageGenConfig,
-  getDefaultImageGenConfig,
   type ImageGenConfig,
-  type ImageGenProvider,
 } from '@/lib/imageGenClient';
-import {
-  getAppActionToolDefinition,
-  resolveAppAction,
-  getListAppsToolDefinition,
-  executeListApps,
-  APP_REGISTRY,
-  loadActionsFromMeta,
-} from '@/lib/appRegistry';
+// loadActionsFromMeta used by useConversationEngine
 import { seedMetaFiles } from '@/lib/seedMeta';
-import { dispatchAgentAction, onUserAction } from '@/lib/vibeContainerMock';
+import { onUserAction } from '@/lib/vibeContainerMock';
 import { closeAllWindows } from '@/lib/windowManager';
-import { getFileToolDefinitions, isFileTool, executeFileTool } from '@/lib/fileTools';
 import { setSessionPath } from '@/lib/sessionPath';
-import {
-  getMemoryToolDefinitions,
-  isMemoryTool,
-  executeMemoryTool,
-  loadMemories,
-  buildMemoryPrompt,
-  type MemoryEntry,
-} from '@/lib/memoryManager';
-import { logger } from '@/lib/logger';
-import {
-  getImageGenToolDefinitions,
-  isImageGenTool,
-  executeImageGenTool,
-} from '@/lib/imageGenTools';
+import { loadMemories, type MemoryEntry } from '@/lib/memoryManager';
 import {
   loadChatHistory,
   loadChatHistorySync,
@@ -61,28 +34,35 @@ import {
   type DisplayMessage,
 } from '@/lib/chatHistoryStorage';
 import {
-  type CharacterConfig,
   type CharacterCollection,
   DEFAULT_COLLECTION as DEFAULT_CHAR_COLLECTION,
   loadCharacterCollection,
   loadCharacterCollectionSync,
   saveCharacterCollection,
   getActiveCharacter,
-  getCharacterPromptContext,
-  resolveEmotionMedia,
-  clearEmotionVideoCache,
 } from '@/lib/characterManager';
 import {
-  ModManager,
   type ModCollection,
   DEFAULT_MOD_COLLECTION,
   loadModCollection,
   loadModCollectionSync,
   saveModCollection,
   getActiveModEntry,
+  ModManager,
 } from '@/lib/modManager';
+import { APP_REGISTRY } from '@/lib/appRegistry';
+import { logger } from '@/lib/logger';
 import CharacterPanel from './CharacterPanel';
 import ModPanel from './ModPanel';
+import { hasUsableLLMConfig } from './toolDefinitions';
+import {
+  CharacterAvatar,
+  StageIndicator,
+  ActionsTaken,
+  renderMessageContent,
+} from './ChatSubComponents';
+import SettingsModal from './SettingsModal';
+import { useConversationEngine, type ConversationDisplayMessage } from './useConversationEngine';
 import styles from './index.module.scss';
 
 // ---------------------------------------------------------------------------
@@ -92,293 +72,16 @@ import styles from './index.module.scss';
 interface CharacterDisplayMessage extends DisplayMessage {
   emotion?: string;
   suggestedReplies?: string[];
-  toolCalls?: string[]; // collapsed tool call summaries
-}
-
-function hasUsableLLMConfig(config: LLMConfig | null | undefined): config is LLMConfig {
-  return !!config?.baseUrl.trim() && !!config.model.trim();
-}
-
-// ---------------------------------------------------------------------------
-// Tool definitions for character system
-// ---------------------------------------------------------------------------
-
-function getRespondToUserToolDef() {
-  return {
-    type: 'function' as const,
-    function: {
-      name: 'respond_to_user',
-      description:
-        'Send a message to the user as the character. ALWAYS use this tool to respond — never output plain text.',
-      parameters: {
-        type: 'object' as const,
-        properties: {
-          character_expression: {
-            type: 'object',
-            properties: {
-              content: {
-                type: 'string',
-                description:
-                  'The message text (dialogue with optional action descriptions in parentheses)',
-              },
-              emotion: {
-                type: 'string',
-                description: 'Character emotion: happy, shy, peaceful, depressing, angry',
-              },
-            },
-            required: ['content'],
-          },
-          user_interaction: {
-            type: 'object',
-            properties: {
-              suggested_replies: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'List of 3 suggested user replies (under 25 chars each)',
-              },
-            },
-          },
-        },
-        required: ['character_expression'],
-      },
-    },
-  };
-}
-
-function getFinishTargetToolDef() {
-  return {
-    type: 'function' as const,
-    function: {
-      name: 'finish_target',
-      description:
-        'Mark story targets as completed when achieved through conversation. Do not announce this to the user.',
-      parameters: {
-        type: 'object' as const,
-        properties: {
-          target_ids: {
-            type: 'array',
-            items: { type: 'number' },
-            description: 'IDs of targets to mark as completed',
-          },
-        },
-        required: ['target_ids'],
-      },
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Build system prompt with Character + Mod context
-// ---------------------------------------------------------------------------
-
-function buildSystemPrompt(
-  character: CharacterConfig,
-  modManager: ModManager | null,
-  hasImageGen: boolean,
-  memories: MemoryEntry[] = [],
-): string {
-  let prompt = getCharacterPromptContext(character);
-
-  if (modManager) {
-    prompt += '\n' + modManager.buildStageReminder();
-  }
-
-  prompt += `
-You can interact with apps on the user's device using tools.
-
-When the user wants to interact with an app, first identify the target app from the user's intent, then follow ALL steps in order:
-1. list_apps — discover available apps
-2. file_read("apps/{appName}/meta.yaml") — learn the target app's available actions
-3. file_read("apps/{appName}/guide.md") — learn its data structure and JSON schema
-4. file_list/file_read — explore existing data in "apps/{appName}/data/"
-5. file_write/file_delete — create/modify/delete data following the JSON schema from step 3
-6. app_action — notify the app to reload (ONLY use actions defined in meta.yaml)
-
-Rules:
-- Always operate on the app the user specified. Do not redirect the operation to a different app or OS action.
-- Data mutations MUST go through file_write/file_delete. app_action only notifies the app to reload, it cannot write data.
-- After file_write, ALWAYS call app_action with the corresponding REFRESH action.
-- Do NOT skip step 5. If the user asked to save/create/add something, you must file_write the data. file_list alone does not save anything.
-- Do NOT skip steps 2-3. You MUST read guide.md before ANY file_write. The guide defines the ONLY valid directory structure and file schemas. Writing to paths not defined in guide.md will cause data loss — the app will not see the files.
-- NEVER invent or guess file paths. ALL file_write paths MUST exactly follow the directory structure in guide.md. For example, if guide.md defines entries under "/entries/{id}.json", you MUST write to "apps/{appName}/data/entries/{id}.json" — NOT to "apps/{appName}/data/{id}.json" or any other path.
-- NAS paths in guide.md like "/articles/xxx.json" map to "apps/{appName}/data/articles/xxx.json". This prefix rule applies to ALL paths — always preserve the full subdirectory structure from guide.md.
-
-When you receive "[User performed action in ... (appName: xxx)]", the appName is already provided. Read its meta.yaml to understand available actions, then respond accordingly. For games, respond with your own move — think strategically.
-
-IMPORTANT: You MUST use the respond_to_user tool to send all messages to the user. Do NOT output plain text responses. Include your emotion and 3 suggested replies.${hasImageGen ? '\n\nYou can use generate_image to create images from text prompts. The generated image will be displayed in chat.' : ''}`;
-
-  prompt += buildMemoryPrompt(memories);
-
-  return prompt;
+  toolCalls?: string[];
 }
 
-// ---------------------------------------------------------------------------
-// Helper: parse action text in parentheses as emotion markers
-// ---------------------------------------------------------------------------
-
-function renderMessageContent(content: string): React.ReactNode {
-  // Match (action text) patterns and render them as styled spans
-  const parts = content.split(/(\([^)]+\))/g);
-  return parts.map((part, i) => {
-    if (/^\([^)]+\)$/.test(part)) {
-      return (
-        <span key={i} className={styles.emotion}>
-          {part}
-        </span>
-      );
-    }
-    return part;
-  });
+interface PendingSaveSnapshot {
+  path: string;
+  messages: CharacterDisplayMessage[];
+  history: ChatMessage[];
+  replies: string[];
 }
 
-// ---------------------------------------------------------------------------
-// Stage Indicator Component
-// ---------------------------------------------------------------------------
-
-const StageIndicator: React.FC<{ modManager: ModManager | null }> = ({ modManager }) => {
-  if (!modManager) return null;
-
-  const total = modManager.stageCount;
-  const current = modManager.currentStageIndex;
-  const finished = modManager.isFinished;
-
-  return (
-    <div className={styles.stageIndicator}>
-      <span className={styles.stageText}>
-        Stage {finished ? total : current + 1}/{total}
-      </span>
-      <div className={styles.stageDots}>
-        {Array.from({ length: total }, (_, i) => (
-          <div
-            key={i}
-            className={`${styles.stageDot} ${
-              i < current || finished
-                ? styles.stageDotCompleted
-                : i === current
-                  ? styles.stageDotCurrent
-                  : ''
-            }`}
-          />
-        ))}
-      </div>
-    </div>
-  );
-};
-
-// ---------------------------------------------------------------------------
-// Actions Taken (collapsible)
-// ---------------------------------------------------------------------------
-
-const ActionsTaken: React.FC<{ calls: string[] }> = ({ calls }) => {
-  const [open, setOpen] = useState(false);
-  if (calls.length === 0) return null;
-
-  return (
-    <div className={styles.actionsTaken}>
-      <button className={styles.actionsTakenToggle} onClick={() => setOpen(!open)}>
-        Actions taken
-        {open ? <ChevronDown size={12} /> : <ChevronRight size={12} />}
-      </button>
-      {open && (
-        <div className={styles.actionsTakenList}>
-          {calls.map((c, i) => (
-            <div key={i}>{c}</div>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-};
-
-// ---------------------------------------------------------------------------
-// CharacterAvatar – crossfade between emotion media without flashing
-// ---------------------------------------------------------------------------
-
-interface AvatarLayer {
-  url: string;
-  type: 'video' | 'image';
-  active: boolean;
-}
-
-const CharacterAvatar: React.FC<{
-  character: CharacterConfig;
-  emotion?: string;
-  onEmotionEnd: () => void;
-}> = memo(({ character, emotion, onEmotionEnd }) => {
-  const isIdle = !emotion;
-  const media = resolveEmotionMedia(character, emotion || 'default');
-
-  const [layers, setLayers] = useState<AvatarLayer[]>(() =>
-    media ? [{ url: media.url, type: media.type, active: true }] : [],
-  );
-  const activeUrl = layers.find((l) => l.active)?.url;
-
-  useEffect(() => {
-    if (!media) {
-      setLayers([]);
-      return;
-    }
-    if (media.url === activeUrl) return;
-    setLayers((prev) => {
-      if (prev.some((l) => l.url === media.url)) return prev;
-      return [...prev, { url: media.url, type: media.type, active: false }];
-    });
-  }, [media?.url, activeUrl]);
-
-  const handleMediaReady = useCallback((readyUrl: string) => {
-    setLayers((prev) => {
-      const staleUrls = prev.filter((l) => l.url !== readyUrl).map((l) => l.url);
-      setTimeout(() => {
-        setLayers((curr) => curr.filter((l) => !staleUrls.includes(l.url)));
-      }, 300);
-      return prev.map((l) => ({ ...l, active: l.url === readyUrl }));
-    });
-  }, []);
-
-  if (layers.length === 0) {
-    return <div className={styles.avatarPlaceholder}>{character.character_name.charAt(0)}</div>;
-  }
-
-  return (
-    <>
-      {layers.map((layer) => {
-        const layerStyle: React.CSSProperties = {
-          position: 'absolute',
-          inset: 0,
-          opacity: layer.active ? 1 : 0,
-          transition: 'opacity 0.25s ease-out',
-        };
-        if (layer.type === 'video') {
-          return (
-            <video
-              key={layer.url}
-              className={styles.avatarImage}
-              style={layerStyle}
-              src={layer.url}
-              autoPlay
-              loop={layer.active ? isIdle : false}
-              muted
-              playsInline
-              onCanPlay={!layer.active ? () => handleMediaReady(layer.url) : undefined}
-              onEnded={layer.active && !isIdle ? onEmotionEnd : undefined}
-            />
-          );
-        }
-        return (
-          <img
-            key={layer.url}
-            className={styles.avatarImage}
-            style={layerStyle}
-            src={layer.url}
-            alt={character.character_name}
-            onLoad={!layer.active ? () => handleMediaReady(layer.url) : undefined}
-          />
-        );
-      })}
-    </>
-  );
-});
-
 // ---------------------------------------------------------------------------
 // ChatPanel
 // ---------------------------------------------------------------------------
@@ -389,7 +92,7 @@ const ChatPanel: React.FC<{
   zIndex?: number;
   onFocus?: () => void;
 }> = ({ onClose, visible = true, zIndex, onFocus }) => {
-  // Character + Mod state (collection-based)
+  // Character + Mod state
   const [charCollection, setCharCollection] = useState<CharacterCollection>(
     () => loadCharacterCollectionSync() ?? DEFAULT_CHAR_COLLECTION,
   );
@@ -404,11 +107,17 @@ const ChatPanel: React.FC<{
     return new ModManager(entry.config, entry.state);
   });
 
-  // Session key for chat history isolation (character × mod)
+  // Session key for chat history isolation (derived, not state)
   const sessionPath = buildSessionPath(charCollection.activeId, modCollection.activeId);
-  setSessionPath(sessionPath);
 
-  // Chat state — initialized from session-scoped cache
+  // Keep the module-level session path in sync synchronously after DOM
+  // mutations so tool execution always reads the latest path, even within the
+  // same paint cycle as a character/mod switch.
+  useLayoutEffect(() => {
+    setSessionPath(sessionPath);
+  }, [sessionPath]);
+
+  // Chat state
   const [messages, setMessages] = useState<CharacterDisplayMessage[]>(() => {
     const cache = loadChatHistorySync(sessionPath);
     return (cache?.messages ?? []) as CharacterDisplayMessage[];
@@ -424,33 +133,14 @@ const ChatPanel: React.FC<{
   const [imageGenConfig, setImageGenConfig] = useState<ImageGenConfig | null>(
     loadImageGenConfigSync,
   );
-
-  // Suggested replies from latest assistant message
   const [suggestedReplies, setSuggestedReplies] = useState<string[]>([]);
   const [showCharacterPanel, setShowCharacterPanel] = useState(false);
   const [showModPanel, setShowModPanel] = useState(false);
   const [initialEditModId, setInitialEditModId] = useState<string | undefined>();
   const [currentEmotion, setCurrentEmotion] = useState<string | undefined>();
-
-  // Open mod editor when triggered from Shell (e.g. after card import mod generation)
-  useEffect(() => {
-    const handler = (e: Event) => {
-      const modId = (e as CustomEvent<{ modId: string }>).detail?.modId;
-      if (modId) {
-        setInitialEditModId(modId);
-        setShowModPanel(true);
-      }
-    };
-    window.addEventListener('open-mod-editor', handler);
-    return () => window.removeEventListener('open-mod-editor', handler);
-  }, []);
-
-  // Memories loaded for SP injection
   const [memories, setMemories] = useState<MemoryEntry[]>([]);
 
-  // Pending tool calls for current response (grouped per assistant turn)
-  const pendingToolCallsRef = useRef<string[]>([]);
-
+  // Refs for stable access in callbacks
   const messagesEndRef = useRef<HTMLDivElement>(null);
   const messagesRef = useRef(messages);
   messagesRef.current = messages;
@@ -459,28 +149,93 @@ const ChatPanel: React.FC<{
   const suggestedRepliesRef = useRef(suggestedReplies);
   suggestedRepliesRef.current = suggestedReplies;
 
-  // Debounced save
-  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
+  const configRef = useRef(config);
+  configRef.current = config;
+  const imageGenConfigRef = useRef(imageGenConfig);
+  imageGenConfigRef.current = imageGenConfig;
+  const modManagerRef = useRef(modManager);
+  modManagerRef.current = modManager;
+  const characterRef = useRef(character);
+  characterRef.current = character;
+  const memoriesRef = useRef(memories);
+  memoriesRef.current = memories;
   const sessionPathRef = useRef(sessionPath);
   sessionPathRef.current = sessionPath;
 
+  // Conversation engine
+  const { runConversation } = useConversationEngine({
+    imageGenConfigRef,
+    modManagerRef,
+    characterRef,
+    memoriesRef,
+    sessionPathRef,
+    callbacks: {
+      addMessage: useCallback((msg: ConversationDisplayMessage) => {
+        setMessages((prev) => [...prev, msg]);
+      }, []),
+      setChatHistory,
+      setSuggestedReplies,
+      setCurrentEmotion,
+      setModCollection,
+      setModManager,
+      setMemories,
+    },
+  });
+
+  // Debounced save — tracks the most recent snapshot to be persisted.
+  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pendingSaveRef = useRef<PendingSaveSnapshot | null>(null);
+
+  // Reschedule the debounce timer on every data change.  Never flush
+  // synchronously here — flushing is handled by the session-switch effect below
+  // so that rapid updates (e.g. streaming tokens) are genuinely batched.
   useEffect(() => {
-    if (messages.length === 0 && chatHistory.length === 0) return;
+    if (messages.length === 0 && chatHistory.length === 0) {
+      pendingSaveRef.current = null;
+      return;
+    }
+    pendingSaveRef.current = {
+      path: sessionPath,
+      messages,
+      history: chatHistory,
+      replies: suggestedReplies,
+    };
     if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
     saveTimerRef.current = setTimeout(() => {
-      saveChatHistory(
-        sessionPathRef.current,
-        messagesRef.current,
-        chatHistoryRef.current,
-        suggestedRepliesRef.current,
-      );
+      if (pendingSaveRef.current) {
+        const { path, messages: m, history: h, replies: r } = pendingSaveRef.current;
+        saveChatHistory(path, m, h, r);
+        pendingSaveRef.current = null;
+      }
+      saveTimerRef.current = null;
     }, 500);
     return () => {
-      if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+      // Cancel the timer so the next render's effect can reschedule it.
+      // Do NOT flush here — that would fire a POST on every state update,
+      // defeating the debounce.
+      if (saveTimerRef.current) {
+        clearTimeout(saveTimerRef.current);
+        saveTimerRef.current = null;
+      }
     };
   }, [messages, chatHistory, suggestedReplies]);
 
+  // Flush any pending save when the session path changes (character/mod switch)
+  // or when the component unmounts, so no data is silently lost.
+  useEffect(() => {
+    return () => {
+      if (saveTimerRef.current) {
+        clearTimeout(saveTimerRef.current);
+        saveTimerRef.current = null;
+      }
+      if (pendingSaveRef.current) {
+        const { path, messages: m, history: h, replies: r } = pendingSaveRef.current;
+        saveChatHistory(path, m, h, r);
+        pendingSaveRef.current = null;
+      }
+    };
+  }, [sessionPath]);
+
   /** Seed prologue and opening replies from active mod */
   const seedPrologue = useCallback(() => {
     const entry = getActiveModEntry(modCollection);
@@ -502,18 +257,19 @@ const ChatPanel: React.FC<{
     setCurrentEmotion(undefined);
   }, [modCollection]);
 
-  // Reload chat history when session (character × mod) changes
+  // Reload chat history when session changes
   useEffect(() => {
-    loadChatHistory(sessionPath).then((data) => {
+    let cancelled = false;
+    const load = async () => {
+      const data = await loadChatHistory(sessionPath);
+      if (cancelled) return;
       const loadedMessages = (data?.messages ?? []) as CharacterDisplayMessage[];
       const loadedHistory = data?.chatHistory ?? [];
       if (loadedMessages.length === 0 && loadedHistory.length === 0) {
-        // No history — seed prologue
         seedPrologue();
       } else {
         setMessages(loadedMessages);
         setChatHistory(loadedHistory);
-        // Restore suggested replies from saved data, or from mod config if only prologue
         if (data?.suggestedReplies?.length) {
           setSuggestedReplies(data.suggestedReplies);
         } else {
@@ -530,15 +286,25 @@ const ChatPanel: React.FC<{
         }
         setCurrentEmotion(undefined);
       }
-    });
-    // Load memories for SP injection
-    loadMemories(sessionPath).then(setMemories);
-  }, [sessionPath, modCollection, seedPrologue]);
+      if (cancelled) return;
+      loadMemories(sessionPath)
+        .then((mems) => {
+          if (!cancelled) setMemories(mems);
+        })
+        .catch(() => {
+          if (!cancelled) setMemories([]);
+        });
+    };
+    load();
+    return () => {
+      cancelled = true;
+    };
+    // sessionPath is derived from charCollection.activeId + modCollection.activeId,
+    // so it already captures session changes. seedPrologue reads modCollection via
+    // closure but we only want to trigger on session identity change.
+  }, [sessionPath]);
 
-  // Load configs from file (async override).
-  // Empty deps [] is intentional: configs (character collection, mod collection,
-  // chat config, image-gen config) are loaded inside the effect and written to
-  // state — they are not external dependencies that should trigger re-runs.
+  // Load configs from file (async override)
   useEffect(() => {
     loadConfig().then((fileConfig) => {
       if (fileConfig) setConfig(fileConfig);
@@ -558,7 +324,7 @@ const ChatPanel: React.FC<{
     });
   }, []);
 
-  // Listen for mod collection changes from Shell (e.g. after mod generation)
+  // Listen for mod collection changes from Shell
   useEffect(() => {
     const handler = (e: Event) => {
       const col = (e as CustomEvent<ModCollection>).detail;
@@ -572,32 +338,39 @@ const ChatPanel: React.FC<{
     return () => window.removeEventListener('mod-collection-changed', handler);
   }, []);
 
+  // Open mod editor when triggered from Shell
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const modId = (e as CustomEvent<{ modId: string }>).detail?.modId;
+      if (modId) {
+        setInitialEditModId(modId);
+        setShowModPanel(true);
+      }
+    };
+    window.addEventListener('open-mod-editor', handler);
+    return () => window.removeEventListener('open-mod-editor', handler);
+  }, []);
+
   const handleClearHistory = useCallback(async () => {
     await clearChatHistory(sessionPathRef.current);
     seedPrologue();
   }, [seedPrologue]);
 
-  /** Reset entire session — clears chat, memories, app data, and mod state */
   const handleResetSession = useCallback(async () => {
     const sp = sessionPathRef.current;
-    // Clear server-side session directory
     try {
       await fetch(`/api/session-reset?path=${encodeURIComponent(sp)}`, { method: 'DELETE' });
     } catch {
       // ignore
     }
-    // Clear local state
     localStorage.removeItem(`openroom_chat_${sp.replace(/\//g, '_')}`);
     setMessages([]);
     setChatHistory([]);
     setSuggestedReplies([]);
     setMemories([]);
     setCurrentEmotion(undefined);
-
-    // Close all open app windows
     closeAllWindows();
 
-    // Reset mod state
     if (modManagerRef.current) {
       modManagerRef.current.reset();
       const mm = modManagerRef.current;
@@ -616,12 +389,9 @@ const ChatPanel: React.FC<{
       });
     }
 
-    // Re-seed prologue and opening replies
     seedPrologue();
-
-    // Re-seed meta files
     await seedMetaFiles();
-  }, [modCollection, seedPrologue]);
+  }, [seedPrologue]);
 
   useEffect(() => {
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
@@ -631,17 +401,6 @@ const ChatPanel: React.FC<{
     setMessages((prev) => [...prev, msg]);
   }, []);
 
-  const configRef = useRef(config);
-  configRef.current = config;
-  const imageGenConfigRef = useRef(imageGenConfig);
-  imageGenConfigRef.current = imageGenConfig;
-  const modManagerRef = useRef(modManager);
-  modManagerRef.current = modManager;
-  const characterRef = useRef(character);
-  characterRef.current = character;
-  const memoriesRef = useRef(memories);
-  memoriesRef.current = memories;
-
   // User action queue
   const actionQueueRef = useRef<string[]>([]);
   const processingRef = useRef(false);
@@ -670,7 +429,7 @@ const ChatPanel: React.FC<{
       }
     }
     processingRef.current = false;
-  }, []);
+  }, [runConversation]);
 
   // Listen for user actions from apps
   useEffect(() => {
@@ -740,295 +499,9 @@ const ChatPanel: React.FC<{
         setLoading(false);
       }
     },
-    [input, loading, config, chatHistory, addMessage],
+    [input, loading, config, chatHistory, addMessage, runConversation],
   );
 
-  // Core conversation loop
-  const runConversation = async (history: ChatMessage[], cfg: LLMConfig) => {
-    await seedMetaFiles();
-    await loadActionsFromMeta();
-    const hasImageGen = !!imageGenConfigRef.current?.apiKey;
-    const mm = modManagerRef.current;
-    const char = characterRef.current;
-
-    const tools = [
-      getRespondToUserToolDef(),
-      getFinishTargetToolDef(),
-      getListAppsToolDefinition(),
-      getAppActionToolDefinition(),
-      ...getFileToolDefinitions(),
-      ...getMemoryToolDefinitions(),
-      ...(hasImageGen ? getImageGenToolDefinitions() : []),
-    ];
-
-    const currentMemories = memoriesRef.current;
-    const fullMessages: ChatMessage[] = [
-      { role: 'system', content: buildSystemPrompt(char, mm, hasImageGen, currentMemories) },
-      ...history,
-    ];
-
-    let currentMessages = fullMessages;
-    let iterations = 0;
-    const maxIterations = 10;
-    pendingToolCallsRef.current = [];
-
-    while (iterations < maxIterations) {
-      iterations++;
-      const response = await chat(currentMessages, tools, cfg);
-
-      if (response.toolCalls.length === 0) {
-        // No tool calls — fallback plain text (shouldn't happen with respond_to_user requirement)
-        if (response.content) {
-          addMessage({
-            id: String(Date.now()),
-            role: 'assistant',
-            content: response.content,
-            toolCalls:
-              pendingToolCallsRef.current.length > 0 ? [...pendingToolCallsRef.current] : undefined,
-          });
-          setChatHistory((prev) => [...prev, { role: 'assistant', content: response.content }]);
-          pendingToolCallsRef.current = [];
-        }
-        break;
-      }
-
-      // Has tool calls
-      const assistantMsg: ChatMessage = {
-        role: 'assistant',
-        content: response.content,
-        tool_calls: response.toolCalls,
-      };
-      currentMessages = [...currentMessages, assistantMsg];
-
-      // Execute each tool call
-      for (const tc of response.toolCalls) {
-        let params: Record<string, unknown> = {};
-        try {
-          params = JSON.parse(tc.function.arguments);
-        } catch {
-          // ignore
-        }
-
-        // ---- respond_to_user ----
-        if (tc.function.name === 'respond_to_user') {
-          const expr =
-            (params.character_expression as { content?: string; emotion?: string }) ?? {};
-          const interaction = (params.user_interaction as { suggested_replies?: string[] }) ?? {};
-
-          const content = expr.content ?? '';
-          const emotion = expr.emotion;
-          const replies = interaction.suggested_replies ?? [];
-
-          addMessage({
-            id: String(Date.now()),
-            role: 'assistant',
-            content,
-            emotion,
-            suggestedReplies: replies,
-            toolCalls:
-              pendingToolCallsRef.current.length > 0 ? [...pendingToolCallsRef.current] : undefined,
-          });
-          setSuggestedReplies(replies);
-          if (emotion) {
-            clearEmotionVideoCache(character.id);
-            setCurrentEmotion(emotion);
-          }
-          pendingToolCallsRef.current = [];
-
-          setChatHistory((prev) => [...prev, { role: 'assistant', content }]);
-          currentMessages = [
-            ...currentMessages,
-            { role: 'tool', content: 'Message delivered.', tool_call_id: tc.id },
-          ];
-          continue;
-        }
-
-        // ---- finish_target ----
-        if (tc.function.name === 'finish_target') {
-          const targetIds = (params.target_ids as number[]) ?? [];
-          if (mm) {
-            const result = mm.finishTarget(targetIds);
-            // Persist state via collection
-            const updatedEntry = { config: mm.getConfig(), state: mm.getState() };
-            setModCollection((prev) => {
-              const updated = {
-                ...prev,
-                items: { ...prev.items, [updatedEntry.config.id]: updatedEntry },
-              };
-              saveModCollection(updated);
-              return updated;
-            });
-            setModManager(new ModManager(mm.getConfig(), mm.getState()));
-
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: JSON.stringify(result), tool_call_id: tc.id },
-            ];
-          } else {
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: 'No mod loaded.', tool_call_id: tc.id },
-            ];
-          }
-          continue;
-        }
-
-        // ---- list_apps ----
-        if (tc.function.name === 'list_apps') {
-          const result = executeListApps();
-          pendingToolCallsRef.current.push(`list_apps`);
-          currentMessages = [
-            ...currentMessages,
-            { role: 'tool', content: result, tool_call_id: tc.id },
-          ];
-          continue;
-        }
-
-        // ---- File tools ----
-        if (isFileTool(tc.function.name)) {
-          pendingToolCallsRef.current.push(
-            `${tc.function.name}(${JSON.stringify(params).slice(0, 60)})`,
-          );
-          try {
-            const result = await executeFileTool(
-              tc.function.name,
-              params as Record<string, string>,
-            );
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // ---- Image gen ----
-        if (isImageGenTool(tc.function.name)) {
-          pendingToolCallsRef.current.push('generate_image');
-          try {
-            const { result, dataUrl } = await executeImageGenTool(
-              params as Record<string, string>,
-              imageGenConfigRef.current,
-            );
-            if (dataUrl) {
-              addMessage({
-                id: String(Date.now()) + '-img',
-                role: 'assistant',
-                content: '',
-                imageUrl: dataUrl,
-              });
-            }
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // ---- Memory tools ----
-        if (isMemoryTool(tc.function.name)) {
-          pendingToolCallsRef.current.push(`save_memory`);
-          try {
-            const result = await executeMemoryTool(
-              sessionPathRef.current,
-              params as Record<string, string>,
-            );
-            // Refresh memories for next turn's SP
-            loadMemories(sessionPathRef.current).then(setMemories);
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // ---- app_action ----
-        if (tc.function.name === 'app_action') {
-          const strParams = params as Record<string, string>;
-          const resolved = resolveAppAction(strParams.app_name, strParams.action_type);
-          if (typeof resolved === 'string') {
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: resolved, tool_call_id: tc.id },
-            ];
-            continue;
-          }
-
-          pendingToolCallsRef.current.push(`${strParams.app_name}/${strParams.action_type}`);
-
-          let actionParams: Record<string, string> = {};
-          if (strParams.params) {
-            try {
-              actionParams = JSON.parse(strParams.params);
-            } catch {
-              // empty
-            }
-          }
-
-          try {
-            const result = await dispatchAgentAction({
-              app_id: resolved.appId,
-              action_type: resolved.actionType,
-              params: actionParams,
-            });
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // Unknown tool
-        currentMessages = [
-          ...currentMessages,
-          { role: 'tool', content: 'error: unknown tool', tool_call_id: tc.id },
-        ];
-      }
-
-      // Update chat history
-      setChatHistory(currentMessages.slice(1));
-    }
-  };
-
   const handleKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
@@ -1064,7 +537,6 @@ const ChatPanel: React.FC<{
               style={{ cursor: 'pointer' }}
             >
               <span className={styles.characterName}>{character.character_name}</span>
-              <ChevronRight size={14} style={{ color: 'rgba(255,255,255,0.4)' }} />
             </div>
             <div className={styles.headerActions}>
               <div onClick={() => setShowModPanel(true)} style={{ cursor: 'pointer' }}>
@@ -1220,253 +692,4 @@ const ChatPanel: React.FC<{
   );
 };
 
-// ---------------------------------------------------------------------------
-// Settings Modal (extended with Character + Mod)
-// ---------------------------------------------------------------------------
-
-const SettingsModal: React.FC<{
-  config: LLMConfig | null;
-  imageGenConfig: ImageGenConfig | null;
-  onSave: (_config: LLMConfig, _igConfig: ImageGenConfig | null) => void;
-  onClose: () => void;
-}> = ({ config, imageGenConfig, onSave, onClose }) => {
-  // LLM settings
-  const [provider, setProvider] = useState<LLMProvider>(config?.provider || 'minimax');
-  const [apiKey, setApiKey] = useState(config?.apiKey || '');
-  const [baseUrl, setBaseUrl] = useState(
-    config?.baseUrl || getDefaultProviderConfig('minimax').baseUrl,
-  );
-  const [model, setModel] = useState(config?.model || getDefaultProviderConfig('minimax').model);
-  const [customHeaders, setCustomHeaders] = useState(config?.customHeaders || '');
-  const [manualModelMode, setManualModelMode] = useState(false);
-
-  const isPresetModel = PROVIDER_MODELS[provider]?.includes(model) ?? false;
-  const showDropdown = !manualModelMode && isPresetModel;
-
-  // Image gen settings
-  const [igProvider, setIgProvider] = useState<ImageGenProvider>(
-    imageGenConfig?.provider || 'gemini',
-  );
-  const [igApiKey, setIgApiKey] = useState(imageGenConfig?.apiKey || '');
-  const [igBaseUrl, setIgBaseUrl] = useState(
-    imageGenConfig?.baseUrl || getDefaultImageGenConfig('gemini').baseUrl,
-  );
-  const [igModel, setIgModel] = useState(
-    imageGenConfig?.model || getDefaultImageGenConfig('gemini').model,
-  );
-  const [igCustomHeaders, setIgCustomHeaders] = useState(imageGenConfig?.customHeaders || '');
-
-  const handleProviderChange = (p: LLMProvider) => {
-    setProvider(p);
-    const defaults = getDefaultProviderConfig(p);
-    setBaseUrl(defaults.baseUrl);
-    setModel(defaults.model);
-    setManualModelMode(false);
-  };
-
-  const handleModelChange = (newModel: string) => {
-    setModel(newModel);
-    setManualModelMode(false);
-  };
-
-  const handleIgProviderChange = (p: ImageGenProvider) => {
-    setIgProvider(p);
-    const defaults = getDefaultImageGenConfig(p);
-    setIgBaseUrl(defaults.baseUrl);
-    setIgModel(defaults.model);
-  };
-
-  return (
-    <div className={styles.overlay} data-testid="settings-overlay">
-      <div className={styles.settingsModal} data-testid="settings-modal">
-        <div className={styles.settingsTitle}>LLM Settings</div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Provider</label>
-          <select
-            className={styles.select}
-            value={provider}
-            onChange={(e) => handleProviderChange(e.target.value as LLMProvider)}
-          >
-            <option value="openai">OpenAI</option>
-            <option value="anthropic">Anthropic</option>
-            <option value="deepseek">DeepSeek</option>
-            <option value="llama.cpp">llama.cpp</option>
-            <option value="minimax">MiniMax</option>
-            <option value="z.ai">Z.ai</option>
-            <option value="kimi">Kimi</option>
-            <option value="openrouter">OpenRouter</option>
-          </select>
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>API Key</label>
-          <input
-            className={styles.fieldInput}
-            type="password"
-            value={apiKey}
-            onChange={(e) => setApiKey(e.target.value)}
-            placeholder="Optional for local servers"
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Base URL</label>
-          <input
-            className={styles.fieldInput}
-            value={baseUrl}
-            onChange={(e) => setBaseUrl(e.target.value)}
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Model</label>
-          <div className={styles.modelSelectorWrapper}>
-            {showDropdown ? (
-              <>
-                <select
-                  className={styles.select}
-                  value={model}
-                  onChange={(e) => handleModelChange(e.target.value)}
-                >
-                  {PROVIDER_MODELS[provider]?.map((m) => (
-                    <option key={m} value={m}>
-                      {m}
-                    </option>
-                  ))}
-                </select>
-                <button
-                  type="button"
-                  onClick={() => setManualModelMode(true)}
-                  className={styles.manualToggleBtn}
-                  title="Enter custom model name"
-                >
-                  <Pencil size={14} />
-                </button>
-              </>
-            ) : (
-              <>
-                <input
-                  className={styles.fieldInput}
-                  value={model}
-                  onChange={(e) => setModel(e.target.value)}
-                  placeholder="e.g. gpt-4-turbo"
-                />
-                {isPresetModel && (
-                  <button
-                    type="button"
-                    onClick={() => setManualModelMode(false)}
-                    className={styles.manualToggleBtn}
-                    title="Back to model list"
-                  >
-                    <List size={14} />
-                  </button>
-                )}
-              </>
-            )}
-          </div>
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Custom Headers (one per line, Key: Value)</label>
-          <textarea
-            className={styles.fieldInput}
-            value={customHeaders}
-            onChange={(e) => setCustomHeaders(e.target.value)}
-            placeholder={'X-Custom-Header: value\nAnother-Header: value'}
-            rows={3}
-            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
-          />
-        </div>
-
-        <div className={styles.settingsDivider} />
-        <div className={styles.settingsTitle}>Image Generation</div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Provider</label>
-          <select
-            className={styles.select}
-            value={igProvider}
-            onChange={(e) => handleIgProviderChange(e.target.value as ImageGenProvider)}
-          >
-            <option value="openai">OpenAI</option>
-            <option value="gemini">Gemini</option>
-          </select>
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>API Key</label>
-          <input
-            className={styles.fieldInput}
-            type="password"
-            value={igApiKey}
-            onChange={(e) => setIgApiKey(e.target.value)}
-            placeholder="API Key..."
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Base URL</label>
-          <input
-            className={styles.fieldInput}
-            value={igBaseUrl}
-            onChange={(e) => setIgBaseUrl(e.target.value)}
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Model</label>
-          <input
-            className={styles.fieldInput}
-            value={igModel}
-            onChange={(e) => setIgModel(e.target.value)}
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Custom Headers</label>
-          <textarea
-            className={styles.fieldInput}
-            value={igCustomHeaders}
-            onChange={(e) => setIgCustomHeaders(e.target.value)}
-            placeholder={'X-Custom-Header: value'}
-            rows={2}
-            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
-          />
-        </div>
-
-        <div className={styles.settingsActions}>
-          <button className={styles.cancelBtn} onClick={onClose}>
-            Cancel
-          </button>
-          <button
-            className={styles.saveBtn}
-            onClick={() => {
-              const llmCfg: LLMConfig = {
-                provider,
-                apiKey,
-                baseUrl,
-                model,
-                ...(customHeaders.trim() ? { customHeaders } : {}),
-              };
-              const igCfg: ImageGenConfig | null = igApiKey.trim()
-                ? {
-                    provider: igProvider,
-                    apiKey: igApiKey,
-                    baseUrl: igBaseUrl,
-                    model: igModel,
-                    ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
-                  }
-                : null;
-              onSave(llmCfg, igCfg);
-            }}
-          >
-            Save
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-};
-
 export default ChatPanel;
diff --git a/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts b/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
new file mode 100644
index 0000000..3bf0367
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
@@ -0,0 +1,136 @@
+/**
+ * Tool Definitions & System Prompt for ChatPanel
+ *
+ * Pure functions with no React dependency — easily testable in isolation.
+ */
+
+import type { CharacterConfig } from '@/lib/characterManager';
+import { getCharacterPromptContext } from '@/lib/characterManager';
+import type { ModManager } from '@/lib/modManager';
+import type { MemoryEntry } from '@/lib/memoryManager';
+import { buildMemoryPrompt } from '@/lib/memoryManager';
+import type { LLMConfig } from '@/lib/llmModels';
+
+// ---------------------------------------------------------------------------
+// Config guard
+// ---------------------------------------------------------------------------
+
+export function hasUsableLLMConfig(config: LLMConfig | null | undefined): config is LLMConfig {
+  const baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl.trim() : '';
+  const model = typeof config?.model === 'string' ? config.model.trim() : '';
+  return !!baseUrl && !!model;
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions for character system
+// ---------------------------------------------------------------------------
+
+export function getRespondToUserToolDef() {
+  return {
+    type: 'function' as const,
+    function: {
+      name: 'respond_to_user',
+      description:
+        'Send a message to the user as the character. ALWAYS use this tool to respond — never output plain text.',
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          character_expression: {
+            type: 'object',
+            properties: {
+              content: {
+                type: 'string',
+                description:
+                  'The message text (dialogue with optional action descriptions in parentheses)',
+              },
+              emotion: {
+                type: 'string',
+                description:
+                  "Character emotion — use one of the active character's defined emotion keys",
+              },
+            },
+            required: ['content'],
+          },
+          user_interaction: {
+            type: 'object',
+            properties: {
+              suggested_replies: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of 3 suggested user replies (under 25 chars each)',
+              },
+            },
+          },
+        },
+        required: ['character_expression'],
+      },
+    },
+  };
+}
+
+export function getFinishTargetToolDef() {
+  return {
+    type: 'function' as const,
+    function: {
+      name: 'finish_target',
+      description:
+        'Mark story targets as completed when achieved through conversation. Do not announce this to the user.',
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          target_ids: {
+            type: 'array',
+            items: { type: 'number' },
+            description: 'IDs of targets to mark as completed',
+          },
+        },
+        required: ['target_ids'],
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// System prompt builder
+// ---------------------------------------------------------------------------
+
+export function buildSystemPrompt(
+  character: CharacterConfig,
+  modManager: ModManager | null,
+  hasImageGen: boolean,
+  memories: MemoryEntry[] = [],
+): string {
+  let prompt = getCharacterPromptContext(character);
+
+  if (modManager) {
+    prompt += '\n' + modManager.buildStageReminder();
+  }
+
+  prompt += `
+You can interact with apps on the user's device using tools.
+
+When the user wants to interact with an app, first identify the target app from the user's intent, then follow ALL steps in order:
+1. list_apps — discover available apps
+2. file_read("apps/{appName}/meta.yaml") — learn the target app's available actions
+3. file_read("apps/{appName}/guide.md") — learn its data structure and JSON schema
+4. file_list/file_read — explore existing data in "apps/{appName}/data/"
+5. file_write/file_delete — create/modify/delete data following the JSON schema from step 3
+6. app_action — notify the app to reload (ONLY use actions defined in meta.yaml)
+
+Rules:
+- Always operate on the app the user specified. Do not redirect the operation to a different app or OS action.
+- Data mutations MUST go through file_write/file_delete. app_action only notifies the app to reload, it cannot write data.
+- After file_write, ALWAYS call app_action with the corresponding REFRESH action.
+- Do NOT skip step 5. If the user asked to save/create/add something, you must file_write the data. file_list alone does not save anything.
+- Do NOT skip steps 2-3. You MUST read guide.md before ANY file_write. The guide defines the ONLY valid directory structure and file schemas. Writing to paths not defined in guide.md will cause data loss — the app will not see the files.
+- NEVER invent or guess file paths. ALL file_write paths MUST exactly follow the directory structure in guide.md. For example, if guide.md defines entries under "/entries/{id}.json", you MUST write to "apps/{appName}/data/entries/{id}.json" — NOT to "apps/{appName}/data/{id}.json" or any other path.
+- NAS paths in guide.md like "/articles/xxx.json" map to "apps/{appName}/data/articles/xxx.json". This prefix rule applies to ALL paths — always preserve the full subdirectory structure from guide.md.
+
+When you receive "[User performed action in ... (appName: xxx)]", the appName is already provided. Read its meta.yaml to understand available actions, then respond accordingly. For games, respond with your own move — think strategically.
+
+IMPORTANT: You MUST use the respond_to_user tool to send all messages to the user. Do NOT output plain text responses. Include your emotion and 3 suggested replies.${hasImageGen ? '\n\nYou can use generate_image to create images from text prompts. The generated image will be displayed in chat.' : ''}`;
+
+  prompt += buildMemoryPrompt(memories);
+
+  return prompt;
+}
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
new file mode 100644
index 0000000..3faf20e
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
@@ -0,0 +1,373 @@
+/**
+ * useConversationEngine — extracted conversation loop from ChatPanel
+ *
+ * Encapsulates the LLM tool-call loop and dispatch logic.
+ * All side effects (state updates) are expressed as callbacks, keeping
+ * the engine itself pure and testable.
+ */
+
+import {
+  useCallback,
+  useRef,
+  type Dispatch,
+  type SetStateAction,
+  type MutableRefObject,
+} from 'react';
+import { chat, type ChatMessage, type ToolCall } from '@/lib/llmClient';
+import type { LLMConfig } from '@/lib/llmModels';
+import type { ImageGenConfig } from '@/lib/imageGenClient';
+import type { CharacterConfig } from '@/lib/characterManager';
+import { clearEmotionVideoCache } from '@/lib/characterManager';
+import type { MemoryEntry } from '@/lib/memoryManager';
+import { loadMemories } from '@/lib/memoryManager';
+import {
+  getAppActionToolDefinition,
+  resolveAppAction,
+  getListAppsToolDefinition,
+  executeListApps,
+  loadActionsFromMeta,
+} from '@/lib/appRegistry';
+import { getFileToolDefinitions, isFileTool, executeFileTool } from '@/lib/fileTools';
+import { seedMetaFiles } from '@/lib/seedMeta';
+import { dispatchAgentAction } from '@/lib/vibeContainerMock';
+import {
+  getImageGenToolDefinitions,
+  isImageGenTool,
+  executeImageGenTool,
+} from '@/lib/imageGenTools';
+import { getMemoryToolDefinitions, isMemoryTool, executeMemoryTool } from '@/lib/memoryManager';
+import { ModManager, saveModCollection } from '@/lib/modManager';
+import {
+  getRespondToUserToolDef,
+  getFinishTargetToolDef,
+  buildSystemPrompt,
+} from './toolDefinitions';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ConversationCallbacks {
+  addMessage: (msg: ConversationDisplayMessage) => void;
+  setChatHistory: Dispatch<SetStateAction<ChatMessage[]>>;
+  setSuggestedReplies: Dispatch<SetStateAction<string[]>>;
+  setCurrentEmotion: Dispatch<SetStateAction<string | undefined>>;
+  setModCollection: Dispatch<SetStateAction<import('@/lib/modManager').ModCollection>>;
+  setModManager: Dispatch<SetStateAction<ModManager | null>>;
+  setMemories: Dispatch<SetStateAction<MemoryEntry[]>>;
+}
+
+export interface ConversationDisplayMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  emotion?: string;
+  suggestedReplies?: string[];
+  toolCalls?: string[];
+  imageUrl?: string;
+}
+
+export interface ConversationEngineDeps {
+  /** Refs to current values (avoids stale closures) */
+  imageGenConfigRef: MutableRefObject<ImageGenConfig | null>;
+  modManagerRef: MutableRefObject<ModManager | null>;
+  characterRef: MutableRefObject<CharacterConfig>;
+  memoriesRef: MutableRefObject<MemoryEntry[]>;
+  sessionPathRef: MutableRefObject<string>;
+
+  /** Side-effect callbacks */
+  callbacks: ConversationCallbacks;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function useConversationEngine(deps: ConversationEngineDeps) {
+  const { imageGenConfigRef, modManagerRef, characterRef, memoriesRef, sessionPathRef } = deps;
+
+  // Keep callbacks in a ref so the stabilized runConversation always reads the
+  // latest versions without needing them in its dependency array.
+  const callbacksRef = useRef(deps.callbacks);
+  callbacksRef.current = deps.callbacks;
+
+  const pendingToolCallsRef = useRef<string[]>([]);
+
+  /**
+   * Core conversation loop — sends messages to LLM, executes tool calls,
+   * and loops until the model responds via respond_to_user or produces plain text.
+   *
+   * Stabilized with useCallback — all inputs are refs, so this identity never
+   * changes, preventing unsubscribe/subscribe churn in the onUserAction listener.
+   */
+  const runConversation = useCallback(async (history: ChatMessage[], cfg: LLMConfig) => {
+    await seedMetaFiles();
+    await loadActionsFromMeta();
+    const hasImageGen = !!imageGenConfigRef.current?.apiKey;
+    const mm = modManagerRef.current;
+    const char = characterRef.current;
+
+    const tools = [
+      getRespondToUserToolDef(),
+      getFinishTargetToolDef(),
+      getListAppsToolDefinition(),
+      getAppActionToolDefinition(),
+      ...getFileToolDefinitions(),
+      ...getMemoryToolDefinitions(),
+      ...(hasImageGen ? getImageGenToolDefinitions() : []),
+    ];
+
+    const currentMemories = memoriesRef.current;
+    const fullMessages: ChatMessage[] = [
+      { role: 'system', content: buildSystemPrompt(char, mm, hasImageGen, currentMemories) },
+      ...history,
+    ];
+
+    let currentMessages = fullMessages;
+    let iterations = 0;
+    const maxIterations = 10;
+    pendingToolCallsRef.current = [];
+
+    while (iterations < maxIterations) {
+      iterations++;
+      const response = await chat(currentMessages, tools, cfg);
+
+      if (response.toolCalls.length === 0) {
+        // No tool calls — fallback plain text
+        if (response.content) {
+          callbacksRef.current.addMessage({
+            id: String(Date.now()),
+            role: 'assistant',
+            content: response.content,
+            toolCalls:
+              pendingToolCallsRef.current.length > 0 ? [...pendingToolCallsRef.current] : undefined,
+          });
+          callbacksRef.current.setChatHistory((prev) => [
+            ...prev,
+            { role: 'assistant', content: response.content },
+          ]);
+          pendingToolCallsRef.current = [];
+        }
+        break;
+      }
+
+      // Has tool calls — build assistant message
+      const assistantMsg: ChatMessage = {
+        role: 'assistant',
+        content: response.content,
+        tool_calls: response.toolCalls,
+      };
+      currentMessages = [...currentMessages, assistantMsg];
+
+      // Execute each tool call
+      const hasRespondToUser = response.toolCalls.some(
+        (tc) => tc.function.name === 'respond_to_user',
+      );
+      for (const tc of response.toolCalls) {
+        const result = await executeToolCall(tc, {
+          mm,
+          hasImageGen,
+          pendingToolCallsRef,
+          sessionPathRef,
+          imageGenConfigRef,
+          characterRef,
+          callbacks: callbacksRef.current,
+        });
+        currentMessages = [...currentMessages, result];
+      }
+
+      // Update chat history (skip system message)
+      callbacksRef.current.setChatHistory(currentMessages.slice(1));
+
+      // Only break when respond_to_user was the sole tool call — if other
+      // tools ran in the same batch the model may still need a follow-up
+      // round-trip (e.g. finish_target) to commit state updates.
+      if (hasRespondToUser && response.toolCalls.length === 1) break;
+    }
+  }, []);
+
+  return { runConversation, pendingToolCallsRef };
+}
+
+// ---------------------------------------------------------------------------
+// Tool dispatch — each branch returns a tool-result ChatMessage
+// ---------------------------------------------------------------------------
+
+async function executeToolCall(
+  tc: ToolCall,
+  ctx: {
+    mm: ModManager | null;
+    hasImageGen: boolean;
+    pendingToolCallsRef: MutableRefObject<string[]>;
+    sessionPathRef: MutableRefObject<string>;
+    imageGenConfigRef: MutableRefObject<ImageGenConfig | null>;
+    characterRef: MutableRefObject<CharacterConfig>;
+    callbacks: ConversationCallbacks;
+  },
+): Promise<ChatMessage> {
+  let params: Record<string, unknown> = {};
+  try {
+    params = JSON.parse(tc.function.arguments);
+  } catch (e) {
+    console.warn('Failed to parse tool call arguments for tool:', tc.function.name, e);
+  }
+
+  const toolResult = (content: string): ChatMessage => ({
+    role: 'tool',
+    content,
+    tool_call_id: tc.id,
+  });
+
+  // ---- respond_to_user ----
+  if (tc.function.name === 'respond_to_user') {
+    const expr = (params.character_expression as { content?: string; emotion?: string }) ?? {};
+    const interaction = (params.user_interaction as { suggested_replies?: string[] }) ?? {};
+
+    const content = expr.content ?? '';
+    const emotion = expr.emotion;
+    const replies = interaction.suggested_replies ?? [];
+
+    ctx.callbacks.addMessage({
+      id: String(Date.now()),
+      role: 'assistant',
+      content,
+      emotion,
+      suggestedReplies: replies,
+      toolCalls:
+        ctx.pendingToolCallsRef.current.length > 0
+          ? [...ctx.pendingToolCallsRef.current]
+          : undefined,
+    });
+    ctx.callbacks.setSuggestedReplies(replies);
+    if (emotion) {
+      clearEmotionVideoCache(ctx.characterRef.current.id);
+      ctx.callbacks.setCurrentEmotion(emotion);
+    }
+    ctx.pendingToolCallsRef.current = [];
+    ctx.callbacks.setChatHistory((prev) => [...prev, { role: 'assistant', content }]);
+    return toolResult('Message delivered.');
+  }
+
+  // ---- finish_target ----
+  if (tc.function.name === 'finish_target') {
+    const targetIds = (params.target_ids as number[]) ?? [];
+    if (ctx.mm) {
+      const result = ctx.mm.finishTarget(targetIds);
+      const updatedEntry = { config: ctx.mm.getConfig(), state: ctx.mm.getState() };
+      ctx.callbacks.setModCollection((prev) => {
+        const updated = {
+          ...prev,
+          items: { ...prev.items, [updatedEntry.config.id]: updatedEntry },
+        };
+        saveModCollection(updated);
+        return updated;
+      });
+      ctx.callbacks.setModManager(new ModManager(ctx.mm.getConfig(), ctx.mm.getState()));
+      return toolResult(JSON.stringify(result));
+    }
+    return toolResult('No mod loaded.');
+  }
+
+  // ---- list_apps ----
+  if (tc.function.name === 'list_apps') {
+    const result = executeListApps();
+    ctx.pendingToolCallsRef.current.push('list_apps');
+    return toolResult(result);
+  }
+
+  // ---- File tools ----
+  if (isFileTool(tc.function.name)) {
+    ctx.pendingToolCallsRef.current.push(
+      `${tc.function.name}(${JSON.stringify(params).slice(0, 60)})`,
+    );
+    try {
+      const result = await executeFileTool(tc.function.name, params as Record<string, string>);
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ---- Image gen ----
+  if (isImageGenTool(tc.function.name)) {
+    ctx.pendingToolCallsRef.current.push('generate_image');
+    try {
+      const { result, dataUrl } = await executeImageGenTool(
+        params as Record<string, string>,
+        ctx.imageGenConfigRef.current,
+      );
+      if (dataUrl) {
+        ctx.callbacks.addMessage({
+          id: String(Date.now()) + '-img',
+          role: 'assistant',
+          content: '',
+          imageUrl: dataUrl,
+        });
+      }
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ---- Memory tools ----
+  if (isMemoryTool(tc.function.name)) {
+    ctx.pendingToolCallsRef.current.push('save_memory');
+    try {
+      const result = await executeMemoryTool(
+        ctx.sessionPathRef.current,
+        params as Record<string, string>,
+      );
+      const capturedSession = ctx.sessionPathRef.current;
+      loadMemories(capturedSession)
+        .then((mems) => {
+          if (ctx.sessionPathRef.current === capturedSession) {
+            ctx.callbacks.setMemories(mems);
+          }
+        })
+        .catch((err) => {
+          console.warn('Failed to reload memories after save:', err);
+          if (ctx.sessionPathRef.current === capturedSession) {
+            ctx.callbacks.setMemories([]);
+          }
+        });
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ---- app_action ----
+  if (tc.function.name === 'app_action') {
+    const strParams = params as Record<string, string>;
+    const resolved = resolveAppAction(strParams.app_name, strParams.action_type);
+    if (typeof resolved === 'string') {
+      return toolResult(resolved);
+    }
+
+    ctx.pendingToolCallsRef.current.push(`${strParams.app_name}/${strParams.action_type}`);
+
+    let actionParams: Record<string, string> = {};
+    if (strParams.params) {
+      try {
+        actionParams = JSON.parse(strParams.params);
+      } catch {
+        // empty
+      }
+    }
+
+    try {
+      const result = await dispatchAgentAction({
+        app_id: resolved.appId,
+        action_type: resolved.actionType,
+        params: actionParams,
+      });
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Unknown tool
+  return toolResult('error: unknown tool');
+}