Refactor backend: extract async stream helper, direct tool registry, nudge_for_result via call_llm

- Add _stream_sync_generator helper in main.py, replacing 5 duplicated async queue patterns
- Add DIRECT_TOOL_REGISTRY in tools.py combining schema + execute in one dict
- Refactor command.py to use DIRECT_TOOL_REGISTRY instead of separate DIRECT_TOOLS set and if/elif dispatch
- Make nudge_for_result use call_llm for debug panel parity (agents.py, agent.py, code.py, image.py)
- Eliminate hardcoded frontend AGENT_REGISTRY, fetch from /api/agents at startup (script.js)
- Debug panel fixes: base64 image placeholders, call enumeration, layout, remove refresh button
- Add drag-and-drop file upload to files panel
- Rewrite README for release with extension/tool/theme documentation
- Reduce debug panel width from 600px to 450px

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -10,7 +10,7 @@ header: mini
 
 # Agent UI
 
-A multi-tab AI assistant interface with support for chat, code execution, and research workflows.
+A multi-agent AI interface with code execution, web search, image generation, and deep research — all orchestrated from a single command center.
 
 ## Quick Start
 
@@ -19,34 +19,255 @@ make install   # Install dependencies
 make dev       # Start server at http://localhost:8765
 ```
 
+## Architecture
+
+```
+backend/
+├── agents.py       # Agent registry (single source of truth) + shared LLM utilities
+├── main.py         # FastAPI routes, SSE streaming, file management
+├── command.py      # Command center: tool routing, agent launching
+├── code.py         # Code agent: E2B sandbox execution
+├── agent.py        # Web agent: search + browse
+├── research.py     # Research agent: multi-source deep analysis
+├── image.py        # Image agent: generate/edit via HuggingFace
+└── tools.py        # Direct tools (execute_code, web_search, show_html, etc.)
+
+frontend/
+├── index.html      # Entry point
+├── script.js       # Application logic, agent registry, settings, themes
+├── style.css       # All styles (CSS custom properties for theming)
+└── research-ui.js  # Research-specific UI components
+```
+
+### How It Works
+
+1. The **command center** receives user messages and decides whether to answer directly or launch sub-agents
+2. Sub-agents (code, web, research, image) run in their own tabs with specialized tools
+3. All communication uses **SSE streaming** — agents yield JSON events with a `type` field
+4. Settings store providers, models, and agent-to-model assignments — any OpenAI-compatible API works
+
+## Extending Agent UI
+
+### Adding a New Agent
+
+Two files need matching entries: `backend/agents.py` and `frontend/script.js`.
+
+**1. Backend registry** — add to `AGENT_REGISTRY` in `backend/agents.py`:
+
+```python
+"my_agent": {
+    "label": "MY AGENT",
+    "system_prompt": "You are a helpful assistant...",
+    "tool": {
+        "type": "function",
+        "function": {
+            "name": "launch_my_agent",
+            "description": "Launch my agent for X tasks.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task": {"type": "string", "description": "The task"},
+                    "task_id": {"type": "string", "description": "2-3 word ID"}
+                },
+                "required": ["task", "task_id"]
+            }
+        }
+    },
+    "tool_arg": "task",
+    "has_counter": True,
+    "in_menu": True,
+    "in_launcher": True,
+    "placeholder": "Enter message...",
+    "capabilities": "Short description of what this agent can do.",
+},
+```
+
+**2. Backend streaming handler** — create `backend/my_agent.py`:
+
+```python
+from .agents import call_llm
+
+def stream_my_agent(client, model, messages, extra_params=None, abort_event=None):
+    """Generator yielding SSE event dicts."""
+    debug_call_number = 0
+
+    while not_done:
+        # call_llm handles retries and emits debug events
+        response = None
+        for event in call_llm(client, model, messages, tools=MY_TOOLS,
+                              extra_params=extra_params, abort_event=abort_event,
+                              call_number=debug_call_number):
+            if "_response" in event:
+                response = event["_response"]
+                debug_call_number = event["_call_number"]
+            else:
+                yield event
+                if event.get("type") in ("error", "aborted"):
+                    return
+
+        # Process response, yield events...
+        yield {"type": "thinking", "content": "..."}
+        yield {"type": "result", "content": "Final answer"}
+
+    yield {"type": "done"}
+```
+
+Required events: `done`, `error`. Common: `thinking`, `content`, `result`, `result_preview`.
+
+**3. Wire the route** — in `backend/main.py`, add to the streaming handler dispatch (search for `agent_type`):
+
+```python
+elif request.agent_type == "my_agent":
+    return StreamingResponse(stream_my_agent_handler(...), ...)
+```
+
+**4. Frontend** — no changes needed. The frontend fetches the registry from `GET /api/agents` at startup.
+
+### Adding a Direct Tool
+
+Direct tools execute synchronously in the command center (no sub-agent spawned).
+
+**1. Define the tool** in `backend/tools.py`:
+
+```python
+my_tool = {
+    "type": "function",
+    "function": {
+        "name": "my_tool",
+        "description": "Does something useful.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "input": {"type": "string", "description": "The input"}
+            },
+            "required": ["input"]
+        }
+    }
+}
+
+def execute_my_tool(input: str) -> dict:
+    return {"content": "Result text for the LLM", "extra_data": "..."}
+```
+
+**2. Register it** in `backend/command.py`:
+
+```python
+from .tools import my_tool, execute_my_tool
+
+TOOLS = get_tools() + [show_html_tool, my_tool]
+DIRECT_TOOLS = {"show_html", "my_tool"}
+```
+
+**3. Add execution handler** in the `stream_command_center` function (same file):
+
+```python
+if function_name == "my_tool":
+    result = execute_my_tool(args.get("input"))
+```
+
+### Modifying System Prompts
+
+All system prompts live in `backend/agents.py` inside `AGENT_REGISTRY`. Edit the `"system_prompt"` field for any agent.
+
+The `get_system_prompt()` function adds dynamic context automatically:
+- `{tools_section}` — replaced with available agent descriptions (command center only)
+- Current date is appended to all prompts
+- Project file tree is appended (in `main.py` wrapper)
+- Theme/styling context is added for code agents
+
+### Adding a Model Provider
+
+In the Settings panel, models are configured through **Providers** and **Models**:
+
+1. **Add a provider**: name + OpenAI-compatible endpoint URL + API token
+2. **Add a model**: name + provider + API model ID (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
+3. **Assign models**: pick which model each agent type uses
+
+Any OpenAI-compatible API works (OpenAI, Anthropic via proxy, Ollama, vLLM, etc.).
+
+Settings are stored in `workspace/settings.json` and managed via the Settings panel in the UI.
+
+### Creating a Theme
+
+Themes are CSS custom property sets defined in `frontend/script.js`.
+
+**Add to `themeColors` object** (search for `const themeColors`):
+
+```javascript
+myTheme: {
+    border: '#8e24aa',
+    bg: '#f3e5f5',
+    hoverBg: '#e1bee7',
+    accent: '#6a1b9a',
+    accentRgb: '106, 27, 154',
+    ...lightSurface    // Use for light themes
+},
+```
+
+For dark themes, override the surface colors instead of spreading `lightSurface`:
+
+```javascript
+myDarkTheme: {
+    border: '#bb86fc',
+    bg: '#1e1e2e',
+    hoverBg: '#2a2a3e',
+    accent: '#bb86fc',
+    accentRgb: '187, 134, 252',
+    bgPrimary: '#121218',
+    bgSecondary: '#1e1e2e',
+    bgTertiary: '#0e0e14',
+    bgInput: '#0e0e14',
+    bgHover: '#2a2a3e',
+    bgCard: '#1e1e2e',
+    textPrimary: '#e0e0e0',
+    textSecondary: '#999999',
+    textMuted: '#666666',
+    borderPrimary: '#333344',
+    borderSubtle: '#222233'
+},
+```
+
+The theme automatically appears in the Settings theme picker — no other changes needed. The `applyTheme()` function reads all properties from the object and sets the corresponding CSS variables.
+
+**Available CSS variables:** `--theme-accent`, `--theme-accent-rgb`, `--theme-bg`, `--theme-hover-bg`, `--theme-border`, `--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--bg-input`, `--bg-hover`, `--bg-card`, `--text-primary`, `--text-secondary`, `--text-muted`, `--border-primary`, `--border-subtle`.
+
+## SSE Event Protocol
+
+All agents communicate via Server-Sent Events. Each event is a JSON object with a `type` field.
+
+| Event | Description |
+|-------|-------------|
+| `done` | Stream complete (required) |
+| `error` | `{content}` — error message (required) |
+| `thinking` | `{content}` — reasoning text |
+| `content` | `{content}` — streamed response tokens |
+| `result` | `{content, figures?}` — final output for command center |
+| `result_preview` | Same as result, shown inline |
+| `retry` | `{attempt, max_attempts, delay, message}` — retrying |
+| `debug_call_input` | `{call_number, messages}` — LLM input (debug panel) |
+| `debug_call_output` | `{call_number, response}` — LLM output (debug panel) |
+| `launch` | `{agent_type, initial_message, task_id}` — spawn sub-agent |
+| `tool_start` | `{tool, args}` — direct tool started |
+| `tool_result` | `{tool, result}` — direct tool completed |
+| `code_start` | `{code}` — code execution started |
+| `code` | `{output, error, images}` — code execution result |
+
 ## Testing
 
 ```bash
-make test           # Run all tests (58 total)
+make test           # Run all tests
 make test-backend   # Backend API tests (pytest)
 make test-frontend  # Frontend unit tests (vitest)
 make test-e2e       # E2E browser tests (playwright)
 ```
 
-## Tab Types
+## Deployment
 
-- **Command Center**: Launch new notebooks and agent workflows
-- **Code**: Jupyter-style notebook with AI agents
-- **Research**: Deep research tasks with agents
-- **Chat**: Standard chat interface
-
-## Project Structure
+The app runs as a Docker container (designed for HuggingFace Spaces):
 
+```bash
+docker build -t agent-ui .
+docker run -p 7860:7860 agent-ui
 ```
-├── backend/          # FastAPI server
-│   └── main.py       # API endpoints
-├── frontend/         # Web UI
-│   ├── index.html    # Entry point
-│   ├── script.js     # Application logic
-│   └── style.css     # Styles
-├── tests/
-│   ├── backend/      # API tests (pytest)
-│   ├── frontend/     # Unit tests (vitest)
-│   └── e2e/          # Browser tests (playwright)
-└── dev/              # Mockups and planning docs
-```
+
+Set API keys via environment variables: `OPENAI_API_KEY`, `E2B_API_KEY`, `SERPER_API_KEY`, `HF_TOKEN`.

backend/agent.py

@@ -250,6 +250,6 @@ def stream_agent_execution(
     # If agent finished without a <result>, nudge it for one
     if not has_result:
         from .agents import nudge_for_result
-        yield from nudge_for_result(client, model, messages, extra_params=extra_params)
+        yield from nudge_for_result(client, model, messages, extra_params=extra_params, call_number=debug_call_number)
 
     yield {"type": "done"}

backend/agents.py

@@ -526,10 +526,11 @@ def call_llm(client, model, messages, tools=None, extra_params=None, abort_event
     yield {"type": "error", "content": f"LLM error after {MAX_RETRIES} attempts: {str(last_error)}"}
 
 
-def nudge_for_result(client, model, messages, extra_params=None, extra_result_data=None):
+def nudge_for_result(client, model, messages, extra_params=None, extra_result_data=None, call_number=0):
     """Nudge an agent that finished without <result> tags to produce one.
 
-    This is a generator that yields SSE events (content, result_preview, result).
+    This is a generator that yields SSE events (content, result_preview, result,
+    plus debug_call_input/output from call_llm).
     Call it after an agent's tool loop when no <result> was found.
 
     Args:
@@ -539,6 +540,7 @@ def nudge_for_result(client, model, messages, extra_params=None, extra_result_da
         extra_params: Optional extra_body params for the LLM call
         extra_result_data: Optional dict of extra fields to include in result events
                            (e.g. {"figures": {...}} or {"images": {...}})
+        call_number: Current debug call number for sequential numbering
     """
     import re
     import logging
@@ -548,29 +550,35 @@ def nudge_for_result(client, model, messages, extra_params=None, extra_result_da
         "role": "user",
         "content": "Please provide your final answer now. Wrap it in <result> tags."
     })
-    try:
-        call_params = {"messages": messages, "model": model}
-        if extra_params:
-            call_params["extra_body"] = extra_params
-        response = client.chat.completions.create(**call_params)
-        nudge_content = response.choices[0].message.content or ""
-        result_match = re.search(r'<result>(.*?)</result>', nudge_content, re.DOTALL | re.IGNORECASE)
-
-        extra = extra_result_data or {}
-
-        if result_match:
-            result_content = result_match.group(1).strip()
-            thinking = re.sub(r'<result>.*?</result>', '', nudge_content, flags=re.DOTALL | re.IGNORECASE).strip()
-            if thinking:
-                yield {"type": "content", "content": thinking}
-            yield {"type": "result_preview", "content": result_content, **extra}
-            yield {"type": "result", "content": result_content, **extra}
-        elif nudge_content.strip():
-            # No result tags but got content — use it as the result
-            yield {"type": "result_preview", "content": nudge_content.strip(), **extra}
-            yield {"type": "result", "content": nudge_content.strip(), **extra}
-    except Exception as e:
-        _logger.warning(f"Result nudge failed: {e}")
+
+    response = None
+    for event in call_llm(client, model, messages, extra_params=extra_params, call_number=call_number):
+        if "_response" in event:
+            response = event["_response"]
+        else:
+            yield event
+            if event.get("type") in ("error", "aborted"):
+                return
+
+    if not response:
+        return
+
+    nudge_content = response.choices[0].message.content or ""
+    result_match = re.search(r'<result>(.*?)</result>', nudge_content, re.DOTALL | re.IGNORECASE)
+
+    extra = extra_result_data or {}
+
+    if result_match:
+        result_content = result_match.group(1).strip()
+        thinking = re.sub(r'<result>.*?</result>', '', nudge_content, flags=re.DOTALL | re.IGNORECASE).strip()
+        if thinking:
+            yield {"type": "content", "content": thinking}
+        yield {"type": "result_preview", "content": result_content, **extra}
+        yield {"type": "result", "content": result_content, **extra}
+    elif nudge_content.strip():
+        # No result tags but got content — use it as the result
+        yield {"type": "result_preview", "content": nudge_content.strip(), **extra}
+        yield {"type": "result", "content": nudge_content.strip(), **extra}
 
 
 def get_tools() -> list:

backend/code.py

@@ -526,7 +526,7 @@ def stream_code_execution(client, model: str, messages: List[Dict], sbx: Sandbox
     # If agent finished without a <result>, nudge it for one
     if not has_result:
         from .agents import nudge_for_result
-        yield from nudge_for_result(client, model, messages, extra_params=extra_params, extra_result_data={"figures": figure_data})
+        yield from nudge_for_result(client, model, messages, extra_params=extra_params, extra_result_data={"figures": figure_data}, call_number=debug_call_number)
 
     # Send done signal
     yield {"type": "done"}

backend/command.py

@@ -9,13 +9,10 @@ logger = logging.getLogger(__name__)
 
 # Tool definitions derived from agent registry
 from .agents import get_tools, get_agent_type_map, get_tool_arg
-from .tools import show_html as show_html_tool, execute_show_html
+from .tools import DIRECT_TOOL_REGISTRY
 
 # Combine agent-launch tools with direct tools
-TOOLS = get_tools() + [show_html_tool]
-
-# Direct tools that execute synchronously (not sub-agent launches)
-DIRECT_TOOLS = {"show_html"}
+TOOLS = get_tools() + [t["schema"] for t in DIRECT_TOOL_REGISTRY.values()]
 
 MAX_TURNS = 10  # Limit conversation turns in command center
 
@@ -83,7 +80,7 @@ def stream_command_center(client, model: str, messages: List[Dict], extra_params
                     return
 
                 # --- Direct tools (execute synchronously) ---
-                if function_name in DIRECT_TOOLS:
+                if function_name in DIRECT_TOOL_REGISTRY:
                     # Emit tool_start for frontend
                     yield {
                         "type": "tool_start",
@@ -94,11 +91,9 @@ def stream_command_center(client, model: str, messages: List[Dict], extra_params
                         "thinking": content,
                     }
 
-                    # Execute the tool
-                    if function_name == "show_html":
-                        result = execute_show_html(args.get("source", ""), files_root=files_root)
-                    else:
-                        result = {"content": f"Unknown direct tool: {function_name}"}
+                    # Execute the tool via registry
+                    tool_entry = DIRECT_TOOL_REGISTRY[function_name]
+                    result = tool_entry["execute"](args, {"files_root": files_root})
 
                     # Emit tool_result for frontend
                     yield {

backend/image.py

@@ -348,7 +348,7 @@ def stream_image_execution(
     if not result_sent and image_store:
         from .agents import nudge_for_result
         nudge_produced_result = False
-        for event in nudge_for_result(client, model, messages, extra_params=extra_params, extra_result_data={"images": image_store}):
+        for event in nudge_for_result(client, model, messages, extra_params=extra_params, extra_result_data={"images": image_store}, call_number=debug_call_number):
             yield event
             if event.get("type") == "result":
                 nudge_produced_result = True

backend/main.py

@@ -23,6 +23,31 @@ _executor = ThreadPoolExecutor(max_workers=10)
 # Flag to signal shutdown to running threads
 _shutdown_flag = False
 
+
+async def _stream_sync_generator(sync_gen_func, *args, **kwargs):
+    """Run a sync generator in a thread, yielding SSE-formatted JSON lines.
+
+    This is the standard pattern for all agent handlers: wrap a blocking
+    sync generator so it doesn't block the async event loop.
+    """
+    loop = asyncio.get_event_loop()
+    queue = asyncio.Queue()
+
+    def run():
+        try:
+            for update in sync_gen_func(*args, **kwargs):
+                loop.call_soon_threadsafe(queue.put_nowait, update)
+        finally:
+            loop.call_soon_threadsafe(queue.put_nowait, None)
+
+    future = loop.run_in_executor(_executor, run)
+    while True:
+        update = await queue.get()
+        if update is None:
+            break
+        yield f"data: {json.dumps(update)}\n\n"
+    await asyncio.wrap_future(future)
+
 def signal_handler(signum, frame):
     """Handle Ctrl+C by setting shutdown flag and exiting"""
     global _shutdown_flag
@@ -366,48 +391,21 @@ async def _stream_code_agent_inner(messages, endpoint, token, model, e2b_key, se
         return
 
     try:
-        # Create or reuse sandbox for this session
         if session_id not in SANDBOXES:
             os.environ["E2B_API_KEY"] = e2b_key
             SANDBOXES[session_id] = Sandbox.create(timeout=SANDBOX_TIMEOUT)
 
         sbx = SANDBOXES[session_id]
-
-        # Create OpenAI client with user's endpoint
         client = OpenAI(base_url=endpoint, api_key=token)
-
-        # Add system prompt for code agent (with file tree and styling context)
         system_prompt = get_system_prompt("code", frontend_context)
-        full_messages = [
-            {"role": "system", "content": system_prompt}
-        ] + messages
-
-
-
-
-        # Stream code execution in a thread to avoid blocking the event loop
-        loop = asyncio.get_event_loop()
-        queue = asyncio.Queue()
-
-        def run_sync_generator():
-            try:
-                for update in stream_code_execution(client, model, full_messages, sbx, files_root=files_root or FILES_ROOT, extra_params=extra_params, abort_event=abort_event, multimodal=multimodal):
-                    loop.call_soon_threadsafe(queue.put_nowait, update)
-            finally:
-                loop.call_soon_threadsafe(queue.put_nowait, None)  # Signal completion
-
-        # Start the sync generator in a thread
-        future = loop.run_in_executor(_executor, run_sync_generator)
-
-        # Yield updates as they arrive
-        while True:
-            update = await queue.get()
-            if update is None:
-                break
-            yield f"data: {json.dumps(update)}\n\n"
+        full_messages = [{"role": "system", "content": system_prompt}] + messages
 
-        # Wait for the thread to complete (handles exceptions)
-        await asyncio.wrap_future(future)
+        async for chunk in _stream_sync_generator(
+            stream_code_execution, client, model, full_messages, sbx,
+            files_root=files_root or FILES_ROOT, extra_params=extra_params,
+            abort_event=abort_event, multimodal=multimodal
+        ):
+            yield chunk
 
     except Exception as e:
         import traceback
@@ -417,7 +415,6 @@ async def _stream_code_agent_inner(messages, endpoint, token, model, e2b_key, se
         # Check if this is a sandbox timeout error (502)
         error_str = str(e)
         if "502" in error_str or "sandbox was not found" in error_str.lower() or "timeout" in error_str.lower():
-            # Remove the timed-out sandbox from cache
             if session_id in SANDBOXES:
                 try:
                     SANDBOXES[session_id].kill()
@@ -425,10 +422,8 @@ async def _stream_code_agent_inner(messages, endpoint, token, model, e2b_key, se
                     pass
                 del SANDBOXES[session_id]
 
-            # Notify user about timeout and retry
             yield f"data: {json.dumps({'type': 'info', 'content': 'Sandbox timed out. Creating new sandbox and retrying...'})}\n\n"
 
-            # Create a new sandbox and retry
             try:
                 os.environ["E2B_API_KEY"] = e2b_key
                 SANDBOXES[session_id] = Sandbox.create(timeout=SANDBOX_TIMEOUT)
@@ -436,25 +431,12 @@ async def _stream_code_agent_inner(messages, endpoint, token, model, e2b_key, se
 
                 yield f"data: {json.dumps({'type': 'info', 'content': 'New sandbox created. Retrying execution...'})}\n\n"
 
-                # Retry code execution with new sandbox (in thread)
-                retry_queue = asyncio.Queue()
-
-                def run_retry_generator():
-                    try:
-                        for update in stream_code_execution(client, model, full_messages, sbx, files_root=files_root or FILES_ROOT, extra_params=extra_params, abort_event=abort_event, multimodal=multimodal):
-                            loop.call_soon_threadsafe(retry_queue.put_nowait, update)
-                    finally:
-                        loop.call_soon_threadsafe(retry_queue.put_nowait, None)
-
-                retry_future = loop.run_in_executor(_executor, run_retry_generator)
-
-                while True:
-                    update = await retry_queue.get()
-                    if update is None:
-                        break
-                    yield f"data: {json.dumps(update)}\n\n"
-
-                await asyncio.wrap_future(retry_future)
+                async for chunk in _stream_sync_generator(
+                    stream_code_execution, client, model, full_messages, sbx,
+                    files_root=files_root or FILES_ROOT, extra_params=extra_params,
+                    abort_event=abort_event, multimodal=multimodal
+                ):
+                    yield chunk
 
             except Exception as retry_error:
                 yield f"data: {json.dumps({'type': 'error', 'content': f'Failed to retry after timeout: {str(retry_error)}'})}\n\n"
@@ -523,29 +505,14 @@ async def _stream_research_agent_inner(messages, endpoint, token, model, serper_
         # Use max websites if provided, otherwise default to 50
         max_sites = max_websites if max_websites else 50
 
-        # Stream research in a thread to avoid blocking the event loop
-        loop = asyncio.get_event_loop()
-        queue = asyncio.Queue()
-
-        def run_sync_generator():
-            try:
-                for update in stream_research(client, model, question, serper_key, max_websites=max_sites, system_prompt=system_prompt, sub_agent_model=analysis_model, parallel_workers=workers, sub_agent_client=sub_agent_client, extra_params=extra_params, sub_agent_extra_params=sub_agent_extra_params, abort_event=abort_event):
-                    loop.call_soon_threadsafe(queue.put_nowait, update)
-            finally:
-                loop.call_soon_threadsafe(queue.put_nowait, None)  # Signal completion
-
-        # Start the sync generator in a thread
-        future = loop.run_in_executor(_executor, run_sync_generator)
-
-        # Yield updates as they arrive
-        while True:
-            update = await queue.get()
-            if update is None:
-                break
-            yield f"data: {json.dumps(update)}\n\n"
-
-        # Wait for the thread to complete (handles exceptions)
-        await asyncio.wrap_future(future)
+        async for chunk in _stream_sync_generator(
+            stream_research, client, model, question, serper_key,
+            max_websites=max_sites, system_prompt=system_prompt,
+            sub_agent_model=analysis_model, parallel_workers=workers,
+            sub_agent_client=sub_agent_client, extra_params=extra_params,
+            sub_agent_extra_params=sub_agent_extra_params, abort_event=abort_event
+        ):
+            yield chunk
 
     except Exception as e:
         import traceback
@@ -579,42 +546,16 @@ async def _stream_command_center_inner(messages, endpoint, token, model, tab_id,
         return
 
     try:
-        # Create OpenAI client
         client = OpenAI(base_url=endpoint, api_key=token)
-
-        # Add system prompt for command center (with file tree)
-        # Frontend sends full conversation history, so just prepend system prompt
         system_prompt = get_system_prompt("command")
         full_messages = [{"role": "system", "content": system_prompt}] + messages
 
-        logger.debug(f"tab_id={tab_id}, messages={len(messages)}, full_messages={len(full_messages)}")
-
-
-
-
-        # Stream command center execution in a thread to avoid blocking the event loop
-        loop = asyncio.get_event_loop()
-        queue = asyncio.Queue()
-
-        def run_sync_generator():
-            try:
-                for update in stream_command_center(client, model, full_messages, extra_params=extra_params, abort_event=abort_event, files_root=files_root or FILES_ROOT):
-                    loop.call_soon_threadsafe(queue.put_nowait, update)
-            finally:
-                loop.call_soon_threadsafe(queue.put_nowait, None)  # Signal completion
-
-        # Start the sync generator in a thread
-        future = loop.run_in_executor(_executor, run_sync_generator)
-
-        # Yield updates as they arrive
-        while True:
-            update = await queue.get()
-            if update is None:
-                break
-            yield f"data: {json.dumps(update)}\n\n"
-
-        # Wait for the thread to complete (handles exceptions)
-        await asyncio.wrap_future(future)
+        async for chunk in _stream_sync_generator(
+            stream_command_center, client, model, full_messages,
+            extra_params=extra_params, abort_event=abort_event,
+            files_root=files_root or FILES_ROOT
+        ):
+            yield chunk
 
     except Exception as e:
         import traceback
@@ -650,31 +591,14 @@ async def _stream_web_agent_inner(messages, endpoint, token, model, serper_key,
 
     try:
         client = OpenAI(base_url=endpoint, api_key=token)
-
         system_prompt = get_system_prompt("agent")
         full_messages = [{"role": "system", "content": system_prompt}] + messages
 
-
-
-        loop = asyncio.get_event_loop()
-        queue = asyncio.Queue()
-
-        def run_sync_generator():
-            try:
-                for update in stream_agent_execution(client, model, full_messages, serper_key, extra_params=extra_params, abort_event=abort_event, multimodal=multimodal):
-                    loop.call_soon_threadsafe(queue.put_nowait, update)
-            finally:
-                loop.call_soon_threadsafe(queue.put_nowait, None)
-
-        future = loop.run_in_executor(_executor, run_sync_generator)
-
-        while True:
-            update = await queue.get()
-            if update is None:
-                break
-            yield f"data: {json.dumps(update)}\n\n"
-
-        await asyncio.wrap_future(future)
+        async for chunk in _stream_sync_generator(
+            stream_agent_execution, client, model, full_messages, serper_key,
+            extra_params=extra_params, abort_event=abort_event, multimodal=multimodal
+        ):
+            yield chunk
 
     except Exception as e:
         import traceback
@@ -716,31 +640,16 @@ async def _stream_image_agent_inner(messages, endpoint, token, model, hf_token,
 
     try:
         client = OpenAI(base_url=endpoint, api_key=token)
-
         system_prompt = get_system_prompt("image")
         full_messages = [{"role": "system", "content": system_prompt}] + messages
 
-
-
-        loop = asyncio.get_event_loop()
-        queue = asyncio.Queue()
-
-        def run_sync_generator():
-            try:
-                for update in stream_image_execution(client, model, full_messages, hf_token, image_gen_model=image_gen_model, image_edit_model=image_edit_model, extra_params=extra_params, abort_event=abort_event, files_root=files_root, multimodal=multimodal):
-                    loop.call_soon_threadsafe(queue.put_nowait, update)
-            finally:
-                loop.call_soon_threadsafe(queue.put_nowait, None)
-
-        future = loop.run_in_executor(_executor, run_sync_generator)
-
-        while True:
-            update = await queue.get()
-            if update is None:
-                break
-            yield f"data: {json.dumps(update)}\n\n"
-
-        await asyncio.wrap_future(future)
+        async for chunk in _stream_sync_generator(
+            stream_image_execution, client, model, full_messages, hf_token,
+            image_gen_model=image_gen_model, image_edit_model=image_edit_model,
+            extra_params=extra_params, abort_event=abort_event,
+            files_root=files_root, multimodal=multimodal
+        ):
+            yield chunk
 
     except Exception as e:
         import traceback

backend/tools.py

@@ -626,3 +626,19 @@ def execute_show_html(source: str, files_root: str = None) -> dict:
             "content": f"Failed to load HTML from '{source}': {e}",
             "html": None,
         }
+
+
+# ============================================================
+# Direct tool registry (used by command center)
+# ============================================================
+# Each entry combines the OpenAI tool schema with an execute function.
+# The execute function receives (args_dict, context_dict).
+
+DIRECT_TOOL_REGISTRY = {
+    "show_html": {
+        "schema": show_html,
+        "execute": lambda args, ctx: execute_show_html(
+            args.get("source", ""), files_root=ctx.get("files_root")
+        ),
+    },
+}

frontend/index.html

@@ -505,6 +505,6 @@
     </div>
 
     <script src="research-ui.js?v=23"></script>
-    <script src="script.js?v=98"></script>
+    <script src="script.js?v=99"></script>
 </body>
 </html>

frontend/script.js

@@ -15,16 +15,10 @@ function sanitizeUsername(name) {
 }
 
 // ============================================================
-// Agent Type Registry — single source of truth for the frontend
-// To add a new agent type, add an entry here and in backend/agents.py
+// Agent Type Registry — populated from backend /api/agents at startup
+// To add a new agent type, add an entry in backend/agents.py (single source of truth)
 // ============================================================
-const AGENT_REGISTRY = {
-    command:  { label: 'MAIN',      hasCounter: false, inMenu: false, inLauncher: false, placeholder: 'Enter message...' },
-    agent:    { label: 'AGENT',     hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Enter message...' },
-    code:     { label: 'CODE',      hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Enter message...' },
-    research: { label: 'RESEARCH',  hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Enter message...' },
-    image:    { label: 'IMAGE',     hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Describe an image or paste a URL...' },
-};
+let AGENT_REGISTRY = {};
 // Virtual types used only in timeline rendering (not real agents)
 const VIRTUAL_TYPE_LABELS = { search: 'SEARCH', browse: 'BROWSE' };
 
@@ -69,7 +63,7 @@ let settings = {
     // New provider/model structure
     providers: {},  // providerId -> {name, endpoint, token}
     models: {},     // modelId -> {name, providerId, modelId (API model string)}
-    agents: Object.fromEntries(Object.keys(AGENT_REGISTRY).map(k => [k, ''])),
+    agents: {},  // Populated after AGENT_REGISTRY is fetched
     // Service API keys
     e2bKey: '',
     serperKey: '',
@@ -737,6 +731,27 @@ document.addEventListener('DOMContentLoaded', async () => {
         }
     }
 
+    // Fetch agent registry from backend (single source of truth)
+    try {
+        const agentsResp = await apiFetch('/api/agents');
+        const agentsData = await agentsResp.json();
+        for (const agent of agentsData.agents) {
+            AGENT_REGISTRY[agent.key] = agent;
+        }
+    } catch (e) {
+        console.error('Failed to fetch agent registry, using fallback');
+        // Minimal fallback so the app still works if backend is slow
+        AGENT_REGISTRY = {
+            command:  { label: 'MAIN',     hasCounter: false, inMenu: false, inLauncher: false, placeholder: 'Enter message...' },
+            agent:    { label: 'AGENT',    hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Enter message...' },
+            code:     { label: 'CODE',     hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Enter message...' },
+            research: { label: 'RESEARCH', hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Enter message...' },
+            image:    { label: 'IMAGE',    hasCounter: true,  inMenu: true,  inLauncher: true,  placeholder: 'Describe an image or paste a URL...' },
+        };
+    }
+    // Initialize settings.agents with registry keys (before loadSettings merges saved values)
+    settings.agents = Object.fromEntries(Object.keys(AGENT_REGISTRY).map(k => [k, '']));
+
     await loadSettings();
     applyTheme(settings.themeColor || 'forest');
     initializeEventListeners();