From c82cbff3ca9ca82127e12ab95f902824bb90ab5b Mon Sep 17 00:00:00 2001
From: Sophia <44297511+SweetSophia@users.noreply.github.com>
Date: Wed, 1 Apr 2026 19:44:26 +0200
Subject: [PATCH 01/13] Addressing PR comments (#1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor: extract ChatPanel into focused modules

Decompose the 1472-line ChatPanel god component into four focused files:

- toolDefinitions.ts (133 lines): tool defs, system prompt builder, config guard
- ChatSubComponents.tsx (178 lines): CharacterAvatar, StageIndicator, ActionsTaken
- SettingsModal.tsx (270 lines): LLM + image generation configuration UI
- useConversationEngine.ts (341 lines): conversation loop + tool dispatch hook

ChatPanel/index.tsx reduced from 1472 → 632 lines (-57%), now a thin shell
that wires state to UI. No behavior changes — pure structural refactor.

Benefits:
- Conversation engine is testable in isolation
- Settings modal can be reasoned about independently
- Each file has a single clear responsibility
- Future PRs can target specific modules without touching the whole

* fix: consolidate duplicate ModManager imports in useConversationEngine.ts

Agent-Logs-Url: https://github.com/SweetSophia/OpenRoom/sessions/f4ebc43a-24c2-4853-b135-f234fd25d12b

Co-authored-by: SweetSophia <44297511+SweetSophia@users.noreply.github.com>

* fix: stabilize runConversation identity to prevent listener churn

runConversation was recreated on every render, causing the onUserAction
subscription effect to unsubscribe/resubscribe on each render. App actions
emitted during the cleanup-rebind window could be silently dropped.

Since runConversation only reads from refs (no reactive state), wrapping
it in useCallback with an empty dependency array makes its identity stable
across renders, eliminating the churn.

* fix: address code review findings across ChatPanel modules

useConversationEngine:
- Wrap callbacks in ref to prevent stale closure in stabilized runConversation
- Break outer loop after respond_to_user to avoid extra model round-trip
- Add console.warn for unparseable tool call arguments
- Handle loadMemories rejection with fallback to empty array

ChatSubComponents:
- Reactivate existing inactive layer instead of skipping it
- Use ref for cleanup timeout to prevent stale timeout interference

index.tsx:
- Move setSessionPath call from render body to useEffect
- Reduce reload effect deps to sessionPath only, add cancellation guard

SettingsModal:
- Sync local state from parent props via useEffect

toolDefinitions:
- Replace hardcoded emotion examples with generic reference to character keys

* fix: address review feedback on types, timeout cleanup, and config guard

Agent-Logs-Url: https://github.com/SweetSophia/OpenRoom/sessions/6cd6bd9b-6a80-474a-b067-8f2ff9f8f32a

Co-authored-by: SweetSophia <44297511+SweetSophia@users.noreply.github.com>

* fix: address Copilot review — tool loop, save snapshot, layer cleanup

useConversationEngine:
- Remove inner break on respond_to_user so sibling tool calls
  (e.g. finish_target) still execute before outer loop stops

index.tsx:
- Guard loadMemories .then/.catch with cancelled flag
- Snapshot session/data at debounce schedule time instead of
  reading refs at fire-time, preventing cross-session data mixing
- Remove now-unused sessionPathRef2

ChatSubComponents:
- On layer reactivation, cancel pending cleanup timeout and
  explicitly deactivate all other layers to prevent dual-active state

* fix: Prettier import style, stale memory guard, remove redundant ref

useConversationEngine:
- Break React import to multiline per Prettier config
- Guard loadMemories handlers against session change during async gap

index.tsx:
- Remove unused sessionPathRef_forSet ref — setSessionPath in
  useEffect alone is sufficient for module-level sync

* fix: flush debounced save on cleanup, remove stale dep in handleResetSession

index.tsx:
- Flush pending saveChatHistory in cleanup instead of discarding,
  preventing data loss on rapid session switches
- Remove modCollection from handleResetSession dependency array
  (uses refs and functional state updates, no direct read needed)

* fix(ChatPanel): useLayoutEffect for setSessionPath; fix debounced save write amplification

Agent-Logs-Url: https://github.com/SweetSophia/OpenRoom/sessions/4ddaf906-91f2-4ac3-ac97-7ce3fd331545

Co-authored-by: SweetSophia <44297511+SweetSophia@users.noreply.github.com>

* refactor: extract PendingSaveSnapshot type from inline ref type

Agent-Logs-Url: https://github.com/SweetSophia/OpenRoom/sessions/4ddaf906-91f2-4ac3-ac97-7ce3fd331545

Co-authored-by: SweetSophia <44297511+SweetSophia@users.noreply.github.com>

* fix: ModManager value import, sessionPath out of save deps, redact sensitive args from warn log

Agent-Logs-Url: https://github.com/SweetSophia/OpenRoom/sessions/1954e0a2-8dec-4da9-85f4-92df5e2ddf00

Co-authored-by: SweetSophia <44297511+SweetSophia@users.noreply.github.com>

* fix: only break loop when respond_to_user is sole tool call

Previously the loop broke after respond_to_user even when other tools
ran in the same batch. If the model planned to emit follow-up tool
calls (e.g. finish_target) in a subsequent round-trip, those were
silently skipped. Now the loop only terminates when respond_to_user
was the only tool call — batched tool calls get their follow-up
round-trip as intended.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
---
 .../ChatPanel/ChatSubComponents.tsx           |  198 +++
 .../components/ChatPanel/SettingsModal.tsx    |  292 +++++
 .../src/components/ChatPanel/index.tsx        | 1103 +++--------------
 .../components/ChatPanel/toolDefinitions.ts   |  136 ++
 .../ChatPanel/useConversationEngine.ts        |  373 ++++++
 5 files changed, 1162 insertions(+), 940 deletions(-)
 create mode 100644 apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
 create mode 100644 apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
 create mode 100644 apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
 create mode 100644 apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts

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');
+}

From c350409fcca9b6ab2319b346d50a6ed99caaa47e Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Wed, 1 Apr 2026 20:15:40 +0200
Subject: [PATCH 02/13] fix: error boundaries, path traversal, SSRF, abort
 controller, stale state

1. Error Boundaries: Wrap AppWindow and ChatPanel in ErrorBoundary
   components so crashes don't take down the entire Shell.

2. Path Traversal: Replace regex-based sanitization in session-data
   and session-reset endpoints with resolve()-based validation that
   ensures paths stay within SESSIONS_DIR.

3. SSRF/Header Injection: LLM proxy now uses an explicit allowlist
   for forwarded headers. x-custom- headers are validated to prevent
   auth injection. Target URLs are validated for protocol.

4. AbortController: Conversation loop accepts AbortSignal.
   handleSend and processActionQueue cancel previous conversations
   before starting new ones.

5. Stale State: handleSend reads chatHistory from chatHistoryRef
   instead of closure, fixing race condition.
---
 .../src/components/ChatPanel/index.tsx        |  48 +++--
 .../ChatPanel/useConversationEngine.ts        | 177 ++++++++++--------
 .../src/components/ErrorBoundary.module.scss  |  50 +++++
 .../src/components/ErrorBoundary.tsx          |  57 ++++++
 apps/webuiapps/src/components/Shell/index.tsx |  21 ++-
 .../src/pages/Album/album_cn/guide.md         |  13 +-
 .../src/pages/Album/album_en/guide.md         |  16 +-
 .../src/pages/Chess/chess_cn/guide.md         | 158 +++++++++++-----
 .../src/pages/Chess/chess_en/guide.md         | 166 +++++++++++-----
 .../src/pages/CyberNews/meta/meta_cn/guide.md |  63 ++++---
 .../src/pages/CyberNews/meta/meta_en/guide.md |  65 ++++---
 .../src/pages/Diary/diary_cn/guide.md         |  39 ++--
 .../src/pages/Diary/diary_en/guide.md         |  74 +++++---
 .../src/pages/Email/email_cn/guide.md         |  53 +++---
 .../src/pages/Email/email_en/guide.md         |  74 ++++----
 .../EvidenceVault/evidencevault_cn/guide.md   |  35 ++--
 .../EvidenceVault/evidencevault_en/guide.md   |  38 ++--
 .../src/pages/FreeCell/freecell_cn/guide.md   |  39 ++--
 .../src/pages/FreeCell/freecell_en/guide.md   |  47 +++--
 .../src/pages/Gomoku/meta/meta_cn/guide.md    |  89 +++++----
 .../src/pages/Gomoku/meta/meta_en/guide.md    |  95 ++++++----
 .../src/pages/MusicApp/meta/meta_cn/guide.md  |  63 ++++---
 .../src/pages/MusicApp/meta/meta_en/guide.md  |  72 +++----
 .../src/pages/Twitter/twitter_cn/guide.md     |  62 +++---
 .../src/pages/Twitter/twitter_en/guide.md     |  76 ++++----
 apps/webuiapps/vite.config.ts                 |  91 ++++++++-
 26 files changed, 1107 insertions(+), 674 deletions(-)
 create mode 100644 apps/webuiapps/src/components/ErrorBoundary.module.scss
 create mode 100644 apps/webuiapps/src/components/ErrorBoundary.tsx

diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index 67e5502..c88a057 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -163,7 +163,7 @@ const ChatPanel: React.FC<{
   sessionPathRef.current = sessionPath;
 
   // Conversation engine
-  const { runConversation } = useConversationEngine({
+  const { runConversation, abortRef } = useConversationEngine({
     imageGenConfigRef,
     modManagerRef,
     characterRef,
@@ -420,16 +420,25 @@ const ChatPanel: React.FC<{
       ];
       setChatHistory(newHistory);
       setLoading(true);
+
+      // Cancel any previous conversation
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
       try {
-        await runConversation(newHistory, cfg);
+        await runConversation(newHistory, cfg, controller.signal);
       } catch (err) {
-        logger.error('ChatPanel', 'User action error:', err);
+        if ((err as Error).name !== 'AbortError') {
+          logger.error('ChatPanel', 'User action error:', err);
+        }
       } finally {
+        if (abortRef.current === controller) abortRef.current = null;
         setLoading(false);
       }
     }
     processingRef.current = false;
-  }, [runConversation]);
+  }, [runConversation, abortRef]);
 
   // Listen for user actions from apps
   useEffect(() => {
@@ -482,24 +491,37 @@ const ChatPanel: React.FC<{
       };
       addMessage(userDisplay);
 
-      const newHistory: ChatMessage[] = [...chatHistory, { role: 'user', content: text }];
+      // Use chatHistoryRef to avoid stale closure over chatHistory state
+      const newHistory: ChatMessage[] = [
+        ...chatHistoryRef.current,
+        { role: 'user', content: text },
+      ];
       setChatHistory(newHistory);
 
       setLoading(true);
+
+      // Cancel any previous conversation
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
       try {
-        await runConversation(newHistory, config);
+        await runConversation(newHistory, config, controller.signal);
       } catch (err) {
-        logger.error('ChatPanel', 'Error:', err);
-        addMessage({
-          id: String(Date.now()),
-          role: 'assistant',
-          content: `Error: ${err instanceof Error ? err.message : String(err)}`,
-        });
+        if ((err as Error).name !== 'AbortError') {
+          logger.error('ChatPanel', 'Error:', err);
+          addMessage({
+            id: String(Date.now()),
+            role: 'assistant',
+            content: `Error: ${err instanceof Error ? err.message : String(err)}`,
+          });
+        }
       } finally {
+        if (abortRef.current === controller) abortRef.current = null;
         setLoading(false);
       }
     },
-    [input, loading, config, chatHistory, addMessage, runConversation],
+    [input, loading, config, addMessage, runConversation, abortRef],
   );
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
index 3faf20e..e593813 100644
--- a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
@@ -93,100 +93,113 @@ export function useConversationEngine(deps: ConversationEngineDeps) {
 
   const pendingToolCallsRef = useRef<string[]>([]);
 
+  // Abort controller for the current conversation — allows cancellation when
+  // the user switches sessions or triggers a new request.
+  const abortRef = useRef<AbortController | null>(null);
+
   /**
    * 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.
+   *
+   * @param signal AbortSignal to cancel the conversation mid-loop
    */
-  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 = [];
+  const runConversation = useCallback(
+    async (history: ChatMessage[], cfg: LLMConfig, signal?: AbortSignal) => {
+      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) {
+        if (signal?.aborted) break;
+        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;
         }
-        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];
-      }
+        // 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));
+        // 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;
-    }
-  }, []);
+        // 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;
+        if (signal?.aborted) break;
+      }
+    },
+    [],
+  );
 
-  return { runConversation, pendingToolCallsRef };
+  return { runConversation, pendingToolCallsRef, abortRef };
 }
 
 // ---------------------------------------------------------------------------
diff --git a/apps/webuiapps/src/components/ErrorBoundary.module.scss b/apps/webuiapps/src/components/ErrorBoundary.module.scss
new file mode 100644
index 0000000..fa5f3aa
--- /dev/null
+++ b/apps/webuiapps/src/components/ErrorBoundary.module.scss
@@ -0,0 +1,50 @@
+.fallback {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  padding: 24px;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 8px;
+  color: #fff;
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+  text-align: center;
+  gap: 8px;
+}
+
+.icon {
+  font-size: 32px;
+  margin-bottom: 4px;
+}
+
+.message {
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.detail {
+  font-size: 12px;
+  color: rgba(255, 255, 255, 0.6);
+  max-width: 280px;
+  word-break: break-word;
+}
+
+.retryBtn {
+  margin-top: 8px;
+  padding: 6px 16px;
+  background: rgba(255, 255, 255, 0.15);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 6px;
+  color: #fff;
+  font-size: 13px;
+  cursor: pointer;
+  transition: background 0.15s;
+
+  &:hover {
+    background: rgba(255, 255, 255, 0.25);
+  }
+}
diff --git a/apps/webuiapps/src/components/ErrorBoundary.tsx b/apps/webuiapps/src/components/ErrorBoundary.tsx
new file mode 100644
index 0000000..a535bda
--- /dev/null
+++ b/apps/webuiapps/src/components/ErrorBoundary.tsx
@@ -0,0 +1,57 @@
+/**
+ * ErrorBoundary — prevents child crashes from taking down the entire Shell.
+ *
+ * Usage: Wrap any subtree that should be isolated (AppWindow, ChatPanel, etc.)
+ * The fallback shows a compact error card with a retry button.
+ */
+
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import styles from './ErrorBoundary.module.scss';
+
+interface Props {
+  children: ReactNode;
+  /** Optional label shown in the fallback UI (e.g. "Chess" or "Chat") */
+  name?: string;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.error(`[ErrorBoundary${this.props.name ? `:${this.props.name}` : ''}]`, error, info);
+  }
+
+  private handleRetry = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return (
+        <div className={styles.fallback} data-testid="error-boundary-fallback">
+          <div className={styles.icon}>⚠️</div>
+          <div className={styles.message}>
+            {this.props.name ? `${this.props.name} crashed` : 'Something went wrong'}
+          </div>
+          <div className={styles.detail}>{this.state.error?.message}</div>
+          <button className={styles.retryBtn} onClick={this.handleRetry}>
+            Retry
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
diff --git a/apps/webuiapps/src/components/Shell/index.tsx b/apps/webuiapps/src/components/Shell/index.tsx
index 2066df3..fb0d903 100644
--- a/apps/webuiapps/src/components/Shell/index.tsx
+++ b/apps/webuiapps/src/components/Shell/index.tsx
@@ -23,6 +23,7 @@ import {
 } from 'lucide-react';
 import ChatPanel from '../ChatPanel';
 import AppWindow from '../AppWindow';
+import { ErrorBoundary } from '../ErrorBoundary';
 import { getWindows, subscribe, openWindow, claimZIndex } from '@/lib/windowManager';
 import { getDesktopApps } from '@/lib/appRegistry';
 import { reportUserOsAction, onOSEvent } from '@/lib/vibeContainerMock';
@@ -350,18 +351,22 @@ const Shell: React.FC = () => {
         </div>
       </div>
 
-      {/* App windows */}
+      {/* App windows — each wrapped in ErrorBoundary so a crash doesn't kill the Shell */}
       {windows.map((win) => (
-        <AppWindow key={win.appId} win={win} />
+        <ErrorBoundary key={win.appId} name={`App ${win.appId}`}>
+          <AppWindow win={win} />
+        </ErrorBoundary>
       ))}
 
       {/* Chat Panel — always mounted to preserve chat history */}
-      <ChatPanel
-        onClose={() => setChatOpen(false)}
-        visible={chatOpen}
-        zIndex={chatZIndex}
-        onFocus={() => setChatZIndex(claimZIndex())}
-      />
+      <ErrorBoundary name="Chat">
+        <ChatPanel
+          onClose={() => setChatOpen(false)}
+          visible={chatOpen}
+          zIndex={chatZIndex}
+          onFocus={() => setChatZIndex(claimZIndex())}
+        />
+      </ErrorBoundary>
 
       {/* Upload Modal */}
       {uploadOpen && (
diff --git a/apps/webuiapps/src/pages/Album/album_cn/guide.md b/apps/webuiapps/src/pages/Album/album_cn/guide.md
index 2e469cf..42c58eb 100644
--- a/apps/webuiapps/src/pages/Album/album_cn/guide.md
+++ b/apps/webuiapps/src/pages/Album/album_cn/guide.md
@@ -21,11 +21,11 @@
 
 #### 图片文件 `{id}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 图片唯一标识，与文件名一致（不含 `.json` 后缀） |
-| src | string | 是 | 图片地址：data URL（如 `data:image/png;base64,...`）或 https URL |
-| createdAt | integer | 是 | 创建时间戳（毫秒） |
+| 字段      | 类型    | 必填 | 说明                                                             |
+| --------- | ------- | ---- | ---------------------------------------------------------------- |
+| id        | string  | 是   | 图片唯一标识，与文件名一致（不含 `.json` 后缀）                  |
+| src       | string  | 是   | 图片地址：data URL（如 `data:image/png;base64,...`）或 https URL |
+| createdAt | integer | 是   | 创建时间戳（毫秒）                                               |
 
 示例：
 
@@ -51,7 +51,8 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 在云端新增或删除图片文件后，下发 `REFRESH` Action，前端收到后重新执行 `initFromCloud()` 并刷新列表。
+Agent 在云端新增或删除图片文件后，下发 `REFRESH` Action，前端收到后重新执行 `initFromCloud()`
+并刷新列表。
 
 ### 用户操作
 
diff --git a/apps/webuiapps/src/pages/Album/album_en/guide.md b/apps/webuiapps/src/pages/Album/album_en/guide.md
index 66007bf..b5b8952 100644
--- a/apps/webuiapps/src/pages/Album/album_en/guide.md
+++ b/apps/webuiapps/src/pages/Album/album_en/guide.md
@@ -21,11 +21,11 @@ Stores metadata for all pre-stored images. Each image has a separate JSON file,
 
 #### Image File `{id}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique image identifier, matches the filename (without `.json` extension) |
-| src | string | Yes | Image URL: data URL (e.g., `data:image/png;base64,...`) or https URL |
-| createdAt | integer | Yes | Creation timestamp (milliseconds) |
+| Field     | Type    | Required | Description                                                               |
+| --------- | ------- | -------- | ------------------------------------------------------------------------- |
+| id        | string  | Yes      | Unique image identifier, matches the filename (without `.json` extension) |
+| src       | string  | Yes      | Image URL: data URL (e.g., `data:image/png;base64,...`) or https URL      |
+| createdAt | integer | Yes      | Creation timestamp (milliseconds)                                         |
 
 Example:
 
@@ -51,8 +51,10 @@ Or using an external link:
 
 ### Agent Operations (Agent → Frontend)
 
-After the Agent adds or deletes image files on the cloud, it dispatches the `REFRESH` Action. Upon receiving it, the frontend re-executes `initFromCloud()` and refreshes the list.
+After the Agent adds or deletes image files on the cloud, it dispatches the `REFRESH` Action. Upon
+receiving it, the frontend re-executes `initFromCloud()` and refreshes the list.
 
 ### User Operations
 
-The album is a read-only app. Users can only browse and click to view full-size images. No Actions are reported.
+The album is a read-only app. Users can only browse and click to view full-size images. No Actions
+are reported.
diff --git a/apps/webuiapps/src/pages/Chess/chess_cn/guide.md b/apps/webuiapps/src/pages/Chess/chess_cn/guide.md
index bf899b7..ea8c917 100644
--- a/apps/webuiapps/src/pages/Chess/chess_cn/guide.md
+++ b/apps/webuiapps/src/pages/Chess/chess_cn/guide.md
@@ -13,74 +13,126 @@
 
 存储当前棋局的完整状态，包括棋盘布局、当前回合、易位权限、过路兵目标、走法历史和游戏状态。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| board | (Piece \| null)[][] | 是 | 8x8 棋盘，索引 [0][0] 为 a8（黑方底线左上角），[7][7] 为 h1（白方底线右下角） |
-| currentTurn | string | 是 | 当前回合：`"w"` 白方 / `"b"` 黑方 |
-| castlingRights | CastlingRights | 是 | 易位权限 |
-| enPassantTarget | [number, number] \| null | 是 | 可执行过路兵的目标格（[row, col]），无则为 null |
-| halfMoveClock | number | 是 | 半步计数器（用于 50 步和棋规则） |
-| moveHistory | MoveRecord[] | 是 | 走法历史记录数组 |
-| gameStatus | string | 是 | 游戏状态：`"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"` |
-| winner | string \| null | 是 | 胜方：`"w"` / `"b"` / null |
-| gameId | string | 是 | 棋局唯一标识 |
-| lastMove | object \| null | 是 | 上一步走法，包含 `from: [row, col]` 和 `to: [row, col]`，无则为 null |
-| isAgentThinking | boolean | 是 | Agent 是否正在思考中。为 true 时前端锁定棋盘，禁止用户操作 |
+| 字段            | 类型                     | 必填 | 说明                                                                          |
+| --------------- | ------------------------ | ---- | ----------------------------------------------------------------------------- |
+| board           | (Piece \| null)[][]      | 是   | 8x8 棋盘，索引 [0][0] 为 a8（黑方底线左上角），[7][7] 为 h1（白方底线右下角） |
+| currentTurn     | string                   | 是   | 当前回合：`"w"` 白方 / `"b"` 黑方                                             |
+| castlingRights  | CastlingRights           | 是   | 易位权限                                                                      |
+| enPassantTarget | [number, number] \| null | 是   | 可执行过路兵的目标格（[row, col]），无则为 null                               |
+| halfMoveClock   | number                   | 是   | 半步计数器（用于 50 步和棋规则）                                              |
+| moveHistory     | MoveRecord[]             | 是   | 走法历史记录数组                                                              |
+| gameStatus      | string                   | 是   | 游戏状态：`"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"`  |
+| winner          | string \| null           | 是   | 胜方：`"w"` / `"b"` / null                                                    |
+| gameId          | string                   | 是   | 棋局唯一标识                                                                  |
+| lastMove        | object \| null           | 是   | 上一步走法，包含 `from: [row, col]` 和 `to: [row, col]`，无则为 null          |
+| isAgentThinking | boolean                  | 是   | Agent 是否正在思考中。为 true 时前端锁定棋盘，禁止用户操作                    |
 
 #### Piece 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| type | string | 是 | 棋子类型：`"K"` 王 / `"Q"` 后 / `"R"` 车 / `"B"` 象 / `"N"` 马 / `"P"` 兵 |
-| color | string | 是 | 棋子颜色：`"w"` 白 / `"b"` 黑 |
+| 字段  | 类型   | 必填 | 说明                                                                      |
+| ----- | ------ | ---- | ------------------------------------------------------------------------- |
+| type  | string | 是   | 棋子类型：`"K"` 王 / `"Q"` 后 / `"R"` 车 / `"B"` 象 / `"N"` 马 / `"P"` 兵 |
+| color | string | 是   | 棋子颜色：`"w"` 白 / `"b"` 黑                                             |
 
 #### CastlingRights 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| wK | boolean | 是 | 白方王翼（短）易位权限 |
-| wQ | boolean | 是 | 白方后翼（长）易位权限 |
-| bK | boolean | 是 | 黑方王翼（短）易位权限 |
-| bQ | boolean | 是 | 黑方后翼（长）易位权限 |
+| 字段 | 类型    | 必填 | 说明                   |
+| ---- | ------- | ---- | ---------------------- |
+| wK   | boolean | 是   | 白方王翼（短）易位权限 |
+| wQ   | boolean | 是   | 白方后翼（长）易位权限 |
+| bK   | boolean | 是   | 黑方王翼（短）易位权限 |
+| bQ   | boolean | 是   | 黑方后翼（长）易位权限 |
 
 #### MoveRecord 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| from | [number, number] | 是 | 起始位置 [row, col] |
-| to | [number, number] | 是 | 目标位置 [row, col] |
-| piece | Piece | 是 | 移动的棋子 |
-| captured | Piece \| null | 是 | 被吃掉的棋子（无则 null） |
-| promotion | string \| null | 是 | 升变棋子类型（如 `"Q"`），无则 null |
-| castling | string \| null | 是 | 易位类型：`"K"` 王翼 / `"Q"` 后翼 / null |
-| enPassant | boolean | 是 | 是否为过路兵吃子 |
+| 字段      | 类型             | 必填 | 说明                                     |
+| --------- | ---------------- | ---- | ---------------------------------------- |
+| from      | [number, number] | 是   | 起始位置 [row, col]                      |
+| to        | [number, number] | 是   | 目标位置 [row, col]                      |
+| piece     | Piece            | 是   | 移动的棋子                               |
+| captured  | Piece \| null    | 是   | 被吃掉的棋子（无则 null）                |
+| promotion | string \| null   | 是   | 升变棋子类型（如 `"Q"`），无则 null      |
+| castling  | string \| null   | 是   | 易位类型：`"K"` 王翼 / `"Q"` 后翼 / null |
+| enPassant | boolean          | 是   | 是否为过路兵吃子                         |
 
 示例：
 
 ```json
 {
   "board": [
-    [{"type":"R","color":"b"}, {"type":"N","color":"b"}, {"type":"B","color":"b"}, {"type":"Q","color":"b"}, {"type":"K","color":"b"}, {"type":"B","color":"b"}, {"type":"N","color":"b"}, {"type":"R","color":"b"}],
-    [{"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, null, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}],
+    [
+      { "type": "R", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "Q", "color": "b" },
+      { "type": "K", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "R", "color": "b" }
+    ],
+    [
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      null,
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" }
+    ],
     [null, null, null, null, null, null, null, null],
-    [null, null, null, null, {"type":"P","color":"b"}, null, null, null],
-    [null, null, null, null, {"type":"P","color":"w"}, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "b" }, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "w" }, null, null, null],
     [null, null, null, null, null, null, null, null],
-    [{"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, null, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}],
-    [{"type":"R","color":"w"}, {"type":"N","color":"w"}, {"type":"B","color":"w"}, {"type":"Q","color":"w"}, {"type":"K","color":"w"}, {"type":"B","color":"w"}, {"type":"N","color":"w"}, {"type":"R","color":"w"}]
+    [
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      null,
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" }
+    ],
+    [
+      { "type": "R", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "Q", "color": "w" },
+      { "type": "K", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "R", "color": "w" }
+    ]
   ],
   "currentTurn": "b",
-  "castlingRights": {"wK": true, "wQ": true, "bK": true, "bQ": true},
+  "castlingRights": { "wK": true, "wQ": true, "bK": true, "bQ": true },
   "enPassantTarget": null,
   "halfMoveClock": 0,
   "moveHistory": [
-    {"from": [6,4], "to": [4,4], "piece": {"type":"P","color":"w"}, "captured": null, "promotion": null, "castling": null, "enPassant": false},
-    {"from": [1,4], "to": [3,4], "piece": {"type":"P","color":"b"}, "captured": null, "promotion": null, "castling": null, "enPassant": false}
+    {
+      "from": [6, 4],
+      "to": [4, 4],
+      "piece": { "type": "P", "color": "w" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    },
+    {
+      "from": [1, 4],
+      "to": [3, 4],
+      "piece": { "type": "P", "color": "b" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    }
   ],
   "gameStatus": "playing",
   "winner": null,
   "gameId": "1706000000000-abc123def",
-  "lastMove": {"from": [1,4], "to": [3,4]},
+  "lastMove": { "from": [1, 4], "to": [3, 4] },
   "isAgentThinking": false
 }
 ```
@@ -90,6 +142,7 @@
 ### 回合制交互模型
 
 本应用采用**严格回合制**：
+
 - 用户执白，Agent 执黑
 - 用户走棋后，棋盘锁定（`isAgentThinking = true`），等待 Agent 响应
 - Agent 走棋后，棋盘解锁（`isAgentThinking = false`），轮到用户操作
@@ -99,22 +152,31 @@
 
 Agent 在云端直接修改 `/state.json`，将自己的走法应用到棋盘上，然后下发 Action 通知前端同步：
 
-- **AGENT_MOVE**：Agent 走了一步棋。Agent 在 state.json 中更新棋盘、将 `currentTurn` 改为 `"w"`、将 `isAgentThinking` 设为 `false`，并更新走法历史和游戏状态。前端收到后执行 `initFromCloud()` 读取最新状态并刷新 UI。
-- **SYNC_STATE**：Agent 修改了 state.json（如调整棋局状态），前端收到后执行 `initFromCloud()` 读取最新状态并刷新 UI。
-- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()` 读取并刷新 UI。
+- **AGENT_MOVE**：Agent 走了一步棋。Agent 在 state.json 中更新棋盘、将 `currentTurn` 改为 `"w"`、将
+  `isAgentThinking` 设为 `false`，并更新走法历史和游戏状态。前端收到后执行 `initFromCloud()`
+  读取最新状态并刷新 UI。
+- **SYNC_STATE**：Agent 修改了 state.json（如调整棋局状态），前端收到后执行 `initFromCloud()`
+  读取最新状态并刷新 UI。
+- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()`
+  读取并刷新 UI。
 
 ### 用户操作（前端 → Agent）
 
-- **USER_MOVE**：用户在界面上走了一步棋后，前端更新本地状态（`currentTurn` 改为 `"b"`、`isAgentThinking` 设为 `true`）并同步到云端，然后上报 `USER_MOVE` Action（附带 from、to 坐标和 gameId）。
-- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新棋局并同步到云端，然后上报 `NEW_GAME` Action（附带 gameId）。
+- **USER_MOVE**：用户在界面上走了一步棋后，前端更新本地状态（`currentTurn` 改为
+  `"b"`、`isAgentThinking` 设为 `true`）并同步到云端，然后上报 `USER_MOVE`
+  Action（附带 from、to 坐标和 gameId）。
+- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新棋局并同步到云端，然后上报 `NEW_GAME`
+  Action（附带 gameId）。
 
 ### 启动恢复
 
-前端启动时调用 `initFromCloud()` 从云端拉取 `/state.json`。若文件不存在，自动生成初始棋局并写入云端。
+前端启动时调用 `initFromCloud()` 从云端拉取
+`/state.json`。若文件不存在，自动生成初始棋局并写入云端。
 
 ### 坐标系统
 
 棋盘坐标使用 `[row, col]` 格式：
+
 - `[0, 0]` = a8（左上角，黑方底线）
 - `[0, 7]` = h8（右上角）
 - `[7, 0]` = a1（左下角，白方底线）
diff --git a/apps/webuiapps/src/pages/Chess/chess_en/guide.md b/apps/webuiapps/src/pages/Chess/chess_en/guide.md
index 04dd3ed..8f5399f 100644
--- a/apps/webuiapps/src/pages/Chess/chess_en/guide.md
+++ b/apps/webuiapps/src/pages/Chess/chess_en/guide.md
@@ -11,76 +11,129 @@
 
 ### State File `/state.json`
 
-Stores the complete state of the current game, including board layout, current turn, castling rights, en passant target, move history, and game status.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| board | (Piece \| null)[][] | Yes | 8x8 board, index [0][0] is a8 (top-left, black's back rank), [7][7] is h1 (bottom-right, white's back rank) |
-| currentTurn | string | Yes | Current turn: `"w"` white / `"b"` black |
-| castlingRights | CastlingRights | Yes | Castling rights |
-| enPassantTarget | [number, number] \| null | Yes | En passant target square ([row, col]), null if none |
-| halfMoveClock | number | Yes | Half-move counter (for 50-move draw rule) |
-| moveHistory | MoveRecord[] | Yes | Array of move history records |
-| gameStatus | string | Yes | Game status: `"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"` |
-| winner | string \| null | Yes | Winner: `"w"` / `"b"` / null |
-| gameId | string | Yes | Unique game identifier |
-| lastMove | object \| null | Yes | Last move with `from: [row, col]` and `to: [row, col]`, null if none |
-| isAgentThinking | boolean | Yes | Whether the Agent is currently thinking. When true, the frontend locks the board and prevents user interaction |
+Stores the complete state of the current game, including board layout, current turn, castling
+rights, en passant target, move history, and game status.
+
+| Field           | Type                     | Required | Description                                                                                                    |
+| --------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------- |
+| board           | (Piece \| null)[][]      | Yes      | 8x8 board, index [0][0] is a8 (top-left, black's back rank), [7][7] is h1 (bottom-right, white's back rank)    |
+| currentTurn     | string                   | Yes      | Current turn: `"w"` white / `"b"` black                                                                        |
+| castlingRights  | CastlingRights           | Yes      | Castling rights                                                                                                |
+| enPassantTarget | [number, number] \| null | Yes      | En passant target square ([row, col]), null if none                                                            |
+| halfMoveClock   | number                   | Yes      | Half-move counter (for 50-move draw rule)                                                                      |
+| moveHistory     | MoveRecord[]             | Yes      | Array of move history records                                                                                  |
+| gameStatus      | string                   | Yes      | Game status: `"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"`                                |
+| winner          | string \| null           | Yes      | Winner: `"w"` / `"b"` / null                                                                                   |
+| gameId          | string                   | Yes      | Unique game identifier                                                                                         |
+| lastMove        | object \| null           | Yes      | Last move with `from: [row, col]` and `to: [row, col]`, null if none                                           |
+| isAgentThinking | boolean                  | Yes      | Whether the Agent is currently thinking. When true, the frontend locks the board and prevents user interaction |
 
 #### Piece Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| type | string | Yes | Piece type: `"K"` King / `"Q"` Queen / `"R"` Rook / `"B"` Bishop / `"N"` Knight / `"P"` Pawn |
-| color | string | Yes | Piece color: `"w"` white / `"b"` black |
+| Field | Type   | Required | Description                                                                                  |
+| ----- | ------ | -------- | -------------------------------------------------------------------------------------------- |
+| type  | string | Yes      | Piece type: `"K"` King / `"Q"` Queen / `"R"` Rook / `"B"` Bishop / `"N"` Knight / `"P"` Pawn |
+| color | string | Yes      | Piece color: `"w"` white / `"b"` black                                                       |
 
 #### CastlingRights Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| wK | boolean | Yes | White kingside castling right |
-| wQ | boolean | Yes | White queenside castling right |
-| bK | boolean | Yes | Black kingside castling right |
-| bQ | boolean | Yes | Black queenside castling right |
+| Field | Type    | Required | Description                    |
+| ----- | ------- | -------- | ------------------------------ |
+| wK    | boolean | Yes      | White kingside castling right  |
+| wQ    | boolean | Yes      | White queenside castling right |
+| bK    | boolean | Yes      | Black kingside castling right  |
+| bQ    | boolean | Yes      | Black queenside castling right |
 
 #### MoveRecord Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| from | [number, number] | Yes | Source position [row, col] |
-| to | [number, number] | Yes | Target position [row, col] |
-| piece | Piece | Yes | The piece that moved |
-| captured | Piece \| null | Yes | The captured piece (null if none) |
-| promotion | string \| null | Yes | Promotion piece type (e.g., `"Q"`), null if none |
-| castling | string \| null | Yes | Castling type: `"K"` kingside / `"Q"` queenside / null |
-| enPassant | boolean | Yes | Whether this was an en passant capture |
+| Field     | Type             | Required | Description                                            |
+| --------- | ---------------- | -------- | ------------------------------------------------------ |
+| from      | [number, number] | Yes      | Source position [row, col]                             |
+| to        | [number, number] | Yes      | Target position [row, col]                             |
+| piece     | Piece            | Yes      | The piece that moved                                   |
+| captured  | Piece \| null    | Yes      | The captured piece (null if none)                      |
+| promotion | string \| null   | Yes      | Promotion piece type (e.g., `"Q"`), null if none       |
+| castling  | string \| null   | Yes      | Castling type: `"K"` kingside / `"Q"` queenside / null |
+| enPassant | boolean          | Yes      | Whether this was an en passant capture                 |
 
 Example:
 
 ```json
 {
   "board": [
-    [{"type":"R","color":"b"}, {"type":"N","color":"b"}, {"type":"B","color":"b"}, {"type":"Q","color":"b"}, {"type":"K","color":"b"}, {"type":"B","color":"b"}, {"type":"N","color":"b"}, {"type":"R","color":"b"}],
-    [{"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, null, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}],
+    [
+      { "type": "R", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "Q", "color": "b" },
+      { "type": "K", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "R", "color": "b" }
+    ],
+    [
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      null,
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" }
+    ],
     [null, null, null, null, null, null, null, null],
-    [null, null, null, null, {"type":"P","color":"b"}, null, null, null],
-    [null, null, null, null, {"type":"P","color":"w"}, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "b" }, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "w" }, null, null, null],
     [null, null, null, null, null, null, null, null],
-    [{"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, null, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}],
-    [{"type":"R","color":"w"}, {"type":"N","color":"w"}, {"type":"B","color":"w"}, {"type":"Q","color":"w"}, {"type":"K","color":"w"}, {"type":"B","color":"w"}, {"type":"N","color":"w"}, {"type":"R","color":"w"}]
+    [
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      null,
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" }
+    ],
+    [
+      { "type": "R", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "Q", "color": "w" },
+      { "type": "K", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "R", "color": "w" }
+    ]
   ],
   "currentTurn": "b",
-  "castlingRights": {"wK": true, "wQ": true, "bK": true, "bQ": true},
+  "castlingRights": { "wK": true, "wQ": true, "bK": true, "bQ": true },
   "enPassantTarget": null,
   "halfMoveClock": 0,
   "moveHistory": [
-    {"from": [6,4], "to": [4,4], "piece": {"type":"P","color":"w"}, "captured": null, "promotion": null, "castling": null, "enPassant": false},
-    {"from": [1,4], "to": [3,4], "piece": {"type":"P","color":"b"}, "captured": null, "promotion": null, "castling": null, "enPassant": false}
+    {
+      "from": [6, 4],
+      "to": [4, 4],
+      "piece": { "type": "P", "color": "w" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    },
+    {
+      "from": [1, 4],
+      "to": [3, 4],
+      "piece": { "type": "P", "color": "b" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    }
   ],
   "gameStatus": "playing",
   "winner": null,
   "gameId": "1706000000000-abc123def",
-  "lastMove": {"from": [1,4], "to": [3,4]},
+  "lastMove": { "from": [1, 4], "to": [3, 4] },
   "isAgentThinking": false
 }
 ```
@@ -90,6 +143,7 @@ Example:
 ### Turn-Based Interaction Model
 
 This application uses a **strict turn-based** model:
+
 - The user plays white, the Agent plays black
 - After the user moves, the board locks (`isAgentThinking = true`), waiting for the Agent to respond
 - After the Agent moves, the board unlocks (`isAgentThinking = false`), and it's the user's turn
@@ -97,24 +151,34 @@ This application uses a **strict turn-based** model:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent directly modifies `/state.json` on the cloud, applying its move to the board, then dispatches an Action to notify the frontend to sync:
+The Agent directly modifies `/state.json` on the cloud, applying its move to the board, then
+dispatches an Action to notify the frontend to sync:
 
-- **AGENT_MOVE**: The Agent made a move. The Agent updates the board in state.json, sets `currentTurn` to `"w"`, sets `isAgentThinking` to `false`, and updates move history and game status. The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
-- **SYNC_STATE**: The Agent modified state.json (e.g., adjusting game state). The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
-- **NEW_GAME**: The Agent wrote a new game's state.json. The frontend executes `initFromCloud()` to read and refresh the UI.
+- **AGENT_MOVE**: The Agent made a move. The Agent updates the board in state.json, sets
+  `currentTurn` to `"w"`, sets `isAgentThinking` to `false`, and updates move history and game
+  status. The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
+- **SYNC_STATE**: The Agent modified state.json (e.g., adjusting game state). The frontend executes
+  `initFromCloud()` to read the latest state and refresh the UI.
+- **NEW_GAME**: The Agent wrote a new game's state.json. The frontend executes `initFromCloud()` to
+  read and refresh the UI.
 
 ### User Operations (Frontend → Agent)
 
-- **USER_MOVE**: After the user makes a move on the board, the frontend updates the local state (`currentTurn` to `"b"`, `isAgentThinking` to `true`) and syncs to the cloud, then reports the `USER_MOVE` Action (with from, to coordinates and gameId).
-- **NEW_GAME**: After the user clicks "New Game", the frontend generates a new game and syncs to the cloud, then reports the `NEW_GAME` Action (with gameId).
+- **USER_MOVE**: After the user makes a move on the board, the frontend updates the local state
+  (`currentTurn` to `"b"`, `isAgentThinking` to `true`) and syncs to the cloud, then reports the
+  `USER_MOVE` Action (with from, to coordinates and gameId).
+- **NEW_GAME**: After the user clicks "New Game", the frontend generates a new game and syncs to the
+  cloud, then reports the `NEW_GAME` Action (with gameId).
 
 ### Startup Recovery
 
-On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file does not exist, an initial game is automatically generated and written to the cloud.
+On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file
+does not exist, an initial game is automatically generated and written to the cloud.
 
 ### Coordinate System
 
 Board coordinates use `[row, col]` format:
+
 - `[0, 0]` = a8 (top-left, black's back rank)
 - `[0, 7]` = h8 (top-right)
 - `[7, 0]` = a1 (bottom-left, white's back rank)
diff --git a/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md b/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md
index 4444101..b02713c 100644
--- a/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md
+++ b/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md
@@ -8,45 +8,45 @@
 
 ### Article（新闻文章）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | string | 唯一标识 |
-| title | string | 标题（大写） |
-| category | 'breaking' \| 'corporate' \| 'street' \| 'tech' | 分类 |
-| summary | string | 摘要 |
-| content | string | 正文 |
-| imageUrl | string | 配图URL（可为空） |
-| publishedAt | string | 发布时间 ISO 格式 |
+| 字段        | 类型                                            | 说明              |
+| ----------- | ----------------------------------------------- | ----------------- |
+| id          | string                                          | 唯一标识          |
+| title       | string                                          | 标题（大写）      |
+| category    | 'breaking' \| 'corporate' \| 'street' \| 'tech' | 分类              |
+| summary     | string                                          | 摘要              |
+| content     | string                                          | 正文              |
+| imageUrl    | string                                          | 配图URL（可为空） |
+| publishedAt | string                                          | 发布时间 ISO 格式 |
 
 ### Case（调查案件）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | string | 唯一标识 |
-| caseNumber | string | 案件编号 |
-| title | string | 案件标题 |
-| status | 'open' \| 'closed' \| 'classified' | 状态 |
-| clues | Clue[] | 线索列表 |
+| 字段       | 类型                               | 说明     |
+| ---------- | ---------------------------------- | -------- |
+| id         | string                             | 唯一标识 |
+| caseNumber | string                             | 案件编号 |
+| title      | string                             | 案件标题 |
+| status     | 'open' \| 'closed' \| 'classified' | 状态     |
+| clues      | Clue[]                             | 线索列表 |
 
 ### Clue（线索卡片）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | string | 唯一标识 |
-| type | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | 类型 |
-| title | string | 标题 |
-| content | string | 内容 |
-| posX | number | 在调查板上的X坐标 |
-| posY | number | 在调查板上的Y坐标 |
+| 字段    | 类型                                                     | 说明              |
+| ------- | -------------------------------------------------------- | ----------------- |
+| id      | string                                                   | 唯一标识          |
+| type    | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | 类型              |
+| title   | string                                                   | 标题              |
+| content | string                                                   | 内容              |
+| posX    | number                                                   | 在调查板上的X坐标 |
+| posY    | number                                                   | 在调查板上的Y坐标 |
 
 ### AppState（应用状态）
 
-| 字段 | 类型 | 默认值 |
-|------|------|--------|
-| currentView | 'news' \| 'case-board' | 'news' |
-| selectedArticleId | string \| null | null |
-| selectedCaseId | string \| null | null |
-| newsFilter | ArticleCategory \| null | null |
+| 字段              | 类型                    | 默认值 |
+| ----------------- | ----------------------- | ------ |
+| currentView       | 'news' \| 'case-board'  | 'news' |
+| selectedArticleId | string \| null          | null   |
+| selectedCaseId    | string \| null          | null   |
+| newsFilter        | ArticleCategory \| null | null   |
 
 ## 存储结构
 
@@ -96,4 +96,5 @@
 
 ### 刷新类 Action
 
-发送 REFRESH_ARTICLES 或 REFRESH_CASES 强制 App 重新读取存储中的所有数据。可用 `navigateTo` 参数切换视图，`focusId` 参数自动选中某项。
+发送 REFRESH_ARTICLES 或 REFRESH_CASES 强制 App 重新读取存储中的所有数据。可用 `navigateTo`
+参数切换视图，`focusId` 参数自动选中某项。
diff --git a/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md b/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md
index d6b86ac..17436a0 100644
--- a/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md
+++ b/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md
@@ -2,42 +2,43 @@
 
 ## Overview
 
-A Cyberpunk 2077 Night City-style news terminal and investigation board app. Features news browsing, article reading, and a case investigation board with draggable clue cards.
+A Cyberpunk 2077 Night City-style news terminal and investigation board app. Features news browsing,
+article reading, and a case investigation board with draggable clue cards.
 
 ## Data Schemas
 
 ### Article
 
-| Field | Type | Description |
-|-------|------|-------------|
-| id | string | Unique identifier |
-| title | string | Title (uppercase) |
-| category | 'breaking' \| 'corporate' \| 'street' \| 'tech' | Category |
-| summary | string | Summary |
-| content | string | Full article body |
-| imageUrl | string | Cover image URL (can be empty) |
-| publishedAt | string | ISO date string |
+| Field       | Type                                            | Description                    |
+| ----------- | ----------------------------------------------- | ------------------------------ |
+| id          | string                                          | Unique identifier              |
+| title       | string                                          | Title (uppercase)              |
+| category    | 'breaking' \| 'corporate' \| 'street' \| 'tech' | Category                       |
+| summary     | string                                          | Summary                        |
+| content     | string                                          | Full article body              |
+| imageUrl    | string                                          | Cover image URL (can be empty) |
+| publishedAt | string                                          | ISO date string                |
 
 ### Case
 
-| Field | Type | Description |
-|-------|------|-------------|
-| id | string | Unique identifier |
-| caseNumber | string | Case number |
-| title | string | Case title |
-| status | 'open' \| 'closed' \| 'classified' | Status |
-| clues | Clue[] | List of clues |
+| Field      | Type                               | Description       |
+| ---------- | ---------------------------------- | ----------------- |
+| id         | string                             | Unique identifier |
+| caseNumber | string                             | Case number       |
+| title      | string                             | Case title        |
+| status     | 'open' \| 'closed' \| 'classified' | Status            |
+| clues      | Clue[]                             | List of clues     |
 
 ### Clue
 
-| Field | Type | Description |
-|-------|------|-------------|
-| id | string | Unique identifier |
-| type | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | Type |
-| title | string | Title |
-| content | string | Content |
-| posX | number | X position on board |
-| posY | number | Y position on board |
+| Field   | Type                                                     | Description         |
+| ------- | -------------------------------------------------------- | ------------------- |
+| id      | string                                                   | Unique identifier   |
+| type    | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | Type                |
+| title   | string                                                   | Title               |
+| content | string                                                   | Content             |
+| posX    | number                                                   | X position on board |
+| posY    | number                                                   | Y position on board |
 
 ## Storage Structure
 
@@ -70,7 +71,10 @@ Step 2: Write full Article JSON (include imageUrl) to /articles/{articleId}.json
 Step 3: Send CREATE_ARTICLE action → App refreshes article list from storage
 ```
 
-**Creating news requires image generation**: Article's imageUrl must be set. Use whatever image-generation tool or capability is provided in the current environment to create a cyberpunk/Night City-style cover image first, then fill imageUrl with the returned URL before writing the article file.
+**Creating news requires image generation**: Article's imageUrl must be set. Use whatever
+image-generation tool or capability is provided in the current environment to create a
+cyberpunk/Night City-style cover image first, then fill imageUrl with the returned URL before
+writing the article file.
 
 Example flow for creating a case with clues:
 
@@ -79,12 +83,15 @@ Step 1: Write full Case JSON (including clues array) to /cases/{caseId}.json (pa
 Step 2: Send CREATE_CASE action → App refreshes case list from storage
 ```
 
-**Important**: The App does NOT create files from action params. It only reads existing files from storage. If you send CREATE_ARTICLE without writing the file first, the article will not appear.
+**Important**: The App does NOT create files from action params. It only reads existing files from
+storage. If you send CREATE_ARTICLE without writing the file first, the article will not appear.
 
 ### Operation Actions (VIEW / SELECT / FILTER / MOVE)
 
-Operation actions execute immediately — no file writing needed. Just send the action with the correct params.
+Operation actions execute immediately — no file writing needed. Just send the action with the
+correct params.
 
 ### Refresh Actions
 
-Send REFRESH_ARTICLES or REFRESH_CASES to force the App to re-read all data from storage. Use `navigateTo` param to switch views, `focusId` to auto-select an item.
+Send REFRESH_ARTICLES or REFRESH_CASES to force the App to re-read all data from storage. Use
+`navigateTo` param to switch views, `focusId` to auto-select an item.
diff --git a/apps/webuiapps/src/pages/Diary/diary_cn/guide.md b/apps/webuiapps/src/pages/Diary/diary_cn/guide.md
index e2def40..fe6ea9e 100644
--- a/apps/webuiapps/src/pages/Diary/diary_cn/guide.md
+++ b/apps/webuiapps/src/pages/Diary/diary_cn/guide.md
@@ -23,16 +23,16 @@
 
 #### 日记文件 `{entryId}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 日记唯一标识，与文件名一致（不含 `.json` 后缀） |
-| date | string | 是 | 日期，格式 YYYY-MM-DD（如 `2026-02-12`），每天最多一条 |
-| title | string | 是 | 日记标题，可为空字符串 |
-| content | string | 是 | 日记内容，支持 Markdown 和特殊标记语法，可为空字符串 |
-| mood | string | 否 | 心情标签：`happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
-| weather | string | 否 | 天气标签：`sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy` |
-| createdAt | integer | 是 | 创建时间戳（毫秒） |
-| updatedAt | integer | 是 | 最后更新时间戳（毫秒） |
+| 字段      | 类型    | 必填 | 说明                                                                                          |
+| --------- | ------- | ---- | --------------------------------------------------------------------------------------------- |
+| id        | string  | 是   | 日记唯一标识，与文件名一致（不含 `.json` 后缀）                                               |
+| date      | string  | 是   | 日期，格式 YYYY-MM-DD（如 `2026-02-12`），每天最多一条                                        |
+| title     | string  | 是   | 日记标题，可为空字符串                                                                        |
+| content   | string  | 是   | 日记内容，支持 Markdown 和特殊标记语法，可为空字符串                                          |
+| mood      | string  | 否   | 心情标签：`happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
+| weather   | string  | 否   | 天气标签：`sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy`                          |
+| createdAt | integer | 是   | 创建时间戳（毫秒）                                                                            |
+| updatedAt | integer | 是   | 最后更新时间戳（毫秒）                                                                        |
 
 示例：
 
@@ -53,19 +53,19 @@
 
 日记内容支持以下手绘效果标记，在预览模式下会渲染为 SVG 动画装饰：
 
-| 标记 | 效果 | 说明 |
-|------|------|------|
-| `{{strike}}文字{{/strike}}` | 手绘删除线 | 红色波浪线划过文字 |
-| `{{scribble}}文字{{/scribble}}` | 涂鸦划掉 | 双重深色删除线 |
-| `{{messy}}文字{{/messy}}` | 凌乱涂黑 | 锯齿形涂鸦遮盖文字 |
+| 标记                            | 效果       | 说明               |
+| ------------------------------- | ---------- | ------------------ |
+| `{{strike}}文字{{/strike}}`     | 手绘删除线 | 红色波浪线划过文字 |
+| `{{scribble}}文字{{/scribble}}` | 涂鸦划掉   | 双重深色删除线     |
+| `{{messy}}文字{{/messy}}`       | 凌乱涂黑   | 锯齿形涂鸦遮盖文字 |
 
 ### 状态文件 `/state.json`
 
 存储应用运行时状态，用于启动时恢复现场。前端在选中日期变更时自动保存并同步到云端。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| selectedDate | string \| null | 是 | 当前选中的日期（YYYY-MM-DD），无选中时为 null |
+| 字段         | 类型           | 必填 | 说明                                          |
+| ------------ | -------------- | ---- | --------------------------------------------- |
+| selectedDate | string \| null | 是   | 当前选中的日期（YYYY-MM-DD），无选中时为 null |
 
 示例：
 
@@ -79,8 +79,7 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。
-前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
+Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
 
 **Agent 创建日记**:
 
diff --git a/apps/webuiapps/src/pages/Diary/diary_en/guide.md b/apps/webuiapps/src/pages/Diary/diary_en/guide.md
index 432c8f5..7c12e44 100644
--- a/apps/webuiapps/src/pages/Diary/diary_en/guide.md
+++ b/apps/webuiapps/src/pages/Diary/diary_en/guide.md
@@ -16,23 +16,25 @@
 
 Stores all diary entry data. Each entry is saved as an independent JSON file, named by entry ID.
 
-- On startup, the frontend reads all files from this directory to render the calendar and diary content
+- On startup, the frontend reads all files from this directory to render the calendar and diary
+  content
 - When the Agent creates a diary entry, it writes a new file directly
-- When a user creates or edits a diary entry, the frontend creates/updates the file and syncs to the cloud
+- When a user creates or edits a diary entry, the frontend creates/updates the file and syncs to the
+  cloud
 - Each date can have at most one entry; entries are browsed by date via the calendar navigator
 
 #### Diary Entry File `{entryId}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique diary entry identifier, matches the filename (without `.json` extension) |
-| date | string | Yes | Date in YYYY-MM-DD format (e.g., `2026-02-12`), at most one entry per day |
-| title | string | Yes | Diary title, can be an empty string |
-| content | string | Yes | Diary content, supports Markdown and special markup syntax, can be an empty string |
-| mood | string | No | Mood tag: `happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
-| weather | string | No | Weather tag: `sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy` |
-| createdAt | integer | Yes | Creation timestamp (milliseconds) |
-| updatedAt | integer | Yes | Last updated timestamp (milliseconds) |
+| Field     | Type    | Required | Description                                                                                   |
+| --------- | ------- | -------- | --------------------------------------------------------------------------------------------- |
+| id        | string  | Yes      | Unique diary entry identifier, matches the filename (without `.json` extension)               |
+| date      | string  | Yes      | Date in YYYY-MM-DD format (e.g., `2026-02-12`), at most one entry per day                     |
+| title     | string  | Yes      | Diary title, can be an empty string                                                           |
+| content   | string  | Yes      | Diary content, supports Markdown and special markup syntax, can be an empty string            |
+| mood      | string  | No       | Mood tag: `happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
+| weather   | string  | No       | Weather tag: `sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy`                       |
+| createdAt | integer | Yes      | Creation timestamp (milliseconds)                                                             |
+| updatedAt | integer | Yes      | Last updated timestamp (milliseconds)                                                         |
 
 Example:
 
@@ -51,21 +53,23 @@ Example:
 
 #### Special Content Markup
 
-Diary content supports the following hand-drawn effect markups. In preview mode, they render as animated SVG decorations:
+Diary content supports the following hand-drawn effect markups. In preview mode, they render as
+animated SVG decorations:
 
-| Markup | Effect | Description |
-|--------|--------|-------------|
-| `{{strike}}text{{/strike}}` | Hand-drawn strikethrough | Red wavy line through text |
-| `{{scribble}}text{{/scribble}}` | Scribble cross-out | Double dark strikethrough lines |
-| `{{messy}}text{{/messy}}` | Messy scribble | Zigzag scribble covering text |
+| Markup                          | Effect                   | Description                     |
+| ------------------------------- | ------------------------ | ------------------------------- |
+| `{{strike}}text{{/strike}}`     | Hand-drawn strikethrough | Red wavy line through text      |
+| `{{scribble}}text{{/scribble}}` | Scribble cross-out       | Double dark strikethrough lines |
+| `{{messy}}text{{/messy}}`       | Messy scribble           | Zigzag scribble covering text   |
 
 ### State File `/state.json`
 
-Stores the app's runtime state for restoring the session on startup. The frontend automatically saves and syncs to the cloud when the selected date changes.
+Stores the app's runtime state for restoring the session on startup. The frontend automatically
+saves and syncs to the cloud when the selected date changes.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| selectedDate | string \| null | Yes | Currently selected date (YYYY-MM-DD), null when nothing is selected |
+| Field        | Type           | Required | Description                                                         |
+| ------------ | -------------- | -------- | ------------------------------------------------------------------- |
+| selectedDate | string \| null | Yes      | Currently selected date (YYYY-MM-DD), null when nothing is selected |
 
 Example:
 
@@ -79,14 +83,18 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to notify the frontend to sync and refresh.
-After receiving an Action, the frontend only reads the latest data from the cloud — it does not create files locally.
+The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to
+notify the frontend to sync and refresh. After receiving an Action, the frontend only reads the
+latest data from the cloud — it does not create files locally.
 
 **Agent Creates a Diary Entry**:
 
-1. The Agent writes the file `/entries/{id}.json` on the cloud (containing the complete diary entry JSON, must include `date` field)
-2. The Agent dispatches the `CREATE_ENTRY` Action with `filePath` in params (e.g., `/entries/{id}.json`)
-3. The frontend reads the file from the cloud, updates the local file tree and calendar, and auto-navigates to that date
+1. The Agent writes the file `/entries/{id}.json` on the cloud (containing the complete diary entry
+   JSON, must include `date` field)
+2. The Agent dispatches the `CREATE_ENTRY` Action with `filePath` in params (e.g.,
+   `/entries/{id}.json`)
+3. The frontend reads the file from the cloud, updates the local file tree and calendar, and
+   auto-navigates to that date
 
 **Agent Updates a Diary Entry**:
 
@@ -112,12 +120,14 @@ After receiving an Action, the frontend only reads the latest data from the clou
 
 ### User Operations (Frontend → Cloud)
 
-User operations on the frontend are handled by the frontend code. The flow is: local operation → sync to cloud → report Action.
+User operations on the frontend are handled by the frontend code. The flow is: local operation →
+sync to cloud → report Action.
 
 **User Creates a Diary Entry**:
 
 1. User selects a date on the calendar and clicks the "Write one" button
-2. The frontend generates diary data (including `date` field) and writes it to the local file system at `/entries/{id}.json`
+2. The frontend generates diary data (including `date` field) and writes it to the local file system
+   at `/entries/{id}.json`
 3. The frontend syncs the file to the cloud
 4. The frontend reports the `CREATE_ENTRY` Action
 
@@ -136,7 +146,8 @@ User operations on the frontend are handled by the frontend code. The flow is: l
 **User Deletes a Diary Entry**:
 
 1. User clicks the delete button
-2. The frontend removes `/entries/{id}.json` from the local file system and syncs the deletion to the cloud
+2. The frontend removes `/entries/{id}.json` from the local file system and syncs the deletion to
+   the cloud
 3. The calendar marker for that date disappears
 4. The frontend reports the `DELETE_ENTRY` Action
 
@@ -144,5 +155,6 @@ User operations on the frontend are handled by the frontend code. The flow is: l
 
 1. The frontend calls `initFromCloud()` to fetch all files
 2. Reads all diary files under `/entries/`, builds a date index for each entry
-3. Reads `/state.json` to restore the previously selected date, and navigates the calendar to that month
+3. Reads `/state.json` to restore the previously selected date, and navigates the calendar to that
+   month
 4. If no saved state, defaults to today
diff --git a/apps/webuiapps/src/pages/Email/email_cn/guide.md b/apps/webuiapps/src/pages/Email/email_cn/guide.md
index 8ed3c77..77fbbb2 100644
--- a/apps/webuiapps/src/pages/Email/email_cn/guide.md
+++ b/apps/webuiapps/src/pages/Email/email_cn/guide.md
@@ -4,12 +4,14 @@
 
 本邮箱是**用户（User）的邮箱**，所有邮件的视角以用户为主。`folder` 字段的设置必须基于用户视角：
 
-- **`inbox`**：用户收到的邮件。Character 发送给用户的邮件应放在 `inbox`，因为对用户来说这是一封收到的邮件。
+- **`inbox`**：用户收到的邮件。Character 发送给用户的邮件应放在
+  `inbox`，因为对用户来说这是一封收到的邮件。
 - **`sent`**：用户发出的邮件。只有用户主动发送的邮件才应放在 `sent`。
 - **`drafts`**：用户的草稿。
 - **`trash`**：用户删除的邮件。
 
-> **常见错误**：Character 向用户发送邮件时，不应将 `folder` 设为 `sent`。虽然这封邮件是 Character "发送"的，但对于用户来说这是一封**收到的邮件**，应设为 `inbox`。
+> **常见错误**：Character 向用户发送邮件时，不应将 `folder` 设为 `sent`。虽然这封邮件是 Character
+> "发送"的，但对于用户来说这是一封**收到的邮件**，应设为 `inbox`。
 
 ## 文件夹结构
 
@@ -34,27 +36,27 @@
 
 #### 邮件文件 `{emailId}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 邮件唯一标识，与文件名一致（不含 `.json` 后缀） |
-| from | object | 是 | 发件人信息 |
-| from.name | string | 是 | 发件人姓名 |
-| from.address | string | 是 | 发件人邮箱地址 |
-| to | array | 是 | 收件人列表，每项为 EmailAddress 对象 |
-| cc | array | 是 | 抄送列表，每项为 EmailAddress 对象，可为空数组 |
-| subject | string | 是 | 邮件主题 |
-| content | string | 是 | 邮件正文内容 |
-| timestamp | integer | 是 | 发送/接收时间戳（毫秒） |
-| isRead | boolean | 是 | 是否已读 |
-| isStarred | boolean | 是 | 是否已加星标 |
-| folder | string | 是 | 所属文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
+| 字段         | 类型    | 必填 | 说明                                                   |
+| ------------ | ------- | ---- | ------------------------------------------------------ |
+| id           | string  | 是   | 邮件唯一标识，与文件名一致（不含 `.json` 后缀）        |
+| from         | object  | 是   | 发件人信息                                             |
+| from.name    | string  | 是   | 发件人姓名                                             |
+| from.address | string  | 是   | 发件人邮箱地址                                         |
+| to           | array   | 是   | 收件人列表，每项为 EmailAddress 对象                   |
+| cc           | array   | 是   | 抄送列表，每项为 EmailAddress 对象，可为空数组         |
+| subject      | string  | 是   | 邮件主题                                               |
+| content      | string  | 是   | 邮件正文内容                                           |
+| timestamp    | integer | 是   | 发送/接收时间戳（毫秒）                                |
+| isRead       | boolean | 是   | 是否已读                                               |
+| isStarred    | boolean | 是   | 是否已加星标                                           |
+| folder       | string  | 是   | 所属文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
 
 **EmailAddress 对象结构：**
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | string | 是 | 姓名 |
-| address | string | 是 | 邮箱地址 |
+| 字段    | 类型   | 必填 | 说明     |
+| ------- | ------ | ---- | -------- |
+| name    | string | 是   | 姓名     |
+| address | string | 是   | 邮箱地址 |
 
 示例：
 
@@ -85,10 +87,10 @@
 
 存储应用运行时状态，用于启动时恢复现场。前端在状态变更时自动保存并同步到云端。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| selectedEmailId | string\|null | 否 | 当前选中的邮件 ID，未选中时为 null |
-| currentFolder | string | 是 | 当前所在文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
+| 字段            | 类型         | 必填 | 说明                                                       |
+| --------------- | ------------ | ---- | ---------------------------------------------------------- |
+| selectedEmailId | string\|null | 否   | 当前选中的邮件 ID，未选中时为 null                         |
+| currentFolder   | string       | 是   | 当前所在文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
 
 示例：
 
@@ -103,8 +105,7 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 负责在云端完成邮件文件的写入/删除，完成后通过下发 Action 通知前端同步刷新。
-前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
+Agent 负责在云端完成邮件文件的写入/删除，完成后通过下发 Action 通知前端同步刷新。前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
 
 **Agent 写邮件**:
 
diff --git a/apps/webuiapps/src/pages/Email/email_en/guide.md b/apps/webuiapps/src/pages/Email/email_en/guide.md
index 3d4cad4..01e177a 100644
--- a/apps/webuiapps/src/pages/Email/email_en/guide.md
+++ b/apps/webuiapps/src/pages/Email/email_en/guide.md
@@ -2,14 +2,19 @@
 
 ## Important: Mailbox Ownership
 
-This mailbox belongs to the **User**. All emails are viewed from the User's perspective. The `folder` field must be set accordingly:
+This mailbox belongs to the **User**. All emails are viewed from the User's perspective. The
+`folder` field must be set accordingly:
 
-- **`inbox`**: Emails received by the User. Emails sent by a Character to the User should be placed in `inbox`, because from the User's perspective, it is a received email.
-- **`sent`**: Emails sent by the User. Only emails actively sent by the User should be placed in `sent`.
+- **`inbox`**: Emails received by the User. Emails sent by a Character to the User should be placed
+  in `inbox`, because from the User's perspective, it is a received email.
+- **`sent`**: Emails sent by the User. Only emails actively sent by the User should be placed in
+  `sent`.
 - **`drafts`**: The User's drafts.
 - **`trash`**: Emails deleted by the User.
 
-> **Common Mistake**: When a Character sends an email to the User, do NOT set `folder` to `sent`. Although the Character "sent" the email, from the User's perspective it is a **received email** and should be set to `inbox`.
+> **Common Mistake**: When a Character sends an email to the User, do NOT set `folder` to `sent`.
+> Although the Character "sent" the email, from the User's perspective it is a **received email**
+> and should be set to `inbox`.
 
 ## Folder Structure
 
@@ -34,27 +39,27 @@ Stores all email data. Each email is saved as an independent JSON file, named by
 
 #### Email File `{emailId}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique email identifier, matches the filename (without `.json` extension) |
-| from | object | Yes | Sender information |
-| from.name | string | Yes | Sender name |
-| from.address | string | Yes | Sender email address |
-| to | array | Yes | Recipient list, each item is an EmailAddress object |
-| cc | array | Yes | CC list, each item is an EmailAddress object, can be an empty array |
-| subject | string | Yes | Email subject |
-| content | string | Yes | Email body content |
-| timestamp | integer | Yes | Send/receive timestamp (milliseconds) |
-| isRead | boolean | Yes | Whether the email has been read |
-| isStarred | boolean | Yes | Whether the email is starred |
-| folder | string | Yes | Folder name, one of: `inbox`, `sent`, `drafts`, `trash` |
+| Field        | Type    | Required | Description                                                               |
+| ------------ | ------- | -------- | ------------------------------------------------------------------------- |
+| id           | string  | Yes      | Unique email identifier, matches the filename (without `.json` extension) |
+| from         | object  | Yes      | Sender information                                                        |
+| from.name    | string  | Yes      | Sender name                                                               |
+| from.address | string  | Yes      | Sender email address                                                      |
+| to           | array   | Yes      | Recipient list, each item is an EmailAddress object                       |
+| cc           | array   | Yes      | CC list, each item is an EmailAddress object, can be an empty array       |
+| subject      | string  | Yes      | Email subject                                                             |
+| content      | string  | Yes      | Email body content                                                        |
+| timestamp    | integer | Yes      | Send/receive timestamp (milliseconds)                                     |
+| isRead       | boolean | Yes      | Whether the email has been read                                           |
+| isStarred    | boolean | Yes      | Whether the email is starred                                              |
+| folder       | string  | Yes      | Folder name, one of: `inbox`, `sent`, `drafts`, `trash`                   |
 
 **EmailAddress Object Structure:**
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| name | string | Yes | Name |
-| address | string | Yes | Email address |
+| Field   | Type   | Required | Description   |
+| ------- | ------ | -------- | ------------- |
+| name    | string | Yes      | Name          |
+| address | string | Yes      | Email address |
 
 Example:
 
@@ -83,12 +88,13 @@ Example:
 
 ### State File `/state.json`
 
-Stores the app's runtime state for restoring the session on startup. The frontend automatically saves and syncs to the cloud when state changes.
+Stores the app's runtime state for restoring the session on startup. The frontend automatically
+saves and syncs to the cloud when state changes.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| selectedEmailId | string\|null | No | Currently selected email ID, null when none is selected |
-| currentFolder | string | Yes | Current folder, one of: `inbox`, `sent`, `drafts`, `trash` |
+| Field           | Type         | Required | Description                                                |
+| --------------- | ------------ | -------- | ---------------------------------------------------------- |
+| selectedEmailId | string\|null | No       | Currently selected email ID, null when none is selected    |
+| currentFolder   | string       | Yes      | Current folder, one of: `inbox`, `sent`, `drafts`, `trash` |
 
 Example:
 
@@ -103,13 +109,16 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent completes email file writes/deletions on the cloud, then dispatches Actions to notify the frontend to sync and refresh.
-After receiving an Action, the frontend only reads the latest data from the cloud — it does not create files locally.
+The Agent completes email file writes/deletions on the cloud, then dispatches Actions to notify the
+frontend to sync and refresh. After receiving an Action, the frontend only reads the latest data
+from the cloud — it does not create files locally.
 
 **Agent Composes an Email**:
 
-1. The Agent writes the email file `/emails/{id}.json` on the cloud (containing the complete email JSON)
-2. The Agent dispatches the `COMPOSE_EMAIL` Action with `filePath` in params (e.g., `/emails/{id}.json`)
+1. The Agent writes the email file `/emails/{id}.json` on the cloud (containing the complete email
+   JSON)
+2. The Agent dispatches the `COMPOSE_EMAIL` Action with `filePath` in params (e.g.,
+   `/emails/{id}.json`)
 3. The frontend reads the file from the cloud, updates the local file tree and UI
 
 **Agent Deletes an Email**:
@@ -126,7 +135,8 @@ After receiving an Action, the frontend only reads the latest data from the clou
 
 ### User Operations (Frontend → Cloud)
 
-User operations on the frontend are in read-only mode — composing, replying, and sending emails are not available. The operations users can perform are:
+User operations on the frontend are in read-only mode — composing, replying, and sending emails are
+not available. The operations users can perform are:
 
 **User Reads an Email**:
 
diff --git a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md
index 74ce404..880be32 100644
--- a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md
+++ b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md
@@ -19,22 +19,22 @@
 
 #### 档案文件 `{id}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 档案唯一标识 |
-| title | string | 是 | 档案标题 |
-| description | string | 是 | 档案描述摘要 |
-| content | string | 是 | 档案正文内容 |
-| type | string | 是 | 档案类型：`video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
-| category | string | 是 | 所属分类：`identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other` |
-| impact | string | 是 | 影响类型：`vindicate`（正面）/ `expose`（负面）/ `neutral`（中性）/ `mixed`（复合） |
-| source | string | 是 | 档案来源 |
-| timestamp | number | 是 | 档案时间戳（Unix 毫秒） |
-| credibility | number | 是 | 可信度（0-100） |
-| importance | number | 是 | 重要性（0-100） |
-| tags | string[] | 是 | 标签数组 |
-| vindicateText | string | 否 | 正面影响说明 |
-| exposeText | string | 否 | 负面影响说明 |
+| 字段          | 类型     | 必填 | 说明                                                                                                                                         |
+| ------------- | -------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| id            | string   | 是   | 档案唯一标识                                                                                                                                 |
+| title         | string   | 是   | 档案标题                                                                                                                                     |
+| description   | string   | 是   | 档案描述摘要                                                                                                                                 |
+| content       | string   | 是   | 档案正文内容                                                                                                                                 |
+| type          | string   | 是   | 档案类型：`video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
+| category      | string   | 是   | 所属分类：`identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other`                                                   |
+| impact        | string   | 是   | 影响类型：`vindicate`（正面）/ `expose`（负面）/ `neutral`（中性）/ `mixed`（复合）                                                          |
+| source        | string   | 是   | 档案来源                                                                                                                                     |
+| timestamp     | number   | 是   | 档案时间戳（Unix 毫秒）                                                                                                                      |
+| credibility   | number   | 是   | 可信度（0-100）                                                                                                                              |
+| importance    | number   | 是   | 重要性（0-100）                                                                                                                              |
+| tags          | string[] | 是   | 标签数组                                                                                                                                     |
+| vindicateText | string   | 否   | 正面影响说明                                                                                                                                 |
+| exposeText    | string   | 否   | 负面影响说明                                                                                                                                 |
 
 示例：
 
@@ -78,4 +78,5 @@
 
 ### 启动恢复
 
-前端启动时调用 `initFromCloud()` 从云端拉取 `/files/` 目录下的所有档案文件。若目录为空，则显示空状态。
+前端启动时调用 `initFromCloud()` 从云端拉取 `/files/`
+目录下的所有档案文件。若目录为空，则显示空状态。
diff --git a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md
index 9f03932..bfdc534 100644
--- a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md
+++ b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md
@@ -13,28 +13,29 @@
 
 ### Evidence File Collection `/files/`
 
-Stores all evidence files, each representing a single evidence/archive record. Data is static and read-only, pre-stored on the cloud.
+Stores all evidence files, each representing a single evidence/archive record. Data is static and
+read-only, pre-stored on the cloud.
 
 File naming convention: `{id}.json`, where `id` is a globally unique identifier.
 
 #### Evidence File `{id}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique evidence identifier |
-| title | string | Yes | Evidence title |
-| description | string | Yes | Evidence summary |
-| content | string | Yes | Evidence body content |
-| type | string | Yes | Evidence type: `video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
-| category | string | Yes | Category: `identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other` |
-| impact | string | Yes | Impact type: `vindicate` (positive) / `expose` (negative) / `neutral` / `mixed` |
-| source | string | Yes | Evidence source |
-| timestamp | number | Yes | Timestamp (Unix milliseconds) |
-| credibility | number | Yes | Credibility score (0-100) |
-| importance | number | Yes | Importance score (0-100) |
-| tags | string[] | Yes | Tag array |
-| vindicateText | string | No | Positive impact description |
-| exposeText | string | No | Negative impact description |
+| Field         | Type     | Required | Description                                                                                                                                       |
+| ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id            | string   | Yes      | Unique evidence identifier                                                                                                                        |
+| title         | string   | Yes      | Evidence title                                                                                                                                    |
+| description   | string   | Yes      | Evidence summary                                                                                                                                  |
+| content       | string   | Yes      | Evidence body content                                                                                                                             |
+| type          | string   | Yes      | Evidence type: `video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
+| category      | string   | Yes      | Category: `identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other`                                                        |
+| impact        | string   | Yes      | Impact type: `vindicate` (positive) / `expose` (negative) / `neutral` / `mixed`                                                                   |
+| source        | string   | Yes      | Evidence source                                                                                                                                   |
+| timestamp     | number   | Yes      | Timestamp (Unix milliseconds)                                                                                                                     |
+| credibility   | number   | Yes      | Credibility score (0-100)                                                                                                                         |
+| importance    | number   | Yes      | Importance score (0-100)                                                                                                                          |
+| tags          | string[] | Yes      | Tag array                                                                                                                                         |
+| vindicateText | string   | No       | Positive impact description                                                                                                                       |
+| exposeText    | string   | No       | Negative impact description                                                                                                                       |
 
 Example:
 
@@ -78,4 +79,5 @@ Users can only perform the following read-only operations (pure frontend, no clo
 
 ### Startup Recovery
 
-On startup, the frontend calls `initFromCloud()` to pull all evidence files from the `/files/` directory on the cloud. If the directory is empty, an empty state is displayed.
+On startup, the frontend calls `initFromCloud()` to pull all evidence files from the `/files/`
+directory on the cloud. If the directory is empty, an empty state is displayed.
diff --git a/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md b/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md
index a20e0ab..0f4911d 100644
--- a/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md
+++ b/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md
@@ -13,21 +13,21 @@
 
 存储当前牌局的完整状态，包括 8 列牌阵、4 个可用单元格、4 个基础牌堆、步数和游戏状态。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| columns | Card[][] | 是 | 8 列牌阵，每列为 Card 数组，索引 0-7 |
-| freeCells | (Card \| null)[] | 是 | 4 个可用单元格，null 表示空位 |
-| foundations | Record<Suit, Card[]> | 是 | 4 个基础牌堆，按花色分组（hearts/diamonds/clubs/spades），从 A 到 K 顺序堆叠 |
-| moveCount | number | 是 | 当前步数 |
-| gameStatus | string | 是 | 游戏状态：`"playing"` 或 `"won"` |
-| gameId | string | 是 | 牌局唯一标识 |
+| 字段        | 类型                 | 必填 | 说明                                                                         |
+| ----------- | -------------------- | ---- | ---------------------------------------------------------------------------- |
+| columns     | Card[][]             | 是   | 8 列牌阵，每列为 Card 数组，索引 0-7                                         |
+| freeCells   | (Card \| null)[]     | 是   | 4 个可用单元格，null 表示空位                                                |
+| foundations | Record<Suit, Card[]> | 是   | 4 个基础牌堆，按花色分组（hearts/diamonds/clubs/spades），从 A 到 K 顺序堆叠 |
+| moveCount   | number               | 是   | 当前步数                                                                     |
+| gameStatus  | string               | 是   | 游戏状态：`"playing"` 或 `"won"`                                             |
+| gameId      | string               | 是   | 牌局唯一标识                                                                 |
 
 #### Card 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| suit | string | 是 | 花色：`"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
-| rank | number | 是 | 点数：1=A, 2-10, 11=J, 12=Q, 13=K |
+| 字段 | 类型   | 必填 | 说明                                                     |
+| ---- | ------ | ---- | -------------------------------------------------------- |
+| suit | string | 是   | 花色：`"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
+| rank | number | 是   | 点数：1=A, 2-10, 11=J, 12=Q, 13=K                        |
 
 示例：
 
@@ -58,14 +58,19 @@
 
 Agent 可以直接写入 `/state.json` 来设置任意合法牌局状态，然后下发以下 Action 通知前端同步：
 
-- **SYNC_STATE**：Agent 修改了 state.json（如代替用户走棋），前端收到后执行 `initFromCloud()` 读取最新状态并刷新 UI。
-- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()` 读取并刷新 UI。
+- **SYNC_STATE**：Agent 修改了 state.json（如代替用户走棋），前端收到后执行 `initFromCloud()`
+  读取最新状态并刷新 UI。
+- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()`
+  读取并刷新 UI。
 
 ### 用户操作（前端 -> Agent）
 
-- **MOVE_CARD**：用户在界面上移动一张或多张牌后，前端更新本地状态并同步到云端，然后上报 `MOVE_CARD` Action（附带 gameId 和 moveCount）。
-- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新牌局并同步到云端，然后上报 `NEW_GAME` Action（附带 gameId）。
+- **MOVE_CARD**：用户在界面上移动一张或多张牌后，前端更新本地状态并同步到云端，然后上报 `MOVE_CARD`
+  Action（附带 gameId 和 moveCount）。
+- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新牌局并同步到云端，然后上报 `NEW_GAME`
+  Action（附带 gameId）。
 
 ### 启动恢复
 
-前端启动时调用 `initFromCloud()` 从云端拉取 `/state.json`。若文件不存在，自动生成一局新游戏并写入云端。
+前端启动时调用 `initFromCloud()` 从云端拉取
+`/state.json`。若文件不存在，自动生成一局新游戏并写入云端。
diff --git a/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md b/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md
index 9c66ec2..b35f98c 100644
--- a/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md
+++ b/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md
@@ -11,23 +11,24 @@
 
 ### State File `/state.json`
 
-Stores the complete state of the current game, including 8 tableau columns, 4 free cells, 4 foundation piles, move count, and game status.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| columns | Card[][] | Yes | 8 tableau columns, each is a Card array, indexed 0-7 |
-| freeCells | (Card \| null)[] | Yes | 4 free cells, null indicates an empty slot |
-| foundations | Record<Suit, Card[]> | Yes | 4 foundation piles, grouped by suit (hearts/diamonds/clubs/spades), stacked in order from A to K |
-| moveCount | number | Yes | Current move count |
-| gameStatus | string | Yes | Game status: `"playing"` or `"won"` |
-| gameId | string | Yes | Unique game identifier |
+Stores the complete state of the current game, including 8 tableau columns, 4 free cells, 4
+foundation piles, move count, and game status.
+
+| Field       | Type                 | Required | Description                                                                                      |
+| ----------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| columns     | Card[][]             | Yes      | 8 tableau columns, each is a Card array, indexed 0-7                                             |
+| freeCells   | (Card \| null)[]     | Yes      | 4 free cells, null indicates an empty slot                                                       |
+| foundations | Record<Suit, Card[]> | Yes      | 4 foundation piles, grouped by suit (hearts/diamonds/clubs/spades), stacked in order from A to K |
+| moveCount   | number               | Yes      | Current move count                                                                               |
+| gameStatus  | string               | Yes      | Game status: `"playing"` or `"won"`                                                              |
+| gameId      | string               | Yes      | Unique game identifier                                                                           |
 
 #### Card Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| suit | string | Yes | Suit: `"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
-| rank | number | Yes | Rank: 1=A, 2-10, 11=J, 12=Q, 13=K |
+| Field | Type   | Required | Description                                              |
+| ----- | ------ | -------- | -------------------------------------------------------- |
+| suit  | string | Yes      | Suit: `"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
+| rank  | number | Yes      | Rank: 1=A, 2-10, 11=J, 12=Q, 13=K                        |
 
 Example:
 
@@ -56,16 +57,22 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent can directly write to `/state.json` to set any valid game state, then dispatch the following Actions to notify the frontend to sync:
+The Agent can directly write to `/state.json` to set any valid game state, then dispatch the
+following Actions to notify the frontend to sync:
 
-- **SYNC_STATE**: The Agent has modified state.json (e.g., making moves on behalf of the user). The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
-- **NEW_GAME**: The Agent has written a new game's state.json. The frontend executes `initFromCloud()` to read and refresh the UI.
+- **SYNC_STATE**: The Agent has modified state.json (e.g., making moves on behalf of the user). The
+  frontend executes `initFromCloud()` to read the latest state and refresh the UI.
+- **NEW_GAME**: The Agent has written a new game's state.json. The frontend executes
+  `initFromCloud()` to read and refresh the UI.
 
 ### User Operations (Frontend → Agent)
 
-- **MOVE_CARD**: After the user moves one or more cards on the board, the frontend updates the local state, syncs to the cloud, and reports the `MOVE_CARD` Action (with gameId and moveCount).
-- **NEW_GAME**: After the user clicks the "New Game" button, the frontend generates a new game and syncs to the cloud, then reports the `NEW_GAME` Action (with gameId).
+- **MOVE_CARD**: After the user moves one or more cards on the board, the frontend updates the local
+  state, syncs to the cloud, and reports the `MOVE_CARD` Action (with gameId and moveCount).
+- **NEW_GAME**: After the user clicks the "New Game" button, the frontend generates a new game and
+  syncs to the cloud, then reports the `NEW_GAME` Action (with gameId).
 
 ### Startup Recovery
 
-On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file does not exist, a new game is automatically generated and written to the cloud.
+On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file
+does not exist, a new game is automatically generated and written to the cloud.
diff --git a/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md b/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md
index 7856f7a..3ef1c50 100644
--- a/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md
+++ b/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md
@@ -18,39 +18,39 @@ apps/gomoku/data/
 
 #### 对局记录文件 `{id}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 对局唯一标识 |
-| players | array | 是 | 两位玩家信息数组，每项包含 name、color、role |
-| moves | array | 是 | 落子记录数组，按时间顺序排列 |
-| result | object \| null | 否 | 对局结果，对局未结束时为 null |
-| startedAt | number | 是 | 对局开始时间戳（毫秒） |
-| endedAt | number \| null | 是 | 对局结束时间戳（毫秒），未结束时为 null |
+| 字段      | 类型           | 必填 | 说明                                         |
+| --------- | -------------- | ---- | -------------------------------------------- |
+| id        | string         | 是   | 对局唯一标识                                 |
+| players   | array          | 是   | 两位玩家信息数组，每项包含 name、color、role |
+| moves     | array          | 是   | 落子记录数组，按时间顺序排列                 |
+| result    | object \| null | 否   | 对局结果，对局未结束时为 null                |
+| startedAt | number         | 是   | 对局开始时间戳（毫秒）                       |
+| endedAt   | number \| null | 是   | 对局结束时间戳（毫秒），未结束时为 null      |
 
 #### Player 对象
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | string | 是 | 玩家名称，如 "You"、"Agent" |
-| color | string | 是 | 棋子颜色，`"black"` 或 `"white"` |
-| role | string | 是 | 角色类型，`"human"` 或 `"agent"` |
+| 字段  | 类型   | 必填 | 说明                             |
+| ----- | ------ | ---- | -------------------------------- |
+| name  | string | 是   | 玩家名称，如 "You"、"Agent"      |
+| color | string | 是   | 棋子颜色，`"black"` 或 `"white"` |
+| role  | string | 是   | 角色类型，`"human"` 或 `"agent"` |
 
 #### Move 对象
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| position | object | 是 | 落子位置，包含 `row`（0-14）和 `col`（0-14） |
-| color | string | 是 | 落子颜色，`"black"` 或 `"white"` |
-| moveNumber | number | 是 | 第几手（从 1 开始） |
-| timestamp | number | 是 | 落子时间戳（毫秒） |
+| 字段       | 类型   | 必填 | 说明                                         |
+| ---------- | ------ | ---- | -------------------------------------------- |
+| position   | object | 是   | 落子位置，包含 `row`（0-14）和 `col`（0-14） |
+| color      | string | 是   | 落子颜色，`"black"` 或 `"white"`             |
+| moveNumber | number | 是   | 第几手（从 1 开始）                          |
+| timestamp  | number | 是   | 落子时间戳（毫秒）                           |
 
 #### Result 对象
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| winner | string \| null | 是 | 获胜方颜色，平局时为 null |
-| winLine | object \| null | 是 | 五连珠位置信息，认输或平局时为 null |
-| reason | string | 是 | 结束原因：`"five-in-a-row"` \| `"surrender"` \| `"draw"` |
+| 字段    | 类型           | 必填 | 说明                                                     |
+| ------- | -------------- | ---- | -------------------------------------------------------- |
+| winner  | string \| null | 是   | 获胜方颜色，平局时为 null                                |
+| winLine | object \| null | 是   | 五连珠位置信息，认输或平局时为 null                      |
+| reason  | string         | 是   | 结束原因：`"five-in-a-row"` \| `"surrender"` \| `"draw"` |
 
 ```json
 {
@@ -60,15 +60,28 @@ apps/gomoku/data/
     { "name": "Agent", "color": "white", "role": "agent" }
   ],
   "moves": [
-    { "position": { "row": 7, "col": 7 }, "color": "black", "moveNumber": 1, "timestamp": 1707350400000 },
-    { "position": { "row": 7, "col": 8 }, "color": "white", "moveNumber": 2, "timestamp": 1707350401000 }
+    {
+      "position": { "row": 7, "col": 7 },
+      "color": "black",
+      "moveNumber": 1,
+      "timestamp": 1707350400000
+    },
+    {
+      "position": { "row": 7, "col": 8 },
+      "color": "white",
+      "moveNumber": 2,
+      "timestamp": 1707350401000
+    }
   ],
   "result": {
     "winner": "black",
     "winLine": {
       "positions": [
-        { "row": 7, "col": 3 }, { "row": 7, "col": 4 }, { "row": 7, "col": 5 },
-        { "row": 7, "col": 6 }, { "row": 7, "col": 7 }
+        { "row": 7, "col": 3 },
+        { "row": 7, "col": 4 },
+        { "row": 7, "col": 5 },
+        { "row": 7, "col": 6 },
+        { "row": 7, "col": 7 }
       ],
       "color": "black"
     },
@@ -83,19 +96,19 @@ apps/gomoku/data/
 
 应用统计数据文件，记录历史对局统计信息。
 
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| currentGameId | string \| null | null | 最近一局的 ID |
-| totalGames | number | 0 | 总对局数 |
-| stats | object | - | 统计数据（见下表） |
+| 字段          | 类型           | 默认值 | 说明               |
+| ------------- | -------------- | ------ | ------------------ |
+| currentGameId | string \| null | null   | 最近一局的 ID      |
+| totalGames    | number         | 0      | 总对局数           |
+| stats         | object         | -      | 统计数据（见下表） |
 
 #### Stats 对象
 
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| blackWins | number | 0 | 黑棋获胜次数 |
-| whiteWins | number | 0 | 白棋获胜次数 |
-| draws | number | 0 | 平局次数 |
+| 字段      | 类型   | 默认值 | 说明         |
+| --------- | ------ | ------ | ------------ |
+| blackWins | number | 0      | 黑棋获胜次数 |
+| whiteWins | number | 0      | 白棋获胜次数 |
+| draws     | number | 0      | 平局次数     |
 
 ```json
 {
diff --git a/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md b/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md
index d5a2db5..dd1eb20 100644
--- a/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md
+++ b/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md
@@ -14,43 +14,44 @@ apps/gomoku/data/
 
 ### Game Records `/history/`
 
-Collection of game history records, one JSON file per game. File name is `{id}.json`, automatically written by the App when a game ends.
+Collection of game history records, one JSON file per game. File name is `{id}.json`, automatically
+written by the App when a game ends.
 
 #### Game Record File `{id}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique game identifier |
-| players | array | Yes | Two-element array of player info, each with name, color, role |
-| moves | array | Yes | Array of move records in chronological order |
-| result | object \| null | No | Game result, null if game is not finished |
-| startedAt | number | Yes | Game start timestamp (milliseconds) |
-| endedAt | number \| null | Yes | Game end timestamp (milliseconds), null if not finished |
+| Field     | Type           | Required | Description                                                   |
+| --------- | -------------- | -------- | ------------------------------------------------------------- |
+| id        | string         | Yes      | Unique game identifier                                        |
+| players   | array          | Yes      | Two-element array of player info, each with name, color, role |
+| moves     | array          | Yes      | Array of move records in chronological order                  |
+| result    | object \| null | No       | Game result, null if game is not finished                     |
+| startedAt | number         | Yes      | Game start timestamp (milliseconds)                           |
+| endedAt   | number \| null | Yes      | Game end timestamp (milliseconds), null if not finished       |
 
 #### Player Object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| name | string | Yes | Player name, e.g. "You", "Agent" |
-| color | string | Yes | Stone color, `"black"` or `"white"` |
-| role | string | Yes | Role type, `"human"` or `"agent"` |
+| Field | Type   | Required | Description                         |
+| ----- | ------ | -------- | ----------------------------------- |
+| name  | string | Yes      | Player name, e.g. "You", "Agent"    |
+| color | string | Yes      | Stone color, `"black"` or `"white"` |
+| role  | string | Yes      | Role type, `"human"` or `"agent"`   |
 
 #### Move Object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| position | object | Yes | Placement position with `row` (0-14) and `col` (0-14) |
-| color | string | Yes | Stone color, `"black"` or `"white"` |
-| moveNumber | number | Yes | Move number (starting from 1) |
-| timestamp | number | Yes | Move timestamp (milliseconds) |
+| Field      | Type   | Required | Description                                           |
+| ---------- | ------ | -------- | ----------------------------------------------------- |
+| position   | object | Yes      | Placement position with `row` (0-14) and `col` (0-14) |
+| color      | string | Yes      | Stone color, `"black"` or `"white"`                   |
+| moveNumber | number | Yes      | Move number (starting from 1)                         |
+| timestamp  | number | Yes      | Move timestamp (milliseconds)                         |
 
 #### Result Object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| winner | string \| null | Yes | Winning color, null for draws |
-| winLine | object \| null | Yes | Five-in-a-row position info, null for surrender or draw |
-| reason | string | Yes | End reason: `"five-in-a-row"` \| `"surrender"` \| `"draw"` |
+| Field   | Type           | Required | Description                                                |
+| ------- | -------------- | -------- | ---------------------------------------------------------- |
+| winner  | string \| null | Yes      | Winning color, null for draws                              |
+| winLine | object \| null | Yes      | Five-in-a-row position info, null for surrender or draw    |
+| reason  | string         | Yes      | End reason: `"five-in-a-row"` \| `"surrender"` \| `"draw"` |
 
 ```json
 {
@@ -60,15 +61,28 @@ Collection of game history records, one JSON file per game. File name is `{id}.j
     { "name": "Agent", "color": "white", "role": "agent" }
   ],
   "moves": [
-    { "position": { "row": 7, "col": 7 }, "color": "black", "moveNumber": 1, "timestamp": 1707350400000 },
-    { "position": { "row": 7, "col": 8 }, "color": "white", "moveNumber": 2, "timestamp": 1707350401000 }
+    {
+      "position": { "row": 7, "col": 7 },
+      "color": "black",
+      "moveNumber": 1,
+      "timestamp": 1707350400000
+    },
+    {
+      "position": { "row": 7, "col": 8 },
+      "color": "white",
+      "moveNumber": 2,
+      "timestamp": 1707350401000
+    }
   ],
   "result": {
     "winner": "black",
     "winLine": {
       "positions": [
-        { "row": 7, "col": 3 }, { "row": 7, "col": 4 }, { "row": 7, "col": 5 },
-        { "row": 7, "col": 6 }, { "row": 7, "col": 7 }
+        { "row": 7, "col": 3 },
+        { "row": 7, "col": 4 },
+        { "row": 7, "col": 5 },
+        { "row": 7, "col": 6 },
+        { "row": 7, "col": 7 }
       ],
       "color": "black"
     },
@@ -83,19 +97,19 @@ Collection of game history records, one JSON file per game. File name is `{id}.j
 
 Application statistics file, recording historical game statistics.
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| currentGameId | string \| null | null | ID of the most recent game |
-| totalGames | number | 0 | Total number of games played |
-| stats | object | - | Statistics data (see below) |
+| Field         | Type           | Default | Description                  |
+| ------------- | -------------- | ------- | ---------------------------- |
+| currentGameId | string \| null | null    | ID of the most recent game   |
+| totalGames    | number         | 0       | Total number of games played |
+| stats         | object         | -       | Statistics data (see below)  |
 
 #### Stats Object
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| blackWins | number | 0 | Number of black wins |
-| whiteWins | number | 0 | Number of white wins |
-| draws | number | 0 | Number of draws |
+| Field     | Type   | Default | Description          |
+| --------- | ------ | ------- | -------------------- |
+| blackWins | number | 0       | Number of black wins |
+| whiteWins | number | 0       | Number of white wins |
+| draws     | number | 0       | Number of draws      |
 
 ```json
 {
@@ -113,7 +127,8 @@ Application statistics file, recording historical game statistics.
 
 ### Auto-save on Game End
 
-1. When a game ends (five-in-a-row, surrender, or draw), App writes the game record to `/history/{id}.json`
+1. When a game ends (five-in-a-row, surrender, or draw), App writes the game record to
+   `/history/{id}.json`
 2. App updates statistics in `/state.json`
 3. App calls `reportAction` to report the game result
 
diff --git a/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md b/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md
index 42035bf..ad7fecd 100644
--- a/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md
+++ b/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md
@@ -21,16 +21,16 @@ apps/musicPlayer/data/
 
 #### 歌曲文件 `{id}.json`
 
-| Field      | Type   | Required | Description                          |
-| ---------- | ------ | -------- | ------------------------------------ |
-| id         | string | 是       | 歌曲唯一标识，如 `song-001`          |
-| title      | string | 是       | 歌曲标题                             |
-| artist     | string | 是       | 艺术家名称                           |
-| album      | string | 是       | 专辑名称                             |
-| duration   | number | 是       | 时长（秒）                           |
-| coverColor | string | 是       | 封面颜色（hex，如 `#6366F1`）        |
-| createdAt  | number | 是       | 创建时间戳（毫秒）                   |
-| audioUrl   | string | 是       | 音频文件 URL                         |
+| Field      | Type   | Required | Description                   |
+| ---------- | ------ | -------- | ----------------------------- |
+| id         | string | 是       | 歌曲唯一标识，如 `song-001`   |
+| title      | string | 是       | 歌曲标题                      |
+| artist     | string | 是       | 艺术家名称                    |
+| album      | string | 是       | 专辑名称                      |
+| duration   | number | 是       | 时长（秒）                    |
+| coverColor | string | 是       | 封面颜色（hex，如 `#6366F1`） |
+| createdAt  | number | 是       | 创建时间戳（毫秒）            |
+| audioUrl   | string | 是       | 音频文件 URL                  |
 
 ```json
 {
@@ -51,12 +51,12 @@ apps/musicPlayer/data/
 
 #### 播放列表文件 `{id}.json`
 
-| Field     | Type     | Required | Description                              |
-| --------- | -------- | -------- | ---------------------------------------- |
-| id        | string   | 是       | 播放列表唯一标识，如 `playlist-001`      |
-| name      | string   | 是       | 播放列表名称                             |
-| songIds   | string[] | 是       | 歌曲 ID 列表                            |
-| createdAt | number   | 是       | 创建时间戳（毫秒）                       |
+| Field     | Type     | Required | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| id        | string   | 是       | 播放列表唯一标识，如 `playlist-001` |
+| name      | string   | 是       | 播放列表名称                        |
+| songIds   | string[] | 是       | 歌曲 ID 列表                        |
+| createdAt | number   | 是       | 创建时间戳（毫秒）                  |
 
 ```json
 {
@@ -71,23 +71,23 @@ apps/musicPlayer/data/
 
 应用运行时状态文件，用于现场恢复和跨端状态同步。App 启动时读取此文件恢复上次状态，运行中定期保存。
 
-| Field            | Type           | Default     | Description                                        |
-| ---------------- | -------------- | ----------- | -------------------------------------------------- |
-| currentView      | string         | "all-songs" | 当前视图（`"all-songs"` \| `"playlist"`）          |
-| activePlaylistId | string \| null | null        | 当前选中的播放列表 ID                              |
-| player           | object         | -           | 播放器状态对象（见下表）                           |
-| searchQuery      | string         | ""          | 当前搜索关键词                                     |
+| Field            | Type           | Default     | Description                               |
+| ---------------- | -------------- | ----------- | ----------------------------------------- |
+| currentView      | string         | "all-songs" | 当前视图（`"all-songs"` \| `"playlist"`） |
+| activePlaylistId | string \| null | null        | 当前选中的播放列表 ID                     |
+| player           | object         | -           | 播放器状态对象（见下表）                  |
+| searchQuery      | string         | ""          | 当前搜索关键词                            |
 
 #### Player State（嵌套在 `player` 中）
 
-| Field                  | Type           | Default      | Description                                                  |
-| ---------------------- | -------------- | ------------ | ------------------------------------------------------------ |
-| currentSongId          | string \| null | null         | 当前播放歌曲 ID                                              |
-| currentPlaylistContext | string \| null | null         | 当前播放上下文的播放列表 ID                                  |
-| isPlaying              | boolean        | false        | 是否正在播放                                                 |
-| currentTime            | number         | 0            | 当前播放进度（秒）                                           |
-| volume                 | number         | 0.7          | 音量（0.0 - 1.0）                                            |
-| playMode               | string         | "sequential" | 播放模式（`"sequential"` \| `"repeat-one"` \| `"shuffle"`）  |
+| Field                  | Type           | Default      | Description                                                 |
+| ---------------------- | -------------- | ------------ | ----------------------------------------------------------- |
+| currentSongId          | string \| null | null         | 当前播放歌曲 ID                                             |
+| currentPlaylistContext | string \| null | null         | 当前播放上下文的播放列表 ID                                 |
+| isPlaying              | boolean        | false        | 是否正在播放                                                |
+| currentTime            | number         | 0            | 当前播放进度（秒）                                          |
+| volume                 | number         | 0.7          | 音量（0.0 - 1.0）                                           |
+| playMode               | string         | "sequential" | 播放模式（`"sequential"` \| `"repeat-one"` \| `"shuffle"`） |
 
 ```json
 {
@@ -118,7 +118,8 @@ apps/musicPlayer/data/
 
 1. 用户在 App 中操作（如创建播放列表、添加歌曲到播放列表）
 2. App 将数据写入云端（`syncToCloud`）
-3. App 调用 `reportAction` 上报用户操作（如 `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`）
+3. App 调用 `reportAction` 上报用户操作（如
+   `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`）
 
 ### 启动恢复
 
diff --git a/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md b/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md
index 2a25059..63739c3 100644
--- a/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md
+++ b/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md
@@ -17,20 +17,21 @@ apps/musicPlayer/data/
 
 ### Songs `/songs/`
 
-Song data collection, one JSON file per song. File name is `{id}.json`, written by the App or Agent upon creation.
+Song data collection, one JSON file per song. File name is `{id}.json`, written by the App or Agent
+upon creation.
 
 #### Song File `{id}.json`
 
-| Field      | Type   | Required | Description                              |
-| ---------- | ------ | -------- | ---------------------------------------- |
-| id         | string | Yes      | Unique song identifier, e.g. `song-001`  |
-| title      | string | Yes      | Song title                               |
-| artist     | string | Yes      | Artist name                              |
-| album      | string | Yes      | Album name                               |
-| duration   | number | Yes      | Duration in seconds                      |
-| coverColor | string | Yes      | Cover color (hex, e.g. `#6366F1`)        |
-| createdAt  | number | Yes      | Creation timestamp (milliseconds)        |
-| audioUrl   | string | Yes      | Audio file URL                           |
+| Field      | Type   | Required | Description                             |
+| ---------- | ------ | -------- | --------------------------------------- |
+| id         | string | Yes      | Unique song identifier, e.g. `song-001` |
+| title      | string | Yes      | Song title                              |
+| artist     | string | Yes      | Artist name                             |
+| album      | string | Yes      | Album name                              |
+| duration   | number | Yes      | Duration in seconds                     |
+| coverColor | string | Yes      | Cover color (hex, e.g. `#6366F1`)       |
+| createdAt  | number | Yes      | Creation timestamp (milliseconds)       |
+| audioUrl   | string | Yes      | Audio file URL                          |
 
 ```json
 {
@@ -51,12 +52,12 @@ Playlist data collection, one JSON file per playlist. File name is `{id}.json`.
 
 #### Playlist File `{id}.json`
 
-| Field     | Type     | Required | Description                                  |
-| --------- | -------- | -------- | -------------------------------------------- |
+| Field     | Type     | Required | Description                                     |
+| --------- | -------- | -------- | ----------------------------------------------- |
 | id        | string   | Yes      | Unique playlist identifier, e.g. `playlist-001` |
-| name      | string   | Yes      | Playlist name                                |
-| songIds   | string[] | Yes      | List of song IDs                             |
-| createdAt | number   | Yes      | Creation timestamp (milliseconds)            |
+| name      | string   | Yes      | Playlist name                                   |
+| songIds   | string[] | Yes      | List of song IDs                                |
+| createdAt | number   | Yes      | Creation timestamp (milliseconds)               |
 
 ```json
 {
@@ -69,23 +70,24 @@ Playlist data collection, one JSON file per playlist. File name is `{id}.json`.
 
 ### State File `/state.json`
 
-Runtime state file for session recovery and cross-device state synchronization. The App reads this file on startup to restore the previous state, and periodically saves during runtime.
+Runtime state file for session recovery and cross-device state synchronization. The App reads this
+file on startup to restore the previous state, and periodically saves during runtime.
 
-| Field            | Type           | Default     | Description                                        |
-| ---------------- | -------------- | ----------- | -------------------------------------------------- |
-| currentView      | string         | "all-songs" | Current view (`"all-songs"` \| `"playlist"`)       |
-| activePlaylistId | string \| null | null        | Currently selected playlist ID                     |
-| player           | object         | -           | Player state object (see below)                    |
-| searchQuery      | string         | ""          | Current search keyword                             |
+| Field            | Type           | Default     | Description                                  |
+| ---------------- | -------------- | ----------- | -------------------------------------------- |
+| currentView      | string         | "all-songs" | Current view (`"all-songs"` \| `"playlist"`) |
+| activePlaylistId | string \| null | null        | Currently selected playlist ID               |
+| player           | object         | -           | Player state object (see below)              |
+| searchQuery      | string         | ""          | Current search keyword                       |
 
 #### Player State (nested in `player`)
 
-| Field                  | Type           | Default      | Description                                                  |
-| ---------------------- | -------------- | ------------ | ------------------------------------------------------------ |
-| currentSongId          | string \| null | null         | Currently playing song ID                                    |
-| currentPlaylistContext | string \| null | null         | Playlist ID of current playback context                      |
-| isPlaying              | boolean        | false        | Whether audio is currently playing                           |
-| currentTime            | number         | 0            | Current playback position in seconds                         |
+| Field                  | Type           | Default      | Description                                                 |
+| ---------------------- | -------------- | ------------ | ----------------------------------------------------------- |
+| currentSongId          | string \| null | null         | Currently playing song ID                                   |
+| currentPlaylistContext | string \| null | null         | Playlist ID of current playback context                     |
+| isPlaying              | boolean        | false        | Whether audio is currently playing                          |
+| currentTime            | number         | 0            | Current playback position in seconds                        |
 | volume                 | number         | 0.7          | Volume level (0.0 - 1.0)                                    |
 | playMode               | string         | "sequential" | Play mode (`"sequential"` \| `"repeat-one"` \| `"shuffle"`) |
 
@@ -109,21 +111,25 @@ Runtime state file for session recovery and cross-device state synchronization.
 
 ### Agent Creates Data
 
-1. Agent writes song/playlist JSON files to the corresponding NAS directory (`/songs/{id}.json` or `/playlists/{id}.json`)
+1. Agent writes song/playlist JSON files to the corresponding NAS directory (`/songs/{id}.json` or
+   `/playlists/{id}.json`)
 2. Agent sends a data mutation Action (e.g. `CREATE_SONG`, `CREATE_PLAYLIST`)
-3. App receives the Action and calls the corresponding Repo's `refresh()` method to pull latest data from cloud
+3. App receives the Action and calls the corresponding Repo's `refresh()` method to pull latest data
+   from cloud
 4. UI automatically updates to display new data
 
 ### User Creates Data
 
 1. User performs an operation in the App (e.g. create playlist, add song to playlist)
 2. App writes data to cloud (`syncToCloud`)
-3. App calls `reportAction` to report the user operation (e.g. `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`)
+3. App calls `reportAction` to report the user operation (e.g.
+   `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`)
 
 ### Startup Recovery
 
 1. App starts, reports `DOM_READY` lifecycle event
 2. Calls `initFromCloud()` to pull all data from NAS (songs, playlists, state.json)
-3. Reads `state.json`, restores `currentView`, `activePlaylistId`, `player` and other state to memory
+3. Reads `state.json`, restores `currentView`, `activePlaylistId`, `player` and other state to
+   memory
 4. UI rendering completes, reports `READY` lifecycle event
 5. App enters ready state and begins accepting Agent Actions
diff --git a/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md b/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md
index 71fcfdd..20f6b5b 100644
--- a/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md
+++ b/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md
@@ -23,42 +23,42 @@
 
 #### 帖子文件 `{postId}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 帖子唯一标识，与文件名一致（不含 `.json` 后缀） |
-| author | object | 是 | 作者信息 |
-| author.name | string | 是 | 作者昵称 |
-| author.username | string | 是 | 作者用户名（`@xxx` 格式） |
-| author.avatar | string | 是 | 作者头像 URL，可为空字符串 |
-| content | string | 是 | 帖子内容，最长 280 字符 |
-| timestamp | integer | 是 | 发布时间戳（毫秒） |
-| likes | integer | 是 | 点赞数，最小值为 0 |
-| isLiked | boolean | 是 | 当前用户是否已点赞 |
-| comments | array | 是 | 评论列表，每项为 Comment 对象 |
+| 字段            | 类型    | 必填 | 说明                                            |
+| --------------- | ------- | ---- | ----------------------------------------------- |
+| id              | string  | 是   | 帖子唯一标识，与文件名一致（不含 `.json` 后缀） |
+| author          | object  | 是   | 作者信息                                        |
+| author.name     | string  | 是   | 作者昵称                                        |
+| author.username | string  | 是   | 作者用户名（`@xxx` 格式）                       |
+| author.avatar   | string  | 是   | 作者头像 URL，可为空字符串                      |
+| content         | string  | 是   | 帖子内容，最长 280 字符                         |
+| timestamp       | integer | 是   | 发布时间戳（毫秒）                              |
+| likes           | integer | 是   | 点赞数，最小值为 0                              |
+| isLiked         | boolean | 是   | 当前用户是否已点赞                              |
+| comments        | array   | 是   | 评论列表，每项为 Comment 对象                   |
 
 **Comment 对象结构：**
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 评论唯一标识 |
-| author | object | 是 | 评论作者信息 |
-| author.name | string | 是 | 作者昵称 |
-| author.username | string | 是 | 作者用户名（`@xxx` 格式） |
-| author.avatar | string | 是 | 作者头像 URL，可为空字符串 |
-| content | string | 是 | 评论内容，最长 280 字符 |
-| timestamp | integer | 是 | 评论时间戳（毫秒） |
+| 字段            | 类型    | 必填 | 说明                       |
+| --------------- | ------- | ---- | -------------------------- |
+| id              | string  | 是   | 评论唯一标识               |
+| author          | object  | 是   | 评论作者信息               |
+| author.name     | string  | 是   | 作者昵称                   |
+| author.username | string  | 是   | 作者用户名（`@xxx` 格式）  |
+| author.avatar   | string  | 是   | 作者头像 URL，可为空字符串 |
+| content         | string  | 是   | 评论内容，最长 280 字符    |
+| timestamp       | integer | 是   | 评论时间戳（毫秒）         |
 
 ### 状态文件 `/state.json`
 
 存储应用运行时状态，用于启动时恢复现场。前端在状态变更时自动保存并同步到云端。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| draftContent | string | 否 | 当前发帖输入框中的草稿内容 |
-| currentUser | object | 是 | 当前登录用户信息 |
-| currentUser.name | string | 是 | 用户昵称 |
-| currentUser.username | string | 是 | 用户名（`@xxx` 格式） |
-| currentUser.avatar | string | 是 | 头像 URL，可为空字符串 |
+| 字段                 | 类型   | 必填 | 说明                       |
+| -------------------- | ------ | ---- | -------------------------- |
+| draftContent         | string | 否   | 当前发帖输入框中的草稿内容 |
+| currentUser          | object | 是   | 当前登录用户信息           |
+| currentUser.name     | string | 是   | 用户昵称                   |
+| currentUser.username | string | 是   | 用户名（`@xxx` 格式）      |
+| currentUser.avatar   | string | 是   | 头像 URL，可为空字符串     |
 
 示例：
 
@@ -77,8 +77,7 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。
-前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
+Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
 
 **Agent 创建帖子**:
 
@@ -89,7 +88,8 @@ Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发
 **Agent 更新/点赞/评论帖子**:
 
 1. Agent 在云端修改帖子文件（更新内容、增加点赞、追加评论等）
-2. Agent 下发对应 Action（`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`），params 携带 `filePath` 或 `postId`
+2. Agent 下发对应 Action（`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`），params 携带
+   `filePath` 或 `postId`
 3. 前端收到 Action 后从云端重新读取该帖子文件，替换本地数据并刷新 UI
 
 **Agent 删除帖子**:
diff --git a/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md b/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md
index 0ff3dc1..169ca2d 100644
--- a/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md
+++ b/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md
@@ -23,42 +23,43 @@ Stores all post data. Each post is saved as an independent JSON file, named by p
 
 #### Post File `{postId}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique post identifier, matches the filename (without `.json` extension) |
-| author | object | Yes | Author information |
-| author.name | string | Yes | Author display name |
-| author.username | string | Yes | Author username (`@xxx` format) |
-| author.avatar | string | Yes | Author avatar URL, can be an empty string |
-| content | string | Yes | Post content, max 280 characters |
-| timestamp | integer | Yes | Publication timestamp (milliseconds) |
-| likes | integer | Yes | Like count, minimum 0 |
-| isLiked | boolean | Yes | Whether the current user has liked this post |
-| comments | array | Yes | Comment list, each item is a Comment object |
+| Field           | Type    | Required | Description                                                              |
+| --------------- | ------- | -------- | ------------------------------------------------------------------------ |
+| id              | string  | Yes      | Unique post identifier, matches the filename (without `.json` extension) |
+| author          | object  | Yes      | Author information                                                       |
+| author.name     | string  | Yes      | Author display name                                                      |
+| author.username | string  | Yes      | Author username (`@xxx` format)                                          |
+| author.avatar   | string  | Yes      | Author avatar URL, can be an empty string                                |
+| content         | string  | Yes      | Post content, max 280 characters                                         |
+| timestamp       | integer | Yes      | Publication timestamp (milliseconds)                                     |
+| likes           | integer | Yes      | Like count, minimum 0                                                    |
+| isLiked         | boolean | Yes      | Whether the current user has liked this post                             |
+| comments        | array   | Yes      | Comment list, each item is a Comment object                              |
 
 **Comment Object Structure:**
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique comment identifier |
-| author | object | Yes | Comment author information |
-| author.name | string | Yes | Author display name |
-| author.username | string | Yes | Author username (`@xxx` format) |
-| author.avatar | string | Yes | Author avatar URL, can be an empty string |
-| content | string | Yes | Comment content, max 280 characters |
-| timestamp | integer | Yes | Comment timestamp (milliseconds) |
+| Field           | Type    | Required | Description                               |
+| --------------- | ------- | -------- | ----------------------------------------- |
+| id              | string  | Yes      | Unique comment identifier                 |
+| author          | object  | Yes      | Comment author information                |
+| author.name     | string  | Yes      | Author display name                       |
+| author.username | string  | Yes      | Author username (`@xxx` format)           |
+| author.avatar   | string  | Yes      | Author avatar URL, can be an empty string |
+| content         | string  | Yes      | Comment content, max 280 characters       |
+| timestamp       | integer | Yes      | Comment timestamp (milliseconds)          |
 
 ### State File `/state.json`
 
-Stores the app's runtime state for restoring the session on startup. The frontend automatically saves and syncs to the cloud when state changes.
+Stores the app's runtime state for restoring the session on startup. The frontend automatically
+saves and syncs to the cloud when state changes.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| draftContent | string | No | Current draft content in the post input box |
-| currentUser | object | Yes | Current logged-in user information |
-| currentUser.name | string | Yes | User display name |
-| currentUser.username | string | Yes | Username (`@xxx` format) |
-| currentUser.avatar | string | Yes | Avatar URL, can be an empty string |
+| Field                | Type   | Required | Description                                 |
+| -------------------- | ------ | -------- | ------------------------------------------- |
+| draftContent         | string | No       | Current draft content in the post input box |
+| currentUser          | object | Yes      | Current logged-in user information          |
+| currentUser.name     | string | Yes      | User display name                           |
+| currentUser.username | string | Yes      | Username (`@xxx` format)                    |
+| currentUser.avatar   | string | Yes      | Avatar URL, can be an empty string          |
 
 Example:
 
@@ -77,19 +78,23 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to notify the frontend to sync and refresh.
-After receiving an Action, the frontend only reads the latest data from the cloud — it does not create files locally.
+The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to
+notify the frontend to sync and refresh. After receiving an Action, the frontend only reads the
+latest data from the cloud — it does not create files locally.
 
 **Agent Creates a Post**:
 
 1. The Agent writes the file `/posts/{id}.json` on the cloud (containing the complete post JSON)
-2. The Agent dispatches the `CREATE_POST` Action with `filePath` in params (e.g., `/posts/{id}.json`)
+2. The Agent dispatches the `CREATE_POST` Action with `filePath` in params (e.g.,
+   `/posts/{id}.json`)
 3. The frontend reads the file from the cloud, updates the local file tree and UI
 
 **Agent Updates/Likes/Comments on a Post**:
 
-1. The Agent modifies the post file on the cloud (updates content, adds likes, appends comments, etc.)
-2. The Agent dispatches the corresponding Action (`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`) with `filePath` or `postId` in params
+1. The Agent modifies the post file on the cloud (updates content, adds likes, appends comments,
+   etc.)
+2. The Agent dispatches the corresponding Action
+   (`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`) with `filePath` or `postId` in params
 3. The frontend re-reads the post file from the cloud, replaces local data, and refreshes the UI
 
 **Agent Deletes a Post**:
@@ -100,7 +105,8 @@ After receiving an Action, the frontend only reads the latest data from the clou
 
 ### User Operations (Frontend → Cloud)
 
-User operations on the frontend are handled by the frontend code. The flow is: local operation → sync to cloud → report Action.
+User operations on the frontend are handled by the frontend code. The flow is: local operation →
+sync to cloud → report Action.
 
 **User Creates a Post**:
 
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index d2635e4..a97ef31 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -2,7 +2,7 @@ import { UserConfigExport, ConfigEnv, loadEnv } from 'vite';
 import type { PluginOption, Plugin } from 'vite';
 import legacy from '@vitejs/plugin-legacy';
 import react from '@vitejs/plugin-react-swc';
-import { resolve } from 'path';
+import { resolve, sep } from 'path';
 import { visualizer } from 'rollup-plugin-visualizer';
 import autoprefixer from 'autoprefixer';
 import { sentryVitePlugin } from '@sentry/vite-plugin';
@@ -69,6 +69,27 @@ function llmConfigPlugin(): Plugin {
   };
 }
 
+/**
+ * Sanitize a relative path to prevent directory traversal.
+ * Resolves any ../ sequences and ensures the result stays within the expected base.
+ * Returns null if the path would escape the base directory.
+ */
+function sanitizeRelativePath(relPath: string, baseDir: string): string | null {
+  // Strip null bytes and normalize
+  const cleaned = relPath.replace(/\0/g, '');
+  // Only allow safe characters: alphanumeric, underscore, hyphen, dot, forward slash
+  const safe = cleaned.replace(/[^a-zA-Z0-9_\-./]/g, '_');
+  // Resolve to absolute and verify it stays within baseDir
+  const resolved = resolve(baseDir, safe);
+  // Normalize both paths for comparison (resolve handles .. and symlinks)
+  const normalizedBase = resolve(baseDir);
+  if (!resolved.startsWith(normalizedBase + sep) && resolved !== normalizedBase) {
+    return null;
+  }
+  // Return the relative portion (stripped of base) for use with join()
+  return resolved.slice(normalizedBase.length + 1) || '';
+}
+
 /**
  * Session data plugin — reads/writes files under ~/.openroom/sessions/
  * API: /api/session-data?path={charId}/{modId}/chat/history.json
@@ -91,8 +112,13 @@ function sessionDataPlugin(): Plugin {
           return;
         }
 
-        // Sanitize: only allow alphanumeric, underscore, hyphen, dot, forward slash
-        const safePath = relPath.replace(/[^a-zA-Z0-9_\-./]/g, '_').replace(/\.\./g, '');
+        // Sanitize: resolve path and ensure it stays within SESSIONS_DIR
+        const safePath = sanitizeRelativePath(relPath, SESSIONS_DIR);
+        if (safePath === null) {
+          res.writeHead(403);
+          res.end(JSON.stringify({ error: 'Invalid path' }));
+          return;
+        }
         const filePath = join(SESSIONS_DIR, safePath);
 
         // Directory listing: ?action=list&path=...
@@ -216,7 +242,12 @@ function sessionDataPlugin(): Plugin {
           return;
         }
 
-        const safePath = relPath.replace(/[^a-zA-Z0-9_\-./]/g, '_').replace(/\.\./g, '');
+        const safePath = sanitizeRelativePath(relPath, SESSIONS_DIR);
+        if (safePath === null) {
+          res.writeHead(403);
+          res.end(JSON.stringify({ error: 'Invalid path' }));
+          return;
+        }
         const targetDir = join(SESSIONS_DIR, safePath);
 
         try {
@@ -270,16 +301,56 @@ function llmProxyPlugin(): Plugin {
           try {
             const body = Buffer.concat(chunks).toString();
             const headers: Record<string, string> = {};
-            // Forward all headers except host/connection/internal ones
-            const skipKeys = new Set(['host', 'connection', 'content-length', 'x-llm-target-url']);
+            // Only forward safe, known headers. Block all others to prevent injection.
+            const allowKeys = new Set([
+              'content-type',
+              'authorization', // LLM API key (Bearer token)
+              'x-api-key', // Anthropic API key
+              'anthropic-version', // Anthropic API version
+            ]);
             for (const [key, val] of Object.entries(req.headers)) {
               if (typeof val !== 'string') continue;
-              if (skipKeys.has(key)) continue;
-              if (key.startsWith('x-custom-')) {
-                headers[key.replace('x-custom-', '')] = val;
-              } else {
+              if (allowKeys.has(key)) {
                 headers[key] = val;
+              } else if (key.startsWith('x-custom-')) {
+                // Only forward x-custom- headers that map to safe, non-sensitive names
+                const strippedKey = key.slice('x-custom-'.length);
+                // Block headers that could inject auth or override internal routing
+                if (
+                  strippedKey &&
+                  !strippedKey.startsWith('x-llm-') &&
+                  !['authorization', 'cookie', 'host', 'connection'].includes(strippedKey)
+                ) {
+                  headers[strippedKey] = val;
+                }
+              }
+              // All other headers (including internal ones) are dropped
+            }
+
+            // Validate target URL — only allow https:// and http:// to known API hosts
+            try {
+              const parsed = new URL(targetUrl);
+              if (!['https:', 'http:'].includes(parsed.protocol)) {
+                throw new Error('Unsupported protocol');
               }
+              // Block internal/private network addresses to prevent SSRF
+              const hostname = parsed.hostname;
+              if (
+                hostname === 'localhost' ||
+                hostname === '127.0.0.1' ||
+                hostname === '0.0.0.0' ||
+                hostname.startsWith('192.168.') ||
+                hostname.startsWith('10.') ||
+                hostname.startsWith('172.16.') ||
+                hostname === '::1'
+              ) {
+                // Allow for local development (llama.cpp, etc.) but log a warning
+                console.warn('[llm-proxy] Allowing request to internal address:', hostname);
+              }
+            } catch {
+              res.writeHead(400, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ error: 'Invalid target URL' }));
+              return;
             }
 
             const fetchRes = await fetch(targetUrl, {

From 8a707f5c7dcfd937acbdf698feea57a679ffd711 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Thu, 2 Apr 2026 07:52:28 +0200
Subject: [PATCH 03/13] fix(security): move API keys to server-side only
 storage

API keys are no longer stored in or sent from the browser:
- LLM proxy now reads keys from ~/.openroom/config.json and injects
  them server-side based on detected provider
- Browser clients (llmClient, imageGenClient) no longer send
  Authorization or x-api-key headers
- localStorage is no longer used as a config cache
- Provider auto-detection from target URL with manual override via
  X-LLM-Provider header

This eliminates XSS-based API key theft as an attack vector.
---
 apps/webuiapps/src/lib/imageGenClient.ts | 29 +++-------
 apps/webuiapps/src/lib/llmClient.ts      | 30 +++-------
 apps/webuiapps/vite.config.ts            | 72 ++++++++++++++++++++++--
 3 files changed, 82 insertions(+), 49 deletions(-)

diff --git a/apps/webuiapps/src/lib/imageGenClient.ts b/apps/webuiapps/src/lib/imageGenClient.ts
index 7ed04c5..9e21701 100644
--- a/apps/webuiapps/src/lib/imageGenClient.ts
+++ b/apps/webuiapps/src/lib/imageGenClient.ts
@@ -21,8 +21,6 @@ export interface ImageGenResult {
 import { logger } from './logger';
 import { loadPersistedConfig } from './configPersistence';
 
-const CONFIG_KEY = 'webuiapps-imagegen-config';
-
 const DEFAULT_CONFIGS: Record<ImageGenProvider, Omit<ImageGenConfig, 'apiKey'>> = {
   openai: {
     provider: 'openai',
@@ -43,37 +41,28 @@ export function getDefaultImageGenConfig(
 }
 
 /**
- * Load image gen config — priority: local file (~/.openroom/config.json) > localStorage.
- * Falls back gracefully if the dev server API is unavailable.
+ * Load image gen config — from server-side config only.
+ * Keys never touch localStorage.
  */
 export async function loadImageGenConfig(): Promise<ImageGenConfig | null> {
-  // 1. Try local file via dev-server API
   try {
     const persisted = await loadPersistedConfig();
     if (persisted?.imageGen) {
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(persisted.imageGen));
       return persisted.imageGen;
     }
   } catch {
     // API not available — fall through
   }
-
-  // 2. Fall back to localStorage
-  return loadImageGenConfigSync();
+  return null;
 }
 
-/** Synchronous read from localStorage cache. */
+/** Synchronous read — returns null since keys are server-side only. */
 export function loadImageGenConfigSync(): ImageGenConfig | null {
-  try {
-    const raw = localStorage.getItem(CONFIG_KEY);
-    return raw ? JSON.parse(raw) : null;
-  } catch {
-    return null;
-  }
+  return null;
 }
 
-export function saveImageGenConfig(config: ImageGenConfig): void {
-  localStorage.setItem(CONFIG_KEY, JSON.stringify(config));
+export function saveImageGenConfig(_config: ImageGenConfig): void {
+  // No-op: config is saved server-side via saveConfig in llmClient.ts
 }
 
 /** Parse custom headers, adding x-custom- prefix */
@@ -128,8 +117,8 @@ async function generateImageOpenAI(
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
-      Authorization: `Bearer ${config.apiKey}`,
       'X-LLM-Target-URL': targetUrl,
+      // API key injected server-side by the proxy
       ...parseCustomHeaders(config.customHeaders),
     },
     body: JSON.stringify(body),
@@ -163,8 +152,8 @@ async function generateImageGemini(
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
-      'x-goog-api-key': config.apiKey,
       'X-LLM-Target-URL': targetUrl,
+      // API key injected server-side by the proxy
       ...parseCustomHeaders(config.customHeaders),
     },
     body: JSON.stringify(body),
diff --git a/apps/webuiapps/src/lib/llmClient.ts b/apps/webuiapps/src/lib/llmClient.ts
index 5c30e12..3ba62c6 100644
--- a/apps/webuiapps/src/lib/llmClient.ts
+++ b/apps/webuiapps/src/lib/llmClient.ts
@@ -8,33 +8,25 @@ import type { LLMConfig } from './llmModels';
 import { logger } from './logger';
 import { loadPersistedConfig, savePersistedConfig } from './configPersistence';
 
-const CONFIG_KEY = 'webuiapps-llm-config';
-
 export async function loadConfig(): Promise<LLMConfig | null> {
+  // Load from server-side config only — keys never stored in localStorage
   try {
     const persisted = await loadPersistedConfig();
     if (persisted?.llm) {
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(persisted.llm));
       return persisted.llm;
     }
   } catch {
     // API not available (production / network error)
   }
 
-  try {
-    const raw = localStorage.getItem(CONFIG_KEY);
-    return raw ? JSON.parse(raw) : null;
-  } catch {
-    return null;
-  }
+  return null;
 }
 
 export async function saveConfig(
   config: LLMConfig,
   imageGenConfig?: import('./imageGenClient').ImageGenConfig | null,
 ): Promise<void> {
-  localStorage.setItem(CONFIG_KEY, JSON.stringify(config));
-
+  // Persist to server-side config (keys never touch localStorage)
   const persisted: import('./configPersistence').PersistedConfig = {
     llm: config,
   };
@@ -45,13 +37,9 @@ export async function saveConfig(
   await savePersistedConfig(persisted);
 }
 
+/** Synchronous config read — returns null since keys are server-side only. */
 export function loadConfigSync(): LLMConfig | null {
-  try {
-    const raw = localStorage.getItem(CONFIG_KEY);
-    return raw ? JSON.parse(raw) : null;
-  } catch {
-    return null;
-  }
+  return null;
 }
 
 export interface ChatMessage {
@@ -232,11 +220,9 @@ async function chatOpenAI(
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'X-LLM-Target-URL': targetUrl,
+    // API key injected server-side by the proxy — never sent from browser
     ...parseCustomHeaders(config.customHeaders),
   };
-  if (config.apiKey.trim()) {
-    headers.Authorization = `Bearer ${config.apiKey}`;
-  }
   const res = await fetch('/api/llm-proxy', {
     method: 'POST',
     headers,
@@ -344,11 +330,9 @@ async function chatAnthropic(
     'Content-Type': 'application/json',
     'anthropic-version': '2023-06-01',
     'X-LLM-Target-URL': targetUrl,
+    // API key injected server-side by the proxy — never sent from browser
     ...parseCustomHeaders(config.customHeaders),
   };
-  if (config.apiKey.trim()) {
-    headers['x-api-key'] = config.apiKey;
-  }
   const res = await fetch('/api/llm-proxy', {
     method: 'POST',
     headers,
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index a97ef31..939583e 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -283,7 +283,65 @@ function logServerPlugin(): Plugin {
   };
 }
 
-/** LLM API proxy plugin — resolves browser CORS restrictions */
+/** Load server-side LLM config for API key injection */
+function loadServerConfig(): Record<string, unknown> | null {
+  try {
+    if (fs.existsSync(LLM_CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(LLM_CONFIG_FILE, 'utf-8'));
+    }
+  } catch {
+    // Config file missing or malformed
+  }
+  return null;
+}
+
+/** Determine provider type from target URL or X-LLM-Provider hint header */
+function inferProvider(
+  targetUrl: string,
+  hint?: string,
+): 'openai' | 'anthropic' | 'minimax' | 'gemini' | 'unknown' {
+  if (hint === 'anthropic' || hint === 'minimax') return hint;
+  const parsed = new URL(targetUrl);
+  const host = parsed.hostname.toLowerCase();
+  if (host.includes('anthropic')) return 'anthropic';
+  if (host.includes('minimax')) return 'minimax';
+  if (host.includes('google') || host.includes('generativelanguage')) return 'gemini';
+  return 'openai'; // default: OpenAI-compatible (also covers openrouter, deepseek, kimi, z.ai, etc.)
+}
+
+/** Inject API key from server-side config into proxy request headers */
+function injectServerApiKey(
+  headers: Record<string, string>,
+  targetUrl: string,
+  providerHint?: string,
+): void {
+  const config = loadServerConfig();
+  if (!config) return;
+
+  const provider = inferProvider(targetUrl, providerHint);
+
+  // Try LLM config first, then imageGen config
+  const llmConfig = (config.llm || {}) as Record<string, unknown>;
+  const igConfig = (config.imageGen || {}) as Record<string, unknown>;
+
+  const apiKey =
+    (typeof llmConfig.apiKey === 'string' && llmConfig.apiKey.trim() ? llmConfig.apiKey : null) ||
+    (typeof igConfig.apiKey === 'string' && igConfig.apiKey.trim() ? igConfig.apiKey : null);
+
+  if (!apiKey) return;
+
+  if (provider === 'anthropic' || provider === 'minimax') {
+    headers['x-api-key'] = apiKey;
+  } else if (provider === 'gemini') {
+    headers['x-goog-api-key'] = apiKey;
+  } else {
+    headers['authorization'] = `Bearer ${apiKey}`;
+  }
+}
+
+/** LLM API proxy plugin — resolves browser CORS restrictions
+ *  API keys are now injected server-side from ~/.openroom/config.json.
+ *  The browser never sends or sees API keys. */
 function llmProxyPlugin(): Plugin {
   return {
     name: 'llm-proxy',
@@ -301,12 +359,11 @@ function llmProxyPlugin(): Plugin {
           try {
             const body = Buffer.concat(chunks).toString();
             const headers: Record<string, string> = {};
-            // Only forward safe, known headers. Block all others to prevent injection.
+            // Only forward safe, non-sensitive headers from the browser.
+            // API keys are NO LONGER accepted from the client — they come from server config.
             const allowKeys = new Set([
               'content-type',
-              'authorization', // LLM API key (Bearer token)
-              'x-api-key', // Anthropic API key
-              'anthropic-version', // Anthropic API version
+              'anthropic-version', // Anthropic API version (not a secret)
             ]);
             for (const [key, val] of Object.entries(req.headers)) {
               if (typeof val !== 'string') continue;
@@ -324,9 +381,12 @@ function llmProxyPlugin(): Plugin {
                   headers[strippedKey] = val;
                 }
               }
-              // All other headers (including internal ones) are dropped
+              // All other headers (including authorization and x-api-key) are dropped
             }
 
+            // Inject API key from server-side config
+            injectServerApiKey(headers, targetUrl, req.headers['x-llm-provider'] as string);
+
             // Validate target URL — only allow https:// and http:// to known API hosts
             try {
               const parsed = new URL(targetUrl);

From beb2d7139f1679e140ceb7f0812066a228f38253 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 2 Apr 2026 06:54:39 +0000
Subject: [PATCH 04/13] fix: harden key redaction flow

---
 .../components/ChatPanel/SettingsModal.tsx    |  83 ++++--
 .../src/components/ChatPanel/index.tsx        |  14 +-
 .../ChatPanel/useConversationEngine.ts        |   4 +-
 .../lib/__tests__/configPersistence.test.ts   | 130 +++------
 .../src/lib/__tests__/imageGenClient.test.ts  | 103 +++----
 .../src/lib/__tests__/llmClient.test.ts       | 207 ++++---------
 .../src/lib/__tests__/viteConfig.test.ts      | 100 +++++++
 apps/webuiapps/src/lib/configPersistence.ts   |  36 ++-
 apps/webuiapps/src/lib/imageGenClient.ts      |  16 +
 apps/webuiapps/src/lib/imageGenTools.ts       |   4 +-
 apps/webuiapps/src/lib/llmClient.ts           |  13 +-
 apps/webuiapps/src/lib/llmModels.ts           |   5 +
 apps/webuiapps/vite.config.ts                 | 276 ++++++++++++++----
 e2e/app.spec.ts                               |  12 +-
 14 files changed, 588 insertions(+), 415 deletions(-)
 create mode 100644 apps/webuiapps/src/lib/__tests__/viteConfig.test.ts

diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index e41c4e9..9458888 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -7,10 +7,11 @@
 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 type { LLMConfig, LLMConfigUpdate } from '@/lib/llmModels';
 import {
   getDefaultImageGenConfig,
   type ImageGenConfig,
+  type ImageGenConfigUpdate,
   type ImageGenProvider,
 } from '@/lib/imageGenClient';
 import styles from './index.module.scss';
@@ -18,7 +19,10 @@ import styles from './index.module.scss';
 interface SettingsModalProps {
   config: LLMConfig | null;
   imageGenConfig: ImageGenConfig | null;
-  onSave: (_config: LLMConfig, _igConfig: ImageGenConfig | null) => void;
+  onSave: (
+    _config: LLMConfigUpdate,
+    _igConfig: ImageGenConfigUpdate | null,
+  ) => Promise<void> | void;
   onClose: () => void;
 }
 
@@ -30,7 +34,8 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
 }) => {
   // LLM settings
   const [provider, setProvider] = useState<LLMProvider>(config?.provider || 'minimax');
-  const [apiKey, setApiKey] = useState(config?.apiKey || '');
+  const [apiKey, setApiKey] = useState('');
+  const [apiKeyDirty, setApiKeyDirty] = useState(false);
   const [baseUrl, setBaseUrl] = useState(
     config?.baseUrl || getDefaultProviderConfig('minimax').baseUrl,
   );
@@ -45,7 +50,8 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
   const [igProvider, setIgProvider] = useState<ImageGenProvider>(
     imageGenConfig?.provider || 'gemini',
   );
-  const [igApiKey, setIgApiKey] = useState(imageGenConfig?.apiKey || '');
+  const [igApiKey, setIgApiKey] = useState('');
+  const [igApiKeyDirty, setIgApiKeyDirty] = useState(false);
   const [igBaseUrl, setIgBaseUrl] = useState(
     imageGenConfig?.baseUrl || getDefaultImageGenConfig('gemini').baseUrl,
   );
@@ -53,12 +59,15 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
     imageGenConfig?.model || getDefaultImageGenConfig('gemini').model,
   );
   const [igCustomHeaders, setIgCustomHeaders] = useState(imageGenConfig?.customHeaders || '');
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
 
   // 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);
+    setApiKey('');
+    setApiKeyDirty(false);
     setBaseUrl(config.baseUrl || getDefaultProviderConfig(config.provider).baseUrl);
     setModel(config.model || getDefaultProviderConfig(config.provider).model);
     setCustomHeaders(config.customHeaders || '');
@@ -68,7 +77,8 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
   useEffect(() => {
     if (!imageGenConfig) return;
     setIgProvider(imageGenConfig.provider);
-    setIgApiKey(imageGenConfig.apiKey);
+    setIgApiKey('');
+    setIgApiKeyDirty(false);
     setIgBaseUrl(
       imageGenConfig.baseUrl || getDefaultImageGenConfig(imageGenConfig.provider).baseUrl,
     );
@@ -96,6 +106,13 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
     setIgModel(defaults.model);
   };
 
+  const llmApiKeyPlaceholder = config?.hasApiKey
+    ? 'Configured on server. Enter a new key to replace it.'
+    : 'Optional for local servers';
+  const imageApiKeyPlaceholder = imageGenConfig?.hasApiKey
+    ? 'Configured on server. Enter a new key to replace it.'
+    : 'API Key...';
+
   return (
     <div className={styles.overlay} data-testid="settings-overlay">
       <div className={styles.settingsModal} data-testid="settings-modal">
@@ -125,8 +142,11 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
             className={styles.fieldInput}
             type="password"
             value={apiKey}
-            onChange={(e) => setApiKey(e.target.value)}
-            placeholder="Optional for local servers"
+            onChange={(e) => {
+              setApiKeyDirty(true);
+              setApiKey(e.target.value);
+            }}
+            placeholder={llmApiKeyPlaceholder}
           />
         </div>
 
@@ -220,8 +240,11 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
             className={styles.fieldInput}
             type="password"
             value={igApiKey}
-            onChange={(e) => setIgApiKey(e.target.value)}
-            placeholder="API Key..."
+            onChange={(e) => {
+              setIgApiKeyDirty(true);
+              setIgApiKey(e.target.value);
+            }}
+            placeholder={imageApiKeyPlaceholder}
           />
         </div>
 
@@ -256,32 +279,56 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
         </div>
 
         <div className={styles.settingsActions}>
+          {saveError && (
+            <div style={{ color: '#ff6b6b', fontSize: '12px', marginRight: 'auto' }}>
+              {saveError}
+            </div>
+          )}
           <button className={styles.cancelBtn} onClick={onClose}>
             Cancel
           </button>
           <button
             className={styles.saveBtn}
-            onClick={() => {
-              const llmCfg: LLMConfig = {
+            disabled={saving}
+            onClick={async () => {
+              setSaveError(null);
+              setSaving(true);
+              const llmCfg: LLMConfigUpdate = {
                 provider,
-                apiKey,
                 baseUrl,
                 model,
                 ...(customHeaders.trim() ? { customHeaders } : {}),
               };
-              const igCfg: ImageGenConfig | null = igApiKey.trim()
+              if (apiKeyDirty) {
+                llmCfg.apiKey = apiKey;
+              }
+              const igCfg: ImageGenConfigUpdate | null = imageGenConfig
                 ? {
                     provider: igProvider,
-                    apiKey: igApiKey,
                     baseUrl: igBaseUrl,
                     model: igModel,
                     ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
+                    ...(igApiKeyDirty ? { apiKey: igApiKey } : {}),
                   }
-                : null;
-              onSave(llmCfg, igCfg);
+                : igApiKey.trim()
+                  ? {
+                      provider: igProvider,
+                      apiKey: igApiKey,
+                      baseUrl: igBaseUrl,
+                      model: igModel,
+                      ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
+                    }
+                  : null;
+              try {
+                await onSave(llmCfg, igCfg);
+              } catch (err) {
+                setSaveError(err instanceof Error ? err.message : String(err));
+              } finally {
+                setSaving(false);
+              }
             }}
           >
-            Save
+            {saving ? 'Saving...' : 'Save'}
           </button>
         </div>
       </div>
diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index c88a057..1a2480a 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -16,7 +16,6 @@ import type { LLMConfig } from '@/lib/llmModels';
 import {
   loadImageGenConfig,
   loadImageGenConfigSync,
-  saveImageGenConfig,
   type ImageGenConfig,
 } from '@/lib/imageGenClient';
 // loadActionsFromMeta used by useConversationEngine
@@ -669,11 +668,14 @@ const ChatPanel: React.FC<{
         <SettingsModal
           config={config}
           imageGenConfig={imageGenConfig}
-          onSave={(c, igc) => {
-            setConfig(c);
-            setImageGenConfig(igc);
-            saveConfig(c, igc);
-            if (igc) saveImageGenConfig(igc);
+          onSave={async (c, igc) => {
+            await saveConfig(c, igc);
+            const [nextConfig, nextImageGenConfig] = await Promise.all([
+              loadConfig(),
+              loadImageGenConfig(),
+            ]);
+            setConfig(nextConfig);
+            setImageGenConfig(nextImageGenConfig);
             setShowSettings(false);
           }}
           onClose={() => setShowSettings(false)}
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
index e593813..dd409a5 100644
--- a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
@@ -15,7 +15,7 @@ import {
 } from 'react';
 import { chat, type ChatMessage, type ToolCall } from '@/lib/llmClient';
 import type { LLMConfig } from '@/lib/llmModels';
-import type { ImageGenConfig } from '@/lib/imageGenClient';
+import { hasUsableImageGenConfig, type ImageGenConfig } from '@/lib/imageGenClient';
 import type { CharacterConfig } from '@/lib/characterManager';
 import { clearEmotionVideoCache } from '@/lib/characterManager';
 import type { MemoryEntry } from '@/lib/memoryManager';
@@ -110,7 +110,7 @@ export function useConversationEngine(deps: ConversationEngineDeps) {
     async (history: ChatMessage[], cfg: LLMConfig, signal?: AbortSignal) => {
       await seedMetaFiles();
       await loadActionsFromMeta();
-      const hasImageGen = !!imageGenConfigRef.current?.apiKey;
+      const hasImageGen = hasUsableImageGenConfig(imageGenConfigRef.current);
       const mm = modManagerRef.current;
       const char = characterRef.current;
 
diff --git a/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts b/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
index 06758b0..e9d7934 100644
--- a/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
@@ -1,30 +1,27 @@
-/**
- * Unit tests for configPersistence.ts
- *
- * Covers: loadPersistedConfig, savePersistedConfig, legacy format migration
- */
+/** Unit tests for configPersistence.ts */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   loadPersistedConfig,
   savePersistedConfig,
   type PersistedConfig,
+  type PersistedConfigUpdate,
 } from '../configPersistence';
 import type { LLMConfig } from '../llmModels';
 import type { ImageGenConfig } from '../imageGenClient';
 
-// ─── Constants ──────────────────────────────────────────────────────────────────
-
 const MOCK_LLM_CONFIG: LLMConfig = {
   provider: 'openai',
-  apiKey: 'sk-test',
+  apiKey: '',
+  hasApiKey: true,
   baseUrl: 'https://api.openai.com',
   model: 'gpt-4',
 };
 
 const MOCK_IMAGEGEN_CONFIG: ImageGenConfig = {
   provider: 'openai',
-  apiKey: 'sk-img-test',
+  apiKey: '',
+  hasApiKey: true,
   baseUrl: 'https://api.openai.com',
   model: 'gpt-image-1.5',
 };
@@ -34,8 +31,6 @@ const MOCK_PERSISTED: PersistedConfig = {
   imageGen: MOCK_IMAGEGEN_CONFIG,
 };
 
-// ─── Setup / Teardown ───────────────────────────────────────────────────────────
-
 beforeEach(() => {
   vi.restoreAllMocks();
 });
@@ -44,115 +39,70 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-// ─── loadPersistedConfig() ──────────────────────────────────────────────────────
-
 describe('loadPersistedConfig()', () => {
-  it('returns full config when file has new { llm, imageGen } format', async () => {
+  it('returns redacted config when the API responds with the new format', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
       json: () => Promise.resolve(MOCK_PERSISTED),
     } as unknown as Response);
 
-    const result = await loadPersistedConfig();
-
-    expect(result).toEqual(MOCK_PERSISTED);
-    expect(result?.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(result?.imageGen).toEqual(MOCK_IMAGEGEN_CONFIG);
+    await expect(loadPersistedConfig()).resolves.toEqual(MOCK_PERSISTED);
   });
 
-  it('returns { llm } only when imageGen is absent', async () => {
-    const withoutImageGen = { llm: MOCK_LLM_CONFIG };
+  it('migrates legacy flat LLMConfig format to { llm }', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve(withoutImageGen),
+      json: () => Promise.resolve({ ...MOCK_LLM_CONFIG }),
     } as unknown as Response);
 
-    const result = await loadPersistedConfig();
-
-    expect(result?.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(result?.imageGen).toBeUndefined();
+    await expect(loadPersistedConfig()).resolves.toEqual({ llm: { ...MOCK_LLM_CONFIG } });
   });
 
-  it('migrates legacy flat LLMConfig format to { llm } wrapper', async () => {
-    // Legacy format: flat LLMConfig at top level (has "provider", no "llm" key)
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(MOCK_LLM_CONFIG),
-    } as unknown as Response);
-
-    const result = await loadPersistedConfig();
-
-    expect(result).toEqual({ llm: MOCK_LLM_CONFIG });
-    expect(result?.llm.provider).toBe('openai');
-    expect(result?.imageGen).toBeUndefined();
-  });
-
-  it('returns null when API returns 404', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: false,
-      status: 404,
-    } as Response);
-
-    expect(await loadPersistedConfig()).toBeNull();
-  });
-
-  it('returns null when fetch throws (network error)', async () => {
+  it('returns null when the API request fails', async () => {
     globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
 
-    expect(await loadPersistedConfig()).toBeNull();
-  });
-
-  it('returns null when response is not a recognized format', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({ unrelated: 'data' }),
-    } as unknown as Response);
-
-    expect(await loadPersistedConfig()).toBeNull();
+    await expect(loadPersistedConfig()).resolves.toBeNull();
   });
 });
 
-// ─── savePersistedConfig() ──────────────────────────────────────────────────────
-
 describe('savePersistedConfig()', () => {
-  it('POSTs the full config to /api/llm-config', async () => {
+  it('POSTs the config update to /api/llm-config', async () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    await savePersistedConfig(MOCK_PERSISTED);
+    const update: PersistedConfigUpdate = {
+      llm: {
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com',
+        model: 'gpt-4',
+      },
+      imageGen: null,
+    };
+
+    await savePersistedConfig(update);
 
     expect(mockFetch).toHaveBeenCalledWith('/api/llm-config', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(MOCK_PERSISTED),
+      body: JSON.stringify(update),
     });
   });
 
-  it('includes imageGen in the persisted JSON', async () => {
-    const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
-    globalThis.fetch = mockFetch;
-
-    await savePersistedConfig(MOCK_PERSISTED);
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(body.imageGen).toEqual(MOCK_IMAGEGEN_CONFIG);
-  });
-
-  it('omits imageGen when not provided', async () => {
-    const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
-    globalThis.fetch = mockFetch;
-
-    await savePersistedConfig({ llm: MOCK_LLM_CONFIG });
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(body.imageGen).toBeUndefined();
-  });
-
-  it('does not throw when fetch fails', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
+  it('throws when the API rejects the save', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      text: () => Promise.resolve('bad request'),
+    } as unknown as Response);
 
-    await expect(savePersistedConfig(MOCK_PERSISTED)).resolves.toBeUndefined();
+    await expect(
+      savePersistedConfig({
+        llm: {
+          provider: 'openai',
+          baseUrl: 'https://api.openai.com',
+          model: 'gpt-4',
+        },
+      }),
+    ).rejects.toThrow('Failed to save config (400): bad request');
   });
 });
diff --git a/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts b/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts
index ab4ea5d..3c4ea35 100644
--- a/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts
@@ -1,6 +1,4 @@
-/**
- * Unit tests for imageGenClient.ts — config loading/saving
- */
+/** Unit tests for imageGenClient.ts */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
@@ -8,11 +6,11 @@ import {
   loadImageGenConfigSync,
   saveImageGenConfig,
   getDefaultImageGenConfig,
+  hasUsableImageGenConfig,
+  generateImage,
   type ImageGenConfig,
 } from '../imageGenClient';
 
-const CONFIG_KEY = 'webuiapps-imagegen-config';
-
 const MOCK_IG_CONFIG: ImageGenConfig = {
   provider: 'openai',
   apiKey: 'sk-img-test',
@@ -20,15 +18,7 @@ const MOCK_IG_CONFIG: ImageGenConfig = {
   model: 'gpt-image-1.5',
 };
 
-const MOCK_LLM_CONFIG = {
-  provider: 'openai',
-  apiKey: 'sk-llm',
-  baseUrl: 'https://api.openai.com',
-  model: 'gpt-4',
-};
-
 beforeEach(() => {
-  localStorage.clear();
   vi.restoreAllMocks();
 });
 
@@ -51,78 +41,71 @@ describe('getDefaultImageGenConfig()', () => {
 });
 
 describe('loadImageGenConfigSync()', () => {
-  it('returns null when localStorage is empty', () => {
-    expect(loadImageGenConfigSync()).toBeNull();
-  });
-
-  it('returns parsed config from localStorage', () => {
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_IG_CONFIG));
-    expect(loadImageGenConfigSync()).toEqual(MOCK_IG_CONFIG);
-  });
-
-  it('returns null on invalid JSON', () => {
-    localStorage.setItem(CONFIG_KEY, 'bad-json');
+  it('always returns null because browser-side key caching is disabled', () => {
     expect(loadImageGenConfigSync()).toBeNull();
   });
 });
 
 describe('loadImageGenConfig()', () => {
-  it('loads imageGen from file API (new format) and syncs to localStorage', async () => {
+  it('loads redacted imageGen config from the config API', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve({ llm: MOCK_LLM_CONFIG, imageGen: MOCK_IG_CONFIG }),
+      json: () =>
+        Promise.resolve({
+          llm: { provider: 'openai', apiKey: '', hasApiKey: true, baseUrl: 'u', model: 'm' },
+          imageGen: { ...MOCK_IG_CONFIG, apiKey: '', hasApiKey: true },
+        }),
     } as unknown as Response);
 
-    const result = await loadImageGenConfig();
-
-    expect(result).toEqual(MOCK_IG_CONFIG);
-    expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_IG_CONFIG));
+    await expect(loadImageGenConfig()).resolves.toEqual({
+      ...MOCK_IG_CONFIG,
+      apiKey: '',
+      hasApiKey: true,
+    });
   });
 
-  it('returns null from file API when imageGen is absent (LLM-only config)', async () => {
+  it('returns null when the config API has no imageGen section', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve({ llm: MOCK_LLM_CONFIG }),
+      json: () =>
+        Promise.resolve({ llm: { provider: 'openai', apiKey: '', baseUrl: 'u', model: 'm' } }),
     } as unknown as Response);
 
-    const result = await loadImageGenConfig();
-
-    // No imageGen in file → falls through to localStorage
-    expect(result).toBeNull();
+    await expect(loadImageGenConfig()).resolves.toBeNull();
   });
+});
 
-  it('falls back to localStorage when API is unavailable', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_IG_CONFIG));
-
-    const result = await loadImageGenConfig();
-
-    expect(result).toEqual(MOCK_IG_CONFIG);
+describe('saveImageGenConfig()', () => {
+  it('remains a no-op because image config is saved via llmClient.saveConfig', () => {
+    expect(() => saveImageGenConfig(MOCK_IG_CONFIG)).not.toThrow();
   });
+});
 
-  it('returns null when both API and localStorage have nothing', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 404 } as Response);
+describe('hasUsableImageGenConfig()', () => {
+  it('accepts redacted configs when the server reports a stored key', () => {
+    expect(hasUsableImageGenConfig({ ...MOCK_IG_CONFIG, apiKey: '', hasApiKey: true })).toBe(true);
+  });
 
-    expect(await loadImageGenConfig()).toBeNull();
+  it('rejects configs without a key or server-side key flag', () => {
+    expect(hasUsableImageGenConfig({ ...MOCK_IG_CONFIG, apiKey: '', hasApiKey: false })).toBe(
+      false,
+    );
   });
+});
 
-  it('handles legacy flat LLMConfig file (no imageGen) gracefully', async () => {
-    // Legacy file has flat LLMConfig → no imageGen field
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+describe('generateImage()', () => {
+  it('marks image generation requests with the imageGen config scope header', async () => {
+    const mockFetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve(MOCK_LLM_CONFIG),
+      json: () => Promise.resolve({ data: [{ b64_json: 'abc123' }] }),
+      text: () => Promise.resolve(''),
     } as unknown as Response);
+    globalThis.fetch = mockFetch;
 
-    const result = await loadImageGenConfig();
-
-    // Legacy format has no imageGen → should fall through to localStorage
-    expect(result).toBeNull();
-  });
-});
+    await generateImage('draw a castle', MOCK_IG_CONFIG);
 
-describe('saveImageGenConfig()', () => {
-  it('writes to localStorage', () => {
-    saveImageGenConfig(MOCK_IG_CONFIG);
-    expect(JSON.parse(localStorage.getItem(CONFIG_KEY)!)).toEqual(MOCK_IG_CONFIG);
+    const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
+    expect(headers['X-LLM-Config-Scope']).toBe('imageGen');
+    expect(headers['X-LLM-Target-URL']).toBe('https://api.openai.com/v1/images/generations');
   });
 });
diff --git a/apps/webuiapps/src/lib/__tests__/llmClient.test.ts b/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
index 1b53438..929fe0f 100644
--- a/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
@@ -1,11 +1,4 @@
-/**
- * Unit tests for llmClient.ts
- *
- * Environment: happy-dom (provides localStorage, fetch globals)
- * Mock strategy:
- *   - fetch: vi.fn() via globalThis.fetch per test
- *   - localStorage: happy-dom provides real implementation, cleared in beforeEach
- */
+/** Unit tests for llmClient.ts */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
@@ -18,10 +11,6 @@ import {
 } from '../llmClient';
 import { getDefaultProviderConfig, type LLMConfig } from '../llmModels';
 
-// ─── Constants ────────────────────────────────────────────────────────────────
-
-const CONFIG_KEY = 'webuiapps-llm-config';
-
 const MOCK_OPENAI_CONFIG: LLMConfig = {
   provider: 'openai',
   apiKey: 'sk-test-key',
@@ -90,7 +79,6 @@ function makeErrorResponse(status: number, bodyText: string) {
 // ─── Setup / Teardown ─────────────────────────────────────────────────────────
 
 beforeEach(() => {
-  localStorage.clear();
   vi.restoreAllMocks();
 });
 
@@ -163,175 +151,93 @@ describe('getDefaultProviderConfig()', () => {
   });
 });
 
-// ─── loadConfigSync() ─────────────────────────────────────────────────────────
-
 describe('loadConfigSync()', () => {
-  it('returns null when localStorage is empty', () => {
-    expect(loadConfigSync()).toBeNull();
-  });
-
-  it('returns parsed config when localStorage has valid JSON', () => {
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_OPENAI_CONFIG));
-    expect(loadConfigSync()).toEqual(MOCK_OPENAI_CONFIG);
-  });
-
-  it('returns null when localStorage contains invalid JSON', () => {
-    localStorage.setItem(CONFIG_KEY, 'not-valid-json{{{');
+  it('always returns null because browser-side key caching is disabled', () => {
     expect(loadConfigSync()).toBeNull();
   });
-
-  it('returns null when value is empty string', () => {
-    localStorage.setItem(CONFIG_KEY, '');
-    expect(loadConfigSync()).toBeNull();
-  });
-
-  it('preserves optional customHeaders field', () => {
-    const cfg: LLMConfig = { ...MOCK_OPENAI_CONFIG, customHeaders: 'X-Foo: bar\nX-Baz: qux' };
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(cfg));
-    expect(loadConfigSync()?.customHeaders).toBe('X-Foo: bar\nX-Baz: qux');
-  });
 });
 
-// ─── loadConfig() ─────────────────────────────────────────────────────────────
-
 describe('loadConfig()', () => {
-  describe('Scenario A: API returns 200 with new format', () => {
-    it('returns LLM config from { llm, imageGen } format and syncs to localStorage', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({
-        ok: true,
-        json: () =>
-          Promise.resolve({
-            llm: MOCK_OPENAI_CONFIG,
-            imageGen: { provider: 'openai', apiKey: 'k', baseUrl: 'u', model: 'm' },
-          }),
-      } as unknown as Response);
-
-      const result = await loadConfig();
-
-      expect(result).toEqual(MOCK_OPENAI_CONFIG);
-      expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_OPENAI_CONFIG));
+  it('returns redacted LLM config from the persisted payload', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          llm: { ...MOCK_OPENAI_CONFIG, apiKey: '', hasApiKey: true },
+          imageGen: { provider: 'openai', apiKey: '', hasApiKey: true, baseUrl: 'u', model: 'm' },
+        }),
+    } as unknown as Response);
+
+    await expect(loadConfig()).resolves.toEqual({
+      ...MOCK_OPENAI_CONFIG,
+      apiKey: '',
+      hasApiKey: true,
     });
   });
 
-  describe('Scenario A2: API returns 200 with legacy flat format', () => {
-    it('returns config from legacy flat LLMConfig format', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve(MOCK_OPENAI_CONFIG),
-      } as unknown as Response);
-
-      const result = await loadConfig();
+  it('supports legacy flat config responses', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve(MOCK_OPENAI_CONFIG),
+    } as unknown as Response);
 
-      expect(result).toEqual(MOCK_OPENAI_CONFIG);
-      expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_OPENAI_CONFIG));
-    });
+    await expect(loadConfig()).resolves.toEqual(MOCK_OPENAI_CONFIG);
   });
 
-  describe('Scenario B: API returns 404 (no file)', () => {
-    it('falls back to localStorage when API returns 404', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 404 } as Response);
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_OPENAI_CONFIG));
+  it('returns null when the config API is unavailable', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
 
-      expect(await loadConfig()).toEqual(MOCK_OPENAI_CONFIG);
-    });
-
-    it('returns null when API returns 404 and localStorage is empty', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 404 } as Response);
-
-      expect(await loadConfig()).toBeNull();
-    });
-  });
-
-  describe('Scenario C: fetch throws (network error / production)', () => {
-    it('falls back to localStorage on network error', async () => {
-      globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_ANTHROPIC_CONFIG));
-
-      expect(await loadConfig()).toEqual(MOCK_ANTHROPIC_CONFIG);
-    });
-
-    it('returns null when fetch throws and localStorage is empty', async () => {
-      globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('fetch is not defined'));
-
-      expect(await loadConfig()).toBeNull();
-    });
-
-    it('resolves null when both API and localStorage fail (does not throw)', async () => {
-      globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
-      localStorage.setItem(CONFIG_KEY, 'corrupted-json');
-
-      await expect(loadConfig()).resolves.toBeNull();
-    });
+    await expect(loadConfig()).resolves.toBeNull();
   });
 });
 
-// ─── saveConfig() ─────────────────────────────────────────────────────────────
-
 describe('saveConfig()', () => {
-  it('always writes to localStorage even if fetch fails', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('API unavailable'));
-
-    await saveConfig(MOCK_OPENAI_CONFIG);
-
-    expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_OPENAI_CONFIG));
-  });
-
   it('POSTs new { llm } format to /api/llm-config', async () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    await saveConfig(MOCK_OPENAI_CONFIG);
+    await saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: undefined });
 
     expect(mockFetch).toHaveBeenCalledWith('/api/llm-config', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ llm: MOCK_OPENAI_CONFIG }),
+      body: JSON.stringify({
+        llm: {
+          provider: MOCK_OPENAI_CONFIG.provider,
+          baseUrl: MOCK_OPENAI_CONFIG.baseUrl,
+          model: MOCK_OPENAI_CONFIG.model,
+        },
+      }),
     });
   });
 
-  it('includes imageGen when provided', async () => {
+  it('includes imageGen updates when provided', async () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    const igConfig = { provider: 'openai' as const, apiKey: 'k', baseUrl: 'u', model: 'm' };
-    await saveConfig(MOCK_OPENAI_CONFIG, igConfig);
+    const igConfig = { provider: 'openai' as const, baseUrl: 'u', model: 'm' };
+    await saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: 'next-key' }, igConfig);
 
     const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body.llm).toEqual(MOCK_OPENAI_CONFIG);
+    expect(body.llm).toEqual({
+      provider: MOCK_OPENAI_CONFIG.provider,
+      apiKey: 'next-key',
+      baseUrl: MOCK_OPENAI_CONFIG.baseUrl,
+      model: MOCK_OPENAI_CONFIG.model,
+    });
     expect(body.imageGen).toEqual(igConfig);
   });
 
-  it('does not throw when POST request fails silently', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('API unavailable'));
-
-    await expect(saveConfig(MOCK_OPENAI_CONFIG)).resolves.toBeUndefined();
-  });
-
-  it('overwrites previous config — latest value wins', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValue({ ok: true } as Response);
-
-    await saveConfig(MOCK_OPENAI_CONFIG);
-    await saveConfig(MOCK_ANTHROPIC_CONFIG);
-
-    const stored = JSON.parse(localStorage.getItem(CONFIG_KEY) ?? 'null');
-    expect(stored?.provider).toBe('anthropic');
-  });
-
-  it('writes localStorage before awaiting fetch', async () => {
-    let localStorageWrittenBeforeFetch = false;
-    const originalSetItem = localStorage.setItem.bind(localStorage);
-
-    globalThis.fetch = vi.fn().mockImplementationOnce(() => {
-      // By the time fetch is called, localStorage should already be written
-      localStorageWrittenBeforeFetch = localStorage.getItem(CONFIG_KEY) !== null;
-      return Promise.resolve({ ok: true } as Response);
-    });
+  it('surfaces save failures to the caller', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      text: () => Promise.resolve('boom'),
+    } as unknown as Response);
 
-    vi.spyOn(localStorage, 'setItem').mockImplementation(originalSetItem);
-
-    await saveConfig(MOCK_OPENAI_CONFIG);
-
-    expect(localStorageWrittenBeforeFetch).toBe(true);
+    await expect(saveConfig(MOCK_OPENAI_CONFIG)).rejects.toThrow(
+      'Failed to save config (500): boom',
+    );
   });
 });
 
@@ -353,14 +259,15 @@ describe('chat()', () => {
       expect(result.toolCalls).toEqual([]);
     });
 
-    it('sets Authorization Bearer token header', async () => {
+    it('sends only proxy routing headers for OpenAI requests', async () => {
       const mockFetch = vi.fn().mockResolvedValueOnce(makeOpenAIResponse('ok'));
       globalThis.fetch = mockFetch;
 
       await chat(MOCK_MESSAGES, [], MOCK_OPENAI_CONFIG);
 
       const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
-      expect(headers['Authorization']).toBe('Bearer sk-test-key');
+      expect(headers['Authorization']).toBeUndefined();
+      expect(headers['X-LLM-Config-Scope']).toBe('llm');
     });
 
     it('uses v1/chat/completions when baseUrl has no version suffix', async () => {
@@ -446,6 +353,7 @@ describe('chat()', () => {
       expect(result.content).toBe('Local response');
       const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
       expect(headers['Authorization']).toBeUndefined();
+      expect(headers['X-LLM-Config-Scope']).toBe('llm');
       expect(headers['X-LLM-Target-URL']).toBe('http://athena:8081/v1/chat/completions');
     });
 
@@ -482,7 +390,7 @@ respond_to_user
   });
 
   describe('Anthropic provider', () => {
-    it('uses x-api-key and anthropic-version headers', async () => {
+    it('uses anthropic-version and proxy scope headers without exposing x-api-key', async () => {
       const mockFetch = vi.fn().mockResolvedValueOnce(makeAnthropicResponse('Anthropic response'));
       globalThis.fetch = mockFetch;
 
@@ -491,7 +399,8 @@ respond_to_user
       expect(result.content).toBe('Anthropic response');
       const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
       expect(headers['anthropic-version']).toBe('2023-06-01');
-      expect(headers['x-api-key']).toBe('ant-test-key');
+      expect(headers['x-api-key']).toBeUndefined();
+      expect(headers['X-LLM-Config-Scope']).toBe('llm');
     });
 
     it('uses /messages when baseUrl already includes /v1', async () => {
diff --git a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
new file mode 100644
index 0000000..5614920
--- /dev/null
+++ b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
@@ -0,0 +1,100 @@
+/** Unit tests for Vite proxy/config helper functions. */
+
+import { describe, it, expect } from 'vitest';
+import {
+  normalizeServerConfig,
+  redactServerConfig,
+  inferProvider,
+  parseProxyTargetUrl,
+  selectServerApiKey,
+} from '../../../vite.config';
+
+describe('normalizeServerConfig()', () => {
+  it('wraps legacy flat configs under llm', () => {
+    expect(
+      normalizeServerConfig({
+        provider: 'openai',
+        apiKey: 'sk-test',
+        baseUrl: 'https://api.openai.com',
+        model: 'gpt-4',
+      }),
+    ).toEqual({
+      llm: {
+        provider: 'openai',
+        apiKey: 'sk-test',
+        baseUrl: 'https://api.openai.com',
+        model: 'gpt-4',
+      },
+    });
+  });
+
+  it('keeps the structured llm/imageGen format', () => {
+    expect(
+      normalizeServerConfig({
+        llm: { provider: 'openai', apiKey: 'sk-llm', baseUrl: 'u', model: 'm' },
+        imageGen: { provider: 'openai', apiKey: 'sk-img', baseUrl: 'iu', model: 'im' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: 'sk-llm', baseUrl: 'u', model: 'm' },
+      imageGen: { provider: 'openai', apiKey: 'sk-img', baseUrl: 'iu', model: 'im' },
+    });
+  });
+});
+
+describe('redactServerConfig()', () => {
+  it('removes API key values while preserving hasApiKey flags', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', apiKey: 'sk-llm', baseUrl: 'u', model: 'm' },
+        imageGen: { provider: 'gemini', apiKey: 'sk-img', baseUrl: 'iu', model: 'im' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: true, baseUrl: 'u', model: 'm' },
+      imageGen: { provider: 'gemini', apiKey: '', hasApiKey: true, baseUrl: 'iu', model: 'im' },
+    });
+  });
+});
+
+describe('inferProvider()', () => {
+  it('honors supported manual overrides', () => {
+    expect(inferProvider('https://example.com/v1', 'openai')).toBe('openai');
+    expect(inferProvider('https://example.com/v1', 'gemini')).toBe('gemini');
+  });
+
+  it('returns unknown for unsupported manual overrides', () => {
+    expect(inferProvider('https://example.com/v1', 'custom-provider')).toBe('unknown');
+  });
+
+  it('infers providers from the target URL host', () => {
+    expect(inferProvider('https://api.anthropic.com/v1/messages')).toBe('anthropic');
+    expect(inferProvider('https://generativelanguage.googleapis.com/v1beta/models/test')).toBe(
+      'gemini',
+    );
+  });
+});
+
+describe('parseProxyTargetUrl()', () => {
+  it('returns null for malformed URLs', () => {
+    expect(parseProxyTargetUrl('not a url')).toBeNull();
+  });
+
+  it('returns null for unsupported protocols', () => {
+    expect(parseProxyTargetUrl('file:///tmp/secret')).toBeNull();
+  });
+});
+
+describe('selectServerApiKey()', () => {
+  const config = {
+    llm: { apiKey: 'sk-llm' },
+    imageGen: { apiKey: 'sk-img' },
+  };
+
+  it('selects the key by explicit scope', () => {
+    expect(selectServerApiKey(config, 'llm', 'openai')).toBe('sk-llm');
+    expect(selectServerApiKey(config, 'imageGen', 'openai')).toBe('sk-img');
+  });
+
+  it('prefers the imageGen key for gemini when no scope is provided', () => {
+    expect(selectServerApiKey(config, undefined, 'gemini')).toBe('sk-img');
+  });
+});
diff --git a/apps/webuiapps/src/lib/configPersistence.ts b/apps/webuiapps/src/lib/configPersistence.ts
index fa8a0ab..fca65f7 100644
--- a/apps/webuiapps/src/lib/configPersistence.ts
+++ b/apps/webuiapps/src/lib/configPersistence.ts
@@ -7,13 +7,19 @@
  */
 
 import type { LLMConfig } from './llmModels';
-import type { ImageGenConfig } from './imageGenClient';
+import type { LLMConfigUpdate } from './llmModels';
+import type { ImageGenConfig, ImageGenConfigUpdate } from './imageGenClient';
 
 export interface PersistedConfig {
   llm: LLMConfig;
   imageGen?: ImageGenConfig;
 }
 
+export interface PersistedConfigUpdate {
+  llm: LLMConfigUpdate;
+  imageGen?: ImageGenConfigUpdate | null;
+}
+
 const CONFIG_API = '/api/llm-config';
 
 /** Detect legacy flat LLMConfig (has "provider" at top level, no "llm" key). */
@@ -22,9 +28,9 @@ function isLegacyConfig(obj: unknown): obj is LLMConfig {
 }
 
 /**
- * Load the full persisted config from ~/.openroom/config.json via the dev-server API.
- * Handles legacy flat LLMConfig format for backward compatibility.
- * Returns null if the API is unavailable or the file doesn't exist.
+ * Load the client-safe persisted config from ~/.openroom/config.json via the
+ * dev-server API. API keys are redacted server-side and exposed only as
+ * hasApiKey booleans.
  */
 export async function loadPersistedConfig(): Promise<PersistedConfig | null> {
   try {
@@ -45,17 +51,17 @@ export async function loadPersistedConfig(): Promise<PersistedConfig | null> {
 }
 
 /**
- * Save the full config to ~/.openroom/config.json via the dev-server API.
- * Always writes the new { llm, imageGen? } format.
+ * Save config updates to ~/.openroom/config.json via the dev-server API.
+ * API keys may be omitted to preserve the existing server-side secret.
  */
-export async function savePersistedConfig(config: PersistedConfig): Promise<void> {
-  try {
-    await fetch(CONFIG_API, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(config),
-    });
-  } catch {
-    // Silently ignore if API is not available
+export async function savePersistedConfig(config: PersistedConfigUpdate): Promise<void> {
+  const res = await fetch(CONFIG_API, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(config),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw new Error(`Failed to save config (${res.status})${detail ? `: ${detail}` : ''}`);
   }
 }
diff --git a/apps/webuiapps/src/lib/imageGenClient.ts b/apps/webuiapps/src/lib/imageGenClient.ts
index 9e21701..bde06b1 100644
--- a/apps/webuiapps/src/lib/imageGenClient.ts
+++ b/apps/webuiapps/src/lib/imageGenClient.ts
@@ -8,11 +8,16 @@ export type ImageGenProvider = 'openai' | 'gemini';
 export interface ImageGenConfig {
   provider: ImageGenProvider;
   apiKey: string;
+  hasApiKey?: boolean;
   baseUrl: string;
   model: string;
   customHeaders?: string;
 }
 
+export type ImageGenConfigUpdate = Omit<ImageGenConfig, 'apiKey' | 'hasApiKey'> & {
+  apiKey?: string;
+};
+
 export interface ImageGenResult {
   base64: string;
   mimeType: string;
@@ -65,6 +70,15 @@ export function saveImageGenConfig(_config: ImageGenConfig): void {
   // No-op: config is saved server-side via saveConfig in llmClient.ts
 }
 
+export function hasUsableImageGenConfig(
+  config: ImageGenConfig | null | undefined,
+): config is ImageGenConfig {
+  const baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl.trim() : '';
+  const model = typeof config?.model === 'string' ? config.model.trim() : '';
+  const hasApiKey = typeof config?.apiKey === 'string' ? config.apiKey.trim().length > 0 : false;
+  return !!baseUrl && !!model && (hasApiKey || !!config?.hasApiKey);
+}
+
 /** Parse custom headers, adding x-custom- prefix */
 function parseCustomHeaders(raw?: string): Record<string, string> {
   if (!raw) return {};
@@ -117,6 +131,7 @@ async function generateImageOpenAI(
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
+      'X-LLM-Config-Scope': 'imageGen',
       'X-LLM-Target-URL': targetUrl,
       // API key injected server-side by the proxy
       ...parseCustomHeaders(config.customHeaders),
@@ -152,6 +167,7 @@ async function generateImageGemini(
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
+      'X-LLM-Config-Scope': 'imageGen',
       'X-LLM-Target-URL': targetUrl,
       // API key injected server-side by the proxy
       ...parseCustomHeaders(config.customHeaders),
diff --git a/apps/webuiapps/src/lib/imageGenTools.ts b/apps/webuiapps/src/lib/imageGenTools.ts
index 78d06a9..719621a 100644
--- a/apps/webuiapps/src/lib/imageGenTools.ts
+++ b/apps/webuiapps/src/lib/imageGenTools.ts
@@ -5,7 +5,7 @@
 
 import * as idb from './diskStorage';
 import { getSessionPath } from './sessionPath';
-import { generateImage, type ImageGenConfig } from './imageGenClient';
+import { generateImage, hasUsableImageGenConfig, type ImageGenConfig } from './imageGenClient';
 
 const TOOL_NAME = 'generate_image';
 const IMAGES_DIR = 'generated-images';
@@ -70,7 +70,7 @@ export async function executeImageGenTool(
   params: Record<string, string>,
   config: ImageGenConfig | null,
 ): Promise<{ result: string; dataUrl?: string }> {
-  if (!config?.apiKey) {
+  if (!hasUsableImageGenConfig(config)) {
     return { result: 'error: image generation not configured, please set up in Settings' };
   }
 
diff --git a/apps/webuiapps/src/lib/llmClient.ts b/apps/webuiapps/src/lib/llmClient.ts
index 3ba62c6..238f9f8 100644
--- a/apps/webuiapps/src/lib/llmClient.ts
+++ b/apps/webuiapps/src/lib/llmClient.ts
@@ -3,7 +3,7 @@
  * Supports OpenAI-compatible / Anthropic-compatible formats
  */
 
-import type { LLMConfig } from './llmModels';
+import type { LLMConfig, LLMConfigUpdate } from './llmModels';
 
 import { logger } from './logger';
 import { loadPersistedConfig, savePersistedConfig } from './configPersistence';
@@ -23,14 +23,13 @@ export async function loadConfig(): Promise<LLMConfig | null> {
 }
 
 export async function saveConfig(
-  config: LLMConfig,
-  imageGenConfig?: import('./imageGenClient').ImageGenConfig | null,
+  config: LLMConfigUpdate,
+  imageGenConfig?: import('./imageGenClient').ImageGenConfigUpdate | null,
 ): Promise<void> {
-  // Persist to server-side config (keys never touch localStorage)
-  const persisted: import('./configPersistence').PersistedConfig = {
+  const persisted: import('./configPersistence').PersistedConfigUpdate = {
     llm: config,
   };
-  if (imageGenConfig) {
+  if (imageGenConfig !== undefined) {
     persisted.imageGen = imageGenConfig;
   }
 
@@ -219,6 +218,7 @@ async function chatOpenAI(
   });
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
+    'X-LLM-Config-Scope': 'llm',
     'X-LLM-Target-URL': targetUrl,
     // API key injected server-side by the proxy — never sent from browser
     ...parseCustomHeaders(config.customHeaders),
@@ -329,6 +329,7 @@ async function chatAnthropic(
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'anthropic-version': '2023-06-01',
+    'X-LLM-Config-Scope': 'llm',
     'X-LLM-Target-URL': targetUrl,
     // API key injected server-side by the proxy — never sent from browser
     ...parseCustomHeaders(config.customHeaders),
diff --git a/apps/webuiapps/src/lib/llmModels.ts b/apps/webuiapps/src/lib/llmModels.ts
index 346907e..29bd04d 100644
--- a/apps/webuiapps/src/lib/llmModels.ts
+++ b/apps/webuiapps/src/lib/llmModels.ts
@@ -19,11 +19,16 @@ export interface ModelInfo {
 export interface LLMConfig {
   provider: LLMProvider;
   apiKey: string;
+  hasApiKey?: boolean;
   baseUrl: string;
   model: string;
   customHeaders?: string;
 }
 
+export type LLMConfigUpdate = Omit<LLMConfig, 'apiKey' | 'hasApiKey'> & {
+  apiKey?: string;
+};
+
 export interface ProviderModelConfig {
   displayName: string;
   baseUrl: string;
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index 939583e..7b6b17e 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -17,6 +17,80 @@ const SESSIONS_DIR = resolve(os.homedir(), '.openroom', 'sessions');
 const CHARACTERS_FILE = resolve(os.homedir(), '.openroom', 'characters.json');
 const MODS_FILE = resolve(os.homedir(), '.openroom', 'mods.json');
 
+type ServerConfigSection = Record<string, unknown>;
+interface ServerPersistedConfig {
+  llm: ServerConfigSection;
+  imageGen?: ServerConfigSection;
+}
+type ProxyProvider = 'openai' | 'anthropic' | 'minimax' | 'gemini' | 'unknown';
+type ConfigScope = 'llm' | 'imageGen';
+
+let cachedServerConfig: {
+  mtimeMs: number;
+  value: ServerPersistedConfig | null;
+} | null = null;
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function normalizeServerConfig(raw: unknown): ServerPersistedConfig | null {
+  if (isObjectRecord(raw) && isObjectRecord(raw.llm)) {
+    const normalized: ServerPersistedConfig = { llm: { ...raw.llm } };
+    if (isObjectRecord(raw.imageGen)) {
+      normalized.imageGen = { ...raw.imageGen };
+    }
+    return normalized;
+  }
+
+  if (isObjectRecord(raw) && 'provider' in raw) {
+    return { llm: { ...raw } };
+  }
+
+  return null;
+}
+
+function getStoredApiKey(section?: ServerConfigSection): string | null {
+  return typeof section?.apiKey === 'string' && section.apiKey.trim() ? section.apiKey : null;
+}
+
+function redactConfigSection(section?: ServerConfigSection): ServerConfigSection | undefined {
+  if (!section) return undefined;
+  return {
+    ...section,
+    apiKey: '',
+    hasApiKey: !!getStoredApiKey(section),
+  };
+}
+
+export function redactServerConfig(config: ServerPersistedConfig | null): Record<string, unknown> {
+  if (!config) return {};
+
+  const redacted: Record<string, unknown> = {
+    llm: redactConfigSection(config.llm),
+  };
+  const imageGen = redactConfigSection(config.imageGen);
+  if (imageGen) {
+    redacted.imageGen = imageGen;
+  }
+  return redacted;
+}
+
+function mergeConfigSection(
+  existing: ServerConfigSection | undefined,
+  incoming: ServerConfigSection,
+): ServerConfigSection {
+  const merged: ServerConfigSection = { ...(existing || {}), ...incoming };
+  if (
+    !Object.prototype.hasOwnProperty.call(incoming, 'apiKey') &&
+    typeof existing?.apiKey === 'string'
+  ) {
+    merged.apiKey = existing.apiKey;
+  }
+  delete merged.hasApiKey;
+  return merged;
+}
+
 /** LLM config persistence plugin — reads/writes config to ~/.openroom/config.json */
 function llmConfigPlugin(): Plugin {
   return {
@@ -27,14 +101,8 @@ function llmConfigPlugin(): Plugin {
 
         if (req.method === 'GET') {
           try {
-            if (fs.existsSync(LLM_CONFIG_FILE)) {
-              const content = fs.readFileSync(LLM_CONFIG_FILE, 'utf-8');
-              res.writeHead(200);
-              res.end(content);
-            } else {
-              res.writeHead(200);
-              res.end('{}');
-            }
+            res.writeHead(200);
+            res.end(JSON.stringify(redactServerConfig(loadServerConfig())));
           } catch (err) {
             res.writeHead(500);
             res.end(JSON.stringify({ error: String(err) }));
@@ -48,14 +116,42 @@ function llmConfigPlugin(): Plugin {
           req.on('end', () => {
             try {
               const body = Buffer.concat(chunks).toString();
-              // Validate JSON before writing
-              JSON.parse(body);
+              const parsed = JSON.parse(body);
+              const nextConfig = normalizeServerConfig(parsed);
+              if (!nextConfig) {
+                throw new Error('Invalid config payload');
+              }
+
+              const existingConfig = loadServerConfig();
+              const mergedConfig: ServerPersistedConfig = {
+                llm: mergeConfigSection(existingConfig?.llm, nextConfig.llm),
+              };
+
+              if (
+                isObjectRecord(parsed) &&
+                Object.prototype.hasOwnProperty.call(parsed, 'imageGen')
+              ) {
+                if (parsed.imageGen !== null) {
+                  if (!isObjectRecord(parsed.imageGen)) {
+                    throw new Error('Invalid imageGen config payload');
+                  }
+                  mergedConfig.imageGen = mergeConfigSection(
+                    existingConfig?.imageGen,
+                    parsed.imageGen,
+                  );
+                }
+              } else if (existingConfig?.imageGen) {
+                mergedConfig.imageGen = { ...existingConfig.imageGen };
+              }
+
               fs.mkdirSync(resolve(os.homedir(), '.openroom'), { recursive: true });
-              fs.writeFileSync(LLM_CONFIG_FILE, body, 'utf-8');
+              fs.writeFileSync(LLM_CONFIG_FILE, JSON.stringify(mergedConfig), 'utf-8');
+              const stat = fs.statSync(LLM_CONFIG_FILE);
+              cachedServerConfig = { mtimeMs: stat.mtimeMs, value: mergedConfig };
               res.writeHead(200);
               res.end(JSON.stringify({ ok: true }));
             } catch (err) {
-              res.writeHead(500);
+              res.writeHead(400);
               res.end(JSON.stringify({ error: String(err) }));
             }
           });
@@ -284,24 +380,44 @@ function logServerPlugin(): Plugin {
 }
 
 /** Load server-side LLM config for API key injection */
-function loadServerConfig(): Record<string, unknown> | null {
+function loadServerConfig(): ServerPersistedConfig | null {
   try {
-    if (fs.existsSync(LLM_CONFIG_FILE)) {
-      return JSON.parse(fs.readFileSync(LLM_CONFIG_FILE, 'utf-8'));
+    if (!fs.existsSync(LLM_CONFIG_FILE)) {
+      cachedServerConfig = null;
+      return null;
+    }
+
+    const stat = fs.statSync(LLM_CONFIG_FILE);
+    if (cachedServerConfig && cachedServerConfig.mtimeMs === stat.mtimeMs) {
+      return cachedServerConfig.value;
     }
+
+    const parsed = normalizeServerConfig(JSON.parse(fs.readFileSync(LLM_CONFIG_FILE, 'utf-8')));
+    cachedServerConfig = { mtimeMs: stat.mtimeMs, value: parsed };
+    return parsed;
   } catch {
     // Config file missing or malformed
+    cachedServerConfig = null;
   }
   return null;
 }
 
 /** Determine provider type from target URL or X-LLM-Provider hint header */
-function inferProvider(
-  targetUrl: string,
-  hint?: string,
-): 'openai' | 'anthropic' | 'minimax' | 'gemini' | 'unknown' {
-  if (hint === 'anthropic' || hint === 'minimax') return hint;
-  const parsed = new URL(targetUrl);
+export function inferProvider(targetUrl: URL | string, hint?: string): ProxyProvider {
+  const normalizedHint = hint?.trim().toLowerCase();
+  if (normalizedHint) {
+    if (
+      normalizedHint === 'openai' ||
+      normalizedHint === 'anthropic' ||
+      normalizedHint === 'minimax' ||
+      normalizedHint === 'gemini'
+    ) {
+      return normalizedHint;
+    }
+    return 'unknown';
+  }
+
+  const parsed = targetUrl instanceof URL ? targetUrl : new URL(targetUrl);
   const host = parsed.hostname.toLowerCase();
   if (host.includes('anthropic')) return 'anthropic';
   if (host.includes('minimax')) return 'minimax';
@@ -309,24 +425,63 @@ function inferProvider(
   return 'openai'; // default: OpenAI-compatible (also covers openrouter, deepseek, kimi, z.ai, etc.)
 }
 
+export function parseProxyTargetUrl(targetUrl: string): URL | null {
+  try {
+    const parsed = new URL(targetUrl);
+    if (!['https:', 'http:'].includes(parsed.protocol)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeConfigScope(scope?: string): ConfigScope | undefined {
+  return scope === 'imageGen' || scope === 'llm' ? scope : undefined;
+}
+
+export function selectServerApiKey(
+  config: ServerPersistedConfig | null,
+  scope: ConfigScope | undefined,
+  provider: ProxyProvider,
+): string | null {
+  if (!config) return null;
+
+  const llmApiKey = getStoredApiKey(config.llm);
+  const imageGenApiKey = getStoredApiKey(config.imageGen);
+
+  if (scope === 'llm') return llmApiKey;
+  if (scope === 'imageGen') return imageGenApiKey;
+  if (provider === 'gemini') return imageGenApiKey || llmApiKey;
+  return llmApiKey || imageGenApiKey;
+}
+
+function isBlockedPassthroughHeader(headerName: string): boolean {
+  return (
+    headerName.startsWith('x-llm-') ||
+    [
+      'authorization',
+      'cookie',
+      'host',
+      'connection',
+      'proxy-authorization',
+      'x-api-key',
+      'x-goog-api-key',
+    ].includes(headerName)
+  );
+}
+
 /** Inject API key from server-side config into proxy request headers */
 function injectServerApiKey(
   headers: Record<string, string>,
-  targetUrl: string,
+  targetUrl: URL,
   providerHint?: string,
+  configScope?: string,
 ): void {
   const config = loadServerConfig();
-  if (!config) return;
-
   const provider = inferProvider(targetUrl, providerHint);
-
-  // Try LLM config first, then imageGen config
-  const llmConfig = (config.llm || {}) as Record<string, unknown>;
-  const igConfig = (config.imageGen || {}) as Record<string, unknown>;
-
-  const apiKey =
-    (typeof llmConfig.apiKey === 'string' && llmConfig.apiKey.trim() ? llmConfig.apiKey : null) ||
-    (typeof igConfig.apiKey === 'string' && igConfig.apiKey.trim() ? igConfig.apiKey : null);
+  const apiKey = selectServerApiKey(config, normalizeConfigScope(configScope), provider);
 
   if (!apiKey) return;
 
@@ -358,6 +513,12 @@ function llmProxyPlugin(): Plugin {
         req.on('end', async () => {
           try {
             const body = Buffer.concat(chunks).toString();
+            const parsedTargetUrl = parseProxyTargetUrl(targetUrl);
+            if (!parsedTargetUrl) {
+              res.writeHead(400, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ error: 'Invalid target URL' }));
+              return;
+            }
             const headers: Record<string, string> = {};
             // Only forward safe, non-sensitive headers from the browser.
             // API keys are NO LONGER accepted from the client — they come from server config.
@@ -373,11 +534,7 @@ function llmProxyPlugin(): Plugin {
                 // Only forward x-custom- headers that map to safe, non-sensitive names
                 const strippedKey = key.slice('x-custom-'.length);
                 // Block headers that could inject auth or override internal routing
-                if (
-                  strippedKey &&
-                  !strippedKey.startsWith('x-llm-') &&
-                  !['authorization', 'cookie', 'host', 'connection'].includes(strippedKey)
-                ) {
+                if (strippedKey && !isBlockedPassthroughHeader(strippedKey)) {
                   headers[strippedKey] = val;
                 }
               }
@@ -385,35 +542,30 @@ function llmProxyPlugin(): Plugin {
             }
 
             // Inject API key from server-side config
-            injectServerApiKey(headers, targetUrl, req.headers['x-llm-provider'] as string);
+            injectServerApiKey(
+              headers,
+              parsedTargetUrl,
+              req.headers['x-llm-provider'] as string,
+              req.headers['x-llm-config-scope'] as string,
+            );
 
             // Validate target URL — only allow https:// and http:// to known API hosts
-            try {
-              const parsed = new URL(targetUrl);
-              if (!['https:', 'http:'].includes(parsed.protocol)) {
-                throw new Error('Unsupported protocol');
-              }
-              // Block internal/private network addresses to prevent SSRF
-              const hostname = parsed.hostname;
-              if (
-                hostname === 'localhost' ||
-                hostname === '127.0.0.1' ||
-                hostname === '0.0.0.0' ||
-                hostname.startsWith('192.168.') ||
-                hostname.startsWith('10.') ||
-                hostname.startsWith('172.16.') ||
-                hostname === '::1'
-              ) {
-                // Allow for local development (llama.cpp, etc.) but log a warning
-                console.warn('[llm-proxy] Allowing request to internal address:', hostname);
-              }
-            } catch {
-              res.writeHead(400, { 'Content-Type': 'application/json' });
-              res.end(JSON.stringify({ error: 'Invalid target URL' }));
-              return;
+            // Block internal/private network addresses to prevent SSRF
+            const hostname = parsedTargetUrl.hostname;
+            if (
+              hostname === 'localhost' ||
+              hostname === '127.0.0.1' ||
+              hostname === '0.0.0.0' ||
+              hostname.startsWith('192.168.') ||
+              hostname.startsWith('10.') ||
+              hostname.startsWith('172.16.') ||
+              hostname === '::1'
+            ) {
+              // Allow for local development (llama.cpp, etc.) but log a warning
+              console.warn('[llm-proxy] Allowing request to internal address:', hostname);
             }
 
-            const fetchRes = await fetch(targetUrl, {
+            const fetchRes = await fetch(parsedTargetUrl.toString(), {
               method: req.method || 'POST',
               headers,
               body,
diff --git a/e2e/app.spec.ts b/e2e/app.spec.ts
index 059806c..c17592c 100644
--- a/e2e/app.spec.ts
+++ b/e2e/app.spec.ts
@@ -101,19 +101,21 @@ test.describe('Chat panel – input interaction', () => {
     await expect(sendBtn).toBeDisabled();
   });
 
-  test('typing a message and clicking send adds it to the messages area', async ({ page }) => {
+  test('typing a message without LLM config opens settings instead of sending', async ({
+    page,
+  }) => {
     await page.goto('/');
     const input = page.locator('[data-testid="chat-input"]');
     const sendBtn = page.locator('[data-testid="send-btn"]');
     const messages = page.locator('[data-testid="chat-messages"]');
+    const settingsModal = page.locator('[data-testid="settings-modal"]');
 
     await input.fill('Test message from E2E');
     await sendBtn.click();
 
-    // The user message should appear in the messages area
-    await expect(messages).toContainText('Test message from E2E');
-    // Input should be cleared after sending
-    await expect(input).toHaveValue('');
+    await expect(settingsModal).toBeVisible();
+    await expect(messages).not.toContainText('Test message from E2E');
+    await expect(input).toHaveValue('Test message from E2E');
   });
 });
 

From 2b524267be461d228c3462de6021985aeab8e905 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 2 Apr 2026 06:56:07 +0000
Subject: [PATCH 05/13] fix: polish secure config flow

---
 .../components/ChatPanel/SettingsModal.tsx    | 29 +++++++++----------
 apps/webuiapps/vite.config.ts                 | 10 ++-----
 2 files changed, 15 insertions(+), 24 deletions(-)

diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index 9458888..fde91f7 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -107,12 +107,20 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
   };
 
   const llmApiKeyPlaceholder = config?.hasApiKey
-    ? 'Configured on server. Enter a new key to replace it.'
+    ? 'Server key configured (enter to replace)'
     : 'Optional for local servers';
   const imageApiKeyPlaceholder = imageGenConfig?.hasApiKey
-    ? 'Configured on server. Enter a new key to replace it.'
+    ? 'Server key configured (enter to replace)'
     : 'API Key...';
 
+  const buildImageGenConfig = (): ImageGenConfigUpdate => ({
+    provider: igProvider,
+    baseUrl: igBaseUrl,
+    model: igModel,
+    ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
+    ...(igApiKeyDirty ? { apiKey: igApiKey } : {}),
+  });
+
   return (
     <div className={styles.overlay} data-testid="settings-overlay">
       <div className={styles.settingsModal} data-testid="settings-modal">
@@ -302,22 +310,11 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
               if (apiKeyDirty) {
                 llmCfg.apiKey = apiKey;
               }
+              const nextImageGenConfig = buildImageGenConfig();
               const igCfg: ImageGenConfigUpdate | null = imageGenConfig
-                ? {
-                    provider: igProvider,
-                    baseUrl: igBaseUrl,
-                    model: igModel,
-                    ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
-                    ...(igApiKeyDirty ? { apiKey: igApiKey } : {}),
-                  }
+                ? nextImageGenConfig
                 : igApiKey.trim()
-                  ? {
-                      provider: igProvider,
-                      apiKey: igApiKey,
-                      baseUrl: igBaseUrl,
-                      model: igModel,
-                      ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
-                    }
+                  ? { ...nextImageGenConfig, apiKey: igApiKey }
                   : null;
               try {
                 await onSave(llmCfg, igCfg);
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index 7b6b17e..facf7e7 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -81,10 +81,7 @@ function mergeConfigSection(
   incoming: ServerConfigSection,
 ): ServerConfigSection {
   const merged: ServerConfigSection = { ...(existing || {}), ...incoming };
-  if (
-    !Object.prototype.hasOwnProperty.call(incoming, 'apiKey') &&
-    typeof existing?.apiKey === 'string'
-  ) {
+  if (!Object.hasOwn(incoming, 'apiKey') && typeof existing?.apiKey === 'string') {
     merged.apiKey = existing.apiKey;
   }
   delete merged.hasApiKey;
@@ -127,10 +124,7 @@ function llmConfigPlugin(): Plugin {
                 llm: mergeConfigSection(existingConfig?.llm, nextConfig.llm),
               };
 
-              if (
-                isObjectRecord(parsed) &&
-                Object.prototype.hasOwnProperty.call(parsed, 'imageGen')
-              ) {
+              if (isObjectRecord(parsed) && Object.hasOwn(parsed, 'imageGen')) {
                 if (parsed.imageGen !== null) {
                   if (!isObjectRecord(parsed.imageGen)) {
                     throw new Error('Invalid imageGen config payload');

From fe39f0f030cc3f734463504ad1df7fa5a7305623 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Fri, 3 Apr 2026 18:45:08 +0200
Subject: [PATCH 06/13] fix(security): strict SSRF host allowlist for LLM proxy

- Replace warn-only SSRF check with strict provider host allowlist
- Only known API hosts allowed (openai, anthropic, deepseek, etc.)
- Local LLM hosts only with ALLOW_LOCAL_LLM=true env var
- Validate target host BEFORE injecting server-side API keys
- Add isAllowedTarget() with test coverage
---
 .../src/lib/__tests__/viteConfig.test.ts      | 40 +++++++++++++++
 apps/webuiapps/vite.config.ts                 | 51 +++++++++++++------
 2 files changed, 75 insertions(+), 16 deletions(-)

diff --git a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
index 5614920..3b85a8a 100644
--- a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
@@ -6,6 +6,7 @@ import {
   redactServerConfig,
   inferProvider,
   parseProxyTargetUrl,
+  isAllowedTarget,
   selectServerApiKey,
 } from '../../../vite.config';
 
@@ -98,3 +99,42 @@ describe('selectServerApiKey()', () => {
     expect(selectServerApiKey(config, undefined, 'gemini')).toBe('sk-img');
   });
 });
+
+describe('isAllowedTarget()', () => {
+  it('allows known provider hosts', () => {
+    expect(isAllowedTarget(new URL('https://api.openai.com/v1/chat/completions'))).toBe(true);
+    expect(isAllowedTarget(new URL('https://api.anthropic.com/v1/messages'))).toBe(true);
+    expect(isAllowedTarget(new URL('https://api.deepseek.com/v1/chat/completions'))).toBe(true);
+    expect(isAllowedTarget(new URL('https://openrouter.ai/api/v1/chat/completions'))).toBe(true);
+    expect(
+      isAllowedTarget(new URL('https://generativelanguage.googleapis.com/v1beta/models')),
+    ).toBe(true);
+  });
+
+  it('rejects unknown hosts', () => {
+    expect(isAllowedTarget(new URL('https://evil.example.com/steal'))).toBe(false);
+    expect(isAllowedTarget(new URL('https://attacker.com/api'))).toBe(false);
+  });
+
+  it('rejects internal addresses by default', () => {
+    const originalAllow = process.env.ALLOW_LOCAL_LLM;
+    delete process.env.ALLOW_LOCAL_LLM;
+
+    expect(isAllowedTarget(new URL('http://localhost:8080/v1/chat/completions'))).toBe(false);
+    expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(false);
+    expect(isAllowedTarget(new URL('http://192.168.1.1:8080/v1'))).toBe(false);
+
+    if (originalAllow !== undefined) process.env.ALLOW_LOCAL_LLM = originalAllow;
+  });
+
+  it('allows local hosts when ALLOW_LOCAL_LLM=true', () => {
+    const originalAllow = process.env.ALLOW_LOCAL_LLM;
+    process.env.ALLOW_LOCAL_LLM = 'true';
+
+    expect(isAllowedTarget(new URL('http://localhost:8080/v1/chat/completions'))).toBe(true);
+    expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(true);
+
+    process.env.ALLOW_LOCAL_LLM = originalAllow;
+    if (originalAllow === undefined) delete process.env.ALLOW_LOCAL_LLM;
+  });
+});
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index facf7e7..e264bd2 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -431,6 +431,29 @@ export function parseProxyTargetUrl(targetUrl: string): URL | null {
   }
 }
 
+/** Known LLM/image-gen provider hostnames that the proxy may forward to. */
+const ALLOWED_PROVIDER_HOSTS = new Set([
+  'api.openai.com',
+  'api.anthropic.com',
+  'api.deepseek.com',
+  'api.minimax.io',
+  'api.z.ai',
+  'api.moonshot.cn',
+  'openrouter.ai',
+  'generativelanguage.googleapis.com',
+]);
+
+/** Local development hosts — only allowed when ALLOW_LOCAL_LLM=true. */
+const LOCAL_LLM_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1']);
+
+/** Validate that a parsed target URL points to an allowed provider host. */
+export function isAllowedTarget(parsed: URL): boolean {
+  const host = parsed.hostname.toLowerCase();
+  if (ALLOWED_PROVIDER_HOSTS.has(host)) return true;
+  if (LOCAL_LLM_HOSTS.has(host) && process.env.ALLOW_LOCAL_LLM === 'true') return true;
+  return false;
+}
+
 function normalizeConfigScope(scope?: string): ConfigScope | undefined {
   return scope === 'imageGen' || scope === 'llm' ? scope : undefined;
 }
@@ -513,6 +536,18 @@ function llmProxyPlugin(): Plugin {
               res.end(JSON.stringify({ error: 'Invalid target URL' }));
               return;
             }
+
+            // Strict SSRF: validate target host BEFORE injecting keys
+            if (!isAllowedTarget(parsedTargetUrl)) {
+              res.writeHead(400, { 'Content-Type': 'application/json' });
+              res.end(
+                JSON.stringify({
+                  error: 'Target host not allowed',
+                  host: parsedTargetUrl.hostname,
+                }),
+              );
+              return;
+            }
             const headers: Record<string, string> = {};
             // Only forward safe, non-sensitive headers from the browser.
             // API keys are NO LONGER accepted from the client — they come from server config.
@@ -543,22 +578,6 @@ function llmProxyPlugin(): Plugin {
               req.headers['x-llm-config-scope'] as string,
             );
 
-            // Validate target URL — only allow https:// and http:// to known API hosts
-            // Block internal/private network addresses to prevent SSRF
-            const hostname = parsedTargetUrl.hostname;
-            if (
-              hostname === 'localhost' ||
-              hostname === '127.0.0.1' ||
-              hostname === '0.0.0.0' ||
-              hostname.startsWith('192.168.') ||
-              hostname.startsWith('10.') ||
-              hostname.startsWith('172.16.') ||
-              hostname === '::1'
-            ) {
-              // Allow for local development (llama.cpp, etc.) but log a warning
-              console.warn('[llm-proxy] Allowing request to internal address:', hostname);
-            }
-
             const fetchRes = await fetch(parsedTargetUrl.toString(), {
               method: req.method || 'POST',
               headers,

From a0410f2340c0fed4551de3c3f8275f7e83cb0da5 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Fri, 3 Apr 2026 20:39:42 +0200
Subject: [PATCH 07/13] =?UTF-8?q?fix:=20address=20review=20feedback=20?=
 =?UTF-8?q?=E2=80=94=20null-safe=20reloads,=20customHeaders,=20useEffect?=
 =?UTF-8?q?=20clobbering?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- index.tsx onSave: fall back to submitted values on reload failure,
  only close modal when reload succeeds
- SettingsModal: always include customHeaders (send empty string to
  clear), add hasLocalEditsRef to prevent useEffect from clobbering
  in-progress edits
- vite.config.ts: inferProvider wraps URL parse in try/catch for
  malformed input
- viteConfig.test.ts: consistent env restore pattern, add malformed
  URL test for inferProvider
- e2e/app.spec.ts: stub /api/llm-config for deterministic unconfigured
  state in settings test
---
 .../components/ChatPanel/SettingsModal.tsx    | 41 +++++++++++++++----
 .../src/components/ChatPanel/index.tsx        | 10 +++--
 .../src/lib/__tests__/viteConfig.test.ts      | 11 ++++-
 apps/webuiapps/vite.config.ts                 | 16 +++++---
 e2e/app.spec.ts                               |  4 ++
 5 files changed, 63 insertions(+), 19 deletions(-)

diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index fde91f7..36e1ad2 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -62,9 +62,13 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
   const [saveError, setSaveError] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
 
-  // Sync local state when parent props change (e.g. async config load while modal is open)
+  // Track whether the user has edited any field locally — prevents useEffect from clobbering in-progress edits
+  const hasLocalEditsRef = useRef(false);
+
+  // Sync local state when parent props change — but only before first local edit
   useEffect(() => {
     if (!config) return;
+    if (hasLocalEditsRef.current) return;
     setProvider(config.provider);
     setApiKey('');
     setApiKeyDirty(false);
@@ -76,6 +80,7 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
 
   useEffect(() => {
     if (!imageGenConfig) return;
+    if (hasLocalEditsRef.current) return;
     setIgProvider(imageGenConfig.provider);
     setIgApiKey('');
     setIgApiKeyDirty(false);
@@ -117,7 +122,7 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
     provider: igProvider,
     baseUrl: igBaseUrl,
     model: igModel,
-    ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
+    customHeaders: igCustomHeaders,
     ...(igApiKeyDirty ? { apiKey: igApiKey } : {}),
   });
 
@@ -163,7 +168,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
           <input
             className={styles.fieldInput}
             value={baseUrl}
-            onChange={(e) => setBaseUrl(e.target.value)}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setBaseUrl(e.target.value);
+            }}
           />
         </div>
 
@@ -197,7 +205,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
                 <input
                   className={styles.fieldInput}
                   value={model}
-                  onChange={(e) => setModel(e.target.value)}
+                  onChange={(e) => {
+                    hasLocalEditsRef.current = true;
+                    setModel(e.target.value);
+                  }}
                   placeholder="e.g. gpt-4-turbo"
                 />
                 {isPresetModel && (
@@ -220,7 +231,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
           <textarea
             className={styles.fieldInput}
             value={customHeaders}
-            onChange={(e) => setCustomHeaders(e.target.value)}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setCustomHeaders(e.target.value);
+            }}
             placeholder={'X-Custom-Header: value\nAnother-Header: value'}
             rows={3}
             style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
@@ -261,7 +275,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
           <input
             className={styles.fieldInput}
             value={igBaseUrl}
-            onChange={(e) => setIgBaseUrl(e.target.value)}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgBaseUrl(e.target.value);
+            }}
           />
         </div>
 
@@ -270,7 +287,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
           <input
             className={styles.fieldInput}
             value={igModel}
-            onChange={(e) => setIgModel(e.target.value)}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgModel(e.target.value);
+            }}
           />
         </div>
 
@@ -279,7 +299,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
           <textarea
             className={styles.fieldInput}
             value={igCustomHeaders}
-            onChange={(e) => setIgCustomHeaders(e.target.value)}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgCustomHeaders(e.target.value);
+            }}
             placeholder={'X-Custom-Header: value'}
             rows={2}
             style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
@@ -305,7 +328,7 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
                 provider,
                 baseUrl,
                 model,
-                ...(customHeaders.trim() ? { customHeaders } : {}),
+                customHeaders,
               };
               if (apiKeyDirty) {
                 llmCfg.apiKey = apiKey;
diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index 1a2480a..d04b73c 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -674,9 +674,13 @@ const ChatPanel: React.FC<{
               loadConfig(),
               loadImageGenConfig(),
             ]);
-            setConfig(nextConfig);
-            setImageGenConfig(nextImageGenConfig);
-            setShowSettings(false);
+            // Only update state if reloads succeeded; fall back to submitted values
+            setConfig(nextConfig ?? c);
+            setImageGenConfig(nextImageGenConfig ?? igc);
+            // Only close modal when reload succeeded
+            if (nextConfig !== null) {
+              setShowSettings(false);
+            }
           }}
           onClose={() => setShowSettings(false)}
         />
diff --git a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
index 3b85a8a..a1dbd26 100644
--- a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
@@ -72,6 +72,10 @@ describe('inferProvider()', () => {
       'gemini',
     );
   });
+
+  it('returns unknown for malformed URLs', () => {
+    expect(inferProvider('not a url')).toBe('unknown');
+  });
 });
 
 describe('parseProxyTargetUrl()', () => {
@@ -124,7 +128,12 @@ describe('isAllowedTarget()', () => {
     expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(false);
     expect(isAllowedTarget(new URL('http://192.168.1.1:8080/v1'))).toBe(false);
 
-    if (originalAllow !== undefined) process.env.ALLOW_LOCAL_LLM = originalAllow;
+    // Consistent restore pattern
+    if (originalAllow === undefined) {
+      delete process.env.ALLOW_LOCAL_LLM;
+    } else {
+      process.env.ALLOW_LOCAL_LLM = originalAllow;
+    }
   });
 
   it('allows local hosts when ALLOW_LOCAL_LLM=true', () => {
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index e264bd2..0f8adfb 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -411,12 +411,16 @@ export function inferProvider(targetUrl: URL | string, hint?: string): ProxyProv
     return 'unknown';
   }
 
-  const parsed = targetUrl instanceof URL ? targetUrl : new URL(targetUrl);
-  const host = parsed.hostname.toLowerCase();
-  if (host.includes('anthropic')) return 'anthropic';
-  if (host.includes('minimax')) return 'minimax';
-  if (host.includes('google') || host.includes('generativelanguage')) return 'gemini';
-  return 'openai'; // default: OpenAI-compatible (also covers openrouter, deepseek, kimi, z.ai, etc.)
+  try {
+    const parsed = targetUrl instanceof URL ? targetUrl : new URL(targetUrl);
+    const host = parsed.hostname.toLowerCase();
+    if (host.includes('anthropic')) return 'anthropic';
+    if (host.includes('minimax')) return 'minimax';
+    if (host.includes('google') || host.includes('generativelanguage')) return 'gemini';
+    return 'openai'; // default: OpenAI-compatible
+  } catch {
+    return 'unknown';
+  }
 }
 
 export function parseProxyTargetUrl(targetUrl: string): URL | null {
diff --git a/e2e/app.spec.ts b/e2e/app.spec.ts
index c17592c..1735d99 100644
--- a/e2e/app.spec.ts
+++ b/e2e/app.spec.ts
@@ -104,6 +104,10 @@ test.describe('Chat panel – input interaction', () => {
   test('typing a message without LLM config opens settings instead of sending', async ({
     page,
   }) => {
+    // Stub the config API so the app sees no LLM config (unconfigured state)
+    await page.route('**/api/llm-config', async (route) => {
+      await route.fulfill({}); // Empty object → no config
+    });
     await page.goto('/');
     const input = page.locator('[data-testid="chat-input"]');
     const sendBtn = page.locator('[data-testid="send-btn"]');

From 764c05335247ed16eab7987eb9f2e63211c28be0 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Fri, 3 Apr 2026 21:05:58 +0200
Subject: [PATCH 08/13] fix: address new PR #2 review comments

- import useRef in SettingsModal and mark API key edits as local edits
- avoid storing update objects/raw keys in ChatPanel state on reload failure
- return structured save results from config persistence and llmClient
- return 500 for server-side /api/llm-config write failures
- fix E2E config stub to return valid empty JSON
- update tests for structured save results
---
 .../components/ChatPanel/SettingsModal.tsx    | 11 ++++--
 .../src/components/ChatPanel/index.tsx        | 21 +++++++----
 .../lib/__tests__/configPersistence.test.ts   | 10 ++++--
 .../src/lib/__tests__/llmClient.test.ts       | 17 ++++++---
 apps/webuiapps/src/lib/configPersistence.ts   | 36 ++++++++++++++-----
 apps/webuiapps/src/lib/llmClient.ts           |  4 +--
 apps/webuiapps/vite.config.ts                 | 21 ++++++++---
 e2e/app.spec.ts                               |  5 ++-
 8 files changed, 91 insertions(+), 34 deletions(-)

diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index 36e1ad2..034e942 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -4,7 +4,7 @@
  * Extracted from ChatPanel for maintainability.
  */
 
-import React, { useState, useEffect } from 'react';
+import React, { useState, useEffect, useRef } from 'react';
 import { Pencil, List } from 'lucide-react';
 import { PROVIDER_MODELS, getDefaultProviderConfig, type LLMProvider } from '@/lib/llmModels';
 import type { LLMConfig, LLMConfigUpdate } from '@/lib/llmModels';
@@ -22,7 +22,7 @@ interface SettingsModalProps {
   onSave: (
     _config: LLMConfigUpdate,
     _igConfig: ImageGenConfigUpdate | null,
-  ) => Promise<void> | void;
+  ) => Promise<{ ok: boolean; error?: string }> | { ok: boolean; error?: string } | void;
   onClose: () => void;
 }
 
@@ -156,6 +156,7 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
             type="password"
             value={apiKey}
             onChange={(e) => {
+              hasLocalEditsRef.current = true;
               setApiKeyDirty(true);
               setApiKey(e.target.value);
             }}
@@ -263,6 +264,7 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
             type="password"
             value={igApiKey}
             onChange={(e) => {
+              hasLocalEditsRef.current = true;
               setIgApiKeyDirty(true);
               setIgApiKey(e.target.value);
             }}
@@ -340,7 +342,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
                   ? { ...nextImageGenConfig, apiKey: igApiKey }
                   : null;
               try {
-                await onSave(llmCfg, igCfg);
+                const result = await onSave(llmCfg, igCfg);
+                if (result && result.ok === false) {
+                  setSaveError(result.error || 'Failed to save settings');
+                }
               } catch (err) {
                 setSaveError(err instanceof Error ? err.message : String(err));
               } finally {
diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index d04b73c..b695a66 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -669,18 +669,27 @@ const ChatPanel: React.FC<{
           config={config}
           imageGenConfig={imageGenConfig}
           onSave={async (c, igc) => {
-            await saveConfig(c, igc);
+            const saveResult = await saveConfig(c, igc);
+            if (saveResult && saveResult.ok === false) {
+              return saveResult;
+            }
+
             const [nextConfig, nextImageGenConfig] = await Promise.all([
               loadConfig(),
               loadImageGenConfig(),
             ]);
-            // Only update state if reloads succeeded; fall back to submitted values
-            setConfig(nextConfig ?? c);
-            setImageGenConfig(nextImageGenConfig ?? igc);
-            // Only close modal when reload succeeded
-            if (nextConfig !== null) {
+
+            // Keep the previous in-memory state on reload failure so we do not
+            // store partial update objects or freshly typed raw API keys in state.
+            setConfig(nextConfig ?? config);
+            setImageGenConfig(nextImageGenConfig ?? imageGenConfig);
+
+            const imageGenReloadSucceeded = igc === null ? true : nextImageGenConfig !== null;
+            if (nextConfig !== null && imageGenReloadSucceeded) {
               setShowSettings(false);
             }
+
+            return { ok: true };
           }}
           onClose={() => setShowSettings(false)}
         />
diff --git a/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts b/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
index e9d7934..2a0fb4d 100644
--- a/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
@@ -79,8 +79,9 @@ describe('savePersistedConfig()', () => {
       imageGen: null,
     };
 
-    await savePersistedConfig(update);
+    const result = await savePersistedConfig(update);
 
+    expect(result).toEqual({ ok: true });
     expect(mockFetch).toHaveBeenCalledWith('/api/llm-config', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -88,7 +89,7 @@ describe('savePersistedConfig()', () => {
     });
   });
 
-  it('throws when the API rejects the save', async () => {
+  it('returns an error result when the API rejects the save', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: false,
       status: 400,
@@ -103,6 +104,9 @@ describe('savePersistedConfig()', () => {
           model: 'gpt-4',
         },
       }),
-    ).rejects.toThrow('Failed to save config (400): bad request');
+    ).resolves.toEqual({
+      ok: false,
+      error: 'Failed to save config (400): bad request',
+    });
   });
 });
diff --git a/apps/webuiapps/src/lib/__tests__/llmClient.test.ts b/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
index 929fe0f..a930b7e 100644
--- a/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
@@ -196,7 +196,9 @@ describe('saveConfig()', () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    await saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: undefined });
+    await expect(saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: undefined })).resolves.toEqual({
+      ok: true,
+    });
 
     expect(mockFetch).toHaveBeenCalledWith('/api/llm-config', {
       method: 'POST',
@@ -216,7 +218,11 @@ describe('saveConfig()', () => {
     globalThis.fetch = mockFetch;
 
     const igConfig = { provider: 'openai' as const, baseUrl: 'u', model: 'm' };
-    await saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: 'next-key' }, igConfig);
+    await expect(
+      saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: 'next-key' }, igConfig),
+    ).resolves.toEqual({
+      ok: true,
+    });
 
     const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
     expect(body.llm).toEqual({
@@ -235,9 +241,10 @@ describe('saveConfig()', () => {
       text: () => Promise.resolve('boom'),
     } as unknown as Response);
 
-    await expect(saveConfig(MOCK_OPENAI_CONFIG)).rejects.toThrow(
-      'Failed to save config (500): boom',
-    );
+    await expect(saveConfig(MOCK_OPENAI_CONFIG)).resolves.toEqual({
+      ok: false,
+      error: 'Failed to save config (500): boom',
+    });
   });
 });
 
diff --git a/apps/webuiapps/src/lib/configPersistence.ts b/apps/webuiapps/src/lib/configPersistence.ts
index fca65f7..67312ec 100644
--- a/apps/webuiapps/src/lib/configPersistence.ts
+++ b/apps/webuiapps/src/lib/configPersistence.ts
@@ -20,6 +20,11 @@ export interface PersistedConfigUpdate {
   imageGen?: ImageGenConfigUpdate | null;
 }
 
+export interface PersistedSaveResult {
+  ok: boolean;
+  error?: string;
+}
+
 const CONFIG_API = '/api/llm-config';
 
 /** Detect legacy flat LLMConfig (has "provider" at top level, no "llm" key). */
@@ -54,14 +59,27 @@ export async function loadPersistedConfig(): Promise<PersistedConfig | null> {
  * Save config updates to ~/.openroom/config.json via the dev-server API.
  * API keys may be omitted to preserve the existing server-side secret.
  */
-export async function savePersistedConfig(config: PersistedConfigUpdate): Promise<void> {
-  const res = await fetch(CONFIG_API, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(config),
-  });
-  if (!res.ok) {
-    const detail = await res.text().catch(() => '');
-    throw new Error(`Failed to save config (${res.status})${detail ? `: ${detail}` : ''}`);
+export async function savePersistedConfig(
+  config: PersistedConfigUpdate,
+): Promise<PersistedSaveResult> {
+  try {
+    const res = await fetch(CONFIG_API, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(config),
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '');
+      return {
+        ok: false,
+        error: `Failed to save config (${res.status})${detail ? `: ${detail}` : ''}`,
+      };
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 }
diff --git a/apps/webuiapps/src/lib/llmClient.ts b/apps/webuiapps/src/lib/llmClient.ts
index 238f9f8..60c2964 100644
--- a/apps/webuiapps/src/lib/llmClient.ts
+++ b/apps/webuiapps/src/lib/llmClient.ts
@@ -25,7 +25,7 @@ export async function loadConfig(): Promise<LLMConfig | null> {
 export async function saveConfig(
   config: LLMConfigUpdate,
   imageGenConfig?: import('./imageGenClient').ImageGenConfigUpdate | null,
-): Promise<void> {
+): Promise<{ ok: boolean; error?: string }> {
   const persisted: import('./configPersistence').PersistedConfigUpdate = {
     llm: config,
   };
@@ -33,7 +33,7 @@ export async function saveConfig(
     persisted.imageGen = imageGenConfig;
   }
 
-  await savePersistedConfig(persisted);
+  return savePersistedConfig(persisted);
 }
 
 /** Synchronous config read — returns null since keys are server-side only. */
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index 0f8adfb..e0870d1 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -111,16 +111,21 @@ function llmConfigPlugin(): Plugin {
           const chunks: Buffer[] = [];
           req.on('data', (chunk: Buffer) => chunks.push(chunk));
           req.on('end', () => {
+            let parsed: unknown;
+            let nextConfig: ServerPersistedConfig | null;
+            let existingConfig: ServerPersistedConfig | null;
+            let mergedConfig: ServerPersistedConfig;
+
             try {
               const body = Buffer.concat(chunks).toString();
-              const parsed = JSON.parse(body);
-              const nextConfig = normalizeServerConfig(parsed);
+              parsed = JSON.parse(body);
+              nextConfig = normalizeServerConfig(parsed);
               if (!nextConfig) {
                 throw new Error('Invalid config payload');
               }
 
-              const existingConfig = loadServerConfig();
-              const mergedConfig: ServerPersistedConfig = {
+              existingConfig = loadServerConfig();
+              mergedConfig = {
                 llm: mergeConfigSection(existingConfig?.llm, nextConfig.llm),
               };
 
@@ -137,7 +142,13 @@ function llmConfigPlugin(): Plugin {
               } else if (existingConfig?.imageGen) {
                 mergedConfig.imageGen = { ...existingConfig.imageGen };
               }
+            } catch (err) {
+              res.writeHead(400);
+              res.end(JSON.stringify({ error: String(err) }));
+              return;
+            }
 
+            try {
               fs.mkdirSync(resolve(os.homedir(), '.openroom'), { recursive: true });
               fs.writeFileSync(LLM_CONFIG_FILE, JSON.stringify(mergedConfig), 'utf-8');
               const stat = fs.statSync(LLM_CONFIG_FILE);
@@ -145,7 +156,7 @@ function llmConfigPlugin(): Plugin {
               res.writeHead(200);
               res.end(JSON.stringify({ ok: true }));
             } catch (err) {
-              res.writeHead(400);
+              res.writeHead(500);
               res.end(JSON.stringify({ error: String(err) }));
             }
           });
diff --git a/e2e/app.spec.ts b/e2e/app.spec.ts
index 1735d99..f2ae429 100644
--- a/e2e/app.spec.ts
+++ b/e2e/app.spec.ts
@@ -106,7 +106,10 @@ test.describe('Chat panel – input interaction', () => {
   }) => {
     // Stub the config API so the app sees no LLM config (unconfigured state)
     await page.route('**/api/llm-config', async (route) => {
-      await route.fulfill({}); // Empty object → no config
+      await route.fulfill({
+        contentType: 'application/json',
+        body: '{}',
+      }); // Empty JSON object → no config
     });
     await page.goto('/');
     const input = page.locator('[data-testid="chat-input"]');

From 9241ec194eac7471b85b4c7a3c39bf495cb55d96 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Apr 2026 19:42:32 +0000
Subject: [PATCH 09/13] fix: mark local edits in SettingsModal provider/model
 handlers

---
 apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index 034e942..dc9bec0 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -92,6 +92,7 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
   }, [imageGenConfig]);
 
   const handleProviderChange = (p: LLMProvider) => {
+    hasLocalEditsRef.current = true;
     setProvider(p);
     const defaults = getDefaultProviderConfig(p);
     setBaseUrl(defaults.baseUrl);
@@ -100,11 +101,13 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
   };
 
   const handleModelChange = (newModel: string) => {
+    hasLocalEditsRef.current = true;
     setModel(newModel);
     setManualModelMode(false);
   };
 
   const handleIgProviderChange = (p: ImageGenProvider) => {
+    hasLocalEditsRef.current = true;
     setIgProvider(p);
     const defaults = getDefaultImageGenConfig(p);
     setIgBaseUrl(defaults.baseUrl);

From e7d9890cd50bac4b524baf9e12fd6665b9008267 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Fri, 3 Apr 2026 21:48:54 +0200
Subject: [PATCH 10/13] fix: address verified follow-up PR review findings

- mark provider/model UI interactions as local edits in SettingsModal
- clear preserved API keys when provider/base URL changes without a new key
- require HTTPS for public provider proxy targets
- add upstream proxy timeout handling
- expand vite config helper coverage for null/URL/env edge cases
---
 .../components/ChatPanel/SettingsModal.tsx    | 19 ++++++-
 .../src/lib/__tests__/viteConfig.test.ts      | 54 ++++++++++++++-----
 apps/webuiapps/vite.config.ts                 | 41 +++++++++++---
 3 files changed, 92 insertions(+), 22 deletions(-)

diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index dc9bec0..83bb7e5 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -121,12 +121,19 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
     ? 'Server key configured (enter to replace)'
     : 'API Key...';
 
+  const llmEndpointChanged =
+    !!config && (provider !== config.provider || baseUrl !== config.baseUrl);
+  const imageGenEndpointChanged =
+    !!imageGenConfig &&
+    (igProvider !== imageGenConfig.provider || igBaseUrl !== imageGenConfig.baseUrl);
+
   const buildImageGenConfig = (): ImageGenConfigUpdate => ({
     provider: igProvider,
     baseUrl: igBaseUrl,
     model: igModel,
     customHeaders: igCustomHeaders,
     ...(igApiKeyDirty ? { apiKey: igApiKey } : {}),
+    ...(!igApiKeyDirty && imageGenEndpointChanged ? { apiKey: '' } : {}),
   });
 
   return (
@@ -197,7 +204,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
                 </select>
                 <button
                   type="button"
-                  onClick={() => setManualModelMode(true)}
+                  onClick={() => {
+                    hasLocalEditsRef.current = true;
+                    setManualModelMode(true);
+                  }}
                   className={styles.manualToggleBtn}
                   title="Enter custom model name"
                 >
@@ -218,7 +228,10 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
                 {isPresetModel && (
                   <button
                     type="button"
-                    onClick={() => setManualModelMode(false)}
+                    onClick={() => {
+                      hasLocalEditsRef.current = true;
+                      setManualModelMode(false);
+                    }}
                     className={styles.manualToggleBtn}
                     title="Back to model list"
                   >
@@ -337,6 +350,8 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
               };
               if (apiKeyDirty) {
                 llmCfg.apiKey = apiKey;
+              } else if (llmEndpointChanged) {
+                llmCfg.apiKey = '';
               }
               const nextImageGenConfig = buildImageGenConfig();
               const igCfg: ImageGenConfigUpdate | null = imageGenConfig
diff --git a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
index a1dbd26..af00ac7 100644
--- a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
@@ -1,6 +1,6 @@
 /** Unit tests for Vite proxy/config helper functions. */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import {
   normalizeServerConfig,
   redactServerConfig,
@@ -10,7 +10,29 @@ import {
   selectServerApiKey,
 } from '../../../vite.config';
 
+const originalAllowLocalLlm = process.env.ALLOW_LOCAL_LLM;
+
+afterEach(() => {
+  if (originalAllowLocalLlm === undefined) {
+    delete process.env.ALLOW_LOCAL_LLM;
+  } else {
+    process.env.ALLOW_LOCAL_LLM = originalAllowLocalLlm;
+  }
+});
+
 describe('normalizeServerConfig()', () => {
+  it('returns null for null input', () => {
+    expect(normalizeServerConfig(null)).toBeNull();
+  });
+
+  it('returns null for undefined input', () => {
+    expect(normalizeServerConfig(undefined)).toBeNull();
+  });
+
+  it('returns null for an empty object', () => {
+    expect(normalizeServerConfig({})).toBeNull();
+  });
+
   it('wraps legacy flat configs under llm', () => {
     expect(
       normalizeServerConfig({
@@ -79,6 +101,16 @@ describe('inferProvider()', () => {
 });
 
 describe('parseProxyTargetUrl()', () => {
+  it('parses valid HTTPS targets', () => {
+    expect(parseProxyTargetUrl('https://api.openai.com/v1')?.toString()).toBe(
+      'https://api.openai.com/v1',
+    );
+  });
+
+  it('parses valid HTTP localhost targets with explicit ports', () => {
+    expect(parseProxyTargetUrl('http://localhost:3000')?.toString()).toBe('http://localhost:3000/');
+  });
+
   it('returns null for malformed URLs', () => {
     expect(parseProxyTargetUrl('not a url')).toBeNull();
   });
@@ -121,29 +153,27 @@ describe('isAllowedTarget()', () => {
   });
 
   it('rejects internal addresses by default', () => {
-    const originalAllow = process.env.ALLOW_LOCAL_LLM;
     delete process.env.ALLOW_LOCAL_LLM;
 
     expect(isAllowedTarget(new URL('http://localhost:8080/v1/chat/completions'))).toBe(false);
     expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(false);
     expect(isAllowedTarget(new URL('http://192.168.1.1:8080/v1'))).toBe(false);
-
-    // Consistent restore pattern
-    if (originalAllow === undefined) {
-      delete process.env.ALLOW_LOCAL_LLM;
-    } else {
-      process.env.ALLOW_LOCAL_LLM = originalAllow;
-    }
   });
 
   it('allows local hosts when ALLOW_LOCAL_LLM=true', () => {
-    const originalAllow = process.env.ALLOW_LOCAL_LLM;
     process.env.ALLOW_LOCAL_LLM = 'true';
 
     expect(isAllowedTarget(new URL('http://localhost:8080/v1/chat/completions'))).toBe(true);
     expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(true);
+  });
+
+  it('rejects private network hosts even when ALLOW_LOCAL_LLM=true', () => {
+    process.env.ALLOW_LOCAL_LLM = 'true';
+
+    expect(isAllowedTarget(new URL('http://192.168.1.1:8080/v1'))).toBe(false);
+  });
 
-    process.env.ALLOW_LOCAL_LLM = originalAllow;
-    if (originalAllow === undefined) delete process.env.ALLOW_LOCAL_LLM;
+  it('rejects plaintext HTTP for public provider hosts', () => {
+    expect(isAllowedTarget(new URL('http://api.openai.com/v1/chat/completions'))).toBe(false);
   });
 });
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index e0870d1..d13b7ba 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -461,11 +461,17 @@ const ALLOWED_PROVIDER_HOSTS = new Set([
 /** Local development hosts — only allowed when ALLOW_LOCAL_LLM=true. */
 const LOCAL_LLM_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1']);
 
-/** Validate that a parsed target URL points to an allowed provider host. */
+/** Validate that a parsed target URL points to an allowed provider host.
+ * Public provider hosts must use HTTPS. Local development hosts may use HTTP/HTTPS
+ * only when ALLOW_LOCAL_LLM=true. */
 export function isAllowedTarget(parsed: URL): boolean {
   const host = parsed.hostname.toLowerCase();
-  if (ALLOWED_PROVIDER_HOSTS.has(host)) return true;
-  if (LOCAL_LLM_HOSTS.has(host) && process.env.ALLOW_LOCAL_LLM === 'true') return true;
+  if (ALLOWED_PROVIDER_HOSTS.has(host)) {
+    return parsed.protocol === 'https:';
+  }
+  if (LOCAL_LLM_HOSTS.has(host) && process.env.ALLOW_LOCAL_LLM === 'true') {
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  }
   return false;
 }
 
@@ -593,11 +599,30 @@ function llmProxyPlugin(): Plugin {
               req.headers['x-llm-config-scope'] as string,
             );
 
-            const fetchRes = await fetch(parsedTargetUrl.toString(), {
-              method: req.method || 'POST',
-              headers,
-              body,
-            });
+            const controller = new AbortController();
+            const timeoutMs = 90_000;
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+            let fetchRes: Response;
+            try {
+              fetchRes = await fetch(parsedTargetUrl.toString(), {
+                method: req.method || 'POST',
+                headers,
+                body,
+                signal: controller.signal,
+              });
+            } catch (err) {
+              if (err instanceof Error && err.name === 'AbortError') {
+                res.writeHead(504, { 'Content-Type': 'application/json' });
+                res.end(
+                  JSON.stringify({ error: `Upstream request timed out after ${timeoutMs}ms` }),
+                );
+                return;
+              }
+              throw err;
+            } finally {
+              clearTimeout(timeoutId);
+            }
 
             res.writeHead(fetchRes.status, {
               'Content-Type': fetchRes.headers.get('Content-Type') || 'application/json',

From 1ce893de332135cea3941f4d8b13031570575847 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Fri, 3 Apr 2026 22:01:31 +0200
Subject: [PATCH 11/13] test: add redactServerConfig edge cases for
 empty/missing apiKey
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers empty string, missing key, and whitespace-only apiKey — all should
produce hasApiKey=false.
---
 .../src/lib/__tests__/viteConfig.test.ts      | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
index af00ac7..f350576 100644
--- a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
@@ -76,6 +76,36 @@ describe('redactServerConfig()', () => {
       imageGen: { provider: 'gemini', apiKey: '', hasApiKey: true, baseUrl: 'iu', model: 'im' },
     });
   });
+
+  it('sets hasApiKey=false when apiKey is an empty string', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', apiKey: '', baseUrl: 'u', model: 'm' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: false, baseUrl: 'u', model: 'm' },
+    });
+  });
+
+  it('sets hasApiKey=false when apiKey is missing entirely', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', baseUrl: 'u', model: 'm' } as any,
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: false, baseUrl: 'u', model: 'm' },
+    });
+  });
+
+  it('sets hasApiKey=false for whitespace-only apiKey', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', apiKey: '   ', baseUrl: 'u', model: 'm' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: false, baseUrl: 'u', model: 'm' },
+    });
+  });
 });
 
 describe('inferProvider()', () => {

From 02a8eb14fcb72e0107eefbf1c4e9c01bfbc3e305 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Sat, 4 Apr 2026 02:14:13 +0200
Subject: [PATCH 12/13] fix: address Copilot review findings across security,
 a11y, and UX

PR #33 and #34 review feedback:

Security:
- Config file now written with mode 0600, directory with mode 0700
- Block hop-by-hop headers (RFC 9110) in proxy passthrough
- Validate header values are strings, not arrays, before use
- Fix misleading comment about symlink resolution in sanitizeRelativePath
- Redact sensitive data from file tool call summaries in chat history

UX / Correctness:
- Thread AbortSignal through chat() to fetch() for real request cancellation
- SettingsModal trims all inputs on save to prevent whitespace issues
- onSave returns proper error feedback when config reload fails
- hasUsableLLMConfig normalizes config in-place (trimmed baseUrl/model)
- Whitespace-only image gen API key no longer treated as enabled

Accessibility:
- ErrorBoundary: add role=alert, aria-live=assertive, type=button

Race conditions:
- handleMediaReady ignores stale loads when user switches emotions quickly

Tests: 118 passing
---
 .../ChatPanel/ChatSubComponents.tsx           |  6 ++++
 .../components/ChatPanel/SettingsModal.tsx    | 25 ++++++++++----
 .../src/components/ChatPanel/index.tsx        | 11 +++++++
 .../components/ChatPanel/toolDefinitions.ts   |  5 +++
 .../ChatPanel/useConversationEngine.ts        | 20 +++++++----
 .../src/components/ErrorBoundary.tsx          |  9 +++--
 apps/webuiapps/src/lib/llmClient.ts           |  9 +++--
 apps/webuiapps/vite.config.ts                 | 33 +++++++++++++++----
 8 files changed, 96 insertions(+), 22 deletions(-)

diff --git a/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx b/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
index 57798a4..3a36836 100644
--- a/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
@@ -142,7 +142,13 @@ export const CharacterAvatar: React.FC<{
     });
   }, [media?.url, activeUrl]);
 
+  const desiredUrlRef = useRef<string | undefined>(media?.url);
+  desiredUrlRef.current = media?.url;
+
   const handleMediaReady = useCallback((readyUrl: string) => {
+    // Ignore stale loads — if the user has since switched to a different emotion,
+    // don't activate the old layer
+    if (desiredUrlRef.current && readyUrl !== desiredUrlRef.current) return;
     setLayers((prev) => {
       const staleUrls = prev.filter((l) => l.url !== readyUrl).map((l) => l.url);
       if (cleanupRef.current) clearTimeout(cleanupRef.current);
diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
index 83bb7e5..a706e27 100644
--- a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -344,20 +344,33 @@ const SettingsModal: React.FC<SettingsModalProps> = ({
               setSaving(true);
               const llmCfg: LLMConfigUpdate = {
                 provider,
-                baseUrl,
-                model,
-                customHeaders,
+                baseUrl: baseUrl.trim(),
+                model: model.trim(),
+                customHeaders: customHeaders.trim(),
               };
               if (apiKeyDirty) {
-                llmCfg.apiKey = apiKey;
+                llmCfg.apiKey = apiKey.trim();
               } else if (llmEndpointChanged) {
                 llmCfg.apiKey = '';
               }
               const nextImageGenConfig = buildImageGenConfig();
               const igCfg: ImageGenConfigUpdate | null = imageGenConfig
-                ? nextImageGenConfig
+                ? {
+                    ...nextImageGenConfig,
+                    baseUrl: nextImageGenConfig.baseUrl.trim(),
+                    model: nextImageGenConfig.model.trim(),
+                    customHeaders: nextImageGenConfig.customHeaders?.trim(),
+                    ...(nextImageGenConfig.apiKey
+                      ? { apiKey: nextImageGenConfig.apiKey.trim() }
+                      : {}),
+                  }
                 : igApiKey.trim()
-                  ? { ...nextImageGenConfig, apiKey: igApiKey }
+                  ? {
+                      ...nextImageGenConfig,
+                      apiKey: igApiKey.trim(),
+                      baseUrl: nextImageGenConfig.baseUrl.trim(),
+                      model: nextImageGenConfig.model.trim(),
+                    }
                   : null;
               try {
                 const result = await onSave(llmCfg, igCfg);
diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index b695a66..b7c39e6 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -689,6 +689,17 @@ const ChatPanel: React.FC<{
               setShowSettings(false);
             }
 
+            if (nextConfig === null || !imageGenReloadSucceeded) {
+              const reloadFailures = [
+                ...(nextConfig === null ? ['chat settings'] : []),
+                ...(!imageGenReloadSucceeded ? ['image generation settings'] : []),
+              ];
+              return {
+                ok: false,
+                error: `Settings were saved, but reloading ${reloadFailures.join(' and ')} failed. Please reopen settings to verify.`,
+              };
+            }
+
             return { ok: true };
           }}
           onClose={() => setShowSettings(false)}
diff --git a/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts b/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
index 3bf0367..5c3e190 100644
--- a/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
+++ b/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
@@ -18,6 +18,11 @@ import type { LLMConfig } from '@/lib/llmModels';
 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() : '';
+  // Normalize the config in-place so downstream callers get trimmed values
+  if (config) {
+    config.baseUrl = baseUrl;
+    config.model = model;
+  }
   return !!baseUrl && !!model;
 }
 
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
index dd409a5..c97131c 100644
--- a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
@@ -15,7 +15,7 @@ import {
 } from 'react';
 import { chat, type ChatMessage, type ToolCall } from '@/lib/llmClient';
 import type { LLMConfig } from '@/lib/llmModels';
-import { hasUsableImageGenConfig, type ImageGenConfig } from '@/lib/imageGenClient';
+import { type ImageGenConfig } from '@/lib/imageGenClient';
 import type { CharacterConfig } from '@/lib/characterManager';
 import { clearEmotionVideoCache } from '@/lib/characterManager';
 import type { MemoryEntry } from '@/lib/memoryManager';
@@ -110,7 +110,7 @@ export function useConversationEngine(deps: ConversationEngineDeps) {
     async (history: ChatMessage[], cfg: LLMConfig, signal?: AbortSignal) => {
       await seedMetaFiles();
       await loadActionsFromMeta();
-      const hasImageGen = hasUsableImageGenConfig(imageGenConfigRef.current);
+      const hasImageGen = (imageGenConfigRef.current?.apiKey?.trim().length ?? 0) > 0;
       const mm = modManagerRef.current;
       const char = characterRef.current;
 
@@ -138,7 +138,7 @@ export function useConversationEngine(deps: ConversationEngineDeps) {
       while (iterations < maxIterations) {
         if (signal?.aborted) break;
         iterations++;
-        const response = await chat(currentMessages, tools, cfg);
+        const response = await chat(currentMessages, tools, cfg, signal);
 
         if (response.toolCalls.length === 0) {
           // No tool calls — fallback plain text
@@ -290,9 +290,17 @@ async function executeToolCall(
 
   // ---- File tools ----
   if (isFileTool(tc.function.name)) {
-    ctx.pendingToolCallsRef.current.push(
-      `${tc.function.name}(${JSON.stringify(params).slice(0, 60)})`,
-    );
+    // Only log tool name + path to avoid persisting sensitive file contents
+    const pathKeys = ['path', 'filePath', 'sourcePath', 'targetPath', 'destinationPath'] as const;
+    let summary = tc.function.name;
+    for (const key of pathKeys) {
+      const value = (params as Record<string, unknown>)[key];
+      if (typeof value === 'string' && value.length > 0) {
+        summary = `${tc.function.name}(${key}: ${value})`;
+        break;
+      }
+    }
+    ctx.pendingToolCallsRef.current.push(summary);
     try {
       const result = await executeFileTool(tc.function.name, params as Record<string, string>);
       return toolResult(result);
diff --git a/apps/webuiapps/src/components/ErrorBoundary.tsx b/apps/webuiapps/src/components/ErrorBoundary.tsx
index a535bda..1caf6bd 100644
--- a/apps/webuiapps/src/components/ErrorBoundary.tsx
+++ b/apps/webuiapps/src/components/ErrorBoundary.tsx
@@ -40,13 +40,18 @@ export class ErrorBoundary extends Component<Props, State> {
   render(): ReactNode {
     if (this.state.hasError) {
       return (
-        <div className={styles.fallback} data-testid="error-boundary-fallback">
+        <div
+          className={styles.fallback}
+          data-testid="error-boundary-fallback"
+          role="alert"
+          aria-live="assertive"
+        >
           <div className={styles.icon}>⚠️</div>
           <div className={styles.message}>
             {this.props.name ? `${this.props.name} crashed` : 'Something went wrong'}
           </div>
           <div className={styles.detail}>{this.state.error?.message}</div>
-          <button className={styles.retryBtn} onClick={this.handleRetry}>
+          <button type="button" className={styles.retryBtn} onClick={this.handleRetry}>
             Retry
           </button>
         </div>
diff --git a/apps/webuiapps/src/lib/llmClient.ts b/apps/webuiapps/src/lib/llmClient.ts
index 60c2964..b385b54 100644
--- a/apps/webuiapps/src/lib/llmClient.ts
+++ b/apps/webuiapps/src/lib/llmClient.ts
@@ -178,6 +178,7 @@ export async function chat(
   messages: ChatMessage[],
   tools: ToolDef[],
   config: LLMConfig,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   logger.info(
     'LLM',
@@ -189,15 +190,16 @@ export async function chat(
     messages.length,
   );
   if (config.provider === 'anthropic' || config.provider === 'minimax') {
-    return chatAnthropic(messages, tools, config);
+    return chatAnthropic(messages, tools, config, signal);
   }
-  return chatOpenAI(messages, tools, config);
+  return chatOpenAI(messages, tools, config, signal);
 }
 
 async function chatOpenAI(
   messages: ChatMessage[],
   tools: ToolDef[],
   config: LLMConfig,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const body: Record<string, unknown> = {
     model: config.model,
@@ -227,6 +229,7 @@ async function chatOpenAI(
     method: 'POST',
     headers,
     body: JSON.stringify(body),
+    signal,
   });
 
   logger.info('LLM', 'Response status:', res.status);
@@ -263,6 +266,7 @@ async function chatAnthropic(
   messages: ChatMessage[],
   tools: ToolDef[],
   config: LLMConfig,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const systemMsg = messages.find((m) => m.role === 'system')?.content || '';
   const nonSystemMessages = messages.filter((m) => m.role !== 'system');
@@ -338,6 +342,7 @@ async function chatAnthropic(
     method: 'POST',
     headers,
     body: JSON.stringify(body),
+    signal,
   });
 
   logger.info('LLM', 'Anthropic Response status:', res.status);
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index d13b7ba..6a16753 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -149,8 +149,12 @@ function llmConfigPlugin(): Plugin {
             }
 
             try {
-              fs.mkdirSync(resolve(os.homedir(), '.openroom'), { recursive: true });
-              fs.writeFileSync(LLM_CONFIG_FILE, JSON.stringify(mergedConfig), 'utf-8');
+              const configDir = resolve(os.homedir(), '.openroom');
+              fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+              fs.writeFileSync(LLM_CONFIG_FILE, JSON.stringify(mergedConfig), {
+                encoding: 'utf-8',
+                mode: 0o600,
+              });
               const stat = fs.statSync(LLM_CONFIG_FILE);
               cachedServerConfig = { mtimeMs: stat.mtimeMs, value: mergedConfig };
               res.writeHead(200);
@@ -182,7 +186,7 @@ function sanitizeRelativePath(relPath: string, baseDir: string): string | null {
   const safe = cleaned.replace(/[^a-zA-Z0-9_\-./]/g, '_');
   // Resolve to absolute and verify it stays within baseDir
   const resolved = resolve(baseDir, safe);
-  // Normalize both paths for comparison (resolve handles .. and symlinks)
+  // Normalize both paths for comparison (resolve handles .. sequences)
   const normalizedBase = resolve(baseDir);
   if (!resolved.startsWith(normalizedBase + sep) && resolved !== normalizedBase) {
     return null;
@@ -506,6 +510,16 @@ function isBlockedPassthroughHeader(headerName: string): boolean {
       'proxy-authorization',
       'x-api-key',
       'x-goog-api-key',
+      // Hop-by-hop headers per RFC 9110 — forwarding these can cause
+      // request smuggling or broken upstream responses
+      'content-length',
+      'transfer-encoding',
+      'content-encoding',
+      'accept-encoding',
+      'te',
+      'trailer',
+      'upgrade',
+      'keep-alive',
     ].includes(headerName)
   );
 }
@@ -540,7 +554,14 @@ function llmProxyPlugin(): Plugin {
     name: 'llm-proxy',
     configureServer(server) {
       server.middlewares.use('/api/llm-proxy', async (req, res) => {
-        const targetUrl = req.headers['x-llm-target-url'] as string;
+        // Normalize header values — Node http headers can be string[] for duplicates
+        const getHeader = (name: string): string | undefined => {
+          const val = req.headers[name];
+          if (Array.isArray(val)) return val[0];
+          return val;
+        };
+
+        const targetUrl = getHeader('x-llm-target-url');
         if (!targetUrl) {
           res.writeHead(400, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify({ error: 'Missing X-LLM-Target-URL header' }));
@@ -595,8 +616,8 @@ function llmProxyPlugin(): Plugin {
             injectServerApiKey(
               headers,
               parsedTargetUrl,
-              req.headers['x-llm-provider'] as string,
-              req.headers['x-llm-config-scope'] as string,
+              getHeader('x-llm-provider'),
+              getHeader('x-llm-config-scope'),
             );
 
             const controller = new AbortController();

From 450d177d4b53c91e6321beea81ac1cffc1600f50 Mon Sep 17 00:00:00 2001
From: SweetSophia <mpreichhardt@gmail.com>
Date: Sat, 4 Apr 2026 13:41:07 +0200
Subject: [PATCH 13/13] fix: chess WebGL fallback + conversation engine test
 coverage

- Chess: add WebGL capability detection before Canvas mount; show
  diagnostic fallback panel when WebGL context creation fails instead
  of crashing silently into ErrorBoundary
- Engine tests: add useConversationEngine test suite (4 cases) covering
  AbortSignal threading, file-tool summary redaction, whitespace-only
  image-gen key handling, and mid-loop abort behavior
- Bugfix: include 'file_path' in tool summary extraction keys so
  file_write summaries show 'file_write(file_path: ...)' instead of
  bare tool name
---
 .../ChatPanel/useConversationEngine.test.tsx  | 277 ++++++++++++++++++
 .../ChatPanel/useConversationEngine.ts        |   9 +-
 .../pages/Chess/components/ChessBoard3D.tsx   | 110 ++++++-
 3 files changed, 394 insertions(+), 2 deletions(-)
 create mode 100644 apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx

diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx
new file mode 100644
index 0000000..d6d47f6
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx
@@ -0,0 +1,277 @@
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import type { LLMConfig } from '@/lib/llmModels';
+import type { ChatMessage, ToolCall } from '@/lib/llmClient';
+
+const {
+  chatMock,
+  seedMetaFilesMock,
+  loadActionsFromMetaMock,
+  executeFileToolMock,
+  getImageGenToolDefinitionsMock,
+  buildSystemPromptMock,
+  clearEmotionVideoCacheMock,
+  loadMemoriesMock,
+} = vi.hoisted(() => ({
+  chatMock: vi.fn(),
+  seedMetaFilesMock: vi.fn().mockResolvedValue(undefined),
+  loadActionsFromMetaMock: vi.fn().mockResolvedValue(undefined),
+  executeFileToolMock: vi.fn(),
+  getImageGenToolDefinitionsMock: vi.fn(() => [
+    { type: 'function', function: { name: 'generate_image' } },
+  ]),
+  buildSystemPromptMock: vi.fn(() => 'system prompt'),
+  clearEmotionVideoCacheMock: vi.fn(),
+  loadMemoriesMock: vi.fn(),
+}));
+
+vi.mock('@/lib/llmClient', () => ({
+  chat: chatMock,
+}));
+
+vi.mock('@/lib/seedMeta', () => ({
+  seedMetaFiles: seedMetaFilesMock,
+}));
+
+vi.mock('@/lib/appRegistry', () => ({
+  getAppActionToolDefinition: () => ({ type: 'function', function: { name: 'app_action' } }),
+  resolveAppAction: vi.fn(),
+  getListAppsToolDefinition: () => ({ type: 'function', function: { name: 'list_apps' } }),
+  executeListApps: vi.fn(() => '[]'),
+  loadActionsFromMeta: loadActionsFromMetaMock,
+}));
+
+vi.mock('@/lib/fileTools', () => ({
+  getFileToolDefinitions: () => [{ type: 'function', function: { name: 'file_write' } }],
+  isFileTool: (name: string) => name.startsWith('file_'),
+  executeFileTool: executeFileToolMock,
+}));
+
+vi.mock('@/lib/imageGenTools', () => ({
+  getImageGenToolDefinitions: getImageGenToolDefinitionsMock,
+  isImageGenTool: (name: string) => name === 'generate_image',
+  executeImageGenTool: vi.fn(),
+}));
+
+vi.mock('@/lib/memoryManager', () => ({
+  getMemoryToolDefinitions: () => [],
+  isMemoryTool: () => false,
+  executeMemoryTool: vi.fn(),
+  loadMemories: loadMemoriesMock,
+}));
+
+vi.mock('@/lib/characterManager', () => ({
+  clearEmotionVideoCache: clearEmotionVideoCacheMock,
+}));
+
+vi.mock('@/lib/modManager', () => ({
+  ModManager: class ModManager {},
+  saveModCollection: vi.fn(),
+}));
+
+vi.mock('@/lib/vibeContainerMock', () => ({
+  dispatchAgentAction: vi.fn(),
+}));
+
+vi.mock('./toolDefinitions', () => ({
+  getRespondToUserToolDef: () => ({ type: 'function', function: { name: 'respond_to_user' } }),
+  getFinishTargetToolDef: () => ({ type: 'function', function: { name: 'finish_target' } }),
+  buildSystemPrompt: buildSystemPromptMock,
+}));
+
+import {
+  useConversationEngine,
+  type ConversationCallbacks,
+  type ConversationDisplayMessage,
+} from './useConversationEngine';
+
+const CFG: LLMConfig = {
+  provider: 'openai',
+  apiKey: 'sk-test',
+  baseUrl: 'https://api.openai.com/v1',
+  model: 'gpt-4.1',
+};
+
+type HookApi = ReturnType<typeof useConversationEngine>;
+
+function makeToolCall(name: string, args: Record<string, unknown>, id = `${name}-1`): ToolCall {
+  return {
+    id,
+    type: 'function',
+    function: { name, arguments: JSON.stringify(args) },
+  };
+}
+
+function renderHookWithDeps(options?: { imageApiKey?: string | null }) {
+  const addMessage = vi.fn<(msg: ConversationDisplayMessage) => void>();
+  const chatHistorySetters: ChatMessage[][] = [];
+
+  const callbacks: ConversationCallbacks = {
+    addMessage,
+    setChatHistory: vi.fn((updater) => {
+      const next = typeof updater === 'function' ? updater([]) : updater;
+      chatHistorySetters.push(next as ChatMessage[]);
+      return next;
+    }),
+    setSuggestedReplies: vi.fn(),
+    setCurrentEmotion: vi.fn(),
+    setModCollection: vi.fn(),
+    setModManager: vi.fn(),
+    setMemories: vi.fn(),
+  };
+
+  const deps = {
+    imageGenConfigRef: {
+      current: options?.imageApiKey === null ? null : { apiKey: options?.imageApiKey ?? 'img-key' },
+    },
+    modManagerRef: { current: null },
+    characterRef: { current: { id: 'char-1' } },
+    memoriesRef: { current: [] },
+    sessionPathRef: { current: 'session/a' },
+    callbacks,
+  } as Parameters<typeof useConversationEngine>[0];
+
+  const host = document.createElement('div');
+  let root: Root | null = createRoot(host);
+  const api: { current: HookApi | null } = { current: null };
+
+  function Harness() {
+    api.current = useConversationEngine(deps);
+    return null;
+  }
+
+  act(() => {
+    root!.render(<Harness />);
+  });
+
+  return {
+    api,
+    callbacks,
+    addMessage,
+    chatHistorySetters,
+    cleanup: () => {
+      if (root) {
+        act(() => {
+          root!.unmount();
+        });
+        root = null;
+      }
+    },
+  };
+}
+
+describe('useConversationEngine', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    executeFileToolMock.mockResolvedValue('ok');
+    (
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = true;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('passes the provided AbortSignal through to chat()', async () => {
+    chatMock.mockResolvedValueOnce({ content: 'hello', toolCalls: [] });
+    const harness = renderHookWithDeps();
+    const controller = new AbortController();
+
+    await harness.api.current!.runConversation(
+      [{ role: 'user', content: 'hi' }],
+      CFG,
+      controller.signal,
+    );
+
+    expect(chatMock).toHaveBeenCalledTimes(1);
+    expect(chatMock.mock.calls[0][3]).toBe(controller.signal);
+    expect(seedMetaFilesMock).toHaveBeenCalledTimes(1);
+    expect(loadActionsFromMetaMock).toHaveBeenCalledTimes(1);
+
+    harness.cleanup();
+  });
+
+  it('redacts file tool summaries to tool name and file path only', async () => {
+    chatMock
+      .mockResolvedValueOnce({
+        content: '',
+        toolCalls: [
+          makeToolCall('file_write', {
+            file_path: 'notes/secret.txt',
+            content: 'TOP SECRET CONTENT',
+            password: 'hunter2',
+          }),
+        ],
+      })
+      .mockResolvedValueOnce({
+        content: '',
+        toolCalls: [
+          makeToolCall('respond_to_user', {
+            character_expression: { content: 'Saved it.', emotion: 'calm' },
+            user_interaction: { suggested_replies: ['Nice'] },
+          }),
+        ],
+      });
+
+    const harness = renderHookWithDeps();
+
+    await harness.api.current!.runConversation([{ role: 'user', content: 'save this' }], CFG);
+
+    expect(executeFileToolMock).toHaveBeenCalledWith('file_write', {
+      file_path: 'notes/secret.txt',
+      content: 'TOP SECRET CONTENT',
+      password: 'hunter2',
+    });
+    expect(harness.addMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: 'Saved it.',
+        toolCalls: ['file_write(file_path: notes/secret.txt)'],
+      }),
+    );
+    expect(JSON.stringify(harness.addMessage.mock.calls)).not.toContain('TOP SECRET CONTENT');
+    expect(JSON.stringify(harness.addMessage.mock.calls)).not.toContain('hunter2');
+
+    harness.cleanup();
+  });
+
+  it('treats whitespace-only image generation keys as disabled', async () => {
+    chatMock.mockResolvedValueOnce({ content: 'no image tools', toolCalls: [] });
+    const harness = renderHookWithDeps({ imageApiKey: '   ' });
+
+    await harness.api.current!.runConversation([{ role: 'user', content: 'hi' }], CFG);
+
+    expect(buildSystemPromptMock).toHaveBeenCalledWith(expect.anything(), null, false, []);
+    expect(getImageGenToolDefinitionsMock).not.toHaveBeenCalled();
+    const toolsArg = chatMock.mock.calls[0][1] as Array<{ function: { name: string } }>;
+    expect(toolsArg.map((tool) => tool.function.name)).not.toContain('generate_image');
+
+    harness.cleanup();
+  });
+
+  it('stops after tool execution when the signal is aborted mid-loop', async () => {
+    const controller = new AbortController();
+    executeFileToolMock.mockImplementationOnce(async () => {
+      controller.abort();
+      return 'ok';
+    });
+    chatMock.mockResolvedValueOnce({
+      content: '',
+      toolCalls: [makeToolCall('file_write', { file_path: 'notes/a.txt', content: 'a' })],
+    });
+
+    const harness = renderHookWithDeps();
+
+    await harness.api.current!.runConversation(
+      [{ role: 'user', content: 'save' }],
+      CFG,
+      controller.signal,
+    );
+
+    expect(chatMock).toHaveBeenCalledTimes(1);
+    expect(executeFileToolMock).toHaveBeenCalledTimes(1);
+
+    harness.cleanup();
+  });
+});
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
index c97131c..accf6ac 100644
--- a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
@@ -291,7 +291,14 @@ async function executeToolCall(
   // ---- File tools ----
   if (isFileTool(tc.function.name)) {
     // Only log tool name + path to avoid persisting sensitive file contents
-    const pathKeys = ['path', 'filePath', 'sourcePath', 'targetPath', 'destinationPath'] as const;
+    const pathKeys = [
+      'path',
+      'file_path',
+      'filePath',
+      'sourcePath',
+      'targetPath',
+      'destinationPath',
+    ] as const;
     let summary = tc.function.name;
     for (const key of pathKeys) {
       const value = (params as Record<string, unknown>)[key];
diff --git a/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx b/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx
index f93b75d..3598d6f 100644
--- a/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx
+++ b/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx
@@ -1,4 +1,4 @@
-import React, { useEffect, useState, Suspense } from 'react';
+import React, { useEffect, useState, Suspense, useMemo } from 'react';
 import { Canvas, useThree } from '@react-three/fiber';
 import { OrbitControls, PerspectiveCamera, ContactShadows, Environment } from '@react-three/drei';
 import * as THREE from 'three';
@@ -282,6 +282,14 @@ const ChessBoard3D: React.FC<ChessBoard3DProps> = ({
   onSquareClick,
 }) => {
   const [pieces, setPieces] = useState<TrackedPiece[]>(() => extractPieces(board));
+  const [webglStatus, setWebglStatus] = useState<
+    { supported: true } | { supported: false; message: string; details: string[] } | null
+  >(null);
+
+  const statusLines = useMemo(() => {
+    if (!webglStatus || webglStatus.supported) return [] as string[];
+    return webglStatus.details;
+  }, [webglStatus]);
 
   // Full-board reconciliation piece tracking
   useEffect(() => {
@@ -369,6 +377,60 @@ const ChessBoard3D: React.FC<ChessBoard3DProps> = ({
     });
   }, [board, lastMove]);
 
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      setWebglStatus({ supported: true });
+      return;
+    }
+
+    const canvas = document.createElement('canvas');
+    const details: string[] = [];
+
+    const tryContext = (kind: 'webgl2' | 'webgl') => {
+      try {
+        return canvas.getContext(kind, {
+          alpha: true,
+          antialias: true,
+          powerPreference: 'high-performance',
+          stencil: true,
+          depth: true,
+        } as WebGLContextAttributes);
+      } catch (error) {
+        details.push(
+          `${kind}: ${error instanceof Error ? error.message : String(error) || 'failed'}`,
+        );
+        return null;
+      }
+    };
+
+    const webgl2 = tryContext('webgl2');
+    const webgl = webgl2 ?? tryContext('webgl');
+
+    if (webgl2 || webgl) {
+      const gl = webgl2 ?? webgl;
+      try {
+        const dbg = gl?.getExtension?.('WEBGL_debug_renderer_info');
+        if (dbg) {
+          const renderer = gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL);
+          const vendor = gl.getParameter(dbg.UNMASKED_VENDOR_WEBGL);
+          details.push(`renderer: ${String(renderer)}`);
+          details.push(`vendor: ${String(vendor)}`);
+        }
+      } catch {
+        // Best-effort diagnostics only.
+      }
+      setWebglStatus({ supported: true });
+      return;
+    }
+
+    details.push('No WebGL context could be created for @react-three/fiber Canvas.');
+    setWebglStatus({
+      supported: false,
+      message: '3D board unavailable in this browser/runtime',
+      details,
+    });
+  }, []);
+
   const selectedSquareKey = selectedPos ? `${selectedPos[0]}-${selectedPos[1]}` : null;
 
   const handleSquareClick = (r: number, c: number) => {
@@ -376,6 +438,52 @@ const ChessBoard3D: React.FC<ChessBoard3DProps> = ({
     onSquareClick(r, c);
   };
 
+  if (webglStatus && !webglStatus.supported) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          backgroundImage: `url(${chessBg})`,
+          backgroundSize: 'cover',
+          backgroundPosition: 'center',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: '24px',
+        }}
+      >
+        <div
+          style={{
+            maxWidth: '520px',
+            background: 'rgba(8, 8, 10, 0.82)',
+            border: '1px solid rgba(255,255,255,0.12)',
+            borderRadius: '16px',
+            padding: '20px 22px',
+            color: 'rgba(255,255,255,0.92)',
+            backdropFilter: 'blur(12px)',
+            boxShadow: '0 12px 40px rgba(0,0,0,0.45)',
+          }}
+        >
+          <div style={{ fontSize: '18px', fontWeight: 700, marginBottom: '8px' }}>
+            {webglStatus.message}
+          </div>
+          <div style={{ fontSize: '14px', lineHeight: 1.5, opacity: 0.85 }}>
+            The Chess app mounted correctly, but this environment failed WebGL initialization, so
+            the Three.js board cannot render here.
+          </div>
+          {statusLines.length > 0 && (
+            <div style={{ marginTop: '14px', fontSize: '12px', opacity: 0.72 }}>
+              {statusLines.map((line, idx) => (
+                <div key={`${idx}-${line}`}>{line}</div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       style={{