feat(providers): add xAI Grok OAuth support

Add APIFree as a built-in OpenAI-compatible provider. APIFree offers
agent-optimised models such as skywork-ai/skyclaw-v1 through an
OpenAI-compatible API at https://api.apifree.ai/agent/v1.

Changes:
- Register apifree provider in the provider registry
- Add config schema field
- Add documentation with configuration example
- Add provider tests, websocket channel tests, and webui tests
- Add provider icon in settings UI

.gitignore

@@ -97,3 +97,4 @@ logs/
 tmp/
 temp/
 *.tmp
+exp/

README.md

@@ -212,6 +212,7 @@ nanobot agent
 
 
 - Want different LLM providers, web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md)
+- Want to run locally? Use [Atomic Chat](./docs/configuration.md#atomic-chat-local), [vLLM](./docs/configuration.md#vllm-local-openai-compatible), [Ollama](./docs/configuration.md#ollama-local), and [others](./docs/configuration.md#local-providers).
 - Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md)
 - Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md)
 
@@ -329,4 +330,4 @@ This project was started by [Xubin Ren](https://github.com/re-bin) as a personal
 <p align="center">
   <em> Thanks for visiting ✨ nanobot!</em><br><br>
   <img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.nanobot&style=for-the-badge&color=00d4ff" alt="Views">
-</p>
+</p>

docs/chat-apps.md

@@ -17,7 +17,6 @@ Connect nanobot to your favorite chat platform. Want to build your own? See the
 | **Wecom** | Bot ID + Bot Secret |
 | **Microsoft Teams** | App ID + App Password + public HTTPS endpoint |
 | **Mochat** | Claw token (auto-setup available) |
-| **Signal** | signal-cli daemon + phone number |
 
 <details>
 <summary><b>Telegram</b> (Recommended)</summary>
@@ -670,69 +669,3 @@ nanobot gateway
 ```
 
 </details>
-
-<details>
-<summary><b>Signal</b></summary>
-
-Uses **signal-cli** daemon in HTTP mode — receive messages via SSE, send via JSON-RPC.
-
-**1. Install signal-cli**
-
-Install [signal-cli](https://github.com/AsamK/signal-cli) and register a phone number:
-
-```bash
-signal-cli -u +1234567890 register
-signal-cli -u +1234567890 verify <CODE>
-```
-
-Start the daemon:
-
-```bash
-signal-cli -a +1234567890 daemon --http localhost:8080
-```
-
-**2. Configure**
-
-```json
-{
-  "channels": {
-    "signal": {
-      "enabled": true,
-      "phoneNumber": "+1234567890",
-      "daemonHost": "localhost",
-      "daemonPort": 8080,
-      "dm": {
-        "enabled": true,
-        "policy": "open"
-      },
-      "group": {
-        "enabled": true,
-        "policy": "open",
-        "requireMention": true
-      }
-    }
-  }
-}
-```
-
-> - `phoneNumber`: Your registered Signal phone number.
-> - `daemonHost` / `daemonPort`: Where signal-cli daemon is listening (default `localhost:8080`).
-> - `dm.policy`: `"open"` (anyone can DM) or `"allowlist"` (only listed numbers/UUIDs). When `"allowlist"`, unlisted DM senders receive a pairing code.
-> - `dm.allowFrom`: List of allowed phone numbers or UUIDs (used when policy is `"allowlist"`).
-> - `group.policy`: `"open"` (all groups) or `"allowlist"` (only listed group IDs).
-> - `group.requireMention`: When `true` (default), the bot only responds in groups when @mentioned.
-> - `group.allowFrom`: List of allowed group IDs (used when group policy is `"allowlist"`).
-> - `attachmentsDir`: Override the directory where signal-cli stores inbound attachments. Defaults to `~/.local/share/signal-cli/attachments` (the Linux default). Set this if signal-cli runs with a custom `XDG_DATA_HOME` or on macOS/Windows.
-> - `groupMessageBufferSize`: Number of recent group messages kept for context (default `20`, must be > 0).
-
-**3. Run**
-
-```bash
-nanobot gateway
-```
-
-> [!TIP]
-> The channel automatically reconnects to the signal-cli daemon with exponential backoff if the connection drops.
-> Markdown in bot replies is automatically converted to Signal text styles (bold, italic, code, etc.).
-
-</details>

docs/configuration.md

@@ -134,6 +134,7 @@ ANTHROPIC_API_KEY="$(bw get password api/anthropic)" nanobot agent
 | `custom` | Any OpenAI-compatible endpoint | — |
 | `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |
 | `huggingface` | LLM (Hugging Face Inference Providers) | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |
+| `skywork` | LLM (Skywork / APIFree API gateway) | [apifree.ai](https://www.apifree.ai) |
 | `volcengine` | LLM (VolcEngine, pay-per-use) | [Coding Plan](https://www.volcengine.com/activity/codingplan?utm_campaign=nanobot&utm_content=nanobot&utm_medium=devrel&utm_source=OWO&utm_term=nanobot) · [volcengine.com](https://www.volcengine.com) |
 | `byteplus` | LLM (VolcEngine international, pay-per-use) | [Coding Plan](https://www.byteplus.com/en/activity/codingplan?utm_campaign=nanobot&utm_content=nanobot&utm_medium=devrel&utm_source=OWO&utm_term=nanobot) · [byteplus.com](https://www.byteplus.com) |
 | `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
@@ -152,6 +153,7 @@ ANTHROPIC_API_KEY="$(bw get password api/anthropic)" nanobot agent
 | `zhipu` | LLM (Zhipu GLM) | [open.bigmodel.cn](https://open.bigmodel.cn) |
 | `mimo` | LLM (MiMo) | [platform.xiaomimimo.com](https://platform.xiaomimimo.com) |
 | `longcat` | LLM (LongCat) | [longcat.chat](https://longcat.chat/platform/docs/zh/) |
+| `ant_ling` | LLM (Ant Ling / 蚂蚁百灵) | [developer.ant-ling.com](https://developer.ant-ling.com/en/docs/api-reference/openai/) |
 | `ollama` | LLM (local, Ollama) | — |
 | `lm_studio` | LLM (local, LM Studio) | — |
 | `atomic_chat` | LLM (local, [Atomic Chat](https://atomic.chat/)) | — |
@@ -163,6 +165,36 @@ ANTHROPIC_API_KEY="$(bw get password api/anthropic)" nanobot agent
 | `github_copilot` | LLM (GitHub Copilot, OAuth) | `nanobot provider login github-copilot` |
 | `qianfan` | LLM (Baidu Qianfan) | [cloud.baidu.com](https://cloud.baidu.com/doc/qianfan/s/Hmh4suq26) |
 
+<details>
+<summary><b>Skywork / APIFree</b></summary>
+
+Skywork uses APIFree's OpenAI-compatible Agent API endpoint. Configure the provider
+once, then use Skywork model IDs such as `skywork-ai/skyclaw-v1`.
+
+```json
+{
+  "providers": {
+    "skywork": {
+      "apiKey": "${SKYWORK_API_KEY}",
+      "apiBase": "https://api.apifree.ai/agent/v1"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "skywork",
+      "model": "skywork-ai/skyclaw-v1",
+      "maxTokens": 32768,
+      "contextWindowTokens": 131072
+    }
+  }
+}
+```
+
+You can also reference `${APIFREE_API_KEY}` in `apiKey` if that is how your
+environment names the credential.
+
+</details>
+
 <details>
 <summary><b>AWS Bedrock (Converse API)</b></summary>
 
@@ -444,6 +476,34 @@ Official model names include `LongCat-Flash-Chat`, `LongCat-Flash-Thinking`,
 
 </details>
 
+<details>
+<summary><b>Ant Ling (OpenAI-compatible)</b></summary>
+
+Ant Ling is available through nanobot's built-in OpenAI-compatible provider flow.
+The default API base points to `https://api.ant-ling.com/v1`, so you usually
+only need to set `apiKey`.
+
+```json
+{
+  "providers": {
+    "antLing": {
+      "apiKey": "${ANT_LING_API_KEY}"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "ant_ling",
+      "model": "Ling-2.6-flash"
+    }
+  }
+}
+```
+
+Official OpenAI-compatible model names include `Ling-2.6-1T`,
+`Ling-2.6-flash`, `Ling-2.5-1T`, `Ling-1T`, `Ring-2.5-1T`, and `Ring-1T`.
+
+</details>
+
 <details>
 <summary><b>Custom Provider (Any OpenAI-compatible API)</b></summary>
 
@@ -512,6 +572,8 @@ Some OpenAI-compatible gateways expose request-body extensions such as vLLM guid
 
 </details>
 
+<a id="local-providers"></a>
+<a id="ollama-local"></a>
 <details>
 <summary><b>Ollama (local)</b></summary>
 
@@ -577,12 +639,19 @@ ollama run llama3.2
 
 </details>
 
+<a id="atomic-chat-local"></a>
 <details>
 <summary><b>Atomic Chat (local)</b></summary>
 
-[Atomic Chat](https://atomic.chat/) is a local-first desktop app that exposes an **OpenAI-compatible** HTTP API (default `http://localhost:1337/v1`). Start Atomic Chat and enable the local API server, then point nanobot at it.
+[Atomic Chat](https://atomic.chat/) is a local-first desktop app that exposes an **OpenAI-compatible** HTTP API (default `http://localhost:1337/v1`). Use it when you want to run nanobot against a model on your own machine instead of a hosted API provider.
 
-**1. Add to config** (partial — merge into `~/.nanobot/config.json`):
+**1. Start Atomic Chat**
+
+- Install [Atomic Chat](https://atomic.chat/) on your machine.
+- Open Atomic Chat, download a model, and keep the app running. The local API is enabled by default.
+- Copy the model ID exposed by the local API. For example, the model ID for `Qwen 3 32B` might be `qwen3-32b`.
+
+**2. Add to config** (partial — merge into `~/.nanobot/config.json`):
 
 ```json
 {
@@ -595,13 +664,13 @@ ollama run llama3.2
   "agents": {
     "defaults": {
       "provider": "atomic_chat",
-      "model": "your-model-id-from-atomic-chat"
+      "model": "qwen3-32b"
     }
   }
 }
 ```
 
-> **Note:** Set `apiKey` to `null` if your Atomic Chat server does not require a key. If it does, set `apiKey` (or the `ATOMIC_CHAT_API_KEY` environment variable) to the value Atomic Chat expects. The `model` string must match the model id Atomic Chat exposes on its OpenAI-compatible endpoint.
+> **Note:** Replace `qwen3-32b` with the model ID from Atomic Chat. Set `apiKey` to `null` if your Atomic Chat server does not require a key. If it does, set `apiKey` (or the `ATOMIC_CHAT_API_KEY` environment variable) to the value Atomic Chat expects.
 
 > `provider: "auto"` also works when `providers.atomic_chat.apiBase` is configured, but setting `"provider": "atomic_chat"` is the clearest option.
 
@@ -682,6 +751,7 @@ docker run -d \
 > See the [official OVMS docs](https://docs.openvino.ai/2026/model-server/ovms_docs_llm_quickstart.html) for more details.
 </details>
 
+<a id="vllm-local-openai-compatible"></a>
 <details>
 <summary><b>vLLM (local / OpenAI-compatible)</b></summary>
 

docs/image-generation.md

@@ -6,8 +6,6 @@ The feature is disabled by default. Enable it in `~/.nanobot/config.json`, confi
 
 ## Quick Setup
 
-OpenRouter example:
-
 ```json
 {
   "providers": {
@@ -19,56 +17,13 @@ OpenRouter example:
     "imageGeneration": {
       "enabled": true,
       "provider": "openrouter",
-      "model": "openai/gpt-5.4-image-2",
+      "model": "openai/gpt-5.4-image-2"
-      "defaultAspectRatio": "1:1",
-      "defaultImageSize": "1K"
     }
   }
 }
 ```
 
-AIHubMix example:
+See [Provider Notes](#provider-notes) for AIHubMix, MiniMax, and Gemini configuration examples.
-
-```json
-{
-  "providers": {
-    "aihubmix": {
-      "apiKey": "${AIHUBMIX_API_KEY}"
-    }
-  },
-  "tools": {
-    "imageGeneration": {
-      "enabled": true,
-      "provider": "aihubmix",
-      "model": "gpt-image-2-free",
-      "defaultAspectRatio": "1:1",
-      "defaultImageSize": "1K"
-    }
-  }
-}
-```
-
-Gemini example (Imagen 4):
-
-```json
-{
-  "providers": {
-    "gemini": {
-      "apiKey": "${GEMINI_API_KEY}"
-    }
-  },
-  "tools": {
-    "imageGeneration": {
-      "enabled": true,
-      "provider": "gemini",
-      "model": "imagen-4.0-generate-001",
-      "defaultAspectRatio": "1:1"
-    }
-  }
-}
-```
-
-For Gemini Flash (which supports reference-image edits) see the [Gemini](#gemini) section below.
 
 > [!TIP]
 > Prefer environment variables for API keys. nanobot resolves `${VAR_NAME}` values from the environment at startup.
@@ -91,7 +46,7 @@ The WebUI hides provider storage details from the user. The agent sees the saved
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `tools.imageGeneration.enabled` | boolean | `false` | Register the `generate_image` tool |
-| `tools.imageGeneration.provider` | string | `"openrouter"` | Image provider name. Supported values: `openrouter`, `aihubmix`, `gemini` |
+| `tools.imageGeneration.provider` | string | `"openrouter"` | Image provider name. Supported values: `openrouter`, `aihubmix`, `minimax`, `gemini`, `stepfun` |
 | `tools.imageGeneration.model` | string | `"openai/gpt-5.4-image-2"` | Provider model name |
 | `tools.imageGeneration.defaultAspectRatio` | string | `"1:1"` | Default ratio when the prompt/tool call does not specify one |
 | `tools.imageGeneration.defaultImageSize` | string | `"1K"` | Default size hint, for example `1K`, `2K`, `4K`, or `1024x1024` |
@@ -161,6 +116,28 @@ Configure:
 
 `quality: low` is optional. It can make free image models faster and less likely to time out, but it is not required for correctness.
 
+### MiniMax
+
+MiniMax `image-01` supports text-to-image and reference-image (subject reference) edits. Supported aspect ratios are `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, and `21:9`.
+
+```json
+{
+  "providers": {
+    "minimax": {
+      "apiKey": "${MINIMAX_API_KEY}"
+    }
+  },
+  "tools": {
+    "imageGeneration": {
+      "enabled": true,
+      "provider": "minimax",
+      "model": "image-01",
+      "defaultAspectRatio": "1:1"
+    }
+  }
+}
+```
+
 ### Gemini
 
 nanobot supports two Gemini image generation model families via Google's Generative Language API:
@@ -191,6 +168,58 @@ For reference-image edits, use a Gemini Flash image model:
 
 Imagen 4 supports the aspect ratios `1:1`, `9:16`, `16:9`, `3:4`, and `4:3`. Unsupported ratios are ignored and the model uses its default. The `defaultImageSize` setting has no effect on Gemini models; sizing is controlled by `defaultAspectRatio` only. Reference images passed with an Imagen model are ignored (with a warning logged).
 
+### StepFun
+
+StepFun (阶跃星辰) `step-image-edit-2` supports text-to-image generation.  The `step-1x-medium` variant additionally supports **style-reference** image edits, where a reference image guides the visual style of the output.
+
+Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`.  Sizes are specified as `WIDTHxHEIGHT` (e.g. `1024x1024`, `1280x800`, `800x1280`).
+
+```json
+{
+  "providers": {
+    "stepfun": {
+      "apiKey": "${STEPFUN_API_KEY}"
+    }
+  },
+  "tools": {
+    "imageGeneration": {
+      "enabled": true,
+      "provider": "stepfun",
+      "model": "step-image-edit-2"
+    }
+  }
+}
+```
+
+> [!NOTE]
+> The StepFun provider reuses the existing `providers.stepfun` config block (the same one used for StepFun's LLM API).  Set `providers.stepfun.apiKey` once and it is shared between text and image generation.
+>
+> When `step-image-edit-2` is used, `reference_images` are ignored (the model does not support style reference).  Switch to `step-1x-medium` to use reference-image-guided generation.
+
+#### StepPlan (Subscription)
+
+StepPlan is StepFun's subscription tier and uses a different API base URL. The image generation endpoint path is the same — just override `apiBase`:
+
+```json
+{
+  "providers": {
+    "stepfun": {
+      "apiKey": "${STEPFUN_API_KEY}",
+      "apiBase": "https://api.stepfun.com/step_plan/v1"
+    }
+  },
+  "tools": {
+    "imageGeneration": {
+      "enabled": true,
+      "provider": "stepfun",
+      "model": "step-image-edit-2"
+    }
+  }
+}
+```
+
+`apiBase` takes precedence over the registry default, so with the StepPlan base URL configured, image requests are sent to `https://api.stepfun.com/step_plan/v1/images/generations` — the same path prefix used for LLM calls. The API key is shared with the standard StepFun provider.
+
 ## Artifacts
 
 Generated images are stored under the active nanobot instance's media directory:
@@ -245,7 +274,7 @@ Use the reference image. Keep the same robot and composition, change the palette
 |---------|-------|
 | `generate_image` is not available | Set `tools.imageGeneration.enabled` to `true` and restart the gateway |
 | Missing API key error | Configure `providers.<provider>.apiKey`; if using `${VAR_NAME}`, confirm the environment variable is visible to the gateway process |
-| `unsupported image generation provider` | Use `openrouter`, `aihubmix`, or `gemini` |
+| `unsupported image generation provider` | Use `openrouter`, `aihubmix`, `minimax`, `gemini`, or `stepfun` |
 | AIHubMix says `Incorrect model ID` | Use `model: "gpt-image-2-free"`; nanobot expands it to the required `openai/gpt-image-2-free` model path internally |
 | Generation times out | Try a smaller/default image size, set AIHubMix `extraBody.quality` to `"low"`, or retry later |
 | Reference image rejected | Reference image paths must be inside the workspace or nanobot media directory and must be valid image files |

nanobot/__init__.py

@@ -2,9 +2,10 @@
 nanobot - A lightweight AI agent framework
 """
 
-from importlib.metadata import PackageNotFoundError, version as _pkg_version
-from pathlib import Path
 import tomllib
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
 
 
 def _read_pyproject_version() -> str | None:
@@ -27,6 +28,21 @@ def _resolve_version() -> str:
 __version__ = _resolve_version()
 __logo__ = "🐈"
 
-from nanobot.nanobot import Nanobot, RunResult
+_LAZY_EXPORTS = {
+    "Nanobot": ".nanobot",
+    "RunResult": ".nanobot",
+}
+
+
+def __getattr__(name: str):
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+    mod = import_module(module_path, __name__)
+    val = getattr(mod, name)
+    globals()[name] = val
+    return val
+
 
 __all__ = ["Nanobot", "RunResult"]

nanobot/agent/loop.py

@@ -36,19 +36,17 @@ from nanobot.session.goal_state import (
     runner_wall_llm_timeout_s,
 )
 from nanobot.session.manager import Session, SessionManager
-from nanobot.utils.artifacts import generated_image_paths_from_messages
+from nanobot.session.webui_turns import (
+    WebuiTurnCoordinator,
+    build_bus_progress_callback,
+    mark_webui_session,
+)
 from nanobot.utils.document import extract_documents
 from nanobot.utils.helpers import image_placeholder_text
 from nanobot.utils.helpers import truncate_text as truncate_text_fn
 from nanobot.utils.image_generation_intent import image_generation_prompt
 from nanobot.utils.llm_runtime import LLMRuntime
 from nanobot.utils.runtime import EMPTY_FINAL_RESPONSE_MESSAGE
-from nanobot.utils.session_attachments import merge_turn_media_into_last_assistant
-from nanobot.utils.webui_turn_helpers import (
-    WebuiTurnCoordinator,
-    build_bus_progress_callback,
-    mark_webui_session,
-)
 
 if TYPE_CHECKING:
     from nanobot.config.schema import (
@@ -103,7 +101,6 @@ class TurnContext:
     save_skip: int = 0
 
     outbound: OutboundMessage | None = None
-    generated_media: list[str] = field(default_factory=list)
 
     on_progress: Callable[..., Awaitable[None]] | None = None
     on_stream: Callable[[str], Awaitable[None]] | None = None
@@ -1194,7 +1191,6 @@ class AgentLoop:
         all_msgs: list[dict[str, Any]],
         stop_reason: str,
         had_injections: bool,
-        generated_media: list[str],
         on_stream: Callable[[str], Awaitable[None]] | None,
         *,
         turn_latency_ms: int | None = None,
@@ -1218,7 +1214,6 @@ class AgentLoop:
             channel=msg.channel,
             chat_id=msg.chat_id,
             content=final_content,
-            media=generated_media,
             metadata=meta,
         )
 
@@ -1348,11 +1343,6 @@ class AgentLoop:
             ctx.final_content = EMPTY_FINAL_RESPONSE_MESSAGE
 
         ctx.save_skip = 1 + len(ctx.history) + (1 if ctx.user_persisted_early else 0)
-        skip_msgs = ctx.all_messages[ctx.save_skip:]
-        ctx.generated_media = generated_image_paths_from_messages(skip_msgs)
-        mt = self.tools.get("message")
-        extra = getattr(mt, "turn_delivered_media_paths", lambda: [])() if mt else []
-        merge_turn_media_into_last_assistant(ctx.all_messages, ctx.generated_media, extra)
 
         ctx.turn_latency_ms = max(0, int((time.time() - ctx.turn_wall_started_at) * 1000))
         self._save_turn(
@@ -1380,7 +1370,6 @@ class AgentLoop:
             ctx.all_messages,
             ctx.stop_reason,
             ctx.had_injections,
-            ctx.generated_media,
             ctx.on_stream,
             turn_latency_ms=ctx.turn_latency_ms,
         )

nanobot/agent/runner.py

@@ -20,6 +20,7 @@ from nanobot.utils.file_edit_events import (
     build_file_edit_error_event,
     build_file_edit_start_event,
     prepare_file_edit_tracker,
+    StreamingFileEditTracker,
 )
 from nanobot.utils.helpers import (
     IncrementalThinkExtractor,
@@ -629,6 +630,24 @@ class AgentRunner:
         )
 
         progress_state: dict[str, bool] | None = None
+        live_file_edits: StreamingFileEditTracker | None = None
+
+        if (
+            spec.progress_callback is not None
+            and on_progress_accepts_file_edit_events(spec.progress_callback)
+        ):
+            async def _emit_live_file_edits(events: list[dict[str, Any]]) -> None:
+                await invoke_file_edit_progress(spec.progress_callback, events)
+
+            live_file_edits = StreamingFileEditTracker(
+                workspace=spec.workspace,
+                tools=spec.tools,
+                emit=_emit_live_file_edits,
+            )
+
+        async def _tool_call_delta(delta: dict[str, Any]) -> None:
+            if live_file_edits is not None:
+                await live_file_edits.update(delta)
 
         if wants_streaming:
             async def _stream(delta: str) -> None:
@@ -646,6 +665,7 @@ class AgentRunner:
                 **kwargs,
                 on_content_delta=_stream,
                 on_thinking_delta=_thinking,
+                on_tool_call_delta=_tool_call_delta if live_file_edits is not None else None,
             )
         elif wants_progress_streaming:
             stream_buf = ""
@@ -675,6 +695,7 @@ class AgentRunner:
             coro = self.provider.chat_stream_with_retry(
                 **kwargs,
                 on_content_delta=_stream_progress,
+                on_tool_call_delta=_tool_call_delta if live_file_edits is not None else None,
             )
         else:
             coro = self.provider.chat_with_retry(**kwargs)
@@ -689,6 +710,14 @@ class AgentRunner:
                 await coro if outer_timeout_s is None
                 else await asyncio.wait_for(coro, timeout=outer_timeout_s)
             )
+            if live_file_edits is not None:
+                await live_file_edits.flush()
+                if response.should_execute_tools:
+                    live_file_edits.apply_final_call_ids(response.tool_calls)
+                await live_file_edits.error_unmatched(
+                    response.tool_calls if response.should_execute_tools else [],
+                    "Tool call did not complete.",
+                )
         except asyncio.TimeoutError:
             if outer_timeout_s is None:
                 return LLMResponse(
@@ -907,7 +936,10 @@ class AgentRunner:
         if file_edit_tracker is not None and progress_callback is not None:
             await invoke_file_edit_progress(
                 progress_callback,
-                [build_file_edit_end_event(file_edit_tracker)],
+                [build_file_edit_end_event(
+                    file_edit_tracker,
+                    params if isinstance(params, dict) else None,
+                )],
             )
 
         detail = "" if result is None else str(result)

nanobot/agent/tools/image_generation.py

@@ -17,11 +17,9 @@ from nanobot.agent.tools.schema import (
 from nanobot.config.paths import get_media_dir
 from nanobot.config.schema import Base
 from nanobot.providers.image_generation import (
-    AIHubMixImageGenerationClient,
-    GeminiImageGenerationClient,
     ImageGenerationError,
-    MiniMaxImageGenerationClient,
+    ImageGenerationProvider,
-    OpenRouterImageGenerationClient,
+    get_image_gen_provider,
 )
 from nanobot.utils.artifacts import (
     ArtifactError,
@@ -119,37 +117,24 @@ class ImageGenerationTool(Tool):
     def _provider_config(self) -> ProviderConfig | None:
         return self.provider_configs.get(self.config.provider)
 
-    def _provider_client(
+    def _provider_client(self) -> ImageGenerationProvider | None:
-        self,
-    ) -> OpenRouterImageGenerationClient | AIHubMixImageGenerationClient | MiniMaxImageGenerationClient | GeminiImageGenerationClient | None:
         provider = self._provider_config()
+        cls = get_image_gen_provider(self.config.provider)
+        if cls is None:
+            return None
         kwargs = {
             "api_key": provider.api_key if provider else None,
             "api_base": provider.api_base if provider else None,
             "extra_headers": provider.extra_headers if provider else None,
             "extra_body": provider.extra_body if provider else None,
         }
-        if self.config.provider == "openrouter":
+        return cls(**kwargs)
-            return OpenRouterImageGenerationClient(**kwargs)
-        if self.config.provider == "aihubmix":
-            return AIHubMixImageGenerationClient(**kwargs)
-        if self.config.provider == "minimax":
-            return MiniMaxImageGenerationClient(**kwargs)
-        if self.config.provider == "gemini":
-            return GeminiImageGenerationClient(**kwargs)
-        return None
 
     def _missing_api_key_error(self) -> str:
-        provider = self.config.provider
+        cls = get_image_gen_provider(self.config.provider)
-        if provider == "openrouter":
+        if cls and cls.missing_key_message:
-            return "Error: OpenRouter API key is not configured. Set providers.openrouter.apiKey."
+            return f"Error: {cls.missing_key_message}"
-        if provider == "aihubmix":
+        return f"Error: {self.config.provider} API key is not configured."
-            return "Error: AIHubMix API key is not configured. Set providers.aihubmix.apiKey."
-        if provider == "minimax":
-            return "Error: MiniMax API key is not configured. Set providers.minimax.apiKey."
-        if provider == "gemini":
-            return "Error: Gemini API key is not configured. Set providers.gemini.apiKey."
-        return f"Error: {provider} API key is not configured."
 
     def _resolve_reference_image(self, value: str) -> str:
         raw_path = Path(value).expanduser()

nanobot/agent/tools/message.py

@@ -31,8 +31,8 @@ from nanobot.config.paths import get_workspace_path
         media=ArraySchema(
             StringSchema(""),
             description=(
-                "Optional list of existing file paths to attach for proactive or cross-channel delivery. "
+                "Optional list of existing file paths to attach. "
-                "Do not use this to resend generate_image outputs in the current chat."
+                "Use artifact paths returned by generate_image here when delivering generated images."
             ),
         ),
         buttons=ArraySchema(
@@ -140,8 +140,8 @@ class MessageTool(Tool, ContextAware):
             "Do not use this for the normal reply in the current chat: answer naturally instead. "
             "If channel/chat_id would target the current runtime conversation, do not call this tool "
             "unless the user explicitly asked you to proactively send an existing file attachment. "
-            "When generate_image creates images in the current chat, the final assistant reply "
+            "When generate_image creates images in the current chat, use the message tool "
-            "automatically attaches them; do not call message just to announce or resend them. "
+            "with the artifact paths in the media parameter to deliver the images to the user. "
             "For proactive attachment delivery, use the 'media' parameter with file paths. "
             "Do NOT use read_file to send files — that only reads content for your own analysis."
         )

nanobot/agent/tools/shell.py

@@ -266,6 +266,7 @@ class ExecTool(Tool):
             # the raw command string to COMSPEC without re-quoting.
             return await asyncio.create_subprocess_shell(
                 command,
+                stdin=asyncio.subprocess.DEVNULL,
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
                 cwd=cwd,
@@ -274,6 +275,7 @@ class ExecTool(Tool):
         bash = shutil.which("bash") or "/bin/bash"
         return await asyncio.create_subprocess_exec(
             bash, "-l", "-c", command,
+            stdin=asyncio.subprocess.DEVNULL,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
             cwd=cwd,

nanobot/channels/manager.py

@@ -70,28 +70,40 @@ class ChannelManager:
 
     def _init_channels(self) -> None:
         """Initialize channels discovered via pkgutil scan + entry_points plugins."""
-        from nanobot.channels.registry import discover_all
+        from nanobot.channels.registry import discover_channel_names, discover_enabled
 
         transcription_provider = self.config.channels.transcription_provider
         transcription_key = self._resolve_transcription_key(transcription_provider)
         transcription_base = self._resolve_transcription_base(transcription_provider)
         transcription_language = self.config.channels.transcription_language
 
-        for name, cls in discover_all().items():
+        # Collect enabled module names first, then only import those.
+        # Channel configs live in ChannelsConfig's extra fields (via
+        # extra="allow"), so we enumerate candidates from pkgutil scan
+        # (cheap, no imports) and any plugin keys in __pydantic_extra__.
+        names = discover_channel_names()
+        candidate_names = set(names)
+        extra = getattr(self.config.channels, "__pydantic_extra__", None) or {}
+        candidate_names.update(extra.keys())
+
+        enabled_names: set[str] = set()
+        for name in candidate_names:
             section = getattr(self.config.channels, name, None)
             if section is None:
                 continue
-            enabled = (
+            if (
                 section.get("enabled", False)
                 if isinstance(section, dict)
                 else getattr(section, "enabled", False)
-            )
+            ):
-            if not enabled:
+                enabled_names.add(name)
+
+        for name, cls in discover_enabled(enabled_names, _names=names).items():
+            section = getattr(self.config.channels, name, None)
+            if section is None:
                 continue
             try:
                 kwargs: dict[str, Any] = {}
-                # Only the WebSocket channel currently hosts the embedded webui
-                # surface; other channels stay oblivious to these knobs.
                 if cls.name == "websocket":
                     if self._session_manager is not None:
                         kwargs["session_manager"] = self._session_manager

nanobot/channels/registry.py

@@ -1,5 +1,4 @@
 """Auto-discovery for built-in channel modules and external plugins."""
-
 from __future__ import annotations
 
 import importlib
@@ -37,12 +36,14 @@ def load_channel_class(module_name: str) -> type[BaseChannel]:
     raise ImportError(f"No BaseChannel subclass in nanobot.channels.{module_name}")
 
 
-def discover_plugins() -> dict[str, type[BaseChannel]]:
+def discover_plugins(enabled_names: set[str] | None = None) -> dict[str, type[BaseChannel]]:
     """Discover external channel plugins registered via entry_points."""
     from importlib.metadata import entry_points
 
     plugins: dict[str, type[BaseChannel]] = {}
     for ep in entry_points(group="nanobot.channels"):
+        if enabled_names is not None and ep.name not in enabled_names:
+            continue
         try:
             cls = ep.load()
             plugins[ep.name] = cls
@@ -51,21 +52,44 @@ def discover_plugins() -> dict[str, type[BaseChannel]]:
     return plugins
 
 
+def discover_enabled(
+    enabled_names: set[str],
+    *,
+    _names: list[str] | None = None,
+    _include_all_external: bool = False,
+) -> dict[str, type[BaseChannel]]:
+    """Return channels whose module names are in *enabled_names*.
+
+    Uses cheap ``pkgutil.iter_modules`` to list names, then imports only
+    those that match — skipping the heavy third-party SDK imports of
+    unneeded channels.
+    """
+    names = _names if _names is not None else discover_channel_names()
+    result: dict[str, type[BaseChannel]] = {}
+    for modname in names:
+        if modname not in enabled_names:
+            continue
+        try:
+            result[modname] = load_channel_class(modname)
+        except ImportError as e:
+            logger.debug("Skipping built-in channel '{}': {}", modname, e)
+
+    external = discover_plugins(None if _include_all_external else enabled_names)
+    shadowed = set(external) & set(result)
+    if shadowed:
+        logger.warning("Plugin(s) shadowed by built-in channels (ignored): {}", shadowed)
+    if _include_all_external:
+        result.update({k: v for k, v in external.items() if k not in shadowed})
+    else:
+        result.update({k: v for k, v in external.items() if k not in shadowed and k in enabled_names})
+
+    return result
+
+
 def discover_all() -> dict[str, type[BaseChannel]]:
     """Return all channels: built-in (pkgutil) merged with external (entry_points).
 
     Built-in channels take priority — an external plugin cannot shadow a built-in name.
     """
-    builtin: dict[str, type[BaseChannel]] = {}
+    names = discover_channel_names()
-    for modname in discover_channel_names():
+    return discover_enabled(set(names), _names=names, _include_all_external=True)
-        try:
-            builtin[modname] = load_channel_class(modname)
-        except ImportError as e:
-            logger.debug("Skipping built-in channel '{}': {}", modname, e)
-
-    external = discover_plugins()
-    shadowed = set(external) & set(builtin)
-    if shadowed:
-        logger.warning("Plugin(s) shadowed by built-in channels (ignored): {}", shadowed)
-
-    return {**external, **builtin}

nanobot/channels/websocket.py

@@ -37,15 +37,27 @@ from nanobot.command.builtin import builtin_command_palette
 from nanobot.config.paths import get_media_dir
 from nanobot.config.schema import Base
 from nanobot.session.goal_state import goal_state_ws_blob
+from nanobot.session.webui_turns import websocket_turn_wall_started_at
 from nanobot.utils.helpers import safe_filename
 from nanobot.utils.media_decode import (
     FileSizeExceeded,
     save_base64_data_url,
 )
 from nanobot.utils.subagent_channel_display import scrub_subagent_messages_for_channel
-from nanobot.utils.webui_thread_disk import delete_webui_thread
+from nanobot.webui.settings_api import (
-from nanobot.utils.webui_transcript import append_transcript_object, build_webui_thread_response
+    WebUISettingsError,
-from nanobot.utils.webui_turn_helpers import websocket_turn_wall_started_at
+    settings_payload,
+    update_agent_settings,
+    update_image_generation_settings,
+    update_provider_settings,
+    update_web_search_settings,
+)
+from nanobot.webui.sidebar_state import (
+    read_webui_sidebar_state,
+    write_webui_sidebar_state,
+)
+from nanobot.webui.thread_disk import delete_webui_thread
+from nanobot.webui.transcript import append_transcript_object, build_webui_thread_response
 
 if TYPE_CHECKING:
     from nanobot.session.manager import SessionManager
@@ -222,47 +234,6 @@ def _query_first(query: dict[str, list[str]], key: str) -> str | None:
     return values[0] if values else None
 
 
-def _mask_secret_hint(secret: str | None) -> str | None:
-    if not secret:
-        return None
-    if len(secret) <= 8:
-        return "••••"
-    return f"{secret[:4]}••••{secret[-4:]}"
-
-
-def _provider_requires_api_key(spec: Any) -> bool:
-    if spec.backend == "azure_openai":
-        return True
-    if spec.is_local or spec.is_direct:
-        return False
-    return True
-
-
-def _provider_configured_for_settings(spec: Any, provider_config: Any) -> bool:
-    if _provider_requires_api_key(spec):
-        return bool(provider_config.api_key)
-    return bool(
-        provider_config.api_key
-        or provider_config.api_base
-        or getattr(provider_config, "region", None)
-        or getattr(provider_config, "profile", None)
-    )
-
-
-_WEB_SEARCH_PROVIDER_OPTIONS: tuple[dict[str, str], ...] = (
-    {"name": "duckduckgo", "label": "DuckDuckGo", "credential": "none"},
-    {"name": "brave", "label": "Brave Search", "credential": "api_key"},
-    {"name": "tavily", "label": "Tavily", "credential": "api_key"},
-    {"name": "searxng", "label": "SearXNG", "credential": "base_url"},
-    {"name": "jina", "label": "Jina", "credential": "api_key"},
-    {"name": "kagi", "label": "Kagi", "credential": "api_key"},
-    {"name": "olostep", "label": "Olostep", "credential": "api_key"},
-)
-_WEB_SEARCH_PROVIDER_BY_NAME = {
-    provider["name"]: provider for provider in _WEB_SEARCH_PROVIDER_OPTIONS
-}
-
-
 def _parse_inbound_payload(raw: str) -> str | None:
     """Parse a client frame into text; return None for empty or unrecognized content."""
     text = raw.strip()
@@ -501,6 +472,7 @@ class WebSocketChannel(BaseChannel):
             static_dist_path.resolve() if static_dist_path is not None else None
         )
         self._runtime_model_name = runtime_model_name
+        self._settings_restart_sections: set[str] = set()
         # Process-local secret used to HMAC-sign media URLs. The signed URL is
         # the capability — anyone who holds a valid URL can fetch that one
         # file, nothing else. The secret regenerates on restart so links
@@ -663,6 +635,12 @@ class WebSocketChannel(BaseChannel):
         if got == "/api/commands":
             return self._handle_commands(request)
 
+        if got == "/api/webui/sidebar-state":
+            return self._handle_webui_sidebar_state(request)
+
+        if got == "/api/webui/sidebar-state/update":
+            return self._handle_webui_sidebar_state_update(request)
+
         if got == "/api/settings/update":
             return self._handle_settings_update(request)
 
@@ -672,6 +650,9 @@ class WebSocketChannel(BaseChannel):
         if got == "/api/settings/web-search/update":
             return self._handle_settings_web_search_update(request)
 
+        if got == "/api/settings/image-generation/update":
+            return self._handle_settings_image_generation_update(request)
+
         m = re.match(r"^/api/sessions/([^/]+)/messages$", got)
         if m:
             return self._handle_session_messages(request, m.group(1))
@@ -783,221 +764,115 @@ class WebSocketChannel(BaseChannel):
         sessions = self._session_manager.list_sessions()
         # Sidebar/chat listing for WS-backed sessions only — CLI / Slack / etc.
         # keys are not intended for resume over this HTTP surface.
-        cleaned = [
+        cleaned = []
-            {k: v for k, v in s.items() if k != "path"}
+        for s in sessions:
-            for s in sessions
+            key = s.get("key")
-            if isinstance(s.get("key"), str) and s["key"].startswith("websocket:")
+            if not (isinstance(key, str) and key.startswith("websocket:")):
-        ]
-        return _http_json_response({"sessions": cleaned})
-
-    def _settings_payload(self, *, requires_restart: bool = False) -> dict[str, Any]:
-        from nanobot.config.loader import get_config_path, load_config
-        from nanobot.providers.registry import PROVIDERS, find_by_name
-
-        config = load_config()
-        defaults = config.agents.defaults
-        provider_name = config.get_provider_name(defaults.model) or defaults.provider
-        provider = config.get_provider(defaults.model)
-        selected_provider = provider_name
-        if defaults.provider != "auto":
-            spec = find_by_name(defaults.provider)
-            selected_provider = spec.name if spec else provider_name
-        providers = []
-        for spec in PROVIDERS:
-            provider_config = getattr(config.providers, spec.name, None)
-            if provider_config is None or spec.is_oauth:
                 continue
-            providers.append(
+            row = {k: v for k, v in s.items() if k != "path"}
-                {
+            chat_id = key.split(":", 1)[1]
-                    "name": spec.name,
+            started_at = websocket_turn_wall_started_at(chat_id)
-                    "label": spec.label,
+            if started_at is not None:
-                    "configured": _provider_configured_for_settings(spec, provider_config),
+                row["run_started_at"] = started_at
-                    "api_key_required": _provider_requires_api_key(spec),
+            cleaned.append(row)
-                    "api_key_hint": _mask_secret_hint(provider_config.api_key),
+        return _http_json_response({"sessions": cleaned})
-                    "api_base": provider_config.api_base,
-                    "default_api_base": spec.default_api_base or None,
-                }
-            )
-        search_config = config.tools.web.search
-        search_provider = (
-            search_config.provider
-            if search_config.provider in _WEB_SEARCH_PROVIDER_BY_NAME
-            else "duckduckgo"
-        )
-        return {
-            "agent": {
-                "model": defaults.model,
-                "provider": selected_provider,
-                "resolved_provider": provider_name,
-                "has_api_key": bool(provider and provider.api_key),
-            },
-            "providers": providers,
-            "web_search": {
-                "provider": search_provider,
-                "api_key_hint": _mask_secret_hint(search_config.api_key),
-                "base_url": search_config.base_url or None,
-                "providers": list(_WEB_SEARCH_PROVIDER_OPTIONS),
-            },
-            "runtime": {
-                "config_path": str(get_config_path().expanduser()),
-            },
-            "requires_restart": requires_restart,
-        }
 
     def _handle_settings(self, request: WsRequest) -> Response:
         if not self._check_api_token(request):
             return _http_error(401, "Unauthorized")
-        return _http_json_response(self._settings_payload())
+        return _http_json_response(self._with_settings_restart_state(settings_payload()))
+
+    def _with_settings_restart_state(
+        self,
+        payload: dict[str, Any],
+        *,
+        section: str | None = None,
+    ) -> dict[str, Any]:
+        """Keep restart-required state alive for this gateway process."""
+        if section and payload.get("requires_restart"):
+            self._settings_restart_sections.add(section)
+        if self._settings_restart_sections:
+            payload = dict(payload)
+            payload["requires_restart"] = True
+            payload["restart_required_sections"] = sorted(self._settings_restart_sections)
+        else:
+            payload = dict(payload)
+            payload["restart_required_sections"] = []
+        return payload
 
     def _handle_commands(self, request: WsRequest) -> Response:
         if not self._check_api_token(request):
             return _http_error(401, "Unauthorized")
         return _http_json_response({"commands": builtin_command_palette()})
 
+    def _handle_webui_sidebar_state(self, request: WsRequest) -> Response:
+        if not self._check_api_token(request):
+            return _http_error(401, "Unauthorized")
+        return _http_json_response(read_webui_sidebar_state())
+
+    def _handle_webui_sidebar_state_update(self, request: WsRequest) -> Response:
+        if not self._check_api_token(request):
+            return _http_error(401, "Unauthorized")
+        query = _parse_query(request.path)
+        raw_state = _query_first(query, "state")
+        if raw_state is None:
+            return _http_error(400, "missing state")
+        try:
+            decoded = json.loads(raw_state)
+        except json.JSONDecodeError:
+            return _http_error(400, "state must be JSON")
+        if not isinstance(decoded, dict):
+            return _http_error(400, "state must be an object")
+        try:
+            state = write_webui_sidebar_state(decoded)
+        except ValueError as e:
+            return _http_error(400, str(e))
+        except OSError:
+            self.logger.exception("failed to write webui sidebar state")
+            return _http_error(500, "failed to write sidebar state")
+        return _http_json_response(state)
+
     def _handle_settings_update(self, request: WsRequest) -> Response:
         if not self._check_api_token(request):
             return _http_error(401, "Unauthorized")
-        from nanobot.config.loader import load_config, save_config
-        from nanobot.providers.registry import find_by_name
-
         query = _parse_query(request.path)
-        config = load_config()
+        try:
-        defaults = config.agents.defaults
+            payload = update_agent_settings(query)
-        changed = False
+        except WebUISettingsError as e:
-
+            return _http_error(e.status, e.message)
-        model = _query_first(query, "model")
+        return _http_json_response(
-        if model is not None:
+            self._with_settings_restart_state(payload, section="runtime")
-            model = model.strip()
+        )
-            if not model:
-                return _http_error(400, "model is required")
-            if defaults.model != model:
-                defaults.model = model
-                changed = True
-
-        provider = _query_first(query, "provider")
-        if provider is not None:
-            provider = provider.strip()
-            if not provider:
-                return _http_error(400, "provider is required")
-            if find_by_name(provider) is None:
-                return _http_error(400, "unknown provider")
-            provider_config = getattr(config.providers, provider, None)
-            spec = find_by_name(provider)
-            if (
-                provider_config is None
-                or spec is None
-                or not _provider_configured_for_settings(spec, provider_config)
-            ):
-                return _http_error(400, "provider is not configured")
-            if defaults.provider != provider:
-                defaults.provider = provider
-                changed = True
-
-        if changed:
-            save_config(config)
-        # LLM provider/model changes are hot-reloaded by AgentLoop before each
-        # new turn via the provider snapshot loader, so a restart is unnecessary.
-        return _http_json_response(self._settings_payload(requires_restart=False))
 
     def _handle_settings_provider_update(self, request: WsRequest) -> Response:
         if not self._check_api_token(request):
             return _http_error(401, "Unauthorized")
-        from nanobot.config.loader import load_config, save_config
-        from nanobot.providers.registry import find_by_name
-
         query = _parse_query(request.path)
-        provider_name = (_query_first(query, "provider") or "").strip()
+        try:
-        if not provider_name:
+            payload = update_provider_settings(query)
-            return _http_error(400, "provider is required")
+        except WebUISettingsError as e:
-        spec = find_by_name(provider_name)
+            return _http_error(e.status, e.message)
-        if spec is None or spec.is_oauth:
+        return _http_json_response(self._with_settings_restart_state(payload, section="image"))
-            return _http_error(400, "unknown provider")
-
-        config = load_config()
-        provider_config = getattr(config.providers, spec.name, None)
-        if provider_config is None:
-            return _http_error(400, "unknown provider")
-
-        changed = False
-        if "api_key" in query or "apiKey" in query:
-            api_key = _query_first(query, "api_key")
-            if api_key is None:
-                api_key = _query_first(query, "apiKey")
-            api_key = (api_key or "").strip() or None
-            if provider_config.api_key != api_key:
-                provider_config.api_key = api_key
-                changed = True
-
-        if "api_base" in query or "apiBase" in query:
-            api_base = _query_first(query, "api_base")
-            if api_base is None:
-                api_base = _query_first(query, "apiBase")
-            api_base = (api_base or "").strip() or None
-            if provider_config.api_base != api_base:
-                provider_config.api_base = api_base
-                changed = True
-
-        if changed:
-            save_config(config)
-        # API key/base changes are picked up by the next provider snapshot refresh.
-        return _http_json_response(self._settings_payload(requires_restart=False))
 
     def _handle_settings_web_search_update(self, request: WsRequest) -> Response:
         if not self._check_api_token(request):
             return _http_error(401, "Unauthorized")
-        from nanobot.config.loader import load_config, save_config
-
         query = _parse_query(request.path)
-        provider_name = (_query_first(query, "provider") or "").strip().lower()
+        try:
-        provider_option = _WEB_SEARCH_PROVIDER_BY_NAME.get(provider_name)
+            payload = update_web_search_settings(query)
-        if provider_option is None:
+        except WebUISettingsError as e:
-            return _http_error(400, "unknown web search provider")
+            return _http_error(e.status, e.message)
+        return _http_json_response(self._with_settings_restart_state(payload, section="web"))
 
-        config = load_config()
+    def _handle_settings_image_generation_update(self, request: WsRequest) -> Response:
-        search_config = config.tools.web.search
+        if not self._check_api_token(request):
-        previous_provider = search_config.provider
+            return _http_error(401, "Unauthorized")
-        changed = False
+        query = _parse_query(request.path)
-
+        try:
-        def set_value(attr: str, value: str | None) -> None:
+            payload = update_image_generation_settings(query)
-            nonlocal changed
+        except WebUISettingsError as e:
-            if getattr(search_config, attr) != value:
+            return _http_error(e.status, e.message)
-                setattr(search_config, attr, value)
+        return _http_json_response(self._with_settings_restart_state(payload, section="image"))
-                changed = True
-
-        if search_config.provider != provider_name:
-            search_config.provider = provider_name
-            changed = True
-
-        credential = provider_option["credential"]
-        if credential == "none":
-            set_value("api_key", "")
-            set_value("base_url", "")
-        elif credential == "base_url":
-            base_url = _query_first(query, "base_url")
-            if base_url is None:
-                base_url = _query_first(query, "baseUrl")
-            base_url = base_url.strip() if base_url is not None else None
-            if not base_url and previous_provider == provider_name and search_config.base_url:
-                base_url = search_config.base_url
-            if not base_url:
-                return _http_error(400, "base_url is required")
-            set_value("base_url", base_url)
-            set_value("api_key", "")
-        else:
-            api_key = _query_first(query, "api_key")
-            if api_key is None:
-                api_key = _query_first(query, "apiKey")
-            api_key = api_key.strip() if api_key is not None else None
-            if not api_key and previous_provider == provider_name and search_config.api_key:
-                api_key = search_config.api_key
-            if not api_key:
-                return _http_error(400, "api_key is required")
-            set_value("api_key", api_key)
-            set_value("base_url", "")
-
-        if changed:
-            save_config(config)
-        return _http_json_response(self._settings_payload(requires_restart=False))
 
     @staticmethod
     def _is_websocket_channel_session_key(key: str) -> bool:

nanobot/cli/commands.py

@@ -1,12 +1,14 @@
 """CLI commands for nanobot."""
 
 import asyncio
+import json
 import os
 import select
 import signal
 import sys
 from collections.abc import Callable
 from contextlib import nullcontext, suppress
+from inspect import signature
 from pathlib import Path
 from typing import Any
 
@@ -620,6 +622,7 @@ def serve(
 
     from nanobot.api.server import create_app
     from nanobot.bus.queue import MessageBus
+    from nanobot.providers.image_generation import image_gen_provider_configs
     from nanobot.session.manager import SessionManager
 
     if verbose:
@@ -639,12 +642,7 @@ def serve(
         agent_loop = AgentLoop.from_config(
             runtime_config, bus,
             session_manager=session_manager,
-            image_generation_provider_configs={
+            image_generation_provider_configs=image_gen_provider_configs(runtime_config),
-                "openrouter": runtime_config.providers.openrouter,
-                "aihubmix": runtime_config.providers.aihubmix,
-                "minimax": runtime_config.providers.minimax,
-                "gemini": runtime_config.providers.gemini,
-            },
         )
     except ValueError as exc:
         console.print(f"[red]Error: {exc}[/red]")
@@ -724,6 +722,7 @@ def _run_gateway(
     from nanobot.cron.types import CronJob
     from nanobot.heartbeat.service import HeartbeatService
     from nanobot.providers.factory import build_provider_snapshot, load_provider_snapshot
+    from nanobot.providers.image_generation import image_gen_provider_configs
     from nanobot.session.manager import SessionManager
 
     port = port if port is not None else config.gateway.port
@@ -754,12 +753,7 @@ def _run_gateway(
         context_window_tokens=provider_snapshot.context_window_tokens,
         cron_service=cron,
         session_manager=session_manager,
-        image_generation_provider_configs={
+        image_generation_provider_configs=image_gen_provider_configs(config),
-            "openrouter": config.providers.openrouter,
-            "aihubmix": config.providers.aihubmix,
-            "minimax": config.providers.minimax,
-            "gemini": config.providers.gemini,
-        },
         provider_snapshot_loader=load_provider_snapshot,
         runtime_model_publisher=lambda model, preset: publish_runtime_model_update(
             bus,
@@ -1126,6 +1120,7 @@ def agent(
 
     from nanobot.bus.queue import MessageBus
     from nanobot.cron.service import CronService
+    from nanobot.providers.image_generation import image_gen_provider_configs
 
     config = _load_runtime_config(config, workspace)
     sync_workspace_templates(config.workspace_path)
@@ -1149,6 +1144,7 @@ def agent(
         agent_loop = AgentLoop.from_config(
             config, bus,
             cron_service=cron,
+            image_generation_provider_configs=image_gen_provider_configs(config),
         )
     except ValueError as exc:
         console.print(f"[red]Error: {exc}[/red]")
@@ -1533,6 +1529,106 @@ def status():
                 console.print(f"{spec.label}: {'[green]✓[/green]' if has_key else '[dim]not set[/dim]'}")
 
 
+# ============================================================================
+# Config Commands
+# ============================================================================
+
+config_app = typer.Typer(help="Manage configuration")
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("set")
+def config_set(
+    path: str = typer.Argument(..., help="Dot path, e.g. agents.defaults.model"),
+    value: str = typer.Argument(..., help="Value. Use null/true/false or JSON for structured values."),
+    config_path: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+):
+    """Set one config value by dot path."""
+    from pydantic import ValidationError
+
+    from nanobot.config.loader import get_config_path, load_config, save_config, set_config_path
+    from nanobot.config.schema import Config
+
+    resolved_path = Path(config_path).expanduser().resolve() if config_path else get_config_path()
+    if config_path:
+        set_config_path(resolved_path)
+
+    config = load_config(resolved_path)
+    parsed = _parse_config_cli_value(value)
+    try:
+        _set_config_cli_value(config, path, parsed)
+        validated = Config.model_validate(config.model_dump(mode="json", by_alias=True))
+    except (AttributeError, KeyError, TypeError, ValueError, ValidationError) as exc:
+        console.print(f"[red]Could not set config value:[/red] {exc}")
+        raise typer.Exit(1)
+
+    save_config(validated, resolved_path)
+    console.print(f"[green]✓[/green] Set [cyan]{path}[/cyan] = [bold]{value}[/bold]")
+    console.print(f"[dim]Config: {resolved_path}[/dim]")
+    if path in {"agents.defaults.provider", "agents.defaults.model"} and validated.agents.defaults.model_preset:
+        console.print(
+            "[yellow]! agents.defaults.model_preset is set and may override this. "
+            "Clear it with: nanobot config set agents.defaults.model_preset null[/yellow]"
+        )
+
+
+def _parse_config_cli_value(raw: str) -> Any:
+    lowered = raw.strip().lower()
+    if lowered == "null":
+        return None
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    with suppress(Exception):
+        return json.loads(raw)
+    return raw
+
+
+def _resolve_config_field(obj: Any, key: str) -> str:
+    from pydantic import BaseModel
+    from pydantic.alias_generators import to_camel, to_snake
+
+    if not isinstance(obj, BaseModel):
+        return key
+    fields = type(obj).model_fields
+    if key in fields:
+        return key
+    normalized = to_snake(key.replace("-", "_"))
+    if normalized in fields:
+        return normalized
+    for name, field in fields.items():
+        aliases = {
+            to_camel(name),
+            str(field.alias) if field.alias else "",
+            str(field.serialization_alias) if field.serialization_alias else "",
+        }
+        if key in aliases:
+            return name
+    raise AttributeError(f"Unknown config path segment {key!r}")
+
+
+def _set_config_cli_value(config: Any, path: str, value: Any) -> None:
+    parts = [part for part in path.split(".") if part]
+    if not parts:
+        raise ValueError("Config path cannot be empty.")
+
+    current = config
+    for raw_part in parts[:-1]:
+        if isinstance(current, dict):
+            current = current.setdefault(raw_part, {})
+            continue
+        part = _resolve_config_field(current, raw_part)
+        current = getattr(current, part)
+
+    leaf = parts[-1]
+    if isinstance(current, dict):
+        current[leaf] = value
+        return
+    leaf = _resolve_config_field(current, leaf)
+    setattr(current, leaf, value)
+
+
 # ============================================================================
 # OAuth Login
 # ============================================================================
@@ -1547,6 +1643,7 @@ _LOGOUT_HANDLERS: dict[str, Callable[[], None]] = {}
 _PROVIDER_DISPLAY: dict[str, str] = {
     "openai_codex": "OpenAI Codex",
     "github_copilot": "GitHub Copilot",
+    "xai_oauth": "xAI Grok OAuth",
 }
 
 
@@ -1582,7 +1679,9 @@ def _resolve_oauth_provider(provider: str):
 
 @provider_app.command("login")
 def provider_login(
-    provider: str = typer.Argument(..., help="OAuth provider (e.g. 'openai-codex', 'github-copilot')"),
+    provider: str = typer.Argument(..., help="OAuth provider (e.g. 'openai-codex', 'github-copilot', 'xai-oauth')"),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print the auth URL instead of opening a browser when supported."),
+    manual_paste: bool = typer.Option(False, "--manual-paste", help="Prompt for a callback URL or fallback code when supported."),
 ):
     """Authenticate with an OAuth provider."""
     spec = _resolve_oauth_provider(provider)
@@ -1593,12 +1692,18 @@ def provider_login(
         raise typer.Exit(1)
 
     console.print(f"{__logo__} OAuth Login - {spec.label}\n")
-    handler()
+    params = signature(handler).parameters
+    kwargs: dict[str, bool] = {}
+    if "no_browser" in params:
+        kwargs["no_browser"] = no_browser
+    if "manual_paste" in params:
+        kwargs["manual_paste"] = manual_paste
+    handler(**kwargs)
 
 
 @provider_app.command("logout")
 def provider_logout(
-    provider: str = typer.Argument(..., help="OAuth provider (e.g. 'openai-codex', 'github-copilot')"),
+    provider: str = typer.Argument(..., help="OAuth provider (e.g. 'openai-codex', 'github-copilot', 'xai-oauth')"),
 ):
     """Log out from an OAuth provider."""
     spec = _resolve_oauth_provider(provider)
@@ -1662,6 +1767,24 @@ def _logout_github_copilot() -> None:
     _delete_oauth_files(storage.get_token_path(), _PROVIDER_DISPLAY["github_copilot"])
 
 
+@_register_logout("xai_oauth")
+def _logout_xai_oauth() -> None:
+    """Clear local OAuth credentials for xAI Grok OAuth."""
+    try:
+        from nanobot.providers.xai_oauth_provider import delete_xai_oauth_credentials
+    except ImportError:
+        console.print("[red]xAI Grok OAuth provider unavailable.[/red]")
+        raise typer.Exit(1)
+
+    removed_paths = delete_xai_oauth_credentials()
+    if not removed_paths:
+        console.print(f"[yellow]! No local OAuth credentials found for {_PROVIDER_DISPLAY['xai_oauth']}[/yellow]")
+        return
+    console.print(f"[green]✓ Logged out from {_PROVIDER_DISPLAY['xai_oauth']}[/green]")
+    for path in removed_paths:
+        console.print(f"[dim]Removed: {path}[/dim]")
+
+
 def _delete_oauth_files(token_path: Path, provider_label: str) -> None:
     """Delete OAuth token and lock files, reporting the result."""
     removed_paths: list[Path] = []
@@ -1705,5 +1828,36 @@ def _login_github_copilot() -> None:
         raise typer.Exit(1)
 
 
+@_register_login("xai_oauth")
+def _login_xai_oauth(
+    *,
+    no_browser: bool = False,
+    manual_paste: bool = False,
+) -> None:
+    try:
+        from nanobot.providers.xai_oauth_provider import login_xai_oauth_interactive
+        from nanobot.providers.xai_oauth_provider import DEFAULT_XAI_MODEL
+
+        console.print("[cyan]Starting xAI Grok OAuth login...[/cyan]\n")
+        credential = login_xai_oauth_interactive(
+            print_fn=lambda s: console.print(s),
+            prompt_fn=lambda s: typer.prompt(s),
+            open_browser=not no_browser,
+            manual_paste=manual_paste,
+        )
+        account = credential.account_id or "xAI"
+        storage = "OS keychain" if credential.storage == "keyring" else "private file"
+        console.print(f"[green]✓ Authenticated with xAI Grok OAuth[/green]  [dim]{account} · {storage}[/dim]")
+        console.print("[dim]To use it for chat:[/dim]")
+        console.print("[dim]  nanobot config set agents.defaults.model_preset null[/dim]")
+        console.print("[dim]  nanobot config set agents.defaults.provider xai-oauth[/dim]")
+        console.print(f"[dim]  nanobot config set agents.defaults.model {DEFAULT_XAI_MODEL}[/dim]")
+        console.print("[dim]Hosted X Search is enabled by default for xAI OAuth.[/dim]")
+        console.print("[dim]To disable it: nanobot config set providers.xai_oauth.x_search.enable false[/dim]")
+    except Exception as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+
+
 if __name__ == "__main__":
     app()

nanobot/config/schema.py

@@ -180,6 +180,28 @@ class BedrockProviderConfig(ProviderConfig):
     profile: str | None = None  # Optional AWS shared config profile
 
 
+class XaiOAuthXSearchConfig(Base):
+    """xAI hosted X Search configuration."""
+
+    enable: bool = True
+    allowed_x_handles: list[str] | None = None
+    excluded_x_handles: list[str] | None = None
+    from_date: str | None = None
+    to_date: str | None = None
+    enable_image_understanding: bool = False
+    enable_video_understanding: bool = False
+
+
+class XaiOAuthProviderConfig(ProviderConfig):
+    """xAI OAuth provider configuration."""
+
+    x_search: XaiOAuthXSearchConfig = Field(default_factory=XaiOAuthXSearchConfig)
+
+
+def _is_default_xai_oauth_config(value: Any) -> bool:
+    return isinstance(value, XaiOAuthProviderConfig) and value == XaiOAuthProviderConfig()
+
+
 class ProvidersConfig(Base):
     """Configuration for LLM providers."""
 
@@ -190,6 +212,7 @@ class ProvidersConfig(Base):
     openai: ProviderConfig = Field(default_factory=ProviderConfig)
     openrouter: ProviderConfig = Field(default_factory=ProviderConfig)
     huggingface: ProviderConfig = Field(default_factory=ProviderConfig)
+    skywork: ProviderConfig = Field(default_factory=ProviderConfig)  # Skywork / APIFree API gateway
     deepseek: ProviderConfig = Field(default_factory=ProviderConfig)
     groq: ProviderConfig = Field(default_factory=ProviderConfig)
     zhipu: ProviderConfig = Field(default_factory=ProviderConfig)
@@ -207,6 +230,7 @@ class ProvidersConfig(Base):
     stepfun: ProviderConfig = Field(default_factory=ProviderConfig)  # Step Fun (阶跃星辰)
     xiaomi_mimo: ProviderConfig = Field(default_factory=ProviderConfig)  # Xiaomi MIMO (小米)
     longcat: ProviderConfig = Field(default_factory=ProviderConfig)  # LongCat
+    ant_ling: ProviderConfig = Field(default_factory=ProviderConfig)  # Ant Ling
     aihubmix: ProviderConfig = Field(default_factory=ProviderConfig)  # AiHubMix API gateway
     siliconflow: ProviderConfig = Field(default_factory=ProviderConfig)  # SiliconFlow (硅基流动)
     volcengine: ProviderConfig = Field(default_factory=ProviderConfig)  # VolcEngine (火山引擎)
@@ -215,6 +239,10 @@ class ProvidersConfig(Base):
     byteplus_coding_plan: ProviderConfig = Field(default_factory=ProviderConfig)  # BytePlus Coding Plan
     openai_codex: ProviderConfig = Field(default_factory=ProviderConfig, exclude=True)  # OpenAI Codex (OAuth)
     github_copilot: ProviderConfig = Field(default_factory=ProviderConfig, exclude=True)  # Github Copilot (OAuth)
+    xai_oauth: XaiOAuthProviderConfig = Field(
+        default_factory=XaiOAuthProviderConfig,
+        exclude_if=_is_default_xai_oauth_config,
+    )  # xAI Grok OAuth
     qianfan: ProviderConfig = Field(default_factory=ProviderConfig)  # Qianfan (百度千帆)
     nvidia: ProviderConfig = Field(default_factory=ProviderConfig)  # NVIDIA NIM (nvapi- keys)
 

nanobot/cron/__init__.py

@@ -1,6 +1,18 @@
 """Cron service for scheduled agent tasks."""
 
-from nanobot.cron.service import CronService
 from nanobot.cron.types import CronJob, CronSchedule
 
 __all__ = ["CronService", "CronJob", "CronSchedule"]
+
+_LAZY = {"CronService": ".service"}
+
+
+def __getattr__(name: str):
+    module_path = _LAZY.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+    mod = import_module(module_path, __name__)
+    val = getattr(mod, name)
+    globals()[name] = val
+    return val

nanobot/nanobot.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from nanobot.agent.hook import AgentHook, SDKCaptureHook
 from nanobot.agent.loop import AgentLoop
+from nanobot.providers.image_generation import image_gen_provider_configs
 
 
 @dataclass(slots=True)
@@ -63,12 +64,7 @@ class Nanobot:
 
         loop = AgentLoop.from_config(
             config,
-            image_generation_provider_configs={
+            image_generation_provider_configs=image_gen_provider_configs(config),
-                "openrouter": config.providers.openrouter,
-                "aihubmix": config.providers.aihubmix,
-                "minimax": config.providers.minimax,
-                "gemini": config.providers.gemini,
-            },
         )
         return cls(loop)
 

nanobot/providers/__init__.py

@@ -14,6 +14,7 @@ __all__ = [
     "OpenAICompatProvider",
     "OpenAICodexProvider",
     "GitHubCopilotProvider",
+    "XaiOAuthProvider",
     "AzureOpenAIProvider",
     "BedrockProvider",
 ]
@@ -23,10 +24,23 @@ _LAZY_IMPORTS = {
     "OpenAICompatProvider": ".openai_compat_provider",
     "OpenAICodexProvider": ".openai_codex_provider",
     "GitHubCopilotProvider": ".github_copilot_provider",
+    "XaiOAuthProvider": ".xai_oauth_provider",
     "AzureOpenAIProvider": ".azure_openai_provider",
     "BedrockProvider": ".bedrock_provider",
 }
 
+_LAZY_SUBMODULES = {
+    "anthropic_provider": ".anthropic_provider",
+    "openai_compat_provider": ".openai_compat_provider",
+    "openai_codex_provider": ".openai_codex_provider",
+    "github_copilot_provider": ".github_copilot_provider",
+    "xai_oauth_provider": ".xai_oauth_provider",
+    "azure_openai_provider": ".azure_openai_provider",
+    "bedrock_provider": ".bedrock_provider",
+    "factory": ".factory",
+    "registry": ".registry",
+}
+
 if TYPE_CHECKING:
     from nanobot.providers.anthropic_provider import AnthropicProvider
     from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
@@ -34,12 +48,18 @@ if TYPE_CHECKING:
     from nanobot.providers.github_copilot_provider import GitHubCopilotProvider
     from nanobot.providers.openai_compat_provider import OpenAICompatProvider
     from nanobot.providers.openai_codex_provider import OpenAICodexProvider
+    from nanobot.providers.xai_oauth_provider import XaiOAuthProvider
 
 
 def __getattr__(name: str):
     """Lazily expose provider implementations without importing all backends up front."""
     module_name = _LAZY_IMPORTS.get(name)
-    if module_name is None:
+    if module_name is not None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        module = import_module(module_name, __name__)
-    module = import_module(module_name, __name__)
+        return getattr(module, name)
-    return getattr(module, name)
+    module_name = _LAZY_SUBMODULES.get(name)
+    if module_name is not None:
+        module = import_module(module_name, __name__)
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nanobot/providers/anthropic_provider.py

@@ -590,6 +590,7 @@ class AnthropicProvider(LLMProvider):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
         kwargs = self._build_kwargs(
             messages, tools, model, max_tokens, temperature,
@@ -598,11 +599,12 @@ class AnthropicProvider(LLMProvider):
         idle_timeout_s = int(os.environ.get("NANOBOT_STREAM_IDLE_TIMEOUT_S", "90"))
         try:
             async with self._client.messages.stream(**kwargs) as stream:
-                if on_content_delta or on_thinking_delta:
+                if on_content_delta or on_thinking_delta or on_tool_call_delta:
                     # Idle timeout must track *any* SSE chunk (thinking_delta,
                     # tool JSON deltas, etc.), not only text_stream tokens.
                     # Otherwise extended thinking can stall text_stream for minutes
                     # while the connection is healthy (e.g. MiniMax Anthropic).
+                    tool_blocks: dict[int, dict[str, str]] = {}
                     while True:
                         try:
                             chunk = await asyncio.wait_for(
@@ -611,7 +613,22 @@ class AnthropicProvider(LLMProvider):
                             )
                         except StopAsyncIteration:
                             break
-                        if (
+                        if chunk.type == "content_block_start":
+                            block = getattr(chunk, "content_block", None)
+                            if getattr(block, "type", None) == "tool_use":
+                                index = int(getattr(chunk, "index", 0) or 0)
+                                state = {
+                                    "call_id": str(getattr(block, "id", "") or ""),
+                                    "name": str(getattr(block, "name", "") or ""),
+                                }
+                                tool_blocks[index] = state
+                                if on_tool_call_delta:
+                                    await on_tool_call_delta({
+                                        "index": index,
+                                        **state,
+                                        "arguments_delta": "",
+                                    })
+                        elif (
                             chunk.type == "content_block_delta"
                             and getattr(chunk.delta, "type", None) == "thinking_delta"
                         ):
@@ -625,6 +642,20 @@ class AnthropicProvider(LLMProvider):
                             text = getattr(chunk.delta, "text", None) or ""
                             if text and on_content_delta:
                                 await on_content_delta(text)
+                        elif (
+                            chunk.type == "content_block_delta"
+                            and getattr(chunk.delta, "type", None) == "input_json_delta"
+                        ):
+                            partial = getattr(chunk.delta, "partial_json", None) or ""
+                            if partial and on_tool_call_delta:
+                                index = int(getattr(chunk, "index", 0) or 0)
+                                state = tool_blocks.get(index, {})
+                                await on_tool_call_delta({
+                                    "index": index,
+                                    "call_id": state.get("call_id", ""),
+                                    "name": state.get("name", ""),
+                                    "arguments_delta": partial,
+                                })
                 response = await asyncio.wait_for(
                     stream.get_final_message(),
                     timeout=idle_timeout_s,

nanobot/providers/azure_openai_provider.py

@@ -158,6 +158,7 @@ class AzureOpenAIProvider(LLMProvider):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
         _ = on_thinking_delta
         body = self._build_body(
@@ -169,7 +170,7 @@ class AzureOpenAIProvider(LLMProvider):
         try:
             stream = await self._client.responses.create(**body)
             content, tool_calls, finish_reason, usage, reasoning_content = (
-                await consume_sdk_stream(stream, on_content_delta)
+                await consume_sdk_stream(stream, on_content_delta, on_tool_call_delta)
             )
             return LLMResponse(
                 content=content or None,

nanobot/providers/base.py

@@ -70,11 +70,11 @@ class LLMResponse:
 
     @property
     def should_execute_tools(self) -> bool:
-        """Tools execute only when has_tool_calls AND finish_reason is ``tool_calls`` / ``stop``.
+        """Tools execute only when has_tool_calls AND finish_reason is a tool-capable stop.
         Blocks gateway-injected calls under ``refusal`` / ``content_filter`` / ``error`` (#3220)."""
         if not self.has_tool_calls:
             return False
-        return self.finish_reason in ("tool_calls", "stop")
+        return self.finish_reason in ("tool_calls", "function_call", "stop")
 
 
 @dataclass(frozen=True)
@@ -501,6 +501,7 @@ class LLMProvider(ABC):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
         """Stream a chat completion, calling *on_content_delta* for each text chunk.
 
@@ -514,7 +515,7 @@ class LLMProvider(ABC):
         full content as a single delta.  Providers that support native
         streaming should override this method.
         """
-        _ = on_thinking_delta
+        _ = on_thinking_delta, on_tool_call_delta
         response = await self.chat(
             messages=messages, tools=tools, model=model,
             max_tokens=max_tokens, temperature=temperature,
@@ -544,6 +545,7 @@ class LLMProvider(ABC):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
         retry_mode: str = "standard",
         on_retry_wait: Callable[[str], Awaitable[None]] | None = None,
     ) -> LLMResponse:
@@ -561,6 +563,7 @@ class LLMProvider(ABC):
             reasoning_effort=reasoning_effort, tool_choice=tool_choice,
             on_content_delta=on_content_delta,
             on_thinking_delta=on_thinking_delta,
+            on_tool_call_delta=on_tool_call_delta,
         )
         return await self._run_with_retry(
             self._safe_chat_stream,

nanobot/providers/bedrock_provider.py

@@ -704,8 +704,9 @@ class BedrockProvider(LLMProvider):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
-        _ = on_thinking_delta
+        _ = on_thinking_delta, on_tool_call_delta
         idle_timeout_s = int(os.environ.get("NANOBOT_STREAM_IDLE_TIMEOUT_S", "90"))
         content_parts: list[str] = []
         reasoning_parts: list[str] = []

nanobot/providers/factory.py

@@ -68,6 +68,10 @@ def _make_provider_core(
         from nanobot.providers.github_copilot_provider import GitHubCopilotProvider
 
         provider = GitHubCopilotProvider(default_model=model)
+    elif backend == "xai_oauth":
+        from nanobot.providers.xai_oauth_provider import XaiOAuthProvider
+
+        provider = XaiOAuthProvider(default_model=model, config=p)
     elif backend == "anthropic":
         from nanobot.providers.anthropic_provider import AnthropicProvider
 

nanobot/providers/github_copilot_provider.py

@@ -207,8 +207,9 @@ class GitHubCopilotProvider(OpenAICompatProvider):
 
     async def _refresh_client_api_key(self) -> str:
         token = await self._get_copilot_access_token()
+        client = await self._ensure_client()
         self.api_key = token
-        self._client.api_key = token
+        client.api_key = token
         return token
 
     async def chat(
@@ -243,6 +244,7 @@ class GitHubCopilotProvider(OpenAICompatProvider):
         tool_choice: str | dict[str, object] | None = None,
         on_content_delta: Callable[[str], None] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, object]], Awaitable[None]] | None = None,
     ):
         await self._refresh_client_api_key()
         return await super().chat_stream(
@@ -255,4 +257,5 @@ class GitHubCopilotProvider(OpenAICompatProvider):
             tool_choice=tool_choice,
             on_content_delta=on_content_delta,
             on_thinking_delta=on_thinking_delta,
+            on_tool_call_delta=on_tool_call_delta,
         )

nanobot/providers/image_generation.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import base64
+import binascii
+from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -44,15 +46,6 @@ class GeneratedImageResponse:
     raw: dict[str, Any]
 
 
-def _provider_base_url(provider: str, api_base: str | None, fallback: str) -> str:
-    if api_base:
-        return api_base.rstrip("/")
-    spec = find_by_name(provider)
-    if spec and spec.default_api_base:
-        return spec.default_api_base.rstrip("/")
-    return fallback
-
-
 def _read_image_b64(path: str | Path) -> tuple[str, str]:
     """Return ``(mime, base64)`` for the image at ``path``."""
     p = Path(path).expanduser()
@@ -75,8 +68,16 @@ def image_path_to_inline_data(path: str | Path) -> dict[str, str]:
     return {"mimeType": mime, "data": encoded}
 
 
-def _b64_png_data_url(value: str) -> str:
+def _b64_image_data_url(value: str) -> str:
-    return f"data:image/png;base64,{value}"
+    encoded = "".join(value.split())
+    try:
+        raw = base64.b64decode(encoded, validate=True)
+    except binascii.Error as exc:
+        raise ImageGenerationError("generated image payload was not valid base64") from exc
+    mime = detect_image_mime(raw)
+    if mime is None:
+        raise ImageGenerationError("generated image payload was not a supported image")
+    return f"data:{mime};base64,{encoded}"
 
 
 def _aihubmix_size(aspect_ratio: str | None, image_size: str | None) -> str:
@@ -120,8 +121,49 @@ async def _download_image_data_url(
     return f"data:{mime};base64,{encoded}"
 
 
-class OpenRouterImageGenerationClient:
+# ---------------------------------------------------------------------------
-    """Small async client for OpenRouter Chat Completions image generation."""
+# Registry
+# ---------------------------------------------------------------------------
+
+_IMAGE_GEN_PROVIDERS: dict[str, type[ImageGenerationProvider]] = {}
+
+
+def register_image_gen_provider(cls: type[ImageGenerationProvider]) -> None:
+    name = cls.provider_name
+    if not name:
+        raise ValueError(f"{cls.__name__} must set provider_name")
+    _IMAGE_GEN_PROVIDERS[name] = cls
+
+
+def get_image_gen_provider(name: str) -> type[ImageGenerationProvider] | None:
+    return _IMAGE_GEN_PROVIDERS.get(name)
+
+
+def image_gen_provider_names() -> tuple[str, ...]:
+    """Return registered image generation provider names in registry order."""
+    return tuple(_IMAGE_GEN_PROVIDERS)
+
+
+def image_gen_provider_configs(config: Any) -> dict[str, Any]:
+    providers_cfg = config.providers
+    return {
+        name: pc
+        for name in _IMAGE_GEN_PROVIDERS
+        if (pc := getattr(providers_cfg, name, None)) is not None
+    }
+
+
+# ---------------------------------------------------------------------------
+# Base class
+# ---------------------------------------------------------------------------
+
+
+class ImageGenerationProvider(ABC):
+    """Base class for image generation provider clients."""
+
+    provider_name: str = ""
+    missing_key_message: str = ""
+    default_timeout: float = _DEFAULT_TIMEOUT_S
 
     def __init__(
         self,
@@ -130,20 +172,71 @@ class OpenRouterImageGenerationClient:
         api_base: str | None = None,
         extra_headers: dict[str, str] | None = None,
         extra_body: dict[str, Any] | None = None,
-        timeout: float = _DEFAULT_TIMEOUT_S,
+        timeout: float | None = None,
         client: httpx.AsyncClient | None = None,
     ) -> None:
         self.api_key = api_key
-        self.api_base = _provider_base_url(
+        self.api_base = self._resolve_base_url(api_base)
-            "openrouter",
-            api_base,
-            "https://openrouter.ai/api/v1",
-        )
         self.extra_headers = extra_headers or {}
         self.extra_body = extra_body or {}
-        self.timeout = timeout
+        self.timeout = timeout if timeout is not None else self.default_timeout
         self._client = client
 
+    def _resolve_base_url(self, api_base: str | None) -> str:
+        if api_base:
+            return api_base.rstrip("/")
+        spec = find_by_name(self.provider_name)
+        if spec and spec.default_api_base:
+            return spec.default_api_base.rstrip("/")
+        return self._default_base_url()
+
+    def _default_base_url(self) -> str:
+        return ""
+
+    @abstractmethod
+    async def generate(
+        self,
+        *,
+        prompt: str,
+        model: str,
+        reference_images: list[str] | None = None,
+        aspect_ratio: str | None = None,
+        image_size: str | None = None,
+    ) -> GeneratedImageResponse: ...
+
+    def _require_images(self, images: list[str], data: dict[str, Any]) -> None:
+        if images:
+            return
+        provider_error = data.get("error") if isinstance(data, dict) else None
+        label = self.provider_name
+        if provider_error:
+            raise ImageGenerationError(f"{label} returned no images: {provider_error}")
+        raise ImageGenerationError(f"{label} returned no images for this request")
+
+    async def _http_post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        body: dict[str, Any],
+    ) -> httpx.Response:
+        if self._client is not None:
+            return await self._client.post(url, headers=headers, json=body)
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            return await c.post(url, headers=headers, json=body)
+
+
+class OpenRouterImageGenerationClient(ImageGenerationProvider):
+    """Small async client for OpenRouter Chat Completions image generation."""
+
+    provider_name = "openrouter"
+    missing_key_message = (
+        "OpenRouter API key is not configured. Set providers.openrouter.apiKey."
+    )
+
+    def _default_base_url(self) -> str:
+        return "https://openrouter.ai/api/v1"
+
     async def generate(
         self,
         *,
@@ -154,9 +247,7 @@ class OpenRouterImageGenerationClient:
         image_size: str | None = None,
     ) -> GeneratedImageResponse:
         if not self.api_key:
-            raise ImageGenerationError(
+            raise ImageGenerationError(self.missing_key_message)
-                "OpenRouter API key is not configured. Set providers.openrouter.apiKey."
-            )
 
         content: str | list[dict[str, Any]]
         references = list(reference_images or [])
@@ -192,12 +283,7 @@ class OpenRouterImageGenerationClient:
             **self.extra_headers,
         }
         url = f"{self.api_base}/chat/completions"
-
+        response = await self._http_post(url, headers=headers, body=body)
-        if self._client is not None:
-            response = await self._client.post(url, headers=headers, json=body)
-        else:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.post(url, headers=headers, json=body)
 
         try:
             response.raise_for_status()
@@ -222,11 +308,7 @@ class OpenRouterImageGenerationClient:
                 if isinstance(url_value, str) and url_value.startswith("data:image/"):
                     images.append(url_value)
 
-        if not images:
+        self._require_images(images, data)
-            provider_error = data.get("error") if isinstance(data, dict) else None
-            if provider_error:
-                raise ImageGenerationError(f"OpenRouter returned no images: {provider_error}")
-            raise ImageGenerationError("OpenRouter returned no images for this request")
 
         return GeneratedImageResponse(
             images=images,
@@ -235,29 +317,17 @@ class OpenRouterImageGenerationClient:
         )
 
 
-class AIHubMixImageGenerationClient:
+class AIHubMixImageGenerationClient(ImageGenerationProvider):
     """Small async client for AIHubMix unified image generation."""
 
-    def __init__(
+    provider_name = "aihubmix"
-        self,
+    missing_key_message = (
-        *,
+        "AIHubMix API key is not configured. Set providers.aihubmix.apiKey."
-        api_key: str | None,
+    )
-        api_base: str | None = None,
+    default_timeout = _AIHUBMIX_TIMEOUT_S
-        extra_headers: dict[str, str] | None = None,
+
-        extra_body: dict[str, Any] | None = None,
+    def _default_base_url(self) -> str:
-        timeout: float = _AIHUBMIX_TIMEOUT_S,
+        return "https://aihubmix.com/v1"
-        client: httpx.AsyncClient | None = None,
-    ) -> None:
-        self.api_key = api_key
-        self.api_base = _provider_base_url(
-            "aihubmix",
-            api_base,
-            "https://aihubmix.com/v1",
-        )
-        self.extra_headers = extra_headers or {}
-        self.extra_body = extra_body or {}
-        self.timeout = timeout
-        self._client = client
 
     async def generate(
         self,
@@ -269,9 +339,7 @@ class AIHubMixImageGenerationClient:
         image_size: str | None = None,
     ) -> GeneratedImageResponse:
         if not self.api_key:
-            raise ImageGenerationError(
+            raise ImageGenerationError(self.missing_key_message)
-                "AIHubMix API key is not configured. Set providers.aihubmix.apiKey."
-            )
 
         refs = list(reference_images or [])
         headers = {
@@ -280,16 +348,8 @@ class AIHubMixImageGenerationClient:
         }
         size = _aihubmix_size(aspect_ratio, image_size)
 
-        if self._client is not None:
+        client = self._client or httpx.AsyncClient(timeout=self.timeout)
-            return await self._generate_with_client(
+        try:
-                self._client,
-                prompt=prompt,
-                model=model,
-                reference_images=refs,
-                size=size,
-                headers=headers,
-            )
-        async with httpx.AsyncClient(timeout=self.timeout) as client:
             return await self._generate_with_client(
                 client,
                 prompt=prompt,
@@ -298,6 +358,9 @@ class AIHubMixImageGenerationClient:
                 size=size,
                 headers=headers,
             )
+        finally:
+            if self._client is None:
+                await client.aclose()
 
     async def _generate_with_client(
         self,
@@ -346,11 +409,7 @@ class AIHubMixImageGenerationClient:
         payload = response.json()
         images = await _aihubmix_images_from_payload(client, payload)
 
-        if not images:
+        self._require_images(images, payload)
-            provider_error = payload.get("error") if isinstance(payload, dict) else None
-            if provider_error:
-                raise ImageGenerationError(f"AIHubMix returned no images: {provider_error}")
-            raise ImageGenerationError("AIHubMix returned no images for this request")
 
         return GeneratedImageResponse(images=images, content="", raw=payload)
 
@@ -370,31 +429,25 @@ def _http_error_detail(response: httpx.Response) -> str:
     return response.text[:500] or "<empty response body>"
 
 
-class GeminiImageGenerationClient:
+class GeminiImageGenerationClient(ImageGenerationProvider):
     """Async client for Gemini/Imagen image generation via the Generative Language API."""
 
-    def __init__(
+    provider_name = "gemini"
-        self,
+    missing_key_message = (
-        *,
+        "Gemini API key is not configured. Set providers.gemini.apiKey."
-        api_key: str | None,
+    )
-        api_base: str | None = None,
+    default_timeout = _GEMINI_DEFAULT_TIMEOUT_S
-        extra_headers: dict[str, str] | None = None,
+
-        extra_body: dict[str, Any] | None = None,
+    def _default_base_url(self) -> str:
-        timeout: float = _GEMINI_DEFAULT_TIMEOUT_S,
+        return "https://generativelanguage.googleapis.com/v1beta"
-        client: httpx.AsyncClient | None = None,
+
-    ) -> None:
+    def _resolve_base_url(self, api_base: str | None) -> str:
-        self.api_key = api_key
         # The Gemini provider's registry default_api_base is the OpenAI-compat
-        # shim (.../v1beta/openai/), which has no image endpoints. Image
+        # shim (.../v1beta/openai/), which has no image endpoints.
-        # generation needs the native Generative Language API base, so we don't
+        # Skip the registry lookup and use the native API base directly.
-        # use _provider_base_url() here.
+        if api_base:
-        self.api_base = (
+            return api_base.rstrip("/")
-            api_base or "https://generativelanguage.googleapis.com/v1beta"
+        return self._default_base_url()
-        ).rstrip("/")
-        self.extra_headers = extra_headers or {}
-        self.extra_body = extra_body or {}
-        self.timeout = timeout
-        self._client = client
 
     async def generate(
         self,
@@ -406,9 +459,7 @@ class GeminiImageGenerationClient:
         image_size: str | None = None,
     ) -> GeneratedImageResponse:
         if not self.api_key:
-            raise ImageGenerationError(
+            raise ImageGenerationError(self.missing_key_message)
-                "Gemini API key is not configured. Set providers.gemini.apiKey."
-            )
         if "imagen" in model.lower():
             if reference_images:
                 logger.warning(
@@ -446,12 +497,7 @@ class GeminiImageGenerationClient:
             "Content-Type": "application/json",
             **self.extra_headers,
         }
-
+        response = await self._http_post(url, headers=headers, body=body)
-        if self._client is not None:
-            response = await self._client.post(url, headers=headers, json=body)
-        else:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.post(url, headers=headers, json=body)
 
         try:
             response.raise_for_status()
@@ -472,11 +518,7 @@ class GeminiImageGenerationClient:
             if isinstance(b64, str) and b64:
                 images.append(f"data:{mime};base64,{b64}")
 
-        if not images:
+        self._require_images(images, data)
-            provider_error = data.get("error") if isinstance(data, dict) else None
-            if provider_error:
-                raise ImageGenerationError(f"Gemini Imagen returned no images: {provider_error}")
-            raise ImageGenerationError("Gemini Imagen returned no images for this request")
 
         return GeneratedImageResponse(images=images, content="", raw=data)
 
@@ -504,12 +546,7 @@ class GeminiImageGenerationClient:
             "Content-Type": "application/json",
             **self.extra_headers,
         }
-
+        response = await self._http_post(url, headers=headers, body=body)
-        if self._client is not None:
-            response = await self._client.post(url, headers=headers, json=body)
-        else:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.post(url, headers=headers, json=body)
 
         try:
             response.raise_for_status()
@@ -539,11 +576,7 @@ class GeminiImageGenerationClient:
                     if b64:
                         images.append(f"data:{mime};base64,{b64}")
 
-        if not images:
+        self._require_images(images, data)
-            provider_error = data.get("error") if isinstance(data, dict) else None
-            if provider_error:
-                raise ImageGenerationError(f"Gemini returned no images: {provider_error}")
-            raise ImageGenerationError("Gemini returned no images for this request")
 
         return GeneratedImageResponse(
             images=images,
@@ -579,13 +612,13 @@ async def _aihubmix_images_from_payload(
 
         b64_json = value.get("b64_json")
         if isinstance(b64_json, str) and b64_json:
-            images.append(_b64_png_data_url(b64_json))
+            images.append(_b64_image_data_url(b64_json))
         elif b64_json is not None:
             await collect(b64_json)
 
         bytes_base64 = value.get("bytesBase64") or value.get("bytes_base64") or value.get("base64")
         if isinstance(bytes_base64, str) and bytes_base64:
-            images.append(_b64_png_data_url(bytes_base64))
+            images.append(_b64_image_data_url(bytes_base64))
 
         image_url = value.get("image_url") or value.get("imageUrl")
         if isinstance(image_url, dict):
@@ -620,29 +653,17 @@ _MINIMAX_ASPECT_RATIO_SIZES = {
 }
 
 
-class MiniMaxImageGenerationClient:
+class MiniMaxImageGenerationClient(ImageGenerationProvider):
     """Async client for MiniMax image generation API."""
 
-    def __init__(
+    provider_name = "minimax"
-        self,
+    missing_key_message = (
-        *,
+        "MiniMax API key is not configured. Set providers.minimax.apiKey."
-        api_key: str | None,
+    )
-        api_base: str | None = None,
+    default_timeout = _MINIMAX_TIMEOUT_S
-        extra_headers: dict[str, str] | None = None,
+
-        extra_body: dict[str, Any] | None = None,
+    def _default_base_url(self) -> str:
-        timeout: float = _MINIMAX_TIMEOUT_S,
+        return "https://api.minimaxi.com/v1"
-        client: httpx.AsyncClient | None = None,
-    ) -> None:
-        self.api_key = api_key
-        self.api_base = _provider_base_url(
-            "minimax",
-            api_base,
-            "https://api.minimaxi.com/v1",
-        )
-        self.extra_headers = extra_headers or {}
-        self.extra_body = extra_body or {}
-        self.timeout = timeout
-        self._client = client
 
     def _resolve_aspect_ratio(self, aspect_ratio: str | None) -> str:
         if aspect_ratio and aspect_ratio in _MINIMAX_ASPECT_RATIO_SIZES:
@@ -659,9 +680,7 @@ class MiniMaxImageGenerationClient:
         image_size: str | None = None,
     ) -> GeneratedImageResponse:
         if not self.api_key:
-            raise ImageGenerationError(
+            raise ImageGenerationError(self.missing_key_message)
-                "MiniMax API key is not configured. Set providers.minimax.apiKey."
-            )
 
         headers = {
             "Authorization": f"Bearer {self.api_key}",
@@ -687,10 +706,12 @@ class MiniMaxImageGenerationClient:
 
         body.update(self.extra_body)
 
-        if self._client is not None:
+        client = self._client or httpx.AsyncClient(timeout=self.timeout)
-            return await self._generate_with_client(self._client, body, headers)
+        try:
-        async with httpx.AsyncClient(timeout=self.timeout) as client:
             return await self._generate_with_client(client, body, headers)
+        finally:
+            if self._client is None:
+                await client.aclose()
 
     async def _generate_with_client(
         self,
@@ -715,11 +736,7 @@ class MiniMaxImageGenerationClient:
         payload = response.json()
         images = _minimax_images_from_payload(payload)
 
-        if not images:
+        self._require_images(images, payload)
-            provider_error = payload.get("error") if isinstance(payload, dict) else None
-            if provider_error:
-                raise ImageGenerationError(f"MiniMax returned no images: {provider_error}")
-            raise ImageGenerationError("MiniMax returned no images for this request")
 
         return GeneratedImageResponse(images=images, content="", raw=payload)
 
@@ -735,5 +752,139 @@ def _minimax_images_from_payload(payload: dict[str, Any]) -> list[str]:
         return images
     for b64 in data.get("image_base64") or []:
         if isinstance(b64, str) and b64:
-            images.append(_b64_png_data_url(b64))
+            images.append(_b64_image_data_url(b64))
     return images
+
+
+# ---------------------------------------------------------------------------
+# StepFun (阶跃星辰) image generation
+# ---------------------------------------------------------------------------
+
+_STEPFUN_ASPECT_RATIO_SIZES = {
+    "1:1": "1024x1024",
+    "16:9": "1280x800",
+    "9:16": "800x1280",
+    "3:4": "768x1360",
+    "4:3": "1360x768",
+}
+
+
+class StepFunImageGenerationClient(ImageGenerationProvider):
+    """Async client for StepFun (阶跃星辰) image generation.
+
+    Supports:
+    - Text-to-image via step-image-edit-2 (default model)
+    - Reference-image-guided generation via style_reference (step-1x-medium)
+    """
+
+    provider_name = "stepfun"
+    missing_key_message = (
+        "StepFun API key is not configured. Set providers.stepfun.apiKey."
+    )
+    default_timeout = 120.0
+
+    def _default_base_url(self) -> str:
+        return "https://api.stepfun.com/v1"
+
+    async def generate(
+        self,
+        *,
+        prompt: str,
+        model: str,
+        reference_images: list[str] | None = None,
+        aspect_ratio: str | None = None,
+        image_size: str | None = None,
+    ) -> GeneratedImageResponse:
+        if not self.api_key:
+            raise ImageGenerationError(self.missing_key_message)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            **self.extra_headers,
+        }
+
+        body: dict[str, Any] = {
+            "model": model,
+            "prompt": prompt,
+            "response_format": "b64_json",
+            "n": 1,
+        }
+
+        # Map aspect ratio / image_size to StepFun size string
+        size = _stepfun_size(aspect_ratio, image_size)
+        if size:
+            body["size"] = size
+
+        # step-1x-medium supports style_reference for reference-image-guided generation
+        refs = list(reference_images or [])
+        if refs and "1x" in model:
+            body["style_reference"] = {
+                "source_url": image_path_to_data_url(refs[0]),
+            }
+
+        body.update(self.extra_body)
+
+        response = await self._http_post(
+            f"{self.api_base}/images/generations",
+            headers=headers,
+            body=body,
+        )
+
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = response.text[:500]
+            raise ImageGenerationError(
+                f"StepFun image generation failed: {detail}"
+            ) from exc
+
+        payload = response.json()
+        images = _stepfun_images_from_payload(payload)
+
+        self._require_images(images, payload)
+
+        return GeneratedImageResponse(images=images, content="", raw=payload)
+
+
+def _stepfun_size(
+    aspect_ratio: str | None,
+    image_size: str | None,
+) -> str:
+    """Resolve aspect ratio / image_size to StepFun size string.
+
+    StepFun expects ``WIDTHxHEIGHT`` (note: width x height, not the more
+    common ``HxW`` order used by other providers).  The accepted sizes are
+    ``1024x1024``, ``768x1360``, ``896x1184``, ``1360x768``, ``1184x896``.
+    """
+    if image_size and "x" in image_size.lower():
+        return image_size
+    if aspect_ratio and aspect_ratio in _STEPFUN_ASPECT_RATIO_SIZES:
+        return _STEPFUN_ASPECT_RATIO_SIZES[aspect_ratio]
+    return "1024x1024"
+
+
+def _stepfun_images_from_payload(payload: dict[str, Any]) -> list[str]:
+    """Extract base64 images from StepFun API response.
+
+    StepFun returns images in ``data[].b64_json`` (base64 strings).
+    """
+    images: list[str] = []
+    for item in payload.get("data") or []:
+        if not isinstance(item, dict):
+            continue
+        b64 = item.get("b64_json")
+        if isinstance(b64, str) and b64:
+            images.append(_b64_image_data_url(b64))
+    return images
+
+
+# ---------------------------------------------------------------------------
+# Provider registration
+# ---------------------------------------------------------------------------
+
+register_image_gen_provider(OpenRouterImageGenerationClient)
+register_image_gen_provider(AIHubMixImageGenerationClient)
+register_image_gen_provider(GeminiImageGenerationClient)
+register_image_gen_provider(MiniMaxImageGenerationClient)
+register_image_gen_provider(StepFunImageGenerationClient)

nanobot/providers/openai_codex_provider.py

@@ -40,6 +40,7 @@ class OpenAICodexProvider(LLMProvider):
         reasoning_effort: str | None,
         tool_choice: str | dict[str, Any] | None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
         """Shared request logic for both chat() and chat_stream()."""
         model = model or self.default_model
@@ -70,6 +71,7 @@ class OpenAICodexProvider(LLMProvider):
                 content, tool_calls, finish_reason = await _request_codex(
                     DEFAULT_CODEX_URL, headers, body, verify=True,
                     on_content_delta=on_content_delta,
+                    on_tool_call_delta=on_tool_call_delta,
                 )
             except Exception as e:
                 if "CERTIFICATE_VERIFY_FAILED" not in str(e):
@@ -78,6 +80,7 @@ class OpenAICodexProvider(LLMProvider):
                 content, tool_calls, finish_reason = await _request_codex(
                     DEFAULT_CODEX_URL, headers, body, verify=False,
                     on_content_delta=on_content_delta,
+                    on_tool_call_delta=on_tool_call_delta,
                 )
             return LLMResponse(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
         except Exception as e:
@@ -100,9 +103,18 @@ class OpenAICodexProvider(LLMProvider):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
         _ = on_thinking_delta
-        return await self._call_codex(messages, tools, model, reasoning_effort, tool_choice, on_content_delta)
+        return await self._call_codex(
+            messages,
+            tools,
+            model,
+            reasoning_effort,
+            tool_choice,
+            on_content_delta,
+            on_tool_call_delta,
+        )
 
     def get_default_model(self) -> str:
         return self.default_model
@@ -138,6 +150,7 @@ async def _request_codex(
     body: dict[str, Any],
     verify: bool,
     on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+    on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
 ) -> tuple[str, list[ToolCallRequest], str]:
     async with httpx.AsyncClient(timeout=60.0, verify=verify) as client:
         async with client.stream("POST", url, headers=headers, json=body) as response:
@@ -148,7 +161,7 @@ async def _request_codex(
                     _friendly_error(response.status_code, text.decode("utf-8", "ignore")),
                     retry_after=retry_after,
                 )
-            return await consume_sse(response, on_content_delta)
+            return await consume_sse(response, on_content_delta, on_tool_call_delta)
 
 
 def _prompt_cache_key(messages: list[dict[str, Any]]) -> str:

nanobot/providers/openai_compat_provider.py

@@ -16,20 +16,9 @@ from ipaddress import ip_address
 from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
-import httpx
 import json_repair
 from loguru import logger
 
-if os.environ.get("LANGFUSE_SECRET_KEY") and importlib.util.find_spec("langfuse"):
-    from langfuse.openai import AsyncOpenAI
-else:
-    if os.environ.get("LANGFUSE_SECRET_KEY"):
-        logger.warning(
-            "LANGFUSE_SECRET_KEY is set but langfuse is not installed; "
-            "install with `pip install langfuse` to enable tracing"
-        )
-    from openai import AsyncOpenAI
-
 from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
 from nanobot.providers.openai_responses import (
     consume_sdk_stream,
@@ -39,8 +28,15 @@ from nanobot.providers.openai_responses import (
 )
 
 if TYPE_CHECKING:
+    from openai import AsyncOpenAI as AsyncOpenAIType
+
     from nanobot.providers.registry import ProviderSpec
 
+# Module-level placeholder — set lazily by _ensure_client on first real
+# use, or replaced by tests via ``patch(...)``.  Kept as a plain name so
+# that ``unittest.mock.patch`` can find and replace it.
+AsyncOpenAI: Any = None
+
 _ALLOWED_MSG_KEYS = frozenset({
     "role", "content", "tool_calls", "tool_call_id", "name",
     "reasoning_content", "extra_content",
@@ -302,43 +298,76 @@ class OpenAICompatProvider(LLMProvider):
 
         effective_base = api_base or (spec.default_api_base if spec else None) or None
         self._effective_base = effective_base
-        default_headers = {"x-session-affinity": uuid.uuid4().hex}
+        self._default_headers = {"x-session-affinity": uuid.uuid4().hex}
         if _uses_openrouter_attribution(spec, effective_base):
-            default_headers.update(_DEFAULT_OPENROUTER_HEADERS)
+            self._default_headers.update(_DEFAULT_OPENROUTER_HEADERS)
         if extra_headers:
-            default_headers.update(extra_headers)
+            self._default_headers.update(extra_headers)
+        self._api_key_for_client = api_key or "no-key"
+        self._is_local = _is_local_endpoint(spec, effective_base)
 
-        # Local model servers (Ollama, llama.cpp, vLLM) often close idle
+        # Lazy-init: the OpenAI client and its httpx transport are expensive
-        # HTTP connections before the client-side keepalive expires.  When
+        # to create (~700 ms on Windows). Defer until first use.
-        # two LLM calls happen seconds apart (e.g. heartbeat _decide then
+        self._client: AsyncOpenAIType | None = None
-        # process_direct), the second call may grab a now-dead pooled
+        self._client_lock = asyncio.Lock()
-        # connection, causing a transient APIConnectionError on every first
-        # attempt.  Disabling keepalive for local endpoints avoids this by
-        # opening a fresh connection for each request, which is cheap on a
-        # LAN.  Cloud providers benefit from keepalive, so we leave the
-        # default pool settings for them.
-        timeout_s = _openai_compat_timeout_s()
-        http_client: httpx.AsyncClient | None = None
-        if _is_local_endpoint(spec, effective_base):
-            http_client = httpx.AsyncClient(
-                limits=httpx.Limits(keepalive_expiry=0),
-                timeout=timeout_s,
-            )
-
-        self._client = AsyncOpenAI(
-            api_key=api_key or "no-key",
-            base_url=effective_base,
-            default_headers=default_headers,
-            max_retries=0,
-            timeout=timeout_s,
-            http_client=http_client,
-        )
 
         # Responses API circuit breaker: skip after repeated failures,
         # probe again after _RESPONSES_PROBE_INTERVAL_S seconds.
         self._responses_failures: dict[str, int] = {}
         self._responses_tripped_at: dict[str, float] = {}
 
+    def _build_client(self) -> None:
+        """Create the OpenAI client using the current module-level AsyncOpenAI."""
+        import httpx
+
+        timeout_s = _openai_compat_timeout_s()
+        http_client: httpx.AsyncClient | None = None
+        if self._is_local:
+            # Local model servers (Ollama, llama.cpp, vLLM) often close idle
+            # HTTP connections before the client-side keepalive expires. When
+            # two LLM calls happen seconds apart (e.g. heartbeat _decide then
+            # process_direct), the second call may grab a now-dead pooled
+            # connection, causing a transient APIConnectionError on every first
+            # attempt. Disabling keepalive for local endpoints avoids this by
+            # opening a fresh connection for each request, which is cheap on a
+            # LAN. Cloud providers benefit from keepalive, so we leave the
+            # default pool settings for them.
+            http_client = httpx.AsyncClient(
+                limits=httpx.Limits(keepalive_expiry=0),
+                timeout=timeout_s,
+            )
+        self._client = AsyncOpenAI(
+            api_key=self._api_key_for_client,
+            base_url=self._effective_base,
+            default_headers=self._default_headers,
+            max_retries=0,
+            timeout=timeout_s,
+            http_client=http_client,
+        )
+
+    async def _ensure_client(self):
+        """Return the shared OpenAI client, creating it on first call."""
+        if self._client is not None:
+            return self._client
+        async with self._client_lock:
+            if self._client is not None:
+                return self._client
+            global AsyncOpenAI
+            if AsyncOpenAI is None:
+                if os.environ.get("LANGFUSE_SECRET_KEY") and importlib.util.find_spec("langfuse"):
+                    from langfuse.openai import AsyncOpenAI as _AsyncOpenAI
+                else:
+                    if os.environ.get("LANGFUSE_SECRET_KEY"):
+                        logger.warning(
+                            "LANGFUSE_SECRET_KEY is set but langfuse is not installed; "
+                            "install with `pip install langfuse` to enable tracing"
+                        )
+                    from openai import AsyncOpenAI as _AsyncOpenAI
+                AsyncOpenAI = _AsyncOpenAI
+
+            self._build_client()
+            return self._client
+
     def _setup_env(self, api_key: str, api_base: str | None) -> None:
         """Set environment variables based on provider spec."""
         spec = self._spec
@@ -999,6 +1028,21 @@ class OpenAICompatProvider(LLMProvider):
             if fn_prov:
                 buf["fn_prov"] = fn_prov
 
+        def _accum_legacy_function_call(function_call: Any) -> None:
+            """Accumulate legacy ``delta.function_call`` streaming chunks."""
+            if not function_call:
+                return
+            buf = tc_bufs.setdefault(0, {
+                "id": "", "name": "", "arguments": "",
+                "extra_content": None, "prov": None, "fn_prov": None,
+            })
+            fn_name = _get(function_call, "name")
+            if fn_name:
+                buf["name"] = str(fn_name)
+            fn_args = _get(function_call, "arguments")
+            if fn_args:
+                buf["arguments"] += str(fn_args)
+
         for chunk in chunks:
             if isinstance(chunk, str):
                 content_parts.append(chunk)
@@ -1029,6 +1073,7 @@ class OpenAICompatProvider(LLMProvider):
                     reasoning_parts.append(text)
                 for idx, tc in enumerate(delta.get("tool_calls") or []):
                     _accum_tc(tc, idx)
+                _accum_legacy_function_call(delta.get("function_call"))
                 usage = cls._extract_usage(chunk_map) or usage
                 continue
 
@@ -1047,8 +1092,10 @@ class OpenAICompatProvider(LLMProvider):
                     reasoning = getattr(delta, "reasoning", None)
                 if reasoning:
                     reasoning_parts.append(reasoning)
-            for tc in (delta.tool_calls or []) if delta else []:
+            for tc in (getattr(delta, "tool_calls", None) or []) if delta else []:
                 _accum_tc(tc, getattr(tc, "index", 0))
+            if delta:
+                _accum_legacy_function_call(getattr(delta, "function_call", None))
 
         return LLMResponse(
             content="".join(content_parts) or None,
@@ -1164,6 +1211,7 @@ class OpenAICompatProvider(LLMProvider):
         reasoning_effort: str | None = None,
         tool_choice: str | dict[str, Any] | None = None,
     ) -> LLMResponse:
+        await self._ensure_client()
         try:
             if self._should_use_responses_api(model, reasoning_effort):
                 try:
@@ -1203,7 +1251,9 @@ class OpenAICompatProvider(LLMProvider):
         tool_choice: str | dict[str, Any] | None = None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> LLMResponse:
+        await self._ensure_client()
         idle_timeout_s = int(os.environ.get("NANOBOT_STREAM_IDLE_TIMEOUT_S", "90"))
         try:
             if self._should_use_responses_api(model, reasoning_effort):
@@ -1226,9 +1276,16 @@ class OpenAICompatProvider(LLMProvider):
                             except StopAsyncIteration:
                                 break
 
-                    content, tool_calls, finish_reason, usage, reasoning_content = await consume_sdk_stream(
+                    (
+                        content,
+                        tool_calls,
+                        finish_reason,
+                        usage,
+                        reasoning_content,
+                    ) = await consume_sdk_stream(
                         _timed_stream(),
                         on_content_delta,
+                        on_tool_call_delta=on_tool_call_delta,
                     )
                     self._record_responses_success(model, reasoning_effort)
                     return LLMResponse(
@@ -1252,6 +1309,12 @@ class OpenAICompatProvider(LLMProvider):
                 messages, tools, model, max_tokens, temperature,
                 reasoning_effort, tool_choice,
             )
+            if self._spec and self._spec.name == "zhipu" and tools and on_tool_call_delta:
+                # Z.AI/GLM keeps streaming tool-call arguments behind an
+                # explicit provider flag.  Pass it through the OpenAI SDK's
+                # extra_body escape hatch so the usual delta.tool_calls path
+                # can surface live file-edit progress.
+                kwargs.setdefault("extra_body", {})["tool_stream"] = True
             kwargs["stream"] = True
             kwargs["stream_options"] = {"include_usage": True}
             stream = await self._client.chat.completions.create(**kwargs)
@@ -1279,6 +1342,28 @@ class OpenAICompatProvider(LLMProvider):
                         r_text = self._extract_text_content(reasoning)
                         if r_text:
                             await on_thinking_delta(r_text)
+                    if on_tool_call_delta:
+                        for idx, tool_delta in enumerate(
+                            getattr(delta_obj, "tool_calls", None) or []
+                        ):
+                            fn = _get(tool_delta, "function")
+                            tool_index = _get(tool_delta, "index")
+                            await on_tool_call_delta({
+                                "index": tool_index if tool_index is not None else idx,
+                                "call_id": str(_get(tool_delta, "id") or ""),
+                                "name": str(_get(fn, "name") or "") if fn is not None else "",
+                                "arguments_delta": (
+                                    str(_get(fn, "arguments") or "") if fn is not None else ""
+                                ),
+                            })
+                        function_call = getattr(delta_obj, "function_call", None)
+                        if function_call:
+                            await on_tool_call_delta({
+                                "index": 0,
+                                "call_id": "",
+                                "name": str(_get(function_call, "name") or ""),
+                                "arguments_delta": str(_get(function_call, "arguments") or ""),
+                            })
             return self._parse_chunks(chunks)
         except asyncio.TimeoutError:
             return LLMResponse(

nanobot/providers/openai_responses/parsing.py

@@ -62,6 +62,7 @@ async def iter_sse(response: httpx.Response) -> AsyncGenerator[dict[str, Any], N
 async def consume_sse(
     response: httpx.Response,
     on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+    on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
 ) -> tuple[str, list[ToolCallRequest], str]:
     """Consume a Responses API SSE stream into ``(content, tool_calls, finish_reason)``."""
     content = ""
@@ -82,6 +83,12 @@ async def consume_sse(
                     "name": item.get("name"),
                     "arguments": item.get("arguments") or "",
                 }
+                if on_tool_call_delta:
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(item.get("name") or ""),
+                        "arguments_delta": "",
+                    })
         elif event_type == "response.output_text.delta":
             delta_text = event.get("delta") or ""
             content += delta_text
@@ -90,7 +97,14 @@ async def consume_sse(
         elif event_type == "response.function_call_arguments.delta":
             call_id = event.get("call_id")
             if call_id and call_id in tool_call_buffers:
-                tool_call_buffers[call_id]["arguments"] += event.get("delta") or ""
+                delta = event.get("delta") or ""
+                tool_call_buffers[call_id]["arguments"] += delta
+                if on_tool_call_delta and delta:
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(tool_call_buffers[call_id].get("name") or ""),
+                        "arguments_delta": str(delta),
+                    })
         elif event_type == "response.function_call_arguments.done":
             call_id = event.get("call_id")
             if call_id and call_id in tool_call_buffers:
@@ -210,6 +224,7 @@ def parse_response_output(response: Any) -> LLMResponse:
 async def consume_sdk_stream(
     stream: Any,
     on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+    on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
 ) -> tuple[str, list[ToolCallRequest], str, dict[str, int], str | None]:
     """Consume an SDK async stream from ``client.responses.create(stream=True)``."""
     content = ""
@@ -232,6 +247,12 @@ async def consume_sdk_stream(
                     "name": getattr(item, "name", None),
                     "arguments": getattr(item, "arguments", None) or "",
                 }
+                if on_tool_call_delta:
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(getattr(item, "name", None) or ""),
+                        "arguments_delta": "",
+                    })
         elif event_type == "response.output_text.delta":
             delta_text = getattr(event, "delta", "") or ""
             content += delta_text
@@ -240,7 +261,14 @@ async def consume_sdk_stream(
         elif event_type == "response.function_call_arguments.delta":
             call_id = getattr(event, "call_id", None)
             if call_id and call_id in tool_call_buffers:
-                tool_call_buffers[call_id]["arguments"] += getattr(event, "delta", "") or ""
+                delta = getattr(event, "delta", "") or ""
+                tool_call_buffers[call_id]["arguments"] += delta
+                if on_tool_call_delta and delta:
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(tool_call_buffers[call_id].get("name") or ""),
+                        "arguments_delta": str(delta),
+                    })
         elif event_type == "response.function_call_arguments.done":
             call_id = getattr(event, "call_id", None)
             if call_id and call_id in tool_call_buffers:

nanobot/providers/registry.py

@@ -34,7 +34,7 @@ class ProviderSpec:
     display_name: str = ""  # shown in `nanobot status`
 
     # which provider implementation to use
-    # "openai_compat" | "anthropic" | "azure_openai" | "openai_codex" | "github_copilot" | "bedrock"
+    # "openai_compat" | "anthropic" | "azure_openai" | "openai_codex" | "github_copilot" | "xai_oauth" | "bedrock"
     backend: str = "openai_compat"
 
     # extra env vars, e.g. (("ZHIPUAI_API_KEY", "{api_key}"),)
@@ -155,6 +155,18 @@ PROVIDERS: tuple[ProviderSpec, ...] = (
         detect_by_base_keyword="huggingface",
         default_api_base="https://router.huggingface.co/v1",
     ),
+    # Skywork API platform (APIFree): OpenAI-compatible MaaS gateway.
+    ProviderSpec(
+        name="skywork",
+        keywords=("skywork", "skyclaw", "apifree"),
+        env_key="SKYWORK_API_KEY",
+        display_name="Skywork",
+        backend="openai_compat",
+        env_extras=(("APIFREE_API_KEY", "{api_key}"),),
+        is_gateway=True,
+        detect_by_base_keyword="apifree.ai",
+        default_api_base="https://api.apifree.ai/agent/v1",
+    ),
     # AiHubMix: global gateway, OpenAI-compatible interface.
     # strip_model_prefix=True: doesn't understand "anthropic/claude-3",
     # strips to bare "claude-3".
@@ -279,6 +291,18 @@ PROVIDERS: tuple[ProviderSpec, ...] = (
         is_oauth=True,
         supports_max_completion_tokens=True,
     ),
+    # xAI Grok OAuth: SuperGrok subscription-backed Responses API provider
+    ProviderSpec(
+        name="xai_oauth",
+        keywords=("xai-oauth", "grok-oauth", "x-ai-oauth", "xai-grok-oauth"),
+        env_key="",
+        display_name="xAI Grok OAuth",
+        backend="xai_oauth",
+        default_api_base="https://api.x.ai/v1",
+        strip_model_prefix=True,
+        is_oauth=True,
+        supports_max_completion_tokens=True,
+    ),
     # DeepSeek: OpenAI-compatible at api.deepseek.com
     ProviderSpec(
         name="deepseek",
@@ -390,6 +414,16 @@ PROVIDERS: tuple[ProviderSpec, ...] = (
         backend="openai_compat",
         default_api_base="https://api.longcat.chat/openai/v1",
     ),
+    # Ant Ling: OpenAI-compatible API for Ling/Ring model families.
+    ProviderSpec(
+        name="ant_ling",
+        keywords=("ant_ling", "ant-ling", "ling-", "ring-"),
+        env_key="ANT_LING_API_KEY",
+        display_name="Ant Ling",
+        backend="openai_compat",
+        detect_by_base_keyword="ant-ling.com",
+        default_api_base="https://api.ant-ling.com/v1",
+    ),
     # === Local deployment (matched by config key, NOT by api_base) =========
     # vLLM / any OpenAI-compatible local server
     ProviderSpec(

nanobot/providers/xai_oauth_provider.py

@@ -0,0 +1,768 @@
+"""xAI Grok OAuth credential flow and Responses provider."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import os
+import secrets
+import time
+import webbrowser
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from hashlib import sha256
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Event, Thread
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+from filelock import FileLock
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+from nanobot.providers.openai_responses import consume_sse, convert_messages, convert_tools
+
+DEFAULT_XAI_API_BASE = "https://api.x.ai/v1"
+DEFAULT_XAI_AUTH_ISSUER = "https://auth.x.ai"
+DEFAULT_XAI_DISCOVERY_URL = f"{DEFAULT_XAI_AUTH_ISSUER}/.well-known/openid-configuration"
+DEFAULT_XAI_REDIRECT_URI = "http://127.0.0.1:56121/callback"
+DEFAULT_XAI_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828"
+DEFAULT_XAI_SCOPE = "openid profile email offline_access grok-cli:access api:access"
+
+_SERVICE_NAME = "nanobot.xai_oauth"
+_SECRET_USERNAME = "default"
+_TOKEN_SKEW_SECONDS = 60
+_LOGIN_TIMEOUT_SECONDS = 300
+
+
+@dataclass(frozen=True)
+class XaiOAuthEndpoints:
+    authorization_endpoint: str
+    token_endpoint: str
+
+
+@dataclass(frozen=True)
+class XaiOAuthCredential:
+    access_token: str
+    refresh_token: str = ""
+    expires_at: float | None = None
+    account_id: str | None = None
+    token_type: str = "Bearer"
+    api_base: str = DEFAULT_XAI_API_BASE
+    storage: str = "unknown"
+
+    @property
+    def is_expiring(self) -> bool:
+        return self.expires_at is not None and self.expires_at <= time.time() + _TOKEN_SKEW_SECONDS
+
+
+def _nanobot_home() -> Path:
+    override = os.environ.get("NANOBOT_HOME")
+    if override:
+        return Path(override).expanduser()
+    from nanobot.config.loader import get_config_path
+
+    return get_config_path().parent
+
+
+def _auth_dir() -> Path:
+    return _nanobot_home() / "auth"
+
+
+def get_xai_oauth_metadata_path() -> Path:
+    """Return the non-secret xAI OAuth metadata path."""
+    return _auth_dir() / "xai-oauth.json"
+
+
+def _lock_path() -> Path:
+    return get_xai_oauth_metadata_path().with_suffix(".lock")
+
+
+def _write_private_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with suppress(OSError):
+        path.parent.chmod(0o700)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    with suppress(OSError):
+        tmp.chmod(0o600)
+    tmp.replace(path)
+    with suppress(OSError):
+        path.chmod(0o600)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _keyring_set(tokens: dict[str, Any]) -> bool:
+    try:
+        import keyring  # type: ignore[import-not-found]
+
+        keyring.set_password(_SERVICE_NAME, _SECRET_USERNAME, json.dumps(tokens))
+        return True
+    except Exception:
+        return False
+
+
+def _keyring_get() -> dict[str, Any] | None:
+    try:
+        import keyring  # type: ignore[import-not-found]
+
+        raw = keyring.get_password(_SERVICE_NAME, _SECRET_USERNAME)
+    except Exception:
+        return None
+    if not raw:
+        return None
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _keyring_delete() -> None:
+    try:
+        import keyring  # type: ignore[import-not-found]
+
+        keyring.delete_password(_SERVICE_NAME, _SECRET_USERNAME)
+    except Exception:
+        pass
+
+
+def _token_payload(credential: XaiOAuthCredential) -> dict[str, Any]:
+    return {
+        "access_token": credential.access_token,
+        "refresh_token": credential.refresh_token,
+        "expires_at": credential.expires_at,
+        "token_type": credential.token_type,
+    }
+
+
+def save_xai_oauth_credential(credential: XaiOAuthCredential) -> XaiOAuthCredential:
+    """Persist xAI OAuth tokens, preferring OS keychain storage."""
+    with FileLock(str(_lock_path())):
+        tokens = _token_payload(credential)
+        metadata: dict[str, Any] = {
+            "provider": "xai_oauth",
+            "api_base": credential.api_base,
+            "account_id": credential.account_id,
+            "expires_at": credential.expires_at,
+            "updated_at": int(time.time()),
+        }
+        if _keyring_set(tokens):
+            metadata["storage"] = "keyring"
+        else:
+            metadata["storage"] = "file"
+            metadata["tokens"] = tokens
+        _write_private_json(get_xai_oauth_metadata_path(), metadata)
+        return XaiOAuthCredential(
+            access_token=credential.access_token,
+            refresh_token=credential.refresh_token,
+            expires_at=credential.expires_at,
+            account_id=credential.account_id,
+            token_type=credential.token_type,
+            api_base=credential.api_base,
+            storage=str(metadata["storage"]),
+        )
+
+
+def load_xai_oauth_credential() -> XaiOAuthCredential | None:
+    """Load xAI OAuth credentials from keyring or the private file fallback."""
+    path = get_xai_oauth_metadata_path()
+    if not path.exists():
+        return None
+    with FileLock(str(_lock_path())):
+        try:
+            metadata = _read_json(path)
+        except (OSError, json.JSONDecodeError):
+            return None
+
+        storage = str(metadata.get("storage") or "file")
+        tokens = _keyring_get() if storage == "keyring" else metadata.get("tokens")
+        if not isinstance(tokens, dict):
+            return None
+        access_token = str(tokens.get("access_token") or "")
+        if not access_token:
+            return None
+
+        return XaiOAuthCredential(
+            access_token=access_token,
+            refresh_token=str(tokens.get("refresh_token") or ""),
+            expires_at=_as_float(tokens.get("expires_at") or metadata.get("expires_at")),
+            account_id=_as_str(metadata.get("account_id")),
+            token_type=str(tokens.get("token_type") or "Bearer"),
+            api_base=str(metadata.get("api_base") or DEFAULT_XAI_API_BASE),
+            storage=storage,
+        )
+
+
+def delete_xai_oauth_credentials() -> list[Path]:
+    """Delete persisted xAI OAuth credentials and return removed local paths."""
+    removed: list[Path] = []
+    path = get_xai_oauth_metadata_path()
+    lock_path = _lock_path()
+    with FileLock(str(lock_path)):
+        _keyring_delete()
+        try:
+            path.unlink()
+            removed.append(path)
+        except FileNotFoundError:
+            pass
+    try:
+        lock_path.unlink()
+    except FileNotFoundError:
+        pass
+    return removed
+
+
+def get_xai_oauth_login_status() -> XaiOAuthCredential | None:
+    return load_xai_oauth_credential()
+
+
+def pkce_challenge(verifier: str) -> str:
+    digest = sha256(verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+
+
+def _new_pkce_verifier() -> str:
+    return base64.urlsafe_b64encode(secrets.token_bytes(48)).decode("ascii").rstrip("=")
+
+
+def build_xai_authorization_url(
+    endpoints: XaiOAuthEndpoints,
+    *,
+    verifier: str,
+    state: str,
+    nonce: str | None = None,
+    redirect_uri: str = DEFAULT_XAI_REDIRECT_URI,
+) -> str:
+    params = {
+        "response_type": "code",
+        "client_id": DEFAULT_XAI_CLIENT_ID,
+        "redirect_uri": redirect_uri,
+        "scope": DEFAULT_XAI_SCOPE,
+        "code_challenge": pkce_challenge(verifier),
+        "code_challenge_method": "S256",
+        "state": state,
+        "nonce": nonce or secrets.token_urlsafe(16),
+        "plan": "generic",
+        "referrer": "nanobot",
+    }
+    return f"{endpoints.authorization_endpoint}?{urlencode(params)}"
+
+
+def discover_xai_oauth_endpoints() -> XaiOAuthEndpoints:
+    try:
+        with httpx.Client(timeout=20.0, follow_redirects=True, trust_env=True) as client:
+            response = client.get(DEFAULT_XAI_DISCOVERY_URL)
+            response.raise_for_status()
+            payload = response.json()
+    except Exception:
+        payload = {}
+
+    endpoints = XaiOAuthEndpoints(
+        authorization_endpoint=str(
+            payload.get("authorization_endpoint")
+            or f"{DEFAULT_XAI_AUTH_ISSUER}/authorize"
+        ),
+        token_endpoint=str(
+            payload.get("token_endpoint")
+            or f"{DEFAULT_XAI_AUTH_ISSUER}/oauth/token"
+        ),
+    )
+    _validate_xai_endpoint(endpoints.authorization_endpoint, "authorization_endpoint")
+    _validate_xai_endpoint(endpoints.token_endpoint, "token_endpoint")
+    return endpoints
+
+
+def _validate_xai_endpoint(url: str, label: str) -> None:
+    parsed = urlparse(url)
+    host = parsed.hostname or ""
+    if parsed.scheme != "https" or not (host == "x.ai" or host.endswith(".x.ai")):
+        raise RuntimeError(f"Refusing non-xAI OAuth {label}: {url}")
+
+
+def _parse_callback_value(raw: str) -> tuple[str, str | None]:
+    raw = raw.strip()
+    parsed = urlparse(raw)
+    if parsed.scheme and parsed.netloc:
+        params = parse_qs(parsed.query)
+        code = (params.get("code") or [""])[0]
+        state = (params.get("state") or [None])[0]
+        if not code:
+            raise RuntimeError("OAuth callback URL did not contain a code.")
+        return code, state
+    if raw.startswith("?") or "=" in raw:
+        params = parse_qs(raw.lstrip("?"))
+        code = (params.get("code") or [""])[0]
+        state = (params.get("state") or [None])[0]
+        if not code:
+            raise RuntimeError("OAuth callback query did not contain a code.")
+        return code, state
+    if raw:
+        return raw, None
+    raise RuntimeError("No OAuth code provided.")
+
+
+def _decode_jwt_payload(token: str) -> dict[str, Any]:
+    parts = token.split(".")
+    if len(parts) < 2:
+        return {}
+    data = parts[1] + "=" * (-len(parts[1]) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(data.encode("ascii"))
+        payload = json.loads(decoded)
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _credential_from_token_response(payload: dict[str, Any], previous: XaiOAuthCredential | None = None) -> XaiOAuthCredential:
+    access_token = str(payload.get("access_token") or "")
+    if not access_token:
+        raise RuntimeError("xAI token response did not include an access token.")
+
+    claims = _decode_jwt_payload(access_token)
+    id_claims = _decode_jwt_payload(str(payload.get("id_token") or ""))
+    expires_at = _as_float(payload.get("expires_at"))
+    if expires_at is None:
+        expires_in = _as_float(payload.get("expires_in"))
+        expires_at = time.time() + expires_in if expires_in else _as_float(claims.get("exp"))
+
+    account_id = (
+        _as_str(id_claims.get("email"))
+        or _as_str(id_claims.get("preferred_username"))
+        or _as_str(id_claims.get("sub"))
+        or _as_str(claims.get("sub"))
+        or (previous.account_id if previous else None)
+    )
+    refresh_token = str(payload.get("refresh_token") or (previous.refresh_token if previous else ""))
+
+    return XaiOAuthCredential(
+        access_token=access_token,
+        refresh_token=refresh_token,
+        expires_at=expires_at,
+        account_id=account_id,
+        token_type=str(payload.get("token_type") or (previous.token_type if previous else "Bearer")),
+        api_base=previous.api_base if previous else DEFAULT_XAI_API_BASE,
+    )
+
+
+def exchange_xai_oauth_code(
+    code: str,
+    *,
+    verifier: str,
+    endpoints: XaiOAuthEndpoints | None = None,
+    redirect_uri: str = DEFAULT_XAI_REDIRECT_URI,
+) -> XaiOAuthCredential:
+    endpoints = endpoints or discover_xai_oauth_endpoints()
+    challenge = pkce_challenge(verifier)
+    with httpx.Client(timeout=30.0, follow_redirects=True, trust_env=True) as client:
+        response = client.post(
+            endpoints.token_endpoint,
+            headers={"Accept": "application/json"},
+            data={
+                "grant_type": "authorization_code",
+                "client_id": DEFAULT_XAI_CLIENT_ID,
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "code_verifier": verifier,
+                "code_challenge": challenge,
+                "code_challenge_method": "S256",
+            },
+        )
+    if response.status_code >= 400:
+        raise RuntimeError(f"xAI token exchange failed: HTTP {response.status_code}: {response.text[:500]}")
+    return _credential_from_token_response(response.json())
+
+
+def refresh_xai_oauth_credential(credential: XaiOAuthCredential | None = None) -> XaiOAuthCredential:
+    credential = credential or load_xai_oauth_credential()
+    if not credential or not credential.refresh_token:
+        raise RuntimeError("xAI Grok OAuth is not logged in. Run: nanobot provider login xai-oauth")
+
+    endpoints = discover_xai_oauth_endpoints()
+    with httpx.Client(timeout=30.0, follow_redirects=True, trust_env=True) as client:
+        response = client.post(
+            endpoints.token_endpoint,
+            headers={"Accept": "application/json"},
+            data={
+                "grant_type": "refresh_token",
+                "client_id": DEFAULT_XAI_CLIENT_ID,
+                "refresh_token": credential.refresh_token,
+            },
+        )
+    if response.status_code >= 400:
+        raise RuntimeError(f"xAI token refresh failed: HTTP {response.status_code}: {response.text[:500]}")
+    return save_xai_oauth_credential(_credential_from_token_response(response.json(), previous=credential))
+
+
+def resolve_xai_oauth_credential(*, force_refresh: bool = False) -> XaiOAuthCredential:
+    credential = load_xai_oauth_credential()
+    if not credential:
+        raise RuntimeError("xAI Grok OAuth is not logged in. Run: nanobot provider login xai-oauth")
+    if force_refresh or credential.is_expiring:
+        credential = refresh_xai_oauth_credential(credential)
+    return credential
+
+
+def login_xai_oauth_interactive(
+    print_fn: Callable[[str], None] | None = None,
+    prompt_fn: Callable[[str], str] | None = None,
+    open_browser: bool = True,
+    manual_paste: bool = False,
+    timeout_seconds: int = _LOGIN_TIMEOUT_SECONDS,
+) -> XaiOAuthCredential:
+    """Run browser PKCE login and persist xAI OAuth credentials."""
+    printer = print_fn or print
+    prompt = prompt_fn or input
+    endpoints = discover_xai_oauth_endpoints()
+    verifier = _new_pkce_verifier()
+    state = secrets.token_urlsafe(24)
+    nonce = secrets.token_urlsafe(24)
+    authorize_url = build_xai_authorization_url(
+        endpoints,
+        verifier=verifier,
+        state=state,
+        nonce=nonce,
+    )
+
+    callback = _LoopbackCallback()
+    server_started = False if manual_paste else callback.start()
+    printer(f"Open: {authorize_url}")
+    if open_browser:
+        with suppress(Exception):
+            webbrowser.open(authorize_url)
+
+    result: dict[str, str] | None = None
+    if manual_paste:
+        printer("Paste the callback URL or xAI fallback code after authorization.")
+    elif server_started:
+        try:
+            result = callback.wait(timeout_seconds)
+        finally:
+            callback.stop()
+    else:
+        printer("Loopback port 56121 is unavailable; paste the callback URL or xAI fallback code.")
+
+    if result:
+        code = result.get("code") or ""
+        returned_state = result.get("state")
+    else:
+        pasted = prompt("Paste callback URL or fallback code")
+        code, returned_state = _parse_callback_value(pasted)
+
+    if not code:
+        raise RuntimeError("OAuth login did not return a code.")
+    if returned_state and returned_state != state:
+        raise RuntimeError("OAuth state mismatch. Please retry login.")
+
+    credential = exchange_xai_oauth_code(code, verifier=verifier, endpoints=endpoints)
+    return save_xai_oauth_credential(credential)
+
+
+class _LoopbackCallback:
+    def __init__(self) -> None:
+        self._event = Event()
+        self._result: dict[str, str] = {}
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: Thread | None = None
+
+    def start(self) -> bool:
+        owner = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802 - stdlib callback name
+                parsed = urlparse(self.path)
+                params = parse_qs(parsed.query)
+                code = (params.get("code") or [""])[0]
+                state = (params.get("state") or [""])[0]
+                if parsed.path != "/callback" or not code:
+                    self.send_response(404)
+                    self.end_headers()
+                    return
+                owner._result = {"code": code, "state": state}
+                owner._event.set()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(b"<html><body>nanobot xAI OAuth complete. You may close this tab.</body></html>")
+
+            def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+                return
+
+        class Server(ThreadingHTTPServer):
+            allow_reuse_address = True
+            daemon_threads = True
+
+        try:
+            self._server = Server(("127.0.0.1", 56121), Handler)
+        except OSError:
+            return False
+        self._thread = Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        return True
+
+    def wait(self, timeout_seconds: int) -> dict[str, str] | None:
+        if self._event.wait(timeout_seconds):
+            return dict(self._result)
+        return None
+
+    def stop(self) -> None:
+        if self._server:
+            self._server.shutdown()
+            self._server.server_close()
+        if self._thread:
+            self._thread.join(timeout=1)
+
+
+def _as_float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_str(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+DEFAULT_XAI_MODEL = "xai-oauth/grok-4.3"
+
+
+class XaiOAuthProvider(LLMProvider):
+    """Use a SuperGrok OAuth session to call xAI's Responses API."""
+
+    supports_progress_deltas = True
+
+    def __init__(self, default_model: str = DEFAULT_XAI_MODEL, config: Any | None = None):
+        super().__init__(api_key=None, api_base=DEFAULT_XAI_API_BASE)
+        self.default_model = default_model
+        self.config = config
+
+    async def _call_xai(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None,
+        model: str | None,
+        max_tokens: int,
+        temperature: float,
+        reasoning_effort: str | None,
+        tool_choice: str | dict[str, Any] | None,
+        on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+    ) -> LLMResponse:
+        body = _build_xai_responses_body(
+            messages=messages,
+            tools=tools,
+            model=model or self.default_model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            reasoning_effort=reasoning_effort,
+            tool_choice=tool_choice,
+            hosted_x_search=getattr(self.config, "x_search", None),
+        )
+        try:
+            credential = await asyncio.to_thread(resolve_xai_oauth_credential)
+            try:
+                content, tool_calls, finish_reason = await _request_xai(
+                    credential,
+                    body,
+                    on_content_delta=on_content_delta,
+                    on_tool_call_delta=on_tool_call_delta,
+                )
+            except _XaiHTTPError as exc:
+                if exc.status_code != 401:
+                    raise
+                credential = await asyncio.to_thread(resolve_xai_oauth_credential, force_refresh=True)
+                content, tool_calls, finish_reason = await _request_xai(
+                    credential,
+                    body,
+                    on_content_delta=on_content_delta,
+                    on_tool_call_delta=on_tool_call_delta,
+                )
+            return LLMResponse(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
+        except Exception as exc:
+            msg = f"Error calling xAI Grok OAuth: {exc}"
+            retry_after = getattr(exc, "retry_after", None) or self._extract_retry_after(msg)
+            return LLMResponse(content=msg, finish_reason="error", retry_after=retry_after)
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+        tool_choice: str | dict[str, Any] | None = None,
+    ) -> LLMResponse:
+        return await self._call_xai(
+            messages,
+            tools,
+            model,
+            max_tokens,
+            temperature,
+            reasoning_effort,
+            tool_choice,
+        )
+
+    async def chat_stream(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+        tool_choice: str | dict[str, Any] | None = None,
+        on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
+        on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+    ) -> LLMResponse:
+        _ = on_thinking_delta
+        return await self._call_xai(
+            messages,
+            tools,
+            model,
+            max_tokens,
+            temperature,
+            reasoning_effort,
+            tool_choice,
+            on_content_delta,
+            on_tool_call_delta,
+        )
+
+    def get_default_model(self) -> str:
+        return self.default_model
+
+
+def _strip_model_prefix(model: str) -> str:
+    for prefix in ("xai-oauth/", "xai_oauth/", "grok-oauth/", "grok_oauth/"):
+        if model.startswith(prefix):
+            return model.split("/", 1)[1]
+    return model
+
+
+def _build_xai_responses_body(
+    *,
+    messages: list[dict[str, Any]],
+    tools: list[dict[str, Any]] | None,
+    model: str,
+    max_tokens: int,
+    temperature: float,
+    reasoning_effort: str | None,
+    tool_choice: str | dict[str, Any] | None,
+    hosted_x_search: Any | None = None,
+) -> dict[str, Any]:
+    system_prompt, input_items = convert_messages(LLMProvider._sanitize_empty_content(messages))
+    if system_prompt:
+        input_items = [
+            {"role": "system", "content": [{"type": "input_text", "text": system_prompt}]},
+            *input_items,
+        ]
+
+    body: dict[str, Any] = {
+        "model": _strip_model_prefix(model),
+        "store": False,
+        "stream": True,
+        "input": input_items,
+        "tool_choice": tool_choice or "auto",
+        "parallel_tool_calls": True,
+    }
+    if max_tokens:
+        body["max_output_tokens"] = max_tokens
+    if temperature is not None:
+        body["temperature"] = temperature
+    if reasoning_effort and reasoning_effort.lower() != "none":
+        body["reasoning"] = {"effort": reasoning_effort}
+    converted_tools = convert_tools(tools) if tools else []
+    hosted_tool = _build_xai_hosted_x_search_tool(hosted_x_search)
+    if hosted_tool:
+        converted_tools.append(hosted_tool)
+    if converted_tools:
+        body["tools"] = converted_tools
+    return body
+
+
+def _clean_x_handles(handles: list[str] | None) -> list[str] | None:
+    if not handles:
+        return None
+    cleaned = [str(handle).strip().lstrip("@") for handle in handles if str(handle).strip()]
+    return cleaned[:10] or None
+
+
+def _build_xai_hosted_x_search_tool(config: Any | None) -> dict[str, Any] | None:
+    if not config or not getattr(config, "enable", False):
+        return None
+
+    allowed = _clean_x_handles(getattr(config, "allowed_x_handles", None))
+    excluded = _clean_x_handles(getattr(config, "excluded_x_handles", None))
+    if allowed and excluded:
+        raise ValueError("providers.xai_oauth.x_search cannot set both allowed_x_handles and excluded_x_handles")
+
+    tool: dict[str, Any] = {"type": "x_search"}
+    if allowed:
+        tool["allowed_x_handles"] = allowed
+    if excluded:
+        tool["excluded_x_handles"] = excluded
+    if getattr(config, "from_date", None):
+        tool["from_date"] = config.from_date
+    if getattr(config, "to_date", None):
+        tool["to_date"] = config.to_date
+    if getattr(config, "enable_image_understanding", False):
+        tool["enable_image_understanding"] = True
+    if getattr(config, "enable_video_understanding", False):
+        tool["enable_video_understanding"] = True
+    return tool
+
+
+class _XaiHTTPError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int, retry_after: float | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.retry_after = retry_after
+
+
+async def _request_xai(
+    credential: XaiOAuthCredential,
+    body: dict[str, Any],
+    on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+    on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+) -> tuple[str, list[ToolCallRequest], str]:
+    url = credential.api_base.rstrip("/") + "/responses"
+    headers = {
+        "Authorization": f"Bearer {credential.access_token}",
+        "Accept": "text/event-stream",
+        "Content-Type": "application/json",
+        "User-Agent": "nanobot (python)",
+    }
+    timeout = httpx.Timeout(120.0, connect=20.0)
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=True, trust_env=True) as client:
+        async with client.stream("POST", url, headers=headers, json=body) as response:
+            if response.status_code != 200:
+                raw = await response.aread()
+                retry_after = LLMProvider._extract_retry_after_from_headers(response.headers)
+                raise _XaiHTTPError(
+                    _friendly_error(response.status_code, raw.decode("utf-8", "ignore")),
+                    status_code=response.status_code,
+                    retry_after=retry_after,
+                )
+            return await consume_sse(response, on_content_delta, on_tool_call_delta)
+
+
+def _friendly_error(status_code: int, raw: str) -> str:
+    if status_code == 401:
+        return "xAI OAuth session expired or was revoked. Run: nanobot provider login xai-oauth"
+    if status_code == 403:
+        return (
+            "xAI accepted the OAuth token, but this account is not entitled for the requested "
+            "Grok API capability yet. Check the active Grok subscription and selected model."
+        )
+    if status_code == 429:
+        return "xAI Grok subscription quota or rate limit was reached. Please try again later."
+    return f"HTTP {status_code}: {raw[:500]}"

nanobot/session/webui_turns.py

@@ -1,4 +1,4 @@
-"""Outbound helpers for the WebSocket/WebUI wire contract.
+"""Session turn helpers for WebUI-capable WebSocket sessions.
 
 AgentLoop uses these without importing a concrete channel plugin; only
 ``channel == "websocket"`` messages are affected.

nanobot/skills/image-generation/SKILL.md

@@ -15,7 +15,7 @@ If the `generate_image` tool is not available in the current tool list, tell the
 - Image editing: pass the saved artifact path or user image path in `reference_images`.
 - Iterative edits in the same conversation: prefer the most recent generated image artifact if the user says things like "make it brighter", "change the background", or "try another version".
 - Ambiguous edits: ask a short clarifying question if multiple recent images could be the target.
-- In the current chat, do not call `message` just to announce or resend generated images. The runtime attaches images from `generate_image` to the final assistant reply automatically.
+- After generating images, call the `message` tool with the artifact paths in the `media` parameter to deliver them to the user.
 
 ## Prompt Rules
 
@@ -42,73 +42,6 @@ For follow-up edits, pass the prior artifact `path` to `reference_images`. If th
 
 Do not include internal replay markers such as `[Message Time: ...]`, `[image: /local/path]`, `generate_image(...)`, or `message(...)` in user-facing replies.
 
-## Provider Notes
-
-Do not ask users to paste API keys into chat. If configuration is needed, describe the fields; LLM provider and BYOK changes are hot-reloaded for new turns.
-
-For OpenRouter, the image tool expects:
-
-```json
-{
-  "providers": {
-    "openrouter": {
-      "apiKey": "sk-or-..."
-    }
-  },
-  "tools": {
-    "imageGeneration": {
-      "enabled": true,
-      "provider": "openrouter",
-      "model": "openai/gpt-5.4-image-2"
-    }
-  }
-}
-```
-
-For AIHubMix, the image tool expects:
-
-```json
-{
-  "providers": {
-    "aihubmix": {
-      "apiKey": "sk-..."
-    }
-  },
-  "tools": {
-    "imageGeneration": {
-      "enabled": true,
-      "provider": "aihubmix",
-      "model": "gpt-image-2-free"
-    }
-  }
-}
-```
-
-AIHubMix `gpt-image-2-free` uses AIHubMix's unified predictions endpoint internally (`/v1/models/openai/gpt-image-2-free/predictions`), not the OpenAI Images `/v1/images/generations` endpoint. If it fails with "Incorrect model ID", do not assume the key lacks permission until the provider config, model name, and gateway restart have been checked.
-
-`providers.aihubmix.extraBody` can be used for provider-specific options. For example, `"extraBody": {"quality": "low"}` is optional but can make `gpt-image-2-free` faster and less likely to time out.
-
-For Gemini, the image tool supports two model families. Imagen 4 (`imagen-4.0-generate-001`) supports text-to-image only. Gemini Flash (`gemini-2.5-flash-image`) also supports reference-image edits. Configuration:
-
-```json
-{
-  "providers": {
-    "gemini": {
-      "apiKey": "AIza..."
-    }
-  },
-  "tools": {
-    "imageGeneration": {
-      "enabled": true,
-      "provider": "gemini",
-      "model": "imagen-4.0-generate-001"
-    }
-  }
-}
-```
-
-For Gemini models, `defaultImageSize` has no effect; use `defaultAspectRatio` instead. Imagen 4 supports `1:1`, `9:16`, `16:9`, `3:4`, and `4:3`.
-
 ## Examples
 
 Generate a new image:

nanobot/templates/agent/identity.md

@@ -30,5 +30,5 @@ Output is rendered in a terminal. Avoid markdown headings and tables. Use plain
 
 Reply directly with text for the current conversation. Do not use the 'message' tool for normal replies in the current chat.
 When you need to call tools before answering, do not include the final user-visible answer in the same assistant message as the tool calls. Wait for the tool results, then answer once.
-Use the 'message' tool only for proactive sends, cross-channel delivery, or explicitly sending existing local files as attachments. When a tool such as 'generate_image' creates user-visible media, the runtime attaches those artifacts to the final assistant reply automatically, so do not call 'message' just to announce or resend them.
+Use the 'message' tool only for proactive sends, cross-channel delivery, or explicitly sending existing local files as attachments. When 'generate_image' creates images, call 'message' with the artifact paths in the 'media' parameter to deliver them to the user.
 To send an existing local file that was not automatically attached by another tool, call 'message' with the 'media' parameter. Do NOT use read_file to "send" a file — reading a file only shows its content to you, it does NOT deliver the file to the user. Example: message(content="Here is the document", channel="telegram", chat_id="...", media=["/path/to/file.pdf"])

nanobot/utils/__init__.py

@@ -1,6 +1,42 @@
 """Utility functions for nanobot."""
 
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+from types import ModuleType
+
 from nanobot.utils.helpers import ensure_dir
 from nanobot.utils.path import abbreviate_path
 
 __all__ = ["ensure_dir", "abbreviate_path"]
+
+
+class _LazyModuleAlias(ModuleType):
+    def __init__(self, name: str, target: str) -> None:
+        super().__init__(name)
+        self.__dict__["_target"] = target
+
+    def _load(self) -> ModuleType:
+        module = import_module(self.__dict__["_target"])
+        sys.modules[self.__name__] = module
+        return module
+
+    def __getattr__(self, name: str) -> object:
+        return getattr(self._load(), name)
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(super().__dir__()) | set(dir(self._load())))
+
+
+_LEGACY_MODULE_ALIASES = {
+    "webui_thread_disk": "nanobot.webui.thread_disk",
+    "webui_transcript": "nanobot.webui.transcript",
+    "webui_turn_helpers": "nanobot.session.webui_turns",
+}
+
+for _legacy_name, _target_name in _LEGACY_MODULE_ALIASES.items():
+    sys.modules.setdefault(
+        f"{__name__}.{_legacy_name}",
+        _LazyModuleAlias(f"{__name__}.{_legacy_name}", _target_name),
+    )

nanobot/utils/artifacts.py

@@ -21,8 +21,6 @@ _MIME_EXTENSIONS = {
     "image/webp": ".webp",
     "image/gif": ".gif",
 }
-_GENERATE_IMAGE_TOOL_NAME = "generate_image"
-
 
 class ArtifactError(ValueError):
     """Raised when an artifact cannot be safely decoded or stored."""
@@ -115,48 +113,10 @@ def generated_image_tool_result(artifacts: list[dict[str, Any]]) -> str:
             "artifacts": artifacts,
             "next_step": (
                 "Use these artifact paths as reference_images for follow-up edits. "
-                "For the current chat, reply naturally; the runtime attaches generated images automatically. "
+                "Call the message tool with the artifact paths in the media parameter "
-                "Do not call message just to announce or resend them. Keep raw paths internal unless the user asks for debug details."
+                "to deliver the images to the user. Keep raw paths internal unless the "
+                "user asks for debug details."
             ),
         },
         ensure_ascii=False,
     )
-
-
-def _extract_text_payload(content: Any) -> str | None:
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        parts: list[str] = []
-        for block in content:
-            if isinstance(block, dict) and isinstance(block.get("text"), str):
-                parts.append(block["text"])
-        return "\n".join(parts) if parts else None
-    return None
-
-
-def generated_image_paths_from_messages(messages: list[dict[str, Any]]) -> list[str]:
-    """Collect generated image artifact paths from generate_image tool results."""
-    paths: list[str] = []
-    seen: set[str] = set()
-    for message in messages:
-        if message.get("role") != "tool" or message.get("name") != _GENERATE_IMAGE_TOOL_NAME:
-            continue
-        payload = _extract_text_payload(message.get("content"))
-        if not payload:
-            continue
-        try:
-            data = json.loads(payload)
-        except json.JSONDecodeError:
-            continue
-        artifacts = data.get("artifacts") if isinstance(data, dict) else None
-        if not isinstance(artifacts, list):
-            continue
-        for artifact in artifacts:
-            if not isinstance(artifact, dict):
-                continue
-            path = artifact.get("path")
-            if isinstance(path, str) and path and path not in seen:
-                paths.append(path)
-                seen.add(path)
-    return paths

nanobot/utils/file_edit_events.py

@@ -4,13 +4,17 @@ from __future__ import annotations
 
 import difflib
 import json
-from dataclasses import dataclass
+import re
+import time
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, Awaitable, Callable
 
 
 TRACKED_FILE_EDIT_TOOLS = frozenset({"write_file", "edit_file", "notebook_edit"})
 _MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024
+_LIVE_EMIT_INTERVAL_S = 0.18
+_LIVE_EMIT_LINE_STEP = 24
 
 
 @dataclass(slots=True)
@@ -103,6 +107,8 @@ def line_diff_stats(before: str | None, after: str | None) -> tuple[int, int]:
     """Return ``(added, deleted)`` for a UTF-8 text line-level diff."""
     if before is None or after is None:
         return 0, 0
+    if before == "":
+        return _text_line_count(after), 0
     before_lines = before.replace("\r\n", "\n").splitlines()
     after_lines = after.replace("\r\n", "\n").splitlines()
     added = 0
@@ -118,6 +124,28 @@ def line_diff_stats(before: str | None, after: str | None) -> tuple[int, int]:
     return added, deleted
 
 
+def _text_line_count(text: str) -> int:
+    if not text:
+        return 0
+    line_count = 0
+    last_was_newline = False
+    last_was_cr = False
+    for ch in text:
+        if ch == "\r":
+            line_count += 1
+            last_was_newline = True
+            last_was_cr = True
+        elif ch == "\n":
+            if not last_was_cr:
+                line_count += 1
+            last_was_newline = True
+            last_was_cr = False
+        else:
+            last_was_newline = False
+            last_was_cr = False
+    return line_count if last_was_newline else line_count + 1
+
+
 def prepare_file_edit_tracker(
     *,
     call_id: str,
@@ -160,12 +188,22 @@ def build_file_edit_start_event(
     )
 
 
-def build_file_edit_end_event(tracker: FileEditTracker) -> dict[str, Any]:
+def build_file_edit_end_event(
+    tracker: FileEditTracker,
+    params: dict[str, Any] | None = None,
+) -> dict[str, Any]:
     after = read_file_snapshot(tracker.path)
+    counted = False
     if tracker.before.countable and after.countable:
         added, deleted = line_diff_stats(tracker.before.text, after.text)
+        counted = True
     else:
-        added, deleted = 0, 0
+        predicted_after = _predict_after_text(tracker.tool, params or {}, tracker.before)
+        if tracker.before.countable and predicted_after is not None:
+            added, deleted = line_diff_stats(tracker.before.text, predicted_after)
+            counted = True
+        else:
+            added, deleted = 0, 0
     return _event_payload(
         tracker,
         phase="end",
@@ -173,11 +211,14 @@ def build_file_edit_end_event(tracker: FileEditTracker) -> dict[str, Any]:
         added=added,
         deleted=deleted,
         approximate=False,
-        binary=after.binary or after.oversized or after.unreadable,
+        binary=(after.binary or after.oversized or after.unreadable) and not counted,
     )
 
 
-def build_file_edit_error_event(tracker: FileEditTracker, error: str | None = None) -> dict[str, Any]:
+def build_file_edit_error_event(
+    tracker: FileEditTracker,
+    error: str | None = None,
+) -> dict[str, Any]:
     payload = _event_payload(
         tracker,
         phase="error",
@@ -191,6 +232,427 @@ def build_file_edit_error_event(tracker: FileEditTracker, error: str | None = No
     return payload
 
 
+def build_file_edit_live_event(
+    tracker: FileEditTracker,
+    *,
+    added: int,
+    deleted: int = 0,
+) -> dict[str, Any]:
+    """Build an approximate in-progress event while tool-call arguments stream."""
+    return _event_payload(
+        tracker,
+        phase="start",
+        status="editing",
+        added=added,
+        deleted=deleted,
+        approximate=True,
+    )
+
+
+def build_file_edit_pending_event(
+    *,
+    call_id: str,
+    tool_name: str,
+    added: int = 0,
+    deleted: int = 0,
+) -> dict[str, Any]:
+    """Build an early placeholder before the streamed JSON path is available."""
+    return {
+        "version": 1,
+        "call_id": str(call_id or ""),
+        "tool": tool_name,
+        "path": "",
+        "phase": "start",
+        "added": max(0, int(added)),
+        "deleted": max(0, int(deleted)),
+        "approximate": True,
+        "status": "editing",
+        "pending": True,
+    }
+
+
+class StreamingFileEditTracker:
+    """Track file-edit tool arguments while the model is still streaming them.
+
+    Tool execution events only begin after the provider has completed the full
+    function call.  For large ``write_file`` calls, the long wait is usually the
+    model producing the JSON ``content`` argument.  Large ``edit_file`` calls
+    can have the same wait while ``old_text`` / ``new_text`` stream in.  This
+    tracker converts those argument deltas into approximate WebUI file-edit
+    events before the final exact diff is available.
+    """
+
+    def __init__(
+        self,
+        *,
+        workspace: Path | None,
+        tools: Any,
+        emit: Callable[[list[dict[str, Any]]], Awaitable[None]],
+    ) -> None:
+        self._workspace = workspace
+        self._tools = tools
+        self._emit = emit
+        self._states: dict[str, _StreamingFileEditState] = {}
+
+    async def update(self, payload: dict[str, Any]) -> None:
+        key = _stream_key(payload)
+        if not key:
+            return
+        state = self._states.get(key)
+        if state is None:
+            state = _StreamingFileEditState(key=key)
+            self._states[key] = state
+
+        state.apply_delta(payload)
+        if state.name not in {"write_file", "edit_file"}:
+            return
+        if state.path is None:
+            state.path = _extract_complete_json_string(state.arguments, "path")
+        if state.path is None:
+            added, deleted = state.live_diff_counts()
+            now = time.monotonic()
+            if state.should_emit_pending(added, deleted, now):
+                state.mark_pending_emitted(added, deleted, now)
+                await self._emit([build_file_edit_pending_event(
+                    call_id=state.call_id or state.key,
+                    tool_name=state.name,
+                    added=added,
+                    deleted=deleted,
+                )])
+            return
+        if state.tracker is None:
+            tool = self._tools.get(state.name) if hasattr(self._tools, "get") else None
+            state.tracker = prepare_file_edit_tracker(
+                call_id=state.call_id or state.key,
+                tool_name=state.name,
+                tool=tool,
+                workspace=self._workspace,
+                params={"path": state.path},
+            )
+            if state.tracker is None:
+                return
+
+        added, deleted = state.live_diff_counts()
+        now = time.monotonic()
+        if not state.should_emit(added, deleted, now):
+            return
+        state.mark_emitted(added, deleted, now)
+        await self._emit([build_file_edit_live_event(
+            state.tracker,
+            added=added,
+            deleted=deleted,
+        )])
+
+    async def flush(self) -> None:
+        events: list[dict[str, Any]] = []
+        now = time.monotonic()
+        for state in self._states.values():
+            if state.tracker is None:
+                continue
+            added, deleted = state.live_diff_counts()
+            if (
+                state.last_emitted_added == added
+                and state.last_emitted_deleted == deleted
+                and state.emitted_once
+            ):
+                continue
+            state.mark_emitted(added, deleted, now)
+            events.append(build_file_edit_live_event(
+                state.tracker,
+                added=added,
+                deleted=deleted,
+            ))
+        if events:
+            await self._emit(events)
+
+    def apply_final_call_ids(self, final_tool_calls: list[Any]) -> None:
+        """Keep final start/end events keyed to any earlier streamed placeholder."""
+        for tool_call in final_tool_calls:
+            canonical = self.canonical_call_id_for(tool_call)
+            if canonical:
+                try:
+                    tool_call.id = canonical
+                except Exception:
+                    pass
+
+    def canonical_call_id_for(self, tool_call: Any) -> str | None:
+        for state in self._states.values():
+            if state.matches_final_tool_call(tool_call):
+                return state.call_id or (state.tracker.call_id if state.tracker else None) or state.key
+        return None
+
+    async def error_unmatched(
+        self,
+        final_tool_calls: list[Any],
+        error: str,
+    ) -> None:
+        """Mark streamed edits as failed when no final tool call will run."""
+        events: list[dict[str, Any]] = []
+        for state in self._states.values():
+            if state.tracker is None:
+                continue
+            if any(state.matches_final_tool_call(tool_call) for tool_call in final_tool_calls):
+                continue
+            events.append(build_file_edit_error_event(state.tracker, error))
+        if events:
+            await self._emit(events)
+
+
+@dataclass(slots=True)
+class _StreamingJsonStringField:
+    key: str
+    scan_pos: int | None = None
+    closed: bool = False
+    escape: bool = False
+    unicode_remaining: int = 0
+    unicode_buffer: str = ""
+    newline_count: int = 0
+    has_chars: bool = False
+    last_char_newline: bool = False
+    last_char_cr: bool = False
+
+    @property
+    def line_count(self) -> int:
+        if not self.has_chars:
+            return 0
+        return self.newline_count + (0 if self.last_char_newline else 1)
+
+    def reset(self) -> None:
+        self.scan_pos = None
+        self.closed = False
+        self.escape = False
+        self.unicode_remaining = 0
+        self.unicode_buffer = ""
+        self.newline_count = 0
+        self.has_chars = False
+        self.last_char_newline = False
+        self.last_char_cr = False
+
+    def scan(self, source: str) -> None:
+        if self.closed:
+            return
+        if self.scan_pos is None:
+            match = re.search(rf'"{re.escape(self.key)}"\s*:\s*"', source)
+            if match is None:
+                return
+            self.scan_pos = match.end()
+        i = self.scan_pos
+        while i < len(source):
+            ch = source[i]
+            if self.unicode_remaining > 0:
+                self.unicode_buffer += ch
+                self.unicode_remaining -= 1
+                if self.unicode_remaining == 0:
+                    try:
+                        decoded = chr(int(self.unicode_buffer, 16))
+                    except ValueError:
+                        decoded = "x"
+                    self.unicode_buffer = ""
+                    self._mark_char(decoded)
+                i += 1
+                continue
+            if self.escape:
+                self.escape = False
+                if ch == "u":
+                    self.unicode_remaining = 4
+                    self.unicode_buffer = ""
+                elif ch == "n":
+                    self._mark_char("\n")
+                elif ch == "r":
+                    self._mark_char("\r")
+                else:
+                    self._mark_char(ch)
+                i += 1
+                continue
+            if ch == "\\":
+                self.escape = True
+                i += 1
+                continue
+            if ch == '"':
+                self.closed = True
+                i += 1
+                break
+            self._mark_char(ch)
+            i += 1
+        self.scan_pos = i
+
+    def _mark_char(self, ch: str) -> None:
+        self.has_chars = True
+        if ch == "\r":
+            self.newline_count += 1
+            self.last_char_newline = True
+            self.last_char_cr = True
+        elif ch == "\n":
+            if not self.last_char_cr:
+                self.newline_count += 1
+            self.last_char_newline = True
+            self.last_char_cr = False
+        else:
+            self.last_char_newline = False
+            self.last_char_cr = False
+
+
+@dataclass(slots=True)
+class _StreamingFileEditState:
+    key: str
+    call_id: str = ""
+    name: str = ""
+    arguments: str = ""
+    path: str | None = None
+    tracker: FileEditTracker | None = None
+    content: _StreamingJsonStringField = field(
+        default_factory=lambda: _StreamingJsonStringField("content")
+    )
+    old_text: _StreamingJsonStringField = field(
+        default_factory=lambda: _StreamingJsonStringField("old_text")
+    )
+    new_text: _StreamingJsonStringField = field(
+        default_factory=lambda: _StreamingJsonStringField("new_text")
+    )
+    emitted_once: bool = False
+    last_emitted_added: int = -1
+    last_emitted_deleted: int = -1
+    last_emit_at: float = 0.0
+    pending_emitted: bool = False
+    last_pending_added: int = -1
+    last_pending_deleted: int = -1
+    last_pending_at: float = 0.0
+
+    def apply_delta(self, payload: dict[str, Any]) -> None:
+        call_id = payload.get("call_id")
+        if isinstance(call_id, str) and call_id:
+            self.call_id = call_id
+        name = payload.get("name")
+        if isinstance(name, str) and name:
+            self.name = name
+        args = payload.get("arguments")
+        if isinstance(args, str):
+            self.arguments = args
+            self.content.reset()
+            self.old_text.reset()
+            self.new_text.reset()
+            return
+        delta = payload.get("arguments_delta")
+        if isinstance(delta, str) and delta:
+            self.arguments += delta
+
+    def live_diff_counts(self) -> tuple[int, int]:
+        if self.name == "write_file":
+            self.content.scan(self.arguments)
+            return self.content.line_count, 0
+        if self.name == "edit_file":
+            self.old_text.scan(self.arguments)
+            self.new_text.scan(self.arguments)
+            return self.new_text.line_count, self.old_text.line_count
+        return 0, 0
+
+    def should_emit(self, added: int, deleted: int, now: float) -> bool:
+        if not self.emitted_once:
+            return True
+        if added == self.last_emitted_added and deleted == self.last_emitted_deleted:
+            return False
+        if max(
+            abs(added - self.last_emitted_added),
+            abs(deleted - self.last_emitted_deleted),
+        ) >= _LIVE_EMIT_LINE_STEP:
+            return True
+        return now - self.last_emit_at >= _LIVE_EMIT_INTERVAL_S
+
+    def mark_emitted(self, added: int, deleted: int, now: float) -> None:
+        self.emitted_once = True
+        self.last_emitted_added = added
+        self.last_emitted_deleted = deleted
+        self.last_emit_at = now
+
+    def should_emit_pending(self, added: int, deleted: int, now: float) -> bool:
+        if not self.pending_emitted:
+            return True
+        if added == self.last_pending_added and deleted == self.last_pending_deleted:
+            return False
+        if max(
+            abs(added - self.last_pending_added),
+            abs(deleted - self.last_pending_deleted),
+        ) >= _LIVE_EMIT_LINE_STEP:
+            return True
+        return now - self.last_pending_at >= _LIVE_EMIT_INTERVAL_S
+
+    def mark_pending_emitted(self, added: int, deleted: int, now: float) -> None:
+        self.pending_emitted = True
+        self.last_pending_added = added
+        self.last_pending_deleted = deleted
+        self.last_pending_at = now
+
+    def matches_final_tool_call(self, tool_call: Any) -> bool:
+        call_id = getattr(tool_call, "id", None)
+        canonical = self.call_id or (self.tracker.call_id if self.tracker else "")
+        if isinstance(call_id, str) and call_id and canonical and call_id == canonical:
+            return True
+        name = getattr(tool_call, "name", None)
+        if name != self.name:
+            return False
+        arguments = getattr(tool_call, "arguments", None)
+        if not isinstance(arguments, dict):
+            return False
+        path = arguments.get("path")
+        if self.path is None and isinstance(path, str) and path:
+            self.path = path
+            return True
+        return isinstance(path, str) and path == self.path
+
+
+def _stream_key(payload: dict[str, Any]) -> str:
+    index = payload.get("index")
+    if isinstance(index, int):
+        return f"idx:{index}"
+    if isinstance(index, str) and index:
+        return f"idx:{index}"
+    call_id = payload.get("call_id")
+    if isinstance(call_id, str) and call_id:
+        return f"id:{call_id}"
+    return ""
+
+
+def _extract_complete_json_string(source: str, key: str) -> str | None:
+    match = re.search(rf'"{re.escape(key)}"\s*:\s*"', source)
+    if match is None:
+        return None
+    out: list[str] = []
+    i = match.end()
+    escape = False
+    while i < len(source):
+        ch = source[i]
+        if escape:
+            escape = False
+            if ch == "n":
+                out.append("\n")
+            elif ch == "r":
+                out.append("\r")
+            elif ch == "t":
+                out.append("\t")
+            elif ch == "u":
+                digits = source[i + 1:i + 5]
+                if len(digits) < 4:
+                    return None
+                try:
+                    out.append(chr(int(digits, 16)))
+                except ValueError:
+                    return None
+                i += 4
+            else:
+                out.append(ch)
+            i += 1
+            continue
+        if ch == "\\":
+            escape = True
+            i += 1
+            continue
+        if ch == '"':
+            return "".join(out)
+        out.append(ch)
+        i += 1
+    return None
+
+
 def _event_payload(
     tracker: FileEditTracker,
     *,
@@ -206,6 +668,7 @@ def _event_payload(
         "call_id": tracker.call_id,
         "tool": tracker.tool,
         "path": tracker.display_path,
+        "absolute_path": tracker.path.as_posix(),
         "phase": phase,
         "added": max(0, int(added)),
         "deleted": max(0, int(deleted)),
@@ -260,8 +723,14 @@ def _predict_notebook_after_text(params: dict[str, Any], before_text: str) -> st
         return None
     new_source = params.get("new_source")
     source = new_source if isinstance(new_source, str) else ""
-    cell_type = params.get("cell_type") if params.get("cell_type") in ("code", "markdown") else "code"
+    cell_type = (
-    mode = params.get("edit_mode") if params.get("edit_mode") in ("replace", "insert", "delete") else "replace"
+        params.get("cell_type") if params.get("cell_type") in ("code", "markdown") else "code"
+    )
+    mode = (
+        params.get("edit_mode")
+        if params.get("edit_mode") in ("replace", "insert", "delete")
+        else "replace"
+    )
     if mode == "delete":
         if 0 <= cell_index < len(cells):
             cells.pop(cell_index)

nanobot/utils/session_attachments.py

@@ -1,74 +0,0 @@
-"""Session replay: ensure assistant ``media`` paths are under the media root.
-
-WebUI history signing (``/api/.../messages``) only works for files inside
-``get_media_dir``. Tool-driven attachments may live in the workspace; stage
-copies into the websocket media bucket before persisting message JSON.
-"""
-
-from __future__ import annotations
-
-import shutil
-import uuid
-from pathlib import Path
-from typing import Any
-
-from loguru import logger
-
-from nanobot.config.paths import get_media_dir
-from nanobot.utils.helpers import safe_filename
-
-
-def stage_media_paths_for_session_replay(paths: list[str]) -> list[str]:
-    """Keep local files only; copy anything outside the media root into ``media/websocket``."""
-    root = get_media_dir().resolve()
-    out: list[str] = []
-    seen: set[str] = set()
-    for raw in paths:
-        if not isinstance(raw, str) or not raw.strip():
-            continue
-        if raw.startswith(("http://", "https://")):
-            continue
-        try:
-            p = Path(raw).expanduser().resolve()
-        except OSError:
-            continue
-        if not p.is_file():
-            continue
-        try:
-            p.relative_to(root)
-            key = str(p)
-        except ValueError:
-            try:
-                media_dir = get_media_dir("websocket")
-                staged = media_dir / f"{uuid.uuid4().hex[:12]}-{safe_filename(p.name) or 'attachment'}"
-                shutil.copyfile(p, staged)
-                key = str(staged.resolve())
-            except OSError as exc:
-                logger.warning("failed to stage session media from {}: {}", raw, exc)
-                continue
-        if key not in seen:
-            out.append(key)
-            seen.add(key)
-    return out
-
-
-def merge_turn_media_into_last_assistant(
-    all_messages: list[dict[str, Any]],
-    generated_image_paths: list[str],
-    extra_attachment_paths: list[str],
-) -> None:
-    """Attach staged paths to the last assistant row in *all_messages* (in-place)."""
-    merged = list(
-        dict.fromkeys(
-            [
-                *stage_media_paths_for_session_replay(generated_image_paths),
-                *stage_media_paths_for_session_replay(extra_attachment_paths),
-            ]
-        )
-    )
-    last = all_messages[-1] if all_messages else None
-    if not merged or not last or last.get("role") != "assistant":
-        return
-    existing = last.get("media")
-    base = existing if isinstance(existing, list) else []
-    last["media"] = list(dict.fromkeys([*base, *merged]))

nanobot/webui/__init__.py

@@ -0,0 +1,2 @@
+"""Backend helpers for the bundled WebUI surface."""
+

nanobot/webui/settings_api.py

@@ -0,0 +1,609 @@
+"""Settings REST helpers for the WebUI HTTP surface.
+
+The WebSocket channel owns transport/authentication. This module owns the
+settings payload shape and the allowlisted config mutations exposed to WebUI.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from nanobot.config.loader import get_config_path, load_config, save_config
+from nanobot.providers.image_generation import (
+    get_image_gen_provider,
+    image_gen_provider_names,
+)
+from nanobot.providers.registry import PROVIDERS, find_by_name
+
+QueryParams = dict[str, list[str]]
+
+_WEB_SEARCH_PROVIDER_OPTIONS: tuple[dict[str, str], ...] = (
+    {"name": "duckduckgo", "label": "DuckDuckGo", "credential": "none"},
+    {"name": "brave", "label": "Brave Search", "credential": "api_key"},
+    {"name": "tavily", "label": "Tavily", "credential": "api_key"},
+    {"name": "searxng", "label": "SearXNG", "credential": "base_url"},
+    {"name": "jina", "label": "Jina", "credential": "api_key"},
+    {"name": "kagi", "label": "Kagi", "credential": "api_key"},
+    {"name": "olostep", "label": "Olostep", "credential": "api_key"},
+)
+_WEB_SEARCH_PROVIDER_BY_NAME = {
+    provider["name"]: provider for provider in _WEB_SEARCH_PROVIDER_OPTIONS
+}
+
+_IMAGE_GENERATION_ASPECT_RATIOS = {
+    "1:1",
+    "3:4",
+    "9:16",
+    "4:3",
+    "16:9",
+    "3:2",
+    "2:3",
+    "21:9",
+}
+
+
+class WebUISettingsError(ValueError):
+    """User-facing settings validation failure."""
+
+    def __init__(self, message: str, *, status: int = 400) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+def _query_first(query: QueryParams, key: str) -> str | None:
+    values = query.get(key)
+    return values[0] if values else None
+
+
+def _query_first_alias(query: QueryParams, snake: str, camel: str) -> str | None:
+    value = _query_first(query, snake)
+    return _query_first(query, camel) if value is None else value
+
+
+def _mask_secret_hint(secret: str | None) -> str | None:
+    if not secret:
+        return None
+    if len(secret) <= 8:
+        return "••••"
+    return f"{secret[:4]}••••{secret[-4:]}"
+
+
+def _provider_requires_api_key(spec: Any) -> bool:
+    if spec.backend == "azure_openai":
+        return True
+    if spec.is_local or spec.is_direct:
+        return False
+    return True
+
+
+def _provider_configured_for_settings(spec: Any, provider_config: Any) -> bool:
+    if _provider_requires_api_key(spec):
+        return bool(provider_config.api_key)
+    return bool(
+        provider_config.api_key
+        or provider_config.api_base
+        or getattr(provider_config, "region", None)
+        or getattr(provider_config, "profile", None)
+    )
+
+
+def _parse_bool(value: str, field: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized not in {"1", "0", "true", "false", "yes", "no"}:
+        raise WebUISettingsError(f"{field} must be boolean")
+    return normalized in {"1", "true", "yes"}
+
+
+def _image_generation_provider_rows(config: Any) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for name in image_gen_provider_names():
+        spec = find_by_name(name)
+        provider_config = getattr(config.providers, name, None)
+        configured = (
+            _provider_configured_for_settings(spec, provider_config)
+            if spec is not None and provider_config is not None
+            else bool(getattr(provider_config, "api_key", None))
+        )
+        rows.append(
+            {
+                "name": name,
+                "label": spec.label if spec is not None else name,
+                "configured": configured,
+                "api_key_hint": _mask_secret_hint(
+                    getattr(provider_config, "api_key", None)
+                ),
+                "api_base": getattr(provider_config, "api_base", None),
+                "default_api_base": (
+                    spec.default_api_base if spec and spec.default_api_base else None
+                ),
+            }
+        )
+    return rows
+
+
+def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
+    config = load_config()
+    defaults = config.agents.defaults
+    active_preset_name = defaults.model_preset or "default"
+    try:
+        effective_preset = config.resolve_preset()
+    except Exception:
+        effective_preset = config.resolve_default_preset()
+        active_preset_name = "default"
+
+    provider_name = (
+        config.get_provider_name(effective_preset.model, preset=effective_preset)
+        or effective_preset.provider
+    )
+    provider = config.get_provider(effective_preset.model, preset=effective_preset)
+    selected_provider = provider_name
+    if effective_preset.provider != "auto":
+        spec = find_by_name(effective_preset.provider)
+        selected_provider = spec.name if spec else provider_name
+
+    providers = []
+    for spec in PROVIDERS:
+        provider_config = getattr(config.providers, spec.name, None)
+        if provider_config is None or spec.is_oauth:
+            continue
+        providers.append(
+            {
+                "name": spec.name,
+                "label": spec.label,
+                "configured": _provider_configured_for_settings(spec, provider_config),
+                "api_key_required": _provider_requires_api_key(spec),
+                "api_key_hint": _mask_secret_hint(provider_config.api_key),
+                "api_base": provider_config.api_base,
+                "default_api_base": spec.default_api_base or None,
+            }
+        )
+
+    search_config = config.tools.web.search
+    image_config = config.tools.image_generation
+    search_provider = (
+        search_config.provider
+        if search_config.provider in _WEB_SEARCH_PROVIDER_BY_NAME
+        else "duckduckgo"
+    )
+    image_providers = _image_generation_provider_rows(config)
+    selected_image_provider = next(
+        (
+            provider
+            for provider in image_providers
+            if provider["name"] == image_config.provider
+        ),
+        None,
+    )
+    model_presets = [
+        {
+            "name": "default",
+            "label": "Default",
+            "active": active_preset_name == "default",
+            "is_default": True,
+            "model": defaults.model,
+            "provider": defaults.provider,
+            "max_tokens": defaults.max_tokens,
+            "context_window_tokens": defaults.context_window_tokens,
+            "temperature": defaults.temperature,
+            "reasoning_effort": defaults.reasoning_effort,
+        }
+    ]
+    for name, preset in config.model_presets.items():
+        model_presets.append(
+            {
+                "name": name,
+                "label": name,
+                "active": active_preset_name == name,
+                "is_default": False,
+                "model": preset.model,
+                "provider": preset.provider,
+                "max_tokens": preset.max_tokens,
+                "context_window_tokens": preset.context_window_tokens,
+                "temperature": preset.temperature,
+                "reasoning_effort": preset.reasoning_effort,
+            }
+        )
+
+    exec_config = config.tools.exec
+    return {
+        "agent": {
+            "model": effective_preset.model,
+            "provider": selected_provider,
+            "resolved_provider": provider_name,
+            "has_api_key": bool(provider and provider.api_key),
+            "model_preset": active_preset_name,
+            "max_tokens": effective_preset.max_tokens,
+            "context_window_tokens": effective_preset.context_window_tokens,
+            "temperature": effective_preset.temperature,
+            "reasoning_effort": effective_preset.reasoning_effort,
+            "timezone": defaults.timezone,
+            "bot_name": defaults.bot_name,
+            "bot_icon": defaults.bot_icon,
+            "tool_hint_max_length": defaults.tool_hint_max_length,
+        },
+        "model_presets": model_presets,
+        "providers": providers,
+        "web_search": {
+            "provider": search_provider,
+            "api_key_hint": _mask_secret_hint(search_config.api_key),
+            "base_url": search_config.base_url or None,
+            "max_results": search_config.max_results,
+            "timeout": search_config.timeout,
+            "providers": list(_WEB_SEARCH_PROVIDER_OPTIONS),
+        },
+        "web": {
+            "enable": config.tools.web.enable,
+            "proxy": config.tools.web.proxy,
+            "user_agent": config.tools.web.user_agent,
+            "search": {
+                "max_results": search_config.max_results,
+                "timeout": search_config.timeout,
+            },
+            "fetch": {
+                "use_jina_reader": config.tools.web.fetch.use_jina_reader,
+            },
+        },
+        "image_generation": {
+            "enabled": image_config.enabled,
+            "provider": image_config.provider,
+            "provider_configured": bool(
+                selected_image_provider and selected_image_provider["configured"]
+            ),
+            "model": image_config.model,
+            "default_aspect_ratio": image_config.default_aspect_ratio,
+            "default_image_size": image_config.default_image_size,
+            "max_images_per_turn": image_config.max_images_per_turn,
+            "save_dir": image_config.save_dir,
+            "providers": image_providers,
+        },
+        "runtime": {
+            "config_path": str(get_config_path().expanduser()),
+            "workspace_path": str(config.workspace_path),
+            "gateway_host": config.gateway.host,
+            "gateway_port": config.gateway.port,
+            "heartbeat": {
+                "enabled": config.gateway.heartbeat.enabled,
+                "interval_s": config.gateway.heartbeat.interval_s,
+                "keep_recent_messages": config.gateway.heartbeat.keep_recent_messages,
+            },
+            "dream": {
+                "schedule": defaults.dream.describe_schedule(),
+                "max_batch_size": defaults.dream.max_batch_size,
+                "max_iterations": defaults.dream.max_iterations,
+                "annotate_line_ages": defaults.dream.annotate_line_ages,
+            },
+            "unified_session": defaults.unified_session,
+        },
+        "advanced": {
+            "restrict_to_workspace": config.tools.restrict_to_workspace,
+            "ssrf_whitelist_count": len(config.tools.ssrf_whitelist),
+            "mcp_server_count": len(config.tools.mcp_servers),
+            "exec_enabled": exec_config.enable,
+            "exec_sandbox": exec_config.sandbox or None,
+            "exec_path_append_set": bool(exec_config.path_append),
+        },
+        "requires_restart": requires_restart,
+    }
+
+
+def update_agent_settings(query: QueryParams) -> dict[str, Any]:
+    config = load_config()
+    defaults = config.agents.defaults
+    changed = False
+    restart_required = False
+
+    if "model_preset" in query or "modelPreset" in query:
+        preset = (_query_first_alias(query, "model_preset", "modelPreset") or "").strip()
+        preset_value = None if not preset or preset == "default" else preset
+        if preset_value is not None and preset_value not in config.model_presets:
+            raise WebUISettingsError("unknown model preset")
+        if defaults.model_preset != preset_value:
+            defaults.model_preset = preset_value
+            changed = True
+
+    model = _query_first(query, "model")
+    if model is not None:
+        model = model.strip()
+        if not model:
+            raise WebUISettingsError("model is required")
+        if defaults.model != model:
+            defaults.model = model
+            changed = True
+
+    provider = _query_first(query, "provider")
+    if provider is not None:
+        provider = provider.strip()
+        if not provider:
+            raise WebUISettingsError("provider is required")
+        spec = find_by_name(provider)
+        if spec is None:
+            raise WebUISettingsError("unknown provider")
+        provider_config = getattr(config.providers, provider, None)
+        if (
+            provider_config is None
+            or not _provider_configured_for_settings(spec, provider_config)
+        ):
+            raise WebUISettingsError("provider is not configured")
+        if defaults.provider != provider:
+            defaults.provider = provider
+            changed = True
+
+    timezone = _query_first(query, "timezone")
+    if timezone is not None:
+        timezone = timezone.strip()
+        if not timezone:
+            raise WebUISettingsError("timezone is required")
+        try:
+            ZoneInfo(timezone)
+        except Exception:
+            raise WebUISettingsError("invalid timezone") from None
+        if defaults.timezone != timezone:
+            defaults.timezone = timezone
+            changed = True
+            restart_required = True
+
+    bot_name = _query_first_alias(query, "bot_name", "botName")
+    if bot_name is not None:
+        bot_name = bot_name.strip()
+        if not bot_name:
+            raise WebUISettingsError("bot_name is required")
+        if defaults.bot_name != bot_name:
+            defaults.bot_name = bot_name
+            changed = True
+            restart_required = True
+
+    bot_icon = _query_first_alias(query, "bot_icon", "botIcon")
+    if bot_icon is not None:
+        bot_icon = bot_icon.strip()
+        if defaults.bot_icon != bot_icon:
+            defaults.bot_icon = bot_icon
+            changed = True
+            restart_required = True
+
+    tool_hint_max_length = _query_first_alias(
+        query,
+        "tool_hint_max_length",
+        "toolHintMaxLength",
+    )
+    if tool_hint_max_length is not None:
+        try:
+            parsed = int(tool_hint_max_length)
+        except ValueError:
+            raise WebUISettingsError("tool_hint_max_length must be an integer") from None
+        if parsed < 20 or parsed > 500:
+            raise WebUISettingsError("tool_hint_max_length must be between 20 and 500")
+        if defaults.tool_hint_max_length != parsed:
+            defaults.tool_hint_max_length = parsed
+            changed = True
+            restart_required = True
+
+    if changed:
+        save_config(config)
+    return settings_payload(requires_restart=restart_required)
+
+
+def update_provider_settings(query: QueryParams) -> dict[str, Any]:
+    provider_name = (_query_first(query, "provider") or "").strip()
+    if not provider_name:
+        raise WebUISettingsError("provider is required")
+    spec = find_by_name(provider_name)
+    if spec is None or spec.is_oauth:
+        raise WebUISettingsError("unknown provider")
+
+    config = load_config()
+    provider_config = getattr(config.providers, spec.name, None)
+    if provider_config is None:
+        raise WebUISettingsError("unknown provider")
+
+    changed = False
+    if "api_key" in query or "apiKey" in query:
+        api_key = _query_first_alias(query, "api_key", "apiKey")
+        api_key = (api_key or "").strip() or None
+        if provider_config.api_key != api_key:
+            provider_config.api_key = api_key
+            changed = True
+
+    if "api_base" in query or "apiBase" in query:
+        api_base = _query_first_alias(query, "api_base", "apiBase")
+        api_base = (api_base or "").strip() or None
+        if provider_config.api_base != api_base:
+            provider_config.api_base = api_base
+            changed = True
+
+    if changed:
+        save_config(config)
+    image_config = config.tools.image_generation
+    restart_required = (
+        changed
+        and image_config.enabled
+        and image_config.provider == spec.name
+        and get_image_gen_provider(spec.name) is not None
+    )
+    return settings_payload(requires_restart=restart_required)
+
+
+def update_web_search_settings(query: QueryParams) -> dict[str, Any]:
+    provider_name = (_query_first(query, "provider") or "").strip().lower()
+    provider_option = _WEB_SEARCH_PROVIDER_BY_NAME.get(provider_name)
+    if provider_option is None:
+        raise WebUISettingsError("unknown web search provider")
+
+    config = load_config()
+    search_config = config.tools.web.search
+    web_config = config.tools.web
+    previous_provider = search_config.provider
+    changed = False
+    restart_required = False
+
+    def set_search_value(attr: str, value: object) -> None:
+        nonlocal changed
+        if getattr(search_config, attr) != value:
+            setattr(search_config, attr, value)
+            changed = True
+
+    def set_fetch_value(attr: str, value: object) -> None:
+        nonlocal changed
+        if getattr(web_config.fetch, attr) != value:
+            setattr(web_config.fetch, attr, value)
+            changed = True
+
+    if search_config.provider != provider_name:
+        search_config.provider = provider_name
+        changed = True
+
+    credential = provider_option["credential"]
+    if credential == "none":
+        set_search_value("api_key", "")
+        set_search_value("base_url", "")
+    elif credential == "base_url":
+        base_url = _query_first_alias(query, "base_url", "baseUrl")
+        base_url = base_url.strip() if base_url is not None else None
+        if not base_url and previous_provider == provider_name and search_config.base_url:
+            base_url = search_config.base_url
+        if not base_url:
+            raise WebUISettingsError("base_url is required")
+        set_search_value("base_url", base_url)
+        set_search_value("api_key", "")
+    else:
+        api_key = _query_first_alias(query, "api_key", "apiKey")
+        api_key = api_key.strip() if api_key is not None else None
+        if not api_key and previous_provider == provider_name and search_config.api_key:
+            api_key = search_config.api_key
+        if not api_key:
+            raise WebUISettingsError("api_key is required")
+        set_search_value("api_key", api_key)
+        set_search_value("base_url", "")
+
+    max_results = _query_first_alias(query, "max_results", "maxResults")
+    if max_results is not None:
+        try:
+            parsed = int(max_results)
+        except ValueError:
+            raise WebUISettingsError("max_results must be an integer") from None
+        if parsed < 1 or parsed > 10:
+            raise WebUISettingsError("max_results must be between 1 and 10")
+        set_search_value("max_results", parsed)
+
+    timeout = _query_first(query, "timeout")
+    if timeout is not None:
+        try:
+            parsed_timeout = int(timeout)
+        except ValueError:
+            raise WebUISettingsError("timeout must be an integer") from None
+        if parsed_timeout < 1 or parsed_timeout > 120:
+            raise WebUISettingsError("timeout must be between 1 and 120")
+        set_search_value("timeout", parsed_timeout)
+
+    use_jina_reader = _query_first_alias(query, "use_jina_reader", "useJinaReader")
+    if use_jina_reader is not None:
+        normalized = use_jina_reader.strip().lower()
+        if normalized not in {"1", "0", "true", "false", "yes", "no"}:
+            raise WebUISettingsError("use_jina_reader must be boolean")
+        previous_jina_reader = web_config.fetch.use_jina_reader
+        set_fetch_value("use_jina_reader", normalized in {"1", "true", "yes"})
+        if web_config.fetch.use_jina_reader != previous_jina_reader:
+            restart_required = True
+
+    if changed:
+        save_config(config)
+    return settings_payload(requires_restart=restart_required)
+
+
+def update_image_generation_settings(query: QueryParams) -> dict[str, Any]:
+    config = load_config()
+    image_config = config.tools.image_generation
+    changed = False
+
+    provider_name = _query_first(query, "provider")
+    if provider_name is not None:
+        provider_name = provider_name.strip().lower()
+        if not provider_name:
+            raise WebUISettingsError("image generation provider is required")
+        if get_image_gen_provider(provider_name) is None:
+            raise WebUISettingsError("unknown image generation provider")
+        if image_config.provider != provider_name:
+            image_config.provider = provider_name
+            changed = True
+
+    enabled = _query_first(query, "enabled")
+    if enabled is not None:
+        parsed_enabled = _parse_bool(enabled, "enabled")
+        if image_config.enabled != parsed_enabled:
+            image_config.enabled = parsed_enabled
+            changed = True
+
+    model = _query_first(query, "model")
+    if model is not None:
+        model = model.strip()
+        if not model:
+            raise WebUISettingsError("image generation model is required")
+        if len(model) > 200:
+            raise WebUISettingsError("image generation model is too long")
+        if image_config.model != model:
+            image_config.model = model
+            changed = True
+
+    default_aspect_ratio = _query_first_alias(
+        query,
+        "default_aspect_ratio",
+        "defaultAspectRatio",
+    )
+    if default_aspect_ratio is not None:
+        default_aspect_ratio = default_aspect_ratio.strip()
+        if default_aspect_ratio not in _IMAGE_GENERATION_ASPECT_RATIOS:
+            raise WebUISettingsError("unsupported image generation aspect ratio")
+        if image_config.default_aspect_ratio != default_aspect_ratio:
+            image_config.default_aspect_ratio = default_aspect_ratio
+            changed = True
+
+    default_image_size = _query_first_alias(
+        query,
+        "default_image_size",
+        "defaultImageSize",
+    )
+    if default_image_size is not None:
+        default_image_size = default_image_size.strip()
+        if not default_image_size:
+            raise WebUISettingsError("default image size is required")
+        if len(default_image_size) > 32 or not all(
+            char.isascii() and (char.isalnum() or char in {"x", "X", ":", "-", "_"})
+            for char in default_image_size
+        ):
+            raise WebUISettingsError("unsupported image generation size")
+        if image_config.default_image_size != default_image_size:
+            image_config.default_image_size = default_image_size
+            changed = True
+
+    max_images_per_turn = _query_first_alias(
+        query,
+        "max_images_per_turn",
+        "maxImagesPerTurn",
+    )
+    if max_images_per_turn is not None:
+        try:
+            parsed_max = int(max_images_per_turn)
+        except ValueError:
+            raise WebUISettingsError("max_images_per_turn must be an integer") from None
+        if parsed_max < 1 or parsed_max > 8:
+            raise WebUISettingsError("max_images_per_turn must be between 1 and 8")
+        if image_config.max_images_per_turn != parsed_max:
+            image_config.max_images_per_turn = parsed_max
+            changed = True
+
+    if image_config.enabled:
+        selected_provider = next(
+            (
+                provider
+                for provider in _image_generation_provider_rows(config)
+                if provider["name"] == image_config.provider
+            ),
+            None,
+        )
+        if not selected_provider or not selected_provider["configured"]:
+            raise WebUISettingsError("image generation provider is not configured")
+
+    if changed:
+        save_config(config)
+    return settings_payload(requires_restart=changed)

nanobot/webui/sidebar_state.py

@@ -0,0 +1,193 @@
+"""Persisted WebUI sidebar workspace state.
+
+This state is UI-only metadata, scoped to the active nanobot instance data
+directory (the directory containing the current config.json). It deliberately
+does not modify agent sessions.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from nanobot.config.paths import get_webui_dir
+
+WEBUI_SIDEBAR_STATE_SCHEMA_VERSION = 1
+_MAX_STATE_FILE_BYTES = 256 * 1024
+_MAX_LIST_ITEMS = 2_000
+_MAX_MAP_ITEMS = 2_000
+_MAX_KEY_LEN = 512
+_MAX_TITLE_LEN = 160
+_MAX_TAG_LEN = 40
+_ALLOWED_DENSITIES = {"comfortable", "compact"}
+_ALLOWED_SORTS = {"updated_desc", "created_desc", "title_asc"}
+
+
+def webui_sidebar_state_path() -> Path:
+    return get_webui_dir() / "sidebar-state.json"
+
+
+def default_webui_sidebar_state() -> dict[str, Any]:
+    return {
+        "schema_version": WEBUI_SIDEBAR_STATE_SCHEMA_VERSION,
+        "pinned_keys": [],
+        "archived_keys": [],
+        "title_overrides": {},
+        "tags_by_key": {},
+        "collapsed_groups": {},
+        "view": {
+            "density": "comfortable",
+            "show_previews": False,
+            "show_timestamps": False,
+            "show_archived": False,
+            "sort": "updated_desc",
+        },
+        "updated_at": None,
+    }
+
+
+def _clean_string(value: Any, *, max_len: int = _MAX_KEY_LEN) -> str | None:
+    if not isinstance(value, str):
+        return None
+    cleaned = value.strip()
+    if not cleaned:
+        return None
+    return cleaned[:max_len]
+
+
+def _clean_string_list(value: Any, *, max_len: int = _MAX_KEY_LEN) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    out: list[str] = []
+    seen: set[str] = set()
+    for item in value[:_MAX_LIST_ITEMS]:
+        cleaned = _clean_string(item, max_len=max_len)
+        if cleaned is None or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        out.append(cleaned)
+    return out
+
+
+def _clean_bool_map(value: Any) -> dict[str, bool]:
+    if not isinstance(value, dict):
+        return {}
+    out: dict[str, bool] = {}
+    for key, raw in list(value.items())[:_MAX_MAP_ITEMS]:
+        cleaned_key = _clean_string(key)
+        if cleaned_key is None:
+            continue
+        out[cleaned_key] = bool(raw)
+    return out
+
+
+def _clean_title_overrides(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    out: dict[str, str] = {}
+    for key, raw_title in list(value.items())[:_MAX_MAP_ITEMS]:
+        cleaned_key = _clean_string(key)
+        cleaned_title = _clean_string(raw_title, max_len=_MAX_TITLE_LEN)
+        if cleaned_key is None or cleaned_title is None:
+            continue
+        out[cleaned_key] = cleaned_title
+    return out
+
+
+def _clean_tags_by_key(value: Any) -> dict[str, list[str]]:
+    if not isinstance(value, dict):
+        return {}
+    out: dict[str, list[str]] = {}
+    for key, raw_tags in list(value.items())[:_MAX_MAP_ITEMS]:
+        cleaned_key = _clean_string(key)
+        if cleaned_key is None:
+            continue
+        tags = _clean_string_list(raw_tags, max_len=_MAX_TAG_LEN)[:12]
+        if tags:
+            out[cleaned_key] = tags
+    return out
+
+
+def _clean_view(value: Any) -> dict[str, Any]:
+    default = default_webui_sidebar_state()["view"]
+    if not isinstance(value, dict):
+        return dict(default)
+    density = value.get("density")
+    sort = value.get("sort")
+    return {
+        "density": density if density in _ALLOWED_DENSITIES else default["density"],
+        "show_previews": bool(value.get("show_previews", default["show_previews"])),
+        "show_timestamps": bool(value.get("show_timestamps", default["show_timestamps"])),
+        "show_archived": bool(value.get("show_archived", default["show_archived"])),
+        "sort": sort if sort in _ALLOWED_SORTS else default["sort"],
+    }
+
+
+def normalize_webui_sidebar_state(raw: Any) -> dict[str, Any]:
+    """Return a schema-v1 sidebar state from any older/partial input."""
+    if not isinstance(raw, dict):
+        raw = {}
+    state = default_webui_sidebar_state()
+    state["pinned_keys"] = _clean_string_list(raw.get("pinned_keys"))
+    state["archived_keys"] = _clean_string_list(raw.get("archived_keys"))
+    state["title_overrides"] = _clean_title_overrides(raw.get("title_overrides"))
+    state["tags_by_key"] = _clean_tags_by_key(raw.get("tags_by_key"))
+    state["collapsed_groups"] = _clean_bool_map(raw.get("collapsed_groups"))
+    state["view"] = _clean_view(raw.get("view"))
+    updated_at = raw.get("updated_at")
+    state["updated_at"] = updated_at if isinstance(updated_at, str) else None
+    return state
+
+
+def read_webui_sidebar_state() -> dict[str, Any]:
+    path = webui_sidebar_state_path()
+    if not path.is_file():
+        return default_webui_sidebar_state()
+    try:
+        if path.stat().st_size > _MAX_STATE_FILE_BYTES:
+            logger.warning("webui sidebar state too large, ignoring: {}", path)
+            return default_webui_sidebar_state()
+        with open(path, encoding="utf-8") as f:
+            raw = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        logger.warning("read webui sidebar state failed {}: {}", path, e)
+        return default_webui_sidebar_state()
+    return normalize_webui_sidebar_state(raw)
+
+
+def write_webui_sidebar_state(raw: dict[str, Any]) -> dict[str, Any]:
+    state = normalize_webui_sidebar_state(raw)
+    state["updated_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    encoded = json.dumps(
+        state,
+        ensure_ascii=False,
+        indent=2,
+        sort_keys=True,
+    ).encode("utf-8")
+    if len(encoded) > _MAX_STATE_FILE_BYTES:
+        raise ValueError("sidebar state is too large")
+
+    path = webui_sidebar_state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    with open(tmp, "wb") as f:
+        f.write(encoded)
+        f.write(b"\n")
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+    try:
+        dir_fd = os.open(path.parent, os.O_RDONLY)
+    except OSError:
+        return state
+    try:
+        os.fsync(dir_fd)
+    finally:
+        os.close(dir_fd)
+    return state
+

nanobot/webui/thread_disk.py

@@ -1,4 +1,4 @@
-"""Legacy WebUI JSON snapshot path helpers (JSON file); transcripts use webui_transcript."""
+"""Legacy WebUI JSON snapshot path helpers (JSON file); transcripts use transcript."""
 
 from __future__ import annotations
 
@@ -8,7 +8,7 @@ from loguru import logger
 
 from nanobot.config.paths import get_webui_dir
 from nanobot.session.manager import SessionManager
-from nanobot.utils.webui_transcript import delete_webui_transcript
+from nanobot.webui.transcript import delete_webui_transcript
 
 
 def webui_thread_file_path(session_key: str) -> Path:

nanobot/webui/transcript.py

@@ -99,17 +99,39 @@ def tool_trace_lines_from_events(events: Any) -> list[str]:
     if not isinstance(events, list):
         return []
     lines: list[str] = []
+    seen: set[str] = set()
     for event in events:
         if not event or not isinstance(event, dict):
             continue
-        if event.get("phase") != "start":
+        if event.get("phase") not in {"start", "end", "error"}:
             continue
+        call_id = event.get("call_id")
+        if isinstance(call_id, str) and call_id:
+            if call_id in seen:
+                continue
+            seen.add(call_id)
         t = _format_tool_call_trace(event)
         if t:
             lines.append(t)
     return lines
 
 
+def _merge_unique_tool_trace_lines(
+    previous_traces: list[str],
+    lines: list[str],
+) -> tuple[list[str], bool]:
+    seen_lines = set(previous_traces)
+    traces = list(previous_traces)
+    added = False
+    for line in lines:
+        if line in seen_lines:
+            continue
+        seen_lines.add(line)
+        traces.append(line)
+        added = True
+    return traces, added
+
+
 def replay_transcript_to_ui_messages(
     lines: list[dict[str, Any]],
     *,
@@ -144,6 +166,17 @@ def replay_transcript_to_ui_messages(
     def _ensure_activity_segment() -> str:
         return active_activity_segment_id or _new_activity_segment()
 
+    def close_activity_for_answer() -> None:
+        nonlocal active_activity_segment_id, active_file_edit_segment_id
+        active_activity_segment_id = None
+        active_file_edit_segment_id = None
+
+    def close_file_edit_phase_before_activity() -> None:
+        nonlocal active_activity_segment_id, active_file_edit_segment_id
+        if active_file_edit_segment_id:
+            active_activity_segment_id = None
+            active_file_edit_segment_id = None
+
     def attach_reasoning_chunk(prev: list[dict[str, Any]], chunk: str, idx: int) -> None:
         for i in range(len(prev) - 1, -1, -1):
             candidate = prev[i]
@@ -243,7 +276,7 @@ def replay_transcript_to_ui_messages(
                 return
 
     def absorb_complete(extra: dict[str, Any], idx: int) -> None:
-        nonlocal active_activity_segment_id
+        nonlocal active_activity_segment_id, active_file_edit_segment_id
         last = messages[-1] if messages else None
         if last and is_reasoning_only_placeholder(last):
             messages[-1] = {
@@ -262,35 +295,50 @@ def replay_transcript_to_ui_messages(
                 },
             )
         active_activity_segment_id = None
+        active_file_edit_segment_id = None
 
     def _file_edit_key(edit: dict[str, Any]) -> str:
-        return "|".join(
+        call_id = str(edit.get("call_id") or "")
-            str(edit.get(k) or "")
+        tool = str(edit.get("tool") or "")
-            for k in ("call_id", "tool", "path")
+        if call_id:
-        )
+            return f"{call_id}|{tool}"
+        return f"{tool}|{edit.get('path') or ''}"
+
+    def find_file_edit_trace_index(
+        segment: str | None,
+        edits: list[dict[str, Any]],
+    ) -> int | None:
+        incoming_keys = {_file_edit_key(edit) for edit in edits if isinstance(edit, dict)}
+        for i in range(len(messages) - 1, -1, -1):
+            candidate = messages[i]
+            if candidate.get("role") == "user":
+                break
+            if candidate.get("kind") != "trace" or not candidate.get("fileEdits"):
+                continue
+            if segment and candidate.get("activitySegmentId") == segment:
+                return i
+            existing_edits = candidate.get("fileEdits")
+            if not isinstance(existing_edits, list):
+                continue
+            for existing in existing_edits:
+                if isinstance(existing, dict) and _file_edit_key(existing) in incoming_keys:
+                    return i
+        return None
 
     def upsert_file_edits(edits: list[dict[str, Any]], idx: int) -> None:
         nonlocal active_file_edit_segment_id
         if not edits:
             return
-        last = messages[-1] if messages else None
+        segment = active_file_edit_segment_id
-        if (
+        target_index = find_file_edit_trace_index(segment, edits)
-            active_file_edit_segment_id
+        if target_index is not None:
-            and last
+            last = messages[target_index]
-            and last.get("kind") == "trace"
+            segment = str(last.get("activitySegmentId") or segment or _new_activity_segment(activate=False))
-            and last.get("fileEdits")
+            active_file_edit_segment_id = segment
-        ):
-            segment = active_file_edit_segment_id
         else:
-            segment = _new_activity_segment(activate=False)
+            if not segment:
+                segment = _new_activity_segment(activate=False)
             active_file_edit_segment_id = segment
-        if not (
-            last
-            and last.get("kind") == "trace"
-            and not last.get("isStreaming")
-            and last.get("fileEdits")
-            and last.get("activitySegmentId") == segment
-        ):
             messages.append(
                 {
                     "id": _new_id("tr", idx),
@@ -303,7 +351,11 @@ def replay_transcript_to_ui_messages(
                     "createdAt": _ts_base + idx,
                 },
             )
-            last = messages[-1]
+            target_index = len(messages) - 1
+            last = messages[target_index]
+        if not segment:
+            segment = _new_activity_segment(activate=False)
+            active_file_edit_segment_id = segment
         existing = list(last.get("fileEdits") or [])
         index_by_key = {
             _file_edit_key(edit): pos
@@ -316,11 +368,14 @@ def replay_transcript_to_ui_messages(
             key = _file_edit_key(edit)
             if key in index_by_key:
                 pos = index_by_key[key]
-                existing[pos] = {**existing[pos], **edit}
+                merged = {**existing[pos], **edit}
+                if edit.get("path") and not edit.get("pending"):
+                    merged.pop("pending", None)
+                existing[pos] = merged
             else:
                 index_by_key[key] = len(existing)
                 existing.append(dict(edit))
-        messages[-1] = {
+        messages[target_index] = {
             **last,
             "fileEdits": existing,
             "activitySegmentId": last.get("activitySegmentId") or segment,
@@ -365,6 +420,7 @@ def replay_transcript_to_ui_messages(
             chunk = rec.get("text")
             if not isinstance(chunk, str):
                 continue
+            close_activity_for_answer()
             adopted = find_active_placeholder(messages) if buffer_message_id is None else None
             if buffer_message_id is None:
                 if adopted:
@@ -403,6 +459,7 @@ def replay_transcript_to_ui_messages(
             chunk = rec.get("text")
             if not isinstance(chunk, str) or not chunk:
                 continue
+            close_file_edit_phase_before_activity()
             attach_reasoning_chunk(messages, chunk, idx)
             continue
 
@@ -424,6 +481,7 @@ def replay_transcript_to_ui_messages(
                 line = rec.get("text")
                 if not isinstance(line, str) or not line:
                     continue
+                close_file_edit_phase_before_activity()
                 attach_reasoning_chunk(messages, line, idx)
                 close_reasoning(messages)
                 continue
@@ -442,13 +500,19 @@ def replay_transcript_to_ui_messages(
                     and (last.get("activitySegmentId") in (None, segment))
                 ):
                     prev_traces = list(last.get("traces") or [last.get("content")])
-                    merged_traces = prev_traces + trace_lines
+                    if structured:
-                    messages[-1] = {
+                        merged_traces, added = _merge_unique_tool_trace_lines(prev_traces, structured)
+                        if not added:
+                            continue
+                    else:
+                        merged_traces = prev_traces + trace_lines
+                    merged = {
                         **last,
                         "traces": merged_traces,
-                        "content": trace_lines[-1],
+                        "content": merged_traces[-1],
                         "activitySegmentId": last.get("activitySegmentId") or segment,
                     }
+                    messages[-1] = merged
                 else:
                     messages.append(
                         {

pyproject.toml

@@ -61,6 +61,7 @@ dependencies = [
     "openpyxl>=3.1.0,<4.0.0",
     "python-pptx>=1.0.0,<2.0.0",
     "filelock>=3.25.2",
+    "keyring>=25.0.0,<26.0.0",
     "boto3>=1.43.0",
 ]
 

tests/agent/test_context_prompt_cache.py

@@ -314,8 +314,8 @@ def test_system_prompt_keeps_message_tool_out_of_current_chat_replies(tmp_path)
     prompt = builder.build_system_prompt(channel="slack")
 
     assert "Do not use the 'message' tool for normal replies in the current chat" in prompt
-    assert "the runtime attaches those artifacts to the final assistant reply automatically" in prompt
+    assert "When 'generate_image' creates images" in prompt
-    assert "do not call 'message' just to announce or resend them" in prompt
+    assert "call 'message' with the artifact paths in the 'media' parameter" in prompt
     assert "Wait for the tool results, then answer once" in prompt
 
 

tests/agent/test_loop_image_generation_media.py

@@ -29,14 +29,15 @@ class FakeImageClient:
 
 
 @pytest.mark.asyncio
-async def test_generated_image_media_is_attached_to_final_assistant_message(
+async def test_outbound_no_longer_carries_generated_media(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+    """Media delivery is now the LLM's responsibility via the message tool."""
     set_config_path(tmp_path / "config.json")
     monkeypatch.setattr(
-        "nanobot.agent.tools.image_generation.OpenRouterImageGenerationClient",
+        "nanobot.agent.tools.image_generation.get_image_gen_provider",
-        FakeImageClient,
+        lambda name: FakeImageClient if name == "openrouter" else None,
     )
     provider = MagicMock()
     provider.get_default_model.return_value = "test-model"
@@ -81,9 +82,6 @@ async def test_generated_image_media_is_attached_to_final_assistant_message(
 
     assert result is not None
     assert result.content == "Done"
-    assert len(result.media) == 1
+    # OutboundMessage no longer carries generated media —
-    assert Path(result.media[0]).is_file()
+    # the LLM sends images via the message tool instead.
-
+    assert result.media == []
-    session = loop.sessions.get_or_create("websocket:chat-image")
-    assert session.messages[-1]["role"] == "assistant"
-    assert session.messages[-1]["media"] == result.media

tests/agent/test_loop_progress.py

@@ -133,6 +133,7 @@ class TestToolEventProgress:
             "call_id": "call-write",
             "tool": "write_file",
             "path": "foo.txt",
+            "absolute_path": (tmp_path / "foo.txt").resolve().as_posix(),
             "phase": "start",
             "added": 2,
             "deleted": 1,
@@ -309,6 +310,100 @@ class TestToolEventProgress:
         await invoke_file_edit_progress(telegram_progress, edit_events)
         assert bus.outbound_size == 0
 
+    @pytest.mark.asyncio
+    async def test_goal_turn_keeps_live_file_edit_progress_for_webui(self, tmp_path: Path) -> None:
+        """The /goal command rewrites the prompt but must not bypass WebUI file-edit progress."""
+        bus = MessageBus()
+        provider = MagicMock()
+        provider.supports_progress_deltas = True
+        provider.get_default_model.return_value = "test-model"
+        call_count = 0
+        target = tmp_path / "goal.txt"
+
+        async def chat_stream_with_retry(*, on_tool_call_delta=None, **kwargs):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                assert on_tool_call_delta is not None
+                await on_tool_call_delta({
+                    "index": 0,
+                    "call_id": "call-goal-write",
+                    "name": "write_file",
+                    "arguments_delta": '{"path":"goal.txt","content":"',
+                })
+                await on_tool_call_delta({
+                    "index": 0,
+                    "arguments_delta": "one\\ntwo\\nthree\\n",
+                })
+                await on_tool_call_delta({"index": 0, "arguments_delta": '"}'})
+                return LLMResponse(
+                    content=None,
+                    tool_calls=[
+                        ToolCallRequest(
+                            id="call-goal-write",
+                            name="write_file",
+                            arguments={
+                                "path": "goal.txt",
+                                "content": "one\ntwo\nthree\n",
+                            },
+                        )
+                    ],
+                    usage={},
+                )
+            return LLMResponse(content="Done", tool_calls=[], usage={})
+
+        async def execute(name: str, params: dict) -> str:
+            assert name == "write_file"
+            target.write_text(params["content"], encoding="utf-8")
+            return "ok"
+
+        provider.chat_stream_with_retry = chat_stream_with_retry
+        provider.chat_with_retry = AsyncMock()
+        loop = AgentLoop(bus=bus, provider=provider, workspace=tmp_path, model="test-model")
+        loop.tools.get_definitions = MagicMock(return_value=[
+            {"type": "function", "function": {"name": "write_file"}},
+        ])
+        loop.tools.prepare_call = MagicMock(
+            return_value=(
+                None,
+                {"path": "goal.txt", "content": "one\ntwo\nthree\n"},
+                None,
+            ),
+        )
+        loop.tools.execute = AsyncMock(side_effect=execute)
+        loop.consolidator.maybe_consolidate_by_tokens = AsyncMock(return_value=False)  # type: ignore[method-assign]
+
+        await loop._dispatch(InboundMessage(
+            channel="websocket",
+            sender_id="u1",
+            chat_id="chat1",
+            content="/goal create goal file",
+            metadata={"_wants_stream": True},
+        ))
+
+        outbound = []
+        while bus.outbound_size > 0:
+            outbound.append(await bus.consume_outbound())
+
+        edit_events = [
+            event
+            for msg in outbound
+            for event in msg.metadata.get("_file_edit_events", [])
+        ]
+        assert any(
+            event["status"] == "editing"
+            and event["approximate"]
+            and event["added"] == 3
+            for event in edit_events
+        )
+        assert any(
+            event["status"] == "done"
+            and not event["approximate"]
+            and event["added"] == 3
+            for event in edit_events
+        )
+        provider.chat_with_retry.assert_not_awaited()
+
     @pytest.mark.asyncio
     async def test_non_streaming_channel_does_not_publish_codex_progress_deltas(
         self,
@@ -556,7 +651,7 @@ class TestToolEventProgress:
             return False
 
         monkeypatch.setattr(
-            "nanobot.utils.webui_turn_helpers.maybe_generate_webui_title_after_turn",
+            "nanobot.session.webui_turns.maybe_generate_webui_title_after_turn",
             fake_title_after_turn,
         )
         scheduled_title: list[object] = []
@@ -603,7 +698,7 @@ class TestToolEventProgress:
             raise AssertionError("command-only turns should not generate titles")
 
         monkeypatch.setattr(
-            "nanobot.utils.webui_turn_helpers.maybe_generate_webui_title_after_turn",
+            "nanobot.session.webui_turns.maybe_generate_webui_title_after_turn",
             fake_title_after_turn,
         )
         scheduled: list[object] = []

tests/agent/test_loop_save_turn.py

@@ -11,7 +11,7 @@ from nanobot.bus.queue import MessageBus
 from nanobot.providers.base import LLMResponse
 from nanobot.session.goal_state import GOAL_STATE_KEY
 from nanobot.session.manager import Session, SessionManager
-from nanobot.utils.webui_turn_helpers import (
+from nanobot.session.webui_turns import (
     TITLE_GENERATION_MAX_TOKENS,
     TITLE_GENERATION_REASONING_EFFORT,
     WEBUI_SESSION_METADATA_KEY,
@@ -143,7 +143,7 @@ def test_webui_title_update_uses_captured_llm_runtime(
         return False
 
     monkeypatch.setattr(
-        "nanobot.utils.webui_turn_helpers.maybe_generate_webui_title_after_turn",
+        "nanobot.session.webui_turns.maybe_generate_webui_title_after_turn",
         fake_title_after_turn,
     )
     coordinator = WebuiTurnCoordinator(

tests/agent/test_runner_progress_deltas.py

@@ -6,7 +6,7 @@ import pytest
 
 from nanobot.agent.runner import AgentRunner, AgentRunSpec
 from nanobot.config.schema import AgentDefaults
-from nanobot.providers.base import LLMResponse
+from nanobot.providers.base import LLMResponse, ToolCallRequest
 
 _MAX_TOOL_RESULT_CHARS = AgentDefaults().max_tool_result_chars
 
@@ -77,3 +77,220 @@ async def test_runner_streams_provider_progress_deltas_by_default():
     assert result.final_content == "hello"
     assert [call.args[0] for call in progress_cb.await_args_list] == ["he", "llo"]
     provider.chat_with_retry.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_runner_streams_live_write_file_activity_from_tool_argument_deltas(tmp_path):
+    provider = MagicMock()
+    provider.supports_progress_deltas = True
+    call_count = 0
+    progress_events: list[dict] = []
+
+    async def progress_cb(content, *, file_edit_events=None, **kwargs):
+        if file_edit_events:
+            progress_events.extend(file_edit_events)
+
+    class Tools:
+        def get_definitions(self):
+            return [{"type": "function", "function": {"name": "write_file"}}]
+
+        def get(self, name):
+            return None
+
+        async def execute(self, name, params):
+            assert name == "write_file"
+            assert any(event["approximate"] and event["added"] == 24 for event in progress_events)
+            target = tmp_path / params["path"]
+            target.write_text(params["content"], encoding="utf-8")
+            return "ok"
+
+    async def chat_stream_with_retry(*, on_tool_call_delta=None, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            assert on_tool_call_delta is not None
+            await on_tool_call_delta({
+                "index": 0,
+                "call_id": "call-write",
+                "name": "write_file",
+                "arguments_delta": '{"path":"big.txt","content":"',
+            })
+            await on_tool_call_delta({"index": 0, "arguments_delta": "line\\n" * 24})
+            return LLMResponse(
+                content=None,
+                tool_calls=[
+                    ToolCallRequest(
+                        id="call-write",
+                        name="write_file",
+                        arguments={"path": "big.txt", "content": "line\n" * 24},
+                    )
+                ],
+                usage={},
+            )
+        return LLMResponse(content="done", tool_calls=[], usage={})
+
+    provider.chat_stream_with_retry = chat_stream_with_retry
+    provider.chat_with_retry = AsyncMock()
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "write a large file"}],
+        tools=Tools(),
+        model="test-model",
+        max_iterations=2,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        progress_callback=progress_cb,
+        workspace=tmp_path,
+    ))
+
+    assert result.final_content == "done"
+    assert any(event["approximate"] and event["added"] == 24 for event in progress_events)
+    assert any(
+        not event["approximate"] and event["phase"] == "end" and event["added"] == 24
+        for event in progress_events
+    )
+    provider.chat_with_retry.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_runner_streams_live_edit_file_activity_from_tool_argument_deltas(tmp_path):
+    provider = MagicMock()
+    provider.supports_progress_deltas = True
+    call_count = 0
+    progress_events: list[dict] = []
+    target = tmp_path / "notes.txt"
+    target.write_text("old\nkeep\n", encoding="utf-8")
+
+    async def progress_cb(content, *, file_edit_events=None, **kwargs):
+        if file_edit_events:
+            progress_events.extend(file_edit_events)
+
+    class Tools:
+        def get_definitions(self):
+            return [{"type": "function", "function": {"name": "edit_file"}}]
+
+        def get(self, name):
+            return None
+
+        async def execute(self, name, params):
+            assert name == "edit_file"
+            assert any(
+                event["tool"] == "edit_file"
+                and event["approximate"]
+                and event["added"] == 3
+                and event["deleted"] == 2
+                for event in progress_events
+            )
+            target.write_text(params["new_text"], encoding="utf-8")
+            return "ok"
+
+    async def chat_stream_with_retry(*, on_tool_call_delta=None, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            assert on_tool_call_delta is not None
+            await on_tool_call_delta({
+                "index": 0,
+                "call_id": "call-edit",
+                "name": "edit_file",
+                "arguments_delta": (
+                    '{"path":"notes.txt","old_text":"old\\nkeep\\n","new_text":"'
+                ),
+            })
+            await on_tool_call_delta({
+                "index": 0,
+                "arguments_delta": "new\\nkeep\\nextra\\n",
+            })
+            await on_tool_call_delta({"index": 0, "arguments_delta": '"}'})
+            return LLMResponse(
+                content=None,
+                tool_calls=[
+                    ToolCallRequest(
+                        id="call-edit",
+                        name="edit_file",
+                        arguments={
+                            "path": "notes.txt",
+                            "old_text": "old\nkeep\n",
+                            "new_text": "new\nkeep\nextra\n",
+                        },
+                    )
+                ],
+                usage={},
+            )
+        return LLMResponse(content="done", tool_calls=[], usage={})
+
+    provider.chat_stream_with_retry = chat_stream_with_retry
+    provider.chat_with_retry = AsyncMock()
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "edit a file"}],
+        tools=Tools(),
+        model="test-model",
+        max_iterations=2,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        progress_callback=progress_cb,
+        workspace=tmp_path,
+    ))
+
+    assert result.final_content == "done"
+    assert any(
+        event["tool"] == "edit_file"
+        and event["approximate"]
+        and event["added"] == 3
+        and event["deleted"] == 2
+        for event in progress_events
+    )
+    assert any(
+        event["tool"] == "edit_file"
+        and not event["approximate"]
+        and event["phase"] == "end"
+        and event["added"] == 2
+        and event["deleted"] == 1
+        for event in progress_events
+    )
+    provider.chat_with_retry.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_runner_marks_unfinished_live_write_file_activity_failed(tmp_path):
+    provider = MagicMock()
+    provider.supports_progress_deltas = True
+    progress_events: list[dict] = []
+
+    async def progress_cb(content, *, file_edit_events=None, **kwargs):
+        if file_edit_events:
+            progress_events.extend(file_edit_events)
+
+    async def chat_stream_with_retry(*, on_tool_call_delta=None, **kwargs):
+        assert on_tool_call_delta is not None
+        await on_tool_call_delta({
+            "index": 0,
+            "call_id": "call-write",
+            "name": "write_file",
+            "arguments_delta": '{"path":"aborted.txt","content":"partial\\n',
+        })
+        return LLMResponse(content="stopped", tool_calls=[], finish_reason="stop", usage={})
+
+    provider.chat_stream_with_retry = chat_stream_with_retry
+    provider.chat_with_retry = AsyncMock()
+    tools = MagicMock()
+    tools.get_definitions.return_value = [{"type": "function", "function": {"name": "write_file"}}]
+    tools.get.return_value = None
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "write a large file"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=1,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        progress_callback=progress_cb,
+        workspace=tmp_path,
+    ))
+
+    assert result.final_content == "stopped"
+    assert progress_events[-1]["path"] == "aborted.txt"
+    assert progress_events[-1]["phase"] == "error"
+    assert progress_events[-1]["status"] == "error"
+    provider.chat_with_retry.assert_not_awaited()

tests/agent/test_session_media_persist.py

@@ -1,34 +0,0 @@
-"""Tests for staging attachment paths into the media bucket for session replay."""
-
-from pathlib import Path
-
-from nanobot.config.loader import set_config_path
-from nanobot.config.paths import get_media_dir
-from nanobot.utils.session_attachments import stage_media_paths_for_session_replay
-
-
-def test_persist_media_stages_workspace_file(tmp_path: Path) -> None:
-    set_config_path(tmp_path / "config.json")
-    outside = tmp_path / "workspace" / "report.md"
-    outside.parent.mkdir(parents=True)
-    outside.write_text("body", encoding="utf-8")
-
-    out = stage_media_paths_for_session_replay([str(outside)])
-
-    assert len(out) == 1
-    staged = Path(out[0])
-    assert staged.is_file()
-    assert staged.read_text(encoding="utf-8") == "body"
-    assert staged.resolve().is_relative_to(get_media_dir().resolve())
-
-
-def test_persist_media_keeps_files_already_under_media_root(tmp_path: Path) -> None:
-    set_config_path(tmp_path / "config.json")
-    media = get_media_dir("websocket")
-    media.mkdir(parents=True, exist_ok=True)
-    inside = media / "keep-me.txt"
-    inside.write_text("x", encoding="utf-8")
-
-    out = stage_media_paths_for_session_replay([str(inside.resolve())])
-
-    assert out == [str(inside.resolve())]

tests/channels/test_channel_plugins.py

@@ -111,6 +111,23 @@ def test_discover_plugins_loads_entry_points():
     assert result["line"] is _FakePlugin
 
 
+def test_discover_plugins_skips_names_outside_enabled_set():
+    from nanobot.channels.registry import discover_plugins
+
+    loaded: list[str] = []
+
+    def _load_disabled():
+        loaded.append("disabled")
+        return _FakePlugin
+
+    ep = SimpleNamespace(name="disabled", load=_load_disabled)
+    with patch(_EP_TARGET, return_value=[ep]):
+        result = discover_plugins({"enabled"})
+
+    assert result == {}
+    assert loaded == []
+
+
 def test_discover_plugins_handles_load_error():
     from nanobot.channels.registry import discover_plugins
 
@@ -152,6 +169,25 @@ def test_discover_all_includes_external_plugin():
     assert result["line"] is _FakePlugin
 
 
+def test_discover_enabled_imports_only_enabled_builtins():
+    from nanobot.channels.registry import discover_enabled
+
+    loaded: list[str] = []
+
+    def _load_channel(name: str):
+        loaded.append(name)
+        return _FakePlugin
+
+    with (
+        patch("nanobot.channels.registry.load_channel_class", side_effect=_load_channel),
+        patch(_EP_TARGET, return_value=[]),
+    ):
+        result = discover_enabled({"enabled"}, _names=["enabled", "disabled"])
+
+    assert result == {"enabled": _FakePlugin}
+    assert loaded == ["enabled"]
+
+
 def test_discover_all_builtin_shadows_plugin():
     from nanobot.channels.registry import discover_all
 
@@ -180,7 +216,7 @@ async def test_manager_loads_plugin_from_dict_config():
     )
 
     with patch(
-        "nanobot.channels.registry.discover_all",
+        "nanobot.channels.registry.discover_enabled",
         return_value={"fakeplugin": _FakePlugin},
     ):
         mgr = ChannelManager.__new__(ChannelManager)
@@ -210,7 +246,7 @@ async def test_manager_propagates_groq_transcription_api_base_to_channels():
     )
 
     with patch(
-        "nanobot.channels.registry.discover_all",
+        "nanobot.channels.registry.discover_enabled",
         return_value={"fakeplugin": _FakePlugin},
     ):
         mgr = ChannelManager.__new__(ChannelManager)
@@ -246,7 +282,7 @@ async def test_manager_propagates_openai_transcription_api_base_to_channels():
     )
 
     with patch(
-        "nanobot.channels.registry.discover_all",
+        "nanobot.channels.registry.discover_enabled",
         return_value={"fakeplugin": _FakePlugin},
     ):
         mgr = ChannelManager.__new__(ChannelManager)
@@ -498,10 +534,8 @@ async def test_manager_skips_disabled_plugin():
         providers=SimpleNamespace(groq=SimpleNamespace(api_key="")),
     )
 
-    with patch(
+    ep = _make_entry_point("fakeplugin", _FakePlugin)
-        "nanobot.channels.registry.discover_all",
+    with patch(_EP_TARGET, return_value=[ep]):
-        return_value={"fakeplugin": _FakePlugin},
-    ):
         mgr = ChannelManager.__new__(ChannelManager)
         mgr.config = fake_config
         mgr.bus = MessageBus()

tests/channels/test_signal_markdown.py

@@ -1,525 +0,0 @@
-"""Unit tests for the Signal markdown → plain text + textStyle converter."""
-
-from nanobot.channels.signal import _markdown_to_signal, _partition_styles
-from nanobot.utils.helpers import split_message
-
-
-def _utf16_len(s: str) -> int:
-    return len(s.encode("utf-16-le")) // 2
-
-
-def styles_for(plain: str, text_styles: list[str]) -> dict[str, list[str]]:
-    """Return a dict mapping each styled substring to its style list."""
-    result: dict[str, list[str]] = {}
-    for entry in text_styles:
-        start_s, length_s, style = entry.split(":", 2)
-        start, length = int(start_s), int(length_s)
-        span = plain[start : start + length]
-        result.setdefault(span, []).append(style)
-    return result
-
-
-def utf16_styles_for(plain: str, text_styles: list[str]) -> dict[str, list[str]]:
-    """Like styles_for, but slices `plain` using UTF-16 offsets (Signal's units)."""
-    encoded = plain.encode("utf-16-le")
-    result: dict[str, list[str]] = {}
-    for entry in text_styles:
-        start_s, length_s, style = entry.split(":", 2)
-        start, length = int(start_s), int(length_s)
-        span = encoded[start * 2 : (start + length) * 2].decode("utf-16-le")
-        result.setdefault(span, []).append(style)
-    return result
-
-
-# ---------------------------------------------------------------------------
-# Basic cases
-# ---------------------------------------------------------------------------
-
-
-def test_empty():
-    plain, styles = _markdown_to_signal("")
-    assert plain == ""
-    assert styles == []
-
-
-def test_plain_text():
-    plain, styles = _markdown_to_signal("hello world")
-    assert plain == "hello world"
-    assert styles == []
-
-
-def test_bold_stars():
-    plain, styles = _markdown_to_signal("say **hello** now")
-    assert plain == "say hello now"
-    assert styles_for(plain, styles) == {"hello": ["BOLD"]}
-
-
-def test_bold_underscores():
-    plain, styles = _markdown_to_signal("say __hello__ now")
-    assert plain == "say hello now"
-    assert styles_for(plain, styles) == {"hello": ["BOLD"]}
-
-
-def test_italic_star():
-    plain, styles = _markdown_to_signal("say *hello* now")
-    assert plain == "say hello now"
-    assert styles_for(plain, styles) == {"hello": ["ITALIC"]}
-
-
-def test_italic_underscore():
-    plain, styles = _markdown_to_signal("say _hello_ now")
-    assert plain == "say hello now"
-    assert styles_for(plain, styles) == {"hello": ["ITALIC"]}
-
-
-def test_strikethrough():
-    plain, styles = _markdown_to_signal("say ~~hello~~ now")
-    assert plain == "say hello now"
-    assert styles_for(plain, styles) == {"hello": ["STRIKETHROUGH"]}
-
-
-# ---------------------------------------------------------------------------
-# Code
-# ---------------------------------------------------------------------------
-
-
-def test_inline_code():
-    plain, styles = _markdown_to_signal("run `ls -la` here")
-    assert plain == "run ls -la here"
-    assert styles_for(plain, styles) == {"ls -la": ["MONOSPACE"]}
-
-
-def test_code_block():
-    plain, styles = _markdown_to_signal("```\nprint('hi')\n```")
-    assert "print('hi')" in plain
-    assert styles_for(plain, styles).get("print('hi')\n") == ["MONOSPACE"] or "MONOSPACE" in str(
-        styles_for(plain, styles)
-    )
-
-
-def test_code_block_with_lang():
-    plain, styles = _markdown_to_signal("```python\ncode\n```")
-    assert "code" in plain
-    assert any("MONOSPACE" in s for s in styles)
-
-
-def test_code_block_not_processed_further():
-    """Markdown inside a code block must not be styled."""
-    plain, styles = _markdown_to_signal("```\n**not bold**\n```")
-    assert "**not bold**" in plain
-    # Only MONOSPACE should be applied, no BOLD
-    for entry in styles:
-        assert "BOLD" not in entry
-
-
-def test_inline_code_not_processed_further():
-    """Markdown inside inline code must not be styled."""
-    plain, styles = _markdown_to_signal("use `**raw**` please")
-    assert "**raw**" in plain
-    for entry in styles:
-        assert "BOLD" not in entry
-
-
-# ---------------------------------------------------------------------------
-# Headers
-# ---------------------------------------------------------------------------
-
-
-def test_header_becomes_bold():
-    plain, styles = _markdown_to_signal("# My Title")
-    assert plain == "My Title"
-    assert styles_for(plain, styles) == {"My Title": ["BOLD"]}
-
-
-def test_h2_becomes_bold():
-    plain, styles = _markdown_to_signal("## Sub-section")
-    assert plain == "Sub-section"
-    assert styles_for(plain, styles) == {"Sub-section": ["BOLD"]}
-
-
-# ---------------------------------------------------------------------------
-# Blockquotes
-# ---------------------------------------------------------------------------
-
-
-def test_blockquote_strips_marker():
-    plain, styles = _markdown_to_signal("> some quote")
-    assert plain == "some quote"
-    assert styles == []
-
-
-# ---------------------------------------------------------------------------
-# Lists
-# ---------------------------------------------------------------------------
-
-
-def test_bullet_dash():
-    plain, styles = _markdown_to_signal("- item one")
-    assert plain == "• item one"
-
-
-def test_bullet_star():
-    plain, styles = _markdown_to_signal("* item two")
-    assert plain == "• item two"
-
-
-def test_numbered_list():
-    plain, styles = _markdown_to_signal("1. first\n2. second")
-    assert "1. first" in plain
-    assert "2. second" in plain
-
-
-# ---------------------------------------------------------------------------
-# Links
-# ---------------------------------------------------------------------------
-
-
-def test_link_text_differs_from_url():
-    plain, styles = _markdown_to_signal("[Click here](https://example.com)")
-    assert plain == "Click here (https://example.com)"
-    assert styles == []
-
-
-def test_link_text_equals_url():
-    plain, styles = _markdown_to_signal("[https://example.com](https://example.com)")
-    assert plain == "https://example.com"
-    assert styles == []
-
-
-def test_link_text_equals_url_without_scheme():
-    plain, styles = _markdown_to_signal("[example.com](https://example.com)")
-    assert plain == "https://example.com"
-
-
-# ---------------------------------------------------------------------------
-# Mixed / nesting
-# ---------------------------------------------------------------------------
-
-
-def test_bold_and_italic_adjacent():
-    plain, styles = _markdown_to_signal("**bold** and *italic*")
-    assert plain == "bold and italic"
-    sd = styles_for(plain, styles)
-    assert sd.get("bold") == ["BOLD"]
-    assert sd.get("italic") == ["ITALIC"]
-
-
-def test_header_with_inline_code():
-    """Header becomes BOLD; code inside becomes MONOSPACE (not double-BOLD)."""
-    plain, styles = _markdown_to_signal("# Use `grep`")
-    assert plain == "Use grep"
-    sd = styles_for(plain, styles)
-    assert "BOLD" in sd.get("Use ", []) or "BOLD" in str(styles)
-    assert "MONOSPACE" in sd.get("grep", [])
-
-
-def test_multiline_mixed():
-    md = "**Title**\n\nSome *italic* text.\n\n- bullet\n- another"
-    plain, styles = _markdown_to_signal(md)
-    assert "Title" in plain
-    assert "italic" in plain
-    assert "• bullet" in plain
-    sd = styles_for(plain, styles)
-    assert "BOLD" in sd.get("Title", [])
-    assert "ITALIC" in sd.get("italic", [])
-
-
-# ---------------------------------------------------------------------------
-# Table rendering
-# ---------------------------------------------------------------------------
-
-
-def test_table_rendered_as_monospace():
-    md = "| A | B |\n| - | - |\n| 1 | 2 |"
-    plain, styles = _markdown_to_signal(md)
-    assert "A" in plain and "B" in plain
-    assert any("MONOSPACE" in s for s in styles)
-
-
-# ---------------------------------------------------------------------------
-# Style range format
-# ---------------------------------------------------------------------------
-
-
-def test_style_range_format():
-    """Each style entry must be 'start:length:STYLE'."""
-    _, styles = _markdown_to_signal("**bold** text")
-    for entry in styles:
-        parts = entry.split(":")
-        assert len(parts) == 3
-        assert parts[0].isdigit()
-        assert parts[1].isdigit()
-        assert parts[2] in {"BOLD", "ITALIC", "STRIKETHROUGH", "MONOSPACE", "SPOILER"}
-
-
-def test_style_ranges_are_within_bounds():
-    text = "hello **world** end"
-    plain, styles = _markdown_to_signal(text)
-    for entry in styles:
-        start_s, length_s, _ = entry.split(":", 2)
-        start, length = int(start_s), int(length_s)
-        assert start >= 0
-        assert start + length <= len(plain)
-
-
-# ---------------------------------------------------------------------------
-# Non-BMP / UTF-16 offsets
-#
-# Signal's BodyRange (and signal-cli's textStyle) interprets start/length in
-# UTF-16 code units. Python's len() counts code points, so characters outside
-# the BMP (emojis, supplementary CJK) shift offsets by +1 per occurrence.
-# ---------------------------------------------------------------------------
-
-
-def assert_within_utf16_bounds(plain: str, styles: list[str]) -> None:
-    limit = _utf16_len(plain)
-    for entry in styles:
-        start_s, length_s, _ = entry.split(":", 2)
-        start, length = int(start_s), int(length_s)
-        assert start >= 0
-        assert start + length <= limit, f"range {entry} exceeds utf-16 length {limit} of {plain!r}"
-
-
-def test_bold_with_emoji_inside():
-    plain, styles = _markdown_to_signal("**hi 🎉 bye**")
-    assert plain == "hi 🎉 bye"
-    assert utf16_styles_for(plain, styles) == {"hi 🎉 bye": ["BOLD"]}
-    assert_within_utf16_bounds(plain, styles)
-
-
-def test_italic_with_trailing_emoji():
-    plain, styles = _markdown_to_signal("*bye 🎉*")
-    assert plain == "bye 🎉"
-    assert utf16_styles_for(plain, styles) == {"bye 🎉": ["ITALIC"]}
-    assert_within_utf16_bounds(plain, styles)
-
-
-def test_bold_after_emoji_prefix():
-    plain, styles = _markdown_to_signal("🎉 **bold**")
-    assert plain == "🎉 bold"
-    assert utf16_styles_for(plain, styles) == {"bold": ["BOLD"]}
-    assert_within_utf16_bounds(plain, styles)
-
-
-def test_bold_after_and_inside_emoji():
-    plain, styles = _markdown_to_signal("🎉 **a 🎊 b**")
-    assert plain == "🎉 a 🎊 b"
-    assert utf16_styles_for(plain, styles) == {"a 🎊 b": ["BOLD"]}
-    assert_within_utf16_bounds(plain, styles)
-
-
-def test_supplementary_cjk_in_bold():
-    """Non-BMP CJK (U+20BB7) proves the bug is UTF-16, not emoji-specific."""
-    plain, styles = _markdown_to_signal("**𠮷野家**")
-    assert plain == "𠮷野家"
-    assert utf16_styles_for(plain, styles) == {"𠮷野家": ["BOLD"]}
-    assert_within_utf16_bounds(plain, styles)
-
-
-def test_zwj_emoji_in_bold():
-    """ZWJ family sequence = multiple surrogate pairs + BMP ZWJs."""
-    plain, styles = _markdown_to_signal("**hi 👨‍👩‍👧 bye**")
-    assert plain == "hi 👨‍👩‍👧 bye"
-    assert utf16_styles_for(plain, styles) == {"hi 👨‍👩‍👧 bye": ["BOLD"]}
-    assert_within_utf16_bounds(plain, styles)
-
-
-def test_ascii_offsets_unchanged():
-    """ASCII-only path must produce the same offsets as before the UTF-16 fix."""
-    plain, styles = _markdown_to_signal("**bold** plain *it*")
-    assert plain == "bold plain it"
-    assert sorted(styles) == sorted(["0:4:BOLD", "11:2:ITALIC"])
-
-
-def test_reported_daily_brief_pattern():
-    """Regression for the reported bug: a single non-BMP emoji shifts every
-    subsequent styled span left by 1 UTF-16 unit, lopping off the last letter.
-    """
-    md = (
-        "**Weather**\n"
-        "- Conditions: 🌩️ Thunderstorms\n\n"
-        "**News**\n"
-        "*World*\n"
-        "*Local*\n\n"
-        "**Quote of the Day**"
-    )
-    plain, styles = _markdown_to_signal(md)
-    sd = utf16_styles_for(plain, styles)
-    assert sd.get("Weather") == ["BOLD"]
-    assert sd.get("News") == ["BOLD"]
-    assert sd.get("World") == ["ITALIC"]
-    assert sd.get("Local") == ["ITALIC"]
-    assert sd.get("Quote of the Day") == ["BOLD"]
-    assert_within_utf16_bounds(plain, styles)
-
-
-# ---------------------------------------------------------------------------
-# Chunk redistribution
-#
-# split_message can break a long Signal payload into multiple chunks. The
-# style ranges from _markdown_to_signal are anchored to the full text, so
-# they must be redistributed per-chunk with rebased offsets — otherwise
-# styles for chunks 1..N are silently lost.
-# ---------------------------------------------------------------------------
-
-
-def _resolve_chunk_styles(text: str, max_len: int) -> tuple[list[str], list[list[str]]]:
-    """Helper: full markdown → signal pipeline, including chunking."""
-    plain, styles = _markdown_to_signal(text)
-    chunks = split_message(plain, max_len) if plain else [""]
-    return chunks, _partition_styles(plain, chunks, styles)
-
-
-def test_partition_styles_single_chunk_passthrough():
-    plain, styles = _markdown_to_signal("**bold** plain *it*")
-    parts = _partition_styles(plain, [plain], styles)
-    assert parts == [styles]
-
-
-def test_partition_styles_no_styles():
-    plain = "hello world"
-    assert _partition_styles(plain, [plain], []) == [[]]
-    assert _partition_styles(plain, ["hello", "world"], []) == [[], []]
-
-
-def test_partition_styles_drops_styles_outside_chunks():
-    """Whitespace trimmed by split_message must not carry a style range."""
-    plain = "a   b"
-    # Fake a style spanning the trimmed whitespace only.
-    chunks = ["a", "b"]
-    parts = _partition_styles(plain, chunks, ["1:3:BOLD"])
-    assert parts == [[], []]
-
-
-def test_partition_styles_long_message_preserves_chunk_one_styles():
-    """A bold span deep in the message must follow the message into chunk 1."""
-    # Two ~30-char paragraphs separated by a blank line, then **tail**.
-    line_a = "alpha " * 5  # 30 chars, ends with space
-    line_b = "beta " * 5
-    md = f"{line_a.strip()}\n\n{line_b.strip()}\n\n**tail**"
-    plain, styles = _markdown_to_signal(md)
-    # Force a split between the paragraphs.
-    max_len = len(line_a.strip()) + 2  # fits paragraph A + the "\n\n"
-    chunks = split_message(plain, max_len)
-    assert len(chunks) >= 2, "test setup must produce a split"
-    parts = _partition_styles(plain, chunks, styles)
-    # The bold "tail" should land in the last chunk, with chunk-relative offset.
-    final_chunk = chunks[-1]
-    final_styles = parts[-1]
-    assert any("BOLD" in s for s in final_styles)
-    for entry in final_styles:
-        s, ln, _ = entry.split(":", 2)
-        start, length = int(s), int(ln)
-        slice_ = final_chunk.encode("utf-16-le")[start * 2 : (start + length) * 2].decode(
-            "utf-16-le"
-        )
-        assert slice_ == "tail"
-
-
-def test_partition_styles_chunk_zero_styles_unchanged():
-    """Styles entirely in chunk 0 keep their original offsets."""
-    md = "**head** middle and **tail**"
-    plain, styles = _markdown_to_signal(md)
-    # Split so chunk 0 contains "head" and part of the rest, chunk 1 contains "tail".
-    chunks = split_message(plain, 12)
-    assert len(chunks) >= 2
-    parts = _partition_styles(plain, chunks, styles)
-    # "head" lives in chunk 0; assert its offset is unchanged (chunk 0 starts at 0).
-    head_entries = [s for s in parts[0] if "BOLD" in s]
-    assert any(s.startswith("0:4:") for s in head_entries)
-
-
-def test_partition_styles_with_non_bmp_chunk_offset():
-    """Chunk-start offsets must be expressed in UTF-16 code units."""
-    # Emoji in chunk 0, bold in chunk 1.
-    md = "🎉 alpha beta gamma\n\n**tail**"
-    plain, styles = _markdown_to_signal(md)
-    chunks = split_message(plain, 18)
-    assert len(chunks) >= 2
-    parts = _partition_styles(plain, chunks, styles)
-    final_styles = parts[-1]
-    assert any("BOLD" in s for s in final_styles)
-    final_chunk = chunks[-1]
-    for entry in final_styles:
-        s, ln, _ = entry.split(":", 2)
-        start, length = int(s), int(ln)
-        slice_ = final_chunk.encode("utf-16-le")[start * 2 : (start + length) * 2].decode(
-            "utf-16-le"
-        )
-        assert slice_ == "tail"
-
-
-def test_partition_styles_range_spanning_chunks_is_split():
-    """A style range that straddles a chunk boundary gets sliced into both chunks."""
-    # Construct manually: plain = "abc def", style covers "abc def" (whole thing).
-    plain = "abc def"
-    chunks = split_message(plain, 4)  # "abc" / "def"
-    assert chunks == ["abc", "def"]
-    parts = _partition_styles(plain, chunks, ["0:7:BOLD"])
-    # Chunk 0 holds 0:3:BOLD, chunk 1 holds 0:3:BOLD (length=3 each, "def" only
-    # since the space was trimmed by lstrip).
-    assert parts[0] == ["0:3:BOLD"]
-    assert parts[1] == ["0:3:BOLD"]
-
-
-# ---------------------------------------------------------------------------
-# Adjacency, nesting, and malformed input
-# ---------------------------------------------------------------------------
-
-
-def test_bold_italic_combo_outer_bold_inner_italic():
-    """`**_combo_**` carries both BOLD and ITALIC over the same span."""
-    plain, styles = _markdown_to_signal("**_combo_**")
-    assert plain == "combo"
-    sd = styles_for(plain, styles)
-    assert set(sd.get("combo", [])) == {"BOLD", "ITALIC"}
-
-
-def test_bold_and_italic_adjacent_no_separator():
-    """`**bold***italic*` produces BOLD on `bold` and ITALIC on `italic`."""
-    plain, styles = _markdown_to_signal("**bold***italic*")
-    assert plain == "bolditalic"
-    sd = styles_for(plain, styles)
-    assert sd.get("bold") == ["BOLD"]
-    assert sd.get("italic") == ["ITALIC"]
-
-
-def test_unclosed_bold_falls_through_as_plain():
-    """An unmatched `**` opener round-trips as literal text with no style."""
-    plain, styles = _markdown_to_signal("**bold")
-    assert plain == "**bold"
-    assert styles == []
-
-
-def test_unclosed_inline_code_falls_through_as_plain():
-    """An unmatched backtick round-trips as literal text with no style."""
-    plain, styles = _markdown_to_signal("use `grep")
-    assert plain == "use `grep"
-    assert styles == []
-
-
-def test_inline_code_inside_blockquote():
-    """Blockquote prefix is stripped; inline code becomes MONOSPACE."""
-    plain, styles = _markdown_to_signal("> use `grep`")
-    assert plain == "use grep"
-    sd = styles_for(plain, styles)
-    assert sd.get("grep") == ["MONOSPACE"]
-
-
-def test_header_with_inner_bold_produces_contiguous_bold_ranges():
-    """`# **wrap** me` — header forces BOLD over the whole line; the inner `**`
-    splits the run, yielding two contiguous BOLD ranges that together cover
-    "wrap me". This is intentional — Signal renders adjacent same-style ranges
-    as a single visual span.
-    """
-    plain, styles = _markdown_to_signal("# **wrap** me")
-    assert plain == "wrap me"
-    # Both ranges are BOLD; collectively they cover the whole "wrap me".
-    bold_ranges = [s for s in styles if s.endswith(":BOLD")]
-    assert len(bold_ranges) == 2
-    covered = set()
-    for entry in bold_ranges:
-        start, length, _ = entry.split(":", 2)
-        for i in range(int(start), int(start) + int(length)):
-            covered.add(i)
-    assert covered == set(range(len(plain)))

tests/channels/test_websocket_channel.py

@@ -29,7 +29,8 @@ from nanobot.channels.websocket import (
     publish_runtime_model_update,
 )
 from nanobot.config.loader import load_config, save_config
-from nanobot.config.schema import Config
+from nanobot.config.schema import Config, ModelPresetConfig
+from nanobot.webui.settings_api import settings_payload
 
 # -- Shared helpers (aligned with test_websocket_integration.py) ---------------
 
@@ -756,7 +757,7 @@ async def test_maybe_push_turn_run_wall_clock_skips_when_no_active_turn() -> Non
     channel = WebSocketChannel({"enabled": True, "allowFrom": ["*"]}, bus)
     mock_ws = AsyncMock()
     channel._attach(mock_ws, "chat-1")
-    from nanobot.utils import webui_turn_helpers as wth
+    from nanobot.session import webui_turns as wth
 
     wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
     await channel._maybe_push_turn_run_wall_clock("chat-1")
@@ -769,7 +770,7 @@ async def test_maybe_push_turn_run_wall_clock_replays_running() -> None:
     channel = WebSocketChannel({"enabled": True, "allowFrom": ["*"]}, bus)
     mock_ws = AsyncMock()
     channel._attach(mock_ws, "chat-1")
-    from nanobot.utils import webui_turn_helpers as wth
+    from nanobot.session import webui_turns as wth
 
     wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
     try:
@@ -991,6 +992,11 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
     config = Config()
     config.agents.defaults.model = "openai/gpt-4o"
     config.providers.openai.api_key = "secret-key"
+    config.model_presets["deep"] = ModelPresetConfig(
+        model="anthropic/claude-opus-4-5",
+        provider="anthropic",
+        reasoning_effort="high",
+    )
     config.tools.web.search.provider = "brave"
     config.tools.web.search.api_key = "brave-secret"
     save_config(config, config_path)
@@ -1011,21 +1017,52 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
         body = settings.json()
         assert body["agent"]["model"] == "openai/gpt-4o"
         assert body["agent"]["provider"] == "openai"
+        assert body["agent"]["model_preset"] == "default"
+        assert body["agent"]["max_tokens"] == 8192
+        assert body["agent"]["timezone"] == "UTC"
+        assert body["agent"]["tool_hint_max_length"] == 40
+        presets = {preset["name"]: preset for preset in body["model_presets"]}
+        assert presets["default"]["active"] is True
+        assert presets["deep"]["reasoning_effort"] == "high"
         providers = {provider["name"]: provider for provider in body["providers"]}
         assert providers["openai"]["configured"] is True
         assert providers["openai"]["api_key_hint"] == "secr••••-key"
         assert providers["azure_openai"]["api_key_required"] is True
         assert providers["openrouter"]["configured"] is False
         assert providers["openrouter"]["api_key_required"] is True
+        assert providers["skywork"]["label"] == "Skywork"
+        assert providers["skywork"]["default_api_base"] == "https://api.apifree.ai/agent/v1"
+        assert providers["ant_ling"]["label"] == "Ant Ling"
+        assert providers["ant_ling"]["default_api_base"] == "https://api.ant-ling.com/v1"
         assert providers["atomic_chat"]["configured"] is False
         assert providers["atomic_chat"]["api_key_required"] is False
         assert providers["atomic_chat"]["default_api_base"] == "http://localhost:1337/v1"
         assert body["agent"]["has_api_key"] is True
         assert body["web_search"]["provider"] == "brave"
         assert body["web_search"]["api_key_hint"] == "brav••••cret"
+        assert body["web_search"]["max_results"] == 5
+        assert body["web"]["fetch"]["use_jina_reader"] is True
         search_providers = {provider["name"]: provider for provider in body["web_search"]["providers"]}
         assert search_providers["duckduckgo"]["credential"] == "none"
         assert search_providers["searxng"]["credential"] == "base_url"
+        assert body["image_generation"]["enabled"] is False
+        assert body["image_generation"]["provider"] == "openrouter"
+        assert body["image_generation"]["provider_configured"] is False
+        assert body["image_generation"]["default_aspect_ratio"] == "1:1"
+        image_providers = {
+            provider["name"]: provider
+            for provider in body["image_generation"]["providers"]
+        }
+        assert image_providers["openrouter"]["label"] == "OpenRouter"
+        assert image_providers["openrouter"]["configured"] is False
+        assert image_providers["gemini"]["label"] == "Gemini"
+        assert body["runtime"]["config_path"] == str(config_path)
+        workspace_path = body["runtime"]["workspace_path"].replace("\\", "/")
+        assert workspace_path.endswith("/.nanobot/workspace")
+        assert body["runtime"]["gateway_port"] == 18790
+        assert body["advanced"]["exec_enabled"] is True
+        assert body["advanced"]["mcp_server_count"] == 0
+        assert body["restart_required_sections"] == []
         assert "secret-key" not in settings.text
         assert "brave-secret" not in settings.text
 
@@ -1040,6 +1077,7 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
         assert provider_body["requires_restart"] is False
         provider_rows = {provider["name"]: provider for provider in provider_body["providers"]}
         assert provider_rows["openrouter"]["configured"] is True
+        assert provider_body["image_generation"]["provider_configured"] is True
         assert "sk-or-test" not in provider_updated.text
 
         local_provider_updated = await _http_get(
@@ -1059,34 +1097,117 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
         updated = await _http_get(
             "http://127.0.0.1:"
             f"{port}/api/settings/update?model=atomic_chat/test"
-            "&provider=atomic_chat",
+            "&provider=atomic_chat&timezone=Asia%2FShanghai"
+            "&bot_name=Nano&bot_icon=N&tool_hint_max_length=120",
             headers={"Authorization": "Bearer tok"},
         )
         assert updated.status_code == 200
-        assert updated.json()["requires_restart"] is False
+        updated_body = updated.json()
+        assert updated_body["requires_restart"] is True
+        assert updated_body["restart_required_sections"] == ["runtime"]
+
+        preset_updated = await _http_get(
+            "http://127.0.0.1:"
+            f"{port}/api/settings/update?model_preset=deep",
+            headers={"Authorization": "Bearer tok"},
+        )
+        assert preset_updated.status_code == 200
+        assert preset_updated.json()["agent"]["model"] == "anthropic/claude-opus-4-5"
+
+        bad_preset = await _http_get(
+            "http://127.0.0.1:"
+            f"{port}/api/settings/update?model_preset=missing",
+            headers={"Authorization": "Bearer tok"},
+        )
+        assert bad_preset.status_code == 400
 
         search_updated = await _http_get(
             "http://127.0.0.1:"
             f"{port}/api/settings/web-search/update?provider=searxng"
-            "&base_url=https%3A%2F%2Fsearch.example.com",
+            "&base_url=https%3A%2F%2Fsearch.example.com"
+            "&max_results=8&timeout=45&use_jina_reader=false",
             headers={"Authorization": "Bearer tok"},
         )
         assert search_updated.status_code == 200
         search_body = search_updated.json()
-        assert search_body["requires_restart"] is False
+        assert search_body["requires_restart"] is True
+        assert search_body["restart_required_sections"] == ["runtime", "web"]
         assert search_body["web_search"]["provider"] == "searxng"
         assert search_body["web_search"]["api_key_hint"] is None
         assert search_body["web_search"]["base_url"] == "https://search.example.com"
+        assert search_body["web_search"]["max_results"] == 8
+        assert search_body["web"]["fetch"]["use_jina_reader"] is False
+
+        image_updated = await _http_get(
+            "http://127.0.0.1:"
+            f"{port}/api/settings/image-generation/update?enabled=true"
+            "&provider=openrouter&model=openai%2Fgpt-image-1"
+            "&default_aspect_ratio=16%3A9&default_image_size=2K"
+            "&max_images_per_turn=3",
+            headers={"Authorization": "Bearer tok"},
+        )
+        assert image_updated.status_code == 200
+        image_body = image_updated.json()
+        assert image_body["requires_restart"] is True
+        assert image_body["restart_required_sections"] == ["image", "runtime", "web"]
+        assert image_body["image_generation"]["enabled"] is True
+        assert image_body["image_generation"]["model"] == "openai/gpt-image-1"
+        assert image_body["image_generation"]["default_aspect_ratio"] == "16:9"
+        assert image_body["image_generation"]["default_image_size"] == "2K"
+        assert image_body["image_generation"]["max_images_per_turn"] == 3
+
+        image_provider_updated = await _http_get(
+            "http://127.0.0.1:"
+            f"{port}/api/settings/provider/update?provider=openrouter"
+            "&api_key=sk-or-next&api_base=https%3A%2F%2Fopenrouter.ai%2Fapi%2Fv1",
+            headers={"Authorization": "Bearer tok"},
+        )
+        assert image_provider_updated.status_code == 200
+        assert image_provider_updated.json()["requires_restart"] is True
+        assert image_provider_updated.json()["restart_required_sections"] == [
+            "image",
+            "runtime",
+            "web",
+        ]
+        assert "sk-or-next" not in image_provider_updated.text
+
+        bad_web = await _http_get(
+            "http://127.0.0.1:"
+            f"{port}/api/settings/web-search/update?provider=duckduckgo&max_results=99",
+            headers={"Authorization": "Bearer tok"},
+        )
+        assert bad_web.status_code == 400
+
+        bad_image = await _http_get(
+            "http://127.0.0.1:"
+            f"{port}/api/settings/image-generation/update?provider=missing",
+            headers={"Authorization": "Bearer tok"},
+        )
+        assert bad_image.status_code == 400
 
         saved = load_config(config_path)
         assert saved.agents.defaults.model == "atomic_chat/test"
         assert saved.agents.defaults.provider == "atomic_chat"
-        assert saved.providers.openrouter.api_key == "sk-or-test"
+        assert saved.agents.defaults.model_preset == "deep"
+        assert saved.agents.defaults.timezone == "Asia/Shanghai"
+        assert saved.agents.defaults.bot_name == "Nano"
+        assert saved.agents.defaults.bot_icon == "N"
+        assert saved.agents.defaults.tool_hint_max_length == 120
+        assert saved.providers.openrouter.api_key == "sk-or-next"
         assert saved.providers.openrouter.api_base == "https://openrouter.ai/api/v1"
         assert saved.providers.atomic_chat.api_base == "http://localhost:1337/v1"
         assert saved.tools.web.search.provider == "searxng"
         assert saved.tools.web.search.api_key == ""
         assert saved.tools.web.search.base_url == "https://search.example.com"
+        assert saved.tools.web.search.max_results == 8
+        assert saved.tools.web.search.timeout == 45
+        assert saved.tools.web.fetch.use_jina_reader is False
+        assert saved.tools.image_generation.enabled is True
+        assert saved.tools.image_generation.provider == "openrouter"
+        assert saved.tools.image_generation.model == "openai/gpt-image-1"
+        assert saved.tools.image_generation.default_aspect_ratio == "16:9"
+        assert saved.tools.image_generation.default_image_size == "2K"
+        assert saved.tools.image_generation.max_images_per_turn == 3
     finally:
         await channel.stop()
         await server_task
@@ -1131,7 +1252,7 @@ def test_settings_payload_normalizes_camel_case_provider(
     save_config(config, config_path)
     monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
 
-    body = _ch(bus)._settings_payload()
+    body = settings_payload()
 
     assert body["agent"]["provider"] == "minimax_anthropic"
 
@@ -1548,6 +1669,54 @@ def test_parse_envelope_rejects_legacy_and_garbage() -> None:
     assert _parse_envelope('{"type":123}') is None
 
 
+def test_sessions_list_includes_active_run_started_at() -> None:
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.session import webui_turns as wth
+
+    bus = MagicMock()
+    channel = _ch(bus)
+    channel._api_tokens["tok"] = time.monotonic() + 300.0
+    channel._session_manager = MagicMock()
+    channel._session_manager.list_sessions.return_value = [
+        {
+            "key": "websocket:chat-1",
+            "created_at": "2026-05-19T10:00:00Z",
+            "updated_at": "2026-05-19T10:01:00Z",
+            "title": "Running",
+            "preview": "work",
+            "path": "/private/path",
+        },
+        {
+            "key": "cli:chat-2",
+            "created_at": "2026-05-19T10:00:00Z",
+            "updated_at": "2026-05-19T10:01:00Z",
+        },
+    ]
+
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    try:
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT["chat-1"] = 1_700_000_000.0
+        req = Request("/api/sessions", Headers([("Authorization", "Bearer tok")]))
+        resp = channel._handle_sessions_list(req)
+    finally:
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+
+    assert resp.status_code == 200
+    body = json.loads(resp.body.decode())
+    assert body["sessions"] == [
+        {
+            "key": "websocket:chat-1",
+            "created_at": "2026-05-19T10:00:00Z",
+            "updated_at": "2026-05-19T10:01:00Z",
+            "title": "Running",
+            "preview": "work",
+            "run_started_at": 1_700_000_000.0,
+        }
+    ]
+
+
 @pytest.mark.parametrize(
     ("value", "expected"),
     [
@@ -1574,7 +1743,7 @@ def test_handle_webui_thread_get_returns_json(tmp_path, monkeypatch) -> None:
     from websockets.datastructures import Headers
     from websockets.http11 import Request
 
-    from nanobot.utils.webui_transcript import append_transcript_object
+    from nanobot.webui.transcript import append_transcript_object
 
     monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
     key = "websocket:c1"

tests/channels/test_websocket_http_routes.py

@@ -6,6 +6,7 @@ import json
 from pathlib import Path
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock
+from urllib.parse import urlencode
 
 import httpx
 import pytest
@@ -176,13 +177,62 @@ async def test_sessions_list_only_returns_websocket_sessions_by_default(
         await server_task
 
 
+@pytest.mark.asyncio
+async def test_webui_sidebar_state_routes_are_config_dir_scoped(
+    bus: MagicMock, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    sm = _seed_session(tmp_path, key="websocket:sidebar")
+    channel = _ch(bus, session_manager=sm, port=29911)
+    server_task = asyncio.create_task(channel.start())
+    await asyncio.sleep(0.3)
+    try:
+        boot = await _http_get("http://127.0.0.1:29911/webui/bootstrap")
+        token = boot.json()["token"]
+        auth = {"Authorization": f"Bearer {token}"}
+
+        initial = await _http_get(
+            "http://127.0.0.1:29911/api/webui/sidebar-state",
+            headers=auth,
+        )
+        assert initial.status_code == 200
+        assert initial.json()["schema_version"] == 1
+        assert initial.json()["pinned_keys"] == []
+
+        payload = {
+            "pinned_keys": ["websocket:sidebar"],
+            "archived_keys": ["websocket:old"],
+            "title_overrides": {"websocket:sidebar": "Pinned work"},
+            "view": {"density": "compact", "show_archived": True},
+        }
+        query = urlencode({"state": json.dumps(payload)})
+        updated = await _http_get(
+            f"http://127.0.0.1:29911/api/webui/sidebar-state/update?{query}",
+            headers=auth,
+        )
+        assert updated.status_code == 200
+        body = updated.json()
+        assert body["pinned_keys"] == ["websocket:sidebar"]
+        assert body["title_overrides"] == {"websocket:sidebar": "Pinned work"}
+        assert body["view"]["density"] == "compact"
+
+        state_path = tmp_path / "webui" / "sidebar-state.json"
+        assert state_path.is_file()
+        assert json.loads(state_path.read_text(encoding="utf-8"))["pinned_keys"] == [
+            "websocket:sidebar"
+        ]
+    finally:
+        await channel.stop()
+        await server_task
+
+
 @pytest.mark.asyncio
 async def test_session_delete_removes_file(
     bus: MagicMock, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
     sm = _seed_session(tmp_path, key="websocket:doomed")
-    from nanobot.utils.webui_transcript import append_transcript_object
+    from nanobot.webui.transcript import append_transcript_object
 
     append_transcript_object("websocket:doomed", {"event": "user", "chat_id": "doomed", "text": "x"})
     channel = _ch(bus, session_manager=sm, port=29903)

tests/cli/test_commands.py

@@ -11,7 +11,7 @@ from typer.testing import CliRunner
 from nanobot.bus.events import OutboundMessage
 from nanobot.cli.commands import app
 from nanobot.providers.factory import make_provider
-from nanobot.config.schema import Config
+from nanobot.config.schema import Config, ModelPresetConfig
 from nanobot.cron.types import CronJob, CronPayload
 from nanobot.providers.factory import ProviderSnapshot
 from nanobot.providers.openai_codex_provider import _strip_model_prefix
@@ -226,6 +226,16 @@ def test_config_dump_excludes_oauth_provider_blocks():
 
     assert "openaiCodex" not in providers
     assert "githubCopilot" not in providers
+    assert "xaiOauth" not in providers
+
+
+def test_config_dump_includes_xai_oauth_when_hosted_search_is_disabled():
+    config = Config()
+    config.providers.xai_oauth.x_search.enable = False
+
+    providers = config.model_dump(by_alias=True)["providers"]
+
+    assert providers["xaiOauth"]["xSearch"]["enable"] is False
 
 
 def test_provider_logout_openai_codex_removes_local_oauth_files(tmp_path, monkeypatch):
@@ -280,6 +290,175 @@ def test_provider_logout_github_copilot_succeeds_when_no_local_oauth_file(monkey
     assert "No local OAuth credentials found for GitHub Copilot" in result.stdout
 
 
+def test_provider_logout_xai_oauth_removes_local_oauth_files(tmp_path, monkeypatch):
+    token_path = tmp_path / "auth" / "xai-oauth.json"
+    lock_path = token_path.with_suffix(".lock")
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+    token_path.write_text("{}", encoding="utf-8")
+    lock_path.write_text("", encoding="utf-8")
+    monkeypatch.setenv("NANOBOT_HOME", str(tmp_path))
+    monkeypatch.setattr("nanobot.providers.xai_oauth_provider._keyring_delete", lambda: None)
+
+    result = runner.invoke(app, ["provider", "logout", "xai-oauth"])
+
+    assert result.exit_code == 0
+    assert not token_path.exists()
+    assert not lock_path.exists()
+    assert "Logged out from xAI Grok OAuth" in result.stdout
+
+
+def test_provider_logout_xai_oauth_succeeds_when_no_local_oauth_file(monkeypatch, tmp_path):
+    monkeypatch.setenv("NANOBOT_HOME", str(tmp_path))
+    monkeypatch.setattr("nanobot.providers.xai_oauth_provider._keyring_delete", lambda: None)
+
+    result = runner.invoke(app, ["provider", "logout", "xai-oauth"])
+
+    assert result.exit_code == 0
+    assert "No local OAuth credentials found for xAI Grok OAuth" in result.stdout
+
+
+def test_provider_login_xai_oauth_forwards_manual_options(monkeypatch):
+    from nanobot.providers.xai_oauth_provider import XaiOAuthCredential
+
+    captured: dict[str, object] = {}
+
+    def fake_login_xai_oauth_interactive(**kwargs):
+        captured.update(kwargs)
+        return XaiOAuthCredential(access_token="access", account_id="acct", storage="keyring")
+
+    monkeypatch.setattr(
+        "nanobot.providers.xai_oauth_provider.login_xai_oauth_interactive",
+        fake_login_xai_oauth_interactive,
+    )
+
+    result = runner.invoke(app, ["provider", "login", "xai-oauth", "--no-browser", "--manual-paste"])
+
+    assert result.exit_code == 0
+    assert captured["open_browser"] is False
+    assert captured["manual_paste"] is True
+    assert "Authenticated with xAI Grok OAuth" in result.stdout
+    assert "nanobot config set agents.defaults.provider xai-oauth" in result.stdout
+
+
+def test_config_set_updates_default_model_selection(tmp_path):
+    config_path = tmp_path / "config.json"
+
+    result = runner.invoke(app, [
+        "config",
+        "set",
+        "--config",
+        str(config_path),
+        "agents.defaults.model_preset",
+        "null",
+    ])
+    assert result.exit_code == 0
+
+    result = runner.invoke(app, [
+        "config",
+        "set",
+        "--config",
+        str(config_path),
+        "agents.defaults.provider",
+        "xai-oauth",
+    ])
+    assert result.exit_code == 0
+
+    result = runner.invoke(app, [
+        "config",
+        "set",
+        "--config",
+        str(config_path),
+        "agents.defaults.model",
+        "xai-oauth/grok-4.3",
+    ])
+    assert result.exit_code == 0
+
+    data = json.loads(config_path.read_text(encoding="utf-8"))
+    config = Config.model_validate(data)
+    assert config.agents.defaults.model_preset is None
+    assert config.agents.defaults.provider == "xai-oauth"
+    assert config.agents.defaults.model == "xai-oauth/grok-4.3"
+
+
+def test_config_set_warns_when_model_preset_would_override_selection(tmp_path):
+    config = Config()
+    config.agents.defaults.model_preset = "fast"
+    config.model_presets["fast"] = ModelPresetConfig(
+        provider="openrouter",
+        model="openrouter/openai/gpt-4o-mini",
+    )
+    config_path = tmp_path / "config.json"
+    config_path.write_text(json.dumps(config.model_dump(mode="json", by_alias=True)), encoding="utf-8")
+
+    result = runner.invoke(app, [
+        "config",
+        "set",
+        "--config",
+        str(config_path),
+        "agents.defaults.provider",
+        "xai-oauth",
+    ])
+
+    assert result.exit_code == 0
+    assert "model_preset is set and may override this" in result.stdout
+
+
+def test_config_set_disables_xai_oauth_hosted_search(tmp_path):
+    config_path = tmp_path / "config.json"
+
+    result = runner.invoke(app, [
+        "config",
+        "set",
+        "--config",
+        str(config_path),
+        "providers.xai_oauth.x_search.enable",
+        "false",
+    ])
+
+    assert result.exit_code == 0
+    data = json.loads(config_path.read_text(encoding="utf-8"))
+    assert data["providers"]["xaiOauth"]["xSearch"]["enable"] is False
+    assert Config.model_validate(data).providers.xai_oauth.x_search.enable is False
+
+
+def test_config_set_rejects_unknown_path(tmp_path):
+    result = runner.invoke(app, [
+        "config",
+        "set",
+        "--config",
+        str(tmp_path / "config.json"),
+        "agents.defaults.not_a_field",
+        "value",
+    ])
+
+    assert result.exit_code == 1
+    assert "Could not set config value" in result.stdout
+
+
+def test_provider_login_xai_oauth_does_not_update_config(monkeypatch, tmp_path):
+    from nanobot.providers.xai_oauth_provider import XaiOAuthCredential
+
+    config = Config()
+    config.agents.defaults.provider = "auto"
+    config.agents.defaults.model = "anthropic/claude-opus-4-5"
+    config_path = tmp_path / "config.json"
+
+    monkeypatch.setattr(
+        "nanobot.providers.xai_oauth_provider.login_xai_oauth_interactive",
+        lambda **_kwargs: XaiOAuthCredential(access_token="access", account_id="acct", storage="keyring"),
+    )
+    monkeypatch.setattr("nanobot.config.loader.get_config_path", lambda: config_path)
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    save_config = MagicMock()
+    monkeypatch.setattr("nanobot.config.loader.save_config", save_config)
+
+    result = runner.invoke(app, ["provider", "login", "xai-oauth"])
+
+    assert result.exit_code == 0
+    save_config.assert_not_called()
+    assert "nanobot config set agents.defaults.model xai-oauth/grok-4.3" in result.stdout
+
+
 def test_provider_logout_rejects_unknown_provider():
     result = runner.invoke(app, ["provider", "logout", "not-a-real-provider"])
 
@@ -398,6 +577,8 @@ def test_find_by_name_accepts_camel_case_and_hyphen_aliases():
     assert find_by_name("volcengineCodingPlan").name == "volcengine_coding_plan"
     assert find_by_name("github-copilot") is not None
     assert find_by_name("github-copilot").name == "github_copilot"
+    assert find_by_name("xai-oauth") is not None
+    assert find_by_name("xai-oauth").name == "xai_oauth"
     assert find_by_name("longcat") is not None
     assert find_by_name("longcat").name == "longcat"
     assert find_by_name("atomic-chat") is not None
@@ -540,6 +721,23 @@ def test_make_provider_uses_github_copilot_backend():
     assert provider.__class__.__name__ == "GitHubCopilotProvider"
 
 
+def test_make_provider_uses_xai_oauth_backend():
+    config = Config.model_validate(
+        {
+            "agents": {
+                "defaults": {
+                    "provider": "xai-oauth",
+                    "model": "xai-oauth/grok-4.3",
+                }
+            }
+        }
+    )
+
+    provider = make_provider(config)
+
+    assert provider.__class__.__name__ == "XaiOAuthProvider"
+
+
 def test_github_copilot_provider_strips_prefixed_model_name():
     from nanobot.providers.github_copilot_provider import GitHubCopilotProvider
 
@@ -572,6 +770,7 @@ async def test_github_copilot_provider_refreshes_client_api_key_before_chat():
 
     with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI", return_value=mock_client):
         provider = GitHubCopilotProvider(default_model="github-copilot/gpt-4")
+        await provider._ensure_client()
 
     provider._get_copilot_access_token = AsyncMock(return_value="copilot-access-token")
 
@@ -611,7 +810,8 @@ def test_make_provider_passes_extra_headers_to_custom_provider():
     )
 
     with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_async_openai:
-        make_provider(config)
+        provider = make_provider(config)
+        asyncio.run(provider._ensure_client())
 
     kwargs = mock_async_openai.call_args.kwargs
     assert kwargs["api_key"] == "test-key"

tests/providers/test_ant_ling_provider.py

@@ -0,0 +1,73 @@
+"""Tests for the Ant Ling provider registration."""
+
+from unittest.mock import patch
+
+from nanobot.config.schema import Config, ProvidersConfig
+from nanobot.providers.openai_compat_provider import OpenAICompatProvider
+from nanobot.providers.registry import PROVIDERS, find_by_name
+
+
+def test_ant_ling_config_field_exists() -> None:
+    config = ProvidersConfig()
+
+    assert hasattr(config, "ant_ling")
+
+
+def test_ant_ling_provider_in_registry() -> None:
+    specs = {spec.name: spec for spec in PROVIDERS}
+
+    assert "ant_ling" in specs
+    ant_ling = specs["ant_ling"]
+    assert ant_ling.backend == "openai_compat"
+    assert ant_ling.env_key == "ANT_LING_API_KEY"
+    assert ant_ling.display_name == "Ant Ling"
+    assert ant_ling.default_api_base == "https://api.ant-ling.com/v1"
+
+
+def test_find_by_name_accepts_ant_ling_spellings() -> None:
+    spec = find_by_name("ant_ling")
+
+    assert spec is not None
+    assert find_by_name("ant-ling") is spec
+    assert find_by_name("antLing") is spec
+
+
+def test_ant_ling_model_auto_matches_with_default_api_base() -> None:
+    config = Config.model_validate({
+        "providers": {
+            "antLing": {
+                "apiKey": "ling-key",
+            },
+        },
+        "agents": {
+            "defaults": {
+                "model": "Ling-2.6-flash",
+            },
+        },
+    })
+
+    assert config.get_provider_name("Ling-2.6-flash") == "ant_ling"
+    assert config.get_api_key("Ling-2.6-flash") == "ling-key"
+    assert config.get_api_base("Ling-2.6-flash") == "https://api.ant-ling.com/v1"
+
+
+def test_ant_ling_preserves_official_model_name() -> None:
+    spec = find_by_name("ant_ling")
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI"):
+        provider = OpenAICompatProvider(
+            api_key="ling-key",
+            default_model="Ling-2.6-flash",
+            spec=spec,
+        )
+
+    kwargs = provider._build_kwargs(
+        messages=[{"role": "user", "content": "hi"}],
+        tools=None,
+        model="Ling-2.6-flash",
+        max_tokens=1024,
+        temperature=0.7,
+        reasoning_effort=None,
+        tool_choice=None,
+    )
+
+    assert kwargs["model"] == "Ling-2.6-flash"

tests/providers/test_anthropic_stream_idle.py

@@ -129,6 +129,74 @@ async def test_chat_stream_invokes_on_thinking_delta_for_thinking_delta() -> Non
     assert text_parts == ["X"]
 
 
+@pytest.mark.asyncio
+async def test_chat_stream_invokes_tool_call_delta_for_input_json_delta() -> None:
+    provider = AnthropicProvider(api_key="sk-test")
+    provider._client = MagicMock()
+
+    chunks = [
+        SimpleNamespace(
+            type="content_block_start",
+            index=1,
+            content_block=SimpleNamespace(
+                type="tool_use",
+                id="toolu_1",
+                name="write_file",
+            ),
+        ),
+        SimpleNamespace(
+            type="content_block_delta",
+            index=1,
+            delta=SimpleNamespace(
+                type="input_json_delta",
+                partial_json='{"path":"notes.md","content":"',
+            ),
+        ),
+        SimpleNamespace(
+            type="content_block_delta",
+            index=1,
+            delta=SimpleNamespace(type="input_json_delta", partial_json="line\\n"),
+        ),
+    ]
+    fake = _FakeAsyncStream(chunks)
+    stream_cm = MagicMock()
+    stream_cm.__aenter__ = AsyncMock(return_value=fake)
+    stream_cm.__aexit__ = AsyncMock(return_value=None)
+    provider._client.messages.stream = MagicMock(return_value=stream_cm)
+
+    deltas: list[dict] = []
+
+    async def on_tool_delta(delta: dict) -> None:
+        deltas.append(delta)
+
+    await provider.chat_stream(
+        messages=[{"role": "user", "content": "write"}],
+        on_tool_call_delta=on_tool_delta,
+    )
+
+    assert deltas == [
+        {
+            "index": 1,
+            "call_id": "toolu_1",
+            "name": "write_file",
+            "arguments_delta": "",
+        },
+        {
+            "index": 1,
+            "call_id": "toolu_1",
+            "name": "write_file",
+            "arguments_delta": '{"path":"notes.md","content":"',
+        },
+        {
+            "index": 1,
+            "call_id": "toolu_1",
+            "name": "write_file",
+            "arguments_delta": "line\\n",
+        },
+    ]
+    fake.get_final_message.assert_awaited_once()
+
+
 @pytest.mark.asyncio
 async def test_chat_stream_without_callback_still_finalizes() -> None:
     provider = AnthropicProvider(api_key="sk-test")

tests/providers/test_github_copilot_routing.py

@@ -65,6 +65,7 @@ async def test_github_copilot_does_not_fall_back_from_responses_error():
 
     with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI", return_value=mock_client):
         provider = GitHubCopilotProvider(default_model="github_copilot/gpt-5.4-mini")
+        await provider._ensure_client()
     provider._get_copilot_access_token = AsyncMock(return_value="copilot-access-token")
 
     response = await provider.chat(

tests/providers/test_image_generation.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import base64
 from pathlib import Path
 from typing import Any
 
@@ -11,7 +12,9 @@ from nanobot.providers.image_generation import (
     GeminiImageGenerationClient,
     GeneratedImageResponse,
     ImageGenerationError,
+    MiniMaxImageGenerationClient,
     OpenRouterImageGenerationClient,
+    StepFunImageGenerationClient,
 )
 
 PNG_BYTES = (
@@ -24,6 +27,7 @@ PNG_DATA_URL = (
     "data:image/png;base64,"
     "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII="
 )
+JPEG_BYTES = b"\xff\xd8\xff\xe0" + b"0" * 12
 
 
 class FakeResponse:
@@ -205,6 +209,20 @@ async def test_aihubmix_image_generation_downloads_url_response() -> None:
     assert fake.get_calls[0]["url"] == "https://cdn.example/image.png"
 
 
+@pytest.mark.asyncio
+async def test_aihubmix_base64_response_uses_detected_mime() -> None:
+    raw_b64 = base64.b64encode(JPEG_BYTES).decode("ascii")
+    fake = FakeClient(FakeResponse({"output": {"b64_json": raw_b64}}))
+    client = AIHubMixImageGenerationClient(
+        api_key="sk-ahm-test",
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    response = await client.generate(prompt="draw", model="gpt-image-2-free")
+
+    assert response.images == [f"data:image/jpeg;base64,{raw_b64}"]
+
+
 RAW_B64 = PNG_DATA_URL.removeprefix("data:image/png;base64,")
 
 
@@ -337,3 +355,163 @@ async def test_gemini_no_images_raises() -> None:
 
     with pytest.raises(ImageGenerationError, match="returned no images"):
         await client.generate(prompt="draw", model="gemini-2.0-flash-preview-image-generation")
+
+
+@pytest.mark.asyncio
+async def test_minimax_payload_and_response_with_reference_image(tmp_path: Path) -> None:
+    ref = tmp_path / "ref.png"
+    ref.write_bytes(PNG_BYTES)
+    fake = FakeClient(FakeResponse({"data": {"image_base64": [RAW_B64]}}))
+    client = MiniMaxImageGenerationClient(
+        api_key="sk-mm-test",
+        api_base="https://api.minimaxi.com/v1/",
+        extra_headers={"X-Test": "1"},
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    response = await client.generate(
+        prompt="draw a character",
+        model="image-01",
+        reference_images=[str(ref)],
+        aspect_ratio="21:9",
+    )
+
+    assert response.images == [PNG_DATA_URL]
+    call = fake.calls[0]
+    assert call["url"] == "https://api.minimaxi.com/v1/image_generation"
+    assert call["headers"]["Authorization"] == "Bearer sk-mm-test"
+    assert call["headers"]["X-Test"] == "1"
+    body = call["json"]
+    assert body["model"] == "image-01"
+    assert body["prompt"] == "draw a character"
+    assert body["response_format"] == "base64"
+    assert body["aspect_ratio"] == "21:9"
+    assert body["subject_reference"][0]["type"] == "character"
+    assert body["subject_reference"][0]["image_file"].startswith("data:image/png;base64,")
+
+
+# ---------------------------------------------------------------------------
+# StepFun (阶跃星辰)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_stepfun_payload_and_response_with_aspect_ratio() -> None:
+    fake = FakeClient(FakeResponse({"data": [{"b64_json": RAW_B64}]}))
+    client = StepFunImageGenerationClient(
+        api_key="sk-sf-test",
+        api_base="https://api.stepfun.com/v1",
+        extra_headers={"X-Test": "1"},
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    response = await client.generate(
+        prompt="a cat on the moon",
+        model="step-image-edit-2",
+        aspect_ratio="16:9",
+    )
+
+    assert response.images == [PNG_DATA_URL]
+    call = fake.calls[0]
+    assert call["url"] == "https://api.stepfun.com/v1/images/generations"
+    assert call["headers"]["Authorization"] == "Bearer sk-sf-test"
+    assert call["headers"]["X-Test"] == "1"
+    body = call["json"]
+    assert body["model"] == "step-image-edit-2"
+    assert body["prompt"] == "a cat on the moon"
+    assert body["response_format"] == "b64_json"
+    assert body["n"] == 1
+    assert body["size"] == "1280x800"
+
+
+@pytest.mark.asyncio
+async def test_stepfun_default_size_when_no_aspect_ratio() -> None:
+    fake = FakeClient(FakeResponse({"data": [{"b64_json": RAW_B64}]}))
+    client = StepFunImageGenerationClient(
+        api_key="sk-sf-test",
+        api_base="https://api.stepfun.com/v1",
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    await client.generate(prompt="a dog", model="step-image-edit-2")
+
+    body = fake.calls[0]["json"]
+    assert body["size"] == "1024x1024"
+
+
+@pytest.mark.asyncio
+async def test_stepfun_uses_explicit_image_size() -> None:
+    fake = FakeClient(FakeResponse({"data": [{"b64_json": RAW_B64}]}))
+    client = StepFunImageGenerationClient(
+        api_key="sk-sf-test",
+        api_base="https://api.stepfun.com/v1",
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    await client.generate(
+        prompt="a bird",
+        model="step-image-edit-2",
+        image_size="1024x1024",
+    )
+
+    body = fake.calls[0]["json"]
+    assert body["size"] == "1024x1024"
+
+
+@pytest.mark.asyncio
+async def test_stepfun_style_reference_on_1x_model(tmp_path: Path) -> None:
+    """step-1x-medium supports style_reference for reference-image generation."""
+    ref = tmp_path / "ref.png"
+    ref.write_bytes(PNG_BYTES)
+    fake = FakeClient(FakeResponse({"data": [{"b64_json": RAW_B64}]}))
+    client = StepFunImageGenerationClient(
+        api_key="sk-sf-test",
+        api_base="https://api.stepfun.com/v1",
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    await client.generate(
+        prompt="in this style",
+        model="step-1x-medium",
+        reference_images=[str(ref)],
+    )
+
+    body = fake.calls[0]["json"]
+    assert "style_reference" in body
+    assert body["style_reference"]["source_url"].startswith("data:image/png;base64,")
+
+
+@pytest.mark.asyncio
+async def test_stepfun_no_style_reference_on_non_1x_model() -> None:
+    """step-image-edit-2 does not use style_reference; reference images are ignored."""
+    fake = FakeClient(FakeResponse({"data": [{"b64_json": RAW_B64}]}))
+    client = StepFunImageGenerationClient(
+        api_key="sk-sf-test",
+        api_base="https://api.stepfun.com/v1",
+        client=fake,  # type: ignore[arg-type]
+    )
+
+    await client.generate(
+        prompt="a flower",
+        model="step-image-edit-2",
+        reference_images=["/tmp/ref.png"],
+    )
+
+    body = fake.calls[0]["json"]
+    assert "style_reference" not in body
+
+
+@pytest.mark.asyncio
+async def test_stepfun_requires_api_key() -> None:
+    client = StepFunImageGenerationClient(api_key=None)
+
+    with pytest.raises(ImageGenerationError, match="API key"):
+        await client.generate(prompt="draw", model="step-image-edit-2")
+
+
+@pytest.mark.asyncio
+async def test_stepfun_no_images_raises() -> None:
+    fake = FakeClient(FakeResponse({"data": [{"text": "sorry"}]}))
+    client = StepFunImageGenerationClient(api_key="sk-sf-test", client=fake)  # type: ignore[arg-type]
+
+    with pytest.raises(ImageGenerationError, match="returned no images"):
+        await client.generate(prompt="draw", model="step-image-edit-2")

tests/providers/test_litellm_kwargs.py

@@ -164,6 +164,130 @@ def _fake_chat_stream_reasoning_chunks():
     return _stream()
 
 
+def _fake_chat_stream_tool_call_chunks():
+    """Mimic OpenAI-compatible streaming tool-call argument deltas."""
+
+    async def _stream():
+        yield SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    finish_reason=None,
+                    delta=SimpleNamespace(
+                        content=None,
+                        reasoning_content=None,
+                        reasoning=None,
+                        tool_calls=[
+                            SimpleNamespace(
+                                index=0,
+                                id="call_write",
+                                function=SimpleNamespace(
+                                    name="write_file",
+                                    arguments='{"path":"notes.md","content":"',
+                                ),
+                            )
+                        ],
+                    ),
+                ),
+            ],
+            usage=None,
+        )
+        yield SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    finish_reason=None,
+                    delta=SimpleNamespace(
+                        content=None,
+                        reasoning_content=None,
+                        reasoning=None,
+                        tool_calls=[
+                            SimpleNamespace(
+                                index=0,
+                                id=None,
+                                function=SimpleNamespace(name=None, arguments='line\\n"}'),
+                            )
+                        ],
+                    ),
+                ),
+            ],
+            usage=None,
+        )
+        yield SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    finish_reason="tool_calls",
+                    delta=SimpleNamespace(
+                        content=None,
+                        reasoning_content=None,
+                        reasoning=None,
+                        tool_calls=None,
+                    ),
+                ),
+            ],
+            usage=SimpleNamespace(prompt_tokens=10, completion_tokens=5, total_tokens=15),
+        )
+
+    return _stream()
+
+
+def _fake_chat_stream_legacy_function_call_chunks():
+    """Mimic older OpenAI-compatible ``delta.function_call`` chunks."""
+
+    async def _stream():
+        yield SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    finish_reason=None,
+                    delta=SimpleNamespace(
+                        content=None,
+                        reasoning_content=None,
+                        reasoning=None,
+                        tool_calls=None,
+                        function_call=SimpleNamespace(
+                            name="write_file",
+                            arguments='{"path":"notes.md","content":"',
+                        ),
+                    ),
+                ),
+            ],
+            usage=None,
+        )
+        yield SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    finish_reason=None,
+                    delta=SimpleNamespace(
+                        content=None,
+                        reasoning_content=None,
+                        reasoning=None,
+                        tool_calls=None,
+                        function_call=SimpleNamespace(
+                            name=None,
+                            arguments='line\\n"}',
+                        ),
+                    ),
+                ),
+            ],
+            usage=None,
+        )
+        yield SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    finish_reason="function_call",
+                    delta=SimpleNamespace(
+                        content=None,
+                        reasoning_content=None,
+                        reasoning=None,
+                        tool_calls=None,
+                        function_call=None,
+                    ),
+                ),
+            ],
+            usage=SimpleNamespace(prompt_tokens=10, completion_tokens=5, total_tokens=15),
+        )
+
+    return _stream()
+
+
 @pytest.mark.asyncio
 async def test_openai_compat_stream_forwards_reasoning_deltas_deepseek_style() -> None:
     """Regression: DeepSeek-V4 / reasoner expose ``delta.reasoning_content`` during streaming."""
@@ -202,6 +326,98 @@ async def test_openai_compat_stream_forwards_reasoning_deltas_deepseek_style() -
     mock_chat.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("provider_name", "model"),
+    [
+        ("openai", "gpt-4o"),
+        ("deepseek", "deepseek-chat"),
+        ("minimax", "MiniMax-M2.7"),
+        ("zhipu", "glm-4.6"),
+    ],
+)
+async def test_openai_compat_stream_forwards_tool_call_argument_deltas(
+    provider_name: str,
+    model: str,
+) -> None:
+    mock_chat = AsyncMock(return_value=_fake_chat_stream_tool_call_chunks())
+    spec = find_by_name(provider_name)
+    deltas: list[dict] = []
+
+    async def on_tool_delta(delta: dict) -> None:
+        deltas.append(delta)
+
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_openai:
+        client_instance = mock_openai.return_value
+        client_instance.chat.completions.create = mock_chat
+
+        provider = OpenAICompatProvider(
+            api_key="sk-test",
+            default_model=model,
+            spec=spec,
+        )
+        result = await provider.chat_stream(
+            messages=[{"role": "user", "content": "write"}],
+            tools=[{"type": "function", "function": {"name": "write_file"}}],
+            model=model,
+            on_tool_call_delta=on_tool_delta,
+        )
+
+    assert deltas == [
+        {
+            "index": 0,
+            "call_id": "call_write",
+            "name": "write_file",
+            "arguments_delta": '{"path":"notes.md","content":"',
+        },
+        {"index": 0, "call_id": "", "name": "", "arguments_delta": 'line\\n"}'},
+    ]
+    assert result.tool_calls[0].name == "write_file"
+    assert result.tool_calls[0].arguments == {"path": "notes.md", "content": "line\n"}
+    kwargs = mock_chat.await_args.kwargs
+    if provider_name == "zhipu":
+        assert kwargs["extra_body"]["tool_stream"] is True
+    else:
+        assert kwargs.get("extra_body", {}).get("tool_stream") is None
+
+
+@pytest.mark.asyncio
+async def test_openai_compat_stream_forwards_legacy_function_call_argument_deltas() -> None:
+    mock_chat = AsyncMock(return_value=_fake_chat_stream_legacy_function_call_chunks())
+    deltas: list[dict] = []
+
+    async def on_tool_delta(delta: dict) -> None:
+        deltas.append(delta)
+
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_openai:
+        client_instance = mock_openai.return_value
+        client_instance.chat.completions.create = mock_chat
+
+        provider = OpenAICompatProvider(
+            api_key="sk-test",
+            default_model="deepseek-chat",
+            spec=find_by_name("deepseek"),
+        )
+        result = await provider.chat_stream(
+            messages=[{"role": "user", "content": "write"}],
+            tools=[{"type": "function", "function": {"name": "write_file"}}],
+            model="deepseek-chat",
+            on_tool_call_delta=on_tool_delta,
+        )
+
+    assert deltas == [
+        {
+            "index": 0,
+            "call_id": "",
+            "name": "write_file",
+            "arguments_delta": '{"path":"notes.md","content":"',
+        },
+        {"index": 0, "call_id": "", "name": "", "arguments_delta": 'line\\n"}'},
+    ]
+    assert result.tool_calls[0].name == "write_file"
+    assert result.tool_calls[0].arguments == {"path": "notes.md", "content": "line\n"}
+
+
 class _FakeResponsesError(Exception):
     def __init__(self, status_code: int, text: str):
         super().__init__(text)
@@ -233,27 +449,28 @@ def test_gemma_routes_to_gemini_provider() -> None:
     assert "gemma" in spec.keywords
 
 
-def test_openrouter_sets_default_attribution_headers() -> None:
+async def test_openrouter_sets_default_attribution_headers() -> None:
     spec = find_by_name("openrouter")
-    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as MockClient:
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_client_cls:
-        OpenAICompatProvider(
+        provider = OpenAICompatProvider(
             api_key="sk-or-test-key",
             api_base="https://openrouter.ai/api/v1",
             default_model="anthropic/claude-sonnet-4-5",
             spec=spec,
         )
+        await provider._ensure_client()
 
-    headers = MockClient.call_args.kwargs["default_headers"]
+    headers = mock_client_cls.call_args.kwargs["default_headers"]
     assert headers["HTTP-Referer"] == "https://github.com/HKUDS/nanobot"
     assert headers["X-OpenRouter-Title"] == "nanobot"
     assert headers["X-OpenRouter-Categories"] == "cli-agent,personal-agent"
     assert "x-session-affinity" in headers
 
 
-def test_openrouter_user_headers_override_default_attribution() -> None:
+async def test_openrouter_user_headers_override_default_attribution() -> None:
     spec = find_by_name("openrouter")
-    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as MockClient:
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_client_cls:
-        OpenAICompatProvider(
+        provider = OpenAICompatProvider(
             api_key="sk-or-test-key",
             api_base="https://openrouter.ai/api/v1",
             default_model="anthropic/claude-sonnet-4-5",
@@ -264,8 +481,9 @@ def test_openrouter_user_headers_override_default_attribution() -> None:
             },
             spec=spec,
         )
+        await provider._ensure_client()
 
-    headers = MockClient.call_args.kwargs["default_headers"]
+    headers = mock_client_cls.call_args.kwargs["default_headers"]
     assert headers["HTTP-Referer"] == "https://nanobot.ai"
     assert headers["X-OpenRouter-Title"] == "Nanobot Pro"
     assert headers["X-OpenRouter-Categories"] == "cli-agent,personal-agent"

tests/providers/test_llm_response.py

@@ -44,9 +44,15 @@ class TestShouldExecuteTools:
         resp = _response("stop")
         assert resp.should_execute_tools is True
 
+    def test_legacy_function_call_reason_executes(self) -> None:
+        # Older OpenAI-compatible streaming APIs can still use the singular
+        # function_call finish reason while carrying a tool-call-shaped payload.
+        resp = _response("function_call")
+        assert resp.should_execute_tools is True
+
     @pytest.mark.parametrize(
         "anomalous_reason",
-        ["refusal", "content_filter", "error", "length", "function_call", ""],
+        ["refusal", "content_filter", "error", "length", ""],
     )
     def test_tool_calls_under_anomalous_reason_blocked(self, anomalous_reason: str) -> None:
         # This is the #3220 bug: gateways injecting tool_calls under any of these

tests/providers/test_local_endpoint_detection.py

@@ -85,17 +85,18 @@ class TestIsLocalEndpoint:
 class TestLocalKeepaliveConfig:
     """Verify that local endpoints get keepalive_expiry=0."""
 
-    def test_local_spec_disables_keepalive(self):
+    async def test_local_spec_disables_keepalive(self):
         spec = _make_spec(is_local=True)
         spec.env_key = ""
         spec.default_api_base = "http://localhost:11434/v1"
         provider = OpenAICompatProvider(
             api_key="test", api_base="http://localhost:11434/v1", spec=spec,
         )
+        await provider._ensure_client()
         pool = provider._client._client._transport._pool
         assert pool._keepalive_expiry == 0
 
-    def test_lan_ip_disables_keepalive(self):
+    async def test_lan_ip_disables_keepalive(self):
         """A generic 'openai' spec with a LAN IP should still disable keepalive."""
         spec = _make_spec(is_local=False)
         spec.env_key = ""
@@ -103,16 +104,18 @@ class TestLocalKeepaliveConfig:
         provider = OpenAICompatProvider(
             api_key="test", api_base="http://192.168.8.188:1234/v1", spec=spec,
         )
+        await provider._ensure_client()
         pool = provider._client._client._transport._pool
         assert pool._keepalive_expiry == 0
 
-    def test_cloud_keeps_default_keepalive(self):
+    async def test_cloud_keeps_default_keepalive(self):
         spec = _make_spec(is_local=False)
         spec.env_key = ""
         spec.default_api_base = "https://api.openai.com/v1"
         provider = OpenAICompatProvider(
             api_key="test", api_base=None, spec=spec,
         )
+        await provider._ensure_client()
         pool = provider._client._client._transport._pool
         # Default httpx keepalive is 5.0s
         assert pool._keepalive_expiry == 5.0

tests/providers/test_openai_codex_provider.py

@@ -16,7 +16,15 @@ async def test_codex_prompt_cache_key_uses_stable_conversation_prefix(monkeypatc
         lambda: SimpleNamespace(account_id="acct", access="token"),
     )
 
-    async def fake_request(url, headers, body, verify, on_content_delta=None):
+    async def fake_request(
+        url,
+        headers,
+        body,
+        verify,
+        on_content_delta=None,
+        on_tool_call_delta=None,
+    ):
+        _ = on_tool_call_delta
         bodies.append(body)
         return "ok", [], "stop"
 

tests/providers/test_openai_compat_timeout.py

@@ -8,16 +8,18 @@ def _assert_openai_compat_timeout(timeout) -> None:
     assert timeout == 120.0
 
 
-def test_openai_compat_provider_sets_sdk_timeout() -> None:
+async def test_openai_compat_provider_defers_sdk_client_until_first_use() -> None:
     with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_async_openai:
-        OpenAICompatProvider(api_key="test-key", api_base="https://example.com/v1")
+        provider = OpenAICompatProvider(api_key="test-key", api_base="https://example.com/v1")
+        mock_async_openai.assert_not_called()
+        await provider._ensure_client()
 
     kwargs = mock_async_openai.call_args.kwargs
     _assert_openai_compat_timeout(kwargs["timeout"])
     assert kwargs["http_client"] is None
 
 
-def test_openai_compat_provider_sets_timeout_on_local_http_client() -> None:
+async def test_openai_compat_provider_sets_timeout_on_local_http_client() -> None:
     spec = ProviderSpec(
         name="local",
         keywords=(),
@@ -29,11 +31,13 @@ def test_openai_compat_provider_sets_timeout_on_local_http_client() -> None:
     with (
         patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_async_openai,
         patch(
-            "nanobot.providers.openai_compat_provider.httpx.AsyncClient",
+            "httpx.AsyncClient",
             return_value=sentinel.http_client,
         ) as mock_http_client,
     ):
-        OpenAICompatProvider(spec=spec)
+        provider = OpenAICompatProvider(spec=spec)
+        mock_async_openai.assert_not_called()
+        await provider._ensure_client()
 
     client_kwargs = mock_http_client.call_args.kwargs
     _assert_openai_compat_timeout(client_kwargs["timeout"])
@@ -44,10 +48,11 @@ def test_openai_compat_provider_sets_timeout_on_local_http_client() -> None:
     assert openai_kwargs["http_client"] is sentinel.http_client
 
 
-def test_openai_compat_provider_timeout_can_be_overridden_by_env(monkeypatch) -> None:
+async def test_openai_compat_provider_timeout_can_be_overridden_by_env(monkeypatch) -> None:
     monkeypatch.setenv("NANOBOT_OPENAI_COMPAT_TIMEOUT_S", "45")
 
     with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_async_openai:
-        OpenAICompatProvider(api_key="test-key", api_base="https://example.com/v1")
+        provider = OpenAICompatProvider(api_key="test-key", api_base="https://example.com/v1")
+        await provider._ensure_client()
 
     assert mock_async_openai.call_args.kwargs["timeout"] == 45.0

tests/providers/test_openai_responses.py

@@ -453,6 +453,56 @@ class TestConsumeSdkStream:
         assert tool_calls[0].name == "get_weather"
         assert tool_calls[0].arguments == {"city": "SF"}
 
+    @pytest.mark.asyncio
+    async def test_tool_call_argument_delta_callback(self):
+        item_added = MagicMock(type="function_call", call_id="c1", id="fc1", arguments="")
+        item_added.name = "write_file"
+        ev1 = MagicMock(type="response.output_item.added", item=item_added)
+        ev2 = MagicMock(
+            type="response.function_call_arguments.delta",
+            call_id="c1",
+            delta='{"path":"a.txt","content":"',
+        )
+        ev3 = MagicMock(
+            type="response.function_call_arguments.delta",
+            call_id="c1",
+            delta='hello\\n',
+        )
+        ev4 = MagicMock(
+            type="response.function_call_arguments.done",
+            call_id="c1",
+            arguments='{"path":"a.txt","content":"hello\\n"}',
+        )
+        item_done = MagicMock(
+            type="function_call",
+            call_id="c1",
+            id="fc1",
+            arguments='{"path":"a.txt","content":"hello\\n"}',
+        )
+        item_done.name = "write_file"
+        ev5 = MagicMock(type="response.output_item.done", item=item_done)
+        resp_obj = MagicMock(status="completed", usage=None, output=[])
+        ev6 = MagicMock(type="response.completed", response=resp_obj)
+        deltas: list[dict] = []
+
+        async def cb(delta: dict) -> None:
+            deltas.append(delta)
+
+        async def stream():
+            for e in [ev1, ev2, ev3, ev4, ev5, ev6]:
+                yield e
+
+        await consume_sdk_stream(stream(), on_tool_call_delta=cb)
+        assert deltas == [
+            {"call_id": "c1", "name": "write_file", "arguments_delta": ""},
+            {
+                "call_id": "c1",
+                "name": "write_file",
+                "arguments_delta": '{"path":"a.txt","content":"',
+            },
+            {"call_id": "c1", "name": "write_file", "arguments_delta": "hello\\n"},
+        ]
+
     @pytest.mark.asyncio
     async def test_usage_extracted(self):
         usage_obj = MagicMock(input_tokens=10, output_tokens=5, total_tokens=15)

tests/providers/test_provider_sdk_retry_defaults.py

@@ -5,9 +5,10 @@ from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
 from nanobot.providers.openai_compat_provider import OpenAICompatProvider
 
 
-def test_openai_compat_disables_sdk_retries_by_default() -> None:
+async def test_openai_compat_disables_sdk_retries_by_default() -> None:
     with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_client:
-        OpenAICompatProvider(api_key="sk-test", default_model="gpt-4o")
+        provider = OpenAICompatProvider(api_key="sk-test", default_model="gpt-4o")
+        await provider._ensure_client()
 
     kwargs = mock_client.call_args.kwargs
     assert kwargs["max_retries"] == 0

tests/providers/test_providers_init.py

@@ -12,6 +12,7 @@ def test_importing_providers_package_is_lazy(monkeypatch) -> None:
     monkeypatch.delitem(sys.modules, "nanobot.providers.openai_compat_provider", raising=False)
     monkeypatch.delitem(sys.modules, "nanobot.providers.openai_codex_provider", raising=False)
     monkeypatch.delitem(sys.modules, "nanobot.providers.github_copilot_provider", raising=False)
+    monkeypatch.delitem(sys.modules, "nanobot.providers.xai_oauth_provider", raising=False)
     monkeypatch.delitem(sys.modules, "nanobot.providers.azure_openai_provider", raising=False)
     monkeypatch.delitem(sys.modules, "nanobot.providers.bedrock_provider", raising=False)
 
@@ -21,6 +22,7 @@ def test_importing_providers_package_is_lazy(monkeypatch) -> None:
     assert "nanobot.providers.openai_compat_provider" not in sys.modules
     assert "nanobot.providers.openai_codex_provider" not in sys.modules
     assert "nanobot.providers.github_copilot_provider" not in sys.modules
+    assert "nanobot.providers.xai_oauth_provider" not in sys.modules
     assert "nanobot.providers.azure_openai_provider" not in sys.modules
     assert "nanobot.providers.bedrock_provider" not in sys.modules
     assert providers.__all__ == [
@@ -30,6 +32,7 @@ def test_importing_providers_package_is_lazy(monkeypatch) -> None:
         "OpenAICompatProvider",
         "OpenAICodexProvider",
         "GitHubCopilotProvider",
+        "XaiOAuthProvider",
         "AzureOpenAIProvider",
         "BedrockProvider",
     ]
@@ -50,3 +53,9 @@ def test_openai_codex_supports_progress_deltas() -> None:
     from nanobot.providers.openai_codex_provider import OpenAICodexProvider
 
     assert OpenAICodexProvider.supports_progress_deltas is True
+
+
+def test_xai_oauth_supports_progress_deltas() -> None:
+    from nanobot.providers.xai_oauth_provider import XaiOAuthProvider
+
+    assert XaiOAuthProvider.supports_progress_deltas is True

tests/providers/test_skywork_provider.py

@@ -0,0 +1,80 @@
+"""Tests for the Skywork provider registration."""
+
+from unittest.mock import patch
+
+from nanobot.config.schema import Config, ProvidersConfig
+from nanobot.providers.openai_compat_provider import OpenAICompatProvider
+from nanobot.providers.registry import PROVIDERS, find_by_name
+
+
+def test_skywork_config_field_exists() -> None:
+    config = ProvidersConfig()
+
+    assert hasattr(config, "skywork")
+
+
+def test_skywork_provider_in_registry() -> None:
+    specs = {spec.name: spec for spec in PROVIDERS}
+
+    assert "skywork" in specs
+    skywork = specs["skywork"]
+    assert skywork.backend == "openai_compat"
+    assert skywork.env_key == "SKYWORK_API_KEY"
+    assert ("APIFREE_API_KEY", "{api_key}") in skywork.env_extras
+    assert skywork.display_name == "Skywork"
+    assert skywork.is_gateway is True
+    assert skywork.detect_by_base_keyword == "apifree.ai"
+    assert skywork.default_api_base == "https://api.apifree.ai/agent/v1"
+    assert skywork.supports_max_completion_tokens is False
+
+
+def test_find_by_name_skywork() -> None:
+    spec = find_by_name("skywork")
+
+    assert spec is not None
+    assert spec.name == "skywork"
+
+
+def test_skywork_model_auto_matches_with_default_api_base() -> None:
+    config = Config.model_validate(
+        {
+            "providers": {
+                "skywork": {
+                    "apiKey": "sky-key",
+                },
+            },
+            "agents": {
+                "defaults": {
+                    "model": "skywork-ai/skyclaw-v1",
+                },
+            },
+        }
+    )
+
+    assert config.get_provider_name("skywork-ai/skyclaw-v1") == "skywork"
+    assert config.get_api_key("skywork-ai/skyclaw-v1") == "sky-key"
+    assert config.get_api_base("skywork-ai/skyclaw-v1") == "https://api.apifree.ai/agent/v1"
+
+
+def test_skywork_preserves_model_id_and_uses_chat_completion_max_tokens() -> None:
+    spec = find_by_name("skywork")
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI"):
+        provider = OpenAICompatProvider(
+            api_key="sky-key",
+            default_model="skywork-ai/skyclaw-v1",
+            spec=spec,
+        )
+
+    kwargs = provider._build_kwargs(
+        messages=[{"role": "user", "content": "hi"}],
+        tools=None,
+        model="skywork-ai/skyclaw-v1",
+        max_tokens=1024,
+        temperature=0.7,
+        reasoning_effort=None,
+        tool_choice=None,
+    )
+
+    assert kwargs["model"] == "skywork-ai/skyclaw-v1"
+    assert kwargs["max_tokens"] == 1024
+    assert "max_completion_tokens" not in kwargs

tests/providers/test_xai_oauth_auth.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+import nanobot.providers.xai_oauth_provider as auth
+
+
+def test_build_xai_authorization_url_includes_pkce_and_grok_scope() -> None:
+    endpoints = auth.XaiOAuthEndpoints(
+        authorization_endpoint="https://auth.x.ai/authorize",
+        token_endpoint="https://auth.x.ai/oauth/token",
+    )
+
+    url = auth.build_xai_authorization_url(
+        endpoints,
+        verifier="verifier",
+        state="state",
+        nonce="nonce",
+    )
+
+    parsed = urlparse(url)
+    params = parse_qs(parsed.query)
+    assert parsed.scheme == "https"
+    assert parsed.hostname == "auth.x.ai"
+    assert params["client_id"] == [auth.DEFAULT_XAI_CLIENT_ID]
+    assert params["code_challenge"] == [auth.pkce_challenge("verifier")]
+    assert params["code_challenge_method"] == ["S256"]
+    assert params["scope"] == [auth.DEFAULT_XAI_SCOPE]
+    assert params["nonce"] == ["nonce"]
+    assert params["plan"] == ["generic"]
+    assert params["referrer"] == ["nanobot"]
+
+
+def test_parse_callback_value_accepts_fallback_shapes() -> None:
+    assert auth._parse_callback_value("https://localhost/callback?code=abc&state=state") == ("abc", "state")
+    assert auth._parse_callback_value("?code=abc&state=state") == ("abc", "state")
+    assert auth._parse_callback_value("code=abc&state=state") == ("abc", "state")
+    assert auth._parse_callback_value("fallback-code") == ("fallback-code", None)
+
+
+def test_file_storage_fallback_is_private_and_round_trips(tmp_path, monkeypatch) -> None:
+    monkeypatch.setenv("NANOBOT_HOME", str(tmp_path))
+    monkeypatch.setattr(auth, "_keyring_set", lambda _tokens: False)
+    monkeypatch.setattr(auth, "_keyring_get", lambda: None)
+
+    saved = auth.save_xai_oauth_credential(
+        auth.XaiOAuthCredential(
+            access_token="access",
+            refresh_token="refresh",
+            expires_at=123.0,
+            account_id="acct",
+        )
+    )
+
+    path = auth.get_xai_oauth_metadata_path()
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    assert saved.storage == "file"
+    assert payload["storage"] == "file"
+    assert payload["tokens"]["access_token"] == "access"
+    if os.name != "nt":
+        assert stat.S_IMODE(path.stat().st_mode) == 0o600
+
+    loaded = auth.load_xai_oauth_credential()
+    assert loaded is not None
+    assert loaded.access_token == "access"
+    assert loaded.refresh_token == "refresh"
+    assert loaded.account_id == "acct"
+    assert loaded.storage == "file"
+
+
+def test_keyring_storage_keeps_tokens_out_of_metadata(tmp_path, monkeypatch) -> None:
+    monkeypatch.setenv("NANOBOT_HOME", str(tmp_path))
+    secret: dict[str, object] = {}
+
+    def fake_set(tokens: dict[str, object]) -> bool:
+        secret.update(tokens)
+        return True
+
+    monkeypatch.setattr(auth, "_keyring_set", fake_set)
+    monkeypatch.setattr(auth, "_keyring_get", lambda: dict(secret))
+
+    auth.save_xai_oauth_credential(
+        auth.XaiOAuthCredential(
+            access_token="access",
+            refresh_token="refresh",
+            expires_at=123.0,
+            account_id="acct",
+        )
+    )
+
+    payload = json.loads(auth.get_xai_oauth_metadata_path().read_text(encoding="utf-8"))
+    assert payload["storage"] == "keyring"
+    assert "tokens" not in payload
+    assert auth.load_xai_oauth_credential().access_token == "access"
+
+
+def test_exchange_xai_oauth_code_sends_required_code_challenge(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    class FakeResponse:
+        status_code = 200
+        text = ""
+
+        def json(self) -> dict[str, object]:
+            return {"access_token": "access", "refresh_token": "refresh", "expires_in": 3600}
+
+    class FakeClient:
+        def __init__(self, *args, **kwargs) -> None:
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *args) -> None:
+            pass
+
+        def post(self, url: str, headers: dict[str, str], data: dict[str, str]) -> FakeResponse:
+            captured["url"] = url
+            captured["headers"] = headers
+            captured["data"] = data
+            return FakeResponse()
+
+    monkeypatch.setattr(auth.httpx, "Client", FakeClient)
+    endpoints = auth.XaiOAuthEndpoints(
+        authorization_endpoint="https://auth.x.ai/authorize",
+        token_endpoint="https://auth.x.ai/oauth/token",
+    )
+
+    credential = auth.exchange_xai_oauth_code("code", verifier="verifier", endpoints=endpoints)
+
+    assert credential.access_token == "access"
+    assert captured["url"] == "https://auth.x.ai/oauth/token"
+    data = captured["data"]
+    assert data["code_verifier"] == "verifier"
+    assert data["code_challenge"] == auth.pkce_challenge("verifier")
+    assert data["code_challenge_method"] == "S256"
+
+
+def test_rejects_non_xai_discovery_endpoints() -> None:
+    with pytest.raises(RuntimeError):
+        auth._validate_xai_endpoint("https://example.com/oauth/token", "token_endpoint")

tests/providers/test_xai_oauth_provider.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import asyncio
+
+from nanobot.config.schema import XaiOAuthXSearchConfig
+import nanobot.providers.xai_oauth_provider as xai_oauth_provider
+from nanobot.providers.xai_oauth_provider import (
+    XaiOAuthCredential,
+    XaiOAuthProvider,
+    _build_xai_responses_body,
+    _strip_model_prefix,
+)
+
+
+def test_xai_oauth_strip_prefix_supports_aliases() -> None:
+    assert _strip_model_prefix("xai-oauth/grok-4.3") == "grok-4.3"
+    assert _strip_model_prefix("xai_oauth/grok-4.3") == "grok-4.3"
+    assert _strip_model_prefix("grok-oauth/grok-4.3") == "grok-4.3"
+    assert _strip_model_prefix("grok-4.3") == "grok-4.3"
+
+
+def test_build_xai_responses_body_keeps_system_prompt_in_input() -> None:
+    body = _build_xai_responses_body(
+        messages=[
+            {"role": "system", "content": "You are nanobot."},
+            {"role": "user", "content": "hi"},
+        ],
+        tools=[
+            {
+                "type": "function",
+                "function": {
+                    "name": "ping",
+                    "description": "Ping",
+                    "parameters": {"type": "object", "properties": {}},
+                },
+            }
+        ],
+        model="xai-oauth/grok-4.3",
+        max_tokens=32,
+        temperature=0.2,
+        reasoning_effort="high",
+        tool_choice=None,
+    )
+
+    assert body["model"] == "grok-4.3"
+    assert "instructions" not in body
+    assert body["input"][0] == {
+        "role": "system",
+        "content": [{"type": "input_text", "text": "You are nanobot."}],
+    }
+    assert body["input"][1]["role"] == "user"
+    assert body["max_output_tokens"] == 32
+    assert body["temperature"] == 0.2
+    assert body["reasoning"] == {"effort": "high"}
+    assert body["tools"][0]["name"] == "ping"
+
+
+def test_build_xai_responses_body_attaches_hosted_x_search_by_default() -> None:
+    body = _build_xai_responses_body(
+        messages=[{"role": "user", "content": "what is happening on X?"}],
+        tools=None,
+        model="xai-oauth/grok-4.3",
+        max_tokens=32,
+        temperature=0.2,
+        reasoning_effort=None,
+        tool_choice=None,
+        hosted_x_search=XaiOAuthXSearchConfig(),
+    )
+
+    assert body["tools"] == [{"type": "x_search"}]
+
+
+def test_build_xai_responses_body_can_customize_hosted_x_search() -> None:
+    body = _build_xai_responses_body(
+        messages=[{"role": "user", "content": "what is happening on X?"}],
+        tools=None,
+        model="xai-oauth/grok-4.3",
+        max_tokens=32,
+        temperature=0.2,
+        reasoning_effort=None,
+        tool_choice=None,
+        hosted_x_search=XaiOAuthXSearchConfig(
+            allowed_x_handles=["@xai", " nanobot "],
+            enable_image_understanding=True,
+        ),
+    )
+
+    assert body["tools"] == [
+        {
+            "type": "x_search",
+            "allowed_x_handles": ["xai", "nanobot"],
+            "enable_image_understanding": True,
+        }
+    ]
+
+
+def test_build_xai_responses_body_omits_disabled_hosted_x_search() -> None:
+    body = _build_xai_responses_body(
+        messages=[{"role": "user", "content": "hi"}],
+        tools=None,
+        model="xai-oauth/grok-4.3",
+        max_tokens=32,
+        temperature=0.2,
+        reasoning_effort=None,
+        tool_choice=None,
+        hosted_x_search=XaiOAuthXSearchConfig(enable=False),
+    )
+
+    assert "tools" not in body
+
+
+def test_xai_oauth_provider_refreshes_once_on_401(monkeypatch) -> None:
+    async def run() -> None:
+        response = await provider.chat([{"role": "user", "content": "hi"}])
+
+        assert response.content == "ok"
+        assert response.finish_reason == "stop"
+        assert calls == [("resolve", False), ("resolve", True)]
+
+    provider = XaiOAuthProvider(default_model="xai-oauth/grok-4.3")
+    credentials = [
+        XaiOAuthCredential(access_token="expired"),
+        XaiOAuthCredential(access_token="fresh"),
+    ]
+    calls: list[tuple[str, bool]] = []
+
+    def fake_resolve(*, force_refresh: bool = False) -> XaiOAuthCredential:
+        calls.append(("resolve", force_refresh))
+        return credentials.pop(0)
+
+    async def fake_request(credential, body, on_content_delta=None, on_tool_call_delta=None):
+        from nanobot.providers.xai_oauth_provider import _XaiHTTPError
+
+        if credential.access_token == "expired":
+            raise _XaiHTTPError("expired", status_code=401)
+        return "ok", [], "stop"
+
+    monkeypatch.setattr(xai_oauth_provider, "resolve_xai_oauth_credential", fake_resolve)
+    monkeypatch.setattr(xai_oauth_provider, "_request_xai", fake_request)
+
+    asyncio.run(run())

tests/tools/test_exec_platform.py

@@ -5,6 +5,7 @@ strategy, and sandbox behaviour per platform — without actually running
 platform-specific binaries (all subprocess calls are mocked).
 """
 
+import asyncio
 import sys
 from unittest.mock import AsyncMock, patch
 
@@ -108,6 +109,9 @@ class TestSpawnUnix:
         assert "-c" in args
         assert "echo hi" in args
 
+        kwargs = mock_exec.call_args[1]
+        assert kwargs["stdin"] == asyncio.subprocess.DEVNULL
+
 
 class TestSpawnWindows:
 
@@ -124,6 +128,9 @@ class TestSpawnWindows:
         args = mock_shell.call_args[0]
         assert "dir" in args
 
+        kwargs = mock_shell.call_args[1]
+        assert kwargs["stdin"] == asyncio.subprocess.DEVNULL
+
     @pytest.mark.asyncio
     async def test_passes_cwd_and_env(self):
         env = {"PATH": "/usr/bin"}

tests/tools/test_image_generation_tool.py

@@ -44,8 +44,8 @@ async def test_generate_image_tool_stores_artifact_and_source_images(
     set_config_path(tmp_path / "config.json")
     FakeImageClient.instances = []
     monkeypatch.setattr(
-        "nanobot.agent.tools.image_generation.OpenRouterImageGenerationClient",
+        "nanobot.agent.tools.image_generation.get_image_gen_provider",
-        FakeImageClient,
+        lambda name: FakeImageClient if name == "openrouter" else None,
     )
     ref = tmp_path / "ref.png"
     ref.write_bytes(PNG_BYTES)
@@ -98,8 +98,8 @@ async def test_generate_image_tool_selects_aihubmix_provider(
     set_config_path(tmp_path / "config.json")
     FakeImageClient.instances = []
     monkeypatch.setattr(
-        "nanobot.agent.tools.image_generation.AIHubMixImageGenerationClient",
+        "nanobot.agent.tools.image_generation.get_image_gen_provider",
-        FakeImageClient,
+        lambda name: FakeImageClient if name == "aihubmix" else None,
     )
     tool = ImageGenerationTool(
         workspace=tmp_path,

tests/utils/test_artifacts.py

@@ -10,8 +10,6 @@ from nanobot.config.loader import set_config_path
 from nanobot.utils.artifacts import (
     ArtifactError,
     decode_image_data_url,
-    generated_image_paths_from_messages,
-    generated_image_tool_result,
     store_generated_image_artifact,
 )
 
@@ -66,22 +64,3 @@ def test_store_generated_image_artifact_rejects_unsafe_save_dir(tmp_path: Path)
             model="m",
             save_dir="../outside",
         )
-
-
-def test_generated_image_paths_from_tool_results() -> None:
-    result = generated_image_tool_result(
-        [
-            {"id": "img_1", "path": "/tmp/one.png"},
-            {"id": "img_2", "path": "/tmp/two.png"},
-        ]
-    )
-    payload = json.loads(result)
-
-    assert generated_image_paths_from_messages(
-        [
-            {"role": "tool", "name": "generate_image", "content": result},
-            {"role": "tool", "name": "other", "content": result},
-        ]
-    ) == ["/tmp/one.png", "/tmp/two.png"]
-    assert "runtime attaches generated images automatically" in payload["next_step"]
-    assert "Do not call message" in payload["next_step"]

tests/utils/test_file_edit_events.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import asyncio
 from pathlib import Path
+from types import SimpleNamespace
 
 from nanobot.utils.file_edit_events import (
     build_file_edit_end_event,
@@ -8,6 +10,7 @@ from nanobot.utils.file_edit_events import (
     line_diff_stats,
     prepare_file_edit_tracker,
     read_file_snapshot,
+    StreamingFileEditTracker,
 )
 
 
@@ -20,6 +23,10 @@ def test_line_diff_stats_normalizes_crlf() -> None:
     assert line_diff_stats("a\r\nb\r\n", "a\nb\nc\n") == (1, 0)
 
 
+def test_line_diff_stats_counts_new_file_crlf_lines_once() -> None:
+    assert line_diff_stats("", "a\r\nb\r\n") == (2, 0)
+
+
 def test_write_file_start_predicts_and_end_calibrates_exact_diff(tmp_path: Path) -> None:
     target = tmp_path / "notes.txt"
     target.write_text("old\nkeep\n", encoding="utf-8")
@@ -39,6 +46,7 @@ def test_write_file_start_predicts_and_end_calibrates_exact_diff(tmp_path: Path)
         "call_id": "call-write",
         "tool": "write_file",
         "path": "notes.txt",
+        "absolute_path": (tmp_path / "notes.txt").resolve().as_posix(),
         "phase": "start",
         "added": 2,
         "deleted": 1,
@@ -73,6 +81,307 @@ def test_binary_file_is_reported_but_not_counted(tmp_path: Path) -> None:
     assert (event["added"], event["deleted"]) == (0, 0)
 
 
+def test_oversized_write_file_end_uses_known_content_for_exact_count(tmp_path: Path) -> None:
+    target = tmp_path / "large.txt"
+    params = {"path": "large.txt", "content": "x" * (2 * 1024 * 1024 + 1)}
+    tracker = prepare_file_edit_tracker(
+        call_id="call-large",
+        tool_name="write_file",
+        tool=None,
+        workspace=tmp_path,
+        params=params,
+    )
+
+    assert tracker is not None
+    target.write_text(params["content"], encoding="utf-8")
+    event = build_file_edit_end_event(tracker, params)
+    assert event.get("binary") is not True
+    assert event["added"] == 1
+    assert event["deleted"] == 0
+
+
+def test_streaming_write_file_tracker_emits_live_line_counts(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-live",
+            "name": "write_file",
+            "arguments_delta": '{"path":"notes.md","content":"',
+        })
+        await tracker.update({
+            "index": 0,
+            "arguments_delta": "line\\n" * 24,
+        })
+
+    asyncio.run(run())
+
+    assert events[0] == {
+        "version": 1,
+        "call_id": "call-live",
+        "tool": "write_file",
+        "path": "notes.md",
+        "absolute_path": (tmp_path / "notes.md").resolve().as_posix(),
+        "phase": "start",
+        "added": 0,
+        "deleted": 0,
+        "approximate": True,
+        "status": "editing",
+    }
+    assert events[-1]["path"] == "notes.md"
+    assert events[-1]["status"] == "editing"
+    assert events[-1]["approximate"] is True
+    assert events[-1]["added"] == 24
+    assert events[-1]["deleted"] == 0
+
+
+def test_streaming_write_file_tracker_emits_pending_before_path(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-live",
+            "name": "write_file",
+            "arguments_delta": '{"content":"line\\n',
+        })
+        await tracker.update({
+            "index": 0,
+            "arguments_delta": 'more\\n","path":"late.md"',
+        })
+
+    asyncio.run(run())
+
+    assert events[0] == {
+        "version": 1,
+        "call_id": "call-live",
+        "tool": "write_file",
+        "path": "",
+        "phase": "start",
+        "added": 1,
+        "deleted": 0,
+        "approximate": True,
+        "status": "editing",
+        "pending": True,
+    }
+    assert events[-1]["path"] == "late.md"
+    assert events[-1].get("pending") is not True
+    assert events[-1]["added"] == 2
+
+
+def test_streaming_write_file_tracker_flushes_small_pending_count(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-live",
+            "name": "write_file",
+            "arguments_delta": '{"path":"small.md","content":"one\\n',
+        })
+        await tracker.flush()
+
+    asyncio.run(run())
+    assert events
+    assert events[-1]["path"] == "small.md"
+    assert events[-1]["added"] == 1
+
+
+def test_streaming_write_file_tracker_normalizes_crlf_line_counts(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-live",
+            "name": "write_file",
+            "arguments_delta": '{"path":"windows.txt","content":"one\\r\\ntwo\\r\\n',
+        })
+        await tracker.flush()
+
+    asyncio.run(run())
+    assert events[-1]["path"] == "windows.txt"
+    assert events[-1]["added"] == 2
+
+
+def test_streaming_write_file_tracker_counts_unicode_escaped_newlines(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-live",
+            "name": "write_file",
+            "arguments_delta": '{"path":"unicode.txt","content":"one\\u000atwo',
+        })
+        await tracker.flush()
+
+    asyncio.run(run())
+    assert events[-1]["path"] == "unicode.txt"
+    assert events[-1]["added"] == 2
+
+
+def test_streaming_edit_file_tracker_emits_live_line_counts(tmp_path: Path) -> None:
+    target = tmp_path / "notes.md"
+    target.write_text("old\nkeep\n", encoding="utf-8")
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-edit",
+            "name": "edit_file",
+            "arguments_delta": '{"path":"notes.md","old_text":"old\\nkeep","new_text":"',
+        })
+        await tracker.update({
+            "index": 0,
+            "arguments_delta": "new\\nkeep\\nextra\\n" * 8,
+        })
+
+    asyncio.run(run())
+
+    assert events[0] == {
+        "version": 1,
+        "call_id": "call-edit",
+        "tool": "edit_file",
+        "path": "notes.md",
+        "absolute_path": (tmp_path / "notes.md").resolve().as_posix(),
+        "phase": "start",
+        "added": 0,
+        "deleted": 2,
+        "approximate": True,
+        "status": "editing",
+    }
+    assert events[-1]["path"] == "notes.md"
+    assert events[-1]["status"] == "editing"
+    assert events[-1]["approximate"] is True
+    assert events[-1]["added"] == 24
+    assert events[-1]["deleted"] == 2
+
+
+def test_streaming_tracker_applies_canonical_call_id_to_final_tool(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "name": "write_file",
+            "arguments_delta": '{"path":"matched.md","content":"one\\n',
+        })
+        final = SimpleNamespace(
+            id="provider-final-id",
+            name="write_file",
+            arguments={"path": "matched.md", "content": "one\n"},
+        )
+        tracker.apply_final_call_ids([final])
+        assert final.id == "idx:0"
+
+    asyncio.run(run())
+
+
+def test_streaming_edit_file_tracker_flushes_small_pending_count(tmp_path: Path) -> None:
+    target = tmp_path / "small.py"
+    target.write_text("old\n", encoding="utf-8")
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-edit",
+            "name": "edit_file",
+            "arguments_delta": '{"path":"small.py","old_text":"old\\n","new_text":"new\\nextra',
+        })
+        await tracker.flush()
+
+    asyncio.run(run())
+    assert events
+    assert events[-1]["path"] == "small.py"
+    assert events[-1]["added"] == 2
+    assert events[-1]["deleted"] == 1
+
+
+def test_streaming_write_file_tracker_errors_unmatched_live_edits(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "call-live",
+            "name": "write_file",
+            "arguments_delta": '{"path":"aborted.md","content":"one\\n',
+        })
+        await tracker.error_unmatched([], "Tool call did not complete.")
+
+    asyncio.run(run())
+    assert events[-1]["path"] == "aborted.md"
+    assert events[-1]["phase"] == "error"
+    assert events[-1]["status"] == "error"
+
+
+def test_streaming_write_file_tracker_keeps_matched_final_tool_call(tmp_path: Path) -> None:
+    events: list[dict] = []
+
+    async def emit(batch: list[dict]) -> None:
+        events.extend(batch)
+
+    async def run() -> None:
+        tracker = StreamingFileEditTracker(workspace=tmp_path, tools={}, emit=emit)
+        await tracker.update({
+            "index": 0,
+            "call_id": "idx-only",
+            "name": "write_file",
+            "arguments_delta": '{"path":"matched.md","content":"one\\n',
+        })
+        await tracker.error_unmatched([
+            SimpleNamespace(
+                id="final-call",
+                name="write_file",
+                arguments={"path": "matched.md", "content": "one\n"},
+            )
+        ], "Tool call did not complete.")
+
+    asyncio.run(run())
+    assert events
+    assert all(event["status"] == "editing" for event in events)
+
+
 def test_untracked_tools_do_not_prepare_file_edit_tracker(tmp_path: Path) -> None:
     assert prepare_file_edit_tracker(
         call_id="call-exec",

tests/utils/test_webui_compat_imports.py

@@ -0,0 +1,14 @@
+import importlib
+
+from nanobot.session import webui_turns
+from nanobot.webui import thread_disk, transcript
+
+
+def test_legacy_webui_utils_imports_resolve_to_new_modules() -> None:
+    legacy_thread_disk = importlib.import_module("nanobot.utils.webui_thread_disk")
+    legacy_transcript = importlib.import_module("nanobot.utils.webui_transcript")
+    legacy_turn_helpers = importlib.import_module("nanobot.utils.webui_turn_helpers")
+
+    assert legacy_thread_disk.delete_webui_thread is thread_disk.delete_webui_thread
+    assert legacy_transcript.append_transcript_object is transcript.append_transcript_object
+    assert legacy_turn_helpers.mark_webui_session is webui_turns.mark_webui_session

tests/utils/test_webui_sidebar_state.py

@@ -0,0 +1,73 @@
+import json
+
+from nanobot.webui.sidebar_state import (
+    default_webui_sidebar_state,
+    read_webui_sidebar_state,
+    webui_sidebar_state_path,
+    write_webui_sidebar_state,
+)
+
+
+def test_sidebar_state_defaults_when_file_missing(tmp_path, monkeypatch) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+
+    state = read_webui_sidebar_state()
+
+    assert state == default_webui_sidebar_state()
+    assert webui_sidebar_state_path() == tmp_path / "webui" / "sidebar-state.json"
+
+
+def test_sidebar_state_normalizes_old_or_partial_payload(tmp_path, monkeypatch) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    path = webui_sidebar_state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(
+            {
+                "pinned_keys": ["websocket:a", "websocket:a", "", 123],
+                "archived_keys": ["websocket:b"],
+                "title_overrides": {"websocket:a": "  Release notes  ", "bad": ""},
+                "tags_by_key": {"websocket:a": ["work", "work", ""]},
+                "collapsed_groups": {"Earlier": 1},
+                "view": {"density": "tiny", "show_archived": True, "sort": "nope"},
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    state = read_webui_sidebar_state()
+
+    assert state["schema_version"] == 1
+    assert state["pinned_keys"] == ["websocket:a"]
+    assert state["archived_keys"] == ["websocket:b"]
+    assert state["title_overrides"] == {"websocket:a": "Release notes"}
+    assert state["tags_by_key"] == {"websocket:a": ["work"]}
+    assert state["collapsed_groups"] == {"Earlier": True}
+    assert state["view"] == {
+        "density": "comfortable",
+        "show_previews": False,
+        "show_timestamps": False,
+        "show_archived": True,
+        "sort": "updated_desc",
+    }
+
+
+def test_sidebar_state_write_is_scoped_to_config_data_dir(tmp_path, monkeypatch) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+
+    state = write_webui_sidebar_state(
+        {
+            "pinned_keys": ["websocket:a"],
+            "archived_keys": ["websocket:b"],
+            "title_overrides": {"websocket:a": "Release"},
+            "view": {"density": "compact", "show_previews": True},
+        }
+    )
+
+    assert state["pinned_keys"] == ["websocket:a"]
+    assert state["archived_keys"] == ["websocket:b"]
+    assert state["title_overrides"] == {"websocket:a": "Release"}
+    assert state["view"]["density"] == "compact"
+    assert state["view"]["show_previews"] is True
+    assert webui_sidebar_state_path().is_file()
+    assert read_webui_sidebar_state()["pinned_keys"] == ["websocket:a"]

tests/utils/test_webui_thread_disk.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from nanobot.utils.webui_thread_disk import delete_webui_thread, webui_thread_file_path
+from nanobot.webui.thread_disk import delete_webui_thread, webui_thread_file_path
-from nanobot.utils.webui_transcript import append_transcript_object, webui_transcript_path
+from nanobot.webui.transcript import append_transcript_object, webui_transcript_path
 
 
 def test_delete_webui_thread_removes_legacy_json_and_transcript(tmp_path, monkeypatch) -> None:

tests/utils/test_webui_transcript.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from nanobot.utils.webui_transcript import (
+from nanobot.webui.transcript import (
     WEBUI_TRANSCRIPT_SCHEMA_VERSION,
     append_transcript_object,
     read_transcript_lines,
@@ -98,8 +98,250 @@ def test_replay_file_edit_event_creates_file_activity(tmp_path, monkeypatch) ->
     assert msgs[2]["activitySegmentId"] != msgs[1]["activitySegmentId"]
 
 
+def test_replay_tool_events_dedupes_finish_after_start() -> None:
+    msgs = replay_transcript_to_ui_messages([
+        {
+            "event": "message",
+            "chat_id": "t-tool",
+            "text": 'exec({"cmd":"ls"})',
+            "kind": "tool_hint",
+            "tool_events": [
+                {
+                    "phase": "start",
+                    "call_id": "call-exec",
+                    "name": "exec",
+                    "arguments": {"cmd": "ls"},
+                },
+            ],
+        },
+        {
+            "event": "message",
+            "chat_id": "t-tool",
+            "text": "",
+            "kind": "progress",
+            "tool_events": [
+                {
+                    "phase": "end",
+                    "call_id": "call-exec",
+                    "name": "exec",
+                    "arguments": {"cmd": "ls"},
+                    "result": "ok",
+                },
+                {
+                    "phase": "end",
+                    "call_id": "call-read",
+                    "name": "read_file",
+                    "arguments": {"path": "notes.md"},
+                    "result": "done",
+                },
+            ],
+        },
+    ])
+
+    assert len(msgs) == 1
+    assert msgs[0]["traces"] == [
+        'exec({"cmd": "ls"})',
+        'read_file({"path": "notes.md"})',
+    ]
+
+
+def test_replay_file_edit_progress_merges_after_interleaved_activity(tmp_path, monkeypatch) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    key = "websocket:t-file-progress"
+    for ev in (
+        {"event": "user", "chat_id": "t-file-progress", "text": "edit"},
+        {
+            "event": "message",
+            "chat_id": "t-file-progress",
+            "text": 'write_file({"path":"foo.txt"})',
+            "kind": "tool_hint",
+        },
+        {
+            "event": "file_edit",
+            "chat_id": "t-file-progress",
+            "edits": [
+                {
+                    "version": 1,
+                    "call_id": "call-write",
+                    "tool": "write_file",
+                    "path": "foo.txt",
+                    "phase": "start",
+                    "added": 12,
+                    "deleted": 0,
+                    "approximate": True,
+                    "status": "editing",
+                },
+            ],
+        },
+        {
+            "event": "message",
+            "chat_id": "t-file-progress",
+            "text": "still working",
+            "kind": "progress",
+        },
+        {
+            "event": "file_edit",
+            "chat_id": "t-file-progress",
+            "edits": [
+                {
+                    "version": 1,
+                    "call_id": "call-write",
+                    "tool": "write_file",
+                    "path": "foo.txt",
+                    "phase": "end",
+                    "added": 30,
+                    "deleted": 0,
+                    "approximate": False,
+                    "status": "done",
+                },
+            ],
+        },
+    ):
+        append_transcript_object(key, ev)
+
+    msgs = replay_transcript_to_ui_messages(read_transcript_lines(key))
+    file_edit_messages = [msg for msg in msgs if msg.get("fileEdits")]
+
+    assert len(file_edit_messages) == 1
+    assert file_edit_messages[0]["fileEdits"] == [
+        {
+            "version": 1,
+            "call_id": "call-write",
+            "tool": "write_file",
+            "path": "foo.txt",
+            "phase": "end",
+            "added": 30,
+            "deleted": 0,
+            "approximate": False,
+            "status": "done",
+        },
+    ]
+
+
+def test_replay_file_edit_pending_placeholder_upgrades_to_path(tmp_path, monkeypatch) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    key = "websocket:t-file-pending"
+    for ev in (
+        {"event": "user", "chat_id": "t-file-pending", "text": "write"},
+        {
+            "event": "file_edit",
+            "chat_id": "t-file-pending",
+            "edits": [
+                {
+                    "version": 1,
+                    "call_id": "call-write",
+                    "tool": "write_file",
+                    "path": "",
+                    "phase": "start",
+                    "added": 1,
+                    "deleted": 0,
+                    "approximate": True,
+                    "status": "editing",
+                    "pending": True,
+                },
+            ],
+        },
+        {
+            "event": "file_edit",
+            "chat_id": "t-file-pending",
+            "edits": [
+                {
+                    "version": 1,
+                    "call_id": "call-write",
+                    "tool": "write_file",
+                    "path": "foo.txt",
+                    "phase": "start",
+                    "added": 12,
+                    "deleted": 0,
+                    "approximate": True,
+                    "status": "editing",
+                },
+            ],
+        },
+    ):
+        append_transcript_object(key, ev)
+
+    msgs = replay_transcript_to_ui_messages(read_transcript_lines(key))
+    file_edit_messages = [msg for msg in msgs if msg.get("fileEdits")]
+
+    assert len(file_edit_messages) == 1
+    assert file_edit_messages[0]["fileEdits"] == [
+        {
+            "version": 1,
+            "call_id": "call-write",
+            "tool": "write_file",
+            "path": "foo.txt",
+            "phase": "start",
+            "added": 12,
+            "deleted": 0,
+            "approximate": True,
+            "status": "editing",
+        },
+    ]
+
+
+def test_replay_keeps_new_file_edit_after_reasoning_in_order(tmp_path, monkeypatch) -> None:
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    key = "websocket:t-file-order"
+    for ev in (
+        {"event": "user", "chat_id": "t-file-order", "text": "edit"},
+        {
+            "event": "file_edit",
+            "chat_id": "t-file-order",
+            "edits": [
+                {
+                    "version": 1,
+                    "call_id": "call-one",
+                    "tool": "write_file",
+                    "path": "one.txt",
+                    "phase": "start",
+                    "added": 10,
+                    "deleted": 0,
+                    "approximate": True,
+                    "status": "editing",
+                },
+            ],
+        },
+        {"event": "reasoning_delta", "chat_id": "t-file-order", "text": "Check next."},
+        {"event": "reasoning_end", "chat_id": "t-file-order"},
+        {
+            "event": "file_edit",
+            "chat_id": "t-file-order",
+            "edits": [
+                {
+                    "version": 1,
+                    "call_id": "call-two",
+                    "tool": "write_file",
+                    "path": "two.txt",
+                    "phase": "start",
+                    "added": 20,
+                    "deleted": 0,
+                    "approximate": True,
+                    "status": "editing",
+                },
+            ],
+        },
+    ):
+        append_transcript_object(key, ev)
+
+    msgs = replay_transcript_to_ui_messages(read_transcript_lines(key))
+
+    assert [msg.get("fileEdits", [{}])[0].get("path") if msg.get("fileEdits") else msg.get("reasoning") for msg in msgs[1:]] == [
+        "one.txt",
+        "Check next.",
+        "two.txt",
+    ]
+    file_edit_segments = [
+        msg.get("activitySegmentId")
+        for msg in msgs
+        if msg.get("fileEdits")
+    ]
+    assert len(file_edit_segments) == 2
+    assert file_edit_segments[0] != file_edit_segments[1]
+
+
 def test_build_response_schema(monkeypatch, tmp_path) -> None:
-    from nanobot.utils.webui_transcript import build_webui_thread_response
+    from nanobot.webui.transcript import build_webui_thread_response
 
     monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
     key = "websocket:t3"

tests/utils/test_webui_turn_helpers.py

@@ -5,7 +5,7 @@ from unittest.mock import AsyncMock, MagicMock
 import pytest
 
 from nanobot.bus.events import InboundMessage
-from nanobot.utils import webui_turn_helpers as wth
+from nanobot.session import webui_turns as wth
 
 
 @pytest.fixture(autouse=True)

webui/package-lock.json

@@ -26,6 +26,7 @@
         "react-markdown": "^9.0.1",
         "react-syntax-highlighter": "^15.6.1",
         "rehype-katex": "^7.0.1",
+        "remark-breaks": "^4.0.0",
         "remark-gfm": "^4.0.0",
         "remark-math": "^6.0.0",
         "tailwind-merge": "^2.6.0"
@@ -3922,6 +3923,20 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdast-util-newline-to-break": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-newline-to-break/-/mdast-util-newline-to-break-2.0.0.tgz",
+      "integrity": "sha512-MbgeFca0hLYIEx/2zGsszCSEJJ1JSCdiY5xQxRcLDDGa8EPvlLPupJ4DSajbMPAnC0je8jfb9TiUATnxxrHUog==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-find-and-replace": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/mdast-util-phrasing": {
       "version": "4.1.0",
       "license": "MIT",
@@ -5141,6 +5156,21 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/remark-breaks": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/remark-breaks/-/remark-breaks-4.0.0.tgz",
+      "integrity": "sha512-IjEjJOkH4FuJvHZVIW0QCDWxcG96kCq7An/KVH2NfJe6rKZU2AsHeB3OEjPNRxi4QC34Xdx7I2KGYn6IpT7gxQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-newline-to-break": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/remark-gfm": {
       "version": "4.0.1",
       "license": "MIT",

webui/src/App.tsx

@@ -1,13 +1,16 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { DeleteConfirm } from "@/components/DeleteConfirm";
+import { RenameChatDialog } from "@/components/RenameChatDialog";
 import { Sidebar } from "@/components/Sidebar";
+import { SessionSearchDialog } from "@/components/SessionSearchDialog";
 import { SettingsView } from "@/components/settings/SettingsView";
 import { ThreadShell } from "@/components/thread/ThreadShell";
-import { Sheet, SheetContent } from "@/components/ui/sheet";
+import { Sheet, SheetContent, SheetTitle } from "@/components/ui/sheet";
 
 import { useSessions } from "@/hooks/useSessions";
 import { useDeferredTitleRefresh } from "@/hooks/useDeferredTitleRefresh";
+import { useSidebarState } from "@/hooks/useSidebarState";
 import { ThemeProvider, useTheme } from "@/hooks/useTheme";
 import { cn } from "@/lib/utils";
 import {
@@ -37,6 +40,7 @@ type BootState =
     };
 
 const SIDEBAR_STORAGE_KEY = "nanobot-webui.sidebar";
+const COMPLETED_RUNS_STORAGE_KEY = "nanobot-webui.sidebar.completed-runs.v1";
 const RESTART_STARTED_KEY = "nanobot-webui.restartStartedAt";
 const SIDEBAR_WIDTH = 272;
 const TOKEN_REFRESH_MARGIN_MS = 30_000;
@@ -121,6 +125,29 @@ function readSidebarOpen(): boolean {
   }
 }
 
+function readCompletedRunChatIds(): Set<string> {
+  if (typeof window === "undefined") return new Set();
+  try {
+    const raw = window.localStorage.getItem(COMPLETED_RUNS_STORAGE_KEY);
+    const parsed = raw ? JSON.parse(raw) : [];
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(parsed.filter((item): item is string => typeof item === "string"));
+  } catch {
+    return new Set();
+  }
+}
+
+function writeCompletedRunChatIds(chatIds: Set<string>): void {
+  try {
+    window.localStorage.setItem(
+      COMPLETED_RUNS_STORAGE_KEY,
+      JSON.stringify(Array.from(chatIds)),
+    );
+  } catch {
+    // ignore storage errors (private mode, etc.)
+  }
+}
+
 export default function App() {
   const { t } = useTranslation();
   const [state, setState] = useState<BootState>({ status: "loading" });
@@ -293,18 +320,28 @@ function Shell({
   const { client } = useClient();
   const { theme, toggle } = useTheme();
   const { sessions, loading, refresh, createChat, deleteChat } = useSessions();
+  const { state: sidebarState, update: updateSidebarState } =
+    useSidebarState(sessions, !loading);
   const [activeKey, setActiveKey] = useState<string | null>(null);
   const [view, setView] = useState<ShellView>("chat");
   const [desktopSidebarOpen, setDesktopSidebarOpen] =
     useState<boolean>(readSidebarOpen);
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
+  const [sessionSearchOpen, setSessionSearchOpen] = useState(false);
   const [pendingDelete, setPendingDelete] = useState<{
     key: string;
     label: string;
   } | null>(null);
+  const [pendingRename, setPendingRename] = useState<{
+    key: string;
+    label: string;
+  } | null>(null);
   const restartSawDisconnectRef = useRef(false);
   const [restartToast, setRestartToast] = useState<string | null>(null);
   const [isRestarting, setIsRestarting] = useState(false);
+  const [runningChatIds, setRunningChatIds] = useState<Set<string>>(() => new Set());
+  const [completedChatIds, setCompletedChatIds] = useState<Set<string>>(readCompletedRunChatIds);
+  const runningChatIdsRef = useRef<Set<string>>(new Set());
 
   useEffect(() => {
     try {
@@ -317,12 +354,58 @@ function Shell({
     }
   }, [desktopSidebarOpen]);
 
-
+  useEffect(() => {
+    writeCompletedRunChatIds(completedChatIds);
+  }, [completedChatIds]);
 
   const activeSession = useMemo<ChatSummary | null>(() => {
     if (!activeKey) return null;
     return sessions.find((s) => s.key === activeKey) ?? null;
   }, [sessions, activeKey]);
+  const runningChatIdList = useMemo(() => Array.from(runningChatIds), [runningChatIds]);
+  const completedChatIdList = useMemo(() => Array.from(completedChatIds), [completedChatIds]);
+
+  useEffect(() => {
+    if (loading) return;
+    const knownChatIds = new Set(sessions.map((session) => session.chatId));
+    setCompletedChatIds((current) => {
+      const next = new Set(
+        Array.from(current).filter((chatId) => knownChatIds.has(chatId)),
+      );
+      return next.size === current.size ? current : next;
+    });
+  }, [loading, sessions]);
+
+  useEffect(() => {
+    if (loading) return;
+    const activeRunIds = sessions
+      .filter((session) => typeof session.runStartedAt === "number")
+      .map((session) => session.chatId);
+    if (activeRunIds.length === 0) return;
+
+    for (const chatId of activeRunIds) {
+      client.attach(chatId);
+    }
+    setRunningChatIds((current) => {
+      let changed = false;
+      const next = new Set(current);
+      for (const chatId of activeRunIds) {
+        if (!next.has(chatId)) changed = true;
+        next.add(chatId);
+      }
+      if (!changed) return current;
+      runningChatIdsRef.current = next;
+      return next;
+    });
+    setCompletedChatIds((current) => {
+      let changed = false;
+      const next = new Set(current);
+      for (const chatId of activeRunIds) {
+        if (next.delete(chatId)) changed = true;
+      }
+      return changed ? next : current;
+    });
+  }, [client, loading, sessions]);
 
   const closeDesktopSidebar = useCallback(() => {
     setDesktopSidebarOpen(false);
@@ -364,14 +447,129 @@ function Shell({
 
   const onSelectChat = useCallback(
     (key: string) => {
+      const selectedChatId = sessions.find((session) => session.key === key)?.chatId;
+      if (selectedChatId) {
+        setCompletedChatIds((current) => {
+          if (!current.has(selectedChatId)) return current;
+          const next = new Set(current);
+          next.delete(selectedChatId);
+          return next;
+        });
+      }
       setActiveKey(key);
       setView("chat");
       setMobileSidebarOpen(false);
     },
-    [],
+    [sessions],
+  );
+
+  const onTogglePin = useCallback(
+    (key: string) => {
+      void updateSidebarState((current) => {
+        const pinned = new Set(current.pinned_keys);
+        if (pinned.has(key)) {
+          pinned.delete(key);
+        } else {
+          pinned.add(key);
+        }
+        return {
+          ...current,
+          pinned_keys: Array.from(pinned),
+        };
+      });
+    },
+    [updateSidebarState],
+  );
+
+  const onRequestRename = useCallback((key: string, label: string) => {
+    setPendingRename({ key, label });
+  }, []);
+
+  const onConfirmRename = useCallback(
+    (title: string) => {
+      if (!pendingRename) return;
+      const key = pendingRename.key;
+      setPendingRename(null);
+      void updateSidebarState((current) => {
+        const titleOverrides = { ...current.title_overrides };
+        const cleaned = title.trim();
+        if (cleaned) {
+          titleOverrides[key] = cleaned;
+        } else {
+          delete titleOverrides[key];
+        }
+        return {
+          ...current,
+          title_overrides: titleOverrides,
+        };
+      });
+    },
+    [pendingRename, updateSidebarState],
+  );
+
+  const onToggleArchive = useCallback(
+    (key: string) => {
+      void updateSidebarState((current) => {
+        const archived = new Set(current.archived_keys);
+        const pinned = current.pinned_keys.filter((item) => item !== key);
+        if (archived.has(key)) {
+          archived.delete(key);
+        } else {
+          archived.add(key);
+        }
+        return {
+          ...current,
+          pinned_keys: pinned,
+          archived_keys: Array.from(archived),
+        };
+      });
+      if (activeKey === key && !sidebarState.archived_keys.includes(key)) {
+        const archived = new Set([...sidebarState.archived_keys, key]);
+        const next = sessions.find((session) => !archived.has(session.key));
+        setActiveKey(next?.key ?? null);
+      }
+    },
+    [activeKey, sessions, sidebarState.archived_keys, updateSidebarState],
+  );
+
+  const onToggleArchived = useCallback(() => {
+    void updateSidebarState((current) => ({
+      ...current,
+      view: {
+        ...current.view,
+        show_archived: !current.view.show_archived,
+      },
+    }));
+  }, [updateSidebarState]);
+
+  const onUpdateSidebarView = useCallback(
+    (viewUpdate: Partial<typeof sidebarState.view>) => {
+      void updateSidebarState((current) => ({
+        ...current,
+        view: {
+          ...current.view,
+          ...viewUpdate,
+        },
+      }));
+    },
+    [updateSidebarState],
+  );
+
+  const onOpenSessionSearch = useCallback(() => {
+    setMobileSidebarOpen(false);
+    setSessionSearchOpen(true);
+  }, []);
+
+  const onSelectSearchResult = useCallback(
+    (key: string) => {
+      setSessionSearchOpen(false);
+      onSelectChat(key);
+    },
+    [onSelectChat],
   );
 
   const onOpenSettings = useCallback(() => {
+    setSessionSearchOpen(false);
     setView("settings");
     setMobileSidebarOpen(false);
   }, []);
@@ -405,6 +603,35 @@ function Shell({
     });
   }, [client, onModelNameChange]);
 
+  useEffect(() => {
+    return client.onRunStatus((chatId, startedAt) => {
+      if (startedAt != null) {
+        const nextRunning = new Set(runningChatIdsRef.current);
+        nextRunning.add(chatId);
+        runningChatIdsRef.current = nextRunning;
+        setRunningChatIds(nextRunning);
+        setCompletedChatIds((current) => {
+          if (!current.has(chatId)) return current;
+          const next = new Set(current);
+          next.delete(chatId);
+          return next;
+        });
+        return;
+      }
+
+      if (!runningChatIdsRef.current.has(chatId)) return;
+      const nextRunning = new Set(runningChatIdsRef.current);
+      nextRunning.delete(chatId);
+      runningChatIdsRef.current = nextRunning;
+      setRunningChatIds(nextRunning);
+      setCompletedChatIds((current) => {
+        const next = new Set(current);
+        next.add(chatId);
+        return next;
+      });
+    });
+  }, [client]);
+
   useEffect(() => {
     return client.onStatus((status) => {
       let startedAt = 0;
@@ -452,7 +679,8 @@ function Shell({
   }, [pendingDelete, deleteChat, activeKey, sessions]);
 
   const headerTitle = activeSession
-    ? activeSession.title ||
+    ? sidebarState.title_overrides[activeSession.key] ||
+      activeSession.title ||
       deriveTitle(activeSession.preview, t("chat.newChat"))
     : t("app.brand");
 
@@ -476,7 +704,21 @@ function Shell({
     onSelect: onSelectChat,
     onRequestDelete: (key: string, label: string) =>
       setPendingDelete({ key, label }),
+    onTogglePin,
+    onRequestRename,
+    onToggleArchive,
     onOpenSettings,
+    onOpenSearch: onOpenSessionSearch,
+    onToggleArchived,
+    onUpdateView: onUpdateSidebarView,
+    pinnedKeys: sidebarState.pinned_keys,
+    archivedKeys: sidebarState.archived_keys,
+    titleOverrides: sidebarState.title_overrides,
+    runningChatIds: runningChatIdList,
+    completedChatIds: completedChatIdList,
+    viewState: sidebarState.view,
+    showArchived: sidebarState.view.show_archived,
+    archivedCount: sidebarState.archived_keys.length,
   };
   const showMainSidebar = view !== "settings";
 
@@ -513,14 +755,32 @@ function Shell({
             <SheetContent
               side="left"
               showCloseButton={false}
+              aria-describedby={undefined}
               className="p-0 lg:hidden"
               style={{ width: SIDEBAR_WIDTH, maxWidth: SIDEBAR_WIDTH }}
             >
-              <Sidebar {...sidebarProps} onCollapse={closeMobileSidebar} />
+              <SheetTitle className="sr-only">{t("sidebar.navigation")}</SheetTitle>
+              <Sidebar
+                {...sidebarProps}
+                onCollapse={closeMobileSidebar}
+                containActionMenus
+              />
             </SheetContent>
           </Sheet>
         ) : null}
 
+        {showMainSidebar ? (
+          <SessionSearchDialog
+            open={sessionSearchOpen}
+            onOpenChange={setSessionSearchOpen}
+            sessions={sessions}
+            activeKey={activeKey}
+            loading={loading}
+            titleOverrides={sidebarState.title_overrides}
+            onSelect={onSelectSearchResult}
+          />
+        ) : null}
+
         <main className="relative flex h-full min-w-0 flex-1 flex-col">
           <div
             className={cn(
@@ -561,6 +821,12 @@ function Shell({
           onCancel={() => setPendingDelete(null)}
           onConfirm={onConfirmDelete}
         />
+        <RenameChatDialog
+          open={!!pendingRename}
+          title={pendingRename?.label ?? ""}
+          onCancel={() => setPendingRename(null)}
+          onConfirm={onConfirmRename}
+        />
         {restartToast ? (
           <div
             role="status"

webui/src/components/ChatList.tsx

@@ -1,4 +1,12 @@
-import { MoreHorizontal, Trash2 } from "lucide-react";
+import {
+  Archive,
+  ArchiveRestore,
+  MoreHorizontal,
+  Pencil,
+  Pin,
+  PinOff,
+  Trash2,
+} from "lucide-react";
 import { useTranslation } from "react-i18next";
 
 import {
@@ -7,15 +15,29 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { deriveTitle } from "@/lib/format";
+import { deriveTitle, relativeTime } from "@/lib/format";
 import { cn } from "@/lib/utils";
-import type { ChatSummary } from "@/lib/types";
+import type { ChatSummary, SidebarDensity, SidebarSortMode } from "@/lib/types";
 
 interface ChatListProps {
   sessions: ChatSummary[];
   activeKey: string | null;
   onSelect: (key: string) => void;
   onRequestDelete: (key: string, label: string) => void;
+  onTogglePin: (key: string) => void;
+  onRequestRename: (key: string, label: string) => void;
+  onToggleArchive: (key: string) => void;
+  pinnedKeys?: string[];
+  archivedKeys?: string[];
+  titleOverrides?: Record<string, string>;
+  runningChatIds?: string[];
+  completedChatIds?: string[];
+  density?: SidebarDensity;
+  showPreviews?: boolean;
+  showTimestamps?: boolean;
+  sort?: SidebarSortMode;
+  showArchived?: boolean;
+  actionMenuPortalContainer?: HTMLElement | null;
   loading?: boolean;
   emptyLabel?: string;
 }
@@ -25,6 +47,20 @@ export function ChatList({
   activeKey,
   onSelect,
   onRequestDelete,
+  onTogglePin,
+  onRequestRename,
+  onToggleArchive,
+  pinnedKeys = [],
+  archivedKeys = [],
+  titleOverrides = {},
+  runningChatIds = [],
+  completedChatIds = [],
+  density = "comfortable",
+  showPreviews = false,
+  showTimestamps = false,
+  sort = "updated_desc",
+  showArchived = false,
+  actionMenuPortalContainer,
   loading,
   emptyLabel,
 }: ChatListProps) {
@@ -46,10 +82,25 @@ export function ChatList({
   }
 
   const groups = groupSessions(sessions, {
+    pinned: t("chat.groups.pinned"),
+    all: t("chat.groups.all"),
     today: t("chat.groups.today"),
     yesterday: t("chat.groups.yesterday"),
     earlier: t("chat.groups.earlier"),
+    archived: t("chat.groups.archived"),
+    fallbackTitle: t("chat.newChat"),
+  }, {
+    pinnedKeys,
+    archivedKeys,
+    titleOverrides,
+    showArchived,
+    sort,
   });
+  const pinned = new Set(pinnedKeys);
+  const archived = new Set(archivedKeys);
+  const running = new Set(runningChatIds);
+  const completed = new Set(completedChatIds);
+  const compact = density === "compact";
 
   return (
     <div className="h-full min-h-0 min-w-0 overflow-x-hidden overflow-y-auto overscroll-contain">
@@ -66,15 +117,29 @@ export function ChatList({
                   id: s.chatId.slice(0, 6),
                 });
                 const generatedTitle = s.title?.trim() || "";
-                const title =
+                const title = displayTitle(s, titleOverrides, t("chat.newChat"));
-                  generatedTitle || deriveTitle(s.preview, t("chat.newChat"));
                 const tooltipTitle =
-                  generatedTitle || deriveTitle(s.preview, fallbackTitle);
+                  titleOverrides[s.key]?.trim() ||
+                  generatedTitle ||
+                  deriveTitle(s.preview, fallbackTitle);
+                const isPinned = pinned.has(s.key);
+                const isArchived = archived.has(s.key);
+                const preview = s.preview.trim();
+                const showPreview = showPreviews && preview && preview !== title;
+                const timestamp = showTimestamps
+                  ? relativeTime(s.updatedAt ?? s.createdAt)
+                  : "";
+                const activityState = running.has(s.chatId)
+                  ? "running"
+                  : completed.has(s.chatId)
+                    ? "complete"
+                    : null;
                 return (
                   <li key={s.key} className="min-w-0">
                     <div
                       className={cn(
-                        "group flex min-h-8 min-w-0 max-w-full items-center gap-2 rounded-xl px-2 text-[13px] transition-colors",
+                        "group flex min-w-0 max-w-full items-center gap-2 rounded-xl px-2 text-[13px] transition-colors",
+                        compact ? "min-h-7" : "min-h-8",
                         active
                           ? "bg-sidebar-accent/70 text-sidebar-accent-foreground shadow-[inset_0_0_0_1px_hsl(var(--sidebar-border)/0.28)]"
                           : "text-sidebar-foreground/82 hover:bg-sidebar-accent/50 hover:text-sidebar-foreground",
@@ -84,10 +149,24 @@ export function ChatList({
                         type="button"
                         onClick={() => onSelect(s.key)}
                         title={tooltipTitle}
-                        className="min-w-0 flex-1 overflow-hidden py-1.5 text-left"
+                        className={cn(
+                          "min-w-0 flex-1 overflow-hidden text-left",
+                          compact ? "py-1" : "py-1.5",
+                        )}
                       >
                         <span className="block w-full truncate font-medium leading-5">{title}</span>
+                        {showPreview ? (
+                          <span className="block w-full truncate text-[11.5px] leading-4 text-muted-foreground/72">
+                            {preview}
+                          </span>
+                        ) : null}
+                        {timestamp ? (
+                          <span className="block w-full truncate text-[11px] leading-4 text-muted-foreground/58">
+                            {timestamp}
+                          </span>
+                        ) : null}
                       </button>
+                      <SessionActivityIndicator state={activityState} />
                       <DropdownMenu modal={false}>
                         <DropdownMenuTrigger
                           className={cn(
@@ -102,8 +181,35 @@ export function ChatList({
                         </DropdownMenuTrigger>
                         <DropdownMenuContent
                           align="end"
+                          portalContainer={actionMenuPortalContainer}
                           onCloseAutoFocus={(event) => event.preventDefault()}
                         >
+                          <DropdownMenuItem
+                            onSelect={() => onTogglePin(s.key)}
+                          >
+                            {isPinned ? (
+                              <PinOff className="mr-2 h-4 w-4" />
+                            ) : (
+                              <Pin className="mr-2 h-4 w-4" />
+                            )}
+                            {isPinned ? t("chat.unpin") : t("chat.pin")}
+                          </DropdownMenuItem>
+                          <DropdownMenuItem
+                            onSelect={() => onRequestRename(s.key, title)}
+                          >
+                            <Pencil className="mr-2 h-4 w-4" />
+                            {t("chat.rename")}
+                          </DropdownMenuItem>
+                          <DropdownMenuItem
+                            onSelect={() => onToggleArchive(s.key)}
+                          >
+                            {isArchived ? (
+                              <ArchiveRestore className="mr-2 h-4 w-4" />
+                            ) : (
+                              <Archive className="mr-2 h-4 w-4" />
+                            )}
+                            {isArchived ? t("chat.unarchive") : t("chat.archive")}
+                          </DropdownMenuItem>
                           <DropdownMenuItem
                             onSelect={() => {
                               window.setTimeout(() => onRequestDelete(s.key, title), 0);
@@ -127,16 +233,85 @@ export function ChatList({
   );
 }
 
+function SessionActivityIndicator({
+  state,
+}: {
+  state: "running" | "complete" | null;
+}) {
+  const { t } = useTranslation();
+
+  if (state === "running") {
+    const label = t("chat.activity.running");
+    return (
+      <span
+        aria-label={label}
+        title={label}
+        className="grid h-4 w-4 shrink-0 place-items-center"
+      >
+        <span className="h-3 w-3 animate-spin rounded-full border border-blue-500/25 border-t-blue-500 [animation-duration:1.4s] motion-reduce:animate-none dark:border-blue-400/25 dark:border-t-blue-400" />
+      </span>
+    );
+  }
+
+  if (state === "complete") {
+    const label = t("chat.activity.complete");
+    return (
+      <span
+        aria-label={label}
+        title={label}
+        className="grid h-4 w-4 shrink-0 place-items-center"
+      >
+        <span className="h-1.5 w-1.5 rounded-full bg-blue-500 shadow-[0_0_0_3px_rgba(59,130,246,0.14)] dark:bg-blue-400 dark:shadow-[0_0_0_3px_rgba(96,165,250,0.18)]" />
+      </span>
+    );
+  }
+
+  return <span className="h-4 w-4 shrink-0" aria-hidden="true" />;
+}
+
 function groupSessions(
   sessions: ChatSummary[],
-  labels: { today: string; yesterday: string; earlier: string },
+  labels: {
+    pinned: string;
+    all: string;
+    today: string;
+    yesterday: string;
+    earlier: string;
+    archived: string;
+    fallbackTitle: string;
+  },
+  options: {
+    pinnedKeys: string[];
+    archivedKeys: string[];
+    titleOverrides: Record<string, string>;
+    showArchived: boolean;
+    sort: SidebarSortMode;
+  },
 ): Array<{ label: string; sessions: ChatSummary[] }> {
   const now = new Date();
   const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
   const startOfYesterday = startOfToday - 24 * 60 * 60 * 1000;
   const buckets = new Map<string, ChatSummary[]>();
+  const pinned = new Set(options.pinnedKeys);
+  const archived = new Set(options.archivedKeys);
+
+  const pinnedSessions: ChatSummary[] = [];
+  const archivedSessions: ChatSummary[] = [];
+  const normalSessions: ChatSummary[] = [];
 
   for (const session of sessions) {
+    if (archived.has(session.key)) {
+      if (options.showArchived) archivedSessions.push(session);
+      continue;
+    }
+    if (pinned.has(session.key)) {
+      pinnedSessions.push(session);
+      continue;
+    }
+    if (options.sort === "title_asc") {
+      normalSessions.push(session);
+      continue;
+    }
     const timestamp = Date.parse(session.updatedAt ?? session.createdAt ?? "");
     const label = Number.isFinite(timestamp) && timestamp >= startOfToday
       ? labels.today
@@ -148,7 +323,101 @@ function groupSessions(
     buckets.set(label, bucket);
   }
 
-  return [labels.today, labels.yesterday, labels.earlier]
+  const groups = [labels.today, labels.yesterday, labels.earlier]
-    .map((label) => ({ label, sessions: buckets.get(label) ?? [] }))
+    .map((label) => ({
+      label,
+      sessions: sortSessions(
+        buckets.get(label) ?? [],
+        options.sort,
+        options.titleOverrides,
+      ),
+    }))
     .filter((group) => group.sessions.length > 0);
+  if (options.sort === "title_asc" && normalSessions.length) {
+    groups.push({
+      label: labels.all,
+      sessions: sortSessions(
+        normalSessions,
+        options.sort,
+        options.titleOverrides,
+      ),
+    });
+  }
+  if (pinnedSessions.length) {
+    groups.unshift({
+      label: labels.pinned,
+      sessions: sortSessions(
+        pinnedSessions,
+        options.sort,
+        options.titleOverrides,
+      ),
+    });
+  }
+  if (archivedSessions.length) {
+    groups.push({
+      label: labels.archived,
+      sessions: sortSessions(
+        archivedSessions,
+        options.sort,
+        options.titleOverrides,
+      ),
+    });
+  }
+  return groups;
+}
+
+function sortSessions(
+  sessions: ChatSummary[],
+  sort: SidebarSortMode,
+  titleOverrides: Record<string, string>,
+): ChatSummary[] {
+  const copy = [...sessions];
+  copy.sort((a, b) => {
+    if (sort === "title_asc") {
+      const titleOrder = titleForSort(a, titleOverrides).localeCompare(
+        titleForSort(b, titleOverrides),
+        "en",
+        { numeric: true, sensitivity: "base" },
+      );
+      if (titleOrder !== 0) return titleOrder;
+      return sessionTime(b, "updatedAt") - sessionTime(a, "updatedAt");
+    }
+    const aTime = sessionTime(a, sort === "created_desc" ? "createdAt" : "updatedAt");
+    const bTime = sessionTime(b, sort === "created_desc" ? "createdAt" : "updatedAt");
+    return bTime - aTime;
+  });
+  return copy;
+}
+
+function titleForSort(
+  session: ChatSummary,
+  titleOverrides: Record<string, string>,
+): string {
+  return (
+    titleOverrides[session.key]?.trim() ||
+    session.title?.trim() ||
+    deriveTitle(session.preview, "new chat")
+  ).toLocaleLowerCase("en");
+}
+
+function displayTitle(
+  session: ChatSummary,
+  titleOverrides: Record<string, string>,
+  fallbackTitle: string,
+): string {
+  return (
+    titleOverrides[session.key]?.trim() ||
+    session.title?.trim() ||
+    deriveTitle(session.preview, fallbackTitle)
+  );
+}
+
+function sessionTime(
+  session: ChatSummary,
+  field: "createdAt" | "updatedAt",
+): number {
+  const primary = Date.parse(session[field] ?? "");
+  if (Number.isFinite(primary)) return primary;
+  const fallback = Date.parse(session.updatedAt ?? session.createdAt ?? "");
+  return Number.isFinite(fallback) ? fallback : 0;
 }

webui/src/components/FileReferenceChip.tsx

@@ -19,6 +19,7 @@ type FileReferenceKind =
 
 interface FileReferenceChipProps {
   path: string;
+  tooltipPath?: string;
   display?: "name" | "path";
   active?: boolean;
   className?: string;
@@ -28,27 +29,29 @@ interface FileReferenceChipProps {
 
 export function FileReferenceChip({
   path,
+  tooltipPath,
   display = "name",
   active = false,
   className,
   textClassName,
   testId = "inline-file-path",
 }: FileReferenceChipProps) {
-  const { name } = splitFilePath(path);
+  const { directory, name } = splitFilePath(path);
   const kind = fileKindForPath(path);
   const displayText = display === "path" ? path.replace(/\\/g, "/") : name;
+  const fullPath = tooltipPath || path;
   return (
     <TooltipProvider delayDuration={500} skipDelayDuration={100}>
       <Tooltip>
         <TooltipTrigger asChild>
           <span
-            className={cn("not-prose inline-flex max-w-full align-[0.14em]", className)}
+            className={cn("not-prose inline-flex max-w-full align-baseline leading-[inherit]", className)}
           >
             <span
               data-testid={testId}
-              aria-label={path}
+              aria-label={fullPath}
               className={cn(
-                "inline-flex max-w-full items-center gap-1 font-medium leading-[1.1]",
+                "inline-flex max-w-full items-center gap-1 font-medium leading-[inherit]",
                 "text-sky-600 transition-colors hover:text-sky-700",
                 "dark:text-sky-300 dark:hover:text-sky-200",
               )}
@@ -57,12 +60,19 @@ export function FileReferenceChip({
               <span
                 data-sheen-text={active ? displayText : undefined}
                 className={cn(
-                  "min-w-0 truncate",
+                  "min-w-0 max-w-full truncate",
-                  active && "streaming-text-sheen",
+                  active && "streaming-text-sheen file-reference-sheen",
                   textClassName,
                 )}
               >
-                {displayText}
+                {display === "path" && directory ? (
+                  <>
+                    <span className="text-muted-foreground/65">{directory}</span>
+                    <span className="font-semibold text-sky-700 dark:text-sky-200">{name}</span>
+                  </>
+                ) : (
+                  displayText
+                )}
               </span>
             </span>
           </span>
@@ -79,7 +89,7 @@ export function FileReferenceChip({
             "shadow-lg backdrop-blur",
           )}
         >
-          {path}
+          {fullPath}
         </TooltipContent>
       </Tooltip>
     </TooltipProvider>

webui/src/components/RenameChatDialog.tsx

@@ -0,0 +1,75 @@
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+
+interface RenameChatDialogProps {
+  open: boolean;
+  title: string;
+  onCancel: () => void;
+  onConfirm: (title: string) => void;
+}
+
+export function RenameChatDialog({
+  open,
+  title,
+  onCancel,
+  onConfirm,
+}: RenameChatDialogProps) {
+  const { t } = useTranslation();
+  const [value, setValue] = useState(title);
+
+  useEffect(() => {
+    if (open) setValue(title);
+  }, [open, title]);
+
+  const trimmed = value.trim();
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => {
+      if (!next) onCancel();
+    }}>
+      <DialogContent className="max-w-sm rounded-[22px] border-border/70 bg-popover p-5 shadow-2xl">
+        <form
+          className="grid gap-4"
+          onSubmit={(event) => {
+            event.preventDefault();
+            if (!trimmed) return;
+            onConfirm(trimmed);
+          }}
+        >
+          <DialogHeader className="text-left">
+            <DialogTitle>{t("chat.renameTitle")}</DialogTitle>
+            <DialogDescription>
+              {t("chat.renameDescription")}
+            </DialogDescription>
+          </DialogHeader>
+          <Input
+            value={value}
+            onChange={(event) => setValue(event.target.value)}
+            placeholder={t("chat.renamePlaceholder")}
+            autoFocus
+            maxLength={160}
+          />
+          <DialogFooter className="gap-2 sm:space-x-0">
+            <Button type="button" variant="outline" onClick={onCancel}>
+              {t("deleteConfirm.cancel")}
+            </Button>
+            <Button type="submit" disabled={!trimmed}>
+              {t("chat.renameSave")}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

webui/src/components/SessionSearchDialog.tsx

@@ -0,0 +1,213 @@
+import { type KeyboardEvent, useEffect, useMemo, useRef, useState } from "react";
+import { Search } from "lucide-react";
+import { useTranslation } from "react-i18next";
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { deriveTitle } from "@/lib/format";
+import { cn } from "@/lib/utils";
+import type { ChatSummary } from "@/lib/types";
+
+interface SessionSearchDialogProps {
+  open: boolean;
+  sessions: ChatSummary[];
+  activeKey: string | null;
+  loading: boolean;
+  titleOverrides?: Record<string, string>;
+  onOpenChange: (open: boolean) => void;
+  onSelect: (key: string) => void;
+}
+
+export function SessionSearchDialog({
+  open,
+  sessions,
+  activeKey,
+  loading,
+  titleOverrides = {},
+  onOpenChange,
+  onSelect,
+}: SessionSearchDialogProps) {
+  const { t } = useTranslation();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [query, setQuery] = useState("");
+  const [highlightedIndex, setHighlightedIndex] = useState(0);
+
+  const normalizedQuery = query.trim().toLowerCase();
+  const results = useMemo(() => {
+    if (!normalizedQuery) return sessions;
+    const terms = normalizedQuery.split(/\s+/).filter(Boolean);
+    return sessions.filter((session) =>
+      sessionMatchesTerms(session, terms, titleOverrides[session.key]),
+    );
+  }, [normalizedQuery, sessions, titleOverrides]);
+
+  useEffect(() => {
+    if (!open) return;
+    setQuery("");
+    setHighlightedIndex(0);
+    window.setTimeout(() => inputRef.current?.focus(), 0);
+  }, [open]);
+
+  useEffect(() => {
+    setHighlightedIndex(0);
+  }, [normalizedQuery]);
+
+  useEffect(() => {
+    setHighlightedIndex((index) =>
+      results.length === 0 ? 0 : Math.min(index, results.length - 1),
+    );
+  }, [results.length]);
+
+  const handleSelect = (key: string) => {
+    onOpenChange(false);
+    onSelect(key);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      setHighlightedIndex((index) =>
+        results.length === 0 ? 0 : Math.min(index + 1, results.length - 1),
+      );
+      return;
+    }
+    if (event.key === "ArrowUp") {
+      event.preventDefault();
+      setHighlightedIndex((index) => Math.max(index - 1, 0));
+      return;
+    }
+    if (event.key === "Enter") {
+      const highlighted = results[highlightedIndex];
+      if (!highlighted) return;
+      event.preventDefault();
+      handleSelect(highlighted.key);
+    }
+  };
+
+  const emptyLabel = normalizedQuery
+    ? t("sidebar.noSearchResults")
+    : t("chat.noSessions");
+  const sectionLabel = normalizedQuery
+    ? t("sidebar.searchResults")
+    : t("sidebar.recent");
+
+  if (!open) return null;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        showCloseButton={false}
+        className={cn(
+          "max-h-[min(34rem,calc(100vh-2rem))] w-[calc(100vw-2rem)] max-w-[42rem] gap-0 overflow-hidden p-0",
+          "rounded-2xl border border-border/70 bg-popover/95 text-popover-foreground shadow-2xl backdrop-blur-xl",
+          "sm:rounded-2xl",
+        )}
+      >
+        <DialogTitle className="sr-only">{t("sidebar.searchAria")}</DialogTitle>
+        <DialogDescription className="sr-only">
+          {t("sidebar.searchPlaceholder")}
+        </DialogDescription>
+        <div className="flex h-14 items-center gap-3 border-b border-border/60 px-5">
+          <Search
+            className="h-4 w-4 shrink-0 text-muted-foreground"
+            aria-hidden
+          />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder={t("sidebar.searchPlaceholder")}
+            aria-label={t("sidebar.searchAria")}
+            className="h-full min-w-0 flex-1 bg-transparent text-[15px] font-medium text-foreground outline-none placeholder:text-muted-foreground/75"
+          />
+        </div>
+
+        <div className="min-h-0 overflow-y-auto overscroll-contain p-2">
+          <div className="px-2 pb-1.5 pt-1 text-[12px] font-medium text-muted-foreground/70">
+            {sectionLabel}
+          </div>
+
+          {loading && sessions.length === 0 ? (
+            <div className="px-3 py-7 text-[13px] text-muted-foreground">
+              {t("chat.loading")}
+            </div>
+          ) : results.length === 0 ? (
+            <div className="px-3 py-7 text-[13px] text-muted-foreground">
+              {emptyLabel}
+            </div>
+          ) : (
+            <ul className="space-y-1">
+              {results.map((session, index) => {
+                const title = titleOverrides[session.key]?.trim() ||
+                  session.title?.trim() ||
+                  deriveTitle(session.preview, t("chat.newChat"));
+                const preview = session.preview.trim();
+                const showPreview =
+                  preview.length > 0 &&
+                  preview.toLowerCase() !== title.trim().toLowerCase();
+                const highlighted = index === highlightedIndex;
+                const active = session.key === activeKey;
+                return (
+                  <li key={session.key}>
+                    <button
+                      type="button"
+                      onClick={() => handleSelect(session.key)}
+                      onMouseEnter={() => setHighlightedIndex(index)}
+                      aria-current={active ? "page" : undefined}
+                      className={cn(
+                        "flex min-h-12 w-full min-w-0 rounded-xl px-3 py-2.5 text-left transition-colors",
+                        highlighted
+                          ? "bg-accent text-accent-foreground"
+                          : "text-popover-foreground hover:bg-accent/75 hover:text-accent-foreground",
+                      )}
+                    >
+                      <span className="min-w-0 flex-1">
+                        <span className="block truncate text-[14px] font-medium leading-5">
+                          {title}
+                        </span>
+                        {showPreview ? (
+                          <span
+                            className={cn(
+                              "block truncate text-[12px] leading-4",
+                              highlighted
+                                ? "text-accent-foreground/70"
+                                : "text-muted-foreground",
+                            )}
+                          >
+                            {preview}
+                          </span>
+                        ) : null}
+                      </span>
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function sessionMatchesTerms(
+  session: ChatSummary,
+  terms: string[],
+  titleOverride?: string,
+) {
+  const haystack = [
+    titleOverride,
+    session.title,
+    session.preview,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+  return terms.every((term) => haystack.includes(term));
+}

webui/src/components/Sidebar.tsx

@@ -1,5 +1,7 @@
-import { useMemo, useState } from "react";
+import { useState } from "react";
 import {
+  Archive,
+  ListFilter,
   Menu,
   Search,
   Settings,
@@ -10,9 +12,22 @@ import { useTranslation } from "react-i18next";
 import { ChatList } from "@/components/ChatList";
 import { ConnectionBadge } from "@/components/ConnectionBadge";
 import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
 import { Separator } from "@/components/ui/separator";
-import { cn } from "@/lib/utils";
+import type {
-import type { ChatSummary } from "@/lib/types";
+  ChatSummary,
+  SidebarSortMode,
+  SidebarViewState,
+} from "@/lib/types";
 
 interface SidebarProps {
   sessions: ChatSummary[];
@@ -21,34 +36,33 @@ interface SidebarProps {
   onNewChat: () => void;
   onSelect: (key: string) => void;
   onRequestDelete: (key: string, label: string) => void;
+  onTogglePin: (key: string) => void;
+  onRequestRename: (key: string, label: string) => void;
+  onToggleArchive: (key: string) => void;
   onOpenSettings: () => void;
+  onOpenSearch: () => void;
+  onToggleArchived: () => void;
+  onUpdateView: (view: Partial<SidebarViewState>) => void;
   onCollapse: () => void;
+  containActionMenus?: boolean;
+  pinnedKeys?: string[];
+  archivedKeys?: string[];
+  titleOverrides?: Record<string, string>;
+  runningChatIds?: string[];
+  completedChatIds?: string[];
+  viewState?: SidebarViewState;
+  showArchived?: boolean;
+  archivedCount?: number;
 }
 
 export function Sidebar(props: SidebarProps) {
   const { t } = useTranslation();
-  const [query, setQuery] = useState("");
+  const [menuPortalContainer, setMenuPortalContainer] =
-  const normalizedQuery = query.trim().toLowerCase();
+    useState<HTMLElement | null>(null);
-  const filteredSessions = useMemo(() => {
-    if (!normalizedQuery) return props.sessions;
-    const terms = normalizedQuery.split(/\s+/).filter(Boolean);
-    return props.sessions.filter((session) => {
-      const haystack = [
-        session.title,
-        session.preview,
-        session.chatId,
-        session.channel,
-        session.key,
-      ]
-        .filter(Boolean)
-        .join(" ")
-        .toLowerCase();
-      return terms.every((term) => haystack.includes(term));
-    });
-  }, [normalizedQuery, props.sessions]);
 
   return (
     <nav
+      ref={props.containActionMenus ? setMenuPortalContainer : undefined}
       aria-label={t("sidebar.navigation")}
       className="flex h-full w-full min-w-0 flex-col border-r border-sidebar-border/60 bg-sidebar text-sidebar-foreground"
     >
@@ -74,27 +88,6 @@ export function Sidebar(props: SidebarProps) {
       </div>
 
       <div className="space-y-1.5 px-2 pb-2">
-        <label className="relative block">
-          <span className="sr-only">{t("sidebar.searchAria")}</span>
-          <Search
-            className="pointer-events-none absolute left-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground/70"
-            aria-hidden
-          />
-          <input
-            value={query}
-            onChange={(event) => setQuery(event.target.value)}
-            placeholder={t("sidebar.searchPlaceholder")}
-            aria-label={t("sidebar.searchAria")}
-            className={cn(
-              "h-8 w-full rounded-full border border-transparent bg-sidebar-accent/45",
-              "pl-8 pr-3 text-[12.5px] text-sidebar-foreground outline-none",
-              "placeholder:text-muted-foreground/75",
-              "transition-colors hover:bg-sidebar-accent/65",
-              "focus:border-sidebar-border/80 focus:bg-sidebar-accent/70",
-              "focus:ring-1 focus:ring-sidebar-border/70",
-            )}
-          />
-        </label>
         <Button
           onClick={props.onNewChat}
           className="h-8 w-full justify-start gap-2 rounded-full px-3 text-[12.5px] font-medium text-sidebar-foreground/92 hover:bg-sidebar-accent/75 hover:text-sidebar-foreground"
@@ -103,17 +96,55 @@ export function Sidebar(props: SidebarProps) {
           <SquarePen className="h-3.5 w-3.5" />
           {t("sidebar.newChat")}
         </Button>
+        <Button
+          type="button"
+          onClick={props.onOpenSearch}
+          className="h-8 w-full justify-start gap-2 rounded-full px-3 text-[12.5px] font-medium text-sidebar-foreground/85 hover:bg-sidebar-accent/75 hover:text-sidebar-foreground"
+          variant="ghost"
+        >
+          <Search className="h-3.5 w-3.5" aria-hidden />
+          {t("sidebar.searchAria")}
+        </Button>
+        <SidebarViewMenu
+          view={props.viewState}
+          onUpdateView={props.onUpdateView}
+        />
+        {props.archivedCount ? (
+          <Button
+            type="button"
+            onClick={props.onToggleArchived}
+            className="h-8 w-full justify-start gap-2 rounded-full px-3 text-[12.5px] font-medium text-sidebar-foreground/75 hover:bg-sidebar-accent/75 hover:text-sidebar-foreground"
+            variant="ghost"
+          >
+            <Archive className="h-3.5 w-3.5" aria-hidden />
+            {props.showArchived ? t("chat.hideArchived") : t("chat.showArchived")}
+          </Button>
+        ) : null}
       </div>
       <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden">
         <ChatList
-          sessions={filteredSessions}
+          sessions={props.sessions}
           activeKey={props.activeKey}
           loading={props.loading}
-          emptyLabel={
+          emptyLabel={t("chat.noSessions")}
-            normalizedQuery ? t("sidebar.noSearchResults") : t("chat.noSessions")
-          }
           onSelect={props.onSelect}
           onRequestDelete={props.onRequestDelete}
+          onTogglePin={props.onTogglePin}
+          onRequestRename={props.onRequestRename}
+          onToggleArchive={props.onToggleArchive}
+          pinnedKeys={props.pinnedKeys}
+          archivedKeys={props.archivedKeys}
+          titleOverrides={props.titleOverrides}
+          runningChatIds={props.runningChatIds}
+          completedChatIds={props.completedChatIds}
+          density={props.viewState?.density}
+          showPreviews={props.viewState?.show_previews}
+          showTimestamps={props.viewState?.show_timestamps}
+          sort={props.viewState?.sort}
+          showArchived={props.showArchived}
+          actionMenuPortalContainer={
+            props.containActionMenus ? menuPortalContainer : undefined
+          }
         />
       </div>
       <Separator className="bg-sidebar-border/50" />
@@ -132,3 +163,83 @@ export function Sidebar(props: SidebarProps) {
     </nav>
   );
 }
+
+function SidebarViewMenu({
+  view,
+  onUpdateView,
+}: {
+  view?: SidebarViewState;
+  onUpdateView: (view: Partial<SidebarViewState>) => void;
+}) {
+  const { t } = useTranslation();
+  const sort = view?.sort ?? "updated_desc";
+  const setSort = (value: string) => {
+    if (isSidebarSortMode(value)) onUpdateView({ sort: value });
+  };
+
+  return (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          type="button"
+          className="h-8 w-full justify-start gap-2 rounded-full px-3 text-[12.5px] font-medium text-sidebar-foreground/75 hover:bg-sidebar-accent/75 hover:text-sidebar-foreground"
+          variant="ghost"
+        >
+          <ListFilter className="h-3.5 w-3.5" aria-hidden />
+          {t("sidebar.viewOptions")}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="w-52">
+        <DropdownMenuLabel className="text-xs text-muted-foreground">
+          {t("sidebar.viewOptions")}
+        </DropdownMenuLabel>
+        <DropdownMenuCheckboxItem
+          checked={view?.density === "compact"}
+          onCheckedChange={(checked) =>
+            onUpdateView({ density: checked ? "compact" : "comfortable" })
+          }
+          onSelect={(event) => event.preventDefault()}
+        >
+          {t("sidebar.compactList")}
+        </DropdownMenuCheckboxItem>
+        <DropdownMenuCheckboxItem
+          checked={Boolean(view?.show_previews)}
+          onCheckedChange={(checked) =>
+            onUpdateView({ show_previews: Boolean(checked) })
+          }
+          onSelect={(event) => event.preventDefault()}
+        >
+          {t("sidebar.showPreviews")}
+        </DropdownMenuCheckboxItem>
+        <DropdownMenuCheckboxItem
+          checked={Boolean(view?.show_timestamps)}
+          onCheckedChange={(checked) =>
+            onUpdateView({ show_timestamps: Boolean(checked) })
+          }
+          onSelect={(event) => event.preventDefault()}
+        >
+          {t("sidebar.showTimestamps")}
+        </DropdownMenuCheckboxItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuLabel className="text-xs text-muted-foreground">
+          {t("sidebar.sortLabel")}
+        </DropdownMenuLabel>
+        <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+          <DropdownMenuRadioItem value="updated_desc">
+            {t("sidebar.sortUpdated")}
+          </DropdownMenuRadioItem>
+          <DropdownMenuRadioItem value="created_desc">
+            {t("sidebar.sortCreated")}
+          </DropdownMenuRadioItem>
+          <DropdownMenuRadioItem value="title_asc">
+            {t("sidebar.sortTitle")}
+          </DropdownMenuRadioItem>
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+function isSidebarSortMode(value: string): value is SidebarSortMode {
+  return value === "updated_desc" || value === "created_desc" || value === "title_asc";
+}

webui/src/components/thread/AgentActivityCluster.tsx

@@ -30,16 +30,19 @@ interface ActivityCounts {
   hasEditingFiles: boolean;
   hasFailedFiles: boolean;
   primaryFilePath?: string;
+  primaryFileTooltipPath?: string;
 }
 
 interface FileEditSummary {
   key: string;
   path: string;
+  absolute_path?: string;
   added: number;
   deleted: number;
   approximate: boolean;
   binary: boolean;
   status: UIFileEdit["status"];
+  pending: boolean;
   error?: string;
 }
 
@@ -61,8 +64,10 @@ function countActivity(messages: UIMessage[], fileEdits: FileEditSummary[]): Act
   let hasEditingFiles = false;
   let failedFileCount = 0;
   let primaryFilePath: string | undefined;
+  let primaryFileTooltipPath: string | undefined;
   for (const edit of fileEdits) {
     primaryFilePath = edit.path;
+    primaryFileTooltipPath = edit.absolute_path || edit.path;
     if (edit.status === "editing") {
       hasEditingFiles = true;
     }
@@ -84,6 +89,7 @@ function countActivity(messages: UIMessage[], fileEdits: FileEditSummary[]): Act
     hasEditingFiles,
     hasFailedFiles: fileEdits.length > 0 && failedFileCount === fileEdits.length,
     primaryFilePath,
+    primaryFileTooltipPath,
   };
 }
 
@@ -117,7 +123,9 @@ export function AgentActivityCluster({
     hasEditingFiles,
     hasFailedFiles,
     primaryFilePath,
+    primaryFileTooltipPath,
   } = countActivity(messages, fileEdits);
+  const hasPendingFileEdit = fileEdits.some((edit) => edit.pending);
 
   const [userToggledOuter, setUserToggledOuter] = useState(false);
   const [outerOpenLocal, setOuterOpenLocal] = useState(false);
@@ -130,11 +138,15 @@ export function AgentActivityCluster({
 
   const hasLiveEditingFiles = isTurnStreaming && hasEditingFiles;
   const headerBusy = fileCount > 0 ? hasEditingFiles : isTurnStreaming;
+  const singleFilePath = fileCount === 1 ? primaryFilePath : undefined;
+  const singleFileTooltipPath = fileCount === 1 ? primaryFileTooltipPath : undefined;
 
   const fileActivitySummary = fileCount > 0
-    ? fileCount === 1 && primaryFilePath
+    ? hasPendingFileEdit && !singleFilePath
+      ? t("message.fileActivityPreparing", { defaultValue: "Preparing edit…" })
+      : singleFilePath
       ? t(fileActivitySummaryKey(hasLiveEditingFiles, hasFailedFiles), {
-          file: shortFileName(primaryFilePath),
+          file: shortFileName(singleFilePath),
           defaultValue: `${fileActivityVerb(hasLiveEditingFiles, hasFailedFiles)} {{file}}`,
         })
       : t(fileActivityManySummaryKey(hasLiveEditingFiles, hasFailedFiles), {
@@ -241,15 +253,35 @@ export function AgentActivityCluster({
           "text-xs text-muted-foreground transition-colors hover:bg-muted/45",
         )}
         aria-expanded={outerExpanded}
+        aria-label={summary}
       >
         <Layers className="h-3.5 w-3.5 shrink-0" aria-hidden />
         <span className="flex min-w-0 flex-1 flex-wrap items-center gap-x-1.5 gap-y-0.5 text-left">
-          <StreamingLabelSheen
+          {singleFilePath ? (
-            active={headerBusy}
+            <span className="inline-flex min-w-0 items-center gap-1.5">
-            className="min-w-0"
+              <StreamingLabelSheen
-          >
+                active={headerBusy}
-            {summary}
+                className="shrink-0"
-          </StreamingLabelSheen>
+              >
+                {fileActivityVerb(hasLiveEditingFiles, hasFailedFiles)}
+              </StreamingLabelSheen>
+              <FileReferenceChip
+                path={singleFilePath}
+                tooltipPath={singleFileTooltipPath}
+                active={hasLiveEditingFiles}
+                className="-my-0.5 min-w-0"
+                textClassName="text-xs"
+                testId="activity-header-file-reference"
+              />
+            </span>
+          ) : (
+            <StreamingLabelSheen
+              active={headerBusy}
+              className="min-w-0"
+            >
+              {summary}
+            </StreamingLabelSheen>
+          )}
           {fileCount > 0 && (
             <span className="inline-flex min-w-0 items-center gap-1 text-muted-foreground/85">
               <DiffPair added={added} deleted={deleted} />
@@ -332,7 +364,8 @@ function fileActivityManySummaryKey(editing: boolean, failed: boolean): string {
 }
 
 function fileEditCallKey(edit: UIFileEdit): string {
-  return `${edit.call_id}|${edit.tool}|${edit.path}`;
+  if (edit.call_id) return `${edit.call_id}|${edit.tool}`;
+  return `${edit.tool}|${edit.path}`;
 }
 
 function collectFileEdits(messages: UIMessage[]): UIFileEdit[] {
@@ -360,10 +393,12 @@ function summarizeFileEdits(edits: UIFileEdit[], active: boolean): FileEditSumma
   interface MutableSummary {
     key: string;
     path: string;
+    absolute_path?: string;
     added: number;
     deleted: number;
     approximate: boolean;
     binary: boolean;
+    pending: boolean;
     hasSuccessfulChange: boolean;
     hasActiveEditing: boolean;
     hasFailed: boolean;
@@ -373,16 +408,18 @@ function summarizeFileEdits(edits: UIFileEdit[], active: boolean): FileEditSumma
   const order: string[] = [];
   const byPath = new Map<string, MutableSummary>();
   for (const edit of latestFileEditEvents(edits)) {
-    const key = edit.path;
+    const key = edit.path || edit.call_id || edit.tool;
     let summary = byPath.get(key);
     if (!summary) {
       summary = {
         key,
-        path: edit.path,
+        path: edit.path || "",
+        absolute_path: edit.absolute_path,
         added: 0,
         deleted: 0,
         approximate: false,
         binary: false,
+        pending: false,
         hasSuccessfulChange: false,
         hasActiveEditing: false,
         hasFailed: false,
@@ -391,6 +428,13 @@ function summarizeFileEdits(edits: UIFileEdit[], active: boolean): FileEditSumma
       order.push(key);
     }
 
+    if (edit.path && !summary.path) {
+      summary.path = edit.path;
+    }
+    if (edit.absolute_path) {
+      summary.absolute_path = edit.absolute_path;
+    }
+    summary.pending = summary.pending || !!edit.pending || !edit.path;
     if (active && edit.status === "editing") {
       summary.hasActiveEditing = true;
       summary.binary = summary.binary || !!edit.binary;
@@ -429,11 +473,13 @@ function summarizeFileEdits(edits: UIFileEdit[], active: boolean): FileEditSumma
     return {
       key: summary.key,
       path: summary.path,
+      absolute_path: summary.absolute_path,
       added: summary.added,
       deleted: summary.deleted,
       approximate: summary.approximate,
       binary: summary.binary,
       status,
+      pending: summary.pending && !summary.path,
       error: summary.error,
     };
   });
@@ -458,14 +504,24 @@ function FileEditRow({ edit }: { edit: FileEditSummary }) {
   return (
     <li className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-3 rounded-md px-2 py-1.5 text-xs">
       <div className="flex min-w-0 items-center gap-2">
-        <FileReferenceChip
+        {edit.pending && !edit.path ? (
-          path={edit.path}
+          <StreamingLabelSheen
-          display="path"
+            active={editing}
-          active={editing}
+            className="min-w-0 text-[12px] font-medium text-muted-foreground"
-          className="min-w-0"
+          >
-          textClassName="text-[12px]"
+            {t("message.fileEditPreparing", { defaultValue: "Preparing file edit…" })}
-          testId="activity-file-reference"
+          </StreamingLabelSheen>
-        />
+        ) : (
+          <FileReferenceChip
+            path={edit.path}
+            tooltipPath={edit.absolute_path}
+            display="path"
+            active={editing}
+            className="min-w-0"
+            textClassName="text-[12px]"
+            testId="activity-file-reference"
+          />
+        )}
         {failed ? (
           <span className="inline-flex shrink-0 items-center gap-1 text-[10.5px] font-medium text-destructive/75">
             <AlertCircle className="h-3 w-3" aria-hidden />
@@ -487,13 +543,30 @@ function FileEditRow({ edit }: { edit: FileEditSummary }) {
 
 function DiffPair({ added, deleted }: { added: number; deleted: number }) {
   return (
-    <span className="inline-flex shrink-0 items-center gap-1.5 tabular-nums">
+    <span className="inline-flex shrink-0 translate-y-[0.055em] items-center gap-1.5 tabular-nums">
-      <span className="text-emerald-600/75 dark:text-emerald-300/75">
+      <DiffValue
-        +<AnimatedNumber value={added} />
+        sign="+"
-      </span>
+        value={added}
-      <span className="text-rose-600/70 dark:text-rose-300/75">
+        className="text-emerald-600/75 dark:text-emerald-300/75"
-        -<AnimatedNumber value={deleted} />
+      />
+      <DiffValue
+        sign="-"
+        value={deleted}
+        className="text-rose-600/70 dark:text-rose-300/75"
+      />
+    </span>
+  );
+}
+
+function DiffValue({ sign, value, className }: { sign: string; value: number; className: string }) {
+  const safeValue = Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0;
+  return (
+    <span className={cn("inline-flex", className)} aria-label={`${sign}${safeValue}`}>
+      <span className="inline-flex" aria-hidden>
+        {sign}
+        <AnimatedNumber value={safeValue} />
       </span>
+      <span className="sr-only">{sign}{safeValue}</span>
     </span>
   );
 }
@@ -537,5 +610,37 @@ function AnimatedNumber({ value }: { value: number }) {
     return () => window.cancelAnimationFrame(frame);
   }, [safeValue, setAnimatedDisplay]);
 
-  return <>{display}</>;
+  return <RollingNumber value={display} />;
+}
+
+function RollingNumber({ value }: { value: number }) {
+  const digits = String(value).split("");
+  return (
+    <span className="inline-flex h-[1em] overflow-hidden align-[-0.13em]" aria-hidden>
+      {digits.map((digit, index) => (
+        <RollingDigit
+          key={`${digits.length}-${index}`}
+          digit={Number(digit)}
+        />
+      ))}
+    </span>
+  );
+}
+
+function RollingDigit({ digit }: { digit: number }) {
+  const safeDigit = Number.isFinite(digit) ? Math.min(9, Math.max(0, digit)) : 0;
+  return (
+    <span className="relative inline-block h-[1em] w-[0.62em] overflow-hidden">
+      <span
+        className="flex flex-col transition-transform duration-200 ease-out will-change-transform"
+        style={{ transform: `translateY(-${safeDigit}em)` }}
+      >
+        {Array.from({ length: 10 }, (_, n) => (
+          <span key={n} className="block h-[1em] leading-none">
+            {n}
+          </span>
+        ))}
+      </span>
+    </span>
+  );
 }

webui/src/components/ui/dialog.tsx

@@ -24,26 +24,35 @@ const DialogOverlay = React.forwardRef<
 ));
 DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
 
+interface DialogContentProps
+  extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
+  showCloseButton?: boolean;
+}
+
 const DialogContent = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+  DialogContentProps
->(({ className, children, ...props }, ref) => (
+>(({ className, children, showCloseButton = true, ...props }, ref) => (
   <DialogPortal>
     <DialogOverlay />
-    <DialogPrimitive.Content
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
-      ref={ref}
+      <DialogPrimitive.Content
-      className={cn(
+        ref={ref}
-        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg",
+        className={cn(
-        className,
+          "grid w-full max-w-lg origin-center gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg",
-      )}
+          className,
-      {...props}
+        )}
-    >
+        {...props}
-      {children}
+      >
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none">
+        {children}
-        <X className="h-4 w-4" />
+        {showCloseButton ? (
-        <span className="sr-only">Close</span>
+          <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none">
-      </DialogPrimitive.Close>
+            <X className="h-4 w-4" />
-    </DialogPrimitive.Content>
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        ) : null}
+      </DialogPrimitive.Content>
+    </div>
   </DialogPortal>
 ));
 DialogContent.displayName = DialogPrimitive.Content.displayName;

webui/src/components/ui/dropdown-menu.tsx

@@ -47,11 +47,16 @@ const DropdownMenuSubContent = React.forwardRef<
 ));
 DropdownMenuSubContent.displayName = DropdownMenuPrimitive.SubContent.displayName;
 
+interface DropdownMenuContentProps
+  extends React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content> {
+  portalContainer?: HTMLElement | null;
+}
+
 const DropdownMenuContent = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+  DropdownMenuContentProps
->(({ className, sideOffset = 4, ...props }, ref) => (
+>(({ className, sideOffset = 4, portalContainer, ...props }, ref) => (
-  <DropdownMenuPrimitive.Portal>
+  <DropdownMenuPrimitive.Portal container={portalContainer ?? undefined}>
     <DropdownMenuPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}

webui/src/globals.css

@@ -131,6 +131,9 @@
     position: relative;
     color: hsl(var(--muted-foreground));
   }
+  .file-reference-sheen {
+    color: inherit;
+  }
   .streaming-text-sheen::after {
     content: attr(data-sheen-text);
     position: absolute;

webui/src/hooks/useNanobotStream.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useClient } from "@/providers/ClientProvider";
 import { toMediaAttachment } from "@/lib/media";
-import { toolTraceLinesFromEvents } from "@/lib/tool-traces";
+import { mergeUniqueToolTraceLines, toolTraceLinesFromEvents } from "@/lib/tool-traces";
 import type { StreamError } from "@/lib/nanobot-client";
 import type {
   InboundEvent,
@@ -215,18 +215,19 @@ function absorbCompleteAssistantMessage(
 }
 
 function fileEditKey(edit: Pick<UIFileEdit, "call_id" | "tool" | "path">): string {
-  return `${edit.call_id}|${edit.tool}|${edit.path}`;
+  if (edit.call_id) return `${edit.call_id}|${edit.tool}`;
+  return `${edit.tool}|${edit.path}`;
 }
 
 function normalizeFileEdit(edit: UIFileEdit): UIFileEdit | null {
-  if (!edit || !edit.path || !edit.tool) return null;
+  if (!edit || !edit.tool || (!edit.path && !edit.pending)) return null;
   const inferredStatus =
     edit.phase === "error"
       ? "error"
       : edit.phase === "end"
         ? "done"
         : "editing";
-  return {
+  const normalized: UIFileEdit = {
     ...edit,
     call_id: edit.call_id || `${edit.tool}:${edit.path}`,
     added: Number.isFinite(edit.added) ? Math.max(0, Math.round(edit.added)) : 0,
@@ -235,6 +236,8 @@ function normalizeFileEdit(edit: UIFileEdit): UIFileEdit | null {
       ? edit.status
       : inferredStatus,
   };
+  if (edit.pending && !edit.path) normalized.pending = true;
+  return normalized;
 }
 
 function mergeFileEdits(existing: UIFileEdit[] | undefined, incoming: UIFileEdit[]): UIFileEdit[] {
@@ -250,11 +253,31 @@ function mergeFileEdits(existing: UIFileEdit[] | undefined, incoming: UIFileEdit
       next.push(edit);
       continue;
     }
-    next[existingIndex] = { ...next[existingIndex], ...edit };
+    const merged = { ...next[existingIndex], ...edit };
+    if (edit.path && !edit.pending) delete merged.pending;
+    next[existingIndex] = merged;
   }
   return next;
 }
 
+function findFileEditTraceIndex(
+  prev: UIMessage[],
+  segmentId: string | null,
+  incoming: UIFileEdit[],
+): number | null {
+  const incomingKeys = new Set(incoming.map(fileEditKey));
+  for (let i = prev.length - 1; i >= 0; i -= 1) {
+    const candidate = prev[i];
+    if (candidate.role === "user") break;
+    if (candidate.kind !== "trace" || !candidate.fileEdits?.length) continue;
+    if (segmentId && candidate.activitySegmentId === segmentId) return i;
+    for (const existing of candidate.fileEdits) {
+      if (incomingKeys.has(fileEditKey(existing))) return i;
+    }
+  }
+  return null;
+}
+
 /**
  * Subscribe to a chat by ID. Returns the in-memory message list for the chat,
  * a streaming flag, and a ``send`` function. Initial history must be seeded
@@ -534,6 +557,7 @@ export function useNanobotStream(
         if (suppressStreamUntilTurnEndRef.current) return;
         const chunk = typeof ev.text === "string" ? ev.text : "";
         if (!chunk) return;
+        clearActivitySegment();
         setIsStreaming(true);
         pendingStreamEventsRef.current.push({ kind: "delta", text: chunk });
         schedulePendingStreamFlush();
@@ -544,6 +568,7 @@ export function useNanobotStream(
         if (suppressStreamUntilTurnEndRef.current) return;
         const chunk = ev.text;
         if (!chunk) return;
+        if (fileEditSegmentRef.current) clearActivitySegment();
         setIsStreaming(true);
         pendingStreamEventsRef.current.push({ kind: "reasoning", text: chunk });
         schedulePendingStreamFlush();
@@ -622,6 +647,7 @@ export function useNanobotStream(
         if (ev.kind === "reasoning") {
           const line = ev.text;
           if (!line) return;
+          if (fileEditSegmentRef.current) clearActivitySegment();
           setMessages((prev) => closeReasoningStream(attachReasoningChunk(prev, line, {
             ensure: ensureActivitySegmentId,
           })));
@@ -652,10 +678,16 @@ export function useNanobotStream(
                 : last.content
                   ? [last.content]
                   : [];
+              const mergedLines = structuredLines.length > 0
+                ? mergeUniqueToolTraceLines(previousTraces, structuredLines)
+                : null;
+              if (mergedLines && !mergedLines.added) return prev;
               const merged: UIMessage = {
                 ...last,
-                traces: [...previousTraces, ...lines],
+                traces: mergedLines ? mergedLines.traces : [...previousTraces, ...lines],
-                content: lines[lines.length - 1],
+                content: mergedLines
+                  ? mergedLines.traces[mergedLines.traces.length - 1]
+                  : lines[lines.length - 1],
                 activitySegmentId: last.activitySegmentId ?? segmentId,
               };
               return [...prev.slice(0, -1), merged];
@@ -685,6 +717,7 @@ export function useNanobotStream(
         // flight, drop the placeholder so we don't render the text twice.
         // Do NOT reset isStreaming here — only ``turn_end`` signals that
         // the full turn (all tool calls + final text) is complete.
+        clearActivitySegment();
         setMessages((prev) => {
           const activeId = buffer.current?.messageId;
           buffer.current = null;
@@ -709,27 +742,32 @@ export function useNanobotStream(
       if (ev.event === "file_edit") {
         const edits = Array.isArray(ev.edits) ? ev.edits : [];
         if (edits.length === 0) return;
+        const normalized = mergeFileEdits(undefined, edits);
+        if (normalized.length === 0) return;
+        const opensFileEditPhase = normalized.some(
+          (edit) => edit.status === "editing" || edit.phase === "start",
+        );
+        let eventSegmentId = fileEditSegmentRef.current;
+        if (!eventSegmentId && opensFileEditPhase) {
+          eventSegmentId = detachedActivitySegmentId();
+          fileEditSegmentRef.current = eventSegmentId;
+        }
         setMessages((prev) => {
-          const last = prev[prev.length - 1];
+          let segmentId = eventSegmentId;
-          let segmentId = fileEditSegmentRef.current;
+          const targetIndex = findFileEditTraceIndex(prev, segmentId, normalized);
-          if (!segmentId || !(last?.kind === "trace" && last.fileEdits?.length)) {
+          if (targetIndex !== null) {
-            segmentId = detachedActivitySegmentId();
+            const target = prev[targetIndex];
-            fileEditSegmentRef.current = segmentId;
+            segmentId = target.activitySegmentId ?? segmentId ?? detachedActivitySegmentId();
-          }
+            if (opensFileEditPhase) fileEditSegmentRef.current = segmentId;
-          if (
-            last
-            && last.kind === "trace"
-            && !last.isStreaming
-            && !!last.fileEdits?.length
-            && last.activitySegmentId === segmentId
-          ) {
             const merged: UIMessage = {
-              ...last,
+              ...target,
-              fileEdits: mergeFileEdits(last.fileEdits, edits),
+              fileEdits: mergeFileEdits(target.fileEdits, normalized),
-              activitySegmentId: last.activitySegmentId ?? segmentId,
+              activitySegmentId: segmentId,
             };
-            return [...prev.slice(0, -1), merged];
+            return replaceMessageAt(prev, targetIndex, merged);
           }
+          segmentId = segmentId ?? detachedActivitySegmentId();
+          if (opensFileEditPhase) fileEditSegmentRef.current = segmentId;
           return [
             ...prev,
             {
@@ -738,7 +776,7 @@ export function useNanobotStream(
               kind: "trace",
               content: "",
               traces: [],
-              fileEdits: mergeFileEdits(undefined, edits),
+              fileEdits: normalized,
               activitySegmentId: segmentId,
               createdAt: Date.now(),
             },

webui/src/hooks/useSidebarState.ts

@@ -0,0 +1,206 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { useClient } from "@/providers/ClientProvider";
+import {
+  fetchSidebarState,
+  updateSidebarState as persistSidebarState,
+} from "@/lib/api";
+import type { ChatSummary, SidebarStatePayload } from "@/lib/types";
+
+export const DEFAULT_SIDEBAR_STATE: SidebarStatePayload = {
+  schema_version: 1,
+  pinned_keys: [],
+  archived_keys: [],
+  title_overrides: {},
+  tags_by_key: {},
+  collapsed_groups: {},
+  view: {
+    density: "comfortable",
+    show_previews: false,
+    show_timestamps: false,
+    show_archived: false,
+    sort: "updated_desc",
+  },
+  updated_at: null,
+};
+
+function uniqueStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const cleaned = item.trim();
+    if (!cleaned || seen.has(cleaned)) continue;
+    seen.add(cleaned);
+    out.push(cleaned);
+  }
+  return out;
+}
+
+function stringMap(value: unknown): Record<string, string> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const out: Record<string, string> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw !== "string") continue;
+    const cleanedKey = key.trim();
+    const cleanedValue = raw.trim();
+    if (!cleanedKey || !cleanedValue) continue;
+    out[cleanedKey] = cleanedValue;
+  }
+  return out;
+}
+
+function tagsMap(value: unknown): Record<string, string[]> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const out: Record<string, string[]> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    const cleanedKey = key.trim();
+    if (!cleanedKey) continue;
+    const tags = uniqueStrings(raw).slice(0, 12);
+    if (tags.length) out[cleanedKey] = tags;
+  }
+  return out;
+}
+
+function boolMap(value: unknown): Record<string, boolean> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const out: Record<string, boolean> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    const cleanedKey = key.trim();
+    if (cleanedKey) out[cleanedKey] = Boolean(raw);
+  }
+  return out;
+}
+
+export function normalizeSidebarState(raw: unknown): SidebarStatePayload {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...DEFAULT_SIDEBAR_STATE, view: { ...DEFAULT_SIDEBAR_STATE.view } };
+  }
+  const value = raw as Partial<SidebarStatePayload>;
+  const view = value.view && typeof value.view === "object"
+    ? value.view
+    : DEFAULT_SIDEBAR_STATE.view;
+  const density = view.density === "compact" ? "compact" : "comfortable";
+  const sort = ["updated_desc", "created_desc", "title_asc"].includes(view.sort)
+    ? view.sort
+    : "updated_desc";
+  return {
+    schema_version: 1,
+    pinned_keys: uniqueStrings(value.pinned_keys),
+    archived_keys: uniqueStrings(value.archived_keys),
+    title_overrides: stringMap(value.title_overrides),
+    tags_by_key: tagsMap(value.tags_by_key),
+    collapsed_groups: boolMap(value.collapsed_groups),
+    view: {
+      density,
+      show_previews: Boolean(view.show_previews),
+      show_timestamps: Boolean(view.show_timestamps),
+      show_archived: Boolean(view.show_archived),
+      sort,
+    },
+    updated_at: typeof value.updated_at === "string" ? value.updated_at : null,
+  };
+}
+
+function pruneMissingSessions(
+  state: SidebarStatePayload,
+  sessions: ChatSummary[],
+): SidebarStatePayload {
+  const valid = new Set(sessions.map((session) => session.key));
+  const filterKeys = (keys: string[]) => keys.filter((key) => valid.has(key));
+  const filterMap = <T,>(map: Record<string, T>): Record<string, T> => {
+    const out: Record<string, T> = {};
+    for (const [key, value] of Object.entries(map)) {
+      if (valid.has(key)) out[key] = value;
+    }
+    return out;
+  };
+  return {
+    ...state,
+    pinned_keys: filterKeys(state.pinned_keys),
+    archived_keys: filterKeys(state.archived_keys),
+    title_overrides: filterMap(state.title_overrides),
+    tags_by_key: filterMap(state.tags_by_key),
+  };
+}
+
+function sameState(a: SidebarStatePayload, b: SidebarStatePayload): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function useSidebarState(
+  sessions: ChatSummary[],
+  sessionsLoaded: boolean,
+): {
+  state: SidebarStatePayload;
+  loading: boolean;
+  update: (
+    updater: (state: SidebarStatePayload) => SidebarStatePayload,
+  ) => Promise<void>;
+} {
+  const { token } = useClient();
+  const tokenRef = useRef(token);
+  const stateRef = useRef(DEFAULT_SIDEBAR_STATE);
+  const persistVersionRef = useRef(0);
+  const [state, setState] = useState<SidebarStatePayload>(DEFAULT_SIDEBAR_STATE);
+  const [loading, setLoading] = useState(true);
+  tokenRef.current = token;
+  stateRef.current = state;
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    (async () => {
+      try {
+        const loaded = normalizeSidebarState(await fetchSidebarState(tokenRef.current));
+        if (cancelled) return;
+        stateRef.current = loaded;
+        setState(loaded);
+      } catch {
+        if (cancelled) return;
+        stateRef.current = DEFAULT_SIDEBAR_STATE;
+        setState(DEFAULT_SIDEBAR_STATE);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const update = useCallback(
+    async (updater: (current: SidebarStatePayload) => SidebarStatePayload) => {
+      const next = normalizeSidebarState(updater(stateRef.current));
+      const version = persistVersionRef.current + 1;
+      persistVersionRef.current = version;
+      stateRef.current = next;
+      setState(next);
+      try {
+        const persisted = normalizeSidebarState(
+          await persistSidebarState(tokenRef.current, next),
+        );
+        if (persistVersionRef.current !== version) return;
+        stateRef.current = persisted;
+        setState(persisted);
+      } catch {
+        // Keep the optimistic UI state. Older gateways or transient auth expiry
+        // should not break the chat list; the next refresh can try again.
+      }
+    },
+    [],
+  );
+
+  const pruned = useMemo(() => {
+    if (!sessionsLoaded || loading) return state;
+    return pruneMissingSessions(state, sessions);
+  }, [loading, sessions, sessionsLoaded, state]);
+
+  useEffect(() => {
+    if (!sessionsLoaded || loading || sameState(pruned, state)) return;
+    void update(() => pruned);
+  }, [loading, pruned, sessionsLoaded, state, update]);
+
+  return { state, loading, update };
+}

webui/src/i18n/locales/en/common.json

@@ -45,8 +45,16 @@
     "toggleTheme": "Toggle theme",
     "home": "Home",
     "newChat": "New chat",
-    "searchAria": "Search chats",
+    "searchAria": "Search",
-    "searchPlaceholder": "Search chats",
+    "viewOptions": "View",
+    "compactList": "Compact list",
+    "showPreviews": "Show previews",
+    "showTimestamps": "Show time",
+    "sortLabel": "Sort",
+    "sortUpdated": "Recently updated",
+    "sortCreated": "Recently created",
+    "sortTitle": "Title A-Z",
+    "searchPlaceholder": "Search",
     "searchResults": "Results",
     "noSearchResults": "No matching chats.",
     "recent": "Recent",
@@ -65,12 +73,31 @@
     },
     "nav": {
       "general": "General",
-      "byok": "BYOK"
+      "byok": "BYOK",
+      "overview": "Overview",
+      "appearance": "Appearance",
+      "models": "Models",
+      "providers": "Providers",
+      "image": "Image",
+      "web": "Web",
+      "runtime": "Runtime",
+      "advanced": "Advanced"
     },
     "sections": {
       "interface": "Interface",
       "ai": "AI",
-      "system": "System"
+      "system": "System",
+      "status": "Status",
+      "localPreferences": "Local preferences",
+      "presets": "Presets",
+      "imageGeneration": "Image generation",
+      "imageDefaults": "Defaults",
+      "webSearch": "Web search",
+      "webBehavior": "Behavior",
+      "identity": "Identity",
+      "safety": "Safety",
+      "capabilities": "Capabilities",
+      "integrations": "Integrations"
     },
     "rows": {
       "theme": "Theme",
@@ -78,31 +105,104 @@
       "provider": "Provider",
       "model": "Model",
       "restart": "Restart nanobot",
-      "configPath": "Config path"
+      "configPath": "Config path",
+      "activePreset": "Active preset",
+      "gateway": "Gateway",
+      "restartState": "Restart state",
+      "pendingChanges": "Pending changes",
+      "selectedPreset": "Selected preset",
+      "presetModel": "Preset model",
+      "density": "Density",
+      "activityMode": "Activity detail",
+      "codeWrap": "Code wrapping",
+      "maxResults": "Max results",
+      "timeout": "Timeout",
+      "jinaReader": "Jina reader",
+      "imageGeneration": "Image generation",
+      "imageProvider": "Image provider",
+      "imageProviderStatus": "Provider status",
+      "imageProviderBase": "Provider base",
+      "imageModel": "Image model",
+      "defaultAspectRatio": "Default aspect",
+      "defaultImageSize": "Default size",
+      "maxImagesPerTurn": "Max images per turn",
+      "imageSaveDir": "Save directory",
+      "botName": "Bot name",
+      "botIcon": "Bot icon",
+      "timezone": "Timezone",
+      "toolHintMaxLength": "Tool hint length",
+      "workspacePath": "Workspace path",
+      "heartbeat": "Heartbeat",
+      "dream": "Dream",
+      "unifiedSession": "Unified session",
+      "restrictWorkspace": "Restrict to workspace",
+      "execTool": "Exec tool",
+      "execSandbox": "Exec sandbox",
+      "ssrfWhitelist": "SSRF whitelist",
+      "mcpServers": "MCP servers",
+      "pathAppend": "PATH append",
+      "configurationDocs": "Configuration docs"
     },
     "help": {
       "theme": "Switch between light and dark appearance.",
       "language": "Choose the language used by the WebUI.",
       "provider": "Select the provider that should serve new model requests.",
       "model": "Set the default model name used by nanobot.",
-      "configPath": "The gateway configuration file currently in use."
+      "configPath": "The gateway configuration file currently in use.",
+      "selectedPreset": "Named presets are read-only here; edit them in config.json.",
+      "presetModel": "Switch to Default to edit model and provider from the WebUI.",
+      "density": "Stored only in this browser.",
+      "activityMode": "Choose how much agent activity chrome to show by default.",
+      "codeWrap": "Keep long code lines readable on smaller screens.",
+      "maxResults": "Results returned by each web_search call.",
+      "timeout": "Seconds before a search provider request times out.",
+      "jinaReader": "Use Jina Reader for web_fetch when available.",
+      "imageGeneration": "Expose generate_image in chats when a configured image provider is available.",
+      "imageProvider": "Choose the registry provider used by generate_image.",
+      "imageProviderStatus": "Image generation reuses provider credentials from Providers.",
+      "imageModel": "Model name sent to the selected image provider.",
+      "defaultAspectRatio": "Used when the prompt does not choose an aspect ratio.",
+      "defaultImageSize": "Size hint sent to providers that support it.",
+      "maxImagesPerTurn": "Upper bound for one generate_image request.",
+      "botName": "Shown in runtime surfaces that use the configured bot identity.",
+      "botIcon": "Short emoji or text shown beside the bot name.",
+      "timezone": "IANA timezone used by runtime context and schedules.",
+      "toolHintMaxLength": "Maximum characters shown in tool progress hints.",
+      "advancedReadOnly": "Advanced safety controls are read-only in WebUI. Edit config.json intentionally when needed."
     },
     "values": {
       "light": "Light",
       "dark": "Dark",
-      "notAvailable": "Not available"
+      "notAvailable": "Not available",
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "restartPending": "Restart pending",
+      "ready": "Ready",
+      "comfortable": "Comfortable",
+      "compact": "Compact",
+      "auto": "Auto",
+      "expanded": "Expanded",
+      "on": "On",
+      "off": "Off",
+      "configured": "Configured",
+      "notConfigured": "Not configured"
     },
     "status": {
       "loading": "Loading settings...",
       "loadError": "Could not load settings",
       "unsaved": "Unsaved changes.",
-      "savedRestart": "Saved. Restart nanobot to apply."
+      "upToDate": "Up to date.",
+      "savedRestart": "Saved. Restart nanobot to apply.",
+      "restartAfterSaving": "Save changes, then restart when ready.",
+      "savedRestartApply": "Saved. Restart when ready.",
+      "imageProviderRestart": "Image provider changes saved. Restart when ready."
     },
     "actions": {
       "save": "Save",
       "saving": "Saving",
       "edit": "Edit",
-      "cancel": "Cancel"
+      "cancel": "Cancel",
+      "openDocs": "Open docs"
     },
     "byok": {
       "description": "Bring your own provider keys. Nanobot reads these values from the current config and only configured providers can be selected in General.",
@@ -145,6 +245,26 @@
         "missingCredential": "Add the required credential before saving.",
         "saveHint": "Changes apply to new web search requests."
       }
+    },
+    "overview": {
+      "model": "Current model",
+      "providers": "Providers",
+      "configuredCount": "{{count}} configured",
+      "totalProviders": "{{count}} available",
+      "webSearch": "Web search",
+      "imageGeneration": "Image generation",
+      "workspace": "Workspace"
+    },
+    "providers": {
+      "searchPlaceholder": "Search providers",
+      "noMatches": "No providers match this search."
+    },
+    "image": {
+      "selectProvider": "Select provider",
+      "selectAspect": "Select aspect",
+      "selectSize": "Select size",
+      "configureProvider": "Configure provider",
+      "missingCredential": "Configure this provider before enabling image generation."
     }
   },
   "chat": {
@@ -152,12 +272,30 @@
     "loading": "Loading…",
     "noSessions": "No sessions yet.",
     "actions": "Chat actions for {{title}}",
+    "activity": {
+      "running": "Agent running",
+      "complete": "Agent finished"
+    },
+    "pin": "Pin",
+    "unpin": "Unpin",
+    "rename": "Rename",
+    "renameTitle": "Rename chat",
+    "renameDescription": "Choose a local sidebar name for this chat.",
+    "renamePlaceholder": "Chat name",
+    "renameSave": "Save",
+    "archive": "Archive",
+    "unarchive": "Unarchive",
+    "showArchived": "Show archived",
+    "hideArchived": "Hide archived",
     "delete": "Delete",
     "newChat": "New chat",
     "groups": {
+      "pinned": "Pinned",
+      "all": "Chats",
       "today": "Today",
       "yesterday": "Yesterday",
-      "earlier": "Earlier"
+      "earlier": "Earlier",
+      "archived": "Archived"
     }
   },
   "deleteConfirm": {

webui/src/i18n/locales/es/common.json

@@ -30,13 +30,25 @@
     "collapse": "Contraer barra lateral",
     "toggleTheme": "Cambiar tema",
     "newChat": "Nuevo chat",
+    "viewOptions": "View",
+    "compactList": "Compact list",
+    "showPreviews": "Show previews",
+    "showTimestamps": "Show time",
+    "sortLabel": "Sort",
+    "sortUpdated": "Recently updated",
+    "sortCreated": "Recently created",
+    "sortTitle": "Title A-Z",
     "recent": "Recientes",
     "refreshSessions": "Actualizar sesiones",
     "settings": "Configuración",
     "language": {
       "label": "Idioma",
       "ariaLabel": "Cambiar idioma"
-    }
+    },
+    "searchAria": "Buscar",
+    "searchPlaceholder": "Buscar",
+    "searchResults": "Resultados",
+    "noSearchResults": "No hay chats coincidentes."
   },
   "settings": {
     "backToChat": "Volver al chat",
@@ -46,12 +58,28 @@
     },
     "nav": {
       "general": "General",
-      "byok": "BYOK"
+      "byok": "BYOK",
+      "overview": "Overview",
+      "appearance": "Appearance",
+      "models": "Models",
+      "providers": "Providers",
+      "image": "Image",
+      "web": "Web",
+      "runtime": "Runtime",
+      "advanced": "Advanced"
     },
     "sections": {
       "interface": "Interfaz",
       "ai": "IA",
-      "system": "Sistema"
+      "system": "Sistema",
+      "status": "Status",
+      "localPreferences": "Local preferences",
+      "presets": "Presets",
+      "webSearch": "Web search",
+      "webBehavior": "Behavior",
+      "identity": "Identity",
+      "safety": "Safety",
+      "integrations": "Integrations"
     },
     "rows": {
       "theme": "Tema",
@@ -59,19 +87,70 @@
       "provider": "Proveedor",
       "model": "Modelo",
       "restart": "Reiniciar nanobot",
-      "configPath": "Ruta de configuración"
+      "configPath": "Ruta de configuración",
+      "activePreset": "Active preset",
+      "gateway": "Gateway",
+      "restartState": "Restart state",
+      "selectedPreset": "Selected preset",
+      "presetModel": "Preset model",
+      "density": "Density",
+      "activityMode": "Activity detail",
+      "codeWrap": "Code wrapping",
+      "maxResults": "Max results",
+      "timeout": "Timeout",
+      "jinaReader": "Jina reader",
+      "botName": "Bot name",
+      "botIcon": "Bot icon",
+      "timezone": "Timezone",
+      "toolHintMaxLength": "Tool hint length",
+      "workspacePath": "Workspace path",
+      "heartbeat": "Heartbeat",
+      "dream": "Dream",
+      "unifiedSession": "Unified session",
+      "restrictWorkspace": "Restrict to workspace",
+      "execTool": "Exec tool",
+      "execSandbox": "Exec sandbox",
+      "ssrfWhitelist": "SSRF whitelist",
+      "mcpServers": "MCP servers",
+      "pathAppend": "PATH append",
+      "configurationDocs": "Configuration docs"
     },
     "help": {
       "theme": "Cambia entre apariencia clara y oscura.",
       "language": "Elige el idioma usado por la WebUI.",
       "provider": "Selecciona el proveedor para nuevas solicitudes de modelo.",
       "model": "Define el nombre del modelo predeterminado que usa nanobot.",
-      "configPath": "El archivo de configuración que usa actualmente el gateway."
+      "configPath": "El archivo de configuración que usa actualmente el gateway.",
+      "selectedPreset": "Named presets are read-only here; edit them in config.json.",
+      "presetModel": "Switch to Default to edit model and provider from the WebUI.",
+      "density": "Stored only in this browser.",
+      "activityMode": "Choose how much agent activity chrome to show by default.",
+      "codeWrap": "Keep long code lines readable on smaller screens.",
+      "maxResults": "Results returned by each web_search call.",
+      "timeout": "Seconds before a search provider request times out.",
+      "jinaReader": "Use Jina Reader for web_fetch when available.",
+      "botName": "Shown in runtime surfaces that use the configured bot identity.",
+      "botIcon": "Short emoji or text shown beside the bot name.",
+      "timezone": "IANA timezone used by runtime context and schedules.",
+      "toolHintMaxLength": "Maximum characters shown in tool progress hints.",
+      "advancedReadOnly": "Advanced safety controls are read-only in WebUI. Edit config.json intentionally when needed."
     },
     "values": {
       "light": "Claro",
       "dark": "Oscuro",
-      "notAvailable": "No disponible"
+      "notAvailable": "No disponible",
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "restartRequired": "Restart required",
+      "liveReload": "Live reload ready",
+      "comfortable": "Comfortable",
+      "compact": "Compact",
+      "auto": "Auto",
+      "expanded": "Expanded",
+      "on": "On",
+      "off": "Off",
+      "configured": "Configured",
+      "notConfigured": "Not configured"
     },
     "status": {
       "loading": "Cargando configuración...",
@@ -83,7 +162,8 @@
       "save": "Guardar",
       "saving": "Guardando",
       "edit": "Editar",
-      "cancel": "Cancelar"
+      "cancel": "Cancelar",
+      "openDocs": "Open docs"
     },
     "byok": {
       "description": "Usa tus propias claves de proveedor. Nanobot lee estos valores desde la configuración actual, y solo los proveedores configurados se pueden elegir en General.",
@@ -126,6 +206,18 @@
         "missingCredential": "Añade la credencial requerida antes de guardar.",
         "saveHint": "Los cambios se aplican a nuevas solicitudes de web search."
       }
+    },
+    "overview": {
+      "model": "Current model",
+      "providers": "Providers",
+      "configuredCount": "{{count}} configured",
+      "totalProviders": "{{count}} available",
+      "webSearch": "Web search",
+      "workspace": "Workspace"
+    },
+    "providers": {
+      "searchPlaceholder": "Search providers",
+      "noMatches": "No providers match this search."
     }
   },
   "chat": {
@@ -133,8 +225,31 @@
     "loading": "Cargando…",
     "noSessions": "Todavía no hay sesiones.",
     "actions": "Acciones del chat {{title}}",
+    "activity": {
+      "running": "Agent running",
+      "complete": "Agent finished"
+    },
+    "pin": "Pin",
+    "unpin": "Unpin",
+    "rename": "Rename",
+    "renameTitle": "Rename chat",
+    "renameDescription": "Choose a local sidebar name for this chat.",
+    "renamePlaceholder": "Chat name",
+    "renameSave": "Save",
+    "archive": "Archive",
+    "unarchive": "Unarchive",
+    "showArchived": "Show archived",
+    "hideArchived": "Hide archived",
     "delete": "Eliminar",
-    "newChat": "Nuevo chat"
+    "newChat": "Nuevo chat",
+    "groups": {
+      "pinned": "Pinned",
+      "all": "Chats",
+      "today": "Today",
+      "yesterday": "Yesterday",
+      "earlier": "Earlier",
+      "archived": "Archived"
+    }
   },
   "deleteConfirm": {
     "title": "¿Eliminar este chat?",

webui/src/i18n/locales/fr/common.json

@@ -30,13 +30,25 @@
     "collapse": "Réduire la barre latérale",
     "toggleTheme": "Changer de thème",
     "newChat": "Nouvelle discussion",
+    "viewOptions": "View",
+    "compactList": "Compact list",
+    "showPreviews": "Show previews",
+    "showTimestamps": "Show time",
+    "sortLabel": "Sort",
+    "sortUpdated": "Recently updated",
+    "sortCreated": "Recently created",
+    "sortTitle": "Title A-Z",
     "recent": "Récentes",
     "refreshSessions": "Actualiser les sessions",
     "settings": "Paramètres",
     "language": {
       "label": "Langue",
       "ariaLabel": "Changer de langue"
-    }
+    },
+    "searchAria": "Rechercher",
+    "searchPlaceholder": "Rechercher",
+    "searchResults": "Résultats",
+    "noSearchResults": "Aucun chat correspondant."
   },
   "settings": {
     "backToChat": "Retour à la discussion",
@@ -46,12 +58,28 @@
     },
     "nav": {
       "general": "Général",
-      "byok": "BYOK"
+      "byok": "BYOK",
+      "overview": "Overview",
+      "appearance": "Appearance",
+      "models": "Models",
+      "providers": "Providers",
+      "image": "Image",
+      "web": "Web",
+      "runtime": "Runtime",
+      "advanced": "Advanced"
     },
     "sections": {
       "interface": "Interface",
       "ai": "IA",
-      "system": "Système"
+      "system": "Système",
+      "status": "Status",
+      "localPreferences": "Local preferences",
+      "presets": "Presets",
+      "webSearch": "Web search",
+      "webBehavior": "Behavior",
+      "identity": "Identity",
+      "safety": "Safety",
+      "integrations": "Integrations"
     },
     "rows": {
       "theme": "Thème",
@@ -59,19 +87,70 @@
       "provider": "Fournisseur",
       "model": "Modèle",
       "restart": "Redémarrer nanobot",
-      "configPath": "Chemin de configuration"
+      "configPath": "Chemin de configuration",
+      "activePreset": "Active preset",
+      "gateway": "Gateway",
+      "restartState": "Restart state",
+      "selectedPreset": "Selected preset",
+      "presetModel": "Preset model",
+      "density": "Density",
+      "activityMode": "Activity detail",
+      "codeWrap": "Code wrapping",
+      "maxResults": "Max results",
+      "timeout": "Timeout",
+      "jinaReader": "Jina reader",
+      "botName": "Bot name",
+      "botIcon": "Bot icon",
+      "timezone": "Timezone",
+      "toolHintMaxLength": "Tool hint length",
+      "workspacePath": "Workspace path",
+      "heartbeat": "Heartbeat",
+      "dream": "Dream",
+      "unifiedSession": "Unified session",
+      "restrictWorkspace": "Restrict to workspace",
+      "execTool": "Exec tool",
+      "execSandbox": "Exec sandbox",
+      "ssrfWhitelist": "SSRF whitelist",
+      "mcpServers": "MCP servers",
+      "pathAppend": "PATH append",
+      "configurationDocs": "Configuration docs"
     },
     "help": {
       "theme": "Basculer entre les apparences claire et sombre.",
       "language": "Choisissez la langue utilisée par le WebUI.",
       "provider": "Sélectionnez le fournisseur des nouvelles requêtes de modèle.",
       "model": "Définissez le nom du modèle par défaut utilisé par nanobot.",
-      "configPath": "Le fichier de configuration actuellement utilisé par la passerelle."
+      "configPath": "Le fichier de configuration actuellement utilisé par la passerelle.",
+      "selectedPreset": "Named presets are read-only here; edit them in config.json.",
+      "presetModel": "Switch to Default to edit model and provider from the WebUI.",
+      "density": "Stored only in this browser.",
+      "activityMode": "Choose how much agent activity chrome to show by default.",
+      "codeWrap": "Keep long code lines readable on smaller screens.",
+      "maxResults": "Results returned by each web_search call.",
+      "timeout": "Seconds before a search provider request times out.",
+      "jinaReader": "Use Jina Reader for web_fetch when available.",
+      "botName": "Shown in runtime surfaces that use the configured bot identity.",
+      "botIcon": "Short emoji or text shown beside the bot name.",
+      "timezone": "IANA timezone used by runtime context and schedules.",
+      "toolHintMaxLength": "Maximum characters shown in tool progress hints.",
+      "advancedReadOnly": "Advanced safety controls are read-only in WebUI. Edit config.json intentionally when needed."
     },
     "values": {
       "light": "Clair",
       "dark": "Sombre",
-      "notAvailable": "Indisponible"
+      "notAvailable": "Indisponible",
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "restartRequired": "Restart required",
+      "liveReload": "Live reload ready",
+      "comfortable": "Comfortable",
+      "compact": "Compact",
+      "auto": "Auto",
+      "expanded": "Expanded",
+      "on": "On",
+      "off": "Off",
+      "configured": "Configured",
+      "notConfigured": "Not configured"
     },
     "status": {
       "loading": "Chargement des paramètres...",
@@ -83,7 +162,8 @@
       "save": "Enregistrer",
       "saving": "Enregistrement",
       "edit": "Modifier",
-      "cancel": "Annuler"
+      "cancel": "Annuler",
+      "openDocs": "Open docs"
     },
     "byok": {
       "description": "Utilisez vos propres clés de fournisseur. Nanobot lit ces valeurs depuis la configuration actuelle, et seuls les fournisseurs configurés peuvent être sélectionnés dans Général.",
@@ -126,6 +206,18 @@
         "missingCredential": "Ajoutez l'identifiant requis avant d'enregistrer.",
         "saveHint": "Les changements s'appliquent aux nouvelles requêtes web search."
       }
+    },
+    "overview": {
+      "model": "Current model",
+      "providers": "Providers",
+      "configuredCount": "{{count}} configured",
+      "totalProviders": "{{count}} available",
+      "webSearch": "Web search",
+      "workspace": "Workspace"
+    },
+    "providers": {
+      "searchPlaceholder": "Search providers",
+      "noMatches": "No providers match this search."
     }
   },
   "chat": {
@@ -133,8 +225,31 @@
     "loading": "Chargement…",
     "noSessions": "Aucune session pour le moment.",
     "actions": "Actions de la discussion {{title}}",
+    "activity": {
+      "running": "Agent running",
+      "complete": "Agent finished"
+    },
+    "pin": "Pin",
+    "unpin": "Unpin",
+    "rename": "Rename",
+    "renameTitle": "Rename chat",
+    "renameDescription": "Choose a local sidebar name for this chat.",
+    "renamePlaceholder": "Chat name",
+    "renameSave": "Save",
+    "archive": "Archive",
+    "unarchive": "Unarchive",
+    "showArchived": "Show archived",
+    "hideArchived": "Hide archived",
     "delete": "Supprimer",
-    "newChat": "Nouvelle discussion"
+    "newChat": "Nouvelle discussion",
+    "groups": {
+      "pinned": "Pinned",
+      "all": "Chats",
+      "today": "Today",
+      "yesterday": "Yesterday",
+      "earlier": "Earlier",
+      "archived": "Archived"
+    }
   },
   "deleteConfirm": {
     "title": "Supprimer cette discussion ?",

webui/src/i18n/locales/id/common.json

@@ -30,13 +30,25 @@
     "collapse": "Ciutkan sidebar",
     "toggleTheme": "Ganti tema",
     "newChat": "Obrolan baru",
+    "viewOptions": "View",
+    "compactList": "Compact list",
+    "showPreviews": "Show previews",
+    "showTimestamps": "Show time",
+    "sortLabel": "Sort",
+    "sortUpdated": "Recently updated",
+    "sortCreated": "Recently created",
+    "sortTitle": "Title A-Z",
     "recent": "Terbaru",
     "refreshSessions": "Segarkan sesi",
     "settings": "Pengaturan",
     "language": {
       "label": "Bahasa",
       "ariaLabel": "Ganti bahasa"
-    }
+    },
+    "searchAria": "Cari",
+    "searchPlaceholder": "Cari",
+    "searchResults": "Hasil",
+    "noSearchResults": "Tidak ada chat yang cocok."
   },
   "settings": {
     "backToChat": "Kembali ke obrolan",
@@ -46,12 +58,28 @@
     },
     "nav": {
       "general": "Umum",
-      "byok": "BYOK"
+      "byok": "BYOK",
+      "overview": "Overview",
+      "appearance": "Appearance",
+      "models": "Models",
+      "providers": "Providers",
+      "image": "Image",
+      "web": "Web",
+      "runtime": "Runtime",
+      "advanced": "Advanced"
     },
     "sections": {
       "interface": "Antarmuka",
       "ai": "AI",
-      "system": "Sistem"
+      "system": "Sistem",
+      "status": "Status",
+      "localPreferences": "Local preferences",
+      "presets": "Presets",
+      "webSearch": "Web search",
+      "webBehavior": "Behavior",
+      "identity": "Identity",
+      "safety": "Safety",
+      "integrations": "Integrations"
     },
     "rows": {
       "theme": "Tema",
@@ -59,19 +87,70 @@
       "provider": "Penyedia",
       "model": "Model",
       "restart": "Mulai ulang nanobot",
-      "configPath": "Path konfigurasi"
+      "configPath": "Path konfigurasi",
+      "activePreset": "Active preset",
+      "gateway": "Gateway",
+      "restartState": "Restart state",
+      "selectedPreset": "Selected preset",
+      "presetModel": "Preset model",
+      "density": "Density",
+      "activityMode": "Activity detail",
+      "codeWrap": "Code wrapping",
+      "maxResults": "Max results",
+      "timeout": "Timeout",
+      "jinaReader": "Jina reader",
+      "botName": "Bot name",
+      "botIcon": "Bot icon",
+      "timezone": "Timezone",
+      "toolHintMaxLength": "Tool hint length",
+      "workspacePath": "Workspace path",
+      "heartbeat": "Heartbeat",
+      "dream": "Dream",
+      "unifiedSession": "Unified session",
+      "restrictWorkspace": "Restrict to workspace",
+      "execTool": "Exec tool",
+      "execSandbox": "Exec sandbox",
+      "ssrfWhitelist": "SSRF whitelist",
+      "mcpServers": "MCP servers",
+      "pathAppend": "PATH append",
+      "configurationDocs": "Configuration docs"
     },
     "help": {
       "theme": "Beralih antara tampilan terang dan gelap.",
       "language": "Pilih bahasa yang digunakan WebUI.",
       "provider": "Pilih penyedia untuk permintaan model baru.",
       "model": "Atur nama model default yang digunakan nanobot.",
-      "configPath": "File konfigurasi gateway yang sedang digunakan."
+      "configPath": "File konfigurasi gateway yang sedang digunakan.",
+      "selectedPreset": "Named presets are read-only here; edit them in config.json.",
+      "presetModel": "Switch to Default to edit model and provider from the WebUI.",
+      "density": "Stored only in this browser.",
+      "activityMode": "Choose how much agent activity chrome to show by default.",
+      "codeWrap": "Keep long code lines readable on smaller screens.",
+      "maxResults": "Results returned by each web_search call.",
+      "timeout": "Seconds before a search provider request times out.",
+      "jinaReader": "Use Jina Reader for web_fetch when available.",
+      "botName": "Shown in runtime surfaces that use the configured bot identity.",
+      "botIcon": "Short emoji or text shown beside the bot name.",
+      "timezone": "IANA timezone used by runtime context and schedules.",
+      "toolHintMaxLength": "Maximum characters shown in tool progress hints.",
+      "advancedReadOnly": "Advanced safety controls are read-only in WebUI. Edit config.json intentionally when needed."
     },
     "values": {
       "light": "Terang",
       "dark": "Gelap",
-      "notAvailable": "Tidak tersedia"
+      "notAvailable": "Tidak tersedia",
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "restartRequired": "Restart required",
+      "liveReload": "Live reload ready",
+      "comfortable": "Comfortable",
+      "compact": "Compact",
+      "auto": "Auto",
+      "expanded": "Expanded",
+      "on": "On",
+      "off": "Off",
+      "configured": "Configured",
+      "notConfigured": "Not configured"
     },
     "status": {
       "loading": "Memuat pengaturan...",
@@ -83,7 +162,8 @@
       "save": "Simpan",
       "saving": "Menyimpan",
       "edit": "Edit",
-      "cancel": "Batal"
+      "cancel": "Batal",
+      "openDocs": "Open docs"
     },
     "byok": {
       "description": "Gunakan kunci provider Anda sendiri. Nanobot membaca nilai ini dari config saat ini, dan hanya provider yang sudah dikonfigurasi yang bisa dipilih di Umum.",
@@ -126,6 +206,18 @@
         "missingCredential": "Tambahkan kredensial yang diperlukan sebelum menyimpan.",
         "saveHint": "Perubahan berlaku untuk permintaan web search baru."
       }
+    },
+    "overview": {
+      "model": "Current model",
+      "providers": "Providers",
+      "configuredCount": "{{count}} configured",
+      "totalProviders": "{{count}} available",
+      "webSearch": "Web search",
+      "workspace": "Workspace"
+    },
+    "providers": {
+      "searchPlaceholder": "Search providers",
+      "noMatches": "No providers match this search."
     }
   },
   "chat": {
@@ -133,8 +225,31 @@
     "loading": "Memuat…",
     "noSessions": "Belum ada sesi.",
     "actions": "Aksi obrolan untuk {{title}}",
+    "activity": {
+      "running": "Agent running",
+      "complete": "Agent finished"
+    },
+    "pin": "Pin",
+    "unpin": "Unpin",
+    "rename": "Rename",
+    "renameTitle": "Rename chat",
+    "renameDescription": "Choose a local sidebar name for this chat.",
+    "renamePlaceholder": "Chat name",
+    "renameSave": "Save",
+    "archive": "Archive",
+    "unarchive": "Unarchive",
+    "showArchived": "Show archived",
+    "hideArchived": "Hide archived",
     "delete": "Hapus",
-    "newChat": "Obrolan baru"
+    "newChat": "Obrolan baru",
+    "groups": {
+      "pinned": "Pinned",
+      "all": "Chats",
+      "today": "Today",
+      "yesterday": "Yesterday",
+      "earlier": "Earlier",
+      "archived": "Archived"
+    }
   },
   "deleteConfirm": {
     "title": "Hapus obrolan ini?",

webui/src/i18n/locales/ja/common.json

@@ -30,13 +30,25 @@
     "collapse": "サイドバーを閉じる",
     "toggleTheme": "テーマを切り替える",
     "newChat": "新しいチャット",
+    "viewOptions": "View",
+    "compactList": "Compact list",
+    "showPreviews": "Show previews",
+    "showTimestamps": "Show time",
+    "sortLabel": "Sort",
+    "sortUpdated": "Recently updated",
+    "sortCreated": "Recently created",
+    "sortTitle": "Title A-Z",
     "recent": "最近のチャット",
     "refreshSessions": "セッションを更新",
     "settings": "設定",
     "language": {
       "label": "言語",
       "ariaLabel": "言語を変更"
-    }
+    },
+    "searchAria": "検索",
+    "searchPlaceholder": "検索",
+    "searchResults": "検索結果",
+    "noSearchResults": "一致するチャットはありません。"
   },
   "settings": {
     "backToChat": "チャットに戻る",
@@ -46,12 +58,28 @@
     },
     "nav": {
       "general": "一般",
-      "byok": "BYOK"
+      "byok": "BYOK",
+      "overview": "Overview",
+      "appearance": "Appearance",
+      "models": "Models",
+      "providers": "Providers",
+      "image": "Image",
+      "web": "Web",
+      "runtime": "Runtime",
+      "advanced": "Advanced"
     },
     "sections": {
       "interface": "インターフェース",
       "ai": "AI",
-      "system": "システム"
+      "system": "システム",
+      "status": "Status",
+      "localPreferences": "Local preferences",
+      "presets": "Presets",
+      "webSearch": "Web search",
+      "webBehavior": "Behavior",
+      "identity": "Identity",
+      "safety": "Safety",
+      "integrations": "Integrations"
     },
     "rows": {
       "theme": "テーマ",
@@ -59,19 +87,70 @@
       "provider": "プロバイダー",
       "model": "モデル",
       "restart": "nanobot を再起動",
-      "configPath": "設定パス"
+      "configPath": "設定パス",
+      "activePreset": "Active preset",
+      "gateway": "Gateway",
+      "restartState": "Restart state",
+      "selectedPreset": "Selected preset",
+      "presetModel": "Preset model",
+      "density": "Density",
+      "activityMode": "Activity detail",
+      "codeWrap": "Code wrapping",
+      "maxResults": "Max results",
+      "timeout": "Timeout",
+      "jinaReader": "Jina reader",
+      "botName": "Bot name",
+      "botIcon": "Bot icon",
+      "timezone": "Timezone",
+      "toolHintMaxLength": "Tool hint length",
+      "workspacePath": "Workspace path",
+      "heartbeat": "Heartbeat",
+      "dream": "Dream",
+      "unifiedSession": "Unified session",
+      "restrictWorkspace": "Restrict to workspace",
+      "execTool": "Exec tool",
+      "execSandbox": "Exec sandbox",
+      "ssrfWhitelist": "SSRF whitelist",
+      "mcpServers": "MCP servers",
+      "pathAppend": "PATH append",
+      "configurationDocs": "Configuration docs"
     },
     "help": {
       "theme": "ライト表示とダーク表示を切り替えます。",
       "language": "WebUI で使用する言語を選択します。",
       "provider": "新しいモデルリクエストに使うプロバイダーを選択します。",
       "model": "nanobot が既定で使用するモデル名を設定します。",
-      "configPath": "現在ゲートウェイが使用している設定ファイルです。"
+      "configPath": "現在ゲートウェイが使用している設定ファイルです。",
+      "selectedPreset": "Named presets are read-only here; edit them in config.json.",
+      "presetModel": "Switch to Default to edit model and provider from the WebUI.",
+      "density": "Stored only in this browser.",
+      "activityMode": "Choose how much agent activity chrome to show by default.",
+      "codeWrap": "Keep long code lines readable on smaller screens.",
+      "maxResults": "Results returned by each web_search call.",
+      "timeout": "Seconds before a search provider request times out.",
+      "jinaReader": "Use Jina Reader for web_fetch when available.",
+      "botName": "Shown in runtime surfaces that use the configured bot identity.",
+      "botIcon": "Short emoji or text shown beside the bot name.",
+      "timezone": "IANA timezone used by runtime context and schedules.",
+      "toolHintMaxLength": "Maximum characters shown in tool progress hints.",
+      "advancedReadOnly": "Advanced safety controls are read-only in WebUI. Edit config.json intentionally when needed."
     },
     "values": {
       "light": "ライト",
       "dark": "ダーク",
-      "notAvailable": "利用不可"
+      "notAvailable": "利用不可",
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "restartRequired": "Restart required",
+      "liveReload": "Live reload ready",
+      "comfortable": "Comfortable",
+      "compact": "Compact",
+      "auto": "Auto",
+      "expanded": "Expanded",
+      "on": "On",
+      "off": "Off",
+      "configured": "Configured",
+      "notConfigured": "Not configured"
     },
     "status": {
       "loading": "設定を読み込んでいます...",
@@ -83,7 +162,8 @@
       "save": "保存",
       "saving": "保存中",
       "edit": "編集",
-      "cancel": "キャンセル"
+      "cancel": "キャンセル",
+      "openDocs": "Open docs"
     },
     "byok": {
       "description": "自分の provider キーを使います。Nanobot は現在の config から値を読み込み、設定済みの provider だけを一般設定で選択できます。",
@@ -126,6 +206,18 @@
         "missingCredential": "保存する前に必要な認証情報を入力してください。",
         "saveHint": "変更は新しい web search リクエストに適用されます。"
       }
+    },
+    "overview": {
+      "model": "Current model",
+      "providers": "Providers",
+      "configuredCount": "{{count}} configured",
+      "totalProviders": "{{count}} available",
+      "webSearch": "Web search",
+      "workspace": "Workspace"
+    },
+    "providers": {
+      "searchPlaceholder": "Search providers",
+      "noMatches": "No providers match this search."
     }
   },
   "chat": {
@@ -133,8 +225,31 @@
     "loading": "読み込み中…",
     "noSessions": "まだセッションがありません。",
     "actions": "「{{title}}」のチャット操作",
+    "activity": {
+      "running": "Agent running",
+      "complete": "Agent finished"
+    },
+    "pin": "Pin",
+    "unpin": "Unpin",
+    "rename": "Rename",
+    "renameTitle": "Rename chat",
+    "renameDescription": "Choose a local sidebar name for this chat.",
+    "renamePlaceholder": "Chat name",
+    "renameSave": "Save",
+    "archive": "Archive",
+    "unarchive": "Unarchive",
+    "showArchived": "Show archived",
+    "hideArchived": "Hide archived",
     "delete": "削除",
-    "newChat": "新しいチャット"
+    "newChat": "新しいチャット",
+    "groups": {
+      "pinned": "Pinned",
+      "all": "Chats",
+      "today": "Today",
+      "yesterday": "Yesterday",
+      "earlier": "Earlier",
+      "archived": "Archived"
+    }
   },
   "deleteConfirm": {
     "title": "このチャットを削除しますか？",